hmbown--codewhale/docs/PLUGIN_BUNDLES.md

Plugin bundles

Codewhale supports a deliberately small plugin-bundle boundary. The boundary was drawn in v0.9.1 and is unchanged in shape as of v0.9.6: a bundle may contribute declarative Skills and MCP server configuration through Codewhale's existing engines, and nothing else activates. Discovery alone never executes, enables, trusts, downloads, updates, or installs anything.

This document owns the bundle format (both manifest encodings), discovery, validation, and the trust/enable/runtime contract. PLUGINS.md owns how bits get onto and off disk — the /plugin install, update, uninstall, and suggest on-ramp added in v0.9.4 (#5182). Claude Code plugin repositories are a different, unconverted format; that boundary is CLAUDE_PLUGIN_COMPAT.md.

Discovery and precedence

Codewhale scans only its own roots, looking in each <name>/ directory for a manifest named plugin.json (the native Agent Plugins v1.0.0 format, since v0.9.4) or plugin.toml (the legacy Codewhale format, still fully readable):

• User: ~/.codewhale/plugins/<name>/
• Workspace: <workspace>/.codewhale/plugins/<name>/

A bundle that dual-publishes both manifests is read through its plugin.json. No built-in bundle ships as of v0.9.6. The internal precedence order is built-in, user, then workspace; the first bundle with a given name wins. This prevents a repository from shadowing an explicitly installed user bundle. Symbolic-link roots, manifests, component paths, and nested component files fail closed.

New user and workspace bundles are always untrusted and disabled. Discovery is read-only and does not inspect any other application's extension or credential directories: ambient roots such as .claude/plugins or .cursor/plugins are never scanned.

Pre-v0.9.1 overrides.json enablement was intentionally not imported as trust; every bundle activates only through the v1 content and capability review below.

Manifest

Both encodings parse into the same internal manifest, so validation, hashing, review, and runtime behavior are identical downstream. On-disk auto-migration between them is deliberately not performed; /plugin export <name> <target-dir> publishes a loaded bundle as a spec-valid Agent Plugins v1.0.0 directory without modifying the installed one.

plugin.json (Agent Plugins v1.0.0)

The standard's manifest root is closed: $schema, name, and the optional well-known fields (version, description, author, homepage, repository, license, keywords, extensions). An unknown root key is a parse error. Client-specific data lives under extensions, keyed by reverse-domain namespace: unknown vendor namespaces are ignored, never rejected — that is what lets a bundle authored for another client load here — while unknown keys inside Codewhale's own extensions["net.codewhale"] namespace are rejected rather than silently dropped.

Names follow the standard's rule: 1–64 lowercase ASCII letters, digits, or internal single -/., starting and ending alphanumeric, never -- or ... A skills/ directory in the bundle root is picked up automatically; other component locations, capabilities, when, and display_name ride in extensions["net.codewhale"].

MCP servers cannot live in plugin.json (the root is closed); they live in a sibling mcp.json under mcpServers, with stdio, streamable-http, or sse transports (type may be omitted and is inferred from command vs url). Codewhale-only server options — timeouts, tool filters, env-backed credentials, enablement — ride per-server under extensions["net.codewhale"]. The env names PLUGIN_ROOT and PLUGIN_DATA are reserved by the standard for the host runtime and are rejected in plugin definitions.

plugin.toml (legacy Codewhale format)

schema_version = 1

[plugin]
name = "example"
version = "0.1.0"
description = "Example instruction and MCP bundle"
author = "Example Author"

[skills]
path = "skills"

[mcp_servers.local]
command = "node"
args = ["server.js"]
cwd = "mcp"

[mcp_servers.remote]
url = "https://example.invalid/mcp"

[capabilities]
network_hosts = ["example.invalid"]

[when]
os = ["macos", "linux", "windows"]
binaries = ["node"]

Legacy TOML names are 1–64 lowercase ASCII letters, digits, or internal hyphens. A pre-versioned manifest without schema_version still parses, with a migration warning from /plugin validate (and 0.0.0 displayed when [plugin].version is missing). An unknown top-level table or field is a parse error (deny_unknown_fields), reported by byte offset without echoing manifest values.

Validation (both formats)

Component paths must be relative, contained, present, and free of symbolic links or Windows reparse points (including junctions and mount points). The v1 schema rejects unknown MCP fields, ambiguous local/remote transport combinations, unbounded lists/timeouts, and overlapping tool filters.

Remote MCP URLs must use HTTPS, except for explicit loopback HTTP endpoints. They cannot contain user information, a query, or a fragment. Literal headers are rejected: authentication must name a source environment variable through env_headers or bearer_token_env_var. A remote bundle must declare exactly the normalized host set used by its endpoints in capabilities.network_hosts; endpoint scheme, normalized host, port, and path remain bound to the review. Redirects are limited and must retain that exact normalized origin. Reviewed remote transports use an explicit no-proxy HTTP client: plugin bundles never read or use ambient HTTP_PROXY, HTTPS_PROXY, or NO_PROXY values, because proxy credentials and proxy observation are outside the reviewed authority. User-authored MCP configuration keeps its existing explicit proxy support.

Local stdio environment entries must use exact ${SOURCE_ENV} references. The review shows destination and source names, but never reads or prints their values. Plugin children inherit only Codewhale's base secret-scrubbed child environment plus those reviewed mappings; credential-capable proxy variables and the broader compatibility environment used by user-authored MCP configuration are not inherited ambiently. Absolute arguments and parent traversal are rejected; contained bundle entrypoints are frozen to their staged paths before spawn.

Every stdio argument is shown losslessly as a JSON string during review. Common credential-bearing flags and known literal token shapes are rejected from argv; credentials must instead use a reviewed environment mapping. Plugin-contributed MCP OAuth has been disabled since v0.9.1 and remains disabled as of v0.9.6, including discovery, login, refresh, and token storage; a manifest declaring OAuth fields on a plugin MCP server fails validation.

Active and inactive component surfaces

[skills] and [mcp_servers.*] are the only active component adapters as of v0.9.6. The manifest can additionally inventory the following future surfaces, but a bundle declaring any of them cannot be enabled yet:

[commands]
path = "commands"

[agents]        # TOML alias: [profiles]
path = "agents"

[hooks]
path = "hooks"

[lsp]           # TOML alias: [lsp_servers]
path = "lsp"

[native]        # TOML alias: [native_extension]
path = "native"

[capabilities]
filesystem_roots = ["workspace"]
network_hosts = ["api.example.invalid"]
lifecycle_mutation = true

(In a plugin.json bundle the same tables ride under extensions["net.codewhale"].)

The accept/reject behavior is deliberately loud, never silent:

• A recognized-but-inactive declaration (commands, agents, hooks, lsp, native, a non-empty capabilities.filesystem_roots, or capabilities.lifecycle_mutation = true) parses and is validated like any component (contained, present, link-free). It is counted in the inventory, shown in the review as an inactive declaration, and blocks activation: /plugin enable fails closed with an error naming each inactive surface (the error text still says "v0.9.1-inactive capabilities"; the behavior is unchanged), and such a bundle is never treated as active at runtime.
• An unrecognized section or field is a validation failure, not an inventory entry: unknown top-level TOML tables, unknown MCP server fields, unknown plugin.json root keys, and unknown keys inside extensions["net.codewhale"] are all rejected outright. The single ignore-without-error case is another vendor's extensions namespace in the Agent Plugins format, which the standard requires clients to skip.
• capabilities.network_hosts is not a future surface: it is enforced today, and must exactly match the normalized host set of the bundle's remote MCP endpoints (so it cannot be declared without them, or omitted with them).

A successful environment or health check is never treated as trust.

Review, trust, and enablement

Use the in-session command surface:

/plugin list
/plugin validate example
/plugin show example
/plugin enable example

The first enable opens a review showing source, component inventory, requested permissions, sanitized MCP endpoints, full content and capability hashes, and inactive declarations. It also prints an exact confirmation:

/plugin trust example <full-content-sha256>.<full-capability-sha256>

Run that exact command only after reviewing the bundle. The confirmation token uses both complete SHA-256 receipts rather than display prefixes. Trust first copies the complete reviewed tree into a Codewhale-owned, content-addressed runtime snapshot and records the matching receipt; it does not activate anything. Then run /plugin enable example again. Trust and enablement are separate:

• /plugin disable example stops contribution while preserving trust.
• /plugin revoke example removes trust while preserving the enablement bit; the bundle remains inactive until reviewed again.
• /plugin reload rebuilds the current workspace registry when files have changed on disk.

(/plugin install, update, and uninstall place, replace, and remove the bits themselves and always drop into this same review — see PLUGINS.md. /plugin suggest only ranks what is already installed.)

Trust, enable, disable, revoke, and reload rebuild the current workspace's Skill catalogue and MCP pool immediately. Each persisted transition advances a per-bundle generation under a stable cross-process lock. A generation change cancels in-flight MCP work, removes cached catalog entries, terminates an idle plugin stdio child, and denies persisted queued Skills carrying the older authority receipt.

The review distinguishes remote MCP endpoints from local stdio MCP servers. A local stdio server is a child process running with the Codewhale user's host filesystem and network authority; plugin trust is not an OS sandbox. The review therefore shows the command, argument count, working directory, environment-variable names, and this host-authority warning without printing environment or header values. MCP tool approval still applies after the server starts.

Trust receipts live in ~/.codewhale/plugins/state.json. Atomic owner-only writes record the full content hash, capability hash, reviewed capability inventory, generation, and review time, with the latest 32 reviews retained as a bounded audit trail. Malformed or unsupported state is not overwritten: all bundles fail closed until the state file is repaired or moved.

The content hash covers the manifest, complete bundle tree, and executable shape in deterministic path order, including local MCP entrypoints and companion assets. Staging is bounded, rejects symbolic links and unsupported file kinds (plus every Windows reparse point and hard-linked files), uses an atomic destination swap, and applies owner-only runtime permissions or ACLs through validated object handles on Windows. The capability hash covers the normalized component and permission inventory. A source or staged-content edit, capability change, or unsafe runtime-root replacement invalidates the receipt deterministically; an already-enabled bundle becomes inactive until it is reviewed again. This is the same invalidation /plugin update relies on: replaced bytes stop matching the receipt, forcing re-review.

Runtime behavior

An active bundle must be enabled, trusted for its current hashes, applicable to the host, free of validation errors, and limited to supported component kinds.

• Skills are exposed only as <plugin>:<skill>. The model-facing catalogue and load_skill use an in-memory snapshot bound to the reviewed staged tree, rather than reading a mutable source path at execution time. load_skill revalidates source, stage, receipt, workspace, and generation immediately before releasing content and fails closed on drift. Queued messages persist the same provenance and repeat that check at dispatch. /skills inspect identifies the reviewed bundle without exposing its mutable source path.
• MCP server names are exposed as plugin-<plugin-name-byte-length>-<plugin>-<server> so hyphens in either component cannot create an authority collision. Disabled or untrusted bundles are denied again at the headless MCP adapter. Authority is checked before connection, immediately before every lazy stdio spawn, after transport construction, and before each tool/resource/prompt operation. Persisted generation/enablement/trust state is also watched while an operation is in flight, so disable, revoke, or another cross-process state transition cancels the operation and terminates a plugin stdio child. Full source and staged-tree hashes are revalidated at dispatch/catalogue boundaries; the runtime does not continuously re-hash those trees during an already-running MCP call. Source or stage drift therefore fails the next boundary and drops the stale connection/catalogue entry, but is not claimed to interrupt a call already executing. Every failure includes instructions to reload, review, trust, and enable the bundle again.
• Plain launch, resume, fork, exec, and serve each construct an immutable workspace-scoped registry before constructing their Skill or MCP catalogue.
• Constitution, repository instructions, permission rules, sandbox policy, and MCP tool approval continue to outrank plugin instructions.

/plugin list, show, suggest, and validate perform no network requests, process launches, credential reads, or configuration writes. Reviews render structural argv as lossless JSON strings and environment provenance without values. Credential-bearing argv is rejected at manifest validation; plugin-originated errors suppress URL query, authentication, argv, and environment material. Legacy executable tools under [tools].plugin_dir remain a distinct system and are listed under /plugin tools.

Explicit non-goals as of v0.9.6

There is no remote marketplace or registry index (/plugin install fetches one reviewed source, and /plugin suggest ranks only what is already installed), no ambient compatibility discovery, no automatic trust, no plugin-contributed MCP OAuth, no hook adapter, command adapter, agent adapter, LSP adapter, native extension runtime, or MCP subscription adapter, no migration of another application's bundle, and no on-disk auto-migration of a legacy plugin.toml to plugin.json. These remain later work rather than implied capabilities.