@edspencer/paddock 0.61.0 → 0.62.0

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

@@ -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.
+ */
+/**
+ * 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 const DEFAULT_HOOKS_MODE = "own";
+/** Type guard, so an unknown config value falls back instead of failing a boot. */
+export function isKnownHooksMode(value) {
+    return value === "own" || value === "host";
+}
+/** The Claude home entry this lever filters. */
+export 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 const HOST_ONLY_SETTINGS_KEYS = ["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 const GENERATED_MARKER_FILE = ".paddock-generated.json";
+/**
+ * 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 function planHostSettings(mode, raw) {
+    if (mode === "host")
+        return { action: "link" };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return { action: "skip", reason: `it is not valid JSON (${String(err)})` };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { action: "skip", reason: "its top level is not a JSON object" };
+    }
+    const settings = parsed;
+    const dropped = HOST_ONLY_SETTINGS_KEYS.filter((k) => k in settings);
+    if (dropped.length === 0)
+        return { action: "link" };
+    const kept = {};
+    // Insertion order preserved, minus the dropped keys — a user comparing the two
+    // files should see a deletion, not a reshuffle.
+    for (const [k, v] of Object.entries(settings)) {
+        if (!dropped.includes(k))
+            kept[k] = v;
+    }
+    return { action: "write", content: `${JSON.stringify(kept, null, 2)}\n`, dropped: [...dropped] };
+}

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 links ~/.claude/projects/<encoded-dir> at this workspace\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 in the\n  environment: CLAUDE_CODE_OAUTH_TOKEN (Max/Pro) or ANTHROPIC_API_KEY (API\n  billing). If you already use Claude Code on this machine, an existing login\n  under ~/.claude is picked up automatically. Otherwise run `claude setup-token`.\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\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";

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

@@ -134,16 +134,50 @@ Opening a directory (--here)
 
     · creates .paddock/ in the directory for this workspace's own state
     · creates .chats/ for transcripts, and adds both to .gitignore
-    · links ~/.claude/projects/<encoded-dir> at this workspace
+    · offers your ~/.claude sessions for this directory for import — nothing
+      there is moved, copied or linked until you confirm
 
   Once done, later runs in the same directory resume it — no flag needed.
   Without --here, Paddock never touches the directory you ran it from.
 
 Credentials
-  Paddock drives Claude Code, so it needs Claude credentials in the
-  environment: CLAUDE_CODE_OAUTH_TOKEN (Max/Pro) or ANTHROPIC_API_KEY (API
-  billing). If you already use Claude Code on this machine, an existing login
-  under ~/.claude is picked up automatically. Otherwise run \`claude setup-token\`.
+  Paddock drives Claude Code, so it needs Claude credentials — and if you
+  already use Claude Code on this machine, it uses the login you already have.
+  That is a macOS Keychain entry on a Mac, or your ~/.claude/.credentials.json
+  elsewhere (symlinked in, never copied). Reading a login writes nothing.
+
+  Otherwise: a CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY in the environment,
+  or a one-off \`CLAUDE_CONFIG_DIR=<data-dir>/claude-home claude login\`. With no
+  login at all anywhere, run \`claude setup-token\`. Paddock says at startup when
+  it can find none.
+
+Sharing your Claude Code state
+  Apart from that login, Paddock writes nothing outside its data dir by
+  default: transcripts go to each project's .chats/, and your ~/.claude is read
+  for config only. Each thing it can share is one key in
+  <data-dir>/paddock.config.yaml:
+
+    claude:
+      transcripts: host   # own | host, default own
+      credentials: host   # own | host, default host
+      instructions: host  # own | host, default own
+      hooks: 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
+  releases it rather than removing it, because it is your history rather than
+  Paddock's copy. credentials: own is the opt-out from sharing the login above.
+
+  instructions: host loads your ~/.claude CLAUDE.md, agents/, commands/ and
+  plugins/. Off by default, which is a change: your curated CLAUDE.md does not
+  reach Paddock's agents unless you say so. Each project's own CLAUDE.md always
+  does.
+
+  hooks: host runs the shell commands your ~/.claude/settings.json binds to
+  tool use. Off by default — inheriting someone's hooks is not something to
+  discover after the fact. Its other keys (permissions, model, statusline)
+  apply either way: under hooks: own Paddock writes its own settings.json
+  carrying them with hooks dropped, regenerated at startup.
 
 Your data
   Everything lives in one directory — ~/.paddock unless you pass --data-dir.

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

@@ -119,6 +119,13 @@ function announceHereConsent(dir, dataDir) {
         "",
         `  Opening ${dir} as a Paddock workspace.`,
         `    · ${path.relative(dir, dataDir) || HERE_MARKER}/ and .chats/ created here, and added to .gitignore`,
+        // Worth stating because it is not what you would predict: paddock reading
+        // the home a user's sessions live in does not turn them into paddock's
+        // chats. Verified against a running instance — a pre-existing transcript
+        // for the directory comes back from `adoptable-chats` (offered) and NOT
+        // from `chats` (listed), because session discovery is attribution-based,
+        // not "whatever is in the folder". So #663's confirmation still gates
+        // every import.
         "    · ~/.claude sessions for this directory are offered for import (nothing is moved)",
         "  Later runs here resume it — no flag needed.",
         "",
@@ -131,7 +138,9 @@ function announceHereConsent(dir, dataDir) {
  * transcripts and prints, and changes nothing on disk.
  */
 function offerHereIfSessionsExist(dir) {
-    const claudeHome = process.env.CLAUDE_HOME ?? path.join(os.homedir(), ".claude");
+    // The USER's own home, always: this is looking for `claude` history they made
+    // in a terminal, which is by definition in `~/.claude` and never in paddock's.
+    const claudeHome = path.join(os.homedir(), ".claude");
     let sessions = 0;
     try {
         sessions = countClaudeSessions(claudeHome, dir);
@@ -204,6 +213,13 @@ async function main() {
     // is `.git`. A flagless run anywhere else touches nothing.
     const resuming = !opts.here && isHereWorkspace(cwd);
     const hereMode = opts.here || resuming;
+    // No Claude-home choice happens here any more (#691). The CLI used to point
+    // `CLAUDE_HOME` at `~/.claude` so a macOS Keychain login would be visible
+    // (#683); paddock now always owns its home, and what a user actually wanted
+    // from that — shared transcripts, shared login — are separate `claude:` config
+    // keys. `claude.credentials` restores the Keychain half and defaults to `host`,
+    // so a Mac whose only login is a `claude /login` still works out of the box
+    // with no flag: see `claude-credentials.ts`.
     // Apply CLI defaults as env vars. This is the whole integration surface: the
     // server resolves config inside `buildApp()`, so anything set before the
     // dynamic import below is picked up with no special-casing in config.ts.
@@ -239,19 +255,27 @@ async function main() {
     //                      `[fleet-manager] …` lines via console.info — pino's
     //                      level cannot reach those.
     // An explicit value for either is left alone, and `--verbose` skips both.
+    // A LEVEL is not enough, which is what #684 was about. Background job failures
+    // are logged at `error` — level 50, above every threshold either variable can
+    // set — and one of them is a bare `console.error` inside the engine. So quiet
+    // mode is also stated as a fact the server can act on: `agent-errors.ts` reads
+    // this to collapse a recognised, non-fatal failure to its cause instead of
+    // printing a stack trace with 2 KB of system prompt in it. Internal to the
+    // CLI; `--verbose` leaves it unset and nothing is suppressed.
     if (!opts.verbose) {
         if (process.env.LOG_LEVEL === undefined)
             process.env.LOG_LEVEL = "warn";
         if (process.env.HERDCTL_LOG_LEVEL === undefined)
             process.env.HERDCTL_LOG_LEVEL = "warn";
+        process.env.PADDOCK_QUIET = "1";
     }
     // No credential preflight here: `ensureClaudeHome` (claude-home.ts) already
     // warns at boot, and it is the only check that can be right. It tests the home
-    // paddock will ACTUALLY use — `<dataDir>/claude-home` since #620 — after the
-    // bridge has symlinked in any `~/.claude/.credentials.json`, and its remedy
-    // names the `CLAUDE_CONFIG_DIR` keychain scoping that is the real reason a
-    // logged-in user can still land with no credentials. It logs at `warn`, which
-    // survives the quiet default set just above.
+    // paddock will ACTUALLY use — after the bridge has symlinked in any
+    // `~/.claude/.credentials.json`, and, on darwin, after probing the Keychain for
+    // the login `CLAUDE_CONFIG_DIR` scoping hides (#683). It logs at `warn`, which
+    // survives the quiet default set just above. Continuity (chosen above) usually
+    // means it has nothing to say, because there is nothing left to bridge.
     const port = process.env.PORT ?? "4000";
     const host = process.env.HOST ?? "127.0.0.1";
     // Imported dynamically, AFTER the env above is set: a static import would

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

@@ -1,4 +1,10 @@
 import { type DriveMode } from "./models.js";
+import { type TranscriptsMode } from "./transcripts.js";
+import { type CredentialsMode } from "./claude-credentials.js";
+import { type InstructionsMode } from "./claude-instructions.js";
+import { type HooksMode } from "./claude-settings.js";
+import { type McpServersMode, type McpServerDefs } from "./claude-mcp.js";
+import { type McpServersConfigFile } from "./mcp-servers.js";
 import { type RecoveryConfig } from "./recovery-config.js";
 import { type CurationConfig } from "./curation-config.js";
 import { type ManagementApiConfig, type ManagementApiConfigFile } from "./management-config.js";
@@ -62,6 +68,75 @@ export interface BrandConfig {
     /** Accent color as a hex string driving the primary buttons + logo chip. */
     accent: string;
 }
+/**
+ * What this instance shares with the host machine's Claude Code (#691).
+ *
+ * One key per concern, one vocabulary: `own` is paddock's, isolated inside the
+ * data dir; `host` is this machine's Claude Code. `own` everywhere is the
+ * guarantee an operator should be able to read straight off the config file —
+ * **nothing outside the data dir is read or written**.
+ *
+ * All five levers of #691's sequence now exist. Each is a key here rather than
+ * another meaning welded onto the Claude home, which is how the three incidents
+ * (#682, #683, #689) that motivated this all happened. What remains of #691 is
+ * step 6 — a place for a user to declare their OWN MCP servers, which is a
+ * different question from whose existing ones this instance borrows.
+ */
+export interface ClaudeConfig {
+    /**
+     * Whose session transcripts this instance uses. `own` (default) keeps them in
+     * each project's `.chats/`; `host` shares the user's real
+     * `~/.claude/projects/<encoded-cwd>/` folder live, in both directions.
+     *
+     * Driven by `PADDOCK_CLAUDE_TRANSCRIPTS`, then the `claude.transcripts:` key.
+     * See `transcripts.ts` for the mechanism and why it is not a repointed
+     * `CLAUDE_CONFIG_DIR`.
+     */
+    transcripts: TranscriptsMode;
+    /**
+     * Whose Claude Code login this instance uses. `host` (the default, and the ONE
+     * key that does not default to `own`) also reads this machine's own login — the
+     * macOS Keychain entry on darwin, the user's `~/.claude/.credentials.json`
+     * elsewhere; `own` uses only what is inside paddock's own Claude home.
+     *
+     * Driven by `PADDOCK_CLAUDE_CREDENTIALS`, then the `claude.credentials:` key.
+     * See `claude-credentials.ts` for the mechanism, and for why sharing a login is
+     * the safe default when everything else here isolates.
+     */
+    credentials: CredentialsMode;
+    /**
+     * Whose user-level instructions this instance loads — the user's `~/.claude`
+     * `CLAUDE.md`, `agents/`, `commands/` and `plugins/`. `own` (default) loads
+     * none of them; `host` symlinks them in, which is what every version before
+     * this one did unconditionally.
+     *
+     * Driven by `PADDOCK_CLAUDE_INSTRUCTIONS`, then the `claude.instructions:` key.
+     * See `claude-instructions.ts` — including the case AGAINST this default,
+     * which is real and is kept there rather than deleted.
+     */
+    instructions: InstructionsMode;
+    /**
+     * Whether this instance runs the host machine's Claude Code hooks — shell
+     * commands `~/.claude/settings.json` binds to tool use and session lifecycle.
+     * `own` (default) writes paddock's own `settings.json` carrying every other key
+     * of the user's with `hooks` dropped; `host` symlinks theirs in whole.
+     *
+     * Driven by `PADDOCK_CLAUDE_HOOKS`, then the `claude.hooks:` key. The one lever
+     * here that governs code execution rather than data — see `claude-settings.ts`.
+     */
+    hooks: HooksMode;
+    /**
+     * Whose MCP servers this instance's keepers get. `own` (default) attaches only
+     * the servers paddock itself provides; `host` also attaches the ones declared
+     * in the user's `~/.claude.json` — the top-level `mcpServers` plus any scoped
+     * to a project's own working directory.
+     *
+     * Driven by `PADDOCK_CLAUDE_MCP_SERVERS`, then the `claude.mcpServers:` key.
+     * The one lever whose source is NOT inside `~/.claude` — see `claude-mcp.ts`
+     * for why that made it break silently and separately from the other four.
+     */
+    mcpServers: McpServersMode;
+}
 /** OpenAPI / Swagger-UI reference surface config (see PaddockConfig.openapi). */
 export interface OpenApiConfig {
     /** Mount the `/open-api` UI + `/open-api.json` spec. Opt-in — defaults false. */
@@ -96,8 +171,9 @@ export interface PaddockConfig {
     /**
      * Absolute path to the Claude home THIS INSTANCE owns — the directory whose
      * `projects/<encoded-cwd>/` folders hold Claude Code's session transcripts.
-     * Defaults to `<dataDir>/claude-home` (#620); see {@link resolveClaudeHome}
-     * for the full precedence.
+     * `<dataDir>/claude-home` unless an operator relocates it; paddock ALWAYS owns
+     * it (#691) and refuses to start if it resolves to the user's own `~/.claude`.
+     * See {@link resolveClaudeHome}.
      *
      * Resolved ONCE here (#588) rather than re-read from `process.env` at each call
      * site, because it must be the SAME value everywhere: paddock's transcript
@@ -123,19 +199,15 @@ export interface PaddockConfig {
      */
     legacyClaudeHome: string;
     /**
-     * Does paddock OWN {@link claudeHome} — i.e. is it something other than the
-     * user's `~/.claude`?
+     * What this instance shares with the host's Claude Code (#691) — currently
+     * just `transcripts`. See {@link ClaudeConfig}.
      *
-     * The single gate on every mutating transcript operation (#620). Paddock's
-     * self-healing relocation is allowed to migrate a stray real transcript
-     * directory into `.chats/` inside a home it owns, because that directory is
-     * its own doing. Inside the user's home it is somebody else's data — a
-     * `claude` CLI session run in a directory paddock happens to also manage — and
-     * moving it is the destructive behaviour this flag exists to prevent.
-     *
-     * Derived, not configured: `resolve(claudeHome) !== resolve(legacyClaudeHome)`.
+     * Replaces the derived `ownsClaudeHome` flag, which was the single lever every
+     * distinct concern hung off. Paddock now always owns its home, so "may we
+     * write here?" has one answer and the question that actually varies — whose
+     * transcripts these are — is asked directly.
      */
-    ownsClaudeHome: boolean;
+    claude: ClaudeConfig;
     /** Provider-agnostic user-authentication config (see AUTH.md). */
     auth: AuthConfig;
     /** Voice-dictation (Whisper) capability (per-instance; default off). */
@@ -288,6 +360,31 @@ export interface PaddockConfig {
         errors: string[];
         warnings: string[];
     };
+    /**
+     * MCP servers this instance declares for itself (#691 step 6), resolved from
+     * the top-level `mcpServers:` block with every `env:VAR_NAME` reference read
+     * from the environment. Every project's keeper is attached all of them, and
+     * they win a name collision against anything inherited via
+     * `claude.mcpServers: host`.
+     *
+     * **Holds resolved secret material** — an MCP server's `env` is where a stdio
+     * server's API token lives — exactly as {@link managementApi}'s client tokens
+     * do. It must never be serialised into an API response; `instance-config.ts`
+     * publishes only the fields in its own `FIELDS` table, and this is
+     * deliberately not one of them.
+     */
+    mcpServers: McpServerDefs;
+    /**
+     * Operator-facing problems found while resolving {@link mcpServers}: a
+     * declaration paddock cannot carry (`errors`, server dropped) or one whose
+     * `env:` reference did not resolve / whose secret is inlined (`warnings`).
+     * Carried, not logged, for the same reason as
+     * {@link managementApiDiagnostics}. Never contains a value from the block.
+     */
+    mcpServersDiagnostics: {
+        errors: string[];
+        warnings: string[];
+    };
     /**
      * Instance default for the hook-management MCP (Epic G / G5, GG-4) — the
      * `mcp__paddock_manage__{list,set,remove}_hook` tools that let a project agent
@@ -385,8 +482,31 @@ export interface PaddockConfigFile {
     stateDir?: string;
     herdctlConfigPath?: string;
     webDist?: string;
-    /** Claude home override; beneath `CLAUDE_HOME`/`CLAUDE_CONFIG_DIR` (#620). */
+    /** Where paddock's OWN Claude home lives; beneath `CLAUDE_CONFIG_DIR` (#691). */
     claudeHome?: string;
+    /**
+     * What this instance shares with the host's Claude Code (#691). Each key takes
+     * `own` or `host`; a matching `PADDOCK_CLAUDE_*` env var still overrides it
+     * (file < env). Absent ⇒ fully isolated.
+     */
+    claude?: {
+        transcripts?: string;
+        credentials?: string;
+        instructions?: string;
+        hooks?: string;
+        mcpServers?: string;
+    };
+    /**
+     * MCP servers this instance declares for ITSELF (#691 step 6) — a sibling of
+     * `claude:`, not a member of it, because it answers a different question:
+     * `claude.mcpServers` borrows whatever this machine already has, while this
+     * says what paddock should have regardless.
+     *
+     * File-only, like `managementApi`: a map of servers does not express as a
+     * scalar env var. Token material belongs in the environment and is referenced
+     * as `env:VAR_NAME` from any string here — see `mcp-servers.ts`.
+     */
+    mcpServers?: McpServersConfigFile;
     auth?: {
         mode?: string;
         userHeader?: string;
@@ -561,35 +681,43 @@ export declare function loadPaddockConfig(): PaddockConfig;
  */
 export declare function userClaudeHome(): string;
 /**
- * Resolve the Claude home paddock runs its agents against.
+ * Resolve where paddock's OWN Claude home lives.
  *
  * Precedence, highest first:
  *
- * 1. **`CLAUDE_HOME`** — paddock's own long-standing override. Setting it to
- *    `$HOME/.claude` restores the pre-#620 behaviour exactly, which is the
- *    documented escape hatch if the relocation causes trouble.
- * 2. **`CLAUDE_CONFIG_DIR`** — the variable *Claude Code itself* resolves its
+ * 1. **`CLAUDE_CONFIG_DIR`** — the variable *Claude Code itself* resolves its
  *    home from. Honouring it is load-bearing, not a courtesy: herdctl
  *    deliberately refuses to clobber an operator-set `CLAUDE_CONFIG_DIR`
  *    (herdctl#423), so if paddock picked a different home the SDK would write
  *    transcripts to one tree while herdctl read from another — the exact
  *    split-brain #588 fixed. Deferring to it makes that state unreachable.
- * 3. A `claudeHome:` key in the instance config file.
- * 4. **`<dataDir>/claude-home`** — the default since #620.
+ * 2. A `claudeHome:` key in the instance config file.
+ * 3. **`<dataDir>/claude-home`** — the default.
  *
- * On the default, and why it changed: paddock already nests herdctl's whole
- * state dir, the projects tree and the generated `herdctl.yaml` under its data
- * dir. Transcripts were the one exception, reached by planting symlinks in the
- * user's home — not a design choice but a constraint, because until
- * herdctl#423 nothing set `CLAUDE_CONFIG_DIR` and the SDK wrote to `~/.claude`
- * no matter what paddock configured. With that gone, owning the home makes the
- * data dir relocatable as a unit, leaves `~/.claude` alone, and (because there
- * is no longer a `.claude` path component) unblocks agent memory writes, which
- * the harness refuses for any path containing `.claude`.
+ * ## Paddock always OWNS this home, and the one value it refuses
+ *
+ * `CLAUDE_HOME` used to sit above all of this, and setting it to `~/.claude` was
+ * the documented escape hatch back to the pre-#620 layout. It is gone (#691),
+ * because pointing the home at the user's own directory is what welded five
+ * unrelated concerns to one lever: it decided whose transcripts were at risk,
+ * which keychain entry was visible, where agent memory landed, and whether
+ * delete meant delete. Those are now separate keys (`claude:`), so the home no
+ * longer needs to move for any of them.
+ *
+ * Which leaves exactly one value that must not be allowed through, from any
+ * source: the user's own `~/.claude`. It re-welds the lever, and it re-breaks
+ * agent memory (#690) — the memory dir is `<claudeHome>/projects/<enc>/memory`,
+ * and the agent harness refuses to write to any path with a `.claude` component.
+ * So it REFUSES TO START rather than silently degrading, which is the same
+ * fail-closed shape as the bind-safety guard. `CLAUDE_CONFIG_DIR` cannot simply
+ * be ignored instead: it is Claude Code's own variable, and disagreeing with an
+ * operator-set value is the herdctl#423 split-brain again.
  *
  * NOT canonical()-ed: this exact string is what herdctl hands Claude Code as
  * `CLAUDE_CONFIG_DIR`, and canonicalising would silently diverge from the
  * literal path the two of them encode into `<home>/projects/<encoded-cwd>`.
+ * The refusal check DOES resolve both sides, so a symlinked or trailing-slash
+ * spelling of `~/.claude` cannot slip past it.
  *
  * This is the RESOLVER, not the accessor. It is read once by
  * {@link loadPaddockConfig} into {@link PaddockConfig.claudeHome}; runtime code
@@ -597,5 +725,13 @@ export declare function userClaudeHome(): string;
  * engine can never end up resolving two different homes (#588).
  */
 export declare function resolveClaudeHome(dataDir: string, fromFile?: string): string;
+/**
+ * Why `home` is unusable as paddock's own Claude home, or `undefined` if it is
+ * fine. Pure, so the whole decision is testable without touching `$HOME`.
+ *
+ * `fromEnv` only changes which fix is named first — the refusal itself is the
+ * same whichever layer supplied the value.
+ */
+export declare function claudeHomeRefusal(home: string, userHome: string, fromEnv: boolean): string | undefined;
 /** Directory name of paddock's own Claude home inside the data dir (#620). */
 export declare const DEFAULT_CLAUDE_HOME_DIRNAME = "claude-home";