Harnesses
Claude Code Mods: TypeScript function hooks let you rewrite the agent loop itself
Claude Code v2.1.287 shipped mods on 1 October 2026: TypeScript functions that run inside the agent's own process and can rewrite prompts, block tool calls, approve permissions and replace built-in features. What the API makes possible, why it is on by default, and how to audit a mod before it sees your API keys.
- Published
- 16 Oct 2026
- Reading
- 9 min
- Class
- harnesses
half-life 90dfrom 16 Oct 2026
Until this month, extending Claude Code meant working from outside it. A settings hook launched a shell command and waited for it to exit; a skill handed the model some markdown; an MCP server offered tools. All three are useful, and all three sit beside the agent rather than inside it. On 1 October 2026, Claude Code v2.1.287 changed that with mods: small TypeScript functions that run in Claude Code's own process and hook the events the agent loop emits — the prompt before it reaches the model, the tool call before it runs, the permission request before you answer it, and the interface that draws the result (Anthropic release notes, 1 October 2026).
Anthropic's own summary of why it built them is the shortest explanation you will get: hooks "can't rewrite events, draw new UI, or replace features. Mods can" (Anthropic, 1 October 2026). The design was published for public comment first, on GitHub issue #91870 from 3 September 2026, so much of the semantics were argued out in the open before shipping. This is the biggest extensibility change to Claude Code since plugins themselves — and it arrives switched on by default, with a trust model you need to read before you install anything.
What a mod actually is
A mod is an ordinary Claude Code plugin with one addition: the plugin's
hooks/hooks.json names a modules entry pointing at a
JavaScript or TypeScript file, and that file exports register(on, options)
(Mods reference, Claude Code docs, current as of v2.1.290). Claude Code loads the
TypeScript directly — no build step, bundler or package install (Firecrawl,
6 October 2026). When the mod loads, register runs once and calls
on(event, matcher?, hook) for each event the mod cares about.
Every hook receives the same three arguments. $ is the mods API — the only
door a mod has to the outside world, covering files, processes, network, drawing and
state. e is the event as frozen plain data. next is the
middleware call: pass the event on, pass on a modified copy, or answer it yourself and
never call next at all. That gives each hook three modes — observe
(read the event after the fact), rewrite (change it before Claude Code
acts), and answer (skip the chain entirely).
Several mods on the same event nest like Koa or Express middleware: the first mod to
load sees the event first and the result last, and mods run in load order rather than
installation time (Anthropic, 1 October 2026; sdd.sh, October 2026). Load order is
tiered — prepend, user, append,
builtin — which is what makes admin control possible: an organisation that
prepends its own mod owns every hook registered below it, and downstream code cannot
undo it (GitHub #91870, 1 October 2026 update).
The event surface is large. A community census of Anthropic's type declarations found
142 event names in v2.1.290 — 46 engine events, 63 calls on $, and 33
classic.* equivalents of the older settings hooks
(claudecodemods.com, read
10 October 2026). The ones you will actually use: tool.call,
tool.check, tool.describe, prompt.submit,
prompt.section, prompt.attachment, turn.step,
ui.render, command.run and session.start.
What you can build with it
With one function on one event, a mod can rewrite a prompt before it reaches the model, block or retry a tool call, approve or deny a permission request, or redact secrets from tool output before the model reads it (Anthropic, 1 October 2026). It can also draw: panes beside the conversation, a band above the prompt, buttons and text fields, and it can replace parts of Claude Code's own interface such as a tool-result row or the spinner. Slash commands can run your function directly, with no model turn. Buttons work in both the terminal and the desktop app.
Anthropic's sample mods in the
claude-code-playground
repository show the practical range: token-weather forecasts your context
window; blast-radius holds a risky command like a force push, shows what it
would change, and waits for proceed or cancel; replay-theater steps through
the previous turn's file edits (sdd.sh, October 2026). Teams are named in the launch post
too: a pane showing your CI/CD status, a confirmation gate before anything touches
production config, and a mod that loads first and logs every call every other mod makes.
Two further details matter more than they look. First, built-ins are moving in:
/diff and the AGENTS.md loader are already mods, with source
published for diff, agents-md, sec-default and
telemetry, and Anthropic says it plans to keep moving features across so you
can "pare Claude Code down to a small core and add back only what you want"
(Anthropic, 1 October 2026; subagentic.ai). Second, state behaves like real code:
module-level variables reset on hot reload, while $.state survives it
(Firecrawl, 6 October 2026). There is also a built-in you-should-know mod —
a side agent that watches long tasks and flags things the main agent missed — off by
default, enabled with /plugin enable cc-plugin-you-should-know@builtin.
The trust model, which is the part you must not skip
Anthropic states it plainly in the launch post: mods "run with the same access to your machine as Claude Code itself. They aren't sandboxed." A loaded mod can read and write any file your user can, start processes, make network requests, read environment variables and settings files including API keys, see every prompt and every tool call, submit prompts as if you had typed them, and spend your plan or API usage by calling a model (Anthropic and sdd.sh, October 2026).
The sharp edge is the approval path. A mod can approve a tool call before you are
asked — including one an ask rule would have prompted for, or that one
of your own PreToolUse hooks blocked (sdd.sh, October 2026). In other
words, an installed mod sits between you and every permission prompt you rely on. Two
containment facts follow. Claude Code's own sandboxing isolates the Bash commands
Claude runs, but a process a mod starts runs outside it. And the one
surface a mod cannot touch is the permission prompt itself: it cannot change what that
prompt shows you.
It is also on by default. v2.1.287 ignores CLAUDE_CODE_ENABLE_FUNCTION_HOOKS,
so the early-access variable will not switch mods off — setting it to 0 does
nothing (Firecrawl, 6 October 2026; claudecodemods.com, 10 October 2026). If you set it
during early access, delete it. The escape hatches that do work:
- 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— but note this also stops your settings hooks and custom status line, while built-in mods keep running.
Before installing anything, audit it. claude plugin validate ./some-mod
reads the manifest and hooks module and prints a hooks: line listing which
events the mod handles and a calls: line listing what it asks Claude Code
to do — file reads, network requests — without running it. A status-line mod that wants
network access and approval hooks deserves a conversation first. Treat
/plugin install like npm install from an unknown publisher,
because that is what it is: a malicious skill has to persuade a model, whereas a
malicious mod simply is code on your machine with your credentials
(sdd.sh, October 2026).
What admins get, and what shipped alongside
Existing plugin controls carry over: admins can allow or block marketplaces, and on Team
and Enterprise plans a built-in guard called sec-default loads ahead of
every mod a user installs. It stops user-installed mods from risky overrides such as
overriding permission deny rules, its source is published in Anthropic's
mods/sec-default directory, and users cannot disable it (Anthropic,
1 October 2026). Managed settings add allowManagedModsOnly — only your
organisation's mods and built-ins load — and a separate
allowModsToOverrideDenyRules option exists for organisations that
deliberately want that (Mods reference, Claude Code docs). Decide your policy before the
first incident, not after.
Two smaller v2.1.287 changes are worth knowing. Repeated crashes in the hooks worker now
switch off only the mods that run there, instead of disabling function hooks for the rest
of the session — and anything those mods were holding back stays held back, so a crash
does not open a gate a mod had closed (Claude Code changelog, v2.1.287, 1 October 2026).
And the OpenTelemetry user_prompt event gained a prompt_text
field: mask or drop it wherever you already mask prompt, or you will leak
prompts to backends you thought were scrubbing them.
What to do about it
- Assume the flag is gone. Remove
CLAUDE_CODE_ENABLE_FUNCTION_HOOKSfrom shells and settings; it is ignored, and current versions of Claude Code have mods on. - Audit what you already run.
/pluginlists what loaded this session;claude plugin validateshows events and API calls without executing anything. - Write your own before you trust someone else's. Claude Code can
generate a mod from a description via the built-in
plugin-authoringskill, andclaude --plugin-dirhot-reloads on save — theblast-radiuspattern is roughly twenty lines of policy you can read end to end. - Use mods where you previously wanted a wrapper. Prompt redaction, command gates and audit logs used to require wrapping the whole agent; they are now a hook on the event itself, which is the control plane running agents unattended actually needs.
- If you run Claude Code across a team, set the guardrails first:
sec-default,allowManagedModsOnly, and your marketplace allow-list — in that order.
Is this a first mover advantage? We have not seen an in-process middleware API of this kind in another terminal coding agent; as sdd.sh put it on the day of release, cursor-style extensions live in an editor extension host "built for human-driven workflows", while mods hook the agent loop itself, where autonomy gets shaped. Expect the comparison to be made for you over the next two release cycles. Meanwhile, the same week's containment work — the fail-closed hooks of 8 October — is the other half of the picture: a mod can now approve anything, so the hooks that say no need to fail the right way (Agent sandboxes go mainstream, 14 October 2026). Extensibility and containment shipped a week apart, and you need both.
Sources
- Anthropic: Customize Claude Code with mods in TypeScript — 1 Oct 2026. Primary source: what mods are, what they can do, the unsandboxed statement, built-ins-as-mods,
sec-defaultand the team use cases. - Claude Code docs: Mods reference — checked 16 Oct 2026, current as of v2.1.290. File layout, the
register(on, options)signature, event tables, tiers and managed-settings flags. - GitHub issue #91870: Mods — make Claude 10x more extensible — opened 3 Sep 2026, community update 1 Oct 2026. Design published before launch; middleware nesting and admin-prepend semantics.
- sdd.sh: Claude Code Mods — plugins that run inside the agent, with your permissions — Oct 2026. Trust-model analysis, the pre-approval capability, kill switches, sample mods, the editor-extension-host comparison.
- Firecrawl: Claude mods — what they are and how to build one in TypeScript — 6 Oct 2026. No build step, hot reload,
$.stateversus module variables, flag removal. - claudecodemods.com: hook events across Claude Code mods — read 10 Oct 2026. The 142-event census (46 engine, 63
$calls, 33 classic). - subagentic.ai: Claude Code 2.1.287 lets plugins rewrite the agent with mods — Oct 2026. Built-in mod source list, where hooks and drawing do and do not run.
- Claude Code changelog — v2.1.287, 1 Oct 2026. Default-on status, hooks-worker crash handling, the OpenTelemetry
prompt_textfield.