minimal-agent 0.1.8 → 0.2.0

package/plugins/ralph-wiggum/hooks/stop-hook.sh

@@ -0,0 +1,191 @@
+#!/bin/bash
+
+# Ralph Wiggum Stop Hook
+# Prevents session exit when a ralph-loop is active
+# Feeds Claude's output back as input to continue the loop
+#
+# NOTE (minimal-agent):
+#   This hook is the original Claude Code contract — kept here so the plugin
+#   stays portable to upstream. In minimal-agent the loop is driven natively
+#   by src/plugins/pluginRunner.ts; this hook is consulted as an *advisory*
+#   signal (block → inject reason into next iteration; pass / errors → no
+#   effect on loop termination). The loop's real exit conditions are:
+#     - <promise>DONE</promise> sentinel + verification pass
+#     - --max-iterations reached
+#     - user abort / NEED_REPLAN
+#   On Windows minimal-agent skips this hook entirely (bash unavailable).
+#   The .minimal-agent/ralph-loop.local.md state file referenced below is
+#   NOT created by minimal-agent — GoalState writes goal.md/phase.md/etc
+#   instead, so this hook simply exits 0 in minimal-agent runs.
+
+set -euo pipefail
+
+# Read hook input from stdin (advanced stop hook API)
+HOOK_INPUT=$(cat)
+
+# Check if ralph-loop is active
+RALPH_STATE_FILE=".minimal-agent/ralph-loop.local.md"
+
+if [[ ! -f "$RALPH_STATE_FILE" ]]; then
+  # No active loop - allow exit
+  exit 0
+fi
+
+# Parse markdown frontmatter (YAML between ---) and extract values
+FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$RALPH_STATE_FILE")
+ITERATION=$(echo "$FRONTMATTER" | grep '^iteration:' | sed 's/iteration: *//')
+MAX_ITERATIONS=$(echo "$FRONTMATTER" | grep '^max_iterations:' | sed 's/max_iterations: *//')
+# Extract completion_promise and strip surrounding quotes if present
+COMPLETION_PROMISE=$(echo "$FRONTMATTER" | grep '^completion_promise:' | sed 's/completion_promise: *//' | sed 's/^"\(.*\)"$/\1/')
+
+# Validate numeric fields before arithmetic operations
+if [[ ! "$ITERATION" =~ ^[0-9]+$ ]]; then
+  echo "⚠️  Ralph loop: State file corrupted" >&2
+  echo "   File: $RALPH_STATE_FILE" >&2
+  echo "   Problem: 'iteration' field is not a valid number (got: '$ITERATION')" >&2
+  echo "" >&2
+  echo "   This usually means the state file was manually edited or corrupted." >&2
+  echo "   Ralph loop is stopping. Run /ralph-loop again to start fresh." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+if [[ ! "$MAX_ITERATIONS" =~ ^[0-9]+$ ]]; then
+  echo "⚠️  Ralph loop: State file corrupted" >&2
+  echo "   File: $RALPH_STATE_FILE" >&2
+  echo "   Problem: 'max_iterations' field is not a valid number (got: '$MAX_ITERATIONS')" >&2
+  echo "" >&2
+  echo "   This usually means the state file was manually edited or corrupted." >&2
+  echo "   Ralph loop is stopping. Run /ralph-loop again to start fresh." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Check if max iterations reached
+if [[ $MAX_ITERATIONS -gt 0 ]] && [[ $ITERATION -ge $MAX_ITERATIONS ]]; then
+  echo "🛑 Ralph loop: Max iterations ($MAX_ITERATIONS) reached."
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Get transcript path from hook input
+TRANSCRIPT_PATH=$(echo "$HOOK_INPUT" | jq -r '.transcript_path')
+
+if [[ ! -f "$TRANSCRIPT_PATH" ]]; then
+  echo "⚠️  Ralph loop: Transcript file not found" >&2
+  echo "   Expected: $TRANSCRIPT_PATH" >&2
+  echo "   This is unusual and may indicate a Claude Code internal issue." >&2
+  echo "   Ralph loop is stopping." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Read last assistant message from transcript (JSONL format - one JSON per line)
+# First check if there are any assistant messages
+if ! grep -q '"role":"assistant"' "$TRANSCRIPT_PATH"; then
+  echo "⚠️  Ralph loop: No assistant messages found in transcript" >&2
+  echo "   Transcript: $TRANSCRIPT_PATH" >&2
+  echo "   This is unusual and may indicate a transcript format issue" >&2
+  echo "   Ralph loop is stopping." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Extract last assistant message with explicit error handling
+LAST_LINE=$(grep '"role":"assistant"' "$TRANSCRIPT_PATH" | tail -1)
+if [[ -z "$LAST_LINE" ]]; then
+  echo "⚠️  Ralph loop: Failed to extract last assistant message" >&2
+  echo "   Ralph loop is stopping." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Parse JSON with error handling
+LAST_OUTPUT=$(echo "$LAST_LINE" | jq -r '
+  .message.content |
+  map(select(.type == "text")) |
+  map(.text) |
+  join("\n")
+' 2>&1)
+
+# Check if jq succeeded
+if [[ $? -ne 0 ]]; then
+  echo "⚠️  Ralph loop: Failed to parse assistant message JSON" >&2
+  echo "   Error: $LAST_OUTPUT" >&2
+  echo "   This may indicate a transcript format issue" >&2
+  echo "   Ralph loop is stopping." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+if [[ -z "$LAST_OUTPUT" ]]; then
+  echo "⚠️  Ralph loop: Assistant message contained no text content" >&2
+  echo "   Ralph loop is stopping." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Check for completion promise (only if set)
+if [[ "$COMPLETION_PROMISE" != "null" ]] && [[ -n "$COMPLETION_PROMISE" ]]; then
+  # Extract text from <promise> tags using Perl for multiline support
+  # -0777 slurps entire input, s flag makes . match newlines
+  # .*? is non-greedy (takes FIRST tag), whitespace normalized
+  PROMISE_TEXT=$(echo "$LAST_OUTPUT" | perl -0777 -pe 's/.*?<promise>(.*?)<\/promise>.*/$1/s; s/^\s+|\s+$//g; s/\s+/ /g' 2>/dev/null || echo "")
+
+  # Use = for literal string comparison (not pattern matching)
+  # == in [[ ]] does glob pattern matching which breaks with *, ?, [ characters
+  if [[ -n "$PROMISE_TEXT" ]] && [[ "$PROMISE_TEXT" = "$COMPLETION_PROMISE" ]]; then
+    echo "✅ Ralph loop: Detected <promise>$COMPLETION_PROMISE</promise>"
+    rm "$RALPH_STATE_FILE"
+    exit 0
+  fi
+fi
+
+# Not complete - continue loop with SAME PROMPT
+NEXT_ITERATION=$((ITERATION + 1))
+
+# Extract prompt (everything after the closing ---)
+# Skip first --- line, skip until second --- line, then print everything after
+# Use i>=2 instead of i==2 to handle --- in prompt content
+PROMPT_TEXT=$(awk '/^---$/{i++; next} i>=2' "$RALPH_STATE_FILE")
+
+if [[ -z "$PROMPT_TEXT" ]]; then
+  echo "⚠️  Ralph loop: State file corrupted or incomplete" >&2
+  echo "   File: $RALPH_STATE_FILE" >&2
+  echo "   Problem: No prompt text found" >&2
+  echo "" >&2
+  echo "   This usually means:" >&2
+  echo "     • State file was manually edited" >&2
+  echo "     • File was corrupted during writing" >&2
+  echo "" >&2
+  echo "   Ralph loop is stopping. Run /ralph-loop again to start fresh." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Update iteration in frontmatter (portable across macOS and Linux)
+# Create temp file, then atomically replace
+TEMP_FILE="${RALPH_STATE_FILE}.tmp.$$"
+sed "s/^iteration: .*/iteration: $NEXT_ITERATION/" "$RALPH_STATE_FILE" > "$TEMP_FILE"
+mv "$TEMP_FILE" "$RALPH_STATE_FILE"
+
+# Build system message with iteration count and completion promise info
+if [[ "$COMPLETION_PROMISE" != "null" ]] && [[ -n "$COMPLETION_PROMISE" ]]; then
+  SYSTEM_MSG="🔄 Ralph iteration $NEXT_ITERATION | To stop: output <promise>$COMPLETION_PROMISE</promise> (ONLY when statement is TRUE - do not lie to exit!)"
+else
+  SYSTEM_MSG="🔄 Ralph iteration $NEXT_ITERATION | No completion promise set - loop runs infinitely"
+fi
+
+# Output JSON to block the stop and feed prompt back
+# The "reason" field contains the prompt that will be sent back to Claude
+jq -n \
+  --arg prompt "$PROMPT_TEXT" \
+  --arg msg "$SYSTEM_MSG" \
+  '{
+    "decision": "block",
+    "reason": $prompt,
+    "systemMessage": $msg
+  }'
+
+# Exit 0 for successful hook execution
+exit 0

package/plugins/ralph-wiggum/plugin.ts

@@ -0,0 +1,275 @@
+/**
+ * ============================================================
+ *  plugins/ralph-wiggum/plugin.ts —— ralph-wiggum 真·插件入口
+ * ------------------------------------------------------------
+ *  把原 src/plugins/pluginRunner.ts 的 do-while 循环驱动整段搬来。
+ *  对外通过 PluginApi.runCommand 暴露 /ralph-loop。
+ *
+ *  循环契约：
+ *    - 每轮把 history 重置成进入循环前的快照（fresh context）
+ *    - 用 GoalState.composeContext() 拼 PLAN/BUILD/VERIFY/HEAL 阶段信息
+ *    - 跑 runQuery
+ *    - 检测 <promise>DONE</promise> → runVerification → 通过则退出
+ *    - 检测 <PROMISE>NEED_REPLAN</PROMISE> → forceSetPhase(PLAN)
+ *    - executeStopHook 是咨询式：block 才把 reason 注入下一轮，pass 不退出
+ *
+ *  终止（独占）：sentinel + verify 通过 / 达 max-iterations / abort / 安全天花板
+ *
+ *  Windows 上 hooks/stop-hook.sh 不可用，但循环不依赖 hook，功能完整，
+ *  只是 hook 的咨询通道失效。
+ * ============================================================
+ */
+
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+import {
+  runQuery,
+  getWorkingDir,
+  type PluginApi,
+  type PluginContext,
+  type LoopEvent,
+  type Message,
+} from '../../src/plugin-sdk.ts';
+
+import { GoalState, Phase } from './src/goalState.ts';
+import { parseVerifyArgs, runVerification } from './src/verificationGate.ts';
+import {
+  hasCompleteSentinel,
+  hasNeedReplanSentinel,
+} from './src/sentinels.ts';
+import { executeStopHook } from './src/stopHookRunner.ts';
+
+const PLUGIN_NAME = 'ralph-wiggum';
+const DEFAULT_MAX_ITERATIONS = 50;
+const SAFETY_CEILING = 200;
+
+const PLUGIN_ROOT = dirname(fileURLToPath(import.meta.url));
+
+function extractMaxIterations(args: string): number | undefined {
+  const match = args.match(/--max-iterations\s+(\d+)/i);
+  return match ? parseInt(match[1], 10) : undefined;
+}
+
+async function* runRalphLoop(
+  args: string,
+  ctx: PluginContext,
+): AsyncGenerator<LoopEvent, void, void> {
+  const { provider, history, signal } = ctx;
+
+  const maxIter = Math.min(
+    extractMaxIterations(args) ?? DEFAULT_MAX_ITERATIONS,
+    SAFETY_CEILING,
+  );
+
+  // 没有 args（用户只敲 /ralph-loop）→ 留个最小 goal placeholder，避免 GoalState.init 拒空串
+  const userGoal = args.trim() || '(未提供目标)';
+
+  yield {
+    type: 'plugin_progress',
+    pluginId: PLUGIN_NAME,
+    current: 0,
+    max: maxIter,
+    message: 'Ralph Wiggum copy-task loop 启动',
+  };
+
+  const checks = parseVerifyArgs(args);
+
+  // sessionTag = 插件名 → 多插件可并发不打架，/new 也能扫到清掉
+  const goalState = new GoalState(getWorkingDir(), PLUGIN_NAME);
+  await goalState.reset();
+  await goalState.init(userGoal, checks);
+  await goalState.appendProgress(
+    `=== Loop 启动 === 目标: ${userGoal.slice(0, 120)}...`,
+  );
+
+  // 进循环前快照 history —— 每轮 runQuery 前用它重置，保证 fresh context
+  const baseHistory = history.slice();
+
+  let iterationCount = 0;
+  let consecutiveFailures = 0;
+  let currentInput = userGoal;
+  let finalAssistantMsg: Message | null = null;
+
+  try {
+    do {
+      iterationCount++;
+      if (iterationCount > maxIter) {
+        await goalState.forceSetPhase(Phase.DONE, `达到迭代上限 ${maxIter}`);
+        await goalState.appendLearning(
+          `[迭代上限] 循环在 ${iterationCount - 1} 轮后强制终止，可能目标过大或陷入死循环`,
+        );
+        yield {
+          type: 'error',
+          error: `Loop 已达迭代上限 ${maxIter}，自动停止`,
+        };
+        return;
+      }
+
+      if (signal?.aborted) {
+        yield { type: 'interrupted' };
+        return;
+      }
+
+      yield {
+        type: 'plugin_progress',
+        pluginId: PLUGIN_NAME,
+        current: iterationCount,
+        max: maxIter,
+      };
+
+      // fresh context：清空 history，重置为入循环前的快照
+      history.length = 0;
+      history.push(...baseHistory);
+
+      const freshContext = goalState.composeContext(iterationCount);
+      const enhancedInput = `${freshContext}\n\n${currentInput}`;
+
+      yield* runQuery(enhancedInput, {
+        provider,
+        history,
+        signal,
+        maxTurns: ctx.maxTurns,
+        sessionState: ctx.sessionState,
+      });
+
+      if (signal?.aborted) {
+        yield { type: 'interrupted' };
+        return;
+      }
+
+      // 从本轮 history 抓最后一个 assistant 消息（runQuery 已 push 进去）
+      const lastAssistantIdx = (() => {
+        for (let i = history.length - 1; i >= 0; i--) {
+          if (history[i].role === 'assistant') return i;
+        }
+        return -1;
+      })();
+      finalAssistantMsg =
+        lastAssistantIdx >= 0 ? history[lastAssistantIdx] : null;
+      const lastAssistantText = finalAssistantMsg
+        ? typeof finalAssistantMsg.content === 'string'
+          ? finalAssistantMsg.content
+          : JSON.stringify(finalAssistantMsg.content)
+        : '';
+
+      if (hasCompleteSentinel(lastAssistantText)) {
+        // 哨兵：可能来自任意阶段（包括 iter 1 的 PLAN），用 force 跳到 VERIFY
+        await goalState.forceSetPhase(Phase.VERIFY, '检测到完成哨兵，进入验证');
+        await goalState.appendProgress(
+          `迭代 ${iterationCount}: 检测到完成哨兵，运行验证门...`,
+        );
+
+        if (checks.length > 0) {
+          const vResult = await runVerification(checks);
+
+          if (!vResult.passed) {
+            consecutiveFailures++;
+            await goalState.appendLearning(
+              `[迭代 ${iterationCount}] 声称完成但验证未通过: ${vResult.summary}`,
+            );
+            yield {
+              type: 'error',
+              error: `⚠️ 验证未通过: ${vResult.summary}。继续尝试...`,
+            };
+
+            if (consecutiveFailures >= 3) {
+              await goalState.forceSetPhase(
+                Phase.HEAL,
+                `连续 ${consecutiveFailures} 次验证失败`,
+              );
+            } else {
+              await goalState.setPhase(Phase.BUILD, '验证未通过，返回构建');
+            }
+            continue;
+          }
+
+          await goalState.appendProgress(`✅ 验证通过: ${vResult.summary}`);
+        }
+
+        await goalState.setPhase(Phase.DONE, 'goal complete & verified');
+        yield {
+          type: 'plugin_iteration',
+          pluginName: PLUGIN_NAME,
+          current: iterationCount,
+          max: maxIter,
+        };
+        return;
+      }
+
+      if (hasNeedReplanSentinel(lastAssistantText)) {
+        await goalState.forceSetPhase(Phase.PLAN, 'agent 请求重新规划');
+        await goalState.appendLearning(
+          '[NEED_REPLAN] Agent 认为当前方案不可行，需要重新规划',
+        );
+        await goalState.appendProgress(
+          'Agent 请求 NEED_REPLAN，回 PLAN 阶段',
+        );
+        consecutiveFailures = 0;
+        continue;
+      }
+
+      // PLAN 阶段跑过一轮还没哨兵，认为规划已完成，自动推进 BUILD
+      if (goalState.currentPhase === Phase.PLAN && iterationCount >= 2) {
+        await goalState.setPhase(Phase.BUILD, '规划阶段已完成，进入构建');
+      }
+
+      // Stop-hook 咨询式调用：block 才把 reason 注入下一轮 prompt
+      // pass / 报错都不再终止循环；终止由 sentinel/maxIter/abort/NEED_REPLAN 独占
+      const hookResult = await executeStopHook(PLUGIN_ROOT, lastAssistantText);
+
+      if (hookResult.decision === 'block' && hookResult.reason) {
+        currentInput = hookResult.reason;
+        consecutiveFailures = 0;
+        await goalState.recordDecision(
+          {
+            iteration: iterationCount,
+            phase: goalState.currentPhase,
+            summary: 'stop-hook 反馈',
+          },
+          ['继续循环', '终止'],
+          '继续循环',
+          hookResult.reason.slice(0, 200),
+        );
+        if (hookResult.systemMessage) {
+          baseHistory.push({
+            role: 'user',
+            content: `[Plugin Stop Hook] ${hookResult.systemMessage}`,
+          });
+        }
+        await goalState.appendProgress(
+          `迭代 ${iterationCount}: Stop hook block，注入反馈继续`,
+        );
+      } else {
+        await goalState.appendProgress(
+          `迭代 ${iterationCount}: 无哨兵 / hook pass，继续下一轮`,
+        );
+      }
+    } while (true);
+  } finally {
+    // 收尾：把循环里临时累积的 history 还原成 baseHistory + 最后一轮 assistant
+    // 这样 TUI 上看到的就是"一次问答"，而不是 N 轮重复
+    history.length = 0;
+    history.push(...baseHistory);
+    if (finalAssistantMsg) {
+      history.push(finalAssistantMsg);
+    }
+    await goalState.cleanup();
+  }
+}
+
+const api: PluginApi = {
+  async *runCommand(commandName, args, ctx) {
+    if (commandName === 'ralph-loop') {
+      yield* runRalphLoop(args, ctx);
+      return;
+    }
+    // 其它命令（help / cancel-ralph）→ 不接管，让框架走声明式 fallback
+    yield {
+      type: 'error',
+      error: `ralph-wiggum: 命令 /${commandName} 未由 plugin.ts 接管`,
+    };
+  },
+};
+
+export default api;

package/plugins/ralph-wiggum/scripts/setup-ralph-loop.sh

@@ -0,0 +1,203 @@
+#!/bin/bash
+
+# Ralph Loop Setup Script
+# Creates state file for in-session Ralph loop
+
+set -euo pipefail
+
+# Parse arguments
+PROMPT_PARTS=()
+MAX_ITERATIONS=0
+COMPLETION_PROMISE="null"
+
+# Parse options and positional arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    -h|--help)
+      cat << 'HELP_EOF'
+Ralph Loop - Interactive self-referential development loop
+
+USAGE:
+  /ralph-loop [PROMPT...] [OPTIONS]
+
+ARGUMENTS:
+  PROMPT...    Initial prompt to start the loop (can be multiple words without quotes)
+
+OPTIONS:
+  --max-iterations <n>           Maximum iterations before auto-stop (default: unlimited)
+  --completion-promise '<text>'  Promise phrase (USE QUOTES for multi-word)
+  -h, --help                     Show this help message
+
+DESCRIPTION:
+  Starts a Ralph Wiggum loop in your CURRENT session. The stop hook prevents
+  exit and feeds your output back as input until completion or iteration limit.
+
+  To signal completion, you must output: <promise>YOUR_PHRASE</promise>
+
+  Use this for:
+  - Interactive iteration where you want to see progress
+  - Tasks requiring self-correction and refinement
+  - Learning how Ralph works
+
+EXAMPLES:
+  /ralph-loop Build a todo API --completion-promise 'DONE' --max-iterations 20
+  /ralph-loop --max-iterations 10 Fix the auth bug
+  /ralph-loop Refactor cache layer  (runs forever)
+  /ralph-loop --completion-promise 'TASK COMPLETE' Create a REST API
+
+STOPPING:
+  Only by reaching --max-iterations or detecting --completion-promise
+  No manual stop - Ralph runs infinitely by default!
+
+MONITORING:
+  # View current iteration:
+  grep '^iteration:' .minimal-agent/ralph-loop.local.md
+
+  # View full state:
+  head -10 .minimal-agent/ralph-loop.local.md
+HELP_EOF
+      exit 0
+      ;;
+    --max-iterations)
+      if [[ -z "${2:-}" ]]; then
+        echo "❌ Error: --max-iterations requires a number argument" >&2
+        echo "" >&2
+        echo "   Valid examples:" >&2
+        echo "     --max-iterations 10" >&2
+        echo "     --max-iterations 50" >&2
+        echo "     --max-iterations 0  (unlimited)" >&2
+        echo "" >&2
+        echo "   You provided: --max-iterations (with no number)" >&2
+        exit 1
+      fi
+      if ! [[ "$2" =~ ^[0-9]+$ ]]; then
+        echo "❌ Error: --max-iterations must be a positive integer or 0, got: $2" >&2
+        echo "" >&2
+        echo "   Valid examples:" >&2
+        echo "     --max-iterations 10" >&2
+        echo "     --max-iterations 50" >&2
+        echo "     --max-iterations 0  (unlimited)" >&2
+        echo "" >&2
+        echo "   Invalid: decimals (10.5), negative numbers (-5), text" >&2
+        exit 1
+      fi
+      MAX_ITERATIONS="$2"
+      shift 2
+      ;;
+    --completion-promise)
+      if [[ -z "${2:-}" ]]; then
+        echo "❌ Error: --completion-promise requires a text argument" >&2
+        echo "" >&2
+        echo "   Valid examples:" >&2
+        echo "     --completion-promise 'DONE'" >&2
+        echo "     --completion-promise 'TASK COMPLETE'" >&2
+        echo "     --completion-promise 'All tests passing'" >&2
+        echo "" >&2
+        echo "   You provided: --completion-promise (with no text)" >&2
+        echo "" >&2
+        echo "   Note: Multi-word promises must be quoted!" >&2
+        exit 1
+      fi
+      COMPLETION_PROMISE="$2"
+      shift 2
+      ;;
+    *)
+      # Non-option argument - collect all as prompt parts
+      PROMPT_PARTS+=("$1")
+      shift
+      ;;
+  esac
+done
+
+# Join all prompt parts with spaces
+PROMPT="${PROMPT_PARTS[*]}"
+
+# Validate prompt is non-empty
+if [[ -z "$PROMPT" ]]; then
+  echo "❌ Error: No prompt provided" >&2
+  echo "" >&2
+  echo "   Ralph needs a task description to work on." >&2
+  echo "" >&2
+  echo "   Examples:" >&2
+  echo "     /ralph-loop Build a REST API for todos" >&2
+  echo "     /ralph-loop Fix the auth bug --max-iterations 20" >&2
+  echo "     /ralph-loop --completion-promise 'DONE' Refactor code" >&2
+  echo "" >&2
+  echo "   For all options: /ralph-loop --help" >&2
+  exit 1
+fi
+
+# Create state file for stop hook (markdown with YAML frontmatter)
+mkdir -p .minimal-agent
+
+# Quote completion promise for YAML if it contains special chars or is not null
+if [[ -n "$COMPLETION_PROMISE" ]] && [[ "$COMPLETION_PROMISE" != "null" ]]; then
+  COMPLETION_PROMISE_YAML="\"$COMPLETION_PROMISE\""
+else
+  COMPLETION_PROMISE_YAML="null"
+fi
+
+cat > .minimal-agent/ralph-loop.local.md <<EOF
+---
+active: true
+iteration: 1
+max_iterations: $MAX_ITERATIONS
+completion_promise: $COMPLETION_PROMISE_YAML
+started_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+---
+
+$PROMPT
+EOF
+
+# Output setup message
+cat <<EOF
+🔄 Ralph loop activated in this session!
+
+Iteration: 1
+Max iterations: $(if [[ $MAX_ITERATIONS -gt 0 ]]; then echo $MAX_ITERATIONS; else echo "unlimited"; fi)
+Completion promise: $(if [[ "$COMPLETION_PROMISE" != "null" ]]; then echo "${COMPLETION_PROMISE//\"/} (ONLY output when TRUE - do not lie!)"; else echo "none (runs forever)"; fi)
+
+The stop hook is now active. When you try to exit, the SAME PROMPT will be
+fed back to you. You'll see your previous work in files, creating a
+self-referential loop where you iteratively improve on the same task.
+
+To monitor: head -10 .minimal-agent/ralph-loop.local.md
+
+⚠️  WARNING: This loop cannot be stopped manually! It will run infinitely
+    unless you set --max-iterations or --completion-promise.
+
+🔄
+EOF
+
+# Output the initial prompt if provided
+if [[ -n "$PROMPT" ]]; then
+  echo ""
+  echo "$PROMPT"
+fi
+
+# Display completion promise requirements if set
+if [[ "$COMPLETION_PROMISE" != "null" ]]; then
+  echo ""
+  echo "═══════════════════════════════════════════════════════════"
+  echo "CRITICAL - Ralph Loop Completion Promise"
+  echo "═══════════════════════════════════════════════════════════"
+  echo ""
+  echo "To complete this loop, output this EXACT text:"
+  echo "  <promise>$COMPLETION_PROMISE</promise>"
+  echo ""
+  echo "STRICT REQUIREMENTS (DO NOT VIOLATE):"
+  echo "  ✓ Use <promise> XML tags EXACTLY as shown above"
+  echo "  ✓ The statement MUST be completely and unequivocally TRUE"
+  echo "  ✓ Do NOT output false statements to exit the loop"
+  echo "  ✓ Do NOT lie even if you think you should exit"
+  echo ""
+  echo "IMPORTANT - Do not circumvent the loop:"
+  echo "  Even if you believe you're stuck, the task is impossible,"
+  echo "  or you've been running too long - you MUST NOT output a"
+  echo "  false promise statement. The loop is designed to continue"
+  echo "  until the promise is GENUINELY TRUE. Trust the process."
+  echo ""
+  echo "  If the loop should stop, the promise statement will become"
+  echo "  true naturally. Do not force it by lying."
+  echo "═══════════════════════════════════════════════════════════"
+fi