CONCEPT Managed settings sit at the top and cannot be overridden
Organizations enforce Claude Code configuration through managed settings — a
managed-settings.json file (same format as any settings file) deployed by an administrator. It is
the highest-priority layer in the precedence chain, above everything a developer can set,
including CLI flags:
| Priority | Scope |
|---|---|
| 1 (highest) | Managed settings — can't be overridden by any other level |
| 2 | Command-line arguments |
| 3 | Local project settings (.claude/settings.local.json) |
| 4 | Shared project settings (.claude/settings.json) |
| 5 (lowest) | User settings (~/.claude/settings.json) |
allow/ask/deny
arrays merge across scopes rather than replace. But the deny-first rule still holds — a managed
deny can't be re-allowed by --allowedTools or any lower scope.CONCEPT Where the file lives, per OS
The file-based managed policy lives at an OS-specific system location a normal user can't write:
| Platform | Managed settings 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 |
Managed policy can also arrive via MDM/OS-level mechanisms (a macOS com.anthropic.claudecode
managed-preferences plist, or the Windows HKLM\SOFTWARE\Policies\ClaudeCode registry key),
server-managed settings on Claude.ai, or a self-hosted Claude apps gateway.
CONCEPT Managed-only settings that lock users out
Some keys only take effect from managed settings — placing them in user/project files does nothing:
permissions.disableBypassPermissionsMode: "disable"— blocksbypassPermissions/--dangerously-skip-permissions. (This one actually works from any scope, but is typically enforced here.)permissions.disableAutoMode: "disable"— blocksautomode.allowManagedPermissionRulesOnly: true— user/project settings can't define anyallow/ask/denyrules; only managed rules apply.allowManagedHooksOnly: true/allowManagedMcpServersOnly: true— restrict hooks and MCP servers to managed (and specifically-approved) sources.sandbox.filesystem.allowManagedReadPathsOnly/sandbox.network.allowManagedDomainsOnly— lock sandbox read paths and network domains to the managed values.
DIAGRAM Effective config = merge, with managed on top
~/.claude/settings.json"] --> MERGE["Merge by precedence"] P["Project settings
.claude/settings.json"] --> MERGE L["Local settings
.claude/settings.local.json"] --> MERGE C["CLI flags"] --> MERGE M["🔒 Managed settings
managed-settings.json"] --> MERGE MERGE --> EFF{"Effective policy"} EFF --> R1["Managed values win — even over CLI flags"] EFF --> R2["deny rules from any scope block — merged, deny-first"] classDef lock fill:#f8d7da,stroke:#dc3545,color:#721c24; classDef ok fill:#d4edda,stroke:#28a745,color:#155724; class M lock; class R1 ok; class R2 ok;
CODE A locked-down managed-settings.json
// macOS: /Library/Application Support/ClaudeCode/managed-settings.json { "permissions": { "defaultMode": "default", "disableBypassPermissionsMode": "disable", "deny": [ "Read(./.env)", "Read(./secrets/**)", "Bash(curl *)", "WebFetch" ] }, "allowManagedPermissionRulesOnly": true, "sandbox": { "enabled": true, "failIfUnavailable": true, "allowUnsandboxedCommands": false } }
curl, and requires a working sandbox (refusing to start otherwise). None of it can be
loosened by a user's ~/.claude/settings.json or a repo's checked-in settings.TRADE-OFFS Central enforcement vs. developer flexibility
✅ Managed policy
- Organization-wide guardrails users cannot weaken
- Deny rules and disabled modes hold even against CLI flags
- Delivered by MDM/registry — consistent across the fleet
⚠️ Cost of locking down
- Over-restriction (e.g.
allowManagedPermissionRulesOnly) means every allowed command must be centrally curated - Array keys like sandbox
excludedCommandsstill merge, so keep the managed list narrow - Requires admin access to system paths on each machine
EXAM TRAPS
deny can't be undone with
--allowedTools.managed-settings.json lives in ~/.claude/." → It lives in
a system location: /Library/Application Support/ClaudeCode/ (macOS),
/etc/claude-code/ (Linux), C:\Program Files\ClaudeCode\ (Windows).allowManagedPermissionRulesOnly that suppress lower-scope allow/ask/deny entirely.sandbox.enabled (a boolean) set in managed settings, Claude Code uses the managed value and ignores
a developer's local override; allowManagedReadPathsOnly further stops them widening read paths.PRACTICE
Q1 · An admin denies Bash(curl *) in managed settings. A developer adds --allowedTools "Bash(curl *)". What happens?
Still denied. Managed settings outrank CLI flags, and deny is evaluated before allow across all scopes. If a tool is denied at any level, no other level can re-enable it.
Q2 · Where does managed-settings.json live on Linux, and why there?
/etc/claude-code/managed-settings.json — a root-owned system path a normal user can't
write, so the policy can't be tampered with from a user account.
Q3 · How do you stop developers from defining their own permission rules at all?
Set allowManagedPermissionRulesOnly: true in managed settings. Then only
allow/ask/deny rules from managed settings apply; user and project rules
are ignored.