@gotgenes/pi-permission-system 15.0.1 → 16.0.0

package/test/decision-audit.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { DecisionAudit } from "#src/decision-audit";
+
+function makeAuditLogger() {
+  return {
+    debug: vi.fn<(event: string, details?: Record<string, unknown>) => void>(),
+    warn: vi.fn<(message: string) => void>(),
+  };
+}
+
+describe("DecisionAudit", () => {
+  it("counts allowed, blocked, and error decisions in the summary", () => {
+    const audit = new DecisionAudit();
+    audit.recordDecision("allow");
+    audit.recordDecision("allow");
+    audit.recordDecision("block");
+    audit.recordError();
+
+    const logger = makeAuditLogger();
+    audit.writeSummary(logger);
+
+    expect(logger.debug).toHaveBeenCalledWith("permission.session_summary", {
+      toolCalls: 4,
+      allowed: 2,
+      blocked: 1,
+      errors: 1,
+    });
+  });
+
+  it("emits a zeroed summary when no calls were recorded", () => {
+    const audit = new DecisionAudit();
+    const logger = makeAuditLogger();
+
+    audit.writeSummary(logger);
+
+    expect(logger.debug).toHaveBeenCalledWith("permission.session_summary", {
+      toolCalls: 0,
+      allowed: 0,
+      blocked: 0,
+      errors: 0,
+    });
+  });
+
+  it("does not warn when the counts are consistent", () => {
+    const audit = new DecisionAudit();
+    audit.recordDecision("allow");
+    audit.recordError();
+
+    const logger = makeAuditLogger();
+    audit.writeSummary(logger);
+
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it("warns when the per-call invariant is violated", () => {
+    const audit = new DecisionAudit();
+    audit.recordDecision("allow");
+    // Force a re-opened silent path: bump the private total without a matching
+    // sub-total, simulating a future regression that resolves a call without
+    // recording its terminal decision.
+    (audit as unknown as { toolCalls: number }).toolCalls++;
+
+    const logger = makeAuditLogger();
+    audit.writeSummary(logger);
+
+    expect(logger.warn).toHaveBeenCalledTimes(1);
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining("invariant violated"),
+    );
+  });
+});

package/test/detect-permissive-bash-fallback.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+
+import { detectPermissiveBashFallback } from "#src/config-loader";
+import type { FlatPermissionConfig } from "#src/types";
+
+describe("detectPermissiveBashFallback", () => {
+  it("warns when top-level '*' is allow and bash is absent", () => {
+    const permission: FlatPermissionConfig = { "*": "allow" };
+
+    const issue = detectPermissiveBashFallback(permission);
+
+    expect(issue).toBeDefined();
+    expect(issue).toContain("bash");
+    expect(issue).toContain("allow");
+  });
+
+  it("warns when top-level '*' is allow and bash map has no '*' key", () => {
+    const permission: FlatPermissionConfig = {
+      "*": "allow",
+      bash: { "git *": "ask" },
+    };
+
+    expect(detectPermissiveBashFallback(permission)).toBeDefined();
+  });
+
+  it("does not warn when bash is a bare string surface", () => {
+    const permission: FlatPermissionConfig = { "*": "allow", bash: "ask" };
+
+    expect(detectPermissiveBashFallback(permission)).toBeUndefined();
+  });
+
+  it("does not warn when bash map has an explicit '*' key", () => {
+    const permission: FlatPermissionConfig = {
+      "*": "allow",
+      bash: { "*": "ask", "git *": "allow" },
+    };
+
+    expect(detectPermissiveBashFallback(permission)).toBeUndefined();
+  });
+
+  it("does not warn when top-level '*' is not allow", () => {
+    const permission: FlatPermissionConfig = { "*": "ask" };
+
+    expect(detectPermissiveBashFallback(permission)).toBeUndefined();
+  });
+
+  it("does not warn when top-level '*' is absent", () => {
+    const permission: FlatPermissionConfig = { bash: { "git *": "ask" } };
+
+    expect(detectPermissiveBashFallback(permission)).toBeUndefined();
+  });
+
+  it("does not warn when permission is undefined", () => {
+    expect(detectPermissiveBashFallback(undefined)).toBeUndefined();
+  });
+});

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

@@ -100,7 +100,7 @@ describe("external_directory path scope", () => {
     const result = await handler.handleToolCall(event, makeCtx());
     // Should not be blocked — the external_directory gate is skipped,
     // and the tool gate sees "allow" (default toolState in makeExtDirCheck)
-    expect(result).toEqual({});
+    expect(result).toEqual({ action: "allow" });
   });
 
   it("fires external_directory check when path is outside CWD", async () => {
@@ -110,7 +110,7 @@ describe("external_directory path scope", () => {
     });
     const event = makeToolCallEvent("read", { input: { path: EXTERNAL_PATH } });
     const result = await handler.handleToolCall(event, makeCtx());
-    expect(result).toMatchObject({ block: true });
+    expect(result).toMatchObject({ action: "block" });
   });
 
   it("skips external_directory check for non-path-bearing tool (bash)", async () => {
@@ -142,7 +142,7 @@ describe("external_directory path scope", () => {
       input: { path: EXTERNAL_PATH },
     });
     const result = await handler.handleToolCall(event, makeCtx());
-    expect(result).toMatchObject({ block: true });
+    expect(result).toMatchObject({ action: "block" });
   });
 
   it.each(
@@ -155,7 +155,7 @@ describe("external_directory path scope", () => {
     // No path in input — external_directory gate should not fire
     const event = makeToolCallEvent(toolName);
     const result = await handler.handleToolCall(event, makeCtx());
-    expect(result).toEqual({});
+    expect(result).toEqual({ action: "allow" });
   });
 });
 
@@ -169,7 +169,7 @@ describe("external_directory policy state — allow", () => {
     });
     const event = makeToolCallEvent("read", { input: { path: EXTERNAL_PATH } });
     const result = await handler.handleToolCall(event, makeCtx());
-    expect(result).toEqual({});
+    expect(result).toEqual({ action: "allow" });
   });
 
   it("emits decision event with policy_allow on external_directory surface", async () => {
@@ -214,7 +214,7 @@ describe("external_directory — allow external reads, gate external writes (#14
     });
     const event = makeToolCallEvent("read", { input: { path: EXTERNAL_PATH } });
     const result = await handler.handleToolCall(event, makeCtx());
-    expect(result).toEqual({});
+    expect(result).toEqual({ action: "allow" });
   });
 
   it("prompts for write to external path when external_directory allows but write is ask", async () => {
@@ -233,7 +233,7 @@ describe("external_directory — allow external reads, gate external writes (#14
     });
     const result = await handler.handleToolCall(event, makeCtx());
     // external_directory passes; write gate prompts and user approves
-    expect(result).toEqual({});
+    expect(result).toEqual({ action: "allow" });
     expect(prompter.prompt).toHaveBeenCalledOnce();
   });
 
@@ -246,7 +246,7 @@ describe("external_directory — allow external reads, gate external writes (#14
       input: { path: EXTERNAL_PATH },
     });
     const result = await handler.handleToolCall(event, makeCtx());
-    expect(result.block).toBe(true);
+    expect(result).toMatchObject({ action: "block" });
   });
 
   it("emits separate decision events for external_directory and write surfaces", async () => {
@@ -284,8 +284,8 @@ describe("external_directory policy state — deny", () => {
     });
     const event = makeToolCallEvent("read", { input: { path: EXTERNAL_PATH } });
     const result = await handler.handleToolCall(event, makeCtx());
-    expect(result.block).toBe(true);
-    expect(result.reason).toContain(EXTERNAL_PATH);
+    expect(result).toMatchObject({ action: "block" });
+    expect((result as { reason?: string }).reason).toContain(EXTERNAL_PATH);
   });
 
   it("block reason contains extension attribution", async () => {
@@ -295,8 +295,10 @@ describe("external_directory policy state — deny", () => {
     });
     const event = makeToolCallEvent("read", { input: { path: EXTERNAL_PATH } });
     const result = await handler.handleToolCall(event, makeCtx());
-    expect(result.reason).toContain("[pi-permission-system]");
-    expect(result.reason).not.toContain("Hard stop");
+    expect((result as { reason?: string }).reason).toContain(
+      "[pi-permission-system]",
+    );
+    expect((result as { reason?: string }).reason).not.toContain("Hard stop");
   });
 
   it("writes review-log entry with resolution policy_denied", async () => {
@@ -351,7 +353,7 @@ describe("external_directory policy state — ask", () => {
     });
     const event = makeToolCallEvent("read", { input: { path: EXTERNAL_PATH } });
     const result = await handler.handleToolCall(event, makeCtx());
-    expect(result).toEqual({});
+    expect(result).toEqual({ action: "allow" });
   });
 
   it("emits user_approved decision when user approves", async () => {
@@ -391,7 +393,7 @@ describe("external_directory policy state — ask", () => {
     });
     const event = makeToolCallEvent("read", { input: { path: EXTERNAL_PATH } });
     const result = await handler.handleToolCall(event, makeCtx());
-    expect(result.block).toBe(true);
+    expect(result).toMatchObject({ action: "block" });
   });
 
   it("emits user_denied decision when user denies", async () => {
@@ -433,8 +435,8 @@ describe("external_directory policy state — ask", () => {
     });
     const event = makeToolCallEvent("read", { input: { path: EXTERNAL_PATH } });
     const result = await handler.handleToolCall(event, makeCtx());
-    expect(result.block).toBe(true);
-    expect(result.reason).toContain("not needed");
+    expect(result).toMatchObject({ action: "block" });
+    expect((result as { reason?: string }).reason).toContain("not needed");
   });
 
   it("blocks with confirmation_unavailable when no UI is available", async () => {
@@ -451,8 +453,10 @@ describe("external_directory policy state — ask", () => {
       event,
       makeCtx({ hasUI: false }),
     );
-    expect(result.block).toBe(true);
-    expect(result.reason).toContain("outside the working directory");
+    expect(result).toMatchObject({ action: "block" });
+    expect((result as { reason?: string }).reason).toContain(
+      "outside the working directory",
+    );
   });
 
   it("writes review-log entry with confirmation_unavailable when no UI", async () => {
@@ -541,7 +545,7 @@ describe("external_directory per-agent override", () => {
     });
     const event = makeToolCallEvent("read", { input: { path: EXTERNAL_PATH } });
     const result1 = await handler1.handleToolCall(event, makeCtx());
-    expect(result1).toEqual({});
+    expect(result1).toEqual({ action: "allow" });
 
     const decisions1 = getDecisionEvents(events1);
     const extDir1 = decisions1.find((d) => d.surface === "external_directory");
@@ -560,7 +564,7 @@ describe("external_directory per-agent override", () => {
       tools: ALL_TOOLS,
     });
     const result2 = await handler2.handleToolCall(event, makeCtx());
-    expect(result2).toMatchObject({ block: true });
+    expect(result2).toMatchObject({ action: "block" });
   });
 });
 

package/test/handlers/external-directory-session-dedup.test.ts

@@ -161,7 +161,7 @@ describe("external-directory session dedup", () => {
         input: { path: externalPath },
       };
       const result1 = await handler.handleToolCall(event1, ctx);
-      expect(result1).toEqual({});
+      expect(result1).toEqual({ action: "allow" });
       expect(prompter.prompt).toHaveBeenCalledTimes(1);
 
       // Second call — same path, should hit session rule, no prompt
@@ -172,7 +172,7 @@ describe("external-directory session dedup", () => {
         input: { path: externalPath },
       };
       const result2 = await handler.handleToolCall(event2, ctx);
-      expect(result2).toEqual({});
+      expect(result2).toEqual({ action: "allow" });
       expect(prompter.prompt).toHaveBeenCalledTimes(1);
     });
 
@@ -272,7 +272,7 @@ describe("external-directory session dedup", () => {
         input: { command: "echo hello > /tmp/out.txt" },
       };
       const result1 = await handler.handleToolCall(event1, ctx);
-      expect(result1).toEqual({});
+      expect(result1).toEqual({ action: "allow" });
       expect(prompter.prompt).toHaveBeenCalledTimes(1);
 
       // Second call — different bash command, same external path
@@ -283,7 +283,7 @@ describe("external-directory session dedup", () => {
         input: { command: "cat /tmp/out.txt" },
       };
       const result2 = await handler.handleToolCall(event2, ctx);
-      expect(result2).toEqual({});
+      expect(result2).toEqual({ action: "allow" });
       expect(prompter.prompt).toHaveBeenCalledTimes(1);
     });
 

package/test/handlers/gates/bash-command-metamorphic.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Metamorphic totality property for the bash command gate (#452, A3).
+ *
+ * Wrapping any `ask`/`deny` command in `cd /x && <cmd>` must not weaken the
+ * decision — the chain decomposition + most-restrictive-wins, combined with the
+ * fail-closed empty-parse fallback, guarantees a `cd …` prefix can never let a
+ * gated command ride a permissive top-level `*`.
+ *
+ * A focused parametrized table over the real tree-sitter parse + resolve, not a
+ * full fuzzer (tree-sitter fuzzing is brittle); it pins A3 directly.
+ */
+import { describe, expect, it } from "vitest";
+
+import { resolveBashCommandCheck } from "#src/handlers/gates/bash-command";
+import { BashProgram } from "#src/handlers/gates/bash-program";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import type { PermissionState } from "#src/types";
+
+import { makeCheckResult } from "#test/helpers/handler-fixtures";
+
+/** Decision strength ordering: deny (2) > ask (1) > allow (0). */
+const STRENGTH: Record<PermissionState, number> = {
+  allow: 0,
+  ask: 1,
+  deny: 2,
+};
+
+/**
+ * Resolver whose decision keys on a command substring → state map. A command
+ * matching no entry resolves to allow (the permissive top-level `*`).
+ */
+function makeKeyedResolver(
+  rules: { match: string; state: PermissionState }[],
+): ScopedPermissionResolver {
+  return {
+    resolve: (_surface: string, input: { command?: string }) => {
+      const command = input.command ?? "";
+      const rule = rules.find((r) => command.includes(r.match));
+      const state: PermissionState = rule?.state ?? "allow";
+      return makeCheckResult({ state, source: "bash", command });
+    },
+    resolvePathPolicy: () => makeCheckResult(),
+  };
+}
+
+async function decide(
+  command: string,
+  resolver: ScopedPermissionResolver,
+): Promise<PermissionState> {
+  const program = await BashProgram.parse(command);
+  return resolveBashCommandCheck(
+    command,
+    program.commands(),
+    undefined,
+    resolver,
+  ).state;
+}
+
+describe("bash command gate — metamorphic totality", () => {
+  const cases: { bare: string; state: PermissionState }[] = [
+    { bare: "git push", state: "ask" },
+    { bare: "git commit -m wip", state: "ask" },
+    { bare: "rm -rf build", state: "deny" },
+    { bare: "npm install pkg", state: "deny" },
+    { bare: "gh pr create", state: "ask" },
+  ];
+
+  for (const { bare, state } of cases) {
+    it(`wrapping "${bare}" in a cd prefix does not weaken its ${state} decision`, async () => {
+      const resolver = makeKeyedResolver([
+        { match: bare.split(" ")[0] ?? bare, state },
+      ]);
+
+      const bareDecision = await decide(bare, resolver);
+      const wrappedDecision = await decide(`cd /repo && ${bare}`, resolver);
+
+      expect(STRENGTH[wrappedDecision]).toBeGreaterThanOrEqual(
+        STRENGTH[bareDecision],
+      );
+      expect(wrappedDecision).toBe(state);
+    });
+  }
+});

package/test/handlers/gates/bash-command.test.ts

@@ -97,21 +97,48 @@ describe("resolveBashCommandCheck", () => {
     expect(result.matchedPattern).toBe("a *");
   });
 
-  it("falls back to the whole command when no top-level commands are found", () => {
-    const resolver = makeResolver(bashResult("ask", "( rm x )", "*"));
+  it("falls back to the whole command for a comment-only line (genuinely nothing to gate)", () => {
+    const resolver = makeResolver(bashResult("allow", "# just a comment", "*"));
 
-    const result = resolveBashCommandCheck("( rm x )", [], undefined, resolver);
+    const result = resolveBashCommandCheck(
+      "# just a comment",
+      [],
+      undefined,
+      resolver,
+    );
 
-    expect(result.state).toBe("ask");
-    expect(result.commandContext).toBeUndefined();
+    expect(result.state).toBe("allow");
     expect(resolver.resolve).toHaveBeenCalledTimes(1);
     expect(resolver.resolve).toHaveBeenCalledWith(
       "bash",
-      { command: "( rm x )" },
+      { command: "# just a comment" },
       undefined,
     );
   });
 
+  it("falls back to the whole command for an empty/whitespace-only command", () => {
+    const resolver = makeResolver(bashResult("allow", "   ", "*"));
+
+    const result = resolveBashCommandCheck("   ", [], undefined, resolver);
+
+    expect(result.state).toBe("allow");
+    expect(resolver.resolve).toHaveBeenCalledTimes(1);
+  });
+
+  it("fails closed to ask when a non-empty command parses to zero command units", () => {
+    const resolver = makeResolver(bashResult("allow", "( rm x )", "*"));
+
+    const result = resolveBashCommandCheck("( rm x )", [], undefined, resolver);
+
+    // A permissive top-level '*' must NOT silently allow an unparseable command.
+    expect(result.state).toBe("ask");
+    expect(result.matchedPattern).toBe("<unparseable-bash-command>");
+    expect(result.command).toBe("( rm x )");
+    expect(result.commandContext).toBeUndefined();
+    // The synthetic ask is returned without consulting the resolver.
+    expect(resolver.resolve).not.toHaveBeenCalled();
+  });
+
   it("forwards the agent name to each sub-command check", () => {
     const resolver = makeResolver(bashResult("allow", "npm i"));
 

package/test/handlers/lifecycle.test.ts

@@ -35,11 +35,13 @@ function makeSetup(opts?: { configIssues?: string[] }) {
   // Use a session-independent logger so assertions verify direct injection,
   // not reach-through to session.logger.
   const logger = makeLogger();
+  const audit = { writeSummary: vi.fn<(logger: unknown) => void>() };
   const handler = new SessionLifecycleHandler(
     session,
     resolver,
     serviceLifecycle,
     logger,
+    audit,
   );
   return {
     handler,
@@ -50,6 +52,7 @@ function makeSetup(opts?: { configIssues?: string[] }) {
     forwarding,
     configStore,
     serviceLifecycle,
+    audit,
   };
 }
 
@@ -209,4 +212,10 @@ describe("handleSessionShutdown", () => {
     await handler.handleSessionShutdown();
     expect(serviceLifecycle.teardown).toHaveBeenCalledOnce();
   });
+
+  it("writes the decision-audit summary to the logger", async () => {
+    const { handler, audit, logger } = makeSetup();
+    await handler.handleSessionShutdown();
+    expect(audit.writeSummary).toHaveBeenCalledWith(logger);
+  });
 });

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

@@ -0,0 +1,145 @@
+/**
+ * The fail-closed boundary is the only tool_call handler the SDK sees.
+ *
+ * The SDK's emitToolCall (@earendil-works/pi-coding-agent dist/core/extensions/
+ * runner.js) awaits the registered handler with NO try/catch — unlike
+ * emitUserBash directly below it, which catches and continues. So a thrown
+ * gate would otherwise yield no block and the command would run ungated with
+ * no trace. This boundary must absorb the throw and fail closed.
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { describe, expect, it, vi } from "vitest";
+import type { GateOutcome } from "#src/handlers/gates/types";
+import { createFailClosedToolCall } from "#src/handlers/tool-call-boundary";
+
+import { makeReporter } from "#test/helpers/gate-fixtures";
+import { makeCtx, makeToolCallEvent } from "#test/helpers/handler-fixtures";
+
+function makeAudit() {
+  return {
+    recordDecision: vi.fn<(action: "allow" | "block") => void>(),
+    recordError: vi.fn<() => void>(),
+  };
+}
+
+function makeTracer() {
+  return {
+    debug: vi.fn<(event: string, details?: Record<string, unknown>) => void>(),
+  };
+}
+
+function gateReturning(outcome: GateOutcome) {
+  return vi
+    .fn<(event: unknown, ctx: ExtensionContext) => Promise<GateOutcome>>()
+    .mockResolvedValue(outcome);
+}
+
+describe("createFailClosedToolCall", () => {
+  it("translates an allow outcome to the empty SDK shape", async () => {
+    const audit = makeAudit();
+    const reporter = makeReporter();
+    const boundary = createFailClosedToolCall(
+      gateReturning({ action: "allow" }),
+      reporter,
+      audit,
+      makeTracer(),
+    );
+
+    const result = await boundary(makeToolCallEvent("read"), makeCtx());
+
+    expect(result).toEqual({});
+    expect(audit.recordDecision).toHaveBeenCalledWith("allow");
+    expect(audit.recordError).not.toHaveBeenCalled();
+    expect(reporter.writeReviewLog).not.toHaveBeenCalled();
+  });
+
+  it("translates a block outcome to the SDK block shape with the reason", async () => {
+    const audit = makeAudit();
+    const reporter = makeReporter();
+    const boundary = createFailClosedToolCall(
+      gateReturning({ action: "block", reason: "denied by policy" }),
+      reporter,
+      audit,
+      makeTracer(),
+    );
+
+    const result = await boundary(makeToolCallEvent("read"), makeCtx());
+
+    expect(result).toEqual({ block: true, reason: "denied by policy" });
+    expect(audit.recordDecision).toHaveBeenCalledWith("block");
+  });
+
+  it("writes a per-call decision trace with the tool name and action", async () => {
+    const tracer = makeTracer();
+    const boundary = createFailClosedToolCall(
+      gateReturning({ action: "allow" }),
+      makeReporter(),
+      makeAudit(),
+      tracer,
+    );
+
+    await boundary(makeToolCallEvent("bash"), makeCtx());
+
+    expect(tracer.debug).toHaveBeenCalledWith(
+      "permission.decision",
+      expect.objectContaining({ toolName: "bash", action: "allow" }),
+    );
+  });
+
+  it("blocks fail-closed when the gate throws, recording an error and a review-log entry", async () => {
+    const audit = makeAudit();
+    const reporter = makeReporter();
+    const gate = vi
+      .fn<(event: unknown, ctx: ExtensionContext) => Promise<GateOutcome>>()
+      .mockRejectedValue(new Error("parser init failed"));
+    const boundary = createFailClosedToolCall(
+      gate,
+      reporter,
+      audit,
+      makeTracer(),
+    );
+
+    const event = makeToolCallEvent("bash", {
+      input: { command: "cd /repo && git push" },
+    });
+    const result = await boundary(event, makeCtx());
+
+    expect((result as { block?: true }).block).toBe(true);
+    expect(audit.recordError).toHaveBeenCalledTimes(1);
+    expect(audit.recordDecision).not.toHaveBeenCalled();
+    expect(reporter.writeReviewLog).toHaveBeenCalledWith(
+      "permission_request.blocked",
+      expect.objectContaining({
+        toolName: "bash",
+        command: "cd /repo && git push",
+        resolution: "gate_error",
+        error: "parser init failed",
+      }),
+    );
+  });
+
+  it("does not throw when the event is malformed and the gate throws", async () => {
+    const audit = makeAudit();
+    const reporter = makeReporter();
+    const gate = vi
+      .fn<(event: unknown, ctx: ExtensionContext) => Promise<GateOutcome>>()
+      .mockRejectedValue("non-error rejection");
+    const boundary = createFailClosedToolCall(
+      gate,
+      reporter,
+      audit,
+      makeTracer(),
+    );
+
+    const result = await boundary(undefined, makeCtx());
+
+    expect((result as { block?: true }).block).toBe(true);
+    expect(reporter.writeReviewLog).toHaveBeenCalledWith(
+      "permission_request.blocked",
+      expect.objectContaining({
+        resolution: "gate_error",
+        error: "non-error rejection",
+      }),
+    );
+  });
+});