claude-code - 💡(How to fix) Fix Background-Agent completion notifications drop silently when ≥3 parallel run_in_background agents dispatched

Summary

When the Agent tool is invoked with run_in_background: true for 3+ parallel agents in a single message (Opus model, long-running multi-tool work in the 20–90 minute range), the first 1–2 agents fire completion notifications normally to the parent agent, but the trailing agents complete silently — TaskStop <task-id> returns "task not found" indicating the harness has already garbage-collected the long-running task even though the work landed (filesystem evidence + green test suite confirm completion).

Net cost per affected dispatch wave: 20–40 minutes of false-wait in the parent agent + manual filesystem audit to confirm silent completion.

Reproducer (S82 canonical, 2026-05-17)

Single message dispatching 4 parallel Opus background agents:

Agent({ subagent_type: "general-purpose", run_in_background: true, ... }) // task ID a, ~26 min
Agent({ subagent_type: "general-purpose", run_in_background: true, ... }) // task ID b, ~60 min
Agent({ subagent_type: "general-purpose", run_in_background: true, ... }) // task ID c, ~30–90 min
Agent({ subagent_type: "general-purpose", run_in_background: true, ... }) // task ID d, ~30–90 min

Observed outcome:

• Task a (~26 min): ✅ completion notification fired normally
• Task b (~60 min): ✅ completion notification fired normally
• Task c (~30–90 min): ❌ silent completion, TaskStop c → "task not found"
• Task d (~30–90 min): ❌ silent completion, TaskStop d → "task not found"

Filesystem audit (git status --short against expected new-file list) confirmed both silent tasks landed their work cleanly. Full test suite passed against the union of all 4 agents' changes.

Sprint history (4-sprint observation)

Pattern is reliable: trailing agents in waves of ≥3 consistently exhibit silent completion.

Workaround currently in use

1. Cap parallel background-agent dispatches at 2 per wave. If a wave needs >2 build agents, run sequential waves of 2 each.
2. Filesystem-watch checkpoint at ~30 min and ~60 min after dispatch — run git status --short against the expected new-file list per item.

Environment

• Claude Code CLI (VSCode native extension)
• Model: claude-opus-4-7 (Opus 4.7 1M context)
• OS: macOS Darwin 23.0.0
• Tasks are general-purpose subagents doing multi-tool R3 build work (file reads, edits, bash commands)

Suggested investigation

Likely candidate: the task GC threshold may be tied to either (a) parent-agent message count between dispatch and check-in, or (b) absolute wall-clock independent of parent-agent activity. If the trailing agents exceed the threshold before the parent next sends a message, the notification path is unreachable when they finally complete.

Impact

Approximately 2 hours of cumulative parent-agent context-window pressure across S79–S82 on a sprint-orchestrating use case (Claude Code driving an internal 17-agent SDLC pipeline). The workaround (cap = 2) doubles the wall-clock for sprints that legitimately need 4-way parallel R3 build dispatches.