What Is a Subagent? How AI Coding Agents Delegate Work

A subagent is a separate AI agent that a main agent spawns to do one bounded task in its own context window, returning only a summary. In AI coding tools the word has a precise meaning, and this article uses Claude Code's, because that is the tool SWARECO uses daily.

It covers the definition, what a subagent inherits and what it does not, how one is defined and invoked, the built-in subagents, our own usage numbers from one engineer's machine over 30 days, and when not to use one.

Key Takeaways

• A subagent runs in its own context window with its own system prompt, tool access and permissions. The main agent writes it a task, the subagent works through it, and only the final summary comes back; the verbose middle never enters the main conversation.
• A fresh subagent starts without the conversation history, the files already read or the skills already invoked. A fork inherits all of it and shares the main session's prompt cache, so it costs less for work that needs the same context.
• A custom subagent is a Markdown file with YAML front matter; only name and description are required. Claude Code warns when all descriptions together exceed 15,000 tokens, because every description is loaded into the main context.
• On one SWARECO engineer's machine, 15 of 54 sessions in 30 days spawned at least one subagent (28 percent), across 81 runs and 7 projects. The median subagent transcript was 676 KB of context that never reached the main window. Every run used a built-in type.
• Use a subagent for a bounded task whose result can be summarised, or for independent tasks that can run in parallel. Do not use one for work that needs the conversation so far, or in an unattended run nobody will read.

What a subagent is

Anthropic's Claude Code documentation, read on 14 October 2026, defines subagents as "specialized AI assistants that handle specific types of tasks." Each runs in its own context window with its own system prompt, its own tool access and its own permissions, and its requests count toward the same usage limits as the main conversation.

The mechanism is simple. The main agent decides to delegate, writes a task message, the subagent works through it with its own tool calls, and only its final summary comes back into the main conversation. The verbose middle, every file it read and every command it ran, stays in the subagent's context.

One paragraph of disambiguation, because the word has older meanings. In real estate a sub-agent is a licensed agent who works under the listing broker and owes duties to the seller rather than the buyer; in publishing and insurance it names a contractual intermediary. None of that applies here. The rest of this article is about AI coding agents.

Subagent, agent and multi-agent system: the difference

An agent is a model in a loop with tools that acts until a task is done. A subagent is an agent that another agent started, for one task, with a result that flows back to the parent. A multi-agent system is the general term for several agents coordinating, with or without a parent; a subagent setup is the simplest multi-agent shape, a tree with one orchestrator at the root.

The shape exists for two reasons. Context isolation: a long search or a noisy test run does not fill the main window. Parallelism: several bounded tasks run at once.

The cost is plain. Each subagent spends its own tokens. Many subagents returning long results still fill the main context. A fresh subagent cannot reuse the parent's cached context. The documentation's own cost-control advice is to route simple tasks to a cheaper model such as Haiku through the subagent's model field.

What a subagent does and does not inherit

What comes back, in both cases, is only the summary. For a background subagent the result arrives as a completion notification in a later turn.

How Claude Code defines and invokes a subagent

A custom subagent is a Markdown file with YAML front matter. Only two fields are required: name and description. Optional fields include tools (an allowlist), disallowedTools (a denylist applied first), model (sonnet, opus, haiku, fable, a full model ID, or inherit), permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort and isolation. Unrecognised fields fail silently, so a misspelled field name is simply dropped.

The files live in five places, highest priority first: managed settings for an organisation; the --agents flag passed at launch, for one session; the project's .claude/agents/ directory; the user's ~/.claude/agents/ directory; and a plugin's agents/ directory. When two share a name, the higher-priority location wins. (The CLAUDE.md files a subagent receives are the same ones we describe in our post on claude init.)

A subagent gets invoked four ways: automatically, because the main agent reads each description and delegates when a task matches, which is why a description should single out one subagent; by asking in plain language; by an @-mention of the agent's name; or for a whole session with the --agent flag or an agent setting. The description budget matters because every description is loaded into the main context: Claude Code warns at startup when the combined descriptions exceed 15,000 tokens.

The built-in subagents and what each is for

• Explore: fast and read-only, for searching and analysing a codebase. Write and Edit are denied. The main agent passes a thoroughness level of quick, medium or very thorough.
• Plan: read-only research used in plan mode.
• General-purpose: every tool a subagent may have, for multi-step tasks that need both exploration and action.
• claude, statusline-setup and claude-code-guide: three smaller ones. The first is a catch-all; the second runs on Sonnet and configures the status line; the third runs on Haiku and answers questions about the tool itself.

Some tools are removed from every subagent regardless of its definition: AskUserQuestion, EnterPlanMode, ScheduleWakeup, Workflow, and Agent once the nesting depth limit is reached. By default at most 20 subagents run concurrently and nesting is three layers deep; both are adjustable through environment variables. Explore and Plan can be switched off with an environment variable, and any type can be blocked with an Agent(name) deny rule. Explore and Plan are one-shot; other subagents can be continued by sending a message to their ID.

A month of subagent runs on one machine: our numbers

On 14 October 2026 we counted the transcript files Claude Code keeps on one SWARECO engineer's machine. The count used file metadata only; nothing was read.

The transcript sizes are the isolation benefit, measured. A transcript holds every tool result the subagent read, so those are kilobytes of context that never entered the main window.

The 28 percent means most sessions never need one. The sessions that do are searches across a large codebase and multi-file research, which is what Explore exists for.

The zero custom definitions is honest rather than a gap: the built-in types covered our work. A custom definition is worth writing only when the same bounded task with the same restricted tool set recurs.

One rule from unattended runs: a scheduled headless job we run twice a day has subagents denied at launch, together with Edit, Write and web tools, because an unattended run should not fan out into work nobody is watching. The reasons are in our posts on headless mode and routines.

When to use a subagent, and when not to

Use one when the task is bounded and its result can be summarised; when the work would read many files or produce long output the main conversation does not need; when two or more such tasks are independent and can run at once; or when the task needs a narrower tool set than the main session, for example a read-only review.

Do not use one when the task needs the conversation so far, because a fresh subagent starts without it and a summary of a summary loses detail; when the task is a handful of tool calls you could make directly; when the result must be inspected step by step; or when the run is unattended and nobody will read the output.

The two costs of misuse are tokens, because each subagent spends its own, and main-window context, because many detailed results returned at once consume it. Anthropic's own best practices are short: design focused subagents that excel at one task; write descriptions that single out one subagent; limit tool access; check project subagents into version control.

Forks: the subagent that keeps your context

A fork is a subagent that inherits the entire conversation at the moment it spawns, with the same system prompt, tools and model as the main session. It shares the main session's prompt cache, so its first request costs less than a fresh subagent doing work that needs the same context.

In interactive sessions fork mode is on by default; in headless runs with the -p flag and in the Agent SDK it is off by default, and the CLAUDE_CODE_FORK_SUBAGENT environment variable overrides both. A fork cannot spawn further forks. A fork can be given an isolated git worktree so its file edits do not touch the main checkout, the same isolation we use in our worktree playbook. When fork mode is on, the subagents the main agent spawns run in the background by default, and the main agent cannot ask for the foreground.

Our reading: use a fork when the task is a side branch of the current conversation; use a fresh subagent when the task should start clean.

Conclusion

A subagent is an agent started by an agent, with its own context and tools, returning a summary. The gain is isolation and parallelism; the cost is tokens and lost conversation context. On one SWARECO machine, 28 percent of sessions used one in a month, and every run was a built-in type. SWARECO builds and runs engineering teams that work with these tools daily.

FAQs

1. What is a subagent in an AI coding agent?

A separate agent the main agent spawns for one bounded task. It runs in its own context window with its own system prompt, tools and permissions, and returns only a summary.

2. What is the difference between a subagent and an agent?

An agent is a model in a loop with tools. A subagent is an agent that another agent started, for one task, with the result flowing back to the parent.

3. Does a subagent see my conversation?

A fresh subagent does not: no history, no files already read, no skills already invoked. A fork does, and shares the main session's prompt cache.

4. How do I create a subagent in Claude Code?

Write a Markdown file with YAML front matter containing at least name and description, and put it in .claude/agents/ for one project or ~/.claude/agents/ for all of them.

5. What does a subagent cost?

Its own tokens, counted against the same usage limits as the main conversation, plus whatever of its summary lands in the main context. Routing simple tasks to a cheaper model through the model field is the documented cost control.

6. When should I not use a subagent?

When the task needs the conversation so far, when it is a handful of direct tool calls, when the result must be inspected step by step, or when the run is unattended and nobody will read the output.