@gotgenes/pi-permission-system 6.0.2 → 7.0.0

package/tests/bash-external-directory.test.ts

@@ -9,14 +9,12 @@ vi.mock("node:os", () => {
   };
 });
 
+import { formatDenyReason } from "../src/denial-messages";
 import {
   extractExternalPathsFromBashCommand,
   extractTokensForPathRules,
 } from "../src/handlers/gates/bash-path-extractor";
-import {
-  formatBashExternalDirectoryAskPrompt,
-  formatBashExternalDirectoryDenyReason,
-} from "../src/handlers/gates/external-directory-messages";
+import { formatBashExternalDirectoryAskPrompt } from "../src/handlers/gates/external-directory-messages";
 
 afterEach(() => {
   vi.restoreAllMocks();
@@ -859,35 +857,19 @@ describe("formatBashExternalDirectoryAskPrompt", () => {
   });
 });
 
-describe("formatBashExternalDirectoryDenyReason", () => {
-  test("includes command, external paths, and CWD", () => {
-    const result = formatBashExternalDirectoryDenyReason(
-      "cat /etc/hosts",
-      ["/etc/hosts"],
-      "/projects/my-app",
-    );
+describe("bash external-directory denial messages (centralized)", () => {
+  test("denial message includes command, paths, and extension tag", () => {
+    const result = formatDenyReason({
+      kind: "bash_external_directory",
+      command: "cat /etc/hosts",
+      externalPaths: ["/etc/hosts"],
+      cwd: "/projects/my-app",
+    });
     expect(result).toContain("cat /etc/hosts");
     expect(result).toContain("/etc/hosts");
     expect(result).toContain("/projects/my-app");
-  });
-
-  test("includes hard stop hint", () => {
-    const result = formatBashExternalDirectoryDenyReason(
-      "cat /etc/hosts",
-      ["/etc/hosts"],
-      "/projects/my-app",
-    );
-    expect(result).toContain("Hard stop");
-  });
-
-  test("includes agent name when provided", () => {
-    const result = formatBashExternalDirectoryDenyReason(
-      "cat /etc/hosts",
-      ["/etc/hosts"],
-      "/projects/my-app",
-      "my-agent",
-    );
-    expect(result).toContain("my-agent");
+    expect(result).toContain("[pi-permission-system]");
+    expect(result).not.toContain("Hard stop");
   });
 });
 

package/tests/denial-messages.test.ts

@@ -0,0 +1,517 @@
+import { describe, expect, test } from "vitest";
+
+import {
+  type DenialContext,
+  EXTENSION_TAG,
+  formatDenyReason,
+  formatUnavailableReason,
+  formatUserDeniedReason,
+} from "../src/denial-messages";
+import type { PermissionCheckResult } from "../src/types";
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function toolCheck(
+  toolName: string,
+  overrides: Partial<PermissionCheckResult> = {},
+): PermissionCheckResult {
+  return {
+    toolName,
+    state: "deny",
+    source: "tool",
+    origin: "builtin",
+    ...overrides,
+  };
+}
+
+function mcpCheck(
+  target: string,
+  overrides: Partial<PermissionCheckResult> = {},
+): PermissionCheckResult {
+  return {
+    toolName: "mcp",
+    target,
+    state: "deny",
+    source: "mcp",
+    origin: "builtin",
+    ...overrides,
+  };
+}
+
+function toolCtx(
+  check: PermissionCheckResult,
+  agentName?: string,
+): Extract<DenialContext, { kind: "tool" }> {
+  return { kind: "tool", check, agentName };
+}
+
+// ── EXTENSION_TAG ──────────────────────────────────────────────────────────
+
+describe("EXTENSION_TAG", () => {
+  test("is [pi-permission-system]", () => {
+    expect(EXTENSION_TAG).toBe("[pi-permission-system]");
+  });
+});
+
+// ── formatDenyReason ───────────────────────────────────────────────────────
+
+describe("formatDenyReason", () => {
+  describe("tool context", () => {
+    test("generic tool without agent", () => {
+      expect(formatDenyReason(toolCtx(toolCheck("write")))).toBe(
+        "[pi-permission-system] is not permitted to run 'write'.",
+      );
+    });
+
+    test("generic tool with agent", () => {
+      expect(formatDenyReason(toolCtx(toolCheck("write"), "my-agent"))).toBe(
+        "[pi-permission-system] Agent 'my-agent' is not permitted to run 'write'.",
+      );
+    });
+
+    test("MCP target", () => {
+      expect(formatDenyReason(toolCtx(mcpCheck("server:do-thing")))).toBe(
+        "[pi-permission-system] is not permitted to run MCP target 'server:do-thing'.",
+      );
+    });
+
+    test("bash with command", () => {
+      expect(
+        formatDenyReason(toolCtx(toolCheck("bash", { command: "rm -rf /" }))),
+      ).toBe(
+        "[pi-permission-system] is not permitted to run 'bash' command 'rm -rf /'.",
+      );
+    });
+
+    test("bash with command and matched pattern", () => {
+      expect(
+        formatDenyReason(
+          toolCtx(
+            toolCheck("bash", {
+              command: "rm -rf /",
+              matchedPattern: "rm *",
+            }),
+          ),
+        ),
+      ).toBe(
+        "[pi-permission-system] is not permitted to run 'bash' command 'rm -rf /' (matched 'rm *').",
+      );
+    });
+
+    test("MCP source with target on non-mcp toolName", () => {
+      expect(
+        formatDenyReason(
+          toolCtx(
+            toolCheck("anything", { source: "mcp", target: "server:tool" }),
+          ),
+        ),
+      ).toBe(
+        "[pi-permission-system] is not permitted to run MCP target 'server:tool'.",
+      );
+    });
+  });
+
+  describe("path context", () => {
+    test("without agent", () => {
+      expect(
+        formatDenyReason({
+          kind: "path",
+          toolName: "read",
+          pathValue: "/etc/passwd",
+        }),
+      ).toBe(
+        "[pi-permission-system] Current agent is not permitted to access path '/etc/passwd' via tool 'read'.",
+      );
+    });
+
+    test("with agent", () => {
+      expect(
+        formatDenyReason({
+          kind: "path",
+          toolName: "read",
+          pathValue: "/etc/passwd",
+          agentName: "sec-agent",
+        }),
+      ).toBe(
+        "[pi-permission-system] Agent 'sec-agent' is not permitted to access path '/etc/passwd' via tool 'read'.",
+      );
+    });
+  });
+
+  describe("external_directory context", () => {
+    test("without agent", () => {
+      expect(
+        formatDenyReason({
+          kind: "external_directory",
+          toolName: "read",
+          pathValue: "/etc/passwd",
+          cwd: "/project",
+        }),
+      ).toBe(
+        "[pi-permission-system] Current agent is not permitted to run tool 'read' for path '/etc/passwd' outside working directory '/project'.",
+      );
+    });
+
+    test("with agent", () => {
+      expect(
+        formatDenyReason({
+          kind: "external_directory",
+          toolName: "read",
+          pathValue: "/etc/passwd",
+          cwd: "/project",
+          agentName: "sec-agent",
+        }),
+      ).toBe(
+        "[pi-permission-system] Agent 'sec-agent' is not permitted to run tool 'read' for path '/etc/passwd' outside working directory '/project'.",
+      );
+    });
+  });
+
+  describe("bash_external_directory context", () => {
+    test("single path without agent", () => {
+      expect(
+        formatDenyReason({
+          kind: "bash_external_directory",
+          command: "cat /etc/hosts",
+          externalPaths: ["/etc/hosts"],
+          cwd: "/project",
+        }),
+      ).toBe(
+        "[pi-permission-system] Current agent is not permitted to run bash command 'cat /etc/hosts' which references path(s) outside working directory '/project': /etc/hosts.",
+      );
+    });
+
+    test("multiple paths with agent", () => {
+      expect(
+        formatDenyReason({
+          kind: "bash_external_directory",
+          command: "cp /etc/hosts /tmp/out",
+          externalPaths: ["/etc/hosts", "/tmp/out"],
+          cwd: "/project",
+          agentName: "my-agent",
+        }),
+      ).toBe(
+        "[pi-permission-system] Agent 'my-agent' is not permitted to run bash command 'cp /etc/hosts /tmp/out' which references path(s) outside working directory '/project': /etc/hosts, /tmp/out.",
+      );
+    });
+  });
+
+  describe("bash_path context", () => {
+    test("without agent", () => {
+      expect(
+        formatDenyReason({
+          kind: "bash_path",
+          command: "cat /etc/passwd",
+          pathValue: "/etc/passwd",
+        }),
+      ).toBe(
+        "[pi-permission-system] Current agent is not permitted to access path '/etc/passwd' via tool 'bash'.",
+      );
+    });
+
+    test("with agent", () => {
+      expect(
+        formatDenyReason({
+          kind: "bash_path",
+          command: "cat /etc/passwd",
+          pathValue: "/etc/passwd",
+          agentName: "my-agent",
+        }),
+      ).toBe(
+        "[pi-permission-system] Agent 'my-agent' is not permitted to access path '/etc/passwd' via tool 'bash'.",
+      );
+    });
+  });
+
+  describe("skill_read context", () => {
+    test("without agent", () => {
+      expect(
+        formatDenyReason({
+          kind: "skill_read",
+          skillName: "librarian",
+          readPath: "/skills/librarian/SKILL.md",
+        }),
+      ).toBe(
+        "[pi-permission-system] Current agent is not permitted to access skill 'librarian' via '/skills/librarian/SKILL.md'.",
+      );
+    });
+
+    test("with agent", () => {
+      expect(
+        formatDenyReason({
+          kind: "skill_read",
+          skillName: "librarian",
+          readPath: "/skills/librarian/SKILL.md",
+          agentName: "my-agent",
+        }),
+      ).toBe(
+        "[pi-permission-system] Agent 'my-agent' is not permitted to access skill 'librarian' via '/skills/librarian/SKILL.md'.",
+      );
+    });
+  });
+});
+
+// ── formatUnavailableReason ────────────────────────────────────────────────
+
+describe("formatUnavailableReason", () => {
+  test("generic tool", () => {
+    expect(formatUnavailableReason(toolCtx(toolCheck("write")))).toBe(
+      "[pi-permission-system] Using tool 'write' requires approval, but no interactive UI is available.",
+    );
+  });
+
+  test("bash with command", () => {
+    expect(
+      formatUnavailableReason(
+        toolCtx(toolCheck("bash", { command: "git push" })),
+      ),
+    ).toBe(
+      "[pi-permission-system] Running bash command 'git push' requires approval, but no interactive UI is available.",
+    );
+  });
+
+  test("mcp", () => {
+    expect(formatUnavailableReason(toolCtx(mcpCheck("server:tool")))).toBe(
+      "[pi-permission-system] Using tool 'mcp' requires approval, but no interactive UI is available.",
+    );
+  });
+
+  test("path", () => {
+    expect(
+      formatUnavailableReason({
+        kind: "path",
+        toolName: "read",
+        pathValue: "/etc/passwd",
+      }),
+    ).toBe(
+      "[pi-permission-system] Accessing '/etc/passwd' requires approval, but no interactive UI is available.",
+    );
+  });
+
+  test("external_directory", () => {
+    expect(
+      formatUnavailableReason({
+        kind: "external_directory",
+        toolName: "read",
+        pathValue: "/etc/passwd",
+        cwd: "/project",
+      }),
+    ).toBe(
+      "[pi-permission-system] Accessing '/etc/passwd' outside the working directory requires approval, but no interactive UI is available.",
+    );
+  });
+
+  test("bash_external_directory", () => {
+    expect(
+      formatUnavailableReason({
+        kind: "bash_external_directory",
+        command: "cat /etc/hosts",
+        externalPaths: ["/etc/hosts"],
+        cwd: "/project",
+      }),
+    ).toBe(
+      "[pi-permission-system] Bash command 'cat /etc/hosts' references path(s) outside the working directory and requires approval, but no interactive UI is available.",
+    );
+  });
+
+  test("bash_path", () => {
+    expect(
+      formatUnavailableReason({
+        kind: "bash_path",
+        command: "cat /etc/passwd",
+        pathValue: "/etc/passwd",
+      }),
+    ).toBe(
+      "[pi-permission-system] Bash command 'cat /etc/passwd' accesses path '/etc/passwd' which requires approval, but no interactive UI is available.",
+    );
+  });
+
+  test("skill_read", () => {
+    expect(
+      formatUnavailableReason({
+        kind: "skill_read",
+        skillName: "librarian",
+        readPath: "/skills/librarian/SKILL.md",
+      }),
+    ).toBe(
+      "[pi-permission-system] Accessing skill 'librarian' requires approval, but no interactive UI is available.",
+    );
+  });
+});
+
+// ── formatUserDeniedReason ─────────────────────────────────────────────────
+
+describe("formatUserDeniedReason", () => {
+  describe("tool context", () => {
+    test("generic tool without reason", () => {
+      expect(formatUserDeniedReason(toolCtx(toolCheck("write")))).toBe(
+        "[pi-permission-system] User denied tool 'write'.",
+      );
+    });
+
+    test("generic tool with reason", () => {
+      expect(
+        formatUserDeniedReason(toolCtx(toolCheck("write")), "too risky"),
+      ).toBe(
+        "[pi-permission-system] User denied tool 'write'. Reason: too risky.",
+      );
+    });
+
+    test("bash with command", () => {
+      expect(
+        formatUserDeniedReason(
+          toolCtx(toolCheck("bash", { command: "ls -la" })),
+        ),
+      ).toBe("[pi-permission-system] User denied bash command 'ls -la'.");
+    });
+
+    test("MCP target", () => {
+      expect(formatUserDeniedReason(toolCtx(mcpCheck("server:query")))).toBe(
+        "[pi-permission-system] User denied MCP target 'server:query'.",
+      );
+    });
+  });
+
+  describe("path context", () => {
+    test("without reason", () => {
+      expect(
+        formatUserDeniedReason({
+          kind: "path",
+          toolName: "read",
+          pathValue: "/etc/passwd",
+        }),
+      ).toBe(
+        "[pi-permission-system] User denied access to path '/etc/passwd'.",
+      );
+    });
+
+    test("with reason", () => {
+      expect(
+        formatUserDeniedReason(
+          { kind: "path", toolName: "read", pathValue: "/etc/passwd" },
+          "sensitive",
+        ),
+      ).toBe(
+        "[pi-permission-system] User denied access to path '/etc/passwd'. Reason: sensitive.",
+      );
+    });
+  });
+
+  describe("external_directory context", () => {
+    test("without reason", () => {
+      expect(
+        formatUserDeniedReason({
+          kind: "external_directory",
+          toolName: "edit",
+          pathValue: "/etc/hosts",
+          cwd: "/project",
+        }),
+      ).toBe(
+        "[pi-permission-system] User denied external directory access for tool 'edit' path '/etc/hosts'.",
+      );
+    });
+
+    test("with reason", () => {
+      expect(
+        formatUserDeniedReason(
+          {
+            kind: "external_directory",
+            toolName: "edit",
+            pathValue: "/etc/hosts",
+            cwd: "/project",
+          },
+          "too risky",
+        ),
+      ).toBe(
+        "[pi-permission-system] User denied external directory access for tool 'edit' path '/etc/hosts'. Reason: too risky.",
+      );
+    });
+  });
+
+  describe("bash_external_directory context", () => {
+    test("without reason", () => {
+      expect(
+        formatUserDeniedReason({
+          kind: "bash_external_directory",
+          command: "rm /etc/hosts",
+          externalPaths: ["/etc/hosts"],
+          cwd: "/project",
+        }),
+      ).toBe(
+        "[pi-permission-system] User denied external directory access for bash command 'rm /etc/hosts'.",
+      );
+    });
+
+    test("with reason", () => {
+      expect(
+        formatUserDeniedReason(
+          {
+            kind: "bash_external_directory",
+            command: "rm /etc/hosts",
+            externalPaths: ["/etc/hosts"],
+            cwd: "/project",
+          },
+          "dangerous",
+        ),
+      ).toBe(
+        "[pi-permission-system] User denied external directory access for bash command 'rm /etc/hosts'. Reason: dangerous.",
+      );
+    });
+  });
+
+  describe("bash_path context", () => {
+    test("without reason", () => {
+      expect(
+        formatUserDeniedReason({
+          kind: "bash_path",
+          command: "cat /etc/passwd",
+          pathValue: "/etc/passwd",
+        }),
+      ).toBe(
+        "[pi-permission-system] User denied path access for bash command 'cat /etc/passwd' (path '/etc/passwd').",
+      );
+    });
+
+    test("with reason", () => {
+      expect(
+        formatUserDeniedReason(
+          {
+            kind: "bash_path",
+            command: "cat /etc/passwd",
+            pathValue: "/etc/passwd",
+          },
+          "sensitive",
+        ),
+      ).toBe(
+        "[pi-permission-system] User denied path access for bash command 'cat /etc/passwd' (path '/etc/passwd'). Reason: sensitive.",
+      );
+    });
+  });
+
+  describe("skill_read context", () => {
+    test("without reason", () => {
+      expect(
+        formatUserDeniedReason({
+          kind: "skill_read",
+          skillName: "librarian",
+          readPath: "/skills/librarian/SKILL.md",
+        }),
+      ).toBe("[pi-permission-system] User denied access to skill 'librarian'.");
+    });
+
+    test("with reason", () => {
+      expect(
+        formatUserDeniedReason(
+          {
+            kind: "skill_read",
+            skillName: "librarian",
+            readPath: "/skills/librarian/SKILL.md",
+          },
+          "not needed",
+        ),
+      ).toBe(
+        "[pi-permission-system] User denied access to skill 'librarian'. Reason: not needed.",
+      );
+    });
+  });
+});

package/tests/handlers/external-directory-integration.test.ts

@@ -11,12 +11,8 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { describe, expect, it, vi } from "vitest";
 
-import {
-  formatExternalDirectoryAskPrompt,
-  formatExternalDirectoryDenyReason,
-  formatExternalDirectoryHardStopHint,
-  formatExternalDirectoryUserDeniedReason,
-} from "../../src/handlers/gates/external-directory-messages";
+import { EXTENSION_TAG } from "../../src/denial-messages";
+import { formatExternalDirectoryAskPrompt } from "../../src/handlers/gates/external-directory-messages";
 import { PermissionGateHandler } from "../../src/handlers/permission-gate-handler";
 import {
   PERMISSIONS_DECISION_CHANNEL,
@@ -177,11 +173,6 @@ function getDecisionEvents(
 // ── Regression guard: helper presence ──────────────────────────────────────
 
 describe("external_directory helper regression guard", () => {
-  it("formatExternalDirectoryHardStopHint is a callable function", () => {
-    expect(typeof formatExternalDirectoryHardStopHint).toBe("function");
-    expect(formatExternalDirectoryHardStopHint()).toContain("Hard stop");
-  });
-
   it("formatExternalDirectoryAskPrompt is a callable function", () => {
     expect(typeof formatExternalDirectoryAskPrompt).toBe("function");
     expect(
@@ -189,19 +180,13 @@ describe("external_directory helper regression guard", () => {
     ).toContain("/outside/file");
   });
 
-  it("formatExternalDirectoryDenyReason is a callable function", () => {
-    expect(typeof formatExternalDirectoryDenyReason).toBe("function");
-    expect(
-      formatExternalDirectoryDenyReason("read", "/outside/file", "/project"),
-    ).toContain("Hard stop");
+  it("EXTENSION_TAG is the expected value", () => {
+    expect(EXTENSION_TAG).toBe("[pi-permission-system]");
   });
 
-  it("formatExternalDirectoryUserDeniedReason is a callable function", () => {
-    expect(typeof formatExternalDirectoryUserDeniedReason).toBe("function");
-    expect(
-      formatExternalDirectoryUserDeniedReason("read", "/outside/file"),
-    ).toContain("User denied");
-  });
+  // formatExternalDirectoryDenyReason, formatExternalDirectoryUserDeniedReason,
+  // and formatExternalDirectoryHardStopHint have moved to denial-messages.ts.
+  // Their behavior is tested in denial-messages.test.ts.
 });
 
 // ── Path scope: gate applicability ────────────────────────────────────────
@@ -386,13 +371,14 @@ describe("external_directory policy state — deny", () => {
     expect(result.reason).toContain(EXTERNAL_PATH);
   });
 
-  it("block reason contains the hard-stop hint", async () => {
+  it("block reason contains extension attribution", async () => {
     const { handler } = makeHandler({
       session: { checkPermission: makeCheckPermission("deny") },
     });
     const event = makeToolCallEvent("read", { path: EXTERNAL_PATH });
     const result = await handler.handleToolCall(event, makeCtx());
-    expect(result.reason).toContain("Hard stop");
+    expect(result.reason).toContain("[pi-permission-system]");
+    expect(result.reason).not.toContain("Hard stop");
   });
 
   it("writes review-log entry with resolution policy_denied", async () => {

package/tests/handlers/gates/bash-external-directory.test.ts

@@ -142,15 +142,18 @@ describe("describeBashExternalDirectoryGate", () => {
     expect(desc.decision.surface).toBe("external_directory");
   });
 
-  it("messages contain the command", async () => {
+  it("denialContext contains the command and external paths", async () => {
     const result = await describeBashExternalDirectoryGate(
       makeTcc({ input: { command: "cat /outside/file.ts" } }),
       vi.fn().mockReturnValue(makeCheckResult("ask")),
       vi.fn().mockReturnValue([]),
     );
     const desc = result as GateDescriptor;
-    expect(desc.messages.denyReason).toContain("cat /outside/file.ts");
-    expect(desc.messages.unavailableReason).toContain("cat /outside/file.ts");
+    expect(desc.denialContext).toMatchObject({
+      kind: "bash_external_directory",
+      command: "cat /outside/file.ts",
+      cwd: "/test/project",
+    });
   });
 
   it("promptDetails includes command and tool_call source", async () => {

package/tests/handlers/gates/bash-path.test.ts

@@ -144,7 +144,11 @@ describe("describeBashPathGate", () => {
       checkPermission,
       getSessionRuleset,
     )) as GateDescriptor;
-    expect(result.messages.denyReason).toContain(".env");
+    expect(result.denialContext).toMatchObject({
+      kind: "bash_path",
+      command: "cat .env",
+      pathValue: ".env",
+    });
     expect(result.promptDetails.message).toContain(".env");
   });