Uncontrolled background agent parallelization causes context overflow, session death, and wasted tokens

Bug Report: Uncontrolled background agent parallelization causes context overflow, session death, and wasted tokens

Environment

• Claude Code version: v2.1.39
• Model: Opus 4.6 (Claude Max subscription)
• OS: Windows 11 Pro 10.0.26200
• Date: 2026-02-14

Summary

When Claude Code launches many background agents (Task tool with run_in_background: true) in parallel, the returning results can overflow the context window. This kills the session with no recovery path, and the user pays for all tokens consumed by the agents — even though the results were never usable.

Steps to Reproduce

1. Start a Claude Code session and work on several tasks (building up context)
2. Ask Claude to document a large codebase comprehensively ("Document everything — theme, plugins, all files")
3. Claude launches 14 background agents (Explore subagent_type) in three waves (6 + 5 + 3)
4. All agents run in the background, each consuming tokens independently
5. Agents start completing and returning results
6. Context window fills up

What Happened

1. Claude launched 14 parallel background agents to explore different parts of the codebase
2. Each agent consumed significant tokens (e.g., "21 tool uses · 80.8k tokens · 1m 25s" for a single agent)
3. As agents completed, each return added to the context
4. After ~10 agents returned, the context was full
5. Every subsequent agent completion showed: Context limit reached · /compact or /clear to continue
6. Running /compact failed with: Error: Error during compaction: Error: Conversation too long. Press esc twice to go up a few messages and try again.
7. Session was completely dead — no further interaction possible
8. All tokens consumed by the 14 agents were billed to the user

Expected Behavior

1. Context budget awareness: Before launching N background agents, Claude Code should estimate whether the returning results will fit in the remaining context window. If not, it should launch fewer agents or process results incrementally.

1. Graceful degradation: When context is approaching limits, agent results should be summarized or truncated rather than causing a hard crash.

1. Compaction should always work: /compact failing with "Conversation too long" is a dead end. If the conversation is too long, that's exactly when compaction is needed most. This is a catch-22.

1. Token accountability: Tokens consumed by agents that cannot return results (because context is full) should not count against the user's quota, or at minimum the system should prevent this scenario.

1. Agent launch limits: There should be a configurable or automatic cap on concurrent background agents to prevent context overflow.

Impact

• Token waste: 14 agents × ~50-80k tokens each = significant token consumption with no usable output
• Lost session: User cannot continue working, must start a new session
• Lost context: All prior conversation context (including earlier productive work in the same session) is inaccessible
• User pays for system failure: The user's subscription quota is consumed by Claude's own architectural limitation, not by the user's actions

Workaround

None available. Once the context overflows:

• /compact fails
• /clear loses all context
• The only option is to start a new session

Suggested Fixes

1. Add a context budget check before launching background agents. Calculate: remaining_context - (estimated_agent_results × num_agents) > safety_margin
2. Implement streaming/incremental agent processing — process each agent's result before launching the next, or cap concurrent agents at 3-4
3. Fix /compact for oversized contexts — compaction should work especially when the context is too long, not fail because of it
4. Add a background agent limit — either hard cap or configurable setting (e.g., max_concurrent_agents: 4)
5. Implement result truncation — if an agent result would overflow context, summarize it automatically instead of crashing

Session Log

The full session transcript is available showing the exact sequence:

• 6 agents launched → 5 more agents launched → 3 more agents launched
• Agents completing with "Context limit reached" errors
• /compact failure
• Session death

Total productive time before crash: ~25 minutes of successful code changes, then ~11 minutes of documentation attempt that killed the session.

pip install cozempic
cozempic init

INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')
[[ "$TOOL" != "Agent" ]] && exit 0
MAX=${CC_MAX_SUBAGENTS:-5}
TRACKER="${HOME}/.claude/active-agents"
mkdir -p "$(dirname "$TRACKER")" 2>/dev/null
NOW=$(date +%s)
ACTIVE=0
if [ -f "$TRACKER" ]; then
    while IFS= read -r line; do
        TS=$(echo "$line" | cut -d'|' -f1)
        (( NOW - TS < 1800 )) && ACTIVE=$((ACTIVE + 1))
    done < "$TRACKER"
fi
if (( ACTIVE >= MAX )); then
    echo "BLOCKED: $ACTIVE subagents active (max: $MAX). Wait for completion." >&2
    exit 2
fi
echo "${NOW}|agent" >> "$TRACKER"
exit 0

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Agent",
      "hooks": [{"type": "command", "command": "bash ~/.claude/hooks/subagent-budget-guard.sh"}]
    }]
  }
}