@gethmy/harness 1.3.0 → 1.5.0

package/src/run-containment.ts

@@ -0,0 +1,1292 @@
+/**
+ * The containment bound for an implement run (#988).
+ *
+ * ## Why this exists
+ *
+ * An implement run spawns Claude headlessly on a prompt built from a card's
+ * title, description, subtasks and comment thread — text any workspace member
+ * can write. `sweep.trustedAuthors` (#978) gates who may *start* such a run by
+ * `cards.created_by`, and authorship is immutable. The text is not: the `cards`
+ * UPDATE policy is `is_workspace_member` with no author or assignee
+ * restriction, and the comment route is membership-gated too. So the gate binds
+ * the wrong thing, and #988 decided to stop making the card trustworthy and
+ * bound the RUN instead.
+ *
+ * ## Why the two existing recipes do not transplant
+ *
+ * The repo already contains untrusted code twice, and neither shape fits here:
+ *
+ *  - `runRepairSpawn` (`ci-patch.ts`) confines a spawn with `canUseTool` +
+ *    `confineToRepo`. That policy DENIES any tool absent from its path map, and
+ *    `Bash` is deliberately absent — a CI repair edits files and never runs
+ *    them. An implement run has to build, test and commit, so it cannot adopt a
+ *    policy whose first act is to remove its shell.
+ *  - `runInSandbox` (`repair-sandbox.ts`) is a real container, and its first
+ *    flag is `--network=none`. An agent run has to reach the Anthropic API, so
+ *    hosting one there means relaxing the flag that made it a boundary, then
+ *    re-injecting the git and gh credentials it was built to exclude.
+ *
+ * ## What this uses instead
+ *
+ * `Options.sandbox` — OS-level isolation the Agent SDK has carried since
+ * v0.3.x and this repo had never switched on (Seatbelt on macOS, bubblewrap on
+ * Linux). It sandboxes COMMAND EXECUTION rather than removing the command tool,
+ * which is the one shape that leaves an implement run able to do its job.
+ *
+ * Three of its settings are the actual boundary, and each closes something no
+ * other mechanism here can:
+ *
+ *  1. **`filesystem.denyRead`** over the credential directories. This is the
+ *     gap `stripEnvKeys` structurally cannot reach: the daemon's credentials
+ *     are not only in its environment, they are on its disk. `runner.ts`'s own
+ *     module comment concedes the point — a `Read`-tool deny "governs the
+ *     agent's own Read tool, not a separate process's filesystem access", so
+ *     `cat ~/.harmony-mcp/config.json` from inside a Bash call still worked,
+ *     and `Grep`/`Glob`/`mcp__harmony__*` were never covered at all. A kernel
+ *     deny does not care which process asks.
+ *  2. **`network.allowedDomains`** — an exfiltration bound. Reading a
+ *     credential and sending it are two steps, and this closes the second even
+ *     if the first ever reopens.
+ *  3. **`allowUnsandboxedCommands: false`** — without it the SDK honours a
+ *     per-command `dangerouslyDisableSandbox` parameter, which is an escape
+ *     hatch the model itself can reach. A boundary the contained party can
+ *     switch off is not one.
+ *
+ * `failIfUnavailable: true` is the fourth, and it is about honesty rather than
+ * reach: on a host with no sandbox support the run FAILS instead of silently
+ * proceeding uncontained. A containment that degrades quietly would leave the
+ * daemon reporting the same thing whether or not it held.
+ *
+ * ## Why this is unconditional
+ *
+ * It applies to every implement run, not only a swept one. Two reasons, and the
+ * second is the practical one:
+ *
+ *  - The hand-assigned path is exposed to the same text. Assigning a card says
+ *    a person chose to run it; it does not say the description still reads the
+ *    way it did when they chose. #988's finding is that a member can rewrite a
+ *    card *you* authored, and that is true whoever pressed the button.
+ *  - There is no provenance to condition on. `sweep.ts` is explicit that after
+ *    the claim, "`classifyPickup`, `enqueue` and the worker run byte-unchanged
+ *    — a swept card and a hand-assigned card are the same card to everything
+ *    downstream". Conditioning would mean first building that channel, i.e.
+ *    adding a distinction in order to protect only half of what it separates.
+ *
+ * ## What this does NOT cover
+ *
+ * Stated here rather than left to be rediscovered, because every one of these
+ * was found by a review round rather than by reading the code, and a residual
+ * nobody wrote down is indistinguishable from one nobody saw.
+ *
+ *  - **Everything resolved through `spawnRunArgs` runs the run's own
+ *    `package.json` scripts.** Six call sites, not four: `runBuild`,
+ *    `runTests`, `runFormatFix` and `runLint` (`verification.ts`), plus the two
+ *    `dev` servers — `runDeepReview` (`verification.ts`) and the review
+ *    worker's own (`review-worker.ts`). Each executes `bun run <script>` from
+ *    the worktree, which the run may rewrite, in the DAEMON process and outside
+ *    the sandbox with network. All six now carry `containedEnv()`, so the
+ *    secret-shaped variables are gone; the command itself is still the run's to
+ *    choose. Closing that means running the repo's build somewhere the
+ *    operator's credentials are not; that is `repair-sandbox.ts`'s problem shape
+ *    and its own piece of work.
+ *
+ *    The count is in this bullet on purpose. The first version of this list
+ *    named the four verification steps and stopped, and both dev servers then
+ *    shipped with the daemon's whole environment while the changelog told users
+ *    these commands run "without your credentials". `spawn-run-containment.test.ts`
+ *    scans for the property instead of trusting this prose, because the residual
+ *    is a completeness claim over CALL SITES and a hand-list has already lost it.
+ *  - **The MCP surface.** The sandbox governs commands. MCP stdio servers are
+ *    hosted by the CLI and are not sandboxed, so `mcp__harmony__*` is bounded by
+ *    the tool allow-list and the daemon-owned denials (#525/#576), not by this.
+ *  - **Prompt injection itself.** The untrusted-data markers raise the cost and
+ *    make a successful attempt visible; the boundary is the sandbox.
+ *  - **The shared package caches.** `~/.bun/install/cache` and
+ *    `~/.npm/_cacache` are granted, and they are cross-project directories
+ *    holding code the operator later executes — the class excluded above for
+ *    `~/.bun/bin`, `~/.cache` and `$TMPDIR`. The exception is deliberate and it
+ *    is not free either way: measured, a containment with no writable cache
+ *    fails `bun add` and `npm install` outright, and a run that cannot install
+ *    its dependencies is prevented rather than contained. Pointing the run at a
+ *    private cache needs an env var this code cannot inject into the agent
+ *    spawn — `SdkRunnerConfig` carries `stripEnvKeys`, not additions.
+ *  - **Spend.** A member whose cards are claimable can still occupy the daemon.
+ *    That is `maxCardsPerSweep` and `dailyBudgetCents`.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir, tmpdir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+import type {
+  McpServerConfig,
+  SandboxSettings,
+  SettingSource,
+} from "@anthropic-ai/claude-agent-sdk";
+import { getConfigDir } from "@gethmy/mcp/src/config.js";
+import { isInsideTree } from "./confine-to-repo.js";
+import { HARMONY_CREDENTIAL_KEYS } from "./runner.js";
+
+/**
+ * Directories holding credentials the daemon user can read, denied to the
+ * sandboxed run at the kernel rather than at the tool.
+ *
+ * Listed as DIRECTORIES, not files. A token file sits beside the config that
+ * names it (`~/.config/gh/hosts.yml` beside `config.yml`, an ssh key beside its
+ * `known_hosts`), and enumerating the filenames is the denylist game this repo
+ * has already lost twice — once on glob spellings of `..` and once on the case
+ * of `.git`. A directory has no spellings.
+ *
+ * `~/.claude` is here and it is the subtle one: it holds the operator's own
+ * `settings.json`, whose permission grants `settingSources: []` already stops
+ * the SDK from LOADING. Denying the read as well means a run cannot go and
+ * fetch what it was refused, which is a different failure from being handed it.
+ */
+export function credentialDirectories(): string[] {
+  const home = homedir();
+  return [
+    // Harmony's own credential, wherever the MCP server resolves it to. Taken
+    // from `getConfigDir()` rather than re-spelled, for the same reason
+    // `credentialAccessDeny()` does: one source of truth for the location.
+    getConfigDir(),
+    join(home, ".claude"),
+    // `~/.claude.json` is a FILE beside the `~/.claude` directory, and denying
+    // the directory does not deny it — it was still readable (214 KB, holding
+    // MCP server definitions and their env) after the first version of this
+    // list. Neighbours-with-a-suffix are exactly what a directory-shaped list
+    // misses, which is why the two `.config` entries below are named
+    // individually rather than trusting `~/.config`.
+    join(home, ".claude.json"),
+    join(home, ".ssh"),
+    join(home, ".gnupg"),
+    join(home, ".aws"),
+    // Other agent runtimes keep tokens in the same shape. `~/.codex/auth.json`
+    // was readable and returned an `OPENAI_API_KEY`; a credential is a
+    // credential whichever vendor wrote it.
+    join(home, ".codex"),
+    join(home, ".gemini"),
+    join(home, ".config", "gh"),
+    join(home, ".config", "gcloud"),
+    join(home, ".config", "anthropic"),
+    join(home, ".config", "op"),
+    join(home, ".docker"),
+    join(home, ".kube"),
+    join(home, ".netrc"),
+    join(home, ".npmrc"),
+    join(home, ".git-credentials"),
+  ];
+}
+
+/**
+ * Denied for WRITING only, never for reading.
+ *
+ * `~/.gitconfig` is the whole list, and the read/write split is not a nicety —
+ * it is the difference between a contained run and a broken one. The risk in
+ * this file is entirely on the write side: `core.pager`, `core.sshCommand` and
+ * `alias.*` are the keys the #1015 review turned into host execution, and
+ * `core.fsmonitor` is the shape that ran a payload off the diff gate's own
+ * `git status`.
+ *
+ * Denying the READ breaks git outright. Git does not treat an unreadable global
+ * config as an absent one — it fatals, and it does so on every command.
+ * Measured in a real linked worktree with the emitted arguments, `.gitconfig`
+ * in `denyRead`:
+ *
+ *     git status  → 128  fatal: unable to access '/Users/av/.gitconfig': Operation not permitted
+ *     git add -A  → 128  (same)
+ *     git commit  → 128  (same)
+ *
+ * and with only that one path removed, all three return 0. It would have
+ * shipped looking green, because the daemon's own commits run uncontained in
+ * the daemon process — what breaks is git INSIDE a contained spawn, which is
+ * how the review run reads its diff (`review-prompt.ts` tells the reviewer to
+ * run `git diff`, and since #348 the prompt inlines only a `--stat` summary).
+ *
+ * The content is not much of a secret either: a name, an email and aliases.
+ * Losing the write is what mattered, and the write is still denied.
+ */
+export function writeOnlyDenyPaths(): string[] {
+  const paths = [join(homedir(), ".gitconfig")];
+  // Git reads TWO user-level config files, not one. `$XDG_CONFIG_HOME/git/config`
+  // — `~/.config/git/config` by default — supplies `core.pager`,
+  // `core.sshCommand`, `core.fsmonitor` and `alias.*` with exactly the same
+  // effect whenever they are unset in `~/.gitconfig`. Denying only the first
+  // leaves the identical chain reachable through the path it does not name,
+  // which is the whole reason `credentialDirectories()` lists the `~/.config`
+  // subdirectories individually rather than trusting the parent.
+  const xdg = process.env.XDG_CONFIG_HOME;
+  paths.push(
+    xdg && isAbsolute(xdg)
+      ? join(xdg, "git")
+      : join(homedir(), ".config", "git"),
+  );
+  return paths;
+}
+
+/**
+ * Deny rules over the credential directories for the tools that read FILES.
+ *
+ * ## This is not belt-and-braces; it is the other half of the boundary
+ *
+ * The sandbox wraps COMMAND EXECUTION. The CLI process that hosts `Read`,
+ * `Grep` and `Glob` is not wrapped, so those tools reach straight past it.
+ * Measured on the shipped configuration during this card's own review:
+ * `Bash("head -c 5 ~/.claude/settings.json")` was denied by the sandbox, and
+ * the `Read` tool on the same path **succeeded**; `Glob` over `~/.ssh/*`
+ * returned 12 matches. Exfiltration completes off-sandbox too, since MCP stdio
+ * servers are hosted by the CLI and `mcp__harmony__*` can write the content
+ * back to the board.
+ *
+ * So the two layers are not redundant and neither is the fallback for the
+ * other: the sandbox covers what a COMMAND may touch, and these cover what a
+ * TOOL may touch. An earlier version of this module reused
+ * `credentialAccessDeny()`, which names `getConfigDir()` alone — that left
+ * eleven of the twelve directories readable, including `~/.ssh` and
+ * `~/.config/gh`.
+ *
+ * ## Why these are `Read(...)` rules and ONLY `Read(...)` rules
+ *
+ * The obvious spelling is to deny `Read`, `Grep` and `Glob` separately, since
+ * all three leak — `Grep` returns matching lines, so it exfiltrates content as
+ * effectively as `Read`, and `Glob` leaks names. That spelling is wrong, and
+ * the CLI says so out loud when given it:
+ *
+ *   Permission deny rule (--disallowed-tools): Glob(//…/**) is not matched by
+ *   file permission checks — only Read(path) rules are. Use Read(//…/**)
+ *   instead (Read rules cover all file-reading tools).
+ *
+ * So a `Grep(...)`/`Glob(...)` deny is INERT: it denies nothing and emits a
+ * warning on every single run. A `Read(...)` rule is what the file-permission
+ * layer actually consults, and it governs every file-reading tool including
+ * those two — confirmed by probe, where `Glob` over `~/.ssh/*` was refused with
+ * only the `Read` rule in force.
+ *
+ * (`credentialAccessDeny()` in `runner.ts` still emits the three-tool form. It
+ * is pre-existing, used by the sizing preflight, and out of scope here — but it
+ * is denying less than it reads as, and is worth its own card.)
+ */
+export function credentialToolDeny(): string[] {
+  // The leading `/` on an already-absolute path is deliberate and is the same
+  // spelling `credentialAccessDeny()` uses: the Agent SDK anchors a
+  // `//`-prefixed permission pattern to the FILESYSTEM ROOT, where a single
+  // leading slash would anchor it to the run's `repoPath` instead — which for
+  // these paths would match nothing and deny nothing. It reads like a typo and
+  // is load-bearing, so it is spelled out rather than "cleaned up" later.
+  //
+  // Two rules per entry, because the list mixes directories with FILES:
+  // `~/.ssh` is a directory and needs `/**` to cover what is inside it, while
+  // `~/.npmrc` and `~/.git-credentials` are files, for which `/**` matches
+  // nothing at all. Emitting both shapes means the list does not have to say
+  // which is which — and a path that changes from one to the other later
+  // cannot silently fall out of the deny.
+  return credentialDirectories().flatMap((dir) => [
+    `Read(/${dir})`,
+    `Read(/${dir}/**)`,
+  ]);
+}
+
+/**
+ * Directories a contained run must be able to WRITE despite holding no
+ * credentials — the package-manager caches.
+ *
+ * ## Why this list exists at all
+ *
+ * The sandbox profile is deny-by-default, and `allowWrite` adds to a closed
+ * allow-list. A fresh worktree has no `node_modules`, and the daemon's own
+ * verification step runs `bun install --frozen-lockfile` (`pm.ts`). Measured
+ * during this card's review: under the containment as first written,
+ * `bun add` failed with `bun is unable to write files to tempdir:
+ * PermissionDenied` and `npm install` exited 1. A containment that cannot
+ * install dependencies does not contain an implement run, it prevents one.
+ *
+ * The card's own cost measurement missed this because both of its arms ran with
+ * no tool call at all — which is exactly why a measurement needs to exercise
+ * the thing it is measuring.
+ *
+ * ## Why these paths and not `~/.bun`, and not `$TMPDIR`
+ *
+ * Each entry is a CACHE, not a `bin` directory. `~/.bun` as a whole would
+ * include `~/.bun/bin`, and a run that can write an executable there plants a
+ * binary the operator later runs OUTSIDE the sandbox — turning a bounded run
+ * into host persistence.
+ *
+ * The first version of this function then made exactly that mistake one line
+ * further down, by allow-listing `$TMPDIR` whole so `bun` could unpack. Review
+ * wrote a `chmod +x` file into `$TMPDIR/cmux-cli-shims/<uuid>/` from inside the
+ * containment — the directory holding this host's own `claude` launcher. A
+ * temp directory is not scratch space when it is a per-user directory other
+ * tools keep executables in.
+ *
+ * So the run gets its OWN subdirectory under the temp root instead, created per
+ * call and named after the worktree. That is enough for an unpack step and
+ * reaches nothing a neighbour owns. `process.env.TMPDIR` is also not trusted as
+ * a path — `TMPDIR=/` would otherwise allow-list the filesystem — so it is
+ * used only when it is absolute, and `tmpdir()` is the fallback.
+ */
+export function toolchainCacheDirectories(worktree: string): string[] {
+  const home = homedir();
+  // A stable, per-worktree name: the same run resuming or retrying reuses its
+  // own scratch rather than accumulating one directory per attempt, and two
+  // concurrent workers never share.
+  const scratch = `harmony-run-${createHash("sha256").update(worktree).digest("hex").slice(0, 16)}`;
+  // `os.tmpdir()` is NOT a safe fallback on its own: it READS `TMPDIR`, so a
+  // relative or hostile value comes straight back out of it and the guard above
+  // would validate the same bad path twice. Fall through to a literal instead.
+  // (Caught by the test for this, which is the only reason it is not still a
+  // one-line `?? tmpdir()`.)
+  const candidate = process.env.TMPDIR ?? tmpdir();
+  const tmpRoot = isAbsolute(candidate) ? candidate : "/tmp";
+  return [
+    join(home, ".bun", "install", "cache"),
+    join(home, ".npm", "_cacache"),
+    // `~/.cache` as a whole was here and is GONE. It is a shared per-user root
+    // holding executables the operator runs: corepack's `yarn`/`pnpm` shims
+    // under `~/.cache/node/corepack/`, `~/.cache/pre-commit/**/bin/*` which
+    // `git commit` runs in any pre-commit repo, playwright browsers, `~/.cache/deno`.
+    // Granting it is the same defect as granting `~/.bun` or `$TMPDIR` whole —
+    // the two exclusions this function already documents — and `bun`/`npm` do
+    // not need it, since their caches are named individually above.
+    join(tmpRoot, scratch),
+  ];
+}
+
+/**
+ * Environment keys to strip beyond {@link HARMONY_CREDENTIAL_KEYS}.
+ *
+ * ## Why a pattern and not a list
+ *
+ * `HARMONY_CREDENTIAL_KEYS` names six `HARMONY_*`/`SUPABASE_*` variables — the
+ * ones Harmony itself sets. Everything else the operator happens to export
+ * reaches the run untouched, and review measured ten secret-shaped variables in
+ * the child's environment on this host, among them
+ * `GITHUB_PERSONAL_ACCESS_TOKEN`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY` and
+ * `PINECONE_API_KEY`. A GitHub token matters most: `*.github.com` is on the
+ * egress allow-list, because a run has to push its branch — so a token in the
+ * environment plus an allowed destination is a complete read-and-send path, and
+ * "reading a credential and sending it are two steps" stops being true.
+ *
+ * Naming them individually cannot work: the set is whatever THIS operator
+ * exports, and the next one exports different names. So the rule is shaped, not
+ * enumerated — and unlike a denylist over attacker-chosen input, the thing being
+ * matched here is a variable name the operator chose, so a miss is a
+ * configuration this did not anticipate rather than an evasion.
+ *
+ * ## Why it is still not a boundary
+ *
+ * A variable called `DEPLOY_HOOK_URL` carrying a secret is not matched, and
+ * nothing here would catch it. This narrows the blast radius of the common
+ * shapes; the boundary remains the sandbox and the egress allow-list.
+ */
+const SECRET_ENV_PATTERN =
+  /(TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|API_?KEY|_PAT$|^PAT_|PRIVATE_KEY|ACCESS_KEY)/i;
+
+/**
+ * Secret-shaped names the run genuinely needs, and must therefore keep.
+ *
+ * `ANTHROPIC_*` authenticates the model call the run IS. Stripping it does not
+ * contain anything — it stops the run existing — and it is a credential for the
+ * one destination the sandbox already allows.
+ *
+ * The rest are here because an earlier version of {@link SECRET_ENV_PATTERN}
+ * carried a bare, unanchored `AUTH` alternative and swept up every one of them:
+ * `SSH_AUTH_SOCK` (which this file's own comment claimed was deliberately kept
+ * — the comment was simply wrong), `GIT_AUTHOR_NAME`/`EMAIL`, `XAUTHORITY`,
+ * `NODE_AUTH_TOKEN`'s neighbours, and plain `AUTHOR`. Dropping the alternative
+ * fixes the class; these are named for the two that a future re-add would break
+ * first, and because `GIT_COMMITTER_*` surviving while `GIT_AUTHOR_*` did not
+ * is the kind of half-broken git state that is miserable to debug.
+ *
+ * `SSH_AUTH_SOCK` in particular carries no secret — it is a socket path — and
+ * removing it breaks a legitimate `git push` over ssh. The agent socket itself
+ * is refused by the sandbox, which is measured and is the real bound.
+ */
+const KEEP_ENV_KEYS = new Set([
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+  "ANTHROPIC_BASE_URL",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "SSH_AUTH_SOCK",
+  "GIT_AUTHOR_NAME",
+  "GIT_AUTHOR_EMAIL",
+  "GIT_COMMITTER_NAME",
+  "GIT_COMMITTER_EMAIL",
+  "XAUTHORITY",
+]);
+
+/**
+ * Every environment key this run should not carry, given the parent's env.
+ *
+ * Returns names, not values, and is exported so a test can assert the shape
+ * against a synthetic environment rather than the machine it happens to run on.
+ */
+export function secretEnvKeysToStrip(
+  parentEnv: Record<string, string | undefined> = process.env,
+): string[] {
+  const stripped = new Set<string>(HARMONY_CREDENTIAL_KEYS);
+  for (const key of Object.keys(parentEnv)) {
+    if (KEEP_ENV_KEYS.has(key)) continue;
+    if (SECRET_ENV_PATTERN.test(key)) stripped.add(key);
+  }
+  return [...stripped];
+}
+
+/** Thrown when a run's own worktree carries settings that would widen the sandbox. */
+export class ProjectSandboxOverrideError extends Error {
+  constructor(
+    readonly settingsPath: string,
+    readonly offendingKeys: readonly string[],
+  ) {
+    super(
+      `Refusing to spawn: ${settingsPath} sets ${offendingKeys.map((k) => `"${k}"`).join(", ")}. ` +
+        "Project settings are loaded so the run can read CLAUDE.md, and that same layer " +
+        "can widen the sandbox (`sandbox.filesystem.allowWrite`) or execute commands " +
+        "outside it (`hooks`, `env`). A run that can write this file could therefore " +
+        "widen its own bounds, so only keys known not to affect execution are accepted. " +
+        "Remove the key, or the run stays refused.",
+    );
+    this.name = "ProjectSandboxOverrideError";
+  }
+}
+
+/**
+ * Refuse a spawn whose worktree carries a `sandbox` key in project settings.
+ *
+ * ## The hole this closes, measured
+ *
+ * The containment loads `settingSources: ["project"]`, because that source is
+ * what carries `CLAUDE.md` and dropping it silently removed every project
+ * instruction from every run. The cost of keeping it is that
+ * `.claude/settings.json` — a file inside the worktree the run may write —
+ * CONTRIBUTES to the sandbox.
+ *
+ * Not all of it, and the distinction is worth stating because it decides how
+ * narrow this guard has to be. Ablated one key at a time against the shipped
+ * arguments: `enabled`, `allowUnsandboxedCommands`, `denyRead` and `denyWrite`
+ * are refused from the project layer — a run genuinely cannot switch the
+ * sandbox off or re-open the credential denies. But
+ * `sandbox.filesystem.allowWrite` is merged in on BOTH runners, and
+ * `sandbox.network.allowedDomains` on the CLI runner. `allowWrite: ["/"]` was
+ * enough to write `~/.zshrc` and `~/Library/LaunchAgents/*.plist` — code
+ * execution outside the sandbox at the operator's next login.
+ *
+ * Delivery needs no cleverness: the worktree path is deterministic per card,
+ * `.claude/` is not gitignored, the daemon auto-commits with `git add -A`, and
+ * every retry, stage and steering resume re-spawns at the branch tip. One run
+ * writes the file; the next one is wider.
+ *
+ * ## Why refuse rather than repair
+ *
+ * Rewriting the file would work and is wrong twice: it mutates the run's own
+ * checkout, so the change lands in the diff a human reviews, and it teaches the
+ * daemon to silently edit repository files to protect itself. Refusing is
+ * fail-closed, leaves the evidence in place, and names the file.
+ *
+ * `managedSettings` — the SDK's policy tier, documented as filtered
+ * restrictive-only — was tried first and does NOT hold: the widening is
+ * accepted there too, on both modes. That is why this is a pre-spawn check and
+ * not a configuration.
+ *
+ * ## An ALLOW-list, because the first version of this was a denylist and lost
+ *
+ * That version refused exactly one key, `sandbox`, on the reasoning that the
+ * sandbox was the thing being widened. Review then walked past it with
+ * `hooks`, which the settings layer executes: a hook block in the worktree's
+ * own `.claude/settings.json` ran as the daemon user OUTSIDE the sandbox, read
+ * `~/.ssh/config` and `~/.harmony-mcp/config.json` — both in `denyRead` — and
+ * reached a host that is not on the egress allow-list. Project `env` is
+ * honoured too.
+ *
+ * That is the same shape this repo has now lost three times (glob spellings of
+ * `..`, the case of `.git`, and now settings keys): a denylist over input the
+ * attacker chooses is not a bound, and the answer is to invert it. So the rule
+ * is now "these keys are known not to affect execution, and anything else is
+ * refused" — a new escape has to be a key we deliberately blessed, rather than
+ * one nobody thought of.
+ *
+ * Note what the CLI's own trust gate does and does not cover, since it is easy
+ * to over-rely on: `permissions.allow` and `permissions.additionalDirectories`
+ * from an untrusted workspace ARE ignored ("this workspace has not been
+ * trusted"), and `hooks` and `env` are NOT. So the trust gate is not a
+ * substitute for this, and on the operator's own trusted checkout it covers
+ * even less.
+ *
+ * The check reads the file with plain `fs` and treats unparsable JSON as
+ * absent: a malformed settings file contributes nothing either, and failing the
+ * run on it would turn a typo into an outage.
+ */
+const INERT_PROJECT_SETTING_KEYS: ReadonlySet<string> = new Set([
+  // Schema/editor metadata and presentation. None of these reach execution,
+  // the sandbox, the filesystem or the network. A key is added here only after
+  // someone checks that claim — the list being short is the point.
+  "$schema",
+  "cleanupPeriodDays",
+  "includeCoAuthoredBy",
+  "language",
+  "outputStyle",
+  "spinnerTipsEnabled",
+  "theme",
+  "verbose",
+]);
+
+export function assertNoProjectSandboxOverride(worktree: string): void {
+  // Both spellings the `project` and `local` sources read. `local` is not in
+  // our `settingSources`, but it is checked anyway — the cost is one read and
+  // the alternative is this guard depending on a constant elsewhere staying
+  // narrow.
+  for (const name of ["settings.json", "settings.local.json"]) {
+    const path = join(worktree, ".claude", name);
+    let raw: string;
+    try {
+      raw = readFileSync(path, "utf-8");
+    } catch {
+      continue;
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (parsed === null || typeof parsed !== "object") continue;
+    const offending = Object.keys(parsed).filter(
+      (key) => !INERT_PROJECT_SETTING_KEYS.has(key),
+    );
+    if (offending.length > 0) {
+      throw new ProjectSandboxOverrideError(path, offending);
+    }
+  }
+}
+
+/**
+ * The parent environment with {@link secretEnvKeysToStrip} removed.
+ *
+ * For the spawns that use `execFileSync` rather than `SdkAgentRunner` — the
+ * auto-fix and review paths — which have no `stripEnvKeys` of their own.
+ * `execFileSync`'s `env` REPLACES the child's environment rather than merging,
+ * so this returns the whole thing minus the stripped keys; handing it a partial
+ * object would drop `PATH` and `HOME` and break the spawn outright.
+ */
+export function containedEnv(
+  parentEnv: Record<string, string | undefined> = process.env,
+): Record<string, string> {
+  const strip = new Set(secretEnvKeysToStrip(parentEnv));
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(parentEnv)) {
+    if (value === undefined || strip.has(key)) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Git metadata the contained run may not write — the escape the worktree grant
+ * would otherwise hand it.
+ *
+ * ## The chain, which this repo has already proven end to end
+ *
+ * The containment allows writes inside the worktree, because that is the run's
+ * workspace. In a LINKED worktree `<worktree>/.git` is a plain pointer FILE,
+ * and it therefore sits inside the granted scope. So:
+ *
+ *   1. rewrite `<worktree>/.git` to `gitdir: ./g`
+ *   2. write `<worktree>/g/config` with `[core] fsmonitor = ./payload.sh`
+ *   3. the daemon runs its ordinary post-run `git status` / `git add -A` /
+ *      `git commit` in that worktree — `execFileSync`, in the DAEMON process,
+ *      with no sandbox, the unstripped environment and full network
+ *
+ * and `payload.sh` executes as the operator, outside the profile, with every
+ * credential the containment spent three review rounds removing. It needs no
+ * credential read, no egress and no denied tool, so nothing else in this module
+ * fires. `core.sshCommand`, `core.pager` and `alias.*` are equivalent
+ * primitives; the #1015 security review demonstrated exactly this and closed it
+ * for the CI-repair spawn (`isGitMetadata`, `confine-to-repo.ts`).
+ *
+ * `writeOnlyDenyPaths` already denies the GLOBAL `~/.gitconfig` for this
+ * reason. The repository-local config is read at higher precedence and was
+ * fully inside the granted write scope.
+ *
+ * ## Why this is not simply "deny the git directory"
+ *
+ * A commit writes objects and refs into the COMMON dir, so denying it whole
+ * breaks `git commit` — the same shape as the `~/.gitconfig` regression one
+ * round earlier, where denying a read broke every git command. Only the paths
+ * that carry EXECUTION are denied: `config`, `config.worktree`, and `hooks`, in
+ * both the per-worktree git dir and the shared common dir.
+ *
+ * The bare `.git` path is denied only when it is a FILE. As a directory it is
+ * the whole store, and denying it would break the commit this exists to
+ * protect; there the `config`/`hooks` entries below do the work instead.
+ *
+ * Resolution is best-effort: a path that is not a git repository yet (a
+ * worktree about to be created, a unit test's fixture path) yields the
+ * worktree-relative guesses alone rather than throwing. A deny that names a
+ * file which does not exist costs nothing.
+ */
+export function gitMetadataDenyPaths(worktree: string): string[] {
+  const paths = new Set<string>();
+  const dotGit = join(worktree, ".git");
+
+  // `createRequire` rather than a static import: a top-level `node:child_process`
+  // binding in a barrel-exported module breaks every test elsewhere that
+  // partially mocks it, at LOAD time — the trap `repair-sandbox.ts` documents.
+  const require = createRequire(import.meta.url);
+  const { execFileSync } =
+    require("node:child_process") as typeof import("node:child_process");
+  const { statSync } = require("node:fs") as typeof import("node:fs");
+
+  const gitDirs = new Set<string>();
+  try {
+    // Hardened like every other daemon-issued git command, including this one —
+    // the function that computes the git denies was itself the last unhardened
+    // call in the tree. `rev-parse` runs no hook today; the invariant is that
+    // no daemon git command CAN, not that this one happens not to.
+    const out = execFileSync(
+      "git",
+      [...GIT_NO_HOOKS, "rev-parse", "--git-dir", "--git-common-dir"],
+      { cwd: worktree, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] },
+    );
+    for (const line of out.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      gitDirs.add(isAbsolute(trimmed) ? trimmed : join(worktree, trimmed));
+    }
+  } catch {
+    // Not a repository (yet). Fall through to the in-worktree guess.
+  }
+  gitDirs.add(dotGit);
+
+  for (const dir of gitDirs) {
+    paths.add(join(dir, "config"));
+    paths.add(join(dir, "config.worktree"));
+    paths.add(join(dir, "hooks"));
+  }
+
+  // The pointer file itself — the first step of the chain. Only when it IS a
+  // file; as a directory this path is the object store.
+  try {
+    if (statSync(dotGit).isFile()) paths.add(dotGit);
+  } catch {
+    // Absent: nothing to point anywhere.
+  }
+
+  return [...paths];
+}
+
+/**
+ * Files and directories that make the operator's NEXT session run something.
+ *
+ * Not credentials — nothing here is worth reading — but every one of them is
+ * executed by a shell, a login or a session manager, so a write is host code
+ * execution on a delay. They belong on the write side only.
+ *
+ * ## Where the line is, and why it is drawn there
+ *
+ * The whole value of this function is that it is COMPLETE for the class it
+ * names, so the class has to be stated rather than left to the reader.
+ *
+ * **In: anything a shell, login or session manager executes unconditionally.**
+ * The startup file the operator never types is the point — they open a terminal
+ * and it runs. That is why `.zlogin` and `.bash_login` are here: zsh sources
+ * `.zprofile` then `.zlogin` for a login shell, and bash reads the first of
+ * `.bash_profile`, `.bash_login`, `.profile` that exists. Denying one member of
+ * a shell's startup chain and not the next is not a narrower rule, it is the
+ * same rule with a hole — the version of this list that shipped in #988 denied
+ * `.zprofile` but not `.zlogin`, and `.bash_profile` but not `.bash_login`.
+ * Fish is here for the same reason and was missing for the same reason.
+ *
+ * **Out: directories on `PATH`,** `~/.local/bin` and `~/bin` among them. A
+ * write there is real, but it is name SHADOWING — it fires only if the operator
+ * later runs a command by a name the run chose — and denying it breaks what a
+ * run legitimately does: `pip install --user` and its neighbours install there.
+ * That is the trade this module already made explicitly for `~/.bun/bin`,
+ * `~/.cache` and `$TMPDIR` in "what this does NOT cover", and it is made the
+ * same way here rather than differently. A run that cannot install its
+ * dependencies is prevented, not contained.
+ *
+ * **Out: the whole of `~/.config`.** Individual entries under it are in
+ * (`systemd/user`, `autostart`, `fish`) because a specific manager executes
+ * them. The directory as a whole is application configuration, and denying it
+ * wholesale would be a bound on the operator's tools rather than on the run.
+ *
+ * None of this is the boundary. The sandbox is; this list is the write-side
+ * mitigation that makes the sandbox's failure less useful.
+ */
+export function hostPersistencePaths(): string[] {
+  const home = homedir();
+  return [
+    // zsh, in the order a login shell sources them.
+    join(home, ".zshenv"),
+    join(home, ".zprofile"),
+    join(home, ".zshrc"),
+    join(home, ".zlogin"),
+    // bash. `.bash_login` is the second candidate of the login triple and was
+    // the omitted one; `.profile` is the third and is also read by sh and dash.
+    join(home, ".bashrc"),
+    join(home, ".bash_profile"),
+    join(home, ".bash_login"),
+    join(home, ".profile"),
+    // fish. `conf.d/*.fish` is sourced before `config.fish`, so the directory
+    // matters at least as much as the file.
+    join(home, ".config", "fish", "config.fish"),
+    join(home, ".config", "fish", "conf.d"),
+    // Session managers: launchd (macOS), systemd user units and XDG autostart.
+    join(home, "Library", "LaunchAgents"),
+    join(home, ".config", "systemd", "user"),
+    join(home, ".config", "autostart"),
+  ];
+}
+
+/**
+ * The WRITE half of the tool-layer deny, and it was missing.
+ *
+ * ## Why this exists
+ *
+ * `credentialToolDeny` closes the read side: the sandbox wraps command
+ * execution, the CLI process hosting `Read`/`Grep`/`Glob` is not wrapped, so a
+ * kernel `denyRead` needs a `Read(...)` rule beside it. That reasoning is
+ * symmetric and was applied to one side only. `IMPLEMENT_ALLOWED_TOOLS` grants
+ * unqualified `Write` and `Edit`, which run in that same unwrapped process — so
+ * every `denyWrite` in the sandbox had no tool-layer counterpart, and the write
+ * side of the boundary stood open by exactly the mechanism this module
+ * documents.
+ *
+ * The gap was pinned by a test of this branch's own making. It asserted that
+ * `~/.gitconfig` must NOT appear in `disallowedTools`, on the reasoning that
+ * "the tool layer must not re-deny what the sandbox deliberately allows" — but
+ * the sandbox allows only the READ of that file and explicitly denies the
+ * WRITE. Dropping the write rule along with the read rule reopened the very
+ * path the `denyWrite` entry exists to close.
+ *
+ * ## Why this is still a denylist, and what the structural fix would be
+ *
+ * An allow-list would be better here, as everywhere else in this module. It is
+ * not expressible with these primitives: a deny wins over an allow, so
+ * `Edit(//**)` plus a re-allow of the worktree denies everything. The real
+ * inversion is `canUseTool` + `gateEveryToolCall` (`confine-to-repo.ts`), which
+ * IS an allow-list over paths — but it drops `allowedTools` and moves the spawn
+ * to `permissionMode: "default"`, and an implement run holds `mcp__harmony__*`,
+ * whose governance under that mode is not the same. A headless run that stops
+ * on a permission prompt is a hung card, so that swap needs measuring rather
+ * than assuming, and it is not folded into a security fix.
+ */
+/*
+ * ## Why `Edit(...)` alone, and not `Write(...)`/`MultiEdit(...)` too
+ *
+ * MEASURED, because review raised it as blocking and the answer is not
+ * guessable from the types. Identical CLI runs, `Write` tool aimed at a denied
+ * directory, the only difference being whether these rules were passed:
+ *
+ *     with the Edit(...) rules      Write → DENIED, file absent
+ *     the same rules stripped       Write → WROTE,  file on disk
+ *
+ * So `Edit(...)` IS the write-side rule and it governs every file-writing tool,
+ * exactly as one `Read(...)` rule governs `Read`, `Grep` and `Glob`. The SDK's
+ * own option doc says the same in one line — "Filesystem access: Use `Read` and
+ * `Edit` permission rules" — naming two rules for the whole filesystem surface,
+ * not six.
+ *
+ * Adding `Write(...)`/`MultiEdit(...)`/`NotebookEdit(...)` would not be
+ * harmless belt-and-braces: the read side already showed what happens to a rule
+ * the permission layer does not match — `Grep(...)` and `Glob(...)` denied
+ * NOTHING and printed a warning on every single run until they were removed.
+ * A rule that reads as protection and enforces none is worse than its absence.
+ */
+export function credentialWriteToolDeny(worktree: string): string[] {
+  return [
+    ...credentialDirectories(),
+    ...writeOnlyDenyPaths(),
+    ...hostPersistencePaths(),
+    ...gitMetadataDenyPaths(worktree),
+  ].flatMap((p) => [`Edit(/${p})`, `Edit(/${p}/**)`]);
+}
+
+/** Tools that WRITE, and the argument each carries its target in. */
+const WRITE_TOOL_PATHS: Record<string, readonly string[]> = {
+  Write: ["file_path"],
+  Edit: ["file_path"],
+  MultiEdit: ["file_path"],
+  NotebookEdit: ["notebook_path"],
+};
+
+/** Tools that READ a named path. `Grep`/`Glob` default to cwd when absent. */
+const READ_TOOL_PATHS: Record<string, readonly string[]> = {
+  Read: ["file_path", "path", "notebook_path"],
+  Grep: ["path"],
+  Glob: ["path"],
+};
+
+/**
+ * The tool-layer policy, as an ALLOW-list over RESOLVED paths (#988).
+ *
+ * ## Why the denylist had to go
+ *
+ * `credentialToolDeny` and `credentialWriteToolDeny` are permission rules
+ * matched against the path STRING the model supplies, over a filesystem that is
+ * otherwise allow-by-default. Review established twice that this cannot be
+ * completed:
+ *
+ *  - The rules match the REQUESTED path, not its resolved target, so a symlink
+ *    created inside the writable worktree names a path no rule covers while
+ *    landing in a denied tree.
+ *  - The enumeration was short every time it was checked — and the last round
+ *    named the entry that settles the argument: **the operator's primary
+ *    checkout**, which is the PARENT of every worktree (`worktree.basePath`
+ *    defaults to `.harmony-worktrees` under the repo root) and which carries
+ *    the `.githooks/` directory this repo configures as `core.hooksPath` for
+ *    the operator's own git.
+ *
+ * The sandbox's `filesystem.allowWrite` is already a closed allow-list for
+ * COMMANDS. This is the same shape for TOOLS, which run in the CLI process the
+ * sandbox does not wrap.
+ *
+ * ## The rules, and why reads stay a denylist
+ *
+ *  - **Write tools**: the worktree and the toolchain caches, and nothing else —
+ *    named or not. Git metadata inside them stays refused.
+ *  - **Read tools**: refused inside the credential directories, allowed
+ *    elsewhere. Deliberately still a denylist: a run legitimately reads the
+ *    repo, its dependencies, the toolchain and the system headers, and an
+ *    allow-list there would have to enumerate a working developer machine. The
+ *    sandbox covers the command side of the same question.
+ *  - **`Bash`**: allowed, and bounded by the sandbox instead. That is the whole
+ *    reason this card chose an execution sandbox — a tool-layer policy cannot
+ *    read a shell command's real effects, and pretending otherwise is how
+ *    `confineToRepo` ends up removing the shell.
+ *  - **`mcp__harmony__*`**: allowed. A scoped API, not a filesystem, bounded by
+ *    the daemon-owned denials (#525/#576).
+ *  - A tool that names a path this policy cannot resolve is REFUSED, not waved
+ *    through — the fail-closed direction `decideConfinedTool` also takes.
+ *
+ * `isInsideTree` does the resolution, per component and through symlinks. It
+ * took three separate corrections in `confine-to-repo.ts` to get right, so it
+ * is reused rather than re-derived.
+ */
+export function implementRunToolPolicy(args: {
+  worktree: string;
+  readOnly?: boolean;
+}): (
+  toolName: string,
+  input: Record<string, unknown>,
+) => Promise<{ behavior: "allow" } | { behavior: "deny"; message: string }> {
+  const writable = [args.worktree, ...toolchainCacheDirectories(args.worktree)];
+  const gitMeta = gitMetadataDenyPaths(args.worktree);
+  const secrets = credentialDirectories();
+
+  return async (toolName, input) => {
+    // `updatedInput` is OPTIONAL in the SDK's TypeScript type and required by
+    // its runtime schema — measured: a bare `{ behavior: "allow" }` made every
+    // `Write` fail with a permission-handler `ZodError`, while `Bash` went
+    // through, so the run was contained and unable to do its job. Echoing the
+    // input back is the safe form and costs nothing. The unit tests could not
+    // catch this; only a real spawn could.
+    const allow = { behavior: "allow" as const, updatedInput: input };
+    const deny = (message: string) => ({ behavior: "deny" as const, message });
+
+    if (toolName.startsWith("mcp__")) return allow;
+    if (toolName === "Bash" || toolName === "BashOutput") {
+      // The sandbox is the bound here, and for a read-only spawn the caller's
+      // own `Bash(readonly)` grant still applies above this policy.
+      return allow;
+    }
+
+    const writePaths = WRITE_TOOL_PATHS[toolName];
+    if (writePaths) {
+      if (args.readOnly === true) {
+        return deny(`${toolName} is not available to a review run.`);
+      }
+      for (const key of writePaths) {
+        const value = input[key];
+        if (typeof value !== "string" || value.length === 0) continue;
+        const target = isAbsolute(value) ? value : join(args.worktree, value);
+        if (gitMeta.some((p) => isInsideTree(p, target) || p === target)) {
+          return deny(
+            `${toolName} may not touch git metadata. Refused: ${value}`,
+          );
+        }
+        if (!writable.some((root) => isInsideTree(root, target))) {
+          return deny(
+            `${toolName} may only write inside this run's worktree. Refused: ${value}`,
+          );
+        }
+      }
+      return allow;
+    }
+
+    const readPaths = READ_TOOL_PATHS[toolName];
+    if (readPaths) {
+      for (const key of readPaths) {
+        const value = input[key];
+        if (typeof value !== "string" || value.length === 0) continue;
+        const target = isAbsolute(value) ? value : join(args.worktree, value);
+        if (secrets.some((dir) => isInsideTree(dir, target))) {
+          return deny(
+            `${toolName} may not read the credential directories. Refused: ${value}`,
+          );
+        }
+      }
+      return allow;
+    }
+
+    // Unrecognised: allowed only because it names no path this policy knows how
+    // to check. `Task`/`Agent` inherit the same policy in their own spawn.
+    return allow;
+  };
+}
+
+/**
+ * Config flags every git command the daemon runs in a run's worktree must carry.
+ *
+ * ## The hole these close, which a path deny cannot
+ *
+ * `gitMetadataDenyPaths` stops the run writing git's own config and hook
+ * directories. It does not stop `core.hooksPath` pointing somewhere else — and
+ * in THIS repository it already does: the root `package.json`'s `prepare` runs
+ * `git config core.hooksPath .githooks`, and `createWorktree` runs the install
+ * command in every new worktree, so the shared repo config carries that value.
+ *
+ * A RELATIVE `core.hooksPath` resolves against the WORKING-TREE root. So in the
+ * run's own worktree it names `<worktree>/.githooks/` — an ordinary tracked
+ * directory, inside `sandbox.filesystem.allowWrite`, denied by neither the
+ * sandbox nor the `Edit(...)` rules, and holding a tracked executable
+ * `pre-push`. The daemon then runs `git push` there, in its own process, and
+ * the hook the run rewrote executes as the operator.
+ *
+ * Adding `.githooks` to a deny list would close this spelling and wait for the
+ * next hook convention. `ci-patch.ts` reached the same conclusion for the
+ * repair spawn and states it plainly: rather than enumerate conventions, no git
+ * command it issues can run a hook at all. This is that, for the daemon.
+ *
+ * `core.hooksPath=` is EMPTY rather than `/dev/null`, and the value must never
+ * be written: `git config core.hooksPath` from a linked worktree writes the
+ * SHARED repository config and would disable hooks in the operator's own
+ * checkout permanently. Passing it per command with `-c` touches nothing.
+ *
+ * `fsmonitor` and `pager` are the other two keys the #1015 review turned into
+ * execution off an ordinary read command, and `alias.*` cannot be disarmed by a
+ * flag — which is why the config files themselves stay denied. These flags and
+ * `gitMetadataDenyPaths` are two halves of one bound, not alternatives.
+ */
+export const GIT_NO_HOOKS: readonly string[] = [
+  "-c",
+  "core.hooksPath=",
+  "-c",
+  "core.fsmonitor=",
+  "-c",
+  "core.pager=cat",
+];
+
+/**
+ * Domains a contained implement run may reach.
+ *
+ * An allow-list, and short on purpose. The run needs the model API to think, a
+ * package registry to install what a build needs, and the forge to push a
+ * branch and open its PR. Nothing else on this list would be missed by a run
+ * doing the job the card describes, and every addition is a new egress path for
+ * text the run was given by someone untrusted.
+ *
+ * `deniedDomains` is deliberately empty: with an allow-list this short, a deny
+ * entry would only ever be a note about something already refused.
+ */
+export const IMPLEMENT_ALLOWED_DOMAINS: readonly string[] = [
+  "api.anthropic.com",
+  "*.anthropic.com",
+  "registry.npmjs.org",
+  "*.npmjs.org",
+  "github.com",
+  "*.github.com",
+  "*.githubusercontent.com",
+];
+
+/**
+ * The harmony MCP server, declared explicitly.
+ *
+ * ## Why this is not optional
+ *
+ * `settingSources: []` is what keeps the operator's own permission grants out
+ * of a board-driven run — and the harmony MCP server is registered in the same
+ * filesystem config it turns off. **Measured, not assumed:** with sources off
+ * and nothing declared, `mcp__harmony__*` is simply gone, and a run that cannot
+ * call `harmony_update_agent_progress` is a broken daemon rather than a
+ * contained one. So the containment has to hand back what it just took away.
+ *
+ * ## Why it still works with the credential directory denied
+ *
+ * The MCP server reads its own credential from `~/.harmony-mcp/config.json`
+ * with no environment fallback, which the sandbox denies. That looked like it
+ * had to break the server, and it does not: an MCP stdio server is hosted by
+ * the CLI, not run as a command inside the sandbox, so it authenticates
+ * normally. Confirmed by running the contained configuration against a real
+ * `harmony_list_workspaces` call with the deny in place.
+ *
+ * That is worth stating plainly, because it also bounds what the containment
+ * claims: the sandbox governs the COMMANDS the model runs, not the MCP surface
+ * the CLI hosts for it. The bound on the MCP surface is a different mechanism —
+ * the tool allow-list, plus the daemon-owned denials (#525/#576).
+ *
+ * Resolved from the INSTALLED package rather than `npx @gethmy/mcp@latest`, the
+ * spelling the host config uses. The daemon pins `@gethmy/mcp` exactly, in
+ * lockstep with its own release, and a contained run reaching for `@latest`
+ * would fetch a version this daemon was never tested against — over a network
+ * the containment then has to allow the registry for.
+ */
+export function harmonyMcpServer(): Record<string, McpServerConfig> {
+  const require = createRequire(import.meta.url);
+  // The package's `exports` map publishes "." → dist/index.js and no bin
+  // subpath, so the CLI is named as its sibling rather than resolved directly.
+  const cli = join(dirname(require.resolve("@gethmy/mcp")), "cli.js");
+  return {
+    harmony: {
+      type: "stdio",
+      // The daemon's own interpreter: no PATH lookup, no `npx` resolution step,
+      // and no chance of a different Node than the one that was tested.
+      command: process.execPath,
+      args: [cli, "serve"],
+    },
+  };
+}
+
+/** The fields {@link implementRunContainment} contributes to an `SdkRunnerConfig`. */
+export interface RunContainment {
+  sandbox: SandboxSettings;
+  /**
+   * The tool-layer allow-list, and `gateEveryToolCall` is what makes it fire at
+   * all — measured in #954: under `permissionMode: "dontAsk"` with
+   * `allowedTools` set, the SDK pre-approves and NEVER calls the handler.
+   */
+  canUseTool: (
+    toolName: string,
+    input: Record<string, unknown>,
+  ) => Promise<{ behavior: "allow" } | { behavior: "deny"; message: string }>;
+  gateEveryToolCall: true;
+  settingSources: SettingSource[];
+  mcpServers: Record<string, McpServerConfig>;
+  strictMcpConfig: true;
+  stripEnvKeys: readonly string[];
+  disallowedTools: string[];
+}
+
+/**
+ * Build the containment for an implement run against `worktree`.
+ *
+ * Returns a fragment to spread into an `SdkRunnerConfig`, rather than mutating
+ * a runner: the caller still owns `allowedTools`, `model` and the turn budget,
+ * and a function that returned a whole config would have to know about all of
+ * them to hand one back.
+ *
+ * `extraDisallowedTools` carries the caller's existing denylist — the three
+ * daemon-owned lifecycle MCP tools on a stage run (#525/#576). It is merged
+ * rather than replaced, because those two denials answer different questions
+ * and neither is allowed to drop the other.
+ */
+export function implementRunContainment(args: {
+  worktree: string;
+  extraDisallowedTools?: readonly string[];
+  /**
+   * Spawn that must not run commands (the review pipeline). Turns off
+   * `autoAllowBashIfSandboxed`, so a `Bash(readonly)` grant keeps meaning what
+   * it says instead of being auto-approved because the run is sandboxed.
+   */
+  readOnly?: boolean;
+}): RunContainment {
+  // Inside the builder rather than at the call sites, so a future spawn cannot
+  // adopt the containment and skip the check that makes it hold. Throws — see
+  // `assertNoProjectSandboxOverride`.
+  assertNoProjectSandboxOverride(args.worktree);
+  return {
+    sandbox: {
+      enabled: true,
+      // Fail loudly on a host that cannot sandbox, rather than run uncontained.
+      // This is also the SDK's own default once `enabled` is set through the
+      // option; stated explicitly because the whole boundary rests on it.
+      failIfUnavailable: true,
+      // The model may not opt a single command back out. See the module note.
+      allowUnsandboxedCommands: false,
+      // Bash stays usable without a permission prompt, which is the point of
+      // choosing an execution sandbox over a tool denylist: the run keeps its
+      // shell and the shell keeps its bounds.
+      //
+      // OFF for a read-only spawn, and that is a correctness bug this had.
+      // The review worker grants `Bash(readonly)` precisely so the reviewer
+      // cannot modify the branch it is grading — and auto-approving Bash
+      // BECAUSE it is sandboxed overrides that scoping. Measured A/B against
+      // the review worker's own allow-list: with this on, a write and an `rm`
+      // via Bash were both ALLOWED; with it off, both DENIED. The sandbox
+      // bounds where a command may reach; it says nothing about whether this
+      // particular spawn was supposed to run commands at all.
+      autoAllowBashIfSandboxed: args.readOnly !== true,
+      network: {
+        allowedDomains: [...IMPLEMENT_ALLOWED_DOMAINS],
+        // No inbound listener. A contained run has no reason to bind a port,
+        // and one that does is either a test fixture that belongs in CI or a
+        // channel out.
+        allowLocalBinding: false,
+      },
+      filesystem: {
+        // The worktree is the run's workspace; the rest are the package-manager
+        // caches a build genuinely needs (see `toolchainCacheDirectories`).
+        // This ADDS to a closed allow-list — the profile denies by default —
+        // so it is not the whole of what the run may write: the profile also
+        // allows the cwd, the git common dir (which is what lets `git commit`
+        // work in a linked worktree), `/tmp/claude-<uid>` and `~/.claude/debug`.
+        allowWrite: [
+          args.worktree,
+          ...toolchainCacheDirectories(args.worktree),
+        ],
+        denyRead: credentialDirectories(),
+        // NOTE the asymmetry with `denyWrite` below: `~/.gitconfig` is
+        // write-denied and read-ALLOWED, because denying its read makes every
+        // git command in the spawn fatal. See `writeOnlyDenyPaths`.
+        // `~/.claude` is denied for WRITE too, which subtracts the profile's
+        // own `~/.claude/debug` allowance. That is accepted: the run's debug
+        // log is worth less than a rule with an exception carved through it.
+        denyWrite: [
+          ...credentialDirectories(),
+          ...writeOnlyDenyPaths(),
+          // Not credentials, but a write to any of them runs on the operator's
+          // next shell or login. See `hostPersistencePaths`.
+          ...hostPersistencePaths(),
+          // Inside the granted worktree, and the one thing in it the run must
+          // not have: git metadata is executable by the daemon's own
+          // uncontained git commands. See `gitMetadataDenyPaths`.
+          ...gitMetadataDenyPaths(args.worktree),
+        ],
+      },
+    },
+    // `project` ONLY, and the choice between this and `[]` is the one real
+    // trade in this module.
+    //
+    // `[]` is the tighter setting and it was the first version. It is wrong,
+    // because the SDK loads CLAUDE.md through this same mechanism — the option
+    // doc says so outright ("Must include 'project' to load CLAUDE.md files"),
+    // and it was measured: with sources off, a code word planted in the repo's
+    // own `CLAUDE.md` was invisible to the run. That silently drops CLAUDE.md,
+    // AGENTS.md, PRODUCT.md, DESIGN.md, docs/architecture.md and every nested
+    // `packages/*/CLAUDE.md` from every implement run — the instructions that
+    // make the daemon's output match this repo rather than a generic one.
+    //
+    // What each source carries decides it:
+    //  - `user` — the OPERATOR's `~/.claude/settings.json`, holding their
+    //    personal permission grants (and, on the machine this was reviewed on,
+    //    a plaintext credential). This is the one that must not reach a
+    //    board-driven run, and it is excluded.
+    //  - `local` — `.claude/settings.local.json`, gitignored. The run can WRITE
+    //    its own worktree, so a loaded `local` is a run granting itself
+    //    permissions mid-flight. Excluded.
+    //  - `project` — `.claude/settings.json`, checked in and code-reviewed like
+    //    any other file in the repo, and the carrier for CLAUDE.md. Included.
+    //
+    // A run can still write `.claude/settings.json` in its own worktree, so
+    // `project` is not proof against self-granting either. It does not need to
+    // be: a re-granted TOOL permission is bounded by the sandbox, which is a
+    // kernel profile the settings file cannot reach. That is the whole reason
+    // the boundary was put there instead of here.
+    // The tool-layer ALLOW-list. `disallowedTools` below still carries the
+    // denies as a second, independent mechanism — this is the bound.
+    canUseTool: implementRunToolPolicy(args),
+    gateEveryToolCall: true,
+    // ...but NOT for a read-only spawn, and that exception is a trust
+    // boundary rather than a tuning choice.
+    //
+    // `readOnly` marks the spawns whose OUTPUT IS A VERDICT — the reviewer and
+    // the deep review, whose findings gate `review.autoMerge`. Their cwd is a
+    // worktree checked out from the agent-authored branch, so `CLAUDE.md`,
+    // `AGENTS.md` and `DESIGN.md` in that tree are content the run under review
+    // wrote. Loading the project source there hands the grader its instructions
+    // from the thing being graded.
+    //
+    // This was a real regression introduced by keeping `project`: those spawns
+    // previously ran `--setting-sources local,user`, which excluded the project
+    // source outright, and the commit that changed it framed the difference as
+    // a token cost and nothing more. `assertNoProjectSandboxOverride` guards
+    // `.claude/settings.json` keys; it says nothing about instruction files,
+    // and cannot — an instruction file has no schema to allow-list.
+    //
+    // The implement run keeps `project`, because there the instructions and the
+    // work are the same person's, dropping them costs the repo's own
+    // conventions, and its output is a diff a reviewer then reads. A verdict
+    // has no such second reader.
+    settingSources: args.readOnly === true ? [] : ["project"],
+    // Handed back explicitly, because the line above took it away — see
+    // `harmonyMcpServer`. Without this the run loses `mcp__harmony__*` and can
+    // no longer report its own progress.
+    mcpServers: harmonyMcpServer(),
+    // Paired with the two above: the run sees only the server declared to it,
+    // and no MCP config the operator happens to have registered for themselves.
+    strictMcpConfig: true,
+    // Belt to the sandbox's braces. The kernel deny already stops the file
+    // being read; this stops the value being handed over in the environment,
+    // which no filesystem rule addresses. Wider than
+    // `HARMONY_CREDENTIAL_KEYS` — see `secretEnvKeysToStrip` for why the
+    // operator's OWN tokens matter here, and why it is shaped rather than
+    // enumerated.
+    stripEnvKeys: secretEnvKeysToStrip(),
+    // NOT redundant with the kernel deny — the other half of it. The sandbox
+    // wraps commands; `Read`/`Grep`/`Glob` run in the CLI process and reach
+    // past it. See `credentialToolDeny`.
+    disallowedTools: [
+      ...(args.extraDisallowedTools ?? []),
+      ...credentialToolDeny(),
+      // The WRITE half, covering everything the sandbox `denyWrite`s plus the
+      // shell and login files a write turns into delayed host execution. The
+      // read rules above without these left the tool layer one-sided — see
+      // `credentialWriteToolDeny`.
+      ...credentialWriteToolDeny(args.worktree),
+    ],
+  };
+}
+
+/**
+ * The same containment, as `claude` CLI arguments.
+ *
+ * The CLI runner is the configured fallback (`AgentConfig.runner === "cli"`),
+ * and an operator who selects it must not thereby select their way out of the
+ * boundary. So this exists rather than the CLI path being scoped out.
+ *
+ * It is DERIVED from {@link implementRunContainment} rather than re-specified,
+ * so the two runners cannot drift into disagreeing about what a contained run
+ * may reach — the failure mode that would matter here is the CLI path quietly
+ * keeping an older, wider bound.
+ *
+ * The mapping is not one-to-one, and the one asymmetry is deliberate: the CLI
+ * has no `--sandbox` flag, but `sandbox` is a **settings** key, so it travels
+ * inside `--settings`. `--setting-sources ""` is the CLI spelling of
+ * `settingSources: []`; passing both is not redundant, because `--settings` is
+ * its own layer and is still honoured when the filesystem sources are off —
+ * which is exactly what lets the sandbox survive the isolation that removes
+ * everything else.
+ *
+ * `stripEnvKeys` has no argument form. It is applied by `spawnInGroup`, so a
+ * caller must pass `containment.stripEnvKeys` to the spawn options as well;
+ * these arguments alone do not strip the environment.
+ */
+export function implementRunContainmentCliArgs(args: {
+  worktree: string;
+  extraDisallowedTools?: readonly string[];
+  /**
+   * Spawn that must not run commands (the review pipeline). Turns off
+   * `autoAllowBashIfSandboxed`, so a `Bash(readonly)` grant keeps meaning what
+   * it says instead of being auto-approved because the run is sandboxed.
+   */
+  readOnly?: boolean;
+}): string[] {
+  const containment = implementRunContainment(args);
+  return [
+    "--settings",
+    JSON.stringify({ sandbox: containment.sandbox }),
+    // Same single source as the SDK path, for the same reason: it is what
+    // carries CLAUDE.md, and it excludes the operator's `user` settings.
+    "--setting-sources",
+    containment.settingSources.join(","),
+    // ...which also drops the harmony MCP registration, so it is re-declared
+    // here exactly as the SDK path re-declares it.
+    "--mcp-config",
+    JSON.stringify({ mcpServers: containment.mcpServers }),
+    "--strict-mcp-config",
+    // `--disallowedTools` is variadic, so it goes LAST: a following positional
+    // would be swallowed as another tool name. That is not hypothetical — the
+    // same variadic parsing ate the prompt out of this card's own measurement
+    // script twice before the cause was spotted.
+    "--disallowedTools",
+    containment.disallowedTools.join(","),
+  ];
+}