Workflow docs: "default to omitting opts.model" makes every bare agent() run on the session model — the most expensive tier
Status Open
Reported on v2.1.271
Maintainer reply None cached
Activity 1 comment · opened Sep 15, 2026
The Workflow script reference (Claude Code 2.1.271) says of agent():
opts.model overrides the model for this agent call. Default to omitting it — the agent inherits the main-loop model (the resolved session model), which is almost always correct. Only set it when you're highly confident a different tier fits the task; when unsure, omit.
On a premium session model that default is the costliest option available, and the guidance steers authors into it.
What we measured (Windows 11, ground truth read from each subagent transcript's message.model, not self-report):
- An 8-cell probe confirmed a bare
agent()(noagentType, nomodel) runs on the session model, and that anagentTypewhose definition pinsmodel:in frontmatter is honoured inside a workflow. - Every spawn pays roughly 50–180k cache-read plus 40–140k cache-write tokens of preamble before it does any work. At list prices a 100k + 100k preamble is about 9x more expensive on the top tier than on Haiku.
- Over one working day, 41 bare
agent()spawns accounted for $643.72 — 54% of all subagent spend. The same token volumes would have cost $170.76 on Sonnet and $85.38 on Haiku.
Suggested replacement text:
Omit it only when opts.agentType names a definition that pins a model — a definition's frontmatter model: is honoured inside a workflow. A bare agent() with neither agentType nor model inherits the session model, and each spawn carries roughly 100k cached input tokens of preamble before it does any work, so on a premium session that default is the most expensive option rather than the safest. When neither applies, name the tier the stage actually needs.
Related, different defect: #88695 (meta.phases[].model reads as an override but is display-only).
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗