@gotgenes/pi-permission-system 13.1.0 → 13.1.2

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [13.1.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v13.1.1...pi-permission-system-v13.1.2) (2026-06-16)
+
+
+### Documentation
+
+* **pi-permission-system:** clarify external_directory surface in README ([#413](https://github.com/gotgenes/pi-packages/issues/413)) ([c09929b](https://github.com/gotgenes/pi-packages/commit/c09929be209050c1f85e9e01dbb231f99e940f82))
+* **pi-permission-system:** document external_directory allow-list for outside-CWD caches ([#413](https://github.com/gotgenes/pi-packages/issues/413)) ([86b1d87](https://github.com/gotgenes/pi-packages/commit/86b1d87ff92e63c26d3f81ddb41aad7aab085074))
+* **pi-permission-system:** show external_directory allow-list in example config and schema ([#413](https://github.com/gotgenes/pi-packages/issues/413)) ([8178a7e](https://github.com/gotgenes/pi-packages/commit/8178a7ebc3237e188b8e492d5c3a8bfca9b197aa))
+
+## [13.1.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v13.1.0...pi-permission-system-v13.1.1) (2026-06-13)
+
+
+### Bug Fixes
+
+* preserve forwarded-permission responses dir while requests pending ([#398](https://github.com/gotgenes/pi-packages/issues/398)) ([9914e70](https://github.com/gotgenes/pi-packages/commit/9914e7093c5addee80bd39f2ff99211991b4a238))
+* recreate forwarded-permission responses dir before write ([#398](https://github.com/gotgenes/pi-packages/issues/398)) ([67d34ef](https://github.com/gotgenes/pi-packages/commit/67d34efb33dbda28f363a004d0945c2a4aacea29))
+
 ## [13.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v13.0.0...pi-permission-system-v13.1.0) (2026-06-13)
 
 

package/README.md

@@ -72,7 +72,25 @@ For per-tool path patterns (`read`, `write`, `edit`, `find`, `grep`, `ls`), patt
 This lets you express rules like "allow reads but deny `.env` files" at the individual tool level.
 When Pi's current working directory is known, relative path inputs also match their cwd-normalized absolute form, so `src/App.jsx` can match both `src/*` and `/workspace/project/*`.
 
+The `external_directory` surface is the CWD-boundary gate: it decides whether reaching **outside** the working tree is allowed, and accepts a pattern map so you can allow specific outside-CWD directories without opening up all external access.
+This is the right surface for silencing repeated prompts on a local cache like `~/.cargo/registry` — allow it here, not on `path`:
+
+```jsonc
+{
+  "permission": {
+    "external_directory": {
+      "*": "ask",
+      "~/.cargo/registry/*": "allow"
+    }
+  }
+}
+```
+
+The trailing `*` is greedy and crosses subdirectory boundaries, so it allows every file beneath the directory; a bare `~/.cargo/registry` matches only the directory entry itself.
+
 Four layers compose with most-restrictive-wins: `path` (cross-cutting) → `external_directory` (CWD boundary) → per-tool patterns → `bash` command patterns.
+Because `ask` is more restrictive than `allow`, a `path` allow cannot loosen an `external_directory: ask` boundary — allow outside-CWD directories on `external_directory`.
+See [docs/configuration.md](docs/configuration.md) for the full recipe.
 
 ## Configuration
 

package/config/config.example.json

@@ -32,7 +32,8 @@
     "skill": { "*": "ask" },
     "external_directory": {
       "*": "ask",
-      "~/development/*": "allow"
+      "~/development/*": "allow",
+      "~/.cargo/registry/*": "allow"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "13.1.0",
+  "version": "13.1.2",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/schemas/permissions.schema.json

@@ -53,7 +53,7 @@
     },
     "permission": {
       "description": "Flat permission policy. Each key is a surface name; values are a PermissionState string (catch-all) or a pattern→action map.",
-      "markdownDescription": "Flat permission policy.\n\nEach top-level key is a surface name:\n- `\"*\"` — universal fallback (replaces `defaultPolicy.tools` from the legacy format)\n- Tool names (`read`, `write`, `bash`, `mcp`, `skill`, `external_directory`, `path`, etc.)\n\nA **string** value is shorthand for `{ \"*\": action }` (surface-level catch-all).\nAn **object** value maps wildcard patterns to actions — last matching pattern wins.\n\nFor built-in file tools (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns are matched against the file path from `input.path`. For example, `\"read\": { \"*\": \"allow\", \"*.env\": \"deny\" }` allows reads but denies `.env` files.\n\nWhen Pi's current working directory is known, relative path inputs also match their cwd-normalized absolute form, so `src/App.jsx` can match both `src/*` and `/workspace/project/*`. Bash path tokens use the effective directory after literal `cd` commands for this matching; non-literal `cd \"$DIR\"` style commands remain conservative.\n\nThe `path` surface is a cross-cutting gate that applies to **all** file access: Pi tools, bash commands, MCP calls (via `input.arguments.path`), and extension tools (via `input.path` or a registered access extractor). A `path` deny cannot be overridden by a per-tool allow. Use it to protect sensitive files (`.env`, `~/.ssh/*`) from all path-aware tools at once.\n\n**Merge order (lowest → highest precedence):** global → project → per-agent frontmatter.",
+      "markdownDescription": "Flat permission policy.\n\nEach top-level key is a surface name:\n- `\"*\"` — universal fallback (replaces `defaultPolicy.tools` from the legacy format)\n- Tool names (`read`, `write`, `bash`, `mcp`, `skill`, `external_directory`, `path`, etc.)\n\nA **string** value is shorthand for `{ \"*\": action }` (surface-level catch-all).\nAn **object** value maps wildcard patterns to actions — last matching pattern wins.\n\nFor built-in file tools (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns are matched against the file path from `input.path`. For example, `\"read\": { \"*\": \"allow\", \"*.env\": \"deny\" }` allows reads but denies `.env` files.\n\nWhen Pi's current working directory is known, relative path inputs also match their cwd-normalized absolute form, so `src/App.jsx` can match both `src/*` and `/workspace/project/*`. Bash path tokens use the effective directory after literal `cd` commands for this matching; non-literal `cd \"$DIR\"` style commands remain conservative.\n\nThe `path` surface is a cross-cutting gate that applies to **all** file access: Pi tools, bash commands, MCP calls (via `input.arguments.path`), and extension tools (via `input.path` or a registered access extractor). A `path` deny cannot be overridden by a per-tool allow. Use it to protect sensitive files (`.env`, `~/.ssh/*`) from all path-aware tools at once.\n\nThe `external_directory` surface gates access **outside** the working directory. Give it a pattern map to allow specific outside-CWD directories without opening all external access — e.g. `\"external_directory\": { \"*\": \"ask\", \"~/.cargo/registry/*\": \"allow\" }` to silence repeated prompts on a local cache. The trailing `*` is greedy and crosses subdirectory boundaries; a bare `~/.cargo/registry` matches only the directory entry itself. Because layers compose with most-restrictive-wins, a `path` allow cannot loosen an `external_directory: ask` boundary — allow outside-CWD directories here, not on `path`.\n\n**Merge order (lowest → highest precedence):** global → project → per-agent frontmatter.",
       "type": "object",
       "propertyNames": {
         "description": "A surface name or the universal fallback key '*'.",
@@ -92,7 +92,7 @@
           },
           "mcp": { "*": "ask", "mcp_status": "allow", "exa:*": "allow" },
           "skill": { "*": "ask", "librarian": "allow" },
-          "external_directory": "ask"
+          "external_directory": { "*": "ask", "~/.cargo/registry/*": "allow" }
         }
       ]
     }

package/src/forwarded-permissions/io.ts

@@ -175,13 +175,20 @@ export function getExistingPermissionForwardingLocation(
   return existsSync(location.requestsDir) ? location : null;
 }
 
+/**
+ * Attempt to remove a directory if it is empty.
+ *
+ * Returns `true` when the directory is absent after the call (successfully
+ * removed, or never existed).  Returns `false` when the directory still exists
+ * (non-empty, or a filesystem error prevented removal).
+ */
 export function tryRemoveDirectoryIfEmpty(
   logger: DebugReviewLogger | null,
   path: string,
   description: string,
-): void {
+): boolean {
   if (!existsSync(path)) {
-    return;
+    return true;
   }
 
   let entries: string[];
@@ -193,18 +200,22 @@ export function tryRemoveDirectoryIfEmpty(
       `Failed to inspect ${description} directory '${path}'`,
       error,
     );
-    return;
+    return false;
   }
 
   if (entries.length > 0) {
-    return;
+    return false;
   }
 
   try {
     rmdirSync(path);
+    return true;
   } catch (error) {
-    if (isErrnoCode(error, "ENOENT") || isErrnoCode(error, "ENOTEMPTY")) {
-      return;
+    if (isErrnoCode(error, "ENOENT")) {
+      return true;
+    }
+    if (isErrnoCode(error, "ENOTEMPTY")) {
+      return false;
     }
 
     logPermissionForwardingWarning(
@@ -212,6 +223,7 @@ export function tryRemoveDirectoryIfEmpty(
       `Failed to remove empty ${description} directory '${path}'`,
       error,
     );
+    return false;
   }
 }
 
@@ -219,16 +231,20 @@ export function cleanupPermissionForwardingLocationIfEmpty(
   logger: DebugReviewLogger | null,
   location: PermissionForwardingLocation,
 ): void {
-  tryRemoveDirectoryIfEmpty(
+  // Only remove responses/ when requests/ is already gone — removing responses/
+  // while a request is still pending causes the ENOENT write loop (issue #398).
+  const requestsGone = tryRemoveDirectoryIfEmpty(
     logger,
     location.requestsDir,
     `${location.label} permission forwarding requests`,
   );
-  tryRemoveDirectoryIfEmpty(
-    logger,
-    location.responsesDir,
-    `${location.label} permission forwarding responses`,
-  );
+  if (requestsGone) {
+    tryRemoveDirectoryIfEmpty(
+      logger,
+      location.responsesDir,
+      `${location.label} permission forwarding responses`,
+    );
+  }
   tryRemoveDirectoryIfEmpty(
     logger,
     location.sessionRootDir,

package/src/forwarded-permissions/permission-forwarder.ts

@@ -35,6 +35,7 @@ import { shouldAutoApprovePermissionState } from "#src/yolo-mode";
 
 import {
   cleanupPermissionForwardingLocationIfEmpty,
+  ensureDirectoryExists,
   ensurePermissionForwardingLocation,
   getExistingPermissionForwardingLocation,
   listRequestFiles,
@@ -255,6 +256,20 @@ export class PermissionForwarder implements ApprovalRequester, InboxProcessor {
       return;
     }
 
+    // Defensively recreate responses/ before writing any response — a
+    // concurrent cleanup pass may have removed it between the requestsDir
+    // existence check above and the write inside processSingleForwardedRequest
+    // (the ENOENT write loop reported in issue #398).
+    if (
+      !ensureDirectoryExists(
+        this.logger,
+        location.responsesDir,
+        "permission forwarding responses",
+      )
+    ) {
+      return;
+    }
+
     for (const fileName of requestFiles) {
       const requestPath = join(location.requestsDir, fileName);
       const request = readForwardedPermissionRequest(this.logger, requestPath);

package/test/forwarded-permissions/io.test.ts

@@ -1,11 +1,24 @@
-import { describe, expect, it, vi } from "vitest";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
 
 import {
+  cleanupPermissionForwardingLocationIfEmpty,
   formatUnknownErrorMessage,
   isErrnoCode,
   logPermissionForwardingError,
   logPermissionForwardingWarning,
+  tryRemoveDirectoryIfEmpty,
 } from "#src/forwarded-permissions/io";
+import { createPermissionForwardingLocation } from "#src/permission-forwarding";
 import type { DebugReviewLogger } from "#src/session-logger";
 
 // ── helpers ────────────────────────────────────────────────────────────────
@@ -130,3 +143,109 @@ describe("logPermissionForwardingError", () => {
     expect(() => logPermissionForwardingError(null, "ignored")).not.toThrow();
   });
 });
+
+// ── tryRemoveDirectoryIfEmpty ──────────────────────────────────────────────
+
+describe("tryRemoveDirectoryIfEmpty", () => {
+  let root: string;
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("returns true when the directory does not exist", () => {
+    root = mkdtempSync(join(tmpdir(), "io-test-"));
+    const absent = join(root, "nonexistent");
+    expect(tryRemoveDirectoryIfEmpty(null, absent, "test")).toBe(true);
+  });
+
+  it("returns true and removes an empty directory", () => {
+    root = mkdtempSync(join(tmpdir(), "io-test-"));
+    const dir = join(root, "empty");
+    mkdirSync(dir);
+    expect(tryRemoveDirectoryIfEmpty(null, dir, "test")).toBe(true);
+    expect(existsSync(dir)).toBe(false);
+  });
+
+  it("returns false and leaves a non-empty directory in place", () => {
+    root = mkdtempSync(join(tmpdir(), "io-test-"));
+    const dir = join(root, "nonempty");
+    mkdirSync(dir);
+    writeFileSync(join(dir, "file.json"), "{}", "utf-8");
+    expect(tryRemoveDirectoryIfEmpty(null, dir, "test")).toBe(false);
+    expect(existsSync(dir)).toBe(true);
+  });
+});
+
+// ── cleanupPermissionForwardingLocationIfEmpty ─────────────────────────────
+
+describe("cleanupPermissionForwardingLocationIfEmpty", () => {
+  let root: string;
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("preserves responses/ when requests/ is non-empty (the concurrent-request race)", () => {
+    root = mkdtempSync(join(tmpdir(), "io-cleanup-"));
+    const forwardingDir = join(root, "forwarding");
+    const location = createPermissionForwardingLocation(
+      forwardingDir,
+      "parent-session",
+    );
+    // Simulate: requests/ has a pending file, responses/ is momentarily empty
+    mkdirSync(location.requestsDir, { recursive: true });
+    mkdirSync(location.responsesDir, { recursive: true });
+    writeFileSync(join(location.requestsDir, "req-b.json"), "{}", "utf-8");
+    // responses/ is empty (sibling subagent A already cleaned up its response)
+
+    cleanupPermissionForwardingLocationIfEmpty(null, location);
+
+    // requests/ is non-empty → should NOT be removed
+    expect(existsSync(location.requestsDir)).toBe(true);
+    // responses/ must survive — removing it causes the ENOENT write loop
+    expect(existsSync(location.responsesDir)).toBe(true);
+    // sessionRoot must also survive while subdirs are present
+    expect(existsSync(location.sessionRootDir)).toBe(true);
+  });
+
+  it("removes both subdirs and sessionRoot when both are empty (normal serial cleanup)", () => {
+    root = mkdtempSync(join(tmpdir(), "io-cleanup-"));
+    const forwardingDir = join(root, "forwarding");
+    const location = createPermissionForwardingLocation(
+      forwardingDir,
+      "parent-session",
+    );
+    mkdirSync(location.requestsDir, { recursive: true });
+    mkdirSync(location.responsesDir, { recursive: true });
+    // Both empty — normal end-of-lifecycle state
+
+    cleanupPermissionForwardingLocationIfEmpty(null, location);
+
+    expect(existsSync(location.requestsDir)).toBe(false);
+    expect(existsSync(location.responsesDir)).toBe(false);
+    expect(existsSync(location.sessionRootDir)).toBe(false);
+  });
+
+  it("leaves responses/ in place when it is non-empty even if requests/ is empty", () => {
+    root = mkdtempSync(join(tmpdir(), "io-cleanup-"));
+    const forwardingDir = join(root, "forwarding");
+    const location = createPermissionForwardingLocation(
+      forwardingDir,
+      "parent-session",
+    );
+    mkdirSync(location.requestsDir, { recursive: true });
+    mkdirSync(location.responsesDir, { recursive: true });
+    writeFileSync(join(location.responsesDir, "resp.json"), "{}", "utf-8");
+    // requests/ is empty, responses/ has a stale response
+
+    cleanupPermissionForwardingLocationIfEmpty(null, location);
+
+    // requests/ is empty so it gets removed
+    expect(existsSync(location.requestsDir)).toBe(false);
+    // responses/ is non-empty → survives
+    expect(existsSync(location.responsesDir)).toBe(true);
+    // sessionRoot survives because responses/ is still present
+    expect(existsSync(location.sessionRootDir)).toBe(true);
+  });
+});

package/test/permission-forwarder.test.ts

@@ -307,4 +307,63 @@ describe("processInbox", () => {
       rmSync(root, { recursive: true, force: true });
     }
   });
+
+  test("recreates a missing responses/ directory and still writes the response", async () => {
+    const root = mkdtempSync(join(tmpdir(), "permission-forwarding-"));
+    try {
+      const forwardingDir = join(root, "forwarding");
+      const location = createPermissionForwardingLocation(
+        forwardingDir,
+        "parent-session",
+      );
+      // Simulate the race: requests/ exists with a pending file, but
+      // responses/ was removed by a concurrent cleanup pass.
+      mkdirSync(location.requestsDir, { recursive: true });
+      // Deliberately do NOT create location.responsesDir.
+      writeFileSync(
+        join(location.requestsDir, "req-race.json"),
+        JSON.stringify({
+          id: "req-race",
+          createdAt: Date.now(),
+          requesterSessionId: "child-session",
+          targetSessionId: "parent-session",
+          requesterAgentName: "Explore",
+          message: "Allow read?",
+        }),
+        "utf-8",
+      );
+
+      const logger = { review: vi.fn(), debug: vi.fn() };
+      const requestPermissionDecisionFromUi = vi
+        .fn()
+        .mockResolvedValue({ approved: true, state: "approved" as const });
+
+      const forwarder = new PermissionForwarder(
+        makeDeps({
+          forwardingDir,
+          logger,
+          requestPermissionDecisionFromUi,
+        }),
+      );
+
+      await forwarder.processInbox(
+        makeCtx({
+          hasUI: true,
+          sessionManager: {
+            getSessionId: vi.fn(() => "parent-session"),
+          },
+        }),
+      );
+
+      // processInbox must have recreated responses/ and written a response
+      // file — no permission_forwarding.error should have been logged.
+      expect(logger.review).not.toHaveBeenCalledWith(
+        "permission_forwarding.error",
+        expect.anything(),
+      );
+      expect(requestPermissionDecisionFromUi).toHaveBeenCalled();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
 });