Claude Code 2.1.287, published to npm on October 1, 2026, adds Mods. A mod is a plugin whose JavaScript or TypeScript functions run inside Claude Code itself, on events such as a tool call, a submitted prompt or a request to the model. Each function can watch the event, change it, or handle it so that Claude Code’s own behaviour never runs. Mods are on by default in this version, and they run with the permissions of the person who installed them.
Editorial note: Prepared October 3 as an October 1, 2026 dispatch from the Claude Code changelog and the Mods documentation at code.claude.com as read on October 3. The documentation describes a moving target. Check the version you run.
- 01Three verbs: observe, rewrite, answerA hook can log an event and pass it on, pass on a changed copy, or return its own result so nothing downstream runs.
- 02It is not a settings hookSettings hooks run a shell command outside the process. A mod’s hooks are functions inside it, and only mods can draw in the interface.
- 03Unsandboxed, by designAnthropic’s own docs say a mod can read your secrets, approve tool calls and spend your usage. Install from people you trust.
- 04Admins decideA built-in guard loads first on managed machines and Team or Enterprise logins. One managed setting stops user-installed mods.
01 — The releaseWhat a mod is
The 2.1.287 changelog gives the feature one line: “Added Claude Mods: plugins may now modify deeper behavior”. The Mods overview fills it in. A mod is an ordinary Claude Code plugin with one extra file, called the hooks module, that exports a function named register. Claude Code calls it once when the mod loads. Inside, the mod subscribes to named events with a call shaped like on(event, handler). No build step is needed; Claude Code loads .js and .ts files directly.
A minimal mod is three files: a plugin manifest, a hooks.json that points at the module, and the module. Anthropic’s own example counts tool calls and prints the count beside the spinner while Claude works. Some of Claude Code’s own features now ship this way, including the diff pane and the loader for AGENTS.md files, and their source is public in the Claude Code repository.
The naming is awkward and the docs say so. Claude Code already had “hooks”, meaning shell commands, HTTP requests or prompts set in a settings file that run on lifecycle events. Those are now called settings hooks. On the Mods pages, “hook” means a mod’s function. This article follows that convention.
02 — The mechanismThe events a mod can hook
A hook receives three arguments: the mods API, the event, and a function named next. The handlers for one event form a chain. Call next with the event and the chain continues to the next mod and then to Claude Code’s own behaviour. Call next with a changed copy and everything downstream sees the change. Return a result without calling next and the chain stops there. That is the whole model. The table lists the events the documentation describes in detail.
| Event | When it fires | What a hook can do |
|---|---|---|
| tool.call | Claude is about to run a tool, including subagent and MCP tool calls. | Refuse it with a deny message Claude reads, change its arguments, retry it, hold it while asking the user, or answer it with a result so the tool never runs. |
| tool.check | After permission rules and settings hooks have decided allow, ask or deny. | Return that decision or a different one, based on what is true at that moment, such as the current branch. |
| prompt.submit | A prompt is sent, before the turn. | Rewrite the text, append context only Claude reads, or drop the prompt with a reason. |
| turn.step | Claude Code is about to send one request to the model. | Read token usage, route the request to a different model, or answer without calling the model. Written as a generator because the response streams. |
| turn.start, turn.complete | A turn begins or ends. | Observe. On completion, read the final answer, duration and token totals, or print a line under the answer. |
| ui.render | Claude Code draws a part of its interface, such as the spinner or a tool-call row. | Replace or restyle it. The permission prompt is excluded: a mod cannot change what that prompt shows. |
| classic.* | Any settings-hook event, such as classic.Stop. | Handle the same lifecycle events settings hooks see, from inside the process. |
Two details in the ordering matter for anyone who already runs settings hooks. A PreToolUse hook from managed settings runs before the first mod sees a tool call, and its block is final. A PreToolUse hook from any other settings file runs after the last mod calls next, so a mod that answers the call itself keeps those hooks from running at all. Anthropic’s events guide also shows how to make a guard fail closed: attach a catch handler that denies the call when the guard throws or times out, because without one Claude Code skips the failed hook and the held command runs.
03 — ContextMods against hooks, skills and MCP
Claude Code now has four extension points that overlap. The documentation’s own comparison reduces to one question: does the thing need to run inside the process? Only a mod can draw a pane, add a slash command that runs at once without a Claude turn, or rewrite an event in flight. The others work from outside.
Mod
Changes tool calls, prompts, commands, turns and what the interface draws. Written in JavaScript or TypeScript. Pick it for a pane, a band above the prompt, a custom command, or to rewrite an event.
Settings hook
Decides whether a tool call or prompt goes ahead, changes arguments or results, adds context. Pick it when you already have a script and want to block, allow or log.
Skill
Changes what Claude knows and does. Pick it when you keep pasting the same instructions into chat.
MCP server
Changes which tools Claude has. Pick it when Claude needs to reach an external system.
A plugin can hold all four, so a mod can ship beside a skill and an MCP server in one install. Our survey of what the Agent Plugins 1.0 standard does and does not carry between tools is the context for that: a mod’s hooks module is specific to Claude Code’s own events and API.
04 — RiskWhat a mod can reach on your machine
The overview page carries a warning box, and its list is worth reading in Anthropic’s own terms rather than ours. A mod runs with your permissions. The documentation says a loaded mod can act on your machine as you, read environment variables and settings files including any API key kept there, see every prompt and tool call, rewrite a prompt or a tool call, submit a prompt as if you typed it, approve a tool call before you are asked, and call a model on your plan. Mods are not sandboxed; turning on sandboxing isolates the Bash commands Claude runs, not a process a mod starts.
One sentence in the admin guide deserves a second read. Where the built-in guard loads, a mod cannot approve a call that a deny rule refuses. But that protection covers Claude’s tool calls, not the mod’s own file and process calls: with a deny rule on reading a .env file, a mod can still read the file through its own API or start a program that does. The only way to limit that is to keep the mod from loading, or to handle its calls in a policy mod of your own.
Anthropic provides a dry run. Clone the plugin and run claude plugin validate ./some-mod. The hooks line lists the events it handles; the calls line lists what it asks Claude Code to do, such as read a file, start a process or fetch a URL. A hook has no other way to reach outside its own code, which is why the list is complete. A mod that handles tool.check and calls the network should be read before it is trusted.
The permission story connects to a change we covered in Claude Code’s shift to auto mode: the admin guide notes that in auto mode, a call a mod approves runs without the classifier check. And the lesson of the ClawHavoc plugin incident applies without change: an extension marketplace is a supply chain, and a mod is the most capable kind of package in it.
05 — ControlsTurning mods off and managing them
Mods require version 2.1.287 or later and are on by default. The early-access environment variable that gated them is now ignored, so setting it to zero does not keep them off. The overview page gives three ways down: disable one mod from the plugin manager, start a session with the safe-mode flag to drop every installed mod along with other customisations, or set disableAllHooks in user settings, which also stops settings hooks and a custom status line. None of those stops a built-in mod.
For organisations, the admin guide describes a built-in guard mod that loads ahead of every user-installed mod on any machine with managed settings, and for any user signed in on a Team or Enterprise plan. One option on the guard, allowManagedModsOnly, stops user-installed mods from loading while leaving settings hooks and status lines alone. A second option, allowModsToOverrideDenyRules, does what its name says and is off unless an administrator sets it. Both are read from managed settings only, so a user cannot flip them locally.
The same release adds a built-in mod called You Should Know. It runs a side agent that watches a longer task and shows a note above the prompt when it spots something you might miss. It is disabled by default and, per the changelog, available to first-party sessions with telemetry on. Enable it with the plugin command the overview page gives.
06 — Practical implicationsWhen a mod is the right tool
For a team that runs coding agents on client work, three uses are worth a day of engineering. A guard that holds destructive shell commands and asks a human, with a catch handler so it fails closed. A cost pane that reads token usage per request and shows it while the session runs, which the turn.step event makes possible for the first time without parsing logs. And a prompt hook that appends the current branch, ticket or client name as context Claude reads, so the agent stops asking.
Two uses are not worth it yet. Routing requests to a different model from inside a mod is documented in a single line of the events guide, and a team that needs routing already has it at the API layer. And a mod that approves tool calls on your behalf is the one capability every warning on these pages is about; write it only when you can name the exact calls it approves and why.
Where a team wants this built and reviewed rather than experimented with, our AI transformation work covers agent configuration, permission design and the review record that goes with it. The companion rule from our inference hooks guide still holds: the hook that can block is only as good as the behaviour it does when it fails.
Validate before you install, and start with a guard
Run the validate command on any mod before it loads, read its hooks and calls lines, and write your first mod as a fail-closed guard on the commands you fear most. Everything else a mod can do is a convenience; that one is a control.