Agent teams (TeamCreate/SendMessage/TaskCreate) are unusable in claude-code-action due to SDK session lifecycle

[passtas]

Use case

We run a multi-agent pipeline via claude-code-action that automates large cross-repo merges: analyzing upstream changes, adapting files in parallel across 10-15 agents, then validating the result. Agent teams are a natural fit: the lead orchestrates waves, teammates work independently on assigned batches, shared task lists track progress, and inter-agent messaging enables coordination between planning, adaptation, and validation phases. Plain subagents work as a fallback but lose the coordination layer that makes teams powerful.

Problem

When CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set in the claude-code-action environment, team tools (TeamCreate, TeamDelete, SendMessage) become discoverable via ToolSearch and appear to work. TeamCreate succeeds. Agent with team_name spawns teammates. But the session terminates immediately after spawning.

The root cause: teammates are separate processes that return instantly ("The agent is now running and will receive instructions via mailbox."). The lead has no pending foreground tool calls, produces end_turn, and the SDK exits the session, typically after 10-11 turns, before any teammate completes work.

In interactive CLI mode this works because the terminal session stays alive and teammate messages arrive as interrupts. In SDK/headless mode (claude-code-action), there is no equivalent mechanism to keep the agent loop running while teammates work.

Workarounds attempted

None of these prevent the premature exit:

• "Watcher" subagent: Spawned a plain Agent (no team_name) alongside teammates, intended to block the session as a foreground subagent. Failed due to a secondary issue: once a team exists, ALL agents spawned by the lead are auto-enrolled as teammates regardless of whether team_name is set. The watcher became wave1-watcher@upstream-sync and returned immediately. See log excerpt below.
• run_in_background: false: No effect. Teammates with team_name always spawn as separate processes.
• Prompt-level instructions: Telling the model not to use run_in_background does not change the underlying SDK behavior.

Secondary issue: agents auto-enroll into active team

When a team is active, spawning an Agent without team_name still enrolls it as a teammate. This prevents any workaround that relies on mixing foreground subagents with team agents.

# Agent spawned WITHOUT team_name
"name": "wave1-watcher",
"model": "haiku",
"mode": "bypassPermissions",

# Result: auto-enrolled into active team
"task_type": "in_process_teammate"
"agent_id: wave1-watcher@upstream-sync"
"team_name: upstream-sync"
"The agent is now running and will receive instructions via mailbox."

# Lead has no pending calls, session exits
"num_turns": 11,
"stop_reason": "end_turn",

Request

We'd most value native support for agent teams in SDK/headless mode. The coordination primitives (shared task lists, inter-agent messaging, teammate lifecycle) are exactly what complex CI/CD pipelines need. Possible approaches:

• A blocking spawn mode for teammates (blocks until the teammate completes, like foreground subagents)
• A session keepalive that prevents end_turn while teammates are active
• Teammate completion callbacks that trigger new turns in the lead's agent loop

At minimum, the current silent failure should be addressed:

• Document the limitation: The SDK features page should state that agent teams are incompatible with headless/SDK mode, not just "not directly configured via SDK options."
• Surface an error: If CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is set in headless mode, disable the tools or return a clear error rather than allowing them to silently break the session.

Reproduction

1. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in the action env
2. Include TeamCreate,TeamDelete,SendMessage in --allowedTools
3. Prompt the agent to create a team and spawn teammates with team_name
4. Observe: session exits with end_turn after teammates spawn, before any work completes

I can create a minimal public reproduction repo if needed.

Note on repo choice

I understand this likely requires changes in the Claude Code CLI or SDK rather than the action itself. I'm filing here because claude-code-action is my interface to the SDK, and this is where the limitation surfaces in practice. Happy to refile against claude-code if that's more appropriate.

Environment

• claude-code-action@v1 (v1.0.78)
• Claude Code CLI v2.1.83 (bundled)
• Model: claude-opus-4-6