pi-better-sandbox 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-better-sandbox
 
-An opt-in write sandbox for Pi's foreground tools.
+Sandbox permissions for Pi's foreground tools and detached subagents.
 
 It is installed by default with [`pi-better-harness`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-harness#readme), and can be installed on its own:
 
@@ -9,19 +9,37 @@ pi install npm:pi-better-sandbox
 ```
 
 Either way you keep starting Pi the way you always have — `pi`. There is
-no launcher or wrapper command. The sandbox starts inactive. Use `/sandbox on`
-for the current session or `/sandbox default on` to persist opt-in. While
-enabled, Pi's built-in `bash` tool and the `!` / `!!` commands you type yourself
-run inside an OS sandbox that lets them write only under the directory you
-launched Pi from, and the built-in `write` and `edit` tools are held to the same
-policy.
+no launcher or wrapper command. Main starts inactive; Subagents start confined.
+Open `/sandbox` to change either column, or use `/sandbox on` for the current
+Main session. **Save as defaults** persists both profiles.
 
+```text
+Sandbox permissions               Main             Subagents
+
+Sandbox                           Off              On
+
+Project files                     -                Read / write
+Outside project                   -                Read
+Stored credentials                -                Read
+Run commands & applications       -                On
+Network access                    -                On
+
+↑↓ Select row   ←→ Select column   Space Change
+Save as defaults
 ```
-Read:       every filesystem path
-Write:      the canonical launch directory and everything under it
-Exceptions: .git/hooks, .env, .env.local
-Network:    unchanged
-```
+
+File permissions cycle through Off, Read, and Read / write. Other rows toggle
+Off/On. Detail cells under an Off sandbox display a dimmed `-` and cannot be
+changed; their values return when the sandbox is enabled again. Outside project
+covers paths outside the assigned root without custom folder lists. Protected
+paths remain write-denied regardless of the broad file settings.
+
+**Stored credentials currently means known credential files.** It covers SSH,
+AWS, GitHub CLI, Google Cloud CLI, Azure, Kubernetes, Docker, npm, netrc, Git
+credentials, and Pi's file-based auth. These rules override ordinary file access.
+OS vault services such as Keychain and Secret Service, and tokens inherited in
+environment variables, are excluded. Read / write may be needed by a CLI that
+refreshes a token or updates its credential database.
 
 For shell commands the denial is done by the kernel, not by inspecting command
 text: macOS uses Seatbelt (`sandbox-exec`) and Linux uses Bubblewrap (`bwrap`).
@@ -36,16 +54,18 @@ nothing behind on disk.
 
 ## What is confined, and what is not
 
-**Reads and network access are never restricted.** Every path on the filesystem
-stays readable and network behaviour is exactly what it was. This sandbox limits
-writes, and nothing else.
+Selected file and network rules apply to confined commands. Main's model
+connection remains outside the tool sandbox. A detached subagent's OS sandbox
+surrounds its whole runtime: until provider networking is isolated, launching a
+subagent with Network access Off is refused with an explanation. Run commands &
+applications Off prevents new shell, application, background-task, and subagent
+launches; in-process file tools can still operate according to their file rules.
 
-Writes are confined for the integrated first-party execution paths, and only
-those:
+Permissions cover the integrated first-party execution paths:
 
 - Pi's built-in `bash` tool.
 - User-entered `!` and `!!` commands.
-- Pi's built-in `write` and `edit` tools.
+- Pi's built-in `read`, `write`, and `edit` tools.
 - Local [`pi-better-background-tasks`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-background-tasks#readme)
   spawns and watches, which capture this policy at launch.
 - [`pi-better-subagents`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-subagents#readme)
@@ -56,6 +76,11 @@ those:
 - Pi's own process.
 - `pi.exec` calls made by extensions.
 - Unrelated third-party extension code.
+- Remote filesystem operations: local permissions cannot constrain the remote
+  host. With Main sandbox enabled, the dedicated `remote_bash` and structured
+  SSH background launchers are blocked because their local SSH client does not
+  yet use the confinement wrapper. Run `ssh` through confined `bash` to apply
+  local file, credential, and network permissions to the SSH client.
 - Another first-party surface's control plane. Each surface denies its own —
   the files naming what it will run next — but not every other surface's, so
   confinement is per surface rather than global.
@@ -71,7 +96,7 @@ operations underneath them are replaced.
 ## Commands
 
 ```text
-/sandbox                     show the effective status
+/sandbox                     open the permission table (text status outside TUI)
 /sandbox on                  enable protection for operations started from now on
 /sandbox off                 turn protection off for this session (interactive confirmation)
 /sandbox default on          persist opt-in and enable it now
@@ -164,9 +189,11 @@ in your rule set but is held out in that project, with a message saying so.
 ## Lifecycle
 
 The foreground sandbox is inactive by default. Session overrides do not survive
-startup, new session, resume, fork, or reload. `/sandbox default on|off` stores
-the default for those future sessions in
-`~/.pi/agent/extensions/pi-better-sandbox-preferences.json`.
+startup, new session, resume, fork, or reload. Save as defaults writes both
+profiles to `~/.pi/agent/extensions/pi-better-sandbox-permissions.json` (or the
+corresponding `$PI_CODING_AGENT_DIR`). Existing activation preferences in
+`pi-better-sandbox-preferences.json` migrate when no profile file exists.
+`/sandbox default on|off` remains available and updates Main's saved switch.
 
 Toggles apply to operations launched after the change. A command already running
 keeps the policy it launched with.
@@ -198,6 +225,20 @@ that exact file, and an alias pointing at a denied file is denied too.
 | Linux    | Bubblewrap (`bwrap`)        | install `bubblewrap`         |
 | Other    | none                        | protected commands are blocked |
 
+A detached subagent gets a private session/temp directory for Pi's runtime
+state. This directory stays writable even with Outside project set to Read or
+Off; other runs' state and the parent's launch metadata are not included.
+Read access to system executable and library directories, device I/O, and root
+directory metadata/listing remains available so a process can start. On macOS,
+the allowance excludes the broad `/System/Volumes` tree.
+
+Linux currently refuses combinations it cannot safely mount: hiding the
+project or credential files inside a visible whole-filesystem bind, writing
+credential stores under a read-only outside root, and a writable outside root
+with protected paths. These launch errors preserve the selected restrictions.
+The macOS permission combinations are covered by real-kernel tests; Linux
+mount behavior requires a Linux runner with Bubblewrap and user namespaces.
+
 ## For other extensions
 
 The effective policy is published as a frozen snapshot on Pi's extension event

package/commands.ts

@@ -12,6 +12,7 @@
  */
 
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
 
 import {
     DenyRuleError,
@@ -26,7 +27,7 @@ import type { ForegroundSandboxController, ForegroundSandboxStatus } from "./sta
 export const SANDBOX_COMMAND_NAME = "sandbox";
 
 export const SANDBOX_COMMAND_DESCRIPTION =
-    "Show the foreground write sandbox, change session or persistent activation, or manage write-denied paths";
+    "Configure Main and Subagents sandbox permissions, activation defaults, and protected paths";
 
 const USAGE = [
     "Usage:",
@@ -79,6 +80,7 @@ export type SandboxCommandDeps = {
     onStateChange: (status: ForegroundSandboxStatus) => void;
     /** Persist a default and apply it to the current session. */
     setDefault: (enabled: boolean) => ForegroundSandboxStatus;
+    openPermissions?: (ctx: ExtensionCommandContext) => Promise<void>;
 };
 
 /** Build the `/sandbox` handler. Exported so its behaviour is directly testable. */
@@ -87,6 +89,7 @@ export function createSandboxCommandHandler({
     denyRules,
     onStateChange,
     setDefault,
+    openPermissions,
 }: SandboxCommandDeps) {
     return async function handleSandboxCommand(
         args: string,
@@ -100,6 +103,10 @@ export function createSandboxCommandHandler({
         const rest = trimmed.slice(verb.length).trim();
 
         if (subcommand === "") {
+            if (openPermissions && ctx.mode === "tui") {
+                await openPermissions(ctx);
+                return;
+            }
             ctx.ui.notify(formatSandboxReport(controller.status()), "info");
             return;
         }
@@ -256,8 +263,22 @@ function announce(ctx: ExtensionCommandContext, change: () => DenyRuleReport): v
 const SUBCOMMANDS = ["on", "off", "default", "deny", "rules"] as const;
 const DENY_ACTIONS = ["list", "add", "remove", "reset"] as const;
 
+const COMPLETION_DESCRIPTIONS: Readonly<Record<string, string>> = {
+    on: "Enable confinement for this session",
+    off: "Disable confinement for this session",
+    default: "Change the persistent activation default",
+    "default on": "Enable confinement by default",
+    "default off": "Disable confinement by default",
+    deny: "Manage write-denied paths",
+    "deny list": "Show configured write-denied paths",
+    "deny add": "Add a write-denied path",
+    "deny remove": "Remove a write-denied path",
+    "deny reset": "Restore packaged write-deny defaults",
+    rules: "Open the write-deny rule manager",
+};
+
 /** Argument completions for `/sandbox`, including the `deny` actions. */
-export function sandboxArgumentCompletions(argumentPrefix: string) {
+export function sandboxArgumentCompletions(argumentPrefix: string): AutocompleteItem[] {
     const prefix = argumentPrefix.trimStart().toLowerCase();
     const denyPrefix = /^deny(\s|$)/.test(prefix) ? prefix.replace(/^deny\s*/, "") : undefined;
     const defaultPrefix = /^default(\s|$)/.test(prefix)
@@ -275,5 +296,12 @@ export function sandboxArgumentCompletions(argumentPrefix: string) {
                     .map((value) => `default ${value}`)
               : SUBCOMMANDS.filter((value) => value.startsWith(prefix));
 
-    return values.map((value) => ({ value, label: value }));
+    return values.map((value) => {
+        const description = COMPLETION_DESCRIPTIONS[value];
+        return {
+            value,
+            label: value,
+            ...(description === undefined ? {} : { description }),
+        };
+    });
 }

package/files.ts

@@ -16,8 +16,8 @@
  * be re-targeted between the check and the syscall: the guard and the `fs` call
  * are the same operation.
  *
- * Reads stay unrestricted. `edit`'s `readFile` is delegated untouched; only the
- * operations that can change the host filesystem are guarded.
+ * Reads and mutations use the same canonical file-permission decisions as the
+ * kernel policy; protected-path write denials remain stricter than broad grants.
  */
 
 import { constants } from "node:fs";
@@ -34,6 +34,7 @@ import {
     type CompiledSandboxWritePolicy,
     compileWritePolicy,
     evaluateWriteAccess,
+    evaluateReadAccess,
     type SandboxSeams,
     type SandboxWritePolicy,
     type WriteAccessDecision,
@@ -77,9 +78,9 @@ function explainDenial(
 ): string {
     const attempt = kind === "directory" ? "create directory" : "write";
     const refused = `Foreground sandbox refused to ${attempt} ${decision.path}; nothing was changed on disk.`;
-    return decision.reason === "outside-writable-root"
-        ? `${refused} Writes are confined to ${policy.writableRoot}.`
-        : `${refused} ${decision.deniedBy} is a write-denied path.`;
+    if (decision.reason === "outside-writable-root") return `${refused} Writes are confined to ${policy.writableRoot}.`;
+    if (decision.reason === "write-denied") return `${refused} ${decision.deniedBy} is a write-denied path.`;
+    return `${refused} The selected file permissions do not allow this write.`;
 }
 
 /**
@@ -95,7 +96,7 @@ export type ForegroundWriteGuard = (absolutePath: string, kind?: MutationKind) =
 
 /** Identity of a compiled policy, so it is recompiled on change and not per mutation. */
 function policyKey(policy: SandboxWritePolicy): string {
-    return JSON.stringify([policy.writableRoot, policy.denyWrite ?? [], policy.home]);
+    return JSON.stringify(policy);
 }
 
 /**
@@ -137,6 +138,17 @@ export function createForegroundWriteGuard(
     };
 }
 
+/** Enforce reads in Pi's in-process file tools using the same canonical policy. */
+export function createForegroundReadGuard(controller: ForegroundSandboxController, seams: SandboxSeams = {}) {
+    return (absolutePath: string): string => {
+        const plan = controller.requireLaunchPlan();
+        if (!plan.confined) return absolutePath;
+        const decision = evaluateReadAccess(absolutePath, compileWritePolicy(plan.policy, seams), seams);
+        if (!decision.allowed) throw new Error(`Foreground sandbox refused to read ${decision.path}: ${decision.reason}.`);
+        return decision.path;
+    };
+}
+
 /** Pi's own default local backends, which the guarded operations delegate to. */
 const localWriteOperations: WriteOperations = {
     writeFile: (path, content) => fsWriteFile(path, content, "utf-8"),
@@ -189,18 +201,19 @@ export function createSandboxedWriteOperations(
  *
  * `access` is Pi's own pre-flight gate for `edit`, so guarding it refuses a
  * denied target before the file is read or a diff is computed; `writeFile` is
- * guarded because it is the mutation. `readFile` is delegated untouched — this
- * sandbox never restricts reads.
+ * guarded because it is the mutation. `readFile` also checks the selected read
+ * permissions before accessing content.
  */
 export function createSandboxedEditOperations(
     controller: ForegroundSandboxController,
     options: SandboxedEditOperationsOptions = {},
 ): EditOperations {
     const assertWritable = createForegroundWriteGuard(controller, options);
+    const assertReadable = createForegroundReadGuard(controller, options);
     const local = options.localOperations ?? localEditOperations;
 
     return {
-        readFile: (absolutePath) => local.readFile(absolutePath),
+        readFile: (absolutePath) => local.readFile(assertReadable(absolutePath)),
         async access(absolutePath) {
             return local.access(assertWritable(absolutePath));
         },

package/index.ts

@@ -5,17 +5,19 @@
  * keep starting Pi with plain `pi`. While enabled, the built-in `bash` tool and
  * user-entered `!` / `!!` commands run under macOS Seatbelt or Linux Bubblewrap
  * with one writable root — the canonical directory Pi was launched from — and
- * the packaged write-denied paths carved back out of it. The built-in `write`
- * and `edit` tools mutate files in Pi's own process rather than in a child, so
- * no argv wrapping can reach them; they are held to the same policy by an
- * in-process containment check instead. Reads and network are untouched.
+ * the packaged write-denied paths carved back out of it. Selected file,
+ * credential-file, command, and network permissions apply to protected tools.
+ * In-process file tools use the same canonical policy as spawned commands.
  *
  * This is a tool-execution sandbox. Pi's own process, `pi.exec` calls, and
  * unrelated third-party extension code are not confined by it.
  */
 
+import { homedir } from "node:os";
+import { resolve } from "node:path";
 import {
     createBashToolDefinition,
+    createReadToolDefinition,
     createEditToolDefinition,
     createWriteToolDefinition,
     SettingsManager,
@@ -37,8 +39,12 @@ import {
 import {
     createSandboxedEditOperations,
     createSandboxedWriteOperations,
+    createForegroundReadGuard,
 } from "./files.ts";
-import { readSandboxDefault, writeSandboxDefault } from "./preferences.ts";
+import { writeSandboxDefault } from "./preferences.ts";
+import { readPermissionSettings, writePermissionSettings } from "./permission-settings.ts";
+import { defaultSandboxPermissions } from "./permissions.ts";
+import { openPermissionsPage } from "./permissions-page.ts";
 import { createSandboxedBashOperations } from "./shell.ts";
 import { footerTone, formatFooterStatus } from "./status.ts";
 import { ForegroundSandboxController, type ForegroundSandboxStatus } from "./state.ts";
@@ -69,6 +75,7 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
     // operations run inside that queue, which is where the enforcement belongs.
     const writeOperations = createSandboxedWriteOperations(controller);
     const editOperations = createSandboxedEditOperations(controller);
+    const assertReadable = createForegroundReadGuard(controller);
 
     // `cwd` is what these tools resolve a relative `path` against, so it has to
     // be the directory Pi itself resolves against. Registration is re-run when
@@ -80,9 +87,42 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
         fileToolCwd = cwd;
         pi.registerTool(createWriteToolDefinition(cwd, { operations: writeOperations }));
         pi.registerTool(createEditToolDefinition(cwd, { operations: editOperations }));
+        const read = createReadToolDefinition(cwd);
+        pi.registerTool({
+            ...read,
+            execute: (id, params, signal, update, ctx) => {
+                const path = params.path.replace(/^@/, "");
+                const expanded = path === "~" ? homedir() : path.startsWith("~/") ? resolve(homedir(), path.slice(2)) : resolve(cwd, path);
+                return read.execute(id, { ...params, path: assertReadable(expanded) }, signal, update, ctx);
+            },
+        });
     };
     registerFileTools(process.cwd());
 
+    pi.on("tool_call", (event) => {
+        const status = controller.status();
+        if (status.state === "inactive" || status.state === "disabled") return;
+        const permissions = status.permissions;
+        if (!permissions) return;
+        const name = event.toolName;
+        const action = (event.input as { action?: string }).action;
+        const launch = ["bash", "powershell", "remote_bash", "subagent_spawn", "subagent_spawn_batch", "bg_task_spawn", "bg_task_watch"].includes(name) ||
+            (name === "bg_task" && (action === "spawn" || action === "watch"));
+        if (!permissions.commands && (launch || name === "grep" || name === "find")) {
+            return { block: true, reason: "Sandbox: Run commands & applications is Off. Change it in /sandbox to launch work." };
+        }
+        if (!permissions.network && (["web_search", "web_fetch", "firecrawl_scrape", "firecrawl_extract", "remote_bash", "mcp", "mcpScript"].includes(name) || name.startsWith("mcp__") ||
+            (launch && Boolean((event.input as { ssh?: unknown }).ssh)))) {
+            return { block: true, reason: "Sandbox: Network access is Off." };
+        }
+        if (name === "powershell" || name === "remote_bash") {
+            return { block: true, reason: `Sandbox: ${name} is not a confined execution surface; use bash (including ssh through bash).` };
+        }
+        if (status.readPolicy === "restricted" && ["grep", "find", "ls"].includes(name)) {
+            return { block: true, reason: "Sandbox: use the guarded read tool or a confined bash command for restricted file access." };
+        }
+    });
+
     let paintFooter: ((status: ForegroundSandboxStatus) => void) | undefined;
 
     const announce = (status: ForegroundSandboxStatus): void => {
@@ -110,19 +150,25 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
             );
         };
 
-        // Every session re-reads the persistent activation preference. Missing
-        // or malformed state resolves to the product default (off), never to an
-        // unexpected fail-closed session.
-        let defaultEnabled = false;
+        // Re-read saved profiles on each session. Malformed policy blocks protected
+        // operations rather than silently widening a restricted session.
+        let settings = defaultSandboxPermissions();
         try {
-            defaultEnabled = readSandboxDefault() === "on";
+            settings = readPermissionSettings();
         } catch (error) {
-            ctx.ui.notify(
-                `Foreground sandbox preference ignored; defaulting off: ${error instanceof Error ? error.message : String(error)}`,
-                "warning",
-            );
+            controller.beginSession(ctx.cwd, true);
+            const message = `Sandbox permissions could not be loaded: ${error instanceof Error ? error.message : String(error)}`;
+            settings.main.enabled = true;
+            settings.main.commands = false;
+            settings.subagents.commands = false;
+            controller.setPermissionSettings(settings);
+            announce(controller.block(message));
+            ctx.ui.notify(message, "error");
+            return;
         }
-        controller.beginSession(ctx.cwd, defaultEnabled);
+        controller.beginSession(ctx.cwd, settings.main.enabled);
+        controller.setPermissionSettings(settings);
+        controller.applyDefault(settings.main.enabled);
 
         // Then the rules are re-read and re-resolved, because the same global
         // template set means different absolute paths in a different project.
@@ -160,8 +206,18 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
             denyRules,
             onStateChange: announce,
             setDefault: (enabled) => {
+                const settings = controller.permissionSettings() ?? defaultSandboxPermissions();
+                settings.main.enabled = enabled;
+                writePermissionSettings(settings);
                 writeSandboxDefault(enabled ? "on" : "off");
-                return controller.applyDefault(enabled);
+                return controller.setPermissionSettings(settings);
+            },
+            openPermissions: async (ctx) => {
+                await openPermissionsPage(ctx, {
+                    getConfig: () => controller.permissionSettings() ?? defaultSandboxPermissions(),
+                    change: (settings) => announce(controller.setPermissionSettings(settings)),
+                    save: (settings) => writePermissionSettings(settings),
+                });
             },
         }),
     });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-better-sandbox",
-  "version": "0.2.0",
-  "description": "Pi extension that confines foreground shell execution to the project directory with a kernel-enforced write sandbox.",
+  "version": "0.4.0",
+  "description": "Pi extension with independent Main and Subagents permission profiles, file guards, and OS sandbox enforcement.",
   "license": "MIT",
   "type": "module",
   "main": "index.ts",

package/permission-settings.ts

@@ -0,0 +1,44 @@
+/** Versioned storage for the permission table; does not activate enforcement. */
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { defaultSandboxPermissions, parseSandboxPermissions, type SandboxPermissionSettings } from "./permissions.ts";
+import { readSandboxDefault, type SandboxPreferenceSeams } from "./preferences.ts";
+
+export function permissionSettingsPath(seams: SandboxPreferenceSeams = {}): string {
+    return join((seams.agentDir ?? getAgentDir)(), "extensions", "pi-better-sandbox-permissions.json");
+}
+
+export function readPermissionSettings(seams: SandboxPreferenceSeams = {}): SandboxPermissionSettings {
+    let raw: string;
+    try {
+        raw = readFileSync(permissionSettingsPath(seams), "utf8");
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+        const settings = defaultSandboxPermissions();
+        settings.main.enabled = readSandboxDefault(seams) === "on";
+        return settings;
+    }
+    const parsed: unknown = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || (parsed as { version?: unknown }).version !== 1) {
+        throw new Error("Unsupported sandbox permissions file version.");
+    }
+    return parseSandboxPermissions((parsed as { permissions?: unknown }).permissions);
+}
+
+export function writePermissionSettings(
+    settings: SandboxPermissionSettings,
+    seams: SandboxPreferenceSeams = {},
+): void {
+    const permissions = parseSandboxPermissions(settings);
+    const path = permissionSettingsPath(seams);
+    mkdirSync(dirname(path), { recursive: true });
+    const pending = `${path}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(pending, JSON.stringify({ version: 1, permissions }, null, 2) + "\n", { mode: 0o600, flag: "wx" });
+        renameSync(pending, path);
+    } finally {
+        rmSync(pending, { force: true });
+    }
+}

package/permissions-page.ts

@@ -0,0 +1,177 @@
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
+
+import { defaultSandboxPermissions, type FileAccess, type SandboxPermissionProfile as PermissionProfile, type SandboxPermissionSettings as PermissionSettings } from "./permissions.ts";
+export type { PermissionProfile, PermissionSettings };
+
+export interface PermissionPageHandlers {
+    getConfig(): PermissionSettings;
+    change(settings: PermissionSettings): void | Promise<void>;
+    save(settings: PermissionSettings): void | Promise<void>;
+}
+
+export const DEFAULT_PERMISSION_SETTINGS = defaultSandboxPermissions();
+
+const rows = [
+    { label: "Sandbox", key: "enabled" },
+    { label: "Project files", key: "projectFiles" },
+    { label: "Outside project", key: "outsideProject" },
+    { label: "Stored credentials", key: "storedCredentials" },
+    { label: "Run commands & applications", key: "commands" },
+    { label: "Network access", key: "network" },
+] as const;
+const fileValues: readonly FileAccess[] = ["off", "read", "read-write"];
+const columns = ["main", "subagents"] as const;
+
+function snapshot(settings: PermissionSettings): PermissionSettings {
+    return { main: { ...settings.main }, subagents: { ...settings.subagents } };
+}
+
+function errorText(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+}
+
+function cell(text: string, width: number): string {
+    if (width <= 0) return "";
+    const cut = truncateToWidth(text, width, "");
+    return cut + " ".repeat(Math.max(0, width - visibleWidth(cut)));
+}
+
+/** A flat, keyboard-driven view; handlers own the effective policy and persistence. */
+export function createPermissionsPage(
+    theme: Theme,
+    handlers: PermissionPageHandlers,
+    requestRender: () => void,
+    close: () => void,
+): Component {
+    let settings: PermissionSettings | undefined;
+    let message = "";
+    let isError = false;
+    try {
+        settings = snapshot(handlers.getConfig());
+    } catch (error) {
+        message = errorText(error);
+        isError = true;
+    }
+    let row = 0;
+    let column = 0;
+    let busy = false;
+
+    function report(error: unknown): void {
+        message = errorText(error);
+        isError = true;
+        requestRender();
+    }
+
+    async function change(): Promise<void> {
+        if (!settings || busy || row === rows.length) return;
+        const key = rows[row]!.key;
+        const profile = columns[column]!;
+        if (key !== "enabled" && !settings[profile].enabled) return;
+        const next = snapshot(settings);
+        if (key === "enabled" || key === "commands" || key === "network") {
+            next[profile][key] = !next[profile][key];
+        } else {
+            const current = next[profile][key];
+            next[profile][key] = fileValues[(fileValues.indexOf(current) + 1) % fileValues.length]!;
+        }
+        busy = true;
+        try {
+            await handlers.change(snapshot(next));
+            settings = next;
+            message = "";
+            isError = false;
+            requestRender();
+        } catch (error) {
+            report(error);
+        } finally {
+            busy = false;
+        }
+    }
+
+    async function save(): Promise<void> {
+        if (!settings || busy) return;
+        busy = true;
+        try {
+            await handlers.save(snapshot(settings));
+            message = "Defaults saved.";
+            isError = false;
+            requestRender();
+        } catch (error) {
+            report(error);
+        } finally {
+            busy = false;
+        }
+    }
+
+    return {
+        invalidate() {},
+        handleInput(data: string) {
+            if (matchesKey(data, Key.escape)) {
+                close();
+            } else if (matchesKey(data, Key.up)) {
+                row = Math.max(0, row - 1);
+                requestRender();
+            } else if (matchesKey(data, Key.down)) {
+                row = Math.min(rows.length, row + 1);
+                requestRender();
+            } else if (matchesKey(data, Key.left)) {
+                column = 0;
+                requestRender();
+            } else if (matchesKey(data, Key.right)) {
+                column = 1;
+                requestRender();
+            } else if (matchesKey(data, Key.space)) {
+                void change();
+            } else if (matchesKey(data, Key.enter) && row === rows.length) {
+                void save();
+            }
+        },
+        render(width: number): string[] {
+            const w = Math.max(0, Math.floor(width));
+            const prefix = w >= 20 ? 2 : 0;
+            const gap = w >= 8 ? 1 : 0;
+            const minimumCell = Math.max(1, Math.min(10, Math.floor((w - prefix - gap) / 3)));
+            const labelWidth = Math.min(28, Math.max(0, w - prefix - gap - 2 * minimumCell));
+            const available = Math.max(0, w - prefix - labelWidth - gap);
+            const mainWidth = Math.ceil(available / 2);
+            const subWidth = available - mainWidth;
+            const line = (label: string, main: string, sub: string, selected: boolean, dimMain = false, dimSub = false) => {
+                const marker = prefix ? (selected ? "> " : "  ") : "";
+                const labelPart = cell(label, labelWidth);
+                const mainPart = cell(main, mainWidth);
+                const subPart = cell(sub, subWidth);
+                return theme.fg(selected ? "accent" : "text", marker + labelPart) + " ".repeat(gap) +
+                    theme.fg(dimMain ? "dim" : selected && column === 0 ? "accent" : "text", mainPart) +
+                    theme.fg(dimSub ? "dim" : selected && column === 1 ? "accent" : "text", subPart);
+            };
+            const output = [line("Sandbox permissions", "Main", "Subagents", false), ""];
+            for (let i = 0; i < rows.length; i++) {
+                const entry = rows[i]!;
+                const value = (profile: PermissionProfile): string => {
+                    if (entry.key !== "enabled" && !profile.enabled) return "-";
+                    const current = profile[entry.key];
+                    return typeof current === "boolean" ? (current ? "On" : "Off") :
+                        current === "read-write" ? "Read / write" : current === "read" ? "Read" : "Off";
+                };
+                output.push(line(entry.label, settings ? value(settings.main) : "-", settings ? value(settings.subagents) : "-",
+                    row === i, !settings || (i > 0 && !settings.main.enabled), !settings || (i > 0 && !settings.subagents.enabled)));
+                if (i === 0) output.push("");
+            }
+            output.push("", line("Save as defaults", "", "", row === rows.length));
+            for (const hint of [
+                "↑↓ Select row · ←→ Select column · Space Change · Enter Save · Esc Back",
+                "Changes apply to new launches. Background tasks follow their launcher.",
+                "Stored credentials: known files only; excludes OS vaults and environment tokens.",
+            ]) output.push(theme.fg("dim", truncateToWidth(hint, w, "")));
+            if (message) output.push(theme.fg(isError ? "error" : "muted", truncateToWidth(message.replace(/[\r\n]+/g, " "), w, "")));
+            return output;
+        },
+    };
+}
+
+export async function openPermissionsPage(ctx: ExtensionContext, handlers: PermissionPageHandlers): Promise<void> {
+    if (ctx.mode !== "tui" || !ctx.hasUI) return;
+    await ctx.ui.custom<null>((tui, theme, _keybindings, done) =>
+        createPermissionsPage(theme, handlers, () => tui.requestRender(), () => done(null)));
+}

package/permissions.ts

@@ -0,0 +1,50 @@
+/** Permission values are intent; launch backends must validate support before enforcement. */
+export type FileAccess = "off" | "read" | "read-write";
+export interface SandboxPermissionProfile {
+    enabled: boolean;
+    projectFiles: FileAccess;
+    outsideProject: FileAccess;
+    storedCredentials: FileAccess;
+    commands: boolean;
+    network: boolean;
+}
+export interface SandboxPermissionSettings {
+    main: SandboxPermissionProfile;
+    subagents: SandboxPermissionProfile;
+}
+
+/** Return fresh profiles so changing one column never changes the other. */
+export function defaultSandboxPermissions(): SandboxPermissionSettings {
+    const profile = (): SandboxPermissionProfile => ({
+        enabled: false,
+        projectFiles: "read-write",
+        outsideProject: "read",
+        storedCredentials: "read",
+        commands: true,
+        network: true,
+    });
+    return { main: profile(), subagents: { ...profile(), enabled: true } };
+}
+
+function isProfile(value: unknown): value is SandboxPermissionProfile {
+    if (!value || typeof value !== "object") return false;
+    const p = value as Record<string, unknown>;
+    const access = (v: unknown): boolean => v === "off" || v === "read" || v === "read-write";
+    return typeof p.enabled === "boolean" && typeof p.commands === "boolean" &&
+        typeof p.network === "boolean" && access(p.projectFiles) &&
+        access(p.outsideProject) && access(p.storedCredentials);
+}
+
+/** Strict decoding: malformed policy must not silently broaden permissions. */
+export function parseSandboxPermissions(value: unknown): SandboxPermissionSettings {
+    if (!value || typeof value !== "object") throw new Error("Invalid sandbox permission settings.");
+    const settings = value as Record<string, unknown>;
+    if (!isProfile(settings.main) || !isProfile(settings.subagents)) {
+        throw new Error("Sandbox settings require Main and Subagents profiles with explicit permission values.");
+    }
+    const copy = (p: SandboxPermissionProfile): SandboxPermissionProfile => ({
+        enabled: p.enabled, projectFiles: p.projectFiles, outsideProject: p.outsideProject,
+        storedCredentials: p.storedCredentials, commands: p.commands, network: p.network,
+    });
+    return { main: copy(settings.main), subagents: copy(settings.subagents) };
+}

package/shared-sandbox-core.ts

@@ -2,11 +2,11 @@
 /**
  * OS-level write sandbox mechanism shared by Pi extensions.
  *
- * Kernel-enforced confinement: the sandboxed process may READ anywhere and use
- * the network (so web_fetch and the model API keep working), but may only WRITE
- * under a single canonical root plus the system paths pi itself needs. Unlike a
- * cooperative guardrails layer (which pattern-matches tool inputs), this cannot
- * be evaded by a crafted bash command — the write syscall itself is denied.
+ * Legacy policies are write-only: a sandboxed process may READ anywhere and use
+ * the network, but may only WRITE under a canonical root plus runtime paths.
+ * Optional permissions add capability restrictions for reads, writes, launches
+ * and network access. They cover known credential files, not OS keychains,
+ * credential services, or tokens inherited in the child environment.
  *
  * This module owns the mechanism only: backend discovery, canonical path
  * containment, write-deny compilation, macOS SBPL profile construction, Linux
@@ -35,6 +35,14 @@ import { basename, delimiter, dirname, join, resolve, sep } from "node:path";
 /** Identifies which kernel mechanism a plan will use. */
 export type SandboxBackendId = "macos-seatbelt" | "linux-bubblewrap";
 
+export type SandboxPermissions = {
+    projectFiles: "off" | "read" | "read-write";
+    outsideProject: "off" | "read" | "read-write";
+    storedCredentials: "off" | "read" | "read-write";
+    commands: boolean;
+    network: boolean;
+};
+
 /**
  * What a sandboxed process may write. `writableRoot` and `denyWrite` entries may
  * be relative or contain symlinks; they are canonicalized before use.
@@ -55,6 +63,10 @@ export type SandboxWritePolicy = {
     denyWrite?: readonly string[];
     /** Home directory whose `~/.pi` state stays writable on macOS. */
     home: string;
+    /** Optional capability profile; omission preserves the original write-only sandbox. */
+    permissions?: SandboxPermissions;
+    /** Trusted per-launch runtime state, never supplied by model tool arguments. */
+    runtimeWrite?: readonly string[];
 };
 
 /** The executable and argv to run inside the sandbox, preserved verbatim. */
@@ -109,6 +121,9 @@ export type CompiledSandboxWritePolicy = {
     readonly writableRoot: string;
     readonly denyWrite: readonly string[];
     readonly home: string;
+    readonly permissions?: SandboxPermissions;
+    readonly credentialPaths?: readonly string[];
+    readonly runtimeWrite?: readonly string[];
 };
 
 /** Why a write target is or is not permitted by a compiled policy. */
@@ -117,11 +132,15 @@ export type WriteAccessDecision =
     | {
           allowed: false;
           path: string;
-          reason: "outside-writable-root" | "write-denied";
+          reason: "outside-writable-root" | "write-denied" | "permission-denied";
           /** The compiled deny entry that matched, for `write-denied` only. */
           deniedBy?: string;
       };
 
+export type ReadAccessDecision =
+    | { allowed: true; path: string }
+    | { allowed: false; path: string; reason: "read-denied" };
+
 /** What the current platform can enforce, and why it cannot when it cannot. */
 export type SandboxSupport =
     | { supported: true; platform: string; backend: SandboxBackendId; executable: string }
@@ -141,6 +160,29 @@ type SandboxBackend = {
 
 const MACOS_SANDBOX_EXEC = "/usr/bin/sandbox-exec";
 
+const CREDENTIAL_LOCATIONS = [
+    ".ssh", ".aws", ".config/gh", ".config/gcloud", ".azure", ".kube",
+    ".docker/config.json", ".npmrc", ".netrc", ".git-credentials", ".pi/agent/auth.json",
+] as const;
+
+// Executables, dynamic libraries and OS frameworks needed to start a child.
+// This deliberately excludes the home directory, /etc, and credential stores.
+// A process relying on /etc or /proc configuration (DNS, certificates, NSS)
+// may not start or function under Linux outsideProject=off; callers must not
+// silently remount these broad host trees to work around that failure.
+const RUNTIME_ROOTS = ["/usr", "/bin", "/sbin", "/lib", "/lib64", "/System/Library", "/System/Cryptexes", "/Library/Apple", "/Library/Developer", "/opt/homebrew"];
+const TEMP_ROOTS = ["/private/var/folders", "/private/tmp", "/tmp", "/dev"];
+const READ_RUNTIME_ROOTS = [...RUNTIME_ROOTS, "/dev"];
+
+/** Only known on-disk credentials: keychains, services and inherited env tokens are out of scope. */
+export function credentialFilePaths(home: string, seams: SandboxSeams = {}): string[] {
+    const paths = CREDENTIAL_LOCATIONS.map((name) => join(home, name));
+    const configuredAgentDir = process.env.PI_CODING_AGENT_DIR;
+    if (configuredAgentDir) paths.push(join(configuredAgentDir.startsWith("~/")
+        ? join(home, configuredAgentDir.slice(2)) : configuredAgentDir, "auth.json"));
+    return [...new Set(paths.map((path) => canonicalizePath(path, seams)))].sort();
+}
+
 function currentPlatform(seams: SandboxSeams): string {
     return (seams.platform ?? osPlatform)();
 }
@@ -154,7 +196,19 @@ export function canonicalizePath(path: string, seams: SandboxSeams = {}): string
     const canonicalize = seams.canonicalize ?? realpathSync;
     const absolute = resolve(path);
     try {
-        return canonicalize(absolute);
+        const resolved = canonicalize(absolute);
+        // APFS firmlinks are not resolved by realpath. Normalize the Data-volume
+        // alias only when both names demonstrably refer to the same inode.
+        const dataPrefix = "/System/Volumes/Data";
+        if (!seams.canonicalize && currentPlatform(seams) === "darwin" && resolved.startsWith(`${dataPrefix}/`)) {
+            const candidate = resolved.slice(dataPrefix.length);
+            try {
+                const source = statSync(resolved);
+                const alias = statSync(candidate);
+                if (source.dev === alias.dev && source.ino === alias.ino) return realpathSync(candidate);
+            } catch { /* An unrelated Data-volume path keeps its original identity. */ }
+        }
+        return resolved;
     } catch {
         // Not created yet (or unreadable): canonicalize the parent instead.
     }
@@ -179,7 +233,14 @@ function compile(
         ...new Set((policy.denyWrite ?? []).map((entry) => canonicalizePath(entry, seams))),
     ].sort();
 
-    return { writableRoot, denyWrite, home: policy.home };
+    return {
+        writableRoot, denyWrite, home: policy.home,
+        ...(policy.permissions && {
+            permissions: { ...policy.permissions },
+            credentialPaths: credentialFilePaths(policy.home, seams),
+            runtimeWrite: (policy.runtimeWrite ?? []).map((path) => canonicalizePath(path, seams)),
+        }),
+    };
 }
 
 /**
@@ -198,6 +259,31 @@ function contains(root: string, target: string): boolean {
     return target.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
 }
 
+function isCredential(path: string, policy: CompiledSandboxWritePolicy): boolean {
+    return (policy.credentialPaths ?? []).some((credential) => contains(credential, path));
+}
+
+function runtimeRoots(seams: SandboxSeams): string[] {
+    return [...new Set(READ_RUNTIME_ROOTS.map((path) => canonicalizePath(path, seams)))];
+}
+
+/** Decide read access using the same canonical path and capability precedence as writes. */
+export function evaluateReadAccess(
+    target: string,
+    policy: CompiledSandboxWritePolicy,
+    seams: SandboxSeams = {},
+): ReadAccessDecision {
+    const path = canonicalizePath(target, seams);
+    const permissions = policy.permissions;
+    if (!permissions) return { allowed: true, path };
+    const mode = isCredential(path, policy) ? permissions.storedCredentials
+        : policy.runtimeWrite?.some((root) => contains(root, path)) ? "read-write"
+        : contains(policy.writableRoot, path) ? permissions.projectFiles
+        : path === sep || runtimeRoots(seams).some((root) => contains(root, path)) ? "read"
+        : permissions.outsideProject;
+    return mode === "off" ? { allowed: false, path, reason: "read-denied" } : { allowed: true, path };
+}
+
 /**
  * Decide whether an in-process write to `target` is permitted by a compiled
  * policy. This is the same containment rule the kernel backends enforce, for
@@ -209,7 +295,7 @@ export function evaluateWriteAccess(
     seams: SandboxSeams = {},
 ): WriteAccessDecision {
     const path = canonicalizePath(target, seams);
-    if (!contains(policy.writableRoot, path)) {
+    if (!policy.permissions && !contains(policy.writableRoot, path)) {
         return { allowed: false, path, reason: "outside-writable-root" };
     }
     for (const denied of policy.denyWrite) {
@@ -217,6 +303,14 @@ export function evaluateWriteAccess(
             return { allowed: false, path, reason: "write-denied", deniedBy: denied };
         }
     }
+    if (policy.permissions) {
+        const mode = isCredential(path, policy) ? policy.permissions.storedCredentials
+            : policy.runtimeWrite?.some((root) => contains(root, path)) ? "read-write"
+            : contains(policy.writableRoot, path) ? policy.permissions.projectFiles
+            : contains(canonicalizePath("/dev", seams), path) ? "read-write"
+            : policy.permissions.outsideProject;
+        if (mode !== "read-write") return { allowed: false, path, reason: "permission-denied" };
+    }
     return { allowed: true, path };
 }
 
@@ -225,13 +319,70 @@ function sbpl(path: string): string {
     return `"${path.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
 
+function validateRuntimeHome(policy: CompiledSandboxWritePolicy, seams: SandboxSeams): void {
+    if (policy.permissions?.outsideProject !== "off") return;
+    const home = canonicalizePath(policy.home, seams);
+    if (RUNTIME_ROOTS.some((root) => contains(canonicalizePath(root, seams), home))) {
+        throw new Error("outsideProject=off cannot expose a home under a required system runtime root; move the home or use another permission mode.");
+    }
+}
+
+function protectedAncestors(paths: readonly string[]): string[] {
+    const parents = new Set<string>();
+    for (const path of paths) {
+        for (let parent = dirname(path); dirname(parent) !== parent; parent = dirname(parent)) parents.add(parent);
+    }
+    return [...parents].sort((a, b) => a.length - b.length);
+}
+
+function buildPermissionProfile(policy: CompiledSandboxWritePolicy, seams: SandboxSeams): string {
+    validateRuntimeHome(policy, seams);
+    const permissions = policy.permissions!;
+    const protectedPaths = [
+        ...policy.denyWrite,
+        ...(permissions.projectFiles !== "read-write" ? [policy.writableRoot] : []),
+        ...(permissions.storedCredentials !== "read-write" ? policy.credentialPaths ?? [] : []),
+    ];
+    const rules = ["(version 1)", "(allow default)", "(deny file-write*)"];
+    if (permissions.outsideProject === "off") {
+        rules.push("(deny file-read*)", "(allow file-read-metadata)", '(allow file-read* (literal "/"))');
+        for (const root of runtimeRoots(seams)) {
+            rules.push(`(allow file-read* (subpath ${sbpl(root)}))`);
+        }
+    }
+    if (permissions.outsideProject === "read-write") rules.push("(allow file-write*)");
+    // Temporary host paths are not granted for off/read: doing so would expose
+    // other users' files in temp. /dev remains necessary for basic shell I/O.
+    for (const root of TEMP_ROOTS.filter((path) => permissions.outsideProject === "read-write" || path === "/dev")
+        .map((path) => canonicalizePath(path, seams))) {
+        rules.push(`(allow file-write* (subpath ${sbpl(root)}))`);
+    }
+    const scoped = (root: string, mode: SandboxPermissions["projectFiles"]) => {
+        if (mode === "off") rules.push(`(deny file-read* (subpath ${sbpl(root)}))`);
+        else rules.push(`(allow file-read* (subpath ${sbpl(root)}))`);
+        if (mode === "read-write") rules.push(`(allow file-write* (subpath ${sbpl(root)}))`);
+        else rules.push(`(deny file-write* (subpath ${sbpl(root)}))`);
+    };
+    // Last matching SBPL rule wins. Credential rules override project and outside;
+    // explicit denyWrite entries always override every write allowance.
+    scoped(policy.writableRoot, permissions.projectFiles);
+    for (const path of policy.runtimeWrite ?? []) scoped(path, "read-write");
+    for (const path of policy.credentialPaths ?? []) scoped(path, permissions.storedCredentials);
+    for (const path of policy.denyWrite) rules.push(`(deny file-write* (subpath ${sbpl(path)}))`);
+    // Protect the directory entries, not their contents: unrelated children can
+    // still be created, while renaming a parent cannot move a denied subtree.
+    for (const path of protectedAncestors(protectedPaths)) rules.push(`(deny file-write-unlink (literal ${sbpl(path)}))`);
+    if (!permissions.network) rules.push("(deny network*)");
+    return [...rules, ""].join("\n");
+}
+
 /** Build the macOS sandbox-exec wrapper and its SBPL profile. */
 function buildMacOSSandboxCommand(args: SandboxCommandArgs, seams: SandboxSeams): SandboxCommand {
     // Match on the real (symlink-resolved) path — sandbox-exec evaluates the
     // canonical path, so /tmp/x must be written as /private/tmp/x.
     const policy = compile(args.policy, seams, false);
 
-    const profile = [
+    const profile = policy.permissions ? buildPermissionProfile(policy, seams) : [
         "(version 1)",
         "(allow default)",          // permissive base: reads, exec, network
         "(deny file-write*)",       // ...then deny all writes...
@@ -344,6 +495,7 @@ function buildLinuxSandboxCommand(
     // boundary. Canonicalizing it before bind-mounting keeps symlink aliases from
     // widening the writable root.
     const policy = compile(args.policy, seams, true);
+    if (policy.permissions) return buildLinuxPermissionCommand(bwrap, args, policy, seams);
     const materialize = seams.materializeDenyPath ?? materializeDenyPath;
     const denyBinds = policy.denyWrite.flatMap((path) => {
         const mountable = writableInsideLinuxSandbox(path, policy.writableRoot) && materialize(path);
@@ -368,6 +520,113 @@ function buildLinuxSandboxCommand(
     };
 }
 
+function buildLinuxPermissionCommand(
+    bwrap: string,
+    args: SandboxCommandArgs,
+    policy: CompiledSandboxWritePolicy,
+    seams: SandboxSeams,
+): SandboxCommand {
+    const permissions = policy.permissions!;
+    validateRuntimeHome(policy, seams);
+    const project = policy.writableRoot;
+    const credentials = policy.credentialPaths ?? [];
+    const writableProject = permissions.projectFiles === "read-write";
+    const overlappingCredentials = credentials.filter((path) => contains(project, path));
+    if (credentials.some((path) => contains(path, project)) &&
+        permissions.projectFiles !== permissions.storedCredentials) {
+        throw new Error("Linux bubblewrap cannot apply differing project and credential permissions when a credential directory contains the project.");
+    }
+    if (writableProject && policy.denyWrite.some((path) => contains(path, project))) {
+        throw new Error("Linux bubblewrap cannot make a project writable inside a write-denied directory.");
+    }
+    // Protected leaves and their writable ancestors become mount points below.
+    // Linux refuses renaming mount points, preventing ancestor replacement.
+    if (permissions.outsideProject === "read-write" && (
+        permissions.projectFiles !== "read-write" || permissions.storedCredentials !== "read-write" ||
+        policy.denyWrite.length > 0
+    )) {
+        throw new Error("Linux bubblewrap cannot enforce restricted project/credential/denyWrite paths under a writable outsideProject mount.");
+    }
+    if (permissions.outsideProject === "read" && permissions.storedCredentials === "read-write" &&
+        credentials.some((path) => !contains(project, path))) {
+        throw new Error("Linux bubblewrap cannot write credential stores under a read-only outsideProject root.");
+    }
+    if (permissions.projectFiles === "read" && permissions.storedCredentials === "read-write" &&
+        overlappingCredentials.length > 0) {
+        throw new Error("Linux bubblewrap cannot write credential stores under a read-only project mount.");
+    }
+    if (permissions.outsideProject === "read" && permissions.storedCredentials === "off") {
+        throw new Error("Linux bubblewrap cannot hide stored credentials in a read-only whole-root bind.");
+    }
+    if (permissions.outsideProject === "off" && permissions.storedCredentials === "off" &&
+        credentials.some((path) => contains(project, path) && permissions.projectFiles !== "off")) {
+        throw new Error("Linux bubblewrap cannot hide credentials inside a visible read-only project.");
+    }
+    if (permissions.outsideProject === "off" && permissions.projectFiles === "off" &&
+        RUNTIME_ROOTS.some((root) => contains(canonicalizePath(root, seams), project))) {
+        throw new Error("Linux bubblewrap cannot hide a project nested under a required system runtime bind.");
+    }
+    if (permissions.outsideProject === "off" && credentials.some((path) =>
+        !contains(project, path) &&
+        RUNTIME_ROOTS.some((root) => contains(canonicalizePath(root, seams), path)) &&
+        permissions.storedCredentials === "off")) {
+        throw new Error("Linux bubblewrap cannot hide credentials under a required system runtime bind.");
+    }
+    if (permissions.outsideProject === "off" && permissions.storedCredentials === "read-write" &&
+        credentials.some((path) => !contains(project, path))) {
+        throw new Error("Linux bubblewrap cannot create or safely bind writable credential stores outside a hidden root.");
+    }
+    if (permissions.outsideProject === "off" && permissions.projectFiles === "off" &&
+        permissions.storedCredentials !== "off" && credentials.some((path) => contains(project, path))) {
+        throw new Error("Linux bubblewrap cannot expose credentials inside a hidden project without exposing the project.");
+    }
+    if (permissions.outsideProject !== "off" && permissions.projectFiles === "off") {
+        throw new Error("Linux bubblewrap cannot hide a project inside a visible outsideProject root.");
+    }
+    const mounts: string[] = permissions.outsideProject === "off" ? ["--tmpfs", "/"]
+        : [permissions.outsideProject === "read" ? "--ro-bind" : "--bind", "/", "/"];
+    if (permissions.outsideProject === "off") {
+        // Bounded system executable/library roots only. /tmp is private, not a
+        // host bind: otherwise outsideProject=off would expose user temp data.
+        for (const root of RUNTIME_ROOTS) {
+            if (existsSync(root)) mounts.push("--ro-bind", root, root);
+        }
+        mounts.push("--tmpfs", "/tmp");
+    } else {
+        mounts.push(permissions.outsideProject === "read" ? "--ro-bind" : "--bind", "/tmp", "/tmp");
+    }
+    mounts.push("--dev", "/dev");
+    if (permissions.projectFiles !== "off") {
+        mounts.push(writableProject ? "--bind" : "--ro-bind", project, project);
+    }
+    if (permissions.outsideProject === "off" && permissions.storedCredentials === "read") {
+        for (const path of credentials) {
+            if (existsSync(path) && !contains(project, path)) mounts.push("--ro-bind", path, path);
+        }
+    }
+    for (const path of policy.runtimeWrite ?? []) {
+        if ([...credentials, ...policy.denyWrite].some((protectedPath) => contains(path, protectedPath) || contains(protectedPath, path))) {
+            throw new Error("Runtime directory overlaps protected credentials or control paths.");
+        }
+        mounts.push("--bind", path, path);
+    }
+    const protectedPaths = [...policy.denyWrite,
+        ...(permissions.storedCredentials !== "read-write" ? overlappingCredentials : [])];
+    if (writableProject) {
+        const materialize = seams.materializeDenyPath ?? materializeDenyPath;
+        const leaves = protectedPaths.filter((path) => contains(project, path) && materialize(path));
+        for (const parent of protectedAncestors(leaves).filter((path) => contains(project, path) && path !== project)) {
+            mounts.push("--bind", parent, parent);
+        }
+        for (const path of leaves) mounts.push("--ro-bind", path, path);
+    }
+    return {
+        file: bwrap,
+        fileArgs: [...mounts, ...(!permissions.network ? ["--unshare-net"] : []),
+            "--", args.execPath, ...args.execArgs],
+    };
+}
+
 function linuxSandboxBackend(seams: SandboxSeams): SandboxBackend | undefined {
     const bwrap = (seams.lookupExecutable ?? executableFromPath)("bwrap");
     if (!bwrap) return undefined;
@@ -436,10 +695,16 @@ export function maybeBuildSandboxCommand(
     request: SandboxRequest,
     seams: SandboxSeams = {},
 ): SandboxCommand | undefined {
+    if (args.policy.permissions?.commands === false) {
+        throw new Error("Sandbox commands permission is off; enable commands before launching a sandboxed process (including bootstrap).");
+    }
     if (!request.sandboxEnabled) return undefined;
 
     const backend = selectedSandboxBackend(seams);
     if (!backend) {
+        if (args.policy.permissions) {
+            throw new Error(`Cannot enforce sandbox permissions: ${sandboxUnavailableMessage(seams)}`);
+        }
         if (request.explicitSandbox) {
             const reason = sandboxUnavailableMessage(seams);
             throw new Error(request.remedy ? `${reason} ${request.remedy}` : reason);
@@ -458,5 +723,12 @@ export function buildSandboxCommand(
     args: SandboxCommandArgs,
     seams: SandboxSeams = {},
 ): SandboxCommand {
-    return (selectedSandboxBackend(seams) ?? macOSSandboxBackend).buildCommand(args, seams);
+    if (args.policy.permissions?.commands === false) {
+        throw new Error("Sandbox commands permission is off; enable commands before launching a sandboxed process (including bootstrap).");
+    }
+    const backend = selectedSandboxBackend(seams);
+    if (!backend && args.policy.permissions) {
+        throw new Error(`Cannot enforce sandbox permissions: ${sandboxUnavailableMessage(seams)}`);
+    }
+    return (backend ?? macOSSandboxBackend).buildCommand(args, seams);
 }

package/state.ts

@@ -11,11 +11,13 @@
  * default and clears the previous override.
  */
 
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { createHash } from "node:crypto";
 import { mkdtempSync, rmSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 
+import { parseSandboxPermissions, type SandboxPermissionSettings, type SandboxPermissionProfile } from "./permissions.ts";
 import {
     canonicalizePath,
     describeSandboxSupport,
@@ -58,9 +60,11 @@ export type ForegroundSandboxStatus = {
     readonly backend: SandboxBackendId | undefined;
     readonly executable: string | undefined;
     /** Reads are never restricted by this sandbox. */
-    readonly readPolicy: "unrestricted";
-    /** Network is never restricted by this sandbox. */
-    readonly networkPolicy: "unrestricted";
+    readonly readPolicy: "unrestricted" | "restricted";
+    /** Network policy for confined commands (not the parent Pi provider connection). */
+    readonly networkPolicy: "unrestricted" | "blocked";
+    readonly permissions?: Readonly<SandboxPermissionProfile>;
+    readonly subagentPermissions?: Readonly<SandboxPermissionProfile>;
     /** Human-readable evidence for why `state` is what it is. */
     readonly reason: string;
 };
@@ -113,6 +117,8 @@ export class ForegroundSandboxController {
     #defaultEnabled = false;
     #sessionOverride: boolean | undefined;
     #profileDir: string | undefined;
+    #permissions: SandboxPermissionSettings | undefined;
+    #policyProblem: string | undefined;
 
     constructor(seams: ForegroundSandboxSeams = {}) {
         this.#seams = seams;
@@ -133,6 +139,8 @@ export class ForegroundSandboxController {
         );
         this.#defaultEnabled = defaultEnabled;
         this.#sessionOverride = undefined;
+        this.#permissions = undefined;
+        this.#policyProblem = undefined;
         return this.status();
     }
 
@@ -145,6 +153,7 @@ export class ForegroundSandboxController {
     /** Turn protection off for this session only. Never persisted. */
     disable(): ForegroundSandboxStatus {
         this.#sessionOverride = false;
+        this.#policyProblem = undefined;
         return this.status();
     }
 
@@ -160,6 +169,27 @@ export class ForegroundSandboxController {
         return this.#sessionOverride ?? this.#defaultEnabled;
     }
 
+    /** Apply human-selected profiles. Disabled profiles keep their detail values. */
+    setPermissionSettings(settings: SandboxPermissionSettings): ForegroundSandboxStatus {
+        this.#permissions = parseSandboxPermissions(settings);
+        this.#policyProblem = undefined;
+        this.#sessionOverride = settings.main.enabled;
+        return this.status();
+    }
+
+    block(reason: string): ForegroundSandboxStatus {
+        this.#policyProblem = reason;
+        return this.status();
+    }
+
+    permissionSettings(): SandboxPermissionSettings | undefined {
+        if (!this.#permissions) return undefined;
+        return parseSandboxPermissions({
+            ...this.#permissions,
+            main: { ...this.#permissions.main, enabled: this.isUserEnabled() },
+        });
+    }
+
     /** The deny-write templates currently in force (packaged defaults for now). */
     denyWriteTemplates(): readonly string[] {
         return this.#denyTemplates;
@@ -185,12 +215,25 @@ export class ForegroundSandboxController {
         const support = describeSandboxSupport(this.#seams);
         const base = {
             projectRoot: this.#projectRoot,
-            denyWrite: this.#denyWrite,
+            denyWrite: this.#permissions
+                ? Object.freeze([...this.#denyWrite, join(getAgentDir(), "extensions")])
+                : this.#denyWrite,
             platform: support.platform,
-            readPolicy: "unrestricted",
-            networkPolicy: "unrestricted",
+            readPolicy: this.isUserEnabled() && this.#permissions && (this.#permissions.main.projectFiles === "off" || this.#permissions.main.outsideProject === "off" || this.#permissions.main.storedCredentials === "off") ? "restricted" as const : "unrestricted" as const,
+            networkPolicy: this.isUserEnabled() && this.#permissions?.main.network === false ? "blocked" as const : "unrestricted" as const,
+            ...(this.#permissions ? {
+                permissions: Object.freeze({ ...this.#permissions.main, enabled: this.isUserEnabled() }),
+                subagentPermissions: Object.freeze({ ...this.#permissions.subagents }),
+            } : {}),
         } as const;
 
+        if (this.#policyProblem !== undefined) {
+            return Object.freeze({ ...base, state: "failed", writableRoot: undefined,
+                backend: support.supported ? support.backend : undefined,
+                executable: support.supported ? support.executable : undefined,
+                reason: this.#policyProblem });
+        }
+
         if (this.#projectRoot === undefined) {
             return Object.freeze({
                 ...base,
@@ -246,7 +289,9 @@ export class ForegroundSandboxController {
             writableRoot: this.#projectRoot,
             backend: support.backend,
             executable: support.executable,
-            reason: `Writes are confined to ${this.#projectRoot} by ${support.backend} (${support.executable}).`,
+            reason: this.#permissions
+                ? `Sandbox permissions are enforced by ${support.backend} (${support.executable}) for ${this.#projectRoot}.`
+                : `Writes are confined to ${this.#projectRoot} by ${support.backend} (${support.executable}).`,
         });
     }
 
@@ -274,6 +319,7 @@ export class ForegroundSandboxController {
             writableRoot: status.writableRoot,
             denyWrite: Object.freeze([...status.denyWrite, profileDir]),
             home: (this.#seams.home ?? homedir)(),
+            ...(status.permissions ? { permissions: status.permissions } : {}),
         };
         return { confined: true, policy, profilePath: this.#profilePathFor(policy) };
     }
@@ -296,7 +342,7 @@ export class ForegroundSandboxController {
      */
     #profilePathFor(policy: SandboxWritePolicy): string {
         const digest = createHash("sha256")
-            .update(JSON.stringify([policy.writableRoot, policy.denyWrite, policy.home]))
+            .update(JSON.stringify(policy))
             .digest("hex")
             .slice(0, 16);
         return join(this.#profileDirectory(), `foreground-${digest}.sb`);

package/status.ts

@@ -57,7 +57,7 @@ export function formatSandboxReport(status: ForegroundSandboxStatus): string {
         "",
         `Project root:  ${status.projectRoot ?? "(not captured yet)"}`,
         `Writable root: ${status.writableRoot ?? "(none while not enabled)"}`,
-        `Reads:         ${status.readPolicy} (every filesystem path)`,
+        `Reads:         ${status.readPolicy}${status.readPolicy === "unrestricted" ? " (every filesystem path)" : " (selected file permissions)"}`,
         `Network:       ${status.networkPolicy}`,
         `Platform:      ${status.platform}`,
         `Backend:       ${status.backend ?? "(none resolved)"}`,