Proactive context management: topic-aware fork prompts and graceful overflow-to-file recovery

Problem

Context compaction threshold overshoot is a persistent, session-breaking problem across Claude Code versions. The current compaction model is reactive — it waits until the context window is already exhausted, then attempts emergency summarization. By that point, the session is frequently unrecoverable.

This is not a single bug but an architectural gap in how context lifecycle is managed. The existing issues document the symptoms extensively:

• Deadlock: /compact fails with "Conversation too long" precisely when it's needed (#23047, #19018, #26317, #24942)
• Misleading metrics: Token percentage only counts input tokens, so users see 20% used but hit the wall (#28167, #19553)
• Auto-compact doesn't fire: Multiple reports of auto-compaction simply never triggering (#29780, #24497, #27560)
• Data loss on compaction: Working knowledge destroyed (#29890), rules overridden by summary narrative (#27993), worktree state lost (#27907)
• Multi-agent amplification: Parallel agents returning simultaneously guarantee overflow on Windows (#25714, #26041)

What's missing is upstream prevention, not better downstream recovery.

Environment

• Claude Code: v2.1.63
• OS: Windows 11 Pro
• Model: Claude Opus 4.6
• Usage pattern: Heavy skill/rules loading (~96 skills), multi-agent workflows, long coding sessions with topic pivots

Proposal 1: Topic-Aware Fork/Clear Prompt

When: Claude detects a significant topic pivot mid-session (different file paths, different domain, different project) after sustained work on a previous topic.

Action: Surface a non-blocking prompt:

You've been working on [Topic X] for ~40 turns. Starting [Topic Y]?
  [1] Fork to new session (carries CLAUDE.md context, sheds Topic X state)
  [2] Continue here (Topic X context will be compacted if needed)
  [3] Dismiss

Why this helps:

• The #1 cause of compaction overshoot in real usage is topic drift — users finish one task, start another in the same session, and the accumulated context from Task A is dead weight that pushes Task B into the danger zone.
• Topic change is detectable: file-path divergence, semantic shift in prompts, different tool usage patterns.
• This is proactive compaction — shedding irrelevant context before hitting the wall, not after.

Implementation signals (heuristics, not exhaustive):

• Working directory change or file-path cluster shift
• No references to prior-topic files for N turns
• User explicitly says "now let's work on..." or "switching to..."
• Subagent work completes and user starts new manual task

Proposal 2: Graceful Overflow-to-File Recovery

When: Context limit is reached (auto-compact threshold exceeded).

Instead of the current behavior (prompt to restore to prior checkpoint, which discards work), do this:

1. Auto-serialize the overflow portion of the conversation to a session transcript file (e.g., .claude/overflow/session-{id}-{timestamp}.md)
2. Run compaction on the remaining context window
3. Inject a structured summary of the saved portion back into the session, preserving:

• Files modified (paths + what changed)
• Decisions made
• Blockers identified
• Current working state (branch, directory, task in progress)

1. Continue the session — no user intervention required

Why this helps:

• The current "restore to checkpoint" option destroys work. Users lose context they were actively using.
• The serialized file becomes a recovery artifact — if the compaction summary missed something critical, the user can reference the saved transcript.
• This is essentially what users are already doing manually (writing state to files, using PreCompact hooks to save context) — just automated and reliable.
• The structured summary is more useful than narrative summarization because it preserves actionable state (file paths, decisions, blockers) rather than a prose recap.

Proposal 3: Graduated Compaction Warnings (Supporting)

Three-stage warning system to give users agency before the emergency:

| Stage | Threshold | Action |
|-------|-----------|--------|
| Yellow | ~60% context | Status bar indicator: "Context filling. Good time to commit/checkpoint." |
| Orange | ~80% context | Non-blocking prompt: "Approaching limit. Auto-save triggered. Consider forking." |
| Red | ~95% context | Execute Proposal 2 automatically (overflow-to-file + compact + rejoin) |

Critical: These thresholds must account for all token types (input + output + thinking), not just input tokens (#28167).

Why These Are Not Duplicates

Existing issues focus on:

• Bugs: Deadlock (#23047), wrong token math (#28167), auto-compact not firing (#29780)
• Configuration: Configurable threshold (#25679, #28728)
• Partial solutions: Lossless cleanup before compaction (#27293), pre-compaction checkpoint dialog (#15405)

This proposal addresses the architectural model: moving from reactive emergency compaction to proactive lifecycle management. The three proposals work together:

1. Prevent unnecessary context accumulation (topic-aware forking)
2. Recover gracefully when limits are hit (overflow-to-file)
3. Warn progressively so users can act before the emergency (graduated warnings)

Additional Context

Power users with heavy configurations (many skills, rules files, multi-agent workflows) hit this disproportionately because their baseline context consumption is already high before any work begins (see #11045 for skills overflow). The proposals above help all users but are critical for this segment.