claude-code - 💡(How to fix) Fix Agent tool description unconditionally documents SendMessage, misleading orchestrator sessions when agent-teams is not enabled

Summary

The built-in Agent tool description recommends SendMessage for subagent continuation without noting that SendMessage is gated behind CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. In sessions where the agent-teams feature is not enabled (the default), this causes orchestrator-role agents to repeatedly believe they can:

1. Continue a running subagent via SendMessage — but the tool is not exposed in the deferred-tools list, so any attempted call fails.
2. "Resume" a completed subagent via a fresh Agent call with the same subagent_type — but the fresh call spawns a no-memory subagent. The prior-context resume path referenced in older system prompts was removed in Claude Code 2.1.77.

Both behaviors are impossible in the default configuration, yet the tool description reads as if they are available unconditionally. The result is orchestrators that silently drift: they skip re-stating context on delegation, or attempt SendMessage that fails to land.

Reproducing

Default Claude Code install, no CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS override. Run any orchestrator-style session that spawns multiple subagents sequentially. Observe the orchestrator occasionally saying things like "I'll continue the previous implementer with SendMessage" or assuming a new Agent call will "pick up where it left off."

Current text in the Agent tool description (problematic fragments)

IMPORTANT: Before spawning a new agent, check if there is already a running or recently completed claude-code-guide agent that you can continue via SendMessage.

To continue a previously spawned agent, use SendMessage with the agent's ID or name as the to field — that resumes it with full context. A new Agent call starts a fresh agent with no memory of prior runs, so the prompt must be self-contained.

Expected behavior

The description should condition SendMessage guidance on whether agent-teams is enabled. Either:

• Gate the text: only include SendMessage continuation guidance when CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set, or
• Add an explicit caveat: "SendMessage requires the agent-teams experimental feature. If CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is not set, the Agent tool is single-shot — each call spawns a fresh subagent with no memory of prior runs, and there is no mid-run communication channel. Delegation prompts must be fully self-contained."

The second claude-code-guide paragraph is also misleading even with agent-teams enabled, per #42999 (agent name silently fails; only raw ID works) — so at minimum that wording should be revised.

Related

• #42737 — SendMessage tool unavailable without agent teams feature, breaking agent resume
• #42999 — SendMessage with agent name silently fails; only agent ID works
• #48160 — Spawned subagents can't originate SendMessage despite env var set

Workaround (for prompt authors)

Projects that run orchestrator-style sessions can inject a counter-statement in their orchestrator system prompt overriding the tool description. In our setup:

The built-in Agent tool description recommends SendMessage-based continuation — ignore it. SendMessage is gated behind CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, which this project does not enable. Every Agent call spawns a fresh subagent with no memory of any prior run.

This works but shouldn't be necessary for every multi-agent project to rediscover.

Environment

Claude Code CLI (current), default settings, no CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS override.