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.