@komarspn/pi-permission-system 16.0.2

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

@@ -0,0 +1,430 @@
+/**
+ * Integration tests verifying that sequential tool calls to the same
+ * external path only prompt once — the session-approval recorded by the
+ * first call covers the second.
+ *
+ * Uses real PermissionSession + PermissionResolver + SessionRules so the
+ * stateful approval-tracking path is exercised end-to-end.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+
+import { GateDecisionReporter } from "#src/decision-reporter";
+import type { GatePrompter } from "#src/gate-prompter";
+import { GateRunner } from "#src/handlers/gates/runner";
+import { SkillInputGatePipeline } from "#src/handlers/gates/skill-input-gate-pipeline";
+import { ToolCallGatePipeline } from "#src/handlers/gates/tool-call-gate-pipeline";
+import { PermissionGateHandler } from "#src/handlers/permission-gate-handler";
+import type { PermissionCheckResult } from "#src/types";
+import { wildcardMatch } from "#src/wildcard-matcher";
+
+import {
+  makeCtx,
+  makeEvents,
+  makeToolRegistry,
+} from "#test/helpers/handler-fixtures";
+import {
+  makeRealResolver,
+  makeRealSession,
+} from "#test/helpers/session-fixtures";
+
+// ── SDK stub ───────────────────────────────────────────────────────────────
+vi.mock("@earendil-works/pi-coding-agent", async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import("@earendil-works/pi-coding-agent")>();
+  return { ...original };
+});
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Build a fully wired PermissionGateHandler for external-directory dedup
+ * tests.
+ *
+ * `permissionManager.checkPermission` is configured so that:
+ * - `external_directory` surface returns "ask" on first call
+ * - On subsequent calls it checks the shared `sessionRules` store; if a
+ *   matching rule was recorded by the runner, it returns "allow" with
+ *   `source: "session"`.
+ * - All other surfaces return "allow".
+ */
+function makeDeduplicatingHandler(prompter?: GatePrompter): {
+  handler: PermissionGateHandler;
+  prompter: GatePrompter;
+} {
+  const { session, permissionManager, sessionRules, logger } =
+    makeRealSession();
+  const { resolver } = makeRealResolver(permissionManager, sessionRules);
+
+  // Configure checkPermission to simulate config-level "ask" for external_directory
+  // but return "allow/session" when a session rule has been recorded.
+  vi.mocked(permissionManager.checkPermission).mockImplementation(
+    (surface, input, _agentName, rules): PermissionCheckResult => {
+      if (surface === "external_directory") {
+        const record = (input ?? {}) as Record<string, unknown>;
+        const pathValue = typeof record.path === "string" ? record.path : null;
+
+        if (pathValue && rules && rules.length > 0) {
+          const match = rules.findLast(
+            (r) =>
+              r.surface === "external_directory" &&
+              wildcardMatch(r.pattern, pathValue),
+          );
+          if (match) {
+            return {
+              state: "allow",
+              toolName: surface,
+              source: "session",
+              origin: "session",
+              matchedPattern: match.pattern,
+            };
+          }
+        }
+
+        return {
+          state: "ask",
+          toolName: surface,
+          source: "special",
+          origin: "global",
+        };
+      }
+
+      return {
+        state: "allow",
+        toolName: surface,
+        source: "tool",
+        origin: "builtin",
+      };
+    },
+  );
+
+  // The external-directory gates resolve through checkPathPolicy (#418); route
+  // it through the same configured checkPermission so session-approval dedup
+  // applies to the typed path alias.
+  vi.mocked(permissionManager.checkPathPolicy).mockImplementation(
+    (values, agentName, rules, surface = "path") =>
+      permissionManager.checkPermission(
+        surface,
+        { path: values[0] ?? "*" },
+        agentName,
+        rules,
+      ),
+  );
+
+  const events = makeEvents();
+  const reporter = new GateDecisionReporter(logger, events);
+  const resolvedPrompter: GatePrompter = prompter ?? {
+    canConfirm: vi.fn().mockReturnValue(true),
+    prompt: vi
+      .fn<GatePrompter["prompt"]>()
+      .mockResolvedValue({ approved: true, state: "approved_for_session" }),
+  };
+  const runner = new GateRunner(
+    resolver,
+    sessionRules,
+    resolvedPrompter,
+    reporter,
+    { recordApproval: vi.fn() } as never,
+  );
+  const handler = new PermissionGateHandler(
+    session,
+    makeToolRegistry({
+      getAll: vi
+        .fn()
+        .mockReturnValue([
+          { name: "read" },
+          { name: "write" },
+          { name: "edit" },
+          { name: "bash" },
+        ]),
+    }),
+    new ToolCallGatePipeline(resolver, session),
+    new SkillInputGatePipeline(resolver),
+    runner,
+  );
+  return { handler, prompter: resolvedPrompter };
+}
+
+// ── tests ──────────────────────────────────────────────────────────────────
+
+describe("external-directory session dedup", () => {
+  describe("path-bearing tools (read, write, edit)", () => {
+    it("does not re-prompt for the same external path after session approval", async () => {
+      const { handler, prompter } = makeDeduplicatingHandler();
+      const ctx = makeCtx();
+      const externalPath = "/outside/project/data.txt";
+
+      // First call — should prompt
+      const event1 = {
+        type: "tool_call",
+        toolCallId: "tc-1",
+        toolName: "read",
+        input: { path: externalPath },
+      };
+      const result1 = await handler.handleToolCall(event1, ctx);
+      expect(result1).toEqual({ action: "allow" });
+      expect(prompter.prompt).toHaveBeenCalledTimes(1);
+
+      // Second call — same path, should hit session rule, no prompt
+      const event2 = {
+        type: "tool_call",
+        toolCallId: "tc-2",
+        toolName: "read",
+        input: { path: externalPath },
+      };
+      const result2 = await handler.handleToolCall(event2, ctx);
+      expect(result2).toEqual({ action: "allow" });
+      expect(prompter.prompt).toHaveBeenCalledTimes(1);
+    });
+
+    it("does not re-prompt for a different file in the same external directory", async () => {
+      const { handler, prompter } = makeDeduplicatingHandler();
+      const ctx = makeCtx();
+
+      // First call — prompt for /outside/project/a.txt
+      const event1 = {
+        type: "tool_call",
+        toolCallId: "tc-1",
+        toolName: "read",
+        input: { path: "/outside/project/a.txt" },
+      };
+      await handler.handleToolCall(event1, ctx);
+      expect(prompter.prompt).toHaveBeenCalledTimes(1);
+
+      // Second call — /outside/project/b.txt is in the same directory
+      const event2 = {
+        type: "tool_call",
+        toolCallId: "tc-2",
+        toolName: "read",
+        input: { path: "/outside/project/b.txt" },
+      };
+      await handler.handleToolCall(event2, ctx);
+      expect(prompter.prompt).toHaveBeenCalledTimes(1);
+    });
+
+    it("does prompt for a file in a different external directory", async () => {
+      const { handler, prompter } = makeDeduplicatingHandler();
+      const ctx = makeCtx();
+
+      // First call — /outside/alpha/file.txt
+      const event1 = {
+        type: "tool_call",
+        toolCallId: "tc-1",
+        toolName: "read",
+        input: { path: "/outside/alpha/file.txt" },
+      };
+      await handler.handleToolCall(event1, ctx);
+      expect(prompter.prompt).toHaveBeenCalledTimes(1);
+
+      // Second call — /outside/beta/file.txt is a different directory
+      const event2 = {
+        type: "tool_call",
+        toolCallId: "tc-2",
+        toolName: "read",
+        input: { path: "/outside/beta/file.txt" },
+      };
+      await handler.handleToolCall(event2, ctx);
+      expect(prompter.prompt).toHaveBeenCalledTimes(2);
+    });
+
+    it("re-prompts when user approved once (not for session)", async () => {
+      const approveOnce: GatePrompter = {
+        canConfirm: vi.fn().mockReturnValue(true),
+        prompt: vi
+          .fn<GatePrompter["prompt"]>()
+          .mockResolvedValue({ approved: true, state: "approved" }),
+      };
+      const { handler, prompter } = makeDeduplicatingHandler(approveOnce);
+      const ctx = makeCtx();
+      const externalPath = "/outside/project/data.txt";
+
+      // First call — prompt, approved once
+      const event1 = {
+        type: "tool_call",
+        toolCallId: "tc-1",
+        toolName: "read",
+        input: { path: externalPath },
+      };
+      await handler.handleToolCall(event1, ctx);
+      expect(prompter.prompt).toHaveBeenCalledTimes(1);
+
+      // Second call — no session rule recorded, should prompt again
+      const event2 = {
+        type: "tool_call",
+        toolCallId: "tc-2",
+        toolName: "read",
+        input: { path: externalPath },
+      };
+      await handler.handleToolCall(event2, ctx);
+      expect(prompter.prompt).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe("bash commands with external paths", () => {
+    it("does not re-prompt for a bash command referencing the same external path after session approval", async () => {
+      const { handler, prompter } = makeDeduplicatingHandler();
+      const ctx = makeCtx();
+
+      // First call — bash referencing /tmp/out.txt
+      const event1 = {
+        type: "tool_call",
+        toolCallId: "tc-1",
+        toolName: "bash",
+        input: { command: "echo hello > /tmp/out.txt" },
+      };
+      const result1 = await handler.handleToolCall(event1, ctx);
+      expect(result1).toEqual({ action: "allow" });
+      expect(prompter.prompt).toHaveBeenCalledTimes(1);
+
+      // Second call — different bash command, same external path
+      const event2 = {
+        type: "tool_call",
+        toolCallId: "tc-2",
+        toolName: "bash",
+        input: { command: "cat /tmp/out.txt" },
+      };
+      const result2 = await handler.handleToolCall(event2, ctx);
+      expect(result2).toEqual({ action: "allow" });
+      expect(prompter.prompt).toHaveBeenCalledTimes(1);
+    });
+
+    it("does not re-prompt for read after bash already approved the same directory", async () => {
+      const { handler, prompter } = makeDeduplicatingHandler();
+      const ctx = makeCtx();
+
+      // First call — bash writes to /tmp/out.txt
+      const event1 = {
+        type: "tool_call",
+        toolCallId: "tc-1",
+        toolName: "bash",
+        input: { command: "echo hello > /tmp/out.txt" },
+      };
+      await handler.handleToolCall(event1, ctx);
+      expect(prompter.prompt).toHaveBeenCalledTimes(1);
+
+      // Second call — read from /tmp/out.txt (same directory, different tool)
+      const event2 = {
+        type: "tool_call",
+        toolCallId: "tc-2",
+        toolName: "read",
+        input: { path: "/tmp/out.txt" },
+      };
+      await handler.handleToolCall(event2, ctx);
+      expect(prompter.prompt).toHaveBeenCalledTimes(1);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Moved from permission-system.test.ts catch-all (#342)
+// ---------------------------------------------------------------------------
+
+describe("session shutdown clears external-directory approvals", () => {
+  it("re-prompts for the same path after session shutdown", async () => {
+    // Build a fully wired handler inline so we can access session directly.
+    const { session, permissionManager, sessionRules, logger } =
+      makeRealSession();
+    const { resolver } = makeRealResolver(permissionManager, sessionRules);
+
+    // external_directory=ask; session-covered paths return allow/session.
+    vi.mocked(permissionManager.checkPermission).mockImplementation(
+      (surface, input, _agentName, rules): PermissionCheckResult => {
+        if (surface === "external_directory") {
+          const record = (input ?? {}) as Record<string, unknown>;
+          const pathValue =
+            typeof record.path === "string" ? record.path : null;
+          if (pathValue && rules && rules.length > 0) {
+            const match = rules.findLast(
+              (r) =>
+                r.surface === "external_directory" &&
+                wildcardMatch(r.pattern, pathValue),
+            );
+            if (match) {
+              return {
+                state: "allow",
+                toolName: surface,
+                source: "session",
+                origin: "session",
+                matchedPattern: match.pattern,
+              };
+            }
+          }
+          return {
+            state: "ask",
+            toolName: surface,
+            source: "special",
+            origin: "global",
+          };
+        }
+        return {
+          state: "allow",
+          toolName: surface,
+          source: "tool",
+          origin: "builtin",
+        };
+      },
+    );
+
+    // The external-directory tool gate resolves through checkPathPolicy (#418);
+    // route it through the same configured checkPermission.
+    vi.mocked(permissionManager.checkPathPolicy).mockImplementation(
+      (values, agentName, rules, surface = "path") =>
+        permissionManager.checkPermission(
+          surface,
+          { path: values[0] ?? "*" },
+          agentName,
+          rules,
+        ),
+    );
+
+    const events = makeEvents();
+    const reporter = new GateDecisionReporter(logger, events);
+    const prompter: GatePrompter = {
+      canConfirm: vi.fn().mockReturnValue(true),
+      // Simulate "Yes, for this session" on first call, "Yes" on subsequent.
+      prompt: vi
+        .fn<GatePrompter["prompt"]>()
+        .mockResolvedValue({ approved: true, state: "approved_for_session" }),
+    };
+    const runner = new GateRunner(
+      resolver,
+      sessionRules,
+      prompter,
+      reporter,
+      { recordApproval: vi.fn() } as never,
+    );
+    const handler = new PermissionGateHandler(
+      session,
+      makeToolRegistry({
+        getAll: vi.fn().mockReturnValue([{ name: "read" }]),
+      }),
+      new ToolCallGatePipeline(resolver, session),
+      new SkillInputGatePipeline(resolver),
+      runner,
+    );
+
+    const externalPath = "/tmp/sibling/foo.ts";
+    const ctx = makeCtx();
+    const event = {
+      type: "tool_call",
+      toolCallId: "tc-1",
+      toolName: "read",
+      input: { path: externalPath },
+    };
+
+    // First access: prompt fires and records session approval.
+    await handler.handleToolCall(event, ctx);
+    expect(vi.mocked(prompter.prompt)).toHaveBeenCalledTimes(1);
+
+    // Second access: covered by session approval — no re-prompt.
+    await handler.handleToolCall({ ...event, toolCallId: "tc-2" }, ctx);
+    expect(vi.mocked(prompter.prompt)).toHaveBeenCalledTimes(1);
+
+    // Shutdown clears session approvals.
+    session.shutdown();
+
+    // Third access: session rules cleared — must re-prompt.
+    await handler.handleToolCall({ ...event, toolCallId: "tc-3" }, ctx);
+    expect(vi.mocked(prompter.prompt)).toHaveBeenCalledTimes(2);
+  });
+});

package/test/handlers/external-directory-symlink-acceptance.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Acceptance test for issue #418.
+ *
+ * Reproduces the reported bug with a real symlink (no `realpathSync` mock):
+ * an `external_directory` allow configured for the path as the user types it
+ * (`<link>/*`) must allow access even though the OS resolves `<link>` to a
+ * different canonical directory. Exercised end-to-end through the real
+ * `PermissionManager` + `PermissionResolver` for both a path-bearing tool and
+ * a bash command, and for an allow keyed on the symlink-resolved form too.
+ */
+
+import { mkdtempSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { describeBashExternalDirectoryGate } from "#src/handlers/gates/bash-external-directory";
+import { BashProgram } from "#src/handlers/gates/bash-program";
+import {
+  type GateDescriptor,
+  isGateBypass,
+  isGateDescriptor,
+} from "#src/handlers/gates/descriptor";
+import { describeExternalDirectoryGate } from "#src/handlers/gates/external-directory";
+import type { ToolCallContext } from "#src/handlers/gates/types";
+import { PermissionResolver } from "#src/permission-resolver";
+import { SessionRules } from "#src/session-rules";
+import type { ScopeConfig } from "#src/types";
+
+import { createManager } from "#test/helpers/manager-harness";
+
+// ── real symlink fixture ─────────────────────────────────────────────────────
+
+let realDir: string;
+let linkDir: string;
+let cwd: string;
+const tempRoots: string[] = [];
+
+function mkTemp(prefix: string): string {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  tempRoots.push(dir);
+  return dir;
+}
+
+beforeEach(() => {
+  realDir = mkTemp("ext-real-");
+  const linkParent = mkTemp("ext-link-");
+  linkDir = join(linkParent, "link");
+  symlinkSync(realDir, linkDir);
+  cwd = mkTemp("ext-cwd-");
+});
+
+afterEach(() => {
+  while (tempRoots.length > 0) {
+    const dir = tempRoots.pop();
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function makeResolver(config: ScopeConfig) {
+  const { manager, cleanup } = createManager(config);
+  manager.configureForCwd(cwd);
+  const resolver = new PermissionResolver(manager, new SessionRules());
+  return { resolver, cleanup };
+}
+
+function readTcc(): ToolCallContext {
+  return {
+    toolName: "read",
+    agentName: null,
+    input: { path: join(linkDir, "file.ts") },
+    toolCallId: "tc-1",
+    cwd,
+  };
+}
+
+// ── tests ────────────────────────────────────────────────────────────────────
+
+describe("external_directory symlink acceptance (#418)", () => {
+  it("allows a path-bearing tool when the allow is keyed on the typed (symlinked) path", () => {
+    const { resolver, cleanup } = makeResolver({
+      permission: {
+        external_directory: { "*": "ask", [`${linkDir}/*`]: "allow" },
+      },
+    });
+    try {
+      const result = describeExternalDirectoryGate(readTcc(), [], resolver);
+      expect(isGateDescriptor(result)).toBe(true);
+      expect((result as GateDescriptor).preCheck?.state).toBe("allow");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("allows a path-bearing tool when the allow is keyed on the resolved path", () => {
+    // Key the allow on the fully symlink-resolved directory (on macOS the
+    // tmpdir root itself is a symlink, e.g. /var -> /private/var).
+    const resolved = realpathSync(realDir);
+    const { resolver, cleanup } = makeResolver({
+      permission: {
+        external_directory: { "*": "ask", [`${resolved}/*`]: "allow" },
+      },
+    });
+    try {
+      const result = describeExternalDirectoryGate(readTcc(), [], resolver);
+      expect(isGateDescriptor(result)).toBe(true);
+      expect((result as GateDescriptor).preCheck?.state).toBe("allow");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("still prompts (ask) when no external_directory allow matches", () => {
+    const { resolver, cleanup } = makeResolver({
+      permission: { external_directory: { "*": "ask" } },
+    });
+    try {
+      const result = describeExternalDirectoryGate(readTcc(), [], resolver);
+      expect(isGateDescriptor(result)).toBe(true);
+      expect((result as GateDescriptor).preCheck?.state).toBe("ask");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("allows a bash command referencing the typed (symlinked) path", async () => {
+    const { resolver, cleanup } = makeResolver({
+      permission: {
+        external_directory: { "*": "ask", [`${linkDir}/*`]: "allow" },
+      },
+    });
+    try {
+      const command = `cat ${join(linkDir, "file.ts")}`;
+      const tcc: ToolCallContext = {
+        toolName: "bash",
+        agentName: null,
+        input: { command },
+        toolCallId: "tc-2",
+        cwd,
+      };
+      const program = await BashProgram.parse(command);
+      const result = describeBashExternalDirectoryGate(tcc, program, resolver);
+      // All external paths are covered by the allow → bypass, no prompt.
+      expect(isGateBypass(result)).toBe(true);
+    } finally {
+      cleanup();
+    }
+  });
+});

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