@gotgenes/pi-permission-system 5.5.1 → 5.6.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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).
 
+## [5.6.0](https://github.com/gotgenes/pi-permission-system/compare/v5.5.1...v5.6.0) (2026-05-07)
+
+
+### Features
+
+* implement runGateCheck gate runner ([#118](https://github.com/gotgenes/pi-permission-system/issues/118)) ([46da4b6](https://github.com/gotgenes/pi-permission-system/commit/46da4b616cddef22d9e1d198a3aac9c640d62bac))
+
+
+### Documentation
+
+* plan gate runner extraction ([#118](https://github.com/gotgenes/pi-permission-system/issues/118)) ([8c0eb18](https://github.com/gotgenes/pi-permission-system/commit/8c0eb1881dabc19dba65f72ba5c30ae02e4070a0))
+* **retro:** add retro notes for issue [#111](https://github.com/gotgenes/pi-permission-system/issues/111) ([e327323](https://github.com/gotgenes/pi-permission-system/commit/e327323187822e779454eeafd7372c6256f869ba))
+* update target architecture for gate runner ([#118](https://github.com/gotgenes/pi-permission-system/issues/118)) ([40e1b1b](https://github.com/gotgenes/pi-permission-system/commit/40e1b1b016730e9be3da18fcb831001a2f498081))
+
 ## [5.5.1](https://github.com/gotgenes/pi-permission-system/compare/v5.5.0...v5.5.1) (2026-05-07)
 
 

package/package.json

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

package/src/handlers/gates/bash-external-directory.ts

@@ -5,26 +5,34 @@ import {
   formatBashExternalDirectoryDenyReason,
   formatExternalDirectoryHardStopHint,
 } from "../../external-directory";
-import type { PermissionPromptDecision } from "../../permission-dialog";
-import { applyPermissionGate } from "../../permission-gate";
+import type { Rule } from "../../rule";
 import { deriveApprovalPattern } from "../../session-rules";
-import type {
-  BashExternalDirectoryGateDeps,
-  GateOutcome,
-  ToolCallContext,
-} from "./types";
+import type { PermissionCheckResult } from "../../types";
+import type { GateResult } from "./descriptor";
+import type { ToolCallContext } from "./types";
+
+/** Function type for checkPermission used by the descriptor factory. */
+type CheckPermissionFn = (
+  surface: string,
+  input: unknown,
+  agentName?: string,
+  sessionRules?: Rule[],
+) => PermissionCheckResult;
 
 /**
- * Evaluate the bash external-directory permission gate.
+ * Build a pure descriptor for the bash external-directory permission gate.
  *
  * Extracts paths from a bash command and checks whether any reference
  * directories outside the working directory. Returns `null` when the gate
  * does not apply (tool is not bash, no CWD, or no external paths found).
+ * Returns a `GateBypass` when all paths are session-covered.
+ * Returns a `GateDescriptor` with multi-pattern sessionApproval for uncovered paths.
  */
-export async function evaluateBashExternalDirectoryGate(
+export async function describeBashExternalDirectoryGate(
   tcc: ToolCallContext,
-  deps: BashExternalDirectoryGateDeps,
-): Promise<GateOutcome | null> {
+  checkPermission: CheckPermissionFn,
+  getSessionRuleset: () => Rule[],
+): Promise<GateResult> {
   if (tcc.toolName !== "bash" || !tcc.cwd) return null;
 
   const command = getNonEmptyString(toRecord(tcc.input).command);
@@ -36,10 +44,10 @@ export async function evaluateBashExternalDirectoryGate(
   );
   if (externalPaths.length === 0) return null;
 
-  const bashSessionRules = deps.getSessionRuleset();
+  const bashSessionRules = getSessionRuleset();
   const uncoveredPaths = externalPaths.filter(
     (p) =>
-      deps.checkPermission(
+      checkPermission(
         "external_directory",
         { path: p },
         tcc.agentName ?? undefined,
@@ -48,58 +56,42 @@ export async function evaluateBashExternalDirectoryGate(
   );
 
   if (uncoveredPaths.length === 0) {
-    deps.writeReviewLog("permission_request.session_approved", {
-      source: "tool_call",
-      toolCallId: tcc.toolCallId,
-      toolName: tcc.toolName,
-      agentName: tcc.agentName,
-      command,
-      externalPaths,
-      resolution: "session_approved",
-    });
-    return null;
+    return {
+      action: "allow",
+      log: {
+        event: "permission_request.session_approved",
+        details: {
+          source: "tool_call",
+          toolCallId: tcc.toolCallId,
+          toolName: tcc.toolName,
+          agentName: tcc.agentName,
+          command,
+          externalPaths,
+          resolution: "session_approved",
+        },
+      },
+    };
   }
 
   // Get the config-level policy (no path → no session check).
-  const extCheck = deps.checkPermission(
+  const extCheck = checkPermission(
     "external_directory",
     {},
     tcc.agentName ?? undefined,
   );
 
-  let bashExtDecision: PermissionPromptDecision | null = null;
   const bashExtMessage = formatBashExternalDirectoryAskPrompt(
     command,
     uncoveredPaths,
     tcc.cwd,
     tcc.agentName ?? undefined,
   );
-  const bashExtGate = await applyPermissionGate({
-    state: extCheck.state,
-    canConfirm: deps.canConfirm(),
-    promptForApproval: async () => {
-      const decision = await deps.promptPermission({
-        requestId: tcc.toolCallId,
-        source: "tool_call",
-        agentName: tcc.agentName,
-        message: bashExtMessage,
-        toolCallId: tcc.toolCallId,
-        toolName: tcc.toolName,
-        command,
-      });
-      bashExtDecision = decision;
-      return decision;
-    },
-    writeLog: deps.writeReviewLog,
-    logContext: {
-      source: "tool_call",
-      toolCallId: tcc.toolCallId,
-      toolName: tcc.toolName,
-      agentName: tcc.agentName,
-      command,
-      externalPaths: uncoveredPaths,
-      message: bashExtMessage,
-    },
+
+  const patterns = uncoveredPaths.map((p) => deriveApprovalPattern(p));
+
+  return {
+    surface: "external_directory",
+    input: {},
     messages: {
       denyReason: formatBashExternalDirectoryDenyReason(
         command,
@@ -115,18 +107,31 @@ export async function evaluateBashExternalDirectoryGate(
         return `User denied external directory access for bash command '${command}'.${reasonSuffix} ${formatExternalDirectoryHardStopHint()}`;
       },
     },
-  });
-
-  if (bashExtGate.action === "block") {
-    return { action: "block", reason: bashExtGate.reason };
-  }
-
-  if (bashExtDecision?.state === "approved_for_session") {
-    for (const extPath of uncoveredPaths) {
-      const pattern = deriveApprovalPattern(extPath);
-      deps.approveSessionRule("external_directory", pattern);
-    }
-  }
-
-  return { action: "allow" };
+    sessionApproval: {
+      surface: "external_directory",
+      patterns,
+    },
+    promptDetails: {
+      source: "tool_call",
+      agentName: tcc.agentName,
+      message: bashExtMessage,
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      command,
+    },
+    logContext: {
+      source: "tool_call",
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      agentName: tcc.agentName,
+      command,
+      externalPaths: uncoveredPaths,
+      message: bashExtMessage,
+    },
+    decision: {
+      surface: "external_directory",
+      value: command,
+    },
+    preCheck: extCheck,
+  };
 }

package/src/handlers/gates/descriptor.ts

@@ -0,0 +1,115 @@
+import type { PermissionPromptDecision } from "../../permission-dialog";
+import type {
+  PermissionDecisionEvent,
+  PermissionDecisionResolution,
+} from "../../permission-events";
+import type { Rule } from "../../rule";
+import type { PermissionCheckResult, PermissionState } from "../../types";
+import type { PromptPermissionDetails } from "../types";
+
+// ── Descriptor types ───────────────────────────────────────────────────────
+
+/**
+ * Pure output of a gate function — describes what to check and how to present it.
+ *
+ * The gate runner (`runGateCheck`) uses this descriptor to execute the
+ * mechanical check→log→emit→approve cycle without the gate needing to know
+ * about logging, event emission, or session-rule recording.
+ */
+export interface GateDescriptor {
+  /** Permission surface to check (e.g. "bash", "external_directory", "skill"). */
+  surface: string;
+  /** Input passed to checkPermission. */
+  input: unknown;
+  /** Message strings/factories for each outcome. */
+  messages: {
+    denyReason: string;
+    unavailableReason: string;
+    userDeniedReason: (decision: PermissionPromptDecision) => string;
+  };
+  /**
+   * Session-approval suggestion for "for this session" option.
+   * Single pattern or multiple patterns (bash external-directory gate).
+   */
+  sessionApproval?:
+    | { surface: string; pattern: string }
+    | { surface: string; patterns: string[] };
+  /** Details passed to the interactive permission prompt (requestId is added by the runner). */
+  promptDetails: Omit<PromptPermissionDetails, "requestId">;
+  /** Extra context fields written to the review log alongside gate outcomes. */
+  logContext: Record<string, unknown>;
+  /** Surface and value for the decision event (may differ from the check surface). */
+  decision: {
+    surface: string;
+    value: string;
+  };
+  /**
+   * When set, the gate has already resolved the permission state
+   * (e.g. from a skill entry match). The runner uses this directly
+   * instead of calling checkPermission.
+   */
+  preResolved?: {
+    state: PermissionState;
+  };
+  /**
+   * When set, the runner uses this pre-computed check result directly
+   * instead of calling checkPermission. Used when the orchestrator has
+   * already performed the check (e.g. to build messages from the result).
+   */
+  preCheck?: PermissionCheckResult;
+}
+
+/**
+ * Early allow result — gate has determined the action without needing the runner.
+ *
+ * Used for cases like Pi infrastructure read bypass where the gate short-circuits
+ * with a deterministic allow before reaching the permission check.
+ */
+export interface GateBypass {
+  action: "allow";
+  /** Optional review log entry to emit. */
+  log?: { event: string; details: Record<string, unknown> };
+  /** Optional decision event to emit. */
+  decision?: PermissionDecisionEvent;
+}
+
+/** Union of possible gate function return values. */
+export type GateResult = GateDescriptor | GateBypass | null;
+
+// ── Runner dependency interface ────────────────────────────────────────────
+
+/**
+ * Infrastructure dependencies for the gate runner.
+ *
+ * Built once in the orchestrator and reused for all gates.
+ * Handles all side effects: permission checks, logging, event emission,
+ * session-rule recording.
+ */
+export interface GateRunnerDeps {
+  checkPermission(
+    surface: string,
+    input: unknown,
+    agentName?: string,
+    sessionRules?: Rule[],
+  ): PermissionCheckResult;
+  getSessionRuleset(): Rule[];
+  approveSessionRule(surface: string, pattern: string): void;
+  writeReviewLog(event: string, details: Record<string, unknown>): void;
+  emitDecision(event: PermissionDecisionEvent): void;
+  canConfirm(): boolean;
+  promptPermission(
+    details: PromptPermissionDetails,
+  ): Promise<PermissionPromptDecision>;
+}
+
+// ── Type guard helpers ─────────────────────────────────────────────────────
+
+/** Check whether a GateResult is a GateBypass (early allow). */
+export function isGateBypass(result: GateResult): result is GateBypass {
+  return result !== null && "action" in result;
+}
+
+/** Check whether a GateResult is a GateDescriptor (needs runner). */
+export function isGateDescriptor(result: GateResult): result is GateDescriptor {
+  return result !== null && !("action" in result);
+}

package/src/handlers/gates/external-directory.ts

@@ -7,26 +7,22 @@ import {
   isPiInfrastructureRead,
   normalizePathForComparison,
 } from "../../external-directory";
-import type { PermissionPromptDecision } from "../../permission-dialog";
-import { applyPermissionGate } from "../../permission-gate";
 import { deriveApprovalPattern } from "../../session-rules";
-import { deriveResolution } from "./helpers";
-import type {
-  ExternalDirectoryGateDeps,
-  GateOutcome,
-  ToolCallContext,
-} from "./types";
+import type { GateResult } from "./descriptor";
+import type { ToolCallContext } from "./types";
 
 /**
- * Evaluate the external-directory permission gate for file tools.
+ * Build a pure descriptor for the external-directory permission gate.
  *
  * Returns `null` when the gate does not apply (no CWD, tool is not
  * path-bearing, or path is inside the working directory).
+ * Returns a `GateBypass` for Pi infrastructure reads.
+ * Returns a `GateDescriptor` for external paths needing a permission check.
  */
-export async function evaluateExternalDirectoryGate(
+export function describeExternalDirectoryGate(
   tcc: ToolCallContext,
-  deps: ExternalDirectoryGateDeps,
-): Promise<GateOutcome | null> {
+  infraDirs: string[],
+): GateResult {
   if (!tcc.cwd) return null;
 
   const externalDirectoryPath = getPathBearingToolPath(tcc.toolName, tcc.input);
@@ -42,99 +38,46 @@ export async function evaluateExternalDirectoryGate(
   );
 
   // ── Pi infrastructure read bypass ──────────────────────────────────────
-  const allInfraDirs = deps.getInfrastructureDirs();
   if (
-    isPiInfrastructureRead(
-      tcc.toolName,
-      normalizedExtPath,
-      allInfraDirs,
-      tcc.cwd,
-    )
+    isPiInfrastructureRead(tcc.toolName, normalizedExtPath, infraDirs, tcc.cwd)
   ) {
-    deps.writeReviewLog("permission_request.infrastructure_auto_allowed", {
-      source: "tool_call",
-      toolCallId: tcc.toolCallId,
-      toolName: tcc.toolName,
-      agentName: tcc.agentName,
-      path: externalDirectoryPath,
-    });
-    deps.emitDecision({
-      surface: tcc.toolName,
-      value: externalDirectoryPath,
-      result: "allow",
-      resolution: "infrastructure_auto_allowed",
-      origin: null,
-      agentName: tcc.agentName ?? null,
-      matchedPattern: null,
-    });
-    return { action: "allow" };
+    return {
+      action: "allow",
+      log: {
+        event: "permission_request.infrastructure_auto_allowed",
+        details: {
+          source: "tool_call",
+          toolCallId: tcc.toolCallId,
+          toolName: tcc.toolName,
+          agentName: tcc.agentName,
+          path: externalDirectoryPath,
+        },
+      },
+      decision: {
+        surface: tcc.toolName,
+        value: externalDirectoryPath,
+        result: "allow",
+        resolution: "infrastructure_auto_allowed",
+        origin: null,
+        agentName: tcc.agentName ?? null,
+        matchedPattern: null,
+      },
+    };
   }
 
-  // ── Policy check ───────────────────────────────────────────────────────
-  const extCheck = deps.checkPermission(
-    "external_directory",
-    { path: normalizedExtPath },
-    tcc.agentName ?? undefined,
-    deps.getSessionRuleset(),
-  );
-
-  // Session-rule hit
-  if (extCheck.source === "session") {
-    deps.writeReviewLog("permission_request.session_approved", {
-      source: "tool_call",
-      toolCallId: tcc.toolCallId,
-      toolName: tcc.toolName,
-      agentName: tcc.agentName,
-      path: externalDirectoryPath,
-      resolution: "session_approved",
-      sessionApprovalPattern: extCheck.matchedPattern,
-    });
-    deps.emitDecision({
-      surface: "external_directory",
-      value: externalDirectoryPath,
-      result: "allow",
-      resolution: "session_approved",
-      origin: extCheck.origin ?? null,
-      agentName: tcc.agentName ?? null,
-      matchedPattern: extCheck.matchedPattern ?? null,
-    });
-    return { action: "allow" };
-  }
-
-  // ── Interactive gate ───────────────────────────────────────────────────
-  let extDirDecision: PermissionPromptDecision | null = null;
+  // ── Build descriptor for permission check ───────────────────────────────
   const extDirMessage = formatExternalDirectoryAskPrompt(
     tcc.toolName,
     externalDirectoryPath,
     tcc.cwd,
     tcc.agentName ?? undefined,
   );
-  const extDirCanConfirm = deps.canConfirm();
-  const extDirGateResult = await applyPermissionGate({
-    state: extCheck.state,
-    canConfirm: extDirCanConfirm,
-    promptForApproval: async () => {
-      const decision = await deps.promptPermission({
-        requestId: tcc.toolCallId,
-        source: "tool_call",
-        agentName: tcc.agentName,
-        message: extDirMessage,
-        toolCallId: tcc.toolCallId,
-        toolName: tcc.toolName,
-        path: externalDirectoryPath,
-      });
-      extDirDecision = decision;
-      return decision;
-    },
-    writeLog: deps.writeReviewLog,
-    logContext: {
-      source: "tool_call",
-      toolCallId: tcc.toolCallId,
-      toolName: tcc.toolName,
-      agentName: tcc.agentName,
-      path: externalDirectoryPath,
-      message: extDirMessage,
-    },
+
+  const pattern = deriveApprovalPattern(normalizedExtPath);
+
+  return {
+    surface: "external_directory",
+    input: { path: normalizedExtPath },
     messages: {
       denyReason: formatExternalDirectoryDenyReason(
         tcc.toolName,
@@ -150,31 +93,29 @@ export async function evaluateExternalDirectoryGate(
           decision.denialReason,
         ),
     },
-  });
-
-  deps.emitDecision({
-    surface: "external_directory",
-    value: externalDirectoryPath,
-    result: extDirGateResult.action === "allow" ? "allow" : "deny",
-    resolution: deriveResolution(
-      extCheck.state,
-      extDirGateResult.action,
-      extDirDecision?.state === "approved_for_session",
-      extDirCanConfirm,
-    ),
-    origin: extCheck.origin ?? null,
-    agentName: tcc.agentName ?? null,
-    matchedPattern: extCheck.matchedPattern ?? null,
-  });
-
-  if (extDirGateResult.action === "block") {
-    return { action: "block", reason: extDirGateResult.reason };
-  }
-
-  if (extDirDecision?.state === "approved_for_session") {
-    const pattern = deriveApprovalPattern(normalizedExtPath);
-    deps.approveSessionRule("external_directory", pattern);
-  }
-
-  return { action: "allow" };
+    sessionApproval: {
+      surface: "external_directory",
+      pattern,
+    },
+    promptDetails: {
+      source: "tool_call",
+      agentName: tcc.agentName,
+      message: extDirMessage,
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      path: externalDirectoryPath,
+    },
+    logContext: {
+      source: "tool_call",
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      agentName: tcc.agentName,
+      path: externalDirectoryPath,
+      message: extDirMessage,
+    },
+    decision: {
+      surface: "external_directory",
+      value: externalDirectoryPath,
+    },
+  };
 }

package/src/handlers/gates/index.ts

@@ -1,6 +1,14 @@
-export { evaluateBashExternalDirectoryGate } from "./bash-external-directory";
-export { evaluateExternalDirectoryGate } from "./external-directory";
+export { describeBashExternalDirectoryGate } from "./bash-external-directory";
+export type {
+  GateBypass,
+  GateDescriptor,
+  GateResult,
+  GateRunnerDeps,
+} from "./descriptor";
+export { isGateBypass, isGateDescriptor } from "./descriptor";
+export { describeExternalDirectoryGate } from "./external-directory";
 export { deriveDecisionValue, deriveResolution } from "./helpers";
-export { evaluateSkillReadGate } from "./skill-read";
-export { evaluateToolGate } from "./tool";
+export { runGateCheck } from "./runner";
+export { describeSkillReadGate } from "./skill-read";
+export { describeToolGate } from "./tool";
 export type { GateOutcome, ToolCallContext } from "./types";