@gotgenes/pi-permission-system 8.0.0 → 8.2.0

package/src/handlers/permission-gate-handler.ts

@@ -16,6 +16,10 @@ import {
   formatUnknownToolReason,
 } from "#src/permission-prompts";
 import type { PermissionSession } from "#src/permission-session";
+import {
+  resolveToolPreviewLimits,
+  ToolPreviewFormatter,
+} from "#src/tool-preview-formatter";
 import {
   checkRequestedToolRegistration,
   getToolNameFromValue,
@@ -23,7 +27,7 @@ import {
 } from "#src/tool-registry";
 import { describeBashExternalDirectoryGate } from "./gates/bash-external-directory";
 import { describeBashPathGate } from "./gates/bash-path";
-import type { GateRunnerDeps } from "./gates/descriptor";
+import type { GateResult, GateRunnerDeps } from "./gates/descriptor";
 import { isGateBypass } from "./gates/descriptor";
 import { describeExternalDirectoryGate } from "./gates/external-directory";
 import { describePathGate } from "./gates/path";
@@ -58,30 +62,13 @@ export class PermissionGateHandler {
   ): Promise<{ block?: true; reason?: string }> {
     this.session.activate(ctx);
 
-    const agentName = this.session.resolveAgentName(ctx);
-    const toolName = getToolNameFromValue(event);
-
-    if (!toolName) {
-      return { block: true, reason: formatMissingToolNameReason() };
-    }
-
-    const registrationCheck = checkRequestedToolRegistration(
-      toolName,
-      this.toolRegistry.getAll(),
-    );
-    if (registrationCheck.status === "missing-tool-name") {
-      return { block: true, reason: formatMissingToolNameReason() };
+    const validation = validateRequestedTool(event, this.toolRegistry.getAll());
+    if (validation.status === "block") {
+      return { block: true, reason: validation.reason };
     }
+    const toolName = validation.toolName;
 
-    if (registrationCheck.status === "unregistered") {
-      return {
-        block: true,
-        reason: formatUnknownToolReason(
-          registrationCheck.requestedToolName,
-          registrationCheck.availableToolNames,
-        ),
-      };
-    }
+    const agentName = this.session.resolveAgentName(ctx);
 
     const input = getEventInput(event);
     const toolCallId =
@@ -112,150 +99,93 @@ export class PermissionGateHandler {
       sessionRules,
     ) => this.session.checkPermission(surface, input, agent, sessionRules);
     const getSessionRuleset = () => this.session.getSessionRuleset();
-    const approveSessionRule = (surface: string, pattern: string) =>
-      this.session.approveSessionRule(surface, pattern);
+    const recordSessionApproval: GateRunnerDeps["recordSessionApproval"] = (
+      approval,
+    ) => this.session.recordSessionApproval(approval);
 
     // ── Shared runner deps (built once, reused for all gates) ────────────
     const runnerDeps: GateRunnerDeps = {
       checkPermission,
       getSessionRuleset,
-      approveSessionRule,
+      recordSessionApproval,
       writeReviewLog,
       emitDecision,
       canConfirm,
       promptPermission,
     };
 
-    // ── Skill-read gate (descriptor + runner) ───────────────────────────────
-    const skillDescriptor = describeSkillReadGate(tcc, () =>
-      this.session.getActiveSkillEntries(),
-    );
-    if (skillDescriptor) {
-      const skillResult = await runGateCheck(
-        skillDescriptor,
+    // ── Unified gate executor ─────────────────────────────────────────────
+    // Handles the bypass log/emit branch, calls runGateCheck for descriptors,
+    // and returns a block result or undefined (allow / no-op).
+    const runGate = async (
+      gate: GateResult,
+    ): Promise<{ block: true; reason: string } | undefined> => {
+      if (!gate) {
+        return undefined;
+      }
+      if (isGateBypass(gate)) {
+        if (gate.log) {
+          writeReviewLog(gate.log.event, gate.log.details);
+        }
+        if (gate.decision) {
+          emitDecision(gate.decision);
+        }
+        return undefined;
+      }
+      const result = await runGateCheck(
+        gate,
         tcc.agentName,
         tcc.toolCallId,
         runnerDeps,
       );
-      if (skillResult.action === "block") {
-        return { block: true, reason: skillResult.reason };
-      }
-    }
+      return result.action === "block"
+        ? { block: true, reason: result.reason }
+        : undefined;
+    };
 
-    // ── Path gate for tools (descriptor + runner) ────────────────────────────
-    const pathDesc = describePathGate(tcc, checkPermission, getSessionRuleset);
-    if (pathDesc) {
-      if (isGateBypass(pathDesc)) {
-        if (pathDesc.log) {
-          writeReviewLog(pathDesc.log.event, pathDesc.log.details);
-        }
-      } else {
-        const pathResult = await runGateCheck(
-          pathDesc,
-          tcc.agentName,
-          tcc.toolCallId,
-          runnerDeps,
-        );
-        if (pathResult.action === "block") {
-          return { block: true, reason: pathResult.reason };
-        }
-      }
-    }
+    const formatter = new ToolPreviewFormatter(
+      resolveToolPreviewLimits(this.session.config),
+    );
 
-    // ── External-directory gate (descriptor + runner) ────────────────────────
+    // ── Ordered gate pipeline ─────────────────────────────────────────────
+    // infraDirs is computed once, outside the pipeline, exactly as before.
     const infraDirs = [
       ...this.session.getInfrastructureDirs(),
       ...this.session.getInfrastructureReadPaths(),
     ];
-    const extDirDesc = describeExternalDirectoryGate(tcc, infraDirs);
-    if (extDirDesc) {
-      if (isGateBypass(extDirDesc)) {
-        if (extDirDesc.log) {
-          writeReviewLog(extDirDesc.log.event, extDirDesc.log.details);
-        }
-        if (extDirDesc.decision) {
-          emitDecision(extDirDesc.decision);
-        }
-      } else {
-        const extDirResult = await runGateCheck(
-          extDirDesc,
-          tcc.agentName,
-          tcc.toolCallId,
-          runnerDeps,
-        );
-        if (extDirResult.action === "block") {
-          return { block: true, reason: extDirResult.reason };
-        }
-      }
-    }
 
-    // ── Bash external-directory gate (descriptor + runner) ───────────────────
-    const bashExtDesc = await describeBashExternalDirectoryGate(
-      tcc,
-      checkPermission,
-      getSessionRuleset,
-    );
-    if (bashExtDesc) {
-      if (isGateBypass(bashExtDesc)) {
-        if (bashExtDesc.log) {
-          writeReviewLog(bashExtDesc.log.event, bashExtDesc.log.details);
-        }
-      } else {
-        const bashExtResult = await runGateCheck(
-          bashExtDesc,
-          tcc.agentName,
-          tcc.toolCallId,
-          runnerDeps,
+    const gateProducers: Array<() => GateResult | Promise<GateResult>> = [
+      () =>
+        describeSkillReadGate(tcc, () => this.session.getActiveSkillEntries()),
+      () => describePathGate(tcc, checkPermission, getSessionRuleset),
+      () => describeExternalDirectoryGate(tcc, infraDirs),
+      () =>
+        describeBashExternalDirectoryGate(
+          tcc,
+          checkPermission,
+          getSessionRuleset,
+        ),
+      () => describeBashPathGate(tcc, checkPermission, getSessionRuleset),
+      () => {
+        const toolCheck = checkPermission(
+          tcc.toolName,
+          tcc.input,
+          tcc.agentName ?? undefined,
+          getSessionRuleset(),
         );
-        if (bashExtResult.action === "block") {
-          return { block: true, reason: bashExtResult.reason };
-        }
-      }
-    }
+        const toolDescriptor = describeToolGate(tcc, toolCheck, formatter);
+        toolDescriptor.preCheck = toolCheck;
+        return toolDescriptor;
+      },
+    ];
 
-    // ── Bash path gate (descriptor + runner) ────────────────────────────────
-    const bashPathDesc = await describeBashPathGate(
-      tcc,
-      checkPermission,
-      getSessionRuleset,
-    );
-    if (bashPathDesc) {
-      if (isGateBypass(bashPathDesc)) {
-        if (bashPathDesc.log) {
-          writeReviewLog(bashPathDesc.log.event, bashPathDesc.log.details);
-        }
-      } else {
-        const bashPathResult = await runGateCheck(
-          bashPathDesc,
-          tcc.agentName,
-          tcc.toolCallId,
-          runnerDeps,
-        );
-        if (bashPathResult.action === "block") {
-          return { block: true, reason: bashPathResult.reason };
-        }
+    for (const produce of gateProducers) {
+      const blocked = await runGate(await produce());
+      if (blocked) {
+        return blocked;
       }
     }
 
-    // ── Normal tool permission gate (descriptor + runner) ────────────────────
-    const toolCheck = checkPermission(
-      tcc.toolName,
-      tcc.input,
-      tcc.agentName ?? undefined,
-      getSessionRuleset(),
-    );
-    const toolDescriptor = describeToolGate(tcc, toolCheck);
-    toolDescriptor.preCheck = toolCheck;
-    const toolResult = await runGateCheck(
-      toolDescriptor,
-      tcc.agentName,
-      tcc.toolCallId,
-      runnerDeps,
-    );
-    if (toolResult.action === "block") {
-      return { block: true, reason: toolResult.reason };
-    }
-
     return {};
   }
 
@@ -352,7 +282,46 @@ export class PermissionGateHandler {
   }
 }
 
-// ── Pure helpers (re-exported from original modules) ──────────────────────
+// ── Pure helpers ─────────────────────────────────────────────────────────
+
+/** Discriminated result of validating a tool-call event's name and registration. */
+export type RequestedToolValidation =
+  | { status: "ok"; toolName: string }
+  | { status: "block"; reason: string };
+
+/**
+ * Validate the tool name from a raw event against the registered tool list.
+ *
+ * Composes `getToolNameFromValue` + `checkRequestedToolRegistration` + the
+ * two reason formatters and returns a discriminated result so `handleToolCall`
+ * reads as a straight validate → proceed path without nested early-returns.
+ *
+ * Returns the **raw** tool name (not the normalised form) so that
+ * `ToolCallContext.toolName` stays identical to the pre-extraction behaviour.
+ */
+export function validateRequestedTool(
+  event: unknown,
+  availableTools: readonly unknown[],
+): RequestedToolValidation {
+  const toolName = getToolNameFromValue(event);
+  if (!toolName) {
+    return { status: "block", reason: formatMissingToolNameReason() };
+  }
+  const check = checkRequestedToolRegistration(toolName, availableTools);
+  if (check.status === "missing-tool-name") {
+    return { status: "block", reason: formatMissingToolNameReason() };
+  }
+  if (check.status === "unregistered") {
+    return {
+      status: "block",
+      reason: formatUnknownToolReason(
+        check.requestedToolName,
+        check.availableToolNames,
+      ),
+    };
+  }
+  return { status: "ok", toolName };
+}
 
 /**
  * Extract the tool input from an event, checking both `input` and `arguments`

package/src/permission-manager.ts

@@ -1,7 +1,6 @@
 import { isPermissionState } from "./common";
 import { normalizeInput } from "./input-normalizer";
 import { normalizeFlatConfig } from "./normalize";
-import { mergeFlatPermissions } from "./permission-merge";
 import {
   FilePolicyLoader,
   type PolicyLoader,
@@ -10,6 +9,7 @@ import {
 } from "./policy-loader";
 import type { Rule, RuleOrigin, Ruleset } from "./rule";
 import { evaluate, evaluateFirst } from "./rule";
+import { mergeScopesWithOrigins } from "./scope-merge";
 import {
   composeRuleset,
   synthesizeBaseline,
@@ -90,58 +90,15 @@ export class PermissionManager {
     const agentConfig = this.loader.loadAgentConfig(agentName);
     const projectAgentConfig = this.loader.loadProjectAgentConfig(agentName);
 
-    // Merge permission objects across scopes (lowest → highest precedence).
-    // Build a parallel origin map that tracks which scope contributed each
-    // (surface, pattern) entry, mirroring mergeFlatPermissions() semantics.
-    type OriginMap = Map<string, Map<string, RuleOrigin>>;
-    const origins: OriginMap = new Map();
-    let mergedPermission: FlatPermissionConfig = {};
-
-    for (const [scopeName, scope] of [
+    // Merge permission objects across scopes (lowest → highest precedence),
+    // building a parallel origin map that tracks which scope contributed each
+    // (surface, pattern) entry.
+    const { mergedPermission, origins } = mergeScopesWithOrigins([
       ["global", globalConfig],
       ["project", projectConfig],
       ["agent", agentConfig],
       ["project-agent", projectAgentConfig],
-    ] as const) {
-      if (!scope.permission) continue;
-
-      for (const [surface, value] of Object.entries(scope.permission)) {
-        const baseVal = mergedPermission[surface];
-        /* eslint-disable @typescript-eslint/no-unnecessary-condition -- defensive null/type checks; config values may differ at runtime */
-        const bothObjects =
-          typeof baseVal === "object" &&
-          baseVal !== null &&
-          typeof value === "object" &&
-          value !== null;
-        /* eslint-enable @typescript-eslint/no-unnecessary-condition */
-
-        if (bothObjects) {
-          // Shallow-merge: each incoming pattern is attributed to this scope;
-          // existing patterns from lower scopes keep their earlier origin.
-          if (!origins.has(surface)) origins.set(surface, new Map());
-          for (const pattern of Object.keys(value)) {
-            origins.get(surface)?.set(pattern, scopeName);
-          }
-        } else {
-          // Full replacement: this scope takes over the entire surface entry.
-          const surfaceOrigins = new Map<string, RuleOrigin>();
-          if (typeof value === "string") {
-            surfaceOrigins.set("*", scopeName);
-            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defensive null check
-          } else if (typeof value === "object" && value !== null) {
-            for (const pattern of Object.keys(value)) {
-              surfaceOrigins.set(pattern, scopeName);
-            }
-          }
-          origins.set(surface, surfaceOrigins);
-        }
-      }
-
-      mergedPermission = mergeFlatPermissions(
-        mergedPermission,
-        scope.permission,
-      );
-    }
+    ]);
 
     // Extract the universal fallback from permission["*"].
     // The "*" key feeds synthesizeDefaults() only — it is NOT included as a

package/src/permission-prompts.ts

@@ -1,5 +1,5 @@
 import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
-import { formatToolInputForPrompt } from "./tool-input-preview";
+import type { ToolPreviewFormatter } from "./tool-preview-formatter";
 import type { PermissionCheckResult } from "./types";
 
 // NOTE: formatDenyReason, formatUserDeniedReason, and
@@ -31,6 +31,7 @@ export function formatAskPrompt(
   result: PermissionCheckResult,
   agentName?: string,
   input?: unknown,
+  formatter?: ToolPreviewFormatter,
 ): string {
   const subject = agentName ? `Agent '${agentName}'` : "Current agent";
 
@@ -51,7 +52,9 @@ export function formatAskPrompt(
   const patternInfo = result.matchedPattern
     ? ` (matched '${result.matchedPattern}')`
     : "";
-  const inputPreview = formatToolInputForPrompt(result.toolName, input);
+  const inputPreview = formatter
+    ? formatter.formatToolInputForPrompt(result.toolName, input)
+    : "";
   const inputSuffix = inputPreview ? ` ${inputPreview}` : "";
   return `${subject} requested tool '${result.toolName}'${patternInfo}${inputSuffix}. Allow this call?`;
 }

package/src/permission-session.ts

@@ -12,6 +12,7 @@ import type { PermissionManager } from "./permission-manager";
 import type { PromptPermissionDetails } from "./permission-prompter";
 import type { Rule } from "./rule";
 import { createPermissionManagerForCwd } from "./runtime";
+import type { SessionApproval } from "./session-approval";
 import type { SessionLogger } from "./session-logger";
 import { SessionRules } from "./session-rules";
 import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
@@ -127,8 +128,8 @@ export class PermissionSession {
     return this.sessionRules.getRuleset();
   }
 
-  approveSessionRule(surface: string, pattern: string): void {
-    this.sessionRules.approve(surface, pattern);
+  recordSessionApproval(approval: SessionApproval): void {
+    this.sessionRules.record(approval);
   }
 
   // ── Session lifecycle ────────────────────────────────────────────────────

package/src/scope-merge.ts

@@ -0,0 +1,72 @@
+import { mergeFlatPermissions } from "#src/permission-merge";
+import type { RuleOrigin } from "#src/rule";
+import type { FlatPermissionConfig, ScopeConfig } from "#src/types";
+
+/** Surface → (pattern → originating scope). */
+type OriginMap = Map<string, Map<string, RuleOrigin>>;
+
+/** Result of merging permission objects across scopes with provenance tracking. */
+export interface MergedScopes {
+  /** Fully merged flat permission config (lowest → highest precedence). */
+  mergedPermission: FlatPermissionConfig;
+  /** Maps each surface to a per-pattern origin (which scope contributed it). */
+  origins: OriginMap;
+}
+
+/**
+ * Merge permission objects across scopes (lowest → highest precedence) while
+ * tracking which scope contributed each (surface, pattern) entry.
+ *
+ * Mirrors mergeFlatPermissions() semantics for origin attribution:
+ * - Both base and incoming are objects → shallow-merge: each incoming pattern
+ *   is attributed to this scope; patterns the higher scope does not redefine
+ *   keep their earlier origin.
+ * - Otherwise → full replacement: this scope takes over the entire surface
+ *   entry, discarding all lower-scope attribution.
+ */
+export function mergeScopesWithOrigins(
+  scopes: readonly (readonly [RuleOrigin, ScopeConfig])[],
+): MergedScopes {
+  const origins: OriginMap = new Map();
+  let mergedPermission: FlatPermissionConfig = {};
+
+  for (const [scopeName, scope] of scopes) {
+    if (!scope.permission) continue;
+
+    for (const [surface, value] of Object.entries(scope.permission)) {
+      const baseVal = mergedPermission[surface];
+      /* eslint-disable @typescript-eslint/no-unnecessary-condition -- defensive null/type checks; config values may differ at runtime */
+      const bothObjects =
+        typeof baseVal === "object" &&
+        baseVal !== null &&
+        typeof value === "object" &&
+        value !== null;
+      /* eslint-enable @typescript-eslint/no-unnecessary-condition */
+
+      if (bothObjects) {
+        // Shallow-merge: each incoming pattern is attributed to this scope;
+        // existing patterns from lower scopes keep their earlier origin.
+        if (!origins.has(surface)) origins.set(surface, new Map());
+        for (const pattern of Object.keys(value)) {
+          origins.get(surface)?.set(pattern, scopeName);
+        }
+      } else {
+        // Full replacement: this scope takes over the entire surface entry.
+        const surfaceOrigins = new Map<string, RuleOrigin>();
+        if (typeof value === "string") {
+          surfaceOrigins.set("*", scopeName);
+          // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defensive null check
+        } else if (typeof value === "object" && value !== null) {
+          for (const pattern of Object.keys(value)) {
+            surfaceOrigins.set(pattern, scopeName);
+          }
+        }
+        origins.set(surface, surfaceOrigins);
+      }
+    }
+
+    mergedPermission = mergeFlatPermissions(mergedPermission, scope.permission);
+  }
+
+  return { mergedPermission, origins };
+}

package/src/session-approval.ts

@@ -0,0 +1,43 @@
+/**
+ * Value object for a session-scoped approval: one surface, one-or-more patterns.
+ *
+ * Owned by gate descriptors and passed to the session store — the runner never
+ * needs to know whether there is one pattern or many.
+ */
+export class SessionApproval {
+  private constructor(
+    readonly surface: string,
+    readonly patterns: readonly string[],
+  ) {}
+
+  /** Create an approval for a single pattern (the common case). */
+  static single(surface: string, pattern: string): SessionApproval {
+    return new SessionApproval(surface, [pattern]);
+  }
+
+  /**
+   * Create an approval for multiple patterns (e.g. bash external-directory
+   * gates that cover several uncovered paths in one prompt).
+   */
+  static multiple(
+    surface: string,
+    patterns: readonly string[],
+  ): SessionApproval {
+    return new SessionApproval(surface, [...patterns]);
+  }
+
+  /** Representative pattern for the interactive prompt — the first, if any. */
+  get representativePattern(): string | undefined {
+    return this.patterns[0];
+  }
+
+  /**
+   * Single-pattern shape `applyPermissionGate` echoes back to the caller.
+   * Returns `undefined` when patterns is empty (degenerate case).
+   */
+  toGateApproval(): { surface: string; pattern: string } | undefined {
+    const pattern = this.representativePattern;
+    if (pattern === undefined) return undefined;
+    return { surface: this.surface, pattern };
+  }
+}

package/src/session-rules.ts

@@ -1,6 +1,7 @@
 import { dirname, sep } from "node:path";
 
 import type { Ruleset } from "./rule";
+import type { SessionApproval } from "./session-approval";
 
 /**
  * Ephemeral in-memory store of session-scoped permission approvals.
@@ -29,6 +30,18 @@ export class SessionRules {
     return [...this.rules];
   }
 
+  /**
+   * Record all patterns from a `SessionApproval` value object.
+   *
+   * The loop lives here so callers never need to know whether an approval
+   * carries one pattern or many — they just tell the store to record it.
+   */
+  record(approval: SessionApproval): void {
+    for (const pattern of approval.patterns) {
+      this.approve(approval.surface, pattern);
+    }
+  }
+
   /** Remove all session approvals. */
   clear(): void {
     this.rules = [];