@edspencer/paddock 0.61.1 → 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/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;