tai/research/cap-protocol/claude-code-sub-agents-docs.md

Claude Code: Custom subagents

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	cap-protocol
Document type	Source Dossier
Tier	1
Source title	Claude Code: Custom subagents
Source URL	https://code.claude.com/docs/en/sub-agents
Source publisher / author	Anthropic
Source type	vendor docs
Source date (published)	Unknown — not stated
Date researched	2026-10-25
Researched by	tai (agent), model: Claude Sonnet 5, on behalf of retoor
Research method	direct page fetch
Confidence	Medium
Status	Active

Summary

Claude Code's documentation of subagents: file format, the model field, model resolution order, delegation modes and context isolation. Only the first 100000 of 116349 characters were read.

Key findings

• Frontmatter: name, description (when to delegate), tools (inherits all if omitted), model (sonnet, opus, haiku, fable, a full id, or inherit).
• Model resolution order: per-invocation model parameter, then the definition's model, then the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then the main conversation's model; before v2.1.251 the environment variable came first.
• Delegation is automatic from descriptions (include 'use proactively' to encourage it), by natural language, by @-mention (guarantees the run), or session-wide.
• Each subagent has its own context window, system prompt, tool access and permissions; a non-fork subagent does not see the conversation history and works from a delegation message; only a summary returns.
• Subagent requests count toward the same usage limits as the main conversation; costs are controlled by routing tasks to faster, lower-cost models like Haiku.
• Combined subagent descriptions above 15,000 tokens trigger a startup warning; use the main conversation for frequent back-and-forth or quick targeted changes.

Pros / strengths

A shipped product's explicit, ordered precedence for the model of a delegated worker, and a cost-routing rationale.

Cons / limitations / caveats

Unread tail of the page; the precedence change between versions shows the rule is unstable across releases.

Relevance to tai

Precedent for a tai rule: per-call model beats the agent's configured model beats a global default beats the parent's model. Also shows 'description decides delegation' costs context, which argues for few, well-described delegation tools.

Changelog

Date	Change
2026-10-25	Initial dossier created.