---
title: "SDK Hooks"
description: "說明 Copilot SDK hooks 如何控制工具執行、修改結果、注入上下文、處理錯誤和審計互動。"
verifiedAt: "2026-05-06"
---

SDK Hooks（鉤子）是讓 agent 進入工程治理的關鍵點。沒有 hooks，你只能事後看結果；有 hooks，你可以在工具呼叫前攔截、在呼叫後記錄、在會話開始時注入上下文、在出錯時統一處理——這是把 demo 升到生產 agent 必經的一道關。

> [!IMPORTANT]
> Hook 不是安全銀彈：底層許可權收緊（API token / 網路 / 檔案許可權）才是第一道防線，hook 是第二道控制和審計。兩條防線缺一道都會留漏洞。

## 1. 官方 hooks 清單

GitHub 官方 quickstart 列出這些 hooks：

- `onPreToolUse`：工具執行前，用於許可權控制和引數校驗。
- `onPostToolUse`：工具執行後，用於結果轉換和日誌記錄。
- `onUserPromptSubmitted`：使用者傳送訊息時，用於 prompt 修改和過濾。
- `onSessionStart`：會話開始，用於追加上下文和配置 session。
- `onSessionEnd`：會話結束，用於清理和分析。
- `onErrorOccurred`：發生錯誤時，用於自定義錯誤處理。

```mermaid
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`：

```ts
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 工作流，必須控制噪聲。過多日誌或過長上下文會反過來汙染模型判斷。

<details>
<summary>深讀：hook 不是安全銀彈</summary>

Hook 可以攔截 SDK session 內的行為，但不能替代底層許可權。真正不能訪問的系統，API token、網路、檔案許可權都應該先收緊。

最穩的安全模型是：底層許可權最小化，hook 做二次控制和審計。
</details>

## 本章自檢

1. 是否有 `onPreToolUse` 阻止危險工具？
2. 是否有 `onPostToolUse` 記錄工具呼叫結果？
3. 是否避免把敏感資料寫入日誌或上下文？
4. 是否有 `onErrorOccurred` 的分級處理？
5. 是否能把 hook 事件關聯到 session 和使用者？

透過標準：工具呼叫前能控，呼叫後能查，失敗時能解釋。

## 官方來源

- [Quickstart for hooks](https://docs.github.com/en/copilot/how-tos/copilot-sdk/use-hooks/quickstart) —— GitHub 官方 hooks 清單和示例。
- [Pre-tool use hook](https://docs.github.com/en/copilot/how-tos/copilot-sdk/use-hooks/pre-tool-use) —— GitHub 官方工具執行前 hook。
- [Post-tool use hook](https://docs.github.com/en/copilot/how-tos/copilot-sdk/use-hooks/post-tool-use) —— GitHub 官方工具執行後 hook。
- [Error handling hook](https://docs.github.com/en/copilot/how-tos/copilot-sdk/use-hooks/error-handling) —— GitHub 官方錯誤處理 hook。

## 接下來去哪

<Cards>
  <Card title="可觀測性" description="把 hook 事件和 OpenTelemetry trace 串起來。" href="/zh-Hant/docs/github-copilot/official/09-sdk-and-custom-agents/observability" />
  <Card title="自定義 Agent" description="給不同 agent 配不同 hook 和工具邊界。" href="/zh-Hant/docs/github-copilot/official/09-sdk-and-custom-agents/custom-agents" />
</Cards>
