claude-code - 💡(How to fix) Fix [BUG] Agent Teams: teammate panes crash on spawn with "Input must be provided … --print" — launch line missing prompt (2.1.140) [1 comments, 2 participants]

Preflight Checklist

• Searched existing issues. Closest matches but distinct bugs:
  • #56788 (open) — agent teams crash on spawn with --model opus teammates; different visible error (Bun stack trace). Same surface (pane dies immediately), but in our case the model is not the trigger — see "Tested With" below.
  • #57892 (closed, fixed in 2.1.138) — Ink renderer <Box>/<Text> crash with permission prompts. Adjacent code path, different bug.
  • #53422 (closed, duplicate) — Ink rendering crash on 2.1.119.
  • #23527 (closed, fixed in 2.1.32) — teammate-instruction delivery bug caused by pane-base-index mismatch.
• Single bug report.
• Latest version — 2.1.140 (released 2026-05-12).

What's Wrong

With CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 and teammateMode: "tmux" (or "auto" while inside tmux), every spawned teammate pane dies on launch with:

Error: Input must be provided either through stdin or as a prompt argument when using --print

The lead's Agent({team_name, prompt: "..."}) call returns success and the team's config.json records the teammate, but the teammate process exits before any TUI renders. The lead sees indefinite silence — teammates appear "in_progress" via TaskList but never advance, never deliver tool calls, never reply.

Minimal Reproduction

Outside of any harness, in a regular shell:

.claude-wrapped --agent-id any-id --agent-name any-name --team-name any-team --agent-type general-purpose
# → Error: Input must be provided either through stdin or as a prompt argument when using --print

The four-flag teammate handshake (--agent-id + --agent-name + --team-name + --agent-type) deterministically flips claude-code into --print mode internally. Adding --parent-session-id, --agent-color, --permission-mode, --settings, --plugin-dir, --model (as the real harness does) does not change the result.

The actual harness-generated tmux-pane launch command looks like:

env CLAUDECODE=1 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 \
  /nix/store/…/.claude-wrapped \
    --agent-id shepherd-mono-1758@finish-prs-20260513-1830 \
    --agent-name shepherd-mono-1758 \
    --team-name finish-prs-20260513-1830 \
    --agent-color green \
    --parent-session-id 360433de-d62d-42c6-b0e3-d6dc2833ba21 \
    --agent-type general-purpose \
    --permission-mode auto \
    --settings /nix/store/…/claude-nix-settings.json \
    --plugin-dir /nix/store/…/claude-code-hm-plugin \
    --model claude-opus-4-7

No --prompt, no stdin pipe, no --input-format=stream-json. The binary therefore exits before the teammate can attach to its parent over IPC.

Expected Behavior

One of:

1. The four-flag teammate-launch handshake should NOT auto-enter --print mode — teammates need an interactive TUI so they can render their live state and receive the initial prompt over the parent IPC channel that --parent-session-id is meant to set up.
2. The tmux-spawn code that builds the teammate launch command should include the prompt, e.g. --prompt "$INITIAL_PROMPT", an --input-format=stream-json plus stdin pipe, or a --resume <id> form that attaches to a session the lead pre-created.

Either path is fine — the two sides of the spawn handshake currently disagree on how the prompt is supposed to be delivered.

Actual Behavior

• tmux list-panes -t <window> briefly shows the spawned pane, then pane_current_command returns to fish/zsh (the agent process exited).
• Pane scrollback contains the exact launch command followed immediately by the --print error.
• ~/.claude/teams/<team_name>/config.json records the teammate with valid tmuxPaneId.
• Lead's SendMessage to the teammate succeeds but no work is ever performed.

Workaround: teammateMode: "in-process" works fine — teammates run inline in the lead session, complete tasks, deliver tool calls. Pane theater is sacrificed.

Tested With

Environment

• claude-code: 2.1.140 (latest as of 2026-05-12)
• OS: NixOS, Linux 6.18.26
• tmux: 3.x
• Shell: fish (also reproduces in bash)
• Settings: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, teammateMode: "tmux" (and "auto")
• Lead model: Opus 4.7 (1M context)
• Distribution: Nix-packaged via numtide/llm-agents.nix overlay. The harness invokes .claude-wrapped directly (bypassing the bash wrapper), but I have verified the same crash with the unwrapped binary in /tmp and via direct claude invocation under the wrapper.

Suspected Cause

The CLI argument parser sees the four-flag teammate handshake and infers "non-interactive agent invocation" → flips internal mode to --print. But the harness code path that constructs this command line (the tmux pane spawner) does not also supply the prompt. Two sides of the handshake disagree on how the prompt is delivered. Either side can be fixed.

Additional Notes

• I have a /finish-prs slash command that fans out one teammate per open PR. With teammateMode: in-process it works end-to-end across 5 concurrent teammate PRs in our monorepo. With tmux (or auto inside tmux) it fails as above for every teammate.
• Happy to attach full pane scrollback, the lead-side session JSON, or test alternative invocations if useful.