Choosing Model, Tools, and Color
The Model Field
The model field controls which Claude model powers the subagent — a direct lever on speed, cost, and capability. You have four kinds of values: a model alias (sonnet, opus, haiku), a full model ID (e.g. claude-opus-4-8), 'inherit' (use the main conversation's model), or omit it (defaults to inherit).
| Choice | Best for |
|---|---|
| haiku | Fast, lightweight, high-volume tasks (e.g. broad search) — cheapest |
| sonnet | A balance of speed and depth — good default for code analysis |
| opus | Complex analysis where capability matters most |
| inherit (default) | Match the main conversation's model |
Pick the cheapest model that does the job well — this is how subagents control cost.
Resolution order (advanced)
When a subagent runs, Claude Code resolves its model in this order: (1) the CLAUDE_CODE_SUBAGENT_MODEL environment variable, (2) a per-invocation model parameter, (3) the subagent's frontmatter model, (4) the main conversation's model. The env var wins over everything.
The Tools Field: Least Privilege
Tool access is both a safety control and a focusing mechanism. Give a subagent only the tools its job requires. You have two complementary fields: tools (an allowlist) and disallowedTools (a denylist). If both are set, disallowedTools is applied first, then tools is resolved against what remains.
# Allowlist: ONLY these four tools, nothing else
---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---# Denylist: inherit everything EXCEPT writes
---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---Common Tool Profiles
| Subagent type | Tools | Rationale |
|---|---|---|
| Research / read-only | Read, Grep, Glob | Cannot accidentally modify files |
| Code reviewer | + Bash | Needs git diff to see changes; still no Edit/Write |
| Styling / modifier | + Edit, Write | Its job IS to change code |
| Full access | (omit tools) | Inherits all tools from the parent |
Match the tool set to the job: read-only for research, Bash for reviewers, Edit/Write only for agents meant to change code.
Some tools never reach subagents
A few tools are unavailable to subagents even if you list them, because they depend on the main UI/session: Agent (no nesting), AskUserQuestion, EnterPlanMode, ExitPlanMode (unless permissionMode is plan), ScheduleWakeup, and WaitForMcpServers.
Color and Persistent Memory
Color is a small but useful touch: it shows up in the UI so you can quickly tell which subagent is active when several are running. Options are red, blue, green, yellow, purple, orange, pink, and cyan.
For subagents you use repeatedly, the memory field gives a persistent directory that survives across conversations — the subagent accumulates knowledge (codebase patterns, recurring issues) over time. Scopes: user (~/.claude/agent-memory/, all projects), project (.claude/agent-memory/, shareable via git), or local (not checked in). Project is the recommended default.
Section complete
You can now create, configure, scope, and tune a subagent. The next section is about DESIGN — the patterns that turn a configured subagent into a reliable one: descriptions, output formats, and tool limits.
Key Takeaways
- ✓The model field takes an alias (haiku/sonnet/opus), a full model ID, 'inherit', or is omitted (defaults to inherit) — your lever on speed, cost, and capability.
- ✓Pick the cheapest model that does the job: Haiku for fast bulk work, Sonnet as a balanced default, Opus for complex analysis.
- ✓Model resolution order: CLAUDE_CODE_SUBAGENT_MODEL env var > per-invocation > frontmatter > main model.
- ✓Restrict tools via 'tools' (allowlist) or 'disallowedTools' (denylist); if both, disallowedTools applies first. Omitting 'tools' inherits all.
- ✓Tool profiles: research = Read/Grep/Glob; reviewer = +Bash (git diff); modifier = +Edit/Write; full = omit tools.
- ✓Some tools never reach subagents (Agent, AskUserQuestion, EnterPlanMode, etc.); color aids UI identification; the memory field (project recommended) gives persistent cross-session learning.
Check Your Understanding
Test what you learned in this lesson.
Q1.What does setting model: inherit do for a subagent?
Q2.Which model is the best choice for a fast, high-volume codebase search subagent?
Q3.If a subagent sets both 'tools' and 'disallowedTools', how are they resolved?
Q4.Which tool is NEVER available to a subagent, even if listed?
Practice This Lesson