@gotgenes/pi-permission-system 4.4.0 → 4.5.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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)
+
+
+### Documentation
+
+* plan delete deprecated defaults.ts stub ([#82](https://github.com/gotgenes/pi-permission-system/issues/82)) ([36fcace](https://github.com/gotgenes/pi-permission-system/commit/36fcaceab824b4334315767ba1cfd3fe24cff1b7))
+* **retro:** add retro notes for issue [#80](https://github.com/gotgenes/pi-permission-system/issues/80) ([bfa11d5](https://github.com/gotgenes/pi-permission-system/commit/bfa11d539920dc24efbcab33329595da4e93e152))
+
+
+### Miscellaneous Chores
+
+* delete deprecated defaults.ts stub ([#82](https://github.com/gotgenes/pi-permission-system/issues/82)) ([40ae42a](https://github.com/gotgenes/pi-permission-system/commit/40ae42ad710bc502f19d8a27e409cc22a6bca4f8))
+
 ## [4.4.0](https://github.com/gotgenes/pi-permission-system/compare/v4.3.0...v4.4.0) (2026-05-05)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "4.4.0",
+  "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;
+}