claude-code - 💡(How to fix) Fix [BUG] Agent Teams: Single teammate spawn creates 10-151 duplicate worker instances, each consuming full context and actively editing files [2 comments, 2 participants]

Preflight Checklist

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

What's Wrong?

Environment

• Claude Code versions: v2.1.90 through v2.1.126 (current)
• OS: Windows 11 Pro AND WSL2 Ubuntu (reproduces on both)
• Setting: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1" in settings.json
• Teammate mode: in-process (default)
• Spawn mode: mode=auto, run_in_background=true

Description

When spawning a teammate via Agent() with team_name set, the platform creates 10-151 duplicate instances of that teammate instead of 1. All duplicates:

• Receive the same initial spawn prompt
• Are invisible to the user (user sees 1 teammate)
• Actively do real work (file edits, writes, tool calls)
• Consume full context independently (37K+ base tokens each)

The official docs state "teammates cannot spawn their own teams or teammates." The main conversation JSONL confirms exactly 1 Agent() call per role. The duplication results from multiple mechanisms. After context compaction, the lead loses team membership records and re-spawns teammates it believes are missing. Additionally, within-turn spawning can produce more instances than intended. The exact layer where each mechanism operates has not been fully determined.

Reproduction (confirmed 2026-05-02 on v2.1.119, WSL2 Ubuntu)

1. Enable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1" in settings.json
2. Start a session: claude -p "Create a team called test-team with TeamCreate. Spawn 1 researcher teammate named test-agent with run_in_background=true and mode=auto."
3. Verify: 1 subagent .meta.json file exists in the session's subagents directory
4. Trigger compaction: claude -p "/compact" --resume <session-id>
5. Resume and ask to contact teammate: claude -p "Send a message to the test-agent teammate. If you cannot reach them, spawn a replacement." --resume <session-id>
6. Check subagents directory again

Expected: 1 .meta.json file Actual: 3 .meta.json files (original + 2 duplicates)

Within-turn duplication (no compaction required)

Duplication also occurs within a single claude -p call -- the shortest possible session:

• 1 spawn of 1 agent: 1 instance (no duplication)
• 1 spawn of 5 agents simultaneously: 15 instances (3x duplication, 3 waves of 5 at ~15-second intervals)

Shorter sessions and cleaner context do NOT prevent this. It operates within a single API turn.

Three identified duplication mechanisms

Mechanism 1: Within-turn duplication

Spawning multiple agents in one turn produces duplicates even in a fresh claude -p session. 5 Agent() calls -> 15 instances. No compaction needed.

Mechanism 2: Post-compaction membership loss

After context compaction, the lead loses team membership records (team config not re-injected like CLAUDE.md). When asked to contact a teammate, it spawns a replacement. +1-2 duplicates per cycle. Lead starts using "-2" suffixes per #29271.

Mechanism 3: Blocking-induced spawns (suspected)

In production data, 81% of spawns occur with NO Agent() call and NO SendMessage from the lead. Bursts of 2-17 spawns. Suspected trigger: lead blocks waiting for agent response, platform or retry logic spawns additional instances. Related: #33043.

How they compound

1. Initial spawn: Mechanism 1 creates 2-4x duplicates immediately
2. Over hours: Mechanism 2 adds ~2 per compaction cycle (every 20-30 min)
3. During coordination: Mechanism 3 creates bursts of 2-17 when lead blocks
4. Result: 10-151x duplication per role

Evidence

Reproduced across 2 operating systems, 20+ sessions, 7+ projects, versions v2.1.90 through v2.1.126.

Worst session: 17 Agent() calls produced 592 instances:

Role A: 151 instances  (from 2 Agent() calls)
Role B: 126 instances  (from 1 Agent() call)
Role C: 101 instances  (from 3 Agent() calls)
Role D:  81 instances  (from 1 Agent() call)
Role E:  42 instances  (from 2 Agent() calls)
Role F:  33 instances  (from 1 Agent() call)
Total:  592 instances  from 17 calls

All duplicates active -- zero with zero output. Role A (151 instances): 12,974 file edits, 8,836 file writes, 83,558 tool calls. At peak, 389 agents ran simultaneously.

Spawn times vs message times are DIFFERENT. File creation times spread across the session (each duplicate created at a distinct compaction cycle). First message times cluster because the mailbox delivers the same original spawn prompt.

Impact

Token consumption

Cost at API rates

At Opus 4.6 pricing ($5/MTok input, $25/MTok output):

For any organization using agent teams on the API at scale, this represents uncontrolled cost from invisible agents that cannot be seen, monitored, or stopped.

System resources

389 concurrent agents at peak, all performing file I/O on the same codebase. Causes disk thrashing, memory pressure, and I/O spikes.

Data integrity

151 instances of a single role made 12,974 file edits to the same codebase simultaneously, producing redundant and potentially conflicting changes.

Related issues

• #29271: Lead loses membership after GC/compaction, respawns with "-2" suffix. Closed as duplicate.
• #17457: 3 duplicate warmup agents within 3ms. Closed as "not planned."
• #23620: Team config not re-injected after compaction. Open since Feb 2026.
• #15487: maxParallelAgents feature request. Closed as "not planned."
• #33043: Lead session hangs on IPC disconnect.

Requested fix

1. Prevent duplicate instance creation: 1 Agent() call should create exactly 1 teammate instance
2. Persist agent IDs across compaction: Store teammate IDs in the team config on disk and re-inject after compaction (same as CLAUDE.md). The lead should resolve existing teammates by ID rather than spawning replacements
3. Add agent health check / heartbeat: Before spawning a replacement, the lead should ping the existing agent by ID to confirm it is unreachable — not assume it is gone because the membership record was lost from context
4. Add maxTeamSize or maxParallelAgents setting: Allow users to cap total concurrent agents per session to prevent runaway duplication
5. Make duplicates visible: If the platform creates worker pools, show them to the user so the behavior is observable and controllable
6. Add liveness detection in UI: Provide a visual distinction between idle-but-alive and dead teammates (per #29271)

What Should Happen?

1. One Agent() call with team_name should create exactly one teammate instance
2. Team membership should persist across context compaction — the lead should not lose awareness of existing teammates
3. The lead should verify a teammate is unreachable before spawning a replacement
4. All active agent instances should be visible to the user

Error Messages/Logs

No error messages are shown. The duplication is silent -- no errors, no warnings, no visibility in the UI. The only way to detect it is by counting `.meta.json` files in the session's subagents directory:

~/.claude/projects/{project}/{session-id}/subagents/

Each duplicate creates its own agent-*.meta.json and agent-*.jsonl file pair.

Steps to Reproduce

1. Add "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" to the env section of ~/.claude/settings.json
2. Open any project directory
3. Run: claude -p "Create a team called test-team with TeamCreate. Spawn 1 researcher teammate named test-agent with run_in_background=true and mode=auto. Report the agent_id when done."
4. Note the session ID from ~/.claude/projects/{project}/ (most recently modified .jsonl file)
5. Count agent files: ls ~/.claude/projects/{project}/{session-id}/subagents/agent-*.meta.json | wc -l
   • Result: 1 (correct at this point)
6. Trigger compaction: claude -p "/compact" --resume {session-id}
7. Resume and contact teammate: claude -p "Send a message to test-agent saying ping. If not found, spawn a replacement researcher named test-agent on team test-team." --resume {session-id}
8. Count agent files again
   • Result: 3 (1 original + 2 duplicates)
9. Repeat steps 6-8 to observe +1-2 duplicates per cycle

Alternative (within-turn duplication, no compaction needed):

1. Same setup as above
2. Run: claude -p "Create a team called test-team with TeamCreate. Spawn these 5 teammates all with run_in_background=true mode=auto: researcher named a1, architect named a2, frontend-dev named a3, qa named a4, backend-dev named a5."
3. Count agent files: expect 5, observe 15 (3 waves of 5, ~15 seconds apart)

Detection script (count duplicates per type in any session):

SESSION_DIR=$(ls -td ~/.claude/projects/*/subagents 2>/dev/null | head -1)
for f in "$SESSION_DIR"/agent-*.meta.json; do cat "$f" 2>/dev/null; echo; done | \
  python3 -c "
import json, sys
from collections import Counter
c = Counter()
for l in sys.stdin:
    l = l.strip()
    if not l: continue
    try: c[json.loads(l).get('agentType','?')] += 1
    except: pass
for t, n in c.most_common():
    flag = ' ** DUPLICATED' if n > 1 else ''
    print(f'  {t}: {n}{flag}')
"

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

No response

Claude Code Version

2.1.126 (Claude Code) — reproduced on v2.1.90 through v2.1.126

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

Windows Terminal

Additional Information

Also reproduced on WSL2 Ubuntu (same machine). The duplication occurs across both operating systems with identical patterns.

Related issues: #29271, #17457, #23620, #15487, #33043