What Claude Code mods are, and why admins should care
A Claude Code mod is a plugin made of JavaScript or TypeScript event handlers that Claude Code calls from inside its own process: when Claude is about to use a tool, when a prompt is submitted, or when part of the interface is drawn. A handler can watch the event, change it, or answer it so the normal behavior never runs. Mods work in the terminal, the Code tab of the Desktop app and the VS Code extension, and they are on by default in Claude Code v2.1.286 and later.
That is a different risk profile from anything else in a plugin. A mod runs with the permissions of the user who installed it, and it is not sandboxed. Once it loads, it can read and write files anywhere the user can, start programs, make network requests, read environment variables and settings files (including API keys kept there), see every prompt and tool call, rewrite them, approve a tool call before the user is asked, and call a model on the user's plan or API key. Turning on Claude Code's sandbox does not change that: the sandbox isolates the Bash commands Claude runs, and a process a mod starts runs outside it.
So the admin question is not whether mods are useful. They are. A mod can add a pane that charts context use, a command that runs instantly without a Claude turn, or a check that holds a risky shell command until someone confirms it. The question is which mods you let run on company machines, and who decides. I call the approach below the CCC Mod Gate: know the default, choose a policy, review before you allow, then run your own.
What your users get when you change nothing
With no mod settings of your own, mods are on. A user can install a plugin that contains a mod from any marketplace your plugin settings allow, or load one from a directory with --plugin-dir. A mod Claude writes during a session can load too.
On managed machines, a built-in guard runs first. Claude Code loads a built-in mod called sec-default@builtin ahead of every mod a user installs, and users cannot turn it off. It appears in /plugin and the debug log as cc-plugin-sec-default. The guard loads when either of these is true:
- The machine has managed settings or a managed-mcp.json file.
- The session runs on /login credentials for a Team or Enterprise plan.
The gap is worth knowing. A user on an API key, or on Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry, gets the guard only on a machine with managed settings or managed-mcp.json. A session running on a long-lived CLAUDE_CODE_OAUTH_TOKEN does not count as a Team or Enterprise login either, even if one is stored on the machine. If part of your fleet runs on cloud providers with no managed settings file, those machines have no guard at all.
What the built-in guard does and does not stop
| Area | With the guard loaded |
|---|---|
| Managed hooks, system prompt, managed CLAUDE.md and managed instructions | A user's mod cannot change them or what your managed hooks receive or decide |
| Managed MCP servers | A user's mod cannot change their tools or descriptions once they connect. On v2.1.323 or later it can keep one from connecting, and /mcp shows the server as held by that mod |
| Deny rules, ask rules and PreToolUse hooks | A user's mod cannot approve a call a deny rule refuses, an ask rule prompts for, or any PreToolUse hook blocked |
| Files, processes and network | Not covered. The mod keeps the user's access. A Read(.env) deny rule does not stop a mod reading .env through its own file API |
| Rewriting prompts and tool calls, adding or removing tools, drawing | Not covered. Outside what you manage, the mod acts as the user |
| The permission prompt itself | No mod can restyle or change what a permission prompt shows |
The guard also refuses to run a user's hooks on a list of sensitive events, including the sections of the system prompt, skill text as it is expanded, commit and pull request attribution text, conversation compaction, and settings reads. On v2.1.299 or later, /plugin shows the user a note naming each hook that will not run.
Choose a mod policy
Each policy is a few managed settings. Find the row that matches what you want:
Mod policies and the managed settings behind them
| What you want | What to set |
|---|---|
| No installed mod runs, settings hooks untouched | The guard's allowManagedModsOnly option, and no mods of your own |
| Only your organization's mods | allowManagedModsOnly, plus your mods installed so they count as yours |
| Any mod from marketplaces you approve | Your marketplace restrictions, plus disableSideloadFlags set to true |
| Any mod, with your own mod checking the others | Your mod installed as yours, listed with sec-default@builtin in prependPlugins |
| No installed mods and no hooks at all, your managed hooks included | disableAllHooks set to true |
My recommendation for most companies is the second row: only your organization's mods, with disableSideloadFlags on top. It keeps the useful part (you can still ship a mod everyone gets) and removes the part you cannot review at scale, which is whatever each developer installs. If you have no mods to ship yet, the first row is the same policy with an empty list.
Be careful with the two wider settings. allowManagedHooksOnly also blocks hooks in users' own settings files, not just mods. disableAllHooks in managed settings is the widest of all: it stops the mods in every installed plugin, yours included, turns off every settings hook, so a PreToolUse hook in your managed settings no longer blocks anything, and also stops custom status lines and /goal. Reaching for it to kill mods also kills your own guardrails.
Stop user-installed mods with allowManagedModsOnly
To stop mods users bring, set one option on the built-in guard in managed settings. Under pluginConfigs, add an entry keyed cc-plugin-sec-default@builtin, and inside its options set allowManagedModsOnly to true. With that in place:
- No mod a user brings runs its hooks. That covers a mod in a plugin they installed, one loaded with --plugin-dir, and one Claude wrote during a session.
- Your organization's mods still run. Every other mod counts as a user's and is refused, including one your organization turns on for members on claude.ai.
- Users cannot undo it. The guard reads the option from managed settings only, so the same entry in a user, project or local settings file, or a file passed with --settings, changes nothing.
- Delivered as a file or through MDM, it works the same on Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry.
- Users' settings hooks, status lines and /goal keep working, and built-in mods such as AGENTS.md support keep running.
Two details trip people up. The options are read only under the id cc-plugin-sec-default@builtin. The short form sec-default@builtin works in prependPlugins, not in pluginConfigs. And the guard fails closed: if it cannot read managed settings, it refuses every user's mod at load.
Add disableSideloadFlags set to true next to it. That rejects --plugin-dir and --plugin-url at startup and keeps mods Claude writes during a session from loading. It also rejects --agents and --mcp-config, so check nobody's scripts depend on those before you ship it.
Confirm the policy on a test machine
Do not assume the file landed. On a test machine, start a session with claude --debug and read the debug log:
What the debug log shows when the policy works
| What you are checking | What you should see |
|---|---|
| Your own mod | Its hooks module line includes tier prepend |
| A mod the user installed | A line reading refused by cc-plugin-sec-default: mods are limited to your organization's by policy (allowManagedModsOnly). An earlier line says the hooks module loaded, so look for the refusal |
| A plugin directory | claude --plugin-dir ./any-mod exits with a message starting --plugin-dir is disabled by your organization's managed settings (disableSideloadFlags) |
If the refusal line is not there, the usual cause is the policy not being in force on that machine at all, which is a managed settings delivery problem rather than a mod problem. Fix delivery first.
Review a mod before you allow it
You can see what a mod is able to do without running it. Get the plugin's files, then run claude plugin validate on the plugin's directory. The output has a hooks line listing the events the mod receives and a calls line listing the mods API methods its code uses. Claude Code refuses to load a mod that uses the API in a way this command cannot read.
Do not approve a mod that fails validation, because some failures do not stop it loading. Run the check on Claude Code v2.1.323 or later, where a long list continues onto more lines with the same label, and read every hooks and calls line. These are the calls to look for:
Mod API calls worth a second look
| Call | What it means |
|---|---|
| $.fs.read, $.fs.write | Reads or writes files anywhere the user can |
| $.process.run, $.process.spawn | Starts programs as the user |
| $.http.fetch | Makes network requests |
| $.env.get, $.settings.read | Reads environment variables and settings, which can hold API keys. An env reads line names each variable |
| $.env.set | Sets an environment variable for Claude Code and everything it starts afterward |
| $.mcp.call | Calls a tool on a connected MCP server with no permission prompt. Claude Code still refuses it under a deny rule, a managed ask rule, or a tool marked as requiring approval |
| $.model.complete | Uses the user's plan or API key for model calls |
| $.prompt.submit | Submits a prompt, and can send it as the user's own words |
| $.session.send | Sends a message another session, subagent or teammate reads |
In the hooks line, tool.call and prompt.submit mean the mod sees and can change every tool call and every prompt. tool.check means it can approve or deny a call before a permission prompt appears. My rule of thumb: a mod that only draws a pane and reads token counts is low risk. A mod with $.http.fetch plus $.env.get or $.settings.read can read a key and send it somewhere, so it needs a person to read the code, not just the summary.
Watch the network controls you think you have
This is the section I would read twice. Network policy covers a mod's $.http.fetch only in one case: if your organization's policy does not allow WebFetch, Claude Code refuses every mod's fetch request too. The other controls admins reach for do not stop mods:
- Turning off the WebFetch tool with CLAUDE_CODE_DISABLE_WEB_FETCH or a WebFetch deny rule, in any settings file including managed settings, does not stop a mod's $.http.fetch requests.
- CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC stops only the built-in mods, plus any fetch that carries the session's Anthropic credentials. Before v2.1.288 it stopped every mod's fetch, so behavior changed under anyone relying on it.
- None of these covers a program a mod starts with $.process.run, which reaches the network with the user's own access.
If outbound traffic from mods matters to you, the clean answer is to keep users' mods from loading. The alternative is a policy mod that hooks http.fetch and refuses requests from users' mods. Give that hook a .catch handler that also refuses, because Claude Code skips a hook that fails, and the request then goes ahead.
Run your organization's own mods
Your mods run where users' mods do not, so Claude Code has to be able to tell a mod came from you. For a mod from a remote marketplace such as a GitHub repository, on v2.1.324 or later, do all three of these in managed settings:
- Set the plugin to true in enabledPlugins.
- Declare the marketplace in extraKnownMarketplaces, and pin the marketplace and the mod's entry if you want to control when its code changes.
- List the mod's id, such as acme-guard@acme-tools, in prependPlugins or appendPlugins. With prependPlugins, also list sec-default@builtin, or you remove the built-in guard.
A mod in a directory on the user's machine counts as yours only if managed enabledPlugins enables it, managed settings name the marketplace as a directory by absolute path, and the marketplace lists the plugin by a relative path so it loads in place. Have device management copy that directory to the same path on every machine, and make it and every directory above it writable only by an administrator. Anyone who can write there can rewrite your mod. The admin console can deliver the settings keys, but it cannot put the directory on a machine.
Order matters. In prependPlugins, your mod sees each event before any user's mod and the result after them, so it can change the event, refuse it, or skip users' mods entirely. In appendPlugins it runs after every user's mod and only sees what they pass on. For a policy mod, prepend it.
The CCC Mod Gate checklist
- Find out where the guard loads today. Any machine on an API key or a cloud provider with no managed settings file has none.
- Pick a policy row. For most companies: only your organization's mods, plus disableSideloadFlags.
- Set allowManagedModsOnly under cc-plugin-sec-default@builtin in managed settings, and remove any leftover CLAUDE_CODE_ENABLE_FUNCTION_HOOKS.
- Confirm on a test machine with claude --debug: tier prepend for yours, the refusal line for a user's.
- Review every mod you allow with claude plugin validate on v2.1.323 or later, and read the code of anything that combines network calls with env or settings reads.
- If you need mods' network traffic controlled, do it in a prepended policy mod with a refusing .catch, not with WebFetch settings.
- Keep your settings hooks. Mods do not replace them, and managed PreToolUse hooks still run first and re-run on any call a mod rewrites.
If something breaks after a rollout, claude --safe-mode turns installed mods off for one session, yours included, which is the quickest way to see whether a mod is the cause. For the rest of the hook model, Claude Code hooks that earn their keep covers settings hooks, and Claude Code permissions explained covers the rules a user's mod cannot override.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
What is a Claude Code mod?
A mod is a plugin made of JavaScript or TypeScript event handlers that Claude Code runs inside its own process. It can watch, change or answer tool calls, prompts and interface drawing, and it runs with the permissions of the user who installed it.
Are Claude Code mods on by default?
Yes. Mods are on by default in Claude Code v2.1.286 and later. An administrator can limit them through managed settings.
How do I stop users installing their own mods?
In managed settings, set allowManagedModsOnly to true in the options of the cc-plugin-sec-default@builtin entry under pluginConfigs. Add disableSideloadFlags to reject --plugin-dir and --plugin-url as well.
Are Claude Code mods sandboxed?
No. A mod runs as the user, with the user's access to files, processes and the network. Claude Code's sandbox isolates the Bash commands Claude runs, and a process a mod starts runs outside it.
Can a user's mod bypass my deny rules?
Not where the built-in guard loads. A user's mod cannot approve a call that a deny rule refuses, an ask rule prompts for, or a PreToolUse hook blocked, unless you set allowModsToOverrideDenyRules. Those rules do not cover the mod's own file and process calls, though.
Does disabling WebFetch stop mods making network requests?
No. Turning off the WebFetch tool by environment variable or deny rule does not stop a mod's $.http.fetch. Only an organization policy that disallows WebFetch does that. Keep users' mods from loading, or refuse their fetches in a policy mod.
Last reviewed by David Iya on November 17, 2026


