前言

在 AI 辅助编程的时代，Claude Code 已经成为开发者的得力助手。然而，一个核心挑战始终存在：Claude 是概率性的，但我们的工作流需要确定性保障。

Claude 可能误改 .env 文件导致密钥泄露，或执行危险命令删除重要文件。这些风险提醒我们：需要一个机制在关键节点进行拦截和验证——这就是 Hooks 登场的时刻。

本文是 Agent Hooks 系列的第一篇，将系统介绍 Claude Code Hooks 的核心概念、类型划分和生命周期事件，为第二篇的实战配置打下理论基础。

一、Hooks 是什么？核心概念解析

1.1 定义

Hooks（钩子） 是用户定义的 Shell 命令、HTTP 请求或 AI 提示，在 Claude Code 生命周期的特定节点自动执行。它们可以：

• 检查输入：在操作执行前验证参数
• 采取行动：执行自动化任务
• 返回决定：允许、阻止或修改操作

用一个比喻来理解：如果把 Claude Code 比作一个智能助手，Hooks 就像是它的"安全带"和"自动导航仪"——既能在危险操作前紧急刹车，也能在常规任务上自动巡航。

1.2 核心价值

Hooks 解决了三个核心问题：

问题	Hooks 的解决方案
安全性	拦截危险命令（如 rm -rf）、保护敏感文件
一致性	自动格式化代码、强制执行团队规范
自动化	Git 自动暂存、测试自动运行、通知自动发送

二、五种 Hook 类型详解

Claude Code 提供了五种 Hook 类型，覆盖从简单脚本到复杂 AI 验证的各种场景。

2.1 Command Hook（命令型）

最常用的类型，覆盖 90% 的使用场景。

Command Hook 执行 Shell 命令，通过标准输入（stdin）接收 JSON 数据，通过退出代码和标准输出（stdout）返回结果。

{
  "type": "command",
  "command": "./scripts/check-command.sh"
}

退出代码含义：

退出代码	含义	效果
0	成功	操作继续，stdout 注入 Claude 上下文
2	阻止	操作被阻止，stderr 作为错误消息
其他	警告	操作继续，stderr 写入日志

典型场景： 文件保护、命令日志、自动格式化。

2.2 HTTP Hook

HTTP Hook 将 JSON 数据以 POST 请求发送到指定 URL，适合与外部服务集成。

{
  "type": "http",
  "url": "https://api.example.com/hook",
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}"
  }
}

典型场景： 调用远程 API、与 CI/CD 系统集成、发送飞书/钉钉通知。

2.3 Prompt Hook（提示型）

Prompt Hook 是一个"AI 守门员"，让 AI 模型（默认使用快速模型如 Haiku）对某个条件进行单轮判断，返回 yes/no 决定。

{
  "type": "prompt",
  "prompt": "检查 Claude 是否完成了用户要求的所有任务。如果完成返回 {\"ok\": true}，否则返回 {\"ok\": false, \"reason\": \"具体说明\"}。$ARGUMENTS"
}

响应格式：

{
  "ok": true,
  "reason": "决策解释"
}

典型场景： 任务完成度检查、代码质量判断、复杂条件验证。

2.4 Agent Hook（代理型）- 实验性

Agent Hook 会启动一个子 Agent（subagent），它可以使用工具进行多轮验证（最多 50 轮）。这是最强大的 Hook 类型，但也最消耗资源。

{
  "type": "agent",
  "prompt": "运行测试并验证所有测试是否通过。$ARGUMENTS",
  "timeout": 120
}

典型场景： 自动运行测试套件、代码审查、复杂的多步骤验证。

2.5 MCP Tool Hook

MCP Tool Hook 直接调用已连接的 MCP（Model Context Protocol）服务器上的工具。

{
  "type": "mcp_tool",
  "server": "memory",
  "tool": "store",
  "input": {
    "key": "last_modified",
    "value": "2026-04-26"
  }
}

典型场景： 与 MCP 生态集成、调用专业工具。

2.6 类型对比总结

类型	复杂度	灵活性	典型场景
Command	低	中	脚本自动化、文件操作
HTTP	中	中	远程服务集成
Prompt	中	高	AI 自主判断
Agent	高	最高	多轮验证、测试运行
MCP Tool	中	中	MCP 工具调用

三、生命周期事件全景图

Hooks 在 Claude Code 的生命周期中特定事件触发时执行。理解这些事件，是正确配置 Hooks 的关键。

3.1 事件流程图

Claude Code Hooks 九大事件：PreToolUse、PostToolUse、Notification、UserPromptSubmit、Stop、SubagentStop、PreCompact、SessionStart、SessionEnd

3.2 事件分类详解

会话级别事件

事件	触发时机	可阻止	用途
SessionStart	会话开始或恢复	否	初始化环境、加载配置
SessionEnd	会话终止	否	清理资源、保存状态

提示级别事件

事件	触发时机	可阻止	用途
UserPromptSubmit	用户提交提示后，Claude 处理前	是	验证用户输入、添加上下文
UserPromptExpansion	斜杠命令展开时	是	阻止特定命令调用

工具级别事件

事件	触发时机	可阻止	用途
PreToolUse	工具调用执行前	是	拦截危险操作、修改参数
PermissionRequest	权限对话框出现时	是	自动放行或拒绝
PermissionDenied	权限被拒绝时	否	记录日志、重试
PostToolUse	工具成功完成后	否	自动格式化、Git 暂存
PostToolUseFailure	工具执行失败时	否	错误处理、日志记录

其他重要事件

事件	触发时机	可阻止	用途
Stop	Claude 完成响应时	是	最终验证、任务完成检查
Notification	发送通知时	否	发送外部通知（Slack等）
PreCompact	上下文压缩前	是	保存关键信息
PostCompact	上下文压缩后	否	重新注入上下文

3.3 最常用的四个事件

根据实践经验，以下四个事件覆盖了绝大多数使用场景：

1. PreToolUse：工具执行前，最适合拦截危险操作
2. PostToolUse：工具执行后，适合自动格式化、自动提交
3. Notification：Claude 等待输入时，适合发送通知
4. Stop：Claude 完成回复时，适合做最终验证

四、配置方式与最佳实践

4.1 配置文件位置

Hooks 可以配置在多个位置，作用范围不同：

位置	作用范围	可提交 Git	适用场景
~/.claude/settings.json	所有项目	否	个人全局配置
.claude/settings.json	当前项目	是	团队共享规范
.claude/settings.local.json	当前项目	否	个人项目配置

4.2 配置结构

4.3 Matcher 匹配器规则

Matcher 用于指定 Hook 应用于哪些工具：

Matcher 值	匹配规则	示例
* 或 "" 或省略	匹配所有	所有工具都触发
仅字母、数字、_ 和 |	精确匹配	Bash 或 Edit|Write
包含其他字符	正则表达式	^mcp__.* 匹配 MCP 工具

MCP 工具命名模式： mcp__<server>__<tool>

• mcp__memory__.* 匹配 memory 服务器的所有工具
• mcp__.*__write.* 匹配任何服务器以 write 开头的工具

4.4 Hook 输入输出机制

Hook 通过标准输入（stdin）接收 JSON 格式的事件数据：

{
  "session_id": "abc123",
  "cwd": "/Users/you/project",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

通过退出代码和标准输出返回决定：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "禁止执行该命令"
  }
}

五、总结

本文要点回顾

1. Hooks 本质：在 Claude Code 生命周期的特定节点自动执行的逻辑，为概率性 AI 添加确定性保障
2. 五种类型：Command（最常用）、HTTP、Prompt、Agent、MCP Tool
3. 生命周期事件：从 SessionStart 到 SessionEnd，PreToolUse 和 PostToolUse 是最常用的事件
4. 配置方式：支持全局配置和项目配置，通过 matcher 精确控制触发条件

---

参考资料：

• Claude Code Hooks 官方文档
• Claude Code Hooks 实战指南

---

本文首发于 CSDN，作者：kingwu