claude-code - 💡(How to fix) Fix Agent-team teammate reports 'Spawned successfully' but never registers in mailbox (v2.1.123, macOS, tmux) [2 comments, 2 participants]

Summary

Agent-team teammates spawned via the Agent tool report Spawned successfully but the child Claude Code subprocess never registers with the parent's mailbox. current-team.json stays at members: [] and the orchestrator never receives a reply.

Environment

• macOS Darwin 24.4.0 (arm64)
• Claude Code v2.1.123 (native installer, binary at ~/.local/share/claude/versions/2.1.123)
• tmux 3.6a (Homebrew)
• zsh
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 enabled
• Reproduced on v2.1.118 and v2.1.123. Issue is independent of binary version.

Reproduction

1. Orchestrator session (interactive claude) calls:

   Agent({
     subagent_type: "general-purpose",
     model: "sonnet",
     mode: "acceptEdits",
     team_name: "<team>",
     name: "test-spawn",
     prompt: "reply HELLO and end your turn"
   })

2. Tool returns Spawned successfully with agent_id: test-spawn@<team>.

3. Tmux pane shows the spawn shell command, optionally a compdef: command not found warning from zsh init, then Resume this session with: claude --resume <uuid>, then a fresh shell prompt.

4. ~/.claude/teams/<team>/config.json contains the team but members is empty.

5. Orchestrator's current-team.json shows members: []. No teammate reply ever arrives. Orchestrator hangs or times out.

Expected behavior

Child process registers itself in the parent team's config.json members array, opens IPC mailbox, processes the prompt, and replies via SendMessage.

Actual behavior

Child exits cleanly (prints "Resume this session" — the standard exit message) before completing the IPC handshake. Orchestrator sees Spawned successfully but never gets a reply.

Diagnostic results

Direct binary tests work:

echo "hi" | /Users/<user>/.local/share/claude/versions/2.1.123 --print --model sonnet --permission-mode bypassPermissions
# returns "Hey."

env CLAUDECODE=1 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 \
  /Users/<user>/.local/share/claude/versions/2.1.123 \
  --print "reply HELLO" \
  --agent-id t@td --agent-name t --team-name td --agent-color blue \
  --parent-session-id <fresh-uuid> --agent-type general-purpose \
  --permission-mode auto --model sonnet
# stdout: HELLO, exit 0

Manual tmux pane reproduction (no orchestrator) — child binary stays alive and shows banner:

tmux new-session -d -s test
tmux send-keys -t test "env CLAUDECODE=1 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 \
  /Users/<user>/.local/share/claude/versions/2.1.123 \
  --agent-id t@td --agent-name t --team-name td --agent-color blue \
  --parent-session-id <fresh-uuid> --agent-type general-purpose \
  --permission-mode auto --model sonnet" Enter
sleep 5
tmux capture-pane -t test -p
# Pane shows Claude Code banner, "@t" agent prompt, no errors, stays alive.

So the binary itself spawns correctly under tmux. The failure is internal to Claude Code's orchestrator-side spawn logic when invoked via the Agent tool with team_name.

Suspected cause

Orchestrator declares Spawned successfully based on tmux pane creation (or the binary returning a session id) rather than on the child completing the mailbox handshake. The child appears to start, then exits before subscribing to the mailbox — possibly because:

• The --parent-session-id it receives doesn't match a parent that has begun listening on the corresponding mailbox path.
• A race between team config write and child subscribe.
• The child's interactive-mode init aborts when its stdin is the tmux pane (different from manual reproduction stdin path).

Side-quest finding (already worked around)

Independent of this bug, ~/.zshrc lines that source process substitutions (source <(ng completion script)) without an [[ -o interactive ]] guard emit compdef: command not found warnings during shell init in tmux panes. After guarding zshrc, the warning is gone and a manual tmux spawn succeeds — but the orchestrator's Agent call still fails to receive a reply, which is why I believe the spawn-vs-handshake issue is a separate bug.

Workaround

Use plain subagents (Agent without team_name) — these spawn reliably. Forfeits team mailbox / per-teammate fresh-context-window benefits.

Repo for reference

The orchestrator system that hits this consistently: https://github.com/borabekarr/claude-code-system (private/local but happy to provide minimum repro on request).