Claude Code model: which setting actually wins (2026)

Quick answer

I went looking for one number on 9 September 2026: which model is answering me right now. It took three separate precedence orders to find out. Claude Code resolves the session model through a five-level list, resolves settings files through a different five-level stack, and resolves subagents through a third four-level list. The two lists disagree about whether a file or an environment variable wins, and the two environment variables that both start with ANTHROPIC_ and both end in MODEL sit on opposite sides of your settings files. Counting conservatively, fourteen documented inputs can decide which model serves a request, and three of them can change it without you choosing again.

The moment

I have a model in my user settings. I remember setting it.

Last week a session started on something else, and I could not tell you why.

So I stopped guessing and read the configuration reference end to end. Everything below is from Anthropic's own documentation, read on 9 September 2026, with the version numbers it gives.

Three systems, not one

This is the part I had wrong. I assumed there was one priority list. There are three, and they are genuinely different lists, not three views of the same one.

One resolves the session model. One resolves settings files. One resolves subagents.

You can learn the first list perfectly and still be wrong about the third.

Finding 1: the session order has five levels

The model configuration reference lists these in priority order, highest first:

1. /model during the session
2. --model at startup
3. the ANTHROPIC_MODEL environment variable
4. the model field in a settings file
5. the ANTHROPIC_DEFAULT_MODEL environment variable

That looks tidy. It is also only the beginning, because item 4 is not a place. It is another whole stack.

Finding 2: environment variables are not in the settings stack

The settings reference gives its own five levels for where a key can live, highest first: managed settings, command line arguments, project local settings, shared project settings, then user settings.

Then it says the sentence that explains my missing week:

"Environment variables aren't a level in this stack. When a behavior has both a shell variable and a settings key, which one applies is decided per pair, not by level."

Per pair. Not by level.

So there is no general rule like "the shell beats your files". There is a rule for each variable, and for the model there are two variables that resolve in opposite directions:

Same prefix. Same subject. Opposite sides.

If you have ever exported one of these because a blog post told you to, and then wondered why your settings file stopped mattering, or why it never started mattering, that table is the answer.

Finding 3: subagents run a different order, and it flips

Here is the one that actually cost me. I have been running subagents daily since July, and I assumed they inherited the session list. They do not. The subagents reference resolves a subagent's model like this, highest first:

1. the per-invocation model parameter
2. the subagent definition's model frontmatter
3. the CLAUDE_CODE_SUBAGENT_MODEL environment variable
4. the main conversation's model

Read that against the session list.

In the session order, the environment variable sits at 3 and the file sits at 4. The variable wins.

In the subagent order, the file sits at 2 and the environment variable sits at 3. The file wins.

The relationship inverts. Whatever you learned from the first list is wrong for the second, and nothing warns you, because both lists are correct and neither mentions the other.

Finding 4: the subagent order flipped in v2.1.251

It gets better. That order is not old.

"Before v2.1.251, CLAUDE_CODE_SUBAGENT_MODEL came first in this order and overrode both the per-invocation parameter and the frontmatter, including model: inherit."

So the variable used to sit at the top of the subagent list, above everything. Now it sits third.

If you set that variable months ago to force your subagents onto a cheap model, it stopped being the final word at some point, and your frontmatter quietly took over.

There is a second dated flip in the same section: before v2.1.196, setting the variable to inherit forced subagents onto the main conversation's model and ignored the other sources. Now it is the same as leaving it unset.

Finding 5: three things move the model without you asking

Everything above is you choosing. These are not.

opusplan switches at the plan boundary. Opus while planning, Sonnet on execution. That one you opt into, so it is fair, but it does mean the model changes mid-session by design.

A fallback chain switches when a request fails. You set it with --fallback-model or the fallbackModel key, Claude Code caps the chain at three entries after removing duplicates, and the switch lasts for the current turn only. The chain also covers compaction, with one sensible guard: Claude Code will not fall back to a model with a smaller context window than the primary, because summarising there would cut off part of the conversation first.

The documentation is unusually candid about how invisible this one is:

"Claude Code doesn't confirm the chain at startup and /status doesn't display it. The notice shown when a switch happens is the first visible sign that a fallback is configured."

So the only way to discover a fallback chain is to watch it fire.

A safety classifier switches on content. Requests flagged as cybersecurity or biology get re-run on a different model.

Finding 6: the one that sticks

The first two are scoped. opusplan follows the mode, and a fallback chain lasts one turn.

The third does not:

"After a fallback, the session continues on the fallback model."

That is the sentence I wish I had read in July. A flagged request does not just get answered elsewhere. It relocates the session, and it stays there until you run /model again.

There is a detail that makes this land on ordinary work rather than exotic work. The docs note that fallback can trigger on the very first request of a session, before you type anything unusual, because that request carries your workspace context: your CLAUDE.md, your git status, your directory names. A repository with security or biology material can trip the classifier on that context alone.

If you want to test whether your own customizations are the trigger, there is a documented way to strip them:

claude --safe-mode

That disables CLAUDE.md, skills, MCP servers and hooks. Git status and directory names still go along, so it isolates the customizations rather than the repository.

You can also turn the automatic part off and get asked instead, with switchModelsOnFlag:

{
  "switchModelsOnFlag": false
}

Finding 7: what page one tells you about this

I wanted to know whether I had simply failed to read the obvious. So I took the Google results for claude code model on 9 September 2026 and counted.

Eight organic results. Three refused an anonymous client, returning 403, 403 and 429, so I excluded them rather than score a blocked fetch as clean. That leaves five I could actually read.

Of those five, the number that mention ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_MODEL, CLAUDE_CODE_SUBAGENT_MODEL, fallbackModel, opusplan, or the word precedence at all is zero.

I ran the same check against Anthropic's model configuration page as a control, and it matched all six terms, so the zero is a real result and not a broken grep.

Anthropic's own documentation does not appear anywhere in the top eight either. The first result is a Reddit thread comparing four harnesses. One is a Python package that happens to be called claude-code-model and is unrelated. One is a post from early 2025.

The information exists. It is just not where anyone looks.

The count

Here is the full tally, on the Anthropic API, ignoring provider-specific pins for Bedrock, Foundry and Agent Platform, which add more.

Fourteen. And the model key on that first row is itself resolved through the five-level file stack from Finding 2.

The resumed-session entry deserves its own note, because it is the one that looks like a bug and is not. A session resumed with --resume or --continue keeps the model saved in its transcript, regardless of your current model setting. That is deliberate, so another session's /model choice cannot change the model under a conversation you come back to.

What I do now

Three things, and they are all small.

I check rather than assume. /status shows the current model, and so does the status line if you have one configured. For subagents there is /tasks, which names the model on each subagent's row.

I stopped exporting model variables in my shell profile. A variable that outranks every file, set once and forgotten, is exactly the thing I could not explain last week. If I want a model for one session I pass --model and it dies with the session.

And when a session starts on the wrong model, I now check whether I resumed it before I check anything else. That is the answer more often than not.

What this does not prove

This is a documentation reading, not a behavioural test. I have not empirically verified all fourteen inputs against a running install, and precedence is exactly the kind of thing where the implementation can drift from the reference.

The version numbers cut both ways. Several of these rules are dated to specific releases in the low v2.1.200s, which tells me the surface is still moving. Anything here could be re-ordered again, as the subagent list already was.

The count of fourteen is mine, not Anthropic's, and it depends on where you draw the line between choosing a model and constraining one. I counted the allowlist as an input because it can change which model you get. Someone could reasonably not.

And the Google measurement is five pages on one day from one machine. The three I could not fetch might cover precedence beautifully.

If you want to re-run any of it, the commands and the doc links are above.

Postscript: I did eventually find my missing model setting. It was a --model flag in a shell alias I wrote in June and forgot.