Subagent processes inherit unbounded V8 heap reservation, causing OOM on large-memory systems

_Generated by CC CLI but I have read the issue and it is what is intended_

Summary

Claude Code v2.1.50 only sets --max-old-space-size=8192 when CLAUDE_CODE_REMOTE=true. In local mode, subagent (Task tool) child processes inherit V8's auto-sized heap limit, which on a 251 GB RAM system reserves 128 GB of virtual address space per process. This causes system crashes under both Linux overcommit modes.

Environment

• Claude Code 2.1.50 (compiled SEA binary embedding Node 24.3.0)
• Pop!_OS 24.04, Linux 6.17.9, x86_64
• 251 GB RAM, 20 GB swap
• 64 CPUs

Root Cause

The binary contains:

if(process.env.CLAUDE_CODE_REMOTE==="true"){
  let H=process.env.NODE_OPTIONS||"";
  process.env.NODE_OPTIONS=H?`${H} --max-old-space-size=8192`:"--max-old-space-size=8192"
}

This guard means local-mode processes get no heap cap. Node 24's V8 auto-sizes max_old_space_size to approximately half of system RAM. On a 251 GB machine, each subagent process attempts to mmap 128 GB (137438953472 bytes), confirmed by kernel log:

__vm_enough_memory: pid: 66067, comm: 2.1.50, bytes: 137438953472 not enough memory for the allocation

Failure Modes

Two crashes observed on the same day, one under each overcommit mode:

With vm.overcommit_memory=0 (heuristic, Linux default)

Multiple concurrent claude sessions consumed real memory unchecked. The OOM killer fired and killed claude processes plus unrelated desktop processes (cosmic-applets, xdg-desktop-portal-cosmic, etc.), causing a system-wide crash.

_Hugh edit: caused by user-error: large memory processes set to run in parallel. Motivated the overcommit memory change but not a bug in CC._

With vm.overcommit_memory=2 (strict accounting)

CommitLimit = SwapTotal + MemTotal × 0.95 ≈ 258 GB. Two processes reserving 128 GB each nearly exhausted this. Sustained subagent spawn failures (25+ over 6 minutes) eventually starved the parent claude process, which failed to allocate even 4096 bytes and aborted with a core dump:

__vm_enough_memory: pid: 10233, comm: claude, bytes: 4096 not enough memory for the allocation

Actual Memory Usage

The parent claude process uses ~580 MB RSS (VmRSS) against its 37 GB VmSize. The 128 GB reservation is pure V8 address space that will never be used by a CLI tool.

Suggested Fix

Remove the CLAUDE_CODE_REMOTE guard so that --max-old-space-size=8192 applies universally, or better, set a smaller limit specifically for subagent child processes (which need even less memory than the parent). The 8192 MB cap already used in remote mode provides ~14x headroom over actual usage.

Workaround

Users can set NODE_OPTIONS="--max-old-space-size=8192" in their shell profile. This matches the remote-mode behavior that Claude Code already applies.