Skip to content
senn-techsenn-tech
Back to blog
ClaudeAI & Development
AI in production2026-10-05· By Franz Senn

Claude Mods: What the New Plugin Format in Claude Code Is Allowed to Do

Updated 11 October 2026. The post of 5 October has been revised: a version table, a corrected policy mod, the community catalogue and our own measurements.

On 1 October 2026 Anthropic released Claude Code 2.1.287. The changelog line for it is one sentence long: "Added Claude Mods: plugins may now modify deeper behavior." The videos about the feature call it one of the biggest updates Claude Code has had. An explainer by Tristen O'Brien from 5 October walks through five mods he built in a week: a checklist view that hides the tool calls, a model and effort switch, a dock that runs a team of helper agents, a photo and video studio wired to the paid Higgsfield service, and a racing game for the waiting time. The channel marks Higgsfield as the sponsor. Jay E from RoboNuggets followed three days later with nine installable mods plus their repos, including two Anthropic samples. Both videos demonstrate the same format from the user side.

For anyone who runs Claude Code on machines their department is responsible for, the interesting question is a different one. What is going to run on those laptops, who is allowed to install it, and how do you take it away again? The answer is fully documented, and it is more specific than any demo. The working conditions of the tool itself are the subject of Claude Code in Practical Use.

What a mod is technically

A mod is a plugin. The directory needs a .claude-plugin/plugin.json, a hooks/hooks.json carrying one path in its modules field, and a JavaScript or TypeScript module exporting register(on, options). Inside it, every function that should do something is registered with on against an event name, for instance on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e)). A handler receives four things: the mods API as $, holding every method, the event as deeply frozen plain data, the next handler next, and an abort signal. The shape is middleware.

Per event the handler has exactly three options. It can watch the event and pass it on, change it by handing a copy to next, or answer it itself, in which case the behavior Claude Code would have shown never happens.

ModHook in a settings fileSkillMCP server
Where it runsinside the Claude Code processas a process or HTTP requesttext in the contextits own process
Can change the interfaceyesnonono
LanguageJavaScript, TypeScriptBash, Python, anything by pathMarkdownanything
Organized byplugin manifest, hooks modulesettings filea folder with SKILL.mdMCP configuration
Reviewed withplugin validate, plugin testsettings reviewread the texttool and process list

One detail here matters more for the review than it looks. A mod only draws where drawing is possible, which means the terminal and the Code tab of the desktop app. In the chat panel of the VS Code extension and under claude -p the hooks do run but draw nothing, and under WSL plugins are not loaded at all. A mod can therefore change the model and the tool calls in an environment where nobody sees any part of it on screen.

On by default, and ten releases in eight days

Mods are enabled by default from 2.1.287. The environment variable from the early-access phase is ignored from that version onward, so setting it to 0 does not keep mods off a machine.

The release pace is fast. The npm registry lists 2.1.287 on 1 October at 16:59 UTC and 2.1.296 on 9 October at 16:58 UTC, with eight more releases in between. The changelog for these ten releases contains several fixes an operator should read, because they concern the protective functions of mods themselves:

VersionDate (UTC)Fix according to the changelog
2.1.2893 OctoberA deny or ask rule on a nested part of a compound shell command did not hold against a user-installed mod's approval on managed machines. A user-installed plugin could rewrite the descriptions of the sign-in tools of an organization-managed MCP server.
2.1.2926 OctoberA mod's guard hook with .catch was skipped for calls that another mod made beneath it. A tampered cache of server-managed settings could switch off the built-in policy plugin while the fetch failed. PreToolUse approvals and auto mode bypassed the prompt for file reads from UNC paths.
2.1.2948 Octoberprompt and agent hooks written as instructions ("Block commands that …") allowed what they should have blocked.
2.1.2958 OctoberA mod's hook was handed a deeply nested tool input cut short with no error, so a guard could pass content it never saw. Calls made while a mod reloaded got past another mod's guard with .catch. New: onFailure: "block" for command and HTTP hooks.
2.1.2969 OctoberA managed PreToolUse hook with "continue": false refused the call but did not end the turn. In headless sessions, Esc during a prompt.submit hook let the unchecked prompt through.

Whoever deployed 2.1.287 had these holes, and each fix is bound to a version. The pattern across the entries is the same: the edge cases in which a guard silently checks nothing are being found one at a time. A policy mod is therefore something you maintain together with the Claude Code version.

What a mod is allowed to do

The docs do not soften it: "A mod is code that runs with your permissions." What they explicitly grant a mod:

  • It acts with the user's permissions, reads and writes files wherever the user can, starts processes and reaches the network.
  • It reads secrets, because it sees environment variables and the settings files, up to and including the API key.
  • It sees the session, every prompt, every model answer, every tool call.
  • It changes the session by rewriting prompts and tool calls, submitting a prompt as though the user had typed it, routing a request to a different model, or messaging another session.
  • It can approve a tool call before the user is ever asked.
  • It spends usage, because it may call a model on the user's plan or API key.

"Not sandboxed" is its own paragraph, with a qualifier that gets skipped often. The Claude Code sandbox isolates Claude's own Bash commands. A process a mod starts through $.process.run runs outside that sandbox. The network policy reaches only so far either: CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC stops the built-in mods and requests that carry the session's Anthropic credentials. Before 2.1.288 it stopped every $.http.fetch request from every mod, and it no longer does. A program a mod starts with $.process.run is covered by none of these rules.

The sharpest sentence in the documentation is aimed at everyone who has already built permission rules. A denied Read(.env) does not protect the file, because a mod can read the same file with $.fs.read. Deny rules and managed PreToolUse hooks do take precedence over a mod's approval, but only for tool calls made by Claude itself, not for the mod's own $.fs and $.process calls. A mod may also approve a request that an ask rule would have put to the user, or one that a PreToolUse hook from unmanaged settings blocked. In auto mode a request approved that way continues without the command classifier. The docs name one limit as well: a mod can restyle much of the interface, but not the permission prompt. Its choices and its text stay untouched.

Four steps, the first three of which execute nothingclaude pluginvalidateread hooks: and calls:check the regimesfs, process, model, networkset the guard optionallowManagedModsOnlypolicy mod with.catchotherwise fail-open
The static review path from the docs. The inventory is dependable; the claim about the process behind it is not. (Quelle: senn-tech, own reading of the Claude Code docs (11 Oct 2026))

The guard and its limits

On a machine with managed settings, and for users signed in with a Team or Enterprise plan, Claude Code loads a built-in mod called sec-default@builtin, ahead of every mod a user brings. It sits at a higher priority tier, it can refuse other mods, and it implements two options. allowManagedModsOnly set to true keeps every mod the user brings from loading, including one Claude wrote during a session. allowModsToOverrideDenyRules set to false stops a mod from approving a request that violates a deny rule or a managed PreToolUse hook. The options live in managed settings under pluginConfigs, key cc-plugin-sec-default@builtin. The same entry in a user, project or local settings file does nothing. If the guard cannot read managed settings it refuses every user mod, so it fails closed.

Where that guard stops is stated in half a sentence and decides a great deal. When authentication happens with an API key, or through Amazon Bedrock, Google Cloud Agent Platform or Microsoft Foundry, the guard loads only if managed settings exist on the device at all. An organization that ships no managed settings has no guard, regardless of what individual users put in their own files.

Shipping your own organization mods takes three conditions before Claude Code recognizes them as yours. Managed enabledPlugins sets the plugin to true, managed settings name its marketplace as a directory on the machine by absolute path, and the marketplace lists the plugin by a relative path. A plugin Claude Code copies into its cache from a GitHub, git, URL or npm source counts as a user's plugin, even when it is enabled by managed settings. That directory and every one above it must be writable by administrators only, otherwise the mod can be rewritten.

Two further levers remain. disableSideloadFlags set to true rejects --plugin-dir and --plugin-url and keeps mods written during a session from loading. disableAllHooks set to true stops the mods of every installed plugin, your own included, and with them every hook from the settings files, so a managed PreToolUse hook no longer blocks anything. claude --safe-mode turns off all installed mods for one session, the organization's among them.

The policy mod and its trap

Anyone who wants to admit some mods and refuse others writes a policy mod of their own. It sits in prependPlugins ahead of all user mods and receives the plugin.register event with the content of the validate list whenever another mod is about to load. In the docs example it refuses every user mod whose code calls $.process.run or $.process.spawn:

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

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) {
  on('plugin.register', checkMod).catch(async ($, e, next) => {
    if (e.tier !== 'user') return next(e)
    return { refuse: 'Acme policy check failed, so this mod was not loaded' }
  })
}

The catch sits in the same section of the docs and is one of the few places where Claude Code leaves a security behavior open by default. A hook that throws or exceeds its time limit is skipped. A checker mod that crashes therefore lets through exactly what it was supposed to stop. Every policy hook needs a .catch handler that returns refuse for anything of the user tier and passes the other tiers on to next(e), so the organization's own mods still load. The earlier version of this post showed a code block at this point with module.exports, a function blockUnauditedProcess and a return value { Veto: … }. None of those spellings appears in the docs. The block above follows the docs.

Two more limits of the policy mod are stated further down that page. If the worker thread that runs installed mods crashes three times, Claude Code unloads every mod that is not built in, the organization's policy included, until the user runs /reload-plugins or restarts. And a mod Claude wrote during a session only stays out if allowManagedModsOnly or disableSideloadFlags is set.

Reading a mod before installing it

claude plugin validate <directory> executes nothing and still prints two lists. Under hooks: it names the events the module handles, and under calls: every mods API call it makes, including calls from a function registered in a registry. --strict turns warnings into errors, --json produces a report a pipeline can consume. claude plugin test runs the mod's .test.ts files and exits with status 1 when one fails.

That list is an inventory rather than a proof. It does not say what a listed $.process.run call then does to the machine. We also read why the list can be trusted. The module runs in a container of its own with no Node access, no fs, Buffer or process, and no dynamic import(), and Claude Code refuses to load a mod whose use of the mods API this command cannot read. A mod that hides its capabilities is therefore excluded by the architecture, and what appears in the list is the whole surface.

Some calls deserve a closer look: $.fs.read and $.fs.write for files, $.process.run and $.process.spawn for programs, $.http.fetch for the network, $.env.get and $.settings.read for keys in the environment and settings, $.env.set for variables passed to every program started afterward, $.model.complete for spend on the user's account and $.session.send for messages to other sessions. Among the events, tool.call and prompt.submit are the lines that mean the mod sees every call and every prompt and can change both.

What the community built from it

The catalogue awesome-claude-code-mods searches public GitHub repositories, runs each plugin through claude plugin validate and records what the validation reports the mod can read, write, run or send over the network. It lists 3,382 mods as of 11 October. The catalogue calls itself an independent scan rather than an Anthropic directory, and a scan is not an approval. Alongside it are Anthropic's sample mods in the claude-code-playground repository: token-weather draws a forecast of the context window above the prompt, blast-radius holds risky shell commands and shows what they would change, and replay-theater steps through the file edits of the last turn with /replay.

The catalogue is organized into dashboards and usage (context, cost, the plan's 5-hour and 7-day limits), games and pets for the waiting time, git, pull requests and CI, safety and privacy, memory and context, rendering, and agents and workflows. The safety mods include one that redacts keys and IP addresses before the model sees them, one that demands a one-time code before risky commands, and modwall, which reads the scanned footprint of each mod as it loads, labels it, and admits, asks or blocks according to a policy.

The catalogue's descriptions, which come from the authors and which we have not checked, show four patterns worth including in a review. One mod syncs event types and times with its own server. Another has due reminders emailed through a third-party server. A third downloads a game, starts it and connects to a shared game server. A fourth syncs click counts with a sponsor server. None of these mods is harmful for that reason. The point is where you find out: in the calls: part of the validation and in the source, not in the interface a user sees.

What we measured

We looked read-only over SSH on 5 October 2026. In the code-server container on our appliance (VM 116, 192.168.180.206) Claude Code ran 2.1.283; on the host librechat-pve6 (192.168.180.2) it is 2.1.199. Both are below the 2.1.287 threshold, so mods are not available there. Neither machine has an /etc/claude-code/managed-settings.json. The check on 11 October found 2.1.199 on .2 again. In the code-server container on .206, docker exec found no claude on the path, and a search by file name down to depth 7 came back empty. We have not established what became of the previous week's version. Our inventory dossier at docs/stack-inventory/inventory.md, last collected 7 September, does not mention Claude Code; the version layer for this tool was never collected.

The work PC runs 2.1.296. We installed six mods there: the three Anthropic samples and, from the catalogue, modwall, limits and smart-compact. Before each install we ran claude plugin validate, then read the calls: line and, wherever a $.process.run appeared, the source behind it. blast-radius starts only sleep and a read-only script. modwall starts claude plugin list --json and claude plugin validate --json. limits starts nothing as long as the costCommand option stays empty. None of the three catalogue mods calls $.http.fetch. When the install of the three catalogue mods ran from inside the session, the auto-mode classifier refused it with the reason "Untrusted Code Integration", even after the user had approved the install. We then started it ourselves in the terminal. That is a usable data point that auto mode does not treat foreign mod code as trusted on its own, though it is a single observation. We installed modwall and have not yet tested whether it works.

We also wrote a guard mod of our own as a trial, one that blocks five known mistakes of our environment in Bash commands. claude plugin validate warned twice, "gating hook without .catch". We added .catch handlers that pass the call through. For a mod that only warns, that is the right choice. For a policy mod it would be the wrong one.

So there is nothing to roll back on the servers today. That changes with the next update a developer takes on their own, because mods arrive enabled by default and we ship no managed settings. What we are missing is two undramatic things: an inventory sheet of agent CLI versions on the devices we can see, and an answer to who deploys managed settings. Running several of these CLIs on the same devices is the normal case by now, see the 2026 survey of the agent tools. Laptops we cannot reach from here are outside that measurement, which is the point rather than a caveat.

The model switchers, panels and games in the videos are consequences of the format. The part that concerns us is that a twenty-line JavaScript module can read files that were never in a user's context, and that this module is an officially supported way to build Claude Code. Allowing or banning mods is a decision you can only make once the versions are known and managed settings exist. Until then, individual developers should follow the order from the docs: run claude plugin validate first, read the calls: line, then install.

Further reading

Questions?
Do mods have to be enabled before they run?+

No. Mods are on by default from Claude Code 2.1.287. The environment variable from early access, CLAUDE_CODE_ENABLE_FUNCTION_HOOKS, is ignored from that version on, so setting it to 0 keeps nothing off. The organization-wide switch is allowManagedModsOnly on the built-in guard cc-plugin-sec-default@builtin, and that guard only loads where managed settings exist or where the user signed in with a Team or Enterprise plan.

Does denying Read of .env protect a developer's machine from a mod?+

Not from a mod. A deny rule and a managed PreToolUse hook take precedence over a mod's approval for Claude's own tool calls. They do not cover the mod's own $.fs and $.process calls, and the docs state the case directly: a mod can read a file that Read(.env) refuses with $.fs.read. We did not reproduce this.

Can a mod be reviewed before it is installed?+

Statically, yes. claude plugin validate <directory> runs nothing and still prints which events the module handles under hooks: and every mods API call it makes under calls:, including calls made from a registry function, with --strict and --json for a pipeline. That is an inventory, not proof, and it says nothing about what a listed $.process.run call then does on the machine. The reason the list is trustworthy is structural: the module has no Node access, and Claude Code refuses to load a module whose mods API usage the command cannot read.

What happens when a policy mod of your own crashes?+

The mod it was checking loads anyway. When a hook throws or exceeds its time limit, Claude Code skips it, so the check fails open. To prevent that, attach a .catch handler to the hook that returns refuse for mods of the user tier. claude plugin validate warns about a gating hook without .catch.