pi-session-mcp 0.12.0 → 0.13.0

package/dist/pi-adapter.d.ts

@@ -14,7 +14,7 @@ export interface PiAppliedSelection {
     readonly model: string;
     readonly thinkingLevel: ThinkingLevel;
 }
-export type PiSessionCreationErrorCode = "unknown_provider" | "unknown_model" | "local_authentication_missing" | "local_authentication_unavailable" | "model_unavailable" | "thinking_level_unavailable" | "execution_selection_mismatch" | "external_mcp_unavailable" | "external_mcp_no_tools" | "external_mcp_grant_tool_missing" | "external_mcp_activation_mismatch" | "extension_not_installed" | "extension_version_mismatch" | "extension_load_failed" | "extension_tool_conflict" | "extension_tool_missing" | "skill_load_failed" | "pi_session_creation_failed";
+export type PiSessionCreationErrorCode = "unknown_provider" | "unknown_model" | "local_authentication_missing" | "local_authentication_unavailable" | "model_unavailable" | "thinking_level_unavailable" | "execution_selection_mismatch" | "external_mcp_unavailable" | "external_mcp_no_tools" | "external_mcp_grant_tool_missing" | "external_mcp_activation_mismatch" | "extension_not_installed" | "extension_version_mismatch" | "extension_load_failed" | "extension_tool_conflict" | "extension_tool_missing" | "skill_load_failed" | "sandbox_unavailable" | "pi_session_creation_failed";
 export declare class PiSessionCreationError extends Error {
     readonly code: PiSessionCreationErrorCode;
     constructor(code: PiSessionCreationErrorCode);

package/dist/pi-adapter.js

@@ -16,6 +16,7 @@ const PI_SESSION_CREATION_MESSAGES = {
     extension_tool_conflict: "Configured Pi extension tools conflict",
     extension_tool_missing: "Granted Pi extension tool is not available",
     skill_load_failed: "Configured Pi skill could not be loaded",
+    sandbox_unavailable: "Read-only shell sandbox is not available",
     pi_session_creation_failed: "Pi session creation failed",
 };
 export class PiSessionCreationError extends Error {

package/dist/sandbox-shell.d.ts

@@ -0,0 +1,71 @@
+import type { BashOperations } from "@earendil-works/pi-coding-agent";
+/** The only bubblewrap binary the shell uses: a fixed path, never a `PATH` lookup. */
+export declare const BWRAP_PATH = "/usr/bin/bwrap";
+export declare const SANDBOX_BASH_PATH = "/usr/bin/bash";
+export declare const PROBE_TIMEOUT_MS = 5000;
+/** Seconds a command may run when the tool call names no `timeout`. */
+export declare const DEFAULT_COMMAND_TIMEOUT_SECONDS = 600;
+/** Size limit of the sandbox's tmpfs `/tmp`, in bytes (512 MiB). */
+export declare const SANDBOX_TMP_BYTES = 536870912;
+export declare const SANDBOX_UNAVAILABLE_MESSAGE = "Read-only shell sandbox is not available";
+export type RootEntry = {
+    readonly path: string;
+    readonly kind: "symlink";
+    readonly target: string;
+} | {
+    readonly path: string;
+    readonly kind: "directory";
+};
+export interface SandboxArgsInput {
+    /** Real path of the workspace, mounted at the same path as an overlay with a temporary upper layer. */
+    readonly workspace: string;
+    /** Real path of a linked worktree's main Git directory, mounted the same way. */
+    readonly gitCommonDir?: string | undefined;
+    readonly cwd: string;
+    readonly rootEntries: readonly RootEntry[];
+    /** The program and its arguments, run after `--`. */
+    readonly argv: readonly string[];
+}
+/** The complete, fixed bubblewrap argument list of ADR 0013. Pure: host facts come in as `rootEntries`. */
+export declare function sandboxArgs(input: SandboxArgsInput): string[];
+/** The host's `/bin`, `/lib`, `/lib64` and `/sbin`: a symlink is recreated, a directory bound, an absent entry skipped. */
+export declare function hostRootEntries(): RootEntry[];
+/**
+ * The main repository's Git directory of a linked worktree, or `undefined`. Only a `.git` regular file
+ * whose `gitdir:` names `<common>/worktrees/<name>` is accepted, and only if that directory points
+ * back at this workspace's `.git`, its `commondir` resolves to `<common>`, and `<common>` holds `HEAD`,
+ * `objects` and `refs`. Never throws on bad content.
+ */
+export declare function resolveWorktreeGitDir(workspace: string): Promise<string | undefined>;
+/** The part of a child process the sandbox uses; the default is `node:child_process`. */
+export interface SandboxChild {
+    readonly stdout: NodeJS.ReadableStream | null;
+    readonly stderr: NodeJS.ReadableStream | null;
+    once(event: "error", listener: (error: Error) => void): unknown;
+    once(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+    kill(signal?: NodeJS.Signals): unknown;
+}
+export type SandboxSpawn = (file: string, args: readonly string[], options: {
+    env: Record<string, never>;
+    stdio: ["ignore", "pipe", "pipe"];
+}) => SandboxChild;
+export interface SandboxDependencies {
+    readonly spawn?: SandboxSpawn;
+    /** Whether the fixed bubblewrap binary may be used; defaults to a trusted-system-binary check. */
+    readonly trusted?: () => boolean;
+    readonly rootEntries?: () => readonly RootEntry[];
+    readonly gitCommonDir?: (workspace: string) => Promise<string | undefined>;
+}
+/** Whether the fixed bubblewrap binary is a trusted system binary. */
+export declare function sandboxBinaryTrusted(dependencies?: SandboxDependencies): boolean;
+/**
+ * Runs `/usr/bin/true` through the same sandbox as a command, bounded by `PROBE_TIMEOUT_MS`.
+ * False for an untrusted binary, a spawn failure, a non-zero exit or a timeout.
+ */
+export declare function probeSandbox(workspace: string, dependencies?: SandboxDependencies, signal?: AbortSignal): Promise<boolean>;
+/**
+ * `BashOperations` that run each command as `bwrap <fixed arguments> -- bash -c <command>`. The passed
+ * `env` is ignored, a working directory outside the workspace is refused and there is no unsandboxed
+ * fallback: a sandbox that cannot start fails the command.
+ */
+export declare function createSandboxedBashOperations(workspace: string, dependencies?: SandboxDependencies): BashOperations;

package/dist/sandbox-shell.js

@@ -0,0 +1,254 @@
+import { spawn } from "node:child_process";
+import { constants as osConstants } from "node:os";
+import { lstatSync, readlinkSync } from "node:fs";
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { isTrustedSystemBinary } from "./setup-platform.js";
+/** The only bubblewrap binary the shell uses: a fixed path, never a `PATH` lookup. */
+export const BWRAP_PATH = "/usr/bin/bwrap";
+export const SANDBOX_BASH_PATH = "/usr/bin/bash";
+const SANDBOX_TRUE_PATH = "/usr/bin/true";
+const SANDBOX_PATH = "/usr/local/bin:/usr/bin:/bin";
+const SANDBOX_HOME = "/tmp/home";
+/** Directories of a merged-`/usr` host that the sandbox recreates as symlinks or binds read-only. */
+const ROOT_ENTRIES = ["/bin", "/lib", "/lib64", "/sbin"];
+export const PROBE_TIMEOUT_MS = 5_000;
+/** Seconds a command may run when the tool call names no `timeout`. */
+export const DEFAULT_COMMAND_TIMEOUT_SECONDS = 600;
+/** Size limit of the sandbox's tmpfs `/tmp`, in bytes (512 MiB). */
+export const SANDBOX_TMP_BYTES = 536_870_912;
+export const SANDBOX_UNAVAILABLE_MESSAGE = "Read-only shell sandbox is not available";
+const GITFILE_LIMIT_BYTES = 4096;
+/** The complete, fixed bubblewrap argument list of ADR 0013. Pure: host facts come in as `rootEntries`. */
+export function sandboxArgs(input) {
+    const args = [
+        "--unshare-all", "--unshare-user", "--disable-userns", "--die-with-parent", "--new-session", "--clearenv",
+        "--setenv", "PATH", SANDBOX_PATH, "--setenv", "HOME", SANDBOX_HOME,
+        "--ro-bind", "/usr", "/usr",
+    ];
+    for (const entry of input.rootEntries) {
+        if (entry.kind === "symlink")
+            args.push("--symlink", entry.target, entry.path);
+        else
+            args.push("--ro-bind", entry.path, entry.path);
+    }
+    args.push("--ro-bind", "/etc", "/etc", "--dev", "/dev", "--proc", "/proc", "--size", String(SANDBOX_TMP_BYTES), "--tmpfs", "/tmp", "--dir", SANDBOX_HOME, "--overlay-src", input.workspace, "--tmp-overlay", input.workspace);
+    if (input.gitCommonDir !== undefined)
+        args.push("--overlay-src", input.gitCommonDir, "--tmp-overlay", input.gitCommonDir);
+    args.push("--chdir", input.cwd, "--", ...input.argv);
+    return args;
+}
+/** The host's `/bin`, `/lib`, `/lib64` and `/sbin`: a symlink is recreated, a directory bound, an absent entry skipped. */
+export function hostRootEntries() {
+    const entries = [];
+    for (const path of ROOT_ENTRIES) {
+        try {
+            const info = lstatSync(path);
+            if (info.isSymbolicLink())
+                entries.push({ path, kind: "symlink", target: readlinkSync(path) });
+            else if (info.isDirectory())
+                entries.push({ path, kind: "directory" });
+        }
+        catch { /* absent */ }
+    }
+    return entries;
+}
+const within = (path, root) => path === root || path.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
+async function readSmall(path) {
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.size > GITFILE_LIMIT_BYTES)
+            return undefined;
+        return (await readFile(path, "utf8")).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+const real = async (path) => { try {
+    return await realpath(path);
+}
+catch {
+    return undefined;
+} };
+const isDirectory = async (path) => { try {
+    return (await stat(path)).isDirectory();
+}
+catch {
+    return false;
+} };
+const isFile = async (path) => { try {
+    return (await stat(path)).isFile();
+}
+catch {
+    return false;
+} };
+/**
+ * The main repository's Git directory of a linked worktree, or `undefined`. Only a `.git` regular file
+ * whose `gitdir:` names `<common>/worktrees/<name>` is accepted, and only if that directory points
+ * back at this workspace's `.git`, its `commondir` resolves to `<common>`, and `<common>` holds `HEAD`,
+ * `objects` and `refs`. Never throws on bad content.
+ */
+export async function resolveWorktreeGitDir(workspace) {
+    try {
+        const gitFile = join(workspace, ".git");
+        const content = await readSmall(gitFile);
+        const match = content === undefined ? null : /^gitdir: (.+)$/.exec(content);
+        if (!match)
+            return undefined;
+        const gitdir = await real(resolve(workspace, match[1]));
+        if (gitdir === undefined || !(await isDirectory(gitdir)))
+            return undefined;
+        const worktrees = dirname(gitdir);
+        if (basename(worktrees) !== "worktrees")
+            return undefined;
+        const common = dirname(worktrees);
+        const back = await readSmall(join(gitdir, "gitdir"));
+        if (back === undefined || (await real(resolve(gitdir, back))) !== (await real(gitFile)))
+            return undefined;
+        const commondir = await readSmall(join(gitdir, "commondir"));
+        if (commondir === undefined || (await real(resolve(gitdir, commondir))) !== common)
+            return undefined;
+        if (!(await isFile(join(common, "HEAD"))) || !(await isDirectory(join(common, "objects"))) || !(await isDirectory(join(common, "refs"))))
+            return undefined;
+        return common;
+    }
+    catch {
+        return undefined;
+    }
+}
+const defaultSpawn = (file, args, options) => spawn(file, [...args], options);
+const defaultTrusted = () => isTrustedSystemBinary(BWRAP_PATH);
+/** Whether the fixed bubblewrap binary is a trusted system binary. */
+export function sandboxBinaryTrusted(dependencies = {}) {
+    try {
+        return (dependencies.trusted ?? defaultTrusted)();
+    }
+    catch {
+        return false;
+    }
+}
+/** The complete argument list for one run; refuses when the fixed binary is not trusted. */
+async function prepare(workspace, cwd, argv, dependencies) {
+    if (!sandboxBinaryTrusted(dependencies))
+        throw new Error(SANDBOX_UNAVAILABLE_MESSAGE);
+    const gitCommonDir = await (dependencies.gitCommonDir ?? resolveWorktreeGitDir)(workspace);
+    return sandboxArgs({ workspace, gitCommonDir, cwd, rootEntries: (dependencies.rootEntries ?? hostRootEntries)(), argv });
+}
+/** Spawns bubblewrap and attaches the termination listeners in the same tick, so no event is missed. */
+function start(args, dependencies) {
+    // An empty environment: neither the server's nor the tool's variables reach the sandbox.
+    const child = (dependencies.spawn ?? defaultSpawn)(BWRAP_PATH, args, { env: {}, stdio: ["ignore", "pipe", "pipe"] });
+    const closed = new Promise((resolvePromise, reject) => {
+        child.once("error", () => reject(new Error(SANDBOX_UNAVAILABLE_MESSAGE)));
+        child.once("close", (code, signal) => resolvePromise({ code, signal }));
+    });
+    closed.catch(() => undefined);
+    return { child, closed };
+}
+/**
+ * Runs `/usr/bin/true` through the same sandbox as a command, bounded by `PROBE_TIMEOUT_MS`.
+ * False for an untrusted binary, a spawn failure, a non-zero exit or a timeout.
+ */
+export async function probeSandbox(workspace, dependencies = {}, signal) {
+    let running;
+    let timer;
+    let onAbort;
+    try {
+        if (signal?.aborted)
+            return false;
+        const workspaceReal = await realpath(workspace);
+        running = start(await prepare(workspaceReal, workspaceReal, [SANDBOX_TRUE_PATH], dependencies), dependencies);
+        const { child, closed } = running;
+        child.stdout?.resume();
+        child.stderr?.resume();
+        const deadline = new Promise((resolvePromise) => {
+            timer = setTimeout(() => resolvePromise(null), PROBE_TIMEOUT_MS);
+            onAbort = () => resolvePromise(null);
+            signal?.addEventListener("abort", onAbort, { once: true });
+            if (signal?.aborted)
+                resolvePromise(null);
+        });
+        const outcome = await Promise.race([closed, deadline]);
+        if (outcome === null)
+            child.kill("SIGKILL");
+        return outcome !== null && outcome.code === 0 && signal?.aborted !== true;
+    }
+    catch {
+        try {
+            running?.child.kill("SIGKILL");
+        }
+        catch { /* already gone */ }
+        return false;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        if (onAbort)
+            signal?.removeEventListener("abort", onAbort);
+    }
+}
+/**
+ * `BashOperations` that run each command as `bwrap <fixed arguments> -- bash -c <command>`. The passed
+ * `env` is ignored, a working directory outside the workspace is refused and there is no unsandboxed
+ * fallback: a sandbox that cannot start fails the command.
+ */
+export function createSandboxedBashOperations(workspace, dependencies = {}) {
+    return {
+        exec: async (command, cwd, { onData, signal, timeout }) => {
+            if (signal?.aborted)
+                throw new Error("aborted");
+            let workspaceReal;
+            let cwdReal;
+            try {
+                workspaceReal = await realpath(workspace);
+                cwdReal = await realpath(isAbsolute(cwd) ? cwd : resolve(workspaceReal, cwd));
+            }
+            catch {
+                throw new Error("Working directory is not available");
+            }
+            if (!within(cwdReal, workspaceReal))
+                throw new Error("Working directory is outside the workspace");
+            let timeoutMs = DEFAULT_COMMAND_TIMEOUT_SECONDS * 1000;
+            if (timeout !== undefined) {
+                if (!Number.isFinite(timeout) || timeout <= 0)
+                    throw new Error("Invalid timeout: must be a finite number of seconds");
+                timeoutMs = Math.min(timeout * 1000, 2_147_483_647);
+            }
+            let running;
+            try {
+                running = start(await prepare(workspaceReal, cwdReal, [SANDBOX_BASH_PATH, "-c", command], dependencies), dependencies);
+            }
+            catch {
+                throw new Error(SANDBOX_UNAVAILABLE_MESSAGE);
+            }
+            const { child, closed } = running;
+            child.stdout?.on("data", onData);
+            child.stderr?.on("data", onData);
+            let timedOut = false;
+            let timer;
+            const kill = () => { try {
+                child.kill("SIGKILL");
+            }
+            catch { /* already gone */ } };
+            const onAbort = () => kill();
+            try {
+                timer = setTimeout(() => { timedOut = true; kill(); }, timeoutMs);
+                signal?.addEventListener("abort", onAbort, { once: true });
+                if (signal?.aborted)
+                    kill();
+                const outcome = await closed;
+                if (signal?.aborted)
+                    throw new Error("aborted");
+                if (timedOut)
+                    throw new Error(`timeout:${timeout ?? DEFAULT_COMMAND_TIMEOUT_SECONDS}`);
+                return { exitCode: outcome.code ?? (outcome.signal ? 128 + (osConstants.signals[outcome.signal] ?? 0) : 1) };
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+            }
+        },
+    };
+}

package/dist/sdk-pi-adapter.d.ts

@@ -3,6 +3,7 @@ import { type ExtensionSpec } from "./extension-spec.js";
 import type { ResolvedExecutionProfile, ThinkingLevel } from "./execution-profile.js";
 import { type McpConnectionFactory } from "./mcp-session-tools.js";
 import { type PiSessionAdapter, type PiSessionCreationErrorCode, type PiSessionHandle, type PiTurnOutcome } from "./pi-adapter.js";
+import { type SandboxDependencies } from "./sandbox-shell.js";
 export { PROFILE_TOOLS } from "./session-tools.js";
 type CreateSession = (options: CreateAgentSessionOptions) => Promise<CreateAgentSessionResult>;
 export declare const AUTH_OPERATION_TIMEOUT_MS = 5000;
@@ -11,7 +12,7 @@ export declare const SESSION_CREATION_TIMEOUT_MS = 10000;
 export interface SdkPiAdapterDiagnostic {
     readonly level: "error";
     readonly event: "pi_session_creation_failed";
-    readonly stage: "runtime" | "provider" | "model" | "check_auth" | "get_auth" | "availability" | "resource_loader" | "mcp_tools" | "create_session" | "postcheck" | "extension_resolve" | "extension_load" | "extension_bind" | "skill_load";
+    readonly stage: "runtime" | "provider" | "model" | "check_auth" | "get_auth" | "availability" | "resource_loader" | "mcp_tools" | "create_session" | "postcheck" | "extension_resolve" | "extension_load" | "extension_bind" | "skill_load" | "sandbox";
     readonly code: PiSessionCreationErrorCode;
     readonly executionProfile: string;
     readonly provider: string;
@@ -39,6 +40,13 @@ export interface SdkPiSessionAdapterOptions {
     /** Resolves a pinned extension to its installed package directory. */
     readonly resolveExtension?: (extension: ExtensionSpec) => Promise<string>;
     readonly extensionSdk?: ExtensionSdk;
+    /** Host seams of the read-only shell sandbox; tests inject a fake runner. */
+    readonly sandbox?: SandboxDependencies;
+    /**
+     * Directories a skill directory must not expose through the read tools, in addition to the
+     * operator's home and the Pi agent directory (`~/.pi`). The server passes the configuration directory.
+     */
+    readonly protectedReadPaths?: readonly string[];
 }
 type SdkAssistantMessage = Extract<Extract<AgentSessionEvent, {
     type: "message_end";
@@ -78,6 +86,8 @@ export declare class SdkPiSessionAdapter implements PiSessionAdapter {
     private readonly mcpConnectionFactory;
     private readonly resolveExtension;
     private readonly extensionSdk;
+    private readonly sandbox;
+    private readonly protectedReadPaths;
     constructor(options?: SdkPiSessionAdapterOptions);
     create(input: {
         cwd: string;
@@ -85,6 +95,12 @@ export declare class SdkPiSessionAdapter implements PiSessionAdapter {
         signal?: AbortSignal;
     }): Promise<PiSessionHandle>;
     private createWithExtensions;
+    /**
+     * The server's own tool definitions of a read-only session (ADR 0013); none for coding. The workspace
+     * root is the session directory: a root that cannot be resolved fails the start. With a sandboxed shell
+     * the sandbox is probed first, and a profile whose sandbox cannot start never gets a session.
+     */
+    private confinedTools;
     private loadSkills;
     private checkResources;
     /** Provider, model, authentication and availability, exactly as configured. */

package/dist/sdk-pi-adapter.js

@@ -1,11 +1,15 @@
-import { createAgentSession, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, DefaultResourceLoader, ModelRuntime, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createBashToolDefinition, DefaultResourceLoader, ModelRuntime, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { homedir, userInfo } from "node:os";
+import { join } from "node:path";
+import { allowedReadRoots, createConfinedReadOnlyTools } from "./confined-tools.js";
 import { PiExtensionError } from "./extension-spec.js";
 import { classifyMcpStartupError, connectSessionMcpTools, } from "./mcp-session-tools.js";
 import { createStdioMcpConnection } from "./mcp-stdio-client.js";
 import { PiSessionCreationError, } from "./pi-adapter.js";
 import { resolvePiExtension } from "./pi-extensions.js";
 import { loadSelectedSkills, PiSkillError } from "./pi-skills.js";
-import { composeSessionTools, PROFILE_TOOLS } from "./session-tools.js";
+import { createSandboxedBashOperations, probeSandbox } from "./sandbox-shell.js";
+import { composeSessionTools, profileTools } from "./session-tools.js";
 export { PROFILE_TOOLS } from "./session-tools.js";
 export const AUTH_OPERATION_TIMEOUT_MS = 5_000;
 /** Server-side bound for SDK session construction. The SDK does not document cancellation. */
@@ -326,6 +330,8 @@ export class SdkPiSessionAdapter {
     mcpConnectionFactory;
     resolveExtension;
     extensionSdk;
+    sandbox;
+    protectedReadPaths;
     constructor(options = {}) {
         this.modelRuntimeFactory = options.modelRuntimeFactory ?? (() => ModelRuntime.create({ refreshOnCreate: false }));
         this.createSession = options.createSession ?? createAgentSession;
@@ -333,6 +339,15 @@ export class SdkPiSessionAdapter {
         this.mcpConnectionFactory = options.mcpConnectionFactory ?? createStdioMcpConnection;
         this.resolveExtension = options.resolveExtension ?? ((extension) => resolvePiExtension(extension));
         this.extensionSdk = options.extensionSdk ?? DEFAULT_EXTENSION_SDK;
+        this.sandbox = options.sandbox ?? {};
+        // The account database's home, not `$HOME`, which a caller's environment could point elsewhere.
+        const home = (() => { try {
+            return userInfo().homedir;
+        }
+        catch {
+            return homedir();
+        } })();
+        this.protectedReadPaths = [home, join(home, ".pi"), ...(options.protectedReadPaths ?? [])];
     }
     async create(input) {
         const extensions = input.executionProfile.extensions ?? [];
@@ -356,8 +371,10 @@ export class SdkPiSessionAdapter {
         catch {
             throw this.failure(executionProfile, "resource_loader", "pi_session_creation_failed");
         }
+        const confined = await this.confinedTools(input, skills);
         const mcpTools = await this.connectMcpTools(input);
-        const tools = [...PROFILE_TOOLS[executionProfile.permissionProfile], ...mcpTools.tools.map((tool) => tool.name)];
+        const tools = [...profileTools(executionProfile.permissionProfile, executionProfile.shell), ...mcpTools.tools.map((tool) => tool.name)];
+        const customTools = [...confined, ...mcpTools.tools];
         let session;
         try {
             ({ session } = await withCreationDeadline(() => this.createSession({
@@ -370,14 +387,14 @@ export class SdkPiSessionAdapter {
                 resourceLoader,
                 // With an explicit tools list, Pi also needs custom tool names here to activate them.
                 tools,
-                ...(mcpTools.tools.length === 0 ? {} : { customTools: mcpTools.tools }),
+                ...(customTools.length === 0 ? {} : { customTools }),
             }), (late) => disposeSdkSession(late.session)));
         }
         catch {
             await mcpTools.close();
             throw this.failure(executionProfile, "create_session", "pi_session_creation_failed");
         }
-        return this.admit(session, executionProfile, tools, mcpTools, () => disposeSdkSession(session), mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : undefined, "exact", skills);
+        return this.admit(session, executionProfile, tools, mcpTools, () => disposeSdkSession(session), mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : undefined, "exact", skills, [], confined);
     }
     async createWithExtensions(input, extensions) {
         const { cwd, executionProfile } = input;
@@ -423,9 +440,11 @@ export class SdkPiSessionAdapter {
             throw this.failure(executionProfile, "extension_load", "extension_load_failed");
         }
         const model = await this.resolveVerifiedModel(services.modelRuntime, executionProfile);
+        const confined = await this.confinedTools(input, skills);
         const mcpTools = await this.connectMcpTools(input);
+        const customTools = [...confined, ...mcpTools.tools];
         const grantedTools = executionProfile.grantedExtensionTools ?? [];
-        const composed = composeSessionTools(executionProfile.permissionProfile, mcpTools.tools.map((tool) => tool.name), extensionTools, grantedTools);
+        const composed = composeSessionTools(executionProfile.permissionProfile, mcpTools.tools.map((tool) => tool.name), extensionTools, grantedTools, executionProfile.shell);
         if (!composed.ok) {
             await mcpTools.close();
             throw this.failure(executionProfile, "extension_load", composed.code);
@@ -440,7 +459,7 @@ export class SdkPiSessionAdapter {
                     model,
                     thinkingLevel: executionProfile.thinkingLevel,
                     tools,
-                    ...(mcpTools.tools.length === 0 ? {} : { customTools: mcpTools.tools }),
+                    ...(customTools.length === 0 ? {} : { customTools }),
                 })),
                 services,
                 diagnostics: services.diagnostics,
@@ -474,7 +493,7 @@ export class SdkPiSessionAdapter {
             // A `session_start` handler may register a tool that replaces a built-in or granted tool.
             // Tools an extension registers later, during a turn, are not re-checked: allowlisted
             // extensions are trusted code.
-            const recheck = composeSessionTools(executionProfile.permissionProfile, mcpTools.tools.map((tool) => tool.name), registeredExtensionTools(services), grantedTools);
+            const recheck = composeSessionTools(executionProfile.permissionProfile, mcpTools.tools.map((tool) => tool.name), registeredExtensionTools(services), grantedTools, executionProfile.shell);
             if (!recheck.ok)
                 throw this.failure(executionProfile, "extension_bind", recheck.code);
             if (recheck.tools.length !== tools.length || recheck.tools.some((name, index) => name !== tools[index]))
@@ -490,7 +509,35 @@ export class SdkPiSessionAdapter {
             await cleanUp();
             throw this.failure(executionProfile, "extension_bind", "extension_tool_conflict");
         }
-        return this.admit(sessionRuntime.session, executionProfile, tools, mcpTools, disposeRuntime, mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : "execution_selection_mismatch", "subset", skills, grantedTools);
+        return this.admit(sessionRuntime.session, executionProfile, tools, mcpTools, disposeRuntime, mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : "execution_selection_mismatch", "subset", skills, grantedTools, confined);
+    }
+    /**
+     * The server's own tool definitions of a read-only session (ADR 0013); none for coding. The workspace
+     * root is the session directory: a root that cannot be resolved fails the start. With a sandboxed shell
+     * the sandbox is probed first, and a profile whose sandbox cannot start never gets a session.
+     */
+    async confinedTools(input, skills) {
+        const { executionProfile } = input;
+        if (executionProfile.permissionProfile !== "read-only")
+            return [];
+        let roots;
+        try {
+            roots = await allowedReadRoots(input.cwd, skills, this.protectedReadPaths);
+        }
+        catch {
+            throw this.failure(executionProfile, "create_session", "pi_session_creation_failed");
+        }
+        const tools = createConfinedReadOnlyTools(input.cwd, roots);
+        if (executionProfile.shell === "sandboxed") {
+            // The first root is the real path of the workspace.
+            if (!(await probeSandbox(roots[0], this.sandbox, input.signal)))
+                throw this.failure(executionProfile, "sandbox", "sandbox_unavailable");
+            tools.push(createBashToolDefinition(input.cwd, {
+                operations: createSandboxedBashOperations(roots[0], this.sandbox),
+                exposeSessionEnvironment: false,
+            }));
+        }
+        return tools;
     }
     async loadSkills(input) {
         try {
@@ -581,9 +628,16 @@ export class SdkPiSessionAdapter {
     /** Post-verifies a created session and wraps it; a mismatch disposes it before reporting. */
     async admit(session, executionProfile, tools, mcpTools, disposeSession, toolMismatch, 
     // `subset` lets an extension narrow its own active tools; nothing outside the allowlist may be active.
-    toolCheck = "exact", skills = [], requiredTools = []) {
+    toolCheck = "exact", skills = [], requiredTools = [], 
+    // The server's own definitions must be the ones the session resolves for their names.
+    ownDefinitions = []) {
         try {
             this.checkResources(session.resourceLoader, skills, executionProfile, "postcheck");
+            for (const definition of ownDefinitions) {
+                if (session.getToolDefinition(definition.name) !== definition) {
+                    throw this.failure(executionProfile, "postcheck", "pi_session_creation_failed");
+                }
+            }
             if (session.model?.provider !== executionProfile.provider || session.model.id !== executionProfile.model) {
                 throw this.failure(executionProfile, "postcheck", "execution_selection_mismatch");
             }

package/dist/session-tools.d.ts

@@ -1,5 +1,7 @@
-import type { PermissionProfile } from "./execution-profile.js";
+import type { PermissionProfile, ShellMode } from "./execution-profile.js";
 export declare const PROFILE_TOOLS: Readonly<Record<PermissionProfile, readonly string[]>>;
+/** The built-in tools of a profile: a read-only profile with a sandboxed shell also has `bash`. */
+export declare function profileTools(permissionProfile: PermissionProfile, shell?: ShellMode): readonly string[];
 export declare const MAX_GRANTED_EXTENSION_TOOLS = 32;
 export declare function isAcceptableExtensionToolName(name: string): boolean;
 export type ComposedSessionTools = {
@@ -15,4 +17,4 @@ export type ComposedSessionTools = {
  * in both profiles so an extension can never shadow a built-in or granted MCP tool.
  * Unsafe names and names the SDK treats as MCP tools also fail closed.
  */
-export declare function composeSessionTools(permissionProfile: PermissionProfile, mcpToolNames: readonly string[], extensionToolNames: readonly (readonly string[])[], grantedExtensionTools?: readonly string[]): ComposedSessionTools;
+export declare function composeSessionTools(permissionProfile: PermissionProfile, mcpToolNames: readonly string[], extensionToolNames: readonly (readonly string[])[], grantedExtensionTools?: readonly string[], shell?: ShellMode): ComposedSessionTools;

package/dist/session-tools.js

@@ -2,6 +2,10 @@ export const PROFILE_TOOLS = {
     "read-only": ["read", "grep", "find", "ls"],
     coding: ["read", "bash", "edit", "write", "grep", "find", "ls"],
 };
+/** The built-in tools of a profile: a read-only profile with a sandboxed shell also has `bash`. */
+export function profileTools(permissionProfile, shell) {
+    return permissionProfile === "read-only" && shell === "sandboxed" ? [...PROFILE_TOOLS["read-only"], "bash"] : PROFILE_TOOLS[permissionProfile];
+}
 export const MAX_GRANTED_EXTENSION_TOOLS = 32;
 /**
  * Letters, digits, `_` and `-`, at most 64 characters, which fits the common provider
@@ -27,7 +31,7 @@ export function isAcceptableExtensionToolName(name) {
  * in both profiles so an extension can never shadow a built-in or granted MCP tool.
  * Unsafe names and names the SDK treats as MCP tools also fail closed.
  */
-export function composeSessionTools(permissionProfile, mcpToolNames, extensionToolNames, grantedExtensionTools = []) {
+export function composeSessionTools(permissionProfile, mcpToolNames, extensionToolNames, grantedExtensionTools = [], shell) {
     const reserved = new Set([...PROFILE_TOOLS.coding, ...PROFILE_TOOLS["read-only"], ...mcpToolNames]);
     const extensionTools = [];
     for (const names of extensionToolNames) {
@@ -41,5 +45,5 @@ export function composeSessionTools(permissionProfile, mcpToolNames, extensionTo
     if (permissionProfile === "read-only" && grantedExtensionTools.some((name) => !extensionTools.includes(name))) {
         return { ok: false, code: "extension_tool_missing" };
     }
-    return { ok: true, tools: [...PROFILE_TOOLS[permissionProfile], ...mcpToolNames, ...(permissionProfile === "coding" ? extensionTools : grantedExtensionTools)] };
+    return { ok: true, tools: [...profileTools(permissionProfile, shell), ...mcpToolNames, ...(permissionProfile === "coding" ? extensionTools : grantedExtensionTools)] };
 }