pi-better-sandbox 0.3.0 → 0.5.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,59 +9,79 @@ 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.
 
-```
-Read:       every filesystem path
-Write:      the canonical launch directory and everything under it
-Exceptions: .git/hooks, .env, .env.local
-Network:    unchanged
-```
-
-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`).
-A crafted command cannot talk its way past it, because the write syscall itself
-is refused.
-
-`write` and `edit` never start a child process — they change files inside Pi's
-own process — so there is no child to wrap. They are confined by a containment
-check on the canonical target instead, run inside Pi's own file-mutation queue,
-immediately before the filesystem call it guards. A refused mutation leaves
-nothing behind on disk.
-
-## What is confined, and what is not
+```text
+Sandbox permissions               Main             Subagents
 
-**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.
+Sandbox                           Off              On
 
-Writes are confined for the integrated first-party execution paths, and only
-those:
+Project files                     -                Read / write
+Outside project                   -                Read
+Stored credentials                -                Read
+Run commands & applications       -                On
+Network access                    -                On
 
-- Pi's built-in `bash` tool.
-- User-entered `!` and `!!` commands.
-- Pi's built-in `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)
-  children, through the same shared mechanism.
+↑↓ Select row   ←→ Select column   Space Change
+Save as defaults
+```
 
-**Not** confined:
+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.
+
+File and shell operations use the kernel: macOS uses Seatbelt (`sandbox-exec`)
+and Linux uses Bubblewrap (`bwrap`). `read`, `write`, and `edit` keep Pi's normal
+tool behavior and mutation queues, while a fixed worker performs filesystem
+syscalls under the selected policy. Canonical checks explain denials; kernel
+enforcement also protects against a symlink changing between checking and use.
+The confined file worker rejects files over 8 MiB instead of silently truncating
+them; larger-file processing can use a confined command when commands are On.
 
-- Pi's own process.
-- `pi.exec` calls made by extensions.
-- Unrelated third-party extension code.
-- 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.
+## What is confined, and what is not
 
-This is a tool-execution sandbox. It limits accidental damage from commands the
-model or you run through Pi's shell; it is not a boundary around Pi itself.
+Pi is the trusted runtime. It can lock configuration/authentication files,
+connect to its provider, and persist sessions. Main and Subagents permissions
+apply to task operations. Subagents can start with task Network access or Run
+commands & applications Off. The fixed file worker remains available according
+to the file permissions even when task commands are Off.
+
+The task executor provides a private scratch directory through `TMPDIR`, `TMP`,
+and `TEMP`. Only that directory is writable in addition to the selected project
+and explicit file grants; a protected anchor prevents replacing its root with a
+symlink. It is separate from Pi's runtime control files.
+
+The currently admitted model-tool implementations are `read`, `write`, `edit`,
+and `bash`. User-entered `!` and `!!` commands use the same shell policy. Other
+model-callable tools require a verified execution adapter and are refused while
+that actor's sandbox is enabled; enabling network alone does not admit them.
+Subagent launch output identifies requested tools that are unavailable. Main
+remains Off by default, so its ordinary orchestration tools remain available
+unless the user enables Main confinement.
+
+Pi and installed runtime extensions remain trusted code, including their
+initialization, provider hooks, and internal `pi.exec` calls. The tool gate is
+not a sandbox around malicious runtime extensions. Loaded runtime code,
+configuration, and policy/control files are protected from task writes, even
+under broader file grants. Task access to `~/.pi` does not receive a blanket
+write allowance or lock-file exception.
+
+Local confinement cannot govern a remote host's filesystem. Dedicated SSH,
+MCP, scripting, background, and nested-agent tools currently lack admission
+adapters and fail closed under an enabled actor profile. SSH through confined
+`bash` receives local file, credential, and network restrictions; remote effects
+remain outside the local filesystem policy.
 
 Overriding `write` and `edit` changes nothing you can see: the parameter
 schemas, prompt guidance, call rendering, write previews, edit diffs, result
@@ -71,7 +91,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 +184,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 +220,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

@@ -27,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:",
@@ -80,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. */
@@ -88,6 +89,7 @@ export function createSandboxCommandHandler({
     denyRules,
     onStateChange,
     setDefault,
+    openPermissions,
 }: SandboxCommandDeps) {
     return async function handleSandboxCommand(
         args: string,
@@ -101,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;
         }

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,19 +5,17 @@
  * 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.
+ * File-tool syscalls and shell commands run under the same kernel policy.
  *
  * 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 { dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import {
-    createBashToolDefinition,
-    createEditToolDefinition,
-    createWriteToolDefinition,
     SettingsManager,
     type ExtensionAPI,
     type ExtensionContext,
@@ -34,12 +32,12 @@ import {
     FOREGROUND_SANDBOX_POLICY_REQUEST_CHANNEL,
     publishForegroundSandboxPolicy,
 } from "./events.ts";
-import {
-    createSandboxedEditOperations,
-    createSandboxedWriteOperations,
-} from "./files.ts";
-import { readSandboxDefault, writeSandboxDefault } from "./preferences.ts";
-import { createSandboxedBashOperations } from "./shell.ts";
+import { installTaskTools, runtimeCodeRoot } from "./shared-task-sandbox.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 { footerTone, formatFooterStatus } from "./status.ts";
 import { ForegroundSandboxController, type ForegroundSandboxStatus } from "./state.ts";
 
@@ -51,37 +49,36 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
     // Pi's shell setting is only readable once a session directory is known, so
     // it is resolved lazily and re-read on every session start.
     let shellPath: string | undefined;
-    const operations = createSandboxedBashOperations(controller, { shellPath: () => shellPath });
-
-    // Overriding the built-in bash tool by name. Only `operations` changes:
-    // Pi's own definition still owns the schema, streaming, timeout,
-    // cancellation, truncation, session environment, result details, and both
-    // renderers, so every bash contract stays the built-in one.
-    pi.registerTool(createBashToolDefinition(process.cwd(), { operations }));
-
-    // The same backend for user-entered ! and !! commands.
-    pi.on("user_bash", () => ({ operations }));
-
-    // Overriding the built-in write and edit tools the same way: only their
-    // file operations change, so Pi's own definitions keep the parameter
-    // schemas, prompt guidance, call rendering, write previews, edit diffs,
-    // result details, file-mutation queue, and cancellation checks. The guarded
-    // operations run inside that queue, which is where the enforcement belongs.
-    const writeOperations = createSandboxedWriteOperations(controller);
-    const editOperations = createSandboxedEditOperations(controller);
+    const ownEntry = fileURLToPath(import.meta.url);
+    const boundary = installTaskTools(pi, { controller, cwd: process.cwd(), shellPath: () => shellPath,
+        trustedSources: [ownEntry,
+            join(dirname(ownEntry), "../../extensions/sandbox/index.ts"),
+            join(dirname(ownEntry), "../pi-better-harness/extensions/sandbox/index.ts")],
+    });
 
-    // `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
-    // a session reports a different cwd (`pi --cwd ...`), which Pi supports and
-    // refreshes in the same session.
-    let fileToolCwd: string | undefined;
-    const registerFileTools = (cwd: string): void => {
-        if (fileToolCwd === cwd) return;
-        fileToolCwd = cwd;
-        pi.registerTool(createWriteToolDefinition(cwd, { operations: writeOperations }));
-        pi.registerTool(createEditToolDefinition(cwd, { operations: editOperations }));
-    };
-    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;
 
@@ -102,7 +99,7 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
 
     pi.on("session_start", (_event, ctx: ExtensionContext) => {
         shellPath = resolveShellPath(ctx.cwd);
-        registerFileTools(ctx.cwd);
+        boundary.register(ctx.cwd);
         paintFooter = (status) => {
             ctx.ui.setStatus(
                 FOOTER_KEY,
@@ -110,19 +107,28 @@ 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.protectRuntimePaths((pi.getAllTools?.() ?? [])
+            .map((tool) => tool.sourceInfo?.path).filter((path): path is string => typeof path === "string" && isAbsolute(path))
+            .map(runtimeCodeRoot));
+        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 +166,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.3.0",
-  "description": "Pi extension that confines foreground shell execution to the project directory with a kernel-enforced write sandbox.",
+  "version": "0.5.0",
+  "description": "Pi extension with independent Main and Subagents permission profiles, file guards, and OS sandbox enforcement.",
   "license": "MIT",
   "type": "module",
   "main": "index.ts",
@@ -31,9 +31,9 @@
     "access": "public"
   },
   "scripts": {
-    "pretypecheck": "node ../../scripts/sync-shared-sandbox-core.mjs",
-    "pretest": "node ../../scripts/sync-shared-sandbox-core.mjs",
-    "prepack": "node ../../scripts/sync-shared-sandbox-core.mjs",
+    "pretypecheck": "node ../../scripts/sync-shared-sandbox-core.mjs && node ../../scripts/sync-task-sandbox.mjs",
+    "pretest": "node ../../scripts/sync-shared-sandbox-core.mjs && node ../../scripts/sync-task-sandbox.mjs",
+    "prepack": "node ../../scripts/sync-shared-sandbox-core.mjs && node ../../scripts/sync-task-sandbox.mjs",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx --test test/*.test.ts",
     "verify": "npm run typecheck && npm test"
@@ -44,7 +44,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": ">=0.82.1",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },

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 });
+    }
+}