A Function Inside the Loop

Anthropic shipped a new extension point for Claude Code called mods, available from version 2.1.287 on. The name undersells what changed. Claude Code already had several ways to extend it, among them settings hooks, skills and MCP servers, and the docs describe them as working from outside Claude Code. A settings hook is a shell command, HTTP request or prompt that Claude Code runs on an event. A skill is a file of instructions Claude reads. An MCP server is an external process that gives Claude tools. A mod is different in kind: its handlers run inside Claude Code, and the docs say that is what lets it do things the others can’t, such as drawing a pane or restyling the spinner.

A mod is JavaScript or TypeScript event handlers that Claude Code calls as functions when an event happens: a tool call, a submitted prompt, a part of the interface being drawn. The handler gets the event and three options: let it continue unchanged, change it, or answer it itself and skip the usual handling. Anthropic’s documentation gives a small complete example, trimmed here of its comments:

let calls = 0

export function register(on) {
  on('tool.call', async ($, e, next) => {
    calls += 1
    $.ui.invalidate('ui.render')
    return next(e)
  })

  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

Two hooks, one shared variable. The first counts tool calls and asks the interface to redraw. The second intercepts Claude Code’s own spinner component and appends the count to whatever it was already going to say. A dozen lines turn “Thinking…” into “Thinking · tool calls: 3…”. The docs list bigger things a mod can do with the same machinery: a pane beside the transcript, a band above the prompt, a /command that runs without spending a model turn, a handler that holds a risky shell command and asks the user a question before it runs (Anthropic’s sample blast-radius mod does this).

What the missing sandbox costs

The feature comparison matters less than the trust boundary underneath it, and Anthropic’s docs are direct about where that boundary sits. A mod is code that runs with your permissions inside Claude Code, and the docs say plainly that mods aren’t sandboxed. They list what a mod can do: read and write any file your account can, read environment variables and settings files (including an API key sitting in either), see every prompt and tool call in your session, rewrite a prompt or a tool call, submit text as if you’d typed it, and approve a tool call before you’re asked.

That last one is the sharp edge. Claude Code’s permission system is meant to stop risky commands and wait for a human. The documentation says a mod that approves tool calls can approve one that an ask rule would prompt for, or that one of your own PreToolUse hooks blocked. It also points to its permissions page for the cases where such a mod can approve a call that a deny rule refuses; I haven’t tested those cases. Sandboxing, if you turn it on, isolates the Bash commands Claude runs, and a process a mod starts runs outside it.

A pane that charts your context window, or a guard that catches rm -rf and shows you what it would delete, needs to see the event before it happens and to draw in the interface. The docs tie drawing to running inside Claude Code, which is the same placement that carries the broader access above. I’d read the lack of a sandbox as the price of that placement, though the docs don’t say whether it was a deliberate trade.

Four extension mechanisms compared A comparison of four extension mechanisms against two properties: whether the code runs inside Claude Code's own process, and whether it can draw in the interface. Mod: runs inside the process, yes, can draw a pane or band. Settings hook: a shell command, HTTP request or prompt run from outside, no, cannot draw. Skill: a file of instructions Claude reads, no, cannot draw. MCP server: an external process that gives Claude tools, no, cannot draw. Panes the mod draws appear in the terminal and Desktop app, not in every place Claude Code runs. Only the mod sits inside the process boundary. CLAUDE CODE · PLUGINS/MODS DOCS, OCT 2026 Runs inside the process Can draw in the interface Mod Yes: a function it calls Yes: panes, bands, rows Settings hook No: runs from outside No Skill No: instructions Claude reads No MCP server No: an external process No A mod that approves tool calls can approve one an ask rule would prompt for. The docs say mods aren't sandboxed.
Of the four mechanisms, only a mod runs inside Claude Code's own process. The docs tie drawing to that placement; panes show in the terminal and Desktop app. The same placement lets a mod approve a call that an ask rule would prompt for.

The part that keeps this honest

What keeps the whole thing from being a plain liability is that a mod has to go through a documented interface to reach beyond its own code. The documentation states the constraint directly: to do anything outside its own code (draw, call a model, read a file, start a process, make a network request) a hook calls the mods API, and it has no other way to do those things. That makes much of a mod’s reach checkable before you run it. claude plugin validate on a mod’s directory lists the events it handles and what it asks Claude Code to do, without executing it. The list shows which calls a mod makes, not what it does with them. You can read that output and see, for instance, that a mod makes no network-request call at all. Approval is handled differently: a handler answers the tool.check event, so it shows up on the hooks: line of the output rather than the calls: line, and you’d look for that event by name.

That is a different trust model from “this plugin is probably fine.” A settings hook runs a script you can read, and a skill is instructions rather than a handler. Mods reopened the question because they added the capability, and Anthropic’s answer to “how do I know what this does” in the docs is the validate listing, alongside organization controls such as managed settings. Whether that’s enough is a judgment for the person installing the mod. The tooling at least gives them something to judge.

References

  1. Anthropic (2026). Mods overview. Claude Code documentation, accessed 3 October 2026. Source of the version requirement (v2.1.287 or later), the example mod, the permissions statements, and the comparison table.
  2. Anthropic (2026). Permissions: extend permissions with hooks. Claude Code documentation, accessed 3 October 2026. Referenced for the cases where a mod can approve a call that a deny rule refuses.
  3. Anthropic (2026). Manage mods for your organization. Claude Code documentation, accessed 3 October 2026. Source of the plugin validate review and the managed-settings controls.