@erichll/pi-sandbox 0.20.1 → 0.21.1

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.21.1 - 2026-09-26
+
+- Alias `@earendil-works/pi-tui` for the `jiti` instance that loads the
+  `pi-subagents` internals. `pi-subagents` imports that host peer from its
+  internal modules but does not ship it, and Pi's own extension loader aliases
+  it to the copy inside the running Pi package. The protected-mode loader
+  created its own `jiti` instance without that alias, so installs where the peer
+  is not hoisted next to the extension (for example the global
+  `~/.pi/agent/npm` tree) failed to load as soon as `subagents.provider` was
+  `pi-subagents` with `pi-subagents compatibility failure: Cannot find module
+  '@earendil-works/pi-tui'`. The alias is computed host-first from the running Pi
+  package (`process.argv[1]`, `PI_PACKAGE_DIR`) and falls back to plain
+  resolution from the extension tree; an unresolvable host peer still fails
+  closed with that explicit error.
+- Add regression coverage for host alias resolution, including a `jiti` load in
+  a tree where `@earendil-works/pi-tui` is unreachable without the alias.
+
+## 0.21.0 - 2026-09-25
+
+- Support project-level configuration at `.pi/extensions/pi-sandbox/config.json`.
+  When present, project configuration is merged with global configuration:
+  array permissions (`additionalAllowRead`, `allowedDomains`, `deniedDomains`,
+  `preflightCommandPrefixes`) form deduplicated unions, and scalar settings
+  (`subagents.provider`, `hostIPC.mode`, `hostIPC.retryOnUnixSocketError`)
+  allow project-level overrides.
+- Harden project-level configuration: added `.pi/extensions/pi-sandbox/config.json`
+  to default sandbox `filesystem.denyWrite` policy. Project configuration is
+  strictly read-only for sandboxed execution processes.
+- Remove legacy configuration compatibility: removed fallback loading for
+  `~/.pi/agent/pi-sandbox.json` and dropped deprecated `externalWorkerIsolation`
+  migration parsing.
+- Pair with `@erichll/pi-auto-review` `^0.21.0`.
+
 ## 0.20.1 - 2026-09-24
 
 - Move `@anthropic-ai/sandbox-runtime` from `devDependencies` to runtime

package/README.md

@@ -71,12 +71,7 @@ macOS uses built-in Seatbelt support but still requires `ripgrep`.
 
 ## Subagent provider
 
-The provider is selected only from the trusted global file
-`~/.pi/agent/extensions/pi-sandbox/config.json`:
-
-If that file is missing, `pi-sandbox` still loads the legacy path
-`~/.pi/agent/pi-sandbox.json` when present. Prefer the extension-local path for
-new installs.
+The provider is selected from the configuration (`~/.pi/agent/extensions/pi-sandbox/config.json` globally or `.pi/extensions/pi-sandbox/config.json` project-locally):
 
 ```json
 {
@@ -99,7 +94,10 @@ Supported modes:
 This provider supports the `pi-subagents >=0.66.0` line (validated through
 0.71.0) and fails closed if its public ceiling API, module layout, or internal
 discovery layout drifts. The peer dependency is a floor with no upper pin; the
-loader's explicit export and layout checks are the real gate.
+loader's explicit export and layout checks are the real gate. The loader also
+aliases `@earendil-works/pi-tui`, a host peer that the `pi-subagents` internals
+import but do not ship, to the copy inside the running Pi package, so installs
+where it is not hoisted next to the extension still load.
 Configure both the protection mode and a non-empty canonical whitelist:
 
 ```json
@@ -141,14 +139,13 @@ Before a release, run the deterministic and model-backed portions of
 verified on upgrade.
 
 The configuration parser rejects malformed JSON, unknown fields, and unknown
-providers instead of silently weakening isolation. All legacy
-`externalWorkerIsolation` configurations produce a migration error.
+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.
+Domain authorization can be configured globally at
+`~/.pi/agent/extensions/pi-sandbox/config.json` or project-locally at
+`.pi/extensions/pi-sandbox/config.json` (merged with union semantics):
 
 ```json
 {
@@ -255,9 +252,23 @@ Persistent built-in sessions support `start`, `follow_up`, `wait`, `status`,
 `stop`, and nested `handoff` operations. At most four sessions are live at
 once, and nesting depth is capped at three.
 
-## Installation
+## Project-level configuration and read-only protection
+
+In addition to user-level configuration at `~/.pi/agent/extensions/pi-sandbox/config.json`,
+`pi-sandbox` supports project-level configuration placed at:
+
+```
+.pi/extensions/pi-sandbox/config.json
+```
+
+When present, project configuration is merged with global configuration:
+- Array policies (`additionalAllowRead`, `allowedDomains`, `deniedDomains`, `preflightCommandPrefixes`) form a deduplicated union.
+- Scalar settings (`provider`, `mode`, `retryOnUnixSocketError`) allow project-level overrides.
 
-Load `pi-auto-review` first so its broker is available:
+**Read-only Security Guarantee**:
+Project-level configuration is explicitly protected in the sandbox policy (`denyWrite`),
+meaning sandboxed tasks can read `.pi/extensions/pi-sandbox/config.json` but can never
+tamper with or overwrite it from within the sandbox.
 
 ```bash
 pi install npm:@erichll/pi-auto-review

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erichll/pi-sandbox",
-  "version": "0.20.1",
+  "version": "0.21.1",
   "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,7 +51,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.77",
-    "@erichll/pi-auto-review": "^0.20.1",
+    "@erichll/pi-auto-review": "^0.21.0",
     "jiti": "2.7.0"
   },
   "peerDependencies": {

package/src/config.ts

@@ -40,8 +40,10 @@ export type PiSandboxConfig = {
 
 export type LoadPiSandboxConfigOptions = {
   path?: string;
-  /** Override home directory when resolving default/legacy trusted paths. */
+  /** Override home directory when resolving default trusted paths. */
   home?: string;
+  /** Override workspace directory when resolving project-level config path. */
+  cwd?: string;
 };
 
 export const DEFAULT_PI_SANDBOX_CONFIG: Readonly<PiSandboxConfig> = Object.freeze(
@@ -75,9 +77,15 @@ export function getPiSandboxConfigPath(home = homedir()): string {
   );
 }
 
-/** Legacy trusted path used before the extension-local config layout. */
-export function getLegacyPiSandboxConfigPath(home = homedir()): string {
-  return join(home, ".pi", "agent", "pi-sandbox.json");
+export const PROJECT_PI_SANDBOX_CONFIG_PATH = join(
+  ".pi",
+  "extensions",
+  "pi-sandbox",
+  "config.json",
+);
+
+export function getProjectPiSandboxConfigPath(cwd = process.cwd()): string {
+  return join(cwd, PROJECT_PI_SANDBOX_CONFIG_PATH);
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -122,7 +130,20 @@ function hasValidDomainLabels(
   );
 }
 
-export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
+export type PartialPiSandboxConfig = {
+  subagents?: {
+    provider?: SubagentProvider;
+    protection?: "native-background-tools";
+    allowedNativeAgents?: readonly string[];
+  };
+  filesystem?: {
+    additionalAllowRead?: readonly string[];
+  };
+  network?: Partial<NetworkConfig>;
+  hostIPC?: Partial<HostIPCConfig>;
+};
+
+export function parsePiSandboxConfigRaw(value: unknown): PartialPiSandboxConfig {
   if (!isRecord(value)) {
     throw new Error("invalid pi-sandbox configuration: root must be an object");
   }
@@ -132,212 +153,271 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
     "root",
   );
 
-  if (value.subagents !== undefined && !isRecord(value.subagents)) {
-    throw new Error(
-      "invalid pi-sandbox configuration: subagents must be an object",
-    );
-  }
-  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", "protection", "allowedNativeAgents"],
-    "subagents",
-  );
-
-  const provider =
-    subagents.provider ?? DEFAULT_PI_SANDBOX_CONFIG.subagents.provider;
-  if (
-    typeof provider !== "string" ||
-    !SUBAGENT_PROVIDERS.includes(provider as SubagentProvider)
-  ) {
-    throw new Error(
-      `invalid pi-sandbox configuration: subagents.provider must be one of ${SUBAGENT_PROVIDERS.join(", ")}`,
-    );
-  }
-  const protection = subagents.protection;
-  const allowedNativeAgents = subagents.allowedNativeAgents;
-  if (provider === "pi-subagents" && protection !== "native-background-tools") {
-    throw new Error(
-      "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'",
+  let parsedSubagents: PartialPiSandboxConfig["subagents"] | undefined;
+  if (value.subagents !== undefined) {
+    if (!isRecord(value.subagents)) {
+      throw new Error(
+        "invalid pi-sandbox configuration: subagents must be an object",
+      );
+    }
+    rejectUnknownKeys(
+      value.subagents,
+      ["provider", "protection", "allowedNativeAgents"],
+      "subagents",
     );
-  }
-  if (provider === "pi-subagents") {
-    if (!Array.isArray(allowedNativeAgents) || allowedNativeAgents.length === 0) {
+    const provider = value.subagents.provider;
+    if (
+      provider !== undefined &&
+      (typeof provider !== "string" ||
+        !SUBAGENT_PROVIDERS.includes(provider as SubagentProvider))
+    ) {
       throw new Error(
-        "invalid pi-sandbox configuration: subagents.allowedNativeAgents must be a non-empty array of canonical agent names",
+        `invalid pi-sandbox configuration: subagents.provider must be one of ${SUBAGENT_PROVIDERS.join(", ")}`,
       );
     }
-    if (allowedNativeAgents.some((name) =>
-      typeof name !== "string" ||
-      name !== name.trim() ||
-      !/^[A-Za-z0-9_.:-]+$/u.test(name)
-    )) {
+    const protection = value.subagents.protection;
+    const allowedNativeAgents = value.subagents.allowedNativeAgents;
+    if (provider === "pi-subagents" && protection !== "native-background-tools") {
       throw new Error(
-        "invalid pi-sandbox configuration: subagents.allowedNativeAgents must contain only canonical agent names",
+        "invalid pi-sandbox configuration: provider 'pi-subagents' requires subagents.protection 'native-background-tools'; migrate legacy configurations explicitly",
       );
     }
-    if (new Set(allowedNativeAgents).size !== allowedNativeAgents.length) {
+    if (provider !== undefined && provider !== "pi-subagents" && (protection !== undefined || allowedNativeAgents !== undefined)) {
       throw new Error(
-        "invalid pi-sandbox configuration: subagents.allowedNativeAgents must not contain duplicates",
+        "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",
+        );
+      }
+    }
+    parsedSubagents = {
+      ...(provider !== undefined ? { provider: provider as SubagentProvider } : {}),
+      ...(provider === "pi-subagents"
+        ? {
+            protection: "native-background-tools" as const,
+            allowedNativeAgents: [...(allowedNativeAgents as string[])],
+          }
+        : {}),
+    };
   }
 
-  if (value.filesystem !== undefined && !isRecord(value.filesystem)) {
-    throw new Error(
-      "invalid pi-sandbox configuration: filesystem must be an object",
-    );
-  }
-  const filesystem = value.filesystem ?? {};
-  rejectUnknownKeys(
-    filesystem,
-    ["additionalAllowRead"],
-    "filesystem",
-  );
-  const additionalAllowRead =
-    filesystem.additionalAllowRead ??
-    DEFAULT_PI_SANDBOX_CONFIG.filesystem.additionalAllowRead;
-  if (
-    !Array.isArray(additionalAllowRead) ||
-    additionalAllowRead.some(
-      (path) =>
-        typeof path !== "string" ||
-        path.trim() === "" ||
-        !isAbsolute(path),
-    )
-  ) {
-    throw new Error(
-      "invalid pi-sandbox configuration: filesystem.additionalAllowRead must be an array of absolute paths",
+  let parsedFilesystem: PartialPiSandboxConfig["filesystem"] | undefined;
+  if (value.filesystem !== undefined) {
+    if (!isRecord(value.filesystem)) {
+      throw new Error(
+        "invalid pi-sandbox configuration: filesystem must be an object",
+      );
+    }
+    rejectUnknownKeys(
+      value.filesystem,
+      ["additionalAllowRead"],
+      "filesystem",
     );
+    const additionalAllowRead = value.filesystem.additionalAllowRead;
+    if (additionalAllowRead !== undefined) {
+      if (
+        !Array.isArray(additionalAllowRead) ||
+        additionalAllowRead.some(
+          (path) =>
+            typeof path !== "string" ||
+            path.trim() === "" ||
+            !isAbsolute(path),
+        )
+      ) {
+        throw new Error(
+          "invalid pi-sandbox configuration: filesystem.additionalAllowRead must be an array of absolute paths",
+        );
+      }
+      parsedFilesystem = {
+        additionalAllowRead: [...new Set(additionalAllowRead)],
+      };
+    } else {
+      parsedFilesystem = {};
+    }
   }
 
-  if (value.network !== undefined && !isRecord(value.network)) {
-    throw new Error(
-      "invalid pi-sandbox configuration: network must be an object",
+  let parsedNetwork: PartialPiSandboxConfig["network"] | undefined;
+  if (value.network !== undefined) {
+    if (!isRecord(value.network)) {
+      throw new Error(
+        "invalid pi-sandbox configuration: network must be an object",
+      );
+    }
+    rejectUnknownKeys(
+      value.network,
+      ["allowedDomains", "deniedDomains"],
+      "network",
     );
+    const normalizeDomainList = (
+      key: "allowedDomains" | "deniedDomains",
+    ): string[] | undefined => {
+      const configured = (value.network as Record<string, unknown>)[key];
+      if (configured === undefined) return undefined;
+      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 allowed = normalizeDomainList("allowedDomains");
+    const denied = normalizeDomainList("deniedDomains");
+    parsedNetwork = {
+      ...(allowed !== undefined ? { allowedDomains: allowed } : {}),
+      ...(denied !== undefined ? { deniedDomains: denied } : {}),
+    };
   }
-  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() === "",
-      )
-    ) {
+
+  let parsedHostIPC: PartialPiSandboxConfig["hostIPC"] | undefined;
+  if (value.hostIPC !== undefined) {
+    if (!isRecord(value.hostIPC)) {
       throw new Error(
-        `invalid pi-sandbox configuration: network.${key} must be an array of non-empty strings`,
+        "invalid pi-sandbox configuration: hostIPC must be an object",
       );
     }
-    const normalized = [
-      ...new Set(configured.map((pattern) => pattern.trim())),
-    ];
-    const invalidIndex = normalized.findIndex(
-      (pattern) => !hasValidDomainLabels(pattern, key === "deniedDomains"),
+    rejectUnknownKeys(
+      value.hostIPC,
+      ["mode", "preflightCommandPrefixes", "retryOnUnixSocketError"],
+      "hostIPC",
     );
-    if (invalidIndex >= 0) {
+    const mode = value.hostIPC.mode;
+    if (
+      mode !== undefined &&
+      (typeof mode !== "string" ||
+        !HOST_IPC_MODES.includes(mode as HostIPCMode))
+    ) {
       throw new Error(
-        `invalid pi-sandbox configuration: network.${key}[${invalidIndex}] contains an invalid domain pattern`,
+        `invalid pi-sandbox configuration: hostIPC.mode must be one of ${HOST_IPC_MODES.join(", ")}`,
       );
     }
-    const candidate = {
-      allowedDomains: key === "allowedDomains" ? normalized : [],
-      deniedDomains: key === "deniedDomains" ? normalized : [],
-    };
-    const result = NetworkConfigSchema.safeParse(candidate);
-    if (!result.success) {
-      const issue = result.error.issues[0];
+    const preflight = value.hostIPC.preflightCommandPrefixes;
+    if (preflight !== undefined) {
+      if (
+        !Array.isArray(preflight) ||
+        preflight.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 retry = value.hostIPC.retryOnUnixSocketError;
+    if (retry !== undefined && typeof retry !== "boolean") {
       throw new Error(
-        `invalid pi-sandbox configuration: network.${key}${typeof issue?.path[1] === "number" ? `[${issue.path[1]}]` : ""} ${issue?.message ?? "contains an invalid domain pattern"}`,
+        "invalid pi-sandbox configuration: hostIPC.retryOnUnixSocketError must be a boolean",
       );
     }
-    return normalized;
+    parsedHostIPC = {
+      ...(mode !== undefined ? { mode: mode as HostIPCMode } : {}),
+      ...(preflight !== undefined
+        ? {
+            preflightCommandPrefixes: [
+              ...new Set(preflight.map((prefix) => prefix.trim())),
+            ],
+          }
+        : {}),
+      ...(retry !== undefined ? { retryOnUnixSocketError: retry } : {}),
+    };
+  }
+
+  return {
+    ...(parsedSubagents !== undefined ? { subagents: parsedSubagents } : {}),
+    ...(parsedFilesystem !== undefined ? { filesystem: parsedFilesystem } : {}),
+    ...(parsedNetwork !== undefined ? { network: parsedNetwork } : {}),
+    ...(parsedHostIPC !== undefined ? { hostIPC: parsedHostIPC } : {}),
   };
-  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",
-    );
-  }
-  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",
-    );
-  }
+export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
+  const raw = parsePiSandboxConfigRaw(value);
+  const provider =
+    raw.subagents?.provider ?? DEFAULT_PI_SANDBOX_CONFIG.subagents.provider;
+  const isPiSubagents = provider === "pi-subagents";
 
   return {
     subagents: {
-      provider: provider as SubagentProvider,
-      ...(provider === "pi-subagents"
+      provider,
+      ...(isPiSubagents
         ? {
             protection: "native-background-tools" as const,
-            allowedNativeAgents: [...(allowedNativeAgents as string[])],
+            allowedNativeAgents: [
+              ...(raw.subagents?.allowedNativeAgents ?? []),
+            ],
           }
         : {}),
     },
     filesystem: {
-      additionalAllowRead: [...new Set(additionalAllowRead)],
+      additionalAllowRead: [
+        ...(raw.filesystem?.additionalAllowRead ??
+          DEFAULT_PI_SANDBOX_CONFIG.filesystem.additionalAllowRead),
+      ],
     },
     network: {
-      allowedDomains: [...allowedDomains],
-      deniedDomains: [...deniedDomains],
+      allowedDomains: [
+        ...(raw.network?.allowedDomains ??
+          DEFAULT_PI_SANDBOX_CONFIG.network.allowedDomains),
+      ],
+      deniedDomains: [
+        ...(raw.network?.deniedDomains ??
+          DEFAULT_PI_SANDBOX_CONFIG.network.deniedDomains),
+      ],
     },
     hostIPC: {
-      mode: hostIPCMode as HostIPCMode,
+      mode: raw.hostIPC?.mode ?? DEFAULT_PI_SANDBOX_CONFIG.hostIPC.mode,
       preflightCommandPrefixes: [
-        ...new Set(preflightCommandPrefixes.map((prefix) => prefix.trim())),
+        ...(raw.hostIPC?.preflightCommandPrefixes ??
+          DEFAULT_PI_SANDBOX_CONFIG.hostIPC.preflightCommandPrefixes),
       ],
-      retryOnUnixSocketError,
+      retryOnUnixSocketError:
+        raw.hostIPC?.retryOnUnixSocketError ??
+        DEFAULT_PI_SANDBOX_CONFIG.hostIPC.retryOnUnixSocketError,
     },
   };
 }
@@ -401,32 +481,123 @@ function parsePiSandboxConfigFile(path: string, source: string): PiSandboxConfig
   return parsePiSandboxConfig(value);
 }
 
+function parsePiSandboxConfigFileRaw(path: string, source: string): PartialPiSandboxConfig {
+  let value: unknown;
+  try {
+    value = JSON.parse(source);
+  } catch (error) {
+    throw new Error(`invalid JSON in pi-sandbox configuration at ${path}`, {
+      cause: error,
+    });
+  }
+  return parsePiSandboxConfigRaw(value);
+}
+
+export function mergePiSandboxConfigs(
+  trusted: PiSandboxConfig,
+  project: PartialPiSandboxConfig,
+): PiSandboxConfig {
+  const provider = project.subagents?.provider ?? trusted.subagents.provider;
+  const isPiSubagents = provider === "pi-subagents";
+
+  let allowedNativeAgents: string[] | undefined;
+  if (isPiSubagents) {
+    const trustedAgents = trusted.subagents.allowedNativeAgents ?? [];
+    const projectAgents = project.subagents?.allowedNativeAgents ?? [];
+    allowedNativeAgents = [...new Set([...trustedAgents, ...projectAgents])];
+  }
+
+  return {
+    subagents: {
+      provider,
+      ...(isPiSubagents
+        ? {
+            protection: "native-background-tools" as const,
+            allowedNativeAgents,
+          }
+        : {}),
+    },
+    filesystem: {
+      additionalAllowRead: [
+        ...new Set([
+          ...trusted.filesystem.additionalAllowRead,
+          ...(project.filesystem?.additionalAllowRead ?? []),
+        ]),
+      ],
+    },
+    network: {
+      allowedDomains: [
+        ...new Set([
+          ...trusted.network.allowedDomains,
+          ...(project.network?.allowedDomains ?? []),
+        ]),
+      ],
+      deniedDomains: [
+        ...new Set([
+          ...trusted.network.deniedDomains,
+          ...(project.network?.deniedDomains ?? []),
+        ]),
+      ],
+    },
+    hostIPC: {
+      mode: project.hostIPC?.mode ?? trusted.hostIPC.mode,
+      preflightCommandPrefixes: [
+        ...new Set([
+          ...trusted.hostIPC.preflightCommandPrefixes,
+          ...(project.hostIPC?.preflightCommandPrefixes ?? []),
+        ]),
+      ],
+      retryOnUnixSocketError:
+        project.hostIPC?.retryOnUnixSocketError ??
+        trusted.hostIPC.retryOnUnixSocketError,
+    },
+  };
+}
+
 export function loadPiSandboxConfig(
   options: LoadPiSandboxConfigOptions = {},
 ): PiSandboxConfig {
-  const path = options.path ?? getPiSandboxConfigPath(options.home);
+  if (options.path !== undefined) {
+    const path = options.path;
+    try {
+      return parsePiSandboxConfigFile(path, readPiSandboxConfigFile(path));
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        return defaultPiSandboxConfig();
+      }
+      throw error;
+    }
+  }
+
+  const globalPath = getPiSandboxConfigPath(options.home);
+  let globalConfig: PiSandboxConfig | undefined;
   try {
-    return parsePiSandboxConfigFile(path, readPiSandboxConfigFile(path));
+    globalConfig = parsePiSandboxConfigFile(
+      globalPath,
+      readPiSandboxConfigFile(globalPath),
+    );
   } catch (error) {
     if (!isNotFoundError(error)) {
       throw error;
     }
   }
 
-  // Only fall back to the legacy path when loading the default trusted location.
-  if (options.path === undefined) {
-    const legacyPath = getLegacyPiSandboxConfigPath(options.home);
-    try {
-      return parsePiSandboxConfigFile(
-        legacyPath,
-        readPiSandboxConfigFile(legacyPath),
-      );
-    } catch (error) {
-      if (!isNotFoundError(error)) {
-        throw error;
-      }
+  const projectPath = getProjectPiSandboxConfigPath(options.cwd);
+  let projectRaw: PartialPiSandboxConfig | undefined;
+  try {
+    projectRaw = parsePiSandboxConfigFileRaw(
+      projectPath,
+      readPiSandboxConfigFile(projectPath),
+    );
+  } catch (error) {
+    if (!isNotFoundError(error)) {
+      throw error;
     }
   }
 
-  return defaultPiSandboxConfig();
+  const base = globalConfig ?? defaultPiSandboxConfig();
+  if (projectRaw) {
+    return mergePiSandboxConfigs(base, projectRaw);
+  }
+  return base;
 }

package/src/index.ts

@@ -218,7 +218,8 @@ async function performRegistration(
   options: PiSandboxExtensionOptions,
 ): Promise<void> {
   let currentTurn = 0;
-  const config = loadPiSandboxConfig();
+  const cwd = process.cwd();
+  const config = loadPiSandboxConfig({ cwd });
   const subagentProvider =
     options.subagentProvider ?? config.subagents.provider;
   const isNativeSubagentChild = process.env.PI_SUBAGENT_CHILD === "1";
@@ -246,7 +247,6 @@ async function performRegistration(
           maxDepth: 3,
         }))
       : undefined;
-  const cwd = process.cwd();
   let capabilityCeiling: CapabilityCeilingHandle | undefined;
   let validatedNativeAgents: string[] = [];
   const localBash = createBashToolDefinition(cwd);

package/src/pi-subagents-native.ts

@@ -1,4 +1,5 @@
-import { readFile } from "node:fs/promises";
+import { readFile, realpath } from "node:fs/promises";
+import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createJiti } from "jiti";
@@ -24,6 +25,10 @@ export const PI_SUBAGENTS_COMPAT_RANGE = ">=0.66.0";
 export const NATIVE_CHILD_TOOLS = ["bash", "read", "grep", "find", "ls"] as const;
 export const PI_SANDBOX_ACKNOWLEDGEMENT = "@erichll:pi-sandbox";
 
+const HOST_PI_PACKAGE = "@earendil-works/pi-coding-agent";
+/** Host peer that pi-subagents' internal modules import but that is not installed next to it. */
+const HOST_PI_TUI_PACKAGE = "@earendil-works/pi-tui";
+
 /**
  * Module extension of the installed pi-subagents layout. Source checkouts (and
  * the 0.66.0-0.69.0 npm line) ship `.ts` modules that need a TypeScript loader;
@@ -142,6 +147,89 @@ export function piSubagentsInternalModulePath(
   return `${relativePath.replace(/\.(?:ts|js)$/u, "")}${extension}`;
 }
 
+async function readPackageName(dir: string): Promise<string | undefined> {
+  try {
+    const manifest = JSON.parse(
+      await readFile(join(dir, "package.json"), "utf8"),
+    ) as { name?: unknown };
+    return typeof manifest?.name === "string" ? manifest.name : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Walk up from a Pi entry script (or a Pi package directory) to the running
+ * `@earendil-works/pi-coding-agent` root. Returns undefined for launchers whose
+ * entry is not a real file (compiled binaries, embedded SDK hosts).
+ */
+export async function findPiPackageRootFromEntry(
+  entryPath: string,
+): Promise<string | undefined> {
+  let dir = entryPath;
+  for (;;) {
+    if ((await readPackageName(dir)) === HOST_PI_PACKAGE) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+function resolveFrom(base: string, specifier: string): string | undefined {
+  try {
+    return createRequire(base).resolve(specifier);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Alias map for the jiti instance that loads pi-subagents internals.
+ *
+ * pi-subagents imports `@earendil-works/pi-tui` from its internal modules but,
+ * as a peer dependency, does not ship it. Pi's own extension loader aliases that
+ * specifier to the copy inside the running Pi package (`getAliases()` in the
+ * host loader), so extensions loaded by Pi resolve it; our jiti instance is a
+ * separate resolver and would otherwise fall back to plain Node resolution,
+ * which fails for installs where pi-tui is neither hoisted next to the
+ * extension nor installed beside `@earendil-works/pi-subagents`.
+ *
+ * The alias is computed host-first so the loaded modules share the host's
+ * pi-tui instance, and degrades to an empty map when no copy is reachable: the
+ * hard failure then stays the explicit compatibility error raised on load.
+ */
+export async function resolvePiSubagentsHostAliases(
+  options: { entry?: string; moduleUrl?: string; env?: Record<string, string | undefined> } = {},
+): Promise<Record<string, string>> {
+  const bases: string[] = [];
+  const entry = options.entry ?? process.argv[1];
+  if (entry) {
+    const realEntry = await realpath(entry).catch(() => undefined);
+    const root = realEntry
+      ? await findPiPackageRootFromEntry(realEntry)
+      : undefined;
+    if (root) bases.push(join(root, "package.json"));
+  }
+  const packageDir = (options.env ?? process.env).PI_PACKAGE_DIR?.trim();
+  if (packageDir && (await readPackageName(packageDir)) === HOST_PI_PACKAGE) {
+    bases.push(join(packageDir, "package.json"));
+  }
+  // Extension-local resolution: the development checkout and installs that
+  // provide pi-tui beside the extension or beside pi-subagents.
+  bases.push(options.moduleUrl ?? import.meta.url);
+
+  const seen = new Set<string>();
+  for (const base of bases) {
+    if (seen.has(base)) continue;
+    seen.add(base);
+    const resolved = resolveFrom(base, HOST_PI_TUI_PACKAGE);
+    if (!resolved) continue;
+    const target = await realpath(resolved).catch(() => resolved);
+    return { [HOST_PI_TUI_PACKAGE]: target };
+  }
+  return {};
+}
+
 /** Load the public ceiling API and the discovery/config internals.
  * This intentionally fails closed on package version, export, or layout drift.
  */
@@ -163,6 +251,7 @@ export async function loadPiSubagentsNativeRuntime(
   const jiti = createJiti(import.meta.url, {
     interopDefault: false,
     fsCache: false,
+    alias: await resolvePiSubagentsHostAliases(),
   });
   const internal = (relative: string): string =>
     pathToFileURL(join(root, piSubagentsInternalModulePath(relative, extension))).href;

package/src/policy.ts

@@ -10,7 +10,10 @@ import {
 } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
-import type { NetworkConfig } from "./config.ts";
+import {
+  PROJECT_PI_SANDBOX_CONFIG_PATH,
+  type NetworkConfig,
+} from "./config.ts";
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const NODE_INSTALL_ROOT = dirname(dirname(process.execPath));
@@ -248,6 +251,7 @@ export function createDefaultPolicy(
       allowWrite: [workspace, "/dev/null"],
       denyWrite: [
         join(workspace, ".pi", "pi-auto-review.json"),
+        join(workspace, PROJECT_PI_SANDBOX_CONFIG_PATH),
         join(home, ".pi", "agent", "logs"),
         // Prevent the sandbox from installing or rewriting trusted extensions
         // (includes ~/.pi/agent/extensions/pi-sandbox/config.json).