@erichll/pi-sandbox 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.4.0 - 2026-07-29
+
+- Add an optional, approval-gated Host-IPC Bash backend for commands that need
+  access to host Unix sockets.
+- Support trusted preflight command prefixes without treating a prefix as
+  authorization; every complete command still requires an exact one-shot
+  approval.
+- Support one non-recursive host retry after a narrowly detected Unix-socket
+  `Operation not permitted` sandbox failure.
+- Preserve the first attempt's output, apply only the original timeout's
+  remaining duration, and never retry successful, timed-out, or aborted
+  commands.
+- Refuse Host-IPC forwarding for built-in subagents.
+- Add deterministic execution and approval coverage plus a Linux tmux socket
+  smoke test.
+
+## 0.3.1 - 2026-07-29
+
+- Add trusted global filesystem read-path extensions while keeping default
+  write and configuration protections intact.
+
+## 0.3.0 - 2026-07-28
+
+- Initial public release.

package/README.md

@@ -20,6 +20,9 @@ also run complete process-backed subagent trees inside independent sandboxes.
   independent policy, proxy, approval, and cleanup lifecycles.
 - Project and global Pi security configuration, the installed package, Git
   hooks, and other Sandbox Runtime mandatory paths remain write-protected.
+- Optional host IPC execution is disabled by default. When enabled, every
+  complete host command still requires a one-shot `pi-auto-review` or human
+  approval and runs outside the OS sandbox.
 
 Windows is not supported by this Pi adapter.
 
@@ -62,6 +65,39 @@ Supported modes:
 The configuration parser rejects malformed JSON, unknown fields, and unknown
 providers instead of silently weakening isolation.
 
+## Optional host IPC fallback
+
+Some host services expose only a Unix socket that the OS sandbox cannot use.
+The trusted global configuration can enable an approval-driven local Bash
+backend for those commands:
+
+```json
+{
+  "hostIPC": {
+    "mode": "ask",
+    "preflightCommandPrefixes": ["tmux", "/usr/bin/tmux"],
+    "retryOnUnixSocketError": true
+  }
+}
+```
+
+`mode` is `off` by default and only accepts `off` or `ask`. Prefixes are
+trimmed, deduplicated, and must be non-empty. A prefix matches only at the
+start of the trimmed command and must end at whitespace or the end of the
+command. Prefixes select commands for review; they never authorize execution.
+The reviewer and one-shot grant are bound to the full command and working
+directory.
+
+With `retryOnUnixSocketError` enabled, commands not selected for preflight
+still run in Sandbox Runtime first. A single host retry is considered only
+after a nonzero exit whose stderr identifies both `Operation not permitted`
+and a socket/connect/IPC operation. The original output is retained, and the
+approval warns that the first attempt may already have had partial side
+effects. Successful, timed-out, or aborted commands are never retried.
+
+Host forwarding is intentionally unavailable inside built-in subagents in
+this version.
+
 ## Additional trusted read paths
 
 The trusted global configuration may append absolute paths to the sandbox's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erichll/pi-sandbox",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Sandbox Runtime-backed Linux and macOS sandbox with pi-auto-review approval",
   "type": "module",
   "license": "Apache-2.0",
@@ -29,6 +29,7 @@
   },
   "files": [
     "src",
+    "CHANGELOG.md",
     "README.md",
     "NOTICE"
   ],
@@ -50,7 +51,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.67",
-    "@erichll/pi-auto-review": "0.3.0"
+    "@erichll/pi-auto-review": "0.3.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.82.1",

package/src/approval.ts

@@ -4,6 +4,7 @@ import type {
 } from "@erichll/pi-auto-review/broker";
 import { sandboxTrapToBoundaryRequest } from "@erichll/pi-auto-review/sandbox";
 import type { SandboxApprovalTrap } from "./traps.ts";
+import type { HostIPCTrigger } from "./host-ipc.ts";
 import { randomUUID } from "node:crypto";
 export type NetworkEndpoint = {
   hostname: string;
@@ -56,6 +57,33 @@ export async function approveDomainEndpoint(
   return approveBoundaryRequest(request, context);
 }
 
+export async function approveHostIPCExecution(
+  trigger: HostIPCTrigger,
+  context: TrapApprovalContext,
+): Promise<TrapApprovalResult> {
+  const request: BoundaryRequest = {
+    id: `sandbox-runtime-host-ipc-${randomUUID()}`,
+    source: "sandbox-runtime",
+    surface: "host-ipc",
+    operation: "execute-host",
+    cwd: context.cwd,
+    command: context.command,
+    matchedPolicy: {
+      decision: "ask",
+      rule:
+        trigger.reason === "preflight-prefix"
+          ? `preflight-prefix:${trigger.rule}`
+          : "unix-socket-eperm",
+    },
+    toolInputPreview:
+      trigger.reason === "unix-socket-eperm"
+        ? "The sandboxed attempt failed and may already have had partial side effects."
+        : "A configured prefix requested approval before sandbox execution.",
+    agentName: context.agentName,
+  };
+  return approveBoundaryRequest(request, context);
+}
+
 async function askHuman(
   request: BoundaryRequest,
   context: TrapApprovalContext,

package/src/config.ts

@@ -10,6 +10,15 @@ export const SUBAGENT_PROVIDERS = [
 
 export type SubagentProvider = (typeof SUBAGENT_PROVIDERS)[number];
 
+export const HOST_IPC_MODES = ["off", "ask"] as const;
+export type HostIPCMode = (typeof HOST_IPC_MODES)[number];
+
+export type HostIPCConfig = {
+  mode: HostIPCMode;
+  preflightCommandPrefixes: readonly string[];
+  retryOnUnixSocketError: boolean;
+};
+
 export type PiSandboxConfig = {
   subagents: {
     provider: SubagentProvider;
@@ -17,6 +26,7 @@ export type PiSandboxConfig = {
   filesystem: {
     additionalAllowRead: readonly string[];
   };
+  hostIPC: HostIPCConfig;
 };
 
 export type LoadPiSandboxConfigOptions = {
@@ -31,6 +41,11 @@ export const DEFAULT_PI_SANDBOX_CONFIG: Readonly<PiSandboxConfig> = Object.freez
     filesystem: Object.freeze({
       additionalAllowRead: Object.freeze([]),
     }),
+    hostIPC: Object.freeze({
+      mode: "off",
+      preflightCommandPrefixes: Object.freeze([]),
+      retryOnUnixSocketError: false,
+    }),
   },
 );
 
@@ -59,7 +74,7 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
   if (!isRecord(value)) {
     throw new Error("invalid pi-sandbox configuration: root must be an object");
   }
-  rejectUnknownKeys(value, ["subagents", "filesystem"], "root");
+  rejectUnknownKeys(value, ["subagents", "filesystem", "hostIPC"], "root");
 
   if (value.subagents !== undefined && !isRecord(value.subagents)) {
     throw new Error(
@@ -108,6 +123,48 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
     );
   }
 
+  if (value.hostIPC !== undefined && !isRecord(value.hostIPC)) {
+    throw new Error(
+      "invalid pi-sandbox configuration: hostIPC must be an object",
+    );
+  }
+  const hostIPC = value.hostIPC ?? {};
+  rejectUnknownKeys(
+    hostIPC,
+    ["mode", "preflightCommandPrefixes", "retryOnUnixSocketError"],
+    "hostIPC",
+  );
+  const hostIPCMode = hostIPC.mode ?? DEFAULT_PI_SANDBOX_CONFIG.hostIPC.mode;
+  if (
+    typeof hostIPCMode !== "string" ||
+    !HOST_IPC_MODES.includes(hostIPCMode as HostIPCMode)
+  ) {
+    throw new Error(
+      `invalid pi-sandbox configuration: hostIPC.mode must be one of ${HOST_IPC_MODES.join(", ")}`,
+    );
+  }
+  const preflightCommandPrefixes =
+    hostIPC.preflightCommandPrefixes ??
+    DEFAULT_PI_SANDBOX_CONFIG.hostIPC.preflightCommandPrefixes;
+  if (
+    !Array.isArray(preflightCommandPrefixes) ||
+    preflightCommandPrefixes.some(
+      (prefix) => typeof prefix !== "string" || prefix.trim() === "",
+    )
+  ) {
+    throw new Error(
+      "invalid pi-sandbox configuration: hostIPC.preflightCommandPrefixes must be an array of non-empty strings",
+    );
+  }
+  const retryOnUnixSocketError =
+    hostIPC.retryOnUnixSocketError ??
+    DEFAULT_PI_SANDBOX_CONFIG.hostIPC.retryOnUnixSocketError;
+  if (typeof retryOnUnixSocketError !== "boolean") {
+    throw new Error(
+      "invalid pi-sandbox configuration: hostIPC.retryOnUnixSocketError must be a boolean",
+    );
+  }
+
   return {
     subagents: {
       provider: provider as SubagentProvider,
@@ -115,6 +172,13 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
     filesystem: {
       additionalAllowRead: [...new Set(additionalAllowRead)],
     },
+    hostIPC: {
+      mode: hostIPCMode as HostIPCMode,
+      preflightCommandPrefixes: [
+        ...new Set(preflightCommandPrefixes.map((prefix) => prefix.trim())),
+      ],
+      retryOnUnixSocketError,
+    },
   };
 }
 
@@ -139,6 +203,14 @@ export function loadPiSandboxConfig(
             ...DEFAULT_PI_SANDBOX_CONFIG.filesystem.additionalAllowRead,
           ],
         },
+        hostIPC: {
+          mode: DEFAULT_PI_SANDBOX_CONFIG.hostIPC.mode,
+          preflightCommandPrefixes: [
+            ...DEFAULT_PI_SANDBOX_CONFIG.hostIPC.preflightCommandPrefixes,
+          ],
+          retryOnUnixSocketError:
+            DEFAULT_PI_SANDBOX_CONFIG.hostIPC.retryOnUnixSocketError,
+        },
       };
     }
     throw new Error(`failed to read pi-sandbox configuration at ${path}`, {

package/src/host-ipc.ts

@@ -0,0 +1,160 @@
+import type { HostIPCConfig } from "./config.ts";
+import type { TrapApprovalResult } from "./approval.ts";
+
+const MAX_STDERR_BYTES = 64 * 1024;
+const SUBAGENT_DEPTH_ENV = "PI_SANDBOX_SUBAGENT_DEPTH";
+
+export type HostIPCTrigger =
+  | {
+      reason: "preflight-prefix";
+      rule: string;
+    }
+  | {
+      reason: "unix-socket-eperm";
+      rule: "unix-socket-eperm";
+    };
+
+type CommandResult = { exitCode: number | null };
+
+export type HostIPCCommandOptions = {
+  command: string;
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+  signal?: AbortSignal;
+  timeout?: number;
+  onData(data: Buffer): void;
+  config: HostIPCConfig;
+  approve(trigger: HostIPCTrigger): Promise<TrapApprovalResult>;
+  runSandbox(onStderr: (data: Buffer) => void): Promise<CommandResult>;
+  runHost(timeout: number | undefined): Promise<CommandResult>;
+  now?: () => number;
+};
+
+export function matchingPreflightPrefix(
+  command: string,
+  prefixes: readonly string[],
+): string | undefined {
+  const trimmed = command.trim();
+  return prefixes.find(
+    (prefix) =>
+      trimmed.startsWith(prefix) &&
+      (trimmed.length === prefix.length ||
+        /\s/.test(trimmed.charAt(prefix.length))),
+  );
+}
+
+export function isUnixSocketPermissionError(stderr: Buffer | string): boolean {
+  const text = typeof stderr === "string" ? stderr : stderr.toString("utf8");
+  return (
+    /operation not permitted/i.test(text) &&
+    /socket|connect(?:ing)?|ipc/i.test(text)
+  );
+}
+
+function appendBounded(current: Buffer, chunk: Buffer): Buffer {
+  if (chunk.length >= MAX_STDERR_BYTES) {
+    return chunk.subarray(chunk.length - MAX_STDERR_BYTES);
+  }
+  const combined = Buffer.concat([current, chunk]);
+  return combined.length <= MAX_STDERR_BYTES
+    ? combined
+    : combined.subarray(combined.length - MAX_STDERR_BYTES);
+}
+
+function isBuiltinSubagent(env: NodeJS.ProcessEnv | undefined): boolean {
+  return Number(env?.[SUBAGENT_DEPTH_ENV] ?? process.env[SUBAGENT_DEPTH_ENV]) > 0;
+}
+
+function remainingTimeout(
+  timeout: number | undefined,
+  startedAt: number,
+  now: () => number,
+): number | undefined {
+  if (timeout === undefined) return undefined;
+  const remaining = timeout - (now() - startedAt) / 1_000;
+  if (remaining <= 0) throw new Error(`timeout:${timeout}`);
+  return remaining;
+}
+
+function refusal(options: HostIPCCommandOptions, reason?: string): CommandResult {
+  options.onData(
+    Buffer.from(
+      `pi-sandbox: host-IPC execution denied${reason ? `: ${reason}` : ""}\n`,
+      "utf8",
+    ),
+  );
+  return { exitCode: 1 };
+}
+
+export async function runCommandWithHostIPC(
+  options: HostIPCCommandOptions,
+): Promise<CommandResult> {
+  const now = options.now ?? Date.now;
+  const startedAt = now();
+  const enabled = options.config.mode === "ask";
+  const prefix = enabled
+    ? matchingPreflightPrefix(
+        options.command,
+        options.config.preflightCommandPrefixes,
+      )
+    : undefined;
+
+  if (prefix !== undefined) {
+    if (isBuiltinSubagent(options.env)) {
+      return refusal(
+        options,
+        "builtin subagents do not support host forwarding",
+      );
+    }
+    const approval = await options.approve({
+      reason: "preflight-prefix",
+      rule: prefix,
+    });
+    if (approval.action === "deny") {
+      return refusal(options, approval.reason);
+    }
+    return options.runHost(
+      remainingTimeout(options.timeout, startedAt, now),
+    );
+  }
+
+  let stderr: Buffer<ArrayBufferLike> = Buffer.alloc(0);
+  const sandboxResult = await options.runSandbox((data) => {
+    stderr = appendBounded(stderr, data);
+  });
+  if (
+    !enabled ||
+    !options.config.retryOnUnixSocketError ||
+    sandboxResult.exitCode === 0 ||
+    sandboxResult.exitCode === null ||
+    options.signal?.aborted ||
+    !isUnixSocketPermissionError(stderr)
+  ) {
+    return sandboxResult;
+  }
+  if (isBuiltinSubagent(options.env)) {
+    options.onData(
+      Buffer.from(
+        "pi-sandbox: host-IPC retry refused: builtin subagents do not support host forwarding\n",
+        "utf8",
+      ),
+    );
+    return sandboxResult;
+  }
+
+  const approval = await options.approve({
+    reason: "unix-socket-eperm",
+    rule: "unix-socket-eperm",
+  });
+  if (approval.action === "deny") return sandboxResult;
+
+  options.onData(
+    Buffer.from(
+      "\n--- pi-sandbox: approved host-IPC retry (outside OS sandbox) ---\n",
+      "utf8",
+    ),
+  );
+  return options.runHost(
+    remainingTimeout(options.timeout, startedAt, now),
+  );
+}

package/src/index.ts

@@ -5,18 +5,22 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import {
   createBashToolDefinition,
+  createLocalBashOperations,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import { getBoundaryBroker } from "@erichll/pi-auto-review/broker";
 import {
   approveDomainEndpoint,
+  approveHostIPCExecution,
   approveSandboxTrap,
   type HumanApproval,
 } from "./approval.ts";
 import {
   loadPiSandboxConfig,
+  type HostIPCConfig,
   type SubagentProvider,
 } from "./config.ts";
+import { runCommandWithHostIPC } from "./host-ipc.ts";
 import {
   runSandboxedCommand,
   type SandboxCommandOptions,
@@ -36,6 +40,8 @@ export type PiSandboxExtensionOptions = {
   subagentManager?: ProcessBackedSubagentManager;
   createSubagentManager?: () => ProcessBackedSubagentManager;
   sandbox?: Pick<SandboxCommandOptions, "broker" | "platform">;
+  /** Test/embedding override. Normal extension loading uses trusted global config. */
+  hostIPC?: HostIPCConfig;
 };
 
 function sessionId(ctx: ExtensionContext): string {
@@ -82,13 +88,21 @@ function humanApproval(ctx: ExtensionContext): HumanApproval {
   return async (request, reason, signal) => {
     if (!ctx.hasUI) return "deny";
     const target =
-      request.resolvedPath ??
-      request.path ??
-      request.destination ??
-      request.operation;
+      request.surface === "host-ipc"
+        ? request.command ?? request.operation
+        : request.resolvedPath ??
+          request.path ??
+          request.destination ??
+          request.operation;
     const suffix = reason ? `\n${reason}` : "";
+    const hostWarning =
+      request.surface === "host-ipc"
+        ? request.matchedPolicy?.rule === "unix-socket-eperm"
+          ? "\nWarning: the first sandboxed attempt may already have had partial side effects. The retry runs on the host outside the OS sandbox."
+          : "\nWarning: this command will run on the host outside the OS sandbox."
+        : "";
     const selected = await ctx.ui.select(
-      `Sandbox approval required: ${request.operation} ${target}${suffix}`,
+      `Sandbox approval required: ${request.operation} ${target}${hostWarning}${suffix}`,
       ["Allow this exact operation once", "Deny"],
       { signal },
     );
@@ -102,53 +116,81 @@ function sandboxOperations(
   ctx: ExtensionContext,
   turnIndex: () => number,
   additionalAllowRead: readonly string[],
+  hostIPC: HostIPCConfig,
   sandbox?: PiSandboxExtensionOptions["sandbox"],
 ): BashOperations {
   return {
     exec(command, cwd, options) {
       const currentSessionId = sessionId(ctx);
-      return runSandboxedCommand({
+      const shellPath = SettingsManager.create(cwd).getShellPath();
+      const approvalContext = {
+        broker: getBoundaryBroker(),
+        command,
+        cwd,
+        sessionId: currentSessionId,
+        scopeKey: `${currentSessionId}:turn:${turnIndex()}`,
+        signal: options.signal,
+        humanApproval: humanApproval(ctx),
+      };
+      const local = createLocalBashOperations({ shellPath });
+      return runCommandWithHostIPC({
         command,
         cwd,
         env: options.env,
         signal: options.signal,
         timeout: options.timeout,
-        ...sandbox,
         onData: options.onData,
-        shellPath: SettingsManager.create(cwd).getShellPath(),
-        policy: createDefaultPolicy(cwd, { additionalAllowRead }),
-        review: async (trap) => {
-          const result = await approveSandboxTrap(trap, {
-            broker: getBoundaryBroker(),
-            command,
-            cwd,
-            sessionId: currentSessionId,
-            scopeKey: `${currentSessionId}:turn:${turnIndex()}`,
-            signal: options.signal,
-            humanApproval: humanApproval(ctx),
-          });
-          if (result.action === "deny" && result.reason) {
-            if (ctx.hasUI) {
-              ctx.ui.notify(`Sandbox denied: ${result.reason}`, "warning");
-            }
+        config: hostIPC,
+        approve: async (trigger) => {
+          const result = await approveHostIPCExecution(
+            trigger,
+            approvalContext,
+          );
+          if (result.action === "deny" && result.reason && ctx.hasUI) {
+            ctx.ui.notify(`Host-IPC denied: ${result.reason}`, "warning");
           }
-          return result.action;
+          return result;
         },
-        reviewDomain: async (endpoint) => {
-          const result = await approveDomainEndpoint(endpoint, {
-            broker: getBoundaryBroker(),
+        runHost: (timeout) =>
+          local.exec(command, cwd, {
+            ...options,
+            timeout,
+          }),
+        runSandbox: (onStderr) =>
+          runSandboxedCommand({
             command,
             cwd,
-            sessionId: currentSessionId,
-            scopeKey: `${currentSessionId}:turn:${turnIndex()}`,
+            env: options.env,
             signal: options.signal,
-            humanApproval: humanApproval(ctx),
-          });
-          if (result.action === "deny" && result.reason && ctx.hasUI) {
-            ctx.ui.notify(`Domain proxy denied: ${result.reason}`, "warning");
-          }
-          return result.action;
-        },
+            timeout: options.timeout,
+            ...sandbox,
+            onData: options.onData,
+            onStderr,
+            shellPath,
+            policy: createDefaultPolicy(cwd, { additionalAllowRead }),
+            review: async (trap) => {
+              const result = await approveSandboxTrap(trap, approvalContext);
+              if (result.action === "deny" && result.reason) {
+                if (ctx.hasUI) {
+                  ctx.ui.notify(`Sandbox denied: ${result.reason}`, "warning");
+                }
+              }
+              return result.action;
+            },
+            reviewDomain: async (endpoint) => {
+              const result = await approveDomainEndpoint(
+                endpoint,
+                approvalContext,
+              );
+              if (result.action === "deny" && result.reason && ctx.hasUI) {
+                ctx.ui.notify(
+                  `Domain proxy denied: ${result.reason}`,
+                  "warning",
+                );
+              }
+              return result.action;
+            },
+          }),
       });
     },
   };
@@ -163,6 +205,7 @@ async function performRegistration(
   const subagentProvider =
     options.subagentProvider ?? config.subagents.provider;
   const additionalAllowRead = config.filesystem.additionalAllowRead;
+  const hostIPC = options.hostIPC ?? config.hostIPC;
   const subagents =
     subagentProvider === "builtin"
       ? (options.subagentManager ??
@@ -185,6 +228,7 @@ async function performRegistration(
           ctx,
           () => currentTurn,
           additionalAllowRead,
+          hostIPC,
           options.sandbox,
         ),
       });
@@ -423,6 +467,7 @@ async function performRegistration(
       ctx,
       () => currentTurn,
       additionalAllowRead,
+      hostIPC,
       options.sandbox,
     ),
   }));