@gotgenes/pi-permission-system 4.4.1 → 4.5.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.5.0](https://github.com/gotgenes/pi-permission-system/compare/v4.4.1...v4.5.0) (2026-05-05)
+
+
+### Features
+
+* add evaluateFirst multi-candidate evaluate helper ([6b1fa60](https://github.com/gotgenes/pi-permission-system/commit/6b1fa603e6eaf750624d1f553ddb84755ab9b78e))
+* add input normalizer for non-MCP surfaces ([6d25624](https://github.com/gotgenes/pi-permission-system/commit/6d256241e3f599aa9db5952a16b10d10b72e5321))
+* add MCP input normalization to input-normalizer ([6fa58b2](https://github.com/gotgenes/pi-permission-system/commit/6fa58b211f06eef5885f1e6f238285cdb77aab09))
+* concatenate session rules into composed ruleset ([e85e844](https://github.com/gotgenes/pi-permission-system/commit/e85e844f414c6dfd14ffbbc74826c976d8f0f234))
+
+
+### Documentation
+
+* mark unified checkPermission as implemented in target architecture ([bb7214a](https://github.com/gotgenes/pi-permission-system/commit/bb7214a8363b6b1ad70ae1233f297d28c36cd423))
+* plan unified checkPermission evaluate path ([#81](https://github.com/gotgenes/pi-permission-system/issues/81)) ([6562328](https://github.com/gotgenes/pi-permission-system/commit/65623287aa899424829b0e31e7c9aa46f17e3f81))
+* **retro:** add retro notes for issue [#82](https://github.com/gotgenes/pi-permission-system/issues/82) ([f748fe0](https://github.com/gotgenes/pi-permission-system/commit/f748fe00105dbce087ec0a41653171c53364d531))
+
 ## [4.4.1](https://github.com/gotgenes/pi-permission-system/compare/v4.4.0...v4.4.1) (2026-05-05)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "4.4.1",
+  "version": "4.5.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "files": [

package/src/input-normalizer.ts

@@ -0,0 +1,94 @@
+import { toRecord } from "./common";
+import { createMcpPermissionTargets } from "./mcp-targets";
+
+/**
+ * Surface-normalized representation of a tool invocation used by
+ * `checkPermission()` to feed a single `evaluateFirst()` call.
+ */
+export interface NormalizedInput {
+  /** The permission surface for `evaluate()` (e.g. "bash", "mcp", "skill"). */
+  surface: string;
+  /**
+   * Candidate lookup values in priority order (most-specific first).
+   * Most surfaces produce a single-element array; MCP produces a
+   * multi-candidate list derived from the invocation input.
+   */
+  values: string[];
+  /**
+   * Surface-specific fields forwarded verbatim into `PermissionCheckResult`
+   * (e.g. `{ command }` for bash, `{ target }` for mcp).
+   */
+  resultExtras: Record<string, unknown>;
+}
+
+const SPECIAL_PERMISSION_KEYS = new Set(["external_directory"]);
+
+/**
+ * Map a raw tool invocation to the surface/values/extras triple needed by
+ * `checkPermission()`.
+ *
+ * @param toolName - Normalized (trimmed) tool name from the tool-call event.
+ * @param input    - Raw input payload from the tool-call event.
+ * @param configuredMcpServerNames - Ordered list of MCP server names from the
+ *   global MCP config, used to derive server-qualified MCP targets.
+ */
+export function normalizeInput(
+  toolName: string,
+  input: unknown,
+  configuredMcpServerNames: readonly string[],
+): NormalizedInput {
+  // --- Special surfaces (external_directory) ---
+  if (SPECIAL_PERMISSION_KEYS.has(toolName)) {
+    const record = toRecord(input);
+    const pathValue = typeof record.path === "string" ? record.path : null;
+    return {
+      surface: toolName,
+      values: [pathValue ?? "*"],
+      resultExtras: {},
+    };
+  }
+
+  // --- Skill ---
+  if (toolName === "skill") {
+    const record = toRecord(input);
+    const skillName = record.name;
+    const lookupValue = typeof skillName === "string" ? skillName : "*";
+    return {
+      surface: "skill",
+      values: [lookupValue],
+      resultExtras: {},
+    };
+  }
+
+  // --- Bash ---
+  if (toolName === "bash") {
+    const record = toRecord(input);
+    const command = typeof record.command === "string" ? record.command : "";
+    return {
+      surface: "bash",
+      values: [command],
+      resultExtras: { command },
+    };
+  }
+
+  // --- MCP ---
+  if (toolName === "mcp") {
+    const mcpTargets = [
+      ...createMcpPermissionTargets(input, configuredMcpServerNames),
+      "mcp",
+    ];
+    const fallbackTarget = mcpTargets[0] ?? "mcp";
+    return {
+      surface: "mcp",
+      values: mcpTargets,
+      resultExtras: { target: fallbackTarget },
+    };
+  }
+
+  // --- Tool surfaces (read, write, edit, grep, find, ls, extension tools) ---
+  return {
+    surface: toolName,
+    values: ["*"],
+    resultExtras: {},
+  };
+}

package/src/mcp-targets.ts

@@ -0,0 +1,160 @@
+import { getNonEmptyString, toRecord } from "./common";
+
+/**
+ * Parse a qualified MCP tool name of the form `server:tool`.
+ *
+ * Returns `{ server, tool }` when the string contains exactly one colon with
+ * non-empty text on both sides; otherwise returns `null`.
+ */
+export function parseQualifiedMcpToolName(
+  value: string,
+): { server: string; tool: string } | null {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  const colonIndex = trimmed.indexOf(":");
+  if (colonIndex <= 0 || colonIndex >= trimmed.length - 1) {
+    return null;
+  }
+
+  const server = trimmed.slice(0, colonIndex).trim();
+  const tool = trimmed.slice(colonIndex + 1).trim();
+  if (!server || !tool) {
+    return null;
+  }
+
+  return { server, tool };
+}
+
+function addDerivedMcpServerTargets(
+  toolName: string,
+  configuredServerNames: readonly string[],
+  pushTarget: (value: string | null) => void,
+): void {
+  const trimmedToolName = toolName.trim();
+  if (!trimmedToolName) {
+    return;
+  }
+
+  for (const serverName of configuredServerNames) {
+    const trimmedServerName = serverName.trim();
+    if (!trimmedServerName) {
+      continue;
+    }
+
+    if (!trimmedToolName.endsWith(`_${trimmedServerName}`)) {
+      continue;
+    }
+
+    if (trimmedToolName.startsWith(`${trimmedServerName}_`)) {
+      continue;
+    }
+
+    pushTarget(`${trimmedServerName}_${trimmedToolName}`);
+    pushTarget(`${trimmedServerName}:${trimmedToolName}`);
+    pushTarget(trimmedServerName);
+  }
+}
+
+function pushMcpToolPermissionTargets(
+  rawReference: string,
+  serverHint: string | null,
+  configuredServerNames: readonly string[],
+  pushTarget: (value: string | null) => void,
+): void {
+  const qualified = parseQualifiedMcpToolName(rawReference);
+  const resolvedServer = serverHint ?? qualified?.server ?? null;
+  const resolvedTool = qualified?.tool ?? rawReference;
+
+  if (resolvedServer) {
+    pushTarget(`${resolvedServer}_${resolvedTool}`);
+    pushTarget(`${resolvedServer}:${resolvedTool}`);
+    pushTarget(resolvedServer);
+  } else {
+    addDerivedMcpServerTargets(resolvedTool, configuredServerNames, pushTarget);
+  }
+
+  pushTarget(resolvedTool);
+  pushTarget(rawReference);
+}
+
+/**
+ * Derive the ordered list of MCP permission-lookup candidates from a raw MCP
+ * tool invocation input.
+ *
+ * Candidates are ordered from most-specific to least-specific so that
+ * `evaluateFirst()` stops at the first non-default match.
+ */
+export function createMcpPermissionTargets(
+  input: unknown,
+  configuredServerNames: readonly string[] = [],
+): string[] {
+  const record = toRecord(input);
+  const tool = getNonEmptyString(record.tool);
+  const server = getNonEmptyString(record.server);
+  const connect = getNonEmptyString(record.connect);
+  const describe = getNonEmptyString(record.describe);
+  const search = getNonEmptyString(record.search);
+
+  const targets: string[] = [];
+  const pushTarget = (value: string | null) => {
+    if (!value) {
+      return;
+    }
+    if (!targets.includes(value)) {
+      targets.push(value);
+    }
+  };
+
+  if (tool) {
+    pushMcpToolPermissionTargets(
+      tool,
+      server,
+      configuredServerNames,
+      pushTarget,
+    );
+    pushTarget("mcp_call");
+    return targets;
+  }
+
+  if (connect) {
+    pushTarget(`mcp_connect_${connect}`);
+    pushTarget(connect);
+    pushTarget("mcp_connect");
+    return targets;
+  }
+
+  if (describe) {
+    pushMcpToolPermissionTargets(
+      describe,
+      server,
+      configuredServerNames,
+      pushTarget,
+    );
+    pushTarget("mcp_describe");
+    return targets;
+  }
+
+  if (search) {
+    if (server) {
+      pushTarget(`mcp_server_${server}`);
+      pushTarget(server);
+    }
+
+    pushTarget(search);
+    pushTarget("mcp_search");
+    return targets;
+  }
+
+  if (server) {
+    pushTarget(`mcp_server_${server}`);
+    pushTarget(server);
+    pushTarget("mcp_list");
+    return targets;
+  }
+
+  pushTarget("mcp_status");
+  return targets;
+}

package/src/permission-manager.ts

@@ -4,7 +4,6 @@ import { getAgentDir } from "@mariozechner/pi-coding-agent";
 
 import {
   extractFrontmatter,
-  getNonEmptyString,
   isPermissionState,
   parseSimpleYamlMap,
   toRecord,
@@ -15,9 +14,10 @@ import {
   stripJsonComments,
 } from "./config-loader";
 import { getGlobalConfigPath } from "./config-paths";
+import { normalizeInput } from "./input-normalizer";
 import { normalizeFlatConfig } from "./normalize";
 import type { Rule, Ruleset } from "./rule";
-import { evaluate } from "./rule";
+import { evaluate, evaluateFirst } from "./rule";
 import {
   composeRuleset,
   synthesizeBaseline,
@@ -453,330 +453,73 @@ export class PermissionManager {
     const { composedRules } = this.resolvePermissions(agentName);
     const normalizedToolName = toolName.trim();
 
-    // --- Special surfaces (external_directory) ---
-    if (SPECIAL_PERMISSION_KEYS.has(normalizedToolName)) {
-      const record = toRecord(input);
-      const pathValue = typeof record.path === "string" ? record.path : null;
-
-      // Session check: match by specific normalized path.
-      if (pathValue && sessionRules && sessionRules.length > 0) {
-        const sessionRule = evaluate(
-          "external_directory",
-          pathValue,
-          sessionRules,
-        );
-        if (sessionRules.includes(sessionRule)) {
-          return {
-            toolName,
-            state: "allow",
-            matchedPattern: sessionRule.pattern,
-            source: "session",
-          };
-        }
-      }
-
-      // Config/default check.
-      const rule = evaluate(
-        normalizedToolName,
-        pathValue ?? "*",
-        composedRules,
-      );
-      return {
-        toolName,
-        state: rule.action,
-        matchedPattern: rule.layer === "config" ? rule.pattern : undefined,
-        source: "special",
-      };
-    }
-
-    // --- Skills ---
-    if (normalizedToolName === "skill") {
-      const skillName = toRecord(input).name;
-      const lookupValue = typeof skillName === "string" ? skillName : "*";
-
-      // Session check.
-      if (sessionRules && sessionRules.length > 0) {
-        const sessionRule = evaluate("skill", lookupValue, sessionRules);
-        if (sessionRules.includes(sessionRule)) {
-          return {
-            toolName,
-            state: "allow",
-            matchedPattern: sessionRule.pattern,
-            source: "session",
-          };
-        }
-      }
-
-      const rule = evaluate("skill", lookupValue, composedRules);
-      return {
-        toolName,
-        state: rule.action,
-        matchedPattern: rule.layer === "config" ? rule.pattern : undefined,
-        source: "skill",
-      };
-    }
-
-    // --- Bash ---
-    if (normalizedToolName === "bash") {
-      const record = toRecord(input);
-      const command = typeof record.command === "string" ? record.command : "";
-
-      // Session check.
-      if (sessionRules && sessionRules.length > 0) {
-        const sessionRule = evaluate("bash", command, sessionRules);
-        if (sessionRules.includes(sessionRule)) {
-          return {
-            toolName,
-            state: "allow",
-            command,
-            matchedPattern: sessionRule.pattern,
-            source: "session",
-          };
-        }
-      }
-
-      const rule = evaluate("bash", command, composedRules);
-      return {
-        toolName,
-        state: rule.action,
-        command,
-        matchedPattern: rule.layer === "config" ? rule.pattern : undefined,
-        source: "bash",
-      };
-    }
+    // Append session rules at the end (highest priority) so evaluate() handles
+    // them via last-match-wins — no separate per-branch pre-check needed.
+    const fullRules: Ruleset = sessionRules?.length
+      ? [...composedRules, ...sessionRules]
+      : composedRules;
 
-    // --- MCP ---
-    if (normalizedToolName === "mcp") {
-      const mcpTargets = [
-        ...createMcpPermissionTargets(
-          input,
-          this.getConfiguredMcpServerNames(),
-        ),
-        "mcp",
-      ];
-      const fallbackTarget = mcpTargets[0] || "mcp";
-
-      // Session check: try each candidate target against session rules.
-      if (sessionRules && sessionRules.length > 0) {
-        for (const target of mcpTargets) {
-          const sessionRule = evaluate("mcp", target, sessionRules);
-          if (sessionRules.includes(sessionRule)) {
-            return {
-              toolName,
-              state: "allow",
-              matchedPattern: sessionRule.pattern,
-              target,
-              source: "session",
-            };
-          }
-        }
-      }
-
-      // Try each candidate target. Stop on the first non-default match.
-      for (const target of mcpTargets) {
-        const rule = evaluate("mcp", target, composedRules);
-        if (rule.layer !== "default") {
-          return {
-            toolName,
-            state: rule.action,
-            matchedPattern: rule.layer === "config" ? rule.pattern : undefined,
-            target,
-            source: rule.layer === "override" ? "tool" : "mcp",
-          };
-        }
-      }
-
-      // All targets matched only the synthesized default.
-      const defaultRule = evaluate("mcp", fallbackTarget, composedRules);
-      return {
-        toolName,
-        state: defaultRule.action,
-        target: fallbackTarget,
-        source: "default",
-      };
-    }
-
-    // --- Tools (read, write, edit, grep, find, ls, extension tools) ---
-
-    // Session check.
-    if (sessionRules && sessionRules.length > 0) {
-      const sessionRule = evaluate(normalizedToolName, "*", sessionRules);
-      if (sessionRules.includes(sessionRule)) {
-        return {
-          toolName,
-          state: "allow",
-          matchedPattern: sessionRule.pattern,
-          source: "session",
-        };
-      }
-    }
+    const { surface, values, resultExtras } = normalizeInput(
+      normalizedToolName,
+      input,
+      this.getConfiguredMcpServerNames(),
+    );
 
-    const rule = evaluate(normalizedToolName, "*", composedRules);
+    const { rule, value } = evaluateFirst(surface, values, fullRules);
 
-    if (BUILT_IN_TOOL_PERMISSION_NAMES.has(normalizedToolName)) {
-      return {
-        toolName,
-        state: rule.action,
-        source: "tool",
-      };
-    }
+    // For MCP, replace the normalizer's fallback target with the actual
+    // matched candidate value so PermissionCheckResult.target is accurate.
+    const extras =
+      surface === "mcp" ? { ...resultExtras, target: value } : resultExtras;
 
     return {
       toolName,
       state: rule.action,
-      source: rule.layer === "default" ? "default" : "tool",
+      matchedPattern:
+        rule.layer === "config" || rule.layer === "session"
+          ? rule.pattern
+          : undefined,
+      source: deriveSource(rule, normalizedToolName),
+      ...extras,
     };
   }
 }
 
-// ---------------------------------------------------------------------------
-// MCP target derivation helpers (unchanged)
-// ---------------------------------------------------------------------------
-
-function parseQualifiedMcpToolName(
-  value: string,
-): { server: string; tool: string } | null {
-  const trimmed = value.trim();
-  if (!trimmed) {
-    return null;
-  }
-
-  const colonIndex = trimmed.indexOf(":");
-  if (colonIndex <= 0 || colonIndex >= trimmed.length - 1) {
-    return null;
-  }
-
-  const server = trimmed.slice(0, colonIndex).trim();
-  const tool = trimmed.slice(colonIndex + 1).trim();
-  if (!server || !tool) {
-    return null;
-  }
-
-  return { server, tool };
-}
-
-function addDerivedMcpServerTargets(
+/**
+ * Map a matched rule + tool name to the correct PermissionCheckResult.source.
+ *
+ * Mirrors the source-derivation logic from the former per-branch
+ * checkPermission() implementation:
+ *
+ * - session          → "session" (always, all surfaces)
+ * - mcp + default    → "default"
+ * - mcp + override   → "tool"
+ * - mcp + other      → "mcp"
+ * - special          → "special" (always)
+ * - skill            → "skill" (always)
+ * - bash             → "bash" (always)
+ * - built-in tool    → "tool" (always)
+ * - extension tool   → "default" when default layer, "tool" otherwise
+ */
+function deriveSource(
+  rule: Rule,
   toolName: string,
-  configuredServerNames: readonly string[],
-  pushTarget: (value: string | null) => void,
-): void {
-  const trimmedToolName = toolName.trim();
-  if (!trimmedToolName) {
-    return;
-  }
-
-  for (const serverName of configuredServerNames) {
-    const trimmedServerName = serverName.trim();
-    if (!trimmedServerName) {
-      continue;
-    }
-
-    if (!trimmedToolName.endsWith(`_${trimmedServerName}`)) {
-      continue;
-    }
-
-    if (trimmedToolName.startsWith(`${trimmedServerName}_`)) {
-      continue;
-    }
+): PermissionCheckResult["source"] {
+  if (rule.layer === "session") return "session";
 
-    pushTarget(`${trimmedServerName}_${trimmedToolName}`);
-    pushTarget(`${trimmedServerName}:${trimmedToolName}`);
-    pushTarget(trimmedServerName);
-  }
-}
-
-function pushMcpToolPermissionTargets(
-  rawReference: string,
-  serverHint: string | null,
-  configuredServerNames: readonly string[],
-  pushTarget: (value: string | null) => void,
-): void {
-  const qualified = parseQualifiedMcpToolName(rawReference);
-  const resolvedServer = serverHint ?? qualified?.server ?? null;
-  const resolvedTool = qualified?.tool ?? rawReference;
-
-  if (resolvedServer) {
-    pushTarget(`${resolvedServer}_${resolvedTool}`);
-    pushTarget(`${resolvedServer}:${resolvedTool}`);
-    pushTarget(resolvedServer);
-  } else {
-    addDerivedMcpServerTargets(resolvedTool, configuredServerNames, pushTarget);
+  if (toolName === "mcp") {
+    if (rule.layer === "default") return "default";
+    if (rule.layer === "override") return "tool";
+    return "mcp";
   }
 
-  pushTarget(resolvedTool);
-  pushTarget(rawReference);
-}
-
-function createMcpPermissionTargets(
-  input: unknown,
-  configuredServerNames: readonly string[] = [],
-): string[] {
-  const record = toRecord(input);
-  const tool = getNonEmptyString(record.tool);
-  const server = getNonEmptyString(record.server);
-  const connect = getNonEmptyString(record.connect);
-  const describe = getNonEmptyString(record.describe);
-  const search = getNonEmptyString(record.search);
-
-  const targets: string[] = [];
-  const pushTarget = (value: string | null) => {
-    if (!value) {
-      return;
-    }
-    if (!targets.includes(value)) {
-      targets.push(value);
-    }
-  };
-
-  if (tool) {
-    pushMcpToolPermissionTargets(
-      tool,
-      server,
-      configuredServerNames,
-      pushTarget,
-    );
-    pushTarget("mcp_call");
-    return targets;
-  }
-
-  if (connect) {
-    pushTarget(`mcp_connect_${connect}`);
-    pushTarget(connect);
-    pushTarget("mcp_connect");
-    return targets;
-  }
-
-  if (describe) {
-    pushMcpToolPermissionTargets(
-      describe,
-      server,
-      configuredServerNames,
-      pushTarget,
-    );
-    pushTarget("mcp_describe");
-    return targets;
-  }
-
-  if (search) {
-    if (server) {
-      pushTarget(`mcp_server_${server}`);
-      pushTarget(server);
-    }
-
-    pushTarget(search);
-    pushTarget("mcp_search");
-    return targets;
-  }
-
-  if (server) {
-    pushTarget(`mcp_server_${server}`);
-    pushTarget(server);
-    pushTarget("mcp_list");
-    return targets;
-  }
+  if (SPECIAL_PERMISSION_KEYS.has(toolName)) return "special";
+  if (toolName === "skill") return "skill";
+  if (toolName === "bash") return "bash";
 
-  pushTarget("mcp_status");
-  return targets;
+  // Built-in tools always report "tool"; extension tools distinguish default.
+  if (BUILT_IN_TOOL_PERMISSION_NAMES.has(toolName)) return "tool";
+  return rule.layer === "default" ? "default" : "tool";
 }
 
 // Keep isPermissionState and toRecord available for convenience — they are