Guide

A Guardrail Only Counts If Nobody Can Switch It Off. Lock Claude Code Hooks to Policy.

By ยท 16 Nov 2026

A developer seen from behind at a pale oak desk looks at a landscape monitor with one large bright blank cream panel beside three smaller dimmed blank tiles against a bright lime wall, with a blank keyboard on the desk.

Short answer: Claude Code can make managed hooks fail closed. Set allowManagedHooksOnly so only organization, Agent SDK and force enabled plugin hooks run. Know that disableAllHooks in user, project or local settings cannot stop managed hooks. Then decide whether to set forceRemoteSettingsRefresh, which makes the CLI exit when a session that fetches server managed policy cannot get a fresh copy.

Hooks are where many teams put real guardrails, such as a check that blocks writes to production config or a log of every shell command. Our Oct 14 brief covered GitHub's similar fail closed setting for Copilot clients as news. This page is the Claude Code counterpart.

What it is

Hook entries merge across settings levels instead of replacing each other. User, project and local settings add their own hooks without removing managed ones, so a managed hook already runs alongside whatever a developer adds. Three settings tighten that picture.

allowManagedHooksOnly: with this managed only key set to true, the settings reference lists what still runs: hooks from managed settings, hooks the Agent SDK registers in process, and hooks from plugins your managed enabledPlugins force enables, matched on the full plugin@marketplace ID. Everything else is blocked, including user, project and local hooks, hooks and mods from other installed plugins, and hooks declared in agent frontmatter. Mods built into Claude Code keep running. From v2.1.310, a plugin's monitors do not start unless the plugin is force enabled. The key also disables plugins with a command source, even force enabled ones, unless you explicitly set disableCommandPluginSources to false. It blocks marketplace headersHelper commands under the same condition, except for a marketplace that managed settings themselves declare. It limits the status line and file suggestion settings to managed values, and the /goal command cannot run while it is set, because it depends on hooks.

disableAllHooks: this key works in any file, but the hooks docs say a value in user, project or local settings cannot disable managed hooks. Only disableAllHooks in managed settings can do that. A developer who sets it in their own file turns off their own hooks, while your managed hooks keep running.

forceRemoteSettingsRefresh: by default, server managed settings do not block startup. If the fetch fails, the CLI continues with the settings cached from the last successful fetch, but the docs say to plan for that cache to expire 24 hours after the last successful fetch. Once it has expired, or on a machine that never fetched, a failed fetch starts the session without server managed settings, while any endpoint managed settings on the device still apply. With this key true, a session that fetches server managed settings blocks at startup until it has a fresh copy and exits if the fetch fails. A session that does not fetch server managed settings starts without waiting. Claude Code honors a true value from any admin controlled source. A server delivered value is read from the cached settings on later startups, and the docs advise also setting the key in an MDM profile or the system managed-settings.json file, so it applies on the very first launch and does not rely on the cached copy. The claude auth subcommands are exempt so a user with expired credentials can still sign in again.

Version requirements, from the docs: the fail closed rule for single value keys and the per field repairs need v2.1.282 or later, requiredMinimumVersion needs v2.1.163 or later, headersHelper blocking under allowManagedHooksOnly needs v2.1.238 or later, and monitor blocking needs v2.1.310 or later. As of 10:24 AM ET Mon Nov 16, 2026, npm showed stable at v2.1.311 and latest and next at v2.1.325, so every channel cleared all four.

How-to

  1. Check your fleet's versions. Run the commands in the script below on a representative machine.
  2. Inventory hooks first. Ask teams which user and project hooks they rely on, because allowManagedHooksOnly will block them. A formatter hook like the one in our Prettier after edit Corner lives in project settings, so it stops unless you move it into policy.
  3. Move the keepers into policy. Put shared hooks in the hooks block of managed settings, using the shape in the hooks reference, or ship them in a plugin you force enable through managed enabledPlugins.
  4. Turn on allowManagedHooksOnly. Set it to true in managed settings and confirm with a pilot group that the hooks you kept still fire.
  5. Set a version floor. Use requiredMinimumVersion with a valid version string at or above the oldest release whose behavior you depend on, and double check the quoting, since an invalid value is dropped.
  6. Pilot fail closed startup. Server managed settings need a Claude for Teams or Claude for Enterprise plan and network access to api.anthropic.com. Turn on forceRemoteSettingsRefresh for one group, set it in your MDM profile or system managed-settings.json as well, and confirm that machines on VPN or flaky networks still start.
  7. Verify on a real machine. Have a user run /status and claude doctor and confirm no managed entry was dropped.
# We have not run this script end to end on every platform
# Read it before you run it. It only prints versions and health information. It changes no settings.
set -e

claude --version
npm view @anthropic-ai/claude-code dist-tags
claude doctor

# Optional installs, left commented. Pick one channel on purpose.
# Default to the stable pin.
# stable channel, v2.1.311 as of 10:24 AM ET Mon Nov 16 2026:
# npm install -g @anthropic-ai/claude-code@2.1.311
# latest channel, v2.1.325 as of 10:24 AM ET Mon Nov 16 2026, test machine only:
# npm install -g @anthropic-ai/claude-code@2.1.325

Gotchas

Invalid values behave differently by key, so a typo can quietly weaken or quietly tighten a policy. The managed settings docs spell out the rules.

  • Keys with one restrictive value fail closed. If a managed source sets a top level key such as allowManagedPermissionRulesOnly, disableAutoMode or skipDangerousModePermissionPrompt to something Claude Code cannot read, the key reads as its restrictive value until you fix it, and the report says the key was present but invalid.
  • Quoted Booleans are repaired. For other Boolean keys this rule covers, the string "true" or "false" reads as that Boolean, with a notice in /status asking you to drop the quotes.
  • An invalid disableAllHooks is dropped, not enforced. Even a quoted Boolean is dropped with a warning, because enforcing true would also unload the hooks your own managed settings deploy.
  • Version floors fail open by design. requiredMinimumVersion and requiredMaximumVersion drop an invalid value rather than enforce it, so a malformed floor means no floor and locks no one out.
  • A null removes the key.
  • An unparseable source blocks launch. A managed settings file, drop in file, MDM plist or HKLM registry value that is not a JSON object makes Claude Code refuse to start, even when another source delivers a valid policy.
  • A stale cache is not a safe fallback. Without forceRemoteSettingsRefresh, a machine that has not fetched for more than 24 hours can start with no server policy when the fetch fails.
  • Fail closed means a policy outage stops work. With forceRemoteSettingsRefresh on, an unreachable api.anthropic.com keeps the CLI from starting, apart from claude auth. Our advice, not the docs': plan for that before you roll it out widely.
  • Plugins, monitors and status lines change too. Command source plugins, marketplace headersHelper commands for marketplaces your managed settings do not declare, monitors from plugins that are not force enabled and non managed status line settings stop working under allowManagedHooksOnly, so warn teams before the switch.

FAQ

What does allowManagedHooksOnly do? With it true in managed settings, only organization hooks, Agent SDK hooks and hooks from force enabled plugins run. Hooks and mods from other plugins are blocked, and mods built into Claude Code keep running.

Can disableAllHooks turn off managed hooks? Not from user, project or local settings. Only a managed settings value can stop managed hooks.

How do I make startup fail closed with forceRemoteSettingsRefresh? Set it true so a session that fetches server managed policy exits when it cannot get a fresh copy. Set it in an MDM profile or the system managed-settings.json too, so it applies from the first launch. The claude auth subcommands are exempt.

What breaks if a managed settings value is invalid? Keys with one restrictive value fail closed when invalid. An invalid disableAllHooks is dropped. Version floors fail open. An unparseable managed source blocks launch.

Sources: Claude Code settings reference, Hooks reference, Server managed settings, and Deploy managed settings.

Recommended AI prompt

Copy this paragraph into ChatGPT, Claude, Gemini, Grok, or whatever AI you use.

Prompt

Act as my Claude Code governance reviewer. I am planning managed settings that use allowManagedHooksOnly so only organization hooks run, rely on the rule that disableAllHooks outside managed settings cannot stop managed hooks, and use forceRemoteSettingsRefresh so sessions exit when they cannot fetch fresh policy. Ask me which hooks, plugins and monitors my teams use today, how we deliver managed settings, what plan we are on and how reliable our network is. Then give me a staged rollout order and the failure cases to test, including a cache older than 24 hours, citing the Claude Code managed settings, server managed settings, hooks and settings reference docs rather than inventing any keys.