Claude Code Subagents: A Practical Guide for 2026

Subagents vs agent view vs agent teams vs dynamic workflows

Four things in Claude Code parallelize work and people mix them up constantly. Anthropic's comparison page draws the line by who coordinates and whether workers talk to each other.⁴

Two questions settle it. Do the workers need to talk to each other? Subagents report back only to the conversation that spawned them, while teammates in an agent team share a task list and message each other directly.⁴ Do they touch the same files? Then isolate with worktrees, because agent teams do not isolate teammates automatically.⁴

For most solo work you want subagents. Agent teams solve a coordination problem you probably do not have yet. If you are running several full sessions rather than delegating inside one, that is the multi-agent dev loop pattern instead.

When delegation actually pays

Anthropic's engineering blog gives the clearest heuristic anyone has published on this: "When a task requires exploring ten or more files, or involves three or more independent pieces of work, that's a strong signal to direct Claude toward subagents."¹

Ten files. Three independent pieces. Write that on a sticky note.

The blog breaks the categories down with a signal and a benefit for each:¹

The fresh-perspective one is underrated. /clear also resets context, but you lose the history permanently. A subagent gives you the same clean slate while your main conversation survives.¹

Conversational invocation is enough to start. "Use a subagent to explore how authentication works in this codebase" works. So does asking for parallelism explicitly: "Research this in parallel. Check the API routes, database models, and frontend components simultaneously."¹ Being specific about the return format matters as much as the task, because you only get back what the subagent chose to summarize.

The built-in subagents you already use

Claude Code delegates to three built-ins automatically, plus a few helpers.²

Explore is a fast, read-only agent for searching and analyzing codebases. Write and Edit are denied. Since v2.1.198 it inherits the main conversation's model rather than always running on Haiku, capped at Opus on the Claude API.² If you want exploration to stay cheap, define your own subagent named Explore with model: haiku: a user or project subagent overrides the built-in and keeps its own model field.

Plan is the research agent used during plan mode. Same read-only tool set, and like Explore it skips your CLAUDE.md files and the parent session's git status to keep research fast and inexpensive.² Every other subagent, built-in or custom, loads both.

General-purpose handles complex, multi-step tasks needing both exploration and action. It gets every tool available to subagents.²

That CLAUDE.md exception is worth knowing if your project rules are load-bearing. An Explore agent will not have read them. Your custom review agent will.

Creating a custom subagent

Where the file goes

Subagents resolve from six locations, and higher priority wins on name collisions:²

Project subagents belong in version control so your team improves them together. Both directories are scanned recursively, so agents/review/ and agents/research/ subfolders are fine, but keep name values unique across the whole tree: identity comes from the frontmatter name, not the path, and duplicates load in filesystem read order.² Plugin subagents are the exception; a subfolder there becomes part of a scoped identifier like my-plugin:review:security.²

The frontmatter that matters

Only name and description are required. Everything else narrows behaviour:²

---
name: security-reviewer
description: Reviews changed code for injection, authz gaps, and secret leakage. Use after any change to auth, API routes, or data access.
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: default
maxTurns: 12
color: red
---

You are a security reviewer. Read only the diff and the files it touches.
For each finding, state the file, the line, the concrete attack path, and the
smallest fix. Say "no findings" rather than inventing severity.

description is not documentation. It is the routing key: "Claude uses each subagent's description to decide when to delegate tasks."² A vague description means the subagent never fires.

The fields worth learning beyond the basics:

• tools / disallowedTools allowlist and denylist. If both are set, disallowedTools applies first, then tools resolves against what remains. Both accept MCP server patterns like mcp__github to cut a whole server.²
• model takes sonnet, opus, haiku, fable, a full model ID, or inherit (the default). This is your main cost lever.²
• isolation: worktree gives the subagent a temporary git worktree branched from your default branch, cleaned up automatically if it makes no changes.² This is how you let two subagents edit files without collision.
• skills preloads full skill content into the subagent's context at startup, not just the description.²
• memory enables persistent scope (user, project, or local) for cross-session learning.²
• background: true forces the subagent to always run as a background task.²

One gotcha that costs people an afternoon: background subagents get a reduced built-in tool set. A background subagent keeps every MCP tool but only a specific list of built-ins (Read, Grep, Glob, Bash, Edit, Write, WebFetch, WebSearch, and a handful more), and Claude Code silently removes the rest.² Since v2.1.198 subagents run in the background by default, so the same definition can resolve to different tools depending on where it runs.

Getting one written

Fastest path is asking for it: describe the specialist you want and where to save it, and Claude writes the file.² Note that /agents no longer opens the creation wizard as of v2.1.198; it just prints a reminder to ask Claude or edit .claude/agents/ directly.² Claude Code watches both agent directories and picks up edits within seconds, but a brand new directory needs a restart before the watcher sees it.

Parallelism, backgrounding, and nesting

Anthropic's SDK blog states the two reasons plainly: "First, they enable parallelization: you can spin up multiple subagents to work on different tasks simultaneously. Second, they help manage context: subagents use their own isolated context windows, and only send relevant information back to the orchestrator, rather than their full context."⁵

Nesting is the 2026 change most people have not internalized. Boris Cherny announced it on X: "Just landed nested subagent support in Claude Code. Starting to experiment more with agents kicking off agents as a way to better manage context. Capped at depth=5 to start, going out in today's release."⁶

The default has moved twice since. Current state per the docs: a subagent can spawn its own subagents up to three layers below the main conversation. Versions v2.1.172 through v2.1.216 allowed five fixed layers, v2.1.217 dropped the default to one, and v2.1.219 raised it to three.² Change it in settings.json:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

Set it to 1 to turn nesting off entirely. At the depth limit Claude Code withholds the Agent tool, so the deepest subagent does its work itself and returns one summary.²

XDA Developers described the pattern that makes nesting click: "a reviewer subagent that dispatches a verifier per finding, so the intermediate output never reaches your main conversation."⁷ Only the top-level summary comes back to you.

Two more limits exist and they are separate variables:²