@erichll/pi-sandbox 0.4.3 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.6.0 - 2026-08-09
+
+- Retarget the development compatibility target from `pi-subagents 0.42.1` to
+  `pi-subagents 0.44.0` and update the coexistence assertions, capability
+  boundary, and compatibility gate. The 0.44.0 line lands internal
+  workflow/mission/schedule fixes that do not change pi-sandbox's contract
+  (tool-ownership detection, `PI_SUBAGENT_PI_BINARY` worker bootstrap).
+- Adapt the compatibility gate's "direct child" probe to the `workflowScript`
+  single-run form: pi-subagents 0.43.0 removed public top-level `agent`/`task`
+  direct execution, so the external provider's direct single-child launch is
+  now `subagent({ workflowScript: "return runs.run('main', { agent, task })" })`.
+  This unblocks the `subagents.externalWorkerIsolation: "enforce"` gate, which
+  previously timed out when the isolated worker could not reconcile the removed
+  direct signature with the newer `workflowScript`-only contract.
+
+## 0.5.0 - 2026-08-08
+
+- Pin the development compatibility target to `pi-subagents 0.42.1` and add
+  coexistence assertions for its package identity and tool ownership.
+- Add `npm run gate:pi-subagents`, an opt-in real-Pi compatibility gate. It
+  uses an isolated agent directory and reports `SKIP` unless a dedicated gate
+  model and credentials are supplied. The gate now waits for returned child
+  results and uses configurable provider-latency timeouts.
+- Add the opt-in `subagents.externalWorkerIsolation: "enforce"` bootstrap for
+  external `pi-subagents` workers. It uses a tarball-shipped launcher and
+  fails closed if its outer Sandbox Runtime broker cannot start, protects
+  first-time security configuration creation, and cleans up only unchanged
+  temporary bind placeholders.
+
 ## 0.4.3 - 2026-08-06
 
 - Move the `pi-auto-review` dependency to `0.3.3`, which allows multi-segment

package/README.md

@@ -59,7 +59,8 @@ new installs.
 ```json
 {
   "subagents": {
-    "provider": "builtin"
+    "provider": "builtin",
+    "externalWorkerIsolation": "off"
   }
 }
 ```
@@ -70,12 +71,59 @@ Supported modes:
   each complete worker process tree.
 - `pi-subagents`: let the external extension own orchestration. Main-agent and
   inherited Bash execution remains sandboxed, but the external worker process
-  itself is not wrapped.
+  itself is not wrapped while `externalWorkerIsolation` is `off`.
 - `off`: protect Bash only.
 
+### `pi-subagents` 0.44.0 capability boundary
+
+`pi-sandbox` verifies the following combination in its test suite and release
+gate:
+
+| Capability | `builtin` | `pi-subagents` 0.44.0 |
+| --- | --- | --- |
+| Outer worker sandbox | Yes | Opt-in (`externalWorkerIsolation: "enforce"`) |
+| Bash sandbox | Yes | Yes |
+| Persistent follow-up | Yes | Yes |
+| `workflowScript`, missions, schedules | No | Yes |
+| permission-system parent forwarding | Not required | Verified by compatibility gate |
+
+For the external provider, `off` leaves the worker process outside the outer
+Sandbox Runtime boundary. Do not treat inherited Bash sandboxing as complete
+worker isolation unless the trusted global configuration explicitly enables
+`enforce`.
+
+Note on the external provider's public execution surface: pi-subagents 0.43.0
+removed top-level `agent`/`task` direct execution. Every public `subagent`
+launch — including a minimal single child — is expressed as a `workflowScript`
+such as `return runs.run('main', { agent, task })`. The compatibility gate's
+"direct single child" probe uses that single-run form.
+
 The configuration parser rejects malformed JSON, unknown fields, and unknown
 providers instead of silently weakening isolation.
 
+To opt in to outer worker isolation for the external provider, use:
+
+```json
+{
+  "subagents": {
+    "provider": "pi-subagents",
+    "externalWorkerIsolation": "enforce"
+  }
+}
+```
+
+`enforce` installs a session-scoped `PI_SUBAGENT_PI_BINARY` wrapper which
+starts the real Pi worker under a dedicated Sandbox Runtime broker. Bootstrap
+failure is terminal for that worker; it never falls back to host execution.
+The wrapper is preserved for nested child launches. This is opt-in while the
+permission-forwarding supervisor and managed-worktree gate continue to mature.
+
+Managed worktrees receive their own writable checkout plus the smallest known
+Git metadata paths as read-only access so `git status` works. The main
+repository `.git` is never made writable by this policy; Git mutation from an
+outer-sandboxed external worker is therefore intentionally unsupported for
+now.
+
 ## Optional host IPC fallback
 
 Some host services expose only a Unix socket that the OS sandbox cannot use.
@@ -157,8 +205,21 @@ From the monorepo root:
 npm install
 npm run check
 npm test
+npm run gate:pi-subagents
 ```
 
+`gate:pi-subagents` is a release/manual integration check, not a default CI
+test. Set `PI_SUBAGENTS_GATE_MODEL` to a configured test model and provide its
+normal Pi credential environment. The command creates a dedicated temporary
+agent directory, never reads or updates your production Pi config, and prints
+`SKIP` when those prerequisites are absent.
+
+It allows 10 minutes for the direct-child phase and 15 minutes for the
+multi-stage workflow, and exits only after the parent reports returned child
+results. Override those bounds with positive millisecond values in
+`PI_SUBAGENTS_GATE_DIRECT_TIMEOUT_MS` and
+`PI_SUBAGENTS_GATE_WORKFLOW_TIMEOUT_MS` when needed for a dedicated provider.
+
 The test suite covers real Linux Sandbox Runtime enforcement when its native
 dependencies are installed, plus deterministic broker, network approval,
 process cleanup, concurrency, and cross-platform orchestration tests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erichll/pi-sandbox",
-  "version": "0.4.3",
+  "version": "0.6.0",
   "description": "Sandbox Runtime-backed Linux and macOS sandbox with pi-auto-review approval",
   "type": "module",
   "license": "Apache-2.0",
@@ -51,7 +51,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.67",
-    "@erichll/pi-auto-review": "0.3.3"
+    "@erichll/pi-auto-review": "0.3.4"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.82.1",
@@ -60,7 +60,7 @@
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.83.0",
     "@types/node": "^22.15.3",
-    "pi-subagents": "0.41.0",
+    "pi-subagents": "0.44.0",
     "typescript": "^6.0.3"
   }
 }

package/src/config.ts

@@ -22,6 +22,7 @@ export type HostIPCConfig = {
 export type PiSandboxConfig = {
   subagents: {
     provider: SubagentProvider;
+    externalWorkerIsolation: "off" | "enforce";
   };
   filesystem: {
     additionalAllowRead: readonly string[];
@@ -39,6 +40,7 @@ export const DEFAULT_PI_SANDBOX_CONFIG: Readonly<PiSandboxConfig> = Object.freez
   {
     subagents: Object.freeze({
       provider: "builtin",
+      externalWorkerIsolation: "off",
     }),
     filesystem: Object.freeze({
       additionalAllowRead: Object.freeze([]),
@@ -96,7 +98,11 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
     );
   }
   const subagents = value.subagents ?? {};
-  rejectUnknownKeys(subagents, ["provider"], "subagents");
+  rejectUnknownKeys(
+    subagents,
+    ["provider", "externalWorkerIsolation"],
+    "subagents",
+  );
 
   const provider =
     subagents.provider ?? DEFAULT_PI_SANDBOX_CONFIG.subagents.provider;
@@ -108,6 +114,17 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
       `invalid pi-sandbox configuration: subagents.provider must be one of ${SUBAGENT_PROVIDERS.join(", ")}`,
     );
   }
+  const externalWorkerIsolation =
+    subagents.externalWorkerIsolation ??
+    DEFAULT_PI_SANDBOX_CONFIG.subagents.externalWorkerIsolation;
+  if (
+    externalWorkerIsolation !== "off" &&
+    externalWorkerIsolation !== "enforce"
+  ) {
+    throw new Error(
+      "invalid pi-sandbox configuration: subagents.externalWorkerIsolation must be off or enforce",
+    );
+  }
 
   if (value.filesystem !== undefined && !isRecord(value.filesystem)) {
     throw new Error(
@@ -182,6 +199,7 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
   return {
     subagents: {
       provider: provider as SubagentProvider,
+      externalWorkerIsolation,
     },
     filesystem: {
       additionalAllowRead: [...new Set(additionalAllowRead)],
@@ -198,7 +216,11 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
 
 function defaultPiSandboxConfig(): PiSandboxConfig {
   return {
-    subagents: { provider: DEFAULT_PI_SANDBOX_CONFIG.subagents.provider },
+    subagents: {
+      provider: DEFAULT_PI_SANDBOX_CONFIG.subagents.provider,
+      externalWorkerIsolation:
+        DEFAULT_PI_SANDBOX_CONFIG.subagents.externalWorkerIsolation,
+    },
     filesystem: {
       additionalAllowRead: [
         ...DEFAULT_PI_SANDBOX_CONFIG.filesystem.additionalAllowRead,

package/src/external-supervisor.ts

@@ -0,0 +1,159 @@
+import { randomBytes } from "node:crypto";
+import { createServer, type Server } from "node:net";
+import { chmod, mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { NetworkEndpoint, TrapApprovalContext } from "./approval.ts";
+import { approveDomainEndpoint } from "./approval.ts";
+
+const MAX_FRAME_BYTES = 16 * 1024;
+const PROTOCOL_VERSION = 1;
+
+type Request = {
+  version?: unknown;
+  capability?: unknown;
+  id?: unknown;
+  type?: unknown;
+  workerId?: unknown;
+  cwd?: unknown;
+  hostname?: unknown;
+  port?: unknown;
+};
+
+export type ExternalWorkerSupervisor = {
+  socketPath: string;
+  capability: string;
+  workers(): ReadonlyArray<{
+    id: string;
+    cwd: string;
+    state: "active" | "exited";
+    startedAt: number;
+    requests: number;
+  }>;
+  close(): Promise<void>;
+};
+
+export async function createExternalWorkerSupervisor(
+  approvalContext: (worker: { id: string; cwd: string }) => TrapApprovalContext,
+): Promise<ExternalWorkerSupervisor> {
+  const directory = await mkdtemp(join(tmpdir(), "pi-sandbox-external-"));
+  await chmod(directory, 0o700);
+  const socketPath = join(directory, "supervisor.sock");
+  const capability = randomBytes(32).toString("hex");
+  const seen = new Set<string>();
+  const workers = new Map<string, {
+    cwd: string;
+    state: "active" | "exited";
+    startedAt: number;
+    requests: number;
+  }>();
+  const server: Server = createServer((socket) => {
+    let buffer = "";
+    socket.setEncoding("utf8");
+    socket.on("data", (chunk: string) => {
+      buffer += chunk;
+      if (Buffer.byteLength(buffer, "utf8") > MAX_FRAME_BYTES) {
+        socket.end('{"action":"deny"}\n');
+        return;
+      }
+      let newline = buffer.indexOf("\n");
+      while (newline >= 0) {
+        const line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        void respond(line);
+        newline = buffer.indexOf("\n");
+      }
+    });
+    const respond = async (line: string): Promise<void> => {
+      let request: Request | undefined;
+      try { request = JSON.parse(line) as Request; } catch { /* denied below */ }
+      if (!request) {
+        socket.write('{"action":"deny"}\n');
+        return;
+      }
+      const baseValid =
+        request.version === PROTOCOL_VERSION &&
+        request.capability === capability &&
+        typeof request.id === "string" && request.id.length > 0 && request.id.length <= 128 &&
+        !seen.has(request.id);
+      if (!baseValid) {
+        socket.write('{"action":"deny"}\n');
+        return;
+      }
+      const registered =
+        request.type === "register" &&
+        typeof request.workerId === "string" && request.workerId.length > 0 && request.workerId.length <= 128 &&
+        typeof request.cwd === "string" && request.cwd.startsWith("/") && request.cwd.length <= 4_096 &&
+        !workers.has(request.workerId);
+      if (registered) {
+        seen.add(request.id as string);
+        workers.set(request.workerId as string, {
+          cwd: request.cwd as string,
+          state: "active",
+          startedAt: Date.now(),
+          requests: 0,
+        });
+        socket.write(`${JSON.stringify({ id: request.id, action: "allow" })}\n`);
+        return;
+      }
+      const knownWorker =
+        typeof request.workerId === "string" && typeof request.cwd === "string"
+          ? workers.get(request.workerId)
+          : undefined;
+      const unregister = request.type === "unregister" &&
+        knownWorker?.state === "active" && knownWorker.cwd === request.cwd;
+      if (unregister) {
+        seen.add(request.id as string);
+        knownWorker.state = "exited";
+        socket.write(`${JSON.stringify({ id: request.id, action: "allow" })}\n`);
+        return;
+      }
+      const workerCwd =
+        knownWorker?.state === "active" ? knownWorker.cwd : undefined;
+      const valid = request.type === "network" &&
+        workerCwd === request.cwd &&
+        typeof request.hostname === "string" && request.hostname.length <= 253 &&
+        Number.isInteger(request.port) && Number(request.port) > 0 && Number(request.port) <= 65535 &&
+        Boolean(workerCwd);
+      if (!valid) {
+        socket.write('{"action":"deny"}\n');
+        return;
+      }
+      const approvedRequest = request as Required<Request>;
+      seen.add(approvedRequest.id as string);
+      knownWorker!.requests++;
+      let action: "allow" | "deny" = "deny";
+      try {
+        const endpoint: NetworkEndpoint = {
+          hostname: approvedRequest.hostname as string,
+          port: approvedRequest.port as number,
+          protocol: "tcp",
+        };
+        action = (await approveDomainEndpoint(endpoint, approvalContext({
+          id: approvedRequest.workerId as string,
+          cwd: workerCwd as string,
+        }))).action;
+      } catch {
+        action = "deny";
+      }
+      socket.write(`${JSON.stringify({ id: approvedRequest.id, action })}\n`);
+    };
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(socketPath, () => resolve());
+  });
+  return {
+    socketPath,
+    capability,
+    workers() {
+      return [...workers.entries()].map(([id, worker]) => ({ id, ...worker }));
+    },
+    async close() {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await rm(directory, { recursive: true, force: true });
+    },
+  };
+}
+
+export const EXTERNAL_SUPERVISOR_PROTOCOL_VERSION = PROTOCOL_VERSION;

package/src/external-worker-launcher.mjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+// Public PI_SUBAGENT_PI_BINARY wrapper. It deliberately has no host fallback:
+// failure to initialize the broker prevents the worker from starting.
+import { fork } from "node:child_process";
+import { createConnection } from "node:net";
+import { randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, parse, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const realPi = process.env.PI_SANDBOX_EXTERNAL_REAL_PI_BINARY;
+const workerId = randomUUID();
+
+function worktreeGitReadPaths(cwd) {
+  const dotGit = join(cwd, ".git");
+  try {
+    const pointer = readFileSync(dotGit, "utf8").match(/^gitdir:\s*(.+)\s*$/m)?.[1];
+    if (!pointer) return [];
+    const gitDir = resolve(cwd, pointer);
+    const paths = [gitDir];
+    try {
+      const common = readFileSync(join(gitDir, "commondir"), "utf8").trim();
+      if (common) paths.push(resolve(gitDir, common));
+    } catch { /* a direct worktree gitdir has no commondir */ }
+    return paths;
+  } catch {
+    return [];
+  }
+}
+
+function supervisorRequest(payload) {
+  const socketPath = process.env.PI_SANDBOX_EXTERNAL_SUPERVISOR_SOCKET;
+  const capability = process.env.PI_SANDBOX_EXTERNAL_SUPERVISOR_CAPABILITY;
+  if (!socketPath || !capability) return Promise.resolve("deny");
+  return new Promise((resolveAction) => {
+    const socket = createConnection(socketPath);
+    let buffer = "";
+    const finish = (action) => { socket.destroy(); resolveAction(action === "allow" ? "allow" : "deny"); };
+    socket.setEncoding("utf8");
+    socket.setTimeout(30_000, () => finish("deny"));
+    socket.once("error", () => finish("deny"));
+    socket.on("data", (chunk) => {
+      buffer += chunk;
+      const newline = buffer.indexOf("\n");
+      if (newline < 0 || Buffer.byteLength(buffer, "utf8") > 16 * 1024) return;
+      try { finish(JSON.parse(buffer.slice(0, newline)).action); } catch { finish("deny"); }
+    });
+    socket.once("connect", () => socket.write(`${JSON.stringify({
+      version: 1, capability, id: randomUUID(), ...payload,
+    })}\n`));
+  });
+}
+function registerWorker() {
+  return supervisorRequest({ type: "register", workerId, cwd: process.cwd() });
+}
+function unregisterWorker() {
+  return supervisorRequest({ type: "unregister", workerId, cwd: process.cwd() });
+}
+function askSupervisor(hostname, port) {
+  return supervisorRequest({ type: "network", workerId, cwd: process.cwd(), hostname, port });
+}
+
+function createMandatoryDenyPlaceholders(cwd, agentDir) {
+  // Sandbox Runtime protects these names unconditionally. Under an outer
+  // bubblewrap it cannot create a missing bind target after the root becomes
+  // read-only, so create only absent regular-file placeholders before broker
+  // bootstrap and remove exactly those placeholders at wrapper exit.
+  const created = [];
+  const remember = (path, kind, content) => {
+    const stat = lstatSync(path);
+    created.push({ path, kind, content, dev: stat.dev, ino: stat.ino });
+  };
+  for (const name of [
+    ".gitconfig", ".gitmodules", ".bashrc", ".bash_profile", ".zshrc",
+    ".zprofile", ".profile", ".ripgreprc", ".mcp.json",
+  ]) {
+    const path = join(cwd, name);
+    if (existsSync(path)) continue;
+    try {
+      writeFileSync(path, "", { flag: "wx", mode: 0o600 });
+      remember(path, "file", "");
+    } catch {
+      // Sandbox bootstrap will fail closed if a mandatory target is unusable.
+    }
+  }
+  for (const directory of [".vscode", ".idea", ".claude/commands", ".claude/agents"]) {
+    let path = cwd;
+    for (const part of directory.split("/")) {
+      path = join(path, part);
+      if (existsSync(path)) continue;
+      try {
+        mkdirSync(path, { mode: 0o700 });
+        remember(path, "directory");
+      } catch {
+        // Sandbox bootstrap will fail closed if a mandatory target is unusable.
+        break;
+      }
+    }
+  }
+  // Keep the project-state directory available so denyWrite can bind missing
+  // security files at their exact paths instead of masking the first missing
+  // `.pi` component and preventing ordinary project-state creation.
+  const projectState = join(cwd, ".pi");
+  if (!existsSync(projectState)) {
+    try {
+      mkdirSync(projectState, { mode: 0o700 });
+      remember(projectState, "directory");
+    } catch {
+      // Sandbox bootstrap will fail closed if the directory remains unusable.
+    }
+  }
+  // The agent directory sits below denyRead(home). Bubblewrap cannot create a
+  // missing nested bind target there after the home mask becomes read-only, so
+  // seed valid empty JSON files and remove only unchanged placeholders later.
+  for (const name of ["settings.json", "permissions.json", "sandbox.json"]) {
+    const path = join(agentDir, name);
+    if (existsSync(path)) continue;
+    try {
+      writeFileSync(path, "{}\n", { flag: "wx", mode: 0o600 });
+      remember(path, "file", "{}\n");
+    } catch {
+      // Sandbox bootstrap will fail closed if a protected target is unusable.
+    }
+  }
+  return () => {
+    for (const item of created.reverse()) {
+      try {
+        const current = lstatSync(item.path);
+        if (current.dev !== item.dev || current.ino !== item.ino) continue;
+        if (item.kind === "directory") rmdirSync(item.path);
+        else if (readFileSync(item.path, "utf8") === item.content) unlinkSync(item.path);
+      } catch { /* remove only unchanged empty placeholders */ }
+    }
+  };
+}
+if (!realPi) {
+  process.stderr.write("pi-sandbox: external worker wrapper has no verified Pi binary\n");
+  process.exitCode = 1;
+} else {
+  const cwd = process.cwd();
+  const workerTempDir = mkdtempSync(join(tmpdir(), "pi-sandbox-external-worker-"));
+  process.once("exit", () => {
+    try { rmSync(workerTempDir, { recursive: true, force: true }); } catch { /* best-effort cleanup */ }
+  });
+  const home = resolve(homedir());
+  const agentDir = resolve(process.env.PI_CODING_AGENT_DIR || join(home, ".pi", "agent"));
+  const removeMandatoryDenyPlaceholders = createMandatoryDenyPlaceholders(cwd, agentDir);
+  process.once("exit", removeMandatoryDenyPlaceholders);
+  const sessionDir = process.env.PI_CODING_AGENT_SESSION_DIR;
+  const packageRoot = dirname(fileURLToPath(import.meta.url));
+  const nodeRoot = dirname(dirname(process.execPath));
+  const runtimeRoot = dirname(dirname(fileURLToPath(import.meta.resolve("@anthropic-ai/sandbox-runtime"))));
+  const extraRead = (process.env.PI_SANDBOX_EXTERNAL_ALLOW_READ || "")
+    .split(":")
+    .filter(Boolean);
+  const existingGitConfig = [
+    join(home, ".gitconfig"),
+    join(home, ".config", "git", "config"),
+  ].filter(existsSync);
+  // On Linux Sandbox Runtime masks the first missing component of a deny path.
+  // Denying a not-yet-created `.pi/settings.json` would therefore mask `.pi`
+  // itself and prevent Pi from creating its ordinary project state directory.
+  // Existing security files remain outer-sandbox protected; creation attempts
+  // are still gated by permission-system and pi-auto-review.
+  const workspaceSecurityFiles = [
+    join(cwd, ".pi", "settings.json"),
+    join(cwd, ".pi", "sandbox.json"),
+    join(cwd, ".pi", "pi-auto-review.json"),
+  ];
+  const agentSecurityPaths = [
+    join(agentDir, "settings.json"),
+    join(agentDir, "permissions.json"),
+    join(agentDir, "sandbox.json"),
+    join(agentDir, "extensions"),
+  ];
+  const runtimeConfig = {
+    filesystem: {
+      denyRead: home === parse(home).root ? [] : [home],
+      allowRead: [cwd, nodeRoot, runtimeRoot, ...existingGitConfig, "/dev/null", ...worktreeGitReadPaths(cwd), ...extraRead],
+      // Child sessions and permission-forwarding request/response files live
+      // here. Keep this narrower than the agent directory, whose security
+      // settings and extensions remain read-only.
+      allowWrite: [
+        cwd,
+        "/dev/null",
+        workerTempDir,
+        ...(sessionDir?.startsWith("/") ? [sessionDir] : []),
+        // Pi creates directory-style settings locks and provider model caches
+        // beside its global settings. Security-sensitive files and extensions
+        // below remain explicit denyWrite entries.
+        agentDir,
+      ],
+      denyWrite: [
+        ...workspaceSecurityFiles,
+        ...agentSecurityPaths,
+        packageRoot,
+        dirname(process.execPath),
+      ],
+      allowGitConfig: true,
+    },
+    network: {
+      allowedDomains: [], deniedDomains: [], allowLocalBinding: false,
+      allowAllUnixSockets: false, allowUnixSockets: [],
+    },
+  };
+  const registration = await registerWorker();
+  if (registration !== "allow") {
+    process.stderr.write("pi-sandbox: external worker registration was denied\n");
+    process.exitCode = 1;
+    process.exit();
+  }
+  const broker = fork(new URL("./srt-broker.mjs", import.meta.url), [], {
+    cwd,
+    detached: true,
+    env: {
+      ...process.env,
+      PI_SANDBOX_EXTERNAL_WORKER_TMPDIR: workerTempDir,
+      CLAUDE_CODE_TMPDIR: workerTempDir,
+      TMPDIR: workerTempDir,
+      TMP: workerTempDir,
+      TEMP: workerTempDir,
+    },
+    stdio: ["pipe", "pipe", "pipe", "ipc"],
+  });
+  broker.stdout.pipe(process.stdout);
+  broker.stderr.pipe(process.stderr);
+  process.stdin.pipe(broker.stdin);
+  broker.on("message", (message) => {
+    if (!message || typeof message !== "object" || message.type !== "network-request") return;
+    void askSupervisor(message.hostname, message.port).then((action) => {
+      if (broker.connected) broker.send({ type: "network-response", id: message.id, action });
+    });
+  });
+  let prefix = [];
+  try { prefix = JSON.parse(process.env.PI_SANDBOX_EXTERNAL_REAL_PI_PREFIX || "[]"); } catch { prefix = []; }
+  if (!Array.isArray(prefix) || prefix.some((item) => typeof item !== "string")) {
+    process.stderr.write("pi-sandbox: external worker wrapper received invalid Pi prefix\n");
+    broker.kill("SIGKILL");
+    process.exitCode = 1;
+  } else {
+    broker.send({ type: "init", invocation: [realPi, ...prefix, ...process.argv.slice(2)], runtimeConfig });
+  }
+  const stop = (signal) => {
+    if (broker.pid) {
+      try { process.kill(-broker.pid, signal); } catch { broker.kill(signal); }
+    }
+  };
+  process.on("SIGINT", () => stop("SIGINT"));
+  process.on("SIGTERM", () => stop("SIGTERM"));
+  broker.once("exit", async (code, signal) => {
+    await unregisterWorker();
+    process.exitCode = code ?? (signal ? 1 : 1);
+  });
+  broker.once("error", (error) => {
+    process.stderr.write(`pi-sandbox: external worker broker failed: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+}

package/src/index.ts

@@ -3,6 +3,7 @@ import type {
   ExtensionAPI,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { fileURLToPath } from "node:url";
 import {
   createBashToolDefinition,
   createLocalBashOperations,
@@ -31,6 +32,10 @@ import type {
   ProcessBackedSubagentSession,
 } from "./subagent.ts";
 import { Type } from "typebox";
+import {
+  createExternalWorkerSupervisor,
+  type ExternalWorkerSupervisor,
+} from "./external-supervisor.ts";
 
 const EXTENSION_NAME = "pi-sandbox";
 const registrations = new WeakMap<ExtensionAPI, Promise<void>>();
@@ -84,6 +89,50 @@ function externalSubagentDiagnostic(pi: ExtensionAPI): {
   };
 }
 
+const EXTERNAL_WORKER_LAUNCHER = fileURLToPath(
+  new URL("./external-worker-launcher.mjs", import.meta.url),
+);
+
+type ExternalWorkerIsolation = {
+  restore(): void;
+};
+
+function enableExternalWorkerIsolation(
+  supervisor: ExternalWorkerSupervisor,
+): ExternalWorkerIsolation {
+  if (process.platform !== "linux" && process.platform !== "darwin") {
+    throw new Error(`external worker isolation is unavailable on ${process.platform}`);
+  }
+  if (process.env.PI_SUBAGENT_PI_BINARY) {
+    throw new Error(
+      "external worker isolation refuses to replace an existing PI_SUBAGENT_PI_BINARY wrapper",
+    );
+  }
+  const entry = process.argv[1];
+  if (!entry) {
+    throw new Error("external worker isolation cannot determine the real Pi CLI entrypoint");
+  }
+  const injected = {
+    PI_SUBAGENT_PI_BINARY: EXTERNAL_WORKER_LAUNCHER,
+    PI_SANDBOX_EXTERNAL_REAL_PI_BINARY: process.execPath,
+    PI_SANDBOX_EXTERNAL_REAL_PI_PREFIX: JSON.stringify([entry]),
+    PI_SANDBOX_EXTERNAL_ALLOW_READ: [
+      process.cwd(),
+      process.env.PI_CODING_AGENT_DIR,
+    ].filter((value): value is string => Boolean(value)).join(":"),
+    PI_SANDBOX_EXTERNAL_SUPERVISOR_SOCKET: supervisor.socketPath,
+    PI_SANDBOX_EXTERNAL_SUPERVISOR_CAPABILITY: supervisor.capability,
+  };
+  Object.assign(process.env, injected);
+  return {
+    restore() {
+      for (const [key, value] of Object.entries(injected)) {
+        if (process.env[key] === value) delete process.env[key];
+      }
+    },
+  };
+}
+
 function humanApproval(ctx: ExtensionContext): HumanApproval {
   return async (request, reason, signal) => {
     if (!ctx.hasUI) return "deny";
@@ -204,6 +253,7 @@ async function performRegistration(
   const config = loadPiSandboxConfig();
   const subagentProvider =
     options.subagentProvider ?? config.subagents.provider;
+  const externalWorkerIsolation = config.subagents.externalWorkerIsolation;
   const additionalAllowRead = config.filesystem.additionalAllowRead;
   const hostIPC = options.hostIPC ?? config.hostIPC;
   const subagents =
@@ -216,6 +266,9 @@ async function performRegistration(
         }))
       : undefined;
   const cwd = process.cwd();
+  let isolation: ExternalWorkerIsolation | undefined;
+  let supervisor: ExternalWorkerSupervisor | undefined;
+  let externalIsolationFailure: string | undefined;
   const localBash = createBashToolDefinition(cwd);
 
   pi.registerTool({
@@ -476,11 +529,65 @@ async function performRegistration(
     currentTurn = event.turnIndex;
   });
 
-  pi.on("session_start", (_event, ctx) => {
+  // pi-subagents owns the public tool, so a failed wrapper bootstrap cannot
+  // be fixed by replacing that tool. Block at Pi's pre-execution boundary:
+  // enforce must never degrade into a host worker launch.
+  pi.on("tool_call", (event) => {
+    if (
+      event.toolName === "subagent" &&
+      subagentProvider === "pi-subagents" &&
+      externalWorkerIsolation === "enforce" &&
+      !isolation
+    ) {
+      return {
+        block: true,
+        reason: `${EXTENSION_NAME}: external worker isolation is unavailable; refusing host worker launch${externalIsolationFailure ? `: ${externalIsolationFailure}` : ""}`,
+      };
+    }
+    return undefined;
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    if (
+      subagentProvider === "pi-subagents" &&
+      externalWorkerIsolation === "enforce"
+    ) {
+      try {
+        isolation?.restore();
+        await supervisor?.close();
+        supervisor = await createExternalWorkerSupervisor((worker) => ({
+          broker: getBoundaryBroker(),
+          command: "external pi-subagents worker network request",
+          cwd: worker.cwd,
+          sessionId: sessionId(ctx),
+          scopeKey: `${sessionId(ctx)}:turn:${currentTurn}`,
+          agentName: `pi-subagents-worker:${worker.id}`,
+          humanApproval: humanApproval(ctx),
+        }));
+        isolation = enableExternalWorkerIsolation(supervisor);
+        externalIsolationFailure = undefined;
+      } catch (error) {
+        const message = `${EXTENSION_NAME}: external worker isolation unavailable; child launches will fail closed: ${error instanceof Error ? error.message : String(error)}`;
+        externalIsolationFailure = message;
+        isolation?.restore();
+        isolation = undefined;
+        await supervisor?.close();
+        supervisor = undefined;
+        console.error(message);
+        if (ctx.hasUI) ctx.ui.notify(message, "warning");
+      }
+    }
     if (ctx.hasUI) {
       if (subagentProvider === "pi-subagents") {
         const diagnostic = externalSubagentDiagnostic(pi);
-        ctx.ui.notify(diagnostic.message, diagnostic.level);
+        ctx.ui.notify(
+          externalWorkerIsolation === "enforce" && isolation
+            ? "pi-subagents orchestration active; external worker process trees require outer Sandbox Runtime isolation."
+            : diagnostic.message,
+          externalWorkerIsolation === "enforce" && isolation
+            ? "info"
+            : diagnostic.level,
+        );
       } else if (subagentProvider === "builtin") {
         ctx.ui.notify(
           "pi-sandbox subagent provider: builtin; worker process trees use the outer Sandbox Runtime sandbox",
@@ -513,6 +620,10 @@ async function performRegistration(
   });
 
   pi.on("session_shutdown", async () => {
+    isolation?.restore();
+    isolation = undefined;
+    await supervisor?.close();
+    supervisor = undefined;
     await subagents?.shutdown();
   });
 }

package/src/srt-broker.mjs

@@ -88,9 +88,12 @@ async function main() {
     undefined,
     process.cwd(),
   );
+  const workerTempDir = process.env.PI_SANDBOX_EXTERNAL_WORKER_TMPDIR;
   target = spawn(wrapped.argv[0], wrapped.argv.slice(1), {
     cwd: process.cwd(),
-    env: wrapped.env,
+    env: workerTempDir
+      ? { ...wrapped.env, TMPDIR: workerTempDir, TMP: workerTempDir, TEMP: workerTempDir }
+      : wrapped.env,
     stdio: ["pipe", "pipe", "pipe"],
   });
   process.stdin.pipe(target.stdin);