Subagents: The Unit That Splits Context

A Claude Agent SDK subagent starts every run with a blank context, keeps its own intermediate tool calls and results inside its own session, and hands the parent only a single final message. Attach a research subagent that digs through dozens of files, and the parent conversation still gains only one summary paragraph. Tool access narrows the same way: a doc-review subagent can keep Read, Grep, and Glob while Edit and Bash are simply absent from its session, not just denied.

From Turn-by-Turn Delegation to Scripted Orchestration

Subagents work well when Claude decides, turn by turn, how many to spawn for a few delegated tasks — but that model breaks down once a job needs dozens to hundreds of agents. At that scale, the orchestration itself has to move into a script that a separate runtime executes: a dynamic workflow. Intermediate results live in script variables instead of the conversation's context window, so the parent session only ever sees the final output.

Build Roadmap and Pitfalls: Budgets and Resume Design for Subagent Workflows

Declare target numbers before writing any code. The workflow runtime enforces a hard ceiling of 16 concurrent agents and 1,000 agents total per run, and the progress view flags a "Large workflow" warning once a run is projected to schedule more than 25 agents or cross 1.5 million tokens. Pick a size guideline — small (under 5 agents), medium (under 15), or large (under 50) — that matches the task's scope, and hard-code a USD budget cap through the query option rather than treating it as an afterthought.

Turn-by-turn subagents run under a separate cap system. Nesting depth — how many layers a subagent can spawn subagents of its own — defaults to 3, and concurrent subagents default to 20 at once. Conflating these two numbers with the workflow's 16 and 1,000 points an operations dashboard's threshold alerts at the wrong ceiling entirely.

The resume rule is the failure mode teams miss most. Stop a running workflow and resume it, and replay follows the order agents started in: any agent that started after the one still running when you stopped reruns from scratch, even if it had already finished. A workflow fanned out across many small agents therefore preserves far more progress on resume than one long-running agent would.

Hitting the concurrency ceiling doesn't kill the session — it comes back as a single tool_result reading "Concurrent subagent limit reached," which should be treated as a backoff signal, not an error. The budget cap fires three ways at once: it refuses new spawns, force-stops background subagents still running, and ends the query with an error_max_budget_usd result — that subtype needs its own code path, separate from other failures. When an API error such as a rate limit kills a subagent mid-run, its result is never delivered at all, so collapsing "finished normally" and "terminated on error" into one null check will silently misclassify failures.

Put least-privilege tool scoping on the operations checklist. Omitting the tools field lets a subagent inherit every tool available to it, so a "read-only" reviewer can still end up holding Edit and Bash. Pre-deployment scenario tests should force the concurrency ceiling, force-exhaust the budget cap, and fail exactly one call in a parallel batch with an API error. Starting in v2.1.210, the parent scans a subagent's final message for control-tag imitation, permission-configuration mentions, and turn-marker patterns before trusting it, neutralizing harness-only tags and appending a [harness: ...] marker — logging whether that marker fired lets you trace, session by session, a subagent that read an external page and carried a prompt injection back with it.

Every week, tally agent counts and token totals from the workflow progress view; a job that keeps tripping the Large workflow warning needs a tighter size guideline or a split into smaller stages. On any run that stopped and resumed, log what fraction of agents reran, and use that to justify reordering the fan-out so cheaper agents run first. An organization's model allowlist can also silently substitute a different model when it blocks the one a script requested, so fold that substitution warning into the weekly cost review too.

Takeaways at a Glance

Running subagent workflows in production means fixing the hard ceilings — 16 concurrent, 1,000 total — plus a size guideline and a USD budget cap in code before launch, designing fan-out order around the resume rule that reruns even finished agents that started late, and routing the concurrency-limit response and the budget-cap termination subtype through distinct code paths. Add subagent output-scanning logs on top, and a large fan-out stays governed on both the cost axis and the security axis.

References

Subagents in the SDK — Claude Docs

Orchestrate subagents at scale with dynamic workflows — Claude Docs