Manage mods for your organization

• Keep users’ own mods out, with or without mods of your own: Stop user-installed mods from loading
• See what your users get when you change nothing: Know what happens by default
• Leave mods on with other limits: Choose how much to allow

​

Stop user-installed mods from loading

{
  "pluginConfigs": {
    "cc-plugin-sec-default@builtin": {
      "options": {
        "allowManagedModsOnly": true
      }
    }
  }
}

• No mod a user brings loads: that covers a mod in a plugin the user installed, a mod loaded with --plugin-dir, and a mod Claude wrote during a session
• Your organization’s mods still load: a mod that counts as your organization’s isn’t checked. Every other mod counts as a user’s and doesn’t load. That includes a mod in a plugin you enable from a GitHub or other remote marketplace, and one your organization turns on for its members on claude.ai. If none counts as yours, no installed mod loads.
• Users can’t undo it: the guard reads the option from managed settings only, so the same entry in a user, project, or local settings file, or in a file passed with --settings, changes nothing
• A file or MDM policy covers every provider: when you deliver the option as a file or through MDM, it works the same way on Amazon Bedrock, Google Cloud’s Agent Platform, and Microsoft Foundry. For delivery from the claude.ai admin console, see Platform availability
• Users’ other customizations keep working: their hooks in settings files, status lines, and /goal aren’t affected
• Built-in mods keep running: mods built into Claude Code, such as AGENTS.md support, each have their own switch

​

Know what happens by default

• 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 built-in guard runs first. Claude Code loads a built-in mod named sec-default@builtin ahead of every mod a user installs. Users can’t turn it off. /plugin and the debug log list it as cc-plugin-sec-default. The guard loads when either of these is true:
  • The machine has managed settings
  • The user is signed in to Claude Code with a Team or Enterprise plan
  A user who authenticates with an API key, or through Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry, gets the guard only on a machine that has managed settings.
• The guard protects what you manage. A user’s mod can’t change what your managed hooks receive or decide, the system prompt, your managed CLAUDE.md and other managed instructions, what any mod reads as settings, or the tools and descriptions of your managed MCP servers.
• Everything else is allowed. The guard adds no other restrictions. A user’s mod can still read and write files, start processes, make network requests, rewrite tool calls and prompts, deny a tool call, approve one that would otherwise prompt, and draw in the interface, all with that user’s permissions.
• Deny rules and your managed hooks take precedence. Where the guard loads, a user’s mod can’t approve a call that a deny rule refuses, whichever settings file holds the rule. A block from a PreToolUse hook in managed settings is final too. Both apply to Claude’s tool calls. Neither applies to a mod’s own $.fs and $.process calls: with Read(.env) denied, a mod can still read that file with $.fs.read or start a program that does. To limit those calls, keep the mod from loading or hook the call in a policy mod.
• Other permission checks can be overridden. A user’s mod that approves tool calls can approve a call that an ask rule would prompt for, or that a PreToolUse hook outside managed settings blocked. In auto mode, a call the mod approves runs without a classifier check.

​

Know which controls still apply

• Settings hooks keep working. Command, HTTP, prompt, and agent hooks in settings files and in plugins’ hooks/hooks.json run as before, alongside mods. Nothing about them is deprecated.
• Deny rules take precedence where the guard loads. A user’s mod can’t approve a call that a deny rule refuses, unless you set allowModsToOverrideDenyRules.
• Managed hooks run first. A PreToolUse hook in managed settings runs before any mod sees the tool call, and its block is final. If a mod then rewrites the call, your managed hooks run again on the rewritten call, so a block still applies. PreToolUse hooks from other settings files and from plugins run after the last mod, so a mod that returns its own result in place of running the tool keeps those from running. See The order mods run in.
• Network policy covers $.http.fetch. If your organization turns off web fetching, or nonessential network traffic is turned off for the session, Claude Code refuses a network request that a mod makes with $.http.fetch. The policy doesn’t cover a program the mod starts with $.process.run. That program reaches the network with the user’s own access.
• Plugin controls cover mods. A mod is a plugin, so the settings that restrict what users can install, such as strictKnownMarketplaces, decide whether it can be installed at all.
• Mods can’t change the permission prompt. A mod can restyle much of Claude Code’s interface, but not the permission prompt, so it can’t change what a prompt shows. A mod can still approve or deny a tool call before the prompt appears, as Know what happens by default describes.
• Trust prompts come first. In an interactive session in a directory the user hasn’t trusted yet, no mod loads until they answer the trust prompt.
• --safe-mode turns installed mods off, yours included. Start a session with claude --safe-mode to check whether a mod caused a problem.

​

Decide whether to leave mods on

​

Review what a mod can do

claude plugin validate ./some-mod

  ❯ ./register.js hooks: session.start, tool.call, ui.render{component=Pane}
  ❯ ./register.js calls: $.fs.read, $.http.fetch, $.store.set, $.ui.open

​

Choose how much to allow

• allowManagedModsOnly: an option on the built-in guard. Users’ own mods don’t load, and their settings hooks, status lines, and /goal keep working. Stop user-installed mods from loading lists what it covers.
• allowManagedHooksOnly: a wider setting. Only your organization’s mods and the mods built into Claude Code load. A mod a user installed themselves doesn’t. The setting also blocks hooks in users’ own settings files. Read What runs under allowManagedHooksOnly before you set it.
• disableAllHooks: the widest setting. In managed settings, it stops the mods in every installed plugin, yours included, and turns off every hook in settings files, so a PreToolUse hook in your managed settings no longer blocks anything. Custom status lines and /goal stop working too. Read disableAllHooks before you set it.
• disableSideloadFlags: rejects --plugin-dir and --plugin-url at startup, so nobody loads a mod from a directory, and keeps mods Claude writes during a session from loading. The setting also rejects --agents and --mcp-config. Read disableSideloadFlags before you set it.

​

Set options on the built-in guard

• The id has one spelling here: Claude Code reads the options only under cc-plugin-sec-default@builtin. prependPlugins accepts sec-default@builtin as well, and pluginConfigs doesn’t.
• Only managed settings count: the same entry in a user, project, or local settings file, or in a file passed with --settings, neither sets an option nor loosens one
• The guard has to load: if you set prependPlugins, name the guard in the list. Where the guard doesn’t load, neither option applies.
• The guard fails closed: if the guard can’t read managed settings, it refuses every user’s mod at load. If it can’t check the deny rules for a call that a user’s mod approved, it refuses the call.

​

Run your organization’s own mods

​

Install your organization’s mods and set the order

• Managed enabledPlugins sets the mod’s plugin to true
• Managed settings name the plugin’s marketplace as a directory on the user’s machine, by absolute path. An extraKnownMarketplaces entry does that and registers the marketplace for the user too.
• The marketplace lists the plugin by a relative path, so Claude Code loads it in place from that directory

/opt/acme/claude-plugins/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── acme-guard/
        ├── .claude-plugin/
        │   └── plugin.json
        └── hooks/
            ├── hooks.json
            └── register.js

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "acme-guard", "source": "./plugins/acme-guard", "description": "Acme policy mod" }
  ]
}

• prependPlugins: your mod sees every event before any user’s mod and every result after. It can change the event, refuse it, or skip the users’ mods.
• appendPlugins: your mod runs after every user’s mod, so it sees only the events those mods pass on, in the form they pass them

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }
    }
  },
  "enabledPlugins": { "acme-guard@acme-tools": true },
  "prependPlugins": ["acme-guard@acme-tools", "sec-default@builtin"]
}

• extraKnownMarketplaces: names the directory that holds the acme-tools marketplace. path is the absolute path of the directory that contains .claude-plugin/marketplace.json.
• enabledPlugins: turns acme-guard on for every user who receives these managed settings
• prependPlugins: puts acme-guard first and the built-in guard second, both ahead of any mod a user installs. Claude Code follows the order you list.

• hooks module acme-guard@acme-tools loaded, with tier prepend: the mod counts as your organization’s and runs first
• The same line with tier user: Claude Code treats it as a user’s mod. A second line, prependPlugins names acme-guard@acme-tools, which is not an enabled managed plugin with a hooks module; skipped, says the list skipped it.

• The list replaces the default: when you set prependPlugins in managed settings, name sec-default@builtin in it to keep the built-in guard. The guard is built in and needs no enabledPlugins entry.
• Your own ids must count as yours: in managed settings, Claude Code skips an id whose plugin doesn’t meet the three conditions for an organization’s mod
• Repositories can’t set them: Claude Code reads both settings from managed settings and never from a repository’s settings file. A user can set them in ~/.claude/settings.json to order their own mods only on a machine with no managed settings, and only when they aren’t signed in with a Team or Enterprise plan. Anywhere else, Claude Code ignores both keys in user settings. A list there neither adds nor removes the built-in guard.

​

Enforce a policy with a mod of your own

// The methods no user's mod may call, each spelled namespace.method
const BLOCKED_CALLS = ['process.run', 'process.spawn']

export function register(on) {
  // Runs each time another mod is about to load
  on('plugin.register', async ($, e, next) => {
    // Keep the calls in that mod's code that are on the blocked list
    const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))
    if (e.tier === 'user' && blocked.length > 0) {
      // Returning refuse keeps the mod from loading, and the text is the reason
      return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }
    }
    // Let every other mod load
    return next(e)
  })

  // Record each tool call, then let it go ahead unchanged
  on('tool.call', async ($, e, next) => {
    $.ui.log('audit tool.call ' + e.tool, { to: 'debug' })
    return next(e)
  })

  // Record which mod wrote a file, then the path, quoted because the mod chose it
  on('fs.write', async ($, e, next) => {
    $.ui.log('audit fs.write by ' + next.origin.plugin + ' ' + JSON.stringify(e.path), { to: 'debug' })
    return next(e)
  })
}

• plugin.register: decides whether another mod loads. It refuses a user’s mod that calls a blocked method and passes every other mod on.
• tool.call: writes a line such as audit tool.call Bash to the debug log for each tool call, and changes nothing
• fs.write: writes a line such as audit fs.write by reader "/tmp/notes.md" for each $.fs.write call another mod makes, and changes nothing. The mod’s name comes first and the path is quoted, so a path that a mod picks can’t pass for another field of the line.

• e.tier: where the mod would run, one of prepend, user, append, or builtin. Every mod a person installs is user.
• e.uses.calls: the mods API methods the mod calls, each spelled namespace.method such as process.run, without the $. that claude plugin validate prints

​

Refuse mods when your check fails

const BLOCKED_CALLS = ['process.run', 'process.spawn']

// The same check as before, moved into a function of its own
async function checkMod($, e, next) {
  const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))
  if (e.tier === 'user' && blocked.length > 0) {
    return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }
  }
  return next(e)
}

export function register(on) {
  // The handler runs only when checkMod throws or runs past its time limit
  on('plugin.register', checkMod).catch(async ($, e, next) => {
    // Let your organization's mods and built-in mods load
    if (e.tier !== 'user') return next(e)
    // Refuse the user's mod that couldn't be checked
    return { refuse: 'Acme policy check failed, so this mod was not loaded' }
  })
}

​

Next steps

• Plugin security: what any plugin can do on a user’s machine, and how to review one before it’s installed
• Mods overview: what a mod is and how it compares to hooks, skills, and MCP servers
• The order mods run in: how prependPlugins and appendPlugins fit with users’ mods
• Settings and environment variables: every setting named on this page in one table