Claude Code 2.1.287: Mods, Function Hooks, and a Side Agent That Watches Your Back

Anthropic released Claude Code 2.1.287 on October 1, 2026. The changelog lists 106 documented changes. The one that changes what the tool is sits at the top: Claude Mods — a new plugin layer that runs in-process, written in TypeScript, with hooks into every engine event.

Until now, extending Claude Code meant shell hooks (run a command, pipe JSON, wait for stdout) or MCP servers (external processes speaking the Model Context Protocol). Both have real limits. A shell hook sees a tool call before it runs but cannot rewrite the input or replace the result. An MCP server can offer new tools but lives outside the agent's process, adding latency and a trust boundary.

Mods remove both constraints. They run in the same process as the agent. A single hook on * sees every event — tool calls, prompt submissions, UI renders, even other plugins' internal calls on the engine interface $. From one vantage point you can audit, rewrite, deny, cache, or draw.

What a Mod Actually Is

A Mod is a TypeScript module that exports a class implementing the Mod interface. The engine calls lifecycle methods: onStart, onToolCall, onPrompt, onRender, onEnd. Each receives a typed context object and can return a modified value, a denial, or nothing (pass through).

The engine interface $ is the same surface plugins already use — $.tool, $.ui, $.config, $.session. The difference is timing. A shell hook runs around a tool call. A Mod runs inside it.

// minimal mod structure
import { Mod, ModContext } from '@anthropic-ai/claude-code/mods';

export class RedactSecretsMod implements Mod {
  name = 'redact-secrets';
  version = '1.0.0';

  async onToolCall(ctx: ModContext) {
    if (ctx.tool.name === 'Bash' && ctx.tool.input.command?.includes('ghp_')) {
      return { ...ctx.tool, input: { ...ctx.tool.input, command: '[REDACTED]' } };
    }
    return null; // pass through
  }
}

The onToolCall hook can return a rewritten tool call object, a denial ({ deny: true, reason: '...' }), or null to continue normally. onPrompt can rewrite the user's prompt before the model sees it. onRender receives the UI virtual DOM and can inject elements — the diff mod opens a dedicated panel for /diff output this way.

Four Reference Mods Ship in the Repo

The anthropics/claude-code repository now contains four public mods with source:

• diff — opens a side panel showing /diff command output with syntax highlighting
• agents-md — loads the project's AGENTS.md as permanent instructions for every session
• sec-default — an organizational guard that keeps approved settings separate from user-installed mods
• telemetry — sends usage records to internal analytics (opt-in)

Two more are documented without public repos: a skill for writing new mods, and the side agent that became the built-in You should know mod.

"You Should Know" — The Side Agent

The flagship built-in mod is cc-plugin-you-should-know@builtin. Enable it with:

/plugin enable cc-plugin-you-should-know@builtin

It runs a background agent that watches long-running first-party sessions (telemetry must be on). When it spots something — a pattern, a missed optimization, a security concern, a hallucination risk — it surfaces a note above the prompt line. Not a modal, not a toast. A line of text that sits in your peripheral vision until you act or dismiss.

The design is deliberate. A side agent that interrupts is annoying. One that whispers is useful. The note appears in the same visual layer as the prompt, styled as a bronze-accented callout. You keep coding. The agent keeps watching.

Plugin Bundles: MCP Servers + Skills + Commands + Hooks + Agents + LSPs

Mods are the deep layer. The distribution layer is plugin bundles. A bundle is a GitHub repository with a defined structure:

plugin-name/
├── .claude-plugin/
│   └── plugin.json        # metadata (required)
├── .mcp.json              # MCP server config (optional)
├── commands/              # slash commands (optional)
├── agents/                # agent definitions (optional)
├── skills/                # skill definitions (optional)
├── hooks/                 # shell or function hooks (optional)
├── lsps/                  # LSP definitions (optional)
└── README.md

You install a bundle once (claude plugin install github:owner/repo) and get everything — MCP servers pre-configured, skills loaded, commands registered, hooks active, agents available. Anthropic's official directory lives at github.com/anthropics/claude-plugins-official. Third parties can submit. Private marketplaces work the same way.

The install command now accepts --config flags for bundled MCP servers (claude plugin install --config server.key=value), so a bundled server starts configured without a separate /mcp step.

MCP Improvements in the Same Release

2.1.287 is not only Mods. The MCP layer got substantive fixes:

• Fixed a repeat MCP sign-in request that could replace a pending sign-in link and break it
• Fixed /usage not crediting an MCP server for tool calls made while the server was still connecting
• Fixed plugins enabled on claude.ai occasionally going missing from Claude Code after a transient server error
• MCP servers on the 2025-11-25 protocol can now raise URL prompts; bareElicitationCapability works as a connect workaround
• Agents view adds an n: filter

Windows and accessibility fixes are also significant: screen reader support improved, terminal session handling stabilized, and the --plugin-url download no longer corrupts the session's cached plugin archive on reload.

What This Means for Developers

Three practical takeaways:

1. Organizational policy can now be code, not docs. sec-default shows the pattern: a mod that enforces approved settings regardless of what a user installs. Your security team writes a mod; every developer's CLI loads it. No more "did you remember to configure X?"
2. Secret redaction, audit logs, and destructive-command guards are now one function. A hook on * sees everything. Redact tokens before the model reads them. Log every tool call to your SIEM. Deny rm -rf with a custom message. All in-process, zero latency.
3. Plugin bundles solve the "tribal knowledge" problem. Anthropic named this in May 2026: the team's best setup lives in one person's ~/.claude. A bundle commits it to Git, versions it, and makes it one-command installable for every new hire.

npm update -g @anthropic-ai/claude-code
# or
claude update

/plugin enable cc-plugin-you-should-know@builtin