claude-code - 💡(How to fix) Fix Bug: Agent(team_name) forces tmux mailbox routing but spawns native process — teammates never receive instructions [1 participants]

Environment

• Claude Code: 2.1.140 (latest as of 2026-05-14)
• Platform: macOS Darwin 25.2.0 (arm64)
• tmux: 3.6a (installed)
• Setting: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 enabled

Summary

When CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is enabled, spawning an Agent with the team_name parameter registers the agent with backendType: "tmux" and a tmux pane ID, but the agent actually runs as a native process. The tmux mailbox communication channel is unreachable, so the teammate never receives instructions and tasks remain pending forever.

Reproduction Steps

1. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS="1" in ~/.claude/settings.json env
2. Call TeamCreate(team_name="test")
3. Call TaskCreate(subject="test", description="run find lib/ -name '*.dart' | head -5")
4. Call TaskUpdate(taskId="1", owner="worker-1")
5. Call Agent(team_name="test", name="worker-1", prompt="Call TaskList, claim your task, execute it, mark completed")

Expected Behavior

Agent spawned with team_name should either:

• (A) Run as a native process with native SendMessage routing, OR
• (B) Actually spawn inside a tmux pane where mailbox delivery works

Actual Behavior

• Agent tool returns "Spawned successfully" and "will receive instructions via mailbox"
• Team config.json registers agent with backendType: "tmux", tmuxPaneId: "%0"
• No tmux session or pane is created (tmux list-sessions → "no server running")
• Agent process runs as native but communication is routed to a nonexistent tmux mailbox
• TaskUpdate from agent never happens → task stays pending forever
• SendMessage to agent goes to "inbox" via mailbox routing → never delivered

Verified Findings

• ✅ Agent WITHOUT team_name works perfectly (returns results directly)
• ✅ tmux 3.6a is installed; manually creating tmux session and starting claude CLI in pane works
• ❌ Removing teammateMode: "tmux" from settings.json does NOT fix the issue
• ❌ When tmux session pre-exists, pane ID is correctly detected (e.g. "%1") but agent still runs native and cannot receive tmux mailbox messages
• ❌ This makes the entire /team skill in the oh-my-claudecode plugin non-functional, as OMC relies on Claude Code's native team tooling

Workaround

Spawn agents WITHOUT team_name parameter. Use TeamCreate/TaskCreate for tracking only, and Agent() (no team_name) for actual execution. The lead updates task status based on agent return values.

This workaround is functional but loses the native team communication (SendMessage between lead and workers) and the worker self-service task claiming protocol.