Agent Hooks

Claude Code Stop/PreToolUse/PostToolUse hook 脚本集。当 agent 提前停止、工具反复失败、或以投机语言完成任务时自动干预。每个脚本是独立的 bash hook，配到 settings.json 即可生效。不用于设计决策（用 harness-design-patterns）或运维监控（用 agent-ops）。

即插即用的 Claude Code hook 脚本。解决 3 类问题：agent 提前停止、工具重试死循环、投机性完成。

When to Use

• Agent 在复杂任务中只完成一部分就停了 → 用 Ralph hooks
• 工具反复失败但 agent 一直重试同一个命令 → 用 tool-error hooks
• Agent 说"可能""大概"就声称完成了 → 用 doubt-gate hook
• 编辑后想立即知道有没有引入错误 → 用 post-edit-check hook

When NOT to Use

• Headless -p 模式（Stop hook 不触发，用 --max-turns）
• 设计多 agent 系统架构 → 用 harness-design-patterns
• 监控运行中的 session、处理限速 → 用 agent-ops

---

安装

将需要的 hook 加入 ~/.claude/settings.json：

json

{
  "hooks": {
    "Stop": [{
      "hooks": [
        {"type": "command", "command": "bash /path/to/agent-hooks/scripts/ralph-stop-hook.sh"},
        {"type": "command", "command": "bash /path/to/agent-hooks/scripts/doubt-gate.sh"}
      ]
    }],
    "PostToolUseFailure": [{
      "hooks": [
        {"type": "command", "command": "bash /path/to/agent-hooks/scripts/tool-error-tracker.sh", "async": true}
      ]
    }],
    "PreToolUse": [{
      "hooks": [
        {"type": "command", "command": "bash /path/to/agent-hooks/scripts/tool-error-advisor.sh"}
      ]
    }],
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [
        {"type": "command", "command": "bash /path/to/agent-hooks/scripts/post-edit-check.sh", "async": true}
      ]
    }]
  }
}

所有脚本需要环境变量 NC_SESSION（session ID）。状态写入 $HOME/<config-dir>/shared-context/sessions/<session-id>/（路径可通过 $HOME 环境变量配置）。

Scripts

脚本	Hook 类型	功能	详情
ralph-init.sh <id> [max]	CLI 调用	初始化持续执行状态（支持 crash 恢复）	详情
ralph-stop-hook.sh	Stop	阻止提前停止，4 个安全阀保底	详情
ralph-cancel.sh <id> [reason]	CLI 调用	发送 30s TTL 取消信号	详情
tool-error-tracker.sh	PostToolUseFailure	追踪连续失败，3 次软提示 / 5 次强制换方案	详情
tool-error-advisor.sh	PreToolUse	5 次失败后 block 同一命令	详情
doubt-gate.sh	Stop	检测投机语言，强制提供证据	详情
post-edit-check.sh	PostToolUse (Write|Edit)	编辑后即时跑 linter/type checker	详情

Hook 协议

所有 hook 脚本遵循 Claude Code hook 协议：

• 输入：stdin 接收 JSON（包含 tool_name, tool_input, session_id 等）
• 输出：stdout 输出 JSON 决策

json

{"continue": true}                                    // 放行
{"decision": "block", "reason": "..."}                 // 阻止（Stop hook）
{"hookSpecificOutput": {"additionalContext": "..."}}   // 注入上下文

安全阀

Ralph stop hook 在以下条件下 MUST 放行，NEVER block：

1. 认证失败（401/403，从 stop_reason 检测）
2. Cancel 信号存在且未过期
3. 闲置超时 > 2 小时
4. 达到 max_iterations

注：Context usage >= 95% 安全阀未实现——Claude Code 不在 hook 输入或 transcript 中暴露 context_window_size。Claude Code 自身的 reactive compaction 机制会独立处理 context 溢出。

条件判断规则

• 如果 headless -p 模式 → 不要用 Ralph，而是用 --max-turns
• 如果任务 < 5 分钟 → 不需要 Ralph
• 如果不确定 → 先不启用，观察 agent 是否提前停止再决定