claude-code - 💡(How to fix) Fix [BUG] Agent Teams (in-process): unbounded team-lead inbox stalls teammate→lead message surfacing at ~1MB / 1000+ msgs

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?

With Agent Teams (teammateMode: "in-process"), the team-lead's inbox file ~/.claude/teams/<team>/inboxes/team-lead.json accumulates every teammate→lead message and is never pruned. Reused across many sessions, mine reached 1065 messages / 1.77 MB. At that scale, new teammate SendMessages to the lead are still appended to the file and marked read: true, but they stop being injected into the lead's conversation — the lead receives no teammate-message turn.

The lead therefore sees silence and mis-judges actively-delivering teammates as "stalled," then shuts down and re-dispatches working agents. In my run this caused repeated churn and near-loss of completed deliverables (a subagent had fully written a spec + run the test suite, but looked "silent" and was almost discarded).

There is no separate delivery cursor — the per-message read flag appears to BE the delivery state, so once the file is large the surfacing path silently degrades while still marking incoming messages read.

What Should Happen?

New teammate→lead messages should surface in the lead's conversation regardless of accumulated inbox size, and/or the inbox should be auto-pruned/capped so it cannot grow unbounded. Surfacing should never silently stop without an error.

Error Messages/Logs

No error is shown — silent failure is the core problem. State of the inbox when it broke:

• ~/.claude/teams/<team>/inboxes/team-lead.json: 1065 messages, all read: true, ~1.77 MB.
• The "missing" deliveries were present in the file (written + flagged read: true); they simply never surfaced as conversation turns.

Workaround that confirms the diagnosis:

cp inboxes/team-lead.json inboxes/team-lead.json.bak
printf '[]' > inboxes/team-lead.json

Immediately after resetting the file to [], the entire backlog of stuck messages flushed into the conversation at once — proving the messages were stuck (not lost) and that inbox size/length is the trigger.

Steps to Reproduce

1. Create a team and spawn many subagents that SendMessage the lead, across several sessions — do not delete/recreate the team, so the inbox persists and accumulates.
2. Watch ~/.claude/teams/<team>/inboxes/team-lead.json grow unbounded (it is never pruned).
3. Once it reaches ~1 MB / ~1000+ messages, new teammate SendMessages to the lead stop surfacing in the lead's conversation, while still being appended to the file with read: true.
4. Reset the file to [] → the backlog flushes immediately (confirms size/length is the trigger).

Suggested fixes: auto-prune/cap the inbox (keep unread + a recent window); or decouple delivery from the read flag with a separate cursor; or stream new messages regardless of accumulated file size.

Claude Model

N/A — this is a harness / teammate-delivery bug, model-independent. (Running Claude Opus 4.x.)

Is this a regression?

Not sure — first time running Agent Teams at this scale (1000+ accumulated messages in one persistent team).

Environment

• Claude Code (CLI), Windows 11
• teammateMode: "in-process"
• A persistent team dir (~/.claude/teams/<team>/) reused across many sessions (not recreated)