---
title: "Hooks"
description: "Hooks 是 Claude Code 的扩展机制——在工具调用前后注入自定义逻辑。理解四种 Hook 能力、匹配机制和安全防护。"
keywords: ["Hooks", "生命周期钩子", "拦截器", "PreToolUse", "Hook 协议"]
---

## 核心问题

Claude Code 提供了强大的内置功能，但每个团队和工作流都不同。Hooks 让你可以在关键节点注入自定义逻辑——不需要修改 Claude Code 本身。

## Hook 事件

Hooks 覆盖 Agent 生命周期的所有关键节点：

| 阶段 | 典型事件 |
|------|---------|
| **会话** | 启动、结束、初始化 |
| **用户交互** | 提交消息、停止响应 |
| **工具执行** | 工具调用前、工具调用后（成功/失败） |
| **权限** | 权限请求、权限被拒 |
| **子 Agent** | 启动、停止 |
| **压缩** | 压缩前、压缩后 |
| **协作** | Teammate 空闲、任务创建/完成 |

## 四种 Hook 能力

Hook 不仅是"执行一个脚本"——它有四种不同的能力：

### 1. 拦截操作（PreToolUse）

在工具执行前拦截，可以阻止危险操作：

```json
{
  "hookSpecificOutput": {
    "permissionDecision": "deny",
    "permissionDecisionReason": "不允许在生产分支上强制推送"
  }
}
```

### 2. 修改行为

修改工具的输入或输出：

```json
{
  "hookSpecificOutput": {
    "updatedInput": { "command": "npm test -- --bail" }
  }
}
```

PostToolUse 的 `updatedMCPToolOutput` 可以替换 MCP 工具的返回值——用于过滤敏感数据。

### 3. 注入上下文

向 AI 的对话中注入额外信息：
- `additionalContext` — 注入为用户消息，AI 可以参考
- `systemMessage` — 显示为系统警告

### 4. 控制流程

阻止 Agent 继续执行：

```json
{
  "continue": false,
  "stopReason": "构建失败，停止执行"
}
```

**设计洞察**：四种能力从"被动观察"到"主动干预"递进。最简单的 Hook 只是记录日志，最强大的 Hook 可以阻止操作、修改输入、控制流程。

## 六种 Hook 类型

| 类型 | 执行方式 | 适用场景 |
|------|---------|---------|
| `command` | Shell 命令 | 通用脚本、CI 检查 |
| `prompt` | 注入到 AI 上下文 | 代码规范提醒 |
| `agent` | 启动子 Agent | 复杂分析任务 |
| `http` | HTTP 请求 | 远程服务、Webhook |
| `callback` | 内部 JS 函数 | 系统内置 Hook |
| `function` | 运行时函数 | Agent/Skill 内部使用 |

### 异步 Hook

Hook 进程的 stdout 第一行如果是 `{"async":true}`，系统将其转为后台任务。异步 Hook 完成后通过通知机制汇报结果。

**设计考量**：有些 Hook 需要长时间运行（如"等待 CI 结果"），不应该阻塞 Agent 的执行。异步 Hook 让这些操作在后台运行，完成后再通知 Agent。

## 匹配机制

### Matcher 模式

```
"Write"              → 精确匹配
"Write|Edit"         → 多值匹配
"^Bash(git.*)"       → 正则匹配
"*" 或 ""            → 通配所有
```

### if 条件

Hook 可以指定 `if` 条件，只在特定输入时触发：

```json
{
  "command": "check-branch.sh",
  "if": "Bash(git push*)"
}
```

条件使用与权限规则相同的语法——工具名 + 参数模式。Bash 工具还会进行 AST 级别的命令解析。

### 多来源合并

Hook 从多个来源汇聚：
- settings.json 中的配置（user/project/local）
- SDK 注册的回调
- Agent/Skill 的 frontmatter
- 运行时动态注册

同一命令可能在不同层级重复出现。系统按复合键去重，保留最后合并的层级。

## 安全防护

### 工作区信任

**所有 Hook 都要求工作区信任**。这是纵深防御——防止恶意仓库的 `.claude/settings.json` 在未信任的情况下执行任意命令。

**设计哲学**：Hook 有执行任意命令的能力，这个能力不应该被不可信的来源获取。项目级配置是团队共享的，任何人都可以修改——信任检查确保只有用户明确信任的项目才能运行 Hook。

### 超时控制

Hook 有默认 10 分钟的超时限制，可以通过配置调整。超时后 Hook 进程被终止，Agent 继续执行。

## Session Hook 的生命周期

Agent 和 Skill 可以注册 session Hook，绑定到特定的 session ID。Agent 结束时自动清理——Agent A 的 Hook 不会泄漏到 Agent B 的执行中。

**设计考量**：如果不自动清理，Agent A 的 PreToolUse Hook 可能意外拦截 Agent B 的工具调用，导致难以调试的问题。

## 接下来

- **Skills** — 理解基于 Hook 的技能系统
- **MCP 配置** — 理解外部工具的注册
- **权限模型** — 理解 PreToolUse Hook 与权限系统的协作