anthropics / anthropics/claude-code
Workflow docs: "default to omitting opts.model" makes every bare agent() run on the session model — the most expensive tier
- Dominant language
- Python
- Stars
- 145k
- Forks
- 23.1k
- PR merge metrics
- PR metrics pending
Description
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()` (no `agentType`, no `model`) runs on the session model, and that an `agentType` whose definition pins `model:` 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).
Contributor guide
No contributing guide indexed for this repository
Research direction
Start at the Workflow script reference entry for agent(), especially the opts.model and opts.agentType guidance. Update the documentation to distinguish bare calls from definitions with frontmatter model:, retain the related distinction from #88695, and confirm the published text matches the suggested replacement.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 72/100