Claude Code suggests non-existent "fan out subagents" command

Managed to get the exact print: Tip: Say "fan out subagents" and Claude sends a team. Each one digs deep so nothing gets missed.

Confirming the gap from the operator side and adding three concrete workarounds you can use today.
The pattern. The Tip text presents "fan out subagents" as if it were a runnable command (a slash command or recognized phrase), but the actual mechanism documented in Anthropic's sub-agents page and Advanced Patterns PDF is the parallel-Agent-call pattern. The Tip surface and the actual mechanism are decoupled: saying the phrase to Claude doesn't trigger anything the harness intercepts, and the model's response after hearing the phrase is whatever Opus 4.7 chooses to do given the conversational context — sometimes that includes parallel Agent invocations, sometimes it doesn't. The Tip is correct in spirit (the model can do this) but misleading in form (it sounds like an installed command).
Three workarounds, by escalation order:

1. Just describe the work in parallel terms. "Investigate X, Y, and Z in parallel — use three Agent tool calls" works reliably with Opus 4.7. The model honors the explicit parallelism request even without any custom configuration. Lowest setup cost; works in any session.
2. Custom slash command for repeatable fan-out. Create .claude/commands/fan-out.md (or whatever name you prefer) with something like:

``
---
description: Fan out N subagents to investigate independent aspects in parallel
---
Given the user's question, identify 3-5 independent sub-questions that can be investigated without depending on each other's results. Dispatch one Agent call per sub-question in parallel. Synthesize the returned summaries into a single coherent answer.
`
Then /fan-out` becomes a real command. This is the mechanism the docs describe but the Tip doesn't actually wire up.

1. Skill with an allowed-tools: Agent declaration. If you want the fan-out behavior to persist across sessions without re-typing the prompt, write a skill at ~/.claude/skills/fan-out/SKILL.md that the model can invoke when relevant. Skills get auto-loaded; commands need to be re-typed.

On the structural shape. This sits in the same family as a few recent issues where the model's narration of a mechanism is decoupled from what actually fires at runtime — the model says "I'll spawn 39 agents" or "use this command" and the operator's downstream behavior depends on whether they verify the surface or trust the narration. There's a cluster of six May 2026 issues on this surface for sub-agents specifically (#60987, #61102, #61107, #61167, #61315, #61405) that I wrote up at https://gist.github.com/yurukusa/9857a9ed407696ba8483b354917ff161 — your issue is the same shape one layer up (the Tip text rather than the model's per-turn narration).
The reasonable fix at the Tip layer is what you proposed in the issue: either reference the pattern descriptively without quoting a runnable phrase, or have the Tip surface a real wiring (e.g., "type /fan-out if you've installed the fan-out command, or just describe the parallel work in your prompt").
Disclosure: I sell two paid books adjacent to this analysis (Claim-Verify Handbook, Postmortems) and maintain the open-source cc-safe-setup hook library. None of the three workarounds above require any of those — they work with stock Claude Code.

Related but distinct symptom — when users attempt the documented "fan-out subagents" pattern via real Agent calls from inside a forked skill context (skill frontmatter context: fork + allowed-tools: [..., "Agent"]), every Agent call returns agent_tool_unavailable instantly, no API call made. Empirically verified on claude-opus-4-7, Claude Code on Linux devcontainer, 2026-05-28.

Workaround we tried that also failed: spawning an outer Agent() without subagent_type from main (i.e. a fork inheriting main's tool list), then having that fork spawn the specialized sub-agents. The fork refused, citing the Agent tool's own boilerplate text "If you ARE the fork — execute directly; do not re-delegate" as a hard rule against any sub-agent spawning, regardless of whether subagent_type was set or not. Net result for our skill: 0% sub-agent coverage, fallback to single-perspective manual analysis.

In current Claude Code, fan-out (parallel sub-agents) and main-context isolation appear to be mutually exclusive — spawn from main and pollute main's context, or fork and lose Agent entirely.

Two possible fixes that would unblock the documented pattern:

1. Make context: fork + Agent in allowed-tools a hard error at skill load time instead of a silent strip (the contract failure is currently invisible).
2. Allow a one-level fork to spawn sub-agents (no recursion). The "do not re-delegate" guidance reads as preventing infinite chains; explicit "one hop OK" wording would unblock the fan-out + isolation combination.

Happy to share a minimal repro if useful (custom skill + 7 agents in allowed-tools, telemetry showing all-fail with reason strings).

The context: fork + Agent mutual-exclusivity that timur-da documents above is the sharpest crystallization of this problem I've seen. The fan-out pattern (parallel sub-agents) and context isolation are both necessary for production multi-agent work, and the harness forces you to choose between them.

The three-layer taxonomy that emerges from this thread is useful for anyone working around this today:

1. Spawn from main, no isolation — Agent calls work, but every spawned sub-agent shares main's context window. Fine for small fan-outs; breaks down when parallel agents accumulate context (especially on long-running sessions or overnight runs where context saturation is the real failure mode).

1. Fork context, no sub-agents — context: fork isolates the context window but strips Task/Agent. The model's allowed-tools: All tools frontmatter promise doesn't match the runtime surface. Silent failure makes this the hardest to debug: everything looks configured correctly; the sub-agent just... doesn't spawn anything.

1. Process-level isolation — move the dispatch loop outside Claude Code entirely, use a separate process (Rust/Python/Node) to manage agent lifecycle, pass work via file-based handoffs or structured stdin. This is what resolves the mutual-exclusivity: isolation lives in the OS process boundary, not in the Claude Code fork primitive, so Agent calls inside each top-level session are unaffected.

The third approach works, but it means every operator who needs both isolation and fan-out has to re-implement the same scheduling, lifecycle, and handoff machinery from scratch. The pattern has converged independently across several teams by now — which is usually a sign the tooling should absorb it.

One concrete suggestion for joeedh's original issue: if the Tip text is changed to reference the real mechanism, it should distinguish these three shapes, because "fan out subagents" means different things depending on whether isolation matters for your use case. The tip as written implies a single action; the actual space has at least three architecturally-distinct configurations with different cost and correctness profiles.

+1 on this - i'm curious how repeatable this pattern actually is and why it warrants a tip if it isn't actually triggering a specific workflow or process under the hood

I also ran into this.

The tip:

"Say 'fan out subagents' and Claude sends a team"

sounds like a real built-in command or trigger phrase, but in practice it seems to be describing a pattern rather than an actual shipped command.

I think the tip should be reworded to describe the capability more accurately, or point to the real mechanism (custom slash commands, skills, or explicit parallel Agent calls).
My personal suggestion is that CLI tips should avoid quote-style phrasing unless the quoted text is actually a real supported command or trigger. Otherwise, users will naturally interpret it as something they can type verbatim and expect the product to handle.

no /fan-out command exists. it's just multiple Agent tool calls in one turn that run in parallel. docs frame it as a pattern, not a builtin.

Tip: Say "fan out subagents" and Claude sends a team. Each one digs deep so nothing gets missed.