When to Use Subagents in Claude Code

While tracking down an auth bug, you have Claude Code search the whole call chain and run the full test suite in the main session. Half an hour later, hundreds of lines of search results and test logs fill the context, and when it's time to decide, the approach you'd worked out earlier has been washed out. Another day, you only want to change one line of button text, and Claude sends out a subagent anyway, and you wait for it to come back.

These are opposite mistakes: one task should have been delegated and wasn't, and the other shouldn't have been and was. A subagent's value is moving part of the work into a separate context, where the intermediate output stays, and only conclusions and evidence come back to the main session. It also has costs: a fresh context has to gather background again, you wait, and it spends extra tokens.

Before delegating, ask three questions:

1. Can the subtask be explained in one self-contained message?
2. Will it produce lots of intermediate output the main session won't need later?
3. Can it finish independently and hand back a short result?

If most answers are yes, consider delegating. As tasks grow larger, Skills, Agent Teams, and Dynamic Workflows are also options, chosen by who controls the next step and how many workers need coordinating. We'll start with the three questions and then go all the way from the main session to scripted orchestration.

01 What Kind of Task Suits a Subagent

A subagent suits a self-contained task: it keeps the bulk of the intermediate work in a separate context and brings back the evidence the main session needs. Tracing an auth call chain and sorting test failures are good examples:

Main session
  ├─ Delegate: map the auth call chain
  │    └─ Subagent A: searches many files, returns only a call-chain summary
  ├─ Delegate: run tests and summarize failures
  │    └─ Subagent B: keeps the full log, returns only the failure causes
  └─ Combine the conclusions and decide the next change

Isolating intermediate work cuts noise in the main session, but it doesn't make conclusions correct. The task definition and final review still decide whether a result is usable.

If most of the three opening questions get a yes, delegation is worth considering. When a task needs constant back-and-forth, depends on background from the current discussion, or touches only one line of code, keep it in the main session. Handing work off costs explanation time and waiting time too.

The Claude Code best practices are frank about the cost: it's mostly tokens, since every subagent sends its own requests and they count against the same usage as your main conversation. Sometimes it costs time too, because a fresh subagent first has to gather context your conversation already had. The guide lists four situations where subagents pay off:

• running independent pieces of work at the same time, so the whole task finishes sooner;
• keeping long output, like a full test run or a wide search, out of the main conversation;
• getting a reviewer that hasn't seen how the code was written;
• giving a task fewer tools than the main session has, like a reviewer that can read but not edit.

02 Start with the Built-in Subagents

Claude Code ships with built-in subagents for common cases:

Explore being a read-only search role doesn't tell you its model. By default it follows the main session; it isn't fixed to Haiku. If you want searches to always use a lighter model, override Explore or define a separate research agent. The subagents documentation describes how: define a user or project subagent named Explore, which overrides the built-in, and give it model: haiku. A role name is no substitute for model configuration.

One more detail affects handoffs: to stay lightweight, Explore and Plan start without the project CLAUDE.md or Git status. Restate any constraints in the delegation message; how to write it is covered in briefing a subagent and checking its findings.

03 From the Main Session to Scripted Orchestration

The same goal can be reached with mechanisms of very different complexity:

Look at the task's size and feedback pattern first. When changes are focused and need frequent discussion, the main session is usually enough; extra agents and orchestration add handoff costs. Skills reuse methods, subagents run work independently, and Agent Teams make sense when you need several long-running sessions that talk to each other. Whether to step up depends on what the collaboration needs.

Within one task, the main session drives the decisions and the other mechanisms each handle their part:

Main session: understands the current goal and decides how to proceed
Skill: provides reusable methods, checklists, and scripts
Subagent: does focused work in a separate context
Hook: runs fixed actions at set lifecycle points
Dynamic Workflow: uses code to control large loops, branches, and aggregation

04 When to Use a Dynamic Workflow

Scripted orchestration is worth it only when there are many targets, stages repeat, or a lot of intermediate noise needs to stay out of the way. Weigh scale, repetition, context, and dependencies together.

The Dynamic Workflows documentation defines a dynamic workflow as a JavaScript script, written by Claude, that orchestrates many subagents; a runtime executes it in the background while your session stays responsive. The docs separate the mechanisms by who holds the plan: with subagents, skills, and agent teams, Claude decides turn by turn and every result goes into a context window; a workflow moves the loop, the branching, and the intermediate results into script variables, so Claude's context holds only the final answer. In scale, subagents handle a few delegated tasks per turn, while a workflow runs dozens to hundreds of agents.

Good fits include routed batches of auth audits, component migrations with per-item verification, bounded multi-round fixes, and research cross-checked across sources. A few points on use:

• watch stages, agents, tokens, and time in /workflows, where you can also pause and resume;
• once stable, save it to the project's .claude/workflows/ and call it from a slash entry later;
• agents' tool calls still go through the session's permissions, so review the plan, script, and write scope before launch;
• try a few files first, check result quality, return format, and stop behavior, then scale up gradually.

If you need approval between stages, split the Dynamic Workflow up; it isn't built for dropping business approval steps in wherever you like.

05 The Cost of Nested Delegation

Older material may say subagents can't delegate further. Per the subagents documentation, a subagent can by default spawn subagents up to three layers below the main conversation, and at that limit Claude Code withholds the Agent tool. A subagent can delegate only if it has the Agent tool. To stop it, leave Agent out of tools or remove it with disallowedTools.

Each extra layer can add handoff, scheduling, and model costs. When one focused agent can do the job, keep it to one layer; when the scope is unclear, add input first. How to divide work when several subagents run at once is covered in how to run Claude Code subagents in parallel safely.

Back to the two mistakes. For the auth investigation, send the call-chain search and the test logs to one subagent each and bring back summaries, leaving the main session free for decisions. For the one-line text change, editing it in the main session is faster. Look at scale, feedback frequency, and intermediate output first, and add a mechanism only when it earns its place.