auto-review: 未映射内置工具缺少脱敏后的 material target,审阅器判据偏薄
- Dominant language
- TypeScript
- Stars
- 2.7k
- Forks
- 395
- Avg merge
- 21h 48m
- Merged PRs (30d)
- 776
Description
## 使用场景 / Use case
Claude Code SDK 每加一个内置工具,Cindy 的 `auto-review-policy.ts` 就多一个未映射工具。
PR #2560 之后这些工具不再被静默拒绝,而是带脱敏证据交轻量审阅器裁决:
```
Claude Code built-in tool "SomeFutureTool" (not individually classified by Cindy).
Arguments withheld; structure only: {path:string(42), secret:string(20)}#2a-1f3c9e01
```
审阅器由此知道「有一个 42 字符的 path 参数」,但**不知道它指向哪里** —— 是构建目录还是
`/etc/passwd`、是工作区内还是区外,判据完全一样。同理 message/url 之类参数也看不出
是否带外发副作用。
## 当前问题 / Current limitation
已映射工具(`Read` / `Write` / `Bash` / `WebFetch` …)之所以能给出准确判档,是因为
adapter 知道哪个键是目标,从而能调用 core 的 `isSensitiveCredentialPath`、工作区边界
判定等既有能力。未映射工具缺的正是这一步:**没有 material target**。
结果是审阅器只能基于「形状」做判断,倾向保守 → 灰区里本可直接放行的调用也可能升级,
或者反过来对真正危险的调用给出无依据的 allow。两个方向都不理想。
PR #2560 的 review 中 codex 提出的两条出路:
1. 未知工具一律 block / ask-only —— **已否决**:那正是 #2560 要修掉的静默拒绝,
且 SDK 每加一个工具就复发一次。
2. 提供安全脱敏的 material target —— 方向正确,但需要新增能力,超出 #2560 的意图契约,
故外推本 issue。
## 期望方案 / Proposed solution
对未映射工具的入参做**通用**的目标性质标注,只报性质、不报内容。大致形态:
```
{path:string(42)[outside-workspace], url:string(31)[remote-host], secret:string(20)}
```
可复用的既有能力:
- `isSensitiveCredentialPath()` —— 值是否落在凭证位置(`~/.ssh`、`~/.aws` 等);
- 工作区边界判定(`reviewAction` 的 read/file-write 分支已有同款逻辑)—— 区内 / 区外;
- URL 判定 —— 本机回环 / 远端主机。
需要解决的设计问题(正是它值得单独立项的原因):
- **误判成本**:任意字符串被当成路径去分类会给审阅器错误信号,比没有信号更糟。
需要一个足够保守的「看起来是路径 / URL」判据,宁可不标注也不标错。
- **标注是否算内容泄漏**:`[outside-workspace]` 本身不含用户数据,但对
`[credential-like]` 这类标注要确认审阅器 prompt 的边界口径。
- **多值与嵌套**:入参里的数组、嵌套对象要不要下探,下探几层。
## 已考虑的替代方案 / Alternatives considered
- **逐个工具补映射**:最准,但是被动追赶 —— SDK 加工具时我们总是慢一步,
期间仍走兜底。它与本 issue 不冲突,是长期该做的事,只是不能替代兜底质量。
- **把原始入参交给审阅器**:判据最足,但 `description` 会进审阅器 prompt,
入参可能是文件正文、凭证或用户数据 → 直接否决。
- **维持现状(只报形状 + 指纹)**:#2560 的落点。不阻塞发布,但审阅器判据确实偏薄。
## 相关
- PR #2560 —— 未映射工具从静默拒绝改为带脱敏证据交审阅器裁决(本 issue 的上游)
- Issue #2563 —— core 侧 PowerShell 载荷跨管道段判据的缺口
Contributor guide
Research direction
Start with auto-review-policy.ts and the existing reviewAction file-write/read handling, then inspect isSensitiveCredentialPath() and the unmapped-tool path introduced by PR #2560. Define conservative annotations for paths and URLs, including nested values and depth limits, while preserving argument secrecy; done means the reviewer receives useful target properties without misclassifying arbitrary strings or leaking content.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100