A subagent definition looks like a few lines of YAML. Most of the ways it goes wrong are silent: a misspelled field is ignored, a “read-only” agent can write files, a permission setting gets overridden by the parent. None of those produce an error.
This is the reference for the definition file. If you haven’t yet, Subagents explains what one is for.
Where definitions live
A definition is a Markdown file with YAML frontmatter (a block of key-value settings between two --- lines) followed by the agent’s instructions. It can live in:
.claude/agents/for the project.~/.claude/agents/for you, across projects.- The session-level
--agentscommand-line option, which takes JSON. - A plugin, which is a bundle of skills, hooks, and agents you install together.
Only name and description are required. The subagent documentation is the authority for the rest.
Fields
name: Must be unique. It can’t contain:or start with-. Project and user agent files must declare it; without it, Claude Code treats the file as adjacent documentation and skips registration. Only plugin agents fall back to the filename.description: Tells Claude when to delegate to this agent. Automatic delegation depends on it, so treat it as a routing rule.tools: An allowlist, as a comma-separated string or a YAML list. ListingAgent(the tool that starts subagents) lets the agent delegate.Agent(researcher, analyst)limits it to those agents, but only when the agent runs the whole session with--agent. In an ordinary subagent definition, the parenthesized list is ignored.disallowedTools: Removes tools from the inherited set. A name pattern likemcp__*(every tool an MCP server supplies) works. A pattern with a specifier, likeBash(git push *), removes the whole tool, not just that command. For command-level blocks, use a deny rule in your settings instead.permissionMode: How much the agent may do without asking.defaultasks before edits and commands.acceptEditsauto-approves file edits.planis read-only planning.autolets a classifier (a background model check) approve actions it judges safe.bypassPermissionsskips prompts entirely.dontAskauto-denies any call that would otherwise prompt. Unset, the agent uses the session’s mode. Heads up: if the parent is inauto,acceptEdits, orbypassPermissions, the subagent runs in that mode and ignores its own setting, so aplanreviewer isn’t read-only underauto. See the permissions documentation for what each mode does.model:sonnet,opus,haiku,fable, a full model ID, orinheritto use the parent’s.effort: How hard the model thinks:low,medium,high,xhigh, ormax.maxTurns: Stops the agent after N agentic turns (one model request plus the tool calls it makes). Output that hits the cap is marked partial.background:trueforces the agent to run in the background. Without it, Claude decides. With fork mode on (the interactive default), subagents normally run in the background. With fork mode off, including headless (claude -p) and SDK defaults, Claude usually backgrounds them but picks foreground when it needs the result before continuing. Set it when a worker must stay in the background; see the scheduling rules.isolation:worktreeruns the agent in its own git worktree (an extra checkout of the same repository, in its own directory). By default it branches from your default branch, not your currentHEAD. To branch from your current commit, setworktree.baseRefto"head"in your Claude Code settings, or name the exact commit in the assignment and have the worker check it out first. (Things that will bite you covers this trap.)initialPrompt: Auto-submits the first message when the agent runs as the main session with--agent.skills: Skills to preload at startup. It doesn’t restrict which others the agent can reach.mcpServers: MCP server names or inline definitions scoped to this agent. (An MCP server is a program that adds tools to the harness over the Model Context Protocol.)hooks: Lifecycle hooks scoped to this agent.memory: Gives the agent a persistent memory directory. Set it touser,project, orlocal:userstores it under~/.claude/agent-memory/<agent-name>/.projectstores it under.claude/agent-memory/<agent-name>/, which can be committed to the repository.localstores it under.claude/agent-memory-local/<agent-name>/, which stays out of version control.
omitClaudeMd: On v2.1.271+, skips user, project, and localCLAUDE.mdinstructions for a spawned subagent. Managed policy still loads for ordinary definitions; managed definitions can omit it too. It’s ignored when the definition runs as the main session through--agentor theagentsetting, and it isn’t a policy-free context switch; see the frontmatter reference.color: Terminal display color, such asred,blue,green,yellow,purple,orange,pink, orcyan.experimental.cacheTtl:5mor1h, the lifetime of this one agent’s prompt cache. ThesubagentPromptCacheTtlsetting does the same job session-wide for everything outside your main conversation, and per Claude Code’s prompt caching documentation, it wins when both are set.
Gotchas
- Omitting
toolsinherits everything: The subagent gets whatever the parent has. To make a leaf worker that can’t delegate any further, listtoolsexplicitly and leaveAgentout. - Bash is the soft spot: A shell can write files, so a “read-only” agent with
Bashisn’t. Back it with a settings deny rule, aPreToolUsehook (a script that runs before a tool call), or the sandbox (operating-system-level isolation that limits what files and network the agent’s shell commands can reach, no matter what the model decides). - Model selection takes the first match: The model passed when spawning, then the definition’s
model, then theCLAUDE_CODE_SUBAGENT_MODELenvironment variable, then the parent’s model. Forks (subagents that start with a copy of your conversation) always run on the parent’s model./tasksshows which model each subagent actually ran on. - Unknown fields fail silently: Write
max_turnsinstead ofmaxTurns, and it’s ignored without so much as a warning. - Plugin agents drop fields:
hooks,mcpServers,permissionMode, andinitialPromptall get dropped from agents that ship in a plugin. - Background by default: With fork mode on (the interactive default), subagents run in the background, and some tools are unavailable there. Where fork mode is off, foreground execution is available;
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1forces it. In an interactive session, a subagent’s permission request shows up in the main session, labeled with the subagent, and the worker waits for your answer. An unattended run may have nobody to answer, so define how it reports a blocked action instead of granting broader access to dodge the prompt. - Limits: 20 subagents running at once and three layers of nesting by default (a subagent starting subagents, which start more). Four children per agent across three layers is 4 + 16 + 64 = 84 workers. (Please don’t.)
Which model a subagent runs on
The model: line in a definition doesn’t guarantee that model. From Claude Code 2.1.251 on, for a custom agent, the first source that’s set wins: the model passed at spawn time, the definition’s model: (inherit means the main model), the CLAUDE_CODE_SUBAGENT_MODEL environment variable (inherit is the same as unset), and then the main conversation’s model.
Before 2.1.251, the environment variable sat at the top and overrode everything. Same files, opposite answer, and no warning either way:
CLAUDE_CODE_SUBAGENT_MODEL=haiku, plus… | Before 2.1.251 | 2.1.251 and later |
|---|---|---|
A definition with model: opus | Haiku | Opus |
| A model passed at spawn time | Haiku | The spawn-time model |
| Nothing else | Haiku | Haiku |
| The variable unset, nothing else | The main model | The main model |
To get the old behavior back, 2.1.257 added CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1. It applies the variable’s model, or the main model if the variable isn’t set, to every subagent and ignores definitions and spawn-time models. Forks and skills running with model: inherit are exempt. On 2.1.251 through 2.1.256 the flag doesn’t exist, so it silently does nothing.
The built-in agents follow their own rules. Explore inherits the main model, capped at Opus on a subscription, a Console account, or an LLM gateway (before 2.1.198 it always ran on Haiku). Plan runs on the main model. The environment variable alone doesn’t move either one; with FORCE on, it does. A project or user agent with the same name as a built-in replaces it and follows the custom-agent order above.
Don’t trust the order; check it. From 2.1.243, /tasks shows the model each subagent actually ran on. Last verified: 2026-10-04 against Claude Code 2.1.289.
Choosing a model per stage
Pick the model by what a mistake at that stage costs:
| Stage | Examples | Cost of a mistake | Claude Code model | Codex-side equivalent |
|---|---|---|---|---|
| Mechanical | Listing files, extracting fields, grepping a known pattern | Low: checkable by hand in seconds | haiku | Luna |
| Discovery | “Find bugs in this module” | High and invisible: a miss never reaches verification | sonnet | Sol |
| Judging | Refuting a finding, scoring competing approaches | High: nothing checks the checker | opus | Sol |
| Synthesis | Merging findings, writing the final report | Highest: it’s the version someone acts on | opus | Sol |
For narrow but careful work, raise the effort field before moving to a bigger model. Compare cost per accepted result, not per run. Prompt Caching and Cost has the prices behind these names.
Claude Code versus Codex
The biggest difference is who decides to delegate.
Claude Code delegates on its own judgment: it reads each agent’s description to route work, and you can force a choice with an @-mention or --agent. You tune the model’s judgment.
Codex delegates when you ask directly or when applicable AGENTS.md or skill instructions request it. You can name the agents in the prompt, but check those standing instructions too: they can trigger parallel work without a new request each turn. Codex runs the agents and gathers their results, and every worker adds token usage and concurrency.
Delegating well covers how to write the assignment these definitions get handed.
Set tools, set model, and check /tasks. Don’t trust the defaults.