Claude Code 多钩子审批出现版本差异
作者观察到,Claude Code 2.1.319 在多钩子同时处理命令审批时可能未经提示就执行命令。相同测试在 2.1.322 中弹出了审批提示,命令未执行。
AI 深度解读
Claude Code 的两个 PreToolUse hook 同时给一条 Bash 命令做权限判断,一个要求暂缓,一个要求确认。在 2.1.319 的一组交互式测试里,暂缓的 hook 先结束,确认框就没弹出来,命令按已有的允许规则执行了。作者在 2.1.322 重跑同一组测试,确认框正常出现。
这组实验把两个容易混在一起的问题拆开了。多个 hook 的决定怎么合并,决定了命令能不能执行。多个 hook 都要求确认时,哪条理由最后可见,决定了人能不能看懂自己在批准什么。
为什么一个 hook 测通了还不够
作者团队在 .claude/settings.json 里配了 5 个 PreToolUse 命令 hook,分在 3 个匹配组。Bash 上的两个分别拦截裸 open 打开 URL、拦截没有评审记录的 git commit。Agent|Task 上的一个检查评审子代理用的模型。浏览器自动化 MCP 的两个工具 hook 分别检查浏览器配置和控制操作间隔。
这 5 个 hook 只做两件事。命中拦截条件就以退出码 2 结束,其余情况静默退出。只要有一个硬拦截,同一次调用就会被拒绝。引入 ask 或 defer 后,Claude Code 才需要判断同一条调用上哪些决定有效,以及最后采用哪条理由。hook 又是并行运行的,脚本写在配置文件里的先后位置,无法保证实际完成顺序。
文档给出的优先级是 deny > defer > ask > allow。退出码 2 按 deny 处理,标准错误(stderr)会成为拒绝理由。defer 则是给通过 claude -p 嵌入 Claude Code 的程序用的。宿主可以先暂停工具调用,在自己的界面收集用户决定,再恢复执行。文档把适用范围限定在非交互模式,而且要求当前轮只有一次工具调用。交互模式会丢弃 defer 并记录警告。按文档,同一轮有多次工具调用时也会忽略 defer,接着走正常的权限流程。
旧版是怎么漏掉确认的
为了区分「命令执行了」和「命令等着批准」,作者用了一个临时项目,通过 --settings 传入实验配置,以 --setting-sources project 隔离用户级 hook 和插件。Bash(echo:*) 已经允许探针命令 echo hooklab-probe,所以一旦 hook 的确认要求没有生效,这条命令就会按现有权限直接跑。两个 Bash hook 使用同一个脚本,分别在约 0 秒和 1.5 秒时返回,并把起止时间写进日志。
作者在两个版本上都用 Haiku 和默认权限模式,各跑了 18 个 print 模式会话和 3 个交互会话。交互测试用 expect 驱动,靠 PermissionRequest 记录确认框即将出现,靠 PostToolUse 判断命令实际执行过。确认框一出来,脚本就按 Esc。

在 2.1.319 上,先结束的 hook 返回 defer。交互会话无法接受暂缓,Claude Code 将它丢弃,随后返回的 ask 也没保留下来。命令回到普通权限流程,被已有的允许规则放行,PostToolUse 留下了执行记录。同样的组合在 2.1.322 上弹出了确认框,脚本按 Esc 后,命令没有执行。让 ask 先结束,两个版本都会弹框。让 defer 搭配静默退出的 hook,两个版本都会执行探针。
2.1.321 的更新日志记载了这项修复。作者实际对照的是手头的 2.1.319 和 2.1.322,修复从哪个版本开始,依据的是更新日志。新版确认框显示 PreToolUse 的 Bash hook、返回 ask 的理由和 [settings] 来源标记。文档说来自设置文件或代理 frontmatter 的 hook 都用这个标记。

决策优先级和确认理由是两回事
在 print 模式下,两条配置 hook 针对单次调用的 12 种组合,在两个版本上都符合文档的优先级。两个 hook 都返回 ask 时,宿主只收到一次权限请求,decision_reason 来自先结束的 hook。另一个理由没有出现在宿主可读的输出里。调用被拒绝时,模型则能收到以 PreToolUse:Bash hook error: 开头的工具错误,后面带着拒绝理由。
作者用 Python 宿主启动 claude -p,传入 --input-format stream-json、--output-format stream-json 和 --permission-prompt-tool stdio,处理 initialize,并拒绝每个 can_use_tool 请求。另有两组测试在 initialize 里注册宿主自己的 PreToolUse 回调,模拟使用 Agent SDK 的应用也返回 ask。在 2.1.319 上,宿主 hook 先结束时,应用收到的是自己给出的理由。在 2.1.322 上,不管谁先结束,应用都收到项目设置里那个 hook 的理由。这是 2.1.321 更新日志记载的另一项修复。
还有一组结果和文档描述对不上。作者让 Haiku 在同一条消息里发出两个 Bash 调用,每个版本各跑了 4 次,结果全部以 stop_reason: "tool_deferred" 结束。deferred_tool_use 只指向第二个调用,两个 echo 都没有输出。日志显示第二个调用的 hook 在第一个调用的慢 hook 结束前就已启动。作者没有恢复这些会话,因此第一个调用恢复后会怎样,实验没有回答。
我的判断
这里最有参考价值的是交互测试的因果链。原有的允许规则、确认框事件和执行事件都有独立观测,所以旧版的「没有弹框」可以进一步确认是「命令确实走了允许规则」。这个结果可以解释共享配置里的一个具体故障,尤其是同一套设置同时供 claude -p 宿主和终端用户使用时。至于多调用时 defer 的表现,目前证据限于 Haiku 和 Bash,拿它当成所有工具组合的行为约定还太早。
团队如果只是要强制执行「评审完成后才能提交」,用 deny 或退出码 2 更贴合要求,作者现有的 5 个 hook 也都属于这种情况。ask 适合把决定交给人,但会受到其他 hook 决策和理由合并的影响。要让同一类确认只出现一种解释,把 ask 和理由集中到一个 hook 是可考虑的做法,代价是需要让它知道相关规则。原文没有比较拆分和集中配置的维护成本,这个取舍只能按团队的规则归属来定。
能拿来做什么
- 给前端仓库的
git commit加评审门槛时,先明确缺评审记录是否允许人工放行。属于强制门槛的,用deny或退出码2,并在stderr写清具体缺什么。 - 如果终端里的 Claude Code 和
claude -p宿主共用会返回defer的 hook,把最低版本设为 2.1.321,再用项目实际安装的版本检查交互确认是否出现。 - 给每个
ask写一条能单独读懂的理由,说明来自哪条规则、为何需要确认。两个 hook 都能对同一个 Bash 调用提出确认时,把快慢顺序对调测一遍,同时检查是否弹框、显示哪条理由,以及命令有没有执行。