@gotgenes/pi-permission-system 4.9.0 → 5.0.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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).
 
+## [5.0.0](https://github.com/gotgenes/pi-permission-system/compare/v4.9.0...v5.0.0) (2026-05-05)
+
+
+### ⚠ BREAKING CHANGES
+
+* Rule.origin and PermissionCheckResult.origin are now required fields. Code that constructs Rule or PermissionCheckResult literals must include an origin value.
+
+### Features
+
+* add RuleOrigin type and origin field to Rule ([b4452d1](https://github.com/gotgenes/pi-permission-system/commit/b4452d1cc9e87a8315edcd6f5f2b1425310bd0b6))
+* display rule origins in /permission-system show output ([af34c8e](https://github.com/gotgenes/pi-permission-system/commit/af34c8e808c7fa67bbe68635f776ec0fd8717bfa))
+* include rule origin in permission review log entries ([b19fdf6](https://github.com/gotgenes/pi-permission-system/commit/b19fdf69b48248430410643ee20bee58535b99d9))
+* make Rule.origin and PermissionCheckResult.origin required ([937a9f5](https://github.com/gotgenes/pi-permission-system/commit/937a9f5c4a9442611606fa3b27962555ed8c25a9))
+* propagate origin to synthesized default rule ([04f9130](https://github.com/gotgenes/pi-permission-system/commit/04f91304ec5ba975ac512989c90757528a30ef7b))
+* track and propagate rule origin through checkPermission ([327bc60](https://github.com/gotgenes/pi-permission-system/commit/327bc60e7f79aafd19995337f62244fd8b0c191f))
+
+
+### Documentation
+
+* plan rule origin provenance tracking ([#88](https://github.com/gotgenes/pi-permission-system/issues/88)) ([d8f8840](https://github.com/gotgenes/pi-permission-system/commit/d8f884028f03682a896dd0d6e8e5a335d8e669f5))
+* **retro:** add retro notes for issue [#48](https://github.com/gotgenes/pi-permission-system/issues/48) ([2187a53](https://github.com/gotgenes/pi-permission-system/commit/2187a53d2af30d6a68f664b1ce4af0dc30b39061))
+* update target architecture for required Rule.origin ([edf0620](https://github.com/gotgenes/pi-permission-system/commit/edf06209ce148b70131a5abf361070571db51e7b))
+* update target architecture for rule origin provenance ([c82435b](https://github.com/gotgenes/pi-permission-system/commit/c82435bb75dd7b22331986c6a23bfe5cf1849ca7))
+
 ## [4.9.0](https://github.com/gotgenes/pi-permission-system/compare/v4.8.0...v4.9.0) (2026-05-05)
 
 

package/package.json

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

package/src/config-modal.ts

@@ -9,6 +9,7 @@ import {
   DEFAULT_EXTENSION_CONFIG,
   type PermissionSystemExtensionConfig,
 } from "./extension-config";
+import type { Ruleset } from "./rule";
 
 interface PermissionSystemConfigController {
   getConfig(): PermissionSystemExtensionConfig;
@@ -17,6 +18,8 @@ interface PermissionSystemConfigController {
     ctx: ExtensionCommandContext,
   ): void;
   getConfigPath(): string;
+  /** Optional: returns the composed config-layer ruleset for origin display. */
+  getComposedRules?(): Ruleset;
 }
 
 const ON_OFF = ["on", "off"];
@@ -57,12 +60,30 @@ function toOnOff(value: boolean): string {
   return value ? "on" : "off";
 }
 
-function summarizeConfig(config: PermissionSystemExtensionConfig): string {
-  return [
+function formatRulesSummary(rules: Ruleset): string {
+  const configRules = rules.filter((r) => r.layer === "config" && r.origin);
+  if (configRules.length === 0) return "";
+  const formatted = configRules
+    .map((r) => {
+      const key =
+        r.pattern === "*" ? r.surface : `${r.surface}["${r.pattern}"]`;
+      return `${key}=${r.action} (${r.origin})`;
+    })
+    .join(", ");
+  return `\n  rules: ${formatted}`;
+}
+
+function summarizeConfig(
+  config: PermissionSystemExtensionConfig,
+  rules?: Ruleset,
+): string {
+  const knobs = [
     `yoloMode=${toOnOff(config.yoloMode)}`,
     `permissionReviewLog=${toOnOff(config.permissionReviewLog)}`,
     `debugLog=${toOnOff(config.debugLog)}`,
   ].join(", ");
+  const rulesSuffix = rules ? formatRulesSummary(rules) : "";
+  return `${knobs}${rulesSuffix}`;
 }
 
 function buildSettingItems(
@@ -183,8 +204,9 @@ function handleArgs(
   }
 
   if (normalized === "show") {
+    const rules = controller.getComposedRules?.();
     ctx.ui.notify(
-      `permission-system: ${summarizeConfig(controller.getConfig())}`,
+      `permission-system: ${summarizeConfig(controller.getConfig(), rules)}`,
       "info",
     );
     return true;

package/src/index.ts

@@ -58,6 +58,10 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     getConfig: () => runtime.config,
     setConfig: (next, ctx) => saveExtensionConfig(runtime, next, ctx),
     getConfigPath: () => getGlobalConfigPath(runtime.agentDir),
+    getComposedRules: () =>
+      runtime.permissionManager.getComposedConfigRules(
+        runtime.lastKnownActiveAgentName ?? undefined,
+      ),
   });
 
   const createPermissionRequestId = (prefix: string): string =>

package/src/normalize.ts

@@ -18,12 +18,12 @@ export function normalizeFlatConfig(permission: FlatPermissionConfig): Ruleset {
   for (const [surface, value] of Object.entries(permission)) {
     if (typeof value === "string") {
       if (isPermissionState(value)) {
-        rules.push({ surface, pattern: "*", action: value });
+        rules.push({ surface, pattern: "*", action: value, origin: "builtin" });
       }
     } else if (typeof value === "object" && value !== null) {
       for (const [pattern, action] of Object.entries(value)) {
         if (isPermissionState(action)) {
-          rules.push({ surface, pattern, action });
+          rules.push({ surface, pattern, action, origin: "builtin" });
         }
       }
     }

package/src/permission-manager.ts

@@ -16,7 +16,7 @@ import {
 import { getGlobalConfigPath } from "./config-paths";
 import { normalizeInput } from "./input-normalizer";
 import { normalizeFlatConfig } from "./normalize";
-import type { Rule, Ruleset } from "./rule";
+import type { Rule, RuleOrigin, Ruleset } from "./rule";
 import { evaluate, evaluateFirst } from "./rule";
 import {
   composeRuleset,
@@ -354,19 +354,55 @@ export class PermissionManager {
     const projectAgentConfig = this.loadProjectScopeConfig(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 scope of [
-      globalConfig,
-      projectConfig,
-      agentConfig,
-      projectAgentConfig,
-    ]) {
-      if (scope.permission) {
-        mergedPermission = mergeFlatPermissions(
-          mergedPermission,
-          scope.permission,
-        );
+
+    for (const [scopeName, scope] of [
+      ["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];
+        const bothObjects =
+          typeof baseVal === "object" &&
+          baseVal !== null &&
+          typeof value === "object" &&
+          value !== null;
+
+        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 as Record<string, unknown>)) {
+            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);
+          } else if (typeof value === "object" && value !== null) {
+            for (const pattern of Object.keys(
+              value as Record<string, unknown>,
+            )) {
+              surfaceOrigins.set(pattern, scopeName);
+            }
+          }
+          origins.set(surface, surfaceOrigins);
+        }
       }
+
+      mergedPermission = mergeFlatPermissions(
+        mergedPermission,
+        scope.permission,
+      );
     }
 
     // Extract the universal fallback from permission["*"].
@@ -375,19 +411,28 @@ export class PermissionManager {
     const universalFallback = isPermissionState(mergedPermission["*"])
       ? (mergedPermission["*"] as PermissionState)
       : DEFAULT_UNIVERSAL_FALLBACK;
+    // Track which scope contributed the universal fallback.
+    const universalFallbackOrigin: RuleOrigin =
+      origins.get("*")?.get("*") ?? "builtin";
 
     // Build config rules from everything except the universal "*" key.
     const permissionWithoutUniversal: FlatPermissionConfig = Object.fromEntries(
       Object.entries(mergedPermission).filter(([k]) => k !== "*"),
     );
 
-    // Normalize to config rules, tagged with "config" layer.
+    // Normalize to config rules, tagged with "config" layer and their origin.
     const configRules: Ruleset = normalizeFlatConfig(
       permissionWithoutUniversal,
-    ).map((r): Rule => ({ ...r, layer: "config" }));
+    ).map(
+      (r): Rule => ({
+        ...r,
+        layer: "config",
+        origin: origins.get(r.surface)?.get(r.pattern) ?? "builtin",
+      }),
+    );
 
     const composedRules = composeRuleset(
-      synthesizeDefaults(universalFallback),
+      synthesizeDefaults(universalFallback, universalFallbackOrigin),
       synthesizeBaseline(configRules),
       configRules,
     );
@@ -415,6 +460,17 @@ export class PermissionManager {
     return value;
   }
 
+  /**
+   * Return the composed config-layer rules for the given agent scope.
+   * Used by the `/permission-system show` command to display effective rules
+   * with their origin annotations.
+   * Session rules are not included — they are runtime-only.
+   */
+  getComposedConfigRules(agentName?: string): Ruleset {
+    const { composedRules } = this.resolvePermissions(agentName);
+    return composedRules.filter((r) => r.layer === "config");
+  }
+
   /**
    * Get the tool-level permission state for a tool, without considering
    * command-level rules. Used for tool injection decisions.
@@ -480,6 +536,7 @@ export class PermissionManager {
           ? rule.pattern
           : undefined,
       source: deriveSource(rule, normalizedToolName),
+      origin: rule.origin,
       ...extras,
     };
   }
@@ -493,7 +550,6 @@ export class PermissionManager {
  *
  * - session          → "session" (always, all surfaces)
  * - mcp + default    → "default"
- * - mcp + override   → "tool"
  * - mcp + other      → "mcp"
  * - special          → "special" (always)
  * - skill            → "skill" (always)
@@ -509,7 +565,6 @@ function deriveSource(
 
   if (toolName === "mcp") {
     if (rule.layer === "default") return "default";
-    if (rule.layer === "override") return "tool";
     return "mcp";
   }
 

package/src/rule.ts

@@ -1,6 +1,23 @@
 import type { PermissionState } from "./types";
 import { wildcardMatch } from "./wildcard-matcher";
 
+/**
+ * Provenance of a rule — which source contributed it.
+ *
+ * Config scopes: "global", "project", "agent", "project-agent".
+ * Synthesized:   "builtin" (universal default / evaluate() fallback),
+ *                "baseline" (conditional MCP metadata auto-allow).
+ * Runtime:       "session" (session approvals).
+ */
+export type RuleOrigin =
+  | "global"
+  | "project"
+  | "agent"
+  | "project-agent"
+  | "builtin"
+  | "baseline"
+  | "session";
+
 /** A single permission rule — the atomic unit of policy. */
 export interface Rule {
   /** The permission surface: "bash", "read", "mcp", "skill", "external_directory", etc. */
@@ -13,7 +30,9 @@ export interface Rule {
    * Origin layer — used to derive PermissionCheckResult.source after evaluation.
    * Not used by evaluate(); purely informational metadata.
    */
-  layer?: "default" | "override" | "baseline" | "config" | "session";
+  layer?: "default" | "baseline" | "config" | "session";
+  /** Which source contributed this rule. */
+  origin: RuleOrigin;
 }
 
 /** An ordered list of rules. Later rules take priority (last-match-wins). */
@@ -39,7 +58,12 @@ export function evaluate(
       wildcardMatch(r.surface, surface) && wildcardMatch(r.pattern, pattern),
   );
   if (rule !== undefined) return rule;
-  return { surface, pattern, action: defaultAction ?? "ask" };
+  return {
+    surface,
+    pattern,
+    action: defaultAction ?? "ask",
+    origin: "builtin",
+  };
 }
 
 /**

package/src/session-rules.ts

@@ -15,7 +15,13 @@ export class SessionRules {
 
   /** Record a wildcard pattern as approved for the given surface. */
   approve(surface: string, pattern: string): void {
-    this.rules.push({ surface, pattern, action: "allow", layer: "session" });
+    this.rules.push({
+      surface,
+      pattern,
+      action: "allow",
+      layer: "session",
+      origin: "session",
+    });
   }
 
   /** Return a defensive copy of the current session ruleset. */

package/src/synthesize.ts

@@ -1,4 +1,4 @@
-import type { Rule, Ruleset } from "./rule";
+import type { Rule, RuleOrigin, Ruleset } from "./rule";
 import type { PermissionState } from "./types";
 
 /**
@@ -11,13 +11,17 @@ import type { PermissionState } from "./types";
  * regular config rules from `normalizeFlatConfig()` and sit at higher indices
  * in the composed array, so they override this default via last-match-wins.
  */
-export function synthesizeDefaults(universalDefault: PermissionState): Ruleset {
+export function synthesizeDefaults(
+  universalDefault: PermissionState,
+  origin: RuleOrigin = "builtin",
+): Ruleset {
   return [
     {
       surface: "*",
       pattern: "*",
       action: universalDefault,
       layer: "default",
+      origin,
     },
   ];
 }
@@ -63,6 +67,7 @@ export function synthesizeBaseline(configRules: Ruleset): Ruleset {
       pattern: target,
       action: "allow",
       layer: "baseline",
+      origin: "baseline",
     }),
   );
 }

package/src/tool-input-preview.ts

@@ -193,7 +193,12 @@ export function getPermissionLogContext(
   result: PermissionCheckResult,
   input: unknown,
   pathBearingTools: ReadonlySet<string>,
-): { command?: string; target?: string; toolInputPreview?: string } {
+): {
+  command?: string;
+  target?: string;
+  toolInputPreview?: string;
+  origin?: string;
+} {
   return {
     command: result.command,
     target: result.target,
@@ -202,5 +207,6 @@ export function getPermissionLogContext(
       input,
       pathBearingTools,
     ),
+    origin: result.origin,
   };
 }

package/src/types.ts

@@ -1,5 +1,9 @@
 export type PermissionState = "allow" | "deny" | "ask";
 
+import type { RuleOrigin } from "./rule";
+
+export type { RuleOrigin };
+
 /**
  * The on-disk permission shape inside the `"permission"` key.
  * Each key is a surface name; values are either a PermissionState string
@@ -36,4 +40,6 @@ export interface PermissionCheckResult {
   command?: string;
   target?: string;
   source: "tool" | "bash" | "mcp" | "skill" | "special" | "default" | "session";
+  /** Which source contributed the winning rule. */
+  origin: RuleOrigin;
 }

package/tests/config-modal.test.ts

@@ -10,6 +10,7 @@ import {
   type PermissionSystemExtensionConfig,
   savePermissionSystemConfig,
 } from "../src/extension-config";
+import type { Rule } from "../src/rule";
 
 vi.mock("@mariozechner/pi-coding-agent", () => ({
   getSettingsListTheme: () => ({}),
@@ -234,3 +235,85 @@ test("permission-system command handlers manage config summary, persistence, and
     rmSync(baseDir, { recursive: true, force: true });
   }
 });
+
+test("show output includes rule origins when getComposedRules is provided", async () => {
+  const config = { ...DEFAULT_EXTENSION_CONFIG };
+  const composedRules: Rule[] = [
+    {
+      surface: "read",
+      pattern: "*",
+      action: "allow",
+      layer: "config",
+      origin: "global",
+    },
+    {
+      surface: "bash",
+      pattern: "rm *",
+      action: "deny",
+      layer: "config",
+      origin: "project",
+    },
+  ];
+
+  const controller = {
+    getConfig: () => config,
+    setConfig: () => {},
+    getConfigPath: () => "/fake/config.json",
+    getComposedRules: () => composedRules,
+  };
+
+  let definition: {
+    handler: (args: string, ctx: CommandContextStub) => Promise<void>;
+  } | null = null;
+
+  registerPermissionSystemCommand(
+    {
+      registerCommand(_name: string, nextDef: typeof definition) {
+        definition = nextDef;
+      },
+    } as never,
+    controller as never,
+  );
+
+  const ctx = createCommandContext(true);
+  await definition!.handler("show", ctx.ctx);
+  const msg = lastNotification(ctx.notifications).message;
+
+  assert.ok(msg.includes("global"), `expected 'global' in: ${msg}`);
+  assert.ok(msg.includes("project"), `expected 'project' in: ${msg}`);
+  assert.ok(msg.includes("read"), `expected 'read' in: ${msg}`);
+  assert.ok(msg.includes("bash"), `expected 'bash' in: ${msg}`);
+});
+
+test("show output omits rule summary when getComposedRules is not provided", async () => {
+  const config = { ...DEFAULT_EXTENSION_CONFIG, yoloMode: true };
+
+  const controller = {
+    getConfig: () => config,
+    setConfig: () => {},
+    getConfigPath: () => "/fake/config.json",
+    // no getComposedRules
+  };
+
+  let definition: {
+    handler: (args: string, ctx: CommandContextStub) => Promise<void>;
+  } | null = null;
+
+  registerPermissionSystemCommand(
+    {
+      registerCommand(_name: string, nextDef: typeof definition) {
+        definition = nextDef;
+      },
+    } as never,
+    controller as never,
+  );
+
+  const ctx = createCommandContext(true);
+  await definition!.handler("show", ctx.ctx);
+  const msg = lastNotification(ctx.notifications).message;
+
+  // Config knobs still present.
+  assert.ok(msg.includes("yoloMode=on"), `expected yoloMode=on in: ${msg}`);
+  // No rule annotation lines.
+  assert.ok(!msg.includes("(global)"), `unexpected '(global)' in: ${msg}`);
+});

package/tests/handlers/tool-call.test.ts

@@ -52,7 +52,7 @@ function makeToolCallEvent(
 function makePermissionResult(
   state: "allow" | "deny" | "ask",
 ): PermissionCheckResult {
-  return { state, toolName: "read", source: "tool" };
+  return { state, toolName: "read", source: "tool", origin: "builtin" };
 }
 
 function makeRuntime(
@@ -761,6 +761,7 @@ describe("handleToolCall — session recording on approved_for_session", () => {
             state: "ask",
             toolName: "read",
             source: "tool",
+            origin: "builtin",
           }),
         } as unknown as ExtensionRuntime["permissionManager"],
         sessionRules,