[BUG] /background mid-turn silently drops the in-flight turn in the forked bg session

One thing that would help here is making the forked bg session carry an explicit turn handoff record, not just a session clone. If the turn ID and last streaming offset were persisted before the background fork, the UI could show background turn continues instead of silently losing the in-flight work. That kind of receipt also gives users a way to trust background mode on long tasks.

Fix: /background Mid-Turn Silently Drops In-Flight Turn in Forked BG Session

Issue: anthropics/claude-code #62118
Severity: High — silent data/work loss on a core workflow
Labels: bug, has repro, area:agent-view, platform:macos
Affected Version: 2.1.150+ (likely earlier)

---

1. Root Cause Analysis

1.1 Symptom

When /background (or /bg) is invoked while a turn is still in flight (Claude is actively streaming or executing tool calls), two things happen:

1. The foreground claude process exits cleanly with the "Session backgrounded" message.
2. The backgrounded session, when reattached via Agent View, shows the user's message but no processing is happening — the in-flight assistant turn is silently dropped. The session is idle, and the user must manually re-send the message.

1.2 Architecture Context

From the CHANGELOG and issue description, claude-code's /background command works as follows:

• The foreground session forks its state (transcript, working directory, MCP connections, permissions) into a background daemon process.
• The daemon persists the session to disk (transcript files, session metadata).
• The foreground process exits, freeing the terminal.
• The user can later reattach to the session via claude agents (Agent View / FleetView).

1.3 Root Cause

The /background handler does not account for the in-flight turn state. When the command fires mid-turn:

+-------------------------------------------------------------+
|  Foreground Session State (mid-turn)                        |
|                                                             |
|  User Message: "Analyze the auth module"                    |
|  Assistant Turn: [STREAMING ------------------------]       |
|    + ToolCall: Read("src/auth.ts")                          |
|    + ToolResult: (received)                                 |
|    + ToolCall: Grep("password", "src/")                     |
|    + [still generating...]                                  |
|                                                             |
|  In-memory state:                                           |
|    - currentTurnId = "turn_abc123"                          |
|    - streamingOffset = 847                                  |
|    - pendingToolCalls = [Grep("password", "src/")]          |
|    - apiStreamHandle = <active SSE connection>              |
+-------------------------------------------------------------+
                          |
                    /background
                          |
                          v
+-------------------------------------------------------------+
|  What Gets Forked (current behavior - BUGGY)                |
|                                                             |
|  + Transcript up to last completed assistant message        |
|  + Working directory, MCP config, permissions               |
|  - In-flight turn state (currentTurnId, streamingOffset,    |
|       pendingToolCalls, apiStreamHandle) - NOT PERSISTED    |
|  - API stream connection - TERMINATED with foreground exit  |
|                                                             |
|  Result: BG session has user message but no assistant       |
|  response. The turn that was running is lost.               |
+-------------------------------------------------------------+

The critical gap is that the turn handoff is incomplete. The fork clones the session transcript but does not:

1. Persist the in-flight turn metadata (turn ID, streaming offset, pending tool calls).
2. Resume or replay the turn in the background daemon.
3. Signal to the BG session that a turn is expected to continue.

1.4 Why This Happens

The /background command handler likely follows this flow:

/background handler:
  1. Capture session metadata (cwd, transcript path, MCP servers)
  2. Spawn background daemon with captured metadata
  3. Wait for daemon to acknowledge
  4. Exit foreground process

Step 1 does not include the active turn state. The daemon starts with a transcript that ends at the last completed assistant message (or at the user message if no assistant response was written yet). Since the daemon has no record of an in-flight turn, it starts in an idle state.

---

2. Step-by-Step Fix Approach

2.1 Fix Strategy: Two Options

The issue suggests two valid approaches. We recommend Option A (resume the turn) as the primary fix, with Option B (block mid-turn) as a defensive fallback.

Option A: Resume the In-Flight Turn in the BG Session (Preferred)

Persist the turn handoff state before forking, and have the background daemon resume the turn automatically.

Option B: Block /background While a Turn Is In Flight (Defensive)

Reject the command with a clear message if a turn is active, preventing data loss.

2.2 Option A Implementation - Turn Handoff Protocol

Step 1: Define the Turn Handoff Record

Add a new data structure to capture the in-flight turn state:

interface TurnHandoffRecord {
  /** Unique ID of the turn that was in flight */
  turnId: string;
  /** Byte/character offset in the streaming response at time of fork */
  streamingOffset: number;
  /** Partial assistant message content accumulated so far */
  partialContent: Array<
    | { type: "text"; text: string }
    | { type: "thinking"; thinking: string }
    | { type: "tool_use"; id: string; name: string; input: unknown }
  >;
  /** Tool results that have been received but not yet fed back to the model */
  pendingToolResults: Array<{
    toolUseId: string;
    content: string;
    isError: boolean;
  }>;
  /** Tool calls that were issued but haven't completed */
  pendingToolCalls: Array<{
    id: string;
    name: string;
    input: unknown;
  }>;
  /** Timestamp when the turn started (for timeout/retry logic) */
  turnStartedAt: number;
  /** Model ID that was processing the turn */
  modelId: string;
}

Step 2: Persist the Handoff Record Before Fork

Modify the /background command handler to capture and persist the handoff record:

// In the /background command handler
async function handleBackgroundCommand(session: Session, args: string[]) {
  // Capture in-flight turn state BEFORE forking
  const activeTurn = session.getActiveTurn();
  let handoffRecord: TurnHandoffRecord | null = null;

  if (activeTurn && activeTurn.state === "in-flight") {
    handoffRecord = {
      turnId: activeTurn.id,
      streamingOffset: activeTurn.streamingOffset,
      partialContent: activeTurn.getAccumulatedContent(),
      pendingToolResults: activeTurn.getPendingToolResults(),
      pendingToolCalls: activeTurn.getPendingToolCalls(),
      turnStartedAt: activeTurn.startedAt,
      modelId: session.model.id,
    };

    // Persist to disk so the daemon can read it
    const handoffPath = path.join(
      session.sessionDir,
      ".claude",
      "turn-handoff.json"
    );
    await fs.writeFile(handoffPath, JSON.stringify(handoffRecord, null, 2));
  }

  // Now proceed with the existing fork logic
  const daemon = await forkSessionToDaemon(session, {
    handoffRecord, // Pass to daemon for resumption
  });

  // ... rest of existing background logic ...
}

Step 3: Have the Daemon Resume the Turn

Modify the background daemon's startup logic to check for a handoff record and resume:

// In the background daemon initialization
async function initializeDaemonSession(sessionDir: string): Promise<Session> {
  const session = await loadSessionFromDisk(sessionDir);

  // Check for a pending turn handoff
  const handoffPath = path.join(sessionDir, ".claude", "turn-handoff.json");
  const handoffExists = await fs.access(handoffPath).then(() => true).catch(() => false);

  if (handoffExists) {
    const handoff: TurnHandoffRecord = JSON.parse(
      await fs.readFile(handoffPath, "utf-8")
    );

    // Restore the partial assistant message to the transcript
    session.transcript.appendAssistantMessage(handoff.partialContent, {
      turnId: handoff.turnId,
      isResumed: true,
    });

    // If there are pending tool calls, replay them
    for (const toolCall of handoff.pendingToolCalls) {
      await session.executeToolCall(toolCall);
    }

    // If there are pending tool results, feed them back to the model
    for (const toolResult of handoff.pendingToolResults) {
      await session.feedToolResult(toolResult);
    }

    // Resume the API stream from where it left off
    if (handoff.partialContent.length > 0 && handoff.pendingToolCalls.length === 0) {
      // No pending tools - resume generation
      await session.resumeGeneration({
        modelId: handoff.modelId,
        turnId: handoff.turnId,
        resumeFromOffset: handoff.streamingOffset,
      });
    }

    // Clean up the handoff file after successful resume
    await fs.unlink(handoffPath);
  }

  return session;
}

Step 4: Add UI Indicators in Agent View

Show the user that a turn is being resumed:

// In Agent View / FleetView rendering
function renderSessionStatus(session: Session): string {
  if (session.turnHandoffPending) {
    return `Background turn continues... (turn ${session.handoff.turnId})`;
  }
  if (session.isRunning) {
    return `Running`;
  }
  return `Idle`;
}

2.3 Option B Implementation - Block Mid-Turn Backgrounding (Fallback)

As a defensive measure, also implement a guard that blocks /background when a turn is active:

async function handleBackgroundCommand(session: Session, args: string[]) {
  const activeTurn = session.getActiveTurn();

  if (activeTurn && activeTurn.state === "in-flight") {
    // Option B: Block and inform the user
    session.ui.write(
      chalk.yellow(
        "Cannot background while a turn is in flight.\n" +
        "  Wait for Claude to finish processing, then run /background again.\n" +
        "  (Alternatively, press Esc to cancel the current turn first.)"
      )
    );
    return; // Don't proceed with forking
  }

  // ... proceed with existing background logic ...
}

2.4 Recommended Approach: Combine A + B

Implement Option A as the primary fix with Option B as a timeout fallback:

1. Attempt to persist the handoff record and resume the turn (Option A).
2. If the handoff persistence fails (disk full, permission error), fall back to blocking with a clear error (Option B).
3. Add a configurable timeout: if the daemon doesn't acknowledge the handoff within N seconds, the foreground exits with a warning rather than silently dropping.

async function handleBackgroundCommand(session: Session, args: string[]) {
  const activeTurn = session.getActiveTurn();

  if (activeTurn && activeTurn.state === "in-flight") {
    const handoff = captureTurnHandoff(activeTurn, session);

    try {
      // Attempt Option A: persist and resume
      await persistHandoff(handoff, session.sessionDir);
    } catch (err) {
      // Fallback to Option B: block with error
      session.ui.write(
        chalk.red(`Failed to persist turn state: ${err.message}\n`) +
        chalk.yellow("  Backgrounding blocked to prevent work loss.\n" +
        "  Wait for the current turn to finish, then try again.")
      );
      return;
    }

    // Fork with handoff, wait for daemon acknowledgment
    const daemonAck = await forkSessionToDaemon(session, { handoff });

    if (!daemonAck) {
      session.ui.write(
        chalk.yellow("Daemon did not acknowledge turn handoff.\n" +
        "  The in-flight turn may be lost. Consider re-sending your message.")
      );
    }
  }

  // ... proceed with existing background logic ...
}

---

3. Testing Strategy

3.1 Unit Tests

| Test | Description | Expected |
|------|-------------|----------|
| turn-handoff-capture | Capture handoff record during active streaming | All fields populated correctly |
| turn-handoff-persist | Write handoff record to disk | File exists, valid JSON |
| turn-handoff-restore | Daemon loads handoff and resumes turn | Partial content restored, tools replayed |
| turn-handoff-empty | No active turn at background time | No handoff record created |
| turn-handoff-tool-results | Handoff with pending tool results | Results fed back to model |
| turn-handoff-persist-fail | Disk write fails during handoff | Falls back to blocking |
| turn-handoff-daemon-timeout | Daemon doesn't acknowledge | Warning shown, foreground exits |

3.2 Integration Tests

| Test | Steps | Expected |
|------|-------|----------|
| bg-mid-turn-resume | 1. Start session, send message 2. /background mid-stream 3. Reattach via Agent View | Turn resumes automatically, output continues |
| bg-mid-turn-with-tools | 1. Send message that triggers tool calls 2. /background mid-tool 3. Reattach | Tool calls complete, results visible |
| bg-mid-stream-only | 1. Send message 2. /background during text streaming (no tools) 3. Reattach | Text generation resumes from offset |
| bg-blocked-mid-turn-fallback | 1. Mock disk write failure 2. Send message, /background mid-turn | Command blocked with clear error message |
| bg-idle-turn-no-op | 1. Send message, wait for completion 2. /background at idle prompt | Normal background (no handoff needed) |

3.3 Manual Reproduction (from the issue)

1. Launch `claude` fresh (no `-r`, no `-w`).
2. Send your first message - Claude starts processing the turn.
3. While the turn is still streaming, run `/background` (no argument).
4. `claude` exits immediately. (expected)
5. Start `claude` again and open Agent View (`claude agents`).
6. Open the backgrounded session.

BEFORE FIX: Session is idle, user message visible but no processing.
AFTER FIX:  Session shows "Background turn continues..." and processing resumes.

3.4 Regression Tests

Ensure existing /background behavior is preserved:

• Backgrounding at an idle prompt works as before
• Backgrounding after a completed turn works as before
• Session metadata (cwd, MCP, permissions) is preserved
• Agent View shows correct session status

---

4. Impact Assessment

4.1 User Impact

| Severity | Description |
|----------|-------------|
| High | Users lose in-progress work when they background mid-turn. This is silent - no error, no warning. The user must re-type or re-send their message. |
| Frequency | Likely common - /background is a natural action to take when Claude starts a long-running task, and users won't wait for it to complete before backgrounding. |
| Data Loss | The user message is preserved, but the assistant's partial response (including any tool calls and results) is lost. For long tasks, this could mean minutes of work. |

4.2 Code Impact

| Area | Risk | Mitigation |
|------|------|------------|
| /background handler | Low - additive change, existing flow preserved | Feature flag / config toggle |
| Daemon initialization | Medium - new code path for handoff resume | Extensive integration tests |
| Transcript persistence | Low - handoff record is separate from transcript | Atomic file writes |
| Agent View UI | Low - new status indicator, existing rendering unchanged | Visual regression tests |

4.3 Edge Cases

1. Disk full during handoff write: Falls back to blocking (Option B).
2. Daemon crashes before acknowledging handoff: Foreground shows warning; handoff file persists for retry on next attach.
3. Multiple /background calls in rapid succession: Handoff file is locked; second call blocked.
4. Turn in-flight but no content yet (just started): Handoff record has empty partial content; daemon starts fresh turn.
5. Session compaction mid-turn: Handoff captures pre-compact state; daemon resumes from there.

4.4 Performance Impact

• Negligible - the handoff record is a small JSON file (typically < 10KB).
• The daemon's resume logic adds ~50-200ms of startup overhead for the handoff case.
• No impact on the common path (backgrounding at idle prompt).

4.5 Security Considerations

• The handoff file is written to the session directory (.claude/turn-handoff.json) with the same permissions as other session files.
• No new network calls or external dependencies.
• The handoff record contains only session-internal state (turn ID, partial content, tool calls) - no secrets or credentials.

---

5. Files to Modify

Based on the claude-code architecture (inferred from changelog and public interface):

| File (inferred path) | Change |
|----------------------|--------|
| src/commands/background.ts | Add turn handoff capture and Option B guard |
| src/session/turn-handoff.ts | New - TurnHandoffRecord type, capture/persist/restore functions |
| src/daemon/session-init.ts | Add handoff detection and turn resume logic |
| src/ui/agent-view/status.ts | Add "Background turn continues..." indicator |
| src/transcript/transcript.ts | Support isResumed flag on assistant messages |

---

6. Summary

The bug occurs because /background forks the session transcript but does not persist or transfer the in-flight turn state (partial assistant content, pending tool calls/results, streaming offset). The background daemon starts with a transcript that ends at the user message, with no record of the turn that was running.

The fix introduces a turn handoff protocol:

1. Before forking, capture the active turn's state into a TurnHandoffRecord.
2. Persist the record to disk.
3. The background daemon detects the handoff record and resumes the turn.
4. As a fallback, block /background if handoff persistence fails.

This ensures zero work loss when users background mid-turn, while maintaining backward compatibility with the existing idle-prompt backgrounding flow.

Addressed by a merged fix. Please reopen with a fresh repro if you still see this on a current version.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.