@gotgenes/pi-permission-system 3.1.0 → 3.3.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.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)
+
+
+### Features
+
+* add SAFE_SYSTEM_PATHS allowlist and isSafeSystemPath helper ([#44](https://github.com/gotgenes/pi-permission-system/issues/44)) ([331b53f](https://github.com/gotgenes/pi-permission-system/commit/331b53f1a6425c7ee641127cbc82b5aada1e7018))
+* filter safe system paths from bash external path extraction ([#44](https://github.com/gotgenes/pi-permission-system/issues/44)) ([a0a907f](https://github.com/gotgenes/pi-permission-system/commit/a0a907f020cbf08722ea47be11d3f67fc95ef448))
+* skip safe system paths in isPathOutsideWorkingDirectory ([#44](https://github.com/gotgenes/pi-permission-system/issues/44)) ([360594c](https://github.com/gotgenes/pi-permission-system/commit/360594c8ddfd6f7f45abe04352a514de292df357))
+
+
+### Documentation
+
+* clarify /dev/null redirect risks in plan [#44](https://github.com/gotgenes/pi-permission-system/issues/44) ([00c61e7](https://github.com/gotgenes/pi-permission-system/commit/00c61e75eb5bf3cd9d5fc3297024ef9642655b86))
+* note safe system path allowlist in external-directory section ([#44](https://github.com/gotgenes/pi-permission-system/issues/44)) ([eaec9ae](https://github.com/gotgenes/pi-permission-system/commit/eaec9ae4ad88155bf2630bba9607920cbbdc8583))
+* plan auto-allow /dev/null in external directory checks ([#44](https://github.com/gotgenes/pi-permission-system/issues/44)) ([90b94f4](https://github.com/gotgenes/pi-permission-system/commit/90b94f4e0ae01b3a9f9dc90c5426720742a652e2))
+
 ## [3.1.0](https://github.com/gotgenes/pi-permission-system/compare/v3.0.5...v3.1.0) (2026-05-03)
 
 

package/README.md

@@ -367,7 +367,7 @@ Reserved permission checks:
 
 `external_directory` is evaluated before the normal tool permission check. For example, `tools.read: "allow"` can permit ordinary reads while `special.external_directory: "ask"` still requires confirmation before reading `../outside.txt` or an absolute path outside `ctx.cwd`. Optional-path search tools (`find`, `grep`, `ls`) skip this check when no `path` is provided because they default to the active working directory.
 
-Bash commands are also covered: the extension extracts path-like tokens from the command string and applies the same gate when any resolve outside `ctx.cwd`. Quoted strings are stripped first to reduce false positives (e.g., paths inside `git commit -m "..."` messages). This is a best-effort heuristic — variable expansion, subshells, and escaped quotes are not parsed.
+Bash commands are also covered: the extension extracts path-like tokens from the command string and applies the same gate when any resolve outside `ctx.cwd`. Quoted strings are stripped first to reduce false positives (e.g., paths inside `git commit -m "..."` messages). This is a best-effort heuristic — variable expansion, subshells, and escaped quotes are not parsed. OS device paths (`/dev/null`, `/dev/stdin`, `/dev/stdout`, `/dev/stderr`) are always excluded from this check — they cannot hold or leak data and commonly appear in stderr-redirect idioms such as `command 2>/dev/null`.
 
 ---
 

package/package.json

@@ -1,14 +1,9 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
-  "main": "./index.ts",
-  "exports": {
-    ".": "./index.ts"
-  },
   "files": [
-    "index.ts",
     "src",
     "tests",
     "config/config.example.json",
@@ -49,7 +44,7 @@
   },
   "pi": {
     "extensions": [
-      "./index.ts"
+      "./src/index.ts"
     ]
   },
   "peerDependencies": {
@@ -71,7 +66,7 @@
     "lint:fix": "biome check --write .",
     "lint:md": "markdownlint-cli2 '*.md' 'docs/**/*.md' '.pi/prompts/**/*.md'",
     "lint:md:fix": "markdownlint-cli2 --fix '*.md' 'docs/**/*.md' '.pi/prompts/**/*.md'",
-    "lint:imports": "! grep -rn --include='*.ts' 'from \"\\.[./][^\"]*\\.js\"' src/ tests/ index.ts",
+    "lint:imports": "! grep -rn --include='*.ts' 'from \"\\.[./][^\"]*\\.js\"' src/ tests/",
     "lint:all": "pnpm run lint && pnpm run lint:md && pnpm run lint:imports",
     "format": "biome format --write .",
     "test": "vitest run",

package/src/external-directory.ts

@@ -3,6 +3,25 @@ import { join, normalize, resolve, sep } from "node:path";
 
 import { getNonEmptyString, toRecord } from "./common";
 
+/**
+ * Paths that are universally safe and should never trigger external-directory checks.
+ * These are OS device files: read returns EOF or process streams, write discards or goes to process streams.
+ */
+export const SAFE_SYSTEM_PATHS: ReadonlySet<string> = new Set([
+  "/dev/null",
+  "/dev/stdin",
+  "/dev/stdout",
+  "/dev/stderr",
+]);
+
+/**
+ * Returns true if the given normalized path is a safe OS device file
+ * that should never trigger external-directory checks.
+ */
+export function isSafeSystemPath(normalizedPath: string): boolean {
+  return SAFE_SYSTEM_PATHS.has(normalizedPath);
+}
+
 export const PATH_BEARING_TOOLS = new Set([
   "read",
   "write",
@@ -72,11 +91,13 @@ export function isPathOutsideWorkingDirectory(
 ): boolean {
   const normalizedCwd = normalizePathForComparison(cwd, cwd);
   const normalizedPath = normalizePathForComparison(pathValue, cwd);
-  return Boolean(
-    normalizedCwd &&
-      normalizedPath &&
-      !isPathWithinDirectory(normalizedPath, normalizedCwd),
-  );
+  if (!normalizedCwd || !normalizedPath) {
+    return false;
+  }
+  if (isSafeSystemPath(normalizedPath)) {
+    return false;
+  }
+  return !isPathWithinDirectory(normalizedPath, normalizedCwd);
 }
 
 export function formatExternalDirectoryHardStopHint(): string {

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,
@@ -673,45 +674,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 +756,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 };
         }
       }
     }
@@ -834,69 +820,52 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
         agentName ?? undefined,
       );
 
-      if (extCheck.state === "deny") {
-        writeReviewLog("permission_request.blocked", {
+      const extDirMessage = formatExternalDirectoryAskPrompt(
+        toolName,
+        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: {
           source: "tool_call",
           toolCallId: event.toolCallId,
           toolName,
           agentName,
           path: externalDirectoryPath,
-          resolution: "policy_denied",
-        });
-        return {
-          block: true,
-          reason: formatExternalDirectoryDenyReason(
+          message: extDirMessage,
+        },
+        messages: {
+          denyReason: formatExternalDirectoryDenyReason(
             toolName,
             externalDirectoryPath,
             ctx.cwd,
             agentName ?? undefined,
           ),
-        };
-      }
-
-      if (extCheck.state === "ask") {
-        const message = formatExternalDirectoryAskPrompt(
-          toolName,
-          externalDirectoryPath,
-          ctx.cwd,
-          agentName ?? undefined,
-        );
-        if (!canRequestPermissionConfirmation(ctx)) {
-          writeReviewLog("permission_request.blocked", {
-            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(
+          unavailableReason: `Accessing '${externalDirectoryPath}' outside the working directory requires approval, but no interactive UI is available.`,
+          userDeniedReason: (decision) =>
+            formatExternalDirectoryUserDeniedReason(
               toolName,
               externalDirectoryPath,
-              extDecision.denialReason,
+              decision.denialReason,
             ),
-          };
-        }
+        },
+      });
+      if (extDirGate.action === "block") {
+        return { block: true, reason: extDirGate.reason };
       }
       // state === "allow" → fall through to normal permission check
     }
@@ -916,69 +885,53 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
             agentName ?? undefined,
           );
 
-          if (extCheck.state === "deny") {
-            writeReviewLog("permission_request.blocked", {
+          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: {
               source: "tool_call",
               toolCallId: event.toolCallId,
               toolName,
               agentName,
               command,
               externalPaths,
-              resolution: "policy_denied",
-            });
-            return {
-              block: true,
-              reason: formatBashExternalDirectoryDenyReason(
+              message: bashExtMessage,
+            },
+            messages: {
+              denyReason: formatBashExternalDirectoryDenyReason(
                 command,
                 externalPaths,
                 ctx.cwd,
                 agentName ?? undefined,
               ),
-            };
-          }
-
-          if (extCheck.state === "ask") {
-            const message = formatBashExternalDirectoryAskPrompt(
-              command,
-              externalPaths,
-              ctx.cwd,
-              agentName ?? undefined,
-            );
-            if (!canRequestPermissionConfirmation(ctx)) {
-              writeReviewLog("permission_request.blocked", {
-                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.`,
-              };
-            }
-
-            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()}`,
-              };
-            }
+              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 };
           }
           // state === "allow" → fall through to normal bash permission check
         }
@@ -996,61 +949,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 {};

package/src/permission-gate.ts

@@ -0,0 +1,74 @@
+import type { PermissionPromptDecision } from "./permission-dialog";
+
+/** Result of applying the permission gate. */
+export type PermissionGateResult =
+  | { action: "allow" }
+  | { action: "block"; reason: string };
+
+/** Everything the gate needs — no direct dependency on ExtensionContext. */
+export interface PermissionGateParams {
+  /** The resolved permission state from checkPermission(). */
+  state: "allow" | "deny" | "ask";
+
+  /** Whether the current context supports interactive prompts. */
+  canConfirm: boolean;
+
+  /** Prompt the user for approval. Only called when state === "ask" and canConfirm is true. */
+  promptForApproval: () => Promise<PermissionPromptDecision>;
+
+  /** Write a review-log entry. Called for deny and ask-but-unavailable paths. */
+  writeLog: (event: string, extra: Record<string, unknown>) => void;
+
+  /** Log context fields shared across all log calls for this gate. */
+  logContext: Record<string, unknown>;
+
+  /** Message strings/factories for each outcome. */
+  messages: {
+    denyReason: string;
+    unavailableReason: string;
+    userDeniedReason: (decision: PermissionPromptDecision) => string;
+  };
+}
+
+/**
+ * Apply the deny/ask/allow permission gate.
+ *
+ * This is a pure decision function: all IO is injected via callbacks.
+ */
+export async function applyPermissionGate(
+  params: PermissionGateParams,
+): Promise<PermissionGateResult> {
+  const {
+    state,
+    canConfirm,
+    promptForApproval,
+    writeLog,
+    logContext,
+    messages,
+  } = params;
+
+  if (state === "deny") {
+    writeLog("permission_request.blocked", {
+      ...logContext,
+      resolution: "policy_denied",
+    });
+    return { action: "block", reason: messages.denyReason };
+  }
+
+  if (state === "ask") {
+    if (!canConfirm) {
+      writeLog("permission_request.blocked", {
+        ...logContext,
+        resolution: "confirmation_unavailable",
+      });
+      return { action: "block", reason: messages.unavailableReason };
+    }
+
+    const decision = await promptForApproval();
+    if (!decision.approved) {
+      return { action: "block", reason: messages.userDeniedReason(decision) };
+    }
+  }
+
+  return { action: "allow" };
+}

package/tests/bash-external-directory.test.ts

@@ -223,6 +223,62 @@ describe("extractExternalPathsFromBashCommand", () => {
     });
   });
 
+  describe("safe system paths are filtered", () => {
+    test("does not flag /dev/null in stderr redirect", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "command 2>/dev/null",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("does not flag /dev/null as a redirect target", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "echo hello > /dev/null",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("does not flag /dev/stdin", () => {
+      const result = extractExternalPathsFromBashCommand("cat /dev/stdin", cwd);
+      expect(result).toHaveLength(0);
+    });
+
+    test("does not flag /dev/stdout", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "cat /dev/stdout",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("does not flag /dev/stderr", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "cat /dev/stderr",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("still flags a real external path alongside /dev/null", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "cat /etc/hosts 2>/dev/null",
+        cwd,
+      );
+      expect(result).toContain("/etc/hosts");
+      expect(result).not.toContain("/dev/null");
+    });
+
+    test("does not flag /dev/null/subdir (not a safe path)", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "cat /dev/null/subdir",
+        cwd,
+      );
+      expect(result).toContain("/dev/null/subdir");
+    });
+  });
+
   describe("deduplication", () => {
     test("returns deduplicated paths", () => {
       const result = extractExternalPathsFromBashCommand(

package/tests/external-directory.test.ts

@@ -18,8 +18,10 @@ import {
   getPathBearingToolPath,
   isPathOutsideWorkingDirectory,
   isPathWithinDirectory,
+  isSafeSystemPath,
   normalizePathForComparison,
   PATH_BEARING_TOOLS,
+  SAFE_SYSTEM_PATHS,
 } from "../src/external-directory";
 
 afterEach(() => {
@@ -39,6 +41,49 @@ describe("PATH_BEARING_TOOLS", () => {
   });
 });
 
+describe("SAFE_SYSTEM_PATHS", () => {
+  test("contains /dev/null, /dev/stdin, /dev/stdout, /dev/stderr", () => {
+    expect(SAFE_SYSTEM_PATHS.has("/dev/null")).toBe(true);
+    expect(SAFE_SYSTEM_PATHS.has("/dev/stdin")).toBe(true);
+    expect(SAFE_SYSTEM_PATHS.has("/dev/stdout")).toBe(true);
+    expect(SAFE_SYSTEM_PATHS.has("/dev/stderr")).toBe(true);
+  });
+});
+
+describe("isSafeSystemPath", () => {
+  test("returns true for /dev/null", () => {
+    expect(isSafeSystemPath("/dev/null")).toBe(true);
+  });
+
+  test("returns true for /dev/stdin", () => {
+    expect(isSafeSystemPath("/dev/stdin")).toBe(true);
+  });
+
+  test("returns true for /dev/stdout", () => {
+    expect(isSafeSystemPath("/dev/stdout")).toBe(true);
+  });
+
+  test("returns true for /dev/stderr", () => {
+    expect(isSafeSystemPath("/dev/stderr")).toBe(true);
+  });
+
+  test("returns false for an arbitrary absolute path", () => {
+    expect(isSafeSystemPath("/etc/passwd")).toBe(false);
+  });
+
+  test("returns false for a path prefixed with a safe system path", () => {
+    expect(isSafeSystemPath("/dev/null/subdir")).toBe(false);
+  });
+
+  test("returns false for an empty string", () => {
+    expect(isSafeSystemPath("")).toBe(false);
+  });
+
+  test("returns false for a relative path", () => {
+    expect(isSafeSystemPath("dev/null")).toBe(false);
+  });
+});
+
 describe("normalizePathForComparison", () => {
   const cwd = "/projects/my-app";
 
@@ -163,6 +208,26 @@ describe("isPathOutsideWorkingDirectory", () => {
   test("returns false for empty path (normalizes to empty string)", () => {
     expect(isPathOutsideWorkingDirectory("", cwd)).toBe(false);
   });
+
+  test("returns false for /dev/null regardless of cwd", () => {
+    expect(isPathOutsideWorkingDirectory("/dev/null", cwd)).toBe(false);
+  });
+
+  test("returns false for /dev/stdin regardless of cwd", () => {
+    expect(isPathOutsideWorkingDirectory("/dev/stdin", cwd)).toBe(false);
+  });
+
+  test("returns false for /dev/stdout regardless of cwd", () => {
+    expect(isPathOutsideWorkingDirectory("/dev/stdout", cwd)).toBe(false);
+  });
+
+  test("returns false for /dev/stderr regardless of cwd", () => {
+    expect(isPathOutsideWorkingDirectory("/dev/stderr", cwd)).toBe(false);
+  });
+
+  test("returns true for /dev/null/subdir (not a safe path)", () => {
+    expect(isPathOutsideWorkingDirectory("/dev/null/subdir", cwd)).toBe(true);
+  });
 });
 
 describe("formatExternalDirectoryHardStopHint", () => {

package/tests/permission-gate.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, it, vi } from "vitest";
+import type { PermissionPromptDecision } from "../src/permission-dialog";
+import {
+  applyPermissionGate,
+  type PermissionGateParams,
+} from "../src/permission-gate";
+
+function makeParams(
+  overrides: Partial<PermissionGateParams> = {},
+): PermissionGateParams {
+  return {
+    state: "allow",
+    canConfirm: true,
+    promptForApproval: vi.fn<() => Promise<PermissionPromptDecision>>(),
+    writeLog: vi.fn(),
+    logContext: { source: "test" },
+    messages: {
+      denyReason: "Denied by policy.",
+      unavailableReason: "No interactive UI available.",
+      userDeniedReason: (d) =>
+        d.denialReason
+          ? `User denied. Reason: ${d.denialReason}.`
+          : "User denied.",
+    },
+    ...overrides,
+  };
+}
+
+describe("applyPermissionGate", () => {
+  describe("deny branch", () => {
+    it("returns block with deny reason when state is deny", async () => {
+      const params = makeParams({ state: "deny" });
+      const result = await applyPermissionGate(params);
+      expect(result).toEqual({
+        action: "block",
+        reason: "Denied by policy.",
+      });
+    });
+
+    it("calls writeLog with policy_denied resolution", async () => {
+      const params = makeParams({
+        state: "deny",
+        logContext: { source: "tool_call", toolName: "bash" },
+      });
+      await applyPermissionGate(params);
+      expect(params.writeLog).toHaveBeenCalledOnce();
+      expect(params.writeLog).toHaveBeenCalledWith(
+        "permission_request.blocked",
+        {
+          source: "tool_call",
+          toolName: "bash",
+          resolution: "policy_denied",
+        },
+      );
+    });
+
+    it("does not call promptForApproval when state is deny", async () => {
+      const params = makeParams({ state: "deny" });
+      await applyPermissionGate(params);
+      expect(params.promptForApproval).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("ask branch — unavailable", () => {
+    it("returns block with unavailable reason when canConfirm is false", async () => {
+      const params = makeParams({ state: "ask", canConfirm: false });
+      const result = await applyPermissionGate(params);
+      expect(result).toEqual({
+        action: "block",
+        reason: "No interactive UI available.",
+      });
+    });
+
+    it("calls writeLog with confirmation_unavailable resolution", async () => {
+      const params = makeParams({
+        state: "ask",
+        canConfirm: false,
+        logContext: { source: "skill_read", skillName: "foo" },
+      });
+      await applyPermissionGate(params);
+      expect(params.writeLog).toHaveBeenCalledOnce();
+      expect(params.writeLog).toHaveBeenCalledWith(
+        "permission_request.blocked",
+        {
+          source: "skill_read",
+          skillName: "foo",
+          resolution: "confirmation_unavailable",
+        },
+      );
+    });
+
+    it("does not call promptForApproval when canConfirm is false", async () => {
+      const params = makeParams({ state: "ask", canConfirm: false });
+      await applyPermissionGate(params);
+      expect(params.promptForApproval).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("ask branch — user rejects", () => {
+    it("returns block with user-denied reason when user rejects", async () => {
+      const decision: PermissionPromptDecision = {
+        approved: false,
+        state: "denied",
+      };
+      const promptForApproval = vi.fn().mockResolvedValue(decision);
+      const params = makeParams({
+        state: "ask",
+        canConfirm: true,
+        promptForApproval,
+      });
+      const result = await applyPermissionGate(params);
+      expect(result).toEqual({ action: "block", reason: "User denied." });
+    });
+
+    it("passes denial reason through userDeniedReason formatter", async () => {
+      const decision: PermissionPromptDecision = {
+        approved: false,
+        state: "denied_with_reason",
+        denialReason: "not now",
+      };
+      const promptForApproval = vi.fn().mockResolvedValue(decision);
+      const params = makeParams({
+        state: "ask",
+        canConfirm: true,
+        promptForApproval,
+      });
+      const result = await applyPermissionGate(params);
+      expect(result).toEqual({
+        action: "block",
+        reason: "User denied. Reason: not now.",
+      });
+    });
+
+    it("does not call writeLog when user rejects (logged by promptPermission)", async () => {
+      const decision: PermissionPromptDecision = {
+        approved: false,
+        state: "denied",
+      };
+      const promptForApproval = vi.fn().mockResolvedValue(decision);
+      const params = makeParams({
+        state: "ask",
+        canConfirm: true,
+        promptForApproval,
+      });
+      await applyPermissionGate(params);
+      expect(params.writeLog).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("ask branch — user approves", () => {
+    it("returns allow when user approves", async () => {
+      const decision: PermissionPromptDecision = {
+        approved: true,
+        state: "approved",
+      };
+      const promptForApproval = vi.fn().mockResolvedValue(decision);
+      const params = makeParams({
+        state: "ask",
+        canConfirm: true,
+        promptForApproval,
+      });
+      const result = await applyPermissionGate(params);
+      expect(result).toEqual({ action: "allow" });
+    });
+
+    it("does not call writeLog when user approves", async () => {
+      const decision: PermissionPromptDecision = {
+        approved: true,
+        state: "approved",
+      };
+      const promptForApproval = vi.fn().mockResolvedValue(decision);
+      const params = makeParams({
+        state: "ask",
+        canConfirm: true,
+        promptForApproval,
+      });
+      await applyPermissionGate(params);
+      expect(params.writeLog).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("allow branch", () => {
+    it("returns allow immediately when state is allow", async () => {
+      const params = makeParams({ state: "allow" });
+      const result = await applyPermissionGate(params);
+      expect(result).toEqual({ action: "allow" });
+    });
+
+    it("does not call writeLog when state is allow", async () => {
+      const params = makeParams({ state: "allow" });
+      await applyPermissionGate(params);
+      expect(params.writeLog).not.toHaveBeenCalled();
+    });
+
+    it("does not call promptForApproval when state is allow", async () => {
+      const params = makeParams({ state: "allow" });
+      await applyPermissionGate(params);
+      expect(params.promptForApproval).not.toHaveBeenCalled();
+    });
+  });
+});

package/index.ts

@@ -1,3 +0,0 @@
-import permissionSystemExtension from "./src/index";
-
-export default permissionSystemExtension;