rafcode 2.0.0 → 2.1.0

package/.claude/settings.local.json

@@ -26,7 +26,9 @@
       "Bash(EDITOR='cp /dev/stdin' node dist/index.js plan testproj 2)",
       "Bash(1 <<'EOF'\nThis is a test project description\nEOF)",
       "Bash(git stash:*)",
-      "Bash(git checkout:*)"
+      "Bash(git checkout:*)",
+      "WebFetch(domain:docs.anthropic.com)",
+      "WebFetch(domain:news.ycombinator.com)"
     ]
   }
 }

package/RAF/ahrren-turbo-finder/decisions.md

@@ -0,0 +1,19 @@
+# Project Decisions
+
+## For the worktree resolution fix: should `raf do turbo-finder` (no --worktree flag) automatically detect and use the worktree project? Or should it still require the --worktree flag but just fix name/ID matching within that flag?
+Auto-detect worktrees — `raf do <name>` searches worktrees automatically if not found in main repo, then auto-enables worktree mode.
+
+## For reducing reasoning: which commands should use low reasoning effort?
+Only do — Use low reasoning only for task execution (`raf do`), not for planning.
+
+## For worktree auto-detection: when `raf do <name>` finds the project in a worktree, should it also trigger the post-execution action picker (merge/PR/leave) like the --worktree flag does?
+Yes, full worktree flow — Auto-detected worktree projects get the same post-action picker as explicitly --worktree projects.
+
+## For the reasoning effort on `raf do`: implementation approach?
+Use env var approach — Set `CLAUDE_CODE_EFFORT_LEVEL=medium` environment variable when spawning Claude processes for task execution.
+
+## What effort level for `raf do`?
+Medium — Use `CLAUDE_CODE_EFFORT_LEVEL=medium` (not low).
+
+## Given the env var UI bug (GitHub #23604), how should RAF set effort?
+Use env var anyway — `CLAUDE_CODE_EFFORT_LEVEL=medium` likely works at the API level despite the `/model` UI not reflecting it. Simplest approach.

package/RAF/ahrren-turbo-finder/input.md

@@ -0,0 +1,2 @@
+- [ ] fix: i can't do "raf do <project name without id>" it the project in the worktree. make sure it works just for project ids as well. rely on naming convention of worktree folder (same a project)
+- [ ] reduce opus reasoning to low for plan do. search for docs on how to do that

package/RAF/ahrren-turbo-finder/outcomes/01-worktree-auto-detect.md

@@ -0,0 +1,40 @@
+# Outcome: Auto-detect worktree projects in `raf do`
+
+## Summary
+
+Implemented automatic worktree project detection in `raf do <identifier>` so that the `--worktree` flag is no longer required when running worktree projects by name, ID, or full folder name.
+
+## Key Changes
+
+### `src/core/worktree.ts`
+- Added `resolveWorktreeProjectByIdentifier()` function that matches a project identifier against worktree folder names using the same resolution strategy as `resolveProjectIdentifierWithDetails`:
+  1. Full folder name match (exact, case-insensitive)
+  2. Base26 prefix match (6-char ID)
+  3. Project name match (portion after prefix)
+- Added `WorktreeProjectResolution` interface for the return type
+- Added import of `extractProjectNumber`, `extractProjectName`, `isBase26Prefix`, `decodeBase26` from paths utility
+
+### `src/commands/do.ts`
+- Modified the standard (non-worktree) resolution path to check worktrees FIRST, then fall back to main repo
+- When a worktree match is found, auto-enables worktree mode: sets `worktreeMode = true`, `worktreeRoot`, `originalBranch`
+- This triggers the full worktree flow: post-execution action picker, worktree cwd, and cleanup
+- Changed `resolvedProject` type to `| undefined` to support the two-step resolution (worktree then main)
+- Added import for `resolveWorktreeProjectByIdentifier`
+
+### `tests/unit/worktree.test.ts`
+- Added 11 test cases for `resolveWorktreeProjectByIdentifier`:
+  - Full folder name match (exact and case-insensitive)
+  - Base26 prefix match
+  - Project name match (case-insensitive)
+  - No match / no worktree projects
+  - Ambiguous name match returns null
+  - Correct worktreeRoot path
+
+### `tests/unit/post-execution-picker.test.ts`
+- Added `resolveWorktreeProjectByIdentifier` to the worktree module mock to prevent import failure
+
+## Test Results
+
+All 45 test suites pass (971 tests total, 0 failures).
+
+<promise>COMPLETE</promise>

package/RAF/ahrren-turbo-finder/outcomes/02-medium-effort-do.md

@@ -0,0 +1,34 @@
+# Outcome: Set medium reasoning effort for `raf do` execution
+
+## Summary
+
+Configured `raf do` to spawn Claude CLI processes with `CLAUDE_CODE_EFFORT_LEVEL=medium` environment variable, reducing reasoning overhead during automated task execution while preserving default (high) effort for interactive planning sessions.
+
+## Key Changes
+
+### `src/core/claude-runner.ts`
+- Added optional `effortLevel` field (`'low' | 'medium' | 'high'`) to `ClaudeRunnerOptions` interface
+- In `run()`: when `effortLevel` is set, spreads `process.env` with `CLAUDE_CODE_EFFORT_LEVEL` override; otherwise passes `process.env` directly
+- In `runVerbose()`: same env injection logic as `run()`
+- `runInteractive()` is unchanged — uses `process.env` as-is (no effort override for planning sessions)
+
+### `src/commands/do.ts`
+- Passes `effortLevel: 'medium'` in both `claudeRunner.run()` and `claudeRunner.runVerbose()` calls during task execution
+
+### `tests/unit/claude-runner.test.ts`
+- Added 6 tests in new `effort level` describe block:
+  - Verifies `CLAUDE_CODE_EFFORT_LEVEL` is set in env for `run()` when effortLevel provided
+  - Verifies `CLAUDE_CODE_EFFORT_LEVEL` is set in env for `runVerbose()` when effortLevel provided
+  - Verifies env is `process.env` directly (no override) when effortLevel not provided in `run()`
+  - Verifies env is `process.env` directly (no override) when effortLevel not provided in `runVerbose()`
+  - Verifies all three levels (low, medium, high) work correctly
+  - Verifies other env vars (e.g., PATH) are preserved when effortLevel is set
+
+### `tests/unit/claude-runner-interactive.test.ts`
+- Added 1 test verifying `runInteractive()` does NOT set `CLAUDE_CODE_EFFORT_LEVEL` in its env
+
+## Test Results
+
+All 45 test suites pass (978 tests total, 0 failures).
+
+<promise>COMPLETE</promise>

package/RAF/ahrren-turbo-finder/plans/01-worktree-auto-detect.md

@@ -0,0 +1,44 @@
+# Task: Auto-detect worktree projects in `raf do`
+
+## Objective
+Make `raf do <name>` and `raf do <id>` automatically find and run worktree projects without requiring the `--worktree` flag.
+
+## Context
+Currently, `raf do <identifier>` without `--worktree` only searches the main repo's RAF directory. If a project lives exclusively in a worktree (or the user simply omits the flag), the command fails with "project not found". The worktree folder name matches the project folder name (e.g., `~/.raf/worktrees/<repo>/ahrren-turbo-finder/`), so resolution can leverage this naming convention.
+
+When a worktree project is auto-detected, the full worktree flow should activate — including the post-execution action picker (merge/PR/leave), worktree cwd, and cleanup behavior — exactly as if `--worktree` had been passed.
+
+## Requirements
+- When `raf do <name>` (e.g., `turbo-finder`) doesn't find the project in the main repo, fall back to searching worktree directories
+- When `raf do <id>` (e.g., `ahrren`) doesn't find the project in the main repo, fall back to searching worktree directories
+- When `raf do <full-folder>` (e.g., `ahrren-turbo-finder`) doesn't find the project in the main repo, fall back to searching worktree directories
+- Use the worktree folder naming convention: worktree folders at `~/.raf/worktrees/<repo-basename>/<project-folder>/` where `<project-folder>` matches the project folder name format (`XXXXXX-name`)
+- Match identifiers against worktree folder names using the same resolution logic as `resolveProjectIdentifierWithDetails` (full name, base26 ID, or project name)
+- When a worktree project is auto-detected, enable the full worktree mode: set `worktreeMode = true`, `worktreeRoot`, `originalBranch`, and trigger the post-execution action picker
+- If project exists in both main repo and worktree, prefer the worktree version (consistent with existing picker deduplication behavior)
+
+## Implementation Steps
+1. In `runDoCommand()` in `src/commands/do.ts`, modify the non-worktree resolution path (currently around line 305) to add a worktree fallback
+2. After `resolveProjectIdentifierWithDetails(rafDir, projectIdentifier)` fails (returns no path), check if the current directory is a git repo
+3. If in a git repo, use `listWorktreeProjects(repoBasename)` to get worktree project folders
+4. For each worktree folder, attempt to match the identifier using the same resolution strategy: full folder name match, base26 prefix match, or name-portion match
+5. If a match is found, set `worktreeMode = true`, compute `worktreeRoot`, record `originalBranch`, and proceed through the existing worktree validation and execution flow
+6. Consider also checking worktrees FIRST (before main repo) or in parallel, to match the picker behavior where worktree versions take priority over main repo versions
+7. Add unit tests for the new auto-detection logic
+8. Add integration-level tests verifying the full flow (identifier → worktree detection → worktree mode enabled)
+
+## Acceptance Criteria
+- [ ] `raf do turbo-finder` finds and runs a worktree project named `ahrren-turbo-finder`
+- [ ] `raf do ahrren` finds and runs a worktree project with ID `ahrren`
+- [ ] `raf do ahrren-turbo-finder` finds and runs the worktree project by full folder name
+- [ ] Auto-detected worktree projects trigger the post-execution action picker (merge/PR/leave)
+- [ ] Auto-detected worktree projects execute with the worktree as cwd
+- [ ] If project exists in both main and worktree, worktree version is preferred
+- [ ] Existing `--worktree` flag behavior is unchanged
+- [ ] All existing tests pass
+- [ ] New tests cover the auto-detection scenarios
+
+## Notes
+- The existing worktree resolution code (lines 240-304 in `do.ts`) already handles the case where `--worktree` is passed. The new code should reuse as much of that logic as possible rather than duplicating it.
+- `listWorktreeProjects()` from `src/core/worktree.ts` returns sorted folder names. Resolution against these can use string matching without needing filesystem reads into each worktree's RAF dir.
+- Be careful with the `projectFolderName` variable scoping — it's currently declared inside the worktree block and needs to be accessible when auto-detection sets worktree mode.

package/RAF/ahrren-turbo-finder/plans/02-medium-effort-do.md

@@ -0,0 +1,39 @@
+# Task: Set medium reasoning effort for `raf do` execution
+
+## Objective
+Configure `raf do` to spawn Claude CLI processes with `CLAUDE_CODE_EFFORT_LEVEL=medium` to reduce reasoning overhead during task execution.
+
+## Dependencies
+01
+
+## Context
+By default, Claude Opus uses "high" effort level which allocates more thinking tokens. For automated task execution via `raf do`, medium effort provides a good balance of speed, cost, and capability. The `CLAUDE_CODE_EFFORT_LEVEL` environment variable is the supported mechanism for controlling this in the Claude Code CLI.
+
+RAF's `ClaudeRunner` already passes `process.env` to spawned processes (lines 296, 400, 512 in `claude-runner.ts`). The change needs to inject `CLAUDE_CODE_EFFORT_LEVEL=medium` into the environment for non-interactive (task execution) runs, while leaving interactive planning sessions (`raf plan`) at default effort.
+
+## Requirements
+- Set `CLAUDE_CODE_EFFORT_LEVEL=medium` in the environment when spawning Claude processes for `raf do` task execution
+- Do NOT affect `raf plan` (interactive planning sessions should keep default/high effort)
+- Do NOT affect failure analysis (which uses Haiku via `ClaudeRunner`)
+- The effort level should be configurable through `ClaudeRunnerOptions` or `ClaudeRunnerConfig` so it's not hardcoded deep in the runner
+- Pass the env var by spreading it into the `env` object passed to `spawn()` and `pty.spawn()`
+
+## Implementation Steps
+1. Add an optional `effortLevel` field to `ClaudeRunnerOptions` or `ClaudeRunnerConfig` in `src/core/claude-runner.ts`
+2. In the `run()` and `runVerbose()` methods, merge `CLAUDE_CODE_EFFORT_LEVEL` into the environment when `effortLevel` is set
+3. In `src/commands/do.ts`, pass `effortLevel: 'medium'` when constructing or calling `ClaudeRunner` for task execution
+4. Ensure the interactive `runInteractive()` method does NOT apply the effort override (planning should stay at default)
+5. Add tests verifying the env var is passed correctly
+6. Add tests verifying that planning mode does not get the env var
+
+## Acceptance Criteria
+- [ ] `raf do` spawns Claude with `CLAUDE_CODE_EFFORT_LEVEL=medium` in the environment
+- [ ] `raf plan` does NOT set `CLAUDE_CODE_EFFORT_LEVEL` (uses default behavior)
+- [ ] The effort level is configurable (not hardcoded in the spawn call)
+- [ ] Existing tests pass
+- [ ] New tests verify the env var injection
+
+## Notes
+- The three spawn points in `claude-runner.ts` are: `pty.spawn()` at line 291 (interactive), `spawn()` at line 390 (non-interactive), and `spawn()` at line 499 (verbose). Only the non-interactive and verbose spawns should get the effort override.
+- The env var `CLAUDE_CODE_EFFORT_LEVEL` is confirmed as the correct name per official docs at code.claude.com/docs/en/model-config. Note: there is a known UI bug (GitHub issue #23604) where the `/model` UI always shows "High effort" regardless of the env var, but the env var is believed to still affect actual API requests.
+- An alternative approach (if the env var turns out to be truly broken) would be to write `"effortLevel": "medium"` to a `.claude/settings.json` in the working directory before spawning Claude. This is a fallback, not the primary approach.

package/RAF/ahrtxf-session-sentinel/decisions.md

@@ -0,0 +1,19 @@
+# Project Decisions
+
+## What's the main use case for logging the session ID?
+Resume interrupted sessions. Capture session ID so RAF can attempt to resume interrupted Claude sessions using `claude --resume <id>`, and also allow manual inspection. Add `raf do <project> --resume <session-id>` flag for resuming after Ctrl+C interruption.
+
+## Should the session ID be captured in all execution modes?
+Verbose + non-interactive. Both modes that run tasks should capture session ID. Interactive planning mode can be skipped.
+
+## When a session is interrupted, should the session ID be displayed to the user?
+Print to terminal. Display session ID in terminal output on interruption so user can copy it for `--resume`.
+
+## For `raf do --resume`, should it resume the exact interrupted task or restart from scratch?
+Resume exact task. Pass `--resume` to Claude CLI for the specific interrupted task, continuing from where Claude left off mid-task. Add metadata (task ID) to support this. Format could be `--resume <task-id>:<session-id>` or assume it's the last unfinished task.
+
+## How should non-interactive mode get access to the session ID?
+Always use `--output-format stream-json` for both verbose and non-interactive modes. Parse the init event to capture session_id. Only render/display the stream output when `--verbose` flag is passed. This gives us session IDs universally without changing user-visible behavior.
+
+## When resuming, should RAF pass the original task's system prompt again?
+Rely on session state. Trust that Claude's `--resume` restores the full context including the original prompt. Don't re-send system prompt or task context.

package/RAF/ahrtxf-session-sentinel/input.md

@@ -0,0 +1 @@
+check if it's possible to log claude session id if session got interrupted

package/RAF/ahrtxf-session-sentinel/outcomes/01-capture-session-id.md

@@ -0,0 +1,37 @@
+# Outcome: Capture Session ID from Claude CLI Output
+
+## Summary
+
+Implemented session ID extraction from Claude CLI's `system.init` NDJSON event in both `run()` and `runVerbose()` methods. The session ID is now captured, returned in `RunResult`, and printed to the terminal on interruption.
+
+## Key Changes
+
+### `src/parsers/stream-renderer.ts`
+- Added `session_id` field to `StreamEvent` interface
+- Added `sessionId` field to `RenderResult` interface
+- Modified `renderStreamEvent()` to extract and return `session_id` from system init events
+
+### `src/core/claude-runner.ts`
+- Added `sessionId?: string` field to `RunResult` interface
+- Added `_sessionId` private field and public `sessionId` getter to `ClaudeRunner` class
+- Refactored `run()` to use `--output-format stream-json --verbose` with silent NDJSON parsing (no stdout display), enabling session ID extraction
+- Updated `runVerbose()` to capture `sessionId` from stream events
+- Both methods return `sessionId` in `RunResult`
+- Session ID is printed via `logger.info()` on timeout and context overflow in both methods
+
+### `src/core/shutdown-handler.ts`
+- Added session ID logging in `handleShutdown()` — prints `Session ID: <id>` when a Claude session is interrupted via Ctrl+C/SIGTERM
+
+### `tests/unit/stream-renderer.test.ts`
+- Added 3 new tests: session_id extraction, undefined for missing session_id, undefined for non-system events
+
+### `tests/unit/claude-runner.test.ts`
+- Updated existing `run()` tests to emit NDJSON events (since `run()` now uses stream-json format)
+- Updated flag assertion: `run()` now includes `--output-format stream-json --verbose`
+- Added 5 new tests: sessionId extraction in run(), runVerbose(), undefined when missing, getter exposure, deduplication
+
+## Test Results
+
+All 986 tests pass (45 test suites). No regressions introduced.
+
+<promise>COMPLETE</promise>

package/RAF/ahrtxf-session-sentinel/outcomes/02-resume-flag.md

@@ -0,0 +1,45 @@
+# Outcome: Add --resume Flag to raf do Command
+
+## Summary
+
+Added `--resume <session-id>` option to `raf do` that resumes an interrupted Claude session for a specific task. When used, Claude is spawned with `--resume` flag only (no prompt/model/system-prompt flags), and completion monitoring works identically to normal execution.
+
+## Key Changes
+
+### `src/types/config.ts`
+- Added `resume?: string` field to `DoCommandOptions` interface
+
+### `src/commands/do.ts`
+- Added `-r, --resume <session-id>` option to the `do` command definition
+- Added `resumeSessionId` to `SingleProjectOptions` interface
+- In the task execution loop: when `activeResumeSessionId` is set, calls `runResume()` instead of `run()`/`runVerbose()` for the first attempt
+- Clears `activeResumeSessionId` after the first task completes, so subsequent tasks use normal execution
+- Prints clear user-facing message: `Resuming task <id> with session <session-id>` in both verbose and minimal modes
+
+### `src/core/claude-runner.ts`
+- Added `runResume(sessionId, options)` method that spawns Claude with:
+  - `--resume <session-id>` — restores the interrupted session
+  - `--dangerously-skip-permissions` — required for non-interactive operation
+  - `--output-format stream-json --verbose` — enables NDJSON event parsing
+  - Does NOT pass `--model`, `--append-system-prompt`, or `-p` (Claude restores these from session state)
+- Same completion detection, timeout handling, context overflow detection, and session ID extraction as existing methods
+
+### `tests/unit/claude-runner.test.ts`
+- Added 11 new tests in `runResume()` describe block:
+  - Spawns with `--resume` flag and session ID
+  - Does NOT include `--model`, `--append-system-prompt`, or `-p` flags
+  - Includes `--dangerously-skip-permissions` flag
+  - Includes `--output-format stream-json` and `--verbose` flags
+  - Collects output from NDJSON events
+  - Handles timeout correctly
+  - Detects completion markers
+  - Extracts session ID from resumed session
+  - Passes cwd to spawn (worktree support)
+  - Detects context overflow
+  - Sets CLAUDE_CODE_EFFORT_LEVEL env var when provided
+
+## Test Results
+
+All 997 tests pass (45 test suites). No regressions introduced.
+
+<promise>COMPLETE</promise>

package/RAF/ahrtxf-session-sentinel/plans/01-capture-session-id.md

@@ -0,0 +1,41 @@
+# Task: Capture Session ID from Claude CLI Output
+
+## Objective
+Extract and store the Claude session ID from stream-json output in both verbose and non-interactive execution modes.
+
+## Context
+Claude CLI emits a `session_id` in its `system.init` NDJSON event when using `--output-format stream-json`. RAF currently discards this event entirely. We need to capture and surface this ID so it can be used for session resumption and debugging.
+
+## Requirements
+- Unify both `run()` (non-interactive) and `runVerbose()` methods to use `--output-format stream-json` so that the system init event is always available
+- In non-verbose mode, parse NDJSON events silently (extract textContent for output accumulation and detect completion markers) without rendering anything to stdout
+- In verbose mode, continue rendering stream events to stdout as before
+- Extract `session_id` from the `system.init` event (first event in the stream)
+- Add `sessionId?: string` field to the `RunResult` type returned by both `run()` and `runVerbose()`
+- Modify `renderStreamEvent()` in `stream-renderer.ts` to return the session_id when it encounters a system init event, rather than discarding it
+- When a session is interrupted (Ctrl+C, timeout, context overflow), print the session ID to terminal: `Session ID: <id>` so the user can copy it
+- Add tests for the session ID extraction from system init events
+- Add tests verifying session ID is included in RunResult
+
+## Implementation Steps
+1. Update the `RunResult` type to include an optional `sessionId` field
+2. Modify `renderStreamEvent()` to extract and return `session_id` from system init events (add a new field to the return type, e.g. `sessionId?: string`)
+3. Refactor `run()` to use `--output-format stream-json` internally, parsing NDJSON lines the same way `runVerbose()` does, but without writing display output to stdout
+4. In both `run()` and `runVerbose()`, capture the session_id from the first system init event and include it in the returned `RunResult`
+5. In the shutdown handler and timeout/overflow paths, print the captured session ID to the terminal before exiting
+6. Write unit tests for session ID extraction from stream events
+7. Write integration-style tests verifying RunResult includes sessionId
+
+## Acceptance Criteria
+- [ ] `run()` uses stream-json format internally and parses events silently
+- [ ] `runVerbose()` continues to display stream events as before
+- [ ] Both methods return `sessionId` in `RunResult` when available
+- [ ] On interruption (Ctrl+C, timeout, overflow), session ID is printed to terminal
+- [ ] Existing tests continue to pass
+- [ ] New tests cover session ID extraction
+
+## Notes
+- The system init event format is: `{ type: 'system', subtype: 'init', session_id: string, tools: string[], model: string }`
+- Currently `stream-renderer.ts` line 96 returns `{ display: '', textContent: '' }` for all system events — this is where extraction should happen
+- The `run()` method currently uses plain text output with `child_process.spawn` — it needs to switch to stream-json parsing similar to `runVerbose()`. Consider extracting shared NDJSON parsing logic to avoid duplication.
+- Be careful: `run()` has its own completion marker detection and timeout logic that must continue to work with the new stream-json parsing

package/RAF/ahrtxf-session-sentinel/plans/02-resume-flag.md

@@ -0,0 +1,51 @@
+# Task: Add --resume Flag to raf do Command
+
+## Objective
+Add a `--resume` option to `raf do` that resumes an interrupted Claude session for a specific task.
+
+## Context
+After task 01 captures the session ID and displays it on interruption, users need a way to actually resume the interrupted session. This task adds `raf do <project> --resume <session-id>` which passes Claude CLI's `--resume` flag to continue a session from where it left off.
+
+## Dependencies
+01
+
+## Requirements
+- Add `--resume <session-id>` option to the `raf do` command in Commander.js
+- When `--resume` is provided, RAF should:
+  1. Identify the task to resume — find the first task that is in-progress (has no outcome file, or has a partial/missing completion marker)
+  2. Skip the normal task execution flow and instead spawn Claude with `--resume <session-id>` flag
+  3. Do NOT pass `-p` (prompt), `--append-system-prompt`, or `--model` flags — rely on Claude's session state to restore these
+  4. DO pass `--dangerously-skip-permissions` as it's required for non-interactive operation
+  5. Still use `--output-format stream-json` so we can capture the new session's events and detect completion
+  6. Continue monitoring for completion markers and outcome file as usual
+- After the resumed session completes, normal post-task flow should apply (outcome validation, commit verification, next task, etc.)
+- If `--resume` is used with `--worktree`, ensure the CWD is set to the worktree path
+- Print a clear message indicating which task is being resumed: `Resuming task <id> with session <session-id>`
+- Add a new method to `ClaudeRunner` (e.g. `runResume(sessionId, options)`) that spawns Claude with the `--resume` flag
+- Cover the new flag and resume method with tests
+
+## Implementation Steps
+1. Add `--resume <session-id>` option to the `do` command definition in `src/commands/do.ts`
+2. Add a `runResume()` method to `ClaudeRunner` that spawns Claude with `--resume <session-id> --dangerously-skip-permissions --output-format stream-json` and the same completion monitoring as existing methods
+3. In the task execution loop, when `--resume` is provided:
+   - Determine the current task (first task without a valid outcome)
+   - Call `runResume()` instead of the normal `run()`/`runVerbose()` method
+   - After the resumed task completes, clear the `--resume` flag so subsequent tasks use normal execution
+4. Handle edge cases: invalid session ID format, all tasks already complete, resumed session fails
+5. Write tests for the new `runResume()` method
+6. Write tests for the `--resume` flag integration in the do command
+
+## Acceptance Criteria
+- [ ] `raf do <project> --resume <session-id>` resumes the interrupted session
+- [ ] Claude is spawned with `--resume` flag and without prompt/model/system-prompt flags
+- [ ] Completion monitoring works the same as normal execution
+- [ ] After resumed task completes, subsequent tasks run normally
+- [ ] Works with `--worktree` mode
+- [ ] Clear user-facing message on resume start
+- [ ] Tests cover resume path
+
+## Notes
+- Claude CLI's `--resume` flag restores the full session context including the system prompt, so we must NOT pass those flags again (they may conflict or be rejected)
+- The `--resume` flag only applies to a single task — after it completes (or fails), remaining tasks use normal execution
+- Consider what happens if the user provides a session ID for a task that already completed — should gracefully handle this
+- Check Claude CLI docs/help to verify exact `--resume` flag syntax: `claude --resume <session-id>`

package/dist/commands/do.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"do.d.ts","sourceRoot":"","sources":["../../src/commands/do.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgDpC;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC;AAE3D;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,EAC1D,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,OAAO,GACf,MAAM,CAkBR;AA0BD,wBAAgB,eAAe,IAAI,OAAO,CAiBzC;AA0QD;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAuBhG"}
+{"version":3,"file":"do.d.ts","sourceRoot":"","sources":["../../src/commands/do.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiDpC;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC;AAE3D;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,EAC1D,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,OAAO,GACf,MAAM,CAkBR;AA0BD,wBAAgB,eAAe,IAAI,OAAO,CAkBzC;AAsSD;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAuBhG"}

package/dist/commands/do.js

@@ -18,7 +18,7 @@ import { createStatusLine } from '../utils/status-line.js';
 import { formatProjectHeader, formatSummary, formatTaskProgress, } from '../utils/terminal-symbols.js';
 import { deriveProjectState, discoverProjects, getNextExecutableTask, getDerivedStats, getDerivedStatsForTasks, isProjectComplete, hasProjectFailed, parseOutcomeStatus, } from '../core/state-derivation.js';
 import { analyzeFailure } from '../core/failure-analyzer.js';
-import { getRepoRoot, getRepoBasename, getCurrentBranch, computeWorktreePath, computeWorktreeBaseDir, validateWorktree, listWorktreeProjects, mergeWorktreeBranch, removeWorktree, } from '../core/worktree.js';
+import { getRepoRoot, getRepoBasename, getCurrentBranch, computeWorktreePath, computeWorktreeBaseDir, validateWorktree, listWorktreeProjects, mergeWorktreeBranch, removeWorktree, resolveWorktreeProjectByIdentifier, } from '../core/worktree.js';
 import { createPullRequest, prPreflight } from '../core/pull-request.js';
 /**
  * Format failure history for console output.
@@ -52,6 +52,7 @@ export function createDoCommand() {
         .option('-m, --model <name>', 'Claude model to use (sonnet, haiku, opus)')
         .option('--sonnet', 'Use Sonnet model (shorthand for --model sonnet)')
         .option('-w, --worktree', 'Execute tasks in a git worktree')
+        .option('-r, --resume <session-id>', 'Resume an interrupted Claude session')
         .action(async (project, options) => {
         await runDoCommand(project, options);
     });
@@ -212,23 +213,45 @@ async function runDoCommand(projectIdentifierArg, options) {
         }
     }
     else {
-        // Standard mode: resolve from main repo
-        const result = resolveProjectIdentifierWithDetails(rafDir, projectIdentifier);
-        if (!result.path) {
-            if (result.error === 'ambiguous' && result.matches) {
-                const matchList = result.matches
-                    .map((m) => `  - ${m.folder}`)
-                    .join('\n');
-                logger.error(`${projectIdentifier}: Ambiguous project name. Multiple projects match:\n${matchList}\nPlease specify the project ID or full folder name.`);
+        // Standard mode: check worktrees first (worktree takes priority), then main repo
+        const repoRoot = getRepoRoot();
+        const repoBasename = repoRoot ? getRepoBasename() : null;
+        // Try worktree resolution first (preferred when project exists in both)
+        if (repoBasename) {
+            const wtResolution = resolveWorktreeProjectByIdentifier(repoBasename, projectIdentifier);
+            if (wtResolution) {
+                const rafRelativePath = path.relative(repoRoot, rafDir);
+                const wtRafDir = path.join(wtResolution.worktreeRoot, rafRelativePath);
+                const wtProjectPath = path.join(wtRafDir, wtResolution.folder);
+                if (fs.existsSync(wtProjectPath)) {
+                    // Auto-switch to worktree mode
+                    worktreeMode = true;
+                    worktreeRoot = wtResolution.worktreeRoot;
+                    originalBranch = getCurrentBranch() ?? undefined;
+                    const projectName = extractProjectName(wtResolution.folder) ?? projectIdentifier;
+                    resolvedProject = { identifier: projectIdentifier, path: wtProjectPath, name: projectName };
+                }
             }
-            else {
-                logger.error(`${projectIdentifier}: Project not found`);
+        }
+        // Fall back to main repo if worktree didn't match
+        if (!resolvedProject) {
+            const result = resolveProjectIdentifierWithDetails(rafDir, projectIdentifier);
+            if (!result.path) {
+                if (result.error === 'ambiguous' && result.matches) {
+                    const matchList = result.matches
+                        .map((m) => `  - ${m.folder}`)
+                        .join('\n');
+                    logger.error(`${projectIdentifier}: Ambiguous project name. Multiple projects match:\n${matchList}\nPlease specify the project ID or full folder name.`);
+                }
+                else {
+                    logger.error(`${projectIdentifier}: Project not found`);
+                }
+                logger.info("Run 'raf status' to see available projects.");
+                process.exit(1);
             }
-            logger.info("Run 'raf status' to see available projects.");
-            process.exit(1);
+            const projectName = extractProjectName(result.path) ?? projectIdentifier;
+            resolvedProject = { identifier: projectIdentifier, path: result.path, name: projectName };
         }
-        const projectName = extractProjectName(result.path) ?? projectIdentifier;
-        resolvedProject = { identifier: projectIdentifier, path: result.path, name: projectName };
     }
     // Get configuration
     const config = getConfig();
@@ -236,6 +259,7 @@ async function runDoCommand(projectIdentifierArg, options) {
     const verbose = options.verbose ?? false;
     const debug = options.debug ?? false;
     const force = options.force ?? false;
+    const resumeSessionId = options.resume;
     const maxRetries = config.maxRetries;
     const autoCommit = config.autoCommit;
     // Configure logger
@@ -267,6 +291,7 @@ async function runDoCommand(projectIdentifierArg, options) {
             showModel: true,
             model,
             worktreeCwd: worktreeRoot,
+            resumeSessionId,
         });
     }
     catch (error) {
@@ -482,7 +507,8 @@ async function discoverAndPickWorktreeProject(repoBasename, rafDir, rafRelativeP
     }
 }
 async function executeSingleProject(projectPath, projectName, options) {
-    const { timeout, verbose, debug, force, maxRetries, autoCommit, showModel, model, worktreeCwd } = options;
+    const { timeout, verbose, debug, force, maxRetries, autoCommit, showModel, model, worktreeCwd, resumeSessionId } = options;
+    let activeResumeSessionId = resumeSessionId;
     if (!validatePlansExist(projectPath)) {
         return {
             projectName,
@@ -653,7 +679,10 @@ async function executeSingleProject(projectPath, projectName, options) {
             const taskContext = `[Task ${taskNumber}/${totalTasks}: ${displayName}]`;
             logger.setContext(taskContext);
             // Log task execution status
-            if (task.status === 'failed') {
+            if (activeResumeSessionId) {
+                logger.info(`Resuming task ${taskLabel} with session ${activeResumeSessionId}`);
+            }
+            else if (task.status === 'failed') {
                 logger.info(`Retrying task ${taskLabel} (previously failed)...`);
             }
             else if (task.status === 'completed' && force) {
@@ -663,6 +692,9 @@ async function executeSingleProject(projectPath, projectName, options) {
                 logger.info(`Executing task ${taskLabel}...`);
             }
         }
+        else if (activeResumeSessionId) {
+            logger.info(`Resuming task ${task.id} with session ${activeResumeSessionId}`);
+        }
         // Get previous outcomes for context
         const previousOutcomes = projectManager.readOutcomes(projectPath);
         // Get dependency outcomes - filter to only include outcomes for tasks this task depends on
@@ -721,9 +753,16 @@ async function executeSingleProject(projectPath, projectName, options) {
                 outcomeFilePath,
             } : undefined;
             // Run Claude (use worktree root as cwd if in worktree mode)
-            const result = verbose
-                ? await claudeRunner.runVerbose(prompt, { timeout, outcomeFilePath, commitContext, cwd: worktreeCwd })
-                : await claudeRunner.run(prompt, { timeout, outcomeFilePath, commitContext, cwd: worktreeCwd });
+            let result;
+            if (activeResumeSessionId && attempts === 1) {
+                // Resume mode: use --resume flag instead of normal prompt execution
+                result = await claudeRunner.runResume(activeResumeSessionId, { timeout, outcomeFilePath, commitContext, cwd: worktreeCwd, effortLevel: 'medium' });
+            }
+            else {
+                result = verbose
+                    ? await claudeRunner.runVerbose(prompt, { timeout, outcomeFilePath, commitContext, cwd: worktreeCwd, effortLevel: 'medium' })
+                    : await claudeRunner.run(prompt, { timeout, outcomeFilePath, commitContext, cwd: worktreeCwd, effortLevel: 'medium' });
+            }
             lastOutput = result.output;
             // Parse result
             const parsed = parseOutput(result.output);
@@ -877,6 +916,8 @@ ${stashName ? `- Stash: ${stashName}` : ''}
         if (verbose) {
             logger.newline();
         }
+        // Clear resume flag after first task — subsequent tasks use normal execution
+        activeResumeSessionId = undefined;
         // Clear context before next task
         logger.clearContext();
         // Re-derive state to get updated task statuses