@erichll/pi-sandbox 0.3.0 → 0.3.1

package/README.md

@@ -62,6 +62,30 @@ Supported modes:
 The configuration parser rejects malformed JSON, unknown fields, and unknown
 providers instead of silently weakening isolation.
 
+## Additional trusted read paths
+
+The trusted global configuration may append absolute paths to the sandbox's
+default read allowlist. This is useful for executables installed below the
+otherwise-denied home directory:
+
+```json
+{
+  "subagents": {
+    "provider": "builtin"
+  },
+  "filesystem": {
+    "additionalAllowRead": [
+      "/home/user/.local/bin/rtk"
+    ]
+  }
+}
+```
+
+`filesystem.additionalAllowRead` must be an array of absolute paths. These
+paths extend the defaults; they do not replace the workspace, Node.js, or
+Sandbox Runtime read permissions. Keep entries as narrow as possible and
+prefer an exact executable path over allowing an entire bin directory.
+
 Persistent built-in sessions support `start`, `follow_up`, `wait`, `status`,
 `stop`, and nested `handoff` operations. At most four sessions are live at
 once, and nesting depth is capped at three.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erichll/pi-sandbox",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Sandbox Runtime-backed Linux and macOS sandbox with pi-auto-review approval",
   "type": "module",
   "license": "Apache-2.0",

package/src/config.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
 
 export const SUBAGENT_PROVIDERS = [
   "builtin",
@@ -14,6 +14,9 @@ export type PiSandboxConfig = {
   subagents: {
     provider: SubagentProvider;
   };
+  filesystem: {
+    additionalAllowRead: readonly string[];
+  };
 };
 
 export type LoadPiSandboxConfigOptions = {
@@ -25,6 +28,9 @@ export const DEFAULT_PI_SANDBOX_CONFIG: Readonly<PiSandboxConfig> = Object.freez
     subagents: Object.freeze({
       provider: "builtin",
     }),
+    filesystem: Object.freeze({
+      additionalAllowRead: Object.freeze([]),
+    }),
   },
 );
 
@@ -53,22 +59,18 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
   if (!isRecord(value)) {
     throw new Error("invalid pi-sandbox configuration: root must be an object");
   }
-  rejectUnknownKeys(value, ["subagents"], "root");
+  rejectUnknownKeys(value, ["subagents", "filesystem"], "root");
 
-  if (value.subagents === undefined) {
-    return {
-      subagents: { provider: DEFAULT_PI_SANDBOX_CONFIG.subagents.provider },
-    };
-  }
-  if (!isRecord(value.subagents)) {
+  if (value.subagents !== undefined && !isRecord(value.subagents)) {
     throw new Error(
       "invalid pi-sandbox configuration: subagents must be an object",
     );
   }
-  rejectUnknownKeys(value.subagents, ["provider"], "subagents");
+  const subagents = value.subagents ?? {};
+  rejectUnknownKeys(subagents, ["provider"], "subagents");
 
   const provider =
-    value.subagents.provider ?? DEFAULT_PI_SANDBOX_CONFIG.subagents.provider;
+    subagents.provider ?? DEFAULT_PI_SANDBOX_CONFIG.subagents.provider;
   if (
     typeof provider !== "string" ||
     !SUBAGENT_PROVIDERS.includes(provider as SubagentProvider)
@@ -78,10 +80,41 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
     );
   }
 
+  if (value.filesystem !== undefined && !isRecord(value.filesystem)) {
+    throw new Error(
+      "invalid pi-sandbox configuration: filesystem must be an object",
+    );
+  }
+  const filesystem = value.filesystem ?? {};
+  rejectUnknownKeys(
+    filesystem,
+    ["additionalAllowRead"],
+    "filesystem",
+  );
+  const additionalAllowRead =
+    filesystem.additionalAllowRead ??
+    DEFAULT_PI_SANDBOX_CONFIG.filesystem.additionalAllowRead;
+  if (
+    !Array.isArray(additionalAllowRead) ||
+    additionalAllowRead.some(
+      (path) =>
+        typeof path !== "string" ||
+        path.trim() === "" ||
+        !isAbsolute(path),
+    )
+  ) {
+    throw new Error(
+      "invalid pi-sandbox configuration: filesystem.additionalAllowRead must be an array of absolute paths",
+    );
+  }
+
   return {
     subagents: {
       provider: provider as SubagentProvider,
     },
+    filesystem: {
+      additionalAllowRead: [...new Set(additionalAllowRead)],
+    },
   };
 }
 
@@ -101,6 +134,11 @@ export function loadPiSandboxConfig(
     ) {
       return {
         subagents: { provider: DEFAULT_PI_SANDBOX_CONFIG.subagents.provider },
+        filesystem: {
+          additionalAllowRead: [
+            ...DEFAULT_PI_SANDBOX_CONFIG.filesystem.additionalAllowRead,
+          ],
+        },
       };
     }
     throw new Error(`failed to read pi-sandbox configuration at ${path}`, {

package/src/index.ts

@@ -21,6 +21,7 @@ import {
   runSandboxedCommand,
   type SandboxCommandOptions,
 } from "./runner.ts";
+import { createDefaultPolicy } from "./policy.ts";
 import type {
   ProcessBackedSubagentManager,
   ProcessBackedSubagentSession,
@@ -100,6 +101,7 @@ function humanApproval(ctx: ExtensionContext): HumanApproval {
 function sandboxOperations(
   ctx: ExtensionContext,
   turnIndex: () => number,
+  additionalAllowRead: readonly string[],
   sandbox?: PiSandboxExtensionOptions["sandbox"],
 ): BashOperations {
   return {
@@ -114,6 +116,7 @@ function sandboxOperations(
         ...sandbox,
         onData: options.onData,
         shellPath: SettingsManager.create(cwd).getShellPath(),
+        policy: createDefaultPolicy(cwd, { additionalAllowRead }),
         review: async (trap) => {
           const result = await approveSandboxTrap(trap, {
             broker: getBoundaryBroker(),
@@ -156,8 +159,10 @@ async function performRegistration(
   options: PiSandboxExtensionOptions,
 ): Promise<void> {
   let currentTurn = 0;
+  const config = loadPiSandboxConfig();
   const subagentProvider =
-    options.subagentProvider ?? loadPiSandboxConfig().subagents.provider;
+    options.subagentProvider ?? config.subagents.provider;
+  const additionalAllowRead = config.filesystem.additionalAllowRead;
   const subagents =
     subagentProvider === "builtin"
       ? (options.subagentManager ??
@@ -176,7 +181,12 @@ async function performRegistration(
     async execute(id, params, signal, onUpdate, ctx) {
       if (!ctx) throw new Error(`${EXTENSION_NAME}: missing extension context`);
       const tool = createBashToolDefinition(ctx.cwd, {
-        operations: sandboxOperations(ctx, () => currentTurn, options.sandbox),
+        operations: sandboxOperations(
+          ctx,
+          () => currentTurn,
+          additionalAllowRead,
+          options.sandbox,
+        ),
       });
       return tool.execute(id, params, signal, onUpdate, ctx);
     },
@@ -262,6 +272,7 @@ async function performRegistration(
           cwd: ctx.cwd,
           model: params.model,
           tools: pi.getActiveTools().filter((name) => name !== "subagent"),
+          policy: createDefaultPolicy(ctx.cwd, { additionalAllowRead }),
           sandbox: options.sandbox,
           review: async (trap: Parameters<typeof approveSandboxTrap>[0]) =>
             (await approveSandboxTrap(trap, approvalContext)).action,
@@ -408,7 +419,12 @@ async function performRegistration(
     });
 
   pi.on("user_bash", (_event, ctx) => ({
-    operations: sandboxOperations(ctx, () => currentTurn, options.sandbox),
+    operations: sandboxOperations(
+      ctx,
+      () => currentTurn,
+      additionalAllowRead,
+      options.sandbox,
+    ),
   }));
 
   pi.on("turn_start", (event) => {

package/src/policy.ts

@@ -35,7 +35,14 @@ export type SandboxPolicy = {
   };
 };
 
-export function createDefaultPolicy(cwd: string): SandboxPolicy {
+export type CreateDefaultPolicyOptions = {
+  additionalAllowRead?: readonly string[];
+};
+
+export function createDefaultPolicy(
+  cwd: string,
+  options: CreateDefaultPolicyOptions = {},
+): SandboxPolicy {
   const workspace = resolve(cwd);
   const home = resolve(homedir());
   const denyRead = home === parse(home).root ? [] : [home];
@@ -53,6 +60,7 @@ export function createDefaultPolicy(cwd: string): SandboxPolicy {
         join(home, ".gitconfig"),
         join(home, ".config", "git", "config"),
         "/dev/null",
+        ...(options.additionalAllowRead ?? []),
       ],
       allowWrite: [workspace, "/dev/null"],
       denyWrite: [