[BUG] JavaScript heap exhaustion (OOM crash) during heavy Task tool/agent usage

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Environment

• Claude Code Version: 2.0.76
• Model: Opus 4.5 (Claude Max subscription)
• Platform: Windows 11 (MSYS_NT-10.0-26200 3.5.7-463ebcdc.x86_64)
• Shell: Git Bash (MSYS2)

Description

Claude Code consistently crashes with JavaScript heap exhaustion during sessions involving heavy use of the Task tool (subagent spawning). The issue has persisted for several weeks across multiple Claude Code versions.

Crash Output

<--- JS stacktrace --->
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Heap metrics at crash:
- Heap: 16125.4 MB used, 16438.5 MB limit
- GC efficiency: average mu = 0.102, current mu = 0.006
- GC time: 23,259.76 ms spent on garbage collection

Steps to Reproduce

1. Start a Claude Code session
2. Use the Task tool to spawn multiple agents (subagent_type parameter)
3. Have agents perform complex tasks (20+ tool uses, returning large context)
4. Spawn agents in parallel (multiple Task calls in single message)
5. Continue for 30-60 minutes with sustained agent usage
6. Session crashes with heap exhaustion

Evidence from Debug Analysis

I analyzed my .claude/debug/ directory containing 766 session debug files totaling 343 MB:

| Metric | Value | Notes |
|--------|-------|-------|
| Largest session file | 49.5 MB | Single session debug log |
| Agent spawns in largest | 626 | Task tool invocations |
| Sessions > 5 MB | 12 | High-risk for crash |

Observed Pattern

The mu value (GC mutator utilization) dropping to 0.006 indicates garbage collection is reclaiming virtually no memory, suggesting strong references are preventing cleanup.

Each spawned agent appears to retain its full context in memory after completion. When agents complete, context is NOT garbage collected. Parallel agent spawning multiplies memory pressure.

Suspected Root Cause

Agent context (conversation history + tool outputs) appears to be retained in memory after agent completion:

1. Each spawned agent holds its full context in memory
2. When agents complete, context is NOT garbage collected
3. Parallel agent spawning multiplies memory pressure
4. Agents returning large outputs (47k+ tokens) cause significant retention

Questions for Engineering

1. Is agent context intentionally retained (for resume capability), and if so, is there a limit?
2. Are there strong references in the agent management system preventing GC?
3. Is there a maximum recommended number of agents per session?

Workarounds Attempted

• Starting fresh sessions frequently (helps but disruptive)
• Sequential instead of parallel agent spawning (reduces peak memory)
• Smaller agent task scopes (conflicts with workflow)

Impact

• Sessions crash mid-task, losing context and progress
• Unable to complete complex multi-component development tasks
• Significantly impacts productivity for power users

What Should Happen?

When agents spawned via the Task tool complete their work, their context should be released from memory and garbage collected. Sessions should be able to run indefinitely with heavy agent usage without memory exhaustion, as long as agents are completing (not running concurrently in unbounded numbers).

Specifically:

1. Agent context should be garbage collected after agent completion
2. GC efficiency (mu) should remain healthy (>50%) during normal operation
3. Memory should stabilize, not grow linearly with cumulative agent spawns
4. Parallel agent spawning should only increase memory during concurrent execution, not permanently

Error Messages/Logs

<--- JS stacktrace --->
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Memory metrics at crash:
- Heap: 16125.4 (16438.5) MB
- pooled: 0 MB
- GC time: 23259.76 / 0.00 ms
- average mu = 0.102, current mu = 0.006
- allocation failure; scavenge might not succeed

----- Native stack trace -----
 1: 00007FF7939BA2ED node::SetCppgcReference+17725
 2: 00007FF793921EA8 v8::base::CPU::num_virtual_address_bits+92328
 3: 00007FF7944A2EE1 v8::Isolate::ReportExternalAllocationLimitReached+65
 4: 00007FF79448FB66 v8::Function::Experimental_IsNopFunction+2870
 5: 00007FF7942DCDC0 v8::internal::StrongRootAllocatorBase::StrongRootAllocatorBase+31456
 6: 00007FF7942D9E2A v8::internal::StrongRootAllocatorBase::StrongRootAllocatorBase+19274
 7: 00007FF7942EF681 v8::Isolate::GetHeapProfiler+7793
 8: 00007FF7942EFF28 v8::Isolate::GetHeapProfiler+10008
 9: 00007FF794300BDB v8::Isolate::GetHeapProfiler+78795
10: 00007FF793FC9ACB v8::base::AddressSpaceReservation::AddressSpaceReservation+322075

Steps to Reproduce

1. Start a new Claude Code session
2. Use Task tool to spawn an agent:

``
Task(subagent_type="devops-engineer", prompt="Check docker status", description="Docker check")
``

1. After agent completes, spawn another agent
2. Repeat steps 2-3 approximately 50-100 times over 30-60 minutes
3. Observe memory growing linearly (check via Task Manager on Windows)
4. Eventually session crashes with heap exhaustion

For faster reproduction:

• Spawn multiple agents in parallel (multiple Task calls in single response)
• Have agents perform complex tasks with many tool uses (20+)
• Run for extended sessions (45+ minutes)

Note: The bug correlates with cumulative agent spawns, not conversation length. Short sessions with heavy agent use crash faster than long sessions with minimal agent use.

Claude Model

Opus

Is this a regression?

Yes, this worked in a previous version

Last Working Version

2.0.76

Claude Code Version

2.0.76

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

Windows Terminal

Additional Information

Contact: domenico@domotz.com (for follow-up if needed)

Additional Evidence Available:

• Debug logs directory: 343 MB across 766 sessions
• Largest session debug file: 49.5 MB with 626 agent spawns
• Pattern analysis shows memory grows linearly with agent spawns, not conversation length

Usage Pattern:

• Heavy Task tool usage for specialist agent orchestration
• Custom hooks injecting routing context (~2-4KB per prompt)
• Parallel agent spawning (multiple agents concurrently)

Key Observation:
The GC efficiency metric (mu) dropping from normal (~0.9) to critical (0.006) strongly indicates that garbage collection cannot reclaim memory due to strong references being held. This suggests agent contexts are retained after completion rather than being released.

I'm happy to provide additional debug files, heap snapshots, or any other diagnostic information if helpful for investigation.