Execution Loop

控制 agent 的执行循环：阻止提前停止、检测任务完成、防止任务漂移。

When to Use

• Agent 只完成一部分就停了 → Ralph persistent loop
• Agent 说"可能"就声称完成 → Doubt gate
• 长 session 中偏离原始任务 → Drift re-anchoring
• 有明确任务清单 → Task completion verifier
• 用 -p headless 模式 → Headless execution control

When NOT to Use

• 工具反复失败 → 用 tool-governance
• 上下文快用完 → 用 context-memory
• Session 挂死 → 用 error-recovery

Patterns

扩展模式（跨 turn 状态对象、多层停止条件、三维预算约束、流式工具执行）→ 详见。Cancel 信号 TTL 机制 → 详见。

Scripts

Workflow

任务到达
  │
  ├─ Interactive 模式？
  │   │
  │   ├─ 是 ──→ 复杂度 triage（Pattern 1.3）
  │   │         │
  │   │         ├─ Trivial/Low ──→ Express/Light 模式
  │   │         │   不启用 Ralph，agent 完成即停。
  │   │         │   判断不确定？→ 走 Standard，Express 跳过验证不可兜底。
  │   │         │
  │   │         └─ Medium+ ──→ Standard/Full 模式
  │   │             │
  │   │             ├─ 1. ralph-init.sh <id> [max]
  │   │             │   有残留状态？从上次迭代恢复，不重置计数器。
  │   │             │
  │   │             ├─ 2. 按复杂度启用 hook 组合
  │   │             │   Standard: Ralph + Context 估算
  │   │             │   Full: + Handoff + Hook Bracket + Post-Edit 诊断
  │   │             │   Critical: + Agent-type 验证门禁
  │   │             │
  │   │             └─ 3. Agent 执行 → 尝试停止 → Stop hook 链
  │   │                 │
  │   │                 ├─ [最高优先级] 安全阀检查
  │   │                 │   context >= 95%? → 放行（阻止会导致溢出崩溃）
  │   │                 │   401/403 认证失败? → 放行（继续执行无意义）
  │   │                 │   cancel 信号存在且 TTL 未过期? → 放行
  │   │                 │   闲置 > 2h? → 放行（防 zombie）
  │   │                 │   迭代 >= max? → 放行
  │   │                 │   ※ 安全阀先于一切 block 逻辑执行，顺序固定
  │   │                 │
  │   │                 ├─ Doubt gate（Pattern 1.2）
  │   │                 │   回复含投机语言? → block，要求证据
  │   │                 │   本轮已触发过? → 放行（守卫去重）
  │   │                 │
  │   │                 ├─ Task completion（Pattern 1.4）
  │   │                 │   .harness-tasks.json 有未完成项? → block，注入缺失项
  │   │                 │
  │   │                 ├─ Ralph 迭代检查（Pattern 1.1）
  │   │                 │   active=true 且 iteration < max? → block
  │   │                 │   注入迭代感知消息（Pattern 1.7）
  │   │                 │
  │   │                 ├─ Drift re-anchor（Pattern 1.5）
  │   │                 │   每 N 轮注入原始任务提醒（不 block，仅注入 context）
  │   │                 │
  │   │                 └─ 所有检查通过 → 放行停止
  │   │
  │   └─ 否（Headless `-p`）──→ 三维控制（Pattern 1.6）
  │       --max-turns 限轮数（简单 10-20 / 中等 30-50 / 复杂 80-120）
  │       prompt 结构化利用 prefix cache
  │       budget 注入让 agent 感知剩余资源
  │       第 80% 轮次时开始收尾，写 handoff 文档

用户：「把 user-service 的 7 个 endpoint 从 REST 迁移到 gRPC」 → Triage: High（7 文件 + 架构变更）→ Full 模式 → ralph-init.sh api-migration 50

Agent 改完 1 个 endpoint → 停 → Ralph block: 「[RALPH 1/50] 检查任务清单，标记已完成项，继续下一项。」 Agent 改完 3 个 → 停 → Task completion block: 「未完成项: endpoint-4, endpoint-5, endpoint-6, endpoint-7」 Agent 改完全部 7 个 → 停 → Doubt gate 通过（无投机语言）→ Task completion 通过（全部 done）→ Ralph 放行 实际迭代: 12/50，自然完成。 </example>

用户：「README 里 'recieve' 改成 'receive'」 错误：ralph-init.sh typo-fix 50 → 改完 1 行被 Ralph block → 被迫"寻找更多错误" → 引入无关改动 正确：Triage → Trivial → Express → 不启 Ralph → 改完即停 </anti-example>

Output

Usage

在 .claude/settings.json 中配置 Stop hook：

{
  "hooks": {
    "Stop": [
      // Ralph 持续执行（Pattern 1.1）
      {
        "hooks": [{
          "type": "command",
          "command": "bash ralph-stop-hook.sh"
        }]
      },
      // Doubt gate（Pattern 1.2）
      {
        "hooks": [{
          "type": "command",
          "command": "bash doubt-gate.sh"
        }]
      },
      // Task completion（Pattern 1.4）
      {
        "hooks": [{
          "type": "command",
          "command": "bash task-completion-gate.sh"
        }]
      }
    ]
  }
}

初始化和取消 Ralph：

# 启动持续执行（50 轮上限）
bash ralph-init.sh api-migration 50

# 取消持续执行
bash ralph-cancel.sh api-migration

Hook 输出格式（ralph-stop-hook.sh stdout）：

{"decision": "block", "hookSpecificOutput": {"reasonForBlocking": "[RALPH 3/50] 检查任务清单，标记已完成项，继续下一项。"}}

安全阀在 block 之前检查，确保不会阻止必要的停止：

{"decision": "allow", "hookSpecificOutput": {"reasonForAllowing": "context >= 95%, 必须放行避免溢出"}}

Related