Sub-agents

A parent hands a sub-task to a child with a fresh context and gets a short report back: a smaller context for the parent, paid for in the child's tokens and in time.

Loading the animation…

Concept

Everything an agent reads stays in its context, and the whole context is sent again on every later turn (chapter 1). Reading four long notes to extract five sentences leaves the four notes in the conversation for the rest of the task. A sub-agent is the harness's answer: the parent calls a task tool with a short prompt; the harness starts a second loop with a fresh context (its own system prompt, the tools, the prompt, nothing else); the sub-agent does the reading; and only its final answer comes back to the parent, as that tool call's result.

The animation draws both contexts to one scale. Inline, the parent's context grows with every note it reads and peaks at 2,785 tokens. With a sub-agent, the notes fill the sub-agent's context instead (it peaks at 2,507 tokens), the report it hands back is 77 tokens, and the parent never holds more than 926 tokens: about a third of the inline peak. Over the whole run the two agents together send 11,557 tokens to the model, against 16,179 tokens inline.

The saving is not free, and here it is not even a saving in money. The sub-agent is another loop, run while the parent waits: the task takes 13.2 s instead of 9.79 s. And because the inline run re-reads its history from the prompt cache (chapter 4) at a tenth of the price, while the sub-agent's fresh context has to be written to the cache first, the run with a sub-agent costs $0.0354 against $0.0256 inline. Fewer tokens, more money: the cache changes which tokens are expensive.

What a sub-agent really buys is room. Switch the window to 3,000 tokens: inline, the parent has to summarise its own history twice to keep going; with a sub-agent, the parent's context never comes near the limit, and only the sub-agent compacts. A parent that keeps a small, clean context makes better decisions for longer; that is why the public harnesses use sub-agents for exploration and side questions, where most of what is read is thrown away.

Maths

Let $N$ be the tokens sent to the model over a run (every call's whole prompt). Inline, a note of $R$ tokens read on turn $j$ is re-sent on every later turn, so it costs about $R\,(n - j)$ tokens over an $n$ -turn run. With a sub-agent, the parent instead carries the report of $S \ll R$ tokens, and the sub-agent pays for its own loop, $N_{\text{child}}$ . The saving

\Delta N = N_{\text{inline}} - (N_{\text{parent}} + N_{\text{child}})

is positive when the notes would have stayed in the parent's context for many turns: here 4,622 tokens, with the parent's peak context down by 1,859 tokens. The extra time is the sub-agent's loop, which runs while the parent waits, less the turns the parent no longer takes: here 3.43 s.

Money follows the price of each token, not their count. Cached tokens cost a tenth of fresh ones and cache writes 1.25 times; a run that re-reads a long, stable history is mostly cache reads, while a new context is mostly writes. With the cache on, the sub-agent here costs $0.00983 more for the same answer.

Code

The task tool, cut from the vendored engine (harness.ts): a second loop with its own system prompt and the parent's tools minus task, so a sub-agent cannot spawn another one here.

const child = `sub${this.spawned}`;
this.emit("handoff", parent, this.t, { direction: "spawn", child, prompt_tokens: this.tok.count(prompt) });
const tools = (this.scenario.tools as string[]).filter((n) => n !== "task");
const sub = this.policy.subagents as Obj;
const [status, answer, used] = this.loop(child, sub.system, prompt, tools, new ScriptedModel(script), sub.max_turns);

Sub-agents in the public harnesses

Harness	Sub-agents (from their docs, accessed 2026-10-07)
Claude Code	"Each subagent starts with a fresh, isolated context window"; it "does that work in its own context and returns only the summary"; by default a sub-agent can spawn its own, "up to three layers below the main conversation" (subagents)
Codex CLI	sub-agents are on by default, and the parent receives "summaries from subagents instead of raw intermediate output" (subagents)
OpenHands	a task tool delegates to a sub-agent with its own conversation, which returns its response to the parent (task tool set)

All three draw the same line the animation draws: the child's context is its own, and only a summary crosses back. How deep the tree may grow, and whether children run in parallel, differ; chapter 9 compares the rest.