claude-code - 💡(How to fix) Fix Workflow model override: 'use Opus to plan' leaks to all subagents instead of planning phase only

Summary

When a user says something like "use Opus to plan, and a workflow if needed", Claude applies model: 'opus' to every agent() call inside the workflow script rather than scoping it to planning-phase agents. This turns a planning-phase instruction into a session-wide model override, dramatically inflating cost.

Steps to reproduce

1. Start a session with default model = Sonnet (or opusplan).
2. Ask Claude to perform a multi-step task and say "use Opus to plan" or "use Opus for planning".
3. Claude generates a workflow script and sets model: 'opus' on every agent() call — including code-writing and file-editing agents that have no planning function.

Expected behaviour

• model: 'opus' should be applied only to agents whose role is design/reasoning (e.g., a "plan" phase agent).
• Code generation, file writing, and execution agents should inherit the session default (Sonnet).
• Alternatively, the documentation/prompt should make clear that model on agent() is a per-agent override, and that "plan with Opus" does not mean "run all agents on Opus".

Actual behaviour

All agents in the workflow ran on Opus. In the session that surfaced this, three consecutive workflows each used Opus for every subagent (including pure code-writing tasks), producing a ~$34 session cost where $5–8 would have been appropriate.

Root cause

The instruction "use Opus to plan" is ambiguous when combined with workflows. The workflow API provides a model parameter on each agent() call with no built-in concept of "planning agent vs execution agent". When the user directive mentions both Opus and workflows, Claude conflates the planning-phase model preference with a global per-agent override.

Suggested fix

One or more of:

• Documentation: Clarify in workflow authoring docs that model on agent() is a per-agent override and that planning-phase guidance should only apply to agents doing pure design/reasoning work.
• Prompt guidance: Add a note in Claude's internal workflow-authoring instructions: "Only set model: 'opus' on agents whose sole task is design or reasoning. Leave execution, code-generation, and file-writing agents at the default model."
• Clearer user-facing instruction patterns: Document canonical phrasings like "Opus for reasoning, Sonnet for writing" so users can express the intent precisely.

Workaround

Users can be explicit: "Use Opus only for the planning phase; use Sonnet for all code generation and execution agents." Tying the model to the phase (not the tool) prevents the ambiguity.

Environment

• Claude Code version: current (session date 2026-06-09)
• Model: claude-sonnet-4-6 (session default), claude-opus-4-6 (incorrectly applied to all workflow agents)

🤖 Filed via Claude Code