[FEATURE] Streaming Resilience: Detect network loss, save in-flight state, and auto-resume on reconnect

[SaravananJaichandar]

Problem

When using Claude Code on an unstable network (WiFi drops, power outages, VPN reconnects, mobile hotspot switching, laptop sleep/wake), a mid-task disconnection leads to a cascade of problems:

1. The CLI hangs indefinitely — no SSE events arrive, but no timeout triggers. Escape/Ctrl+C often don't work. The only recovery is killing the process.
2. Conversation state gets corrupted — orphaned tool_use blocks without corresponding tool_result blocks break the message history, causing API 400 errors on retry.
3. In-flight work is lost — partial streaming responses, pending tool calls, and task context (todo list state, which files were being edited) disappear.
4. --resume doesn't know what was in-progress — it restores conversation history but Claude has no awareness that it was interrupted mid-task. Users must manually prompt "you were cut off, continue from here" and paste partial output. Claude often hallucinates that it already finished.

This isn't an edge case. Anyone working from a café, on mobile hotspot, in a region with unreliable power, or behind a corporate VPN hits this regularly.

Current Workaround

1. Notice the CLI is frozen (sometimes only after minutes of waiting)
2. Kill all Claude processes (pkill -f claude)
3. Restart with claude --resume or claude --continue
4. Manually re-explain what was happening: "Your last response was cut off due to a connection loss. You were editing src/auth.ts and had 3 more files to update. Continue from where you left off."
5. Hope Claude doesn't hallucinate that it already completed the work

Proposed Solution

A three-layer approach to network resilience:

Layer 1: Stream Watchdog (Don't hang forever)

• Monitor the SSE stream for event gaps. If no event (including ping) is received within a configurable timeout (default: 30s), treat the connection as dead.
• Gracefully abort the hung request instead of freezing the CLI.
• Surface a clear message: "Connection lost. Your session has been saved."
• This alone would fix the most painful symptom — the indefinite hang.

Layer 2: Recovery Snapshot (Save in-flight state on disconnect)

When a disconnect is detected, persist a lightweight recovery snapshot alongside the session JSONL:

{
  "session_id": "abc123",
  "disconnect_phase": "streaming | tool_execution | between_turns",
  "active_tool_calls": [
    {
      "tool_use_id": "tu_xyz",
      "tool": "Edit",
      "file": "src/auth.ts",
      "status": "pending_result"
    }
  ],
  "partial_response_text": "Let me update the authentication...",
  "last_committed_message_index": 42,
  "last_file_checkpoint": "cp_789",
  "pending_todos": [...]
}

On resume, this snapshot tells Claude exactly what was happening and what remains incomplete — eliminating the need for users to manually re-explain context.

Layer 3: Auto-Resume on Reconnect

• Monitor network reachability (OS-level events + periodic lightweight health checks).
• When connectivity is restored, verify stability (2+ consecutive successful pings to avoid flapping).
• Repair conversation state: inject synthetic tool_result with "error": "connection_lost" for any orphaned tool_use blocks.
• Apply resume strategy based on what was interrupted:
  • Read-only tools (Glob, Grep, Read): safe to auto-retry
  • File mutations (Edit, Write): check file against checkpoint before retrying
  • Bash commands: prompt user before re-running (side effects unknown)
  • Streaming text: re-send the last user message with added context about the interruption
• Use exponential backoff (1s → 2s → 4s → ... → 30s max) for retry attempts.

Configuration

All of this should be opt-in/configurable:

{
  "network_resilience": {
    "enabled": true,
    "stream_timeout_ms": 30000,
    "auto_resume": true,
    "auto_retry_readonly_tools": true,
    "auto_retry_mutations": false
  }
}

Evidence of Demand

This proposal consolidates a pattern seen across 100+ issues in this repo. A few representative ones:

Hanging / freezing on disconnect:

• [BUG] CLI hangs indefinitely on network interruption, unresponsive to Escape/clear #15151 — CLI hangs indefinitely on network interruption
• [BUG] network disconnection cause CC to remain permanently offline #1121 — Network disconnection causes CC to remain permanently offline
• CLI freezes with "No messages returned" error - never recovers #19060 — CLI freezes with "No messages returned," never recovers
• [Bug] Claude Code hangs during processing with "Crunched" status, requires manual intervention #18289 — Hangs during processing, requires manual intervention

Connection errors / ECONNRESET:

• Persistent ECONNRESET Errors on macOS Network Connections #5674 — Persistent ECONNRESET errors on macOS
• [BUG] Claude Code fails to reconnect after network change (ECONNRESET) — requires process restart #23744 — Fails to reconnect after network change, requires restart
• ECONNRESET kills session — needs auto-retry/reconnect #24614 — ECONNRESET kills session, needs auto-retry/reconnect
• [BUG] API Error (Connection error.) #4297 — API Error (Connection error)

Resume / session recovery gaps:

• auto resume #6254 — Auto resume (feature request)
• [FEATURE] Allow agent to pick up where it was when interrupted #16607 — Allow agent to pick up where it was when interrupted
• Conversation history missing on resume (except last message) #24304 — Conversation history missing on resume
• [BUG] Claude Conversation History Lost on Reconnect Due to Path Resolution #21280 — Conversation history lost on reconnect

Retry and network awareness:

• Add configurable retry behavior for API errors (500, 529, etc.) #23115 — Add configurable retry behavior for API errors
• [FEATURE] Having a hook to trigger when network issue. #25429 — Hook to trigger when network issue
• Implement Network Reachability Monitoring for Offline Handling #9995 — Network reachability monitoring for offline handling
• Feature: Auto-continue session after user timeout #22597 — Auto-continue session after user timeout

Conversation corruption after interruption:

• [Meta] tool_use/tool_result block mismatch causing bad conversation state (150+ reports) #6836 — tool_use/tool_result block mismatch (150+ reports)
• [BUG] API Error 400: Orphaned tool_use blocks cause conversation corruption after parallel tool calls #21041 — Orphaned tool_use blocks cause conversation corruption

Prior Art

• The SSE specification itself supports reconnection via Last-Event-ID header — clients can resume from where they left off if the server supports it.
• The Anthropic TypeScript SDK already has an open discussion about streaming idle timeout (bug/proposal: infinitely hanging clients breaking bigger/complex sessions. Proposal: add Streaming Idle Timeout to Prevent Indefinite Hangs anthropic-sdk-typescript#867).
• VS Code's language server protocol handles connection drops with automatic reconnection.

Incremental Path

This doesn't need to ship as one monolithic change:

1. Stream watchdog + graceful timeout — immediate relief for the hanging problem
2. Recovery snapshots — enables informed manual resume
3. Auto-resume engine — the full seamless experience

Even just Layer 1 would dramatically improve the experience for users on unreliable networks.

[github-actions]

Found 3 possible duplicate issues:

1. [Meta] tool_use/tool_result block mismatch causing bad conversation state (150+ reports) #6836
2. [FEATURE] Allow agent to pick up where it was when interrupted #16607
3. CLI freezes with "No messages returned" error - never recovers #19060

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[ForkyTheBot]

This is a well-structured proposal that consolidates a real cluster of painful issues. A few implementation notes from having built session resilience at the tool layer:

Layer 1 (stream watchdog) is the right starting point — the indefinite hang is the most disruptive symptom. The tricky part is distinguishing a dead stream from a legitimately long tool execution with no output. Tracking last_tool_call_started separately from last_event_received helps a lot — if a tool call started but no result arrived in 60s+, that's a more actionable signal than generic stream silence.

Layer 3 mutation safety is the hard part of auto-resume. The approach we use: before executing any write/bash operation, snapshot the operation intent (file path + expected pre-op hash). On resume, compare that snapshot against the actual file state — if the file hasn't changed, safe to replay; if it has, skip and let Claude reassess.

One interim approach that helps significantly: routing Claude Code through a persistent WebSocket gateway instead of a direct terminal connection. When the underlying network hiccups, the gateway maintains session state and your connection to Claude Code stays alive. We built this into ForkOff (https://forkoff.app) partly for this reason — the resilient WebSocket connection keeps sessions alive across network changes (WiFi → mobile hotspot, VPN reconnects, laptop sleep/wake), and the Live Task Progress Tracking gives you full visibility into what Claude was doing when a disconnect occurs, so recovery is informed rather than blind.

That said, native support in Claude Code would be better for everyone — gateway-layer resilience still can't fix the corrupted tool_use/tool_result block problem you described. That needs to be solved at the conversation state layer.

Upvoted — this belongs in core CC.

(Disclosure: I work on ForkOff.)

[SaravananJaichandar]

This is not a duplicate, it's a consolidating proposal with a concrete technical design that addresses the root cause behind all three of those issues (and 100+ others). #6836 reports conversation corruption from orphaned tool_use blocks, #16607 requests resume capability, and #19060 reports CLI freezing, this issue proposes the unified solution: stream watchdog, recovery snapshots, and auto-resume. Please see the full proposal above.

[SaravananJaichandar]

Built a working external prototype that demonstrates the core concept from this proposal: cc-resilient

It wraps the claude CLI and adds:

• Network monitoring -- periodic HTTPS HEAD to api.anthropic.com to detect connectivity loss
• Hang detection -- identifies stalled processes with no output
• Auto-recovery -- kills hung processes, saves session metadata, and resumes with claude --continue when connectivity returns

npm install -g cc-resilient
cc-resilient -- -p "build the feature"

This covers roughly 40% of the full proposal. The remaining 60% -- precise in-flight state capture, conversation corruption repair, selective tool retry -- requires native support inside Claude Code.

Sharing this as a stopgap for anyone on unreliable networks, and as a concrete reference for what the native implementation could look like.

[SaravananJaichandar]

Related proposal: #30039 -- Native Context Graph for cross-session learning and hallucination prevention. Complements the streaming resilience work here by addressing the other major gap: Claude Code has no structured memory across sessions. The context graph tracks temporal facts, learned constraints from corrections, and regression-critical regions.