@komarspn/pi-permission-system 16.0.2

package/test/handlers/gates/candidate-check.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+
+import { pickMostRestrictive } from "#src/handlers/gates/candidate-check";
+
+import { makeGateCheckResult } from "#test/helpers/gate-fixtures";
+
+describe("pickMostRestrictive", () => {
+  it("returns undefined for an empty list", () => {
+    expect(pickMostRestrictive([])).toBeUndefined();
+  });
+
+  it("returns the single result for a one-element list", () => {
+    const only = makeGateCheckResult({ state: "allow" });
+    expect(pickMostRestrictive([only])).toBe(only);
+  });
+
+  it("prefers deny over ask and allow regardless of position", () => {
+    const allow = makeGateCheckResult({ state: "allow", matchedPattern: "a" });
+    const ask = makeGateCheckResult({ state: "ask", matchedPattern: "b" });
+    const deny = makeGateCheckResult({ state: "deny", matchedPattern: "c" });
+    expect(pickMostRestrictive([allow, ask, deny])).toBe(deny);
+    expect(pickMostRestrictive([deny, ask, allow])).toBe(deny);
+  });
+
+  it("prefers ask over allow when no deny is present", () => {
+    const allow = makeGateCheckResult({ state: "allow" });
+    const ask = makeGateCheckResult({ state: "ask" });
+    expect(pickMostRestrictive([allow, ask])).toBe(ask);
+  });
+
+  it("keeps the first deny on ties", () => {
+    const deny1 = makeGateCheckResult({
+      state: "deny",
+      matchedPattern: "first",
+    });
+    const deny2 = makeGateCheckResult({
+      state: "deny",
+      matchedPattern: "second",
+    });
+    expect(pickMostRestrictive([deny1, deny2])).toBe(deny1);
+  });
+
+  it("keeps the first ask on ties when no deny is present", () => {
+    const allow = makeGateCheckResult({ state: "allow" });
+    const ask1 = makeGateCheckResult({ state: "ask", matchedPattern: "first" });
+    const ask2 = makeGateCheckResult({
+      state: "ask",
+      matchedPattern: "second",
+    });
+    expect(pickMostRestrictive([allow, ask1, ask2])).toBe(ask1);
+  });
+});

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

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "vitest";
+
+import {
+  formatBashExternalDirectoryAskPrompt,
+  formatExternalDirectoryAskPrompt,
+} from "#src/handlers/gates/external-directory-messages";
+
+// 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", () => {
+    const result = formatExternalDirectoryAskPrompt(
+      "read",
+      "/etc/passwd",
+      "/projects/my-app",
+    );
+    expect(result).toContain("Current agent");
+    expect(result).toContain("read");
+    expect(result).toContain("/etc/passwd");
+    expect(result).toContain("/projects/my-app");
+  });
+
+  test("uses agent name when provided", () => {
+    const result = formatExternalDirectoryAskPrompt(
+      "write",
+      "/tmp/out.txt",
+      "/projects/my-app",
+      "my-agent",
+    );
+    expect(result).toContain("Agent 'my-agent'");
+    expect(result).toContain("write");
+    expect(result).toContain("/tmp/out.txt");
+  });
+});
+
+describe("formatBashExternalDirectoryAskPrompt", () => {
+  test("includes command, paths, cwd, and agent name", () => {
+    const result = formatBashExternalDirectoryAskPrompt(
+      "cat /etc/passwd",
+      ["/etc/passwd"],
+      "/projects/my-app",
+      "my-agent",
+    );
+    expect(result).toContain("Agent 'my-agent'");
+    expect(result).toContain("cat /etc/passwd");
+    expect(result).toContain("/etc/passwd");
+    expect(result).toContain("/projects/my-app");
+  });
+
+  test("uses 'Current agent' when no agent name provided", () => {
+    const result = formatBashExternalDirectoryAskPrompt(
+      "ls /tmp",
+      ["/tmp"],
+      "/projects/my-app",
+    );
+    expect(result).toContain("Current agent");
+  });
+});

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

@@ -0,0 +1,259 @@
+import { describe, expect, it } from "vitest";
+
+import type {
+  GateBypass,
+  GateDescriptor,
+} from "#src/handlers/gates/descriptor";
+import { isGateBypass, isGateDescriptor } from "#src/handlers/gates/descriptor";
+import { describeExternalDirectoryGate } from "#src/handlers/gates/external-directory";
+import type { ToolCallContext } from "#src/handlers/gates/types";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
+import { makeResolver } from "#test/helpers/gate-fixtures";
+import { makeCheckResult } from "#test/helpers/handler-fixtures";
+
+// ── helpers ───────────────────────────��────────────────────────────��───────
+
+function makeTcc(overrides: Partial<ToolCallContext> = {}): ToolCallContext {
+  return {
+    toolName: "read",
+    agentName: null,
+    input: { path: "/outside/project/file.ts" },
+    toolCallId: "tc-1",
+    cwd: "/test/project",
+    ...overrides,
+  };
+}
+
+// Default resolver for descriptor-shape tests that do not assert the resolved
+// state: returns `ask` for the external_directory surface so a descriptor is
+// produced. Tests that assert the typed+resolved matching pass an explicit
+// resolver to `describeExternalDirectoryGate` directly.
+function gateUnderTest(
+  tcc: ToolCallContext,
+  infraDirs: string[],
+  extractors?: ToolAccessExtractorLookup,
+  resolver: ScopedPermissionResolver = makeResolver(
+    makeCheckResult({ state: "ask", toolName: "external_directory" }),
+  ),
+) {
+  return describeExternalDirectoryGate(tcc, infraDirs, resolver, extractors);
+}
+
+// ── tests ────────────────────��────────────────────────────────────��────────
+
+describe("describeExternalDirectoryGate", () => {
+  it("returns null when no CWD", () => {
+    const result = gateUnderTest(makeTcc({ cwd: undefined }), ["/test/agent"]);
+    expect(result).toBeNull();
+  });
+
+  it("returns null when tool is not path-bearing", () => {
+    const result = gateUnderTest(
+      makeTcc({ toolName: "bash", input: { command: "ls" } }),
+      ["/test/agent"],
+    );
+    expect(result).toBeNull();
+  });
+
+  it("returns null when path is inside CWD", () => {
+    const result = gateUnderTest(
+      makeTcc({ input: { path: "/test/project/src/index.ts" } }),
+      ["/test/agent"],
+    );
+    expect(result).toBeNull();
+  });
+
+  // ── Pi infrastructure read bypass ─────────────────���────────────────────
+
+  it("returns GateBypass for read targeting an infra dir", () => {
+    const result = gateUnderTest(
+      makeTcc({
+        toolName: "read",
+        input: { path: "/test/agent/git/some-package/SKILL.md" },
+      }),
+      ["/test/agent", "/test/agent/git"],
+    );
+    expect(result).not.toBeNull();
+    expect(isGateBypass(result)).toBe(true);
+    const bypass = result as GateBypass;
+    expect(bypass.action).toBe("allow");
+    expect(bypass.decision).toMatchObject({
+      resolution: "infrastructure_auto_allowed",
+      result: "allow",
+    });
+    expect(bypass.log).toMatchObject({
+      event: "permission_request.infrastructure_auto_allowed",
+    });
+  });
+
+  it("returns GateBypass respecting custom infraDirs", () => {
+    const result = gateUnderTest(
+      makeTcc({
+        toolName: "read",
+        input: { path: "/custom/infra/SKILL.md" },
+      }),
+      ["/custom/infra"],
+    );
+    expect(isGateBypass(result)).toBe(true);
+  });
+
+  it("does NOT bypass for write tools targeting infra dirs", () => {
+    const result = gateUnderTest(
+      makeTcc({
+        toolName: "write",
+        input: { path: "/test/agent/git/some-file.ts", content: "x" },
+      }),
+      ["/test/agent", "/test/agent/git"],
+    );
+    // Should be a GateDescriptor (needs permission check), not a bypass
+    expect(result).not.toBeNull();
+    expect(isGateDescriptor(result)).toBe(true);
+  });
+
+  // ── GateDescriptor for external paths ─────────────────────────────────��
+
+  it("returns GateDescriptor with surface 'external_directory'", () => {
+    const result = gateUnderTest(makeTcc(), ["/test/agent"]);
+    expect(isGateDescriptor(result)).toBe(true);
+    const desc = result as GateDescriptor;
+    expect(desc.surface).toBe("external_directory");
+  });
+
+  it("decision value is the external path", () => {
+    const result = gateUnderTest(
+      makeTcc({ input: { path: "/outside/project/file.ts" } }),
+      ["/test/agent"],
+    ) as GateDescriptor;
+    expect(result.decision.value).toBe("/outside/project/file.ts");
+    expect(result.decision.surface).toBe("external_directory");
+  });
+
+  it("carries a precomputed preCheck and an empty input (matching is done by the gate)", () => {
+    const result = gateUnderTest(
+      makeTcc({ input: { path: "/outside/project/file.ts" } }),
+      ["/test/agent"],
+    ) as GateDescriptor;
+    expect(result.input).toEqual({});
+    expect(result.preCheck).toBeDefined();
+    expect(result.preCheck?.state).toBe("ask");
+  });
+
+  it("resolves the typed and symlink-resolved aliases on the external_directory surface (#418)", () => {
+    const resolver = makeResolver(
+      makeCheckResult({ state: "ask", toolName: "external_directory" }),
+    );
+    gateUnderTest(
+      makeTcc({ input: { path: "/outside/project/file.ts" } }),
+      ["/test/agent"],
+      undefined,
+      resolver,
+    );
+    expect(resolver.resolvePathPolicy).toHaveBeenCalledWith(
+      ["/outside/project/file.ts"],
+      undefined,
+      "external_directory",
+    );
+    expect(resolver.resolve).not.toHaveBeenCalled();
+  });
+
+  it("sessionApproval uses deriveApprovalPattern", () => {
+    const result = gateUnderTest(
+      makeTcc({ input: { path: "/outside/project/file.ts" } }),
+      ["/test/agent"],
+    ) as GateDescriptor;
+    expect(result.sessionApproval).toBeDefined();
+    expect(result.sessionApproval?.surface).toBe("external_directory");
+    expect(result.sessionApproval?.representativePattern).toBeDefined();
+  });
+
+  it("denialContext contains the external path and cwd", () => {
+    const result = gateUnderTest(
+      makeTcc({ input: { path: "/outside/project/file.ts" } }),
+      ["/test/agent"],
+    ) as GateDescriptor;
+    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", () => {
+    const result = gateUnderTest(
+      makeTcc({ toolName: "read", agentName: "agent-1", toolCallId: "tc-5" }),
+      ["/test/agent"],
+    ) as GateDescriptor;
+    expect(result.promptDetails).toMatchObject({
+      source: "tool_call",
+      agentName: "agent-1",
+      toolCallId: "tc-5",
+      toolName: "read",
+      path: "/outside/project/file.ts",
+    });
+  });
+
+  it("logContext includes path and message", () => {
+    const result = gateUnderTest(makeTcc(), ["/test/agent"]) as GateDescriptor;
+    expect(result.logContext).toMatchObject({
+      source: "tool_call",
+      path: "/outside/project/file.ts",
+    });
+    expect(result.logContext.message).toBeDefined();
+  });
+});
+
+// Extension and MCP tools are now external-directory gated (#352) ───────────
+
+describe("describeExternalDirectoryGate — extension and MCP tools (#352)", () => {
+  it("gates an extension tool with an external input.path", () => {
+    const result = gateUnderTest(
+      makeTcc({
+        toolName: "my-ext",
+        input: { path: "/outside/project/file.ts" },
+      }),
+      ["/test/agent"],
+    );
+    expect(isGateDescriptor(result)).toBe(true);
+    expect((result as GateDescriptor).surface).toBe("external_directory");
+  });
+
+  it("gates an MCP tool with an external arguments.path", () => {
+    const result = gateUnderTest(
+      makeTcc({
+        toolName: "mcp",
+        input: { arguments: { path: "/outside/project/file.ts" } },
+      }),
+      ["/test/agent"],
+    );
+    expect(isGateDescriptor(result)).toBe(true);
+  });
+
+  it("uses a registered extractor's external path for a custom-shaped tool", () => {
+    const extractors = {
+      get: (name: string) =>
+        name === "ffgrep"
+          ? (input: Record<string, unknown>) =>
+              typeof input.target === "string" ? input.target : undefined
+          : undefined,
+    };
+    const result = gateUnderTest(
+      makeTcc({ toolName: "ffgrep", input: { target: "/outside/project/x" } }),
+      ["/test/agent"],
+      extractors,
+    );
+    expect(isGateDescriptor(result)).toBe(true);
+  });
+
+  it("returns null for an extension tool whose path is inside cwd", () => {
+    const result = gateUnderTest(
+      makeTcc({
+        toolName: "my-ext",
+        input: { path: "/test/project/src/x.ts" },
+      }),
+      ["/test/agent"],
+    );
+    expect(result).toBeNull();
+  });
+});

package/test/handlers/gates/helpers.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  buildDecisionEvent,
+  deriveDecisionValue,
+  deriveResolution,
+} from "#src/handlers/gates/helpers";
+import type { PermissionCheckResult } from "#src/types";
+
+describe("deriveDecisionValue", () => {
+  it("returns command for bash", () => {
+    expect(deriveDecisionValue("bash", { command: "git status" })).toBe(
+      "git status",
+    );
+  });
+
+  it("falls back to toolName when bash has no command", () => {
+    expect(deriveDecisionValue("bash", {})).toBe("bash");
+  });
+
+  it("returns target for mcp", () => {
+    expect(deriveDecisionValue("mcp", { target: "exa:search" })).toBe(
+      "exa:search",
+    );
+  });
+
+  it("falls back to toolName when mcp has no target", () => {
+    expect(deriveDecisionValue("mcp", {})).toBe("mcp");
+  });
+
+  it("returns toolName for non-path-bearing tools", () => {
+    expect(deriveDecisionValue("my_extension_tool", {})).toBe(
+      "my_extension_tool",
+    );
+  });
+
+  it("returns path for path-bearing tools when path is provided", () => {
+    expect(deriveDecisionValue("read", {}, "/project/src/main.ts")).toBe(
+      "/project/src/main.ts",
+    );
+    expect(deriveDecisionValue("write", {}, "src/.env")).toBe("src/.env");
+  });
+
+  it("falls back to toolName for path-bearing tools when path is missing", () => {
+    expect(deriveDecisionValue("read", {})).toBe("read");
+    expect(deriveDecisionValue("write", {}, undefined)).toBe("write");
+  });
+});
+
+describe("deriveResolution", () => {
+  it("returns policy_allow for allow state", () => {
+    expect(deriveResolution("allow", "allow", false, true)).toBe(
+      "policy_allow",
+    );
+  });
+
+  it("returns policy_deny for deny state", () => {
+    expect(deriveResolution("deny", "block", false, true)).toBe("policy_deny");
+  });
+
+  it("returns user_approved for ask + allow without session", () => {
+    expect(deriveResolution("ask", "allow", false, true)).toBe("user_approved");
+  });
+
+  it("returns user_approved_for_session for ask + allow with session", () => {
+    expect(deriveResolution("ask", "allow", true, true)).toBe(
+      "user_approved_for_session",
+    );
+  });
+
+  it("returns auto_approved when autoApproved flag is set", () => {
+    expect(deriveResolution("ask", "allow", false, true, true)).toBe(
+      "auto_approved",
+    );
+  });
+
+  it("returns user_approved_for_project for project persistent approval", () => {
+    expect(deriveResolution("ask", "allow", false, true, false, "project")).toBe(
+      "user_approved_for_project",
+    );
+  });
+
+  it("returns user_approved_globally for global persistent approval", () => {
+    expect(deriveResolution("ask", "allow", false, true, false, "global")).toBe(
+      "user_approved_globally",
+    );
+  });
+
+  it("returns user_denied for ask + block with canConfirm", () => {
+    expect(deriveResolution("ask", "block", false, true)).toBe("user_denied");
+  });
+
+  it("returns confirmation_unavailable for ask + block without canConfirm", () => {
+    expect(deriveResolution("ask", "block", false, false)).toBe(
+      "confirmation_unavailable",
+    );
+  });
+});
+
+describe("buildDecisionEvent", () => {
+  function makeCheck(
+    overrides: Partial<PermissionCheckResult> = {},
+  ): PermissionCheckResult {
+    return {
+      state: "allow",
+      toolName: "read",
+      source: "tool",
+      origin: "builtin",
+      matchedPattern: "*",
+      ...overrides,
+    };
+  }
+
+  it("builds a decision event with all fields populated", () => {
+    const event = buildDecisionEvent(
+      { surface: "read", value: "read" },
+      makeCheck({ origin: "global", matchedPattern: "read" }),
+      "test-agent",
+      "allow",
+      "policy_allow",
+    );
+    expect(event).toEqual({
+      surface: "read",
+      value: "read",
+      result: "allow",
+      resolution: "policy_allow",
+      origin: "global",
+      agentName: "test-agent",
+      matchedPattern: "read",
+    });
+  });
+
+  it("normalises undefined origin to null", () => {
+    const event = buildDecisionEvent(
+      { surface: "bash", value: "git status" },
+      makeCheck({ origin: undefined }),
+      null,
+      "allow",
+      "user_approved",
+    );
+    expect(event.origin).toBeNull();
+  });
+
+  it("normalises null agentName to null", () => {
+    const event = buildDecisionEvent(
+      { surface: "read", value: "read" },
+      makeCheck(),
+      null,
+      "deny",
+      "policy_deny",
+    );
+    expect(event.agentName).toBeNull();
+  });
+
+  it("normalises undefined matchedPattern to null", () => {
+    const event = buildDecisionEvent(
+      { surface: "read", value: "read" },
+      makeCheck({ matchedPattern: undefined }),
+      null,
+      "deny",
+      "policy_deny",
+    );
+    expect(event.matchedPattern).toBeNull();
+  });
+
+  it("passes result and resolution through", () => {
+    const event = buildDecisionEvent(
+      { surface: "bash", value: "rm -rf /" },
+      makeCheck(),
+      null,
+      "deny",
+      "user_denied",
+    );
+    expect(event.result).toBe("deny");
+    expect(event.resolution).toBe("user_denied");
+  });
+});