Claude Code CLI 2.1.235 Hooks：31 个事件到底在什么时候运行、能改什么¶

版本：2.1.235 | 证据：目标版本 readable bundle 的 Static 路径；未做账号侧或远端服务行为倒推

Hooks 不是一组等价的“回调”。有的发生在副作用之前，可以拒绝或改写动作；有的发生在工具、压缩、目录切换或会话结束之后，只能补充反馈；还有的直接承担 Worktree 创建这类业务动作。判断一个 Hook 是否安全、是否能恢复，必须先回答：它在状态变化的前面还是后面，输出由谁消费，失败时原动作是否已经发生。

60 秒理解 Hook 控制面¶

读者问题： 为什么同样是 Hook，PreToolUse 能阻止命令，PostToolUse 却撤不回网络请求，Stop 又能让已经准备结束的 Agent 继续一轮？

一句话模型： Claude Code 把运行时事件映射成带公共会话字段和事件字段的 Hook input，经来源、信任、matcher 与条件筛选后并发执行，再按事件所在阶段把结果解释成前置决策、后置反馈、显示替换或生命周期动作。

贯穿场景：模型准备执行 Bash 修改文件。PreToolUse 在 tool.call 前看到工具名、输入和 ID，可以拒绝、要求询问或返回 updatedInput；工具成功后，PostToolUse 能替换送回模型的工具输出或增加上下文，但文件已经写入；一批工具都结束后，PostToolBatch 可进行整批审计；主 Agent 准备结束时，Stop 的 blocking feedback 又能重新打开 Agent Loop。

一、Hook 运行管线¶

1. 事件不是直接执行命令¶

目标版本把 31 个事件登记到同一个 registry。事件发生后，runner 先汇合 managed settings、用户/项目设置、plugin/skill 动态 Hook，再完成以下筛选：

1. workspace 是否可信，disableAllHooks 是否关闭全部 Hook；
2. 当前 Agent 是否只允许 managed hooks；
3. event 名是否匹配；
4. matcher 是否命中事件的匹配字段；
5. 可选 if 条件是否成立；
6. 同源、同配置 Hook 是否已经去重；
7. once Hook 是否已经消费并应从 session registry 移除。

筛选后的匹配项以 Promise.all 形态并发执行。这里的“并发”指同一事件命中的 Hook 之间没有默认串行保证；它不表示所有事件彼此并发。例如 PostToolBatch 本身要等本批工具 resolve 后才触发。

证据：事件枚举见 source-inventory/hook-events.txt；registry、来源汇合与 matcher 路径见 cli.readable.js 405354、405890-405976、488410-488517 附近。

2. 每个 input 都有一组公共字段¶

createBaseHookInput 会按可用状态写入：

公共字段不应被当成稳定公开 API 的全部合同。2.1.235 的 bundle 能证明客户端当前构造形状，但后续版本可增加字段；Hook 消费方应忽略未知字段。

3. matcher 只匹配事件选择字段¶

matcher 不是任意 JSON 查询。每类事件有自己的 matchQuery：

• 工具事件、PermissionRequest、PermissionDenied：工具名；
• Notification：notification type；
• SessionStart：startup/resume/clear/compact/fork 等 source；
• PreCompact/PostCompact：manual/auto；
• ConfigChange：配置 source；
• InstructionsLoaded：load reason；
• MCP Elicitation：server name；
• UserPromptExpansion：command name；
• 任务、Stop、显示等没有专属 matcher metadata 时，配置 matcher 不产生同样的字段过滤语义。

设置界面列出的 matcher values 是帮助和 schema 表面；真实是否触发仍取决于事件调用点、workspace trust、配置来源和当前运行模式。

4. 执行载体并不等价¶

本版 runner 可看到 command、HTTP、MCP tool、prompt、agent、function/callback 等 Hook 形态，但不是每个事件都支持所有载体。

SessionStart、Setup、CwdChanged、FileChanged 的 command Hook 还可拿到 CLAUDE_ENV_FILE，向其中写 shell exports 影响后续 Bash 环境。它是跨后续命令的状态写入，不只是一次 Hook stdout。

二、输出如何改变控制流¶

Exit code 不是全事件统一语义¶

命令 Hook 的通用规律是：

• 0 表示命令本身成功，随后仍要解析和校验 JSON；
• 2 常用于 blocking，但具体阻止什么由事件决定；
• 其他非零通常成为 non-blocking error，显示或记录错误后继续原流程。

不能把这三条机械套到全部事件。StopFailure 输出被忽略；SessionEnd 失败只写 stderr；WorktreeCreate 没有有效路径就整体失败；PostToolBatch 的 exit 2 停止后续 Agent Loop，但不能回滚已完成的工具批次；ConfigChange(policy_settings) 的结果会被强制标为不阻塞。

JSON 输出的共享字段¶

JSON 必须通过 schema，并且 hookSpecificOutput.hookEventName 必须与当前事件一致。命令 stdout 以 { 开头但 schema 不合法时会报告 validation error；HTTP body 则必须是合法 JSON，不能退回普通文本。

能实际修改的状态¶

过长输出如何处理¶

Hook 输出小于限制时直接返回；过长时会写入本地持久化文件并用引用/缩减文本进入上下文。若持久化失败，客户端截断到限制并附失败说明。它解决上下文膨胀，不等于敏感信息脱敏：Hook stdout/stderr、路径、tool input 和 response 仍可能进入 transcript、日志或持久化附件。

三、31 个事件逐项合同¶

下表的“阻塞/修改”描述的是本版调用方实际消费，不是从事件名称猜测。Boundary 表示 bundle 中能看到输入或 schema，却没有足够证据证明远端服务、账号状态或外部程序完成了什么。

四、并发、超时与失败矩阵¶

三个默认超时不能混用¶

单个 Hook 配置的 timeout 以秒转毫秒覆盖一般值。超时不是统一 fail-open：PreToolUse 超时明确不执行工具；生命周期或后置 Hook 通常记录失败并让既有状态继续。审计时要记录“原动作是否已发生”，不能只记录 Hook status。

五、成本、隐私和安全¶

最重要的安全边界是：Hook runner 与被控制工具是两个副作用主体。即使 PreToolUse 阻止了 Bash，Hook command/HTTP/MCP 自己也可能已经执行本地或远端动作；即使 PostToolUse 返回 block，原工具的文件写入、进程启动或远端请求也已经完成。2.1.235 没有把这两者包进统一事务。

六、配置和排障顺序¶

遇到“Hook 没运行”时按状态路径排查，而不是先改脚本：

1. 确认事件在当前模式真的有调用点，例如 StopFailure 不会和正常 Stop 同时触发；
2. 确认 workspace trust、safe/bare mode、disableAllHooks 与 managed-only gate；
3. 确认 Hook 来源已加载，plugin/skill one-shot Hook 尚未被消费；
4. 用事件的真实 matcher 字段检查配置，不要拿 tool matcher 套到 lifecycle 事件；
5. 检查 if 条件、工作目录和环境变量 allowlist；
6. 区分“命令没启动”“命令非零”“JSON 不合法”“输出修改后二次校验失败”；
7. 同时核对原动作状态：文件是否写入、请求是否到达、task 是否进入 registry、Agent 是否已继续；
8. 最后看 transcript/attachment、debug log 和持久化的大输出引用。

七、证据范围¶

这些 Static 证据可以证明客户端在 2.1.235 中怎样构造、筛选、执行和消费 Hook。它不能证明用户机器上的某个 Hook 配置已经启用，也不能证明 Hook 调用的 HTTP/MCP/脚本完成了远端业务动作。服务端账号风控、组织审计保留期、Hook endpoint 的处理逻辑和外部系统事务性都保持 Boundary。