@edspencer/paddock 0.61.0 → 0.62.0

package/packages/server/dist/config.js

@@ -24,6 +24,12 @@ import { fileURLToPath } from "node:url";
 import YAML from "yaml";
 import { DEFAULT_DRIVE_MODE, isKnownDriveMode, isKnownModel, } from "./models.js";
 import { DEFAULT_MAX_SPAWN_DEPTH, isValidMaxSpawnDepth } from "./spawn-capability.js";
+import { DEFAULT_TRANSCRIPTS_MODE, isKnownTranscriptsMode, } from "./transcripts.js";
+import { DEFAULT_CREDENTIALS_MODE, isKnownCredentialsMode, } from "./claude-credentials.js";
+import { DEFAULT_INSTRUCTIONS_MODE, isKnownInstructionsMode, } from "./claude-instructions.js";
+import { DEFAULT_HOOKS_MODE, isKnownHooksMode } from "./claude-settings.js";
+import { DEFAULT_MCP_SERVERS_MODE, isKnownMcpServersMode, } from "./claude-mcp.js";
+import { resolveDeclaredMcpServers } from "./mcp-servers.js";
 import { DEFAULT_ENVIRONMENT_PROMPT } from "./environment-prompt.js";
 import { DEFAULT_RECOVERY } from "./recovery-config.js";
 import { DEFAULT_CURATION } from "./curation-config.js";
@@ -286,10 +292,7 @@ export function loadPaddockConfig() {
         webDist: abs(envOr("PADDOCK_WEB_DIST", fileOr(file.webDist, defaultWebDist))),
         claudeHome: resolvedClaudeHome,
         legacyClaudeHome,
-        // Paddock owns any home that is not the user's own `~/.claude` (#620) —
-        // including one an operator pointed it at explicitly. The user's home is the
-        // only one whose contents belong to somebody else.
-        ownsClaudeHome: path.resolve(resolvedClaudeHome) !== path.resolve(legacyClaudeHome),
+        claude: loadClaudeConfig(file.claude),
         auth: loadAuthConfig(file.auth),
         transcription: loadTranscriptionConfig(file.transcription),
         brand: loadBrandConfig(file.brand),
@@ -312,6 +315,13 @@ export function loadPaddockConfig() {
             const { config, errors, warnings } = resolveManagementApiConfig(file.managementApi, process.env);
             return { managementApi: config, managementApiDiagnostics: { errors, warnings } };
         })(),
+        ...(() => {
+            // #691 step 6: file-only, and resolved against the real environment because
+            // any string in the block may be an `env:VAR_NAME` reference. Diagnostics
+            // ride along for app.ts to log — they never carry a resolved value.
+            const { servers, errors, warnings } = resolveDeclaredMcpServers(file.mcpServers, process.env);
+            return { mcpServers: servers, mcpServersDiagnostics: { errors, warnings } };
+        })(),
         hooksMcpEnabled: loadHooksMcpEnabled(file.hooksMcpEnabled),
         recovery: loadRecoveryConfig(file.recovery),
         attachments: loadAttachmentsConfig(file.attachments),
@@ -625,35 +635,78 @@ export function userClaudeHome() {
     return path.join(os.homedir(), ".claude");
 }
 /**
- * Resolve the Claude home paddock runs its agents against.
+ * Resolve what this instance shares with the host's Claude Code (#691).
+ *
+ * Precedence is the file's usual env > file > default. An unrecognised value
+ * falls back to the default rather than failing the boot — the same rule every
+ * other enum here follows (`driveMode`, whisper `mode`). For `transcripts` that
+ * is also the safe direction: a typo isolates rather than silently sharing the
+ * user's files. For `credentials` the default is `host` and a typo therefore
+ * falls back to sharing — deliberately, because the failure it avoids (#683: an
+ * instance that boots clean and fails every turn) is the worse one, and reading a
+ * login risks no file of the user's. See `claude-credentials.ts`.
+ *
+ * `hooks` is the one where falling back on a typo is load-bearing in the other
+ * direction: `PADDOCK_CLAUDE_HOOKS=hots` isolates rather than executing the
+ * host's shell commands, which is the only acceptable way for a security lever
+ * to misread its input. `mcpServers` follows the same direction for a weaker
+ * reason — an MCP server is a process paddock spawns, so a typo that attaches
+ * nothing is better than one that attaches the user's whole set unasked.
+ */
+function loadClaudeConfig(file = {}) {
+    const transcripts = (envOpt("PADDOCK_CLAUDE_TRANSCRIPTS") ?? fileOpt(file.transcripts))?.toLowerCase();
+    const credentials = (envOpt("PADDOCK_CLAUDE_CREDENTIALS") ?? fileOpt(file.credentials))?.toLowerCase();
+    const instructions = (envOpt("PADDOCK_CLAUDE_INSTRUCTIONS") ?? fileOpt(file.instructions))?.toLowerCase();
+    const hooks = (envOpt("PADDOCK_CLAUDE_HOOKS") ?? fileOpt(file.hooks))?.toLowerCase();
+    const mcpServers = (envOpt("PADDOCK_CLAUDE_MCP_SERVERS") ?? fileOpt(file.mcpServers))?.toLowerCase();
+    return {
+        transcripts: transcripts && isKnownTranscriptsMode(transcripts) ? transcripts : DEFAULT_TRANSCRIPTS_MODE,
+        credentials: credentials && isKnownCredentialsMode(credentials) ? credentials : DEFAULT_CREDENTIALS_MODE,
+        instructions: instructions && isKnownInstructionsMode(instructions)
+            ? instructions
+            : DEFAULT_INSTRUCTIONS_MODE,
+        hooks: hooks && isKnownHooksMode(hooks) ? hooks : DEFAULT_HOOKS_MODE,
+        mcpServers: mcpServers && isKnownMcpServersMode(mcpServers) ? mcpServers : DEFAULT_MCP_SERVERS_MODE,
+    };
+}
+/**
+ * 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
@@ -661,12 +714,39 @@ export function userClaudeHome() {
  * engine can never end up resolving two different homes (#588).
  */
 export function resolveClaudeHome(dataDir, fromFile) {
-    const env = envOpt("CLAUDE_HOME") ?? envOpt("CLAUDE_CONFIG_DIR");
-    if (env !== undefined)
-        return abs(env);
-    if (fromFile !== undefined && fromFile !== "")
-        return abs(fromFile);
-    return path.join(dataDir, DEFAULT_CLAUDE_HOME_DIRNAME);
+    const env = envOpt("CLAUDE_CONFIG_DIR");
+    const home = env !== undefined
+        ? abs(env)
+        : fromFile !== undefined && fromFile !== ""
+            ? abs(fromFile)
+            : path.join(dataDir, DEFAULT_CLAUDE_HOME_DIRNAME);
+    const refusal = claudeHomeRefusal(home, userClaudeHome(), env !== undefined);
+    if (refusal !== undefined)
+        throw new Error(refusal);
+    return home;
+}
+/**
+ * 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 function claudeHomeRefusal(home, userHome, fromEnv) {
+    if (path.resolve(home) !== path.resolve(userHome))
+        return undefined;
+    return (`refusing to start: the Claude home resolves to your own ${userHome}, which paddock ` +
+        `must not run as its own home. It re-couples everything paddock keeps separate — ` +
+        `whose transcripts a delete removes, which login is visible, where agent memory is ` +
+        `written (agents cannot write under a \`.claude\` path at all, #690). ` +
+        (fromEnv
+            ? `CLAUDE_CONFIG_DIR is what points it there: unset it, or point it at a directory ` +
+                `of paddock's own. `
+            : `The \`claudeHome:\` key in paddock.config.yaml points it there: remove it, or name a ` +
+                `directory of paddock's own. `) +
+        `To SHARE your Claude Code transcripts, set \`claude: { transcripts: host }\` (or ` +
+        `PADDOCK_CLAUDE_TRANSCRIPTS=host) — that shares the files themselves and keeps ` +
+        `paddock's home where it belongs.`);
 }
 /** Directory name of paddock's own Claude home inside the data dir (#620). */
 export const DEFAULT_CLAUDE_HOME_DIRNAME = "claude-home";

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

@@ -1,5 +1,6 @@
 import type { PaddockConfig } from "./config.js";
 import type { Project } from "./projects.js";
+import { type McpSources } from "./claude-mcp.js";
 import { type PaddockTrigger } from "./trigger-config.js";
 /**
  * A project's keeper agent config. Inherits the fleet `defaults` (runtime,
@@ -24,8 +25,17 @@ import { type PaddockTrigger } from "./trigger-config.js";
  * not `<dataDir>`: `projectsRoot` IS the instance's backing repo, so the file is
  * version-controlled. Since #516 the ROOT project reaches it the same way —
  * its cwd IS `projectsRoot`, so the walk-up needs no special-casing.
+ *
+ * `mcpSources` is the external MCP servers this instance attaches — the user's
+ * own under `claude.mcpServers: host` (#691 step 5) plus the ones the instance
+ * declares in its own `mcpServers:` block (step 6). Both are resolved once at
+ * boot and passed in rather than re-read here, so this stays pure and so a
+ * `.claude.json` is never opened under `mcpServers: own`. It defaults to empty,
+ * which is both the isolated mode and what every existing caller means. The
+ * KEEPER is the only agent that gets them: the sweeper is tool-less and each
+ * trigger declares its own narrow allowlist, so neither could call one anyway.
  */
-export declare function buildAgentConfig(cfg: PaddockConfig, project: Project, modelOverride?: string): Record<string, unknown> & {
+export declare function buildAgentConfig(cfg: PaddockConfig, project: Project, modelOverride?: string, mcpSources?: McpSources): Record<string, unknown> & {
     name: string;
 };
 /**

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

@@ -13,9 +13,10 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import YAML from "yaml";
+import { EMPTY_MCP_SOURCES, mcpServersFor, mcpToolPattern, } from "./claude-mcp.js";
 import { DEFAULT_MODEL, SWEEPER_DEFAULT_MODEL, DEFAULT_PERMISSION_MODE, DEFAULT_MAX_TURNS, } from "./models.js";
 import { triggerToAgentToolConfig, triggersToHerdctlSchedules, curatorTriggerOf, } from "./trigger-config.js";
-import { keeperAgentName, sweeperAgentName, triggerAgentName, browserMcpServers, BROWSER_MCP_TOOL, DENIED_TOOLS, KEEPER_MAX_CONCURRENT, KEEPER_SESSION_TIMEOUT, } from "./herdctl-agent-names.js";
+import { keeperAgentName, sweeperAgentName, triggerAgentName, browserMcpServers, FLEET_ALLOWED_TOOLS, DENIED_TOOLS, KEEPER_MAX_CONCURRENT, KEEPER_SESSION_TIMEOUT, } from "./herdctl-agent-names.js";
 /**
  * A project's keeper agent config. Inherits the fleet `defaults` (runtime,
  * max_turns, permission_mode, allowed/denied tools) via addAgent's deep-merge;
@@ -39,8 +40,17 @@ import { keeperAgentName, sweeperAgentName, triggerAgentName, browserMcpServers,
  * not `<dataDir>`: `projectsRoot` IS the instance's backing repo, so the file is
  * version-controlled. Since #516 the ROOT project reaches it the same way —
  * its cwd IS `projectsRoot`, so the walk-up needs no special-casing.
+ *
+ * `mcpSources` is the external MCP servers this instance attaches — the user's
+ * own under `claude.mcpServers: host` (#691 step 5) plus the ones the instance
+ * declares in its own `mcpServers:` block (step 6). Both are resolved once at
+ * boot and passed in rather than re-read here, so this stays pure and so a
+ * `.claude.json` is never opened under `mcpServers: own`. It defaults to empty,
+ * which is both the isolated mode and what every existing caller means. The
+ * KEEPER is the only agent that gets them: the sweeper is tool-less and each
+ * trigger declares its own narrow allowlist, so neither could call one anyway.
  */
-export function buildAgentConfig(cfg, project, modelOverride) {
+export function buildAgentConfig(cfg, project, modelOverride, mcpSources = EMPTY_MCP_SOURCES) {
     const config = {
         name: keeperAgentName(project.slug),
         description: project.summary || `Claude Code agent for project ${project.name}.`,
@@ -101,11 +111,42 @@ export function buildAgentConfig(cfg, project, modelOverride) {
     const schedules = triggersToHerdctlSchedules(project.triggers);
     if (schedules)
         config.schedules = schedules;
-    // Browser MCP (headless Chromium) when enabled for this box; `mcp__playwright__*`
-    // is already on the inherited defaults.allowed_tools.
+    // MCP servers, from three sources, all landing on the SAME `mcp_servers` key:
+    //
+    //  - the browser MCP (headless Chromium) when enabled for this box —
+    //    `mcp__playwright__*` is already on the inherited defaults.allowed_tools;
+    //  - the user's own servers under `claude.mcpServers: host` (#691 step 5);
+    //  - the ones this instance declares in its own `mcpServers:` block (#691 step
+    //    6), which win over the inherited ones (`mcpServersFor` merges them last).
+    //
+    // Neither of the latter two is on the default allowlist, because their names are
+    // not knowable at config-file-write time — hence the widening below.
+    //
+    // Paddock's own server still wins a name collision, against BOTH: its flags are
+    // box-specific (the Ansible-installed chromium engine, --no-sandbox for an
+    // unprivileged LXC) and someone else's `playwright` would almost certainly not
+    // start here. A declared collision is warned about by name at boot
+    // (`declaredMcpNotices`) so it is not silent.
     const browser = browserMcpServers(cfg.browserMcp);
-    if (browser)
-        config.mcp_servers = browser;
+    const external = mcpServersFor(mcpSources, project.workingDir);
+    const servers = { ...external, ...(browser ?? {}) };
+    if (Object.keys(servers).length > 0)
+        config.mcp_servers = servers;
+    // Widen the allowlist by exactly those servers' tool patterns. WITHOUT this
+    // both levers are a no-op with no error: both runtimes auto-deny any tool
+    // missing from an explicit `allowed_tools`, so an attached-but-unlisted server
+    // connects and then has every call refused. herdctl does this automatically for
+    // INJECTED servers only (`cli-runtime.js`), never for config `mcp_servers` —
+    // which is why `mcp__playwright__*` is hard-coded into the defaults.
+    //
+    // Patterns already on the defaults are filtered out, so nothing is restated
+    // for an instance with no external servers (or one whose only server paddock's
+    // own overrode above) — that config stays byte-identical to before this lever.
+    const extra = Object.keys(external)
+        .map(mcpToolPattern)
+        .filter((pattern) => !FLEET_ALLOWED_TOOLS.includes(pattern));
+    if (extra.length > 0)
+        config.allowed_tools = [...FLEET_ALLOWED_TOOLS, ...extra];
     return config;
 }
 /**
@@ -330,7 +371,12 @@ export async function ensureConfigFile(cfg) {
             // several of these surface as deferred tools reached through it. These
             // only actually DO anything in session drive-mode (the reaper re-fires
             // them); in batch mode they're inert (documented in the box CLAUDE.md).
-            allowed_tools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep", "WebFetch", "WebSearch", "Task", "TodoWrite", "Skill", "NotebookEdit", "ToolSearch", "ScheduleWakeup", "Monitor", "CronCreate", "CronList", "CronDelete", BROWSER_MCP_TOOL],
+            // The list itself lives in `herdctl-agent-names.ts` as FLEET_ALLOWED_TOOLS,
+            // because a keeper with host MCP servers attached (#691 step 5) has to
+            // restate it plus their `mcp__<server>__*` patterns — herdctl's
+            // `mergeAgentConfig` REPLACES arrays rather than merging them, so an agent
+            // that widens the allowlist inherits nothing from here.
+            allowed_tools: [...FLEET_ALLOWED_TOOLS],
             // Best-effort denylist (#179): narrow, honest catastrophic-wipe patterns
             // that do NOT block legitimate absolute-path cleanup. See DENIED_TOOLS.
             denied_tools: [...DENIED_TOOLS],

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

@@ -100,6 +100,17 @@ export declare function visibleProjectAgentNames(project: Project): string[];
  * no-op.
  */
 export declare const BROWSER_MCP_TOOL = "mcp__playwright__*";
+/**
+ * The fleet-wide `defaults.allowed_tools` a keeper inherits.
+ *
+ * Extracted from `ensureConfigFile` — where the reasoning for each entry still
+ * lives — because `claude.mcpServers: host` (#691 step 5) has to hand a keeper
+ * this list PLUS one `mcp__<server>__*` pattern per attached host server. Arrays
+ * are replaced rather than merged by herdctl's `mergeAgentConfig`, so widening
+ * the allowlist per-agent means restating the defaults, and restating them means
+ * they can only be written down once.
+ */
+export declare const FLEET_ALLOWED_TOOLS: readonly string[];
 /**
  * The keeper's default `denied_tools` — a **best-effort, defence-in-depth**
  * denylist, NOT a sandbox. Real isolation (per-agent filesystem confinement)

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

@@ -116,6 +116,37 @@ export function visibleProjectAgentNames(project) {
  * no-op.
  */
 export const BROWSER_MCP_TOOL = "mcp__playwright__*";
+/**
+ * The fleet-wide `defaults.allowed_tools` a keeper inherits.
+ *
+ * Extracted from `ensureConfigFile` — where the reasoning for each entry still
+ * lives — because `claude.mcpServers: host` (#691 step 5) has to hand a keeper
+ * this list PLUS one `mcp__<server>__*` pattern per attached host server. Arrays
+ * are replaced rather than merged by herdctl's `mergeAgentConfig`, so widening
+ * the allowlist per-agent means restating the defaults, and restating them means
+ * they can only be written down once.
+ */
+export const FLEET_ALLOWED_TOOLS = [
+    "Read",
+    "Edit",
+    "Write",
+    "Bash",
+    "Glob",
+    "Grep",
+    "WebFetch",
+    "WebSearch",
+    "Task",
+    "TodoWrite",
+    "Skill",
+    "NotebookEdit",
+    "ToolSearch",
+    "ScheduleWakeup",
+    "Monitor",
+    "CronCreate",
+    "CronList",
+    "CronDelete",
+    BROWSER_MCP_TOOL,
+];
 /**
  * The keeper's default `denied_tools` — a **best-effort, defence-in-depth**
  * denylist, NOT a sandbox. Real isolation (per-agent filesystem confinement)

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

@@ -50,6 +50,7 @@ import { FleetManager, type DiscoveredSession, type ChatMessage, type SDKMessage
 import type { PaddockConfig } from "./config.js";
 import type { Project } from "./projects.js";
 import { type PaddockTrigger } from "./trigger-config.js";
+import { type McpSources } from "./claude-mcp.js";
 import { type AdoptableSummary, type FilterReason } from "./adoptable.js";
 /**
  * One session an import did NOT bring in, with a reason a UI can show verbatim.
@@ -63,6 +64,20 @@ export type AdoptSkipped = AdoptSkippedSession | {
     reason: FilterReason;
     detail?: string;
 };
+/**
+ * Outcome of deleting a chat (#689).
+ *
+ * Two fields rather than one boolean because "the transcript is gone" and "the
+ * chat is no longer listed here" stopped being the same thing: in a home paddock
+ * does not own, the file belongs to the user's terminal `claude` and is released
+ * rather than removed. See {@link HerdctlService.deleteSession}.
+ */
+export interface ChatDeletion {
+    /** A transcript file was unlinked. False when none existed, or when retained. */
+    removed: boolean;
+    /** The transcript was deliberately left on disk because it is not paddock's. */
+    retained: boolean;
+}
 /** Options passed through to a streamed trigger. */
 export interface ChatTurnOptions {
     prompt: string;
@@ -105,6 +120,7 @@ export { keeperAgentName, keeperSlugFromAgent, SWEEPER_PREFIX, sweeperAgentName,
 export declare function sliceTranscriptAtUuid(raw: string, cutUuid: string, endOnCompletedAssistant?: boolean): string | null;
 export declare class HerdctlService {
     private readonly cfg;
+    private readonly mcpSources;
     private fleet;
     private started;
     /**
@@ -164,13 +180,27 @@ export declare class HerdctlService {
      */
     private jobsIndexOrNull;
     private get jobsIndex();
-    constructor(cfg: PaddockConfig);
     /**
-     * The Claude home every transcript symlink is planted in, plus whether paddock
-     * owns it (#620). One accessor, so no call site can quietly take a default and
-     * land in a different home than the FleetManager was built with — the bug
-     * `ensureSweeperHome` had, which put the sweeper's symlink in `~/.claude` while
-     * every other agent's went to the configured home.
+     * The external MCP servers every keeper gets: the user's own under
+     * `claude.mcpServers: host` (#691 step 5, read once at boot by
+     * `loadHostMcpSource`) plus the ones this instance declares in its own
+     * `mcpServers:` block (step 6, resolved during config load). Both are merged
+     * into one value by `buildApp` and handed in here.
+     *
+     * A constructor argument rather than something this service reads for itself,
+     * for the same reason `ensureClaudeHome` runs in `buildApp`: the read has
+     * notices an operator needs to see in the boot log, and it must not happen at
+     * all under `mcpServers: own`. Defaults to empty so every existing caller —
+     * including the several tests that construct this with `{} as PaddockConfig` —
+     * keeps meaning "isolated".
+     */
+    constructor(cfg: PaddockConfig, mcpSources?: McpSources);
+    /**
+     * The Claude home every transcript symlink is planted in, plus where those
+     * symlinks point (#620, #691). One accessor, so no call site can quietly take
+     * a default and land in a different home than the FleetManager was built with
+     * — the bug `ensureSweeperHome` had, which put the sweeper's symlink in
+     * `~/.claude` while every other agent's went to the configured home.
      */
     private get claudeHomeTarget();
     /**
@@ -421,13 +451,39 @@ export declare class HerdctlService {
      */
     removeProjectAgent(slug: string, hookNames?: string[], triggerNames?: string[]): Promise<void>;
     /**
-     * Delete a single chat (session) by agent name + session id. The FleetManager
-     * resolves the agent's working directory, removes the transcript JSONL, and
-     * invalidates the discovery cache so the list reflects it immediately.
-     * Validates the sessionId (rejects path traversal). Returns true if a
-     * transcript file was removed, false if none existed.
-     */
-    deleteSession(agentName: string, sessionId: string): Promise<boolean>;
+     * Delete a single chat (session) by agent name + session id.
+     *
+     * Under `claude.transcripts: own`, this removes the transcript JSONL: the file
+     * lives in paddock's own tree (via the project's `.chats/` symlink), so it is
+     * ours to delete. The FleetManager resolves the agent's working directory,
+     * unlinks the file, validates the sessionId against traversal, and invalidates
+     * the discovery cache so the list reflects it immediately.
+     *
+     * Under `claude.transcripts: host`, it **releases the session instead** (#689).
+     * There is no copy to delete there: the symlink points OUT at
+     * `~/.claude/projects/<encoded-cwd>/`, so the transcript the agent reads and
+     * writes is the user's own — for an adopted chat, literally their terminal
+     * history. `rm`-ing it destroys history paddock never owned, which is the same
+     * class of mistake #682 was, pointed the other way: that one claimed where
+     * future sessions get written, this one deletes the past ones.
+     *
+     * `undoImport` already draws exactly this line ("A session adopted in place has
+     * no copy, and its transcript is the user's own — removing it would destroy
+     * history rather than restore it"); the invariant simply never reached here.
+     *
+     * The discriminator changed with #691 and the meaning did not. It used to be
+     * `ownsClaudeHome` — "is this home ours?" — which is now always true; the
+     * question that survives is "is this transcript ours?", and that is exactly
+     * what `transcripts` says. Deliberately NOT narrowed to "only adopted chats":
+     * under `host` a chat paddock started itself is in the user's tree too, and
+     * distinguishing them well enough to risk an `rm` is not worth the failure mode
+     * of getting it wrong. The cost is a transcript left behind, which the caller
+     * is told about; the alternative cost is somebody's history.
+     *
+     * The chat leaves paddock's list either way — which is what the user asked for
+     * — so `retained` is how a caller tells "gone" from "no longer shown here".
+     */
+    deleteSession(agentName: string, sessionId: string): Promise<ChatDeletion>;
     /**
      * Set (or clear) a chat's custom display name. Writes through the fleet's
      * shared SessionMetadataStore so a subsequent getAgentSessions reflects it

package/packages/server/dist/herdctl.js

@@ -56,6 +56,7 @@ import { DEFAULT_MODEL } from "./models.js";
 import { ensureProjectChats, projectChatsDir } from "./transcripts.js";
 import { triggerRunsOnOwnAgent, isCuratorTrigger, } from "./trigger-config.js";
 import { buildAgentConfig, buildSweeperConfig, sweeperWorkingDir, buildTriggerConfig, ensureConfigFile as writeBootConfigFile, } from "./herdctl-agent-config.js";
+import { EMPTY_MCP_SOURCES } from "./claude-mcp.js";
 import * as jobs from "./herdctl-jobs.js";
 import { JobsDirIndex } from "./herdctl-jobs-index.js";
 import { AdoptableIndex } from "./adoptable.js";
@@ -162,6 +163,7 @@ export function sliceTranscriptAtUuid(raw, cutUuid, endOnCompletedAssistant = fa
 }
 export class HerdctlService {
     cfg;
+    mcpSources;
     fleet = null;
     started = false;
     /**
@@ -223,18 +225,37 @@ export class HerdctlService {
     get jobsIndex() {
         return (this.jobsIndexOrNull ??= new JobsDirIndex(this.cfg.stateDir));
     }
-    constructor(cfg) {
+    /**
+     * The external MCP servers every keeper gets: the user's own under
+     * `claude.mcpServers: host` (#691 step 5, read once at boot by
+     * `loadHostMcpSource`) plus the ones this instance declares in its own
+     * `mcpServers:` block (step 6, resolved during config load). Both are merged
+     * into one value by `buildApp` and handed in here.
+     *
+     * A constructor argument rather than something this service reads for itself,
+     * for the same reason `ensureClaudeHome` runs in `buildApp`: the read has
+     * notices an operator needs to see in the boot log, and it must not happen at
+     * all under `mcpServers: own`. Defaults to empty so every existing caller —
+     * including the several tests that construct this with `{} as PaddockConfig` —
+     * keeps meaning "isolated".
+     */
+    constructor(cfg, mcpSources = EMPTY_MCP_SOURCES) {
         this.cfg = cfg;
+        this.mcpSources = mcpSources;
     }
     /**
-     * The Claude home every transcript symlink is planted in, plus whether paddock
-     * owns it (#620). One accessor, so no call site can quietly take a default and
-     * land in a different home than the FleetManager was built with — the bug
-     * `ensureSweeperHome` had, which put the sweeper's symlink in `~/.claude` while
-     * every other agent's went to the configured home.
+     * The Claude home every transcript symlink is planted in, plus where those
+     * symlinks point (#620, #691). One accessor, so no call site can quietly take
+     * a default and land in a different home than the FleetManager was built with
+     * — the bug `ensureSweeperHome` had, which put the sweeper's symlink in
+     * `~/.claude` while every other agent's went to the configured home.
      */
     get claudeHomeTarget() {
-        return { path: this.cfg.claudeHome, owned: this.cfg.ownsClaudeHome };
+        return {
+            path: this.cfg.claudeHome,
+            transcripts: this.cfg.claude.transcripts,
+            userHome: this.cfg.legacyClaudeHome,
+        };
     }
     /**
      * The environment system prompt to append to a keeper turn (issue #635), or
@@ -309,10 +330,10 @@ export class HerdctlService {
             allowScheduleMutation: this.cfg.scheduleMutationEnabled,
             // Hand the engine the SAME Claude home paddock resolved (#588). Omitting
             // it makes the engine fall back to `os.homedir()/.claude` while paddock
-            // honours `CLAUDE_HOME`, so discovery, adoption and paddock's `.chats/`
-            // symlinks would resolve against different directories — sessions list
-            // from one home and open empty from the other. Masked whenever the two
-            // coincide, which is why it must be explicit.
+            // uses its own, so discovery, adoption and paddock's transcript symlinks
+            // would resolve against different directories — sessions list from one
+            // home and open empty from the other. Masked whenever the two coincide,
+            // which is why it must be explicit.
             claudeHomePath: this.cfg.claudeHome,
         });
         await this.fleet.initialize();
@@ -763,14 +784,45 @@ export class HerdctlService {
         }
     }
     /**
-     * Delete a single chat (session) by agent name + session id. The FleetManager
-     * resolves the agent's working directory, removes the transcript JSONL, and
-     * invalidates the discovery cache so the list reflects it immediately.
-     * Validates the sessionId (rejects path traversal). Returns true if a
-     * transcript file was removed, false if none existed.
+     * Delete a single chat (session) by agent name + session id.
+     *
+     * Under `claude.transcripts: own`, this removes the transcript JSONL: the file
+     * lives in paddock's own tree (via the project's `.chats/` symlink), so it is
+     * ours to delete. The FleetManager resolves the agent's working directory,
+     * unlinks the file, validates the sessionId against traversal, and invalidates
+     * the discovery cache so the list reflects it immediately.
+     *
+     * Under `claude.transcripts: host`, it **releases the session instead** (#689).
+     * There is no copy to delete there: the symlink points OUT at
+     * `~/.claude/projects/<encoded-cwd>/`, so the transcript the agent reads and
+     * writes is the user's own — for an adopted chat, literally their terminal
+     * history. `rm`-ing it destroys history paddock never owned, which is the same
+     * class of mistake #682 was, pointed the other way: that one claimed where
+     * future sessions get written, this one deletes the past ones.
+     *
+     * `undoImport` already draws exactly this line ("A session adopted in place has
+     * no copy, and its transcript is the user's own — removing it would destroy
+     * history rather than restore it"); the invariant simply never reached here.
+     *
+     * The discriminator changed with #691 and the meaning did not. It used to be
+     * `ownsClaudeHome` — "is this home ours?" — which is now always true; the
+     * question that survives is "is this transcript ours?", and that is exactly
+     * what `transcripts` says. Deliberately NOT narrowed to "only adopted chats":
+     * under `host` a chat paddock started itself is in the user's tree too, and
+     * distinguishing them well enough to risk an `rm` is not worth the failure mode
+     * of getting it wrong. The cost is a transcript left behind, which the caller
+     * is told about; the alternative cost is somebody's history.
+     *
+     * The chat leaves paddock's list either way — which is what the user asked for
+     * — so `retained` is how a caller tells "gone" from "no longer shown here".
      */
     async deleteSession(agentName, sessionId) {
-        return this.manager.deleteSession(agentName, sessionId);
+        if (this.cfg.claude.transcripts === "own") {
+            return { removed: await this.manager.deleteSession(agentName, sessionId), retained: false };
+        }
+        await this.manager.unadoptSession(agentName, sessionId).catch(() => undefined);
+        this.invalidateSessions(agentName);
+        return { removed: false, retained: true };
     }
     /**
      * Set (or clear) a chat's custom display name. Writes through the fleet's
@@ -1456,7 +1508,7 @@ export class HerdctlService {
     // existing unit-test seams (which reach `sweeperAgentConfig`/`ensureConfigFile`
     // via a cast) and internal callers keep working.
     keeperAgentConfig(project, modelOverride) {
-        return buildAgentConfig(this.cfg, project, modelOverride);
+        return buildAgentConfig(this.cfg, project, modelOverride, this.mcpSources);
     }
     sweeperAgentConfig(project) {
         return buildSweeperConfig(this.cfg, project);