Claude Code Hooks

Hooks 会围绕 Claude Code 生命周期事件运行命令、处理器或提示词。它们可以把团队规则变成可重复检查，而不是依赖记忆。

最近核验: 2026/7/19
适用版本: 适用于 Claude Code 2.1.x。本机使用 2.1.198 检查 CLI 拼写；当前官方文档可能包含更新的 2.1.x 行为。
核验方式: 2026-07-19 对照官方文档、CLI reference 和 changelog。对照官方 reference 核验 hook schema 和退出码语义；可独立测试 blocker script，本次未写入用户 settings。
官方来源: 官方 Hooks guide 官方 Hooks reference 官方 Changelog

可复现实践

用项目 Hook 阻止危险数据库命令

先独立构建和测试确定性的 PreToolUse guard，再在 Claude Code 会话中依赖它。

准备

可信测试仓库、jq 和 POSIX shell。
仅在团队接受该策略时提交 .claude/hooks。
测试环境不含生产数据库凭据。

执行步骤

创建 blocker script
把这段完整脚本保存为 .claude/hooks/block-drop-table.sh。它从 hook JSON 读取 Bash command，保守匹配危险模式，并在 stderr 解释拒绝原因。
步骤 1
```
#!/bin/sh
COMMAND=$(jq -r '.tool_input.command // ""')
if echo "$COMMAND" | grep -Eiq 'drop[[:space:]]+table'; then
  echo 'Blocked: DROP TABLE is not allowed' >&2
  exit 2
fi
exit 0
```

在 Claude Code 外测试脚本

危险 fixture 必须返回 2，无害 fixture 必须返回 0。

步骤 2

chmod +x .claude/hooks/block-drop-table.sh
printf '%s' '{"tool_input":{"command":"drop table demo"}}' | .claude/hooks/block-drop-table.sh; test $? -eq 2
printf '%s' '{"tool_input":{"command":"git status"}}' | .claude/hooks/block-drop-table.sh

注册 PreToolUse Bash matcher
JSON 审查后才加入 project settings；hook command 指向 $CLAUDE_PROJECT_DIR/.claude/hooks/block-drop-table.sh。
在临时会话覆盖两个路径
请求无害 git status，再请求包含 DROP TABLE 的非执行命令字符串，确认后者在工具执行前被拒绝。

预期结果

独立 fixtures 分别返回 0 和 2，会话显示拒绝原因且匹配的 Bash call 未执行。

验证

用 jq -e . .claude/settings.json 校验设置。
每次改脚本都直接测试 allow 和 deny fixture。
hook 未触发时才开启 hooks debug category。

失败处理

Hook 从未触发

检查 event、Bash matcher、执行位、settings scope 和 JSON parsing。

所有命令都被阻止

把脱敏 fixture 输入脚本并收窄模式，明确 fail-safe 行为。

清理或回退

先删除 hook entry，确认设置仍可解析后再删脚本。
高风险动作仍保留普通 permission deny；Hook 不应成为唯一安全边界。

边界与不适用场景

Hook 以用户权限执行，应像生产自动化一样审查。
exit 2 可阻止 PreToolUse，但部分其他事件不可阻止，事件语义不能互换。

生命周期自动化

Hooks 可在会话开始、工具调用、文件变化和停止等节点运行。常见用途包括编辑后格式化、命令安全检查和进度记录。

质量门禁

Hook 可在相关动作后运行 lint、格式化、静态检查或自定义校验。轻量检查适合高频执行，较重检查应放在明确验证阶段。

团队约定

Hooks 可约束生成文件、审查说明、通知规则等仓库特定要求。失败信息应足够清楚，让代理和开发者知道应该修哪里。

权限

与 permission rules 配合，形成纵深防御。

阅读指南

CI/CD

在 GitHub Actions 和本地运行相同的 hook 检查。

阅读指南

插件

把团队 hooks 打包进可安装插件。

阅读指南

工作流

交付前用 Stop hooks 做最终 lint 或 test 步骤。

阅读指南

失败处理

有用的 Hook 会用聚焦的信息失败，并给出恢复路径。避免输出噪声很大的宽泛脚本，否则会掩盖真正阻塞的动作。

hooks.json 示例

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "pnpm lint --fix" }]
      }
    ]
  }
}