Claude Code plugins: what they contain and what Mods change

The official plugin architecture packages reusable customizations into one installable unit. It does not define a plugin as simply an MCP server, and a plugin is not an IDE extension.

• Skills: instructions and supporting files for a repeatable workflow, typically a SKILL.md. See Claude Skills.
• MCP servers: tools and external data connections. A plugin can bundle their configuration without being identical to the server.
• Agents: specialized subagent definitions with their own instructions and configuration.
• Commands: explicit slash-command entrypoints; existing command files remain a supported plugin component.
• Settings hooks: event-triggered shell, HTTP or prompt-based behavior using the documented hook configuration.
• Mods: JavaScript or TypeScript event handlers running inside the Claude Code session, with deeper behavioral and UI access.

A marketplace is the discovery and distribution layer. Adding a marketplace does not install every package in it. MCP and agent skills explains the tool/instruction distinction; this page owns the Claude Code package and runtime.

In an interactive session, open /plugin and use Discover. The official marketplace is added on the first interactive terminal session. Review the author, component list, configuration and permission implications before choosing a scope. Installation documentation.

In-session /plugin install NAME@MARKETPLACE opens the plugin details so you can review and choose the scope. It is not the same interaction as a shell installation command. These are shell command shapes; replace the uppercase placeholders with a verified package and marketplace:

claude plugin marketplace add OWNER/REPOSITORY
claude plugin install NAME@MARKETPLACE --scope user
claude plugin list

User scope applies to your projects on this machine. Project scope shares the project configuration with collaborators. Local scope applies only to you in this project. Choose deliberately before committing a project configuration.

Read the installation summary for active components, missing configuration, reload instructions and errors. Shell-side changes to an open session can require /reload-plugins. Verify the installed version, scope and status with the list command, then test the intended component. An installed MCP configuration may still need authentication; a successful package install alone does not prove a working tool.

2.1.292 marketplace shortcut: claude plugin install NAME --marketplace SOURCE adds a missing marketplace under the same policy checks as marketplace add, then installs the plugin from that source. It does not bypass organization policy. Review SOURCE before running it. Release note.

The component reference and Mod API reference define the relevant files. This is an illustrative combined layout, not a package we built or ran:

example-plugin/
  .claude-plugin/
    plugin.json
  skills/example/SKILL.md
  commands/example.md
  agents/example.md
  hooks/
    hooks.json
    register.js
  .mcp.json

The manifest belongs in .claude-plugin/plugin.json. Skills, commands, agents, hooks and the MCP file belong at their documented component paths, outside that manifest folder. Include only components your plugin actually needs; a Skill does not require an MCP server.

For a Mod, hooks/hooks.json declares a modules array. The module path is relative to hooks.json:

{ "modules": ["./register.js"] }

The module exports register(on, options) and registers callbacks with on(event, matcher?, hook). A callback receives ($, e, next): use the documented $ APIs, inspect the event, and call next(e) to delegate. Event objects are deeply frozen; construct a replacement to change a supported event. This is an API map, not a complete runnable Mod.

The formal Mod overview documents observing, changing or taking over session events. Examples include intercepting a tool call, rewriting a prompt, supplying a tool response, routing a request to another model, registering commands or tools, and sharing state. UI hooks can draw panes, bands and controls or replace supported built-in rows and dialogs. Mods cannot redraw the permission prompt.

Mod hooks load on supported sessions that load the plugin. Custom visuals are supported in the terminal and Desktop Code surfaces. The VS Code chat panel, print mode/Agent SDK and cloud sessions do not gain those visuals just because hooks load; cloud behavior also depends on the plugin reaching the environment. Remote Control hooks run on the local machine, with visuals in its local terminal. Consult the surface table before choosing a UI feature.

The tutorial introduces events such as tool.call, prompt, turn, command and ui.render. Generated .claude-plugin/types describe the API for the installed build and take precedence over potentially newer online examples. Do not infer an entrypoint, event payload or manifest field from the changelog alone.

Mods are supported from 2.1.287 and enabled by default as a capability. That does not mean every available Mod is installed or enabled. Public-directory acceptance of custom Mods is not established by the reviewed tutorial; do not treat creating a Mod as proof it can already be submitted.

2.1.287 is the Mods launch milestone. Version 2.1.288 adds follow-on Mod and MCP workflow features; 2.1.289 updates agent events and closes specific security and reliability defects. This is a plugin-focused update, not a complete Claude Code release digest. Official changelog.

For 2.1.288, $.ui.selection() returns the last text selected in fullscreen mode and also the transcript row when the selection stays within one row. This does not establish selection support in every client. The current reference lists the method, but the repository type file reviewed here does not declare it; use your installed build’s generated types before writing a return-value destructuring expression. Mod reference.

The 2.1.287 built-in You should know remains a separate opt-in: /plugin enable cc-plugin-you-should-know@builtin, with first-party sessions and telemetry enabled as stated in its launch note. Updating Claude Code is not the same as enabling that plugin.

The earlier 2.1.288 and 2.1.289 changes remain relevant:

2.1.292, reviewed October 7: that release adds prompt.autocomplete so Mods can contribute rows to the prompt autocomplete list; prompt/system text blocks with cache: true in $.model.complete; and workflow-agent run and index context in agent.spawn, allowing a Mod to refuse the spawn. These are release-note claims, not runtime tests.

Exact-contract gap as of October 7: the reviewed public mods/types/claude-code.d.ts and Mod reference still omit prompt.autocomplete; ModelCompleteRequest still declares prompt: string and system?: string; the published spawn input does not expose the new workflow run/index contract. We therefore do not invent autocomplete input/output types, cache block schemas, cache pricing/TTL or workflow-field types. Inspect the generated types for your installed build before implementing these features. Refusing a spawn is not control over every workflow behavior.

Adjacent agent change—not a plugin API: the Agent tool gains an effort parameter in 2.1.292. This is a general Claude Code subagent capability, not a new Mod method. Official release.

2.1.296, checked October 10: workflow model selection. CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL selects one model for workflow agents while other subagents keep their models. This is a workflow-specific override, not the first release to support choosing a subagent model. The release note does not specify its precedence against the separate force override; do not infer that interaction. Official release.

For ordinary subagents, the documented model order is the per-invocation model, then the definition's model, then the default CLAUDE_CODE_SUBAGENT_MODEL, then inheritance from the main conversation. A Mod's agent.spawn model rewrite replaces the per-invocation choice. Explicit inherit has its documented inheritance behavior; the global default alone does not replace the built-in Explore/Plan models.

Keep three other controls separate: CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 forces the global model when set, rather than acting as another default; organization availableModels restrictions still constrain model selection and may substitute an allowed model; effort controls supported reasoning effort, not model identity. Force-only and special subagent exceptions are documented separately, so this is not a promise that every agent always uses one model. Check the requested and actual model in the session.

Earlier compaction: autoCompactWindow can now be set in subagent frontmatter or --agents definitions to compact before the main conversation's window. The release note does not establish a numeric range here; no unverified configuration value is supplied.

Plugin reliability fixes worth checking after an upgrade:

• Managed PreToolUse with continue: false and blocking managed prompt hooks now address the case where the tool was refused but the turn did not end.
• Managed PostToolUse updates to MCP output apply in the affected sessions; disabled project MCP servers no longer start incorrectly after a directory change or plugin reload in headless mode.
• Workflow results/options avoid the reported deep-nesting truncation, and plugin-served $ methods use the calling agent's working directory and held hook turn.
• Windows plugin installation can retry owner/repo shortcuts over HTTPS when SSH is unavailable; PowerShell allow rules/read-only checks now cover commands up to 32 KB instead of repeatedly asking above about 1 KB.

These are release-note fixes, not tests performed here. Mods remain trusted executable code, not sandboxed extensions.

The 2.1.290 release adds plugin observability and approval context:

• turn.step → serverToolUses: records calls executed by the API/advisor itself, with the documented id, name, input, start and end information. Keep these distinct from client-executed tool calls; the release does not establish additional fields here.
• tool.check → agentId: identifies a subagent's permission check versus the main session's context.
• tool.check question/verdict → ceiling: exposes the approval required by the organization. This reports a managed approval boundary, not permission for a Mod to override it.
• ThemeKey / Color: typing support helps editors identify theme colors a Mod's UI can use.
• claude plugin validate --json → gatingHooks: reports registrations at gating sites and whether each has a .catch handler. Coverage information is not runtime safety certification.

Release notes and public types are not synchronized. The current repository declarations reviewed on October 6, including the v2.1.291 copy, still lack serverToolUses on TurnStepResult, ThemeKey, and the new tool.check fields. The reference and validation guide also do not yet spell out the complete new contract. Exact ceiling value types and the start/end representation are therefore UNKNOWN in the reviewed public declarations. Use the generated types from your installed build before implementing these fields; this guide does not invent a combined signature.

Existing managed permission precedence still applies. Mods remain trusted executable code, not sandboxed extensions. Added context and validation do not change that trust model.

2.1.291 is a reliability follow-up. Its two release notes fix lost answers to cloud-session permission prompts introduced in 2.1.290, and lost final session messages on quit introduced in 2.1.288. Neither note introduces a new Mod API. This is source review, not a test of either regression.

The current reference says the agent.spawn event covers a subagent or teammate about to start, with e.isTeammate for the teammate case. The 2.1.289 release also names one agent ID across plugin hook events and idle / waiting states in $.agent.list(). Treat those states as observations, not completed answers.

Repository type boundary. In the current type definitions, AgentSpawnArgs requires prompt; optional caller fields are description, subagentType, model, name and cwd. The resolved AgentSpawnInput is a different shape: a hook may rewrite prompt, description, subagentType, model, background and cwd. Identity/context fields tool_use_id, name, fork, parentModel, permissionMode, parentAgentId and provider are pinned. In this type, provider identifies the agent definition’s origin, not an arbitrary model-provider switch.

The same repository file has no isTeammate field in AgentSpawnInput, while the reference documents it; AgentInfo.status remains a string rather than a closed state union. Do not invent a combined signature. Check the generated .claude-plugin/types for the build you run; teammate-specific callable fields beyond the reviewed declarations remain UNKNOWN here.

Dispatch and completion. $.agent.spawn delegates through the spawn hooks (skipping the calling hook) into the Agent tool. Its call starts background work and resolves with the started agent identity or a denial; the answer arrives through turn.complete. Match that answer to the saved agentId. Matchers filter event fields, and next(e) delegates; they do not grant permission. Event semantics.

Runtime limits still apply. A subagent type must resolve to an available definition. An unspecified cwd uses the parent’s directory. The type describes model fallback to the agent’s model, then the parent’s; forks inherit the parent model. The engine can force background behavior on or off. Agent teams remain experimental and require CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1; teammate model selection, organization model restrictions and permission inheritance have their own documented rules. No unconditional or unlimited agent spawning is established by these APIs.

The MCP documentation describes URL-mode elicitation: the server can request that the user open a URL, such as a sign-in page; Claude opens it after the user accepts. The current document also describes form and URL capability negotiation for newer protocol versions. A URL prompt is not proof that authentication completed.

The 2.1.287 changelog says that if a server no longer connects, its MCP configuration entry can use "bareElicitationCapability": true. We did not find a formal explanation of that option in the reviewed MCP documentation. Its exact wire-format/downgrade semantics are UNKNOWN in those documents. This page therefore records the release-note workaround without inventing a full configuration recipe or recommending it for every server. Check your server’s compatibility and retest connection and sign-in separately.

2.1.288 follow-on: when a tool call needs additional OAuth scopes, Claude Code offers re-authentication. When a URL-prompt server cannot report completion, the client waits for the user’s “I’m done, continue” action. Neither control is evidence that the requested scope was granted or the tool succeeded; inspect the connection and the actual tool result. Release details.

The formal security section explicitly says Mods are not sandboxed. A Mod can read or write files accessible to your OS user, access environment secrets and settings, inspect session content, rewrite prompts and tool calls, and initiate actions. Processes it starts are not isolated by the Claude Bash sandbox. The tutorial’s runtime description is not a filesystem or permission guarantee.

Mods remain trusted executable plugin code. The current permission rules still allow some Mod approvals to replace ask decisions or non-managed hook blocks. Deny rules hold over user-installed Mods by default on managed machines and Team/Enterprise sessions, subject to organization policy; the documentation describes different behavior elsewhere. Managed PreToolUse blocks remain final. Review the module and dependencies rather than relying on prompts to contain untrusted code.

Specific 2.1.289 fixes: nested deny/ask rules in compound shell commands now hold over user-installed Mod approval on managed machines; Bash rules no longer miss commands behind expanded environment-variable prefixes or bare assignments under sandbox auto-allow. User-installed plugins can no longer rewrite managed MCP sign-in tool descriptions. Read-denied files arriving through symlinked IDE context are also covered by the fix. These are targeted bypass/precedence corrections, not a claim that every Mod is safe or every approval is forbidden. Official security fixes.

claude plugin validate ./example-plugin can report registered hooks and API usage without running the Mod. Validation helps inspection; it is not proof the code is safe. Review any bundled MCP endpoint and credential needs separately using the MCP security checklist.

Disable an installed Mod through its plugin controls. --safe-mode disables installed Mods and customizations for one session. The user setting disableAllHooks: true stops installed Mods, settings hooks and the status line, while managed organization customizations can continue. Managed allowManagedModsOnly can stop non-managed modules while other components of their plugins still load. Do not recommend the old CLAUDE_CODE_ENABLE_FUNCTION_HOOKS switch for 2.1.287; it is ignored.

Built-in plugins appear under Installed → Built-in and have different management limits: they cannot be updated or uninstalled like downloaded packages. Check whether the specific built-in component offers a disable control.

2.1.292 security maintenance: the release closes UNC-read permission prompt bypasses involving PreToolUse approvals/auto mode, updates managed sandbox read-deny handling and covered-file credential injection, and fixes swapped-link notebook/PDF reads outside the approved file. It also addresses tampering with cached managed settings that could displace the policy plugin; plugin commands now wait for managed settings on first run. MCP tools whose names exceed 128 characters are omitted with an error identifying the tool rather than breaking every request. Related Mod fixes preserve permission hooks during worker restarts and reject interrupted failing hooks. These changes do not sandbox Mods: they remain trusted executable plugin code. Release details.

Use a disposable project and a narrowly chosen plugin. Confirm version, scope, loaded components, required credentials and the actual output of the intended workflow. If a Mod’s UI is absent, check the supported surface and generated API types before changing code. If an MCP connection fails, inspect its authentication and protocol compatibility separately from the plugin install.

For this editorial update we did not install 2.1.296, exercise marketplace shortcut installation, prompt.autocomplete or model prompt caching, install or build a Mod, enable You should know, call agent.spawn, inspect a live $.agent.list(), exercise MCP re-authentication, or test permission precedence. This is SOURCE_CHECKED_ONLY, not a hands-on validation of the release. For a catalog comparison rather than plugin internals, see Claude Code extensions.