Subagents

You ask Claude to investigate how auth works across your codebase before touching it. Twenty minutes later it has read thirty files, and your window is carrying every one of them: forty thousand tokens of middleware you needed for one paragraph of conclusions. The task has not started and the session is already half spent. Lesson 1.3 diagnosed this; Claude Code ships the surgical fix. A subagent does the reading in its own context window and sends back only what survived the distillation: the summary. This lesson is how they work, the two things they are genuinely great at, the cost nobody mentions, and a bright-line rule for when to reach for one.

What a subagent actually is

A subagent is a separate agent loop with its own context window, its own system prompt, its own tool access, and independent permissions. When Claude delegates, it writes a task message describing the job; the subagent starts fresh from that message, works its own loop, and returns its final report to your conversation. Get the isolation exact, because both the wins and the costs fall out of it. A subagent does not see your conversation history, the files already read, or the skills already invoked. Per the docs, its starting context is: its own system prompt (not the full Claude Code one), the delegation message, your CLAUDE.md hierarchy, and a git status snapshot. Everything else it must gather itself.

Claude Code ships built-ins: Explore (fast, read-only, for search and codebase analysis), Plan (research for planning), and general-purpose. Explore and Plan even skip CLAUDE.md and the git snapshot to stay cheap. Claude delegates to them automatically; you have probably already seen Explore fire during a codebase question.

Custom subagents are markdown files, and the docs' code-reviewer example is the canonical shape. Save this to .claude/agents/code-reviewer.md in the practice repo:

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for
quality, security, and maintainability. Use immediately after writing
or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality
and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

The frontmatter is the control surface. name and description are the only required fields, and the description doubles as the delegation trigger, exactly like skill descriptions in 2.4; "use proactively" phrasing genuinely increases automatic delegation. tools allowlists capability: this reviewer gets read tools plus Bash and pointedly not Edit or Write, which turns "the reviewer should not fix things itself" from a request into a structural fact. model: inherit follows your session; setting haiku here is how you route bulk work to a cheaper model. Other fields worth knowing: permissionMode, maxTurns, memory (persistent notes across runs), and isolation: worktree, which gives the subagent a disposable copy of the repo. Files in .claude/agents/ are project-scoped and committed; ~/.claude/agents/ is personal and global. There is no wizard anymore (/agents retired in v2.1.198); you ask Claude to write the file, or write it yourself.

Invocation escalates in firmness: name it in prose ("use the code-reviewer subagent on my changes") and Claude usually delegates; @-mention it (@code-reviewer via the typeahead) and delegation is guaranteed; pass claude --agent code-reviewer and the whole session becomes that agent. Subagents run in the background by default now, with permission prompts surfacing in your main session, and Ctrl+B backgrounds a running task.

The two real wins, and the real cost

Win one: context isolation. The docs' framing matches this course's: use a subagent when a side task would flood your main conversation with content you will not reference again. The subagent's window absorbs the thirty auth files; yours receives four paragraphs. High-volume operations are the canonical case: "use a subagent to run the test suite and report only the failures with their error messages" keeps two thousand lines of test output out of your window permanently.

Win two: parallelism. Independent investigations can run simultaneously: "research the auth, database, and API modules in parallel using separate subagents." Three loops explore at once, and Claude synthesizes. This works exactly when the paths are independent; parallel subagents cannot see each other's findings mid-flight, so coupled questions parallelize badly.

The cost: handoff loss. Every delegation crosses a lossy boundary twice. Out: the subagent knows only what the delegation message says, and Claude writes that message, not you; the accumulated nuance of your session (the constraint you mentioned an hour ago, the approach you already rejected) does not come along unless it gets restated. Back: you receive the summary, not the reasoning; if the subagent misread something, your session inherits the conclusion without the evidence trail that would let you catch it. And fresh starts cost latency: a subagent re-gathers context your session already has. The docs' warning about results is the same cost from another angle: many subagents each returning detailed reports can fill the very window you were protecting.

That cost structure produces this lesson's position: subagents for research and review, the main thread for the edit, until proven otherwise. The argument is mechanical, not aesthetic. Research and review are compressible: their value survives summarization, because what you need is findings, not transcripts, and they suffer least from the outbound handoff since the job fits in a paragraph. Implementation is the opposite on both counts. An implementer needs the full intent of your session (everything you have decided, rejected, and clarified), which is exactly what the delegation message compresses away, and its output (a diff plus the reasoning behind it) is exactly what you should not accept in summary form. Edits also iterate; back-and-forth through a delegation boundary means re-paying the handoff on every round. So: dispatch readers and reviewers, keep the writer where the context lives. "Until proven otherwise" is earned the moment an edit is genuinely self-contained and verifiable by machine; then the boundary costs little, and Part 3's dispatch patterns build on exactly that exception.

Where it breaks

The classic failure is delegating the edit. An operator, sold on isolation, dispatches "have a subagent implement the refactor we discussed." The subagent never saw the discussion. It receives a two-line summary of an hour of decisions, re-derives the missing pieces wrong, and returns a diff that conflicts with three constraints from your session. The output looks like defiance; it is actually amnesia by construction.

The second failure is trusting the summary because it is confident. A research subagent that misread the code returns conclusions with no hedge, and your session builds on them. Countermeasure: for load-bearing conclusions, ask for the evidence inline ("report the exact file and lines that prove each claim") so the summary carries its receipts, and spot-check one.

The third is over-parallelizing: six subagents, each returning a detailed report, and your main window is fuller than if you had read the files yourself. Parallelism pays when breadth is real and reports are disciplined. Two or three focused subagents with tight reporting instructions beat six vague ones every time.

Knowledge check

Sources

• Create custom subagents (definition format, frontmatter fields, built-in agents, what loads at startup, invocation paths, background execution, patterns, choose-between guidance, code-reviewer example): https://code.claude.com/docs/en/sub-agents (fetched July 2026)
• Best practices: use subagents for investigation (context as the constraint, research delegation, verification subagents): https://code.claude.com/docs/en/best-practices (fetched July 2026)