NOTES / HARNESSES

Subagents and delegation

Handing parts of a task to helper agents that work in their own context window and report back a summary: when it helps, what it costs, and how to brief them.

UPDATED 18 NOV 2026#harness#subagents#delegation#context

The idea

A subagent is a helper the main agent hands a task to. The defining feature is isolation: in Claude Code, each subagent runs in its own context window with a custom system prompt, specific tool access and independent permissions1. It does the messy work (reading dozens of files, running a test suite, crawling documentation) inside its own window, and returns a short result. The main conversation sees the summary, not the journey.

Diagram: a lead agent delegates to three subagents, each with its own context window, which return short summaries to the lead

Diagram: my own.

Why bother

The motivation is context. Anthropic notes that in long sessions every file read and every tangent stays in the window, which slows responses and raises token cost3. Pushing side work into a separate context keeps the main window focused on coordination13. In Claude Code, for example, exploring a codebase in plan mode can be delegated to a Plan subagent so the exploration output stays out of the main conversation1.

The second motivation is parallelism. Anthropic’s research system uses an orchestrator-worker design: a lead agent plans, spawns several subagents that search different directions at once, and then synthesises the results2. In their internal evaluation, a system with Claude Opus 4 as lead and Claude Sonnet 4 subagents beat a single-agent Opus 4 by 90.2% on a research task2. They found multi-agent systems shine on breadth-first queries, on information that exceeds one context window and on tasks with many complex tools2.

The costs

Diagram: two panels; when subagents help (parallel breadth, too much for one window, many tools) and what they cost (more tokens, coordination mistakes, poor fit for tightly coupled work)

Diagram: my own, from the trade-offs discussed in 2.

Multi-agent systems use far more tokens, so Anthropic’s guidance is that the task’s value has to justify the cost2. They are also a poor fit when agents need shared context or have many dependencies between steps, which is common in coding2. Isolation cuts both ways: a subagent does not see your conversation or the files already read, so it only knows what you tell it. This is also why the choice is about design patterns as well as harness features.

Briefing a subagent

Because a subagent starts fresh, the delegation message is its entire world. Vague tasks produce duplicated or off-target work. Good briefs state:

  1. the objective and why it matters;
  2. the output format wanted back (a short list, a table, file paths);
  3. which tools and sources to use;
  4. clear boundaries so two subagents do not do the same thing;
  5. how much effort is appropriate for the task.

Anthropic found that early versions of their lead agent gave terse instructions and subagents duplicated work or left gaps, and that writing detailed task descriptions and scaling effort to query complexity fixed much of it2. In Claude Code, a custom subagent’s description field decides when the main agent picks it, so make it specific and action-oriented1.

Configuring one

A custom subagent is typically a file with a name, a description of when to use it, a system prompt and a tool list. Restricting tools is a safety feature: a “code reviewer” subagent that can read but not write cannot damage anything. Subagent descriptions also consume context in the parent, so keep them short1. Do not confuse subagents (inside one session) with agent teams that coordinate across separate sessions1, or with A2A, where the other agent is a separate service.

A rule of thumb

Delegate when the work is independent, noisy or parallel, and the answer can be summarised. Keep work in the main agent when steps depend tightly on each other or need the full conversation. When in doubt, start with one agent and add subagents only after you see context filling up or latency hurting.

Sources

  1. [1]Create custom subagents — Anthropic, Claude Code documentationPARAPHRASED
  2. [2]How we built our multi-agent research system — Anthropic Engineering · Anthropic · 2025PARAPHRASED
  3. [3]How and when to use subagents in Claude Code — AnthropicPARAPHRASED

© Ashish Kumar. All rights reserved. Quoted and cited material belongs to its owners. How I attribute sources.

Product, company and framework names are trademarks of their respective owners. Mentioning them does not imply affiliation or endorsement.