@edspencer/paddock 0.61.1 → 0.62.0

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

@@ -0,0 +1,367 @@
+/**
+ * The `claude.mcpServers` lever (#691): whose MCP servers this instance's agents
+ * get.
+ *
+ * The last of the five levers, and the only one that is not about a file inside
+ * `~/.claude`. Everything else in the `claude:` block is a bridge decision about
+ * an entry of the home directory; MCP servers are declared in **`~/.claude.json`**,
+ * which is a SIBLING of that directory rather than a member of it. Claude Code
+ * resolves it as `join(CLAUDE_CONFIG_DIR ?? homedir(), ".claude.json")` — read
+ * out of the SDK bundle, where the two paths sit one expression apart and do not
+ * agree:
+ *
+ * ```js
+ * let d = n?.CLAUDE_CONFIG_DIR ?? process.env.CLAUDE_CONFIG_DIR,
+ *     f = d ?? Dr(sO(), ".claude");     // .credentials.json lives under here
+ * … await eV(Dr(f, ".credentials.json"), "utf-8")
+ * … await KMe(Dr(d ?? sO(), ".claude.json"), …)   // ← homedir, NOT ~/.claude
+ * ```
+ *
+ * So the moment paddock owns its own home (#620/#691) the user's `.claude.json`
+ * stops being on the path, and NO symlink bridge inside the home structurally
+ * can reach it. That is why MCP inheritance broke silently, separately from
+ * everything else, and why this lever is a read rather than a link.
+ *
+ * ## Why not just symlink `.claude.json`
+ *
+ * Because Claude Code WRITES to it — per-project trust, `enabledMcpjsonServers`,
+ * onboarding/migration flags, cached tips. Bridging it means paddock's instance
+ * mutating the user's real config, which is the exact thing #691 exists to stop.
+ * Read it, take the two keys that declare servers, hand those to the runtime.
+ *
+ * ## The seam, which is not the one #691 names
+ *
+ * #691 says to pass the servers through herdctl's runner option
+ * (`SDKQueryOptions.mcpServers`, merged at `sdk-runtime.js`) and that **"paddock
+ * sets none today"**. Both halves are wrong in a way that makes the work
+ * smaller, not larger:
+ *
+ * 1. `SDKQueryOptions` is built BY herdctl (`toSDKOptions`), not by paddock.
+ *    Paddock never constructs one. The field is populated from
+ *    `transformMcpServers(agent.mcp_servers)` — i.e. from the AGENT CONFIG.
+ * 2. Paddock already sets `mcp_servers`: the headless-Chromium server from
+ *    `browserMcpServers` (#269) is an external stdio MCP server passed exactly
+ *    this way, on every keeper and every trigger, whenever `PADDOCK_BROWSER_MCP`
+ *    is on.
+ *
+ * `agent.mcp_servers` is also the seam that covers BOTH runtimes for free: the
+ * SDK runtime transforms it into `sdkOptions.mcpServers`, and the CLI runtime
+ * serialises the same record into `--mcp-config '{"mcpServers":…}'`
+ * (`cli-runtime.js`). Passing it as a per-run option would have covered one.
+ *
+ * `injectedMcpServers` is, as #691 says, the wrong hook — `InjectedMcpServerDef`
+ * is `{name, version, tools}` with in-process JS handlers (`send_file`), and both
+ * runtimes materialise it as an HTTP bridge. It cannot express a stdio command.
+ *
+ * ## The allowlist, without which this lever is a no-op
+ *
+ * Paddock's fleet defaults carry an explicit `allowed_tools` array, and **both
+ * runtimes auto-deny any tool not on it, with no prompt** (the lesson `Skill`
+ * taught, recorded in `ensureConfigFile`). Tools from an MCP server are named
+ * `mcp__<server>__<tool>`, so a host server that is passed but not allowlisted
+ * connects and then has every one of its tools denied — an instance that looks
+ * configured and does nothing.
+ *
+ * herdctl handles this for INJECTED servers only ("Auto-add injected MCP tool
+ * patterns to allowedTools… only needed when the agent has an explicit
+ * allowlist", `cli-runtime.js`); config `mcp_servers` get no such treatment,
+ * which is why `mcp__playwright__*` is hard-coded into the defaults today. So
+ * this module also produces {@link mcpToolPattern} for each host server, and
+ * `buildAgentConfig` widens the keeper's allowlist by exactly those entries —
+ * only when there are some, so an instance with no host servers stays
+ * byte-identical to before.
+ *
+ * ## What cannot be carried, honestly
+ *
+ * herdctl's `McpServerSchema` is `{command?, args?, env?, url?}` and it is a
+ * plain `z.object`, so anything else is silently STRIPPED at `addAgent`. Two
+ * consequences that matter and that #691 does not mention:
+ *
+ * - **`headers` is dropped.** A remote MCP server authenticated with a bearer
+ *   header therefore arrives unauthenticated.
+ * - **`type` is dropped**, and `transformMcpServer` maps any `url` to
+ *   `type: "http"`. An `sse` server is silently downgraded to HTTP.
+ *
+ * And those two strippings are worse than they look, because of where MCP OAuth
+ * tokens turn out to live. #691 listed that as an open question; it is now
+ * answered, from the bundled CLI binary rather than by inference:
+ *
+ * - Tokens are stored under a top-level **`mcpOAuth`** key in the SAME credential
+ *   store as `claudeAiOauth` — `<securestorage-dir>/.credentials.json` on Linux,
+ *   the one `Claude Code-credentials` keychain item on darwin. There is no
+ *   MCP-specific service name and no `mcp-oauth/` directory. The store is
+ *   resolved by `CLAUDE_SECURESTORAGE_CONFIG_DIR ?? CLAUDE_CONFIG_DIR ?? ~/.claude`,
+ *   which is exactly the variable `claude.credentials` drives. **So
+ *   `credentials: host` DOES carry MCP OAuth tokens** — they are not separable
+ *   from the Anthropic login, in either direction.
+ * - But the per-server key is `` `${serverName}|${sha256({type,url,headers}).slice(0,16)}` ``.
+ *   A dropped `headers`, or an `sse` coerced to `http`, changes that hash and the
+ *   stored token is simply not found. So the combination that works today is
+ *   `credentials: host` + `mcpServers: host` for an OAuth server declared with no
+ *   headers and no `type` disagreement; a header-authenticated or `sse` server
+ *   arrives looking unauthenticated even though its token is right there.
+ *
+ * Neither is paddock's to fix here (both need a herdctl schema change). What
+ * paddock CAN do is refuse to be silent about it: {@link parseHostMcpConfig}
+ * records every key it had to drop and every `sse` it had to coerce, and the
+ * boot notice names the server. The server is still passed — this is a
+ * capability lever, not a security one, and a user who declared a server should
+ * get it plus a warning rather than nothing plus a warning. The one case that IS
+ * dropped is a server with neither `command` nor `url`, which cannot be started
+ * at all.
+ *
+ * ## Scope: keepers only
+ *
+ * The sweeper is tool-less by design and the trigger agents declare their own
+ * narrow `allowed_tools` per trigger, so neither would be able to call a host
+ * server even if it were attached. Attaching one anyway would spawn a stdio
+ * process per fire for nothing. Keepers are what a user means by "my MCP servers
+ * in paddock".
+ *
+ * ## Step 6 landed here, as an addition
+ *
+ * #691 step 6 — an instance-level `mcpServers:` block in `paddock.config.yaml`
+ * for servers a user declares themselves — is `mcp-servers.ts`. It contributes
+ * {@link McpSources.declared} and nothing else: the shape, {@link mcpServersFor},
+ * and the allowlist widening in `buildAgentConfig` were already source-agnostic
+ * and did not change. What it does NOT share is validation posture — a host
+ * server paddock cannot carry faithfully is passed with a warning (the user
+ * declared it elsewhere, for something else), while a declared one is refused
+ * with an error (they typed it here, at us, and can fix it).
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+/** Isolation is the default, as everywhere except `credentials`. */
+export const DEFAULT_MCP_SERVERS_MODE = "own";
+/** Type guard, so an unknown config value falls back instead of failing a boot. */
+export function isKnownMcpServersMode(value) {
+    return value === "own" || value === "host";
+}
+/**
+ * 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 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 function hostMcpConfigPath(legacyClaudeHome) {
+    return path.join(path.dirname(legacyClaudeHome), HOST_MCP_CONFIG_FILE);
+}
+/** No servers from anywhere: `mcpServers: own` + an empty block, and where tests start. */
+export const EMPTY_MCP_SOURCES = Object.freeze({
+    user: {},
+    byDir: {},
+    declared: {},
+    caveats: [],
+});
+/** The allowlist entry that lets a server's tools actually be called. */
+export function mcpToolPattern(name) {
+    return `mcp__${name}__*`;
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Narrow one declared server to what herdctl can carry, recording what was lost.
+ *
+ * Returns `undefined` for a server that cannot be started at all — no `command`
+ * and no `url` — which is the only case where dropping beats degrading.
+ */
+function narrowServer(name, raw, caveats) {
+    if (!isRecord(raw)) {
+        caveats.push({ name, kind: "dropped", reason: "its declaration is not a JSON object" });
+        return undefined;
+    }
+    const server = {};
+    if (typeof raw.command === "string" && raw.command !== "")
+        server.command = raw.command;
+    if (Array.isArray(raw.args) && raw.args.every((a) => typeof a === "string")) {
+        if (raw.args.length > 0)
+            server.args = [...raw.args];
+    }
+    if (isRecord(raw.env)) {
+        const env = {};
+        for (const [k, v] of Object.entries(raw.env))
+            if (typeof v === "string")
+                env[k] = v;
+        if (Object.keys(env).length > 0)
+            server.env = env;
+    }
+    if (typeof raw.url === "string" && raw.url !== "")
+        server.url = raw.url;
+    if (server.command === undefined && server.url === undefined) {
+        caveats.push({
+            name,
+            kind: "dropped",
+            reason: "it declares neither a `command` nor a `url`, so there is nothing to start",
+        });
+        return undefined;
+    }
+    // The lossy bits. `type` and `headers` are real keys of Claude Code's own MCP
+    // config that herdctl's schema has no field for and therefore strips; saying so
+    // is the difference between "my Notion server does not work" and "my Notion
+    // server's bearer header was dropped, here is the issue to file".
+    if (isRecord(raw.headers) && Object.keys(raw.headers).length > 0) {
+        caveats.push({
+            name,
+            kind: "degraded",
+            reason: `its \`headers\` (${Object.keys(raw.headers).join(", ")}) cannot be carried — ` +
+                `herdctl's MCP schema has no field for them, so the server is passed WITHOUT them, ` +
+                `any auth they held is gone, and its stored OAuth token (keyed on a hash that ` +
+                `includes the headers) will not be found either`,
+        });
+    }
+    if (raw.type === "sse") {
+        caveats.push({
+            name,
+            kind: "degraded",
+            reason: 'it is an `sse` server, and herdctl maps every `url` to `type: "http"` — it will ' +
+                "be connected to as HTTP, and any OAuth token stored against the `sse` shape " +
+                "will not be found",
+        });
+    }
+    return server;
+}
+function serversOf(raw, caveats) {
+    if (!isRecord(raw))
+        return {};
+    const out = {};
+    for (const [name, decl] of Object.entries(raw)) {
+        const server = narrowServer(name, decl, caveats);
+        if (server)
+            out[name] = server;
+    }
+    return out;
+}
+/**
+ * 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 function parseHostMcpConfig(raw) {
+    const caveats = [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { user: {}, byDir: {}, declared: {}, caveats };
+    }
+    if (!isRecord(parsed))
+        return { user: {}, byDir: {}, declared: {}, caveats };
+    const user = serversOf(parsed.mcpServers, caveats);
+    const byDir = {};
+    if (isRecord(parsed.projects)) {
+        for (const [dir, entry] of Object.entries(parsed.projects)) {
+            if (!isRecord(entry))
+                continue;
+            const servers = serversOf(entry.mcpServers, caveats);
+            if (Object.keys(servers).length > 0)
+                byDir[dir] = servers;
+        }
+    }
+    return { user, byDir, declared: {}, caveats };
+}
+/**
+ * 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 function mcpServersFor(source, workingDir) {
+    return { ...source.user, ...(source.byDir[workingDir] ?? {}), ...source.declared };
+}
+/** Every directory-scoped key, for the boot notice. */
+export function hostMcpScopedDirs(source) {
+    return Object.keys(source.byDir);
+}
+/**
+ * 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 async function loadHostMcpSource(cfg) {
+    if (cfg.claude.mcpServers !== "host")
+        return { source: EMPTY_MCP_SOURCES, notices: [] };
+    const file = hostMcpConfigPath(cfg.legacyClaudeHome);
+    const notices = [];
+    let raw;
+    try {
+        raw = await fs.readFile(file, "utf8");
+    }
+    catch (err) {
+        notices.push({
+            level: "info",
+            message: `\`claude.mcpServers: host\` is set but ${file} could not be read (${String(err)}) — ` +
+                `no host MCP servers are attached. That file is where \`claude mcp add\` writes; ` +
+                `it does not exist until you have added one.`,
+        });
+        return { source: EMPTY_MCP_SOURCES, notices };
+    }
+    const source = parseHostMcpConfig(raw);
+    const userNames = Object.keys(source.user);
+    const scoped = hostMcpScopedDirs(source);
+    const total = userNames.length + scoped.reduce((n, d) => n + Object.keys(source.byDir[d]).length, 0);
+    if (total === 0) {
+        notices.push({
+            level: "info",
+            message: `\`claude.mcpServers: host\`: no MCP servers are declared in ${file} ` +
+                `(neither at the top level nor under any \`projects\` entry).`,
+        });
+    }
+    else {
+        notices.push({
+            level: "info",
+            message: `Claude MCP servers: host (\`claude.mcpServers: host\`) — ` +
+                (userNames.length > 0 ? `user scope: ${userNames.join(", ")}` : "no user-scope servers") +
+                (scoped.length > 0
+                    ? `; directory scope: ${scoped
+                        .map((d) => `${d} (${Object.keys(source.byDir[d]).join(", ")})`)
+                        .join(", ")}`
+                    : "") +
+                `. A project's keeper gets the user-scope servers plus any scoped to its own ` +
+                `working directory.`,
+        });
+    }
+    for (const caveat of source.caveats) {
+        notices.push({
+            level: "warn",
+            message: caveat.kind === "dropped"
+                ? `MCP server "${caveat.name}" in ${file} was NOT attached: ${caveat.reason}.`
+                : `MCP server "${caveat.name}" from ${file} is attached but degraded: ${caveat.reason}.`,
+        });
+    }
+    return { source, notices };
+}

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

@@ -0,0 +1,159 @@
+/**
+ * The `claude.hooks` lever (#691): whether this instance runs the host machine's
+ * Claude Code hooks.
+ *
+ * This is the one lever in the `claude:` block that is about code execution
+ * rather than data. A hook is a shell command Claude Code runs on `PreToolUse`,
+ * `PostToolUse`, `SessionStart` and friends, and since #620 paddock has symlinked
+ * the user's `~/.claude/settings.json` into its own home unconditionally — so
+ * every hook the user has ever configured fires inside every paddock turn, with
+ * no key to turn it off. "Isolate it by just trying paddock" was not true, and
+ * this is why.
+ *
+ * ## Why this cannot be a symlink decision
+ *
+ * `settings.json` is a mixed bag. It carries `hooks`, and also `permissions`,
+ * `model`, `statusLine`, `enabledPlugins`, `env`, `outputStyle` — the things a
+ * user configures once and expects everywhere. A symlink is all-or-nothing and
+ * the file is not, so `hooks: own` has to leave the rest inherited while dropping
+ * one key.
+ *
+ * So paddock WRITES `<ownHome>/settings.json` itself: parse the user's, drop
+ * {@link HOST_ONLY_SETTINGS_KEYS}, serialise the remainder. `hooks: host` is the
+ * old symlink, unchanged.
+ *
+ * ### The staleness this buys, which is real
+ *
+ * A copy diverges the moment the user edits theirs; a symlink does not — and
+ * **that difference is live, not just at the next process start.** Claude Code
+ * runs a settings-change watcher (~1s poll + 500ms debounce) that follows the
+ * symlink to its real target, clears its whole settings memo and re-applies the
+ * result mid-session; verified by mutating a symlink target under a running
+ * `query()` and watching `Detected change to … (via symlink target …)` come back.
+ * So the honest statement is that a symlink propagates an edit in about a second
+ * and the copy propagates it at the next paddock restart. Two things make that
+ * an acceptable price rather than a design flaw:
+ *
+ * 1. **Only users who actually have hooks pay it.** {@link planHostSettings}
+ *    returns `link` when the user's file has none of the governed keys, which is
+ *    most files — nothing to filter, so nothing is copied and there is nothing to
+ *    go stale. The copy exists exactly where filtering is doing work.
+ * 2. **It is regenerated on every boot** (`ensureClaudeHome`), so a restart is
+ *    the whole of the fix, and paddock says so in the boot notice.
+ *
+ * A file-watcher on the user's file, re-running the filter, would close the gap
+ * — and because Claude Code's own watcher fires on content change regardless of
+ * who wrote it, paddock re-writing the copy WOULD be picked up live. That is a
+ * real option if the cadence ever matters. It is not taken here: it puts a
+ * watcher on a path in the user's home, races paddock's own write against the
+ * 5s echo-suppression window Claude Code uses for exactly this, and buys a
+ * narrower window on a file people edit a handful of times a year.
+ *
+ * ### Which turns this actually governs today, which is not all of them
+ *
+ * `<claudeHome>/settings.json` is Claude Code's `userSettings` source, and
+ * **herdctl does not load that source on the SDK runtime.** `sdk-adapter.js`
+ * defaults `settingSources` to `["project"]` for any agent with a
+ * `working_directory` — which is every paddock keeper — so the SDK is invoked
+ * with `--setting-sources=project` and never reads this file at all. The CLI
+ * runtime passes `--setting-sources` only when an agent declares
+ * `setting_sources`, and paddock declares none, so `claude -p` runs on the
+ * default `["user","project","local"]` and DOES read it.
+ *
+ * So the host's hooks execute in the sweeper, in triggers, and in
+ * `driveMode: batch` chats — and not, today, in a default SDK chat turn. That
+ * makes this lever narrower than #691 assumed, and worth keeping regardless:
+ * those paths are real code execution, the asymmetry is a herdctl default rather
+ * than a guarantee, and a lever that is correct before the default changes is
+ * the only kind worth having. The same caveat applies to the keys it KEEPS —
+ * the user's `permissions` and `model` reach the CLI paths and not the SDK ones,
+ * which was true before this change too.
+ *
+ * ## What `own` does NOT stop, and should
+ *
+ * `hooks` is not the only key in `settings.json` that names a command to run.
+ * Read straight out of the SDK's own settings schema
+ * (`@anthropic-ai/claude-agent-sdk/sdk.mjs`), these do too:
+ *
+ * - `apiKeyHelper` — "Path to a script that outputs authentication values"
+ * - `awsCredentialExport` — "Path to a script that exports AWS credentials"
+ * - `awsAuthRefresh` — "Path to a script that refreshes AWS authentication"
+ * - `gcpAuthRefresh` — "Command to refresh GCP authentication"
+ * - `proxyAuthHelper` — "Shell command that outputs a Proxy-Authorization header"
+ * - `otelHeadersHelper` — "Path to a script that outputs OpenTelemetry headers"
+ * - `statusLine`, `subagentStatusLine`, `fileSuggestion` — `{type:"command", …}`
+ *
+ * #691 scopes this lever to `hooks`, so `hooks` is what {@link
+ * HOST_ONLY_SETTINGS_KEYS} contains — widening a default-on security lever past
+ * its brief is the maintainer's call, not this module's. It is one line when he
+ * makes it, and the trade-off is not obvious in either direction: the first five
+ * of those are how a user's login WORKS on a corporate setup, so dropping them
+ * under a key named `hooks` would break authentication for exactly the people who
+ * did nothing wrong — an argument that they belong under `claude.credentials`
+ * rather than here. Until someone decides, `hooks: own` means "no host hooks",
+ * not "no host commands", and this comment is the difference.
+ */
+/**
+ * Whether this instance runs the host machine's Claude Code hooks — the
+ * `claude.hooks` key.
+ *
+ * `own` (default) = paddock writes a `settings.json` carrying the user's other
+ * keys with `hooks` dropped. `host` = the user's `~/.claude/settings.json`
+ * symlinked in whole, hooks included, which is what every version before this
+ * one did.
+ */
+export type HooksMode = "own" | "host";
+/**
+ * Isolation is the default, and here it is the only defensible one: `host` means
+ * arbitrary commands from outside the data dir execute inside paddock's turns,
+ * and that is not something a user should opt out of after the fact.
+ */
+export declare const DEFAULT_HOOKS_MODE: HooksMode;
+/** Type guard, so an unknown config value falls back instead of failing a boot. */
+export declare function isKnownHooksMode(value: string): value is HooksMode;
+/** The Claude home entry this lever filters. */
+export declare const SETTINGS_ENTRY = "settings.json";
+/**
+ * Keys of `settings.json` that `hooks: own` drops. See the module doc for the
+ * several others that arguably belong here and are deliberately not.
+ */
+export declare const HOST_ONLY_SETTINGS_KEYS: readonly ["hooks"];
+/**
+ * Where paddock records the SHA-256 of each file it generated in its own home,
+ * so a later boot can tell its own output from something a human put there.
+ *
+ * A marker key inside `settings.json` would need no second file, but the schema
+ * is Claude Code's and adding a key to it is asking for a validation warning on
+ * some future version. A hash sidecar is inert by construction.
+ */
+export declare const GENERATED_MARKER_FILE = ".paddock-generated.json";
+/** What {@link planHostSettings} decided to do with the user's settings file. */
+export type SettingsPlan = 
+/** Nothing governed is present: symlink it, exactly as `host` would. */
+{
+    action: "link";
+}
+/** Write this content into paddock's home instead of linking. */
+ | {
+    action: "write";
+    content: string;
+    dropped: string[];
+}
+/** Unusable: plant nothing, and say why. Fail closed, never link. */
+ | {
+    action: "skip";
+    reason: string;
+};
+/**
+ * Decide what paddock's own `settings.json` should be, given the user's.
+ *
+ * Pure, so the whole decision is testable without a filesystem.
+ *
+ * The `skip` case is the security-relevant one. A `settings.json` that will not
+ * parse cannot be filtered, and the safe response is to plant NOTHING rather than
+ * fall back to a symlink — a symlink would hand over the hooks this lever exists
+ * to withhold, and it would do it precisely when something is already wrong.
+ * Claude Code will not be able to read that file either, so the instance loses
+ * nothing it would otherwise have had.
+ */
+export declare function planHostSettings(mode: HooksMode, raw: string): SettingsPlan;