Claude Code's managed settings already deny some reads, yet developers still pre-approve tools and run their own hooks — which managed-only keys close that gap?
answer
- managed wins conflicts, lists still merge
- a lock honours only the managed value
- permissions, hooks, MCP servers, marketplaces
- the allowManaged…Only family
- bypass mode has its own switch
basics
~10 sManaged settings win conflicts, but lists such as permission rules and hooks still merge in from lower files. Locks close that: allowManagedPermissionRulesOnly, allowManagedHooksOnly, allowManagedMcpServersOnly and strictKnownMarketplaces make Claude Code honour only managed values.
solid answer
~40 s"Managed wins" only settles conflicting values. Permission rules, hooks and MCP allowlists are lists, and lists from user, project and local files still merge in, so a developer's own `allow` rules and hooks keep working beside the managed `deny`. The managed-only **locks** change that: `allowManagedPermissionRulesOnly` makes managed settings the only source of permission rules (it also ignores `--allowedTools` and hides the always-allow choices); `allowManagedHooksOnly` runs only managed hooks, SDK hooks and hooks from plugins managed `enabledPlugins` force-enables; `allowManagedMcpServersOnly` reads `allowedMcpServers` from managed settings alone; `strictKnownMarketplaces` allowlists plugin marketplace sources. Add `permissions.disableBypassPermissionsMode: "disable"` so `--dangerously-skip-permissions` is rejected. These keys do nothing in user or project files.
code
json · 12 lines{
"permissions": {
"deny": ["Read(./.env)", "Read(./secrets/**)"],
"disableBypassPermissionsMode": "disable"
},
"allowManagedPermissionRulesOnly": true,
"allowManagedHooksOnly": true,
"strictKnownMarketplaces": [
{ "source": "github", "repo": "example-org/approved-plugins" }
],
"availableModels": ["sonnet", "haiku"]
}go deeper
Remember that an organization can lock some settings so only its own values count, and that a developer's files then cannot add to them.
Explain why list keys merge across files, and name the lock for permission rules, hooks, MCP servers and plugin marketplaces.
Show the side effects you plan for: --allowedTools ignored, always-allow choices hidden, /goal unavailable, and an empty marketplace allowlist blocking the official one.
Weigh lockdown against developer autonomy: each lock moves ownership of a list to the platform team, which must then curate it.
## Why "managed wins" is not "only managed" Claude Code layers settings files, with **managed settings** on top. When two files set the same single value, the higher one wins. But many security-relevant keys are **lists** — `permissions.allow`, `permissions.deny`, `hooks`, `allowedMcpServers` — and lists from different files **merge**. A managed `deny` therefore sits beside whatever `allow` rules a developer keeps in `~/.claude/settings.json` or a repository's `.claude/settings.json`, and every hook those files declare still runs. The deny rules still beat any allow rule that matches them, but everything the managed policy didn't mention remains the developer's to grant. A **lock** is a managed-only key that tells Claude Code to honour only the managed value of some list. Most locks govern an ordinary key any level can set; the lock itself is read only from a managed source, and placing it in a user or project file has no effect. ## The locks | Lock | What it narrows to managed only | Side effect or exception | | :- | :- | :- | | `allowManagedPermissionRulesOnly` | `allow`, `ask` and `deny` rules; also ignores `--allowedTools`, hides the always-allow choices in prompts and stops saving new rules | `--disallowedTools` and session `deny`/`ask` rules, which only restrict | | `allowManagedHooksOnly` | Hooks: only managed hooks, Agent SDK hooks and hooks from plugins that managed `enabledPlugins` force-enables run | Status line and file suggestion are read from managed settings only | | `allowManagedMcpServersOnly` | The `allowedMcpServers` allowlist | `deniedMcpServers` still merges from every scope | | `strictKnownMarketplaces` | Which plugin marketplace sources can be added and installed from | `blockedMarketplaces` adds a blocklist on top | Details worth knowing for each: - **Permission rules**: the lock is separate from the MCP lock — it does not enforce the MCP allowlist. - **Hooks**: user, project and local hooks, hooks from other plugins and hooks in agent frontmatter are blocked. The `/goal` command can't run under this lock because it depends on hooks. Matching for force-enabled plugins uses the full `plugin@marketplace` ID. - **Marketplaces**: unset means any marketplace; an **empty array is a complete lockdown**, blocking even the official Anthropic marketplace. The check runs on add, install, update, refresh and auto-update, so a marketplace added before the policy can't fetch plugins once its source no longer matches. ## Turning bypass mode off `permissions.disableBypassPermissionsMode` set to `"disable"` prevents anyone entering `bypassPermissions` mode: Claude Code rejects `--dangerously-skip-permissions` and ignores a subagent definition's `permissionMode: bypassPermissions`. Unlike the locks it can live in any file, so it only binds the organization when it is delivered in managed settings. ## Models: a default versus a restriction A managed `model` is a default — `--model` and `ANTHROPIC_MODEL` still pick the session's model. To restrict choice, deploy **`availableModels`**: a managed list constrains `/model`, `--model` and the `model` key in a developer's own files, and the managed list is applied as-is rather than merged with user entries. With default prefix matching it doesn't remap the **Default** option on its own; `enforceAvailableModels: true` closes that gap. ## What developers notice after the locks Rolling out locks changes daily use, so tell people before the policy lands: - Permission prompts no longer offer an always-allow choice, and an approval doesn't get saved as a new rule. - Hooks in their own `~/.claude/settings.json` or in the repository simply stop running; `/hooks` is the place to see what is active. - Adding a marketplace whose source isn't on the allowlist fails with an error naming the managed policy. - A user-level `disableAllHooks` can't switch the organization's hooks off: only managed settings can disable managed hooks. - `/permissions` shows the effective rules, which is the quickest way for a developer to see what the policy now allows. ## A rollout order 1. Deploy the restrictions first: managed `deny` rules and `disableBypassPermissionsMode`. 2. Move the team's approved `allow` rules and hooks into managed settings or a force-enabled plugin. 3. Turn on the locks, so nothing outside the managed set grants anything. 4. Verify on one machine with `/permissions` and `/status` before the fleet. ## Summary The managed tier decides conflicts; the locks decide whose lists count. Without them, an organization's policy is a floor that developers can still build on.
- With `allowManagedHooksOnly` on, how do you still ship a team's vetted hooks?Declare them in managed settings, or package them in a plugin from an organization marketplace and force-enable it through managed `enabledPlugins`. Hooks from force-enabled plugins still run, matched on the full `plugin@marketplace` ID, so a same-named plugin from another marketplace stays blocked.
- Does `allowManagedPermissionRulesOnly` also stop developers adding their own MCP servers?No. It governs permission rules only. MCP servers have their own lock: `allowManagedMcpServersOnly` with a managed `allowedMcpServers` list, while `deniedMcpServers` keeps merging from every scope so users can still block servers for themselves.
- Why isn't a managed `model` key enough to keep everyone on approved models?A managed `model` is only a default; `--model` and `ANTHROPIC_MODEL` still choose the session's model. Deploy `availableModels` to restrict selection, and add `enforceAvailableModels: true` so the Default option can't resolve to a model outside the list.
- Because managed settings rank highest, user allow rules are already ignored.
- Putting allowManagedHooksOnly in a repository's .claude/settings.json locks hooks there.
- allowManagedPermissionRulesOnly also restricts which MCP servers can load.
- An empty strictKnownMarketplaces array leaves marketplaces unrestricted.
- A developer's disableAllHooks can switch off the organization's managed hooks.