@soleur/opencode 0.0.0-stage → 1.0.0

package/hooks/stop-hook.sh

@@ -0,0 +1,367 @@
+#!/usr/bin/env bash
+
+# Ralph Loop Stop Hook
+# Prevents session exit when a ralph-loop is active.
+# Feeds Claude's output back as input to continue the loop.
+#
+# Ported from the ralph-loop plugin (Anthropic, Apache 2.0).
+# Original: https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ralph-loop
+
+set -euo pipefail
+
+# Source shared helper for repo root resolution
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../scripts/resolve-git-root.sh" || {
+  # Not in a git repo -- allow exit
+  exit 0
+}
+PROJECT_ROOT="$GIT_COMMON_ROOT"
+# Session identifier: PPID by default, overridable via RALPH_LOOP_PID for testing
+_RALPH_LOOP_PID="${RALPH_LOOP_PID:-$PPID}"
+RALPH_STATE_FILE="${PROJECT_ROOT}/.claude/ralph-loop.${_RALPH_LOOP_PID}.local.md"
+
+# --- Legacy Cleanup: Remove old-format state files (pre-PID naming) ---
+# The official ralph-loop plugin and older Soleur versions used
+# ralph-loop.local.md (no PID). These collide across sessions. Remove them.
+LEGACY_FILE="${PROJECT_ROOT}/.claude/ralph-loop.local.md"
+if [[ -f "$LEGACY_FILE" ]]; then
+  echo "Ralph loop: removing legacy state file (no session isolation). Use Soleur's fork instead." >&2
+  rm -f "$LEGACY_FILE"
+fi
+
+# --- TTL Check: Auto-remove stale state files from ANY crashed session ---
+# Glob over all session-scoped state files and remove stale ones before
+# checking our own file. This cleans up orphans from crashed sessions.
+TTL_HOURS=1
+NOW_EPOCH=$(date +%s)
+for state_file in "${PROJECT_ROOT}/.claude"/ralph-loop.*.local.md; do
+  [[ -f "$state_file" ]] || continue
+
+  # Extract owner PID from filename: ralph-loop.PID.local.md
+  OWNER_PID=$(basename "$state_file" | sed 's/^ralph-loop\.\([0-9]*\)\.local\.md$/\1/')
+
+  # If the owning process is dead, clean up immediately (no TTL wait)
+  if [[ "$OWNER_PID" =~ ^[0-9]+$ ]] && ! kill -0 "$OWNER_PID" 2>/dev/null; then
+    echo "Ralph loop: owner process $OWNER_PID is dead ($(basename "$state_file")). Auto-removing." >&2
+    rm -f "$state_file"
+    continue
+  fi
+
+  # TTL fallback: remove files older than TTL_HOURS even if owner is alive
+  STARTED_AT=$(awk '/^---$/{c++; next} c==1' "$state_file" 2>/dev/null | grep '^started_at:' | sed 's/started_at: *//' | sed 's/^"\(.*\)"$/\1/' || true)
+  if [[ -n "$STARTED_AT" ]]; then
+    STARTED_EPOCH=$(date -d "$STARTED_AT" +%s 2>/dev/null || true)
+    if [[ -n "$STARTED_EPOCH" ]] && [[ $((NOW_EPOCH - STARTED_EPOCH)) -gt $((TTL_HOURS * 3600)) ]]; then
+      AGE_MINS=$(( (NOW_EPOCH - STARTED_EPOCH) / 60 ))
+      echo "Ralph loop: stale state file detected ($(basename "$state_file"), started ${AGE_MINS}m ago, TTL=${TTL_HOURS}h). Auto-removing." >&2
+      rm -f "$state_file"
+    fi
+  fi
+done
+
+# Check if ralph-loop is active for THIS session
+if [[ ! -f "$RALPH_STATE_FILE" ]]; then
+  # No active loop for this session - allow exit
+  exit 0
+fi
+
+# Read hook input from stdin (advanced stop hook API)
+HOOK_INPUT=$(cat)
+
+# Re-check after potential race -- file may have been removed between
+# the existence check above and here (stdin read is blocking)
+[[ -f "$RALPH_STATE_FILE" ]] || exit 0
+
+# Parse markdown frontmatter (YAML between first and second --- only)
+FRONTMATTER=$(awk '/^---$/{c++; next} c==1' "$RALPH_STATE_FILE" 2>/dev/null)
+
+# Safety net: if awk produced nothing (file vanished between check and read), exit cleanly
+if [[ -z "$FRONTMATTER" ]]; then
+  exit 0
+fi
+
+ITERATION=$(echo "$FRONTMATTER" | grep '^iteration:' | sed 's/iteration: *//' || true)
+MAX_ITERATIONS=$(echo "$FRONTMATTER" | grep '^max_iterations:' | sed 's/max_iterations: *//' || true)
+# Extract completion_promise and strip surrounding quotes if present
+COMPLETION_PROMISE=$(echo "$FRONTMATTER" | grep '^completion_promise:' | sed 's/completion_promise: *//' | sed 's/^"\(.*\)"$/\1/' || true)
+
+# --- Stuck Detection ---
+# Parse stuck detection fields from frontmatter
+# CRITICAL: || true guards prevent grep exit 1 from aborting under set -euo pipefail
+# when fields are missing (pre-existing state files without stuck_count/stuck_threshold)
+STUCK_COUNT=$(echo "$FRONTMATTER" | grep '^stuck_count:' | sed 's/stuck_count: *//' || true)
+STUCK_THRESHOLD=$(echo "$FRONTMATTER" | grep '^stuck_threshold:' | sed 's/stuck_threshold: *//' || true)
+LAST_RESPONSE_HASH=$(echo "$FRONTMATTER" | grep '^last_response_hash:' | sed 's/last_response_hash: *//' || true)
+REPEAT_COUNT=$(echo "$FRONTMATTER" | grep '^repeat_count:' | sed 's/repeat_count: *//' || true)
+SIMILARITY_COUNT=$(echo "$FRONTMATTER" | grep '^similarity_count:' | sed 's/similarity_count: *//' || true)
+LAST_RESPONSE_WORDS=$(echo "$FRONTMATTER" | grep '^last_response_words:' | sed 's/last_response_words: *//' || true)
+
+# Default values for backward compatibility with pre-existing state files
+if [[ ! "$STUCK_COUNT" =~ ^[0-9]+$ ]]; then
+  STUCK_COUNT=0
+fi
+if [[ ! "$STUCK_THRESHOLD" =~ ^[0-9]+$ ]]; then
+  STUCK_THRESHOLD=3
+fi
+if [[ ! "$REPEAT_COUNT" =~ ^[0-9]+$ ]]; then
+  REPEAT_COUNT=0
+fi
+if [[ ! "$SIMILARITY_COUNT" =~ ^[0-9]+$ ]]; then
+  SIMILARITY_COUNT=0
+fi
+
+# Validate numeric fields before arithmetic operations
+if [[ ! "$ITERATION" =~ ^[0-9]+$ ]]; then
+  echo "Warning: Ralph loop state file corrupted (iteration: '$ITERATION'). Stopping." >&2
+  rm -f "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+if [[ ! "$MAX_ITERATIONS" =~ ^[0-9]+$ ]]; then
+  echo "Warning: Ralph loop state file corrupted (max_iterations: '$MAX_ITERATIONS'). Stopping." >&2
+  rm -f "$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." >&2
+  rm -f "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# --- Hard Safety Valve ---
+# Even with max_iterations=0 (unlimited), cap at 50 to prevent runaway loops
+# from trapping sessions indefinitely (e.g., after context compaction).
+HARD_CAP=50
+if [[ $ITERATION -ge $HARD_CAP ]]; then
+  echo "Ralph loop: Hard safety cap ($HARD_CAP iterations) reached. Auto-removing." >&2
+  rm -f "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Extract last assistant message directly from hook input (stop hook API)
+LAST_OUTPUT=$(echo "$HOOK_INPUT" | jq -r '.last_assistant_message // ""' 2>/dev/null || true)
+
+# Empty LAST_OUTPUT is valid for tool-use-only responses -- do not terminate
+# The stuck detection counter below handles repeated empty outputs
+
+# 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
+  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 glob pattern matching)
+  if [[ -n "$PROMISE_TEXT" ]] && [[ "$PROMISE_TEXT" = "$COMPLETION_PROMISE" ]]; then
+    echo "Ralph loop: Detected <promise>$COMPLETION_PROMISE</promise>" >&2
+    rm -f "$RALPH_STATE_FILE"
+    exit 0
+  fi
+fi
+
+# --- Stuck Detection: Measure and Update ---
+# Measure response substantiveness (strip whitespace, check length)
+# Note: LAST_OUTPUT may be empty for tool-use-only responses (jq text extraction
+# yields nothing when all content blocks are type "tool_use"). This is fine --
+# empty string has length 0, which counts as minimal.
+STRIPPED_OUTPUT=$(echo "$LAST_OUTPUT" | tr -d '[:space:]')
+RESPONSE_LENGTH=${#STRIPPED_OUTPUT}
+
+# --- Idle Pattern Detection ---
+# Responses that say "nothing to do" in >20 chars fool the length check.
+# Only apply to short-ish responses (< 200 chars stripped) to avoid false positives
+# on substantive responses that contain idle phrases as substrings.
+# Verified: the `if` statement absorbs grep exit 1 under set -euo pipefail.
+IS_IDLE=false
+if [[ $RESPONSE_LENGTH -lt 200 ]]; then
+  NORMALIZED_OUTPUT=$(echo "$LAST_OUTPUT" | tr '[:upper:]' '[:lower:]' | tr -s '[:space:]' ' ' | sed 's/^ *//;s/ *$//')
+  if grep -iqE '(all (done|complete|finished)|all (slash )?commands? (are |have been )?(done|complete|finished|already)|nothing (left|pending|remaining|to do|to complete|to run)|no (active|running|pending) (commands?|tasks?|slash commands?)|session (complete|finished|done|already)|already (done|complete|finished))' < <(printf '%s\n' "$NORMALIZED_OUTPUT"); then
+    IS_IDLE=true
+  fi
+fi
+
+# --- Repetition Detection ---
+CURRENT_HASH=""
+if [[ -n "$STRIPPED_OUTPUT" ]]; then
+  CURRENT_HASH=$(echo "$STRIPPED_OUTPUT" | tr '[:upper:]' '[:lower:]' | md5sum | cut -d' ' -f1)
+fi
+
+if [[ -n "$CURRENT_HASH" ]] && [[ "$CURRENT_HASH" == "$LAST_RESPONSE_HASH" ]]; then
+  REPEAT_COUNT=$((REPEAT_COUNT + 1))
+else
+  REPEAT_COUNT=0
+fi
+LAST_RESPONSE_HASH="$CURRENT_HASH"
+
+# Update stuck counter: idle patterns OR short responses increment, substantive resets
+# Three tiers:
+#   < 150 chars: definitely minimal (formulaic responses fall below this)
+#   150-199 chars + idle pattern: semantically idle
+#   >= 200 chars: always substantive (long enough to contain real work)
+if [[ "$IS_IDLE" == "true" ]] || [[ $RESPONSE_LENGTH -lt 150 ]]; then
+  STUCK_COUNT=$((STUCK_COUNT + 1))
+else
+  STUCK_COUNT=0
+fi
+
+# Check stuck threshold (0 = disabled)
+if [[ $STUCK_THRESHOLD -gt 0 ]] && [[ $STUCK_COUNT -ge $STUCK_THRESHOLD ]]; then
+  echo "Ralph loop: terminated after $STUCK_COUNT consecutive empty/idle responses (stuck detection)" >&2
+  rm -f "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Check repetition threshold (3 identical consecutive responses)
+REPEAT_THRESHOLD=3
+if [[ $REPEAT_COUNT -ge $REPEAT_THRESHOLD ]]; then
+  echo "Ralph loop: terminated after $((REPEAT_COUNT + 1)) consecutive identical responses (repetition detection)" >&2
+  rm -f "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# --- Similarity Detection ---
+# Catch loops producing minor variations of the same response.
+# Tokenize into unique words, compute Jaccard similarity via comm.
+CURRENT_WORDS=$(echo "$LAST_OUTPUT" | tr '[:upper:]' '[:lower:]' | tr -cs '[:alnum:]' '\n' | sort -u | tr '\n' ' ' | sed 's/ $//')
+
+if [[ -n "$LAST_RESPONSE_WORDS" ]] && [[ -n "$CURRENT_WORDS" ]]; then
+  # Word lists are already sorted unique from tokenization
+  PREV_LINES=$(echo "$LAST_RESPONSE_WORDS" | tr ' ' '\n')
+  CURR_LINES=$(echo "$CURRENT_WORDS" | tr ' ' '\n')
+  PREV_N=$(echo "$PREV_LINES" | wc -l)
+  CURR_N=$(echo "$CURR_LINES" | wc -l)
+  COMMON=$(comm -12 <(echo "$PREV_LINES") <(echo "$CURR_LINES") | wc -l)
+  UNION=$(( PREV_N + CURR_N - COMMON ))
+
+  if [[ $UNION -gt 0 ]]; then
+    SIMILARITY=$((COMMON * 100 / UNION))
+  else
+    SIMILARITY=0
+  fi
+
+  if [[ $SIMILARITY -ge 80 ]]; then
+    SIMILARITY_COUNT=$((SIMILARITY_COUNT + 1))
+  else
+    SIMILARITY_COUNT=0
+  fi
+else
+  SIMILARITY_COUNT=0
+fi
+LAST_RESPONSE_WORDS="$CURRENT_WORDS"
+
+# Check similarity threshold (3 consecutive similar responses)
+SIMILARITY_THRESHOLD=3
+if [[ $SIMILARITY_COUNT -ge $SIMILARITY_THRESHOLD ]]; then
+  echo "Ralph loop: terminated after $((SIMILARITY_COUNT + 1)) consecutive similar responses (similarity detection)" >&2
+  rm -f "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Not complete - continue loop with SAME PROMPT
+NEXT_ITERATION=$((ITERATION + 1))
+
+# Re-check before prompt extraction -- file may have been removed by concurrent invocation
+[[ -f "$RALPH_STATE_FILE" ]] || exit 0
+
+# Extract prompt (everything after the closing ---)
+PROMPT_TEXT=$(awk '/^---$/{i++; next} i>=2' "$RALPH_STATE_FILE" 2>/dev/null)
+
+if [[ -z "$PROMPT_TEXT" ]]; then
+  echo "Warning: No prompt text in state file. Stopping." >&2
+  rm -f "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Update iteration and stuck_count in first frontmatter block only (awk scoped to c==1)
+# Note: on legacy state files without stuck_count field, the awk match is a no-op for that line.
+# The counter will not persist across iterations. Acceptable because legacy files are only
+# created by pre-stuck-detection versions of setup-ralph-loop.sh; all new loops include the field.
+TEMP_FILE="${RALPH_STATE_FILE}.tmp.$$"
+awk -v iter="$NEXT_ITERATION" -v sc="$STUCK_COUNT" -v lrh="$LAST_RESPONSE_HASH" -v rc="$REPEAT_COUNT" -v simc="$SIMILARITY_COUNT" -v lrw="$LAST_RESPONSE_WORDS" '
+  /^---$/ { c++; print; next }
+  c==1 && /^iteration:/ { print "iteration: " iter; next }
+  c==1 && /^stuck_count:/ { print "stuck_count: " sc; next }
+  c==1 && /^last_response_hash:/ { print "last_response_hash: " lrh; next }
+  c==1 && /^repeat_count:/ { print "repeat_count: " rc; next }
+  c==1 && /^similarity_count:/ { print "similarity_count: " simc; next }
+  c==1 && /^last_response_words:/ { print "last_response_words: " lrw; next }
+  { print }
+' "$RALPH_STATE_FILE" > "$TEMP_FILE" 2>/dev/null || true
+if [[ -s "$TEMP_FILE" ]]; then
+  mv "$TEMP_FILE" "$RALPH_STATE_FILE"
+else
+  # awk produced empty output (file vanished) -- clean up and exit
+  rm -f "$TEMP_FILE"
+  exit 0
+fi
+
+# 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
+
+# --- Pipeline Tally Cap Floor (#9403) ---
+# Negative enforcement: when the branch's ledger shows a cap crossed — the
+# `capped` latch OR any count >= its cap_<dim> (catches a latch that never got
+# set: a skipped gate, a gate that returned UNKNOWN, a dim nobody gates) — the
+# pipeline is budget-capped and this hook declines to keep the loop alive: it
+# removes the fuel rather than denying a tool. Placed immediately before the
+# block emit so every terminating path above still wins. Fail-open in BOTH
+# directions: absent/corrupt/UNKNOWN output changes nothing — the hook never
+# blocks FOR the tally.
+#
+# Path resolution lives in pipeline-tally.sh — this hook reads `show` output
+# (`tally:` counts, `cap:<dim>=<n>` tokens, `capped:<dim>=<cap>`), never the
+# file, so there is one resolver and the transforms cannot drift.
+TALLY_SCRIPT="$SCRIPT_DIR/../scripts/pipeline-tally.sh"
+if [[ -f "$TALLY_SCRIPT" ]]; then
+  TALLY_OUT=$(bash "$TALLY_SCRIPT" show 2>/dev/null || true)
+  TALLY_CAPPED=""
+  TALLY_CAP=""
+  if [[ "$TALLY_OUT" == *"tally:"* && "$TALLY_OUT" != "UNKNOWN"* ]]; then
+    _TD="" _TC="" _TN=""
+    for _TD in $(printf '%s' "$TALLY_OUT" | grep -o 'capped:[a-z_]*=[0-9]*' | cut -d: -f2 | cut -d= -f1) \
+               $(printf '%s' "$TALLY_OUT" | grep -o 'cap:[a-z_]*=[0-9]*' | cut -d: -f2 | cut -d= -f1); do
+      [[ -n "$_TD" ]] || continue
+      if [[ "$TALLY_OUT" == *"capped:${_TD}="* ]]; then
+        TALLY_CAPPED="$_TD"
+        TALLY_CAP=$(printf '%s' "$TALLY_OUT" | grep -o "capped:${_TD}=[0-9]*" | cut -d= -f2 || true)
+        break
+      fi
+      # `|| true` on every extraction: a grep no-match under `set -e`/`pipefail`
+      # would exit the hook mid-loop — the opposite of this block's fail-open
+      # contract.
+      _TC=$(printf '%s' "$TALLY_OUT" | grep -o "cap:${_TD}=[0-9]*" | cut -d= -f2 || true)
+      _TN=$(printf '%s' "$TALLY_OUT" | grep -o "^tally:.*" | grep -o "${_TD}=[0-9]*" | cut -d= -f2 || true)
+      if [[ "$_TC" =~ ^[0-9]+$ ]] && [[ "$_TN" =~ ^[0-9]+$ ]] && (( 10#$_TC > 0 )) && (( 10#$_TN >= 10#$_TC )); then
+        TALLY_CAPPED="$_TD"; TALLY_CAP="$_TC"; break
+      fi
+    done
+    if [[ -n "$TALLY_CAPPED" ]]; then
+      _TN=$(printf '%s' "$TALLY_OUT" | grep -o "^tally:.*" | grep -o "${TALLY_CAPPED}=[0-9]*" | cut -d= -f2 || true)
+      printf 'SOLEUR_TALLY_CAPPED dim=%s cap=%s\n' "$TALLY_CAPPED" "${TALLY_CAP:-0}" >&2
+      # `--reset` deliberately NOT suggested: bare `init --max-<dim> N` takes
+      # `capped-reset`, which unlatches but PRESERVES the tally the feature
+      # exists to keep.
+      printf 'Ralph loop: pipeline tally is budget-capped; resume via pipeline-tally.sh init --max-%s N (raised caps).\n' "$(printf '%s' "$TALLY_CAPPED" | tr '_' '-')" >&2
+      # Classified-stop artifact: the state file is the ralph loop's own
+      # record — a resume that only reads stderr would never see the stop.
+      printf 'budget-capped: %s=%s/%s\n' "$TALLY_CAPPED" "${_TN:-0}" "${TALLY_CAP:-0}" >> "$RALPH_STATE_FILE" 2>/dev/null || true
+      exit 0
+    fi
+  fi
+fi
+
+# Output JSON to block the stop and feed prompt back
+jq -n \
+  --arg prompt "$PROMPT_TEXT" \
+  --arg msg "$SYSTEM_MSG" \
+  '{
+    "decision": "block",
+    "reason": $prompt,
+    "systemMessage": $msg
+  }'
+
+exit 0