钩子（hooks）是什么

它是什么

钩子（hooks）是在固定生命周期点自动执行的命令或校验。比如工具调用之前、工具调用之后、会话开始、代理准备停止时，宿主按配置运行你指定的脚本，不需要模型同意，也不由模型决定是否跳过。

它解决的是「每次都别忘了做某件事」。格式化、跑检查、拦截危险命令、记录审计日志、发通知，这些动作适合交给钩子，而不是写进提示里指望模型记住。

钩子不是模型能力，是你自己的代码。它跑在你的机器上，用的是你的权限。

怎么工作

以 Claude Code 为例，钩子配置里主要包含事件、匹配条件与要执行的命令。事件决定时机，匹配条件用来限定工具或范围，命令拿到一份 JSON 输入，里面有会话、工具名和参数。

执行结果通常看退出码：

• 正常退出，动作继续；
• 特定退出码表示阻断，错误信息会回传给模型，让它知道为什么被拦；
• 其他非零退出码一般只提示错误，不阻断。

所以「失败时阻断还是放行」要提前设计。拦截危险操作的钩子应该阻断，并给出可执行的替代建议；格式化、日志这类钩子失败时通常放行，避免因为一个辅助脚本挂掉整个流程。还要设超时，钩子卡住会拖住整个回合。

钩子适合放在这些位置：

• 写文件后自动格式化、跑 lint；
• 执行命令前检查是否碰到生产环境、是否包含删除操作；
• 每次工具调用后追加审计记录，留下谁在什么时候改了什么；
• 会话结束时汇总本次改动。

它和工具调用互补：工具调用是模型发起的动作，钩子是宿主在动作前后加的固定关卡。它和权限系统也不是一回事：权限回答「这个工具能不能用」，钩子回答「这一次具体操作要不要额外检查、做完之后要做什么」。权限是边界，钩子是边界上的检查和副作用。钩子本身不是沙箱，写得不好会误放行，也会误拦截。在Agent 循环里，这种确定性尤其重要：模型可以改变计划，但改变不了钩子的运行时机。

常见误解

• 「钩子是提示词」：不是。它不进入模型的对话，模型也无法说服它跳过。
• 「加了钩子就安全」：钩子只能检查你想到的情况；它降低误操作概率，不保证隔离。
• 「钩子能撤销操作」：工具执行后的钩子只能做事后处理，已经发生的写入不会自动回滚。
• 「所有事件都能阻断」：不同生命周期点能力不同，有的只能观察和记录，设计前先查清楚。