--- title: "Claude Code Mods: Plugins That Run Inside the Agent, With Your Permissions" date: 2026-10-02 tags: ["claude-code","mods","plugins","security","extensibility"] categories: ["AI Tools"] summary: "Claude Code v2.1.287 (Oct 1) ships mods: TypeScript plugins that run in-process and can rewrite prompts, block or approve tool calls, and redraw the UI. They are on by default, unsandboxed, and run with your user permissions." --- ![Claude Code Mods: Plugins That Run Inside the Agent, With Your Permissions](/images/claude-code-mods-in-process-plugins-v2-1-287.png) 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](https://code.claude.com/docs/en/plugins/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](https://claude.com/blog/claude-code-mods) 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 `/commands` that run your function immediately, with no model turn Anthropic's sample mods in the [claude-code-playground repo](https://github.com/anthropics/claude-code-playground/tree/main/claude-code/mods) 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](/posts/claude-code-model-governance-vs-copilot-model-breadth/)), 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 `ask` rule would prompt for or that one of your own `PreToolUse` hooks 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](/posts/agent-skill-scanners-skillspector-cisco-supply-chain/), 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: ```bash claude plugin validate ./some-mod ``` The 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 `/plugin` Installed tab - Every installed mod for one session: `claude --safe-mode` - Every installed mod, always: `"disableAllHooks": true` in `~/.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": true` to its config entry. - A `prompt_text` field on the OpenTelemetry `user_prompt` event. Drop or mask it wherever you already mask `prompt`, 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. ## Sources - [Mods overview, Claude Code Docs](https://code.claude.com/docs/en/plugins/mods/overview) - [Customize Claude Code with mods in TypeScript, Anthropic](https://claude.com/blog/claude-code-mods) - [Claude Code changelog, v2.1.286–2.1.287](https://code.claude.com/docs/en/changelog) - [Sample mods, anthropics/claude-code-playground](https://github.com/anthropics/claude-code-playground/tree/main/claude-code/mods)