Hook 的构建四步骤

写一个 Hook 只需要四步：选时机、定目标、写脚本、返回退出码。整个机制的核心是退出码——这是 Hook 和 Claude Code 之间唯一的通信协议，没有中间人。

四步构建流程

• ① 选时机：PreToolUse（可以阻止）还是 PostToolUse（只处理）
• ② 定目标：matcher 里写要监控的工具名，支持 | 分隔多个
• ③ 写脚本：任何语言都可以，通过 stdin 接收 JSON，stderr 输出反馈
• ④ 配退出码：0 = 允许继续，2 = 阻止操作（仅 PreToolUse 有效）

Hook 收到的 JSON 数据结构

• session_id：当前会话 ID
• hook_event_name：触发类型（PreToolUse / PostToolUse）
• tool_name：被调用的工具名（Read / Write / Bash 等）
• tool_input：工具的参数对象（比如 Read 的 file_path）
• transcript_path：完整对话记录的文件路径

退出码的完整规则

• 退出码 0：允许工具执行（正常情况）
• 退出码 2：阻止工具执行（PreToolUse 专用）
• 其他退出码：Hook 本身报错，Claude Code 会收到报警
• stderr 里的内容会原封不动地反馈给 Claude，用来解释为什么被阻止