Claude Mods in 2026: An In-Process Extension Architecture

Agent harness extension architecture

Agent harness extension architecture changes with Claude Mods, an in-process extension surface launched in Claude Code v2.1.287 on October 1, 2026; handlers run inside Claude Code and can intercept runtime events, requests, and interface rendering, as described in Anthropic’s Claude Mods launch post.

How This Guide Was Built

This analysis is based on Anthropic’s published documentation and launch posts, fetched on 2026-10-02 — we did not run mods hands-on. It describes the documented capabilities and security boundaries, not observed runtime behavior; details can vary across CLI, Desktop, VS Code, cloud sessions, and non-interactive use, as the mods overview explains.

What changes when extensions run in-process?

Mods move extension handlers into Claude Code’s process, unlike settings hooks, which configure shell, HTTP, or prompt-based handlers that run outside it. That placement lets mods intervene in the host’s events and interface rather than merely react across a process boundary; the hooks documentation and mods overview describe the distinction.

A mod can handle events and make runtime requests through the documented mod APIs. That is a different contract from a hook that receives an event and returns a result through its configured mechanism. Skills provide instructions or workflows, while MCP servers expose tools and resources; neither is an in-process UI and event-rewriting layer.

These boundaries matter when a team ports existing tooling into an agent harness. A shell hook remains a useful choice when an external command can enforce the requirement; an in-process mod adds power, but also makes the host’s own behavior part of the extension contract.

What can a mod do that other surfaces cannot?

Mods can draw custom panes beside the transcript and a band above the prompt with tabs, buttons, and text fields. They can also redraw Claude Code’s own interface, including tool rows, the spinner, and dialogs. The documented mod events and mod APIs expose the relevant interaction surface.

That surface extends beyond display. A mod can step into, guard, wrap, or replace tool calls and requests; provide functions for slash commands that run without a Claude turn; and share variables between hooks. A skill can explain a policy, and an MCP server can implement a tool, but neither offers this same combination of host UI control and in-process interception.

The UI option is particularly consequential: a mod can change what the operator sees while a request is being made. That can make an intervention clearer, but it can also obscure familiar interaction patterns. The permission prompt is the important exception: mods cannot restyle it.

The trust boundary is the host’s permission boundary

A loaded mod runs with YOUR permissions. It is not sandboxed: it can read and write files anywhere, start processes, make network requests, read environment variables and settings files including API keys, and see every prompt and tool call. The mods security documentation and permissions documentation describe the implications.

A mod can rewrite prompts or tool calls, submit a prompt as if you typed it, message another session, approve tool calls before you are asked, and spend your usage. The documented approval power includes calls that a deny rule refuses, so ordinary permission flow cannot be assumed to remain authoritative. Review the permission controls as part of reviewing any mod’s behavior.

Claude Code’s sandboxing does not change this boundary. Sandboxing isolates Bash commands, but a process started by a mod runs outside the sandbox; see the sandboxing documentation. The permission prompt is the one UI surface a mod cannot restyle, which preserves a visible control but does not make untrusted code safe.

This is why mod review belongs alongside prompt-injection defense, not after it. A compromised or overly broad extension can observe and alter the same interactions that defenses are meant to protect. See CodeIntel’s prompt-injection defense architecture for tool-using agents.

Load order composes enforcement

Mods run in load order with onion semantics: the first-loaded mod sees an event first and sees the result last. This lets a stack of mods from different authors compose policy and behavior, but also means ordering is part of the security design, not just configuration. See the mod administration documentation.

On Team, Enterprise, and managed-settings machines, the sec-default mod loads first by default. It is intended to stop user-installed mods from overriding permission deny rules. Admins can load their own mods first, but must keep sec-default restrictions; the guarantee is conditional on those managed configurations, not universal.

A mod loaded first can also implement an audit-mod pattern, recording every call that every other mod makes. This creates a useful observation point, but it does not remove the need to trust code with access to that point. The same ordered composition that supports layered guardrails raises questions addressed in CodeIntel’s guardrails architecture.

Limit blast radius before enabling a mod

Run claude plugin validate ./some-mod to list a mod’s hooks, meaning the events it handles, and calls, meaning its runtime requests, before running it. Anthropic’s guidance is direct: “if a settings hook, skill, or MCP server already does what you need, use that instead.” The mods overview documents the validation step and the preference for narrower surfaces.

There are multiple disable layers, with different blast radii. Disable one mod through /plugin for the narrowest change. --safe-mode disables customizations for one session, not just one mod. disableAllHooks:true also disables settings hooks and a custom status line, but does not disable built-in mods; the --bare flag likewise leaves built-in mods running.

Organizations can control which marketplaces are allowed or blocked and manage mod load order. Those policies complement local validation; they cannot make an unsafe mod harmless once it is granted the host’s permissions. The admin guide covers managed controls.

A small core changes harness design

Claude Code’s direction is to pare the host down to a small core and add back only the behavior an environment wants. /diff is already a mod; agents-md, sec-default, and telemetry are mods with public source in Anthropic’s Claude Code mods repository. The changelog and launch materials describe this move toward more mod-based built-ins.

cc-plugin-you-should-know is a built-in side-agent warden mod, disabled by default. It can be enabled with /plugin enable cc-plugin-you-should-know@builtin; its first-party sessions have telemetry on, per the built-in mods documentation. Anthropic states more built-ins will move to mods over time, per the launch announcement, so teams should treat the built-in set as configurable architecture rather than an immutable core.

For harness architects, this makes the extension stack a deployment artifact. Pin and review mod source, define load order, establish enterprise defaults, and decide which built-ins belong in each environment. The agents-md mod also makes instruction files part of that extension story; compare it with AGENTS.md as an engineering contract.

Choose the narrowest surface that fits

For a harness team porting internal tooling onto agents, choose by the required control point: settings hooks for external event automation, skills for reusable instructions, MCP servers for external tools and resources, and mods when the requirement depends on in-process UI or runtime interception. The skills review is useful context for the instruction-layer option.

The sample mods show the kinds of artifacts this surface enables. In the Claude Code Playground mods repository, token-weather draws a context-forecast band above the prompt. That makes context-window management visible at the point of work, an approach related to context-window management.

blast-radius holds rm -rf and force-push actions, shows diffs, and offers proceed or cancel choices. replay-theater adds /replay to step through file edits from the last turn. These examples illustrate distinct uses: context visibility, high-impact action review, and interaction replay. They are provided as-is without support, so teams should inspect and adapt them rather than treat them as maintained dependencies.

The practical decision is whether the requirement truly needs to alter Claude Code itself. If a hook, skill, or MCP server is sufficient, its smaller authority and simpler operational boundary are advantages. Use a mod when those surfaces cannot deliver the needed interaction or interception, and pair that power with source review, validation, load-order policy, and an explicit owner.

The Bottom Line

Claude Mods make Claude Code extensible at the point where its UI, events, and tool execution meet. That is a substantial harness capability, but also a process-level trust grant: mods are not sandboxed and can act with the user’s permissions. Treat each mod as privileged runtime code, not merely as a plugin package.

The architectural upside is composability: teams can layer policy, custom operator interfaces, and workflow behavior without making every feature part of the core. The tradeoff is that load order, review, and disable semantics now belong in production design. Start with the narrowest surface, and reserve mods for requirements that need their stronger control.

FAQ

Claude Mods introduce an in-process extension surface, but the right choice depends on the required capability and trust boundary. These answers summarize the key distinctions for teams designing production agent harnesses, based on the official mods documentation and related launch material.

Are Claude Mods sandboxed?

No. A loaded mod runs with your permissions and can access files, environment variables, settings, prompts, tool calls, and network requests. Bash sandboxing does not contain a process started by a mod. The sandboxing documentation and security guidance describe this boundary.

Can a mod bypass a permission deny rule?

Yes. A mod can approve tool calls before the user is asked, per the mods overview documentation, including calls a deny rule refuses per the permissions documentation. Managed sec-default configuration is intended to prevent user-installed mods from overriding deny rules, but its load-order protection is conditional on the managed setup and its restrictions.

When should a team choose a mod over an MCP server?

Choose an MCP server when the requirement is to expose external tools or resources. Choose a mod when the requirement needs in-process UI, interception, or host behavior changes that a server cannot provide. If a hook, skill, or MCP server already meets the need, Anthropic’s mods guidance recommends that narrower option.

📖 Related Reads

• ToolBrain — tool reviews, LLM comparisons, and AI workflow guides
• Hermes Tutorials — Hermes Agent setup, configuration, and advanced workflows

Cross-links automatically generated from CodeIntel Log.