跳到主要内容

hook 系统

在 agent 生命周期节点做确定性拦截，比 prompt 约束更可靠的原因

核心要点：

  • hook 在生命周期节点自动执行
  • 事件按 Session/Turn/Tool-Use 分粒度
  • PreToolUse 可阻断，deny 让模型改方案重试
  • hook 是代码强制，不耗推理、抗注入
  • 模型决定"做什么",hook 决定"能不能"

本文讲 hook 扩展机制。skill 见 02-skill系统。

hook 是什么，在哪触发？​

核心问题：想在 agent 每次调工具前后自动做点事，该用什么？

hook 是在 agent 生命周期节点自动执行的处理器，按事件触发[1]。它不是让模型决定，而是在固定时点由系统强制运行。

事件按三个粒度分层：Session（会话级）、Turn（轮次级）、Tool-Use（工具调用级）。核心事件包括：

  • PreToolUse：工具执行前触发，可阻断。
  • PostToolUse：工具执行后触发，不可阻断，可注入后置上下文。
  • Stop：一轮完成时触发。

处理器可以是 shell 命令、HTTP 调用、MCP 工具等多种形式。可借鉴的用途：格式化、校验、阻断危险操作、注入上下文——都是确定性的自动化动作。

hook 能拦截和阻断吗？​

核心问题：PreToolUse 能不能直接拦下一个危险操作？

能——PreToolUse 可以 deny 阻断，但这是"路由信号"而非硬停止[1]。被 deny 后，模型收到拒绝信息会修正方案重试，而非直接崩溃。

这个设计很关键：阻断保留了 agent 的自适应能力。hook 说"这条路不行"，模型换一条路，而不是任务直接失败。它和 09-人机交互/02-权限与审批 的 deny-first 是同一思路在不同层——权限门管授权，hook 管自定义的生命周期逻辑。可借鉴的判断：阻断要给模型反馈让它改，而非粗暴终止。

hook 为什么比 prompt 约束更可靠？​

核心问题：同样是"别做某事"，写进 system prompt 和写成 hook 有什么区别？

hook 是代码层面的强制，不受 prompt injection 影响、不消耗推理注意力[2]。prompt 约束是"请模型记住",hook 是"系统保证执行"，可靠性差一个量级。

两个关键优势：

  • 抗注入：hook 是确定性代码，不会被注入的恶意指令绕过(对比 07-安全与沙箱/02-prompt-injection)。
  • 不耗注意力：hook 不占上下文、不分散模型推理，而 prompt 约束要常驻上下文且可能被淹没。

可借鉴的原则：必须保证的约束写成 hook，不要只写进 prompt——prompt 是软提示，hook 是硬保证。

hook 和 agent 自主性是什么关系？​

核心问题：加了一堆 hook，会不会把 agent 框死失去灵活？

hook 实现"确定性自动化与模型自主性的分离"：模型决定做什么，hook 决定能不能做[2]。两者分工而非互相挤压。

这对应 Claude Code 的 "minimal scaffolding, maximal operational harness" 原则——不限制模型的认知路径（让它自由推理），但用确定性的 harness 框住执行（hook、权限、沙箱）。可借鉴的设计哲学：把"判断"留给模型、把"保证"交给代码，agent 才能既灵活又可控。这也是整个 01-总览 章 harness 思想的微观体现。

Takeaway​

知识点核心结论
hook 定位生命周期节点的确定性处理器，系统强制执行
事件分层Session / Turn / Tool-Use,PreToolUse 可阻断
阻断设计deny 是路由信号，模型改方案重试而非崩溃
比 prompt 可靠代码强制、抗注入、不耗推理注意力
自主性分工模型决定"做什么",hook 决定"能不能"

参考资料​

  1. Anthropic. Hooks reference. Claude Code Docs, 2025. https://code.claude.com/docs/en/hooks
  2. Liu et al. Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems. arXiv:2604.14228, 2026. https://arxiv.org/abs/2604.14228

延伸阅读​