@edspencer/paddock 0.62.0 → 0.63.0

package/packages/server/dist/claude-plugins.js

@@ -0,0 +1,394 @@
+/**
+ * Host Claude Code **plugins**, handed to each keeper as `agent.plugins` (#700).
+ *
+ * The half of MCP inheritance that `claude-mcp.ts` structurally could not reach.
+ * A plugin bundles commands, agents, skills, hooks and — the reported symptom —
+ * MCP servers, and none of it is declared in `~/.claude.json`, so reading that
+ * file finds nothing however carefully it is read.
+ *
+ * ## Why the symlink was not enough
+ *
+ * `plugins/` IS bridged into paddock's home (under `claude.instructions: host`,
+ * see `claude-home.ts`) and the SDK really does auto-discover plugins under
+ * `join(CLAUDE_CONFIG_DIR, "plugins")` — two facts that together made this look
+ * fixed for months. It is not, because discovery of an *installed* plugin is
+ * driven by the `enabledPlugins` key, and `enabledPlugins` lives in the **user**
+ * settings source, which herdctl does not load: every agent with a working
+ * directory is invoked with `setting_sources: ["project"]`. So the plugin is
+ * found and then never enabled, silently.
+ *
+ * herdctl 5.32.0 (herdctl#446, closing herdctl#444) adds the channel this needs:
+ * an optional `plugins` array on the agent config, translated to the SDK's own
+ * `plugins` option and to `--plugin-dir` on the CLI runtime. A plugin passed that
+ * way is a *session* plugin, and — read out of the CLI bundle rather than
+ * assumed — a session plugin's enablement is
+ * `enabledPlugins[`${name}@inline`] ?? manifest.defaultEnabled !== false`, i.e.
+ * **enabled by default**, with no settings-source grant required. That is why the
+ * passthrough works where the symlink did not, and why herdctl#446 was right to
+ * refuse to widen `setting_sources` instead.
+ *
+ * ## Which lever gates this, which is NOT the one #700 assumes
+ *
+ * #700 (and the brief written from it) scope plugin enumeration to
+ * `claude.mcpServers: host`. That is half right, and shipping it that way would
+ * have punched a hole through a different lever:
+ *
+ * - `plugins/` is bridged by **`claude.instructions`**, alongside `CLAUDE.md`,
+ *   `agents/` and `commands/` — because most of a plugin IS instructions. Under
+ *   `instructions: own` paddock withdraws that symlink and prints a notice saying
+ *   the host's plugins are not loaded. Passing them anyway because a *different*
+ *   key says `host` would contradict a notice paddock itself emits.
+ * - the MCP servers inside a plugin are what `claude.mcpServers` is about.
+ *
+ * So both levers apply, to the two halves of a plugin, and the SDK has exactly
+ * the flag needed to split them: `skipMcpDiscovery` loads a plugin's
+ * skills/hooks/agents/commands but does NOT read its `.mcp.json` or manifest
+ * `mcpServers`. Hence {@link enumerateHostPlugins}:
+ *
+ * | `instructions` | `mcpServers` | result |
+ * |---|---|---|
+ * | `host` | `host` | plugins passed whole |
+ * | `host` | `own`  | plugins passed with `skipMcpDiscovery: true` |
+ * | `own`  | *any*  | no plugins, and a notice saying which key turns them on |
+ *
+ * ## The allowlist, which is where this gets uncomfortable
+ *
+ * Both runtimes auto-deny any tool missing from an explicit `allowed_tools`, with
+ * no prompt and nothing in the logs — the trap `claude-mcp.ts` documents at
+ * length. A plugin-provided MCP server needs the same widening, so paddock has to
+ * know its tool prefix *before* the plugin has ever run.
+ *
+ * It is knowable, from the CLI bundle: a plugin's servers are registered under
+ * `` `plugin:${pluginName}:${serverName}` ``, and a server name is normalised
+ * with `[^a-zA-Z0-9_-] → _` before it becomes a tool prefix. So the pattern is
+ * `mcp__plugin_<plugin>_<server>__*` — matching the SDK's own documented example,
+ * `mcp__plugin_documents_docs__doc_export`. {@link pluginMcpToolPattern} is that
+ * one line, and {@link readPluginServerNames} recovers `<server>` by reading the
+ * two places a plugin declares servers statically: `<dir>/.mcp.json` and an
+ * inline `mcpServers` object in `<dir>/.claude-plugin/plugin.json`.
+ *
+ * What it CANNOT recover is a manifest whose `mcpServers` is a string or an array
+ * of strings — a pointer to another file, or to an MCPB source the CLI downloads.
+ * Resolving a same-directory JSON pointer is easy and is done; anything else is
+ * recorded as a caveat and warned about at boot, naming the plugin, because the
+ * failure it produces otherwise is the silent one: the plugin loads, its server
+ * connects, and every tool call is denied with no log line. Better a warning that
+ * says "add `mcp__plugin_x_y__*` yourself" than a mystery.
+ *
+ * ## What is read, and what is not verified
+ *
+ * Enumeration is from `<pluginRoot>/installed_plugins.json`, the CLI's own
+ * registry of installs (v2: `{plugins: {"<name>@<marketplace>": [{installPath,
+ * scope, …}]}}`; v1 keyed the same ids to a single record, whose path was derived
+ * as `<pluginRoot>/cache/<marketplace>/<name>/<version>`). Both are read. The
+ * host's `settings.json` `enabledPlugins` is consulted only to VETO — an id set
+ * to `false` is skipped — because a session plugin's own default is "enabled",
+ * so honouring the veto is the only thing that can respect a host's `/plugin
+ * disable`.
+ *
+ * None of this was validated against a machine with plugins installed: this box
+ * is Linux with an empty plugin root, and no test here proves a plugin *loads*.
+ * Every path, file name and naming rule above comes from reading the bundled CLI
+ * (`node_modules/@anthropic-ai/claude-agent-sdk-linux-x64/claude`), and the tests
+ * assert what config paddock produces from a planted directory tree, which is a
+ * strictly weaker claim. A `marketplace`-installed plugin loading via
+ * `type: "local"` remains unverified end-to-end and needs a real host.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+/** Nothing inherited: `instructions: own`, and where tests start. */
+export const EMPTY_HOST_PLUGINS = Object.freeze({
+    plugins: [],
+    toolPatterns: [],
+    caveats: [],
+});
+/** The plugin root, `join(CLAUDE_CONFIG_DIR, "plugins")` in the CLI's terms. */
+export function hostPluginRoot(legacyClaudeHome) {
+    return path.join(legacyClaudeHome, "plugins");
+}
+/** The CLI's own registry of what is installed, under {@link hostPluginRoot}. */
+export const INSTALLED_PLUGINS_FILE = "installed_plugins.json";
+/** A plugin's manifest, relative to its directory. */
+export const PLUGIN_MANIFEST = path.join(".claude-plugin", "plugin.json");
+/** A plugin's out-of-manifest MCP declaration, relative to its directory. */
+export const PLUGIN_MCP_FILE = ".mcp.json";
+/**
+ * The CLI's server-name normalisation: `[^a-zA-Z0-9_-] → _`, applied to the whole
+ * `plugin:<plugin>:<server>` name before it becomes a `mcp__…__` prefix. Applied
+ * to the joined string, not to the parts, so a `.` in a plugin name normalises
+ * the same way the separators do.
+ */
+function normalizeServerName(name) {
+    return name.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+/**
+ * The allowlist pattern for one server of one plugin.
+ *
+ * Deliberately not `mcpToolPattern` from `claude-mcp.ts`: the name a plugin's
+ * server is registered under is not the name it is declared under, and that
+ * derivation is the whole content of this function.
+ */
+export function pluginMcpToolPattern(pluginName, serverName) {
+    return `mcp__${normalizeServerName(`plugin:${pluginName}:${serverName}`)}__*`;
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+async function readJson(file) {
+    try {
+        return JSON.parse(await fs.readFile(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The server names one `.mcp.json`-shaped document declares.
+ *
+ * Claude Code accepts both `{mcpServers: {…}}` and a bare map at the top level,
+ * so both are read — the CLI does `parsed.mcpServers || parsed`.
+ */
+function serverNamesOf(doc) {
+    if (!isRecord(doc))
+        return [];
+    const servers = isRecord(doc.mcpServers) ? doc.mcpServers : doc;
+    return Object.keys(servers).filter((k) => isRecord(servers[k]));
+}
+/**
+ * Read one plugin directory's declared MCP server names.
+ *
+ * Mirrors the CLI's own discovery order — `<dir>/.mcp.json` first, then whatever
+ * `manifest.mcpServers` adds — with the one deliberate gap described in the
+ * module doc: a manifest that points at an MCPB source (or at any path outside
+ * its own directory) is recorded in {@link PluginServerNames.unresolved} rather
+ * than fetched. Paddock does not download anything to build an allowlist.
+ */
+export async function readPluginServerNames(dir) {
+    const manifest = await readJson(path.join(dir, PLUGIN_MANIFEST));
+    const pluginName = isRecord(manifest) && typeof manifest.name === "string" && manifest.name.trim() !== ""
+        ? manifest.name.trim()
+        : path.basename(dir);
+    const servers = new Set(serverNamesOf(await readJson(path.join(dir, PLUGIN_MCP_FILE))));
+    const unresolved = [];
+    const declared = isRecord(manifest) ? manifest.mcpServers : undefined;
+    // A string entry is a path relative to the plugin directory (or an MCPB
+    // source, which looks the same and is not resolvable without downloading it).
+    // Resolve it only when it stays inside the directory and parses as JSON;
+    // anything else is a gap paddock reports rather than guesses at.
+    const resolveRef = async (ref) => {
+        const target = path.resolve(dir, ref);
+        if (target !== dir && !target.startsWith(dir + path.sep)) {
+            unresolved.push(ref);
+            return;
+        }
+        const names = serverNamesOf(await readJson(target));
+        if (names.length === 0)
+            unresolved.push(ref);
+        else
+            for (const n of names)
+                servers.add(n);
+    };
+    if (typeof declared === "string")
+        await resolveRef(declared);
+    else if (Array.isArray(declared)) {
+        for (const entry of declared) {
+            if (typeof entry === "string")
+                await resolveRef(entry);
+            else
+                for (const n of serverNamesOf(entry))
+                    servers.add(n);
+        }
+    }
+    else if (isRecord(declared)) {
+        for (const n of serverNamesOf(declared))
+            servers.add(n);
+    }
+    return { pluginName, servers: [...servers], unresolved };
+}
+/**
+ * Parse `installed_plugins.json`, v1 or v2. Pure, so the whole selection is
+ * testable from a string.
+ *
+ * v2 keys each `<name>@<marketplace>` id to an ARRAY of installations (one per
+ * scope), each carrying an explicit `installPath`. v1 keyed it to a single record
+ * with no path, which the CLI derives as
+ * `<root>/cache/<marketplace>/<name>/<version>` with each segment sanitised
+ * `[^a-zA-Z0-9\-_] → -` (and the version segment additionally allowing `.`).
+ *
+ * Fails soft in every direction: this is a file paddock does not own and must
+ * never turn into a boot failure.
+ */
+export function parseInstalledPlugins(raw, root) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!isRecord(parsed) || !isRecord(parsed.plugins))
+        return [];
+    const out = [];
+    for (const [id, entry] of Object.entries(parsed.plugins)) {
+        if (Array.isArray(entry)) {
+            for (const install of entry) {
+                if (isRecord(install) && typeof install.installPath === "string" && install.installPath) {
+                    out.push({ id, installPath: install.installPath });
+                }
+            }
+        }
+        else if (isRecord(entry)) {
+            const derived = legacyInstallPath(root, id, entry.version);
+            if (derived)
+                out.push({ id, installPath: derived });
+        }
+    }
+    return out;
+}
+/** The v1 path derivation, kept beside its only caller. */
+function legacyInstallPath(root, id, version) {
+    if (typeof version !== "string" || version === "")
+        return undefined;
+    const at = id.lastIndexOf("@");
+    const name = at > 0 ? id.slice(0, at) : id;
+    const marketplace = at > 0 ? id.slice(at + 1) : "unknown";
+    const seg = (s) => s.replace(/[^a-zA-Z0-9\-_]/g, "-");
+    let ver = version.replace(/[^a-zA-Z0-9\-_.]/g, "-");
+    if (ver === "." || ver === "..")
+        ver = "-";
+    return path.join(root, "cache", seg(marketplace || "unknown"), seg(name), ver);
+}
+/** Ids the host has explicitly turned off, from its `settings.json`. */
+function disabledIds(settings) {
+    const out = new Set();
+    if (!isRecord(settings) || !isRecord(settings.enabledPlugins))
+        return out;
+    for (const [id, value] of Object.entries(settings.enabledPlugins)) {
+        // Anything that is not an explicit `false` counts as enabled: the key also
+        // takes an extended object form carrying a version constraint, and a version
+        // constraint is not a disable.
+        if (value === false)
+            out.add(id.toLowerCase());
+    }
+    return out;
+}
+/**
+ * Enumerate the host's installed plugin directories. Pure apart from reading the
+ * plugin tree, and takes the two files' contents rather than paths so the whole
+ * selection is testable without a home directory.
+ */
+export async function enumerateHostPlugins(opts) {
+    const caveats = [];
+    if (opts.installed === undefined)
+        return { plugins: [], toolPatterns: [], caveats };
+    const disabled = disabledIds(opts.settings);
+    const plugins = [];
+    const toolPatterns = new Set();
+    // One plugin can be recorded under several scopes, and two ids can in principle
+    // resolve to one directory. `--plugin-dir` the same path twice and the CLI loads
+    // it twice under one name, so collapse them here.
+    const seen = new Set();
+    for (const install of parseInstalledPlugins(opts.installed, opts.root)) {
+        if (disabled.has(install.id.toLowerCase()))
+            continue;
+        if (seen.has(install.installPath))
+            continue;
+        seen.add(install.installPath);
+        // A registry entry whose directory is gone is the normal aftermath of a
+        // hand-deleted plugin. The SDK would log "Plugin path does not exist" and
+        // carry on, but saying it here is what makes an empty `plugins` explicable.
+        try {
+            if (!(await fs.stat(install.installPath)).isDirectory())
+                throw new Error("not a directory");
+        }
+        catch {
+            caveats.push({
+                name: install.id,
+                kind: "dropped",
+                reason: `its recorded install directory (${install.installPath}) is missing`,
+            });
+            continue;
+        }
+        plugins.push(opts.mcp
+            ? { type: "local", path: install.installPath }
+            : { type: "local", path: install.installPath, skipMcpDiscovery: true });
+        if (!opts.mcp)
+            continue;
+        const { pluginName, servers, unresolved } = await readPluginServerNames(install.installPath);
+        for (const server of servers)
+            toolPatterns.add(pluginMcpToolPattern(pluginName, server));
+        if (unresolved.length > 0) {
+            caveats.push({
+                name: install.id,
+                kind: "degraded",
+                reason: `its manifest points \`mcpServers\` at ${unresolved.join(", ")} rather than declaring ` +
+                    `them inline, so paddock cannot name its servers — the plugin is attached, but any ` +
+                    `tool it provides will be auto-denied with no prompt until you add the matching ` +
+                    `\`mcp__plugin_${normalizeServerName(pluginName)}_<server>__*\` to the keeper's ` +
+                    `allowed tools`,
+            });
+        }
+    }
+    return { plugins, toolPatterns: [...toolPatterns], caveats };
+}
+/**
+ * Read the host's plugin registry — once, at boot — and say what came of it.
+ *
+ * Under `instructions: own` nothing is opened at all, for the same reason
+ * `loadHostMcpSource` does not open `.claude.json` under `mcpServers: own`: "own
+ * everywhere means nothing outside the data dir is read" is a guarantee that has
+ * to be true in the place someone would check it.
+ */
+export async function loadHostPlugins(cfg) {
+    const notices = [];
+    const mcp = cfg.claude.mcpServers === "host";
+    if (cfg.claude.instructions !== "host") {
+        if (mcp) {
+            // The one combination that silently does less than a user asked for, so it
+            // is the one that gets a line naming the other key.
+            notices.push({
+                level: "info",
+                message: "`claude.mcpServers: host` does not reach MCP servers provided by a Claude Code " +
+                    "plugin: a plugin is mostly commands, agents and skills, so loading one is a " +
+                    "`claude.instructions` decision. Set `claude.instructions: host` (or " +
+                    "PADDOCK_CLAUDE_INSTRUCTIONS=host) as well to inherit your plugins.",
+            });
+        }
+        return { source: EMPTY_HOST_PLUGINS, notices };
+    }
+    const root = hostPluginRoot(cfg.legacyClaudeHome);
+    const file = path.join(root, INSTALLED_PLUGINS_FILE);
+    let installed;
+    try {
+        installed = await fs.readFile(file, "utf8");
+    }
+    catch {
+        // Not a warning: no plugins installed is the overwhelmingly common case, and
+        // this file does not exist until the first `claude plugin install`.
+        return { source: EMPTY_HOST_PLUGINS, notices };
+    }
+    const settings = await readJson(path.join(cfg.legacyClaudeHome, "settings.json"));
+    const source = await enumerateHostPlugins({ root, installed, settings, mcp });
+    if (source.plugins.length > 0) {
+        notices.push({
+            level: "info",
+            message: `Claude plugins: host (\`claude.instructions: host\`) — ${source.plugins.length} ` +
+                `installed plugin${source.plugins.length === 1 ? "" : "s"} attached to every keeper` +
+                (mcp
+                    ? source.toolPatterns.length > 0
+                        ? `, including their MCP servers (${source.toolPatterns.join(", ")})`
+                        : ", including their MCP servers (none declared)"
+                    : ". Their MCP servers are NOT attached (`claude.mcpServers: own`)") +
+                ".",
+        });
+    }
+    for (const caveat of source.caveats) {
+        notices.push({
+            level: "warn",
+            message: caveat.kind === "dropped"
+                ? `Claude plugin "${caveat.name}" was NOT attached: ${caveat.reason}.`
+                : `Claude plugin "${caveat.name}" is attached but incomplete: ${caveat.reason}.`,
+        });
+    }
+    return { source, notices };
+}

package/packages/server/dist/cli/args.d.ts

@@ -53,4 +53,4 @@ export declare function nodeVersionProblem(nodeVersion: string): string | undefi
  * flag that fixes it.
  */
 export declare function explainListenError(err: unknown, host: string, port: string): string;
-export declare const USAGE = "paddock \u2014 run a Paddock instance locally\n\nUsage\n  npx @edspencer/paddock [options]\n\nOptions\n  -p, --port <port>       HTTP/WS port (default 4000, or $PORT)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)\n      --here              Open the CURRENT directory as the workspace (see below)\n  -o, --open              Open the app in your browser once it is listening\n      --verbose           Show the server's own logs (quiet by default)\n  -v, --version           Print the Paddock version and exit\n  -h, --help              Show this help\n\nOpening a directory (--here)\n  Run `paddock --here` inside a project and Paddock opens THAT directory as its\n  workspace: Claude works in your files, and any Claude Code sessions you already\n  have for the directory are offered for import. It:\n\n    \u00B7 creates .paddock/ in the directory for this workspace's own state\n    \u00B7 creates .chats/ for transcripts, and adds both to .gitignore\n    \u00B7 offers your ~/.claude sessions for this directory for import \u2014 nothing\n      there is moved, copied or linked until you confirm\n\n  Once done, later runs in the same directory resume it \u2014 no flag needed.\n  Without --here, Paddock never touches the directory you ran it from.\n\nCredentials\n  Paddock drives Claude Code, so it needs Claude credentials \u2014 and if you\n  already use Claude Code on this machine, it uses the login you already have.\n  That is a macOS Keychain entry on a Mac, or your ~/.claude/.credentials.json\n  elsewhere (symlinked in, never copied). Reading a login writes nothing.\n\n  Otherwise: a CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY in the environment,\n  or a one-off `CLAUDE_CONFIG_DIR=<data-dir>/claude-home claude login`. With no\n  login at all anywhere, run `claude setup-token`. Paddock says at startup when\n  it can find none.\n\nSharing your Claude Code state\n  Apart from that login, Paddock writes nothing outside its data dir by\n  default: transcripts go to each project's .chats/, and your ~/.claude is read\n  for config only. Each thing it can share is one key in\n  <data-dir>/paddock.config.yaml:\n\n    claude:\n      transcripts: host   # own | host, default own\n      credentials: host   # own | host, default host\n      instructions: host  # own | host, default own\n      hooks: host         # own | host, default own\n\n  transcripts: host makes a chat and a `claude --resume` in the same directory\n  the same file, live in both directions; deleting such a chat in Paddock\n  releases it rather than removing it, because it is your history rather than\n  Paddock's copy. credentials: own is the opt-out from sharing the login above.\n\n  instructions: host loads your ~/.claude CLAUDE.md, agents/, commands/ and\n  plugins/. Off by default, which is a change: your curated CLAUDE.md does not\n  reach Paddock's agents unless you say so. Each project's own CLAUDE.md always\n  does.\n\n  hooks: host runs the shell commands your ~/.claude/settings.json binds to\n  tool use. Off by default \u2014 inheriting someone's hooks is not something to\n  discover after the fact. Its other keys (permissions, model, statusline)\n  apply either way: under hooks: own Paddock writes its own settings.json\n  carrying them with hooks dropped, regenerated at startup.\n\nYour data\n  Everything lives in one directory \u2014 ~/.paddock unless you pass --data-dir.\n  Projects, chat transcripts and settings all persist there between runs. Move\n  that directory to move your instance; delete it to start over. Nothing is\n  stored anywhere else.\n\nNotes\n  Binds loopback with authentication disabled, which is safe for a laptop. To\n  expose it on a network, set PADDOCK_AUTH_MODE first \u2014 Paddock refuses to bind\n  a routable interface wide open. See AUTH.md.\n\nDocs: https://github.com/edspencer/paddock";
+export declare const USAGE = "paddock \u2014 run a Paddock instance locally\n\nUsage\n  npx @edspencer/paddock [options]\n\nOptions\n  -p, --port <port>       HTTP/WS port (default 4000, or $PORT)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)\n      --here              Open the CURRENT directory as the workspace (see below)\n  -o, --open              Open the app in your browser once it is listening\n      --verbose           Show the server's own logs (quiet by default)\n  -v, --version           Print the Paddock version and exit\n  -h, --help              Show this help\n\nOpening a directory (--here)\n  Run `paddock --here` inside a project and Paddock opens THAT directory as its\n  workspace: Claude works in your files, and any Claude Code sessions you already\n  have for the directory are offered for import. It:\n\n    \u00B7 creates .paddock/ in the directory for this workspace's own state\n    \u00B7 creates .chats/ for transcripts, and adds both to .gitignore\n    \u00B7 offers your ~/.claude sessions for this directory for import \u2014 nothing\n      there is moved, copied or linked until you confirm\n\n  Once done, later runs in the same directory resume it \u2014 no flag needed.\n  Without --here, Paddock never touches the directory you ran it from.\n\nCredentials\n  Paddock drives Claude Code, so it needs Claude credentials \u2014 and if you\n  already use Claude Code on this machine, it uses the login you already have.\n  That is a macOS Keychain entry on a Mac, or your ~/.claude/.credentials.json\n  elsewhere (symlinked in, never copied). Reading a login writes nothing.\n\n  Otherwise: a CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY in the environment,\n  or a one-off `CLAUDE_CONFIG_DIR=<data-dir>/claude-home claude login`. With no\n  login at all anywhere, run `claude setup-token`. Paddock says at startup when\n  it can find none.\n\nSharing your Claude Code state\n  Apart from that login, Paddock writes nothing outside its data dir by\n  default: transcripts go to each project's .chats/, and your ~/.claude is read\n  for config only. Each thing it can share is one key in\n  <data-dir>/paddock.config.yaml:\n\n    claude:\n      transcripts: host   # own | host, default own\n      credentials: host   # own | host, default host\n      instructions: host  # own | host, default own\n      hooks: host         # own | host, default own\n      mcpServers: host    # own | host, default own\n\n  transcripts: host makes a chat and a `claude --resume` in the same directory\n  the same file, live in both directions; deleting such a chat in Paddock\n  releases it rather than removing it, because it is your history rather than\n  Paddock's copy. credentials: own is the opt-out from sharing the login above.\n\n  instructions: host loads your ~/.claude CLAUDE.md, agents/, commands/ and\n  plugins/. Off by default, which is a change: your curated CLAUDE.md does not\n  reach Paddock's agents unless you say so. Each project's own CLAUDE.md always\n  does.\n\n  hooks: host runs the shell commands your ~/.claude/settings.json binds to\n  tool use. Off by default \u2014 inheriting someone's hooks is not something to\n  discover after the fact. Its other keys (permissions, model, statusline)\n  apply either way: under hooks: own Paddock writes its own settings.json\n  carrying them with hooks dropped, regenerated at startup.\n\n  mcpServers: host attaches the MCP servers declared in your ~/.claude.json \u2014\n  the top-level ones, plus a project's own when its directory matches. To give\n  this instance a server your machine doesn't have, declare it instead in a\n  sibling mcpServers: block of the same file; use env:VAR_NAME anywhere a\n  string goes so tokens stay out of it. That keeps a token out of the file, not\n  out of `ps`: leave driveMode on its default (session) for a server holding\n  one, since batch passes the definition to claude as a command-line argument.\n\nYour data\n  Everything lives in one directory \u2014 ~/.paddock unless you pass --data-dir.\n  Projects, chat transcripts and settings all persist there between runs. Move\n  that directory to move your instance; delete it to start over. Nothing is\n  stored anywhere else.\n\nNotes\n  Binds loopback with authentication disabled, which is safe for a laptop. To\n  expose it on a network, set PADDOCK_AUTH_MODE first \u2014 Paddock refuses to bind\n  a routable interface wide open. See AUTH.md.\n\nDocs: https://github.com/edspencer/paddock";

package/packages/server/dist/cli/args.js

@@ -162,6 +162,7 @@ Sharing your Claude Code state
       credentials: host   # own | host, default host
       instructions: host  # own | host, default own
       hooks: host         # own | host, default own
+      mcpServers: host    # own | host, default own
 
   transcripts: host makes a chat and a \`claude --resume\` in the same directory
   the same file, live in both directions; deleting such a chat in Paddock
@@ -179,6 +180,14 @@ Sharing your Claude Code state
   apply either way: under hooks: own Paddock writes its own settings.json
   carrying them with hooks dropped, regenerated at startup.
 
+  mcpServers: host attaches the MCP servers declared in your ~/.claude.json —
+  the top-level ones, plus a project's own when its directory matches. To give
+  this instance a server your machine doesn't have, declare it instead in a
+  sibling mcpServers: block of the same file; use env:VAR_NAME anywhere a
+  string goes so tokens stay out of it. That keeps a token out of the file, not
+  out of \`ps\`: leave driveMode on its default (session) for a server holding
+  one, since batch passes the definition to claude as a command-line argument.
+
 Your data
   Everything lives in one directory — ~/.paddock unless you pass --data-dir.
   Projects, chat transcripts and settings all persist there between runs. Move

package/packages/server/dist/herdctl-agent-config.d.ts

@@ -1,6 +1,7 @@
 import type { PaddockConfig } from "./config.js";
 import type { Project } from "./projects.js";
 import { type McpSources } from "./claude-mcp.js";
+import { type HostPluginSource } from "./claude-plugins.js";
 import { type PaddockTrigger } from "./trigger-config.js";
 /**
  * A project's keeper agent config. Inherits the fleet `defaults` (runtime,
@@ -34,8 +35,13 @@ import { type PaddockTrigger } from "./trigger-config.js";
  * which is both the isolated mode and what every existing caller means. The
  * KEEPER is the only agent that gets them: the sweeper is tool-less and each
  * trigger declares its own narrow allowlist, so neither could call one anyway.
+ *
+ * `hostPlugins` is the same story for the host's Claude Code plugins (#700),
+ * resolved once at boot by `claude-plugins.ts` and gated by `claude.instructions`
+ * rather than `claude.mcpServers` — see that module for why. Keeper-only for the
+ * same reasons, and empty unless the lever is on.
  */
-export declare function buildAgentConfig(cfg: PaddockConfig, project: Project, modelOverride?: string, mcpSources?: McpSources): Record<string, unknown> & {
+export declare function buildAgentConfig(cfg: PaddockConfig, project: Project, modelOverride?: string, mcpSources?: McpSources, hostPlugins?: HostPluginSource): Record<string, unknown> & {
     name: string;
 };
 /**

package/packages/server/dist/herdctl-agent-config.js

@@ -14,6 +14,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import YAML from "yaml";
 import { EMPTY_MCP_SOURCES, mcpServersFor, mcpToolPattern, } from "./claude-mcp.js";
+import { EMPTY_HOST_PLUGINS } from "./claude-plugins.js";
 import { DEFAULT_MODEL, SWEEPER_DEFAULT_MODEL, DEFAULT_PERMISSION_MODE, DEFAULT_MAX_TURNS, } from "./models.js";
 import { triggerToAgentToolConfig, triggersToHerdctlSchedules, curatorTriggerOf, } from "./trigger-config.js";
 import { keeperAgentName, sweeperAgentName, triggerAgentName, browserMcpServers, FLEET_ALLOWED_TOOLS, DENIED_TOOLS, KEEPER_MAX_CONCURRENT, KEEPER_SESSION_TIMEOUT, } from "./herdctl-agent-names.js";
@@ -49,8 +50,13 @@ import { keeperAgentName, sweeperAgentName, triggerAgentName, browserMcpServers,
  * which is both the isolated mode and what every existing caller means. The
  * KEEPER is the only agent that gets them: the sweeper is tool-less and each
  * trigger declares its own narrow allowlist, so neither could call one anyway.
+ *
+ * `hostPlugins` is the same story for the host's Claude Code plugins (#700),
+ * resolved once at boot by `claude-plugins.ts` and gated by `claude.instructions`
+ * rather than `claude.mcpServers` — see that module for why. Keeper-only for the
+ * same reasons, and empty unless the lever is on.
  */
-export function buildAgentConfig(cfg, project, modelOverride, mcpSources = EMPTY_MCP_SOURCES) {
+export function buildAgentConfig(cfg, project, modelOverride, mcpSources = EMPTY_MCP_SOURCES, hostPlugins = EMPTY_HOST_PLUGINS) {
     const config = {
         name: keeperAgentName(project.slug),
         description: project.summary || `Claude Code agent for project ${project.name}.`,
@@ -142,9 +148,19 @@ export function buildAgentConfig(cfg, project, modelOverride, mcpSources = EMPTY
     // Patterns already on the defaults are filtered out, so nothing is restated
     // for an instance with no external servers (or one whose only server paddock's
     // own overrode above) — that config stays byte-identical to before this lever.
-    const extra = Object.keys(external)
-        .map(mcpToolPattern)
-        .filter((pattern) => !FLEET_ALLOWED_TOOLS.includes(pattern));
+    //
+    // The host's Claude Code PLUGINS ride on the same two mechanisms (#700, and the
+    // `plugins` passthrough herdctl 5.32.0 added for it). They are a separate key
+    // rather than more `mcp_servers` because a plugin is a directory the engine
+    // loads, not a server paddock can describe — but their servers land in the same
+    // tool namespace and need the same allowlist widening, under names paddock has
+    // to derive rather than read (`claude-plugins.ts`).
+    if (hostPlugins.plugins.length > 0)
+        config.plugins = hostPlugins.plugins;
+    const extra = [
+        ...Object.keys(external).map(mcpToolPattern),
+        ...hostPlugins.toolPatterns,
+    ].filter((pattern) => !FLEET_ALLOWED_TOOLS.includes(pattern));
     if (extra.length > 0)
         config.allowed_tools = [...FLEET_ALLOWED_TOOLS, ...extra];
     return config;

package/packages/server/dist/herdctl.d.ts

@@ -51,6 +51,7 @@ import type { PaddockConfig } from "./config.js";
 import type { Project } from "./projects.js";
 import { type PaddockTrigger } from "./trigger-config.js";
 import { type McpSources } from "./claude-mcp.js";
+import { type HostPluginSource } from "./claude-plugins.js";
 import { type AdoptableSummary, type FilterReason } from "./adoptable.js";
 /**
  * One session an import did NOT bring in, with a reason a UI can show verbatim.
@@ -121,6 +122,7 @@ export declare function sliceTranscriptAtUuid(raw: string, cutUuid: string, endO
 export declare class HerdctlService {
     private readonly cfg;
     private readonly mcpSources;
+    private readonly hostPlugins;
     private fleet;
     private started;
     /**
@@ -193,8 +195,12 @@ export declare class HerdctlService {
      * all under `mcpServers: own`. Defaults to empty so every existing caller —
      * including the several tests that construct this with `{} as PaddockConfig` —
      * keeps meaning "isolated".
+     *
+     * `hostPlugins` is the host's Claude Code plugins (#700), read at boot by
+     * `loadHostPlugins` under `claude.instructions: host`, and handed in for
+     * exactly the same reasons.
      */
-    constructor(cfg: PaddockConfig, mcpSources?: McpSources);
+    constructor(cfg: PaddockConfig, mcpSources?: McpSources, hostPlugins?: HostPluginSource);
     /**
      * The Claude home every transcript symlink is planted in, plus where those
      * symlinks point (#620, #691). One accessor, so no call site can quietly take

package/packages/server/dist/herdctl.js

@@ -57,6 +57,7 @@ import { ensureProjectChats, projectChatsDir } from "./transcripts.js";
 import { triggerRunsOnOwnAgent, isCuratorTrigger, } from "./trigger-config.js";
 import { buildAgentConfig, buildSweeperConfig, sweeperWorkingDir, buildTriggerConfig, ensureConfigFile as writeBootConfigFile, } from "./herdctl-agent-config.js";
 import { EMPTY_MCP_SOURCES } from "./claude-mcp.js";
+import { EMPTY_HOST_PLUGINS } from "./claude-plugins.js";
 import * as jobs from "./herdctl-jobs.js";
 import { JobsDirIndex } from "./herdctl-jobs-index.js";
 import { AdoptableIndex } from "./adoptable.js";
@@ -164,6 +165,7 @@ export function sliceTranscriptAtUuid(raw, cutUuid, endOnCompletedAssistant = fa
 export class HerdctlService {
     cfg;
     mcpSources;
+    hostPlugins;
     fleet = null;
     started = false;
     /**
@@ -238,10 +240,15 @@ export class HerdctlService {
      * all under `mcpServers: own`. Defaults to empty so every existing caller —
      * including the several tests that construct this with `{} as PaddockConfig` —
      * keeps meaning "isolated".
+     *
+     * `hostPlugins` is the host's Claude Code plugins (#700), read at boot by
+     * `loadHostPlugins` under `claude.instructions: host`, and handed in for
+     * exactly the same reasons.
      */
-    constructor(cfg, mcpSources = EMPTY_MCP_SOURCES) {
+    constructor(cfg, mcpSources = EMPTY_MCP_SOURCES, hostPlugins = EMPTY_HOST_PLUGINS) {
         this.cfg = cfg;
         this.mcpSources = mcpSources;
+        this.hostPlugins = hostPlugins;
     }
     /**
      * The Claude home every transcript symlink is planted in, plus where those
@@ -1508,7 +1515,7 @@ export class HerdctlService {
     // existing unit-test seams (which reach `sweeperAgentConfig`/`ensureConfigFile`
     // via a cast) and internal callers keep working.
     keeperAgentConfig(project, modelOverride) {
-        return buildAgentConfig(this.cfg, project, modelOverride, this.mcpSources);
+        return buildAgentConfig(this.cfg, project, modelOverride, this.mcpSources, this.hostPlugins);
     }
     sweeperAgentConfig(project) {
         return buildSweeperConfig(this.cfg, project);