@gotgenes/pi-permission-system 5.5.1 → 5.6.0

package/src/handlers/gates/runner.ts

@@ -0,0 +1,144 @@
+import type { PermissionPromptDecision } from "../../permission-dialog";
+import { applyPermissionGate } from "../../permission-gate";
+import type { PermissionCheckResult } from "../../types";
+import type { GateDescriptor, GateRunnerDeps } from "./descriptor";
+import { deriveResolution } from "./helpers";
+import type { GateOutcome } from "./types";
+
+/**
+ * Execute the full check→log→emit→approve cycle for a gate descriptor.
+ *
+ * This is the single site for:
+ * - Permission checking (or using pre-resolved state)
+ * - Session-hit fast path
+ * - Interactive prompt orchestration
+ * - Decision event emission
+ * - Session-rule recording
+ *
+ * Gate functions produce descriptors; this runner executes them.
+ */
+export async function runGateCheck(
+  descriptor: GateDescriptor,
+  agentName: string | null,
+  toolCallId: string,
+  deps: GateRunnerDeps,
+): Promise<GateOutcome> {
+  // 1. Resolve permission state — pre-check, pre-resolved, or via checkPermission
+  let check: PermissionCheckResult;
+  if (descriptor.preCheck) {
+    check = descriptor.preCheck;
+  } else if (descriptor.preResolved) {
+    check = {
+      state: descriptor.preResolved.state,
+      toolName: descriptor.surface,
+      source: "tool",
+      origin: "builtin",
+    };
+  } else {
+    check = deps.checkPermission(
+      descriptor.surface,
+      descriptor.input,
+      agentName ?? undefined,
+      deps.getSessionRuleset(),
+    );
+  }
+
+  // 2. Session-hit fast path
+  if (check.source === "session") {
+    deps.writeReviewLog("permission_request.session_approved", {
+      ...descriptor.logContext,
+      agentName,
+      resolution: "session_approved",
+      sessionApprovalPattern: check.matchedPattern,
+    });
+    deps.emitDecision({
+      surface: descriptor.decision.surface,
+      value: descriptor.decision.value,
+      result: "allow",
+      resolution: "session_approved",
+      origin: check.origin ?? null,
+      agentName: agentName ?? null,
+      matchedPattern: check.matchedPattern ?? null,
+    });
+    return { action: "allow" };
+  }
+
+  // 3. Apply the deny/ask/allow gate
+  const canConfirm = deps.canConfirm();
+
+  // Resolve the first pattern for applyPermissionGate's sessionApproval param
+  const singleSessionApproval = descriptor.sessionApproval
+    ? "pattern" in descriptor.sessionApproval
+      ? {
+          surface: descriptor.sessionApproval.surface,
+          pattern: descriptor.sessionApproval.pattern,
+        }
+      : descriptor.sessionApproval.patterns.length > 0
+        ? {
+            surface: descriptor.sessionApproval.surface,
+            pattern: descriptor.sessionApproval.patterns[0],
+          }
+        : undefined
+    : undefined;
+
+  let autoApproved = false;
+  const gateResult = await applyPermissionGate({
+    state: check.state,
+    canConfirm,
+    sessionApproval: singleSessionApproval,
+    promptForApproval: async () => {
+      const decision = await deps.promptPermission({
+        requestId: toolCallId,
+        ...descriptor.promptDetails,
+      });
+      autoApproved = decision.autoApproved === true;
+      return decision;
+    },
+    writeLog: deps.writeReviewLog,
+    logContext: { ...descriptor.logContext, agentName },
+    messages: descriptor.messages,
+  });
+
+  // 4. Determine whether session approval was granted
+  const hasSessionApproval =
+    gateResult.action === "allow" && gateResult.sessionApproval !== undefined;
+
+  // 5. Emit decision event
+  deps.emitDecision({
+    surface: descriptor.decision.surface,
+    value: descriptor.decision.value,
+    result: gateResult.action === "allow" ? "allow" : "deny",
+    resolution: deriveResolution(
+      check.state,
+      gateResult.action,
+      hasSessionApproval,
+      canConfirm,
+      autoApproved,
+    ),
+    origin: check.origin ?? null,
+    agentName: agentName ?? null,
+    matchedPattern: check.matchedPattern ?? null,
+  });
+
+  // 6. Record session approval(s)
+  if (gateResult.action === "allow" && hasSessionApproval) {
+    if (descriptor.sessionApproval) {
+      if ("patterns" in descriptor.sessionApproval) {
+        for (const pattern of descriptor.sessionApproval.patterns) {
+          deps.approveSessionRule(descriptor.sessionApproval.surface, pattern);
+        }
+      } else {
+        deps.approveSessionRule(
+          descriptor.sessionApproval.surface,
+          descriptor.sessionApproval.pattern,
+        );
+      }
+    }
+  }
+
+  if (gateResult.action === "block") {
+    return { action: "block", reason: gateResult.reason };
+  }
+
+  return { action: "allow" };
+}

package/src/handlers/gates/skill-read.ts

@@ -1,27 +1,27 @@
 import { toRecord } from "../../common";
 import { normalizePathForComparison } from "../../external-directory";
-import { applyPermissionGate } from "../../permission-gate";
 import {
   formatSkillPathAskPrompt,
   formatSkillPathDenyReason,
 } from "../../permission-prompts";
+import type { SkillPromptEntry } from "../../skill-prompt-sanitizer";
 import { findSkillPathMatch } from "../../skill-prompt-sanitizer";
-import { deriveResolution } from "./helpers";
-import type { GateOutcome, SkillReadGateDeps, ToolCallContext } from "./types";
+import type { GateDescriptor } from "./descriptor";
+import type { ToolCallContext } from "./types";
 
 /**
- * Evaluate the skill-read permission gate.
+ * Build a pure descriptor for the skill-read permission gate.
  *
  * Returns `null` when the gate does not apply (tool is not `read`, no active
  * skill entries, or the read path does not match any skill).
+ * Returns a GateDescriptor with preResolved state from the matched skill entry.
  */
-export async function evaluateSkillReadGate(
+export function describeSkillReadGate(
   tcc: ToolCallContext,
-  deps: SkillReadGateDeps,
-): Promise<GateOutcome | null> {
-  const activeSkillEntries = deps.getActiveSkillEntries();
+  getActiveSkillEntries: () => SkillPromptEntry[],
+): GateDescriptor | null {
+  const activeSkillEntries = getActiveSkillEntries();
 
-  // Only applies to read tool calls with active skill entries
   if (tcc.toolName !== "read" || activeSkillEntries.length === 0) {
     return null;
   }
@@ -47,29 +47,10 @@ export async function evaluateSkillReadGate(
     path,
     tcc.agentName ?? undefined,
   );
-  const skillReadCanConfirm = deps.canConfirm();
-  const skillReadGate = await applyPermissionGate({
-    state: matchedSkill.state,
-    canConfirm: skillReadCanConfirm,
-    promptForApproval: () =>
-      deps.promptPermission({
-        requestId: tcc.toolCallId,
-        source: "skill_read",
-        agentName: tcc.agentName,
-        message: skillReadMessage,
-        toolCallId: tcc.toolCallId,
-        toolName: tcc.toolName,
-        skillName: matchedSkill.name,
-        path,
-      }),
-    writeLog: deps.writeReviewLog,
-    logContext: {
-      source: "skill_read",
-      skillName: matchedSkill.name,
-      agentName: tcc.agentName,
-      path,
-      message: skillReadMessage,
-    },
+
+  return {
+    surface: "skill",
+    input: { name: matchedSkill.name },
     messages: {
       denyReason: formatSkillPathDenyReason(
         matchedSkill,
@@ -84,26 +65,28 @@ export async function evaluateSkillReadGate(
         return `User denied access to skill '${matchedSkill.name}'.${denialReason}`;
       },
     },
-  });
-
-  deps.emitDecision({
-    surface: "skill",
-    value: matchedSkill.name,
-    result: skillReadGate.action === "allow" ? "allow" : "deny",
-    resolution: deriveResolution(
-      matchedSkill.state,
-      skillReadGate.action,
-      false,
-      skillReadCanConfirm,
-    ),
-    origin: null,
-    agentName: tcc.agentName ?? null,
-    matchedPattern: null,
-  });
-
-  if (skillReadGate.action === "block") {
-    return { action: "block", reason: skillReadGate.reason };
-  }
-
-  return { action: "allow" };
+    promptDetails: {
+      source: "skill_read",
+      agentName: tcc.agentName,
+      message: skillReadMessage,
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      skillName: matchedSkill.name,
+      path,
+    },
+    logContext: {
+      source: "skill_read",
+      skillName: matchedSkill.name,
+      agentName: tcc.agentName,
+      path,
+      message: skillReadMessage,
+    },
+    decision: {
+      surface: "skill",
+      value: matchedSkill.name,
+    },
+    preResolved: {
+      state: matchedSkill.state,
+    },
+  };
 }

package/src/handlers/gates/tool.ts

@@ -1,53 +1,26 @@
 import { PATH_BEARING_TOOLS } from "../../external-directory";
 import { suggestSessionPattern } from "../../pattern-suggest";
-import { applyPermissionGate } from "../../permission-gate";
 import {
   formatAskPrompt,
   formatDenyReason,
   formatUserDeniedReason,
 } from "../../permission-prompts";
 import { getPermissionLogContext } from "../../tool-input-preview";
-import { deriveDecisionValue, deriveResolution } from "./helpers";
-import type { GateOutcome, ToolCallContext, ToolGateDeps } from "./types";
+import type { PermissionCheckResult } from "../../types";
+import type { GateDescriptor } from "./descriptor";
+import { deriveDecisionValue } from "./helpers";
+import type { ToolCallContext } from "./types";
 
 /**
- * Evaluate the normal tool permission gate.
+ * Build a pure descriptor for the normal tool permission gate.
  *
- * Unlike the other gates this one always applies — it never returns `null`.
+ * Takes a pre-computed PermissionCheckResult (from checkPermission) and
+ * returns a GateDescriptor that the runner can execute. No side effects.
  */
-export async function evaluateToolGate(
+export function describeToolGate(
   tcc: ToolCallContext,
-  deps: ToolGateDeps,
-): Promise<GateOutcome> {
-  const check = deps.checkPermission(
-    tcc.toolName,
-    tcc.input,
-    tcc.agentName ?? undefined,
-    deps.getSessionRuleset(),
-  );
-
-  // Session-hit: already approved by a session rule — skip the gate entirely.
-  if (check.source === "session") {
-    deps.writeReviewLog("permission_request.session_approved", {
-      source: "tool_call",
-      toolCallId: tcc.toolCallId,
-      toolName: tcc.toolName,
-      agentName: tcc.agentName,
-      resolution: "session_approved",
-      sessionApprovalPattern: check.matchedPattern,
-    });
-    deps.emitDecision({
-      surface: tcc.toolName,
-      value: deriveDecisionValue(tcc.toolName, check),
-      result: "allow",
-      resolution: "session_approved",
-      origin: check.origin ?? null,
-      agentName: tcc.agentName ?? null,
-      matchedPattern: check.matchedPattern ?? null,
-    });
-    return { action: "allow" };
-  }
-
+  check: PermissionCheckResult,
+): GateDescriptor {
   const permissionLogContext = getPermissionLogContext(
     check,
     tcc.input,
@@ -69,85 +42,50 @@ export async function evaluateToolGate(
     typeof (tcc.input as Record<string, unknown>)?.command === "string"
       ? ((tcc.input as Record<string, unknown>).command as string)
       : null;
-  const toolUnavailableReason = inputCommand
+  const unavailableReason = inputCommand
     ? `Running bash command '${inputCommand}' requires approval, but no interactive UI is available.`
     : tcc.toolName === "mcp"
       ? "Using tool 'mcp' requires approval, but no interactive UI is available."
       : `Using tool '${tcc.toolName}' requires approval, but no interactive UI is available.`;
 
-  const toolAskMessage = formatAskPrompt(
+  const askMessage = formatAskPrompt(
     check,
     tcc.agentName ?? undefined,
     tcc.input,
   );
-  const toolCanConfirm = deps.canConfirm();
-  let toolDecisionAutoApproved = false;
-  const toolGate = await applyPermissionGate({
-    state: check.state,
-    canConfirm: toolCanConfirm,
+
+  return {
+    surface: tcc.toolName,
+    input: tcc.input,
+    messages: {
+      denyReason: formatDenyReason(check, tcc.agentName ?? undefined),
+      unavailableReason,
+      userDeniedReason: (decision) =>
+        formatUserDeniedReason(check, decision.denialReason),
+    },
     sessionApproval: {
       surface: suggestion.surface,
       pattern: suggestion.pattern,
     },
-    promptForApproval: async () => {
-      const decision = await deps.promptPermission({
-        requestId: tcc.toolCallId,
-        source: "tool_call",
-        agentName: tcc.agentName,
-        message: toolAskMessage,
-        toolCallId: tcc.toolCallId,
-        toolName: tcc.toolName,
-        sessionLabel: suggestion.label,
-        ...permissionLogContext,
-      });
-      toolDecisionAutoApproved = decision.autoApproved === true;
-      return decision;
+    promptDetails: {
+      source: "tool_call",
+      agentName: tcc.agentName,
+      message: askMessage,
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      sessionLabel: suggestion.label,
+      ...permissionLogContext,
     },
-    writeLog: deps.writeReviewLog,
     logContext: {
       source: "tool_call",
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
-      agentName: tcc.agentName,
-      message: toolAskMessage,
+      message: askMessage,
       ...permissionLogContext,
     },
-    messages: {
-      denyReason: formatDenyReason(check, tcc.agentName ?? undefined),
-      unavailableReason: toolUnavailableReason,
-      userDeniedReason: (decision) =>
-        formatUserDeniedReason(check, decision.denialReason),
+    decision: {
+      surface: tcc.toolName,
+      value: deriveDecisionValue(tcc.toolName, check),
     },
-  });
-
-  const toolGateHasSession =
-    toolGate.action === "allow" && toolGate.sessionApproval !== undefined;
-  deps.emitDecision({
-    surface: tcc.toolName,
-    value: deriveDecisionValue(tcc.toolName, check),
-    result: toolGate.action === "allow" ? "allow" : "deny",
-    resolution: deriveResolution(
-      check.state,
-      toolGate.action,
-      toolGateHasSession,
-      toolCanConfirm,
-      toolDecisionAutoApproved,
-    ),
-    origin: check.origin ?? null,
-    agentName: tcc.agentName ?? null,
-    matchedPattern: check.matchedPattern ?? null,
-  });
-
-  if (toolGate.action === "block") {
-    return { action: "block", reason: toolGate.reason };
-  }
-
-  if (toolGate.sessionApproval) {
-    deps.approveSessionRule(
-      toolGate.sessionApproval.surface,
-      toolGate.sessionApproval.pattern,
-    );
-  }
-
-  return { action: "allow" };
+  };
 }

package/src/handlers/gates/types.ts

@@ -1,12 +1,3 @@
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
-
-import type { PermissionPromptDecision } from "../../permission-dialog";
-import type { PermissionDecisionEvent } from "../../permission-events";
-import type { Rule } from "../../rule";
-import type { SkillPromptEntry } from "../../skill-prompt-sanitizer";
-import type { PermissionCheckResult } from "../../types";
-import type { PromptPermissionDetails } from "../types";
-
 /** Outcome of a single permission gate evaluation. */
 export type GateOutcome =
   | { action: "allow" }
@@ -20,71 +11,3 @@ export interface ToolCallContext {
   toolCallId: string;
   cwd: string | undefined;
 }
-
-// ── Per-gate narrow dependency interfaces ──────────────────────────────────
-
-/** Narrow deps for evaluateToolGate — every field is a leaf method. */
-export interface ToolGateDeps {
-  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>;
-}
-
-/** Narrow deps for evaluateExternalDirectoryGate. */
-export interface ExternalDirectoryGateDeps {
-  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>;
-  /** Resolved infrastructure dirs (static + config-based). */
-  getInfrastructureDirs(): string[];
-}
-
-/** Narrow deps for evaluateBashExternalDirectoryGate. */
-export interface BashExternalDirectoryGateDeps {
-  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;
-  canConfirm(): boolean;
-  promptPermission(
-    details: PromptPermissionDetails,
-  ): Promise<PermissionPromptDecision>;
-}
-
-/** Narrow deps for evaluateSkillReadGate. */
-export interface SkillReadGateDeps {
-  getActiveSkillEntries(): SkillPromptEntry[];
-  writeReviewLog(event: string, details: Record<string, unknown>): void;
-  emitDecision(event: PermissionDecisionEvent): void;
-  canConfirm(): boolean;
-  promptPermission(
-    details: PromptPermissionDetails,
-  ): Promise<PermissionPromptDecision>;
-}