How do I configure Claude Code managed settings (availableModels / deniedModels)?

Deploy managed settings (system managed-settings.json, MDM/OS policy, or server-managed from the claude.ai console / gateway) so org policy sits above user, project, local, and --settings. To restrict models: set availableModels, add enforceAvailableModels: true if Default must obey the list, and on Claude Code 2.1.283+ use deniedModels and/or availableModelsMatch: "exact". Confirm with /status → Enterprise managed settings. Tool ask/deny lives on the permissions Spec; sharing AGENTS.md / CLAUDE.md on the share Spec.

TL;DR: Managed settings = org policy above every other Claude Code settings file. Restrict models with availableModels (+ enforceAvailableModels for Default). On 2.1.283+, block versions with deniedModels or pin with availableModelsMatch: "exact" — both are managed-only. Managed model is a start default, not a lock. Verify /status. Labs seed: claude code managed settings (170 / KD 7). Checked managed-settings + model-config + CHANGELOG 2.1.283 on 2026-09-27.

What managed settings are (and where they live)

Managed settings are the settings your organization deploys so developers cannot widen them from ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, or --settings. A few security-sensitive keys still honor a stricter lower-level value; the default rule is: managed wins.

Same JSON shape as settings.json for enforceable keys. Place the file at:

OS	Path
macOS	/Library/Application Support/ClaudeCode/managed-settings.json
Linux / WSL	/etc/claude-code/managed-settings.json
Windows	C:\Program Files\ClaudeCode\managed-settings.json

Optional drop-ins: managed-settings.d/*.json next to that file (merged alphabetically after the main file). Other delivery: MDM/OS policy (Jamf, Intune, Group Policy), server-managed from the claude.ai console or a self-hosted gateway, and a Windows HKCU registry fallback when nothing higher delivers policy.

After deploy, run /status in Claude Code. Setting sources should show Enterprise managed settings (file|remote|plist|HKLM|…). Use claude doctor when entries were dropped. Honest limit: managed binds Claude Code only — not every other API client.

Managed can also lock permissions (deny rules, disableBypassPermissionsMode, allowManagedPermissionRulesOnly). Full ask/deny teaching stays on the permissions Spec — this page owns model allow/deny.

Restrict models with availableModels (+ enforce)

Enterprise admins set availableModels in managed settings to allowlist what users can pick. Entries match a family alias (sonnet, haiku, opus, fable), a version prefix (claude-sonnet-4-5), or a full model ID. Prefix matching matters: claude-fable-5 permits Fable 5 and Fable 5.1; claude-fable-5-1 permits 5.1 only. That is why deny/exact keys exist later.

When managed settings define availableModels, user/project/local lists cannot widen it. The allowlist covers /model, --model, ANTHROPIC_MODEL, the model setting, alias env pins, subagents/teammates, skill/command frontmatter models, advisor, and related surfaces (see model-config → Restrict model selection).

enforceAvailableModels: true (managed; v2.1.175+) extends the allowlist to the Default option so Default cannot escape to the account runtime default. Pair both keys in the highest-ranked managed source you deliver.

{
  "availableModels": ["sonnet", "haiku"],
  "enforceAvailableModels": true
}

What model is not: a managed "model": "sonnet" is a default start, not a lock. Users can still open /model and pick Default unless you deploy availableModels (+ enforce / deny / match). Invalid managed availableModels fails closed to an empty allowlist (Default only) until fixed.

deniedModels + availableModelsMatch (2.1.283)

CHANGELOG ## 2.1.283 adds two managed keys (HEAD checked 2026-09-27; ## 2.1.282 has no new model-allow/deny keys for this H1):

Key	Role
deniedModels	Block listed models even if the allowlist permits them; also works with no allowlist
availableModelsMatch: "exact"	Each availableModels ID permits only that version — newer siblings stay blocked until listed

Both are managed-only. In user/project/local settings or --settings, Claude Code ignores them with a warning.

{
  "availableModels": ["opus", "sonnet"],
  "deniedModels": ["claude-opus-5-5"]
}

Pair with requiredMinimumVersion so older CLIs that ignore the new keys cannot start. Fail-closed notes from managed-settings: invalid availableModelsMatch → treated as exact; wholly invalid deniedModels is dropped with a warning (does not block every model).

Pitfalls

• Expecting deniedModels / availableModelsMatch in ~/.claude/settings.json to enforce — managed-only.

• Treating managed model as a hard lock without availableModels.

• Cloning the permissions Spec body, or the AGENTS.md share Spec, instead of linking them.

• Dead-linking the memory Spec while it is still 404 — mention in prose (“companion memory Spec when live”) only.

• Inventing settings keys not in official docs / CHANGELOG.

• Skipping /status / claude doctor after rollout.

Thin ops neighbors (link only): max effort · rate limits.

FAQ

Where do I put managed settings on Linux?
/etc/claude-code/managed-settings.json (optional drop-ins in managed-settings.d/).

What’s the difference between availableModels and deniedModels?
availableModels is an allowlist. deniedModels is an explicit block — even when the allowlist would permit the model — and needs 2.1.283+ (managed-only).

Does setting "model": "sonnet" stop users picking Opus?
No. That sets the session start default. Restrict choice with availableModels (and enforceAvailableModels for Default).

Is this the same as configuring permissions ask/deny?
No. Ask/deny and permission modes: permissions Spec. Sharing instruction files: AGENTS.md / CLAUDE.md share Spec. Memory / CLAUDE.md setup: companion Spec when live (no dead link here).

How do I confirm policy applied?
/status → Setting sources lists Enterprise managed settings (…). claude doctor names dropped or invalid entries.

Sources (checked 2026-09-27)

• Deploy managed settings — precedence; file paths; delivery; /status; fail-closed keys including availableModels / deniedModels / availableModelsMatch

• Model configuration → Restrict model selection / Block specific models — availableModels, enforceAvailableModels, deniedModels, availableModelsMatch; managed model is not a lock

• Settings files and precedence — managed above user / project / local / --settings

• CHANGELOG — ## 2.1.283 (availableModelsMatch, deniedModels); supporting ## 2.1.175 (enforceAvailableModels); ## 2.1.282 checked — no new allow/deny keys for this H1

• Live bridges: permissions Spec · share AGENTS.md / CLAUDE.md