A Claude Code upgrade can now enable extensions that change permission decisions inside the agent. Anthropic launched mods on October 1, 2026, shipping them inside plugins for the CLI and desktop app. Mods can rewrite tool calls, approve permission requests, and alter the interface. Anthropic says they run with Claude Code's access to the machine and are not sandboxed.
The upgrade detail matters: mods are on by default in v2.1.287 and later. The old CLAUDE_CODE_ENABLE_FUNCTION_HOOKS environment variable is ignored, including a value of 0. Administrators who used that early-access opt-out need a managed policy before expanding the rollout. Anthropic documents the replacement in its mods administration guide.
Decide which mods may load, then check what the upgraded client actually admits. The procedure below combines Anthropic's documentation with its published guard source; we have not exercised it in an enterprise tenant. Use the broader Claude Code deployment baseline for identity, endpoint, and network controls.
Keep the built-in guard in the chain#
Claude Code's sec-default mod protects selected controls from user-installed mods. It loads ahead of those mods when the machine has managed settings or the user signs in with a Team or Enterprise plan. API-key and cloud-provider sessions need managed settings on the machine to get that default guard. See Anthropic's default behavior.
A mod that runs first can see an event before later mods change it and inspect the result on its way back. An appended mod only sees what earlier mods pass along. An audit mod placed at the end can therefore miss an event another mod answers itself.
If managed settings define prependPlugins, that list replaces the default. Include sec-default@builtin explicitly to retain the guard. Adding a custom policy mod without retaining that entry removes the protection its options depend on. Anthropic documents this in the organization mod installation rules.
Do not treat the presence of sec-default as approval of every installed mod. Its published source protects particular events and passes others through. Review both the extension's source and the authority available to it.
See how your AI systems hold up under real attacks
General Analysis maps AI applications and agents, red teams prompts, retrieval, tools, MCP servers, browser actions, permissions, and business workflows, then turns findings into evidence your team can reproduce and retest.
Restrict user mods without disabling existing hooks#
For a fleet that has not approved user-installed mods, merge this fragment into the existing managed settings. It leaves settings hooks and built-in mods available. Avoid replacing the whole settings file and losing unrelated controls.
Code source: Anthropic's managed-only mods configuration, adapted as a fragment to merge.
{
"pluginConfigs": {
"cc-plugin-sec-default@builtin": {
"options": {
"allowManagedModsOnly": true
}
}
}
}
The spelling is intentional. prependPlugins accepts sec-default@builtin; pluginConfigs reads the options only under cc-plugin-sec-default@builtin. The guard reads these options from managed settings. A matching entry in a user's file, repository settings, or --settings does not establish this policy.
Keep allowModsToOverrideDenyRules unset or false unless the organization deliberately permits user mods to override deny rules. These are separate choices: one controls module admission, the other controls what an admitted user mod may do to a tool-check verdict. The guard options reference describes both.
A marketplace allowlist alone does not close every loading path. Anthropic lists local --plugin-dir loading separately; disableSideloadFlags restricts the sideload flags. Use allowManagedModsOnly for the module-admission decision rather than assuming an approved catalog covers all mods. Existing classic hooks need their own review under the settings and hooks policy.
Verify what counts as an organization mod#
Consider an internal policy plugin hosted in the company's GitHub organization. An administrator enables it through managed settings and lists it in prependPlugins. That sounds centrally controlled, but it does not meet Claude Code's documented requirements for an organization mod.
Anthropic requires all of the following in its installation procedure:
- Managed
enabledPluginsenables the plugin. - Managed settings identify its marketplace as an absolute directory on the user's machine.
- The marketplace names the plugin with a relative path so it loads in place.
A plugin copied from GitHub, git, a URL, or npm remains in the user tier, even if managed settings enable it. The ordering lists skip it, and a managed-only policy refuses its mod. Deploy a policy mod through a local marketplace that administrators control. If you keep the remote installation, review it as a user extension.
Protect the marketplace directory and every parent directory from ordinary user writes. Otherwise, the person whose extensions the policy is meant to govern can change the policy mod itself. Settings delivered from the admin console can name that directory; they cannot put its files on the endpoint.
Open the debug log from claude --debug and check the mod's effective tier. tier prepend establishes the intended position; tier user calls for an origin review. For an account-synced plugin, also consult the account-sync inventory procedure. Familiar names do not establish which copy loaded.
Resolve these rollout failures before closing the change#
Collect the client version, selected managed source, reviewed configuration, plugin origin, and final admission message together. The following checks use Anthropic's admin diagnostics and guard implementation notes; they are acceptance criteria, not reported test results.
| Observation | What to investigate | Evidence needed to close it |
|---|---|---|
| A user mod remains active after policy delivery | Admission is checked at load or reload. An already-running module can continue until then. | Reload or restart the affected session; retain the new refusal or admission result. |
| The log says a hooks module loaded | A later guard refusal can follow that line. Loading text alone does not prove admission. | Read through the final result for that module and its policy reason. |
A centrally enabled policy mod has tier user | A copied remote plugin does not qualify as an organization mod. | Verify the local directory, relative plugin path, managed enablement, and resulting tier. |
| The managed-only option appears present but has no effect | Wrong option key, wrong settings source, missing guard, or rejected configuration. | Confirm the effective source, guard entry, exact key, and absence of validation warnings. |
One failure deserves a separate check. The guard README says a schema-invalid value such as null or an object in pluginConfigs can cause Claude Code to ignore the entire key, with a settings warning. That leaves the managed-only option unset. This differs from the guard failing closed when it cannot read policy: rejected configuration can remove the option before the guard reads it. Validate every entry in that object, including entries unrelated to mods.
For a pilot, use a reviewed, harmless mod to confirm the intended admission outcome. Do not load an unknown extension to test whether it is safe. A noninteractive -p run may put the refusal only in the debug log, so a quiet terminal is insufficient evidence.
Separate tool decisions from a mod's own access#
The guard preserves deny rules for Claude's tool calls by default. It also protects managed hooks. Those protections do not cover a mod's own $.fs or $.process operations. Anthropic explicitly documents that a denied file can remain readable through a mod's direct filesystem API. Similarly, policy covering $.http.fetch does not constrain the network access of a program started through $.process.run. See which controls still apply.
This changes the approval question. Before admitting a mod, review the files, processes, credentials, and destinations it can reach. Use claude plugin validate to inspect its declared hooks and API calls, then review the implementation. The validator shows what to review; it cannot decide whether those operations fit your policy.
Custom policy mods have their own availability limits. Anthropic documents that --safe-mode starts without installed mods, including organization mods, and repeated hooks-worker crashes can unload them for the session. A hook that fails also needs an explicit failure handler if it must refuse an action. The policy-mod guidance covers these cases. Keep essential filesystem restrictions, network controls, and destination authorization outside a custom mod whose absence would otherwise leave the action unrestricted.
Approve the rollout when the intended client version and managed source are present, the guard remains in the effective order, each policy mod has the correct origin and tier, and existing sessions have crossed the required reload or restart boundary. Retain those results with the reviewed policy. After the next update, compare the same settings and admission results.
Frequently asked questions
- Does enabling a plugin centrally make its mod an organization-managed mod?
Not by itself. Anthropic requires managed enablement, an absolute local marketplace directory named in managed settings, and a relative plugin path that loads in place. A plugin copied from GitHub, git, a URL, or npm remains in the user tier even when managed settings enable it.
- Does allowManagedModsOnly immediately stop a running mod?
The restriction applies when a module loads or reloads. A module already running when the setting changes continues until that lifecycle step. Restart or reload the affected sessions and check the resulting admission messages before closing the rollout.
