@gotgenes/pi-permission-system 5.5.0 → 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,28 +1,28 @@
 import { toRecord } from "../../common";
 import { normalizePathForComparison } from "../../external-directory";
-import { emitDecisionEvent } from "../../permission-events";
-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 type { HandlerDeps } from "../types";
-import { deriveResolution } from "./helpers";
-import type { GateOutcome, 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: HandlerDeps,
-): Promise<GateOutcome | null> {
-  // Only applies to read tool calls with active skill entries
-  if (tcc.toolName !== "read" || deps.runtime.activeSkillEntries.length === 0) {
+  getActiveSkillEntries: () => SkillPromptEntry[],
+): GateDescriptor | null {
+  const activeSkillEntries = getActiveSkillEntries();
+
+  if (tcc.toolName !== "read" || activeSkillEntries.length === 0) {
     return null;
   }
 
@@ -35,7 +35,7 @@ export async function evaluateSkillReadGate(
   const normalizedReadPath = normalizePathForComparison(path, tcc.cwd);
   const matchedSkill = findSkillPathMatch(
     normalizedReadPath,
-    deps.runtime.activeSkillEntries,
+    activeSkillEntries,
   );
 
   if (!matchedSkill) {
@@ -47,31 +47,10 @@ export async function evaluateSkillReadGate(
     path,
     tcc.agentName ?? undefined,
   );
-  const skillReadCanConfirm = deps.canRequestPermissionConfirmation(
-    deps.runtime.runtimeContext!,
-  );
-  const skillReadGate = await applyPermissionGate({
-    state: matchedSkill.state,
-    canConfirm: skillReadCanConfirm,
-    promptForApproval: () =>
-      deps.promptPermission(deps.runtime.runtimeContext!, {
-        requestId: tcc.toolCallId,
-        source: "skill_read",
-        agentName: tcc.agentName,
-        message: skillReadMessage,
-        toolCallId: tcc.toolCallId,
-        toolName: tcc.toolName,
-        skillName: matchedSkill.name,
-        path,
-      }),
-    writeLog: deps.runtime.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,
@@ -86,26 +65,28 @@ export async function evaluateSkillReadGate(
         return `User denied access to skill '${matchedSkill.name}'.${denialReason}`;
       },
     },
-  });
-
-  emitDecisionEvent(deps.events, {
-    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,55 +1,26 @@
 import { PATH_BEARING_TOOLS } from "../../external-directory";
 import { suggestSessionPattern } from "../../pattern-suggest";
-import { emitDecisionEvent } from "../../permission-events";
-import { applyPermissionGate } from "../../permission-gate";
 import {
   formatAskPrompt,
   formatDenyReason,
   formatUserDeniedReason,
 } from "../../permission-prompts";
 import { getPermissionLogContext } from "../../tool-input-preview";
-import type { HandlerDeps } from "../types";
-import { deriveDecisionValue, deriveResolution } from "./helpers";
-import type { GateOutcome, ToolCallContext } 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: HandlerDeps,
-): Promise<GateOutcome> {
-  const check = deps.runtime.permissionManager.checkPermission(
-    tcc.toolName,
-    tcc.input,
-    tcc.agentName ?? undefined,
-    deps.runtime.sessionRules.getRuleset(),
-  );
-
-  // Session-hit: already approved by a session rule — skip the gate entirely.
-  if (check.source === "session") {
-    deps.runtime.writeReviewLog("permission_request.session_approved", {
-      source: "tool_call",
-      toolCallId: tcc.toolCallId,
-      toolName: tcc.toolName,
-      agentName: tcc.agentName,
-      resolution: "session_approved",
-      sessionApprovalPattern: check.matchedPattern,
-    });
-    emitDecisionEvent(deps.events, {
-      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,
@@ -71,90 +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.canRequestPermissionConfirmation(
-    deps.runtime.runtimeContext!,
-  );
-  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(
-        deps.runtime.runtimeContext!,
-        {
-          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.runtime.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;
-  emitDecisionEvent(deps.events, {
-    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.runtime.sessionRules.approve(
-      toolGate.sessionApproval.surface,
-      toolGate.sessionApproval.pattern,
-    );
-  }
-
-  return { action: "allow" };
+  };
 }

package/src/handlers/gates/types.ts

@@ -1,5 +1,3 @@
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
-
 /** Outcome of a single permission gate evaluation. */
 export type GateOutcome =
   | { action: "allow" }

package/src/handlers/input.ts

@@ -40,7 +40,7 @@ export async function handleInput(
   event: InputPayload,
   ctx: ExtensionContext,
 ): Promise<InputEventResult> {
-  deps.runtime.runtimeContext = ctx;
+  deps.session.runtimeContext = ctx;
   deps.startForwardedPermissionPolling(ctx);
 
   const skillName = extractSkillNameFromInput(event.text);
@@ -49,7 +49,7 @@ export async function handleInput(
   }
 
   const agentName = deps.resolveAgentName(ctx);
-  const check = deps.runtime.permissionManager.checkPermission(
+  const check = deps.session.permissionManager.checkPermission(
     "skill",
     { name: skillName },
     agentName ?? undefined,
@@ -82,7 +82,7 @@ export async function handleInput(
       skillInputAutoApproved = decision.autoApproved === true;
       return decision;
     },
-    writeLog: deps.runtime.writeReviewLog,
+    writeLog: deps.writeReviewLog,
     logContext: {
       source: "skill_input",
       skillName,

package/src/handlers/lifecycle.ts

@@ -19,25 +19,25 @@ export async function handleSessionStart(
   event: SessionStartPayload,
   ctx: ExtensionContext,
 ): Promise<void> {
-  deps.runtime.runtimeContext = ctx;
+  deps.session.runtimeContext = ctx;
   deps.refreshExtensionConfig(ctx);
-  deps.runtime.permissionManager = deps.createPermissionManagerForCwd(ctx.cwd);
-  deps.runtime.activeSkillEntries = [];
-  deps.runtime.lastActiveToolsCacheKey = null;
-  deps.runtime.lastPromptStateCacheKey = null;
-  deps.runtime.lastKnownActiveAgentName = getActiveAgentName(ctx);
+  deps.session.permissionManager = deps.createPermissionManagerForCwd(ctx.cwd);
+  deps.session.activeSkillEntries = [];
+  deps.session.lastActiveToolsCacheKey = null;
+  deps.session.lastPromptStateCacheKey = null;
+  deps.session.lastKnownActiveAgentName = getActiveAgentName(ctx);
   deps.startForwardedPermissionPolling(ctx);
   deps.logResolvedConfigPaths();
 
-  const agentName = deps.runtime.lastKnownActiveAgentName;
+  const agentName = deps.session.lastKnownActiveAgentName;
   const policyIssues =
-    deps.runtime.permissionManager.getConfigIssues(agentName);
+    deps.session.permissionManager.getConfigIssues(agentName);
   for (const issue of policyIssues) {
     deps.notifyWarning(issue);
   }
 
   if (event.reason === "reload") {
-    deps.runtime.writeDebugLog("lifecycle.reload", {
+    deps.writeDebugLog("lifecycle.reload", {
       triggeredBy: "session_start",
       reason: event.reason,
       cwd: ctx.cwd,
@@ -53,14 +53,14 @@ export async function handleResourcesDiscover(
     return;
   }
 
-  const { runtimeContext } = deps.runtime;
-  deps.runtime.permissionManager = deps.createPermissionManagerForCwd(
+  const { runtimeContext } = deps.session;
+  deps.session.permissionManager = deps.createPermissionManagerForCwd(
     runtimeContext?.cwd,
   );
-  deps.runtime.activeSkillEntries = [];
-  deps.runtime.lastActiveToolsCacheKey = null;
-  deps.runtime.lastPromptStateCacheKey = null;
-  deps.runtime.writeDebugLog("lifecycle.reload", {
+  deps.session.activeSkillEntries = [];
+  deps.session.lastActiveToolsCacheKey = null;
+  deps.session.lastPromptStateCacheKey = null;
+  deps.writeDebugLog("lifecycle.reload", {
     triggeredBy: "resources_discover",
     reason: event.reason,
     cwd: runtimeContext?.cwd ?? null,
@@ -68,15 +68,15 @@ export async function handleResourcesDiscover(
 }
 
 export async function handleSessionShutdown(deps: HandlerDeps): Promise<void> {
-  const { runtimeContext } = deps.runtime;
+  const { runtimeContext } = deps.session;
   if (runtimeContext) {
     runtimeContext.ui.setStatus(PERMISSION_SYSTEM_STATUS_KEY, undefined);
   }
-  deps.runtime.runtimeContext = null;
-  deps.runtime.activeSkillEntries = [];
-  deps.runtime.lastActiveToolsCacheKey = null;
-  deps.runtime.lastPromptStateCacheKey = null;
-  deps.runtime.sessionRules.clear();
+  deps.session.runtimeContext = null;
+  deps.session.activeSkillEntries = [];
+  deps.session.lastActiveToolsCacheKey = null;
+  deps.session.lastPromptStateCacheKey = null;
+  deps.session.sessionRules.clear();
   deps.stopForwardedPermissionPolling();
   deps.stopPermissionRpcHandlers();
 }