@komarspn/pi-permission-system 16.0.2

package/src/handlers/gates/runner.ts

@@ -0,0 +1,186 @@
+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 { PersistentApprovalRecorder } from "#src/persistent-approval-recorder";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import type { SessionApprovalRecorder } from "#src/session-approval-recorder";
+import type { PermissionCheckResult } from "#src/types";
+import type { GateDescriptor, GateResult } from "./descriptor";
+import { isGateBypass } from "./descriptor";
+import { buildDecisionEvent, deriveResolution } from "./helpers";
+import type { GateOutcome } from "./types";
+
+// ── GateRunner class ───────────────────────────────────────────────────────
+
+/**
+ * Executes permission gate checks for a single gate result (null, bypass, or
+ * descriptor).
+ *
+ * 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 class GateRunner {
+  constructor(
+    private readonly resolver: ScopedPermissionResolver,
+    private readonly recorder: SessionApprovalRecorder,
+    private readonly prompter: GatePrompter,
+    private readonly reporter: DecisionReporter,
+    private readonly persistentRecorder: PersistentApprovalRecorder,
+  ) {}
+
+  /**
+   * 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);
+  }
+
+  // ── 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.prompt({
+          requestId: toolCallId,
+          ...descriptor.promptDetails,
+        });
+        autoApproved = decision.autoApproved === true;
+        return decision;
+      },
+      writeLog: (event, details) =>
+        this.reporter.writeReviewLog(event, details),
+      logContext: { ...descriptor.logContext, agentName },
+      messages,
+    });
+
+    // 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,
+        gateResult.action === "allow" ? "allow" : "deny",
+        deriveResolution(
+          check.state,
+          gateResult.action,
+          hasSessionApproval,
+          canConfirm,
+          autoApproved,
+          gateResult.action === "allow"
+            ? gateResult.persistentApprovalScope
+            : undefined,
+        ),
+      ),
+    );
+
+    // 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);
+    }
+
+    if (
+      gateResult.action === "allow" &&
+      gateResult.persistentApprovalScope &&
+      descriptor.sessionApproval
+    ) {
+      this.persistentRecorder.recordApproval(
+        gateResult.persistentApprovalScope,
+        descriptor.sessionApproval,
+      );
+    }
+
+    if (gateResult.action === "block") {
+      return { action: "block", reason: gateResult.reason };
+    }
+
+    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,46 @@
+import { formatSkillAskPrompt } from "#src/permission-prompts";
+import { SessionApproval } from "#src/session-approval";
+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,
+    },
+    sessionApproval: SessionApproval.single("skill", skillName),
+  };
+}

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

@@ -0,0 +1,87 @@
+import { toRecord } from "#src/common";
+import { normalizePathForComparison } from "#src/path-utils";
+import { formatSkillPathAskPrompt } from "#src/permission-prompts";
+import { SessionApproval } from "#src/session-approval";
+import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
+import { findSkillPathMatch } from "#src/skill-prompt-sanitizer";
+import type { GateDescriptor } from "./descriptor";
+import type { ToolCallContext } from "./types";
+
+/**
+ * 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 function describeSkillReadGate(
+  tcc: ToolCallContext,
+  getActiveSkillEntries: () => SkillPromptEntry[],
+): GateDescriptor | null {
+  const activeSkillEntries = getActiveSkillEntries();
+
+  if (tcc.toolName !== "read" || activeSkillEntries.length === 0) {
+    return null;
+  }
+
+  const inputRecord = toRecord(tcc.input);
+  const path = typeof inputRecord.path === "string" ? inputRecord.path : "";
+  if (!path) {
+    return null;
+  }
+
+  if (tcc.cwd === undefined) {
+    return null;
+  }
+
+  const normalizedReadPath = normalizePathForComparison(path, tcc.cwd);
+  const matchedSkill = findSkillPathMatch(
+    normalizedReadPath,
+    activeSkillEntries,
+  );
+
+  if (!matchedSkill) {
+    return null;
+  }
+
+  const skillReadMessage = formatSkillPathAskPrompt(
+    matchedSkill,
+    path,
+    tcc.agentName ?? undefined,
+  );
+
+  return {
+    surface: "skill",
+    input: { name: matchedSkill.name },
+    denialContext: {
+      kind: "skill_read",
+      skillName: matchedSkill.name,
+      readPath: path,
+      agentName: tcc.agentName ?? undefined,
+    },
+    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,
+    },
+    sessionApproval: SessionApproval.single("skill", matchedSkill.name),
+  };
+}

package/src/handlers/gates/tool-call-gate-pipeline.ts

@@ -0,0 +1,129 @@
+import { getNonEmptyString, toRecord } from "#src/common";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
+import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
+import type { ToolInputFormatterLookup } from "#src/tool-input-formatter-registry";
+import {
+  ToolPreviewFormatter,
+  type ToolPreviewFormatterOptions,
+} from "#src/tool-preview-formatter";
+import { resolveBashCommandCheck } from "./bash-command";
+import { describeBashExternalDirectoryGate } from "./bash-external-directory";
+import { describeBashPathGate } from "./bash-path";
+import { BashProgram } from "./bash-program";
+import type { GateResult } from "./descriptor";
+import { describeExternalDirectoryGate } from "./external-directory";
+import { describePathGate } from "./path";
+import type { GateRunner } from "./runner";
+import { describeSkillReadGate } from "./skill-read";
+import { describeToolGate } from "./tool";
+import type { GateOutcome, ToolCallContext } from "./types";
+
+/**
+ * Narrow interface the pipeline needs from its session-side dependency.
+ *
+ * The three query methods needed to assemble gate inputs.
+ * The resolver is injected separately as a constructor parameter.
+ *
+ * `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 ToolCallGateInputs {
+  /** Active skill prompt entries for the skill-read gate. */
+  getActiveSkillEntries(): SkillPromptEntry[];
+  /** Combined infrastructure read directories (static + config-derived). */
+  getInfrastructureReadDirs(): string[];
+  /** Resolved tool-preview formatter options from the current config. */
+  getToolPreviewLimits(): ToolPreviewFormatterOptions;
+}
+
+/**
+ * Owns the ordered tool-call gate-producer assembly and the run loop.
+ *
+ * Constructed once in the composition root and injected into
+ * `PermissionGateHandler`. `evaluate(tcc, runner)` encapsulates:
+ * - bash-command extraction and single `BashProgram.parse` (#308)
+ * - `ToolPreviewFormatter` construction from `getToolPreviewLimits()`
+ * - infrastructure-dir list from `getInfrastructureReadDirs()`
+ * - all six gate producers in their prescribed order
+ * - the run loop that returns the first block outcome, or allow
+ */
+export class ToolCallGatePipeline {
+  constructor(
+    private readonly resolver: ScopedPermissionResolver,
+    private readonly inputs: ToolCallGateInputs,
+    private readonly customFormatters?: ToolInputFormatterLookup,
+    private readonly customExtractors?: ToolAccessExtractorLookup,
+  ) {}
+
+  async evaluate(
+    tcc: ToolCallContext,
+    runner: GateRunner,
+  ): Promise<GateOutcome> {
+    // Parse the bash command exactly once per evaluate; the three bash gates
+    // share this single BashProgram instead of each re-parsing (#308).
+    const command = getNonEmptyString(toRecord(tcc.input).command);
+    const bashProgram =
+      tcc.toolName === "bash" && command
+        ? await BashProgram.parse(command)
+        : null;
+
+    const formatter = new ToolPreviewFormatter(
+      this.inputs.getToolPreviewLimits(),
+      this.customFormatters,
+    );
+
+    const infraDirs = this.inputs.getInfrastructureReadDirs();
+
+    const gateProducers: Array<() => GateResult | Promise<GateResult>> = [
+      () =>
+        describeSkillReadGate(tcc, () => this.inputs.getActiveSkillEntries()),
+      () => describePathGate(tcc, this.resolver, this.customExtractors),
+      () =>
+        describeExternalDirectoryGate(
+          tcc,
+          infraDirs,
+          this.resolver,
+          this.customExtractors,
+        ),
+      () => describeBashExternalDirectoryGate(tcc, bashProgram, this.resolver),
+      () => describeBashPathGate(tcc, bashProgram, this.resolver),
+      () => {
+        // Bash commands may chain several sub-commands (`a && b`, `a | b`, …);
+        // evaluate each unit from the shared parse on the bash surface and
+        // select the most restrictive, rather than matching the whole program
+        // string (#301). Other tools evaluate their single input directly.
+        const toolCheck =
+          tcc.toolName === "bash" && bashProgram
+            ? resolveBashCommandCheck(
+                command ?? "",
+                bashProgram.commands(),
+                tcc.agentName ?? undefined,
+                this.resolver,
+              )
+            : this.resolver.resolve(
+                tcc.toolName,
+                tcc.input,
+                tcc.agentName ?? undefined,
+              );
+        const toolDescriptor = describeToolGate(tcc, toolCheck, formatter);
+        toolDescriptor.preCheck = toolCheck;
+        return toolDescriptor;
+      },
+    ];
+
+    for (const produce of gateProducers) {
+      const outcome = await runner.run(
+        await produce(),
+        tcc.agentName,
+        tcc.toolCallId,
+      );
+      if (outcome.action === "block") {
+        return outcome;
+      }
+    }
+
+    return { action: "allow" };
+  }
+}

package/src/handlers/gates/tool.ts

@@ -0,0 +1,102 @@
+import {
+  getPathBearingToolPath,
+  normalizePathForComparison,
+  PATH_BEARING_TOOLS,
+} from "#src/path-utils";
+import { suggestSessionPattern } from "#src/pattern-suggest";
+import { formatAskPrompt } from "#src/permission-prompts";
+import { SessionApproval } from "#src/session-approval";
+import type { ToolPreviewFormatter } from "#src/tool-preview-formatter";
+import type { PermissionCheckResult } from "#src/types";
+import type { GateDescriptor } from "./descriptor";
+import { deriveDecisionValue } from "./helpers";
+import type { ToolCallContext } from "./types";
+
+/**
+ * Derive the value used for session-approval pattern suggestions.
+ *
+ * Bash → command string; MCP → qualified target;
+ * path-bearing tools → the file path resolved to its canonical (cwd-anchored,
+ * absolute) form so the suggested pattern matches the policy values a later
+ * call produces; others → catch-all wildcard.
+ */
+function deriveSuggestionValue(
+  tcc: ToolCallContext,
+  check: PermissionCheckResult,
+): string {
+  if (tcc.toolName === "bash") return check.command ?? "";
+  if (tcc.toolName === "mcp") return check.target ?? "mcp";
+  const path = getPathBearingToolPath(tcc.toolName, tcc.input);
+  if (path === null) return "*";
+  return tcc.cwd ? normalizePathForComparison(path, tcc.cwd) : path;
+}
+
+/**
+ * Build a pure descriptor for the normal tool permission gate.
+ *
+ * Takes a pre-computed PermissionCheckResult (from checkPermission) and
+ * returns a GateDescriptor that the runner can execute. No side effects.
+ */
+export function describeToolGate(
+  tcc: ToolCallContext,
+  check: PermissionCheckResult,
+  formatter: ToolPreviewFormatter,
+): GateDescriptor {
+  const permissionLogContext = formatter.getPermissionLogContext(
+    check,
+    tcc.input,
+    PATH_BEARING_TOOLS,
+  );
+
+  // Compute session approval suggestion for the "for this session" option.
+  const suggestion = suggestSessionPattern(
+    tcc.toolName,
+    deriveSuggestionValue(tcc, check),
+  );
+
+  const askMessage = formatAskPrompt(
+    check,
+    tcc.agentName ?? undefined,
+    tcc.input,
+    formatter,
+  );
+
+  return {
+    surface: tcc.toolName,
+    input: tcc.input,
+    denialContext: {
+      kind: "tool",
+      check,
+      agentName: tcc.agentName ?? undefined,
+      input: tcc.input,
+    },
+    sessionApproval: SessionApproval.single(
+      suggestion.surface,
+      suggestion.pattern,
+    ),
+    promptDetails: {
+      source: "tool_call",
+      agentName: tcc.agentName,
+      message: askMessage,
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      sessionLabel: suggestion.label,
+      ...permissionLogContext,
+    },
+    logContext: {
+      source: "tool_call",
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      message: askMessage,
+      ...permissionLogContext,
+    },
+    decision: {
+      surface: tcc.toolName,
+      value: deriveDecisionValue(
+        tcc.toolName,
+        check,
+        getPathBearingToolPath(tcc.toolName, tcc.input) ?? undefined,
+      ),
+    },
+  };
+}

package/src/handlers/gates/types.ts

@@ -0,0 +1,13 @@
+/** Outcome of a single permission gate evaluation. */
+export type GateOutcome =
+  | { action: "allow" }
+  | { action: "block"; reason: string };
+
+/** Pre-validated context shared across all gates. */
+export interface ToolCallContext {
+  toolName: string;
+  agentName: string | null;
+  input: unknown;
+  toolCallId: string;
+  cwd: string | undefined;
+}

package/src/handlers/index.ts

@@ -0,0 +1,3 @@
+export { AgentPrepHandler } from "./before-agent-start";
+export { SessionLifecycleHandler } from "./lifecycle";
+export { PermissionGateHandler } from "./permission-gate-handler";