Subagents: when to delegate and when not to

Delegate when the task produces a lot of output, when it needs restricted tools, or when you are about to repeat the same instruction many times. Outside of that, a single session does the job better.

What a subagent gives you is context isolation: the verbose output stays in its window, and only the summary comes back to your conversation. The gain is that your window does not fill up. Anyone who delegates expecting speed comes away disappointed.

This guide covers what loads at the start of a subagent, what does not, and three documented behaviors that run against intuition.

Three ways to extend Claude Code, with different trade-offs.

The official rule: subagent for high-volume work, tool restriction or a self-contained task. Skill for a reusable prompt in the main conversation. Agent team for sustained parallelism or coordination across sessions.

Translated into a decision: if the output dirties your context, use a subagent. If it is knowledge you want applied to the work in progress, use a skill. If the workers need to talk to each other, use an agent team.

Where each one fits sits in the map of the five layers of a setup that survives production.

A subagent is markdown with YAML frontmatter. You have to set two fields: name and description.

---
name: reviewer
description: Reviews code for quality and security. Use it after writing changes.
tools: Read, Grep, Glob, Bash
model: sonnet
memory: project
---

You are a senior code reviewer.

When you are invoked:
1. Run `git diff` to see the recent changes
2. Review only the modified files
3. Check clarity, naming, duplication, error handling and security

Return format: Critical (fix), Warning (should fix), Suggestion.

There are more than fifteen fields available. These six cover almost everything:

Two tool restrictions worth knowing. Some tools are always removed from a subagent even if you list them. That set includes AskUserQuestion, EnterPlanMode/ExitPlanMode and EndConversation. And you can limit what the subagent can create: tools: Agent(worker, researcher) lets it spawn only those two types.

This is the one that catches people, because it contradicts the neighboring feature.

Rows 3 and 4 hold the difference. With a subagent, the project's wins over the personal one. With a skill, the personal wins over the project's.

If you have a personal deploy skill and another in the project, the personal one runs. If you have a personal deploy subagent and another in the project, the project's runs. Same name, same folder structure, inverted behavior.

The official documentation recommends keeping project-specific subagents in .claude/agents/ because that is where git versions them and the team shares them. The precedence follows that intent.

Skill precedence, and the rest of the format, sits in how to write your first Agent Skill.

A non-fork subagent starts almost from zero. The exact list matters more than it sounds.

It loads: the system prompt from the file's body, the delegation message Claude wrote, the CLAUDE.md hierarchy, a snapshot of the git status, the skills preloaded through the skills field, and the list of siblings it can message.

It does not load: the conversation history, your output style, automatic memory (unless the subagent has its own memory field) and the skills you invoked earlier.

That last one causes the most confusion. You invoke a skill in the main conversation, delegate a related task, and the subagent behaves as though the skill does not exist. To it, the skill does not. To carry it along, use the skills field in the frontmatter.

And there are two little-known exceptions: the built-in Explore and Plan subagents skip CLAUDE.md and the git status. That is deliberate. Both exist to be fast and cheap at searching code, and loading the context hierarchy would work against that.

In other words: if you delegated a search to Explore and it ignored a convention that lives in your CLAUDE.md, that is the tool's design, not a defect.

The anatomy of a CLAUDE.md that works covers what goes into that hierarchy.

The separate window is only one of the layers. There are three more, and they solve different problems.

Worktree. The isolation: worktree field runs the subagent in a temporary git worktree, created from the default branch and removed on its own if nothing changed. It is the way out for parallel work that touches files: two subagents editing the same repository overwrite each other, two in separate worktrees do not.

isolation: worktree

Scoped MCP. Rather than leaving an MCP server available for the whole session, the mcpServers field pins it to one subagent:

---
name: browser-tester
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
---

Playwright exists for that subagent alone. The main session does not pay its context cost, and no other subagent can reach it.

Validation hooks. The frontmatter accepts hooks, which lets you validate before executing rather than trusting the prompt:

tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-read-only-query.sh"

The script receives JSON on stdin and exits with code 2 to block. That is the difference between asking the subagent not to write to the database and making it unable to.

There is also maxTurns, which caps how many agentic turns it runs before stopping, which helps with an autonomous subagent that could loop.

A fork is a subagent that inherits your whole conversation instead of starting from zero.

The counterintuitive part is the cache row. A fork carries far more context and the documentation still lists lower cost among the reasons to use it, because it reuses the main conversation's prompt cache. An ordinary subagent starts from zero and pays for a separate cache.

That inverts the instinct that less context is cheaper. For a side task that needs a good deal of the conversation's context, the fork is the right route and not the waste it looks like.

A fork works well for three things: a side task that depends on what was already discussed, trying several approaches in parallel from the same point, and cheaper execution. It starts with /subtask, and CLAUDE_CODE_FORK_SUBAGENT controls the mode. It defaults to on in an interactive session and off in headless.

The decision is not yours. It is a tree of five rules where the first match wins:

1. An in-process agent team teammate → foreground
2. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 → foreground
3. Fork mode on (the interactive default) → background
4. Fork mode off and Claude needs the result → foreground
5. Fork mode off and background: true in the definition → background

In the foreground, the subagent blocks the conversation and permission prompts come straight to you. In the background, it runs in parallel and the prompts rise to the main session, where you approve or deny each call.

The background catch: a subagent in the background loses almost every built-in tool. An allowlist survives: Read, Grep, Glob, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, plus a few for worktrees and messaging.

That explains a symptom that looks random: the subagent works when you test it and fails when it runs on its own. The tool set changes with the execution mode.

The memory field turns on knowledge accumulation across sessions, with three scopes:

project is the interesting one: a code reviewer that records that repository's recurring patterns and problems turns into versioned institutional knowledge, rather than staying in the head of whoever set it up.

The same limit as automatic memory's MEMORY.md applies: the first 200 lines or 25 KB go in. The rest lives in topic files, read on demand.

For it to work, the subagent's body has to spell it out:

Update your memory with the patterns, conventions and recurring problems you
find. Review your memory before you start.

Without that instruction, the field is on and the subagent writes nothing.

Four situations where a subagent is the wrong call.

When you need the result in the middle of your own reasoning. A subagent returns a summary, not the raw material. If you need the detail to decide the next step, delegating throws away the very thing you were going to use.

When the task is short. The cost of assembling a fresh context, loading CLAUDE.md and the git status does not pay for itself on a two-file task.

When you cannot judge the result. Delegating what you cannot review transfers the risk without transferring the responsibility, and the responsibility is still yours at code review.

When the problem is ambiguity, not volume. A subagent fixes dirty context. It does not fix a vague requirement: it will start with less context than you and guess with more confidence.

The use that pays off is the inverse of all that: run the test suite and return only the failures, fetch documentation and return the answer, process a log and return the pattern. Large output, small return, objective criterion.

If the question is still which mechanism to use, rather than when to delegate, the comparison between skills, subagents and commands settles it in four questions.

One case of delegation with a rule of its own is code review, which runs as a forked subagent in the background: it is in git with an agent.

Does a subagent make the task faster?

It can. In the background it runs in parallel, which cuts wall-clock time. But the main gain is context: the verbose output stays isolated and your window does not fill up. If you delegate expecting speed, the result tends to disappoint.

Can you continue a subagent that already finished?

You can. A completed subagent keeps its full history and you can resume it. Ask it to continue and Claude reopens the same subagent with the context it already had, rather than creating another from scratch.

How do I guarantee a specific subagent gets used?

Three levels. Plain language (use the reviewer agent) leaves Claude to decide. The mention @agent-reviewer guarantees it runs. And claude --agent reviewer uses the subagent as the main agent for the whole session.

My subagent never gets invoked. Why?

In most cases the description does not match the way you ask for things, and that is what Claude decides on. Make it specific about when to use the subagent, not what it does. If you want a guarantee, use the direct mention.

• Anthropic — Claude Code Docs: Sub-agents. Accessed 20 August 2026.
• Anthropic — Claude Code Docs: Extend Claude with skills. Accessed 20 August 2026.
• Anthropic — Claude Code Docs: Orchestrate teams of Claude Code sessions. Accessed 20 August 2026.
• Anthropic — Claude Code Docs: How Claude remembers your project. Accessed 20 August 2026.
• Anthropic — Claude Code Docs: Hooks reference. Accessed 20 August 2026.

Verified on 20 August 2026.

Review trigger: revisit when (a) the precedence between project and personal scope is aligned across skills and subagents, (b) the tool list available to a background subagent changes, (c) Explore and Plan start loading CLAUDE.md, or (d) the fork's caching behavior changes.