Subagent
An auxiliary agent used in AI-assisted programming to isolate exploration tasks, preventing contamination of the main agent's context and keeping the main context clean.
Core Facts
In multi-agent collaborative architectures, the controller agent is responsible for task planning and scheduling, while sub-agents serve as execution units with specific tool access permissions and behavioral constraints.
Claude Code's sub-agents work in independent contexts and, upon completion, return only a summary of results to the main agent, achieving context isolation.
Timeline (last 90 days)
In the hierarchical agent architecture of main agent and sub-agents, sub-agents are suitable for being handled by small, slow local models, while the main agent, because it needs long context and strong reasoning, is better handed to cloud models.
v2.1.311 fixes the issue where a background agent launched by a subagent had its isolated worktree deleted prematurely while still working in it, and ensures that in auto mode a background agent does not start a new main conversation turn on each wake-up.
Previously the SubagentStop hook fired about twice per minute for each running subagent rather than once when the subagent completed; v2.1.311 fixes this behavior.
The Anthropic guide notes that sub-agents are worth keeping in only three scenarios: quality degradation from context bloat has been measured, parallel processing is needed and subtask context can be discarded, and too many tools or conflicting instructions make a single agent unable to cope.
When the main flow performs a steer operation, if a sub-agent is in the middle of a task, it is automatically moved to the background to continue working rather than being forcibly interrupted.
Forcibly terminating a sub-agent loses its completed intermediate results, while leaving it alone may block the main flow—this is a trade-off in sub-agent lifecycle management.
The design of moving sub-agents to the background is an optimistic concurrency strategy that defers the judgment of "whether it is wasteful" until after the sub-agent completes, rather than killing it at the moment the steer occurs.
Under the old mechanism, the parent agent's stream could close early before sub-agents finished, causing results to be lost or requiring extra state management.
TinyFish's engineering team found that the hierarchical structure of a standalone planner plus per-query subagents brings coordination overhead and information loss in deep research scenarios.
Per-query subagents further assign each subquery to an independent agent, each maintaining its own context, which tends to cause information fragmentation and duplicate retrieval during aggregation.
17 more timeline events
All Facts (20)
In multi-agent collaborative architectures, the controller agent is responsible for task planning and scheduling, while sub-agents serve as execution units with specific tool access permissions and behavioral constraints.
70%VerifiedClaude Code's sub-agents work in independent contexts and, upon completion, return only a summary of results to the main agent, achieving context isolation.
65%UnverifiedIn the hierarchical agent architecture of main agent and sub-agents, sub-agents are suitable for being handled by small, slow local models, while the main agent, because it needs long context and strong reasoning, is better handed to cloud models.
50%UnverifiedThe Anthropic guide notes that sub-agents are worth keeping in only three scenarios: quality degradation from context bloat has been measured, parallel processing is needed and subtask context can be discarded, and too many tools or conflicting instructions make a single agent unable to cope.
50%UnverifiedWhen the main flow performs a steer operation, if a sub-agent is in the middle of a task, it is automatically moved to the background to continue working rather than being forcibly interrupted.
50%UnverifiedForcibly terminating a sub-agent loses its completed intermediate results, while leaving it alone may block the main flow—this is a trade-off in sub-agent lifecycle management.
50%UnverifiedThe design of moving sub-agents to the background is an optimistic concurrency strategy that defers the judgment of "whether it is wasteful" until after the sub-agent completes, rather than killing it at the moment the steer occurs.
50%UnverifiedUnder the old mechanism, the parent agent's stream could close early before sub-agents finished, causing results to be lost or requiring extra state management.
50%UnverifiedPer-query subagents further assign each subquery to an independent agent, each maintaining its own context, which tends to cause information fragmentation and duplicate retrieval during aggregation.
50%UnverifiedTinyFish's engineering team found that the hierarchical structure of a standalone planner plus per-query subagents brings coordination overhead and information loss in deep research scenarios.
50%UnverifiedTinyFish's deep research system abandoned the standalone planner and per-query subagents.
50%UnverifiedThe one-agent-per-project-plus-sub-agents model has the advantage of concentrated context and simple coordination, but the disadvantage is that a single agent easily becomes a bottleneck, and dependencies among sub-agents still need to be scheduled by the main agent.
50%UnverifiedBy default, Claude Code's subagents do not share memory with each other and do not communicate directly; all coordination must be relayed through the main agent.
50%UnverifiedAsynchronous sub-agents mean that the main agent can spawn sub-agents to handle time-consuming operations while it continues to interact with the user or handle other matters.
50%UnverifiedA reasonable onboarding path for adopting the Claude Agent SDK is: first get a single agent plus structured output working, then introduce SessionStore for state persistence, and only then split out sub-agents; skills and plugins should be abstracted only when a second reuse need arises.
50%UnverifiedIf the parent agent passes incomplete information when spawning a sub-agent, the sub-agent may make wrong judgments based on partial information, and the error propagates up the call chain.
50%UnverifiedSub-agents usually run in independent context windows, and the parent agent's conversation history is not automatically visible to the sub-agent.
50%Unverifiedv2.1.299 fixed an edge case where an MCP server named constructor or prototype could never connect.
50%UnverifiedSub-agents independently select models based on their own assessment of subtask complexity rather than inheriting the model setting of the main session, which causes multiple models that the user never manually selected to appear in usage reports.
50%UnverifiedSwitching models via /model or startup parameters does not override the model used by sub-agents during task execution.
50%