Agent Hooks#

即插即用的 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.shStop阻止提前停止，4 个安全阀保底详情ralph-cancel.sh <id> [reason]CLI 调用发送 30s TTL 取消信号详情tool-error-tracker.shPostToolUseFailure追踪连续失败，3 次软提示 / 5 次强制换方案详情tool-error-advisor.shPreToolUse5 次失败后 block 同一命令详情doubt-gate.shStop检测投机语言，强制提供证据详情post-edit-check.shPostToolUse (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 是否提前停止再决定