[BUG] In-process team agents lack the Agent tool (cannot spawn subagents)

[marcoabreu]

Description

Team agents spawned with the default --teammate-mode in-process do not have the Agent tool in their available toolset. This prevents them from spawning subagents (e.g., Explore, Plan, or general-purpose agents).

Using --teammate-mode tmux resolves the issue — teammates get full tool access including Agent. This suggests the restriction is specific to the in-process backend, not an intentional design constraint.

Reproduction

1. Create a team and spawn a named team agent (any subagent_type):

TeamCreate(team_name="test-team")
Agent(
  name="worker",
  team_name="test-team",
  subagent_type="general-purpose",
  prompt="Search your deferred tools for 'Agent' using ToolSearch, then report whether it exists."
)

2. The spawned agent will report Agent is not in its deferred tools list.
3. Repeat with mode: "bypassPermissions" — same result.
4. Repeat with a custom agent definition that has no tools: restriction in front matter — same result.
5. Switch to --teammate-mode tmux — the agent now has Agent in its toolset and can spawn subagents.

Tested Configurations (in-process mode)

Variant	Agent tool available?
Default mode	No
mode: "bypassPermissions"	No
Custom agent, no tools: in front matter	No
Custom agent with model: opus	No
Built-in general-purpose subagent_type	No

Impact

In the main session, the standard efficiency pattern is to delegate broad exploration to cheap Haiku subagents:

• "Explore the codebase for all implementations of X" → Haiku scans 50 files, returns 5 relevant locations
• "Read these 20 files and summarize patterns" → Haiku batch-reads, returns a digest

Inside in-process team agents, this pattern breaks. An Opus team agent that needs to explore the codebase has to do all grepping, globbing, and file reading directly in its own context window — consuming expensive tokens on mechanical work that a Haiku subagent could handle.

This makes in-process mode significantly less cost-efficient than tmux mode for non-trivial team workflows.

Expected Behavior

In-process team agents should have the Agent tool available, matching the behavior of tmux-mode teammates. If there's a technical reason this can't work in-process, it should be documented.

Environment

• Claude Code v2.1.71
• macOS (Darwin 24.5.0)
• Model: Claude Opus 4.6

[justyn]

I've confirmed this on my system. The lack of subagents, Explore etc for in-process teammates is a pretty significant limitation.

[yurukusa]

Workaround: ensure the Agent tool is available by declaring it in the agent definition's tools frontmatter:

---
name: team-lead
tools: [Agent, Bash, Read, Edit, Write, Grep, Glob]
---
You are a team lead. Use the Agent tool to delegate subtasks.

If the Agent tool is still missing, a UserPromptSubmit hook can inject a reminder:

jq -n '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"The Agent tool is available for delegating subtasks to specialized subagents."}}'
exit 0

[AstroMined]

Adding a fresh data point with a real-world impact measurement.

Environment: Claude Code 2.1.114 on both hosts (Mac: Darwin 25.4.0 / macOS 14, Linux: dev-server). CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 set on both. Mac launched under iTerm2, dev-server over SSH (no TMUX integration available).

Four-cell test (Mac iTerm/TMUX backend vs Linux in-process backend, bypass vs auto permission modes)

Host	Backend	Permission mode	Teammate immediate tools	Agent present
Mac	iTerm/TMUX	bypassPermissions	Agent, Bash, Edit, Glob, Grep, Read, ScheduleWakeup, Skill, ToolSearch, Write	yes
Mac	iTerm/TMUX	auto	Agent, Bash, Edit, Glob, Grep, Read, ScheduleWakeup, Skill, ToolSearch, Write	yes
Linux	in-process	bypassPermissions	Bash, Edit, Glob, Grep, Read, Skill, ToolSearch, Write	no
Linux	in-process	auto	Bash, Edit, Glob, Grep, Read, Skill, ToolSearch, Write	no

Permission mode is not a factor. ScheduleWakeup is also missing from the in-process teammate roster. On Linux the deferred roster (via ToolSearch) likewise has no Agent, so teammates have no path to subagent spawning at all.

Silent failure mode

The teammate does not receive an error when it would otherwise call Agent. The tool is simply absent from its schema, so the call is never attempted. Downstream orchestrator skills that expect teammate-level fan-out fall back to doing the work themselves in-band. There is no log, no warning, no hint that a level of parallelism was lost.

Real workflow impact

A production orchestration skill I run (/implement-feature) uses a 2-level nesting pattern: team lead spawns one teammate per epic, each teammate spawns anonymous subagents per task in a wave (typically 6-10 subagents per wave, 2-3 waves per epic, 3-5 epics per feature). End-to-end runtimes:

• Mac iTerm/TMUX backend: 1 to 2 hours per feature
• Linux in-process backend: 7 to 8 hours per feature

Roughly 4-5x regression, driven entirely by the collapse of teammate fan-out into serial in-band work on the lead. I verified this against the session transcript: every Agent tool call in the Linux run originated from isSidechain: false (the main thread); zero spawns came from teammates.

Note on the tools: frontmatter workaround

The workaround above (declare Agent in a custom agent definition's frontmatter) only applies to custom agents in .claude/agents/. It does not expose Agent to subagent_type: "general-purpose" teammates, which is what orchestrator skills commonly spawn when they need a full-capability worker without a bespoke role. The general-purpose teammate roster appears to be hard-coded at the backend level.

Supporting a matching roster on the in-process backend (or at minimum allowing general-purpose teammates to inherit Agent when the parent had it) would close this cleanly.

[Butanium]

Filed a closely-related bug at #54827: in-process teammates also lack extended thinking, not just the Agent tool. Same architectural pattern (in-process teammate = subagent-in-disguise), so the fix space probably wants to address both together.

Concrete measurement: same project, same Opus 4.7 model — team lead session had 112 thinking blocks across 74 assistant turns; in-process teammate spawned via Agent(team_name=...) had 0 thinking blocks across 96 assistant turns. Tmux-backed teammates do get thinking, so the inconsistency is purely backend-driven.

[kcarriedo]

@AstroMined's four-cell table and @Butanium's "0 thinking blocks across 96 assistant turns" measurement together do a much cleaner job of nailing this to the in-process backend than any single repro alone — the consistency across backends-only (not permission-mode, not OS, not agent definition) is the load-bearing signal.

A few things worth adding from running both topologies in production-shape setups:

1. The cost-efficiency framing in the original report is the buy-line for prioritization. Opus-tier in-process teammates that can't delegate cheap exploration to Haiku subagents end up burning context-window and dollars on grep/glob/read work that a single Agent(subagent_type="general-purpose", model="haiku") call would handle. We've measured ~3–5× token-cost overhead per teammate task in the in-process-only configuration vs. the tmux-mode control, on the same project. That's not a polish issue, it's an architectural regression for any team where Opus pricing matters.

2. The "silent failure mode" call-out from @AstroMined is the part that breaks orchestration. When the tool is absent from the schema rather than failing at call time, the model can't fall back — it just inlines the work. Skills written against tmux-mode teammates (where Agent is present) will silently degrade to inlined work when run in-process, with no log trace. This is the same failure shape as #54018 and #54879 (silent harness-side behavioral divergence vs. explicit error signal). A schema-level "tool unavailable" entry the model could read would let the skill author write a graceful-degradation branch instead of an invisible cost cliff.

3. @Butanium's thinking-blocks measurement (#54827) is probably the same fix space. If in-process teammates are running on a strict subset of the harness's main-session tool/feature surface (no Agent, no ScheduleWakeup, no extended thinking), the question is whether that subset is intentional or a backend-feature-gap. The original report's "tmux mode has it, in-process doesn't" framing suggests gap, not policy.

4. @yurukusa's tools: [Agent, ...] frontmatter workaround: confirmed it doesn't help in our testing — declaring the tool doesn't add it to the in-process schema, because the gap is at the harness's tool-registration layer for in-process subagents, not at the agent-definition merge layer. The UserPromptSubmit hook injection is a partial mitigation (reminds the model the tool should exist) but doesn't restore actual capability.

Concrete ask for triage: feature-parity matrix between in-process and tmux backends, with each gap labeled as intentional / gap / regression. Right now community-side workarounds vary wildly because no one knows which side they're working against, and --teammate-mode tmux (a workable production answer for Mac) doesn't exist on Linux/SSH.