Claude Code v2.1.287, released October 1, adds the biggest extensibility change since plugins themselves: mods. A mod is a plugin whose JavaScript or TypeScript handlers run inside the Claude Code process. That is a different category from everything Claude Code offered before, and it deserves both enthusiasm and a careful read of the trust model.
What a mod actually is#
Until now, extending Claude Code meant working from outside: a settings hook runs a shell command, a skill hands Claude some markdown, an MCP server exposes tools. Per the mods overview, a mod registers event handlers that Claude Code calls when something happens: a tool call, a submitted prompt, a turn, a slash command, or part of the interface being drawn. A handler can observe the event, rewrite it, or answer it itself.
The docs’ minimal example is about fifteen lines. One hook on tool.call increments a counter. A second hook on ui.render appends it to the spinner, so you see Thinking · tool calls: 3…. The two hooks share module-level variables, which is the quiet superpower here: state flows between handlers without files or IPC.
Per the launch post and docs, mods can:
- rewrite prompts before they reach the model
- block, rewrite, or retry tool calls, or hold one while asking you a question
- approve or deny permission requests
- redact secrets from tool output
- send a single request to a different model
- draw panes, a band above the prompt, buttons, and text fields, and replace pieces of Claude Code’s own UI such as a tool-call row or the spinner
- add
/commandsthat run your function immediately, with no model turn
Anthropic’s sample mods in the claude-code-playground repo show the range: token-weather forecasts your context window, blast-radius holds a risky command like rm -rf or a force push and shows what it would change with proceed/cancel buttons, and replay-theater adds a /replay that steps through the last turn’s file edits. Some built-ins are mods too, including /diff and the AGENTS.md loader.
Why this matters for agentic workflows#
Terminal-native agents have always had one honest weakness against IDE wrappers: UI. If you wanted a side panel of CI status or a visual diff gate, you were out of luck. Mods close that gap without giving up the terminal-first model. The pane lives in your terminal or the Desktop app’s Code tab.
More important for autonomous work is the control plane. A blast-radius-style mod is a policy engine you write in twenty lines: intercept the tool call, apply your rule, and either allow, deny, or escalate to a human. Combined with last week’s deniedModels and availableModelsMatch governance settings (see our v2.1.283 piece), Claude Code now has policy surfaces at the model, permission, and event layers. That’s what running agents unattended actually requires.
Compare the alternative. Cursor-style extensions live in an editor extension host built for human-driven workflows. Mods hook the agent loop itself, which is where autonomy gets shaped.
The part you must not skip: trust#
Here is the sober half. The docs are blunt: “A mod is code that runs with your permissions.” Once loaded, a mod can:
- read and write any file your user can, start processes, and make network requests
- read environment variables and settings files, including API keys
- see every prompt and tool call
- submit prompts as if you typed them, or message your other sessions
- approve a tool call before you’re asked, including one an
askrule would prompt for or that one of your ownPreToolUsehooks blocked - spend your plan or API usage by calling a model
Mods are not sandboxed. Turn on Claude Code sandboxing and it isolates the Bash commands Claude runs, but a process a mod starts runs outside it. The one UI surface a mod cannot touch is the permission prompt: it can’t change what a prompt shows you.
And mods are on by default in v2.1.287 and later. The CLAUDE_CODE_ENABLE_FUNCTION_HOOKS early-access variable is now ignored, so setting it to 0 won’t keep them off.
This is the same supply-chain surface we covered in the skill scanner piece, but sharper. A malicious skill can persuade a model. A malicious mod simply is code on your machine with your credentials, sitting between you and every approval. Treat /plugin install like npm install from an unknown publisher, because that is what it is.
Practical hygiene#
Anthropic gives you decent tooling; use it.
Audit before installing. Clone the plugin and run:
claude plugin validate ./some-modThe output’s hooks: and calls: lines list which events the mod handles and what it asks Claude Code to do (read files, make network requests), without running it. A status-line mod that requests network access and approval hooks deserves questions.
Know the kill switches.
- One mod: disable or uninstall it in the
/pluginInstalled tab - Every installed mod for one session:
claude --safe-mode - Every installed mod, always:
"disableAllHooks": truein~/.claude/settings.json(this also stops your settings hooks and custom status line)
Built-in mods are not stopped by those switches, and cc-plugin-sec-default can’t be disabled by users.
For organizations, mods are governed through managed settings. allowManagedModsOnly stops user-installed mods from loading, and the built-in sec-default mod loads first to guard what the organization manages from user-installed mods. If you run Claude Code across a team, decide your policy this week, not after the first incident.
Write them with Claude. A built-in plugin-authoring skill lets you describe the mod you want and have Claude write it. That’s the SDD way: spec the behavior, review the generated code, and run validate on it like anyone else’s.
Also in v2.1.287#
- A built-in opt-in mod,
you-should-know, runs a side agent that watches long tasks and surfaces things you might miss. It is disabled by default; enable it with/plugin enable cc-plugin-you-should-know@builtin. - URL prompts from MCP servers on the 2025-11-25 protocol, such as sign-in flows. If a server stops connecting after the update, add
"bareElicitationCapability": trueto its config entry. - A
prompt_textfield on the OpenTelemetryuser_promptevent. Drop or mask it wherever you already maskprompt, or you’ll leak prompts to backends you thought were scrubbed.
Verdict#
Mods are the right design: extensibility at the event level of the agent loop, with the trust cost stated up front rather than buried. They also change your threat model overnight, and the default-on rollout puts the burden on you. Turn them off org-wide if you can’t review them, or allow-list a handful and enjoy the best extension model in any agentic coding tool.