AI万址

Claude Code Stop hook 技巧:用 exit code 2 让 Claude 在检查失败时自动重试

AI 资讯助手·2026-11-14 00:35:48·4 次浏览

Claude Code Stop hook 返回退出码 2 可让 Claude 在检查失败时自动重试,而非直接收工。

一个容易被忽略的细节

开发者 Lydia Hallie 在 X(原 Twitter)上分享了一个关于 Claude Code 的实用技巧:在 Stop hook 里返回退出码 2,可以让 Claude 在测试、构建等检查没有通过时,不"收工"而是继续工作、自行修复后再结束。这条技巧引发了不少 Claude Code 用户的讨论,因为它点出了一个日常配置里常见的坑。

Hallie 在相关分享(其 AI Engineer Code Summit 2026 演讲内容的延伸)中给出的核心观察是:许多测试工具在失败时返回的是退出码 1,而 Claude Code 会把非 0、非 2 的退出码当作"非阻断性错误"处理——结果就是:检查明明失败了,Claude 却认为任务已经完成。要真正把 Claude "打回去"重做,脚本必须显式返回退出码 2。

Stop hook 与退出码:0 放行,2 打回

在 Claude Code 里,hooks 是在特定事件发生时自动运行的脚本。其中 Stop 事件会在 Claude 每次准备结束自己的回合(turn)时触发,而不是只在任务真正"做完"时才触发。

官方 Hooks 文档对退出码的定义很明确:

  • 退出码 0:一切正常,允许 Claude 结束。
  • 退出码 2:阻断收工,Claude 会据此继续对话、再处理一轮。文档将退出码 2 描述为"hook 用来表达'停,别这么做'的方式"。

也就是说,Stop hook 返回 2 时,Claude 不会停下,而是把 hook 给出的反馈读进去,再尝试一次。这正是"检查失败时自动重试"的实现基础。相比之下,返回 1 这类退出码在 Stop 事件上属于非阻断错误,不会触发重做循环。

为什么是 2 而不是 1

关键就在于 Claude Code 对不同退出码的区分。对于 Stop、SubagentStop、TaskCompleted 这类"已经发生的事情"事件,退出码 2 的含义是"阻止其生效、让模型继续";而退出码 1 等则只被当作一次普通报错,模型照常收工。

这也是 Hallie 强调"必须退出 2"的原因:如果你把 npm test 之类直接挂在 Stop hook 上,而测试失败时返回的是 1,那么 Claude 会认为"没问题,收工",你以为的"测试门禁"其实根本没生效。只有显式 exit 2,Claude 才会被送回去修复问题。

一个最小可用的 Stop hook 示例

下面是一段社区中常见的写法(思路来自 Claude Code 文档与多位开发者的实践整理),在 .claude/settings.json 中注册一个 Stop hook:

json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/check.sh" }
        ]
      }
    ]
  }
}

check.sh 负责跑你想当作门禁的检查(如测试),并在失败时把原因写到标准错误、以退出码 2 打回:

bash
#!/usr/bin/env bash
# 已在上一轮阻断过则放行,避免死循环(见下节)
if [ "$CLAUDE_CODE_STOP_HOOK_ACTIVE" = "1" ]; then
  exit 0
fi

if ! npm test --silent 2>&1; then
  echo "测试未通过,请修复后再收工。" >&2
  exit 2
fi
exit 0

需要提醒的是:反馈信息应当通过 stderr 传递给 Claude,而不是 stdout;同时尽量让检查保持轻量(官方文档提示单次 hook 有约 60 秒的超时),不要挂重型集成测试。

防死循环:必须检查 stop_hook_active

如果 hook 在检查失败时总是 exit 2,而问题始终修不好,Claude 就会被困在无限重试里。解决这个问题有一个关键抓手:Claude Code 在 Stop hook 已经阻断过当前尝试时,会把环境变量 CLAUDE_CODE_STOP_HOOK_ACTIVE 置为 "1",并且在传给 hook 的 JSON 输入里带上 stop_hook_active 字段。

因此,标准做法是:脚本开头先判断"自己是否已经阻断过一次"——如果是,就 exit 0 放行,让 Claude 正常结束,而不是继续阻塞。上面的示例脚本正是这个逻辑。

此外,Claude Code 对 Stop hook 的阻断次数有默认上限(社区资料中记为约 8 次,对应环境变量 CLAUDE_CODE_STOP_HOOK_BLOCK_CAP),到顶后会停止阻断。但依赖上限兜底不如在脚本里主动 fail-open 来得稳妥。

适用场景与限制

这种"退出码 2 门禁"适合作为收工前的一道自动检查:快速单元测试、lint 是否引入新违规、某个必要产物文件是否生成等。它运行在 shell 环境里,只能看到磁盘上的状态,看不到 Claude 的"思路"——如果失败源自 Claude 没意识到自己影响了某段代码,循环未必能收敛。

从更大的工作流看,Hallie 的观点是:与其让人去逐条审批 Claude Code 的每一步,不如用 deny 规则、沙箱/云机器,以及这类自动检查来兜底。Stop hook 的退出码 2,只是其中"用检查代替信任"的一个具体落点。

参考来源

  1. 1Lydia Hallie 的 X 帖子(首要信源):x.com/lydiahallie/status/2121313048820617645
  2. 2Anthropic,Claude Code Hooks 文档(Hooks reference):docs.claude.com/en/docs/claude-code/hooks
  3. 3llms.blog,*Anthropic Says Stop Approving Every Claude Code Command*(含 Hallie 在 AI Engineer Code Summit 2026 的发言要点):llms.blog/posts/claude-code-best-practices-auto-mode-deny-rules
  4. 4CloudCodeTree,*A Stop Hook That Exits 2 Blocks Completion and Sends Claude Back*(含 CLAUDE_CODE_STOP_HOOK_ACTIVE 与阻断上限说明):cloudcodetree.com/ai-news/2026-11-02-04-stop-hook-exit-2-test-gate-stop-hook-active-guard
  5. 5AI Parabellum,*Claude Code Stop Hook: Examples You Can Copy*(含 stop_hook_active 判断与常见误区):aiparabellum.com/claude-code-stop-hook-examples-you-can-copy