SDK Hooks

SDK Hooks（钩子）是让 agent 进入工程治理的关键点。没有 hooks，你只能事后看结果；有 hooks，你可以在工具调用前拦截、在调用后记录、在会话开始时注入上下文、在出错时统一处理——这是把 demo 升到生产 agent 必经的一道关。

1. 官方 hooks 清单

GitHub 官方 quickstart 列出这些 hooks：

• onPreToolUse：工具执行前，用于权限控制和参数校验。
• onPostToolUse：工具执行后，用于结果转换和日志记录。
• onUserPromptSubmitted：用户发送消息时，用于 prompt 修改和过滤。
• onSessionStart：会话开始，用于追加上下文和配置 session。
• onSessionEnd：会话结束，用于清理和分析。
• onErrorOccurred：发生错误时，用于自定义错误处理。

flowchart TD
    Start["onSessionStart"] --> Prompt["onUserPromptSubmitted"]
    Prompt --> Pre["onPreToolUse"]
    Pre --> Decision{"allow / deny / modify?"}
    Decision --> Tool["Tool executes"]
    Tool --> Post["onPostToolUse"]
    Post --> Response["Assistant response"]
    Response --> End["onSessionEnd"]
    Tool --> Error["onErrorOccurred"]

    style Pre fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style Error fill:#fee2e2,stroke:#dc2626,stroke-width:2px

2. 最小拦截示例

onPreToolUse 可以返回 permissionDecision：

const blockedTools = ["shell", "bash", "exec"];

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      if (blockedTools.includes(input.toolName)) {
        return {
          permissionDecision: "deny",
          permissionDecisionReason: "Shell access is not permitted",
        };
      }
      return { permissionDecision: "allow" };
    },
  },
});

这类 hook 适合做：

• 工具 allowlist / denylist。
• 参数校验。
• 路径边界检查。
• 高风险操作审批。
• 敏感 prompt 过滤。

3. Hook 的正确职责

适合放进 hook：

• 记录 tool name、tool args、tool result 摘要。
• 阻止危险工具。
• 注入用户偏好和当前组织上下文。
• 统一错误处理。
• 添加 trace correlation id。

不适合放进 hook：

• 大段业务逻辑。
• 长时间阻塞任务。
• 靠字符串猜测所有安全风险。
• 把密钥打进日志。
• 悄悄改写用户意图。

4. 商业级 hook 策略

上线前至少做 4 类 hook：

1. Pre-tool guard：阻止危险工具、危险路径、危险参数。
2. Post-tool audit：记录成功和失败结果，但脱敏。
3. Session context：注入 tenant、role、policy version。
4. Error handling：把错误分成可重试、需人工、应停止。

Hook 输出会进入 agent 工作流，必须控制噪声。过多日志或过长上下文会反过来污染模型判断。

本章自检

1. 是否有 onPreToolUse 阻止危险工具？
2. 是否有 onPostToolUse 记录工具调用结果？
3. 是否避免把敏感数据写入日志或上下文？
4. 是否有 onErrorOccurred 的分级处理？
5. 是否能把 hook 事件关联到 session 和用户？

通过标准：工具调用前能控，调用后能查，失败时能解释。

官方来源

• Quickstart for hooks —— GitHub 官方 hooks 清单和示例。
• Pre-tool use hook —— GitHub 官方工具执行前 hook。
• Post-tool use hook —— GitHub 官方工具执行后 hook。
• Error handling hook —— GitHub 官方错误处理 hook。

接下来去哪