@komarspn/pi-permission-system 16.0.2

package/test/handlers/lifecycle.test.ts

@@ -0,0 +1,221 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { SessionLifecycleHandler } from "#src/handlers/lifecycle";
+import type { ServiceLifecycle } from "#src/service-lifecycle";
+
+import { makeCtx } from "#test/helpers/handler-fixtures";
+import {
+  makeLogger,
+  makeRealResolver,
+  makeRealSession,
+} from "#test/helpers/session-fixtures";
+
+// ── status stub ────────────────────────────────────────────────────────────
+vi.mock("../../src/status", () => ({
+  PERMISSION_SYSTEM_STATUS_KEY: "permission-system",
+  syncPermissionSystemStatus: vi.fn(),
+  getPermissionSystemStatus: vi.fn(),
+}));
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function makeSetup(opts?: { configIssues?: string[] }) {
+  const { session, permissionManager, sessionRules, forwarding, configStore } =
+    makeRealSession();
+  const { resolver } = makeRealResolver(permissionManager, sessionRules);
+  if (opts?.configIssues) {
+    vi.mocked(permissionManager.getConfigIssues).mockReturnValue(
+      opts.configIssues,
+    );
+  }
+  const serviceLifecycle: ServiceLifecycle = {
+    activate: vi.fn<ServiceLifecycle["activate"]>(),
+    teardown: vi.fn<ServiceLifecycle["teardown"]>(),
+  };
+  // 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,
+    session,
+    resolver,
+    permissionManager,
+    logger,
+    forwarding,
+    configStore,
+    serviceLifecycle,
+    audit,
+  };
+}
+
+// ── handleSessionStart ─────────────────────────────────────────────────────
+
+describe("handleSessionStart", () => {
+  it("refreshes config with ctx", async () => {
+    const ctx = makeCtx();
+    const { handler, configStore } = makeSetup();
+    await handler.handleSessionStart({ reason: "startup" }, ctx);
+    expect(configStore.refresh).toHaveBeenCalledWith(ctx);
+  });
+
+  it("calls resetForNewSession with ctx", async () => {
+    const ctx = makeCtx();
+    const { handler, session } = makeSetup();
+    const spy = vi.spyOn(session, "resetForNewSession");
+    await handler.handleSessionStart({ reason: "startup" }, ctx);
+    expect(spy).toHaveBeenCalledWith(ctx);
+  });
+
+  it("logs resolved config paths", async () => {
+    const { handler, configStore } = makeSetup();
+    await handler.handleSessionStart({ reason: "startup" }, makeCtx());
+    expect(configStore.logResolvedPaths).toHaveBeenCalledOnce();
+  });
+
+  it("resolves agent name from ctx", async () => {
+    const ctx = makeCtx();
+    const { handler, session } = makeSetup();
+    const spy = vi.spyOn(session, "resolveAgentName");
+    await handler.handleSessionStart({ reason: "startup" }, ctx);
+    expect(spy).toHaveBeenCalledWith(ctx);
+  });
+
+  it("notifies each policy issue", async () => {
+    const { handler, logger } = makeSetup({
+      configIssues: ["issue A", "issue B"],
+    });
+    await handler.handleSessionStart({ reason: "startup" }, makeCtx());
+    expect(logger.warn).toHaveBeenCalledWith("issue A");
+    expect(logger.warn).toHaveBeenCalledWith("issue B");
+  });
+
+  it("does not warn when there are no policy issues", async () => {
+    const { handler, logger } = makeSetup();
+    await handler.handleSessionStart({ reason: "startup" }, makeCtx());
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it("writes lifecycle.reload debug log when reason is reload", async () => {
+    const ctx = makeCtx({ cwd: "/proj" });
+    const { handler, logger } = makeSetup();
+    await handler.handleSessionStart({ reason: "reload" }, ctx);
+    expect(logger.debug).toHaveBeenCalledWith("lifecycle.reload", {
+      triggeredBy: "session_start",
+      reason: "reload",
+      cwd: "/proj",
+    });
+  });
+
+  it("does not write lifecycle.reload debug log for non-reload reasons", async () => {
+    const { handler, logger } = makeSetup();
+    await handler.handleSessionStart({ reason: "startup" }, makeCtx());
+    expect(logger.debug).not.toHaveBeenCalled();
+  });
+
+  it("activates the service for the session with ctx", async () => {
+    const ctx = makeCtx();
+    const { handler, serviceLifecycle } = makeSetup();
+    await handler.handleSessionStart({ reason: "startup" }, ctx);
+    expect(serviceLifecycle.activate).toHaveBeenCalledWith(ctx);
+  });
+
+  it("calls refreshConfig before resetForNewSession", async () => {
+    const callOrder: string[] = [];
+    const { handler, session, configStore } = makeSetup();
+    vi.spyOn(configStore, "refresh").mockImplementation(() => {
+      callOrder.push("refreshConfig");
+    });
+    vi.spyOn(session, "resetForNewSession").mockImplementation(() => {
+      callOrder.push("resetForNewSession");
+    });
+    await handler.handleSessionStart({ reason: "startup" }, makeCtx());
+    expect(callOrder).toEqual(["refreshConfig", "resetForNewSession"]);
+  });
+});
+
+// ── handleResourcesDiscover ────────────────────────────────────────────────
+
+describe("handleResourcesDiscover", () => {
+  it("does nothing when reason is not reload", async () => {
+    const { handler, session } = makeSetup();
+    const spy = vi.spyOn(session, "reload");
+    await handler.handleResourcesDiscover({ reason: "startup" });
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it("calls reload on the session on reload", async () => {
+    const { handler, session } = makeSetup();
+    const spy = vi.spyOn(session, "reload");
+    await handler.handleResourcesDiscover({ reason: "reload" });
+    expect(spy).toHaveBeenCalledOnce();
+  });
+
+  it("writes lifecycle.reload debug log on reload", async () => {
+    const ctx = makeCtx({ cwd: "/proj" });
+    const { handler, session, logger } = makeSetup();
+    session.activate(ctx);
+    await handler.handleResourcesDiscover({ reason: "reload" });
+    expect(logger.debug).toHaveBeenCalledWith("lifecycle.reload", {
+      triggeredBy: "resources_discover",
+      reason: "reload",
+      cwd: "/proj",
+    });
+  });
+
+  it("logs cwd as null when runtimeContext is null on reload", async () => {
+    const { handler, logger } = makeSetup();
+    await handler.handleResourcesDiscover({ reason: "reload" });
+    expect(logger.debug).toHaveBeenCalledWith("lifecycle.reload", {
+      triggeredBy: "resources_discover",
+      reason: "reload",
+      cwd: null,
+    });
+  });
+});
+
+// ── handleSessionShutdown ──────────────────────────────────────────────────
+
+describe("handleSessionShutdown", () => {
+  it("clears UI status when runtime context is present", async () => {
+    const ctx = makeCtx();
+    const { handler, session } = makeSetup();
+    session.activate(ctx);
+    await handler.handleSessionShutdown();
+    expect(ctx.ui.setStatus).toHaveBeenCalledWith(
+      "permission-system",
+      undefined,
+    );
+  });
+
+  it("does not throw when runtime context is null", async () => {
+    const { handler } = makeSetup();
+    await expect(handler.handleSessionShutdown()).resolves.not.toThrow();
+  });
+
+  it("calls shutdown on the session", async () => {
+    const { handler, session } = makeSetup();
+    const spy = vi.spyOn(session, "shutdown");
+    await handler.handleSessionShutdown();
+    expect(spy).toHaveBeenCalledOnce();
+  });
+
+  it("calls serviceLifecycle.teardown", async () => {
+    const { handler, serviceLifecycle } = makeSetup();
+    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",
+      }),
+    );
+  });
+});

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

@@ -0,0 +1,277 @@
+/**
+ * Tests that handleToolCall emits permissions:decision events at every
+ * gate resolution and fast-path site.
+ */
+import { describe, expect, it, vi } from "vitest";
+
+import type { GatePrompter } from "#src/gate-prompter";
+import {
+  getDecisionEvents,
+  makeCheckResult,
+  makeCtx,
+  makeHandler,
+  makeToolCallEvent,
+} from "#test/helpers/handler-fixtures";
+
+// ── policy_allow path ──────────────────────────────────────────────────────
+
+describe("handleToolCall decision events — policy_allow", () => {
+  it("emits allow with policy_allow when checkPermission returns allow", async () => {
+    const { handler, events } = makeHandler({
+      session: {
+        checkPermission: vi.fn().mockReturnValue(
+          makeCheckResult({
+            state: "allow",
+            origin: "global",
+            matchedPattern: "*",
+          }),
+        ),
+      },
+    });
+
+    await handler.handleToolCall(makeToolCallEvent("read"), makeCtx());
+
+    const decisions = getDecisionEvents(events);
+    expect(decisions).toHaveLength(1);
+    expect(decisions[0]).toMatchObject({
+      surface: "read",
+      result: "allow",
+      resolution: "policy_allow",
+      origin: "global",
+      matchedPattern: "*",
+    });
+  });
+});
+
+// ── policy_deny path ───────────────────────────────────────────────────────
+
+describe("handleToolCall decision events — policy_deny", () => {
+  it("emits deny with policy_deny when checkPermission returns deny", async () => {
+    const { handler, events } = makeHandler({
+      session: {
+        checkPermission: vi.fn().mockReturnValue(
+          makeCheckResult({
+            state: "deny",
+            origin: "project",
+            matchedPattern: "read",
+          }),
+        ),
+      },
+    });
+
+    await handler.handleToolCall(makeToolCallEvent("read"), makeCtx());
+
+    const decisions = getDecisionEvents(events);
+    expect(decisions).toHaveLength(1);
+    expect(decisions[0]).toMatchObject({
+      surface: "read",
+      result: "deny",
+      resolution: "policy_deny",
+    });
+  });
+});
+
+// ── session_approved fast path ─────────────────────────────────────────────
+
+describe("handleToolCall decision events — session_approved", () => {
+  it("emits allow with session_approved when checkPermission returns source:session", async () => {
+    const { handler, events } = makeHandler({
+      session: {
+        checkPermission: vi.fn().mockReturnValue(
+          makeCheckResult({
+            state: "allow",
+            source: "session",
+            matchedPattern: "git *",
+          }),
+        ),
+      },
+    });
+
+    await handler.handleToolCall(
+      makeToolCallEvent("bash", { input: { command: "git status" } }),
+      makeCtx(),
+    );
+
+    const decisions = getDecisionEvents(events);
+    expect(decisions).toHaveLength(1);
+    expect(decisions[0]).toMatchObject({
+      surface: "bash",
+      result: "allow",
+      resolution: "session_approved",
+    });
+  });
+});
+
+// ── user_approved path ─────────────────────────────────────────────────────
+
+describe("handleToolCall decision events — user_approved", () => {
+  it("emits allow with user_approved when state=ask and user approves once", async () => {
+    const { handler, events } = makeHandler({
+      session: {
+        checkPermission: vi
+          .fn()
+          .mockReturnValue(makeCheckResult({ state: "ask" })),
+      },
+      prompter: {
+        canConfirm: vi.fn().mockReturnValue(true),
+        prompt: vi
+          .fn<GatePrompter["prompt"]>()
+          .mockResolvedValue({ approved: true, state: "approved" }),
+      },
+    });
+
+    await handler.handleToolCall(makeToolCallEvent("read"), makeCtx());
+
+    const decisions = getDecisionEvents(events);
+    expect(decisions).toHaveLength(1);
+    expect(decisions[0]).toMatchObject({
+      result: "allow",
+      resolution: "user_approved",
+    });
+  });
+
+  it("emits allow with user_approved_for_session when user approves for session", async () => {
+    const { handler, events } = makeHandler({
+      session: {
+        checkPermission: vi
+          .fn()
+          .mockReturnValue(makeCheckResult({ state: "ask" })),
+      },
+      prompter: {
+        canConfirm: vi.fn().mockReturnValue(true),
+        prompt: vi.fn<GatePrompter["prompt"]>().mockResolvedValue({
+          approved: true,
+          state: "approved_for_session",
+        }),
+      },
+    });
+
+    await handler.handleToolCall(makeToolCallEvent("read"), makeCtx());
+
+    const decisions = getDecisionEvents(events);
+    expect(decisions).toHaveLength(1);
+    expect(decisions[0]).toMatchObject({
+      result: "allow",
+      resolution: "user_approved_for_session",
+    });
+  });
+});
+
+// ── user_denied path ───────────────────────────────────────────────────────
+
+describe("handleToolCall decision events — user_denied", () => {
+  it("emits deny with user_denied when state=ask and user denies", async () => {
+    const { handler, events } = makeHandler({
+      session: {
+        checkPermission: vi
+          .fn()
+          .mockReturnValue(makeCheckResult({ state: "ask" })),
+      },
+      prompter: {
+        canConfirm: vi.fn().mockReturnValue(true),
+        prompt: vi
+          .fn<GatePrompter["prompt"]>()
+          .mockResolvedValue({ approved: false, state: "denied" }),
+      },
+    });
+
+    await handler.handleToolCall(makeToolCallEvent("read"), makeCtx());
+
+    const decisions = getDecisionEvents(events);
+    expect(decisions).toHaveLength(1);
+    expect(decisions[0]).toMatchObject({
+      result: "deny",
+      resolution: "user_denied",
+    });
+  });
+});
+
+// ── confirmation_unavailable path ──────────────────────────────────────────
+
+describe("handleToolCall decision events — confirmation_unavailable", () => {
+  it("emits deny with confirmation_unavailable when state=ask but no UI", async () => {
+    const { handler, events } = makeHandler({
+      session: {
+        checkPermission: vi
+          .fn()
+          .mockReturnValue(makeCheckResult({ state: "ask" })),
+      },
+      prompter: {
+        canConfirm: vi.fn().mockReturnValue(false),
+        prompt: vi.fn<GatePrompter["prompt"]>(),
+      },
+    });
+
+    await handler.handleToolCall(
+      makeToolCallEvent("read"),
+      makeCtx({ hasUI: false }),
+    );
+
+    const decisions = getDecisionEvents(events);
+    expect(decisions).toHaveLength(1);
+    expect(decisions[0]).toMatchObject({
+      result: "deny",
+      resolution: "confirmation_unavailable",
+    });
+  });
+});
+
+// ── infrastructure_auto_allowed path ──────────────────────────────────────
+
+describe("handleToolCall decision events — infrastructure_auto_allowed", () => {
+  it("emits allow with infrastructure_auto_allowed for Pi infra reads", async () => {
+    const infraDir = "/test/agent";
+    const { handler, events } = makeHandler({
+      session: {
+        checkPermission: vi.fn().mockReturnValue(makeCheckResult()),
+        getInfrastructureReadDirs: vi.fn().mockReturnValue([infraDir]),
+      },
+    });
+
+    const event = makeToolCallEvent("read", {
+      input: { path: `${infraDir}/some-file.json` },
+    });
+    await handler.handleToolCall(event, makeCtx());
+
+    const decisions = getDecisionEvents(events);
+    const infraEvents = decisions.filter(
+      (e) => e.resolution === "infrastructure_auto_allowed",
+    );
+    expect(infraEvents).toHaveLength(1);
+    expect(infraEvents[0]).toMatchObject({
+      result: "allow",
+      resolution: "infrastructure_auto_allowed",
+    });
+  });
+});
+
+// ── auto_approved path (yolo mode) ───────────────────────────────────
+
+describe("handleToolCall decision events — auto_approved", () => {
+  it("emits allow with auto_approved when prompt returns autoApproved:true", async () => {
+    const { handler, events } = makeHandler({
+      session: {
+        checkPermission: vi
+          .fn()
+          .mockReturnValue(makeCheckResult({ state: "ask" })),
+      },
+      prompter: {
+        canConfirm: vi.fn().mockReturnValue(true),
+        prompt: vi.fn<GatePrompter["prompt"]>().mockResolvedValue({
+          approved: true,
+          state: "approved",
+          autoApproved: true,
+        }),
+      },
+    });
+
+    await handler.handleToolCall(makeToolCallEvent("read"), makeCtx());
+
+    const decisions = getDecisionEvents(events);
+    expect(decisions).toHaveLength(1);
+    expect(decisions[0]).toMatchObject({
+      result: "allow",
+      resolution: "auto_approved",
+    });
+  });
+});