The Model System

The model system is split across two directories. Every path below is in src/.

Every model the system can reference is declared in a single object in configs.ts. Each entry is a ModelConfig — a record keyed by provider — so the same logical model has exactly one canonical entry regardless of how Bedrock or Vertex want to name it.

// utils/model/configs.ts
export type ModelConfig = Record<APIProvider, ModelName>

export const CLAUDE_OPUS_4_6_CONFIG = {
  firstParty: 'claude-opus-4-6',
  bedrock:     'us.anthropic.claude-opus-4-6-v1',
  vertex:      'claude-opus-4-6',
  foundry:     'claude-opus-4-6',
} as const satisfies ModelConfig

// @[MODEL LAUNCH]: Register the new config here.
export const ALL_MODEL_CONFIGS = {
  haiku35:  CLAUDE_3_5_HAIKU_CONFIG,
  haiku45:  CLAUDE_HAIKU_4_5_CONFIG,
  sonnet35: CLAUDE_3_5_V2_SONNET_CONFIG,
  sonnet37: CLAUDE_3_7_SONNET_CONFIG,
  sonnet40: CLAUDE_SONNET_4_CONFIG,
  sonnet45: CLAUDE_SONNET_4_5_CONFIG,
  sonnet46: CLAUDE_SONNET_4_6_CONFIG,
  opus40:   CLAUDE_OPUS_4_CONFIG,
  opus41:   CLAUDE_OPUS_4_1_CONFIG,
  opus45:   CLAUDE_OPUS_4_5_CONFIG,
  opus46:   CLAUDE_OPUS_4_6_CONFIG,
} as const satisfies Record<string, ModelConfig>

The Four Providers

// utils/model/providers.ts
export function getAPIProvider(): APIProvider {
  return isEnvTruthy(process.env.CLAUDE_CODE_USE_BEDROCK)
    ? 'bedrock'
    : isEnvTruthy(process.env.CLAUDE_CODE_USE_VERTEX)
      ? 'vertex'
      : isEnvTruthy(process.env.CLAUDE_CODE_USE_FOUNDRY)
        ? 'foundry'
        : 'firstParty'
}

async function getBedrockModelStrings(): Promise<ModelStrings> {
  const profiles = await getBedrockInferenceProfiles()
  const out = {} as ModelStrings
  for (const key of MODEL_KEYS) {
    const needle = ALL_MODEL_CONFIGS[key].firstParty
    out[key] = findFirstMatch(profiles, needle) || fallback[key]
  }
  return out
}

getMainLoopModel() in model.ts is the single function that determines which model runs a conversation. It walks five layers in strict priority order:

1. /model command during session Stored in bootstrap state as mainLoopModelOverride. Highest priority — overrides everything for the rest of the session.
2. --model CLI flag at startup Also sets mainLoopModelOverride in bootstrap state, but only before the session begins.
3. ANTHROPIC_MODEL env var Checked synchronously. Accepts both full model IDs and aliases.
4. settings.json → model field Set by /model and persisted across sessions. The only layer migrations touch.
5. Built-in subscription default Max/Team Premium → Opus 4.6. Everyone else → Sonnet 4.6 (3P may default to 4.5).

// utils/model/model.ts — simplified
export function getUserSpecifiedModelSetting(): ModelSetting | undefined {
  const modelOverride = getMainLoopModelOverride()          // layers 1+2
  if (modelOverride !== undefined) return modelOverride

  const settings = getSettings_DEPRECATED() || {}
  const specifiedModel =
    process.env.ANTHROPIC_MODEL || settings.model || undefined    // layers 3+4

  if (specifiedModel && !isModelAllowed(specifiedModel)) return undefined
  return specifiedModel
}

export function getRuntimeMainLoopModel(params: {
  permissionMode: PermissionMode
  mainLoopModel: string
  exceeds200kTokens?: boolean
}): ModelName {
  if (getUserSpecifiedModelSetting() === 'opusplan'
      && permissionMode === 'plan'
      && !exceeds200kTokens) {
    return getDefaultOpusModel()    // upgrade to Opus in plan mode
  }
  if (getUserSpecifiedModelSetting() === 'haiku' && permissionMode === 'plan') {
    return getDefaultSonnetModel()   // upgrade haiku to sonnet for plan
  }
  return mainLoopModel
}

Users never need to type a full versioned model ID. The alias system resolves short names to current provider-appropriate model strings:

// utils/model/aliases.ts
export const MODEL_ALIASES = [
  'sonnet', 'opus', 'haiku', 'best',
  'sonnet[1m]', 'opus[1m]',
  'opusplan',
] as const

The [1m] suffix is special: it is accepted on any alias or model ID and signals the 1 million token context window variant. parseUserSpecifiedModel() strips it before resolving the base model, then re-appends it so the API receives the correct model string:

export function parseUserSpecifiedModel(modelInput: ModelName | ModelAlias): ModelName {
  const has1mTag  = has1mContext(normalizedModel)           // checks for [1m] suffix
  const baseModel = has1mTag
    ? normalizedModel.replace(/\[1m]$/i, '').trim()
    : normalizedModel

  if (isModelAlias(baseModel)) {
    switch (baseModel) {
      case 'opus':   return getDefaultOpusModel() + (has1mTag ? '[1m]' : '')
      case 'sonnet': return getDefaultSonnetModel() + (has1mTag ? '[1m]' : '')
      case 'haiku':  return getDefaultHaikuModel() + (has1mTag ? '[1m]' : '')
      // ...
    }
  }
  return modelInputTrimmed  // preserve original case for custom IDs
}

Extended context is not a separate model; it is a runtime flag on an existing model. The [1m] suffix travels through the entire pipeline and is stripped only at the API call boundary by normalizeModelStringForAPI().

Access Gates

Two functions gate access to 1M, one each for Opus and Sonnet:

// utils/model/check1mAccess.ts
export function checkOpus1mAccess(): boolean {
  if (is1mContextDisabled()) return false    // CLAUDE_CODE_DISABLE_1M_CONTEXT env
  if (isClaudeAISubscriber()) return isExtraUsageEnabled()  // subscriber: extra-usage billing
  return true                                  // API/PAYG: always available
}

The Opus 1M Merge

For Max and Team Premium subscribers, there is only one Opus option: opus[1m] — they always get extended context. This "merge" is controlled by isOpus1mMergeEnabled():

export function isOpus1mMergeEnabled(): boolean {
  if (is1mContextDisabled() || isProSubscriber() || getAPIProvider() !== 'firstParty')
    return false
  if (isClaudeAISubscriber() && getSubscriptionType() === null)
    return false  // fail closed: unknown sub type → no 1M (avoids API rate-limit error)
  return true
}

Effort is a thinking-budget hint sent to the API as a parameter. It only applies to models that support it — currently claude-opus-4-6 and claude-sonnet-4-6.

Resolution order

// utils/effort.ts — resolveAppliedEffort()
// Priority: env > appState > model default
const envOverride = getEffortEnvOverride()  // CLAUDE_CODE_EFFORT_LEVEL env var
if (envOverride === null) return undefined    // null = explicit 'unset'
const resolved = envOverride ?? appStateEffortValue ?? getDefaultEffortForModel(model)
// API rejects 'max' on non-Opus-4.6 — auto-downgrade
if (resolved === 'max' && !modelSupportsMaxEffort(model)) return 'high'
return resolved

Persistence rules

Not all effort values can be saved to settings.json. The toPersistableEffort() function enforces these constraints:

• low, medium, high — always persisted
• max — only persisted for Anthropic employees (USER_TYPE === 'ant'); session-scoped for everyone else
• Numeric values (e.g. 42) — never persisted, model-default only

Fast mode is a research-preview feature that enables a lower-latency execution path for Opus 4.6 only on the first-party API. It is toggled via /fast or settings, and the command is hidden unless fast mode is available for the session.

// commands/fast/index.ts
const fast = {
  type: 'local-jsx',
  name: 'fast',
  get description() { return `Toggle fast mode (${FAST_MODE_MODEL_DISPLAY} only)` },
  availability: ['claude-ai', 'console'],
  isEnabled: () => isFastModeEnabled(),
  get isHidden() { return !isFastModeEnabled() },
}

Availability checks

Fast mode goes through a layered availability check before being offered to the user:

• CLAUDE_CODE_DISABLE_FAST_MODE=1 hard-disables it globally
• Only available on firstParty provider — not on Bedrock/Vertex/Foundry
• Requires a paid subscription; free accounts see "Fast mode requires a paid subscription"
• Subscribers need extra-usage billing enabled; without it the reason is "Fast mode requires extra usage billing"
• Not available in the Agent SDK (non-interactive sessions) unless fastMode: true is explicitly set in flag settings
• Statsig feature flag tengu_penguins_off can kill it remotely with a custom reason string

Model switching on toggle

Enabling fast mode only switches the model if the current model does not support fast mode. If you are already on Opus 4.6, the model is left unchanged:

// commands/fast/fast.tsx — applyFastMode()
if (enable) {
  setAppState(prev => {
    const needsSwitch = !isFastModeSupportedByModel(prev.mainLoopModel)
    return {
      ...prev,
      ...(needsSwitch ? { mainLoopModel: getFastModeModel() } : {}),
      fastMode: true,
    }
  })
}

Enterprise and team admins can restrict which models users can select by setting availableModels in a policy settings file. The matching logic has three tiers, applied in order:

1. Family wildcard — "opus" allows any Opus model, unless narrower entries for that family also exist
2. Version prefix — "opus-4-5" or "claude-opus-4-5" matches any build of that version at a segment boundary
3. Exact ID — "claude-opus-4-5-20251101" matches only that exact string

// Example: restrict to Sonnet 4.6 and Haiku 4.5 only
// ~/.claude/settings.json (admin policy)
{
  "availableModels": ["sonnet", "haiku"]
}

// Example: allow only Opus 4.5 (not 4.6)
{
  "availableModels": ["opus-4-5"]
}

// Example: empty allowlist blocks ALL user-specified models
// (user gets the subscription default only)
{
  "availableModels": []
}

export function isModelAllowed(model: string): boolean {
  const { availableModels } = settings
  if (!availableModels) return true         // no restriction
  if (availableModels.length === 0) return false // empty blocks all

  // 1. Direct match — but skip family aliases that are narrowed
  if (allowlist.includes(model)) {
    if (!isModelFamilyAlias(model) || !familyHasSpecificEntries(model, allowlist))
      return true
  }

  // 2. Family wildcard (only if no specific entries for that family)
  for (const entry of allowlist) {
    if (isModelFamilyAlias(entry)
        && !familyHasSpecificEntries(entry, allowlist)
        && modelBelongsToFamily(model, entry)) return true
  }

  // 3. Version-prefix match at segment boundary
  for (const entry of allowlist) {
    if (!isModelFamilyAlias(entry) && !isModelAlias(entry)) {
      if (modelMatchesVersionPrefix(model, entry)) return true
    }
  }

  return false
}

When Claude Code spawns a subagent (via Task tool or SDK), the subagent needs to know which model to use. The resolution happens in utils/model/agent.ts and follows this precedence:

1. CLAUDE_CODE_SUBAGENT_MODEL env var Global override for all subagents. Useful in CI pipelines.
2. Tool-specified model (model param on the Task call) The orchestrating model can request a specific model for a subagent.
3. Agent config model field Set in the agent definition. Accepts any alias or model ID.
4. "inherit" (default) Subagent uses the same model as the parent thread, including opusplan resolution.

Alias-matches-parent-tier optimization

When a bare family alias (opus, sonnet, haiku) matches the parent model's family, the subagent inherits the parent's exact model string instead of resolving the alias to the provider default. This prevents a Vertex user on a pinned Opus version from having subagents silently downgrade:

// utils/model/agent.ts
function aliasMatchesParentTier(alias: string, parentModel: string): boolean {
  const canonical = getCanonicalName(parentModel)
  switch (alias.toLowerCase()) {
    case 'opus':   return canonical.includes('opus')
    case 'sonnet': return canonical.includes('sonnet')
    case 'haiku':  return canonical.includes('haiku')
    default: return false
  }
}
// Note: opus[1m], best, opusplan fall through — they have extra semantics

Bedrock region prefix inheritance

On Bedrock, cross-region inference profiles carry a region prefix (eu., us.). If the parent model uses eu.anthropic.claude-opus-4-6-v1, subagents using alias models must also use the eu. prefix. This is handled by applyParentRegionPrefix() — which is skipped if the subagent's model spec already carries its own explicit prefix.

When Claude Code upgrades its default models, users who had previously pinned a specific model need their settings migrated automatically. The migration system runs a set of functions on every startup; each migration is idempotent (safe to re-run).

Live model validation

When a user types a custom model ID into /model, the system cannot know if it is valid just by string-matching. validateModel() sends a real API call with max_tokens: 1 to probe the model:

// utils/model/validateModel.ts
await sideQuery({
  model: normalizedModel,
  max_tokens: 1,
  maxRetries: 0,
  querySource: 'model_validation',
  messages: [{ role: 'user', content: [{ type: 'text', text: 'Hi' }] }],
})

A NotFoundError (404) means the model does not exist. For 3P users, a fallback suggestion is returned (e.g. if you ask for opus-4-6 on Vertex but it is not available yet, it suggests opus-4-1).

Deprecation warnings

The deprecation table in deprecation.ts maps model substrings to retirement dates per provider:

const DEPRECATED_MODELS: Record<string, DeprecationEntry> = {
  'claude-3-7-sonnet': {
    modelName: 'Claude 3.7 Sonnet',
    retirementDates: {
      firstParty: 'February 19, 2026',
      bedrock:    'April 28, 2026',
      vertex:     'May 11, 2026',
      foundry:    'February 19, 2026',
    },
  },
  // ...
}

If the active model matches any entry and has a retirement date for the current provider, the UI shows a yellow warning banner. Bedrock and Vertex often get longer retirement windows than first-party.