Claude Code Hooks：构建可编程、可管控的 AI 编码代理
在 AI 编码代理（AI Coding Agent）的演进中，最大的痛点在于模型只能“建议”而非“执行”。Claude Code Hooks 的出现，正是为了解决这一瓶颈。它允许用户在 AI 生命周期的特定节点自动运行自定义命令、HTTP 端点或 MCP 工具调用，从而实现对代码检查、危险操作拦截、日志记录及上下文注入的确定性控制。
什么是 Claude Code Hooks？
Hook 本质上是一个处理程序（Handler），它会在 Claude Code 暴露的生命周期事件发生时自动执行。与传统的“提示词工程”不同，Hooks 将 AI 代理从一个依赖概率的“聪明助手”，转变为一个遵循团队规则的“可编程助手”。
核心能力
- 拦截与阻止：在工具调用前（PreToolUse）阻止危险操作。
- 校验与格式化：在工具调用后（PostToolUse）自动运行 Linter 或 Formatter。
- 审计与记录：记录所有工具调用的参数与结果，满足合规需求。
- 改写与注入：动态修改工具输入或注入额外上下文。
生命周期事件与触发机制
Hooks 挂载在事件上，覆盖了从会话开始到结束的完整流程。以下是最高频触发的关键事件：
| 事件类型 | 触发时机 | 典型应用场景 |
|---|---|---|
| SessionStart | 会话开始时 | 加载项目上下文、环境变量、未解决 Issue |
| UserPromptSubmit | 用户提交提示后 | 过滤或增强用户输入 |
| PreToolUse | 工具调用之前 | 阻断危险命令（如 rm -rf） |
| PostToolUse | 工具调用之后 | 代码检查、格式化、验证输出 |
| Stop | 响应完成时 | 发送桌面通知、记录最终日志 |
此外，系统还支持子代理（Subagent）、任务（Task）、上下文压缩（Compact）及文件变更（FileChanged）等细粒度事件，几乎覆盖了代理循环的每一个环节。
五种 Hook 处理程序类型
系统提供了高度的灵活性，支持五种类型的处理程序：
- command：运行 Shell 命令。通过
stdin接收输入，通过退出码（Exit Code）和stdout传达决策。这是最常用的类型。 - http：将事件 JSON 以 POST 方式发送到自定义 URL，并读取响应。
- mcp_tool：调用已连接的 MCP 服务器上的工具。
- prompt：进行一次单轮模型评估，返回结构化决策（如
is_valid: true）。 - agent：生成子代理（实验性功能）。
注：对于大多数团队，
command类型的 Shell 脚本即可满足 90% 的需求。
核心配置与实战范例
配置结构
Hooks 配置位于 settings.json 中，结构分为三层：
- 事件：选择触发时机（如
PostToolUse）。 - 匹配器 (Matcher)：定义适用的工具（如
"Edit|Write"或正则表达式）。 - 处理程序 (Handlers)：定义具体执行的命令或逻辑。
实战案例：阻断破坏性命令
这是一个典型的 PreToolUse Hook 配置，用于防止 rm -rf 等危险操作：
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"handlers": [
{
"type": "command",
"command": "/path/to/guard.sh"
}
]
}
]
}
}
配合脚本 guard.sh：
#!/usr/bin/env bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')
# 关键逻辑：使用 exit 2 阻断
if echo "$cmd" | grep -Eq 'rm +-rf|mkfs'; then
echo "Blocked: destructive command refused by policy." >&2
exit 2 # 只有 exit 2 才会真正阻止操作
fi
exit 0
关键细节：退出码陷阱
这是使用 Hooks 时最容易踩的坑。对于 command 类型的 Hook，只有退出码 2 才会阻止操作。
- Exit Code 0：成功。
stdout会被解析以获取 JSON 决策。 - Exit Code 2：阻断性错误。
stderr会被反馈给 Claude，操作被终止。 - Exit Code 1：非阻断性错误。Claude 会忽略此错误并继续执行。
警示：如果你编写了一个阻断脚本却使用 exit 1，该操作依然会执行！务必使用 exit 2。
适用场景与局限
- 适用：确定性规则（如“所有编辑后必须格式化”、“禁止运行 rm -rf”）、审计日志。
- 不适用：需要复杂判断的场景（建议使用
prompt类型 Hook 或权限系统）、需要交互式终端的场景（Hooks 无/dev/tty）。
结语：Harness Engineering 的落地
Claude Code Hooks 是 Harness Engineering（运行框架工程） 理念的具体体现。它让开发者能够围绕 AI 模型构建确定的护栏，而非仅仅依赖模型的随机性。对于希望在不配置本地环境的情况下体验完整能力的用户，Happycapy 提供了基于云端沙箱的托管解决方案，让 Hooks 机制在浏览器中无缝运行。
通过 Hooks，你不再是在训练一个模型，而是在构建一个拥有明确规则、可审计、可管控的自动化工程系统。
