Agent 教程

外观

Hooks ​

Hooks 是 Agent 产品的扩展点。

Claude Code 在工具执行前后支持 Hook，大致分为：

  • PreToolUse
  • PostToolUse
  • PostToolUseFailure
  • session lifecycle hooks

这些 Hook 允许外部逻辑参与执行流程，而不需要改核心 AgentLoop。

Hook 插入在哪里 ​

典型位置：

text
schema parse
  -> validate input
  -> PreToolUse Hook
  -> permission
  -> execute tool
  -> PostToolUse Hook
  -> return tool_result

Pre Hook 可以用于：

  • 记录审计。
  • 阻止某些工具。
  • 修改输入。
  • 提供权限决策。

但要注意：Hook 给出的 allow 不应该直接绕过权限系统。Claude Code 通过 resolveHookPermissionDecision() 合并 Hook 决策和正常权限判断，显式 deny/ask 规则仍然可以覆盖 Hook allow。

Post Hook 可以用于：

  • 记录执行结果。
  • 附加额外上下文。
  • 触发外部自动化。
  • 做失败处理。

Hook 的风险 ​

Hook 能力越强，系统越难调试。

如果 Hook 能修改输入、修改结果、阻止继续、改变权限决策，那么一次工具调用的行为就不再只由工具本身决定。

Claude Code 支持强 Hook，是因为它需要接入大型产品生态。自己写 Agent 时，建议先限制 Hook 能力。

简化版 Hook 设计 ​

推荐第一版只做：

ts
type Hooks = {
  beforeTool?: (event: ToolEvent) => Promise<"continue" | "deny">
  afterTool?: (event: ToolResultEvent) => Promise<void>
  onToolError?: (event: ToolErrorEvent) => Promise<void>
}

不要一开始允许 Hook 改输入和改结果。

小结 ​

Hook 的本质是把 Agent 核心循环和外部策略解耦。但 Hook 不是越强越好，能力边界越清晰，系统越容易维护。