52 lines
2.5 KiB
Markdown
52 lines
2.5 KiB
Markdown
# 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. |
|