Claude Code subagents: the 2026 production playbook (with examples)

Claude Code subagents are isolated Claude instances that the main session spawns to work in parallel, each with its own context window, its own tool permissions, and its own model. The lead agent sees only each subagent's final summary, never its intermediate steps, which keeps the main transcript clean for orchestration. As of August 2026, Claude Code ships built-in subagent types, supports nested subagents (agents that spawn agents, capped at depth 5), and lets a lead plan and fan out tens to hundreds of parallel subagents through Dynamic Workflows, with a Performance Outcomes grader that sends each result back to revise until it meets a rubric. This guide is the 2026 production playbook for Claude Code subagents: what they are, a starter roster of examples, when to spawn one, how to scope its tools, how to gate output with a SubagentStop hook, and how to combine subagents with Skills and Hooks. It is the third piece in our trilogy of Claude Code production playbooks, following the Claude Code Skills production playbook and the Claude Code hooks production playbook.

Quick Answer

• A Claude Code subagent is a fresh Claude instance the main agent spawns, with its own context window, its own tools, and its own model. The lead gets only the subagent's final summary back.
• You create one by dropping a markdown file into .claude/agents/ with frontmatter for name, description, tools, and model; the lead reads the description to decide when to delegate. Claude Code also ships built-in types (Explore, general-purpose, Plan) you can use without defining anything.
• Common examples: an explorer for read-only search, a code-reviewer, a test-writer, a doc-writer, and a migration-writer. A focused roster of five to seven scoped specialists beats one do-everything agent.
• Subagents inherit the lead's current model by default in 2026, so set the model field explicitly (for example claude-haiku-4-5 for cheap triage). Nested subagents are supported up to depth 5, and every subagent should be paired with a SubagentStop hook that enforces non-negotiables before the lead folds a result back in.
• The decision rule we ship: Skill teaches the how, Hook enforces the rule, Subagent isolates the work. Use all three together for production agent setups.

> Updated August 11, 2026: refreshed with Claude Code's built-in subagent types, nested subagents (depth 5), the 2026 model-inheritance default, and a copy-ready starter roster of example subagents.

What a Claude Code subagent actually is

A subagent is not a thread, a fork, or a sub-routine. It is a fresh Claude instance that the lead agent spawns inside the same session. Each subagent gets:

• Its own context window, so the lead's already-crowded transcript stays clean.
• Its own tool permissions, so a research subagent cannot accidentally write files and a writer subagent cannot accidentally hit production APIs.
• Its own system prompt, so you can specialise behaviour (a security-review subagent acts differently than a feature-writer subagent).
• Optionally its own model, so a cheap fast model can do triage and a stronger model can do the hard work.

The lead never sees the subagent's intermediate steps. It receives a single summary back, the way a tech lead receives a pull-request description from a delegate. That asymmetric information flow is the whole point: it keeps the lead's reasoning room free for orchestration, not for re-reading grep output.

In practice you create a subagent definition by dropping a markdown file into .claude/agents/ with frontmatter for name, description, tools, model, and a system-prompt body. The lead reads the description string to decide when to delegate, the same way it reads tool descriptions to decide when to call a tool. If you want the official primer alongside this playbook, Anthropic's Introduction to Subagents course walks through creating one from scratch.

Built-in Claude Code subagent types

You do not have to define every subagent yourself. As of 2026 Claude Code ships a small set of built-in subagent types the lead can delegate to out of the box:

• Explore: a read-only search agent for fanning out across a large codebase. It reads excerpts rather than whole files and runs on a fast, cheap Haiku-class model, so broad discovery does not burn your main budget.
• General-purpose: a full-capability worker for multi-step tasks that need to search, edit, and run commands.
• Plan: a read-only architect that designs an implementation strategy and returns a step-by-step plan without touching files.

Built-in types cover the common cases. You define custom subagents in .claude/agents/ when you need a fixed system prompt, a specific tool scope, or a pinned model that the built-ins do not give you.

When to use a subagent (and when not to)

Subagents are a heavy mechanism. Each one costs a full context window and adds round-trip overhead. Use them when the savings outweigh the cost. Skip them when a Skill or a tool call would do the same job.

Situation	Use a subagent	Use a Skill or tool instead
Five independent investigations (auth, db, api, infra, frontend)	Yes, one per area, in parallel	No, one transcript would interleave them
One file edit, one test run	No, lead can do it	Yes, no isolation benefit
Long-running scan that returns a 200-line report	Yes, summary-only return is the win	No, the lead does not need to read the scan
Repeated procedure (e.g. "always lint before commit")	No, this is a Skill	Yes, a Skill makes the lead consistent
Hard rule (e.g. "never push to main")	No, this is a Hook	Yes, a Hook enforces it deterministically
Refactor that touches 30 files in 6 modules	Yes, one subagent per module	No, single-context refactors lose track

Three to five concurrent subagents is the sweet spot for most jobs. Beyond that you spend more time merging summaries than you save by running them in parallel. The 2026 Dynamic Workflows release lets the lead push that ceiling to tens or hundreds for tasks that genuinely fan out, like running a benchmark suite across 80 model-prompt combinations, but for everyday work the three-to-five rule still holds.

Claude Code subagents examples: a starter roster

The fastest way to get value is to copy a small roster of specialists into .claude/agents/. Here is the set we run internally, each with a single job, the minimum tools for that job, and a fixed return shape the lead can merge.

Subagent	Job	Tools	Model	Returns
explorer	Read-only codebase and web discovery	Read, Grep, Glob, WebSearch	haiku (fast)	A map of where the relevant code lives
code-reviewer	Security, dead code, and rule violations on a diff	Read, Grep, Bash	haiku	pass/fail plus file:line findings
test-writer	Write and run tests for a changed module	Read, Edit, Bash	sonnet	Coverage summary plus pass/fail
doc-writer	Update README and changelog from a merged diff	Read, Edit	haiku	The edited files plus a one-line changelog
migration-writer	Author a schema migration behind a Skill	Read, Edit, Bash	sonnet	"migration ready" or "tests failed at step N"
build-runner	One Totalum app build per subagent via MCP	Totalum MCP, Bash	sonnet	A deploy URL once the SubagentStop gate is green

What makes a roster work is not the number of agents. It is that each one has a single job, the smallest tool scope that job needs, and a predictable return shape. A tight five-to-seven-agent roster beats one general agent asked to do everything, and it beats a sprawling thirty-agent swarm that steps on its own edits. Start with the explorer and the code-reviewer; they pay for themselves in the first week.

The trinity: Skills, Hooks, and Subagents in 2026

Skills and Hooks are the other two production primitives. Subagents close the loop. The decision rule we use internally at Totalum:

Primitive	What it does	When the lead reaches for it
Skill	Teaches the lead a procedure	"I know what good looks like for this task, I want the lead to follow it every time"
Hook	Enforces a rule outside the model	"There is a non-negotiable I cannot trust the lead to remember"
Subagent	Isolates a unit of work	"The lead should not see the inside of this work, only the outcome"

A Skill alone is a polite suggestion. A Hook alone is a rule with no taught procedure. A Subagent alone is delegation without enforcement. The combination is what makes the setup production-grade.

A concrete example. We have a Skill that teaches the lead our database-migration procedure. We have a Hook that runs SubagentStop and fails the subagent's return if the test suite did not pass. We have a Subagent definition for migration-writer that spawns whenever the lead is asked for a schema change. The lead delegates the work, the subagent follows the procedure, the hook enforces the gate, and the lead only sees a clean "migration ready" summary or a clean "tests failed at step 3" failure. Nothing in the middle.

Spawning subagents in parallel

The single phrase that matters is "in parallel using separate subagents." If you do not say parallel, Claude Code will sometimes run the work sequentially, which defeats the purpose. Explicit prompt patterns we use:

• "Research the auth, database, and API modules in parallel using separate subagents. Return a one-paragraph summary per module."
• "Refactor the 6 service files in the billing/ directory in parallel using separate subagents. Each subagent owns exactly one file."
• "Run the benchmark suite across these 8 prompt variants in parallel using separate subagents. Score each on accuracy and latency."

Inside Dynamic Workflows the lead can decide the parallelism itself. You can write a prompt like "decide how to parallelise the refactor and execute it" and the lead will plan, fan out, collect, and verify. The Performance Outcomes grader sits on top: you supply a rubric ("all tests pass, no new TODOs introduced, no public API changes"), and each subagent's result is graded in a separate context window. A failure sends the subagent back to revise. This is what bumped Anthropic's reported task-success rate by up to 10 points on the hardest internal benchmarks.

Three rules of thumb for parallel spawning that hold even with Dynamic Workflows:

1. Independent units only. Two subagents writing to the same file at the same time will race. Plan the partition before you fan out.
2. Per-subagent scope, per-subagent tools. A research subagent gets read-only file tools and web search. A writer subagent gets Edit and Bash but not network. Tight scopes mean one bad subagent cannot poison the rest.
3. Bounded summaries. Tell each subagent the exact shape of the summary you want back. The lead has to merge them, so consistent shapes save a second pass.

Effort level is the other lever here, and it changed with the current model: see our Claude Opus 5 guide for why running an orchestrator at high effort while subagents run at low effort is now the recommended cost structure.

Nested subagents: agents that spawn agents

Claude Code supports nested subagents: a subagent can itself spawn subagents, capped at depth 5 in 2026. This is what lets you hand off a whole project to a lead that spins up module owners, each of which spins up its own file-level workers. Nesting is powerful and easy to abuse. The teams that win with it are not the ones running the most agents; they cap and scope. Two rules keep nesting safe:

1. Cap the depth you actually need. Two or three levels covers almost every real project (lead to module owner to file worker). Depth 5 exists for genuinely deep fan-out, not as a default.
2. Budget context and cost at every level. Each level multiplies token spend. A lead that unleashes a swarm without caps will burn through context and money while the agents quietly step on each other's work. Scope each level to independent units and gate every return.

Gating subagent output with a SubagentStop hook

The SubagentStop hook fires when a subagent finishes and before its summary reaches the lead. In 2026 the hook payload includes hookSpecificOutput.additionalContext, so you can extend the subagent's turn with new context instead of treating the hook as a binary error. Common patterns:

• Test gate. Run the test suite. If it fails, return exit 2 with a message; the subagent is sent back to fix it. If it passes, return exit 0 with an additionalContext message that says "tests passed at commit abc123" so the lead has audit-trail context.
• Secret scrubbing. Grep the subagent's diff for API keys, JWTs, and connection strings. Block the return if any are found.
• Out-of-scope write block. If the subagent was meant to edit billing/ but its diff touches auth/, block the return and ask the subagent to restate its plan.
• Style enforcement. Run ruff format and eslint --fix. Re-run the diff check. Block if files were modified outside the subagent's stated scope.

A minimal SubagentStop hook in shell:

#!/usr/bin/env bash
set -euo pipefail
if ! pytest -q; then
  echo "tests failed; subagent must fix before returning" >&2
  exit 2
fi
if git diff --cached | grep -E 'sk-[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}'; then
  echo "secret detected in subagent diff" >&2
  exit 2
fi
echo '{"hookSpecificOutput":{"additionalContext":"tests passed, no secrets in diff"}}'

Pair that file path with the subagent name in your hooks configuration. The lead never sees the test output, just the gate result and the additional-context line.

A real subagent definition we use at Totalum

Here is a trimmed code-reviewer subagent definition we run internally. It is the kind of thing that pays for itself the first week.

---
name: code-reviewer
description: Review a pull request for security issues, dead code, and rule violations. Use after the feature subagent finishes its edits.
tools: Read, Grep, Bash
model: claude-haiku-4-5
---

You review pull requests for one purpose: catch what a tired tech lead would miss. Focus on:
1. Security: secrets, SSRF surfaces, SQLi, unsafe deserialization.
2. Rule violations: forbidden imports, missing migrations, schema drift.
3. Dead code: functions added in this diff that are never called.

Return a single markdown block:
- VERDICT: pass | fail
- Findings: bulleted, file:line specific
- Suggested fixes: one line per finding
Do not fix anything yourself. The lead decides what to apply.

We spawn this subagent automatically whenever the lead is about to mark a feature subagent's work as done. The feature subagent does the work, the reviewer subagent catches the issues, the SubagentStop hook enforces the test gate, and the lead sees three clean lines: feature done, reviewer pass, gate green. Note the explicit model line; without it the reviewer would inherit whatever model the lead is running, which is the most common cost surprise in 2026 (see the failure modes below).

Subagents and the Claude Agent SDK

If you are building your own agent surface (a SaaS embed, a CLI, an internal tool), the same primitives are available through the Claude Agent SDK. You declare subagent specs the same way, you supply your own hook scripts, you control the model selection per subagent, and you get the same Dynamic Workflows fan-out for free if the lead is a 4.7-class model.

A common SDK pattern we see in production: the parent application boots a lead agent for an end-user request, the lead spawns three parallel subagents (research, draft, review), each subagent has scoped tools matching what the user has paid for, and a SubagentStop hook gates anything that touches billable resources. Everything billed is gated, everything gated is logged, and the lead's context stays focused on coordination.

For Claude Code itself, the SDK is what powers Cline, Codex, and the other surfaces. If you have been comparing tools, the Cline vs Claude Code breakdown covers how subagent support differs across surfaces.

Subagents and MCP: parallel app builds with Totalum

A pattern we use ourselves: spawn one subagent per Totalum app build, each with its own MCP connection to the Totalum MCP server. The lead supplies a project list, each subagent owns one project end to end, and a SubagentStop hook verifies the deploy succeeded before returning the URL.

The fan-out shape is the obvious win. Five client apps that used to ship in five sequential sessions ship in parallel inside one. The lead reads five short summaries instead of sitting through five full build sessions. The work that used to take half a day takes the time of the longest single build.

The hook is what makes this safe. The SubagentStop hook hits Totalum's deploy-status endpoint, refuses to return until the deploy is green, and writes the URL into hookSpecificOutput.additionalContext. The lead can then update a tracker, post to Slack, or hand the URL back to the user without having to re-derive it. Subagents get far more useful once each one has the right MCP servers to call; see the best MCP servers in 2026 for the highest-leverage installs to pair with a subagent setup.

Common failure modes and how to avoid them

We have spent enough time running subagents to know the patterns that go wrong.

• Too many subagents. Past five concurrent for everyday work, the lead spends more time summarising than the parallelism saved. Plan the partition first.
• Unset model on subagents. In 2026 subagents inherit the lead's current model by default. If the lead is on Opus, a throwaway triage subagent silently runs on Opus too, at Opus prices. Set the model field on every subagent definition so cost and capability are a choice, not an accident.
• Unbounded nesting. Nested subagents make it easy to spawn a swarm five levels deep that costs a fortune and races on shared files. Cap the depth to what the task needs and scope each level to independent units.
• Shared state. Two subagents writing to the same file race. If you need cross-subagent state, write it to a designated path and let a third subagent merge it.
• Loose tool scopes. A research subagent with Edit permission will, eventually, edit. Give every subagent only the tools it needs.
• No SubagentStop gate. Without a gate, a bad subagent return becomes the lead's problem to discover. With a gate, the bad return is forced into a fix-it loop before the lead ever sees it.
• No rubric for Dynamic Workflows. If you use Dynamic Workflows without a Performance Outcomes rubric, the lead has no way to grade the fan-out and you lose the verification benefit.
• Context bloat in the subagent system prompt. Subagents are cheap on the lead's context but not on their own. Keep their system prompts tight and put procedure in a Skill instead.

For safety-first surfaces, Cursor uses a similar subagent idea: Cursor Auto-review hands ambiguous tool calls to a classifier subagent that decides allow, retry differently, or ask you. And for work that runs on a schedule instead of a developer's keystroke, our Anthropic Managed Agents production playbook extends the subagent pattern with Anthropic-owned scheduling and outcome grading.

If you are comparing editors and agents more broadly, our Cline vs Cursor comparison for 2026 covers the open-source agent versus the AI editor.

Subagents inherit the lead's model by default, so the model you pick sets the cost of every worker. Our guide to the best Claude model for coding in 2026 covers why Opus 5 is now the escalation tier and why pinning Haiku 4.5 on triage subagents keeps spend predictable.

FAQ

Are Claude Code subagents the same as the Task tool?

On the surface yes. The Task tool is the lead's way of spawning a subagent, and the subagent runs the work in its own context window. The difference is in how you scope it. A subagent definition in .claude/agents/ is a re-usable specialist with a fixed system prompt and tools. A bare Task call is ad-hoc and inherits whatever the lead happens to be doing. Use definitions for repeat work, bare Task calls for one-offs.

What are the built-in Claude Code subagent types?

Claude Code ships a few subagents out of the box in 2026: an Explore type for read-only codebase and file discovery (it reads excerpts and runs on a fast Haiku-class model), a general-purpose type for multi-step search-edit-run work, and a Plan type that designs an implementation strategy without touching files. You define your own in .claude/agents/ when you need a fixed system prompt, a tight tool scope, or a pinned model.

Can a subagent spawn its own subagents?

Yes. Claude Code supports nested subagents, capped at depth 5 in 2026. A lead can spawn module owners, and each module owner can spawn file-level workers. Nesting is powerful but easy to abuse; cap the depth to what the task actually needs (two or three levels covers most projects) and gate every return with a SubagentStop hook.

How many subagents can run in parallel in 2026?

For everyday code work, three to five is the sweet spot. With Dynamic Workflows the lead can plan and run tens to hundreds in one session for tasks that fan out cleanly (benchmark suites, programmatic edits across many independent files). Beyond that, summary-merging overhead eats the parallel gains.

What is the difference between subagents and agent teams?

A subagent is a single isolated worker the lead delegates one job to. An "agent team" is just a roster of several subagents coordinated by one lead, often nested. The mechanism is the same; the difference is scale and orchestration. A focused team of five to seven scoped subagents ships; a sprawling swarm with no caps burns context and races on shared files.

Do subagents share context with the lead?

No. Each subagent has its own context window. The lead sees only the summary the subagent returns. That is the whole point: it keeps the lead's transcript clean for orchestration.

Which model do subagents run on by default?

In 2026 subagents inherit the lead's current model unless you set the model field in the definition. That default is convenient but expensive: a triage subagent will silently run on Opus if the lead is on Opus. Pin a cheap model like claude-haiku-4-5 for lightweight work and reserve stronger models for the subagents that need them.

Can subagents call MCP servers?

Yes. Subagents inherit MCP access from the project the lead is running in, subject to the tool scope you set in the subagent definition. A subagent restricted to read-only MCP tools cannot accidentally mutate state, which is the safe default for research subagents.

Ready to build with Totalum

Totalum is an AI app builder for humans and for agents. The same primitives Claude Code uses, Skills, Hooks, Subagents, MCP, Totalum supports natively, so the agent setup you build for code carries over to the apps you build for users. If you want to try the parallel-build pattern in this post, register at totalum.app and connect your Claude Code session to the Totalum MCP server. The free tier is enough to ship a real app.