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。

接下來去哪