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：
{
"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 决策
{"continue": true} // 放行
{"decision": "block", "reason": "..."} // 阻止（Stop hook）
{"hookSpecificOutput": {"additionalContext": "..."}} // 注入上下文
安全阀
Ralph stop hook 在以下条件下 MUST 放行，NEVER block：
- 认证失败（401/403，从 stop_reason 检测）
- Cancel 信号存在且未过期
- 闲置超时 > 2 小时
- 达到 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 是否提前停止再决定
