feat(ralph-wiggum): add session isolation for multi-session support

State files now stored with session_id suffix to prevent cross-session
interference when multiple Claude Code sessions run concurrently.

Added:
- session-start-hook.sh: Captures session_id at session start
- lib/utils.sh: Session isolation utilities (get_session_id, get_state_file_path, etc.)

Changed:
- State file location: .claude/ralph-*.local.* → .claude/ralph-session.local/{name}.{session_id}.{ext}
- All lib modules use dynamic path resolution via utils.sh
- Updated docs to reflect new session-based state file naming
- Bump version to 1.1.0

Fixed:
- Cross-session interference: Stop hook now only processes state
  belonging to its session, preventing multiple Claude Code sessions
  from hijacking each other's loops

Co-Authored-By: duyetbot <duyetbot@users.noreply.github.com>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: duyet

.claude/iteration-log.md

@@ -1,7 +1,7 @@
 {
   "name": "ralph-wiggum",
-  "version": "1.0.1",
-  "description": "Self-referential development loop for Claude Code. Run iterative tasks with automatic progress detection and safety controls.",
+  "version": "1.1.0",
+  "description": "Self-referential development loop for Claude Code with session isolation. Run iterative tasks with automatic progress detection and safety controls.",
   "author": {
     "name": "duyet",
     "contributors": ["Daisy Hollman <daisy@anthropic.com>"]

ralph-wiggum/.claude-plugin/plugin.json

@@ -144,20 +144,19 @@ Output <promise>REFACTORED</promise> when complete.
 Use the status command or inspect files directly:
 
 ```bash
-# Quick status check
+# Quick status check (shows session ID)
 /status
 
-# Loop state file
-cat .claude/ralph-loop.local.md
+# List all session state files
+ls -la .claude/ralph-session.local/
 
-# Circuit breaker state
-cat .claude/ralph-circuit.json
-
-# Response analysis
-cat .claude/ralph-analysis.json
+# View specific session state (session_id shown in /status)
+cat .claude/ralph-session.local/ralph-loop.{session_id}.local.md
+cat .claude/ralph-session.local/ralph-circuit.{session_id}.json
+cat .claude/ralph-session.local/ralph-analysis.{session_id}.json
 ```
 
-State files are stored in `.claude/ralph-*` in your project directory.
+State files are stored in `.claude/ralph-session.local/` with session_id as filename suffix. Each Claude Code session has isolated state. The `.local` suffix ensures gitignore compatibility.
 
 ## Configuration
 
@@ -183,8 +182,10 @@ ralph-wiggum/
 │   └── help.md              # Plugin documentation
 ├── hooks/
 │   ├── hooks.json           # Hook configuration
+│   ├── session-start-hook.sh # Session ID capture
 │   └── stop-hook.sh         # Main loop interceptor
 ├── lib/
+│   ├── utils.sh             # Session isolation utilities
 │   ├── circuit_breaker.sh   # Stagnation detection
 │   ├── response_analyzer.sh # Completion analysis
 │   ├── api_limit_handler.sh # Rate limit handling
@@ -193,6 +194,14 @@ ralph-wiggum/
     ├── setup-ralph-loop.sh  # Loop initialization
     ├── status.sh            # Status display
     └── cancel-ralph.sh      # Cancellation handler
+
+Project directory (.claude/):
+├── ralph-session.local/
+│   ├── ralph-loop.{session_id}.local.md
+│   ├── ralph-circuit.{session_id}.json
+│   ├── ralph-analysis.{session_id}.json
+│   ├── ralph-limits.{session_id}.json
+│   └── ralph-tasks.{session_id}.json
 ```
 
 ## When to Use
@@ -220,7 +229,7 @@ ralph-wiggum/
 The smart exit feature may trigger on completion keywords. Options:
 - Use `--no-smart-exit` to disable completion detection
 - Add more specific requirements to your prompt
-- Check `.claude/ralph-analysis.json` to see what triggered the exit
+- Check `.claude/ralph-session.local/ralph-analysis.{session_id}.json` to see what triggered the exit
 
 ### Loop runs forever
 
@@ -233,7 +242,7 @@ Ensure your prompt includes:
 
 The circuit breaker stops loops that aren't making progress:
 - Ensure each iteration changes files
-- Check `.claude/ralph-circuit.json` for details
+- Check `.claude/ralph-session.local/ralph-circuit.{session_id}.json` for details
 - Use `--reset-circuit` to reset state if needed
 
 ### Rate limits
@@ -246,19 +255,41 @@ If you hit Claude's API limits:
 ### Debugging
 
 ```bash
-# Check all state files
-ls -la .claude/ralph-*
+# Check all session state files
+ls -la .claude/ralph-session.local/
 
-# View loop configuration
-cat .claude/ralph-loop.local.md
+# View loop configuration (use session_id from /status)
+cat .claude/ralph-session.local/ralph-loop.{session_id}.local.md
 
 # Check circuit breaker state
-cat .claude/ralph-circuit.json
+cat .claude/ralph-session.local/ralph-circuit.{session_id}.json
 
 # Review completion analysis
-cat .claude/ralph-analysis.json
+cat .claude/ralph-session.local/ralph-analysis.{session_id}.json
 ```
 
+## Changelog
+
+### [1.1.0] - Session Isolation
+
+**Added**
+- Session isolation: State files now stored as `.claude/ralph-session.local/{name}.{session_id}.{ext}`
+- SessionStart hook: Captures session_id at session start
+- Session ID display: `/status` shows current session ID
+- lib/utils.sh: New utility module for session isolation
+
+**Fixed**
+- Cross-session interference: Stop hook now only processes state belonging to its session, preventing multiple Claude Code sessions from hijacking each other's loops
+
+**Changed**
+- State file location moved from `.claude/ralph-*.local.*` to `.claude/ralph-session.local/{name}.{session_id}.{ext}`
+- All library modules use dynamic path resolution
+- `.local` suffix on directory ensures gitignore compatibility
+
+### [1.0.1] - Initial Release
+
+Self-referential development loop with circuit breaker, smart exit, and API limit handling.
+
 ## References
 
 - [ghuntley.com/ralph](https://ghuntley.com/ralph/)

ralph-wiggum/README.md

@@ -13,8 +13,8 @@ Execute the setup script to initialize the Ralph loop:
 "${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS
 
 # Display completion promise if set
-if [ -f .claude/ralph-loop.local.md ]; then
-  PROMISE=$(grep '^completion_promise:' .claude/ralph-loop.local.md | sed 's/completion_promise: *//' | sed 's/^"\(.*\)"$/\1/')
+if [ -f "${RALPH_STATE_DIR:-.claude}/ralph-loop.md" ]; then
+  PROMISE=$(grep '^completion_promise:' "${RALPH_STATE_DIR:-.claude}/ralph-loop.md" | sed 's/completion_promise: *//' | sed 's/^"\(.*\)"$/\1/')
   if [ -n "$PROMISE" ] && [ "$PROMISE" != "null" ]; then
     echo ""
     echo "==============================================================="

ralph-wiggum/commands/ralph-loop.md

@@ -1,5 +1,15 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start-hook.sh"
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "hooks": [

ralph-wiggum/hooks/hooks.json

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+# Ralph Wiggum Session Start Hook
+# Captures session ID and persists it for use in commands and stop hook
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(dirname "$SCRIPT_DIR")"
+LIB_DIR="$PLUGIN_ROOT/lib"
+
+# Load utilities
+[[ -f "$LIB_DIR/utils.sh" ]] && source "$LIB_DIR/utils.sh"
+
+# Read hook input from stdin
+HOOK_INPUT=$(cat)
+
+# Extract and persist session ID
+load_session_from_hook_input "$HOOK_INPUT"
+
+# Session start hook must exit 0 and produce no output
+exit 0

ralph-wiggum/hooks/session-start-hook.sh

@@ -9,7 +9,11 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PLUGIN_ROOT="$(dirname "$SCRIPT_DIR")"
 LIB_DIR="$PLUGIN_ROOT/lib"
 
-export RALPH_STATE_DIR=".claude"
+# Load utilities for session isolation
+[[ -f "$LIB_DIR/utils.sh" ]] && source "$LIB_DIR/utils.sh"
+
+export RALPH_STATE_DIR
+RALPH_STATE_DIR=$(get_ralph_state_dir)
 
 load_modules() {
   local modules_loaded=0
@@ -21,13 +25,27 @@ load_modules() {
 }
 
 HOOK_INPUT=$(cat)
-RALPH_STATE_FILE=".claude/ralph-loop.local.md"
+HOOK_SESSION_ID=$(echo "$HOOK_INPUT" | jq -r '.session_id')
+
+# Get current session ID from env file if not in hook input
+if [[ -z "$HOOK_SESSION_ID" ]] || [[ "$HOOK_SESSION_ID" == "null" ]]; then
+  HOOK_SESSION_ID=$(get_session_id)
+fi
+
+RALPH_STATE_FILE=$(get_state_file_path "ralph-loop" "md")
 
-# No active loop - allow exit
+# No active loop in this session - allow exit
 if [[ ! -f "$RALPH_STATE_FILE" ]]; then
   exit 0
 fi
 
+# Verify state file belongs to this session
+STATE_SESSION_ID=$(grep '^session_id:' "$RALPH_STATE_FILE" 2>/dev/null | sed 's/session_id: *//' || echo "")
+if [[ -n "$STATE_SESSION_ID" ]] && [[ "$STATE_SESSION_ID" != "$HOOK_SESSION_ID" ]]; then
+  # State file belongs to different session - ignore it
+  exit 0
+fi
+
 MODULES_LOADED=$(load_modules)
 
 # Parse state file frontmatter
@@ -215,8 +233,9 @@ fi
 
 ANALYSIS_STATUS=""
 if [[ "$ENABLE_SMART_EXIT" == "true" ]] && type should_exit &>/dev/null; then
-  [[ -f "${RALPH_STATE_DIR:-.claude}/ralph-analysis.json" ]] && {
-    LAST_CONF=$(jq -r '.last_confidence // 0' "${RALPH_STATE_DIR:-.claude}/ralph-analysis.json")
+  ANALYSIS_FILE=$(get_state_file_path "ralph-analysis.json")
+  [[ -f "$ANALYSIS_FILE" ]] && {
+    LAST_CONF=$(jq -r '.last_confidence // 0' "$ANALYSIS_FILE")
     ANALYSIS_STATUS=" | Confidence: ${LAST_CONF}/40"
   }
 fi

ralph-wiggum/hooks/stop-hook.sh

@@ -5,7 +5,12 @@
 
 set -eo pipefail
 
-LIMIT_STATE_FILE="${RALPH_STATE_DIR:-.claude}/ralph-limits.json"
+# Use get_state_file_path utility if available, otherwise use RALPH_STATE_DIR
+if type get_state_file_path &>/dev/null; then
+  LIMIT_STATE_FILE=$(get_state_file_path "ralph-limits" "json")
+else
+  LIMIT_STATE_FILE="${RALPH_STATE_DIR:-.claude}/ralph-limits.json"
+fi
 DEFAULT_WAIT_SECONDS=${RALPH_WAIT_SECONDS:-3600}
 
 # Rate limit patterns as space-separated string (portable across bash versions)