Claude Code 2.1.283 model allowlists: block surprise upgrades with exact matching

Quick answer

Claude Code 2.1.283 adds two managed controls for organizations that need a model approval gate. Set availableModelsMatch to "exact" when an availableModels entry must permit only the version it names. Use deniedModels as a separate emergency blocklist, even when another rule would allow that model. Do not stop at checking the /model picker: test startup flags, environment variables, Default, resumed sessions, subagents, skills, advisor mode, and fallback paths, then record the model that actually served each request.

This is a stable Claude Code release published on September 25, 2026. The controls require 2.1.283 or later and apply only from managed settings; user, project, local, and --settings copies are ignored with a warning.

Who this is for

This guide is for platform and security teams that approve model versions before production use. It matters when a minor release may change price, retention eligibility, context behavior, regional availability, or an internal evaluation result. Individual developers who only want a preferred default do not need this machinery; model is a default, while an allowlist is policy.

What changed and why the old prefix rule can surprise you

Before 2.1.283, a version-like entry used prefix matching. For example, "claude-opus-5" also permitted a later ID such as claude-opus-5-5. That is convenient for automatic adoption, but it is not a version approval gate.

With "availableModelsMatch": "exact", that entry permits Opus 5, including dated IDs for that version, but not Opus 5.5. There are three important boundaries:

• A family alias such as "opus" still permits the whole family. Do not use family aliases when the goal is version pinning.
• deniedModels wins over an allowlist. A full version block also covers dated and provider-specific spellings.
• Model selection is not uniformly fail-stop. An interactive switch can be rejected, startup can substitute the default with a warning, a subagent can fall back, and a skill override can be ignored. Success exit status is therefore not proof of policy compliance.

Start with a copyable managed policy

Deploy the policy through the admin console, MDM, or a managed settings file. Put the allowlist and its Default behavior in the same highest-ranked managed source.

{
  "availableModels": [
    "claude-opus-5",
    "claude-sonnet-5"
  ],
  "availableModelsMatch": "exact",
  "deniedModels": [
    "claude-opus-5-5"
  ],
  "enforceAvailableModels": true
}

The deny entry is intentionally redundant while exact matching is active. It remains an explicit incident cordon if someone later broadens the allowlist. Under managed-source merge behavior, deniedModels lists combine, availableModels is taken whole from the highest-ranked source that defines it, and the strictest availableModelsMatch lock applies.

Run a seven-surface canary

Use harmless prompts and a non-production account. Capture requested model, resolved model, client version, settings source, surface, warning or error, and request or session ID.

Canary	Attempt	Pass condition
Interactive	/model claude-opus-5-5	Switch is rejected or lands only on an explicitly permitted version
Startup	claude --model claude-opus-5-5	Warning and resolved model match the documented replacement path
Environment	Set ANTHROPIC_MODEL to the denied version	Denied version never serves the request
Default	Start with no explicit model	Default resolves inside the exact list
Resume	Resume a transcript saved on the denied version	Restored model is not used; receipt shows the replacement
Delegation	Request a denied subagent or teammate model	Actual fallback is recorded; no silent acceptance is counted as pass
Skill/advisor	Put a denied model in skill frontmatter and try --advisor	Skill stays on the session model; advisor follows its documented refusal path

Also run one negative configuration test: replace a version ID with the family alias "opus". The test should demonstrate that exact matching does not turn a family alias into a version pin. Restore the approved policy immediately afterward.

Promotion and rollback gate

Promote only when every managed delivery surface has fetched 2.1.283 or later, all seven canaries resolve to an approved model, and the receipt identifies the model that actually ran. Test CLI/IDE, Desktop local sessions, cloud sessions, self-hosted runners, and Agent SDK separately: server-managed settings do not reach every environment, and device-managed files do not reach Anthropic-hosted cloud VMs.

Rollback means restoring the last known policy, not loosening to a family alias. If a new model must be stopped urgently, add it to deniedModels, confirm distribution, rerun Default and delegation canaries, and keep the deny until the evaluation and allowlist change are approved together.

Common mistakes

• Treating model as a lock. It controls the starting choice, not the selectable set.
• Using "opus" or "sonnet" while claiming a version pin.
• Checking only the picker and missing startup substitution, subagent fallback, or ignored skill overrides.
• Putting the new keys in project settings, where they are ignored.
• Reading a zero exit code as proof without recording the resolved model.
• Assuming one delivery mechanism covers local, cloud, third-party-provider, and self-hosted sessions.

Make your Mac notch useful with SuperNotch—22 native tools for music, clipboard, focus, screenshots, system controls, and more.

FAQ

Does exact block dated IDs for an approved version?

No. The documentation says an exact version entry also permits that version's dated IDs. It blocks later versions, not alternate spellings of the approved version.

Can developers override these keys with --settings?

No. availableModelsMatch and deniedModels are managed-only. Claude Code ignores lower-scope copies and warns about them.

Is /model visibility sufficient evidence?

No. The picker is useful feedback, but policy validation needs an actual request receipt because fallback and substitution behavior differs by surface.

Sources

• Claude Code 2.1.283 release
• Claude Code model configuration
• availableModelsMatch reference
• deniedModels reference
• Managed settings merge behavior
• Community demand signal: non-interactive substitution visibility

Originally published on IndieSeek.