github / github/copilot-cli

Document safe parsing for preToolUse.toolArgs when it is a JSON-encoded string

未关闭 适合新手
#3,349 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
area:plugins
主要语言
Shell
星标
11.2k
派生
1.9k
平均合并
14 小时 16 分钟
30 天内合并 PR
6

描述

## 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`.

贡献指南

打开贡献指南

调研方向

从 Hooks 参考文档及其 preToolUse payload 部分开始。记录 toolArgs 可能是 JSON 编码的字符串,然后添加能够处理无效值或非对象值的安全 Bash 和 Python 解析示例;当 hook 作者能够可靠地检查 command、path 或 url 等字段时,即视为完成。

由索引模型根据 Issue 内容生成。

评估

技术栈
python, shell
领域
documentation, security
Issue 类型
文档
难度
2/5
预计耗时
1-3 小时
活跃度
冷清
描述清晰度
基本清楚
新手友好度
68/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。