Source: ai-research (web research, 2026-04-11); raw/x-account-bcherny-2071647677591466098.md (X post, 2026-06-29 — background-by-default default flip); Claude Code release notes v2.1.246–v2.1.280 (raw/anthropic-watch-claude-code-tag-v2-1-{246,247,277,280}.md, ai-research/claude-code-release-v2-1-{248,251,257,260,261,271}.md) for the 2026-08/09 configuration changes Type: Product Feature Product: Claude Code

Subagents are isolated Claude instances spawned by a main session to handle specific tasks independently. Each subagent gets its own context window, custom system prompt, and scoped tool access. They run in parallel, return only their summary/results, and keep the main context window clean. This is the workhorse pattern for scaling Claude Code work.

How subagents work

  • The main session spawns one or more subagents, each with a defined task
  • Each subagent gets its own context window — isolated from the parent and from each other
  • Subagents can have different permissions: read-only, research-only, or full editing access
  • Custom system prompts scope each subagent to its specific task
  • Results flow back to the parent session as summaries — raw context is discarded
  • Multiple subagents run in parallel for throughput

Subagent types

  • Read-only — reviewers, auditors, code analysis. Cannot modify files.
  • Research — gather information, search codebases, read documentation. Read access only.
  • Code writers — create files, execute code, make changes. Full editing permissions.

Defining reusable agents

  • Store agent definitions in .claude/agents/ for project-level shared specialists
  • These become reusable across sessions and team members
  • Each definition specifies the system prompt, tool access, and permissions

Nested subagents — depth up to 5 (2026-06-09)

[X signal — @bcherny, Claude Code creator, ~2026-06-09] Claude Code added nested subagents: a subagent can now itself spawn further subagents, instead of the prior single-level main→subagent fan-out. Deep work can decompose hierarchically — a research subagent delegates its own sub-investigations, each layer keeping its context isolated.

  • Depth cap = 5. Nesting is initially capped at five levels; Anthropic is experimenting with deeper hierarchical agents.
  • Why it matters: better context management for large tasks — each level offloads to fresh isolated contexts rather than one orchestrator holding the whole tree. Complements dynamic workflows (which orchestrate hundreds of parallel subagents from a written script) by letting any agent in the tree branch on its own.
  • First-party post from Claude Code’s creator; the exact shipping version is unconfirmed (announced alongside the ~June 9 release wave — see W25). ^[inferred — depth/version detail from a single X post; confirm against the changelog]

Background execution by default (2026-06-29)

[X signal — @bcherny, Claude Code creator, 2026-06-29] In the next version of Claude Code, subagents will run in the background by default — you can keep conversing with the main Claude instance while a subagent works, instead of the session blocking until it returns. To force a specific subagent to run in the foreground, just instruct Claude to do so.

  • Rollout: the behavior had already been rolling out gradually to a subset of users before this default flip was announced.
  • Interacting with a running background subagent: arrow-down + enter to message it while it works (per thread replies); separate tabs for background agents are coming.
  • Demand surfaced in replies (not confirmed shipping): persistence, naming, skills, directories, inter-agent communication, and a “merger” step for reconciling parallel work. ^[inferred — these are community requests surfaced in thread replies, not confirmed roadmap items]
  • First-party post from Claude Code’s creator; the exact shipping version is unconfirmed. ^[inferred — version detail from a single X post; confirm against the changelog]

Cross-provider limit: a fork must match its parent’s model (2026-08-25)

A constraint worth stating plainly because it blocks an otherwise obvious cost pattern.

  • A normal subagent starts with fresh context by design. It receives the delegated task and the applicable project instructions — not the parent conversation, and not every file the parent read. That bounded context is why subagents are good at narrow work and why their logs and side investigations stay out of the main conversation.
  • A forked subagent does receive the full conversation and can reuse the parent’s prompt cache. The trade-off: a fork must use the same model as the parent.
  • Claude Code documents how a subagent chooses its model. It does not document a separate provider address per subagent. So there is no native configuration for “the parent stays on Anthropic, but send this one child to a cheaper third-party provider.”

The consequence for anyone trying to run a cheap worker beside an expensive lead is that the supported answer is two sessions, not one delegation — an ordinary session as lead, a second session launched against the other provider as worker, an explicit written handoff between them, and a git worktree if both will edit concurrently. Full pattern: Running a Cheap Model Beside Your Expensive One. A gateway or custom integration is described as possible but is explicitly not recommended for beginners in that source.

Field report: effort level can multiply subagent count (2026-08-25)

An r/ClaudeCode post (score 20, 18 comments) reports asking for an xhigh /code-review on a 430-line script and Claude “immediately trying to spawn 10 Fable-level subagents.” The poster stopped it at five, by which point it “had already burned through almost 200k tokens.”

Recorded as an unverified single field report, but the shape is plausible and the lesson is cheap: raising review effort raises fan-out, and fan-out at a frontier model is the expensive axis — the cost is roughly effort × agents × model price, not effort alone. Match the review depth to the size of the diff, not to the importance you feel about it. See Model vs. Effort.

Configuration changes, August–September 2026 (v2.1.246–v2.1.280)

Model routing — CLAUDE_CODE_SUBAGENT_MODEL changed meaning.

  • 2026-08-28 — v2.1.251: CLAUDE_CODE_SUBAGENT_MODEL now sets the default subagent model rather than overriding everything; an agent definition’s model: and an explicit per-spawn model take precedence over it.
  • 2026-09-01 — v2.1.257: CLAUDE_CODE_SUBAGENT_MODEL_FORCE restores override-everything: it applies CLAUDE_CODE_SUBAGENT_MODEL (or the main model) to every subagent, ignoring per-spawn and agent-definition model overrides.
  • v2.1.247: a subagent whose first call hits a model 404 now uses the session’s fallback model chain instead of dying.

Context — run a subagent without CLAUDE.md.

  • 2026-09-14 — v2.1.271: omitClaudeMd in agent frontmatter and --agents JSON lets custom and plugin subagents run without user, project and local CLAUDE.md files; managed policy files still load. Useful for narrow reviewers or linters that don’t need project conventions.
  • v2.1.248: agent frontmatter experimental.cacheTtl ("5m" or "1h") sets a per-agent prompt-cache TTL when no subagent TTL setting is configured.
  • v2.1.261: --append-subagent-system-prompt-file reads the subagent system prompt from a file, for prompts too large for the command line.

Safety — subagent output can’t pass as instructions.

  • v2.1.271: in auto mode, a subagent reports back to its caller through a dedicated hand-back call that the safety classifier reviews, instead of its last message being reviewed after the fact.
  • v2.1.277: subagent results reach the main agent under a header marking them as subagent output, with the result indented, “so text in a subagent’s result cannot pass as the session’s own instructions”.
  • v2.1.251: messages from your own subagents are framed as coming from a worker inside this session, not an unrelated Claude session.

Lifecycle and messaging.

  • v2.1.246: a subagent that stops at its maxTurns limit returns its output marked partial, with a hint to continue it via SendMessage, instead of appearing finished.
  • v2.1.248: SendMessage from a subagent to another session notes that any reply goes to the parent session’s conversation, not to the subagent.
  • v2.1.251: background subagents can reply to a message from an unnamed sibling or parent agent.
  • v2.1.257: subagents automatically continue after a response is cut off mid-stream; v2.1.260: a subagent that resumed another via SendMessage is woken on its completion, and background commands started by subagents no longer have a one-hour limit.
  • v2.1.280: background subagents can use the LSP tool; resumed fork subagents keep their original tool list, preserving the prompt cache.

Digests: W35 · W36 · W38 · W39.

Subagent effort default (v2.1.316, 2026-10-31)

  • CLAUDE_CODE_SUBAGENT_EFFORT sets the effort level subagents run at when nothing else names one. Without it, subagents inherit the session’s effort.
  • v2.1.316 also fixed sub-agents that inherited a parent sub-agent’s model moving to the main model when a background job or message woke them.
  • Source: the v2.1.316 release; see What’s New — Week 44.

Community pattern: a dashboard subagent for long runs (2026-09)

A widely saved X post (@Voxyz_ai, 3,861 likes / 9,881 bookmarks, raw/x-bookmarks-recent-digest-2026-09-29.md) packages “watch without interrupting” as a reusable subagent:

  • Definition. A dashboard-builder agent in ~/.claude/agents with model: opus, effort: medium, memory: user, and an installed design skill preloaded. It may only read and write .dashboard/ and its own memory. Both effort and memory are documented subagent frontmatter fields (memory: user stores learnings in ~/.claude/agent-memory/), checked against the Claude Code subagents docs on 2026-09-29.
  • First run. It asks your style (dark/light, dense/airy, one accent colour) and saves the answer to its memory.
  • Trigger. A ~/.claude/CLAUDE.md rule: for any task with more than 5 steps or likely to take over 30 minutes, have it set up the dashboard before starting and update it after every step.
  • Output. One self-refreshing HTML file (10-second refresh) showing tasks and status, questions waiting on you with the default action it will take, latest deliverables, and anything stuck. The main session keeps working and proceeds on the defaults.

This is a single community recipe, not an Anthropic pattern. Its useful idea is the question queue with stated defaults, which lets a long run keep going without blocking on you.

Key Takeaways

  • CLAUDE_CODE_SUBAGENT_MODEL is a default, not an override (v2.1.251, 2026-08-28). An agent’s model: wins; set CLAUDE_CODE_SUBAGENT_MODEL_FORCE (v2.1.257) for the old behaviour.
  • omitClaudeMd (v2.1.271) runs a subagent without user/project/local CLAUDE.md; subagent output now arrives under a subagent-output header (v2.1.277).
  • Nested subagents (2026-06-09): subagents can now spawn subagents, capped at depth 5 — hierarchical decomposition with per-level context isolation
  • Background execution by default (2026-06-29): subagents run in the background by default in the next Claude Code version — you keep working with the main instance while they run; instruct Claude explicitly to force a subagent to run in the foreground instead
  • Subagents keep the main context window clean by offloading work to isolated instances
  • Different permission levels (read-only, research, code writer) control what each subagent can do
  • Parallel execution means 3 subagents finish roughly 3x faster than sequential work
  • Reusable agent definitions in .claude/agents/ create project-level specialists
  • Subagents do NOT communicate with each other — use Agent Teams when peer coordination is needed. (Dated note, 2026-09-29: this was true when written in April. By August–September 2026 the release notes describe subagents messaging and resuming other agents via SendMessage (v2.1.246, v2.1.251, v2.1.260), so read this as “subagents have no built-in coordination model” — Agent Teams is still the structured option.^[inferred])
  • Custom system prompts + scoped tool access = precise control over each subagent’s behavior

Try It

  1. In Claude Code, ask for a task that benefits from parallelism (e.g., “Audit the security of the auth module while simultaneously writing tests for the payments module”)
  2. Observe how Claude Code spawns subagents with appropriate permissions
  3. Create a reusable agent: add a YAML file to .claude/agents/ with a specialist definition (e.g., security-reviewer.yml with read-only permissions and a security-focused system prompt)
  4. Use subagents liberally for research tasks — “have a subagent investigate how the caching layer works while I continue implementing the feature”

Update (2026-11-11): the built-in Explore subagent follows your session model

Anthropic’s model-choice playbook (claude.dev, 2026-11-09) says: “In current versions of Claude Code, the built-in Explore subagent runs on your session’s model instead of always running on Haiku. On the Claude API, that model is capped at Opus.” To keep exploration cheap, define your own subagent named Explore with model: haiku; CLAUDE_CODE_SUBAGENT_MODEL sets the default for subagents without a model. See Claude Fable 5.2 + Mythos 5.2.

Open Questions

  • Can a gateway give one subagent a different provider? Described as possible in the 2026-08-25 source but not detailed, and explicitly not recommended for beginners. Untested here.

  • What actually drives subagent fan-out at high effort? The 10-subagents-on-430-lines report is a single unverified case. Whether fan-out scales with effort, with diff size, with both, or is non-deterministic is undocumented.

  • What is the maximum number of concurrent subagents before performance degrades?

  • Partially resolved 2026-07-16: Anthropic’s steering-Claude-Code post confirms only the subagent’s final message (summary plus metadata) returns to the parent session — the larger instructional body never enters it at all — but doesn’t quantify a token ceiling on that returned summary, so “how much context can a subagent return before the parent is impacted” remains open as a quantitative question.

  • Can subagent definitions in .claude/agents/ reference MCP servers or skills?

  • What Claude Code version number ships background-by-default subagent execution, and is the rollout fully complete or still gradual?