Claude Code subagents: when they are worth it, job by job, and when the main session is cheaper

The Claude Code subagents page answers “when should I use one” in a sentence: when a side task “would flood your main conversation with search results, logs, or file contents you won’t reference again: the subagent does that work in its own context and returns only the summary.” Over two weeks of my own transcripts, background subagents were about 11.5% of priced usage, and 64% of that was cache writes. So the subagent does pay to read the mess. What the docs’ sentence leaves out is what you get back, and what you lose with it.

Delegating changes three things at once. Tokens: the output gets cached somewhere else, at a different rate, for a different lifetime. Evidence: the parent sees the subagent’s account, while the raw output stays in a transcript on disk that nobody opens unless something looks wrong. Framing: a fresh subagent doesn’t carry the parent’s theory of the problem, which is sometimes the whole point. Each job below trades these differently.

Labels, so you know what rests on what. Documented: the Claude Code docs describe the pattern. Measured: I measured something about it on my own setup, in a post linked at the claim. Reported: Anthropic published a result from its own research system, which is not Claude Code. The cost reasoning is arithmetic at list rates, and I haven’t run any of these jobs both ways.

How does a Claude Code subagent change what a task costs?

It moves where tool output gets cached. In the main conversation, a tool result stays in context and is re-read on every later request until compaction, /clear, or Claude Code clearing old tool results. In a subagent, the same output is read in the subagent’s own context, and only its result lands in the parent.

The prompt caching docs set the defaults. On a Claude subscription within plan usage, the main conversation gets the one-hour cache; subagents get five minutes “even on a subscription until you choose a longer one”, and a subagent’s first request “doesn’t read the parent’s cache, because the two prefixes differ.” On an API key, a cloud provider or usage credits, the main conversation defaults to five minutes too. promptCacheTtl and subagentPromptCacheTtl change either bucket. At Opus 5.5 list rates, per the Claude Code cost breakdown, a cache read costs 0.05 times base input, a five-minute write 1.25 times and a one-hour write 2 times.

Take an idealized chunk of output that stays cached with no misses. In the main conversation on the subscription default it is written once at 2x, and every twenty later requests re-read it for one more base-input price (20 × 0.05). A subagent writes it at 1.25x, reads it a few times, and leaves it behind. Against that, the subagent pays a start: its instructions, tool definitions and brief, written cold. You can read the size of that start in any subagent transcript, as the cache-write tokens on its first request.

Set the subagent’s own reads and its returned summary aside, and the break-even is the chunk size above which delegating is cheaper, as a multiple of that start:

On a subscription, a big chunk is cheaper in a subagent even if the session ends right after, because the one-hour write costs more than the five-minute one. With both on five minutes the write is a wash, and only the re-reads you avoid pay for the start. Count API requests, not messages you type: every response that returns tool results starts another one.

The start turned out to be the small part in practice. In my background subagents audit (measured), first requests were about 10% of subagent cache writes. The rest came later, from what the subagents read in and from rebuilds, which the transcripts can’t tell apart. The same audit, aggregated over different work, gives a rough lifetime price per cached token: 29.6 reads per write in the main conversation, about 3.5x base input at list ratios, against 9.4 in background subagents, about 1.7x. Different jobs, so a sketch, not a comparison.

A fork skips the cold start. It inherits the parent’s instructions, tools and history exactly, so per the caching docs “its first request reads the parent’s cache”, and the subagents docs say a fork “costs less than a fresh subagent for tasks that need the same context.” It is cheaper for the same reason it is riskier, which comes back in review. All of it draws on one limit: a subagent “sends its own requests, which count toward the same usage limits as your main conversation.”

Should a Claude Code subagent run your test suite?

Yes, and it is the cleanest case. The docs’ first example under “Isolate high-volume operations” is exactly this prompt:

Use a subagent to run the test suite and report only the failing tests with their error messages

A full test run is exactly the chunk you won’t reference again, and usually a big one, so it sits well above the break-even. What you give up is the log. I would go one step past the docs’ prompt and ask for the failing test names and the error messages verbatim, so the account stays checkable against the transcript if something doesn’t add up.

For the narrow version of the job there is a cheaper tool. If all you want is the tail of the output, the costs page shows a PreToolUse hook that rewrites test commands to keep the last 100 lines. It is a shell filter, with no second context to pay for. A subagent earns its place over the hook when the failures need reading and grouping, not trimming.

Slow suites have one more cost. A subagent’s cache defaults to five minutes, so one that sits idle longer than that waiting on a command comes back to an expired cache. Since 2.1.318, a background subagent’s shell command moves to the background after 3 minutes to prevent that. In my audit the case was rare: requests arriving more than five minutes after the same subagent’s previous one carried 0.73% of background-subagent cache writes. That is a proxy, and my subagents seldom ran long builds.

Is a Claude Code subagent worth it for codebase search?

For “where does this behavior live” in a repository you don’t hold in your head, yes, even when the answer is small. The built-in Explore agent is read-only, and per the docs “Explore and Plan start without your CLAUDE.md files and the git status snapshot to keep research fast and inexpensive.”

The case here is framing more than tokens. In August I wrote that I reach for the clean-context searcher constantly: a fresh searcher reads the code, while a searcher holding your theory of the bug finds evidence for your theory. So the line is not output size. When you know the file, grep it yourself; a subagent would pay its whole start to return the same few lines. When you only think you know, that is the case for a clean searcher.

The bill has its own catches. Explore runs on the parent conversation’s model, not on Haiku: since v2.1.198 it inherits the session’s model capped at Opus, so under an Opus session every search is an Opus call, as the Haiku 5.5 subagent post traced (under a Fable session, the docs say it depends on how you connect). CLAUDE_CODE_SUBAGENT_MODEL alone doesn’t move Explore or Plan; per that post, add CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1, or define your own agent named Explore with model: haiku. And Explore is one-shot: it returns no agent ID and can’t be resumed, so a search you will want to extend belongs in general-purpose or a custom agent.

Should a Claude Code subagent review your diff?

Yes, and it is the case where the arithmetic says stay and you should delegate anyway. The main conversation already holds the diff, so a reviewer pays to read what the parent has cached. What you buy is a reader that doesn’t share the author’s framing. A reviewer that inherits the session that wrote the code also inherits its abandoned guesses, written in the same flat tone as its conclusions.

The docs’ example code-reviewer is a read-only subagent with tools: Read, Grep, Glob, Bash that starts from git diff. That starting point matters, because the parent writes the brief: give the reviewer the diff and a checklist, not the author’s account of what the change does.

It also makes the fork the wrong subagent for this job, and since 2.1.302 forks are on by default in claude -p and the Agent SDK too. In the one neutral-prompt run I did on 2.1.302 (measured: Haiku, with my own plugins and agents loaded), the model asked for general-purpose, not a fork. One run on one model says nothing about yours. For a review step, add "Agent(fork)" to permissions.deny or set CLAUDE_CODE_FORK_SUBAGENT=0, both documented.

The summary problem is sharpest here, because “no issues found” is a summary. Ask for findings with file and line, so each can be checked in seconds. Treat an empty review as unverified until the subagent’s transcript under ~/.claude/projects/ shows it actually opened the diff.

Do Claude Code subagents pay off for parallel research?

Sometimes, and it is the one job where a subagent is not a saving. Fan-out buys results by spending more tokens than one context could. The docs’ “Run parallel research” pattern spawns several subagents on separate modules and says it “works best when the research paths don’t depend on each other,” with a warning that many subagents each returning detailed results “can consume significant context, and each subagent spends tokens of its own while it runs.”

The strongest numbers are reported, from Anthropic’s research system post of June 2025, about its Research feature on Claude Opus 4 and Sonnet 4. They come from separate comparisons. Against a single Opus 4 agent, the multi-agent setup scored 90.2% higher on an internal research eval. On BrowseComp, token usage by itself explained 80% of the performance variance. And against chat: “agents typically use about 4× more tokens than chat interactions, and multi-agent systems use about 15× more tokens than chats.” The post also draws the line that matters for coding: “most coding tasks involve fewer truly parallelizable tasks than research.”

Some of its lessons carry over without the numbers. Each subagent needs an objective, an output format, guidance on tools and sources, and clear boundaries; with vague briefs, Anthropic says, agents duplicated work, left gaps or missed what they needed. And to cut the “game of telephone”, their subagents stored work in external systems and passed “lightweight references back.” In Claude Code terms: have each researcher write its findings to a file, with source URLs or file-and-line citations next to every claim, and return the path. A path to a paraphrase is still a paraphrase; the citations are what let the parent check.

Should parallel edits go to Claude Code subagents?

Rarely. An edit returns a small diff, so there is no output worth isolating, and the only gain is wall-clock time, which is what separate sessions are for. The docs draw the same boundary: “For work that needs to keep running in parallel or won’t fit in one context window, run it in separate sessions.”

The mechanics push the same way. A subagent starts in the main conversation’s working directory, so parallel subagents edit one checkout. isolation: worktree gives one its own copy, “branched by default from your default branch rather than the parent session’s HEAD.” Setting worktree.baseRef to "head" brings your commits along, but in my tests it still left uncommitted changes behind, which is the normal state in the middle of a feature. Commit, or hand the change over explicitly.

In my worktree tests on 2.1.316 (measured, claude -p --worktree sessions; I did not run subagents), two worktrees collided on one port, Docker Compose planned a separate Postgres volume for each, and the default base skipped the unpushed commit. Per the docs, a subagent worktree uses the same worktree.baseRef, so I expect the same from isolation: worktree. That part is untested.

When is the main Claude Code session cheaper than a subagent?

When the work shares context across steps, or the output is small enough to sit under the break-even. The docs list four cases for staying in the main conversation: frequent back-and-forth or iterative refinement; several phases that share significant context, like planning, implementation and testing; a quick, targeted change; and latency, since a non-fork subagent “starts fresh and may need time to gather context.”

Each maps onto the cost shape. Iteration means repeated starts, or resumes that only stay cheap while the subagent’s five-minute cache is warm. Shared phases mean the subagent must be handed context the parent already holds, and a brief that rich is most of what you were trying to save; if the work really is one continuing line of thought, that is the fork’s job, not a fresh subagent’s. A targeted change produces too little output to isolate. For a question about something already in the conversation, the docs point to /btw: it “has no tool access, and the answer isn’t added to history.”

Chaining subagents, review in one and fix in the next, is documented too, but every hop passes through the parent as a summary. If the fixer needs the reviewer’s evidence and not its conclusions, write the findings to a file between the steps.

Which model should a Claude Code subagent run on?

The parent’s, unless you route it on purpose. Per the docs, a subagent you define “runs on the same model as the conversation that starts it”, and Claude Code takes the per-invocation parameter first, then the definition’s model field, then CLAUDE_CODE_SUBAGENT_MODEL, then the parent; CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 overrides the first two. The costs page suggests model: haiku for “simple subagent tasks.”

Check what the alias resolves to before you count savings. haiku means Haiku 5.5 on the Anthropic API, while Bedrock, Google Cloud, Microsoft Foundry and Claude Platform on AWS still map it to Haiku 4.5. And Haiku 5.5 is cheaper per token, not automatically per task. A summary that fits in one call is what its price card was built for. A long search loop is where the 100K long-prompt rate shows up, so pin effort and set /autocompact 100k first, as the Haiku 5.5 subagent post goes through. For review, the closest evidence there is Bug Hunt Bench: 21.5 of 105 planted bugs for Haiku 5.5 at max effort, against 36 for Opus 5.5 at xhigh.

How do you check whether Claude Code subagents pay off in your sessions?

Look at the share first, then at what fills it. On a Pro, Max, Ultra, Team or Enterprise plan, /usage attributes recent usage to subagents as a percentage over 24 hours or 7 days, computed from local history. Its Prompt cache (main) line covers the main conversation only, so for subagents’ own cache behavior you need the transcripts under ~/.claude/projects/.

When I ran that audit (measured, a Max plan, October 22 to November 4), background subagents were about 11.5% of priced usage and 64% of their cost was five-minute cache writes. Most of those writes came after the first request, and the audit couldn’t separate new content from cache rebuilds. The script is in that post. It can’t say whether the same jobs would have cost more in the main conversation, because I didn’t run them both ways.

So the docs’ test, output you won’t reference again, is half the decision. The other half: is there enough of it to clear the start, which on a subscription is not much; will the result come back in a form you can check against the transcript; and does the job need a reader without your framing. Test runs pass all three. A known-file grep fails the first. Review fails the cost test and should be delegated anyway.