@gotgenes/pi-permission-system 13.0.0 → 13.1.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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).
 
+## [13.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v13.0.0...pi-permission-system-v13.1.0) (2026-06-13)
+
+
+### Features
+
+* **pi-permission-system:** add DenyWithReason type and shared guard ([51750e1](https://github.com/gotgenes/pi-packages/commit/51750e188592520798eaf9676a15a709a779cf96)), closes [#395](https://github.com/gotgenes/pi-packages/issues/395)
+* **pi-permission-system:** append custom reason to denial messages ([d8e5756](https://github.com/gotgenes/pi-packages/commit/d8e575632678b806d381f1436dbb06197d742104)), closes [#395](https://github.com/gotgenes/pi-packages/issues/395)
+* **pi-permission-system:** build deny rules with reason in normalizeFlatConfig ([186c15a](https://github.com/gotgenes/pi-packages/commit/186c15a74944bc2800bcea738984021169fabc8d)), closes [#395](https://github.com/gotgenes/pi-packages/issues/395)
+* **pi-permission-system:** preserve deny-with-reason from JSON config ([3201bfd](https://github.com/gotgenes/pi-packages/commit/3201bfd55d68aac1ee87ac452723f6d0783dba6d)), closes [#395](https://github.com/gotgenes/pi-packages/issues/395)
+* **pi-permission-system:** thread deny reason into PermissionCheckResult ([ed712e4](https://github.com/gotgenes/pi-packages/commit/ed712e47458a662e3d1159e2f5096c709ab2ddf5)), closes [#395](https://github.com/gotgenes/pi-packages/issues/395)
+
+
+### Documentation
+
+* **pi-permission-system:** document deny-with-reason config form ([45be4e7](https://github.com/gotgenes/pi-packages/commit/45be4e72c0ca43040cb0f55ca196a0cab0b9fc14)), closes [#395](https://github.com/gotgenes/pi-packages/issues/395)
+
 ## [13.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v12.0.0...pi-permission-system-v13.0.0) (2026-06-12)
 
 

package/config/config.example.json

@@ -25,7 +25,8 @@
       "*": "ask",
       "git *": "ask",
       "git status": "allow",
-      "git diff": "allow"
+      "git diff": "allow",
+      "npm *": { "action": "deny", "reason": "Use pnpm instead" }
     },
     "mcp": { "*": "ask", "mcp_status": "allow", "mcp_list": "allow" },
     "skill": { "*": "ask" },

package/package.json

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

package/schemas/permissions.schema.json

@@ -125,8 +125,34 @@
         "minLength": 1
       },
       "additionalProperties": {
-        "$ref": "#/$defs/permissionState"
+        "oneOf": [
+          {
+            "$ref": "#/$defs/permissionState",
+            "description": "A permission decision for this pattern."
+          },
+          {
+            "$ref": "#/$defs/denyWithReason",
+            "description": "Deny this pattern with an optional custom reason."
+          }
+        ]
       }
+    },
+    "denyWithReason": {
+      "type": "object",
+      "description": "Deny with an optional custom reason shown to the agent when the action is blocked.",
+      "properties": {
+        "action": {
+          "const": "deny",
+          "description": "The permission decision \u2014 must be \"deny\"."
+        },
+        "reason": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Optional reason shown to the agent when this action is denied."
+        }
+      },
+      "required": ["action"],
+      "additionalProperties": false
     }
   }
 }

package/src/common.ts

@@ -1,4 +1,4 @@
-import type { PermissionState } from "./types";
+import type { DenyWithReason, PermissionState } from "./types";
 
 export function toRecord(value: unknown): Record<string, unknown> {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -38,6 +38,22 @@ export function isPermissionState(value: unknown): value is PermissionState {
   return value === "allow" || value === "deny" || value === "ask";
 }
 
+/**
+ * Narrow type guard: a raw value representing a DenyWithReason object.
+ * Accepts `{ action: "deny" }` and `{ action: "deny", reason: "…" }`.
+ * Rejects a non-string `reason` to keep malformed config out of the rule set.
+ */
+export function isDenyWithReason(value: unknown): value is DenyWithReason {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    record.action === "deny" &&
+    (record.reason === undefined || typeof record.reason === "string")
+  );
+}
+
 type StackNode = { indent: number; target: Record<string, unknown> };
 
 export function parseSimpleYamlMap(input: string): Record<string, unknown> {

package/src/config-loader.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { normalize } from "node:path";
-
 import {
+  isDenyWithReason,
   isPermissionState,
   normalizeOptionalPositiveInt,
   normalizeOptionalStringArray,
@@ -15,7 +15,7 @@ import {
   getProjectConfigPath,
 } from "./config-paths";
 import { mergeFlatPermissions } from "./permission-merge";
-import type { FlatPermissionConfig } from "./types";
+import type { FlatPermissionConfig, PatternValue } from "./types";
 
 /**
  * Unified config shape combining runtime knobs and flat permission policy.
@@ -127,7 +127,8 @@ function normalizeOptionalBoolean(value: unknown): boolean | undefined {
 
 /**
  * Normalize a raw `permission` value from parsed JSON into a FlatPermissionConfig.
- * Drops non-object top-level values, invalid PermissionState strings, and
+ * Accepts PermissionState strings and DenyWithReason objects inside pattern
+ * maps. Drops non-object top-level values, invalid PermissionState strings, and
  * invalid action values inside object maps.
  */
 function normalizeFlatPermissionValue(
@@ -147,12 +148,15 @@ function normalizeFlatPermissionValue(
         hasAny = true;
       }
     } else if (typeof val === "object" && val !== null && !Array.isArray(val)) {
-      const map: Record<string, import("./types").PermissionState> = {};
+      const map: Record<string, PatternValue> = {};
       let mapHasAny = false;
       for (const [pattern, action] of Object.entries(
         val as Record<string, unknown>,
       )) {
-        if (isPermissionState(action)) {
+        if (isDenyWithReason(action)) {
+          map[pattern] = action;
+          mapHasAny = true;
+        } else if (isPermissionState(action)) {
           map[pattern] = action;
           mapHasAny = true;
         }

package/src/denial-messages.ts

@@ -126,7 +126,8 @@ function buildToolDenyBody(
     parts.push(qualifier);
   }
 
-  return `${parts.join(" ")}.`;
+  // reasonSuffix appends ` Reason: <reason>.` after the sentence-ending period.
+  return `${parts.join(" ")}.${reasonSuffix(check.reason)}`;
 }
 
 /**

package/src/normalize.ts

@@ -1,4 +1,4 @@
-import { isPermissionState } from "./common";
+import { isDenyWithReason, isPermissionState } from "./common";
 import type { Rule, Ruleset } from "./rule";
 import type { FlatPermissionConfig } from "./types";
 
@@ -7,6 +7,8 @@ import type { FlatPermissionConfig } from "./types";
  *
  * Each key is a surface name. A string value is shorthand for
  * `{ "*": action }`. An object value maps patterns to actions.
+ * A pattern value may be a PermissionState string or a `DenyWithReason`
+ * object (`{ action: "deny", reason?: string }`).
  * Invalid action values are silently skipped.
  *
  * The universal fallback key `"*"` is included if present — callers
@@ -23,7 +25,15 @@ export function normalizeFlatConfig(permission: FlatPermissionConfig): Ruleset {
       // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defensive null check; value type does not include null but runtime JSON may
     } else if (typeof value === "object" && value !== null) {
       for (const [pattern, action] of Object.entries(value)) {
-        if (isPermissionState(action)) {
+        if (isDenyWithReason(action)) {
+          rules.push({
+            surface,
+            pattern,
+            action: "deny",
+            reason: action.reason,
+            origin: "builtin",
+          });
+        } else if (isPermissionState(action)) {
           rules.push({ surface, pattern, action, origin: "builtin" });
         }
       }

package/src/permission-manager.ts

@@ -322,6 +322,7 @@ function buildCheckResult(
   return {
     toolName,
     state: rule.action,
+    reason: rule.reason,
     matchedPattern:
       rule.layer === "config" || rule.layer === "session"
         ? rule.pattern

package/src/rule.ts

@@ -27,6 +27,8 @@ export interface Rule {
   pattern: string;
   /** The permission decision. */
   action: PermissionState;
+  /** Custom denial reason for deny rules (optional). */
+  reason?: string;
   /**
    * Origin layer — used to derive PermissionCheckResult.source after evaluation.
    * Not used by evaluate(); purely informational metadata.

package/src/types.ts

@@ -4,14 +4,27 @@ import type { RuleOrigin } from "./rule";
 
 export type { RuleOrigin };
 
+/**
+ * A deny action with an optional reason annotation, used when a pattern maps
+ * to an object instead of a plain PermissionState string.
+ */
+export interface DenyWithReason {
+  action: "deny";
+  reason?: string;
+}
+
+/** A pattern value: a PermissionState string OR a DenyWithReason object. */
+export type PatternValue = PermissionState | DenyWithReason;
+
 /**
  * The on-disk permission shape inside the `"permission"` key.
- * Each key is a surface name; values are either a PermissionState string
- * (shorthand for `{ "*": action }`) or a pattern→action map.
+ * A surface value is a PermissionState string (shorthand for `{ "*": action }`)
+ * or a pattern→value map. Pattern values may be a PermissionState string or a
+ * DenyWithReason object. A top-level value is never a bare DenyWithReason.
  */
 export type FlatPermissionConfig = Record<
   string,
-  PermissionState | Record<string, PermissionState>
+  PermissionState | Record<string, PatternValue>
 >;
 
 /**
@@ -34,6 +47,8 @@ export type BashCommandContext =
 export interface PermissionCheckResult {
   toolName: string;
   state: PermissionState;
+  /** Custom denial reason from a deny-with-reason pattern, when present. */
+  reason?: string;
   matchedPattern?: string;
   command?: string;
   target?: string;

package/test/common.test.ts

@@ -3,6 +3,7 @@ import { afterEach, describe, expect, it, test, vi } from "vitest";
 import {
   extractFrontmatter,
   getNonEmptyString,
+  isDenyWithReason,
   isPermissionState,
   normalizeOptionalPositiveInt,
   normalizeOptionalStringArray,
@@ -102,6 +103,33 @@ describe("isPermissionState", () => {
   });
 });
 
+describe("isDenyWithReason", () => {
+  test("returns true for { action: 'deny' } without a reason", () => {
+    expect(isDenyWithReason({ action: "deny" })).toBe(true);
+  });
+
+  test("returns true for { action: 'deny', reason: '...' }", () => {
+    expect(isDenyWithReason({ action: "deny", reason: "Use pnpm" })).toBe(true);
+  });
+
+  test("returns false for non-deny actions", () => {
+    expect(isDenyWithReason({ action: "allow" })).toBe(false);
+    expect(isDenyWithReason({ action: "ask" })).toBe(false);
+  });
+
+  test("returns false for a non-string reason", () => {
+    expect(isDenyWithReason({ action: "deny", reason: 42 })).toBe(false);
+    expect(isDenyWithReason({ action: "deny", reason: null })).toBe(false);
+  });
+
+  test("returns false for non-object types", () => {
+    expect(isDenyWithReason(null)).toBe(false);
+    expect(isDenyWithReason(undefined)).toBe(false);
+    expect(isDenyWithReason("deny")).toBe(false);
+    expect(isDenyWithReason(["deny"])).toBe(false);
+  });
+});
+
 describe("extractFrontmatter", () => {
   test("returns empty string when no frontmatter delimiter", () => {
     expect(extractFrontmatter("# Hello\nSome content")).toBe("");

package/test/config-loader.test.ts

@@ -243,6 +243,49 @@ describe("loadUnifiedConfig", () => {
     });
   });
 
+  it("preserves a deny-with-reason object inside a pattern map", () => {
+    const configPath = join(tempDir, "config.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({
+        permission: {
+          bash: {
+            "git *": "allow",
+            "npm *": { action: "deny", reason: "Use pnpm instead" },
+          },
+        },
+      }),
+    );
+
+    const result = loadUnifiedConfig(configPath);
+    expect(result.config.permission).toEqual({
+      bash: {
+        "git *": "allow",
+        "npm *": { action: "deny", reason: "Use pnpm instead" },
+      },
+    });
+  });
+
+  it("strips a deny object with a non-string reason (malformed)", () => {
+    const configPath = join(tempDir, "config.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({
+        permission: {
+          bash: {
+            "git *": "allow",
+            "npm *": { action: "deny", reason: 42 },
+          },
+        },
+      }),
+    );
+
+    const result = loadUnifiedConfig(configPath);
+    expect(result.config.permission).toEqual({
+      bash: { "git *": "allow" },
+    });
+  });
+
   it("returns no permission when the permission field is absent", () => {
     const configPath = join(tempDir, "config.json");
     writeFileSync(configPath, JSON.stringify({ debugLog: false }));

package/test/denial-messages.test.ts

@@ -114,6 +114,67 @@ describe("formatDenyReason", () => {
       );
     });
 
+    test("bash with a custom reason appended after the period", () => {
+      expect(
+        formatDenyReason(
+          toolCtx(
+            toolCheck("bash", {
+              command: "npm install",
+              matchedPattern: "npm *",
+              reason: "Use pnpm instead",
+            }),
+          ),
+        ),
+      ).toBe(
+        "[pi-permission-system] is not permitted to run 'bash' command 'npm install' (matched 'npm *'). Reason: Use pnpm instead.",
+      );
+    });
+
+    test("custom reason with no matched pattern", () => {
+      expect(
+        formatDenyReason(
+          toolCtx(
+            toolCheck("write", {
+              reason: "Write access is disabled for security",
+            }),
+          ),
+        ),
+      ).toBe(
+        "[pi-permission-system] is not permitted to run 'write'. Reason: Write access is disabled for security.",
+      );
+    });
+
+    test("custom reason is included alongside the agent name", () => {
+      expect(
+        formatDenyReason(
+          toolCtx(
+            toolCheck("bash", {
+              command: "yarn build",
+              matchedPattern: "yarn *",
+              reason: "Use pnpm instead",
+            }),
+            "dev-agent",
+          ),
+        ),
+      ).toBe(
+        "[pi-permission-system] Agent 'dev-agent' is not permitted to run 'bash' command 'yarn build' (matched 'yarn *'). Reason: Use pnpm instead.",
+      );
+    });
+
+    test("custom reason on an MCP target", () => {
+      expect(
+        formatDenyReason(
+          toolCtx(
+            mcpCheck("server:deploy", {
+              reason: "Deploy requires approval from a senior engineer",
+            }),
+          ),
+        ),
+      ).toBe(
+        "[pi-permission-system] is not permitted to run MCP target 'server:deploy'. Reason: Deploy requires approval from a senior engineer.",
+      );
+    });
+
     test("MCP source with target on non-mcp toolName", () => {
       expect(
         formatDenyReason(

package/test/normalize.test.ts

@@ -163,4 +163,85 @@ describe("normalizeFlatConfig", () => {
       ]);
     });
   });
+
+  describe("deny with reason", () => {
+    test("{ action: 'deny', reason } produces a deny rule carrying the reason", () => {
+      const result = normalizeFlatConfig({
+        bash: { "npm *": { action: "deny", reason: "Use pnpm instead" } },
+      });
+      expect(result).toEqual([
+        {
+          surface: "bash",
+          pattern: "npm *",
+          action: "deny",
+          reason: "Use pnpm instead",
+          origin: "builtin",
+        },
+      ]);
+    });
+
+    test("{ action: 'deny' } without a reason produces a deny rule without reason", () => {
+      const result = normalizeFlatConfig({
+        bash: { "rm -rf *": { action: "deny" } },
+      });
+      expect(result).toEqual([
+        {
+          surface: "bash",
+          pattern: "rm -rf *",
+          action: "deny",
+          origin: "builtin",
+        },
+      ]);
+    });
+
+    test("deny-with-reason and plain strings coexist in the same surface", () => {
+      const result = normalizeFlatConfig({
+        bash: {
+          "git *": "allow",
+          "npm *": { action: "deny", reason: "Use pnpm" },
+          "*": "ask",
+        },
+      });
+      expect(result).toEqual([
+        {
+          surface: "bash",
+          pattern: "git *",
+          action: "allow",
+          origin: "builtin",
+        },
+        {
+          surface: "bash",
+          pattern: "npm *",
+          action: "deny",
+          reason: "Use pnpm",
+          origin: "builtin",
+        },
+        { surface: "bash", pattern: "*", action: "ask", origin: "builtin" },
+      ]);
+    });
+
+    test("top-level deny-with-reason object is treated as a pattern map", () => {
+      // At the surface level, { action: "deny", reason: "..." } is parsed as a
+      // pattern→action map: "action" is a pattern key with action "deny", and
+      // "reason" maps to a non-PermissionState string that is dropped.
+      const result = normalizeFlatConfig({
+        bash: { action: "deny", reason: "Not allowed" } as never,
+      });
+      expect(result).toEqual([
+        {
+          surface: "bash",
+          pattern: "action",
+          action: "deny",
+          origin: "builtin",
+        },
+      ]);
+    });
+
+    test("non-string reason is rejected (malformed config)", () => {
+      const result = normalizeFlatConfig({
+        bash: { "npm *": { action: "deny", reason: 42 } as never },
+      });
+      expect(result).toEqual([]);
+    });
+  });
 });

package/test/permission-manager-unified.test.ts

@@ -1245,6 +1245,71 @@ describe("cross-cutting path surface", () => {
     }
   });
 
+  // ── Deny-with-reason ────────────────────────────────────────────────────
+
+  it("deny-with-reason: reason threads through to PermissionCheckResult", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      bash: { "npm *": { action: "deny", reason: "Use pnpm instead" } },
+    });
+    try {
+      const result = manager.checkPermission("bash", {
+        command: "npm install",
+      });
+      expect(result.state).toBe("deny");
+      expect(result.reason).toBe("Use pnpm instead");
+      expect(result.matchedPattern).toBe("npm *");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("deny-without-reason: reason is undefined in PermissionCheckResult", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      bash: { "rm -rf *": "deny" },
+    });
+    try {
+      const result = manager.checkPermission("bash", { command: "rm -rf /" });
+      expect(result.state).toBe("deny");
+      expect(result.reason).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("deny-with-reason on a non-bash surface", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      read: {
+        "*.env": {
+          action: "deny",
+          reason: "Environment files contain secrets",
+        },
+      },
+    });
+    try {
+      const result = manager.checkPermission("read", { path: ".env" });
+      expect(result.state).toBe("deny");
+      expect(result.reason).toBe("Environment files contain secrets");
+      expect(result.matchedPattern).toBe("*.env");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("non-string reason falls through to the default (malformed config)", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      bash: { "npm *": { action: "deny", reason: 42 } },
+    });
+    try {
+      const result = manager.checkPermission("bash", {
+        command: "npm install",
+      });
+      expect(result.state).toBe("ask");
+      expect(result.reason).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+
   // ── Last-match-wins ordering ────────────────────────────────────────────
 
   it("last-match-wins: catch-all after deny overrides the deny", () => {

package/test/rule.test.ts

@@ -216,6 +216,67 @@ describe("evaluate", () => {
     expect(result.origin).toBe("builtin");
   });
 
+  test("evaluate() propagates reason from the matched deny rule", () => {
+    const rule: Rule = {
+      surface: "bash",
+      pattern: "npm *",
+      action: "deny",
+      reason: "Use pnpm instead",
+      layer: "config",
+      origin: "global",
+    };
+    const result = evaluate("bash", "npm install", [rule]);
+    expect(result.action).toBe("deny");
+    expect(result.reason).toBe("Use pnpm instead");
+  });
+
+  test("evaluate() carries reason through last-match-wins when deny wins", () => {
+    const allowAll: Rule = {
+      surface: "bash",
+      pattern: "*",
+      action: "allow",
+      layer: "config",
+      origin: "global",
+    };
+    const denyNpm: Rule = {
+      surface: "bash",
+      pattern: "npm *",
+      action: "deny",
+      reason: "Use pnpm",
+      layer: "config",
+      origin: "global",
+    };
+    const result = evaluate("bash", "npm install", [allowAll, denyNpm]);
+    expect(result.action).toBe("deny");
+    expect(result.reason).toBe("Use pnpm");
+  });
+
+  test("evaluate() drops reason when a later allow overrides the deny", () => {
+    const denyNpm: Rule = {
+      surface: "bash",
+      pattern: "npm *",
+      action: "deny",
+      reason: "Use pnpm",
+      layer: "config",
+      origin: "global",
+    };
+    const allowInstall: Rule = {
+      surface: "bash",
+      pattern: "npm install",
+      action: "allow",
+      layer: "config",
+      origin: "global",
+    };
+    const result = evaluate("bash", "npm install", [denyNpm, allowInstall]);
+    expect(result.action).toBe("allow");
+    expect(result.reason).toBeUndefined();
+  });
+
+  test("evaluate() synthetic fallback rule has no reason", () => {
+    const result = evaluate("bash", "npm install", []);
+    expect(result.reason).toBeUndefined();
+  });
+
   test("RuleOrigin covers all seven provenance values", () => {
     const origins: RuleOrigin[] = [
       "global",