@gotgenes/pi-permission-system 3.2.0 → 3.4.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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)
+
+
+### Features
+
+* add permission-gate module ([507a1b6](https://github.com/gotgenes/pi-permission-system/commit/507a1b6155513562958bb277cd7c38ed8d44c215)), closes [#41](https://github.com/gotgenes/pi-permission-system/issues/41)
+
+
+### Documentation
+
+* plan extract reusable permission-gate function ([#41](https://github.com/gotgenes/pi-permission-system/issues/41)) ([2458bf2](https://github.com/gotgenes/pi-permission-system/commit/2458bf28f6c698db78c7a65cfdb6afa488e5b6ee))
+* **retro:** add retro notes for issue [#44](https://github.com/gotgenes/pi-permission-system/issues/44) ([963bb1b](https://github.com/gotgenes/pi-permission-system/commit/963bb1ba78d7e305a80732a55e385266e5222b82))
+
 ## [3.2.0](https://github.com/gotgenes/pi-permission-system/compare/v3.1.0...v3.2.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.2.0",
+  "version": "3.4.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "files": [

package/src/index.ts

@@ -68,6 +68,7 @@ import {
   requestPermissionDecisionFromUi,
 } from "./permission-dialog";
 import { PERMISSION_FORWARDING_POLL_INTERVAL_MS } from "./permission-forwarding";
+import { applyPermissionGate } from "./permission-gate";
 import { PermissionManager } from "./permission-manager";
 import {
   formatAskPrompt,
@@ -79,6 +80,10 @@ import {
   formatUnknownToolReason,
   formatUserDeniedReason,
 } from "./permission-prompts";
+import {
+  deriveApprovalPrefix,
+  SessionApprovalCache,
+} from "./session-approval-cache";
 import {
   findSkillPathMatch,
   resolveSkillPromptEntries,
@@ -233,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;
@@ -586,6 +592,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     runtimeContext?.ui.setStatus(PERMISSION_SYSTEM_STATUS_KEY, undefined);
     runtimeContext = null;
     invalidateAgentStartCache();
+    sessionApprovalCache.clear();
     stopForwardedPermissionPolling();
   });
 
@@ -673,45 +680,44 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       agentName ?? undefined,
     );
 
-    if (check.state === "deny") {
-      if (ctx.hasUI) {
-        const message = agentName
-          ? `Skill '${skillName}' is not permitted for agent '${agentName}'.`
-          : `Skill '${skillName}' is not permitted by the current skill policy.`;
-        ctx.ui.notify(message, "warning");
-      }
-      writeReviewLog("permission_request.blocked", {
-        source: "skill_input",
-        skillName,
-        agentName,
-        resolution: "policy_denied",
-      });
-      return { action: "handled" };
+    if (check.state === "deny" && ctx.hasUI) {
+      const notifyMessage = agentName
+        ? `Skill '${skillName}' is not permitted for agent '${agentName}'.`
+        : `Skill '${skillName}' is not permitted by the current skill policy.`;
+      ctx.ui.notify(notifyMessage, "warning");
     }
 
-    if (check.state === "ask") {
-      const message = formatSkillAskPrompt(skillName, agentName ?? undefined);
-      if (!canRequestPermissionConfirmation(ctx)) {
-        writeReviewLog("permission_request.blocked", {
+    const skillInputMessage = formatSkillAskPrompt(
+      skillName,
+      agentName ?? undefined,
+    );
+    const skillInputGate = await applyPermissionGate({
+      state: check.state,
+      canConfirm: canRequestPermissionConfirmation(ctx),
+      promptForApproval: () =>
+        promptPermission(ctx, {
+          requestId: createPermissionRequestId("skill-input"),
           source: "skill_input",
-          skillName,
           agentName,
-          message,
-          resolution: "confirmation_unavailable",
-        });
-        return { action: "handled" };
-      }
-
-      const decision = await promptPermission(ctx, {
-        requestId: createPermissionRequestId("skill-input"),
+          message: skillInputMessage,
+          skillName,
+        }),
+      writeLog: writeReviewLog,
+      logContext: {
         source: "skill_input",
-        agentName,
-        message,
         skillName,
-      });
-      if (!decision.approved) {
-        return { action: "handled" };
-      }
+        agentName,
+        message: skillInputMessage,
+      },
+      messages: {
+        denyReason: skillInputMessage,
+        unavailableReason:
+          "Skill requires approval, but no interactive UI is available.",
+        userDeniedReason: () => "User denied skill.",
+      },
+    });
+    if (skillInputGate.action === "block") {
+      return { action: "handled" };
     }
 
     return { action: "continue" };
@@ -756,64 +762,50 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       );
 
       if (matchedSkill) {
-        if (matchedSkill.state === "deny") {
-          writeReviewLog("permission_request.blocked", {
+        const skillReadMessage = formatSkillPathAskPrompt(
+          matchedSkill,
+          event.input.path,
+          agentName ?? undefined,
+        );
+        const skillReadGate = await applyPermissionGate({
+          state: matchedSkill.state,
+          canConfirm: canRequestPermissionConfirmation(ctx),
+          promptForApproval: () =>
+            promptPermission(ctx, {
+              requestId: event.toolCallId,
+              source: "skill_read",
+              agentName,
+              message: skillReadMessage,
+              toolCallId: event.toolCallId,
+              toolName: toolName,
+              skillName: matchedSkill.name,
+              path: event.input.path,
+            }),
+          writeLog: writeReviewLog,
+          logContext: {
             source: "skill_read",
             skillName: matchedSkill.name,
             agentName,
             path: event.input.path,
-            resolution: "policy_denied",
-          });
-          return {
-            block: true,
-            reason: formatSkillPathDenyReason(
+            message: skillReadMessage,
+          },
+          messages: {
+            denyReason: formatSkillPathDenyReason(
               matchedSkill,
               event.input.path,
               agentName ?? undefined,
             ),
-          };
-        }
-
-        if (matchedSkill.state === "ask") {
-          const message = formatSkillPathAskPrompt(
-            matchedSkill,
-            event.input.path,
-            agentName ?? undefined,
-          );
-          if (!canRequestPermissionConfirmation(ctx)) {
-            writeReviewLog("permission_request.blocked", {
-              source: "skill_read",
-              skillName: matchedSkill.name,
-              agentName,
-              path: event.input.path,
-              message,
-              resolution: "confirmation_unavailable",
-            });
-            return {
-              block: true,
-              reason: `Accessing skill '${matchedSkill.name}' requires approval, but no interactive UI is available.`,
-            };
-          }
-
-          const decision = await promptPermission(ctx, {
-            requestId: event.toolCallId,
-            source: "skill_read",
-            agentName,
-            message,
-            toolCallId: event.toolCallId,
-            toolName: toolName,
-            skillName: matchedSkill.name,
-            path: event.input.path,
-          });
-          if (!decision.approved) {
-            const denialReason = decision.denialReason
-              ? ` Reason: ${decision.denialReason}.`
-              : "";
-            return {
-              block: true,
-              reason: `User denied access to skill '${matchedSkill.name}'.${denialReason}`,
-            };
-          }
+            unavailableReason: `Accessing skill '${matchedSkill.name}' requires approval, but no interactive UI is available.`,
+            userDeniedReason: (decision) => {
+              const denialReason = decision.denialReason
+                ? ` Reason: ${decision.denialReason}.`
+                : "";
+              return `User denied access to skill '${matchedSkill.name}'.${denialReason}`;
+            },
+          },
+        });
+        if (skillReadGate.action === "block") {
+          return { block: true, reason: skillReadGate.reason };
         }
       }
     }
@@ -828,77 +820,91 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       externalDirectoryPath &&
       isPathOutsideWorkingDirectory(externalDirectoryPath, ctx.cwd)
     ) {
-      const extCheck = permissionManager.checkPermission(
+      const normalizedExtPath = normalizePathForComparison(
+        externalDirectoryPath,
+        ctx.cwd,
+      );
+      const sessionPrefix = sessionApprovalCache.findMatchingPrefix(
         "external_directory",
-        {},
-        agentName ?? undefined,
+        normalizedExtPath,
       );
 
-      if (extCheck.state === "deny") {
-        writeReviewLog("permission_request.blocked", {
+      if (sessionPrefix) {
+        writeReviewLog("permission_request.session_approved", {
           source: "tool_call",
           toolCallId: event.toolCallId,
           toolName,
           agentName,
           path: externalDirectoryPath,
-          resolution: "policy_denied",
+          resolution: "session_approved",
+          sessionApprovalPrefix: sessionPrefix,
         });
-        return {
-          block: true,
-          reason: formatExternalDirectoryDenyReason(
-            toolName,
-            externalDirectoryPath,
-            ctx.cwd,
-            agentName ?? undefined,
-          ),
-        };
-      }
+        // Fall through to normal permission check
+      } else {
+        const extCheck = permissionManager.checkPermission(
+          "external_directory",
+          {},
+          agentName ?? undefined,
+        );
 
-      if (extCheck.state === "ask") {
-        const message = formatExternalDirectoryAskPrompt(
+        let extDirDecision: PermissionPromptDecision | null = null;
+        const extDirMessage = formatExternalDirectoryAskPrompt(
           toolName,
           externalDirectoryPath,
           ctx.cwd,
           agentName ?? undefined,
         );
-        if (!canRequestPermissionConfirmation(ctx)) {
-          writeReviewLog("permission_request.blocked", {
+        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,
             agentName,
             path: externalDirectoryPath,
-            message,
-            resolution: "confirmation_unavailable",
-          });
-          return {
-            block: true,
-            reason: `Accessing '${externalDirectoryPath}' outside the working directory requires approval, but no interactive UI is available.`,
-          };
-        }
-
-        const extDecision = await promptPermission(ctx, {
-          requestId: event.toolCallId,
-          source: "tool_call",
-          agentName,
-          message,
-          toolCallId: event.toolCallId,
-          toolName,
-          path: externalDirectoryPath,
-        });
-
-        if (!extDecision.approved) {
-          return {
-            block: true,
-            reason: formatExternalDirectoryUserDeniedReason(
+            message: extDirMessage,
+          },
+          messages: {
+            denyReason: formatExternalDirectoryDenyReason(
               toolName,
               externalDirectoryPath,
-              extDecision.denialReason,
+              ctx.cwd,
+              agentName ?? undefined,
             ),
-          };
+            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
@@ -910,77 +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),
           );
 
-          if (extCheck.state === "deny") {
-            writeReviewLog("permission_request.blocked", {
+          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,
-              resolution: "policy_denied",
+              resolution: "session_approved",
             });
-            return {
-              block: true,
-              reason: formatBashExternalDirectoryDenyReason(
-                command,
-                externalPaths,
-                ctx.cwd,
-                agentName ?? undefined,
-              ),
-            };
-          }
+            // Fall through to normal bash permission check
+          } else {
+            const extCheck = permissionManager.checkPermission(
+              "external_directory",
+              {},
+              agentName ?? undefined,
+            );
 
-          if (extCheck.state === "ask") {
-            const message = formatBashExternalDirectoryAskPrompt(
+            let bashExtDecision: PermissionPromptDecision | null = null;
+            const bashExtMessage = formatBashExternalDirectoryAskPrompt(
               command,
-              externalPaths,
+              uncoveredPaths,
               ctx.cwd,
               agentName ?? undefined,
             );
-            if (!canRequestPermissionConfirmation(ctx)) {
-              writeReviewLog("permission_request.blocked", {
+            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,
-                message,
-                resolution: "confirmation_unavailable",
-              });
-              return {
-                block: true,
-                reason: `Bash command '${command}' references path(s) outside the working directory and requires approval, but no interactive UI is available.`,
-              };
+                externalPaths: uncoveredPaths,
+                message: bashExtMessage,
+              },
+              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 };
             }
 
-            const extDecision = await promptPermission(ctx, {
-              requestId: event.toolCallId,
-              source: "tool_call",
-              agentName,
-              message,
-              toolCallId: event.toolCallId,
-              toolName,
-              command,
-            });
-            if (!extDecision.approved) {
-              const reasonSuffix = extDecision.denialReason
-                ? ` Reason: ${extDecision.denialReason}.`
-                : "";
-              return {
-                block: true,
-                reason: `User denied external directory access for bash command '${command}'.${reasonSuffix} ${formatExternalDirectoryHardStopHint()}`,
-              };
+            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
         }
       }
     }
@@ -996,61 +1016,49 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       PATH_BEARING_TOOLS,
     );
 
-    if (check.state === "deny") {
-      writeReviewLog("permission_request.blocked", {
-        source: "tool_call",
-        toolCallId: event.toolCallId,
-        toolName,
-        agentName,
-        ...permissionLogContext,
-        resolution: "policy_denied",
-      });
-      return {
-        block: true,
-        reason: formatDenyReason(check, agentName ?? undefined),
-      };
-    }
+    const toolUnavailableReason =
+      toolName === "bash" && isToolCallEventType("bash", event)
+        ? `Running bash command '${event.input.command}' requires approval, but no interactive UI is available.`
+        : toolName === "mcp"
+          ? "Using tool 'mcp' requires approval, but no interactive UI is available."
+          : `Using tool '${toolName}' requires approval, but no interactive UI is available.`;
 
-    if (check.state === "ask") {
-      const unavailableReason =
-        toolName === "bash" && isToolCallEventType("bash", event)
-          ? `Running bash command '${event.input.command}' requires approval, but no interactive UI is available.`
-          : toolName === "mcp"
-            ? "Using tool 'mcp' requires approval, but no interactive UI is available."
-            : `Using tool '${toolName}' requires approval, but no interactive UI is available.`;
-
-      const message = formatAskPrompt(check, agentName ?? undefined, input);
-      if (!canRequestPermissionConfirmation(ctx)) {
-        writeReviewLog("permission_request.blocked", {
+    const toolAskMessage = formatAskPrompt(
+      check,
+      agentName ?? undefined,
+      input,
+    );
+    const toolGate = await applyPermissionGate({
+      state: check.state,
+      canConfirm: canRequestPermissionConfirmation(ctx),
+      promptForApproval: () =>
+        promptPermission(ctx, {
+          requestId: event.toolCallId,
           source: "tool_call",
+          agentName,
+          message: toolAskMessage,
           toolCallId: event.toolCallId,
           toolName,
-          agentName,
-          message,
           ...permissionLogContext,
-          resolution: "confirmation_unavailable",
-        });
-        return {
-          block: true,
-          reason: unavailableReason,
-        };
-      }
-
-      const decision = await promptPermission(ctx, {
-        requestId: event.toolCallId,
+        }),
+      writeLog: writeReviewLog,
+      logContext: {
         source: "tool_call",
-        agentName,
-        message,
         toolCallId: event.toolCallId,
         toolName,
+        agentName,
+        message: toolAskMessage,
         ...permissionLogContext,
-      });
-      if (!decision.approved) {
-        return {
-          block: true,
-          reason: formatUserDeniedReason(check, decision.denialReason),
-        };
-      }
+      },
+      messages: {
+        denyReason: formatDenyReason(check, agentName ?? undefined),
+        unavailableReason: toolUnavailableReason,
+        userDeniedReason: (decision) =>
+          formatUserDeniedReason(check, decision.denialReason),
+      },
+    });
+    if (toolGate.action === "block") {
+      return { block: true, reason: toolGate.reason };
     }
 
     return {};