pi-session-mcp 0.8.3 → 0.12.0

package/docs/adr/0003-post-mvp-maintenance.md

@@ -53,8 +53,8 @@ Changes that keep the public MCP contract (tools, fields, states, error codes) s
 
 ## Revisit triggers
 
-- **E (isolation research):** coding profiles are used on non-disposable repositories or with untrusted content, at the latest before a local writer runs on real repositories. This trigger fired on 2026-10-15: coding profiles had written on non-disposable repositories. Sprint 4 authorizes the isolation decision as the one next investment, an options comparison in ADR 0008, not an implementation; see [#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79) and the [Sprint 4 decision](../sprints/2026-10-15-s4-decision.md).
-- **C (bounded wait):** clients routinely need more than about five polls per turn, or client tool-call limits or approval prompts make polling costly.
+- **E (isolation research):** coding profiles are used on non-disposable repositories or with untrusted content, at the latest before a local writer runs on real repositories. This trigger fired on 2026-10-15: coding profiles had written on non-disposable repositories. Sprint 4 authorizes the isolation decision as the one next investment, an options comparison in ADR 0008, not an implementation; see [#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79), the [Sprint 4 decision](../sprints/2026-10-15-s4-decision.md) and [ADR 0008](0008-coding-profile-isolation.md), accepted for Linux on 2026-10-18 (option 1, wrapped registration; acceptance pending).
+- **C (bounded wait):** clients routinely need more than about five polls per turn, or the uncached controller input attributable to polling becomes material in a measurement like the M1 A/B, or client tool-call limits or approval prompts make polling costly. Re-evaluated on 2026-10-18 with the [M1 A/B](../evaluation/m1-ab-proposal-2026-10-18/results/README.md) (#91): 1–3 running polls per turn, quality kept, the skill guidance of #86 already reduced avoidable calls; candidate C stays rejected.
 - **D (persistence research):** a client or server restart loses useful work in practice.
 - **F (remote architecture):** a concrete remote or mobile use case that SSH or existing remote-development workflows cannot satisfy.
 - **B-type work:** repeated setup or diagnosis friction beyond version drift. This trigger fired for the client-version allowlist; see [ADR 0004](0004-client-contract-not-version.md).

package/docs/adr/0006-pi-extension-allowlist.md

@@ -1,6 +1,8 @@
 # ADR 0006: Execution profiles may load pinned Pi extensions
 
-**Status:** Accepted (2026-10-11). Issue #34. Design:
+**Status:** Accepted (2026-10-11); amended by
+[ADR 0010](0010-read-only-extension-tools.md) for granted extension tools in
+read-only profiles. Issue #34. Design:
 [Pi extensions design](../pi-extensions-design.md).
 
 Amended by [ADR 0007](0007-profile-skill-selection.md) for skills that extension

package/docs/adr/0008-coding-profile-isolation.md

@@ -0,0 +1,295 @@
+# ADR 0008: Isolation for coding profiles on non-disposable repositories
+
+**Status:** Accepted for Linux (2026-10-18, maintainer decision on the
+[decision brief](../reviews/2026-10-18-adr-0008-decision-brief.md)); proposed
+2026-10-16. macOS keeps the Sprint 4 interim rules. The Linux setup's acceptance
+below passed on 2026-10-18 for one writer of this repository
+([evidence](../evaluation/isolation-acceptance-2026-10-18/README.md)); the interim
+rules end on Linux for coding work that runs through an accepted wrapped
+registration. Issue
+[#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79). Follows the
+fired isolation trigger of [ADR 0003](0003-post-mvp-maintenance.md#revisit-triggers)
+and the [Sprint 4 decision](../sprints/2026-10-15-s4-decision.md).
+
+## Context
+
+Coding profiles have written on non-disposable repositories (maintainer,
+2026-10-15). ADR 0003 deferred isolation until coding profiles are used on
+non-disposable repositories or with untrusted content, at the latest before a
+local writer runs on real repositories; that point has passed. Sprint 4
+chose this decision as the one next investment and ruled out any runtime
+change before it is accepted.
+
+Facts the options must meet:
+
+- A `coding` profile grants the built-in tools `read`, `bash`, `edit`,
+  `write`, `grep`, `find` and `ls` ([`src/session-tools.ts`](../../src/session-tools.ts)),
+  plus granted MCP and extension tools. Pi runs inside the server process
+  (ADR 0002): `edit` and `write` are file writes of the server's own Node.js
+  process. `bash` starts a shell, and `grep` and `find` start `rg` and `fd`,
+  which the SDK downloads into its tool directory when they are missing (Pi
+  SDK 1.2.0, `core/tools/` and `utils/tools-manager.js`), in `read-only`
+  profiles too.
+- Other child processes exist too. A granted external MCP server is started
+  with the workspace as its working directory and with host environment values
+  named in its `envFrom` ([`src/mcp-stdio-client.ts`](../../src/mcp-stdio-client.ts)).
+  The Cursor runtime of `pi-cursor-sdk` starts `git`, `ssh`, `gh` and its own
+  MCP servers, in `read-only` profiles too ([threat model](../threat-model.md#residual-risks)).
+- One server process serves every session of its client. Whatever confines
+  that process confines all of its sessions alike, so it can only allow the
+  union of their workspaces, plus what the process itself needs: its
+  installation, configuration and skill files, Pi's agent directory, temporary
+  files, the tool directory and the provider network.
+- A workspace alias selects a working directory, not a boundary; symlinks and
+  Pi tools reach whatever the OS identity can reach. Pi's agent directory holds
+  provider authentication and the installed extension packages that
+  allowlisted profiles load.
+- A linked Git worktree shares `hooks/` and `config` with its main repository
+  ([gitrepository-layout](https://git-scm.com/docs/gitrepository-layout),
+  [git-worktree](https://git-scm.com/docs/git-worktree));
+  `extensions.worktreeConfig` adds a per-worktree scope but removes no sharing
+  ([git-config](https://git-scm.com/docs/git-config)). Local configuration
+  such as `core.fsmonitor` or `diff.external` runs commands, so a writer that
+  changes a repository's `.git` can run code in the operator's later Git
+  commands.
+- Linux and macOS are supported platforms. macOS live acceptance on real
+  hardware (R10, R11) passed for Claude Code on 2026-10-16 (release 0.8.3);
+  it covers setup and smoke, not containment, and Codex on macOS is not
+  established. The server runs without root.
+- Each client starts its own server over stdio, so a client can register a
+  second server under another name with another command. A registration that
+  setup did not make is not bound to a build and not owned or verified by
+  setup ([installation](../installation.md#if-the-build-changed-first)).
+
+## Threats
+
+| Threat | Acting through |
+| --- | --- |
+| T1 model error | the session's tools |
+| T2 prompt injection from repository content or `AGENTS.md` | the session's tools |
+| T3 host code execution later: changed `.git` hooks or config, Pi's agent directory, shell start-up files, scheduled jobs | writes outside the change the operator reviews |
+| T4 credential use: push, SSH, tokens | `bash`, MCP and extension children |
+| T5 exfiltration of readable data | the network, including the provider connection |
+| T6 allowlisted extension code | trusted code with the server's rights (ADR 0006) |
+
+## Options
+
+Sources were read on 2026-10-16.
+
+1. **Operator-environment containment, no server change.** A second client
+   registration for coding work (for example `pi-coding`) starts the server
+   inside a boundary: rootless Podman (`podman run -i --rm …`) or a separate
+   OS user. The host registration stays for read-only work, and Claude Code
+   and Codex stay on the host. Inside the boundary only the writer's full
+   clone is writable, its `.git/hooks` and `.git/config` are mounted
+   read-only, Pi's agent directory is a separate copy or read-only, and no SSH
+   agent, GitHub token or Git credential helper is passed in.
+   - Confines the whole server process tree: `edit`, `write`, `bash`, `rg`,
+     `fd`, MCP and extension children, and limits the reach of extension
+     code.
+   - One wrapped registration sees the union of what it mounts. Writers are
+     isolated from each other only with one boundary per writer.
+   - Linux first. On macOS it needs a Linux VM (for example Lima or Podman
+     machine); no macOS VM setup has been tried or accepted (R10/R11 cover
+     setup and smoke only).
+   - Adds no code, dependency or platform path to the server. The operator
+     carries the setup, and setup does not own or verify the wrapped
+     registration.
+   - Limits: network egress stays possible unless the boundary removes it,
+     and every writable mount stays writable.
+2. **In-server layered sandbox.** Start the server with the Node.js
+   permission model (`--permission`, `--allow-fs-write` for the aliases) to
+   confine `edit` and `write`, and wrap each `bash` child in bubblewrap on
+   Linux and `sandbox-exec` (Seatbelt) on macOS, as Claude Code does for its
+   shell tool ([Claude Code sandboxing](https://code.claude.com/docs/en/sandboxing)).
+   - Node defines its permission model as a guard "to reduce the blast radius
+     of mistakes in trusted application code", not "a security boundary
+     against intentional misuse"
+     ([Node SECURITY.md](https://github.com/nodejs/node/blob/main/SECURITY.md));
+     symlinks and existing file descriptors bypass it by design
+     ([permissions](https://nodejs.org/docs/latest-v24.x/api/permissions.html)).
+     Node security releases fixed bypasses of its checks in
+     [December 2025](https://nodejs.org/en/blog/vulnerability/december-2025-security-releases),
+     [June 2026](https://nodejs.org/en/blog/vulnerability/june-2026-security-releases)
+     and [July 2026](https://nodejs.org/en/blog/vulnerability/july-2026-security-releases).
+   - `bash`, `rg`, `fd`, MCP servers and extension children need
+     `--allow-child-process`, which leaves them outside Node's model; a `bash`
+     wrapper confines only `bash`.
+   - bubblewrap needs unprivileged user namespaces, which Ubuntu 24.04
+     restricts through AppArmor by default
+     ([Ubuntu](https://ubuntu.com/blog/ubuntu-23-10-restricted-unprivileged-user-namespaces));
+     `sandbox-exec` is deprecated and its profile language is not API
+     ([Apple DTS](https://developer.apple.com/forums/thread/777509)).
+   - A partial form, a `bash` wrapper that only protects `.git/hooks` and
+     `.git/config`, is false assurance: `edit` and `write` reach the same files
+     from the server process.
+   - Adds two platform-specific sandbox paths and a launch-mode change to a
+     deliberately small server. Claude Code's own built-in file tools also run
+     outside its sandbox, which is the same gap.
+3. **Linux whole-process self-restriction.** The server restricts itself with
+   Landlock (and seccomp) at start
+   ([landlock(7)](https://man7.org/linux/man-pages/man7/landlock.7.html)).
+   - Covers in-process writes and every child, but is Linux-only, needs a
+     native addon or helper, applies to all threads only with kernel 7.0
+     (`TSYNC`), and gives every session the union of all aliases. Network rules
+     cover TCP ports only, and only from kernel 6.7.
+4. **One sandboxed worker process per session.** Move each Pi session out of
+   process into a worker confined to its own workspace, with the server
+   relaying MCP calls.
+   - The only server-side option with per-session confinement of every tool.
+   - Amends ADR 0002 and adds process supervision, a relay protocol, abort and
+     close across processes, and platform wrappers; the largest change.
+
+| Threat | 1 wrapped registration | 2 in-server sandbox | 3 Landlock | 4 worker per session |
+| --- | --- | --- | --- | --- |
+| T1, T2 writes outside the workspace | confined to the mounts | `bash` only reliably; in-process writes best effort | confined to the union | confined per session |
+| T3 later host code execution | prevented by read-only `.git` and agent directory | partly (`bash` only) | partly (union of aliases) | per session, with read-only `.git` |
+| T4 credentials | not passed in | `bash` only | not addressed | depends on the worker's environment |
+| T5 exfiltration | only if the boundary removes the network; the provider stays reachable | `bash` network only | TCP rules only | with an OS wrapper |
+| T6 extension code | reach limited to the boundary | not confined | confined to the union | confined per session |
+
+## Decision
+
+Accepted on 2026-10-18 as proposed below, for Linux first:
+
+- Direction: option 1 in its wrapped-registration form, rootless Podman with one
+  boundary per writer and a full clone per writer; a separate OS user remains the
+  documented alternative.
+- macOS keeps the Sprint 4 interim rules; a VM runbook is not planned yet.
+- The open questions below (auth refresh, external MCP grants and `envFrom`,
+  network egress) are settled in the setup's acceptance, not in advance.
+- Review point: 2026-11-15, to review the switch of the remaining coding work
+  to wrapped registrations. The Linux acceptance passed on 2026-10-18 for the
+  writer `psm-alpha`, with a writable agent directory copy holding only the
+  access token, network not limited and no external MCP grants.
+- Until the acceptance passes, the interim rules stay in force. As an immediate
+  step, coding workers for this repository get a dedicated workspace alias on a
+  full clone instead of a linked worktree. The operator runbook is
+  [Isolation setup](../isolation-setup.md).
+
+## Proposed decision (as proposed on 2026-10-16)
+
+Choose **option 1 in its wrapped-registration form** and add no runtime
+change.
+
+- Document one setup first: on Linux, a coding-only registration that starts
+  the server in rootless Podman, one boundary per writer, with the mounts and
+  exclusions of option 1, and the host registration for read-only work. A
+  separate OS user is the documented alternative where Podman is not
+  available.
+- Review a writer's result from outside the boundary by fetching its branch
+  into the host repository and inspecting it there. Never run Git as the host
+  user inside a writer's clone: its local configuration can run code.
+- Cursor-backed coding profiles stay off non-disposable repositories until
+  they are accepted inside the boundary, because their runtime brings its own
+  authentication and processes.
+- End of the interim period: once this ADR is accepted and the setup passed
+  its acceptance below, coding profiles write on non-disposable repositories
+  only through the wrapped registration, and the Sprint 4 interim rules end.
+  Until then they stay in force with their recorded residual risks.
+- Reject option 2 and its partial forms as false assurance for the surface
+  they add. Reject option 3: Linux-only, union-wide, and kernel-dependent.
+- Defer option 4 with a trigger: untrusted content, more than one person's
+  sessions on one server, or an incident that option 1 would not have
+  prevented.
+
+Follow-ups, each with its own issue:
+- The threat model states the boundary of option 1; today it only says that
+  OS isolation is outside the verified boundary.
+- The installation guide documents the wrapped registration.
+- First, because linked worktrees are in use today: an offline Doctor
+  advisory when a workspace alias is a linked Git worktree while a coding
+  profile exists ([#81](https://github.com/plagor44-ux/pi-session-mcp/issues/81)).
+  Implemented in Sprint 5 as the warning `workspace_gitfile`, which detects a
+  possible linked worktree from a `.git` gitfile without following it; not yet
+  released. Refusing coding sessions on such an alias would add a public
+  error code and needs a minor release and its own decision.
+- Setup support for a wrapped registration would change setup's contract and
+  needs its own decision.
+
+Open questions to settle in the setup's acceptance: whether provider
+authentication refresh needs write access to Pi's agent directory (a writable
+copy then holds only that boundary's credentials), and which external MCP
+grants and `envFrom` values a coding registration keeps.
+
+## Acceptance
+
+Linux only. The setup is accepted when all of these pass:
+
+- **Launch binding.** The server process that the client's registered command
+  starts runs inside the boundary: checked from the host by its user,
+  namespaces or container, not assumed from the configuration.
+- **Writes**, provider-free, through that launch command and as its user:
+  create or change files outside the workspace through Node.js file writes (as
+  `edit` and `write` do) and through `bash`: an absolute path, `../`, a
+  symlink that points out, the operator's home, the source repository's
+  `.git/hooks` and `.git/config`, Pi's agent directory and its extension
+  packages. Every attempt fails. The digests of the host-side targets are
+  taken from outside the boundary, before and after, and are unchanged; a
+  write that only lands in a bind mount of the protected path does not pass.
+- **Credentials**: `~/.ssh`, the SSH agent socket, GitHub and Git credentials,
+  the client configurations and the Pi Session MCP configuration are not
+  visible, and `git push` and `ssh` to a remote fail.
+- **Persistence**: no process, scheduled job or user service outlives the
+  session.
+- **Children**: MCP children receive only the intended `envFrom` values.
+- **Network**: egress is recorded as limited, or explicitly as not limited.
+- **Live**: one coding session through the wrapped registration is asked to
+  write outside its workspace with `edit`, `write` and `bash`; every attempt
+  fails, the host digests stay unchanged, and an ordinary in-workspace change
+  still succeeds.
+
+## Consequences
+
+- The server keeps its size, platform parity and MCP contract; ADR 0002 stays
+  unchanged.
+- Safety for real-repository writing becomes an operator responsibility with a
+  documented, tested setup, not a server guarantee.
+- Residual risks inside the boundary remain: network egress, the credentials
+  the boundary needs for its provider, and trusted extension code.
+- macOS keeps the interim rules until a VM-based setup is accepted there.
+- If option 4 becomes necessary later, it needs its own decision and amends
+  ADR 0002.
+
+## Amendment (2026-10-21): event spool mount
+
+[ADR 0011](0011-turn-events-and-controller-wake.md) adds an opt-in, content-free
+event spool so that a Claude Code hook on the host can wake the controller when
+a turn ends. For a wrapped registration the server writes from inside the
+boundary, so each writer gets **one additional bind mount**:
+
+- A dedicated host directory inside the writer's own state directory
+  (`~/.local/state/pi-session-mcp/writers/<name>/events/`), mode 0700, mounted
+  read-write at `/pi/events` inside the boundary. It is on disk, not on the
+  operator's runtime tmpfs, so the worker can fill only the disk that it can
+  already fill through its writable clone mount, and never `$XDG_RUNTIME_DIR`.
+- It is never shared between writers and never holds a ledger, credentials,
+  configuration or results.
+- Setup creates the writer's state directory (0700). Every launch checks it
+  (real directory, owner, no group or other access), creates `events/` if
+  missing, resets a mode that the worker changed, and prunes it before
+  mounting: entries that are not a server instance directory are removed, and
+  instance directories only by age, so a launch never breaks a live server of
+  the same writer. The cleanup runs through open directory descriptors and
+  never follows a link that a running worker swaps in. Removing the writer
+  deletes it with the writer's state directory.
+- It is mounted only when the writer's generated server configuration enables
+  event delivery. Changing delivery on an existing writer is reported as a
+  settings change: the writer has to be removed and added again.
+- Wake claims live outside every writer mount
+  (`$XDG_RUNTIME_DIR/pi-session-mcp/claims/`), so a worker cannot forge or block
+  claims.
+
+Threat note: the worker inside the boundary can write to this directory. It can
+therefore forge, delete or flood events. The consequences are bounded by design:
+
+- an event is only a wake trigger and carries no state the controller trusts,
+  since the controller always reads `pi_turn_get`;
+- the host hook validates the event schema strictly, caps the size and number
+  of files it reads and never follows links;
+- the worst outcome is a spurious or missing wake. A missing wake falls back to
+  the hook's budget and one running read.
+
+The mount gives the worker no new read access to host data and no write access
+outside this directory. The acceptance of a wrapped writer with event delivery
+must show both, in addition to the existing checks.

package/docs/adr/0009-execution-modes.md

@@ -0,0 +1,131 @@
+# ADR 0009: Per-repository execution modes
+
+**Status:** Accepted (2026-10-18)
+
+## Context
+
+[ADR 0003](0003-post-mvp-maintenance.md#revisit-triggers)'s isolation trigger
+fired when coding profiles wrote on non-disposable repositories.
+[ADR 0008](0008-coding-profile-isolation.md) accepted a Linux boundary made
+from rootless Podman, a wrapped registration and one full clone per writer.
+Its [operator runbook](../isolation-setup.md) now describes the automated
+route; historical manual acceptance remains separately recorded. The host server previously offered coding profiles for every workspace,
+without recording which repositories were intended to stay inside a boundary.
+
+## Decision
+
+Record an execution mode per configured workspace alias and enforce it at
+coding-session start:
+
+- `host` permits coding directly in the operator's checkout and requires the
+  stored acknowledgment `acceptHostWrites: true`.
+- `container` records the intended writer settings and forbids coding through
+  the host server. Missing or unusable rootless Podman is an error in Doctor
+  and an explicit container choice is refused by setup, never downgraded to host.
+- `read-only` forbids coding sessions for that workspace.
+- A missing entry is reported as `unset` and permits host coding for backward
+  compatibility, with a Doctor warning when a coding profile exists. This is
+  a migration state, not a silent host default for new setup choices.
+
+Read-only profiles remain available in every mode. Modes are application policy,
+not an OS sandbox; a read-only profile does not confine provider runtimes or
+extension code.
+
+`pi-session-mcp-setup --repo <alias>` chooses container only if the local
+rootless Podman probe passes. Otherwise it requires an explicit `host` choice
+with `--accept-host-writes`, or `read-only`. Setup defaults to dry-run; only
+`--apply` writes the choice. It preserves other workspace entries and never
+restarts controllers. Running servers keep their loaded policy until restart
+or an MCP reconnect that starts a new server process.
+
+## Configuration compatibility
+
+Modes live in `execution-modes.json` next to the configuration, with
+`schemaVersion: 1` and a `workspaces` object keyed by configured aliases.
+The main configuration's `workspaces` remains an alias-to-path map. A separate
+file lets older servers read the unchanged strict 0.8.3 configuration schema;
+those servers **ignore modes and do not enforce this policy**. Missing files
+and entries resolve to `unset`; an invalid modes file fails server startup
+with `invalid_execution_modes`.
+
+Container entries record writers (1–16, default 1), lifecycle (`persistent` by
+default or `ephemeral`), selected coding profiles, image (default `node`) and
+network (`pasta` by default or `none`). Profiles must exist, be coding profiles
+and not use the Cursor provider. These settings alone are intent, not proof
+of provisioned or accepted writers. Container entries also accept cache `none`
+(default) or `go`, selected with `--cache` in the CLI.
+
+## Contract change and versioning
+
+Under [ADR 0003](0003-post-mvp-maintenance.md#versioning), this public MCP
+contract change requires the minor release **0.9.0**, not a 0.8.x patch:
+
+- `pi_capabilities_get` workspace entries include `mode` (`unset`, `host`,
+  `container` or `read-only`).
+- `pi_session_start` with a coding profile on `container` or `read-only`
+  returns `workspace_mode_forbids_coding`, before creating a session.
+
+This decision does not itself bump the package version or authorize publication.
+
+## Consequences
+
+- The operator's host-write choice is visible in Doctor as
+  `workspace_host_writes_accepted` (`ok`); unresolved choices warn with
+  `workspace_mode_unset` when a coding profile exists.
+- Host coding is blocked for container repositories. Changing the mode does
+  not stop sessions already running.
+- Plan A implements policy, selection and offline diagnosis. Plan B implements
+  the Linux writer lifecycle below; selecting a mode alone still proves no
+  acceptance and does not authorize publication or a live rollout.
+- Local stdio, in-memory sessions and one trusted local peer remain the product
+  boundary. macOS containment remains unaccepted; its interim rules still apply.
+
+## Plan B: automated writer decisions
+
+1. **Separate clones and guarded admission.** One full clone and boundary per
+   writer; never host Git inside a clone. Coding admission refuses a clone
+   not at baseline (extra branches, stash, dirty/untracked files, different HEAD)
+   or another open coding session. Baseline guards are re-read so reset works
+   without restarting the contained server.
+2. **Explicit profiles.** Contained configs contain selected supported coding
+   profiles and the synthetic default `boundary-read-only`. Coding must name
+   its profile explicitly; extensions, external MCP grants and non-builtin
+   skills are not supported in these configs.
+3. **Safe completion.** Finish collects then resets persistent writers or
+   recreates ephemeral writers. Any refused branch name makes collection
+   incomplete; finish stops. Rename inside the writer, or explicitly resolve
+   loss with reset/discard. No implicit data-loss authorization follows a partial
+   export. Controllers finish after takeover and session close, before reuse.
+4. **Untrusted export.** Bundles import into the operator's checkout at
+   `refs/remotes/writer-<name>/<branch>`; dirty work uses `<branch>-wip`.
+   The operator reviews before integration; setup never merges results.
+5. **Explicit acceptance.** Host control requires
+   `--isolation-control --repo <alias> --apply`, writes real canaries below
+   $HOME and removes them. Dry-run plans only. Writers stay not ready until
+   it passes, then require contained provider-free acceptance bound to wrapper,
+   package version, image ID, Podman version, network and cache.
+6. **Credential lifetime.** Launcher checks every 60 seconds. Only selected
+   OAuth tokens expired or within 2 minutes of expiry trigger host login
+   warmup (invalid/missing expiry also triggers it); measured warmup refreshes
+   expired/almost expired tokens only. It then re-copies credentials, with
+   OAuth refresh tokens emptied. Direct verify disables refresh with
+   `PI_WRITER_NO_CREDENTIAL_REFRESH=1`, makes no session/provider request and
+   touches no credential in that launch. Residual risk remains: access tokens
+   or API keys are readable inside the boundary; pasta networking is not limited.
+7. **Honest inspection.** Doctor stays offline. Writer verify includes Doctor,
+   registration equality and a bounded direct MCP check. `claude mcp get`
+   health-checks the registration and briefly starts the container; setup's
+   inspect/verify do this too. That client health-check subprocess does not
+   receive the direct launch's credential-refresh override from setup.
+8. **Migration, not adoption.** Collect manual `psm-alpha`/`go-app-alpha` work,
+   remove their local registration in its project, remove wrapper/state, then
+   provision by configured alias with `--repo … --mode container --profiles …
+   --apply`. Go requires an operator-supplied image ID and `cache: go` settings;
+   select it with `--image <image-id> --cache go`. CLI mode requests rebuild
+   supplied options/defaults, so repeat those flags. Generated names and
+   ownership are not the manual ones.
+
+These decisions keep local stdio and in-memory MCP sessions. Durable writer
+lifecycle metadata is not persistence/resume of sessions. No HTTP, remote or
+multi-user behavior is added. See [Execution modes](../execution-modes.md) for
+commands, reports, readiness and restart rules.

package/docs/adr/0010-read-only-extension-tools.md

@@ -0,0 +1,68 @@
+# ADR 0010: Granted extension tools in read-only profiles
+
+**Status:** Accepted (2026-10-19). Amends
+[ADR 0006](0006-pi-extension-allowlist.md).
+
+## Context
+
+ADR 0006 keeps read-only built-in tools at `read`, `grep`, `find` and `ls`.
+Extensions can already run hooks and change prompts, but their tools remain
+inactive in read-only profiles. Review workers need selected extension tools
+for code navigation without enabling every tool a package registers.
+
+## Decision
+
+Allow the optional profile field `grantedExtensionTools`, an array of individual
+extension tool names, only on `read-only` profiles with at least one extension.
+There is no package-wide grant. Without grants, behavior stays unchanged.
+
+Each name must be 1–64 characters from `[A-Za-z0-9_-]`, not start with `-`,
+and not be MCP-reserved (`mcp__` prefix, `list_mcp_resources`,
+`list_mcp_resource_templates`, `read_mcp_resource`). No duplicates or built-in
+names (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`) are allowed, and
+there are at most 32 entries. A violation prevents startup with
+`invalid_execution_profile_config`.
+
+The active tools are `read`, `grep`, `find`, `ls`, the granted MCP tools and
+exactly the granted extension tools. An extension's `setActiveTools` cannot
+add others. A granted name must be registered when extensions load, before
+binding. After bind the existing registered-set re-check applies. Each granted
+tool must also be active and declared to the model at admission; otherwise
+`pi_session_start` fails with `extension_tool_missing`, message
+`Granted Pi extension tool is not available`, class `needs_operator`.
+Extension resolution errors (`extension_not_installed`,
+`extension_version_mismatch`) take precedence. Tool conflict rules are checked
+first and still fail with `extension_tool_conflict`.
+
+The SDK activates only declarable tools. Registration alone is not availability:
+several registered `pi-lens` tools were never active in the
+[provider-free evaluation](../evaluation/pi-lens-registration-2026-10-19/).
+Granting such a tool fails closed. Extensions that register tools lazily in
+`session_start` or later are unsupported.
+
+Capabilities expose `grantedExtensionTools` directly after `extensions` for
+every profile, in configured order, or `[]` when absent. This is configuration
+intent only. Setup verify validates it; Doctor remains offline and cannot inspect
+registered tools without importing extension code.
+
+## Contract change and versioning
+
+The new capabilities field and start error are a public contract change for
+minor release **0.10.0** under
+[ADR 0003](0003-post-mvp-maintenance.md#versioning). This decision does not
+itself bump the version or authorize publication. See
+[Tool contracts](../tool-contracts.md#capability-discovery) for the bounded
+setup-verifier limit.
+
+## Consequences
+
+- A grant is the operator's trust decision, not proof that a tool only reads.
+  Granted tools are third-party code and may write with the server user's rights.
+- Workspace modes `container` and `read-only` do not restrict granted tools;
+  read-only profiles remain allowed in every mode. Modes are application policy,
+  not a sandbox for extensions.
+- Hooks and prompt changes retain their existing rights. Coding profiles still
+  get every extension tool and cannot configure this field.
+- Misspelled, unavailable or non-declarable grants fail closed, rather than
+  silently starting a session without the promised tool. Controllers report
+  `extension_tool_missing` to the operator without retrying or switching profiles.