pi-session-mcp 0.12.1 → 0.13.1

package/.pi-session-mcp-cli/writer-state.js

@@ -5,6 +5,7 @@ import { lstat, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { z } from "zod";
 import { PACKAGE_VERSION } from "./package-metadata.js";
+import { writerLimitsSchema } from "./writer-limits.js";
 import { ALIAS_PATTERN } from "./execution-profile.js";
 export const WRITER_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,63}-w([1-9]|1[0-6])$/;
 export class WriterStateError extends Error {
@@ -31,8 +32,10 @@ export const writerStateSchema = z.object({
         model: z.string().min(1).max(200),
     }).strict()).refine((providers) => new Set(providers.map(({ provider }) => provider)).size === providers.length).readonly(),
     network: z.enum(["pasta", "none"]),
-    cache: z.enum(["none", "go", "uv"]),
+    cache: z.enum(["none", "go", "uv", "npm"]),
     tags: z.enum(["none", "reachable"]).default("none"),
+    clean: z.enum(["untracked", "all"]).default("untracked"),
+    limits: writerLimitsSchema.optional(),
     imageId: hex64,
     base: z.object({ ref: z.string(), commit: z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/) }).strict(),
     acceptance: z.object({
@@ -62,7 +65,7 @@ export function writerPaths(home, name) {
     const root = join(writersRoot(home), name);
     return {
         root, clone: join(root, "clone"), agent: join(root, "agent"), bundles: join(root, "bundles"),
-        config: join(root, "config"), events: join(root, "events"), go: join(root, "go"), uv: join(root, "uv"), wrapper: join(root, "wrapper.sh"), state: join(root, "state.json"),
+        config: join(root, "config"), events: join(root, "events"), go: join(root, "go"), uv: join(root, "uv"), npm: join(root, "npm"), wrapper: join(root, "wrapper.sh"), state: join(root, "state.json"),
         acceptanceFailure: join(root, "acceptance-failure.json"),
     };
 }

package/CHANGELOG.md

@@ -2,6 +2,153 @@
 
 ## Unreleased
 
+## 0.13.1 — 2026-10-29
+
+Patch release under ADR 0003 with an unchanged MCP contract. It ships the
+fixes after 0.13.0: Doctor names where the configuration schema rejects a
+file ([#173](https://github.com/plagor44-ux/pi-session-mcp/issues/173)),
+read-only confinement of Pi's agent directory
+([#177](https://github.com/plagor44-ux/pi-session-mcp/issues/177)), a writer
+added without `--base` ([#176](https://github.com/plagor44-ux/pi-session-mcp/issues/176)),
+stale waiter-lock reclamation in the wake hook
+([#179](https://github.com/plagor44-ux/pi-session-mcp/issues/179)) and
+per-writer reconcile failures
+([#180](https://github.com/plagor44-ux/pi-session-mcp/issues/180)). Setup
+reports change for a broken kept writer: it now carries its own code on its
+target instead of `writer_reconcile_failed`. `npm audit` still reports
+`undici` 8.10.2, pinned by Pi SDK 1.4.0, the latest SDK release, now with
+eight advisories ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+
+Upgrading follows [Installation](docs/installation.md#upgrade); writers must be
+accepted again after the upgrade, as after every release.
+
+### Changed
+
+- Doctor's `config_invalid` names where the schema rejects the configuration:
+  one check per issue location (at most five) with the subject
+  `configuration:<location>`, for example
+  `configuration:executionProfiles.review.default`. Locations hold only schema
+  field names, aliases and array indexes; an unknown key that is not a schema
+  field name, and any other key that is not a valid alias, is shown as
+  `<key>`, and values and messages are never reported. An error without a
+  location keeps the subject `configuration`
+  ([#173](https://github.com/plagor44-ux/pi-session-mcp/issues/173)).
+
+### Added
+
+- Issue forms for bug reports, change proposals and maintenance tasks, and a
+  pull request template, written so that a person or a coding agent can carry
+  an issue out and a reviewer can check it
+  ([#178](https://github.com/plagor44-ux/pi-session-mcp/issues/178)).
+
+### Fixed
+
+- Security, in the lockfile only, development path: `@hono/node-server`
+  2.1.1 → 2.1.5 (via MCP Inspector; GHSA-rmxm-3fg6-px4f). Still open:
+  `undici` 8.10.2 in the production path, pinned exactly by Pi SDK 1.4.0, now
+  with eight advisories (GHSA-4qv8-2p9j-2685, GHSA-f72v-6w45-q472,
+  GHSA-xjj6-f33q-929c, GHSA-4w7w-5xrc-9h26, GHSA-2m5v-pch6-74hx,
+  GHSA-qrxm-fqhp-jwvm, GHSA-9fm3-97px-rjf6, GHSA-55wc-3pg8-jfw6), so
+  `npm audit` still reports it
+  ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+- Writer reconciliation reports a kept writer that fails, for example with
+  a missing wrapper after a crash during provisioning, on that writer's
+  target with its own code (`writer_state_invalid`) and still reconciles the
+  other writers. Only failures of shared setup state (configuration,
+  ownership) end the whole step with `writer_reconcile_failed`
+  ([#180](https://github.com/plagor44-ux/pi-session-mcp/issues/180)).
+- Wake hook: reclaiming a stale waiter lock is serialized by an exclusive
+  `<lock>.reclaim` guard, and the lock is judged again while holding it. Two
+  waiters that both saw the same stale lock can no longer both take the turn
+  and send a duplicate wake reminder
+  ([#179](https://github.com/plagor44-ux/pi-session-mcp/issues/179)).
+- Read-only confinement protects Pi's agent directory (`~/.pi/agent`, or
+  `PI_CODING_AGENT_DIR`) and, for a symlinked configuration file, its target's
+  directory: a skill directory that equals or contains either contributes only
+  the skill file as a read root. Before, a skill file placed directly in the
+  agent directory made `auth.json` readable. The real file of a symlinked skill
+  file is now a read root too, so the model can read a skill it was given
+  ([#177](https://github.com/plagor44-ux/pi-session-mcp/issues/177)).
+- Setup provisions a writer added without `--base` (for example by raising
+  `--writers`) on the workspace's recorded default base, as finish and recreate
+  already did. Before, it landed on `origin/HEAD` and default starts never
+  leased it. A recorded base that is the repository default still provisions
+  from `origin/HEAD` ([#176](https://github.com/plagor44-ux/pi-session-mcp/issues/176)).
+
+## 0.13.0 — 2026-10-28
+
+Minor release under ADR 0003 for
+[ADR 0013](docs/adr/0013-hardened-read-only-profiles.md)
+([#169](https://github.com/plagor44-ux/pi-session-mcp/issues/169)): hardened
+read-only profiles. The MCP contract changes: read-only tools are confined to
+the workspace and the selected skills' directories, profiles gain the optional
+`shell` field, capabilities report `shell`, and `pi_session_start` has the new
+error code `sandbox_unavailable`. It also ships the writer settings changes of
+[#162](https://github.com/plagor44-ux/pi-session-mcp/issues/162),
+[#163](https://github.com/plagor44-ux/pi-session-mcp/issues/163),
+[#165](https://github.com/plagor44-ux/pi-session-mcp/issues/165) and
+[#166](https://github.com/plagor44-ux/pi-session-mcp/issues/166). `npm audit`
+still reports `undici` 8.10.2, pinned by Pi SDK 1.4.0, the latest SDK release
+([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+
+Upgrading follows [Installation](docs/installation.md#upgrade); writers must be
+accepted again after the upgrade, as after every release.
+
+### Changed
+
+- **Breaking for read-only workflows:** `read`, `grep`, `find` and `ls` of every
+  read-only profile now accept only paths inside the session's workspace and the
+  directories of the profile's selected skill files. An absolute path, `..`, `~`
+  or a symlink leading outside is refused with the tool error `Path is outside
+  the allowed read roots`. Read-only workers that read files outside the
+  workspace, Pi credentials included, can no longer do so. Coding profiles are
+  unchanged ([ADR 0013](docs/adr/0013-hardened-read-only-profiles.md),
+  [#169](https://github.com/plagor44-ux/pi-session-mcp/issues/169)).
+
+### Added
+
+- Optional profile field `"shell": "sandboxed"` for read-only profiles: a `bash`
+  tool whose commands run in a bubblewrap sandbox without network and with the
+  workspace as a temporary overlay, so review workers can run `git log`,
+  `git blame`, tests and scripts without touching the host tree. Linux only,
+  not together with `grantedExtensionTools`. New start error
+  `sandbox_unavailable` (class `needs_operator`), new capabilities field
+  `shell` (`none` or `sandboxed`) after `grantedExtensionTools`, and the Doctor
+  checks `sandbox_unavailable` (error, probed for each configured workspace) and
+  `workspace_git_unavailable` (warning). The sandbox's `/tmp` is limited to
+  512 MiB, commands default to a 600 second timeout and are killed with all
+  their processes on timeout or abort; the start probe is cancelled with the
+  start request. A skill directory that equals or contains the operator's home,
+  the configuration directory or `~/.pi` is no longer a read root, only its
+  skill file is
+  ([#169](https://github.com/plagor44-ux/pi-session-mcp/issues/169)).
+
+- Optional container resource settings `--cpus`, `--cpu-shares` and `--memory`,
+  with host cgroup-controller preflight and fenced in-place writer updates
+  without reprovisioning. A later mode request that omits a limit keeps it;
+  `none` removes it
+  ([#166](https://github.com/plagor44-ux/pi-session-mcp/issues/166)).
+
+- `--cache npm` mounts a private per-writer npm cache at `/pi/npm` with
+  `npm_config_cache=/pi/npm/cache`, retained across reset, finish and recreate
+  and removed with the writer
+  ([#165](https://github.com/plagor44-ux/pi-session-mcp/issues/165)).
+
+- Opt-in container setting `--clean all` removes ignored files from writer
+  clones on reset and finish while preserving the default dependency-cache
+  behavior and per-writer caches outside the clone
+  ([#162](https://github.com/plagor44-ux/pi-session-mcp/issues/162)).
+
+### Fixed
+
+- An apply of `pi-session-mcp-setup --repo <alias> --mode container ...` with
+  drifted settings is now refused before the mode is written: each kept writer
+  with a difference reports `writer_settings_changed`, the modes file stays
+  unchanged and no kept writer is changed (a surplus writer of a smaller count
+  may already have been fenced), so the recorded mode never drifts from
+  what the writers run
+  ([#163](https://github.com/plagor44-ux/pi-session-mcp/issues/163)).
+
 ## 0.12.1 — 2026-10-28
 
 Patch release for

package/CONTRIBUTING.md

@@ -42,7 +42,14 @@ ones:
 Pull requests are limited to collaborators. If you are not a collaborator and
 want to contribute a fix, open an issue that describes it.
 
-- Keep a pull request to one focused change, and say which issue it addresses.
+Issues use the forms in [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/):
+bug report, change proposal or maintenance task. Each asks for acceptance
+criteria and a way to verify them, so that a person or a coding agent can carry
+the issue out and a reviewer can check it. Pull requests use
+[`.github/pull_request_template.md`](.github/pull_request_template.md).
+
+- Keep a pull request to one focused change, and name every issue it addresses
+  with its own closing keyword (`Closes #12. Closes #13.`).
 - Run the checks above and `npm audit` before opening it.
 - Describe what you verified and how. State only what was run: provider-free
   tests do not establish live client or model behavior.

package/README.md

@@ -30,10 +30,12 @@ It is not the right tool when:
 
 ## Status
 
-The package version is **0.12.1**.
+The package version is **0.13.1**.
 
 [Per-repository execution modes](docs/execution-modes.md) make host writes explicit and block coding on read-only aliases. On container workspaces, the one host `pi-session-mcp` registration leases a rootless-Podman writer per coding session on Linux; no per-writer registrations or tool prefixes are needed ([ADR 0012](docs/adr/0012-leased-writer-pool.md)). Setup provisions, accepts, collects and resets the pool. Starts normally use the workspace default base; fix rounds can pass a short branch `base`. Start/get report `writer` and `base` for collection, and capabilities report configured `writers` and `defaultBase`. Reset, finish and recreate need no reconnect; finish returns the writer to the default base. See the [container upgrade runbook](docs/installation.md#container-writers).
 
+Every read-only profile reads only inside its workspace and the directories of its selected skills, and a read-only profile on Linux can opt into a bubblewrap shell without network, home or host writes (`shell: "sandboxed"`, [ADR 0013](docs/adr/0013-hardened-read-only-profiles.md)).
+
 - **Pre-1.0.** The public tool contract is stable within a minor line: a change to tools, fields, states or error codes needs a new minor release.
 - **Linux and macOS**, Node.js 22.19.0 or newer. macOS is tested in CI on macOS 15 and 26 on Apple silicon; Intel Macs run the same code but are untested. Setup acceptance on a real Mac is recorded for Claude Code only; Codex is still pending. See [Acceptance](docs/acceptance.md#status). On other platforms `setup` refuses with `platform_unsupported`.
 - **Clients:** Codex CLI and Claude Code. The `setup` command does not pin client versions: it accepts a client whose public `mcp` command output matches the expected contract and fails closed otherwise.
@@ -113,7 +115,7 @@ The [installation guide](docs/installation.md) also covers installing from a rel
 ```
 
 - A workspace alias maps to a directory. Clients can select aliases only.
-- An execution profile binds a permission profile (`read-only` or `coding`), a provider, a model and a thinking level. Exactly one profile is the default, and it must be `read-only`.
+- An execution profile binds a permission profile (`read-only` or `coding`), a provider, a model and a thinking level. Exactly one profile is the default, and it must be `read-only`. A read-only profile can add `shell: "sandboxed"` on Linux.
 - A profile can grant individual tools of local stdio MCP servers to its sessions; see [External MCP tools in embedded sessions](docs/session-mcp.md).
 - An optional top-level `skillCatalog` maps skill aliases to `builtin:<name>` (a skill of the package or of your override directory) or to a `SKILL.md` file, and a profile's optional `skills` selects aliases from it. A profile without `skills` gets no skills. See [Pi skills](docs/skills.md).
 - An optional top-level `"events": { "delivery": "spool" }` turns on content-free turn events, so that a Claude Code hook can wake the controller when a turn ends instead of polling. It is off by default and changes nothing for Codex. See [Wake the controller](docs/installation.md#wake-the-controller-claude-code).
@@ -174,6 +176,7 @@ Contract and design:
 - [ADR 0007: execution profiles select Pi skills from an operator catalog](docs/adr/0007-profile-skill-selection.md)
 - [ADR 0011: turn events and controller wake](docs/adr/0011-turn-events-and-controller-wake.md)
 - [ADR 0012: one registration with a leased writer pool](docs/adr/0012-leased-writer-pool.md)
+- [ADR 0013: hardened read-only profiles](docs/adr/0013-hardened-read-only-profiles.md)
 
 Maintain:
 

package/dist/capabilities.d.ts

@@ -30,6 +30,7 @@ export declare function projectCapabilities(workspaces: ReadonlyMap<string, stri
         thinkingLevel: import("./execution-profile.js").ThinkingLevel;
         extensions: string[];
         grantedExtensionTools: string[];
+        shell: "none" | "sandboxed";
         skills: string[];
     }[];
 };

package/dist/capabilities.js

@@ -18,7 +18,7 @@ export function projectCapabilities(workspaces, executionProfiles, configuration
         }),
         executionProfiles: [...executionProfiles.values()]
             .sort((left, right) => compareAliases(left.alias, right.alias))
-            .map(({ alias, default: isDefault, permissionProfile, provider, model, thinkingLevel, extensions, grantedExtensionTools, skills }) => ({
+            .map(({ alias, default: isDefault, permissionProfile, provider, model, thinkingLevel, extensions, grantedExtensionTools, shell, skills }) => ({
             alias,
             default: isDefault,
             permissionProfile,
@@ -27,6 +27,8 @@ export function projectCapabilities(workspaces, executionProfiles, configuration
             thinkingLevel,
             extensions: (extensions ?? []).map((extension) => extension.spec),
             grantedExtensionTools: [...(grantedExtensionTools ?? [])],
+            // Configured intent only: whether the server's probe succeeds is a start-time fact.
+            shell: shell ?? "none",
             skills: (skills ?? []).map((skill) => skill.alias),
         })),
     };

package/dist/client-adapters/mcp-verifier.js

@@ -118,7 +118,7 @@ function validCapabilities(value) {
         if (!profile || typeof profile !== "object")
             return false;
         const record = profile;
-        return exactKeys(record, ["alias", "default", "permissionProfile", "provider", "model", "thinkingLevel", "extensions", "grantedExtensionTools", "skills"])
+        return exactKeys(record, ["alias", "default", "permissionProfile", "provider", "model", "thinkingLevel", "extensions", "grantedExtensionTools", "shell", "skills"])
             && typeof record.alias === "string" && ALIAS_PATTERN.test(record.alias)
             && typeof record.default === "boolean"
             && (record.permissionProfile === "read-only" || record.permissionProfile === "coding")
@@ -130,6 +130,7 @@ function validCapabilities(value) {
             && Array.isArray(record.grantedExtensionTools) && record.grantedExtensionTools.length <= MAX_GRANTED_EXTENSION_TOOLS
             && record.grantedExtensionTools.every((name) => typeof name === "string" && isAcceptableExtensionToolName(name))
             && new Set(record.grantedExtensionTools).size === record.grantedExtensionTools.length
+            && (record.shell === "none" || record.shell === "sandboxed")
             && Array.isArray(record.skills) && record.skills.length <= MAX_PROFILE_SKILLS
             && record.skills.every((skill) => typeof skill === "string" && ALIAS_PATTERN.test(skill))
             && new Set(record.skills).size === record.skills.length;

package/dist/config.d.ts

@@ -4,8 +4,18 @@ import { type WorkspaceModeEntry } from "./execution-modes.js";
 export type ConfigErrorCode = "config_path_required" | "invalid_execution_profile_config" | "invalid_thinking_level" | "invalid_execution_modes" | "invalid_event_delivery";
 export declare class ConfigError extends Error {
     readonly code: ConfigErrorCode;
-    constructor(code: ConfigErrorCode);
+    /** Dotted schema issue locations for Doctor; built by `issueLocations`, never a value, message or path. */
+    readonly locations: readonly string[];
+    constructor(code: ConfigErrorCode, locations?: readonly string[]);
 }
+export declare const MAX_CONFIG_ISSUE_LOCATIONS = 5;
+/**
+ * Sorted, deduplicated and bounded issue locations; an issue at the root has the empty location.
+ * A segment is kept only if it is a schema field name, or, inside the path, a key that has the alias
+ * form (record keys are aliases, which Doctor already reports). Any other key, and every unrecognized
+ * key that is not a schema field name, could be a path or a secret and becomes `<key>`.
+ */
+export declare function issueLocations(issues: readonly z.core.$ZodIssue[]): string[];
 export declare const configSchema: z.ZodObject<{
     events: z.ZodOptional<z.ZodObject<{
         delivery: z.ZodEnum<{
@@ -35,6 +45,7 @@ export declare const configSchema: z.ZodObject<{
         mcpServers: z.ZodOptional<z.ZodCustom<Readonly<Record<string, import("./mcp-config.js").McpServerConfig>>, Readonly<Record<string, import("./mcp-config.js").McpServerConfig>>>>;
         extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
         grantedExtensionTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        shell: z.ZodOptional<z.ZodLiteral<"sandboxed">>;
         skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;

package/dist/config.js

@@ -20,6 +20,7 @@ const profileSchema = z.object({
     mcpServers: z.custom((value) => isMcpServers(value)).optional(),
     extensions: z.array(extensionSpec).max(MAX_PROFILE_EXTENSIONS).optional(),
     grantedExtensionTools: z.array(z.string().refine(isAcceptableExtensionToolName)).max(MAX_GRANTED_EXTENSION_TOOLS).optional(),
+    shell: z.literal("sandboxed").optional(),
     skills: z.array(alias).max(MAX_PROFILE_SKILLS).optional(),
 }).strict().superRefine((profile, context) => {
     if (profile.mcpServers !== undefined && !isMcpServers(profile.mcpServers, profile.permissionProfile)) {
@@ -46,6 +47,18 @@ const profileSchema = z.object({
             context.addIssue({ code: "custom", path: ["grantedExtensionTools"], message: "Extension tool grants must not name built-in tools" });
         }
     }
+    if (profile.shell !== undefined) {
+        // Granted extension tools may write, so the sandbox's read-only guarantee would not hold (ADR 0013).
+        if (profile.permissionProfile !== "read-only") {
+            context.addIssue({ code: "custom", path: ["shell"], message: "A sandboxed shell requires a read-only profile" });
+        }
+        if (profile.grantedExtensionTools !== undefined) {
+            context.addIssue({ code: "custom", path: ["shell"], message: "A sandboxed shell cannot be combined with granted extension tools" });
+        }
+        if (process.platform !== "linux") {
+            context.addIssue({ code: "custom", path: ["shell"], message: "A sandboxed shell requires Linux" });
+        }
+    }
     if (profile.skills !== undefined && new Set(profile.skills).size !== profile.skills.length) {
         context.addIssue({ code: "custom", path: ["skills"], message: "A skill alias may appear only once per profile" });
     }
@@ -59,12 +72,31 @@ const CONFIG_ERROR_MESSAGES = {
 };
 export class ConfigError extends Error {
     code;
-    constructor(code) {
+    /** Dotted schema issue locations for Doctor; built by `issueLocations`, never a value, message or path. */
+    locations;
+    constructor(code, locations = []) {
         super(CONFIG_ERROR_MESSAGES[code]);
         this.name = "ConfigError";
         this.code = code;
+        this.locations = Object.freeze([...locations]);
     }
 }
+export const MAX_CONFIG_ISSUE_LOCATIONS = 5;
+/**
+ * Sorted, deduplicated and bounded issue locations; an issue at the root has the empty location.
+ * A segment is kept only if it is a schema field name, or, inside the path, a key that has the alias
+ * form (record keys are aliases, which Doctor already reports). Any other key, and every unrecognized
+ * key that is not a schema field name, could be a path or a secret and becomes `<key>`.
+ */
+export function issueLocations(issues) {
+    const fields = new Set([...Object.keys(configSchema.shape), ...Object.keys(profileSchema.shape), ...Object.keys(eventsSchema.shape)]);
+    const segment = (value, aliasAllowed) => typeof value === "number" ? String(value) : typeof value === "string" && (fields.has(value) || (aliasAllowed && ALIAS_PATTERN.test(value))) ? value : "<key>";
+    const locations = issues.flatMap((issue) => {
+        const path = issue.path.map((value) => segment(value, true));
+        return issue.code === "unrecognized_keys" ? issue.keys.map((key) => [...path, segment(key, false)]) : [path];
+    });
+    return [...new Set(locations.map((path) => path.join(".")))].sort().slice(0, MAX_CONFIG_ISSUE_LOCATIONS);
+}
 const eventsSchema = z.object({ delivery: z.enum(["spool", "off"]) }).strict();
 export const configSchema = z.object({
     events: eventsSchema.optional(),
@@ -138,7 +170,7 @@ export async function loadConfig(path = process.env.PI_SESSION_MCP_CONFIG) {
             const thinkingLevelIssue = error.issues.some((issue) => issue.path.at(-1) === "thinkingLevel");
             // Only the events field's own issues map to the delivery code; an unknown top-level key stays a profile-config error.
             const eventsIssue = error.issues.some((issue) => issue.path[0] === "events");
-            throw new ConfigError(thinkingLevelIssue ? "invalid_thinking_level" : eventsIssue ? "invalid_event_delivery" : "invalid_execution_profile_config");
+            throw new ConfigError(thinkingLevelIssue ? "invalid_thinking_level" : eventsIssue ? "invalid_event_delivery" : "invalid_execution_profile_config", issueLocations(error.issues));
         }
         throw error;
     }
@@ -146,13 +178,14 @@ export async function loadConfig(path = process.env.PI_SESSION_MCP_CONFIG) {
     const overrideDirectory = skillOverrideDirectory(absoluteConfig);
     const workspaces = new ImmutableMap(Object.entries(parsed.workspaces).map(([key, value]) => [key, resolve(base, value)]));
     const catalog = parsed.skillCatalog ?? {};
-    const executionProfiles = new ImmutableMap(Object.entries(parsed.executionProfiles).map(([key, { mcpServers, extensions, grantedExtensionTools, skills, ...value }]) => {
+    const executionProfiles = new ImmutableMap(Object.entries(parsed.executionProfiles).map(([key, { mcpServers, extensions, grantedExtensionTools, shell, skills, ...value }]) => {
         const selection = resolveSkillSelection(skills, catalog, base, overrideDirectory);
         return [key, Object.freeze({
                 alias: key, ...value,
                 ...(mcpServers === undefined ? {} : { mcpServers: snapshotMcpServers(mcpServers) }),
                 ...(extensions === undefined ? {} : { extensions: Object.freeze(extensions.map((spec) => parseExtensionSpec(spec))) }),
                 ...(grantedExtensionTools === undefined ? {} : { grantedExtensionTools: Object.freeze([...grantedExtensionTools]) }),
+                ...(shell === undefined ? {} : { shell }),
                 ...(selection === undefined ? {} : { skills: selection }),
             })];
     }));

package/dist/confined-tools.d.ts

@@ -0,0 +1,30 @@
+import { type GrepOperations, type LsOperations, type ReadOperations, type Skill, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+/** Fixed refusal text; it never names the refused path. */
+export declare const OUTSIDE_ROOTS_MESSAGE = "Path is outside the allowed read roots";
+/** The read-only built-ins whose definitions this server replaces with confined ones. */
+export declare const CONFINED_TOOL_NAMES: readonly string[];
+/**
+ * The allowed read roots: the workspace and the directory of each selected skill file, as real paths.
+ * A skill directory that equals or contains a protected path (the operator's home, the configuration
+ * directory, the Pi agent directory) would expose it, so only the skill file itself is a root then.
+ * A symlinked skill file resolves outside its directory, so its real file is a root as well.
+ */
+export declare function allowedReadRoots(workspace: string, skills: readonly Skill[], protectedPaths?: readonly string[]): Promise<string[]>;
+/**
+ * Resolves a tool `path` argument the way the SDK will and checks the canonical result against the
+ * roots. Arguments the SDK would rewrite before resolving are refused, so both resolve the same path.
+ * Returns the canonical path; a refusal throws a fixed message without the path.
+ */
+export declare function confineToolPath(input: unknown, cwd: string, roots: readonly string[]): Promise<string>;
+/** The `*Operations` hooks that re-check every absolute path the SDK hands them; exported for tests. */
+export declare function confinedOperations(roots: readonly string[]): {
+    read: ReadOperations;
+    grep: GrepOperations;
+    ls: LsOperations;
+};
+/**
+ * Definitions named `read`, `grep`, `find` and `ls` that accept only paths below `roots`. Registered as
+ * SDK custom tools they replace the built-ins of the same name. `find` has no operations hook that
+ * would still cover `fd`, so it relies on the execute wrapper alone.
+ */
+export declare function createConfinedReadOnlyTools(cwd: string, roots: readonly string[]): ToolDefinition[];

package/dist/confined-tools.js

@@ -0,0 +1,122 @@
+import { access, readdir, readFile, realpath, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createReadToolDefinition, detectSupportedImageMimeTypeFromFile, } from "@earendil-works/pi-coding-agent";
+/** Fixed refusal text; it never names the refused path. */
+export const OUTSIDE_ROOTS_MESSAGE = "Path is outside the allowed read roots";
+/** The read-only built-ins whose definitions this server replaces with confined ones. */
+export const CONFINED_TOOL_NAMES = ["read", "grep", "find", "ls"];
+/** What the SDK's `normalizePath` would rewrite before resolving (core/tools/path-utils.js, utils/paths.js). */
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/;
+/** Real path of an existing path, or the nearest existing ancestor's real path plus the missing rest. */
+async function canonical(path) {
+    let current = resolve(path);
+    const rest = [];
+    for (;;) {
+        try {
+            return join(await realpath(current), ...rest.reverse());
+        }
+        catch {
+            const parent = dirname(current);
+            if (parent === current)
+                return resolve(path);
+            rest.push(basename(current));
+            current = parent;
+        }
+    }
+}
+function isWithin(path, root) {
+    return path === root || path.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
+}
+/**
+ * The allowed read roots: the workspace and the directory of each selected skill file, as real paths.
+ * A skill directory that equals or contains a protected path (the operator's home, the configuration
+ * directory, the Pi agent directory) would expose it, so only the skill file itself is a root then.
+ * A symlinked skill file resolves outside its directory, so its real file is a root as well.
+ */
+export async function allowedReadRoots(workspace, skills, protectedPaths = []) {
+    const roots = new Set([await realpath(workspace)]);
+    const protectedReal = await Promise.all(protectedPaths.map((path) => canonical(path)));
+    for (const skill of skills) {
+        const directory = await realpath(dirname(skill.filePath)), file = await canonical(skill.filePath);
+        const root = protectedReal.some((path) => isWithin(path, directory)) ? file : directory;
+        roots.add(root);
+        if (!isWithin(file, root))
+            roots.add(file);
+    }
+    return [...roots];
+}
+/**
+ * Resolves a tool `path` argument the way the SDK will and checks the canonical result against the
+ * roots. Arguments the SDK would rewrite before resolving are refused, so both resolve the same path.
+ * Returns the canonical path; a refusal throws a fixed message without the path.
+ */
+export async function confineToolPath(input, cwd, roots) {
+    const value = input === undefined || input === "" ? "." : input;
+    if (typeof value !== "string"
+        || value.startsWith("@") || value.startsWith("~") || value.startsWith("file:")
+        || value.includes("\0") || UNICODE_SPACES.test(value)) {
+        throw new Error(OUTSIDE_ROOTS_MESSAGE);
+    }
+    const real = await canonical(resolve(cwd, value));
+    if (!roots.some((root) => isWithin(real, root)))
+        throw new Error(OUTSIDE_ROOTS_MESSAGE);
+    return real;
+}
+/** The second layer: the absolute path the SDK hands to an operations hook. */
+async function checkAbsolute(path, roots) {
+    const real = await canonical(path);
+    if (!roots.some((root) => isWithin(real, root)))
+        throw new Error(OUTSIDE_ROOTS_MESSAGE);
+}
+/** The `*Operations` hooks that re-check every absolute path the SDK hands them; exported for tests. */
+export function confinedOperations(roots) {
+    const guard = async (path, run) => { await checkAbsolute(path, roots); return run(); };
+    return {
+        read: {
+            access: (path) => guard(path, () => access(path, constants.R_OK)),
+            readFile: (path) => guard(path, () => readFile(path)),
+            detectImageMimeType: (path) => guard(path, () => detectSupportedImageMimeTypeFromFile(path)),
+        },
+        grep: {
+            isDirectory: (path) => guard(path, async () => (await stat(path)).isDirectory()),
+            readFile: (path) => guard(path, () => readFile(path, "utf-8")),
+        },
+        ls: {
+            exists: (path) => guard(path, async () => { try {
+                await access(path, constants.F_OK);
+                return true;
+            }
+            catch {
+                return false;
+            } }),
+            stat: (path) => guard(path, () => stat(path)),
+            readdir: (path) => guard(path, () => readdir(path)),
+        },
+    };
+}
+/** Runs the root check on `params.path` before the SDK tool executes. */
+function confine(definition, cwd, roots) {
+    return {
+        ...definition,
+        execute: async (toolCallId, params, signal, onUpdate, context) => {
+            // The SDK resolves against `ctx.cwd || cwd`; resolve the same way.
+            await confineToolPath(params.path, context?.cwd || cwd, roots);
+            return definition.execute(toolCallId, params, signal, onUpdate, context);
+        },
+    };
+}
+/**
+ * Definitions named `read`, `grep`, `find` and `ls` that accept only paths below `roots`. Registered as
+ * SDK custom tools they replace the built-ins of the same name. `find` has no operations hook that
+ * would still cover `fd`, so it relies on the execute wrapper alone.
+ */
+export function createConfinedReadOnlyTools(cwd, roots) {
+    const operations = confinedOperations(roots);
+    return [
+        confine(createReadToolDefinition(cwd, { operations: operations.read }), cwd, roots),
+        confine(createGrepToolDefinition(cwd, { operations: operations.grep }), cwd, roots),
+        confine(createFindToolDefinition(cwd), cwd, roots),
+        confine(createLsToolDefinition(cwd, { operations: operations.ls }), cwd, roots),
+    ];
+}

package/dist/doctor.d.ts

@@ -3,7 +3,7 @@ import { type ExtensionSpec } from "./extension-spec.js";
 import { type ReleasedSkillTree } from "./skill-library.js";
 export type DoctorSeverity = "ok" | "warning" | "error";
 export type DoctorExitCode = 0 | 1 | 2 | 64;
-export type DoctorCheckId = "node_version_unsupported" | "package_metadata_unreadable" | "build_missing" | "build_stale" | "version_mismatch" | "config_missing" | "config_unreadable" | "config_invalid" | "workspace_missing" | "workspace_not_directory" | "workspace_unreadable" | "workspace_not_writable" | "workspace_gitfile" | "workspace_mode_unset" | "workspace_base_unset" | "workspace_host_writes_accepted" | "container_runtime_unavailable" | "container_profile_refused" | "writer_lease_directory" | "writer_not_ready" | "writer_not_migrated" | "writer_off_default_base" | "writer_dirty" | "writer_git_identity_missing" | "writer_uncollected_bundle" | "extension_missing" | "extension_version_mismatch" | "extension_unpinned" | "skill_missing" | "skill_unreadable" | "skill_duplicate" | "skill_override_outdated" | "event_spool_root";
+export type DoctorCheckId = "node_version_unsupported" | "package_metadata_unreadable" | "build_missing" | "build_stale" | "version_mismatch" | "config_missing" | "config_unreadable" | "config_invalid" | "workspace_missing" | "workspace_not_directory" | "workspace_unreadable" | "workspace_not_writable" | "workspace_gitfile" | "workspace_mode_unset" | "workspace_base_unset" | "workspace_host_writes_accepted" | "container_runtime_unavailable" | "container_profile_refused" | "writer_lease_directory" | "writer_not_ready" | "writer_not_migrated" | "writer_off_default_base" | "writer_dirty" | "writer_git_identity_missing" | "writer_uncollected_bundle" | "extension_missing" | "extension_version_mismatch" | "extension_unpinned" | "skill_missing" | "skill_unreadable" | "skill_duplicate" | "skill_override_outdated" | "sandbox_unavailable" | "workspace_git_unavailable" | "event_spool_root";
 export interface DoctorCheck {
     readonly id: DoctorCheckId;
     readonly severity: DoctorSeverity;
@@ -76,6 +76,10 @@ export interface DoctorDependencies {
     readonly writerLeaseRoot?: (path: string) => Promise<EventSpoolRootInfo | undefined>;
     /** Effective user id of the current process; defaults to the real one. */
     readonly uid?: number;
+    /** Probes the read-only shell sandbox with the session's fixed arguments for one workspace; called only when a profile selects it. */
+    readonly sandboxProbe?: (workspace: string) => Promise<boolean>;
+    /** The main Git directory of a linked worktree workspace, or `undefined` when the pointer is unusable. */
+    readonly worktreeGitDir?: (workspace: string) => Promise<string | undefined>;
 }
 export interface EventSpoolRootInfo {
     readonly isDirectory: boolean;