claude-code - 💡(How to fix) Fix [BUG] Agent Teams (Desktop, in-process): SendMessage content dropped when racing with idle notification

Environment

• Client: Claude Desktop (CLAUDE_CODE_ENTRYPOINT=claude-desktop)
• Agent SDK version: 0.2.128
• Model: claude-opus-4-7[1m]
• Backend: in-process (per team config; not tmux, not SDK, not VS Code)
• OS: macOS, Apple silicon, Node v25.8.1
• Experimental flag: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (verified reaching the process via env)
• Date observed: 2026-05-08

Summary

A teammate's SendMessage call returns {success: true}, the message is correctly written to ~/.claude/teams/<team>/inboxes/team-lead.json, the message is marked "read": true, but it never appears as a <teammate-message> block in the lead's conversation. Idle notifications that follow shortly after appear to win the delivery race.

This appears distinct from the existing related issues:

• The inbox is being polled (other messages from the same teammate in the same session are delivered correctly).
• Recipient name resolution works (the teammate is named probe, target team-lead; non-dropped messages from the same agent reach the lead).
• This is on Claude Desktop with the in-process backend, not VS Code (#25254), not tmux (#23415), not SDK streaming mode (#26426, agent-sdk-python #577).

The delivery layer is intermittently dropping content messages that arrive close in time to a subsequent idle notification.

Reproduction

1. TeamCreate({team_name: "stability-test", description: "...", agent_type: "researcher"})

2. Agent({
     subagent_type: "general-purpose",
     team_name: "stability-test",
     name: "probe",
     model: "opus",
     prompt: "Read /path/to/file-A, report line count via SendMessage to team-lead. Then go idle."
   })
   → returns synchronously: agent_id "probe@stability-test", spawned

3. Wait. Lead receives a `<teammate-message>` with `idle_notification` after first task.

4. Lead sends second task:
   SendMessage({
     to: "probe",
     message: "Read /path/to/file-B, report line count via SendMessage. Then go idle.",
     summary: "Cycle-2 stability test"
   })

5. Wait. Lead receives ONE `<teammate-message>` ~16 seconds later — but it is the
   `idle_notification`, not the content reply. No content message arrived in conversation.

6. Read `~/.claude/teams/stability-test/inboxes/team-lead.json` directly:
   the content message IS there, written ~4 seconds BEFORE the idle notification,
   already marked `"read": true`.

Concrete inbox excerpt

team-lead.json (the lead's inbox) shortly after the cycle-2 wake-up:

[
  {
    "from": "probe",
    "text": "29 lines. `/Users/.../pipeline/CLAUDE.md` has 29 lines total.",
    "summary": "Cycle 2: pipeline/CLAUDE.md line count",
    "timestamp": "2026-05-08T22:36:26.798Z",
    "color": "blue",
    "read": true
  },
  {
    "from": "probe",
    "text": "{\"type\":\"idle_notification\",\"from\":\"probe\",\"timestamp\":\"2026-05-08T22:36:30.260Z\",\"idleReason\":\"available\"}",
    "timestamp": "2026-05-08T22:36:30.260Z",
    "color": "blue",
    "read": true
  }
]

The first entry (22:36:26) was the substantive content reply the lead was expecting. It was never delivered to the lead's conversation as a <teammate-message> block. Only the second entry (22:36:30, the idle notification) was delivered.

When later prompted, the teammate confirmed it had sent the message successfully:

"I did send this same result via SendMessage on the previous turn (summary 'Cycle 2: pipeline/CLAUDE.md line count') and got success+routing back from the tool — so if that one didn't reach you, the issue is delivery, not my use of the tool."

This was reproducible: the same pattern happened on the first task as well — initial content reply went to the inbox file but only the idle notification surfaced in conversation. A diagnostic re-prompt got the agent to re-send, and the re-send was delivered.

Impact

This makes Agent Teams unreliable for any production workflow. Users observe their teammate "going silent" after each task and reasonably conclude the agent or the whole feature is broken, when in fact the agent has correctly used the protocol and the failure is in the inbox→conversation delivery infrastructure. Re-prompting and asking the agent to re-send works as a workaround, but it doubles round-trip cost and is invisible without inbox file inspection.

Workaround (for users hitting this now)

1. When an expected response doesn't arrive, read ~/.claude/teams/<team>/inboxes/team-lead.json directly. The lost message is almost certainly there.
2. SendMessage the teammate asking it to re-send. It will, and often correctly notes (in its own re-sent reply) that it had already sent the message and got success from the tool.

Related issues

• #25254 — VS Code extension variant of similar delivery failure
• #34668 — intermittent SendMessage receive failures after extended polling
• #25135 — SendMessage silent success when recipient name doesn't match polling target
• #24246 — idle notifications delivered out of order vs content messages
• #23415 — tmux backend variant (inbox not polled at all)
• #26426 / agent-sdk-python #577 — non-interactive / SDK streaming mode variant

This Desktop in-process variant — where the inbox is polled, the recipient name does match, but content messages racing with idle notifications get dropped — does not appear to be exactly covered by any of the above.

Suggested fix

Investigate the inbox→conversation delivery batch logic. The bug appears to be that when multiple inbox messages accumulate close together (a content message followed within ~5 s by an idle notification), only the idle notification (or only the most recent) surfaces as a <teammate-message> in the next conversation turn.

Suggested behavior: at every turn boundary, flush all unread inbox messages to the conversation in timestamp order — and only mark them read: true after they have been emitted as <teammate-message> blocks, not at the moment they're written to the file.