Document safe parsing for preToolUse.toolArgs when it is a JSON-encoded string
- Linguagem predominante
- Shell
- Estrelas
- 11.2k
- Forks
- 1.9k
- Merge médio
- 14h 16min
- PRs com merge (30d)
- 6
Descrição
## Summary
The Hooks reference documents `preToolUse.toolArgs` as `unknown`, but does not show how hook authors should safely parse it.
In actual Copilot CLI hook invocations I tested, `toolArgs` arrived as a JSON-encoded string rather than a parsed object. That may be valid under the current `unknown` contract, but it is easy for hook authors to assume object-style access and accidentally write hooks that fail to inspect tool arguments.
Because hook failures are fail-open, this is a security footgun for policy-enforcing hooks.
## Observed behavior
For `preToolUse`, the documentation shows the camelCase payload shape as:
```ts
{
sessionId: string;
timestamp: number;
cwd: string;
toolName: string;
toolArgs: unknown;
}
```
In tested CLI/App-backed hook invocations, the payload effectively behaved like:
```json
{
"toolName": "bash",
"toolArgs": "{\"command\":\"echo hello\"}"
}
```
rather than:
```json
{
"toolName": "bash",
"toolArgs": {
"command": "echo hello"
}
}
```
I am not claiming the string form is invalid. Since the schema says `unknown`, this may be intentional or implementation-defined. The problem is that the docs do not tell hook authors how to handle it safely.
## Why this matters
Security hooks commonly inspect fields like:
```bash
.toolArgs.command
.toolArgs.path
.toolArgs.url
```
If `toolArgs` is a JSON-encoded string, this kind of access does not work as expected. Depending on the script and shell settings, the hook may fail, emit invalid output, or skip the intended check.
Since hook failures are fail-open, a parsing mistake can silently bypass a security policy.
## Request
Please document the expected handling for `toolArgs` and provide safe parsing examples.
At minimum, the docs should say something like:
> `toolArgs` is `unknown` and may be a JSON-encoded string. Hook scripts should check its runtime type and parse it before inspecting tool arguments.
A Bash example would help:
```bash
INPUT="$(cat)"
TOOL_ARGS_JSON="$(
jq -c '
(.toolArgs // .tool_args // .tool_input // {}) as $args
| if ($args | type) == "string" then ($args | fromjson? // {}) else $args end
' <<< "$INPUT"
)"
COMMAND="$(jq -r '.command // ""' <<< "$TOOL_ARGS_JSON")"
```
Python example:
```python
import json
import sys
payload = json.load(sys.stdin)
tool_args = payload.get("toolArgs", payload.get("tool_input", {}))
if isinstance(tool_args, str):
try:
tool_args = json.loads(tool_args)
except json.JSONDecodeError:
tool_args = {}
if not isinstance(tool_args, dict):
tool_args = {}
command = tool_args.get("command", "")
```
## Expected improvement
This would make hook authoring safer, especially for security-focused `preToolUse` hooks, and reduce the chance of fail-open bypasses caused by incorrect assumptions about the runtime type of `toolArgs`.
Guia de contribuição
Direção de pesquisa
Comece pela referência de Hooks e pela seção de payload de preToolUse. Documente que toolArgs pode ser uma string codificada em JSON e, em seguida, adicione exemplos seguros de parsing em Bash e Python que lidem com valores inválidos ou que não sejam objetos; a tarefa estará concluída quando os autores de hooks puderem inspecionar de forma confiável campos como command, path ou url.
Escrita pelo modelo de indexação a partir do texto da issue.
Avaliação
- Stack de tecnologia
- python, shell
- Domínio
- documentation, security
- Tipo de issue
- Documentação
- Dificuldade
- 2/5
- Tempo estimado
- 1-3 horas
- Status de atividade
- Pouca atividade
- Clareza
- Razoavelmente clara
- Facilidade para iniciantes
- 68/100