@join-pantheon/cli 0.30.0 → 0.31.1

package/README.md

@@ -76,13 +76,13 @@ That's it — one command each sets up the **whole machine**: a relay and space
 (them), pantheon wired into whichever agents each of you already has (**user scope** — every project,
 every Conductor window, nothing to commit), the wake-up hook so an agent finishes what a peer is
 waiting for, the **worker** so the machine answers the team even while its human is away (on by
-default when run inside a git repo; `--no-worker` opts out — and a peer can use it only once you
-approve them on this machine with `pantheon wake allow <name>`), native decision alerts, and the menu bar. Each command
-ends with a "You're set" summary, then a short guided setup on a terminal: three questions — your
-name, your role, and (inside a repo) whether a run a teammate wakes may execute commands — and one
-screen of defaults to keep or change: who may wake your machine while you are away, which alerts you
-want, which decisions are yours alone (so agents stop and ask you), the worker's playbook and its base
-branch. `pantheon setup` re-runs it any time. An agent setting you up runs `pantheon setup --questions`,
+default when run inside a git repo; `--no-worker` opts out), native decision alerts, and the menu bar. Each command
+ends with a "You're set" summary, then a short guided setup on a terminal: two questions — your
+name and your role — and one screen of defaults to keep or change: your teammates can hand work to
+your machine while you are away, that work runs your tests and commits to its own branch so it
+arrives ready to review, whichever agent you use (Claude Code, Codex, Cursor or Copilot) answers
+them, which alerts you want, which decisions are yours alone (so agents stop and ask you), the
+worker's playbook and its base branch. `pantheon setup` re-runs it any time. An agent setting you up runs `pantheon setup --questions`,
 asks you in chat, and passes your answers back as flags — to `pantheon setup --yes`, or straight to
 `pantheon start` / `pantheon join`, which apply them the moment the team exists — so nobody has to
 open a terminal. Restart your agent once and ask it *"check pantheon_status"*.
@@ -171,8 +171,32 @@ pantheon profile set --space mobile --human-required pricing   # authority that
 
 The relay checks too: a session whose checkout is not one of the team's repos is refused, and a
 `DELIVERED` must name a commit in one of them, so work from the wrong repo cannot land in a team.
-The worker serves every bound repo from one process, one run at a time, on `pantheon/<team>/<goal>`
-branches. Details and the scenario list: `docs/MULTI-SPACE.md`.
+Details and the scenario list: `docs/MULTI-SPACE.md`.
+
+**Several repos (a frontend, a backend, a mobile app) — set up once.**
+- `pantheon use <team> --here` in the folder that holds them binds every repo inside it, and
+  registers each with the team, in one go.
+- `pantheon repo find` (and `join`, on its own) looks for the team's repos on this machine — in the
+  usual code folders, in a folder you name, and, if you say yes, in the folders your editors and
+  agents have opened. It reads only folder names and git remote addresses; nothing leaves the machine.
+- A clone of one of the team's repos, wherever it lives, is that team's the first time an agent is
+  opened in it — no binding needed.
+- The relay knows each repo by a fingerprint and its everyday name (`web`), never its address.
+
+**One worker, every repo.** The worker serves every repo and folder bound to its team, one run at a
+time, and runs each request where it belongs: in the repo the request names (`the api repo`,
+`` `mobile` ``, `acme/web`), else where the goal's work was delivered, else the repo the asker sent
+it from, else the most recently active one — with the team's other repos here attached read-only
+(clean checkouts, never your working folder) so it can look across them. A request about a team repo
+this machine does not have runs nothing: the asker is told it waits, and it is never answered from
+another repo's code. `pantheon spaces` and `doctor` say what the worker serves and what is not here.
+
+**No git at all (a PM, ops, a founder's docs).** `start` or `join` from a plain folder binds it
+(never your home folder). The worker serves it too: a teammate's question is answered from that
+folder, which the run can read but never change; anything it writes goes to a drafts folder of its
+own, and you are told. Answering from a folder unattended needs Claude Code on that machine (the one
+agent that can be opened a folder to read and held off editing it); with another agent, those requests
+wait for your live session, and the teammate is told.
 
 ### If something is wrong
 
@@ -347,20 +371,23 @@ domain is a conflict, not a committee — routing blocks until one of them drops
 it or delegates. Decide domain ownership out loud before publishing; shared
 decisions belong to whoever answers for them, with delegation covering absence.
 
-When a teammate you approved to wake this machine asks something and no session of yours picks it up, the
+When a teammate asks this machine something and no session of yours picks it up, the
 worker spawns a headless agent run to handle it. Verified end to end: an `ASK` from an idle
 peer's machine was answered in **31 seconds with no human involved**, and:
 
 - the run happens in a **dedicated git worktree on a `pantheon/<goal>` branch** — your checkout and
   your uncommitted work are never touched, and nothing is merged
-- it runs with **only the pantheon message tools** approved; commands stay gated unless a person on
-  this machine grants them (`pantheon policy grant run-commands`, or answering the worker's own request
-  from `pantheon approvals` or the menu bar — never from the ledger) or you pass `--allow-bash`
-- two conditions, both enforced: the team must let the peer wake workers at all (the relay's per-member
-  `may_wake`, set by `pantheon admit <who> --may-wake` — the relay refuses a claim without it), and,
-  unless you chose wake "anyone", a person on THIS machine must have approved them:
-  `pantheon wake allow <who>` (`wake deny`, `wake list`). That list lives only on this machine and
-  nothing about it is sent to the team. Nobody is approved until you approve them.
+- in a repo it runs your tests, commits and pushes to its own branch (setup's default; `pantheon setup
+  --commands no` keeps runs to edits), so work arrives ready to review; a person on this machine can
+  also grant commands later (`pantheon policy grant run-commands`, or answering the worker's own
+  request from `pantheon approvals` or the menu bar)
+- teammates the team lets wake workers (the relay's per-member `may_wake`, which the invites you send
+  include) can hand this machine work — wake "anyone", the default. To approve each teammate on this
+  machine first, choose "only people I approve" (`pantheon setup --wake approved`); then
+  `pantheon wake allow <who>` (`wake deny`, `wake list`) keeps that list, on this machine only, and the
+  first time an unapproved teammate's request needs this machine the menu bar shows "Let <them> start
+  work here? Always / Just this once / No" (or `pantheon approvals`). The same buttons answer the
+  worker's request for commands; granting it runs the request that needed them.
 - upgrading keeps what you had said: teammates you admitted with `--may-wake` are carried over; so is
   everyone the team lets wake if you had chosen "anyone" (or never chose, on a machine set up before
   0.30, when that was the default); a joiner who was never asked keeps the team's founder. The worker
@@ -420,12 +447,21 @@ With `auto` (the default) the order is: the agent a persona pins, then the one y
 then PATH order — and a candidate that is not signed in is skipped and named in the run log, so a
 run never fails on an expired session when another agent could have answered. If nothing is
 signed in, the first on PATH runs and the alert says exactly that, with the sign-in command.
-`pantheon doctor` shows the same choice (`worker agent`). Each backend is driven the way it
-actually works, with the same "no shell unless you said so" rule spelled in its own dialect:
-
-| backend | bash gated (default) | with the command grant (`run-commands` or `--allow-bash`) |
+`pantheon doctor` shows the same choice (`worker agent`).
+
+**Whichever agent you use answers your teammates while you are away** — Claude Code, Codex, Cursor
+or Copilot. Claude Code runs inside its own OS sandbox (macOS and Linux, 2.1.83+), so `auto`
+prefers it when it is installed; Codex, Cursor and Copilot answer too, so a team on any of them is
+never kept waiting. To have Codex, Cursor and Copilot leave requests for you instead,
+`pantheon setup --unsandboxed no` (or `pantheon policy revoke unsandboxed-runs`; a woken run can never
+change it). Kiro answers in your live sessions; for unattended runs the worker uses another installed
+agent. Setup turns commands on for a worker that serves a repo (`pantheon setup --commands no` keeps
+runs to edits). Each backend is driven the way it actually works, with the same commands rule
+spelled in its own dialect:
+
+| backend | bash gated (`--commands no`) | with commands (setup's default in a repo, `run-commands` or `--allow-bash`) |
 |---|---|---|
-| claude-code | `acceptEdits`, no shell, reads held to the worktree, `~/.ssh` `~/.aws` `~/.config/gh` `~/.pantheon` and similar denied; the repo's own `.claude` settings never load (`--setting-sources user`) | the same file rules, plus Claude Code's OS sandbox (macOS/Linux): commands may write only the worktree, its git data and temp dirs, may not read the secret paths, and a run whose sandbox cannot start does not start. Commands: git subcommands (with its run-a-program options denied), the repo's scripts via npm/pnpm/yarn/bun, make, cargo, go, pytest, mvn/gradle, dotnet, plus the committed `.pantheon/commands` on the base branch (one per line; shells, wrappers, package runners like `npx`, and inline code are refused — use `./node_modules/.bin/vitest`). The run names any command it needed that was refused. On Windows, or a Claude Code too old for these settings, the list is all there is — it is not a boundary |
+| claude-code | `acceptEdits`, no shell, reads held to the worktree, `~/.ssh` `~/.aws` `~/.config/gh` `~/.pantheon` and similar denied; the repo's own `.claude` settings never load (`--setting-sources user`) | the same file rules, plus Claude Code's OS sandbox (macOS/Linux): commands may write only the worktree, its git data and temp dirs, may not read the secret paths, and a run whose sandbox cannot start does not start. Commands: git subcommands (with its run-a-program options denied), the repo's scripts via npm/pnpm/yarn/bun, make, cargo, go, pytest, mvn/gradle, dotnet, plus the committed `.pantheon/commands` on the base branch (one per line; shells, wrappers, package runners like `npx`, and inline code are refused — use `./node_modules/.bin/vitest`). The run names any command it needed that was refused. On Windows, or a Claude Code older than 2.1.83, commands run from that same list without the OS sandbox (`pantheon setup --unsandboxed no` keeps those runs to edits) |
 | codex | `--sandbox read-only` (codex has no edits-without-shell mode; reads are not restricted) | `--approve-for-me` (Codex's workspace-write sandbox, its auto-reviewer approves; any command) |
 | cursor | proposes edits, never applies (`-p` without `--force`) | `--force` (any command, no allowlist, no sandbox) |
 | copilot | `--allow-tool=pantheon-worker --allow-tool=write` (edits without shell, Copilot's `write` kind) | `--allow-all-tools` (any command, no allowlist, no sandbox) |
@@ -434,14 +470,17 @@ actually works, with the same "no shell unless you said so" rule spelled in its
 **What the command grant really means.** A run allowed to run commands can edit the repo's own
 scripts and then run them through a listed command (`npm test` runs whatever `package.json` says), so
 the command list alone never contains it. Where Claude Code's sandbox runs (macOS, Linux) that
-sandbox is the boundary. Everywhere else, a command run can do what you can. After every run
+sandbox is the boundary. Everywhere else, a command run can read what you can — and, outside
+Codex's own write sandbox, change it. After every run
 Pantheon checks for the plain ways it could have widened what the NEXT run may do — a grant or wake
 approval it added, a loosened wake setting, a changed relay address, a queued menu-bar action —
 takes them back and tells you. That is a check after the fact, not a boundary: a run that can do
 what you can could change something it does not look at. Pantheon also refuses to send an act that
 holds this machine's key, a team token, or text in the shape of a common secret (a private key, a
 cloud or API token) — a guard against a pasted secret, not against one a run takes care to disguise.
-What keeps your secrets from a run is that it cannot read them: the denies and the sandbox above.
+With Claude Code, what keeps your secrets from a run is that it cannot read them: the denies and the
+sandbox above. With other agents, grant commands only where you would be comfortable with the run
+having your access.
 
 Claude Code, Cursor and Codex are verified with **real live woken runs** — an idle machine answering a
 peer's ASK end to end. Codex quirks the tooling handles for
@@ -571,7 +610,8 @@ The rules that make this safe to commit into a shared repo:
 
 ## Guardrails
 
-All enforced in the relay, not in a prompt — a prompt can be argued out of its instructions.
+All enforced in code — by the relay, or by each machine where the relay is not to be trusted —
+never in a prompt: a prompt can be argued out of its instructions.
 
 | Guard | Default | Why |
 |---|---|---|
@@ -587,9 +627,10 @@ All enforced in the relay, not in a prompt — a prompt can be argued out of its
 | Membership | explicit allowlist, ed25519 | the token is not a credential; a name needs its key |
 | Invites | single-use, expiring | a leaked link is inert once redeemed or timed out |
 | Claims | one session per obligation | parallel Conductor workspaces cannot duplicate work |
-| Wake rights | `pantheon wake allow`, per machine; `--may-wake`, per member for the team | only peers the team lets wake AND you approved here may start a run on your machine |
+| Wake rights | `pantheon wake allow`, per machine; `--may-wake`, per member for the team | under "anyone" (the default): every peer the team lets wake; under "approved": only those you also approved here. Checked by the worker before a run starts, and by the relay at its claim |
 | Run budget | 12/hour, 1 concurrent | a peer cannot drain your tokens |
 | Personas | tighten-only | a persona file — even one a teammate committed — can lower caps and turn bash off, never the reverse |
+| Signed acts | every act and goal, ed25519, since 0.31 | checked on each receiving machine against the key it pinned for the sender: the relay cannot forge, alter, re-file or replay a teammate's request without that machine noticing, and a worker runs only requests that check out. A teammate's changed key is held back until you confirm it (`pantheon trust`) |
 | Worktree hygiene | no secrets on disk | credentials reach a woken run through its environment only; run scratch files are git-excluded |
 | Verifiable delivery | branch + commit required | "I wrote the file" is not checkable from another machine |
 | Durable state | goals + obligations on disk | a relay restart used to discard every open goal |
@@ -619,8 +660,9 @@ pantheon mcp                       the stdio MCP server — your agent runs this
 ```
 
 `pantheon help --all` lists everything. `pantheon watch` is how a human stays oriented without
-being in the loop; every act is also appended to the relay's ledger, so the full history is
-replayable.
+being in the loop; every act is also appended to the relay's ledger, so a goal's history is
+replayable while it is open — closed goals are compacted once the space needs room, so export what
+you need to keep with `pantheon audit --json`.
 
 ## What this still is not
 
@@ -631,18 +673,55 @@ replayable.
   the next real gap: `DELIVERED` is now verifiable, but *conformance to the contract* is not.
 - **Nothing fetches the delivered commit for you.** The relay requires a ref and the receiving
   delegate is told to check it, but there is no `pantheon fetch` helper yet.
-- **The space token is still a shared secret** for *reaching* the relay, even though membership is
-  now key-based. Treat the relay endpoint as semi-public and rely on the allowlist.
-- **A woken run is trusted with your repo.** `--allow-bash` in particular means a peer's request
-  can execute commands on your machine. Approve wakers (`pantheon wake allow`) deliberately.
+- **The space token still reads a team's history until someone is removed.** Joining takes an
+  admitted key, but in a team that has never removed anyone the token alone can read its history
+  over HTTP (older clients need that); after any removal, reads need an admitted key. Share invite
+  links, not the token.
+- **Commands on a woken run are on by default in a repo.** A run works in its own worktree and
+  branch, inside your agent's sandbox where it has one (see above). `pantheon setup --commands no`
+  keeps runs to edits, and `pantheon setup --wake approved` lets you approve each teammate first.
+
+## Is Pantheon safe for my team?
+
+Short answer: your teammates' agents can hand your machine work while you are away — it runs in its
+own copy of the repo and is delivered on a branch for your review — and whoever runs the relay
+cannot fake or alter a teammate's request. What that means in practice:
+
+- **Pantheon never uploads your code, credentials or repo.** The relay passes messages between
+  agents and has no filesystem or shell access to anyone's computer; what leaves your machine is
+  what an agent writes into a message.
+- **The relay can read the messages** (they are not end-to-end encrypted), so treat a team space
+  like a shared team channel. It **cannot write one in a teammate's name or change one**: with 0.31
+  on the relay and on your machine, every message is signed by its sender and checked against the
+  key your machine keeps for them, and one that does not check out is marked NOT VERIFIED and never
+  starts work. (The first time your machine meets a teammate it takes their key from the member
+  list; a changed key later is held back until you confirm it.) It can still delay or withhold messages.
+- **Your teammates can hand your machine work while you are away.** `pantheon start` in a repo turns
+  the worker on (`--no-worker` leaves it off). Each run works in its own copy of the repo, runs your
+  tests, and delivers on its own branch for your review; runs are capped at 12 an hour, and
+  `pantheon panic` pauses all of it at once. `pantheon wake list` shows who can hand you work, and
+  `pantheon setup --wake approved` lets you approve each teammate first.
+- **You can see and change all of it:** `pantheon policy` (what the worker may do, including whether
+  Pantheon updates itself), `pantheon trust` (the teammates' keys this machine checks messages
+  against), `pantheon audit`, `pantheon doctor`.
+
+For a team of five, the defaults are the setup: everyone's agent answers the team while they are
+away, work arrives tested on its own branch, and decisions you reserved still come to you. Prefer to
+review every change by hand on one machine? `pantheon setup --commands no` there. When Pantheon says
+a teammate's key changed, check it with them before `pantheon trust`. Claude Code runs inside its
+OS sandbox; Codex answers inside its own workspace sandbox, and Cursor and Copilot run commands
+without asking, as you (`pantheon setup --unsandboxed no` has them leave requests for you). The
+full model, and how to report a problem: [joinpantheon.network/security](https://www.joinpantheon.network/security).
 
 ## Privacy, data, and support
 
 The hosted relay at `relay.joinpantheon.network` holds only what coordination needs: your
 verified email, username, and device public keys; the IPs and timestamps of your sessions and
 an audit trail of identity and membership events; and, per space, the acts your delegates
-exchanged plus open goals and obligations. Your code, credentials, and repo never leave your
-machine — the relay has no filesystem or shell access by design.
+exchanged plus open goals and obligations. Pantheon never uploads your code, credentials or repo,
+and the relay has no filesystem or shell access by design: what leaves your machine is what an
+agent writes into a message (and Pantheon refuses to send its own keys, team tokens, or text in the
+shape of a common secret).
 Whoever operates the relay can read those acts — the operator dashboard shows each space's
 message history — so treat a space like a shared team channel, not a private notebook.
 

package/dist/agents.js

@@ -6,7 +6,7 @@ import { join, dirname, isAbsolute } from "node:path";
 import { launcher, kiroDir } from "./install.js";
 import { agentSpawn, which } from "./which.js";
 import { PANTHEON_TOOL_NAMES, PANTHEON_TOOLS } from "./tools.js";
-import { claudeRunSettings, NO_CLAUDE_FEATURES, runTmpDir, sandboxCacheEnv } from "./claude-confine.js";
+import { claudeRunSettings, NO_CLAUDE_FEATURES, runTmpDir, sandboxCacheEnv, versionAtLeast } from "./claude-confine.js";
 export function launchArgs(agent, prompt, name) {
     if (agent === "claude-code")
         return ["--name", name, prompt];
@@ -125,7 +125,16 @@ export const SIGN_IN_CHECK = {
 };
 export const NEEDS_SIGN_IN_BEFORE_SPAWN = new Set(["kiro"]);
 export const NOT_FOR_UNATTENDED_RUNS = new Set(["kiro"]);
-export const KIRO_UNATTENDED_REFUSAL = "Kiro cannot yet be fenced to its worktree for unattended runs; the worker uses another installed agent, or none";
+export const KIRO_UNATTENDED_REFUSAL = "Kiro answers in your live sessions; for runs while you are away the worker uses another installed agent (Claude Code, Codex, Cursor or Copilot)";
+export const SANDBOXED_FOR_UNATTENDED = new Set(["claude-code"]);
+export const unsandboxedRefusal = (label) => `${label} is set to leave teammates' requests for you on this machine, so this one waits for your next session. ` +
+    `To have ${label} answer them while you're away: pantheon policy grant unsandboxed-runs`;
+export function agentsNeedingUnsandboxed(available = detectAvailable()) {
+    if (available.some((a) => SANDBOXED_FOR_UNATTENDED.has(a.backend.id)))
+        return [];
+    return [...new Set(available.filter((a) => !NOT_FOR_UNATTENDED_RUNS.has(a.backend.id)).map((a) => a.backend.label))];
+}
+export const claudeSandboxable = (f, os = process.platform) => os !== "win32" && !!f.settings && versionAtLeast(f.version, "2.1.83");
 export function kiroSignedIn(binary, run = runStatus, env = process.env, home = homedir(), os = platform()) {
     if (env.KIRO_API_KEY)
         return { ok: true, detail: "signed in (KIRO_API_KEY in the environment)" };
@@ -221,6 +230,14 @@ export function chooseAgent(preferred, opts = {}) {
             skipped.push({ backend: c.backend, why: KIRO_UNATTENDED_REFUSAL });
     if (usable.length)
         order.splice(0, order.length, ...usable);
+    if (!opts.unsandboxedOk) {
+        const boxed = order.filter((c) => SANDBOXED_FOR_UNATTENDED.has(c.backend.id));
+        for (const c of order)
+            if (!SANDBOXED_FOR_UNATTENDED.has(c.backend.id) && boxed.length)
+                skipped.push({ backend: c.backend, why: unsandboxedRefusal(c.backend.label) });
+        if (boxed.length)
+            order.splice(0, order.length, ...boxed);
+    }
     for (const c of order) {
         const s = state(c.backend, c.binary);
         if (!s || s.ok || s.unknown)
@@ -230,9 +247,15 @@ export function chooseAgent(preferred, opts = {}) {
     const first = order.find((o) => !NEEDS_SIGN_IN_BEFORE_SPAWN.has(o.backend.id)) ?? order[0];
     return { backend: first.backend, binary: first.binary, signIn: state(first.backend, first.binary), because: `${first.because} (none signed in)`, skipped };
 }
-export function unattendedRefusal(c) {
+export function unattendedRefusal(c, o = {}) {
     if (NOT_FOR_UNATTENDED_RUNS.has(c.backend.id))
         return KIRO_UNATTENDED_REFUSAL;
+    if (!SANDBOXED_FOR_UNATTENDED.has(c.backend.id) && !o.unsandboxedOk) {
+        return c.because === "pinned"
+            ? `woken runs here are pinned to ${c.backend.label} (a persona's agent: line, or the worker's --agent), which is set to leave teammates' requests for you, so this one waits for your next session. ` +
+                `To have ${c.backend.label} answer them: pantheon policy grant unsandboxed-runs — or unpin it so Claude Code takes them`
+            : unsandboxedRefusal(c.backend.label);
+    }
     if (!NEEDS_SIGN_IN_BEFORE_SPAWN.has(c.backend.id) || c.signIn?.ok)
         return null;
     return `${c.backend.label} is not signed in (${c.signIn?.detail ?? "not checked"}), and signed out it opens a browser to log in, so it is not started while you are away — ${SIGN_IN_CHECK[c.backend.id].fix}`;
@@ -244,7 +267,8 @@ export function describeChoice(c) {
 export function skippedSummary(c) {
     if (!c.skipped.length)
         return "";
-    const why = [...new Set(c.skipped.map((s) => (s.why === KIRO_UNATTENDED_REFUSAL ? `${s.backend.label} cannot run unattended yet` : "not signed in")))];
+    const why = [...new Set(c.skipped.map((s) => (s.why === KIRO_UNATTENDED_REFUSAL ? `${s.backend.label} cannot run unattended yet`
+            : s.why === unsandboxedRefusal(s.backend.label) ? `${s.backend.label} has no sandbox` : "not signed in")))];
     return `${c.skipped.length} skipped (${why.join("; ")})`;
 }
 export function resolveAgent(preferred) {
@@ -370,19 +394,15 @@ export function decodeCommandsFile(b) {
     return text.includes("\0") ? null : text;
 }
 export const REPO_RULES_ARGV_MAX = 3_000;
-export const COMMAND_GRANT_SCOPE = "a granted run starts in its own worktree on a pantheon/* branch and runs commands as you, with your network access. " +
-    "The command list is not a boundary on its own: the run can edit the repo's scripts (package.json, a Makefile, a test file) and then run them " +
-    "through a listed command such as npm test, so whatever it can run, it can make run anything. " +
-    "Claude Code (macOS and Linux): the boundary is Claude Code's OS sandbox — every command, and everything it starts, may write only the run's worktree, " +
-    "its repo's shared git data (never the hooks or config) and the temp dirs, may not read ~/.ssh, ~/.aws, ~/.config/gh, ~/.gnupg, ~/.netrc, " +
-    "~/.docker/config.json, ~/.kube, ~/.git-credentials or ~/.pantheon, and may reach the network; if the sandbox cannot start the run does not start. " +
-    "It may run only git subcommands (status, diff, log, add, commit, push of its own branch, fetch, checkout …), the repo's scripts through npm/pnpm/yarn/bun, make, cargo, go, " +
-    "pytest, mvn/gradle and dotnet, plus what the committed .pantheon/commands on the base branch lists (a shell, a wrapper, a package runner or inline code is never accepted there). " +
-    "What it can still do: change anything in its worktree, push its branch, and read the rest of your files. " +
-    "On a Claude Code older than 2.1.83 (it cannot refuse to run unsandboxed), or on Windows, it has only the list — no boundary; if Pantheon cannot tell what the installed Claude Code supports, that run gets no commands. " +
-    "Codex: any command, inside Codex's own workspace-write sandbox, approved by Codex's auto-reviewer. " +
-    "Cursor, Copilot and Kiro: any command, as you, with no sandbox — they take no allowlist from Pantheon, so such a run can read and change anything you can, " +
-    "Pantheon's own files included (a changed policy or config file is put back after the run, and you are told).";
+export const COMMAND_GRANT_SCOPE = "a run with commands works in its own worktree on a pantheon/* branch: it runs your tests and builds, commits, pushes its own branch for your review, and never merges. " +
+    "Claude Code (macOS and Linux) runs those commands inside its OS sandbox: they write only the run's worktree, its git data and the temp dirs, stay clear of your keys and credentials " +
+    "(~/.ssh, ~/.aws, ~/.config/gh, ~/.gnupg, ~/.netrc, ~/.docker/config.json, ~/.kube, ~/.git-credentials, ~/.pantheon), and use git, the repo's scripts through npm/pnpm/yarn/bun, " +
+    "make, cargo, go, pytest, mvn/gradle and dotnet, plus whatever the committed .pantheon/commands on the base branch lists. " +
+    "Codex runs them in its own workspace-write sandbox, approved by its auto-reviewer. " +
+    "Cursor and Copilot run any command without asking, as you and with no sandbox; Claude Code on Windows or before 2.1.83 runs its listed commands the same way, without its sandbox. " +
+    "After every run Pantheon checks its own settings and puts back any change a run made to them; " +
+    "pantheon setup --unsandboxed no leaves those requests for you instead. Kiro answers in your live sessions. " +
+    "Turn commands off any time: pantheon policy revoke run-commands.";
 export function headlessSpawn(opts) {
     const l = launcher();
     const identity = {
@@ -428,6 +448,7 @@ export function headlessSpawn(opts) {
             const runTmp = runTmpDir(opts.runHome);
             const c = claudeRunSettings({
                 allowBash: opts.allowBash, worktree: opts.worktree, runHome: opts.runHome, pantheonHome: opts.claude.pantheonHome,
+                ...(opts.readOnlyDirs?.length ? { readOnlyDirs: opts.readOnlyDirs } : {}),
                 runTmp, bashRules, version: f.version, ...(opts.claude.home ? { home: opts.claude.home } : {}),
                 ...(opts.os ? { os: opts.os } : {}), ...(opts.claude.userSettings ? { userSettings: opts.claude.userSettings } : {}),
             });
@@ -435,6 +456,9 @@ export function headlessSpawn(opts) {
                 extra.push("--permission-prompts", "none");
             if (f.settingSources)
                 extra.push("--setting-sources", "user");
+            if (f.addDir && f.settings)
+                for (const d of c.readOnly)
+                    extra.push("--add-dir", d);
             if (f.settings) {
                 const file = join(opts.runHome, "claude-settings.json");
                 writeFiles.push({ path: file, contents: JSON.stringify(c.settings, null, 2) });

package/dist/claude-confine.js

@@ -12,6 +12,7 @@ export function parseClaudeHelp(help, version = null) {
         settings: /(^|\s)--settings\s/m.test(help),
         settingSources: /(^|\s)--setting-sources\b/m.test(help),
         disallowedTools: /(^|\s)--disallowed-?tools\b/im.test(help),
+        addDir: /(^|\s)--add-dir\b/m.test(help),
     };
 }
 export function versionAtLeast(a, b) {
@@ -125,14 +126,15 @@ function userExcludedCommands(file) {
         return [];
     }
 }
+const SECRET_FILE_GLOBS = [".env", ".env.*", "*.pem", "*.key", "*.p12", "*.pfx", "id_rsa*", "id_ed25519*", ".npmrc", ".netrc", "credentials*", "*.keystore", "service-account*.json"];
 const PANTHEON_HOME_ENTRIES = ["config.json", "config.json.bak", "config.json.lock", "worker-policy.json", "profile.json", "continued.json", "bin", "ops", "run-homes", "logs", "mcp", "data"];
-function aroundWorktree(top, worktree, named) {
+function aroundWorktree(top, keeps, named) {
+    const keep = (typeof keeps === "string" ? [keeps] : [...keeps]).map((k) => resolve(k));
     const out = [];
-    let level = top;
-    while (level !== worktree) {
-        const next = relative(level, worktree).split(sep)[0];
-        if (!next || next === "..")
-            break;
+    const walk = (level, isTop) => {
+        if (keep.includes(resolve(level)))
+            return;
+        const nexts = new Set(keep.map((k) => relative(level, k).split(sep)[0]).filter((n) => !!n && n !== ".." && !isAbsolute(n)));
         let names = [];
         try {
             names = readdirSync(level);
@@ -144,11 +146,13 @@ function aroundWorktree(top, worktree, named) {
         catch {
             return !n.includes(".");
         } };
-        for (const n of new Set([...names, ...(level === top ? named : [])]))
-            if (n !== next)
+        for (const n of new Set([...names, ...(isTop ? named : [])]))
+            if (!nexts.has(n))
                 out.push({ abs: join(level, n), dir: isDir(n) });
-        level = join(level, next);
-    }
+        for (const n of nexts)
+            walk(join(level, n), false);
+    };
+    walk(top, true);
     return out;
 }
 export function claudeRunSettings(i) {
@@ -163,16 +167,25 @@ export function claudeRunSettings(i) {
     ];
     const seen = new Set();
     const denied = [];
+    const secretTargets = targets.filter((t) => t.abs !== resolve(i.pantheonHome));
+    const readOnly = (i.readOnlyDirs ?? []).map((d) => resolve(d)).filter((d) => {
+        const bad = secretTargets.find((t) => inside(d, t.abs) || inside(t.abs, d));
+        if (bad)
+            notes.push(`${d} is not opened to the run: it holds or is inside ${bad.abs}`);
+        return !bad;
+    });
+    const keeps = [worktree, ...readOnly];
     for (const t of targets) {
         if (seen.has(t.abs))
             continue;
         seen.add(t.abs);
-        if (inside(worktree, t.abs)) {
+        const kept = keeps.filter((k) => inside(k, t.abs));
+        if (kept.length) {
             if (worktree === t.abs) {
                 notes.push(`${t.abs} is this run's worktree, so it is not denied to the run`);
                 continue;
             }
-            for (const d of aroundWorktree(t.abs, worktree, t.abs === resolve(i.pantheonHome) ? PANTHEON_HOME_ENTRIES : []))
+            for (const d of aroundWorktree(t.abs, kept, t.abs === resolve(i.pantheonHome) ? PANTHEON_HOME_ENTRIES : []))
                 if (!seen.has(d.abs)) {
                     seen.add(d.abs);
                     denied.push(d);
@@ -181,10 +194,13 @@ export function claudeRunSettings(i) {
         }
         denied.push(t);
     }
-    const fileRules = denied.flatMap((t) => {
-        const p = `${ruleSpelling(t.abs, home, os)}${t.dir ? "/**" : ""}`;
-        return [`Read(${p})`, `Edit(${p})`];
-    });
+    const fileRules = [
+        ...denied.flatMap((t) => {
+            const p = `${ruleSpelling(t.abs, home, os)}${t.dir ? "/**" : ""}`;
+            return [`Read(${p})`, `Edit(${p})`];
+        }),
+        ...readOnly.flatMap((d) => [`Edit(${ruleSpelling(d, home, os)}/**)`, ...SECRET_FILE_GLOBS.map((g) => `Read(${ruleSpelling(d, home, os)}/**/${g})`)]),
+    ];
     if (!i.allowBash) {
         const permissions = { deny: ["Bash", "PowerShell", ...fileRules] };
         if (versionAtLeast(i.version, "2.1.257"))
@@ -192,7 +208,7 @@ export function claudeRunSettings(i) {
         else
             notes.push(`reads outside the worktree are not blocked wholesale (needs Claude Code 2.1.257+, this is ${i.version ?? "an unknown version"}) — only the secret paths are denied`);
         notes.push("edits only: no shell, file tools held to the worktree, secrets and Pantheon's files denied");
-        return { settings: { permissions }, notes, sandboxed: false };
+        return { settings: { permissions }, notes, sandboxed: false, readOnly };
     }
     const excluded = userExcludedCommands(i.userSettings);
     if (excluded.length)
@@ -203,7 +219,7 @@ export function claudeRunSettings(i) {
     };
     if (os === "win32") {
         notes.push("no OS sandbox on Windows (Claude Code has none there): the command list is the only line, and it is not a boundary; commands run through Git Bash only (the PowerShell tool is denied), so without Git Bash this run has no shell");
-        return { settings: { permissions }, notes, sandboxed: false };
+        return { settings: { permissions }, notes, sandboxed: false, readOnly };
     }
     const failsClosed = versionAtLeast(i.version, "2.1.83");
     const hooks = join(resolve(i.runHome), "git-hooks");
@@ -214,7 +230,7 @@ export function claudeRunSettings(i) {
         allowUnsandboxedCommands: false,
         filesystem: {
             allowWrite: [...new Set([resolve(i.runTmp), resolve(tmpdir())])],
-            denyWrite: [],
+            denyWrite: readOnly.map((d) => sandboxSpelling(d, home)),
             denyRead: denied.map((t) => sandboxSpelling(t.abs, home)),
             allowRead: [hooks],
         },
@@ -222,10 +238,10 @@ export function claudeRunSettings(i) {
     };
     if (!failsClosed) {
         notes.push(`this Claude Code (${i.version ?? "version unknown"}) cannot refuse to run a command when its sandbox does not start — update it to 2.1.83 or later; until then the command list is the only line, and it is not a boundary`);
-        return { settings: { permissions, sandbox }, notes, sandboxed: false };
+        return { settings: { permissions, sandbox }, notes, sandboxed: false, readOnly };
     }
     notes.push(`sandboxed: commands write only the worktree, its repo's git data and the temp dirs; the secret paths and Pantheon's files are unreadable; network allowed`);
-    return { settings: { permissions, sandbox }, notes, sandboxed: true };
+    return { settings: { permissions, sandbox }, notes, sandboxed: true, readOnly };
 }
 export function runTmpDir(runHome) {
     const saltFile = join(runHome, ".tmp-salt");