@gotgenes/pi-permission-system 3.3.0 → 3.4.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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).
 
+## [3.4.0](https://github.com/gotgenes/pi-permission-system/compare/v3.3.0...v3.4.0) (2026-05-03)
+
+
+### Features
+
+* add "approve for session" option to permission dialog ([#45](https://github.com/gotgenes/pi-permission-system/issues/45)) ([909d5ee](https://github.com/gotgenes/pi-permission-system/commit/909d5ee540615f876852b3bdb60154487c2570fd))
+* add SessionApprovalCache for ephemeral session approvals ([#45](https://github.com/gotgenes/pi-permission-system/issues/45)) ([4f97779](https://github.com/gotgenes/pi-permission-system/commit/4f9777980eba139c9c85a027eeddc84ff932911c))
+* wire session approvals into external-directory gates ([#45](https://github.com/gotgenes/pi-permission-system/issues/45)) ([3ab156d](https://github.com/gotgenes/pi-permission-system/commit/3ab156dc4ad10bd37938a5096dc6c33970767b1a))
+
+
+### Documentation
+
+* document session-scoped approval option ([#45](https://github.com/gotgenes/pi-permission-system/issues/45)) ([eb1eb9c](https://github.com/gotgenes/pi-permission-system/commit/eb1eb9c0052e7dd88ad7162b322160cfd6e0e62b))
+* plan session-scoped approvals for permission prompts ([#45](https://github.com/gotgenes/pi-permission-system/issues/45)) ([29dcede](https://github.com/gotgenes/pi-permission-system/commit/29dcede17ad68fd3980bf3289069e237de2b4ef0))
+* **retro:** add retro notes for issue [#41](https://github.com/gotgenes/pi-permission-system/issues/41) ([fd2755f](https://github.com/gotgenes/pi-permission-system/commit/fd2755fcf4ec68c9e65e6128e9b869da1f368abb))
+
 ## [3.3.0](https://github.com/gotgenes/pi-permission-system/compare/v3.2.0...v3.3.0) (2026-05-03)
 
 

package/README.md

@@ -470,6 +470,23 @@ Example edit approval prompt:
 Current agent requested tool 'edit' for '.gitignore' (1 replacement: edit #1 replaces 5 lines with 2 lines). Allow this call?
 ```
 
+### Session-Scoped Approvals
+
+When `special.external_directory` resolves to `ask`, the permission dialog offers four options:
+
+```text
+Yes | Yes, for this session | No | No, provide reason
+```
+
+Selecting **Yes, for this session** approves the current request and caches the directory prefix so that subsequent accesses under the same directory skip the prompt for the remainder of the session.
+For example, approving access to `~/other-project/src/foo.ts` covers all paths under `~/other-project/src/` until the session ends.
+
+Session approvals are ephemeral — they are never persisted to disk and are cleared on `session_shutdown`.
+The review log records these decisions with `resolution: "session_approved"` so they remain auditable.
+
+This is currently scoped to the `external_directory` surface only.
+Other permission surfaces (tools, bash patterns, MCP, skills) always use the standard one-time approval flow.
+
 ### Subagent Permission Forwarding
 
 When a delegated or routed subagent runs without direct UI access, `ask` permissions can still be enforced by forwarding the confirmation request through Pi session directories. The main interactive session polls for forwarded requests, shows the confirmation prompt, writes the response, and the subagent resumes once that decision is available.
@@ -514,6 +531,7 @@ This makes it easy to verify which files the extension actually loaded:
 index.ts                    → Root Pi entrypoint shim
 src/
 ├── index.ts                → Extension bootstrap, permission checks, readable prompts, review logging, reload handling, and subagent forwarding
+├── session-approval-cache.ts → Ephemeral session-scoped approval cache for external-directory access
 ├── config-loader.ts        → Unified config loader, merger, and legacy-path detection
 ├── config-paths.ts         → Path derivation for global, project, and legacy config locations
 ├── config-reporter.ts      → Resolved config path reporting for diagnostic logs

package/package.json

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

package/src/index.ts

@@ -80,6 +80,10 @@ import {
   formatUnknownToolReason,
   formatUserDeniedReason,
 } from "./permission-prompts";
+import {
+  deriveApprovalPrefix,
+  SessionApprovalCache,
+} from "./session-approval-cache";
 import {
   findSkillPathMatch,
   resolveSkillPromptEntries,
@@ -234,6 +238,7 @@ function createPermissionManagerForCwd(
 
 export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   let permissionManager = new PermissionManager();
+  const sessionApprovalCache = new SessionApprovalCache();
   let activeSkillEntries: SkillPromptEntry[] = [];
   let lastKnownActiveAgentName: string | null = null;
   let lastActiveToolsCacheKey: string | null = null;
@@ -587,6 +592,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     runtimeContext?.ui.setStatus(PERMISSION_SYSTEM_STATUS_KEY, undefined);
     runtimeContext = null;
     invalidateAgentStartCache();
+    sessionApprovalCache.clear();
     stopForwardedPermissionPolling();
   });
 
@@ -814,60 +820,91 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       externalDirectoryPath &&
       isPathOutsideWorkingDirectory(externalDirectoryPath, ctx.cwd)
     ) {
-      const extCheck = permissionManager.checkPermission(
-        "external_directory",
-        {},
-        agentName ?? undefined,
-      );
-
-      const extDirMessage = formatExternalDirectoryAskPrompt(
-        toolName,
+      const normalizedExtPath = normalizePathForComparison(
         externalDirectoryPath,
         ctx.cwd,
-        agentName ?? undefined,
       );
-      const extDirGate = await applyPermissionGate({
-        state: extCheck.state,
-        canConfirm: canRequestPermissionConfirmation(ctx),
-        promptForApproval: () =>
-          promptPermission(ctx, {
-            requestId: event.toolCallId,
-            source: "tool_call",
-            agentName,
-            message: extDirMessage,
-            toolCallId: event.toolCallId,
-            toolName,
-            path: externalDirectoryPath,
-          }),
-        writeLog: writeReviewLog,
-        logContext: {
+      const sessionPrefix = sessionApprovalCache.findMatchingPrefix(
+        "external_directory",
+        normalizedExtPath,
+      );
+
+      if (sessionPrefix) {
+        writeReviewLog("permission_request.session_approved", {
           source: "tool_call",
           toolCallId: event.toolCallId,
           toolName,
           agentName,
           path: externalDirectoryPath,
-          message: extDirMessage,
-        },
-        messages: {
-          denyReason: formatExternalDirectoryDenyReason(
+          resolution: "session_approved",
+          sessionApprovalPrefix: sessionPrefix,
+        });
+        // Fall through to normal permission check
+      } else {
+        const extCheck = permissionManager.checkPermission(
+          "external_directory",
+          {},
+          agentName ?? undefined,
+        );
+
+        let extDirDecision: PermissionPromptDecision | null = null;
+        const extDirMessage = formatExternalDirectoryAskPrompt(
+          toolName,
+          externalDirectoryPath,
+          ctx.cwd,
+          agentName ?? undefined,
+        );
+        const extDirGate = await applyPermissionGate({
+          state: extCheck.state,
+          canConfirm: canRequestPermissionConfirmation(ctx),
+          promptForApproval: async () => {
+            const decision = await promptPermission(ctx, {
+              requestId: event.toolCallId,
+              source: "tool_call",
+              agentName,
+              message: extDirMessage,
+              toolCallId: event.toolCallId,
+              toolName,
+              path: externalDirectoryPath,
+            });
+            extDirDecision = decision;
+            return decision;
+          },
+          writeLog: writeReviewLog,
+          logContext: {
+            source: "tool_call",
+            toolCallId: event.toolCallId,
             toolName,
-            externalDirectoryPath,
-            ctx.cwd,
-            agentName ?? undefined,
-          ),
-          unavailableReason: `Accessing '${externalDirectoryPath}' outside the working directory requires approval, but no interactive UI is available.`,
-          userDeniedReason: (decision) =>
-            formatExternalDirectoryUserDeniedReason(
+            agentName,
+            path: externalDirectoryPath,
+            message: extDirMessage,
+          },
+          messages: {
+            denyReason: formatExternalDirectoryDenyReason(
               toolName,
               externalDirectoryPath,
-              decision.denialReason,
+              ctx.cwd,
+              agentName ?? undefined,
             ),
-        },
-      });
-      if (extDirGate.action === "block") {
-        return { block: true, reason: extDirGate.reason };
+            unavailableReason: `Accessing '${externalDirectoryPath}' outside the working directory requires approval, but no interactive UI is available.`,
+            userDeniedReason: (decision) =>
+              formatExternalDirectoryUserDeniedReason(
+                toolName,
+                externalDirectoryPath,
+                decision.denialReason,
+              ),
+          },
+        });
+        if (extDirGate.action === "block") {
+          return { block: true, reason: extDirGate.reason };
+        }
+
+        if (extDirDecision?.state === "approved_for_session") {
+          const prefix = deriveApprovalPrefix(normalizedExtPath);
+          sessionApprovalCache.approve("external_directory", prefix);
+        }
       }
-      // state === "allow" → fall through to normal permission check
+      // Fall through to normal permission check
     }
 
     // Bash external directory gate: extract paths from bash commands
@@ -879,61 +916,91 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
           ctx.cwd,
         );
         if (externalPaths.length > 0) {
-          const extCheck = permissionManager.checkPermission(
-            "external_directory",
-            {},
-            agentName ?? undefined,
+          // Filter out paths already covered by session approvals
+          const uncoveredPaths = externalPaths.filter(
+            (p) => !sessionApprovalCache.has("external_directory", p),
           );
 
-          const bashExtMessage = formatBashExternalDirectoryAskPrompt(
-            command,
-            externalPaths,
-            ctx.cwd,
-            agentName ?? undefined,
-          );
-          const bashExtGate = await applyPermissionGate({
-            state: extCheck.state,
-            canConfirm: canRequestPermissionConfirmation(ctx),
-            promptForApproval: () =>
-              promptPermission(ctx, {
-                requestId: event.toolCallId,
-                source: "tool_call",
-                agentName,
-                message: bashExtMessage,
-                toolCallId: event.toolCallId,
-                toolName,
-                command,
-              }),
-            writeLog: writeReviewLog,
-            logContext: {
+          if (uncoveredPaths.length === 0) {
+            // All external paths are session-approved
+            writeReviewLog("permission_request.session_approved", {
               source: "tool_call",
               toolCallId: event.toolCallId,
               toolName,
               agentName,
               command,
               externalPaths,
-              message: bashExtMessage,
-            },
-            messages: {
-              denyReason: formatBashExternalDirectoryDenyReason(
+              resolution: "session_approved",
+            });
+            // Fall through to normal bash permission check
+          } else {
+            const extCheck = permissionManager.checkPermission(
+              "external_directory",
+              {},
+              agentName ?? undefined,
+            );
+
+            let bashExtDecision: PermissionPromptDecision | null = null;
+            const bashExtMessage = formatBashExternalDirectoryAskPrompt(
+              command,
+              uncoveredPaths,
+              ctx.cwd,
+              agentName ?? undefined,
+            );
+            const bashExtGate = await applyPermissionGate({
+              state: extCheck.state,
+              canConfirm: canRequestPermissionConfirmation(ctx),
+              promptForApproval: async () => {
+                const decision = await promptPermission(ctx, {
+                  requestId: event.toolCallId,
+                  source: "tool_call",
+                  agentName,
+                  message: bashExtMessage,
+                  toolCallId: event.toolCallId,
+                  toolName,
+                  command,
+                });
+                bashExtDecision = decision;
+                return decision;
+              },
+              writeLog: writeReviewLog,
+              logContext: {
+                source: "tool_call",
+                toolCallId: event.toolCallId,
+                toolName,
+                agentName,
                 command,
-                externalPaths,
-                ctx.cwd,
-                agentName ?? undefined,
-              ),
-              unavailableReason: `Bash command '${command}' references path(s) outside the working directory and requires approval, but no interactive UI is available.`,
-              userDeniedReason: (decision) => {
-                const reasonSuffix = decision.denialReason
-                  ? ` Reason: ${decision.denialReason}.`
-                  : "";
-                return `User denied external directory access for bash command '${command}'.${reasonSuffix} ${formatExternalDirectoryHardStopHint()}`;
+                externalPaths: uncoveredPaths,
+                message: bashExtMessage,
               },
-            },
-          });
-          if (bashExtGate.action === "block") {
-            return { block: true, reason: bashExtGate.reason };
+              messages: {
+                denyReason: formatBashExternalDirectoryDenyReason(
+                  command,
+                  uncoveredPaths,
+                  ctx.cwd,
+                  agentName ?? undefined,
+                ),
+                unavailableReason: `Bash command '${command}' references path(s) outside the working directory and requires approval, but no interactive UI is available.`,
+                userDeniedReason: (decision) => {
+                  const reasonSuffix = decision.denialReason
+                    ? ` Reason: ${decision.denialReason}.`
+                    : "";
+                  return `User denied external directory access for bash command '${command}'.${reasonSuffix} ${formatExternalDirectoryHardStopHint()}`;
+                },
+              },
+            });
+            if (bashExtGate.action === "block") {
+              return { block: true, reason: bashExtGate.reason };
+            }
+
+            if (bashExtDecision?.state === "approved_for_session") {
+              for (const extPath of uncoveredPaths) {
+                const prefix = deriveApprovalPrefix(extPath);
+                sessionApprovalCache.approve("external_directory", prefix);
+              }
+            }
           }
-          // state === "allow" → fall through to normal bash permission check
+          // Fall through to normal bash permission check
         }
       }
     }

package/src/permission-dialog.ts

@@ -1,5 +1,6 @@
 export type PermissionDecisionState =
   | "approved"
+  | "approved_for_session"
   | "denied"
   | "denied_with_reason";
 
@@ -15,10 +16,12 @@ export interface PermissionDecisionUi {
 }
 
 const APPROVE_OPTION = "Yes";
+const APPROVE_FOR_SESSION_OPTION = "Yes, for this session";
 const DENY_OPTION = "No";
 const DENY_WITH_REASON_OPTION = "No, provide reason";
 const PERMISSION_DECISION_OPTIONS = [
   APPROVE_OPTION,
+  APPROVE_FOR_SESSION_OPTION,
   DENY_OPTION,
   DENY_WITH_REASON_OPTION,
 ] as const;
@@ -54,7 +57,10 @@ export function isPermissionDecisionState(
   value: unknown,
 ): value is PermissionDecisionState {
   return (
-    value === "approved" || value === "denied" || value === "denied_with_reason"
+    value === "approved" ||
+    value === "approved_for_session" ||
+    value === "denied" ||
+    value === "denied_with_reason"
   );
 }
 
@@ -74,6 +80,13 @@ export async function requestPermissionDecisionFromUi(
     };
   }
 
+  if (selected === APPROVE_FOR_SESSION_OPTION) {
+    return {
+      approved: true,
+      state: "approved_for_session",
+    };
+  }
+
   if (selected === DENY_WITH_REASON_OPTION) {
     const denialReason = normalizePermissionDenialReason(
       await ui.input(

package/src/session-approval-cache.ts

@@ -0,0 +1,81 @@
+import { dirname, sep } from "node:path";
+
+import { isPathWithinDirectory } from "./external-directory";
+
+/**
+ * Ephemeral in-memory cache of session-scoped permission approvals.
+ * Keyed by permission surface (e.g. "external_directory"), values are
+ * normalized directory prefixes that have been approved for the session.
+ *
+ * Cleared on session_shutdown — never persisted to disk.
+ */
+export class SessionApprovalCache {
+  private approvals = new Map<string, Set<string>>();
+
+  /** Record a directory prefix as approved for the given surface. */
+  approve(surface: string, prefix: string): void {
+    let prefixes = this.approvals.get(surface);
+    if (!prefixes) {
+      prefixes = new Set();
+      this.approvals.set(surface, prefixes);
+    }
+    prefixes.add(prefix);
+  }
+
+  /**
+   * Check whether a path falls under any approved prefix for the given surface.
+   * Uses `isPathWithinDirectory()` for correct separator-aware prefix matching.
+   */
+  has(surface: string, path: string): boolean {
+    const prefixes = this.approvals.get(surface);
+    if (!prefixes) {
+      return false;
+    }
+    for (const prefix of prefixes) {
+      if (isPathWithinDirectory(path, prefix)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /** Find and return the matching approved prefix, or null if none matches. */
+  findMatchingPrefix(surface: string, path: string): string | null {
+    const prefixes = this.approvals.get(surface);
+    if (!prefixes) {
+      return null;
+    }
+    for (const prefix of prefixes) {
+      if (isPathWithinDirectory(path, prefix)) {
+        return prefix;
+      }
+    }
+    return null;
+  }
+
+  /** Remove all session approvals. */
+  clear(): void {
+    this.approvals.clear();
+  }
+}
+
+/**
+ * Derive the directory prefix to approve from a normalized path.
+ * Returns `dirname(path)` with a trailing separator so that
+ * prefix matching via `isPathWithinDirectory()` works correctly.
+ *
+ * For paths that already end with a separator (directories),
+ * the trailing separator is stripped by dirname and re-added.
+ */
+export function deriveApprovalPrefix(normalizedPath: string): string {
+  // If the path already ends with a separator, it's a directory — return as-is.
+  if (normalizedPath.endsWith(sep)) {
+    return normalizedPath;
+  }
+  const dir = dirname(normalizedPath);
+  if (dir === normalizedPath) {
+    // Root path — dirname('/') === '/'
+    return dir;
+  }
+  return dir.endsWith(sep) ? dir : `${dir}${sep}`;
+}

package/tests/permission-dialog.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  createDeniedPermissionDecision,
+  isPermissionDecisionState,
+  normalizePermissionDenialReason,
+  type PermissionDecisionUi,
+  requestPermissionDecisionFromUi,
+} from "../src/permission-dialog";
+
+describe("isPermissionDecisionState", () => {
+  it("accepts approved", () => {
+    expect(isPermissionDecisionState("approved")).toBe(true);
+  });
+
+  it("accepts denied", () => {
+    expect(isPermissionDecisionState("denied")).toBe(true);
+  });
+
+  it("accepts denied_with_reason", () => {
+    expect(isPermissionDecisionState("denied_with_reason")).toBe(true);
+  });
+
+  it("accepts approved_for_session", () => {
+    expect(isPermissionDecisionState("approved_for_session")).toBe(true);
+  });
+
+  it("rejects unknown strings", () => {
+    expect(isPermissionDecisionState("unknown")).toBe(false);
+  });
+
+  it("rejects non-strings", () => {
+    expect(isPermissionDecisionState(42)).toBe(false);
+    expect(isPermissionDecisionState(null)).toBe(false);
+  });
+});
+
+describe("requestPermissionDecisionFromUi", () => {
+  it("returns approved when user selects Yes", async () => {
+    const ui: PermissionDecisionUi = {
+      select: vi.fn().mockResolvedValue("Yes"),
+      input: vi.fn(),
+    };
+    const result = await requestPermissionDecisionFromUi(
+      ui,
+      "Title",
+      "Message",
+    );
+    expect(result).toEqual({ approved: true, state: "approved" });
+  });
+
+  it("returns approved_for_session when user selects session option", async () => {
+    const ui: PermissionDecisionUi = {
+      select: vi.fn().mockResolvedValue("Yes, for this session"),
+      input: vi.fn(),
+    };
+    const result = await requestPermissionDecisionFromUi(
+      ui,
+      "Title",
+      "Message",
+    );
+    expect(result).toEqual({ approved: true, state: "approved_for_session" });
+  });
+
+  it("returns denied when user selects No", async () => {
+    const ui: PermissionDecisionUi = {
+      select: vi.fn().mockResolvedValue("No"),
+      input: vi.fn(),
+    };
+    const result = await requestPermissionDecisionFromUi(
+      ui,
+      "Title",
+      "Message",
+    );
+    expect(result).toEqual({ approved: false, state: "denied" });
+  });
+
+  it("returns denied_with_reason when user provides reason", async () => {
+    const ui: PermissionDecisionUi = {
+      select: vi.fn().mockResolvedValue("No, provide reason"),
+      input: vi.fn().mockResolvedValue("not now"),
+    };
+    const result = await requestPermissionDecisionFromUi(
+      ui,
+      "Title",
+      "Message",
+    );
+    expect(result).toEqual({
+      approved: false,
+      state: "denied_with_reason",
+      denialReason: "not now",
+    });
+  });
+
+  it("returns denied when user selects deny-with-reason but gives empty input", async () => {
+    const ui: PermissionDecisionUi = {
+      select: vi.fn().mockResolvedValue("No, provide reason"),
+      input: vi.fn().mockResolvedValue(""),
+    };
+    const result = await requestPermissionDecisionFromUi(
+      ui,
+      "Title",
+      "Message",
+    );
+    expect(result).toEqual({ approved: false, state: "denied" });
+  });
+
+  it("returns denied when user dismisses dialog (undefined)", async () => {
+    const ui: PermissionDecisionUi = {
+      select: vi.fn().mockResolvedValue(undefined),
+      input: vi.fn(),
+    };
+    const result = await requestPermissionDecisionFromUi(
+      ui,
+      "Title",
+      "Message",
+    );
+    expect(result).toEqual({ approved: false, state: "denied" });
+  });
+
+  it("passes four options to ui.select", async () => {
+    const selectFn = vi.fn().mockResolvedValue("Yes");
+    const ui: PermissionDecisionUi = {
+      select: selectFn,
+      input: vi.fn(),
+    };
+    await requestPermissionDecisionFromUi(ui, "Title", "Message");
+    const options = selectFn.mock.calls[0][1] as string[];
+    expect(options).toEqual([
+      "Yes",
+      "Yes, for this session",
+      "No",
+      "No, provide reason",
+    ]);
+  });
+});
+
+describe("normalizePermissionDenialReason", () => {
+  it("returns trimmed string for non-empty input", () => {
+    expect(normalizePermissionDenialReason("  reason  ")).toBe("reason");
+  });
+
+  it("returns undefined for empty string", () => {
+    expect(normalizePermissionDenialReason("")).toBeUndefined();
+  });
+
+  it("returns undefined for non-string", () => {
+    expect(normalizePermissionDenialReason(42)).toBeUndefined();
+  });
+});
+
+describe("createDeniedPermissionDecision", () => {
+  it("returns denied_with_reason when reason provided", () => {
+    expect(createDeniedPermissionDecision("nope")).toEqual({
+      approved: false,
+      state: "denied_with_reason",
+      denialReason: "nope",
+    });
+  });
+
+  it("returns denied when no reason", () => {
+    expect(createDeniedPermissionDecision()).toEqual({
+      approved: false,
+      state: "denied",
+    });
+  });
+});

package/tests/permission-system.test.ts

@@ -2644,3 +2644,292 @@ test("PermissionManager.getConfigIssues returns empty array for clean config", (
     cleanup();
   }
 });
+
+// --- session-scoped approval tests (#45) ---
+
+test("session approval: first prompt with 'Yes, for this session' skips subsequent prompts under same prefix", async () => {
+  const rootDir = mkdtempSync(join(tmpdir(), "pi-session-approval-"));
+  const cwd = join(rootDir, "repo");
+  const siblingDir = join(rootDir, "sibling-project");
+  mkdirSync(cwd, { recursive: true });
+  mkdirSync(siblingDir, { recursive: true });
+
+  const harness = createToolCallHarness(
+    {
+      defaultPolicy: {
+        tools: "allow",
+        bash: "allow",
+        mcp: "allow",
+        skills: "allow",
+        special: "ask",
+      },
+      special: { external_directory: "ask" },
+    },
+    ["read", "grep"],
+    { cwd },
+  );
+
+  try {
+    // First access — user selects "Yes, for this session"
+    const result1 = await runToolCall(
+      harness,
+      {
+        toolName: "read",
+        toolCallId: "ext-session-1",
+        input: { path: join(siblingDir, "src", "foo.ts") },
+      },
+      { hasUI: true, selectResponse: "Yes, for this session" },
+    );
+    assert.deepEqual(result1, {});
+    assert.equal(harness.prompts.length, 1);
+
+    // Second access under same prefix — should skip prompt
+    const result2 = await runToolCall(
+      harness,
+      {
+        toolName: "read",
+        toolCallId: "ext-session-2",
+        input: { path: join(siblingDir, "src", "bar.ts") },
+      },
+      { hasUI: true, selectResponse: "Yes, for this session" },
+    );
+    assert.deepEqual(result2, {});
+    // No new prompt — still just the original one
+    assert.equal(harness.prompts.length, 1);
+
+    // Third access with different tool under same prefix — also skipped
+    const result3 = await runToolCall(
+      harness,
+      {
+        toolName: "grep",
+        toolCallId: "ext-session-3",
+        input: { pattern: "needle", path: join(siblingDir, "src", "baz.ts") },
+      },
+      { hasUI: true, selectResponse: "Yes, for this session" },
+    );
+    assert.deepEqual(result3, {});
+    assert.equal(harness.prompts.length, 1);
+  } finally {
+    await harness.cleanup();
+    rmSync(rootDir, { recursive: true, force: true });
+  }
+});
+
+test("session approval: different directory prefix still prompts", async () => {
+  const rootDir = mkdtempSync(join(tmpdir(), "pi-session-approval-"));
+  const cwd = join(rootDir, "repo");
+  const siblingA = join(rootDir, "sibling-a");
+  const siblingB = join(rootDir, "sibling-b");
+  mkdirSync(cwd, { recursive: true });
+  mkdirSync(siblingA, { recursive: true });
+  mkdirSync(siblingB, { recursive: true });
+
+  const harness = createToolCallHarness(
+    {
+      defaultPolicy: {
+        tools: "allow",
+        bash: "allow",
+        mcp: "allow",
+        skills: "allow",
+        special: "ask",
+      },
+      special: { external_directory: "ask" },
+    },
+    ["read"],
+    { cwd },
+  );
+
+  try {
+    // Approve sibling-a/src/ for session
+    await runToolCall(
+      harness,
+      {
+        toolName: "read",
+        toolCallId: "ext-diff-1",
+        input: { path: join(siblingA, "src", "foo.ts") },
+      },
+      { hasUI: true, selectResponse: "Yes, for this session" },
+    );
+    assert.equal(harness.prompts.length, 1);
+
+    // Access sibling-b — different prefix, should prompt again
+    await runToolCall(
+      harness,
+      {
+        toolName: "read",
+        toolCallId: "ext-diff-2",
+        input: { path: join(siblingB, "src", "bar.ts") },
+      },
+      { hasUI: true, selectResponse: "Yes" },
+    );
+    assert.equal(harness.prompts.length, 2);
+  } finally {
+    await harness.cleanup();
+    rmSync(rootDir, { recursive: true, force: true });
+  }
+});
+
+test("session approval: session_shutdown clears session approvals", async () => {
+  const rootDir = mkdtempSync(join(tmpdir(), "pi-session-approval-"));
+  const cwd = join(rootDir, "repo");
+  const siblingDir = join(rootDir, "sibling");
+  mkdirSync(cwd, { recursive: true });
+  mkdirSync(siblingDir, { recursive: true });
+
+  const harness = createToolCallHarness(
+    {
+      defaultPolicy: {
+        tools: "allow",
+        bash: "allow",
+        mcp: "allow",
+        skills: "allow",
+        special: "ask",
+      },
+      special: { external_directory: "ask" },
+    },
+    ["read"],
+    { cwd },
+  );
+
+  try {
+    // Approve for session
+    await runToolCall(
+      harness,
+      {
+        toolName: "read",
+        toolCallId: "ext-shutdown-1",
+        input: { path: join(siblingDir, "src", "foo.ts") },
+      },
+      { hasUI: true, selectResponse: "Yes, for this session" },
+    );
+    assert.equal(harness.prompts.length, 1);
+
+    // Trigger session_shutdown (clears cache)
+    const shutdownCtx = createMockContext(cwd, harness.prompts, {
+      hasUI: true,
+      selectResponse: "Yes",
+    });
+    await Promise.resolve(harness.handlers.session_shutdown?.({}, shutdownCtx));
+
+    // Access same path again — should prompt because cache was cleared
+    const result = await runToolCall(
+      harness,
+      {
+        toolName: "read",
+        toolCallId: "ext-shutdown-2",
+        input: { path: join(siblingDir, "src", "foo.ts") },
+      },
+      { hasUI: true, selectResponse: "Yes" },
+    );
+    assert.deepEqual(result, {});
+    assert.equal(harness.prompts.length, 2);
+  } finally {
+    await harness.cleanup();
+    rmSync(rootDir, { recursive: true, force: true });
+  }
+});
+
+test("session approval: bash external directory with 'Yes, for this session' skips subsequent prompts", async () => {
+  const rootDir = mkdtempSync(join(tmpdir(), "pi-session-approval-"));
+  const cwd = join(rootDir, "repo");
+  mkdirSync(cwd, { recursive: true });
+
+  const harness = createToolCallHarness(
+    {
+      defaultPolicy: {
+        tools: "allow",
+        bash: "allow",
+        mcp: "allow",
+        skills: "allow",
+        special: "ask",
+      },
+      special: { external_directory: "ask" },
+    },
+    ["bash"],
+    { cwd },
+  );
+
+  try {
+    const externalPath = join(rootDir, "other-project", "src");
+    // First bash command referencing external path
+    const result1 = await runToolCall(
+      harness,
+      {
+        toolName: "bash",
+        toolCallId: "bash-session-1",
+        input: { command: `ls ${externalPath}/foo.ts` },
+      },
+      { hasUI: true, selectResponse: "Yes, for this session" },
+    );
+    assert.deepEqual(result1, {});
+    assert.equal(harness.prompts.length, 1);
+
+    // Second bash command referencing path under same prefix — skips prompt
+    const result2 = await runToolCall(
+      harness,
+      {
+        toolName: "bash",
+        toolCallId: "bash-session-2",
+        input: { command: `cat ${externalPath}/bar.ts` },
+      },
+      { hasUI: true, selectResponse: "Yes, for this session" },
+    );
+    assert.deepEqual(result2, {});
+    assert.equal(harness.prompts.length, 1);
+  } finally {
+    await harness.cleanup();
+    rmSync(rootDir, { recursive: true, force: true });
+  }
+});
+
+test("session approval: regular 'Yes' does not create session approval", async () => {
+  const rootDir = mkdtempSync(join(tmpdir(), "pi-session-approval-"));
+  const cwd = join(rootDir, "repo");
+  const siblingDir = join(rootDir, "sibling");
+  mkdirSync(cwd, { recursive: true });
+  mkdirSync(siblingDir, { recursive: true });
+
+  const harness = createToolCallHarness(
+    {
+      defaultPolicy: {
+        tools: "allow",
+        bash: "allow",
+        mcp: "allow",
+        skills: "allow",
+        special: "ask",
+      },
+      special: { external_directory: "ask" },
+    },
+    ["read"],
+    { cwd },
+  );
+
+  try {
+    // Approve once with "Yes" (not session)
+    await runToolCall(
+      harness,
+      {
+        toolName: "read",
+        toolCallId: "ext-once-1",
+        input: { path: join(siblingDir, "src", "foo.ts") },
+      },
+      { hasUI: true, selectResponse: "Yes" },
+    );
+    assert.equal(harness.prompts.length, 1);
+
+    // Same prefix — should still prompt since we used "Yes" not session
+    await runToolCall(
+      harness,
+      {
+        toolName: "read",
+        toolCallId: "ext-once-2",
+        input: { path: join(siblingDir, "src", "bar.ts") },
+      },
+      { hasUI: true, selectResponse: "Yes" },
+    );
+    assert.equal(harness.prompts.length, 2);
+  } finally {
+    await harness.cleanup();
+    rmSync(rootDir, { recursive: true, force: true });
+  }
+});

package/tests/session-approval-cache.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it, vi } from "vitest";
+
+// Mock node:os so tilde-expansion is deterministic across platforms.
+vi.mock("node:os", () => {
+  const homedir = vi.fn(() => "/mock/home");
+  return {
+    homedir,
+    default: { homedir },
+  };
+});
+
+import {
+  deriveApprovalPrefix,
+  SessionApprovalCache,
+} from "../src/session-approval-cache";
+
+describe("SessionApprovalCache", () => {
+  describe("approve and has", () => {
+    it("returns false when no approvals exist", () => {
+      const cache = new SessionApprovalCache();
+      expect(cache.has("external_directory", "/some/path")).toBe(false);
+    });
+
+    it("returns true for a path under an approved prefix", () => {
+      const cache = new SessionApprovalCache();
+      cache.approve("external_directory", "/other/project/src/");
+      expect(cache.has("external_directory", "/other/project/src/foo.ts")).toBe(
+        true,
+      );
+    });
+
+    it("returns true for the exact approved prefix path", () => {
+      const cache = new SessionApprovalCache();
+      cache.approve("external_directory", "/other/project/src/");
+      expect(cache.has("external_directory", "/other/project/src/")).toBe(true);
+    });
+
+    it("returns false for a path outside the approved prefix", () => {
+      const cache = new SessionApprovalCache();
+      cache.approve("external_directory", "/other/project/src/");
+      expect(cache.has("external_directory", "/other/project/lib/foo.ts")).toBe(
+        false,
+      );
+    });
+
+    it("returns false for a sibling directory that shares a string prefix", () => {
+      const cache = new SessionApprovalCache();
+      cache.approve("external_directory", "/other/project/");
+      // /other/project-b/ should NOT match /other/project/
+      expect(cache.has("external_directory", "/other/project-b/foo.ts")).toBe(
+        false,
+      );
+    });
+
+    it("handles multiple approved prefixes for the same surface", () => {
+      const cache = new SessionApprovalCache();
+      cache.approve("external_directory", "/other/project-a/");
+      cache.approve("external_directory", "/other/project-b/");
+      expect(cache.has("external_directory", "/other/project-a/foo.ts")).toBe(
+        true,
+      );
+      expect(cache.has("external_directory", "/other/project-b/bar.ts")).toBe(
+        true,
+      );
+      expect(cache.has("external_directory", "/other/project-c/baz.ts")).toBe(
+        false,
+      );
+    });
+
+    it("does not duplicate identical prefixes", () => {
+      const cache = new SessionApprovalCache();
+      cache.approve("external_directory", "/other/project/");
+      cache.approve("external_directory", "/other/project/");
+      // Set semantics — just verify it still works
+      expect(cache.has("external_directory", "/other/project/foo.ts")).toBe(
+        true,
+      );
+    });
+  });
+
+  describe("surface isolation", () => {
+    it("does not match across different surface types", () => {
+      const cache = new SessionApprovalCache();
+      cache.approve("external_directory", "/other/project/");
+      expect(cache.has("some_other_surface", "/other/project/foo.ts")).toBe(
+        false,
+      );
+    });
+  });
+
+  describe("clear", () => {
+    it("removes all approvals", () => {
+      const cache = new SessionApprovalCache();
+      cache.approve("external_directory", "/other/project/");
+      cache.approve("some_surface", "/another/path/");
+      cache.clear();
+      expect(cache.has("external_directory", "/other/project/foo.ts")).toBe(
+        false,
+      );
+      expect(cache.has("some_surface", "/another/path/file")).toBe(false);
+    });
+  });
+});
+
+describe("deriveApprovalPrefix", () => {
+  it("returns parent directory with trailing separator for a file path", () => {
+    expect(deriveApprovalPrefix("/other/project/src/foo.ts")).toBe(
+      "/other/project/src/",
+    );
+  });
+
+  it("returns the directory itself with trailing separator for a directory path", () => {
+    expect(deriveApprovalPrefix("/other/project/src/")).toBe(
+      "/other/project/src/",
+    );
+  });
+
+  it("returns the directory itself when path has no trailing separator", () => {
+    // For a path like /other/project/src (directory), dirname gives /other/project
+    // but we can't distinguish dir from file without stat. dirname is the safe choice.
+    expect(deriveApprovalPrefix("/other/project/src")).toBe("/other/project/");
+  });
+
+  it("handles root path", () => {
+    expect(deriveApprovalPrefix("/")).toBe("/");
+  });
+
+  it("handles single-level path", () => {
+    expect(deriveApprovalPrefix("/foo")).toBe("/");
+  });
+});