@gotgenes/pi-permission-system 6.0.1 → 7.0.0

package/src/permission-prompts.ts

@@ -2,6 +2,10 @@ import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
 import { formatToolInputForPrompt } from "./tool-input-preview";
 import type { PermissionCheckResult } from "./types";
 
+// NOTE: formatDenyReason, formatUserDeniedReason, and
+// formatPermissionHardStopHint have been moved to denial-messages.ts.
+// This module retains only pre-check messages and user-facing ask prompts.
+
 export function formatMissingToolNameReason(): string {
   return "Tool call was blocked because no tool name was provided. Use a registered tool name from pi.getAllTools().";
 }
@@ -23,58 +27,6 @@ export function formatUnknownToolReason(
   return `Tool '${toolName}' is not registered in this runtime and was blocked before permission checks.${mcpHint} Registered tools: ${availableList}.`;
 }
 
-export function formatPermissionHardStopHint(
-  result: PermissionCheckResult,
-): string {
-  if ((result.source === "mcp" || result.toolName === "mcp") && result.target) {
-    return "Hard stop: this MCP permission denial is policy-enforced. Do not retry this target, do not run discovery/investigation to bypass it, and report the block to the user.";
-  }
-
-  return "Hard stop: this permission denial is policy-enforced. Do not retry or investigate bypasses; report the block to the user.";
-}
-
-export function formatDenyReason(
-  result: PermissionCheckResult,
-  agentName?: string,
-): string {
-  const parts: string[] = [];
-
-  if (agentName) {
-    parts.push(`Agent '${agentName}'`);
-  }
-
-  if ((result.source === "mcp" || result.toolName === "mcp") && result.target) {
-    parts.push(`is not permitted to run MCP target '${result.target}'`);
-  } else {
-    parts.push(`is not permitted to run '${result.toolName}'`);
-  }
-
-  if (result.command) {
-    parts.push(`command '${result.command}'`);
-  }
-
-  if (result.matchedPattern) {
-    parts.push(`(matched '${result.matchedPattern}')`);
-  }
-
-  return `${parts.join(" ")}. ${formatPermissionHardStopHint(result)}`;
-}
-
-export function formatUserDeniedReason(
-  result: PermissionCheckResult,
-  denialReason?: string,
-): string {
-  const base =
-    (result.source === "mcp" || result.toolName === "mcp") && result.target
-      ? `User denied MCP target '${result.target}'.`
-      : result.toolName === "bash" && result.command
-        ? `User denied bash command '${result.command}'.`
-        : `User denied tool '${result.toolName}'.`;
-  const reasonSuffix = denialReason ? ` Reason: ${denialReason}.` : "";
-
-  return `${base}${reasonSuffix} ${formatPermissionHardStopHint(result)}`;
-}
-
 export function formatAskPrompt(
   result: PermissionCheckResult,
   agentName?: string,
@@ -121,11 +73,4 @@ export function formatSkillPathAskPrompt(
   return `${subject} requested access to skill '${skill.name}' via '${readPath}'. Allow this read?`;
 }
 
-export function formatSkillPathDenyReason(
-  skill: SkillPromptEntry,
-  readPath: string,
-  agentName?: string,
-): string {
-  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-  return `${subject} is not permitted to access skill '${skill.name}' via '${readPath}'.`;
-}
+// formatSkillPathDenyReason has been moved to denial-messages.ts.

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.",
+      );
+    });
+  });
+});