Lifecycle Hooks：在 Agent 关键节点自动执行

Lifecycle Hooks：在 Agent 关键节点自动执行

基础概念

Claude Code 的 Lifecycle Hooks（生命周期钩子），可以理解成在 Agent 跑的过程中预埋的若干个"开关位"。每当 Agent 走到某个关键节点——比如"准备调一个工具"、"工具刚跑完"、"用户输入还没进 LLM"、"会话即将结束"——Claude Code 这个壳就会去检查 settings.json，看你有没有为这个节点注册脚本。注册了，它就把当前节点的全部上下文（工具名、参数、cwd、session_id 等）按 JSON 喂到脚本的标准输入；脚本怎么处理、要不要拦截，由你写的逻辑决定。

为什么要单独做"hooks"，而不是让 Claude 自己在 prompt 里"记得"在某些时刻去做某事？两个原因：

1. 确定性。Claude 是概率模型，让它"记住每次写完 Python 文件都跑一次 ruff" —— 多跑几轮就会忘掉。Hook 是 CLI 这个进程外的事件钩子，不进 LLM 推理，100% 必跑。
2. 零 token 成本。Hook 跑在 LLM 之外，本身不消耗模型 token。把"格式化、跑 lint、记审计日志、拦危险命令"这些机械动作全交给 hook，模型上下文就能省下来做真正需要思考的事。

一句话说人话：hook = "Claude 不参与的、由 CLI 这一侧自动触发的脚本"。它不是给 Claude 用的工具，而是 Claude Code 这个外壳给你提供的"自动化插槽"。

核心要素

典型 hook 触发时序

下图画出一次"用户提问 → Claude 决定调 Bash → 工具执行 → Claude 输出 → 结束"完整 turn 中各 hook 的触发位置：

注意几个细节：PreToolUse 在工具真正跑之前，所以它是唯一能"拦下危险命令"的位置；PostToolUse 在工具已经成功执行之后，它能给 Claude 反馈但已经无法撤销操作——这是新手最常踩的坑（详见"常见误区"）。

基础用法

写一个 hook 一共三步：① 在 settings.json 里登记事件 + 匹配器；② 写脚本读 stdin 里的事件 JSON；③ 用 exit code 或 stdout JSON 控制后续行为。

第一步：最小可运行配置

在项目根目录建 .claude/settings.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-format.sh"
          }
        ]
      }
    ]
  }
}

这段配置的含义：每当 Claude 调用 Write 或 Edit 工具改完文件后，自动跑 .claude/hooks/auto-format.sh。$CLAUDE_PROJECT_DIR 是 Claude Code 启动时注入的环境变量，指向项目根，路径鲁棒性比写死好。

第二步：脚本读 stdin、按需做事

新建 .claude/hooks/auto-format.sh，给它执行权限（chmod +x）：

#!/bin/bash
# PostToolUse: 给刚刚被 Write/Edit 的文件按扩展名自动格式化

# Claude Code 通过 stdin 传入完整事件 JSON，这里用 jq 取出文件路径
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path')

case "$FILE_PATH" in
  *.py)   ruff format "$FILE_PATH" ;;
  *.ts|*.tsx|*.js|*.jsx) npx prettier --write "$FILE_PATH" ;;
  *.go)   gofmt -w "$FILE_PATH" ;;
  *)      exit 0 ;;  # 其他扩展名直接跳过
esac

# 把 lint 错误（如果有）回灌给 Claude
if ! ruff check "$FILE_PATH" 2>/dev/null; then
  echo "ruff 发现风格问题，请修复" >&2
fi

exit 0

预期效果：你让 Claude 改一个 app.py，Edit 工具刚执行完，Claude 还没开始下一句话，hook 已经跑完 ruff format，文件就已经是规范风格了；如果 lint 有问题，stderr 会被自动注入 Claude 的下文，让模型在下一步回复时主动修复。

第三步：拦截危险命令（阻断式 hook）

PreToolUse 是少数几个能"真的阻止 Claude 做某事"的事件之一。下面这个脚本会拦截一切 rm -rf 命令：

#!/bin/bash
# .claude/hooks/block-dangerous-bash.sh
# 注册到 PreToolUse + matcher: "Bash"

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

# 黑名单：rm -rf、sudo、curl | sh 等
if echo "$COMMAND" | grep -qE '(rm\s+-rf|sudo|curl\s+[^|]+\|\s*sh)'; then
  # 用 hookSpecificOutput 给 PreToolUse 显式 deny
  jq -n --arg cmd "$COMMAND" '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: ("拦截高危命令：" + $cmd + "。请改用更安全的方案。")
    }
  }'
  exit 0
fi

exit 0

对应 settings.json 片段：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-bash.sh" }
        ]
      }
    ]
  }
}

效果：模型若生成了 rm -rf dist/，命令根本不会跑到 shell，原因会回灌给模型，让它换一种方式（比如逐文件删）。这比依赖"我让 Claude 别用 rm -rf"的提示词靠谱得多。

速查：PreToolUse 控制工具执行的标准做法是 hookSpecificOutput.permissionDecision，可选值 "allow" | "deny" | "ask" | "defer"，多个 hook 同时触发时优先级 deny > defer > ask > allow。

Claude Code 当前支持的事件清单（节选）

同类工具对比

CLI Agent 周边有不少"自动化"机制，初学者常分不清。下面这张表把 hooks 和最容易混的几个邻居放一起对比：

核心区别一句话：hooks 是 CLI 外壳的事件回调，确定性、零 token、能硬拦；Skills/MCP/Rules 是 喂给模型的上下文或工具，灵活但不可靠。要"必须执行"用 hooks，要"灵活执行"用 Skills/MCP，要"风格约定"用 CLAUDE.md。互相不能替代。

互链：MCP 和 hooks 的关系详见 /mcp/cards/what-is-mcp；Skills 和 hooks 怎么搭配见 /skills/cards 下相关卡。

常见误区

优劣势分析

思考题

#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path')
[[ "$FILE" == *.py ]] || exit 0

if ! OUTPUT=$(ruff check "$FILE" 2>&1); then
  echo "ruff 报错，请修复后重试：" >&2
  echo "$OUTPUT" >&2
  exit 2   # PostToolUse 上 exit 2 = 把 stderr 注入下一轮上下文
fi

参考资料

1. Claude Code Hooks 官方参考：https://code.claude.com/docs/en/hooks（查询日期 2026-04-22）
2. Claude Code Settings 官方文档：https://code.claude.com/docs/en/settings（查询日期 2026-04-22）
3. Claude Code GitHub 仓库 - Issues 关于 hook 行为的讨论：https://github.com/anthropics/claude-code/issues/19009（PostToolUse exit 2 行为）
4. Claude Code GitHub Issue #24327：https://github.com/anthropics/claude-code/issues/24327（PreToolUse exit 2 边界场景）
5. Steve Kinney - Claude Code Hook Control Flow：https://stevekinney.com/courses/ai-development/claude-code-hook-control-flow
6. Claude Directory Blog - Claude Code Hooks Guide 2026：https://www.claudedirectory.org/blog/claude-code-hooks-guide
7. Pixelmojo - Claude Code Hooks: All 12 Events with Examples (2026)：https://www.pixelmojo.io/blogs/claude-code-hooks-production-quality-ci-cd-patterns