@edspencer/paddock 0.61.0 → 0.62.0

package/packages/server/dist/claude-instructions.d.ts

@@ -0,0 +1,121 @@
+/**
+ * The `claude.instructions` lever (#691): whose CLAUDE.md, subagents and slash
+ * commands this instance runs with.
+ *
+ * Paddock always owns its Claude home (`<dataDir>/claude-home`, #691), and
+ * relocating a home means the user-level config that lives in `~/.claude` is no
+ * longer on Claude Code's path. Since #620 paddock has symlinked it back in
+ * unconditionally. This key makes that a choice.
+ *
+ * ## What is in scope
+ *
+ * {@link INSTRUCTION_ENTRIES} — `CLAUDE.md`, `agents/`, `commands/`, `plugins/`.
+ * Content the model reads, or definitions it can invoke by name: prompts,
+ * subagent descriptions, slash commands. Nothing here runs a command on this
+ * machine of its own accord, which is what separates it from `claude.hooks`.
+ *
+ * Bridged by SYMLINK, as before — user-level config is the user's to maintain,
+ * and a copy would go stale the moment they edited it.
+ *
+ * ## The case against `own` as the default, which is real
+ *
+ * This default reverses the argument #620 shipped with, and that argument is
+ * worth keeping rather than deleting. Verbatim, from the docstring that used to
+ * sit on `BRIDGED_ENTRIES`:
+ *
+ * > Without this, relocating the home silently changes agent behaviour: the
+ * > user's `~/.claude/CLAUDE.md` is auto-loaded into every session,
+ * > `settings.json` carries permissions and hooks, and `agents/` `commands/`
+ * > `plugins/` are capability. Dropping them is not "a clean home", it is a
+ * > behaviour regression nobody asked for.
+ *
+ * The reasoning is sound and the premise is **false for the runtime paddock
+ * actually uses**, which is worth knowing before weighing the default.
+ *
+ * `~/.claude/CLAUDE.md` is NOT "auto-loaded into every session". User memory,
+ * `agents/` and `commands/` all move as one unit with Claude Code's `user`
+ * setting source, and herdctl invokes the Agent SDK with
+ * `--setting-sources=project` for every agent that has a working directory —
+ * which is every paddock keeper. Verified by capturing the outbound request
+ * body: under the default sources the prompt carries a `# claudeMd` block naming
+ * `<claudeHome>/CLAUDE.md`; under `["project"]` that block is absent entirely,
+ * while the PROJECT's own `CLAUDE.md` still loads. `system/init` likewise drops
+ * the home's subagents and slash commands from `agents` / `slash_commands`.
+ * (The one thing in the home that is NOT gated is `projects/<enc>/memory/` —
+ * auto-memory reaches the agent either way.)
+ *
+ * So on a default chat turn these four entries have been inert since chats moved
+ * to the SDK runtime, bridged or not. Where they DO bite is the CLI paths — the
+ * post-turn sweeper, triggers, and `driveMode: batch` chats — which pass no
+ * `--setting-sources` and therefore run on the default `user,project,local`.
+ *
+ * That shrinks the case against `own` rather than answering it: the behaviour
+ * regression the docstring warned about has, for the main path, already
+ * happened, silently, and nobody filed it. What is left is a real change to the
+ * CLI paths, and a lever that is correct before herdctl's default changes rather
+ * than after.
+ *
+ * `own` is the default (#691) because the remaining argument is about what a
+ * user can *state*. "`own` everywhere means nothing outside the data dir is read
+ * or written" is a guarantee an operator can read off a config file; "…except
+ * your CLAUDE.md, agents, commands and plugins, always, with no key to turn them
+ * off" is not a guarantee, it is a footnote. A regression one documented key away
+ * from being undone is recoverable; an inherited capability with no lever at all
+ * is the thing #691 exists to end.
+ *
+ * The residual cost lands on exactly the users who invested most in their own
+ * Claude Code setup, so the boot notice names the key rather than leaving them to
+ * find it — see `ensureClaudeHome`.
+ *
+ * ## Not in scope, deliberately
+ *
+ * - **`settings.json`** — a mixed bag whose executable half is `claude.hooks`
+ *   and whose remaining keys (permissions, model, statusline) are inherited
+ *   either way. See `claude-settings.ts`.
+ * - **`enabledPlugins`**, which lives inside `settings.json` and is therefore
+ *   still inherited under `instructions: own`, orphaned from the `plugins/` dir
+ *   it names. Harmless as long as bridging `plugins/` is inert (below) — and step
+ *   5 has now been built without changing that: `claude.mcpServers: host` reads
+ *   `~/.claude.json` and touches no setting source, so the flag is still never
+ *   loaded and a bridged plugin still never switches on. If that ever changes,
+ *   this key has to move under this lever with the directory it names.
+ * - **`.credentials.json`** — `claude.credentials`, step 3.
+ * - **`projects/`, `todos/`, `shell-snapshots/`, `statsig/`, `sessions/`** — never
+ *   bridged in either mode. Per-instance runtime state, which is exactly what
+ *   should be per-instance.
+ */
+/**
+ * Whose user-level instructions this instance uses — the `claude.instructions`
+ * key.
+ *
+ * `own` (default) = only what is inside paddock's own Claude home, plus whatever
+ * each project's own directory provides. `host` = the user's `~/.claude`
+ * CLAUDE.md, agents, commands and plugins as well, symlinked in.
+ */
+export type InstructionsMode = "own" | "host";
+/** Isolation is the default. See the module doc for the case against it. */
+export declare const DEFAULT_INSTRUCTIONS_MODE: InstructionsMode;
+/** Type guard, so an unknown config value falls back instead of failing a boot. */
+export declare function isKnownInstructionsMode(value: string): value is InstructionsMode;
+/**
+ * The entries of the user's Claude home this lever governs.
+ *
+ * `plugins` is here on the strength of the files rather than their effect —
+ * though NOT for the reason #691 gives. The design says the SDK "does not
+ * auto-discover installed plugins" and that bridging the directory is therefore
+ * inert. That is wrong on the mechanism: the runtime's plugin root IS the Claude
+ * home (`join(CLAUDE_CONFIG_DIR, "plugins")`), the `plugins?: SdkPluginConfig[]`
+ * option is a sideload channel that gets MERGED with what is discovered there,
+ * and a live probe loaded a plugin from a planted home with no `plugins` option
+ * passed at all.
+ *
+ * What makes it inert for paddock is one step further along: discovery is driven
+ * by `enabledPlugins`, which lives in `settings.json`, and herdctl runs the SDK
+ * with `--setting-sources=project` so the HOME's `settings.json` is never read
+ * (see `claude-settings.ts`). Bridge the directory and the flag that turns its
+ * contents on is still not loaded. That is a property of two callers rather than
+ * of the files, which is exactly why this lever governs them anyway: step 5 is
+ * about to change one of those callers, and a lever that silently omitted
+ * plugins would then start leaking them.
+ */
+export declare const INSTRUCTION_ENTRIES: readonly ["CLAUDE.md", "agents", "commands", "plugins"];

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

@@ -0,0 +1,114 @@
+/**
+ * The `claude.instructions` lever (#691): whose CLAUDE.md, subagents and slash
+ * commands this instance runs with.
+ *
+ * Paddock always owns its Claude home (`<dataDir>/claude-home`, #691), and
+ * relocating a home means the user-level config that lives in `~/.claude` is no
+ * longer on Claude Code's path. Since #620 paddock has symlinked it back in
+ * unconditionally. This key makes that a choice.
+ *
+ * ## What is in scope
+ *
+ * {@link INSTRUCTION_ENTRIES} — `CLAUDE.md`, `agents/`, `commands/`, `plugins/`.
+ * Content the model reads, or definitions it can invoke by name: prompts,
+ * subagent descriptions, slash commands. Nothing here runs a command on this
+ * machine of its own accord, which is what separates it from `claude.hooks`.
+ *
+ * Bridged by SYMLINK, as before — user-level config is the user's to maintain,
+ * and a copy would go stale the moment they edited it.
+ *
+ * ## The case against `own` as the default, which is real
+ *
+ * This default reverses the argument #620 shipped with, and that argument is
+ * worth keeping rather than deleting. Verbatim, from the docstring that used to
+ * sit on `BRIDGED_ENTRIES`:
+ *
+ * > Without this, relocating the home silently changes agent behaviour: the
+ * > user's `~/.claude/CLAUDE.md` is auto-loaded into every session,
+ * > `settings.json` carries permissions and hooks, and `agents/` `commands/`
+ * > `plugins/` are capability. Dropping them is not "a clean home", it is a
+ * > behaviour regression nobody asked for.
+ *
+ * The reasoning is sound and the premise is **false for the runtime paddock
+ * actually uses**, which is worth knowing before weighing the default.
+ *
+ * `~/.claude/CLAUDE.md` is NOT "auto-loaded into every session". User memory,
+ * `agents/` and `commands/` all move as one unit with Claude Code's `user`
+ * setting source, and herdctl invokes the Agent SDK with
+ * `--setting-sources=project` for every agent that has a working directory —
+ * which is every paddock keeper. Verified by capturing the outbound request
+ * body: under the default sources the prompt carries a `# claudeMd` block naming
+ * `<claudeHome>/CLAUDE.md`; under `["project"]` that block is absent entirely,
+ * while the PROJECT's own `CLAUDE.md` still loads. `system/init` likewise drops
+ * the home's subagents and slash commands from `agents` / `slash_commands`.
+ * (The one thing in the home that is NOT gated is `projects/<enc>/memory/` —
+ * auto-memory reaches the agent either way.)
+ *
+ * So on a default chat turn these four entries have been inert since chats moved
+ * to the SDK runtime, bridged or not. Where they DO bite is the CLI paths — the
+ * post-turn sweeper, triggers, and `driveMode: batch` chats — which pass no
+ * `--setting-sources` and therefore run on the default `user,project,local`.
+ *
+ * That shrinks the case against `own` rather than answering it: the behaviour
+ * regression the docstring warned about has, for the main path, already
+ * happened, silently, and nobody filed it. What is left is a real change to the
+ * CLI paths, and a lever that is correct before herdctl's default changes rather
+ * than after.
+ *
+ * `own` is the default (#691) because the remaining argument is about what a
+ * user can *state*. "`own` everywhere means nothing outside the data dir is read
+ * or written" is a guarantee an operator can read off a config file; "…except
+ * your CLAUDE.md, agents, commands and plugins, always, with no key to turn them
+ * off" is not a guarantee, it is a footnote. A regression one documented key away
+ * from being undone is recoverable; an inherited capability with no lever at all
+ * is the thing #691 exists to end.
+ *
+ * The residual cost lands on exactly the users who invested most in their own
+ * Claude Code setup, so the boot notice names the key rather than leaving them to
+ * find it — see `ensureClaudeHome`.
+ *
+ * ## Not in scope, deliberately
+ *
+ * - **`settings.json`** — a mixed bag whose executable half is `claude.hooks`
+ *   and whose remaining keys (permissions, model, statusline) are inherited
+ *   either way. See `claude-settings.ts`.
+ * - **`enabledPlugins`**, which lives inside `settings.json` and is therefore
+ *   still inherited under `instructions: own`, orphaned from the `plugins/` dir
+ *   it names. Harmless as long as bridging `plugins/` is inert (below) — and step
+ *   5 has now been built without changing that: `claude.mcpServers: host` reads
+ *   `~/.claude.json` and touches no setting source, so the flag is still never
+ *   loaded and a bridged plugin still never switches on. If that ever changes,
+ *   this key has to move under this lever with the directory it names.
+ * - **`.credentials.json`** — `claude.credentials`, step 3.
+ * - **`projects/`, `todos/`, `shell-snapshots/`, `statsig/`, `sessions/`** — never
+ *   bridged in either mode. Per-instance runtime state, which is exactly what
+ *   should be per-instance.
+ */
+/** Isolation is the default. See the module doc for the case against it. */
+export const DEFAULT_INSTRUCTIONS_MODE = "own";
+/** Type guard, so an unknown config value falls back instead of failing a boot. */
+export function isKnownInstructionsMode(value) {
+    return value === "own" || value === "host";
+}
+/**
+ * The entries of the user's Claude home this lever governs.
+ *
+ * `plugins` is here on the strength of the files rather than their effect —
+ * though NOT for the reason #691 gives. The design says the SDK "does not
+ * auto-discover installed plugins" and that bridging the directory is therefore
+ * inert. That is wrong on the mechanism: the runtime's plugin root IS the Claude
+ * home (`join(CLAUDE_CONFIG_DIR, "plugins")`), the `plugins?: SdkPluginConfig[]`
+ * option is a sideload channel that gets MERGED with what is discovered there,
+ * and a live probe loaded a plugin from a planted home with no `plugins` option
+ * passed at all.
+ *
+ * What makes it inert for paddock is one step further along: discovery is driven
+ * by `enabledPlugins`, which lives in `settings.json`, and herdctl runs the SDK
+ * with `--setting-sources=project` so the HOME's `settings.json` is never read
+ * (see `claude-settings.ts`). Bridge the directory and the flag that turns its
+ * contents on is still not loaded. That is a property of two callers rather than
+ * of the files, which is exactly why this lever governs them anyway: step 5 is
+ * about to change one of those callers, and a lever that silently omitted
+ * plugins would then start leaking them.
+ */
+export const INSTRUCTION_ENTRIES = ["CLAUDE.md", "agents", "commands", "plugins"];

package/packages/server/dist/claude-mcp.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Whose MCP servers this instance's agents get — the `claude.mcpServers` key.
+ *
+ * `own` (default) = only the servers paddock itself attaches (`send_file`, the
+ * optional self-management tools, the optional browser server). `host` = the
+ * servers declared in the user's `~/.claude.json` as well, both the user-scope
+ * ones and the ones scoped to a project's own directory.
+ */
+export type McpServersMode = "own" | "host";
+/** Isolation is the default, as everywhere except `credentials`. */
+export declare const DEFAULT_MCP_SERVERS_MODE: McpServersMode;
+/** Type guard, so an unknown config value falls back instead of failing a boot. */
+export declare function isKnownMcpServersMode(value: string): value is McpServersMode;
+/**
+ * The file MCP servers are declared in — a SIBLING of the Claude home, not an
+ * entry inside it. See the module doc for the SDK expression that settles this.
+ */
+export declare const HOST_MCP_CONFIG_FILE = ".claude.json";
+/**
+ * Where the user's own `.claude.json` is.
+ *
+ * Derived from `cfg.legacyClaudeHome` (always `~/.claude`) rather than read from
+ * `os.homedir()` again, so it moves with the one value the rest of the bridge
+ * already treats as "the host's Claude Code" — and so a test can point the whole
+ * lever at a temp dir by setting that one field.
+ */
+export declare function hostMcpConfigPath(legacyClaudeHome: string): string;
+/**
+ * One MCP server, in the only shape herdctl's `McpServerSchema` can carry.
+ *
+ * Deliberately NOT `SDKMcpServerConfig`: that is what herdctl produces on the
+ * far side of `transformMcpServer`, and pinning the narrower agent-config shape
+ * here is what makes the lossiness above visible at the type level rather than
+ * at runtime.
+ */
+export interface McpServerDef {
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+}
+/** A set of MCP servers, keyed by the name their tools are namespaced under. */
+export type McpServerDefs = Record<string, McpServerDef>;
+/** Something about a declared server that could not be carried through. */
+export interface HostMcpCaveat {
+    /** The server's name in `.claude.json`. */
+    name: string;
+    /** `dropped` = not passed at all; `degraded` = passed, but not faithfully. */
+    kind: "dropped" | "degraded";
+    /** Human-readable, and specific enough to act on. */
+    reason: string;
+}
+/**
+ * Every MCP server this instance will attach, from every source, plus what could
+ * not be carried.
+ *
+ * The host's `~/.claude.json` supplies two scopes, because that file has two: a
+ * top-level `mcpServers` that applies everywhere, and a
+ * `projects[<absolute dir>].mcpServers` that applies only in that directory. The
+ * per-directory one is keyed by the LITERAL absolute path — not the `-`-encoded
+ * form the transcript folders use — and it is the scope a `--here` workspace
+ * hits, because `claude mcp add` without `--scope user` writes there.
+ *
+ * {@link declared} is the third contributor and the one that is not the host's at
+ * all: paddock's own top-level `mcpServers:` config block (#691 step 6), resolved
+ * by `mcp-servers.ts`. It is carried here rather than threaded separately so that
+ * everything downstream of this type — {@link mcpServersFor}, the allowlist
+ * widening in `buildAgentConfig` — stays source-agnostic and had to change not at
+ * all when it was added.
+ */
+export interface McpSources {
+    /** Host `~/.claude.json` top-level `mcpServers`: every keeper gets these. */
+    user: McpServerDefs;
+    /** Host `projects[<dir>].mcpServers`, keyed by the literal absolute directory. */
+    byDir: Record<string, McpServerDefs>;
+    /** Declared by this instance in `paddock.config.yaml`; every keeper gets these. */
+    declared: McpServerDefs;
+    /** Everything the host file could not carry faithfully, for the boot notice. */
+    caveats: HostMcpCaveat[];
+}
+/** No servers from anywhere: `mcpServers: own` + an empty block, and where tests start. */
+export declare const EMPTY_MCP_SOURCES: McpSources;
+/** The allowlist entry that lets a server's tools actually be called. */
+export declare function mcpToolPattern(name: string): string;
+/**
+ * Parse a `.claude.json` into the two server scopes. Pure, so the whole
+ * selection is testable from a string with no filesystem and no real home.
+ *
+ * Fails soft in both directions on purpose. Unparseable JSON, a non-object top
+ * level, a `projects` value that is not a map — none of them throw, because the
+ * user's `.claude.json` is a file paddock does not own, cannot validate and must
+ * never turn into a boot failure. What it does instead is return nothing and let
+ * the caller say so.
+ */
+export declare function parseHostMcpConfig(raw: string): McpSources;
+/**
+ * The servers that apply to one agent's working directory.
+ *
+ * Precedence, weakest first: host user scope, host directory scope, then this
+ * instance's own `mcpServers:` block.
+ *
+ * Host per-directory wins over host user scope because it is the more specific
+ * declaration, and it is the one `claude mcp add` writes by default, so a user
+ * who re-declared a server inside a project meant that one. {@link
+ * McpSources.declared} wins over both because it is a statement about THIS
+ * instance while `~/.claude.json` is ambient machine state — a user who wrote a
+ * server into paddock's own config was answering "what should paddock have?",
+ * which is a narrower question than "what does this machine have?".
+ *
+ * The host lookup is exact rather than a prefix walk. `.claude.json`'s `projects`
+ * keys are the literal cwd Claude Code was started in, and Claude Code does not
+ * inherit a parent directory's entry either — matching that keeps paddock's
+ * answer the same as the terminal's, which is the whole point of `host`.
+ */
+export declare function mcpServersFor(source: McpSources, workingDir: string): McpServerDefs;
+/** Every directory-scoped key, for the boot notice. */
+export declare function hostMcpScopedDirs(source: McpSources): string[];
+/** A line for the boot log, at a level (mirrors `ClaudeHomeReport.notices`). */
+export interface HostMcpNotice {
+    level: "info" | "warn";
+    message: string;
+}
+/** What {@link loadHostMcpSource} found. */
+export interface HostMcpReport {
+    source: McpSources;
+    notices: HostMcpNotice[];
+}
+/**
+ * Read the host's `.claude.json` — once, at boot — and say what came of it.
+ *
+ * Under `own` the file is not opened at all. That is not an optimisation: "own
+ * everywhere means nothing outside the data dir is read" is the guarantee #691
+ * exists to make sayable, and a lever that read the file and then discarded it
+ * would make the guarantee false in the only place anyone could check.
+ *
+ * Read once rather than per turn, for the same reason `claude.hooks` materialises
+ * its `settings.json` once: a `.claude.json` that grows a server mid-run is picked
+ * up at the next restart, and the boot notice is where a user looks to confirm
+ * what this instance actually has.
+ */
+export declare function loadHostMcpSource(cfg: {
+    legacyClaudeHome: string;
+    claude: {
+        mcpServers: McpServersMode;
+    };
+}): Promise<HostMcpReport>;