Custom subagents — protect context with specialized delegates

Q12 · Extensibility Do you use subagents (specialized sub-agents with tool restrictions)?

Max-score answer: “Full set: code-reviewer, code-explorer, code-architect — and I know upfront what to delegate.”

Why it matters: Subagents protect main-context budget and parallelize independent research. Without them, your context fills with raw tool output.

Why this matters in 2026

Context is a scarce resource in an agentic coding session. Even with Anthropic’s 1M-token window on Sonnet 5 and Opus 4.8, long tool transcripts can crowd out the plan and relevant code before the advertised limit is reached. Anthropic’s context-engineering guidance and independent long-context research both support the qualitative point that more context is not automatically better; the degradation point varies by model, task, and harness.

Subagents can help when independent research can be summarized before it returns to the orchestrator. Delegate a call-site search to a code explorer, require a concise structured summary, and compare the result with doing the same work in the main thread. Parallel explorers can reduce wall-clock time only when the work is genuinely independent; tool latency, duplicated reads, and review overhead can erase the gain.

The rate card can favor a cheaper subagent: Haiku 4.5 is $1/$5 per MTok, while Sonnet 5 is temporarily $2/$10 through August 31 (then $3/$15) and Opus 4.8 is $5/$25. Those ratios compare equal token mixes, not whole tasks. Measure total tokens, retries, and accepted output before claiming a saving or quality equivalence.

What “max score” actually looks like

You get full marks on Q12 only when all four of these are true:

A full set of role-based subagents installed. Minimum code-reviewer, code-explorer (or Claude Code’s built-in Explore), and code-architect, plus 2–4 task-specific (e.g. migration-planner, test-author, doc-writer, sql-reviewer). They live in .claude/agents/ (project) and ~/.claude/agents/ (user), each as a single .md file with YAML frontmatter.
Tools whitelisted per subagent. A code-reviewer gets Read, Grep, Glob — no Bash, no Write, no Edit. A code-architect gets read-only plus WebSearch. A test-author gets Read, Write, Edit, Bash (scoped to test commands). Least privilege is enforced in the frontmatter, not in your head.
Models routed per subagent. Explorers, reviewers and bulk-scan agents on claude-haiku-4-5-20251001. Architects and planners on claude-opus-4-8. Test-authors and refactor-bots typically on claude-sonnet-5. The orchestrator stays on Sonnet and decides who to delegate to. That routing holds even if you move the main session up to Claude Fable 5 (the new tier above Opus 4.8, released June 9, 2026): pinned subagents stay on Haiku/Sonnet/Opus. This containment is exactly what makes a Fable 5 default affordable when velocity and quality outweigh budget.
You can name, upfront, what gets delegated. Before you ship a task, you’ve already decided which steps the main agent does itself and which it fans out. “Map the call sites” → explorer. “Review this diff” → reviewer. “Design the migration plan” → architect. If you’re inventing the delegation mid-task, you don’t have a strategy — you have a toy.

Anything less — “I have one custom agent I never use”, “I rely on the built-in general-purpose agent for everything”, or “I let the model decide whether to subagent” — is mid-tier on Q12.

Current landscape (web-search-verified)

Claude Code built-ins (Explore, general-purpose)

Claude Code ships with two subagent-like primitives out of the box, and you should know both before you build your own.

Explore. A built-in subagent specialized for codebase reconnaissance — file discovery, call-site mapping, “where is feature X implemented” questions. Explore is invoked automatically when the orchestrator decides it needs a read-only sweep, and it returns a structured summary instead of raw file contents. This is the agent that single-handedly protects your context from the “I just read 40 files to find one function” anti-pattern.
General-purpose. The catch-all Task agent. Useful when you want fan-out without authoring a custom agent yet, but it has no role specialization and no tool restrictions — which means it can do anything and therefore tends to do too much. Treat it as a temporary scaffold while you write the proper specialized agent.

Both are fine as defaults, but neither replaces a curated set. The whole point of Q12 is that you have decided what your common delegations are and codified them.

Custom subagents in `.claude/agents/` (markdown frontmatter spec, tools whitelist)

Custom subagents are markdown files with YAML frontmatter. Two locations:

.claude/agents/<name>.md — project-scoped, checked into the repo, available only in this project.
~/.claude/agents/<name>.md — user-scoped, available in every project.

Project-scoped wins on collision. Claude Code reads the agent file at session start. Claude Code v2.1.198 removed the /agents wizard, so ask Claude to draft the definition or edit .claude/agents/*.md directly.

The frontmatter spec, with everything that actually matters:

---
name: code-reviewer
description: Reviews diffs against project style and architecture rules. Read-only.
tools: Read, Grep, Glob, WebSearch
model: claude-haiku-4-5-20251001
memory: user
---

# code-reviewer

You are a senior reviewer for this TypeScript/Next.js codebase. When invoked
on a diff or a set of changed files:

1. **Map the change.** Use Grep/Glob to find every call site touched by the
   diff. Read enough surrounding code to understand the contract, not the
   whole file.

2. **Score against the rules.** Apply, in order:
   - The project's CLAUDE.md style rules (single quotes, import ordering,
     interface for object shapes).
   - The relevant skill (if any) under .claude/skills/.
   - Standard quality: dead code, missing error paths, leaky abstractions,
     test coverage on changed branches.

3. **Return a structured summary.** Top section: must-fix items with file:line.
   Middle: nits and style. Bottom: praise-worthy choices (so the orchestrator
   knows what to keep). Never paste the whole file back — return diff hunks
   or line ranges only.

Hard rules:
- You have no Write/Edit/Bash. Do not propose to run anything.
- If you find a structural problem requiring an architectural decision, stop
  and surface it. Do not redesign — that's the code-architect's job.

Fields that matter most:

tools — comma-separated allowlist. If missing, the subagent inherits all tools from the orchestrator — the default that gets people in trouble. Always set it. Common patterns: Read, Grep, Glob for read-only; add Write, Edit, MultiEdit for editors; add Bash(npm test:*) for narrowly-scoped runners.
model — pin the model per agent. Reviewers, explorers and bulk-scanners on claude-haiku-4-5-20251001. Architects and planners on claude-opus-4-8. Most others on claude-sonnet-5. The field also accepts the short aliases haiku, opus, sonnet, or inherit — the aliases track the latest snapshot of each tier and are the more forward-compatible choice; a fully-dated ID pins to a specific snapshot. This field is also what keeps a Fable 5 setup economical: the main loop’s default can be claude-fable-5 while every subagent’s model field keeps pointing at these cheaper tiers.
description — the first sentence is what the orchestrator reads when deciding to delegate. Lead with the verb and the scope (“Reviews diffs against project style rules”), not the role name.
memory — opts the subagent into a persistent knowledge directory across conversations. Useful for code-explorer (builds a feature map over time) and code-architect (accumulates design decisions). Don’t enable for stateless reviewers.

Cursor 3.0+ subagents

Cursor shipped first-class subagents in 2.4 and consolidated them through 3.0 (2026). Mental model is identical to Claude Code: a parent delegates to a child agent with its own context, prompt and tool restrictions. Three Cursor-specific notes:

Tool inheritance is opt-in, not automatic. Custom rules and “efficiency prompts” defined for the main agent do not propagate to subagents unless you explicitly include them. Subagent ignores your style guide because you never gave it the style guide.
You can constrain which subagent types a parent may spawn. Useful for nested orchestration: a top-level architect spawns explorers but not editors; an editor spawns a test-author but not another architect. That gives you a finite delegation tree instead of a recursive free-for-all.
Cloud subagents are first-class. Since Cursor 3.7, /in-cloud launches an isolated cloud subagent and /babysit assigns a cloud agent to prepare a PR for merge while the parent continues locally or in the cloud.

Codex multi-agent support

Codex now supports native multi-agent delegation. CLI 0.142 added thread/turn policy modes for disabled, explicit-request-only, or proactive delegation, and current Codex can run subagents in parallel and surface their progress across desktop and mobile. Repository AGENTS.md and skills can authorize delegation. The configuration model is not a drop-in copy of Claude Code’s .claude/agents/ files, so keep tool-specific agent definitions separate and document equivalent roles explicitly.

Example: a small but real set

A working set on a TypeScript/Next.js + Cloudflare repo:

.claude/agents/
  code-reviewer.md      # Haiku · Read/Grep/Glob · diffs vs CLAUDE.md rules
  code-explorer.md      # Haiku · Read/Grep/Glob · call sites & feature maps
  code-architect.md     # Opus · Read/Grep/Glob/WebSearch · plan-mode partner
  migration-planner.md  # Opus · Read/Grep/Glob/WebSearch · multi-PR migrations
  test-author.md        # Sonnet · Read/Write/Edit/Bash(npm test:*) · writes tests
  sql-reviewer.md       # Haiku · Read/Grep · D1 schema + queries review
~/.claude/agents/
  pr-writer.md          # Haiku · Read/Bash(gh,git) · drafts PR titles & bodies
  doc-writer.md         # Sonnet · Read/Write/Edit · MDX docs in project voice

Seven specialized agents covers ~90% of the delegations a real coding day will produce.

Step-by-step: building a subagent

Pick the next delegation you’re tired of doing yourself. Open your last week of Claude Code transcripts and find the task you ran more than three times. “Map every call site of X.” “Write tests for this function.” That’s your first subagent.
Create the agent definition. Ask Claude to draft the Markdown with frontmatter, or edit it directly. Use project scope (.claude/agents/) if it is repo-specific and user scope (~/.claude/agents/) if you want it everywhere. The former /agents wizard was removed in v2.1.198.
Write the description first, prompt second. The description is what the orchestrator sees when deciding to delegate. Lead with a verb and a scope (“Reviews diffs”, “Maps call sites”) — not a noun (“A reviewer agent”).
Whitelist tools explicitly. Never leave tools: blank. Code-reviewer: Read, Grep, Glob. Code-architect: add WebSearch. Editor: add Write, Edit, MultiEdit. Bash-running agent: scope it (Bash(npm test:*), not bare Bash).
Pin the model. Read-only / bulk-scan → claude-haiku-4-5-20251001. Plan-mode partner / architecture → claude-opus-4-8. Editors and test-authors → claude-sonnet-5. If you don’t pin, the subagent inherits the orchestrator’s model and you lose the cost win.
Tell the agent what not to do. Every prompt should end with a “Hard rules” section: when to stop, what to escalate, what not to redesign. A code-reviewer that starts redesigning the architecture is worse than no subagent.
Test it on three real cases. Invoke the subagent on three actual backlog tasks. If the summary is >500 tokens, tighten compression. If it’s too short, widen it. Iterate on the prompt, not the orchestrator.
Commit the file and add the delegation rule to CLAUDE.md. Project-scoped agents into the repo so teammates get the same behavior; user-scoped into your dotfiles. Then add a one-line bullet to CLAUDE.md (“When asked to review a diff, delegate to the code-reviewer subagent”). Without this hint, the orchestrator may forget the agent exists.

Common pitfalls

Over-delegating. Subagents are a sharp tool. Delegating “fix this typo” adds two network round-trips and a context handoff for a 5-token edit. Rule of thumb: delegate when the task would otherwise consume >5k tokens of main context, or when it’s embarrassingly parallel.
No model override. Subagents can inherit the orchestrator’s model. Pin a cheaper model for narrowly scoped work when your own evaluations show acceptable quality; compare total task cost rather than assuming the rate-card ratio equals the saving.
Leaky context — returning raw output. The point of a subagent is that its reads, greps and tool calls do not enter the orchestrator’s context. If your prompt says “return the file contents”, you’ve defeated the purpose. Force a summary.
No tool restrictions. A subagent that inherits all tools is just the main agent in a different window. Always whitelist. A code-reviewer with Write access will eventually try to “helpfully” edit the file it’s reviewing.
One mega-agent instead of a set. A single “do-everything” custom agent isn’t a subagent strategy; it’s a second main agent. The win comes from role-specialized prompts, tools and models. If your agents all have the same tools: line, you’re not specializing.
Forgetting Cursor’s prompt-inheritance rule. Cursor subagents don’t inherit your project rules unless you explicitly include them. The fix is a single @.cursor/rules/style.md include in the subagent prompt.
Treating Codex as single-context. Current Codex can delegate natively. Set the multi-agent policy deliberately, constrain concurrency, and use AGENTS.md or skills to state when delegation is authorized.
Letting Explore be your “subagent strategy”. Built-in agents are great defaults, but max score requires that you’ve decided what to delegate. A curated set in .claude/agents/ is the artifact that proves it.

How to verify you’re there

Your project has at least three role-based subagents (code-reviewer, code-explorer, code-architect) in .claude/agents/ or ~/.claude/agents/.
At least two more task-specific subagents exist (e.g. migration-planner, test-author, doc-writer, pr-writer).
Every subagent has an explicit tools: whitelist in its frontmatter — none rely on inherited tools.
At least one subagent is pinned to claude-haiku-4-5-20251001 and at least one is pinned to claude-opus-4-8 — you can read the cost difference in your spend dashboard.
Your CLAUDE.md has at least one line per agent explaining when to delegate to it.
You can name, without looking, the three or four tasks you delegate by default — and the agent each one goes to.
Subagent summaries returned to the orchestrator are <500 tokens on average, not raw file contents.
You’ve run the same task once without and once with subagent delegation in the last month, and you noticed the context-usage difference.