---
type: types/instruction.md
name: claude-code-model-selection
description: Which Claude model and effort level to run a Claude Code session, a spawned subagent, or a /code-review pass at for a given task in this repo.
---

# Pick the Claude model and effort level for the task at hand

Scale the model and effort to **what catches a mistake in this part of the work** - not to how
important the task feels, and not to its name. Running everything at the most capable model and
highest effort is safe but wasteful: the gates in [gates.md](gates.md) are enforced in code, not
by model judgment, so a weaker model cannot bypass them - it can only do a worse job of the calls
the gates don't cover.

That last clause is the whole rule, turned into a test. Where a check lives in code - `pytest`,
`docs verify`, `instructions verify`, CI, the gates - a weaker model's mistake surfaces and costs
one more round. Where the only enforcement is a session reading prose, the same mistake does not
surface at all: it ships, and it stays until someone happens to notice. The two are not the same
risk, and they should not get the same model. This is the argument
[docs/why-gates-are-code.md](../docs/why-gates-are-code.md) makes about gates, applied to who is
holding the keyboard.

Both directions cost something, which is why the axis matters rather than a blanket answer:
over-provisioning is a standing cost paid every session, while under-provisioning in an unchecked
phase is a silent error with a long tail. A corrective session, its bump, its CI runs and its
release together cost more compute than the model difference they were saving.

Claude-Code-only, and imported by CLAUDE.md rather than linked from AGENTS.md: the model names,
the `/code-review` effort dial and the `Agent` tool's `model:` override have no equivalent in the
other harnesses this repo supports (Codex CLI, GitHub Copilot CLI, Mistral Vibe). See
[instructions/CONTRACT.md](CONTRACT.md) for that split.

## When to run

Before spawning a subagent with an explicit `model:` override, before picking a `/code-review`
effort level, and when the user asks which model to use - or when the session's current model is
clearly mismatched to the task that just started.

Two of the three choices are the agent's to make; the session's own model is not. An agent cannot
switch the model it is running as - that is the user's `/model` - so step 1 is a recommendation
to *make*, not a setting to apply.

## Steps

1. **Recommend the session's model and effort by what catches a mistake in the phase it is in**,
   when asked or when the mismatch is worth one sentence. Say it once and continue working either
   way - a session that argues about its own model instead of doing the task has already cost
   more than the model difference:

   | Phase / task | What catches a mistake here | Model | Effort |
   |---|---|---|---|
   | `wiki-status`, simple `wiki-query` lookups | the answer is re-checkable against the corpus | Sonnet | default |
   | `wiki-lint` | `lint` itself is the check | Sonnet | default |
   | `wiki-ingest`, `wiki-manage`, judgment-heavy `wiki-query` | `lint` and `docs verify`, partly - the judgment about a claim is not covered | Sonnet | high |
   | Stack dev: design, the version part, a boundary-crossing judgment | nothing - `docs verify` checks that a crossing documents itself, never that the part was right | Opus | high |
   | Stack dev: code, tests, mechanical doc sync (command tables, contract rows) | `pytest`, `docs verify`, `instructions verify`, CI | Sonnet | high |
   | Stack dev: closing an issue, `docs/` staleness, changelog prose | nothing, by construction - see below | Opus | high |

   **Stack development is not one row**, which is the point of splitting it. The middle phase is
   where the tokens are and where the checks are, so it is the phase worth running cheaper. The
   two around it have no mechanical guard at all - a `docs/` page carries no normative sentence,
   so there is nothing for `docs verify` to check ([AGENTS.md](../AGENTS.md) § File naming), and
   the same holds for whatever tracker an instance keeps its open work in, which `wikitool`
   deliberately knows nothing about. Those two phases are short - minutes, not hours - so keeping
   them on the stronger model is cheap, and it protects the only work in the session that fails
   silently.

   **Effort is the cheaper lever than the model.** Reach for it first: `medium` deliberately does
   not appear in this table for stack work, because multi-file consistency is exactly what a
   reduced effort level gives up. Sonnet at `high` is the floor for anything touching more than
   one file or a contract; `default` is for a single-file mechanical edit with a test behind it.

   **A session cannot switch its own model**, so these rows only become real if someone offers the
   switch at the moment the phase changes - once, without arguing about it, and never as a reason
   to stop work that is already underway.
<!-- dist:strip-start -->
   In this repo those moments are named: the `stack-dev` skill breaks for them at its steps 3
   (design settled, work turns mechanical) and 6 (publish done, the unchecked tail begins).
<!-- dist:strip-end -->

2. **Pick a spawned subagent's model by what it does**, via the `Agent` tool's `model:`
   parameter - the values are `haiku`, `sonnet`, `opus`, `fable`:

   - Read-only search/lookup (an `Explore` agent, or a `general-purpose` agent doing pure
     retrieval): `model: "haiku"`. No judgment call is being delegated, only retrieval.
   - A subagent that writes pages, reviews code, or decides something: leave `model:` off so it
     inherits the session's model, chosen per step 1.
   - A fork (`subagent_type: "fork"`) always inherits the parent session's model; a `model:`
     override on a fork is ignored.

3. **Pick a `/code-review` effort level by blast radius, not by habit.** The levels are `low`,
   `medium`, `high`, `xhigh`, `max` and `ultra` (multi-agent, in the cloud):

   - A routine diff (a skill wording fix, an ordinary ingest's tool output): `low` or `medium` -
     fewer, high-confidence findings are enough.
   - Gate code (`run_budget.py`, `git_publish.py`, anything implementing the Mass-Update or
     Iteration gates), the compiler, or a change about to ship in a version bump: `high` and up -
     broader coverage is worth the cost when the blast radius of a missed bug is a safety gate.
   - `ultra` is user-triggered and billed separately; recommend it, never assume it.

## Decision points

- **Task spans both a mechanical step and a judgment call?** Pick by the judgment call, not the
  mechanical one - `wikitool` carries the mechanical part regardless of which model is
  supervising it.
- **Unsure which row applies?** Default to Sonnet at high effort, not the most capable model at
  the highest effort. Under-provisioning *where a check exists* costs one worse answer in one
  session; reflexively over-provisioning is a standing cost paid every session.
- **Unsure whether the phase is checked?** Treat it as unchecked. The asymmetry is not symmetric:
  a needless Opus phase costs money once, an unchecked Sonnet phase can ship something nobody
  looks at again.
- **Mid-session and the phase changed, but nobody switched?** Do the work anyway - never block a
  publish or an issue close on a model the session cannot change itself. Say which phase ran on
  which model in the handover, so the gap is visible rather than silent.

## Scope

Does not apply to non-Claude-Code harnesses - see the note above; a follow-up issue tracks
whether and how they should decide this differently. Does not set the classifier model behind
Claude Code's own `auto` permission mode - that is a harness internal, not a per-task choice
this repo controls.