Debugging a Ghost in the Machine: Session Isolation for Claude Code Plugins

Last week one of my Claude Code sessions got hijacked. I’d opened it for a quick, unrelated fix; it finished the job — and then, instead of handing control back to me, it picked up a long-running task from a different session in the same project and started working on that instead.

Running several sessions in one project at once is normal for me. One will grind through a long task on a Ralph Wiggum loop — a self-referential technique where the agent feeds its own prompt back to itself and keeps iterating — while I spin up another on the side for a quick fix. Two sessions, one directory, no problem. Until there was.

Hooks are global, but state must be local. Any plugin that keeps its state in one fixed-name file will collide the moment two sessions share a project directory — and Claude Code makes sharing one trivial.

The bug was subtle but reproducible. Finding it forced me to understand how Claude Code’s hooks actually work.

The hook behavior that mattered

Claude Code has an event-driven hook system — small shell scripts that run when a session starts (SessionStart), tries a tool (PreToolUse), tries to stop (Stop), and so on. Plugins register these scripts. The important detail is that hooks are global: every registered hook fires for every session in the project.

The Stop hook is the interesting one. When Claude tries to end a conversation, a Stop hook can refuse to let it exit by returning a JSON payload:

{
  "decision": "block",
  "reason": "Your next prompt goes here",
  "systemMessage": "Context injected as a system message"
}

That is how the Ralph Wiggum loop works. The Stop hook intercepts the exit, reads the loop state, and feeds the prompt back in. Claude sees its previous work in the codebase and iterates. The problem appears when a second session opens.

The collision

The ralph-wiggum plugin kept its loop state in a single file: .claude/ralph-loop.local.md. The Stop hook checked whether that file existed and, if it did, blocked the exit. The problem was obvious once I traced it — though it took me a minute to get there, because each session looked perfectly healthy on its own:

The Stop hook had no session identity. It asked one question — does the state file exist? — and blocked the exit when the answer was yes. It did not matter that another window had created the file. A single-session test will never expose this isolation bug. Any plugin that writes to disk needs a two-session test; it is the ordinary concurrent-access problem — two processes writing to one path — at the AI-session level.

The fix: one file per session

Claude Code includes a session_id — a unique ID it assigns to each conversation — in the JSON payload it pipes to every hook via stdin (the standard input stream every Unix program can read). The fix is to use that ID to give each session its own state file:

# In the Stop hook — extract session_id from hook input
HOOK_INPUT=$(cat)
SESSION_ID=$(echo "$HOOK_INPUT" | jq -r '.session_id // empty')

# Only look for THIS session's state file
RALPH_STATE_FILE=".claude/ralph-loop.${SESSION_ID}.local.md"

if [[ ! -f "$RALPH_STATE_FILE" ]]; then
  # Not our loop — allow normal exit
  exit 0
fi

jq is a command-line tool for pulling fields out of JSON; the // empty says “if session_id is missing, return nothing instead of the literal word null.”

There was one catch. The setup script that creates the state file when /ralph-loop runs uses the Bash tool (the command-run feature inside a Claude Code session), not a hook. It does not receive the same JSON input. It still needed the session ID.

Passing the ID across the boundary

Hooks receive JSON with the session ID, transcript path, and current working directory. Bash commands run through the tool do not. Claude Code provides CLAUDE_ENV_FILE: a SessionStart hook can write export statements into it, and later commands in that session read them as environment variables. This is the canonical way to pass session context across the hook and command boundary:

#!/bin/bash
# session-start-hook.sh — fires when any session begins
HOOK_INPUT=$(cat)
SESSION_ID=$(echo "$HOOK_INPUT" | jq -r '.session_id // empty')

if [[ -n "$SESSION_ID" ]] && [[ -n "${CLAUDE_ENV_FILE:-}" ]]; then
  echo "export CLAUDE_SESSION_ID='$SESSION_ID'" >> "$CLAUDE_ENV_FILE"
fi

Now the setup script can read $CLAUDE_SESSION_ID and create the matching state file:

# In setup-ralph-loop.sh
SESSION_ID="${CLAUDE_SESSION_ID:-$(date +%s%N | md5sum | cut -c1-12)}"
RALPH_STATE_FILE=".claude/ralph-loop.${SESSION_ID}.local.md"

The fallback — a random 12-character ID — covers a session that started before the new SessionStart hook was installed and never received CLAUDE_SESSION_ID. It invents an ID instead of crashing.

The fix is submitted upstream to the ralph-wiggum plugin in the claude-code repo. If a plugin has caused mysterious interference between sessions, shared state is very likely why.

Architecture: the three-script pattern

# SessionStart hook — stamp env, reap orphans older than 24h
HOOK_INPUT=$(cat)
SESSION_ID=$(echo "$HOOK_INPUT" | jq -r '.session_id // empty')
[[ -n "$SESSION_ID" && -n "${CLAUDE_ENV_FILE:-}" ]] &&
  echo "export CLAUDE_SESSION_ID='$SESSION_ID'" >> "$CLAUDE_ENV_FILE"

# Clean up state files from sessions that exited without cleanup
find .claude -name 'ralph-loop.*.local.md' -mmin +1440 -delete 2>/dev/null