Claude Code Subagents

Definition

Custom subagents in Claude Code: markdown files with YAML frontmatter whose body becomes the subagent’s system prompt, running in an isolated context window. The primary context-isolation mechanism for keeping verbose work out of the main conversation (captured from code.claude.com/docs/en/sub-agents, 2026-07-31).

Key Points

• Context isolation is the core purpose — each subagent runs in its own context window with its own system prompt, tools, and permissions; “Running tests, fetching documentation, or processing log files can consume significant context. By delegating these to a subagent, the verbose output stays in the subagent’s context while only the relevant summary returns.”
• A subagent is a Markdown file — YAML frontmatter (config) + body (system prompt); only name and description required; “Subagents receive only this system prompt plus basic environment details like the working directory, not the full Claude Code system prompt.” 15+ optional fields: tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, effort, background, isolation, color.
• Five scopes with strict precedence — managed settings > --agents CLI JSON > .claude/agents/ > ~/.claude/agents/ > plugin agents/; scanned recursively; same name in nested dirs resolves to the definition closest to the working directory; “identity comes only from the name frontmatter field.” Plugin agents get scoped identifiers (my-plugin:review:security) and drop hooks/mcpServers/permissionMode.
• Model routing enables cost control — model accepts aliases/full IDs/inherit (default); resolution order env var → per-invocation → frontmatter → main conversation, all checked against org availableModels allowlist; “Control costs by routing tasks to faster, cheaper models like Haiku.”
• Capability control — tools is an allowlist, disallowedTools a denylist (deny applied first), MCP server-level patterns (mcp__<server>); background subagent (default as of v2.1.198) reduced to a ~19-tool built-in set; AskUserQuestion, EnterPlanMode, EndConversation always removed; zero-tools is an error since v2.1.208.
• Prompt-level orchestration can sit above native subagents — the gauntlet-loop transcript describes a user-facing prompt pattern where the main agent fans out many subagents and pairs each with a critic. That makes subagents visible as a design primitive for prompt authors, not just a configuration feature for tool builders.

Implications

Subagents are the vault’s canonical context-isolation pattern: they implement the “verbose output stays in the worker’s window” principle that token-usage-reduction prescribes and that the paper shows naive compression fails to achieve (evidence is deferred, not destroyed). The name-based identity + scope precedence is multi-file-agent-architecture instantiated concretely. Cost routing (Haiku for background work) is a model-selection lever orthogonal to context management. The gauntlet-loop example extends this by showing how a prompt can explicitly require worker/critic subagent pairs and a bar-to-hit loop as part of the output contract.

Open Questions

• Heavily version-sensitive (v2.1.198 / v2.1.212 / v2.1.217 / v2.1.219 gates): Explore model inheritance, /agents wizard removal, spawn depth (5→1→3), limits (200/session v2.1.212+, 20 concurrent v2.1.217+), background-by-default (v2.1.198+), Task→Agent rename (v2.1.63), /fork→/subtask (v2.1.212).
• Fork-vs-fresh cache behavior and how returned results/many parallel subagents still consume main context — open question shared with claude-code-sessions.

Related

claude-code-environment-variables — CLAUDE_CODE_SUBAGENT_MODEL, _MAX_SUBAGENTS_PER_SESSION, _MAX_CONCURRENT_SUBAGENTS, _MAX_SUBAGENT_SPAWN_DEPTH claude-code-memory — memory frontmatter gives persistent agent-memory/ dirs claude-code-system-prompt — subagents get only their own body prompt, not the full system prompt token-usage-reduction — context-isolation token savings with parallel-subagent caveats multi-file-agent-architecture — distributed per-scope markdown config concrete instantiation claude-code-parallel-agents — where subagents fit among parallelization approaches gauntlet-loop-prompting — user-facing workflow pattern that explicitly pairs worker and critic subagents

Sources

• raw/external/code-claude-com-sub-agents-5d62f063.md
• raw/prompts/articles/robonuggets-gauntlet-loop-youtube-transcript.md