@gotgenes/pi-permission-system 9.2.0 → 10.1.0

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

@@ -1,5 +1,5 @@
 import { getNonEmptyString, toRecord } from "#src/common";
-import type { Rule } from "#src/rule";
+import type { PermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { PermissionCheckResult } from "#src/types";
@@ -9,14 +9,6 @@ import type { GateResult } from "./descriptor";
 import { formatBashExternalDirectoryAskPrompt } from "./external-directory-messages";
 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;
-
 /**
  * Build a pure descriptor for the bash external-directory permission gate.
  *
@@ -29,8 +21,7 @@ type CheckPermissionFn = (
 export function describeBashExternalDirectoryGate(
   tcc: ToolCallContext,
   bashProgram: BashProgram | null,
-  checkPermission: CheckPermissionFn,
-  getSessionRuleset: () => Rule[],
+  resolver: PermissionResolver,
 ): GateResult {
   if (tcc.toolName !== "bash" || !tcc.cwd) return null;
 
@@ -42,8 +33,6 @@ export function describeBashExternalDirectoryGate(
   const externalPaths = bashProgram.externalPaths(tcc.cwd);
   if (externalPaths.length === 0) return null;
 
-  const bashSessionRules = getSessionRuleset();
-
   // Collect paths whose resolved state is not already "allow".
   // Checking state (not source) ensures config-level allow rules (source: "special")
   // suppress the prompt just as session-level allow rules (source: "session") do.
@@ -52,11 +41,10 @@ export function describeBashExternalDirectoryGate(
     check: PermissionCheckResult;
   }> = [];
   for (const p of externalPaths) {
-    const check = checkPermission(
+    const check = resolver.resolve(
       "external_directory",
       { path: p },
       tcc.agentName ?? undefined,
-      bashSessionRules,
     );
     if (check.state !== "allow") {
       uncoveredEntries.push({ path: p, check });

package/src/handlers/gates/bash-path.ts

@@ -1,5 +1,5 @@
 import { getNonEmptyString, toRecord } from "#src/common";
-import type { Rule } from "#src/rule";
+import type { PermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { PermissionCheckResult } from "#src/types";
@@ -9,14 +9,6 @@ import type { GateResult } from "./descriptor";
 import { formatPathAskPrompt } from "./path";
 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;
-
 /**
  * Build a pure descriptor for the cross-cutting path permission gate (bash).
  *
@@ -33,8 +25,7 @@ type CheckPermissionFn = (
 export function describeBashPathGate(
   tcc: ToolCallContext,
   bashProgram: BashProgram | null,
-  checkPermission: CheckPermissionFn,
-  getSessionRuleset: () => Rule[],
+  resolver: PermissionResolver,
 ): GateResult {
   if (tcc.toolName !== "bash") return null;
 
@@ -46,20 +37,16 @@ export function describeBashPathGate(
   const tokens = bashProgram.pathTokens();
   if (tokens.length === 0) return null;
 
-  // Check each token against path rules with session rules appended.
-  const sessionRules = getSessionRuleset();
-
   // Tokens whose resolved state needs a check (deny/ask), paired with the
   // token that produced them so the descriptor can derive its pattern.
   const uncovered: Array<{ token: string; check: PermissionCheckResult }> = [];
   let allSessionCovered = true;
 
   for (const token of tokens) {
-    const check = checkPermission(
+    const check = resolver.resolve(
       "path",
       { path: token },
       tcc.agentName ?? undefined,
-      sessionRules,
     );
 
     // No explicit path rule matched — only the universal default fired.

package/src/handlers/gates/descriptor.ts

@@ -1,8 +1,6 @@
 import type { DenialContext } from "#src/denial-messages";
-import type { PermissionPromptDecision } from "#src/permission-dialog";
 import type { PermissionDecisionEvent } from "#src/permission-events";
 import type { PromptPermissionDetails } from "#src/permission-prompter";
-import type { Rule } from "#src/rule";
 import type { SessionApproval } from "#src/session-approval";
 import type { PermissionCheckResult, PermissionState } from "#src/types";
 
@@ -70,32 +68,6 @@ export interface GateBypass {
 /** 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[];
-  recordSessionApproval(approval: SessionApproval): 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). */

package/src/handlers/gates/path.ts

@@ -1,19 +1,10 @@
 import { getPathBearingToolPath } from "#src/path-utils";
-import type { Rule } from "#src/rule";
+import type { PermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
-import type { PermissionCheckResult } from "#src/types";
 import type { GateDescriptor, 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;
-
 /**
  * Build a pure descriptor for the cross-cutting path permission gate (tools).
  *
@@ -24,18 +15,15 @@ type CheckPermissionFn = (
  */
 export function describePathGate(
   tcc: ToolCallContext,
-  checkPermission: CheckPermissionFn,
-  getSessionRuleset: () => Rule[],
+  resolver: PermissionResolver,
 ): GateResult {
   const filePath = getPathBearingToolPath(tcc.toolName, tcc.input);
   if (!filePath) return null;
 
-  const sessionRules = getSessionRuleset();
-  const check = checkPermission(
+  const check = resolver.resolve(
     "path",
     { path: filePath },
     tcc.agentName ?? undefined,
-    sessionRules,
   );
 
   if (check.state === "allow") return null;

package/src/handlers/gates/runner.ts

@@ -1,133 +1,170 @@
+import type { DecisionReporter } from "#src/decision-reporter";
 import {
   formatDenyReason,
   formatUnavailableReason,
   formatUserDeniedReason,
 } from "#src/denial-messages";
+import type { GatePrompter } from "#src/gate-prompter";
 import type { PermissionPromptDecision } from "#src/permission-dialog";
 import { applyPermissionGate } from "#src/permission-gate";
+import type { PermissionResolver } from "#src/permission-resolver";
+import type { SessionApprovalRecorder } from "#src/session-approval-recorder";
 import type { PermissionCheckResult } from "#src/types";
-import type { GateDescriptor, GateRunnerDeps } from "./descriptor";
+import type { GateDescriptor, GateResult } from "./descriptor";
+import { isGateBypass } from "./descriptor";
 import { buildDecisionEvent, deriveResolution } from "./helpers";
 import type { GateOutcome } from "./types";
 
+// ── GateRunner class ───────────────────────────────────────────────────────
+
 /**
- * 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
+ * Executes permission gate checks for a single gate result (null, bypass, or
+ * descriptor).
  *
- * Gate functions produce descriptors; this runner executes them.
+ * Constructed once per handler with its four role collaborators and reused
+ * for every gate in a tool-call pipeline. The `run` method absorbs the null /
+ * bypass / descriptor dispatch that previously lived as an anonymous closure
+ * in `PermissionGateHandler.handleToolCall`.
  */
-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(),
-    );
+export class GateRunner {
+  constructor(
+    private readonly resolver: PermissionResolver,
+    private readonly recorder: SessionApprovalRecorder,
+    private readonly prompter: GatePrompter,
+    private readonly reporter: DecisionReporter,
+  ) {}
+
+  /**
+   * Execute a gate: null → allow; bypass → log/emit side effects then allow;
+   * descriptor → full check→log→emit→approve cycle.
+   */
+  async run(
+    gate: GateResult,
+    agentName: string | null,
+    toolCallId: string,
+  ): Promise<GateOutcome> {
+    if (!gate) {
+      return { action: "allow" };
+    }
+    if (isGateBypass(gate)) {
+      if (gate.log) {
+        this.reporter.writeReviewLog(gate.log.event, gate.log.details);
+      }
+      if (gate.decision) {
+        this.reporter.emitDecision(gate.decision);
+      }
+      return { action: "allow" };
+    }
+    return this.runDescriptor(gate, agentName, toolCallId);
   }
 
-  // 2. Session-hit fast path
-  if (check.source === "session") {
-    deps.writeReviewLog("permission_request.session_approved", {
-      ...descriptor.logContext,
-      agentName,
-      resolution: "session_approved",
-      sessionApprovalPattern: check.matchedPattern,
+  // ── Private helpers ──────────────────────────────────────────────────────
+
+  private async runDescriptor(
+    descriptor: GateDescriptor,
+    agentName: string | null,
+    toolCallId: string,
+  ): Promise<GateOutcome> {
+    // 1. Resolve permission state — pre-check, pre-resolved, or via resolver
+    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 = this.resolver.resolve(
+        descriptor.surface,
+        descriptor.input,
+        agentName ?? undefined,
+      );
+    }
+
+    // 2. Session-hit fast path
+    if (check.source === "session") {
+      this.reporter.writeReviewLog("permission_request.session_approved", {
+        ...descriptor.logContext,
+        agentName,
+        resolution: "session_approved",
+        sessionApprovalPattern: check.matchedPattern,
+      });
+      this.reporter.emitDecision(
+        buildDecisionEvent(
+          descriptor.decision,
+          check,
+          agentName,
+          "allow",
+          "session_approved",
+        ),
+      );
+      return { action: "allow" };
+    }
+
+    // 3. Apply the deny/ask/allow gate
+    const canConfirm = this.prompter.canConfirm();
+
+    // Construct messages from the centralized formatter.
+    const messages = {
+      denyReason: formatDenyReason(descriptor.denialContext),
+      unavailableReason: formatUnavailableReason(descriptor.denialContext),
+      userDeniedReason: (decision: PermissionPromptDecision) =>
+        formatUserDeniedReason(descriptor.denialContext, decision.denialReason),
+    };
+
+    let autoApproved = false;
+    const gateResult = await applyPermissionGate({
+      state: check.state,
+      canConfirm,
+      sessionApproval: descriptor.sessionApproval?.toGateApproval(),
+      promptForApproval: async () => {
+        const decision = await this.prompter.promptPermission({
+          requestId: toolCallId,
+          ...descriptor.promptDetails,
+        });
+        autoApproved = decision.autoApproved === true;
+        return decision;
+      },
+      writeLog: (event, details) =>
+        this.reporter.writeReviewLog(event, details),
+      logContext: { ...descriptor.logContext, agentName },
+      messages,
     });
-    deps.emitDecision(
+
+    // 4. Determine whether session approval was granted
+    const hasSessionApproval =
+      gateResult.action === "allow" && gateResult.sessionApproval !== undefined;
+
+    // 5. Emit decision event
+    this.reporter.emitDecision(
       buildDecisionEvent(
         descriptor.decision,
         check,
         agentName,
-        "allow",
-        "session_approved",
+        gateResult.action === "allow" ? "allow" : "deny",
+        deriveResolution(
+          check.state,
+          gateResult.action,
+          hasSessionApproval,
+          canConfirm,
+          autoApproved,
+        ),
       ),
     );
-    return { action: "allow" };
-  }
 
-  // 3. Apply the deny/ask/allow gate
-  const canConfirm = deps.canConfirm();
-
-  // Construct messages from the centralized formatter.
-  const messages = {
-    denyReason: formatDenyReason(descriptor.denialContext),
-    unavailableReason: formatUnavailableReason(descriptor.denialContext),
-    userDeniedReason: (decision: PermissionPromptDecision) =>
-      formatUserDeniedReason(descriptor.denialContext, decision.denialReason),
-  };
-
-  let autoApproved = false;
-  const gateResult = await applyPermissionGate({
-    state: check.state,
-    canConfirm,
-    sessionApproval: descriptor.sessionApproval?.toGateApproval(),
-    promptForApproval: async () => {
-      const decision = await deps.promptPermission({
-        requestId: toolCallId,
-        ...descriptor.promptDetails,
-      });
-      autoApproved = decision.autoApproved === true;
-      return decision;
-    },
-    // eslint-disable-next-line @typescript-eslint/unbound-method -- logger methods are plain functions; no this-binding issue
-    writeLog: deps.writeReviewLog,
-    logContext: { ...descriptor.logContext, agentName },
-    messages,
-  });
+    // 6. Record session approval — tell the store; it owns the per-pattern loop
+    // hasSessionApproval already implies gateResult.action === "allow"
+    if (hasSessionApproval && descriptor.sessionApproval) {
+      this.recorder.recordSessionApproval(descriptor.sessionApproval);
+    }
 
-  // 4. Determine whether session approval was granted
-  const hasSessionApproval =
-    gateResult.action === "allow" && gateResult.sessionApproval !== undefined;
+    if (gateResult.action === "block") {
+      return { action: "block", reason: gateResult.reason };
+    }
 
-  // 5. Emit decision event
-  deps.emitDecision(
-    buildDecisionEvent(
-      descriptor.decision,
-      check,
-      agentName,
-      gateResult.action === "allow" ? "allow" : "deny",
-      deriveResolution(
-        check.state,
-        gateResult.action,
-        hasSessionApproval,
-        canConfirm,
-        autoApproved,
-      ),
-    ),
-  );
-
-  // 6. Record session approval — tell the store; it owns the per-pattern loop
-  // hasSessionApproval already implies gateResult.action === "allow"
-  if (hasSessionApproval && descriptor.sessionApproval) {
-    deps.recordSessionApproval(descriptor.sessionApproval);
-  }
-
-  if (gateResult.action === "block") {
-    return { action: "block", reason: gateResult.reason };
+    return { action: "allow" };
   }
-
-  return { action: "allow" };
 }

package/src/handlers/gates/skill-input-gate-pipeline.ts

@@ -0,0 +1,104 @@
+import type { PermissionCheckResult } from "#src/types";
+import type { GateRunner } from "./runner";
+import { describeSkillInputGate } from "./skill-input";
+import type { GateOutcome } from "./types";
+
+// ── Interfaces ────────────────────────────────────────────────────────────────
+
+/**
+ * Narrow interface the pipeline needs from its session-side dependency.
+ *
+ * A raw `checkPermission` (no session rules) — preserves the skill-input
+ * semantics established in #326 where the skill-input gate intentionally
+ * bypasses session-rule resolution.
+ *
+ * `PermissionSession` satisfies this structurally at the construction call
+ * site; no `implements` clause is needed and would create a layer-inversion
+ * import from the domain module into the handler layer.
+ */
+export interface SkillInputGateInputs {
+  checkPermission(
+    surface: string,
+    input: unknown,
+    agentName?: string,
+  ): PermissionCheckResult;
+}
+
+/**
+ * Narrow UI seam: warn the user when a skill is denied.
+ *
+ * The handler builds this per-event from `ctx`, encapsulating the `hasUI`
+ * guard so the pipeline never touches `ExtensionContext` directly
+ * (Tell-Don't-Ask: the pipeline tells the notifier to warn; the notifier
+ * decides whether a UI is present).
+ */
+export interface GateNotifier {
+  warn(message: string): void;
+}
+
+// ── Pipeline ─────────────────────────────────────────────────────────────────
+
+/**
+ * Owns the skill-input gate assembly: raw permission pre-check, deny notify,
+ * `describeSkillInputGate` descriptor, request-id mint, and `runner.run(...)`.
+ *
+ * Constructed once in the composition root and injected into
+ * `PermissionGateHandler`, mirroring `ToolCallGatePipeline` for the `input`
+ * path.
+ *
+ * `evaluate` is not `async` because it has no `await` of its own — it returns
+ * `runner.run(...)` directly (`@typescript-eslint/require-await` would reject
+ * an `async` body with no `await`).
+ */
+export class SkillInputGatePipeline {
+  constructor(private readonly inputs: SkillInputGateInputs) {}
+
+  evaluate(
+    skillName: string,
+    agentName: string | null,
+    notifier: GateNotifier,
+    runner: GateRunner,
+  ): Promise<GateOutcome> {
+    const check = this.inputs.checkPermission(
+      "skill",
+      { name: skillName },
+      agentName ?? undefined,
+    );
+    if (check.state === "deny") {
+      notifier.warn(formatSkillDenyNotice(skillName, agentName));
+    }
+    return runner.run(
+      describeSkillInputGate(skillName, agentName, check),
+      agentName,
+      createSkillInputRequestId(),
+    );
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Mint a unique id for a skill-input permission request.
+ *
+ * Format is `skill-input-<timestamp>-<random>-<pid>`, matching the
+ * `createPermissionRequestId("skill-input")` pattern it replaces (#330).
+ */
+export function createSkillInputRequestId(): string {
+  return `skill-input-${Date.now()}-${Math.random().toString(36).slice(2, 10)}-${process.pid}`;
+}
+
+/**
+ * Format the deny warning shown in the UI when a skill is blocked.
+ *
+ * Intentionally untagged (no `[pi-permission-system]` prefix) — this is a
+ * UI notify distinct from the gate deny reasons the runner routes through
+ * `formatDenyReason`.
+ */
+export function formatSkillDenyNotice(
+  skillName: string,
+  agentName: string | null,
+): string {
+  return agentName
+    ? `Skill '${skillName}' is not permitted for agent '${agentName}'.`
+    : `Skill '${skillName}' is not permitted by the current skill policy.`;
+}

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

@@ -0,0 +1,44 @@
+import { formatSkillAskPrompt } from "#src/permission-prompts";
+import type { PermissionCheckResult } from "#src/types";
+import type { GateDescriptor } from "./descriptor";
+
+/**
+ * Build a pure descriptor for the skill-input permission gate.
+ *
+ * Takes the pre-computed check result so the gate can reuse the result the
+ * caller already obtained (e.g. to conditionally emit a deny warning) without
+ * re-running the check inside the runner.
+ */
+export function describeSkillInputGate(
+  skillName: string,
+  agentName: string | null,
+  preCheck: PermissionCheckResult,
+): GateDescriptor {
+  const message = formatSkillAskPrompt(skillName, agentName ?? undefined);
+  return {
+    surface: "skill",
+    input: { name: skillName },
+    preCheck,
+    denialContext: {
+      kind: "skill_input",
+      skillName,
+      agentName: agentName ?? undefined,
+    },
+    promptDetails: {
+      source: "skill_input",
+      agentName,
+      message,
+      skillName,
+    },
+    logContext: {
+      source: "skill_input",
+      skillName,
+      agentName,
+      message,
+    },
+    decision: {
+      surface: "skill",
+      value: skillName,
+    },
+  };
+}