@erichll/pi-sandbox 0.6.2 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 0.8.0 - 2026-08-18
+
+- **Trusted network domain policies.** Persistent `network.allowedDomains` and
+  `network.deniedDomains` arrays in the trusted global configuration
+  (`~/.pi/agent/extensions/pi-sandbox/config.json`, with legacy fallback) now
+  authorize matching connections statically, without the one-shot reviewer.
+  Entries use Sandbox Runtime-compatible patterns: exact domains,
+  strict-subdomain wildcards such as `*.example.com`, and an optional `:port`;
+  a bare `*` (optionally with a port) is accepted only in `deniedDomains`.
+  Values are trimmed and deduplicated, and malformed or unknown configuration
+  fails closed. Precedence is deterministic — deny, then allow, then the
+  existing one-shot reviewer — and empty arrays preserve the previous
+  behavior (no persistent network authorization, with every eligible public
+  connection reviewed once).
+- **Policy parity across execution surfaces.** The same copied network policy
+  is applied to main-agent Bash, built-in subagents, and outer-isolated
+  `pi-subagents` workers. External workers receive policy only through their
+  capability-bound supervisor registration; missing, malformed, or extra-field
+  transport becomes deny-all without disabling dynamic review for valid
+  policies.
+- **Exfiltration-risk documentation.** The README now warns that domain
+  allowlists are not a complete data-loss-prevention boundary, that
+  multi-tenant or user-uploadable destinations (for example `github.com`) can
+  themselves be exfiltration channels, and that pi-sandbox never infers or
+  silently adds domains.
+- Pin `@anthropic-ai/sandbox-runtime` to `0.0.73` (fixed version; its
+  network-policy evaluation semantics are reused by the static allow/deny
+  matching).
+
+## 0.7.0 - 2026-08-17
+
+- **Builtin `subagent` model fail-fast.** An explicit `model` on `start`/
+  `handoff` is now validated against the host model registry before a child Pi
+  spawns. Unknown models fail before any session/broker/process is created;
+  ambiguous bare ids are rejected with a `provider/model` hint; a trailing
+  `:thinking` suffix is preserved; `status`/`wait`/`stop`/`follow_up` are never
+  intercepted.
+
+- **FleetView external-worker display.** Declare `pi-subagents >=0.50.0` as an
+  **optional** peer dependency (no forced install for builtin/off users) and
+  mirror pi-sandbox's isolated external workers into pi-subagents' FleetView
+  (caller-owned `external-runs`) whenever `subagents.provider ===
+  "pi-subagents"` AND `externalWorkerIsolation === "enforce"`. Loading uses a
+  dynamic import only; import/registry failures disable the display path
+  without weakening fail-closed isolation or network approval. v1 records are
+  `running`-only and cleaned up on worker unregister, session shutdown, and
+  supervisor replacement.
+
+- **`pi-subagents` capability baseline raised to `0.50.0`** (test/CI only;
+  does not affect the published runtime). The dev dependency is pinned exactly
+  to `0.50.0`, the capability boundary is redocumented, the compatibility-gate
+  entry resolves through the package `exports["."]` via `import.meta.resolve`,
+  and the external-isolation probe is generalized. Verified by
+  `gate:external-isolation` and the model-backed `gate:pi-subagents`
+  (`PASS`, `piSubagents: 0.50.0`).
+
 ## 0.6.2 - 2026-08-13
 
 - Bump `@erichll/pi-auto-review` to `0.3.5` so consumers inherit the raised

package/README.md

@@ -12,9 +12,10 @@ also run complete process-backed subagent trees inside independent sandboxes.
   writes outside the workspace fail closed. Runtime filesystem denials are not
   converted into dynamic grants because Sandbox Runtime does not expose a
   trustworthy filesystem ask callback.
-- Network access is denied by default. Each unmatched destination is sent to
-  `pi-auto-review` as a concrete hostname and port. An approval applies only to
-  that connection.
+- Network policy is evaluated as static deny, then static allow, then dynamic
+  review. Each unmatched public destination is sent to `pi-auto-review` as a
+  canonical hostname and concrete port. An approval applies only to that
+  connection.
 - Every Bash command and persistent subagent session owns a separate broker
   process and Sandbox Runtime manager. Concurrent workers therefore keep
   independent policy, proxy, approval, and cleanup lifecycles.
@@ -82,12 +83,16 @@ Supported modes:
   itself is not wrapped while `externalWorkerIsolation` is `off`.
 - `off`: protect Bash only.
 
-### `pi-subagents` 0.45.2 capability boundary
+### `pi-subagents` 0.50.0 capability boundary
 
 `pi-sandbox` verifies the following combination in its test suite and release
-gate:
+gate. This version boundary is pinned exactly (see the package
+`devDependencies`) and additionally exercised against the latest published
+`pi-subagents` on a nightly CI schedule. The `PI_SUBAGENT_PI_BINARY` seam
+(`externalWorkerIsolation: "enforce"`) is re-checked deterministically by the
+`gate:external-isolation` probe on the pinned and latest dependency.
 
-| Capability | `builtin` | `pi-subagents` 0.45.2 |
+| Capability | `builtin` | `pi-subagents` 0.50.0 |
 | --- | --- | --- |
 | Outer worker sandbox | Yes | Opt-in (`externalWorkerIsolation: "enforce"`) |
 | Bash sandbox | Yes | Yes |
@@ -95,6 +100,11 @@ gate:
 | `workflowScript`, missions, schedules | No | Yes |
 | permission-system parent forwarding | Not required | Verified by compatibility gate |
 
+Upgrading across a capability boundary (for example `0.49.0` → `0.50.0`)
+requires re-running `npm run gate:external-isolation` and, before a release,
+the model-backed `npm run gate:pi-subagents`. See `docs/compat-notes.md` for
+the recorded compatibility seams and how each is verified on upgrade.
+
 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
@@ -109,6 +119,53 @@ such as `return runs.run('main', { agent, task })`. The compatibility gate's
 The configuration parser rejects malformed JSON, unknown fields, and unknown
 providers instead of silently weakening isolation.
 
+## Network domain policy
+
+Persistent domain authorization is accepted only from the trusted global
+`~/.pi/agent/extensions/pi-sandbox/config.json` (or its legacy trusted fallback
+when the new file is absent). Project configuration cannot override it.
+
+```json
+{
+  "network": {
+    "allowedDomains": [
+      "github.com",
+      "*.github.com",
+      "registry.npmjs.org:443"
+    ],
+    "deniedDomains": [
+      "uploads.github.com",
+      "*:22"
+    ]
+  }
+}
+```
+
+Entries support exact domains, strict-subdomain wildcards such as
+`*.example.com`, and an optional `:port` restriction. A bare `*` (optionally
+with a port) is accepted only in `deniedDomains`. Values are trimmed and
+deduplicated, and malformed or unknown configuration fails closed.
+
+The precedence is deterministic:
+
+1. A matching `deniedDomains` entry rejects the connection.
+2. Otherwise, a matching `allowedDomains` entry permits it without review.
+3. Otherwise, the canonical public hostname and port enter the existing
+   one-shot auto-review or human approval flow.
+
+Both arrays default to empty. That preserves the prior behavior: no persistent
+network authorization, with every eligible public connection reviewed once.
+The same trusted arrays are copied into main-agent Bash, built-in subagents,
+and external `pi-subagents` workers when outer isolation is enforced. Missing
+or malformed external-worker policy transport hard-denies network access.
+
+Domain allowlists are not a complete data-loss-prevention boundary. A
+multi-tenant or user-uploadable destination such as `github.com` can itself be
+an exfiltration channel; grant only the narrow domains and ports you intend.
+Real package-manager traffic may require additional hosts—for example, PyPI
+downloads commonly use `files.pythonhosted.org`. `pi-sandbox` never infers or
+silently adds those domains.
+
 To opt in to outer worker isolation for the external provider, use:
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erichll/pi-sandbox",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "Sandbox Runtime-backed Linux and macOS sandbox with pi-auto-review approval",
   "type": "module",
   "license": "Apache-2.0",
@@ -50,17 +50,23 @@
     "test": "node --experimental-strip-types --test test/*.test.ts"
   },
   "dependencies": {
-    "@anthropic-ai/sandbox-runtime": "0.0.71",
+    "@anthropic-ai/sandbox-runtime": "0.0.73",
     "@erichll/pi-auto-review": "0.3.5"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.82.1",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "pi-subagents": ">=0.50.0",
     "typebox": ">=1.0.0"
   },
+  "peerDependenciesMeta": {
+    "pi-subagents": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.83.0",
-    "@types/node": "^22.15.3",
-    "pi-subagents": "^0.47.1",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@types/node": "^26.2.0",
+    "pi-subagents": "0.50.0",
     "typescript": "^6.0.3"
   }
 }

package/src/config.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
+import { NetworkConfigSchema } from "@anthropic-ai/sandbox-runtime";
 
 export const SUBAGENT_PROVIDERS = [
   "builtin",
@@ -19,6 +20,11 @@ export type HostIPCConfig = {
   retryOnUnixSocketError: boolean;
 };
 
+export type NetworkConfig = {
+  readonly allowedDomains: readonly string[];
+  readonly deniedDomains: readonly string[];
+};
+
 export type PiSandboxConfig = {
   subagents: {
     provider: SubagentProvider;
@@ -27,6 +33,7 @@ export type PiSandboxConfig = {
   filesystem: {
     additionalAllowRead: readonly string[];
   };
+  network: NetworkConfig;
   hostIPC: HostIPCConfig;
 };
 
@@ -45,6 +52,10 @@ export const DEFAULT_PI_SANDBOX_CONFIG: Readonly<PiSandboxConfig> = Object.freez
     filesystem: Object.freeze({
       additionalAllowRead: Object.freeze([]),
     }),
+    network: Object.freeze({
+      allowedDomains: Object.freeze([]),
+      deniedDomains: Object.freeze([]),
+    }),
     hostIPC: Object.freeze({
       mode: "off",
       preflightCommandPrefixes: Object.freeze([]),
@@ -86,11 +97,40 @@ function rejectUnknownKeys(
   }
 }
 
+function hasValidDomainLabels(
+  pattern: string,
+  allowDenyAll: boolean,
+): boolean {
+  const portMatch = pattern.match(/:([1-9][0-9]{0,4})$/);
+  const hostPattern = portMatch
+    ? pattern.slice(0, -portMatch[0].length)
+    : pattern;
+  if (portMatch && Number(portMatch[1]) > 65_535) return false;
+  if (hostPattern === "*") return allowDenyAll;
+  const hostname = hostPattern.startsWith("*.")
+    ? hostPattern.slice(2)
+    : hostPattern;
+  return (
+    hostname.length <= 253 &&
+    hostname.includes(".") &&
+    hostname.split(".").every(
+      (label) =>
+        label.length > 0 &&
+        label.length <= 63 &&
+        /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/i.test(label),
+    )
+  );
+}
+
 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", "hostIPC"], "root");
+  rejectUnknownKeys(
+    value,
+    ["subagents", "filesystem", "network", "hostIPC"],
+    "root",
+  );
 
   if (value.subagents !== undefined && !isRecord(value.subagents)) {
     throw new Error(
@@ -154,6 +194,58 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
     );
   }
 
+  if (value.network !== undefined && !isRecord(value.network)) {
+    throw new Error(
+      "invalid pi-sandbox configuration: network must be an object",
+    );
+  }
+  const network = value.network ?? {};
+  rejectUnknownKeys(
+    network,
+    ["allowedDomains", "deniedDomains"],
+    "network",
+  );
+  const normalizeDomainList = (
+    key: "allowedDomains" | "deniedDomains",
+  ): string[] => {
+    const configured = network[key] ?? DEFAULT_PI_SANDBOX_CONFIG.network[key];
+    if (
+      !Array.isArray(configured) ||
+      configured.some(
+        (pattern) => typeof pattern !== "string" || pattern.trim() === "",
+      )
+    ) {
+      throw new Error(
+        `invalid pi-sandbox configuration: network.${key} must be an array of non-empty strings`,
+      );
+    }
+    const normalized = [
+      ...new Set(configured.map((pattern) => pattern.trim())),
+    ];
+    const invalidIndex = normalized.findIndex(
+      (pattern) => !hasValidDomainLabels(pattern, key === "deniedDomains"),
+    );
+    if (invalidIndex >= 0) {
+      throw new Error(
+        `invalid pi-sandbox configuration: network.${key}[${invalidIndex}] contains an invalid domain pattern`,
+      );
+    }
+    const candidate = {
+      allowedDomains: key === "allowedDomains" ? normalized : [],
+      deniedDomains: key === "deniedDomains" ? normalized : [],
+    };
+    const result = NetworkConfigSchema.safeParse(candidate);
+    if (!result.success) {
+      const issue = result.error.issues[0];
+      throw new Error(
+        `invalid pi-sandbox configuration: network.${key}${typeof issue?.path[1] === "number" ? `[${issue.path[1]}]` : ""} ${issue?.message ?? "contains an invalid domain pattern"}`,
+      );
+    }
+    return normalized;
+  };
+  const allowedDomains = normalizeDomainList("allowedDomains");
+  const deniedDomains = normalizeDomainList("deniedDomains");
+
   if (value.hostIPC !== undefined && !isRecord(value.hostIPC)) {
     throw new Error(
       "invalid pi-sandbox configuration: hostIPC must be an object",
@@ -204,6 +296,10 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
     filesystem: {
       additionalAllowRead: [...new Set(additionalAllowRead)],
     },
+    network: {
+      allowedDomains: [...allowedDomains],
+      deniedDomains: [...deniedDomains],
+    },
     hostIPC: {
       mode: hostIPCMode as HostIPCMode,
       preflightCommandPrefixes: [
@@ -226,6 +322,10 @@ function defaultPiSandboxConfig(): PiSandboxConfig {
         ...DEFAULT_PI_SANDBOX_CONFIG.filesystem.additionalAllowRead,
       ],
     },
+    network: {
+      allowedDomains: [...DEFAULT_PI_SANDBOX_CONFIG.network.allowedDomains],
+      deniedDomains: [...DEFAULT_PI_SANDBOX_CONFIG.network.deniedDomains],
+    },
     hostIPC: {
       mode: DEFAULT_PI_SANDBOX_CONFIG.hostIPC.mode,
       preflightCommandPrefixes: [

package/src/external-network-policy.d.mts

@@ -0,0 +1,8 @@
+export type ExternalNetworkPolicy = {
+  allowedDomains: string[];
+  deniedDomains: string[];
+};
+
+export function decodeExternalNetworkPolicy(
+  value: unknown,
+): ExternalNetworkPolicy;

package/src/external-network-policy.mjs

@@ -0,0 +1,27 @@
+import { NetworkConfigSchema } from "@anthropic-ai/sandbox-runtime";
+
+/**
+ * Decode the supervisor-owned network policy delivered during registration.
+ * Any missing, extra, or malformed data becomes a deny-all policy so a broken
+ * transport can never widen an external worker's access.
+ */
+export function decodeExternalNetworkPolicy(value) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    Object.keys(value).some(
+      (key) => key !== "allowedDomains" && key !== "deniedDomains",
+    )
+  ) {
+    return { allowedDomains: [], deniedDomains: ["*"] };
+  }
+  const result = NetworkConfigSchema.safeParse(value);
+  if (!result.success) {
+    return { allowedDomains: [], deniedDomains: ["*"] };
+  }
+  return {
+    allowedDomains: [...result.data.allowedDomains],
+    deniedDomains: [...result.data.deniedDomains],
+  };
+}

package/src/external-runs-view.ts

@@ -0,0 +1,173 @@
+// Optional FleetView integration for pi-sandbox's isolated external workers.
+//
+// When the host is running the external `pi-subagents` provider with
+// `externalWorkerIsolation: "enforce"`, pi-sandbox supervises the external
+// worker process trees itself. This module mirrors those supervised workers
+// into pi-subagents' caller-owned external-run registry so they show up in the
+// FleetView (pi-subagents >= 0.50.0).
+//
+// This is a pure observability enhancement: it participates in NO sandbox
+// allow/deny decision, and nothing here can downgrade an isolated worker into
+// host execution. `pi-subagents/external-runs` is loaded via a DYNAMIC import
+// only (never a top-level static import), because pi-subagents is an OPTIONAL
+// peer dependency: builtin/off deployments may not have it installed.
+//
+// Deliberate scope of v1: records are "running" only. No completed/failed/
+// endedAt are fabricated because neither the launcher nor the supervisor
+// protocol currently reports process exit evidence to this extension (the
+// record would therefore be a lie). See docs/compat-notes.md seam 5.
+
+type ExternalRunState = "running";
+
+/** Structural view of the specific pi-subagents API we consume. */
+type ExternalRunsApi = {
+  registerExternalRun(input: {
+    id: string;
+    sessionId: string;
+    source: string;
+    label: string;
+    state: ExternalRunState;
+    startedAt: number;
+    preview?: string;
+  }): unknown;
+  unregisterExternalRun(sessionId: string, id: string): boolean;
+};
+
+export type ExternalRunsView = {
+  /** Whether the pi-subagents runtime is reachable (dynamic import succeeded). */
+  readonly enabled: boolean;
+  /** Diagnostic string when the runtime is disabled. */
+  readonly error?: string;
+  /** Mirror a supervisor lifecycle.registered event into the registry. */
+  registered(worker: { id: string; cwd: string; startedAt: number }): void;
+  /** Mirror a supervisor lifecycle.unregistered event out of the registry. */
+  unregistered(workerId: string): void;
+  /** Unregister every run this view registered (session shutdown / replace). */
+  close(): void;
+};
+
+const VIEW_LABEL = "isolated pi-subagents worker";
+const VIEW_SOURCE = "pi-sandbox";
+
+/**
+ * Whether the FleetView integration should be enabled for a given provider /
+ * isolation combination. It is enabled ONLY when the external pi-subagents
+ * provider owns orchestration AND outer worker isolation is enforced -- the
+ * sole case where pi-sandbox actually supervises external workers and can
+ * truthfully vouch for a "running" record it owns.
+ */
+export function externalRunsViewEnabledWhen(
+  provider: string,
+  externalWorkerIsolation: string,
+): boolean {
+  return provider === "pi-subagents" && externalWorkerIsolation === "enforce";
+}
+
+function ident(value: string): { ok: true; value: string } | { ok: false; error: string } {
+  const trimmed = value.trim();
+  if (!trimmed || trimmed !== value) {
+    return { ok: false, error: "must be a non-empty trimmed string" };
+  }
+  return { ok: true, value: trimmed };
+}
+
+export function createExternalRunsView(
+  sessionIdInput: string,
+  load: () => Promise<unknown> = () => import("pi-subagents/external-runs"),
+): Promise<ExternalRunsView> {
+  return (async () => {
+    const sessionId = ident(sessionIdInput);
+    if (!sessionId.ok) {
+      return disabledView(`invalid session id: ${sessionId.error}`);
+    }
+    let api: ExternalRunsApi | undefined;
+    let loadError: string | undefined;
+    try {
+      const mod = (await load()) as Record<string, unknown>;
+      const registerExternalRun = mod.registerExternalRun;
+      const unregisterExternalRun = mod.unregisterExternalRun;
+      if (typeof registerExternalRun !== "function" || typeof unregisterExternalRun !== "function") {
+        throw new Error("pi-subagents/external-runs does not expose registerExternalRun/unregisterExternalRun");
+      }
+      api = { registerExternalRun, unregisterExternalRun } as unknown as ExternalRunsApi;
+    } catch (error) {
+      loadError = `FleetView external-run registration unavailable: ${error instanceof Error ? error.message : String(error)}`;
+      // Never thrown: disable only the display path. Sandbox fail-closed and
+      // network approval for the supervisor are untouched.
+      return disabledView(loadError);
+    }
+
+    // (sessionId, workerId) pairs this extension registered, so we never
+    // duplicate-register and never unregister records owned by other sources.
+    const registered = new Map<string, number>();
+
+    return {
+      get enabled() {
+        return Boolean(api);
+      },
+      error: loadError,
+      registered(worker) {
+        const fullId = ident(worker.id);
+        const cwd = ident(worker.cwd);
+        if (!api || !fullId.ok || !cwd.ok) return;
+        if (registered.has(fullId.value)) return; // avoid duplicate registration
+        try {
+          api!.registerExternalRun({
+            id: fullId.value,
+            sessionId: sessionId.value,
+            source: VIEW_SOURCE,
+            label: VIEW_LABEL,
+            state: "running",
+            startedAt:
+              Number.isSafeInteger(worker.startedAt) && worker.startedAt > 0
+                ? worker.startedAt
+                : Date.now(),
+            preview: cwd.value,
+          });
+          registered.set(fullId.value, Date.now());
+        } catch (error) {
+          // Registry full / malformed record / unknown fields: log, do not emit.
+          console.error(
+            `pi-sandbox: could not register external run for worker '${fullId.value}': ${error instanceof Error ? error.message : String(error)}`,
+          );
+        }
+      },
+      unregistered(workerId) {
+        const fullId = ident(workerId);
+        if (!fullId.ok) return;
+        if (!registered.has(fullId.value)) return; // we did not register it
+        registered.delete(fullId.value);
+        if (api) {
+          try {
+            api.unregisterExternalRun(sessionId.value, fullId.value);
+          } catch {
+            // Best-effort; nothing else to fall back to.
+          }
+        }
+      },
+      close() {
+        for (const workerId of registered.keys()) {
+          if (api) {
+            try {
+              api.unregisterExternalRun(sessionId.value, workerId);
+            } catch {
+              // best-effort
+            }
+          }
+        }
+        registered.clear();
+      },
+    };
+  })();
+}
+
+function disabledView(error: string): ExternalRunsView {
+  console.error(`pi-sandbox: ${error}`);
+  return {
+    enabled: false,
+    error,
+    registered() {},
+    unregistered() {},
+    close() {},
+  };
+}

package/src/external-supervisor.ts

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import type { NetworkEndpoint, TrapApprovalContext } from "./approval.ts";
 import { approveDomainEndpoint } from "./approval.ts";
+import type { NetworkConfig } from "./config.ts";
 
 const MAX_FRAME_BYTES = 16 * 1024;
 const PROTOCOL_VERSION = 1;
@@ -20,6 +21,13 @@ type Request = {
   port?: unknown;
 };
 
+export type ExternalWorkerSupervisorLifecycle = {
+  /** Called immediately after a worker finishes the register protocol. */
+  registered?(worker: { id: string; cwd: string; startedAt: number }): void;
+  /** Called immediately after a worker completes the unregister protocol. */
+  unregistered?(worker: { id: string; cwd: string }): void;
+};
+
 export type ExternalWorkerSupervisor = {
   socketPath: string;
   capability: string;
@@ -35,7 +43,13 @@ export type ExternalWorkerSupervisor = {
 
 export async function createExternalWorkerSupervisor(
   approvalContext: (worker: { id: string; cwd: string }) => TrapApprovalContext,
+  lifecycle: ExternalWorkerSupervisorLifecycle = {},
+  network: NetworkConfig = { allowedDomains: [], deniedDomains: [] },
 ): Promise<ExternalWorkerSupervisor> {
+  const trustedNetwork = {
+    allowedDomains: [...network.allowedDomains],
+    deniedDomains: [...network.deniedDomains],
+  };
   const directory = await mkdtemp(join(tmpdir(), "pi-sandbox-external-"));
   await chmod(directory, 0o700);
   const socketPath = join(directory, "supervisor.sock");
@@ -93,7 +107,19 @@ export async function createExternalWorkerSupervisor(
           startedAt: Date.now(),
           requests: 0,
         });
-        socket.write(`${JSON.stringify({ id: request.id, action: "allow" })}\n`);
+        socket.write(`${JSON.stringify({
+          id: request.id,
+          action: "allow",
+          network: {
+            allowedDomains: [...trustedNetwork.allowedDomains],
+            deniedDomains: [...trustedNetwork.deniedDomains],
+          },
+        })}\n`);
+        lifecycle.registered?.({
+          id: request.workerId as string,
+          cwd: request.cwd as string,
+          startedAt: workers.get(request.workerId as string)!.startedAt,
+        });
         return;
       }
       const knownWorker =
@@ -106,6 +132,10 @@ export async function createExternalWorkerSupervisor(
         seen.add(request.id as string);
         knownWorker.state = "exited";
         socket.write(`${JSON.stringify({ id: request.id, action: "allow" })}\n`);
+        lifecycle.unregistered?.({
+          id: request.workerId as string,
+          cwd: request.cwd as string,
+        });
         return;
       }
       const workerCwd =

package/src/external-worker-launcher.mjs

@@ -8,6 +8,7 @@ import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmdirSync,
 import { homedir, tmpdir } from "node:os";
 import { dirname, join, parse, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { decodeExternalNetworkPolicy } from "./external-network-policy.mjs";
 
 const realPi = process.env.PI_SANDBOX_EXTERNAL_REAL_PI_BINARY;
 const workerId = randomUUID();
@@ -32,19 +33,22 @@ function worktreeGitReadPaths(cwd) {
 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) => {
+  if (!socketPath || !capability) return Promise.resolve({ action: "deny" });
+  return new Promise((resolveResponse) => {
     const socket = createConnection(socketPath);
     let buffer = "";
-    const finish = (action) => { socket.destroy(); resolveAction(action === "allow" ? "allow" : "deny"); };
+    const finish = (response) => {
+      socket.destroy();
+      resolveResponse(response?.action === "allow" ? response : { action: "deny" });
+    };
     socket.setEncoding("utf8");
-    socket.setTimeout(30_000, () => finish("deny"));
-    socket.once("error", () => finish("deny"));
+    socket.setTimeout(30_000, () => finish({ action: "deny" }));
+    socket.once("error", () => finish({ action: "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"); }
+      try { finish(JSON.parse(buffer.slice(0, newline))); } catch { finish({ action: "deny" }); }
     });
     socket.once("connect", () => socket.write(`${JSON.stringify({
       version: 1, capability, id: randomUUID(), ...payload,
@@ -55,10 +59,10 @@ function registerWorker() {
   return supervisorRequest({ type: "register", workerId, cwd: process.cwd() });
 }
 function unregisterWorker() {
-  return supervisorRequest({ type: "unregister", workerId, cwd: process.cwd() });
+  return supervisorRequest({ type: "unregister", workerId, cwd: process.cwd() }).then((response) => response.action);
 }
 function askSupervisor(hostname, port) {
-  return supervisorRequest({ type: "network", workerId, cwd: process.cwd(), hostname, port });
+  return supervisorRequest({ type: "network", workerId, cwd: process.cwd(), hostname, port }).then((response) => response.action);
 }
 
 function createMandatoryDenyPlaceholders(cwd, agentDir) {
@@ -174,6 +178,13 @@ if (!realPi) {
     join(agentDir, "sandbox.json"),
     join(agentDir, "extensions"),
   ];
+  const registration = await registerWorker();
+  if (registration.action !== "allow") {
+    process.stderr.write("pi-sandbox: external worker registration was denied\n");
+    process.exitCode = 1;
+    process.exit();
+  }
+  const registeredNetwork = decodeExternalNetworkPolicy(registration.network);
   const runtimeConfig = {
     filesystem: {
       denyRead: home === parse(home).root ? [] : [home],
@@ -200,16 +211,12 @@ if (!realPi) {
       allowGitConfig: true,
     },
     network: {
-      allowedDomains: [], deniedDomains: [], allowLocalBinding: false,
+      allowedDomains: registeredNetwork.allowedDomains,
+      deniedDomains: registeredNetwork.deniedDomains,
       allowAllUnixSockets: false, allowUnixSockets: [],
+      allowLocalBinding: false,
     },
   };
-  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,

package/src/index.ts

@@ -19,6 +19,7 @@ import {
 import {
   loadPiSandboxConfig,
   type HostIPCConfig,
+  type NetworkConfig,
   type SubagentProvider,
 } from "./config.ts";
 import { runCommandWithHostIPC } from "./host-ipc.ts";
@@ -31,11 +32,17 @@ import type {
   ProcessBackedSubagentManager,
   ProcessBackedSubagentSession,
 } from "./subagent.ts";
+import { validateSubagentModel } from "./subagent.ts";
 import { Type } from "typebox";
 import {
   createExternalWorkerSupervisor,
   type ExternalWorkerSupervisor,
 } from "./external-supervisor.ts";
+import {
+  createExternalRunsView,
+  externalRunsViewEnabledWhen,
+  type ExternalRunsView,
+} from "./external-runs-view.ts";
 
 const EXTENSION_NAME = "pi-sandbox";
 const registrations = new WeakMap<ExtensionAPI, Promise<void>>();
@@ -165,6 +172,7 @@ function sandboxOperations(
   ctx: ExtensionContext,
   turnIndex: () => number,
   additionalAllowRead: readonly string[],
+  network: NetworkConfig,
   hostIPC: HostIPCConfig,
   sandbox?: PiSandboxExtensionOptions["sandbox"],
 ): BashOperations {
@@ -216,7 +224,7 @@ function sandboxOperations(
             onData: options.onData,
             onStderr,
             shellPath,
-            policy: createDefaultPolicy(cwd, { additionalAllowRead }),
+            policy: createDefaultPolicy(cwd, { additionalAllowRead, network }),
             review: async (trap) => {
               const result = await approveSandboxTrap(trap, approvalContext);
               if (result.action === "deny" && result.reason) {
@@ -254,7 +262,12 @@ async function performRegistration(
   const subagentProvider =
     options.subagentProvider ?? config.subagents.provider;
   const externalWorkerIsolation = config.subagents.externalWorkerIsolation;
+  const externalRunsViewEnabled = externalRunsViewEnabledWhen(
+    subagentProvider,
+    externalWorkerIsolation,
+  );
   const additionalAllowRead = config.filesystem.additionalAllowRead;
+  const network = config.network;
   const hostIPC = options.hostIPC ?? config.hostIPC;
   const subagents =
     subagentProvider === "builtin"
@@ -268,6 +281,7 @@ async function performRegistration(
   const cwd = process.cwd();
   let isolation: ExternalWorkerIsolation | undefined;
   let supervisor: ExternalWorkerSupervisor | undefined;
+  let fleetView: ExternalRunsView | undefined;
   let externalIsolationFailure: string | undefined;
   const localBash = createBashToolDefinition(cwd);
 
@@ -281,6 +295,7 @@ async function performRegistration(
           ctx,
           () => currentTurn,
           additionalAllowRead,
+          network,
           hostIPC,
           options.sandbox,
         ),
@@ -369,7 +384,7 @@ async function performRegistration(
           cwd: ctx.cwd,
           model: params.model,
           tools: pi.getActiveTools().filter((name) => name !== "subagent"),
-          policy: createDefaultPolicy(ctx.cwd, { additionalAllowRead }),
+          policy: createDefaultPolicy(ctx.cwd, { additionalAllowRead, network }),
           sandbox: options.sandbox,
           review: async (trap: Parameters<typeof approveSandboxTrap>[0]) =>
             (await approveSandboxTrap(trap, approvalContext)).action,
@@ -474,6 +489,21 @@ async function performRegistration(
           : requireTask();
       const parentId =
         action === "handoff" ? requireSession().id : undefined;
+      // Fail fast on an invalid explicit model before spawning a child Pi.
+      // Only process-spawning actions (start/handoff) reach this block, so
+      // status/wait/stop/follow_up are never intercepted by model validation.
+      // When no model is specified the child inherits host behavior (no check).
+      const modelSpec = params.model?.trim();
+      if (modelSpec) {
+        const modelCheck = validateSubagentModel(
+          modelSpec,
+          ctx.modelRegistry?.getAvailable() ?? [],
+          ctx.model?.provider,
+        );
+        if (!modelCheck.ok) {
+          throw new Error(modelCheck.error);
+        }
+      }
       const session = await subagents.start(sessionOptions(task, parentId));
       const unsubscribe = update(session);
       try {
@@ -520,6 +550,7 @@ async function performRegistration(
       ctx,
       () => currentTurn,
       additionalAllowRead,
+      network,
       hostIPC,
       options.sandbox,
     ),
@@ -548,6 +579,10 @@ async function performRegistration(
   });
 
   pi.on("session_start", async (_event, ctx) => {
+    // A new session may replace a prior supervisor ownership; drop the old
+    // session's FleetView registrations before reconstructing.
+    fleetView?.close();
+    fleetView = undefined;
     if (
       subagentProvider === "pi-subagents" &&
       externalWorkerIsolation === "enforce"
@@ -555,15 +590,29 @@ async function performRegistration(
       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),
-        }));
+        supervisor = undefined;
+        if (externalRunsViewEnabled) {
+          fleetView = await createExternalRunsView(sessionId(ctx));
+        }
+        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),
+          }),
+          {
+            // Observability-only: never influences allow/deny, and a failure
+            // here must not stop the supervisor from answering approval RPCs
+            // or make the worker launch on the host.
+            registered: (worker) => fleetView?.registered(worker),
+            unregistered: (worker) => fleetView?.unregistered(worker.id),
+          },
+          network,
+        );
         isolation = enableExternalWorkerIsolation(supervisor);
         externalIsolationFailure = undefined;
       } catch (error) {
@@ -573,6 +622,8 @@ async function performRegistration(
         isolation = undefined;
         await supervisor?.close();
         supervisor = undefined;
+        fleetView?.close();
+        fleetView = undefined;
         console.error(message);
         if (ctx.hasUI) ctx.ui.notify(message, "warning");
       }
@@ -612,8 +663,8 @@ async function performRegistration(
     if (ctx.hasUI) {
       ctx.ui.notify(
         process.platform === "darwin"
-          ? `${EXTENSION_NAME} enabled: macOS Sandbox Runtime with static filesystem policy and per-connection network review`
-          : `${EXTENSION_NAME} enabled: Linux Sandbox Runtime with static filesystem policy and per-connection network review`,
+          ? `${EXTENSION_NAME} enabled: macOS Sandbox Runtime with static filesystem/domain policy and per-connection network review`
+          : `${EXTENSION_NAME} enabled: Linux Sandbox Runtime with static filesystem/domain policy and per-connection network review`,
         "info",
       );
     }
@@ -622,6 +673,8 @@ async function performRegistration(
   pi.on("session_shutdown", async () => {
     isolation?.restore();
     isolation = undefined;
+    fleetView?.close();
+    fleetView = undefined;
     await supervisor?.close();
     supervisor = undefined;
     await subagents?.shutdown();

package/src/policy.ts

@@ -10,6 +10,7 @@ import {
 } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
+import type { NetworkConfig } from "./config.ts";
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const NODE_INSTALL_ROOT = dirname(dirname(process.execPath));
@@ -120,6 +121,7 @@ export type SandboxPolicy = {
 
 export type CreateDefaultPolicyOptions = {
   additionalAllowRead?: readonly string[];
+  network?: NetworkConfig;
 };
 
 export function isSecretDenyWriteBasename(name: string): boolean {
@@ -271,8 +273,8 @@ export function createDefaultPolicy(
       ],
     },
     network: {
-      allowedDomains: [],
-      deniedDomains: [],
+      allowedDomains: [...(options.network?.allowedDomains ?? [])],
+      deniedDomains: [...(options.network?.deniedDomains ?? [])],
       allowLocalBinding: false,
       allowAllUnixSockets: false,
       allowUnixSockets: [],

package/src/subagent.ts

@@ -104,6 +104,103 @@ function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
+/**
+ * Minimal structural shape of a registry model used for validation. Kept as
+ * a structural type so this pure helper does not depend on the host coding
+ * agent's `Model` type.
+ */
+export interface SubagentModelLike {
+  /** Bare model id, e.g. `claude-3-5-sonnet` (not provider-prefixed). */
+  id: string;
+  /** Provider id, e.g. `anthropic`. */
+  provider: string;
+}
+
+export type SubagentModelValidation =
+  | { ok: true; mode: "inherit" }
+  | { ok: true; mode: "explicit" }
+  | { ok: false; error: string };
+
+// Mirrors pi's valid thinking levels (cli/args.ts VALID_THINKING_LEVELS).
+const VALID_THINKING_LEVELS = new Set([
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+]);
+
+/**
+ * Split an optional trailing `:thinking` suffix off a model pattern. A suffix
+ * that is not a valid thinking level is treated as part of the model id (pi
+ * supports model ids containing colons, e.g. OpenRouter's `:exacto`).
+ */
+export function splitModelThinking(
+  modelSpec: string,
+): { base: string; thinking?: string } {
+  const colon = modelSpec.lastIndexOf(":");
+  if (colon === -1) return { base: modelSpec };
+  const suffix = modelSpec.slice(colon + 1);
+  if (VALID_THINKING_LEVELS.has(suffix)) {
+    return { base: modelSpec.slice(0, colon), thinking: suffix };
+  }
+  return { base: modelSpec };
+}
+
+/**
+ * Fail-fast validation of an explicit subagent model before a child Pi spawns.
+ *
+ * Rules (see docs/compat-notes.md / Plan.md phase C2):
+ *  - `undefined`/empty -> inherit host behavior, never validated.
+ *  - `provider/model` -> requires an exact match on `${provider}/${modelId}`.
+ *  - bare model id -> preferred provider first; otherwise accept only when
+ *    globally unique; otherwise reject as ambiguous and ask for the full id.
+ *  - a valid trailing `:thinking` suffix is stripped for base validation and
+ *    preserved in the original pattern passed to the child.
+ *
+ * Only `start`/`handoff` (process-spawning actions) should call this.
+ */
+export function validateSubagentModel(
+  modelSpec: string | undefined,
+  available: readonly SubagentModelLike[],
+  preferredProvider: string | undefined,
+): SubagentModelValidation {
+  const spec = (modelSpec ?? "").trim();
+  if (!spec) return { ok: true, mode: "inherit" };
+  const { base } = splitModelThinking(spec);
+
+  // Full `provider/model` reference: require an exact registry match.
+  const fullMatch = available.find((m) => `${m.provider}/${m.id}` === base);
+  if (fullMatch) return { ok: true, mode: "explicit" };
+
+  // Contains a `/`, so it was intended as a full provider/model reference that
+  // did not match any registered model. Do not fall back to bare matching.
+  if (base.includes("/")) {
+    return {
+      ok: false,
+      error: `subagent start requires an available model; unknown model '${base}'`, // eslint-disable-line
+    };
+  }
+
+  // Bare model id.
+  const matches = available.filter((m) => m.id === base);
+  if (matches.length === 0) {
+    return {
+      ok: false,
+      error: `subagent start requires an available model; unknown model '${base}'`, // eslint-disable-line
+    };
+  }
+  const preferred = matches.find((m) => m.provider === preferredProvider);
+  if (preferred) return { ok: true, mode: "explicit" };
+  if (matches.length === 1) return { ok: true, mode: "explicit" };
+  return {
+    ok: false,
+    error: `subagent start requires an unambiguous model; '${base}' is available under multiple providers (${matches.map((m) => m.provider).join(", ")}). Use provider/model or set PI_MODEL to disambiguate.`,
+  };
+}
+
 export function resolvePiInvocation(): ProcessInvocation {
   const currentEntry = process.argv[1];
   if (