---
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="/docs/github-copilot/official/09-sdk-and-custom-agents/observability" />
  <Card title="自定义 Agent" description="给不同 agent 配不同 hook 和工具边界。" href="/docs/github-copilot/official/09-sdk-and-custom-agents/custom-agents" />
</Cards>
