Context Limit Reached error should auto-compact and queue user message instead of failing

Description

When running long sessions with multiple parallel background agents (Task tool with run_in_background: true), sending a user message (especially with a screenshot attachment) while agents are still running throws a "Context Limit Reached" error instead of gracefully handling it.

This is on a Max plan — not a billing or rate limit issue. The model's context window is exhausted by accumulated agent results.

Expected Behavior

1. User sends a message while agents are running
2. System detects context is near/at limit
3. System auto-compacts (summarizes prior messages)
4. User's message is queued and processed after compaction
5. Session continues seamlessly

Actual Behavior

1. User sends a message while agents are running
2. System throws "Context Limit Reached" error
3. User cannot send any further messages
4. /compact may also fail with the same error
5. Only option is /clear — which loses all conversation history, agent results, and work in progress

Reproduction Steps

1. Start a Claude Code session (Opus 4.6, Max plan)
2. Launch 4-6 parallel background agents using the Task tool (e.g., SEO audit with 6 specialist subagents)
3. While agents are running and returning results, send a new user message with a screenshot attachment
4. Observe "Context Limit Reached" error

Root Cause Analysis

From investigating a crashed session (46MB JSONL transcript):

• 274 user messages averaging 164KB each
• 12 messages over 1MB, 39 over 100KB
• 97.5% of context came from subagent results returned as user messages
• The Task tool returns agent output as user-visible messages, which accumulate rapidly

Impact

• Loss of work: Hours of multi-agent analysis lost when /clear is the only recovery
• No recovery path: /compact fails with the same error, creating a dead-end state
• Session state destroyed: TaskList, agent results, conversation history — all gone
• Workaround burden on users: Must manually track when to /compact, which defeats the purpose of autonomous agent workflows

Suggested Solutions

Priority 1: Graceful degradation

When context limit is approaching:

• Auto-trigger compaction before the hard limit is hit
• Queue the user's pending message
• Process the queued message after compaction succeeds

Priority 2: Pre-emptive compaction

• Add a threshold (e.g., 80% of context window) that triggers automatic compaction
• Or add a hook event like PreContextLimit that fires before the hard limit

Priority 3: Agent result management

• Task tool results from background agents should not expand into full user messages
• Consider: agent results as compressible system messages, or file-based result passing where agents write to disk and parent reads files

Current Workarounds

We've implemented partial mitigations via hooks and CLAUDE.md instructions:

• SubagentStop hook reminds to /compact after agent work
• PreCompact hook preserves critical context
• All custom skills use file-based result passing (agents write to files, return only brief summaries)
• But none of these prevent the hard crash when a user message arrives during heavy agent work

Environment

• Plan: Claude Max (Opus 4.6)
• Platform: macOS (Darwin 25.2.0)
• Claude Code version: Latest as of Feb 2026
• Model: claude-opus-4-6