@gotgenes/pi-permission-system 6.0.1 → 7.0.0

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

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

@@ -2,20 +2,13 @@ import { describe, expect, test } from "vitest";
 
 import {
   formatBashExternalDirectoryAskPrompt,
-  formatBashExternalDirectoryDenyReason,
   formatExternalDirectoryAskPrompt,
-  formatExternalDirectoryDenyReason,
-  formatExternalDirectoryHardStopHint,
-  formatExternalDirectoryUserDeniedReason,
 } from "../../../src/handlers/gates/external-directory-messages";
 
-describe("formatExternalDirectoryHardStopHint", () => {
-  test("returns the hard stop instruction string", () => {
-    const hint = formatExternalDirectoryHardStopHint();
-    expect(hint).toContain("Hard stop");
-    expect(hint).toContain("external directory");
-  });
-});
+// Denial message functions (formatExternalDirectoryDenyReason,
+// formatExternalDirectoryUserDeniedReason, formatExternalDirectoryHardStopHint,
+// formatBashExternalDirectoryDenyReason) have moved to denial-messages.ts.
+// Their behavior is tested in denial-messages.test.ts.
 
 describe("formatExternalDirectoryAskPrompt", () => {
   test("uses 'Current agent' when no agent name provided", () => {
@@ -43,60 +36,6 @@ describe("formatExternalDirectoryAskPrompt", () => {
   });
 });
 
-describe("formatExternalDirectoryDenyReason", () => {
-  test("includes tool name, path, cwd, agent name, and hard stop hint", () => {
-    const result = formatExternalDirectoryDenyReason(
-      "read",
-      "/etc/passwd",
-      "/projects/my-app",
-      "sec-agent",
-    );
-    expect(result).toContain("Agent 'sec-agent'");
-    expect(result).toContain("read");
-    expect(result).toContain("/etc/passwd");
-    expect(result).toContain("/projects/my-app");
-    expect(result).toContain("Hard stop");
-  });
-
-  test("uses 'Current agent' without agent name", () => {
-    const result = formatExternalDirectoryDenyReason(
-      "read",
-      "/etc",
-      "/projects",
-    );
-    expect(result).toContain("Current agent");
-  });
-});
-
-describe("formatExternalDirectoryUserDeniedReason", () => {
-  test("includes tool name and path", () => {
-    const result = formatExternalDirectoryUserDeniedReason(
-      "edit",
-      "/etc/hosts",
-    );
-    expect(result).toContain("edit");
-    expect(result).toContain("/etc/hosts");
-    expect(result).toContain("Hard stop");
-  });
-
-  test("appends denial reason when provided", () => {
-    const result = formatExternalDirectoryUserDeniedReason(
-      "edit",
-      "/etc/hosts",
-      "too risky",
-    );
-    expect(result).toContain("Reason: too risky");
-  });
-
-  test("omits reason suffix when not provided", () => {
-    const result = formatExternalDirectoryUserDeniedReason(
-      "edit",
-      "/etc/hosts",
-    );
-    expect(result).not.toContain("Reason:");
-  });
-});
-
 describe("formatBashExternalDirectoryAskPrompt", () => {
   test("includes command, paths, cwd, and agent name", () => {
     const result = formatBashExternalDirectoryAskPrompt(
@@ -120,18 +59,3 @@ describe("formatBashExternalDirectoryAskPrompt", () => {
     expect(result).toContain("Current agent");
   });
 });
-
-describe("formatBashExternalDirectoryDenyReason", () => {
-  test("includes command, paths, cwd, agent name, and hard stop hint", () => {
-    const result = formatBashExternalDirectoryDenyReason(
-      "rm /etc/hosts",
-      ["/etc/hosts"],
-      "/projects/my-app",
-      "sec-agent",
-    );
-    expect(result).toContain("Agent 'sec-agent'");
-    expect(result).toContain("rm /etc/hosts");
-    expect(result).toContain("/etc/hosts");
-    expect(result).toContain("Hard stop");
-  });
-});

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

@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
 
 import type {
   GateBypass,
@@ -136,15 +136,17 @@ describe("describeExternalDirectoryGate", () => {
     expect(result.sessionApproval).toHaveProperty("pattern");
   });
 
-  it("messages contain the external path", () => {
+  it("denialContext contains the external path and cwd", () => {
     const result = describeExternalDirectoryGate(
       makeTcc({ input: { path: "/outside/project/file.ts" } }),
       ["/test/agent"],
     ) as GateDescriptor;
-    expect(result.messages.denyReason).toContain("/outside/project/file.ts");
-    expect(result.messages.unavailableReason).toContain(
-      "/outside/project/file.ts",
-    );
+    expect(result.denialContext).toMatchObject({
+      kind: "external_directory",
+      toolName: "read",
+      pathValue: "/outside/project/file.ts",
+      cwd: "/test/project",
+    });
   });
 
   it("promptDetails includes path and tool_call source", () => {

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

@@ -164,7 +164,7 @@ describe("describePathGate", () => {
     expect(result.sessionApproval).toHaveProperty("pattern");
   });
 
-  it("descriptor messages reference the file path", () => {
+  it("descriptor denialContext references the file path and tool name", () => {
     const checkPermission = vi
       .fn<CheckPermissionFn>()
       .mockReturnValue(
@@ -175,8 +175,12 @@ describe("describePathGate", () => {
       checkPermission,
       getSessionRuleset,
     ) as GateDescriptor;
-    expect(result.messages.denyReason).toContain(".env");
-    expect(result.messages.unavailableReason).toContain(".env");
+    expect(result.denialContext).toEqual({
+      kind: "path",
+      toolName: "read",
+      pathValue: ".env",
+      agentName: undefined,
+    });
   });
 
   it("descriptor decision uses surface 'path' and the file path as value", () => {

package/tests/handlers/gates/runner.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 
+import type { DenialContext } from "../../../src/denial-messages";
+import { EXTENSION_TAG } from "../../../src/denial-messages";
 import type {
   GateDescriptor,
   GateRunnerDeps,
@@ -15,10 +17,9 @@ function makeDescriptor(
   return {
     surface: "read",
     input: {},
-    messages: {
-      denyReason: "Tool 'read' is denied.",
-      unavailableReason: "No UI available.",
-      userDeniedReason: (d) => `User denied. ${d.denialReason ?? ""}`,
+    denialContext: {
+      kind: "tool",
+      check: makeCheckResult("deny"),
     },
     promptDetails: {
       source: "tool_call",
@@ -358,4 +359,104 @@ describe("runGateCheck", () => {
     await runGateCheck(makeDescriptor(), null, "tc-1", deps);
     expect(deps.approveSessionRule).not.toHaveBeenCalled();
   });
+
+  describe("denialContext formatting", () => {
+    function makeDenialContextDescriptor(
+      denialContext: DenialContext,
+      overrides: Partial<GateDescriptor> = {},
+    ): GateDescriptor {
+      return {
+        surface: "write",
+        input: {},
+        denialContext,
+        promptDetails: {
+          source: "tool_call",
+          agentName: null,
+          message: "Allow tool 'write'?",
+          toolCallId: "tc-1",
+          toolName: "write",
+        },
+        logContext: {
+          source: "tool_call",
+          toolCallId: "tc-1",
+          toolName: "write",
+        },
+        decision: {
+          surface: "write",
+          value: "write",
+        },
+        ...overrides,
+      };
+    }
+
+    it("uses denialContext to format denyReason with extension tag", async () => {
+      const deps = makeRunnerDeps({
+        checkPermission: vi.fn().mockReturnValue(makeCheckResult("deny")),
+      });
+      const ctx: DenialContext = {
+        kind: "tool",
+        check: makeCheckResult("deny"),
+        agentName: "test-agent",
+      };
+      const result = await runGateCheck(
+        makeDenialContextDescriptor(ctx),
+        "test-agent",
+        "tc-1",
+        deps,
+      );
+      expect(result.action).toBe("block");
+      if (result.action === "block") {
+        expect(result.reason).toContain(EXTENSION_TAG);
+        expect(result.reason).not.toContain("Hard stop");
+      }
+    });
+
+    it("uses denialContext to format unavailableReason with extension tag", async () => {
+      const deps = makeRunnerDeps({
+        checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+        canConfirm: vi.fn().mockReturnValue(false),
+      });
+      const ctx: DenialContext = {
+        kind: "tool",
+        check: makeCheckResult("ask"),
+      };
+      const result = await runGateCheck(
+        makeDenialContextDescriptor(ctx),
+        null,
+        "tc-1",
+        deps,
+      );
+      expect(result.action).toBe("block");
+      if (result.action === "block") {
+        expect(result.reason).toContain(EXTENSION_TAG);
+        expect(result.reason).toContain("no interactive UI");
+      }
+    });
+
+    it("uses denialContext to format userDeniedReason with extension tag", async () => {
+      const deps = makeRunnerDeps({
+        checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+        promptPermission: vi.fn().mockResolvedValue({
+          approved: false,
+          state: "denied",
+          denialReason: "too risky",
+        }),
+      });
+      const ctx: DenialContext = {
+        kind: "tool",
+        check: makeCheckResult("ask"),
+      };
+      const result = await runGateCheck(
+        makeDenialContextDescriptor(ctx),
+        null,
+        "tc-1",
+        deps,
+      );
+      expect(result.action).toBe("block");
+      if (result.action === "block") {
+        expect(result.reason).toContain(EXTENSION_TAG);
+        expect(result.reason).toContain("too risky");
+      }
+    });
+  });
 });

package/tests/handlers/gates/skill-read.test.ts

@@ -104,17 +104,16 @@ describe("describeSkillReadGate", () => {
     expect(result.decision.value).toBe("my-skill");
   });
 
-  it("messages contain the skill name", () => {
+  it("denialContext contains the skill name and read path", () => {
     const result = describeSkillReadGate(makeTcc(), () => [
       makeSkillEntry({ name: "librarian" }),
     ]) as GateDescriptor;
-    expect(result.messages.denyReason).toContain("librarian");
-    expect(result.messages.unavailableReason).toContain("librarian");
-    const deniedMsg = result.messages.userDeniedReason({
-      approved: false,
-      state: "denied",
+    expect(result.denialContext).toEqual({
+      kind: "skill_read",
+      skillName: "librarian",
+      readPath: "/skills/librarian/SKILL.md",
+      agentName: undefined,
     });
-    expect(deniedMsg).toContain("librarian");
   });
 
   it("promptDetails includes skill_read source and skillName", () => {

package/tests/handlers/gates/tool.test.ts

@@ -1,6 +1,5 @@
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
 
-import type { GateDescriptor } from "../../../src/handlers/gates/descriptor";
 import { describeToolGate } from "../../../src/handlers/gates/tool";
 import type { ToolCallContext } from "../../../src/handlers/gates/types";
 import type { PermissionCheckResult } from "../../../src/types";
@@ -80,50 +79,33 @@ describe("describeToolGate", () => {
     expect(desc.decision.value).toBe("server:tool");
   });
 
-  it("populates messages.denyReason via formatDenyReason", () => {
+  it("populates denialContext with kind 'tool' and check result", () => {
     const check = makeCheckResult("deny", { toolName: "read" });
     const desc = describeToolGate(makeTcc(), check);
-    expect(desc.messages.denyReason).toContain("read");
-    expect(desc.messages.denyReason).toContain("not permitted");
+    expect(desc.denialContext).toEqual({
+      kind: "tool",
+      check,
+      agentName: undefined,
+      input: {},
+    });
   });
 
-  it("populates messages.unavailableReason with bash command when tool is bash", () => {
-    const check = makeCheckResult("ask", {
-      toolName: "bash",
-      command: "rm -rf /",
-    });
-    const desc = describeToolGate(
-      makeTcc({ toolName: "bash", input: { command: "rm -rf /" } }),
-      check,
-    );
-    expect(desc.messages.unavailableReason).toContain("rm -rf /");
-    expect(desc.messages.unavailableReason).toContain("no interactive UI");
+  it("populates denialContext with agent name when provided", () => {
+    const check = makeCheckResult("ask", { toolName: "read" });
+    const desc = describeToolGate(makeTcc({ agentName: "my-agent" }), check);
+    expect(desc.denialContext!.agentName).toBe("my-agent");
   });
 
-  it("populates messages.unavailableReason with tool name for non-bash tools", () => {
+  it("populates denialContext with input for tool context", () => {
+    const check = makeCheckResult("ask", { toolName: "bash", command: "ls" });
     const desc = describeToolGate(
-      makeTcc({ toolName: "write" }),
-      makeCheckResult("ask"),
+      makeTcc({ toolName: "bash", input: { command: "ls" } }),
+      check,
     );
-    expect(desc.messages.unavailableReason).toContain("write");
-    expect(desc.messages.unavailableReason).toContain("no interactive UI");
-  });
-
-  it("populates messages.unavailableReason with mcp for mcp tool", () => {
-    const check = makeCheckResult("ask", { toolName: "mcp", target: "s:t" });
-    const desc = describeToolGate(makeTcc({ toolName: "mcp" }), check);
-    expect(desc.messages.unavailableReason).toContain("mcp");
-  });
-
-  it("populates messages.userDeniedReason as a function", () => {
-    const check = makeCheckResult("ask", { toolName: "read" });
-    const desc = describeToolGate(makeTcc(), check);
-    const reason = desc.messages.userDeniedReason({
-      approved: false,
-      state: "denied",
-      denialReason: "too risky",
+    expect(desc.denialContext).toMatchObject({
+      kind: "tool",
+      input: { command: "ls" },
     });
-    expect(reason).toContain("too risky");
   });
 
   it("populates sessionApproval via suggestSessionPattern", () => {

package/tests/permission-prompts.test.ts

@@ -7,14 +7,10 @@ vi.mock("../src/tool-input-preview.js", () => ({
 
 import {
   formatAskPrompt,
-  formatDenyReason,
   formatMissingToolNameReason,
-  formatPermissionHardStopHint,
   formatSkillAskPrompt,
   formatSkillPathAskPrompt,
-  formatSkillPathDenyReason,
   formatUnknownToolReason,
-  formatUserDeniedReason,
 } from "../src/permission-prompts";
 import type { SkillPromptEntry } from "../src/skill-prompt-sanitizer";
 import { formatToolInputForPrompt } from "../src/tool-input-preview";
@@ -106,89 +102,6 @@ describe("formatUnknownToolReason", () => {
   });
 });
 
-describe("formatPermissionHardStopHint", () => {
-  test("returns MCP-specific message for mcp tool with target", () => {
-    const result = formatPermissionHardStopHint(mcpResult("server:tool"));
-    expect(result).toContain("MCP permission denial");
-  });
-
-  test("returns MCP-specific message for mcp source with target", () => {
-    const result = formatPermissionHardStopHint(
-      toolResult("anything", { source: "mcp", target: "server:tool" }),
-    );
-    expect(result).toContain("MCP permission denial");
-  });
-
-  test("returns generic message for non-MCP tools", () => {
-    const result = formatPermissionHardStopHint(toolResult("read"));
-    expect(result).toContain("Hard stop");
-    expect(result).not.toContain("MCP");
-  });
-});
-
-describe("formatDenyReason", () => {
-  test("includes tool name and hard stop hint", () => {
-    const result = formatDenyReason(toolResult("read"));
-    expect(result).toContain("read");
-    expect(result).toContain("Hard stop");
-  });
-
-  test("includes agent name when provided", () => {
-    const result = formatDenyReason(toolResult("write"), "my-agent");
-    expect(result).toContain("Agent 'my-agent'");
-  });
-
-  test("includes MCP target for mcp results", () => {
-    const result = formatDenyReason(mcpResult("server:do-thing"));
-    expect(result).toContain("server:do-thing");
-    expect(result).toContain("MCP");
-  });
-
-  test("includes bash command when present", () => {
-    const result = formatDenyReason(
-      toolResult("bash", { command: "rm -rf /" }),
-    );
-    expect(result).toContain("rm -rf /");
-  });
-
-  test("includes matched pattern when present", () => {
-    const result = formatDenyReason(
-      toolResult("bash", { command: "rm -rf /", matchedPattern: "rm *" }),
-    );
-    expect(result).toContain("matched 'rm *'");
-  });
-});
-
-describe("formatUserDeniedReason", () => {
-  test("mentions tool name for generic tools", () => {
-    const result = formatUserDeniedReason(toolResult("read"));
-    expect(result).toContain("read");
-    expect(result).toContain("Hard stop");
-  });
-
-  test("mentions bash command for bash results", () => {
-    const result = formatUserDeniedReason(
-      toolResult("bash", { command: "ls -la" }),
-    );
-    expect(result).toContain("ls -la");
-  });
-
-  test("mentions MCP target for mcp results", () => {
-    const result = formatUserDeniedReason(mcpResult("server:query"));
-    expect(result).toContain("server:query");
-  });
-
-  test("appends denial reason when provided", () => {
-    const result = formatUserDeniedReason(toolResult("read"), "too sensitive");
-    expect(result).toContain("Reason: too sensitive");
-  });
-
-  test("omits reason suffix when not provided", () => {
-    const result = formatUserDeniedReason(toolResult("read"));
-    expect(result).not.toContain("Reason:");
-  });
-});
-
 describe("formatAskPrompt", () => {
   test("uses 'Current agent' when no agent name given", () => {
     const result = formatAskPrompt(toolResult("read"), undefined, {
@@ -289,23 +202,5 @@ describe("formatSkillPathAskPrompt", () => {
   });
 });
 
-describe("formatSkillPathDenyReason", () => {
-  test("includes skill name, read path, and agent name", () => {
-    const result = formatSkillPathDenyReason(
-      skillEntry("librarian"),
-      "/skills/librarian/SKILL.md",
-      "my-agent",
-    );
-    expect(result).toContain("librarian");
-    expect(result).toContain("/skills/librarian/SKILL.md");
-    expect(result).toContain("Agent 'my-agent'");
-  });
-
-  test("uses 'Current agent' without agent name", () => {
-    const result = formatSkillPathDenyReason(
-      skillEntry("librarian"),
-      "/skills/librarian/SKILL.md",
-    );
-    expect(result).toContain("Current agent");
-  });
-});
+// formatSkillPathDenyReason has moved to denial-messages.ts.
+// Its behavior is tested in denial-messages.test.ts.

package/tests/permission-system.test.ts

@@ -1874,10 +1874,11 @@ test("tool_call blocks path-bearing tools outside cwd when external_directory is
     });
 
     expect(result.block).toBe(true);
-    expect(String(result.reason)).toMatch(
-      /external directory permission denial/i,
-    );
-    expect(String(result.reason)).toMatch(/repo-sibling/);
+    const reason = String(result.reason);
+    expect(reason).toContain("is not permitted to run tool 'read'");
+    expect(reason).toContain("repo-sibling");
+    expect(reason).toContain("[pi-permission-system]");
+    expect(reason).not.toContain("Hard stop");
   } finally {
     await harness.cleanup();
     rmSync(rootDir, { recursive: true, force: true });
@@ -2003,10 +2004,13 @@ test("tool_call blocks bash command with external path when external_directory i
     });
 
     expect(result.block).toBe(true);
-    expect(String(result.reason)).toMatch(
-      /external directory permission denial/i,
+    const reason = String(result.reason);
+    expect(reason).toContain(
+      "is not permitted to run bash command 'cat /etc/hosts'",
     );
-    expect(String(result.reason)).toMatch(/\/etc\/hosts/);
+    expect(reason).toContain("/etc/hosts");
+    expect(reason).toContain("[pi-permission-system]");
+    expect(reason).not.toContain("Hard stop");
   } finally {
     await harness.cleanup();
   }