anthropics / anthropics/claude-code

Workflow docs: "default to omitting opts.model" makes every bare agent() run on the session model — the most expensive tier

Open Beginner friendly
#94,534 1 comment 0 reactions 0 assignees View on GitHub
area:agents area:cost documentation enhancement
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.