@erichll/pi-sandbox 0.15.2 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.16.0 - 2026-09-05
+
+- Depend on the coordinated `@erichll/pi-auto-review 0.16.0` release.
+- Replace the obsolete `externalWorkerIsolation` integration with the required
+  `native-background-tools` protection mode for `pi-subagents 0.65.0`.
+- Require a validated canonical native-agent whitelist, explicit asynchronous
+  launches, ambient child extensions, disabled nested delegation, and
+  `scheduledRuns.enabled=false`.
+- Register the upstream capability ceiling with only `bash`, `read`, `grep`,
+  `find`, and `ls`; child writes therefore pass through sandboxed Bash while
+  `write`, `edit`, MCP, and extension tools are unavailable.
+- Reject external runners, all workflow forms, schedules, resume, and agent or
+  workflow management mutations. Protected mode supports only explicit async
+  direct-agent launches because 0.65.0 workflow children disable ambient
+  extensions.
+- Remove the obsolete external launcher, supervisor, network-policy transport,
+  and FleetView bridge. This mode is a tool boundary, not OS process isolation;
+  use the default `builtin` provider when whole-worker isolation is required.
+
+## 0.15.3 - 2026-09-03
+
+- Reviewer decisions on sandbox network boundaries inherit the fenced-JSON
+  tolerance fix through the `@erichll/pi-auto-review` 0.15.3 dependency
+  (strict decision-schema validation unchanged).
+- Move the tested `pi-subagents` baseline to 0.64.0.
+- Verify watchdog launch blocking occurs before worker spawn and leaves no child
+  transcript in the model-backed gate.
+- Exercise `watchdog_diff` against read-only Git worktree metadata through the
+  real outer-sandbox launcher.
+
 ## 0.15.2 - 2026-09-02
 
 - No user-facing changes. Compatibility-verification release only: the

package/README.md

@@ -9,7 +9,7 @@ also run complete process-backed subagent trees inside independent sandboxes.
 - [Security model](#security-model)
 - [Linux requirements](#linux-requirements)
 - [Subagent provider](#subagent-provider)
-  - [`pi-subagents` 0.63.0 capability boundary](#pi-subagents-0630-capability-boundary)
+  - [`pi-subagents` 0.65.0 native-background tool boundary](#pi-subagents-0650-native-background-tool-boundary)
 - [Network domain policy](#network-domain-policy)
 - [Optional host IPC fallback](#optional-host-ipc-fallback)
 - [Additional trusted read paths](#additional-trusted-read-paths)
@@ -81,8 +81,7 @@ new installs.
 ```json
 {
   "subagents": {
-    "provider": "builtin",
-    "externalWorkerIsolation": "off"
+    "provider": "builtin"
   }
 }
 ```
@@ -91,55 +90,57 @@ Supported modes:
 
 - `builtin` (default): register the process-backed `subagent` tool and sandbox
   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 while `externalWorkerIsolation` is `off`.
+- `pi-subagents`: let `pi-subagents 0.65.0` own orchestration under the required
+  native-background tool boundary described below.
 - `off`: protect Bash only.
 
-### `pi-subagents` 0.63.0 capability boundary
+### `pi-subagents` 0.65.0 native-background tool boundary
 
-`pi-sandbox` verifies the following combination in its test suite and release
-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. The
-published peer range remains `>=0.50.0`; this documents the current tested
-development baseline, not a runtime minimum.
+This provider is intentionally locked to exactly `pi-subagents 0.65.0` and
+fails closed if its public ceiling API or internal discovery layout drifts.
+Configure both the protection mode and a non-empty canonical whitelist:
 
-| Capability | `builtin` | `pi-subagents` 0.63.0 |
+```json
+{
+  "subagents": {
+    "provider": "pi-subagents",
+    "protection": "native-background-tools",
+    "allowedNativeAgents": ["worker", "reviewer", "scout"]
+  }
+}
+```
+
+The `pi-subagents` config at
+`~/.pi/agent/extensions/subagent/config.json` must also contain
+`"scheduledRuns": { "enabled": false }`. Every launch must explicitly set
+`async: true`. Only direct single-agent launches are supported. In 0.65.0,
+public `workflowScript` / `workflowScriptPath` children disable ambient
+extensions, so both are rejected along with named workflows, schedules,
+configuration mutations, resume, nested subagents, and external runners.
+
+Every child is constrained by the upstream capability ceiling to `bash`,
+`read`, `grep`, `find`, and `ls`. The child loads ambient extensions and must
+acknowledge `@erichll:pi-sandbox`; writes can therefore occur only through the
+sandboxed Bash tool. `write`, `edit`, MCP, and other extension tools are not
+available.
+
+| Capability | `builtin` | `pi-subagents` 0.65.0 protected mode |
 | --- | --- | --- |
-| Outer worker sandbox | Yes | Opt-in (`externalWorkerIsolation: "enforce"`) |
+| Outer worker sandbox | Yes | No |
 | Bash sandbox | Yes | Yes |
 | Persistent follow-up | Yes | Yes |
-| `workflowScript`, missions, schedules | No | Yes |
-| Named workflow resources | No | Yes |
-| permission-system parent forwarding | Not required | Verified by compatibility gate |
+| Public async `workflowScript` | No | No (ambient extensions disabled upstream) |
+| Schedules / named workflow resources | No | No |
+| Child tools | Configured parent tools | Fixed five-tool ceiling |
 
-Moving the tested baseline requires re-running `npm run gate:external-isolation`
-and, before a release, the model-backed `npm run gate:pi-subagents`. See
+Before a release, run the deterministic and model-backed portions of
+`npm run gate:pi-subagents`. See
 `docs/compat-notes.md` for the recorded compatibility seams and how each is
 verified on upgrade.
 
-The 0.63.0 baseline also exercises tasks passed as an `@task.md` argument and
-standard Git worktree metadata (`.git` pointer plus `commondir`) through the
-real outer-sandbox launcher. Worktrunk itself is not a dependency; provider
-selection remains upstream behavior.
-
-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 the old static multi-agent controls; `workflowScript` remains the
-public multi-agent orchestration surface. Current releases also accept a direct
-single-child `{ agent, task }` launch. The compatibility gate deliberately uses
-`return runs.run('main', { agent, task })` so the single-child probe continues
-to exercise the workflow executor and its isolation seam.
-
 The configuration parser rejects malformed JSON, unknown fields, and unknown
-providers instead of silently weakening isolation.
+providers instead of silently weakening isolation. All legacy
+`externalWorkerIsolation` configurations produce a migration error.
 
 ## Network domain policy
 
@@ -177,9 +178,8 @@ The precedence is deterministic:
 
 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.
+The same trusted arrays govern main-agent Bash, built-in subagents, and the
+sandboxed Bash tool loaded by protected native `pi-subagents` children.
 
 Domain allowlists are not a complete data-loss-prevention boundary. A
 multi-tenant or user-uploadable destination such as `github.com` can itself be
@@ -188,28 +188,9 @@ 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
-{
-  "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.
+Native background runner initialization itself is outside the OS sandbox.
+Only the child's Bash modification channel is sandboxed. Select `builtin` when
+the entire worker process tree must be contained by Sandbox Runtime.
 
 ## Optional host IPC fallback
 
@@ -295,17 +276,11 @@ 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.
+`gate:pi-subagents` verifies the pinned package layout, discovery behavior,
+capability ceiling, and protected launch policy in an isolated temporary agent
+directory. It never reads or updates production Pi configuration. Model-backed
+acceptance requires `PI_SUBAGENTS_GATE_MODEL` and an already-exported matching
+credential; missing prerequisites are reported as `SKIP`.
 
 The test suite covers real Linux Sandbox Runtime enforcement when its native
 dependencies are installed, plus deterministic broker, network approval,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erichll/pi-sandbox",
-  "version": "0.15.2",
+  "version": "0.16.0",
   "description": "Linux (bubblewrap) and macOS (Seatbelt) process sandbox for Pi backed by Anthropic's @anthropic-ai/sandbox-runtime. Fail-closed static filesystem policy plus per-connection network approval from pi-auto-review; sandboxes main-agent Bash and built-in subagent process trees.",
   "type": "module",
   "license": "Apache-2.0",
@@ -51,11 +51,12 @@
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.75",
-    "@erichll/pi-auto-review": "0.15.2"
+    "@erichll/pi-auto-review": "0.16.0",
+    "jiti": "2.7.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.1",
-    "pi-subagents": ">=0.50.0",
+    "@earendil-works/pi-coding-agent": "^0.85.0",
+    "pi-subagents": "0.65.0",
     "typebox": ">=1.0.0"
   },
   "peerDependenciesMeta": {
@@ -64,9 +65,10 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@earendil-works/pi-coding-agent": "^0.85.0",
+    "@earendil-works/pi-server": "^0.85.0",
     "@types/node": "^26.2.0",
-    "pi-subagents": "0.63.0",
+    "pi-subagents": "0.65.0",
     "typescript": "^6.0.3"
   }
 }

package/src/config.ts

@@ -28,7 +28,8 @@ export type NetworkConfig = {
 export type PiSandboxConfig = {
   subagents: {
     provider: SubagentProvider;
-    externalWorkerIsolation: "off" | "enforce";
+    protection?: "native-background-tools";
+    allowedNativeAgents?: readonly string[];
   };
   filesystem: {
     additionalAllowRead: readonly string[];
@@ -47,7 +48,6 @@ export const DEFAULT_PI_SANDBOX_CONFIG: Readonly<PiSandboxConfig> = Object.freez
   {
     subagents: Object.freeze({
       provider: "builtin",
-      externalWorkerIsolation: "off",
     }),
     filesystem: Object.freeze({
       additionalAllowRead: Object.freeze([]),
@@ -138,9 +138,14 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
     );
   }
   const subagents = value.subagents ?? {};
+  if (Object.hasOwn(subagents, "externalWorkerIsolation")) {
+    throw new Error(
+      "invalid pi-sandbox configuration: subagents.externalWorkerIsolation was removed in 0.16.0; migrate pi-subagents to protection 'native-background-tools' with allowedNativeAgents, or use provider 'builtin' for OS-level worker isolation",
+    );
+  }
   rejectUnknownKeys(
     subagents,
-    ["provider", "externalWorkerIsolation"],
+    ["provider", "protection", "allowedNativeAgents"],
     "subagents",
   );
 
@@ -154,17 +159,39 @@ 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"
-  ) {
+  const protection = subagents.protection;
+  const allowedNativeAgents = subagents.allowedNativeAgents;
+  if (provider === "pi-subagents" && protection !== "native-background-tools") {
     throw new Error(
-      "invalid pi-sandbox configuration: subagents.externalWorkerIsolation must be off or enforce",
+      "invalid pi-sandbox configuration: provider 'pi-subagents' requires subagents.protection 'native-background-tools'; migrate legacy configurations explicitly",
     );
   }
+  if (provider !== "pi-subagents" && (protection !== undefined || allowedNativeAgents !== undefined)) {
+    throw new Error(
+      "invalid pi-sandbox configuration: subagents.protection and allowedNativeAgents are only valid with provider 'pi-subagents'",
+    );
+  }
+  if (provider === "pi-subagents") {
+    if (!Array.isArray(allowedNativeAgents) || allowedNativeAgents.length === 0) {
+      throw new Error(
+        "invalid pi-sandbox configuration: subagents.allowedNativeAgents must be a non-empty array of canonical agent names",
+      );
+    }
+    if (allowedNativeAgents.some((name) =>
+      typeof name !== "string" ||
+      name !== name.trim() ||
+      !/^[A-Za-z0-9_.:-]+$/u.test(name)
+    )) {
+      throw new Error(
+        "invalid pi-sandbox configuration: subagents.allowedNativeAgents must contain only canonical agent names",
+      );
+    }
+    if (new Set(allowedNativeAgents).size !== allowedNativeAgents.length) {
+      throw new Error(
+        "invalid pi-sandbox configuration: subagents.allowedNativeAgents must not contain duplicates",
+      );
+    }
+  }
 
   if (value.filesystem !== undefined && !isRecord(value.filesystem)) {
     throw new Error(
@@ -291,7 +318,12 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
   return {
     subagents: {
       provider: provider as SubagentProvider,
-      externalWorkerIsolation,
+      ...(provider === "pi-subagents"
+        ? {
+            protection: "native-background-tools" as const,
+            allowedNativeAgents: [...(allowedNativeAgents as string[])],
+          }
+        : {}),
     },
     filesystem: {
       additionalAllowRead: [...new Set(additionalAllowRead)],
@@ -314,8 +346,6 @@ function defaultPiSandboxConfig(): PiSandboxConfig {
   return {
     subagents: {
       provider: DEFAULT_PI_SANDBOX_CONFIG.subagents.provider,
-      externalWorkerIsolation:
-        DEFAULT_PI_SANDBOX_CONFIG.subagents.externalWorkerIsolation,
     },
     filesystem: {
       additionalAllowRead: [