@erichll/pi-sandbox 0.20.1 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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
 {
@@ -141,14 +136,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 +249,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.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,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/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).