Hooks

核心概念：Hooks (钩子)

• Hooks 的作用 (Function of Hooks):
• 将 Claude 通常遵循的规则（Rule）转化为 Claude 必须遵循的规则（Deterministic Code）。
• 确保在未被实时监控的运行中也能保证行为。
• 主要 Hook 类型 (Key Hook Types):
• Pre-tool use (工具使用前): 在工具调用之前触发，是执行强制性规则（Enforcement Primitive）的关键。
• Post-tool use (工具使用后): 在工具调用成功之后触发，常用于自动格式化或自动检查（Auto-formatting/Lint）。
• Stop (停止): 当 Claude 希望结束当前回合时触发。
• Refuse (拒绝): 当条件不满足时触发。
• Subagent stop (子代理停止): 子代理完成任务时触发的信号。
• Pre-compact / Post-compact (压缩前/后): 在对话压缩（Compaction）前后触发。
• Instructions loaded (指令加载): 当 Claude. md 或规则文件加载时触发，用于审计上下文内容。
• Session start (会话开始): 初始化环境，可配合 compact matcher 使用。

关键功能与返回值 (Key Functions and Return Values)

• Pre-tool use 的响应 (Pre-tool use Responses):
• 返回 JSON: 必须返回 JSON 格式并以退出码 0 退出，以授予权限（Permission）。
• 决策字段 (Decision Fields):
• allow: 允许执行。
• deny: 拒绝执行。
• ask: 询问用户。
• defer: 仅适用于非交互式运行，调用进程暂停并稍后恢复工具。
• 更新输入 (Updated Input): 可返回更新后的输入对象来修改工具调用（例如，从 bash 命令中移除敏感信息），但需替换整个输入对象。
• 退出码 (Exit Codes):
• 0 (Success): 成功。如果标准输出是 JSON，Claude 会解析它。
• 1 (Non-blocking): 看起来像错误，但实际上不阻塞。Claude 会继续执行命令。
• 2 (Blocking Error): 阻塞错误。标准错误会被反馈给 Claude 作为上下文。
• Stop (Blocking Stop): 用于表示“你还没有完成”，阻止 Claude 继续执行。

进阶机制 (Advanced Mechanisms)

• 上下文保留 (Context Preservation):
• Session start + compact matcher: 在对话被压缩时，使用此 Hook 重新注入上下文（Context），确保 Claude 能从上次停止的地方继续工作，而不是从头开始。
• Guardrail 机制 (Guardrail Mechanism):
• Matcher: 匹配要监控的工具（如 bash），并可选地使用 if 子句缩小范围。
• **Redaction vs. Blocking:**
• 返回 deny：阻止危险调用。
• 返回 updated input：在允许调用时，修改输入（如移除秘密），允许调用继续执行。
• 忽略阻塞的事件 (Non-blocking Events):
• 某些事件（如 notification, session start, file change）会忽略阻塞性，直接显示标准错误并继续运行。

Takeaways

• Hooks的作用是将Claude的规则（Rule）转化为必须遵循的确定性代码（Deterministic Code）。
• 工具使用前（Pre-tool use）是执行强制性规则的关键，必须返回JSON并使用allow、deny等决策字段来授予或拒绝权限。
• Guardrail机制通过Matcher监控工具，可选择返回deny阻止调用，或返回updated input进行输入修改（Redaction）。
• 使用Session start配合compact matcher实现上下文保留，确保对话在被压缩后能从上次停止的地方继续工作。