settled-reach/team-test.md

Team Tmux Pane Test

Problem

teammateMode: "tmux" is broken in Claude Code v2.1.117-119. Agents spawn as invisible background processes instead of getting their own tmux panes. This is a regression — tmux panes worked correctly on this machine through Sprint 35 (see ~/.claude/teams/sprint-35-*/config.json for proof: backendType: "tmux" with real pane IDs).

Relevant GitHub issues

• https://github.com/anthropics/claude-code/issues/51818 — teammate CLI crash on permission_response
• https://github.com/anthropics/claude-code/issues/52337 — subagent Ink rendering crash on Edit/Write

Config (already set, do not change)

• .claude/settings.json has "teammateMode": "tmux" and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
• tmux is running, $TMUX is set, TERM=tmux-256color

Version gate

Always start by looking up the release notes for any versions between the last tested version and the current one. Check the GitHub releases page at https://github.com/anthropics/claude-code/releases for fixes related to teams, tmux, teammates, or the tracked issues below. If the release notes show no relevant fixes, log the version as SKIPPED (no relevant fixes) and stop — do not run the test procedure.

Check claude --version first. If the version appears in the "Tested versions" log below, the bug was already confirmed broken on that release — do not re-test. Only run the test procedure on a version not yet logged.

Tested versions

Version	Date	Result
2.1.119	2026-04-25	BROKEN — no tmux pane, no team config on disk
2.1.120–122	2026-04-30	SKIPPED — release notes show no teams/tmux/teammate fixes; #51818 and #52337 still open (dupes of #51855, unreleased)
2.1.123	2026-04-30	PARTIAL — tmux pane spawns, config on disk correct (backendType: tmux, paneId: %23). Custom subagent_type ("qatux") missing SendMessage — can receive but not send. General-purpose subagent_type has SendMessage — two-way comms work. BOTH types fail to process shutdown_request. TeamDelete reports success but does NOT kill the tmux pane — agent process keeps running, requires manual ctrl-c + exit.
2.1.123 (workshop)	2026-04-30	UPDATE — full workshop run with 4 general-purpose agents. Two-way comms confirmed for all. shutdown_request processed successfully by all 4 agents (contradicts earlier single-agent test). TeamDelete cleaned up correctly. Workaround: use general-purpose subagent_type with personality baked into prompt instead of custom subagent_type.
2.1.124–2.1.147	2026-05-22	NOT SEPARATELY TESTED — relevant fixes in range: 2.1.133 (subagent SendMessage cwd restore + skill discovery), 2.1.139 (agent view research preview — unified session list), 2.1.144 (background subagent completion notifications), 2.1.145 (Agent Teams non-ASCII name header fix). Cluster of background-session fixes 2.1.140–2.1.143 signals a shift to an in-process/daemon background-agent model. Tested cumulatively at 2.1.148.
2.1.148	2026-05-22	NOT A BUG — root cause found. Agent spawned backendType: "in-process" because .claude/settings.json actually contains "teammateMode": "in-process", NOT "tmux" as the "Config" section of this file wrongly claimed. The in-process backend behaved exactly as configured. All split-pane prerequisites ARE met: tmux 3.6a in PATH, running inside tmux (CC in pane %5, $TMUX set), CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Per official docs (code.claude.com/docs/en/agent-teams), teammateMode values are auto (panes if inside tmux, else in-process) / tmux (force panes) / in-process (force main terminal). Setting it to "tmux" or "auto" should produce split panes. Functional results in-process mode: two-way comms WORK with custom subagent_type "qatux" (it sent its message — improvement over 2.1.123 single-agent), shutdown_request processed cleanly, TeamDelete cleaned up correctly. The "broken regression" premise of this file was a stale/incorrect config claim, not a Claude Code defect.
2.1.148 (auto re-test)	2026-05-22	INCONCLUSIVE (needs restart) — flipped .claude/settings.json to "teammateMode": "auto" mid-session and re-spawned. Agent STILL spawned in-process (pane count unchanged %0–%6, qatux backendType=in-process, lead backendType empty). Cause: teammateMode is read at session startup and cached — a live edit is not picked up by the running session. The new "auto" value is on disk. Next step: restart Claude Code, then re-run the spawn test. With auto + inside tmux (CC was in pane %5) + tmux 3.6a in PATH, teammates should spawn in split panes. If auto still fails post-restart, set "tmux" explicitly.
2.1.148 (post-restart, auto)	2026-05-22	WORKS + ROOT CAUSE OF SUBAGENT GAP FOUND. After restart, teammateMode: "auto" + inside tmux spawned qatux in a real split pane (backendType: "tmux", paneId %7). CONFIRMED the 2.1.123 finding: a custom subagent_type whose agent definition has a restricted tools: list does NOT get the team-coordination tools injected in pane mode — qatux had only Read/Edit/Write/Bash; SendMessage "exists but is not enabled"; TaskCreate/TaskUpdate/TaskList/Agent absent entirely. (In-process mode does inject SendMessage — backend-inconsistent, contradicts the docs which say coordination tools are always available.) Consequence: such a teammate can't message AND can't return a shutdown_response, so it orphans its pane on shutdown (requires manual tmux kill-pane). FIX: added SendMessage to the tools: frontmatter of all 21 agent definitions in .claude/agents/. Re-spawned qatux → SendMessage works AND clean shutdown works (pane self-closes, no orphan), picked up at spawn with NO session restart needed. Net: the feature is fully functional on 2.1.148; the only real defect is that custom restricted-tool subagents need coordination tools listed explicitly to work as pane-mode teammates.

Test procedure

1. Check version: claude --version
2. If the version is already in the "Tested versions" table above, stop here — log nothing, do not spawn agents. Report that the version is unchanged.
3. Create a team and spawn one agent:

TeamCreate: team_name = "tmux-test"
Agent: name = "qatux", subagent_type = "qatux", model = "sonnet",
       run_in_background = true,
       prompt = "You are a test agent. Message the team lead: 'tmux pane test — I am alive.' Then stay idle."

4. Check: did a new tmux pane appear? Run tmux list-panes -a to verify.
5. Check: does ~/.claude/teams/tmux-test/config.json exist and contain backendType: "tmux"?
6. Log the result in the "Tested versions" table above (version, date, BROKEN/FIXED + notes).
7. If BROKEN, clean up any leftover team state and stop. If FIXED, proceed to "Cleanup".

Expected result (when fixed)

• A new tmux pane opens with the Qatux session visible
• Team config on disk shows backendType: "tmux" with a real pane ID
• Agent is reachable via SendMessage

Actual result (v2.1.119)

• No tmux pane appears
• No team config directory created on disk
• Agent runs as invisible background process

Context

This blocks the generation-cascade workshop (ticket #897, Sprint 38). The full workshop has 3 participants (Gestalt, Tyre, Miri) + Qatux documenter, 3 rounds. Team and tasks are already created — once tmux panes work again, spawn the agents and go. See docs/workshops/generation-cascade/BRIEF.md for the full workshop brief.

Cleanup

Delete this file and TeamDelete the tmux-test team once the test passes.