@komarspn/pi-permission-system 16.0.2

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

@@ -0,0 +1,223 @@
+import { describe, expect, it } from "vitest";
+
+import { describeToolGate } from "#src/handlers/gates/tool";
+import type { ToolCallContext } from "#src/handlers/gates/types";
+import {
+  TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH,
+  TOOL_INPUT_PREVIEW_MAX_LENGTH,
+  TOOL_TEXT_SUMMARY_MAX_LENGTH,
+} from "#src/tool-input-preview";
+import { ToolPreviewFormatter } from "#src/tool-preview-formatter";
+import type { PermissionCheckResult } from "#src/types";
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function makeFormatter(): ToolPreviewFormatter {
+  return new ToolPreviewFormatter({
+    toolInputPreviewMaxLength: TOOL_INPUT_PREVIEW_MAX_LENGTH,
+    toolTextSummaryMaxLength: TOOL_TEXT_SUMMARY_MAX_LENGTH,
+    toolInputLogPreviewMaxLength: TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH,
+  });
+}
+
+function makeTcc(overrides: Partial<ToolCallContext> = {}): ToolCallContext {
+  return {
+    toolName: "read",
+    agentName: null,
+    input: {},
+    toolCallId: "tc-1",
+    cwd: "/test/project",
+    ...overrides,
+  };
+}
+
+function makeCheckResult(
+  state: "allow" | "deny" | "ask",
+  overrides: Partial<PermissionCheckResult> = {},
+): PermissionCheckResult {
+  return {
+    state,
+    toolName: "read",
+    source: "tool",
+    origin: "builtin",
+    matchedPattern: "*",
+    ...overrides,
+  };
+}
+
+// ── tests ──────────────────────────────────────────────────────────────────
+
+describe("describeToolGate", () => {
+  it("returns descriptor with tool name as surface for standard tools", () => {
+    const desc = describeToolGate(
+      makeTcc({ toolName: "read" }),
+      makeCheckResult("ask"),
+      makeFormatter(),
+    );
+    expect(desc.surface).toBe("read");
+    expect(desc.decision.surface).toBe("read");
+  });
+
+  it("returns descriptor with tool name as decision value for standard tools", () => {
+    const desc = describeToolGate(
+      makeTcc({ toolName: "write" }),
+      makeCheckResult("ask"),
+      makeFormatter(),
+    );
+    expect(desc.decision.value).toBe("write");
+  });
+
+  it("returns bash surface with command in decision.value for bash tools", () => {
+    const check = makeCheckResult("ask", {
+      toolName: "bash",
+      command: "git status",
+    });
+    const desc = describeToolGate(
+      makeTcc({ toolName: "bash", input: { command: "git status" } }),
+      check,
+      makeFormatter(),
+    );
+    expect(desc.surface).toBe("bash");
+    expect(desc.decision.surface).toBe("bash");
+    expect(desc.decision.value).toBe("git status");
+  });
+
+  it("returns mcp surface with target in decision.value for MCP tools", () => {
+    const check = makeCheckResult("ask", {
+      toolName: "mcp",
+      target: "server:tool",
+    });
+    const desc = describeToolGate(
+      makeTcc({ toolName: "mcp", input: { tool: "server:tool" } }),
+      check,
+      makeFormatter(),
+    );
+    expect(desc.surface).toBe("mcp");
+    expect(desc.decision.surface).toBe("mcp");
+    expect(desc.decision.value).toBe("server:tool");
+  });
+
+  it("populates denialContext with kind 'tool' and check result", () => {
+    const check = makeCheckResult("deny", { toolName: "read" });
+    const desc = describeToolGate(makeTcc(), check, makeFormatter());
+    expect(desc.denialContext).toEqual({
+      kind: "tool",
+      check,
+      agentName: undefined,
+      input: {},
+    });
+  });
+
+  it("populates denialContext with agent name when provided", () => {
+    const check = makeCheckResult("ask", { toolName: "read" });
+    const desc = describeToolGate(
+      makeTcc({ agentName: "my-agent" }),
+      check,
+      makeFormatter(),
+    );
+    expect(desc.denialContext.agentName).toBe("my-agent");
+  });
+
+  it("populates denialContext with input for tool context", () => {
+    const check = makeCheckResult("ask", { toolName: "bash", command: "ls" });
+    const desc = describeToolGate(
+      makeTcc({ toolName: "bash", input: { command: "ls" } }),
+      check,
+      makeFormatter(),
+    );
+    expect(desc.denialContext).toMatchObject({
+      kind: "tool",
+      input: { command: "ls" },
+    });
+  });
+
+  it("populates sessionApproval via suggestSessionPattern", () => {
+    const check = makeCheckResult("ask", {
+      toolName: "bash",
+      command: "git status",
+    });
+    const desc = describeToolGate(
+      makeTcc({ toolName: "bash", input: { command: "git status" } }),
+      check,
+      makeFormatter(),
+    );
+    expect(desc.sessionApproval).toBeDefined();
+    expect(desc.sessionApproval?.surface).toBe("bash");
+    expect(desc.sessionApproval?.representativePattern).toBeDefined();
+  });
+
+  it("binds a current-directory file's session approval to the cwd subtree", () => {
+    const check = makeCheckResult("ask", { toolName: "edit" });
+    const desc = describeToolGate(
+      makeTcc({
+        toolName: "edit",
+        input: { path: "index.html" },
+        cwd: "/test/project",
+      }),
+      check,
+      makeFormatter(),
+    );
+    expect(desc.sessionApproval?.surface).toBe("edit");
+    expect(desc.sessionApproval?.representativePattern).toBe("/test/project/*");
+  });
+
+  it("resolves a sub-directory file's session approval to an absolute pattern", () => {
+    // Resolve-at-gate canonicalizes every path (not just the cwd-root case),
+    // so sub-directory approvals are absolute too — the deliberate tradeoff
+    // that keeps the pattern aligned with the policy values it is matched against.
+    const check = makeCheckResult("ask", { toolName: "edit" });
+    const desc = describeToolGate(
+      makeTcc({
+        toolName: "edit",
+        input: { path: "src/foo.ts" },
+        cwd: "/test/project",
+      }),
+      check,
+      makeFormatter(),
+    );
+    expect(desc.sessionApproval?.representativePattern).toBe(
+      "/test/project/src/*",
+    );
+  });
+
+  it("populates promptDetails with correct fields", () => {
+    const check = makeCheckResult("ask");
+    const desc = describeToolGate(
+      makeTcc({ toolName: "read", agentName: "my-agent", toolCallId: "tc-42" }),
+      check,
+      makeFormatter(),
+    );
+    expect(desc.promptDetails).toMatchObject({
+      source: "tool_call",
+      agentName: "my-agent",
+      toolCallId: "tc-42",
+      toolName: "read",
+    });
+    expect(desc.promptDetails.message).toBeDefined();
+    expect(desc.promptDetails.sessionLabel).toBeDefined();
+  });
+
+  it("populates logContext with tool input preview fields", () => {
+    const check = makeCheckResult("ask", { toolName: "bash", command: "ls" });
+    const desc = describeToolGate(
+      makeTcc({ toolName: "bash", input: { command: "ls" } }),
+      check,
+      makeFormatter(),
+    );
+    expect(desc.logContext).toMatchObject({
+      source: "tool_call",
+      toolName: "bash",
+    });
+    expect(desc.logContext.command).toBe("ls");
+  });
+
+  it("uses toolName as input for checkPermission surface", () => {
+    const desc = describeToolGate(
+      makeTcc({ toolName: "edit", input: { path: "/a.ts" } }),
+      makeCheckResult("ask", { toolName: "edit" }),
+      makeFormatter(),
+    );
+    expect(desc.surface).toBe("edit");
+    expect(desc.input).toEqual({ path: "/a.ts" });
+  });
+});

package/test/handlers/input-events.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Tests that handleInput emits permissions:decision events for skill input gates.
+ */
+import { describe, expect, it, vi } from "vitest";
+
+import type { GatePrompter } from "#src/gate-prompter";
+import {
+  getDecisionEvents,
+  makeCheckResult,
+  makeCtx,
+  makeHandler,
+} from "#test/helpers/handler-fixtures";
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+/** Build a checkPermission mock returning a skill-surface result. */
+function makeSkillCheckPermission(state: "allow" | "deny" | "ask") {
+  return vi.fn().mockReturnValue(
+    makeCheckResult({
+      state,
+      toolName: "skill",
+      source: "skill",
+      origin: "global",
+      matchedPattern: "*",
+    }),
+  );
+}
+
+// ── tests ──────────────────────────────────────────────────────────────────
+
+describe("handleInput decision events — skill gate", () => {
+  it("does not emit when input is not a skill invocation", async () => {
+    const { handler, events } = makeHandler();
+    await handler.handleInput({ text: "hello world" }, makeCtx());
+    expect(getDecisionEvents(events)).toHaveLength(0);
+  });
+
+  it("emits allow with policy_allow for an allowed skill", async () => {
+    const { handler, events } = makeHandler({
+      session: { checkPermission: makeSkillCheckPermission("allow") },
+    });
+    await handler.handleInput({ text: "/skill:librarian" }, makeCtx());
+
+    const decisions = getDecisionEvents(events);
+    expect(decisions).toHaveLength(1);
+    expect(decisions[0]).toMatchObject({
+      surface: "skill",
+      value: "librarian",
+      result: "allow",
+      resolution: "policy_allow",
+    });
+  });
+
+  it("emits deny with policy_deny for a denied skill", async () => {
+    const { handler, events } = makeHandler({
+      session: { checkPermission: makeSkillCheckPermission("deny") },
+    });
+    await handler.handleInput({ text: "/skill:restricted" }, makeCtx());
+
+    const decisions = getDecisionEvents(events);
+    expect(decisions).toHaveLength(1);
+    expect(decisions[0]).toMatchObject({
+      surface: "skill",
+      value: "restricted",
+      result: "deny",
+      resolution: "policy_deny",
+    });
+  });
+
+  it("emits allow with user_approved when state=ask and user approves", async () => {
+    const { handler, events } = makeHandler({
+      session: {
+        checkPermission: makeSkillCheckPermission("ask"),
+      },
+      prompter: {
+        canConfirm: vi.fn().mockReturnValue(true),
+        prompt: vi
+          .fn<GatePrompter["prompt"]>()
+          .mockResolvedValue({ approved: true, state: "approved" }),
+      },
+    });
+    await handler.handleInput({ text: "/skill:explorer" }, makeCtx());
+
+    const decisions = getDecisionEvents(events);
+    expect(decisions).toHaveLength(1);
+    expect(decisions[0]).toMatchObject({
+      surface: "skill",
+      value: "explorer",
+      result: "allow",
+      resolution: "user_approved",
+    });
+  });
+
+  it("emits deny with user_denied when state=ask and user denies", async () => {
+    const { handler, events } = makeHandler({
+      session: {
+        checkPermission: makeSkillCheckPermission("ask"),
+      },
+      prompter: {
+        canConfirm: vi.fn().mockReturnValue(true),
+        prompt: vi
+          .fn<GatePrompter["prompt"]>()
+          .mockResolvedValue({ approved: false, state: "denied" }),
+      },
+    });
+    await handler.handleInput({ text: "/skill:explorer" }, makeCtx());
+
+    const decisions = getDecisionEvents(events);
+    expect(decisions).toHaveLength(1);
+    expect(decisions[0]).toMatchObject({
+      surface: "skill",
+      value: "explorer",
+      result: "deny",
+      resolution: "user_denied",
+    });
+  });
+
+  it("emits deny with confirmation_unavailable when state=ask but no UI", async () => {
+    const { handler, events } = makeHandler({
+      session: {
+        checkPermission: makeSkillCheckPermission("ask"),
+      },
+      prompter: {
+        canConfirm: vi.fn().mockReturnValue(false),
+        prompt: vi.fn<GatePrompter["prompt"]>(),
+      },
+    });
+    await handler.handleInput(
+      { text: "/skill:explorer" },
+      makeCtx({ hasUI: false }),
+    );
+
+    const decisions = getDecisionEvents(events);
+    expect(decisions).toHaveLength(1);
+    expect(decisions[0]).toMatchObject({
+      surface: "skill",
+      value: "explorer",
+      result: "deny",
+      resolution: "confirmation_unavailable",
+    });
+  });
+
+  it("emits allow with auto_approved when prompt returns autoApproved:true", async () => {
+    const { handler, events } = makeHandler({
+      session: {
+        checkPermission: makeSkillCheckPermission("ask"),
+      },
+      prompter: {
+        canConfirm: vi.fn().mockReturnValue(true),
+        prompt: vi.fn<GatePrompter["prompt"]>().mockResolvedValue({
+          approved: true,
+          state: "approved",
+          autoApproved: true,
+        }),
+      },
+    });
+    await handler.handleInput({ text: "/skill:explorer" }, makeCtx());
+
+    const decisions = getDecisionEvents(events);
+    expect(decisions).toHaveLength(1);
+    expect(decisions[0]).toMatchObject({
+      surface: "skill",
+      value: "explorer",
+      result: "allow",
+      resolution: "auto_approved",
+    });
+  });
+});

package/test/handlers/input.test.ts

@@ -0,0 +1,199 @@
+import { describe, expect, it, vi } from "vitest";
+import type { GatePrompter } from "#src/gate-prompter";
+import { extractSkillNameFromInput } from "#src/handlers/permission-gate-handler";
+
+import { makeCtx, makeHandler } from "#test/helpers/handler-fixtures";
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function makeInputEvent(text: string) {
+  return { text };
+}
+
+// ── extractSkillNameFromInput ──────────────────────────────────────────────
+
+describe("extractSkillNameFromInput", () => {
+  it("returns null for plain text", () => {
+    expect(extractSkillNameFromInput("hello world")).toBeNull();
+  });
+
+  it("returns null for empty string", () => {
+    expect(extractSkillNameFromInput("")).toBeNull();
+  });
+
+  it("returns null for bare /skill: with no name", () => {
+    expect(extractSkillNameFromInput("/skill:")).toBeNull();
+  });
+
+  it("extracts skill name from /skill:<name>", () => {
+    expect(extractSkillNameFromInput("/skill:librarian")).toBe("librarian");
+  });
+
+  it("extracts skill name stopping at whitespace", () => {
+    expect(extractSkillNameFromInput("/skill:librarian some extra")).toBe(
+      "librarian",
+    );
+  });
+
+  it("trims leading whitespace before the prefix", () => {
+    expect(extractSkillNameFromInput("  /skill:my-skill")).toBe("my-skill");
+  });
+
+  it("returns null when the skill name after trimming is empty", () => {
+    expect(extractSkillNameFromInput("/skill: ")).toBeNull();
+  });
+});
+
+// ── handleInput ───────────────────────────────────────────────────────────
+
+describe("handleInput", () => {
+  it("activates session with ctx", async () => {
+    const ctx = makeCtx();
+    const { handler, forwarding } = makeHandler();
+    await handler.handleInput(makeInputEvent("hello"), ctx);
+    // session.activate(ctx) calls forwarding.start(ctx) on the real session
+    expect(forwarding.start).toHaveBeenCalledWith(ctx);
+  });
+
+  it("returns continue for non-skill input", async () => {
+    const { handler } = makeHandler();
+    const result = await handler.handleInput(
+      makeInputEvent("just a message"),
+      makeCtx(),
+    );
+    expect(result).toEqual({ action: "continue" });
+  });
+
+  it("does not check permissions for non-skill input", async () => {
+    const { handler, permissionManager } = makeHandler();
+    await handler.handleInput(makeInputEvent("just a message"), makeCtx());
+    expect(permissionManager.checkPermission).not.toHaveBeenCalled();
+  });
+
+  it("returns continue when skill is allowed", async () => {
+    const { handler } = makeHandler();
+    const result = await handler.handleInput(
+      makeInputEvent("/skill:librarian"),
+      makeCtx(),
+    );
+    expect(result).toEqual({ action: "continue" });
+  });
+
+  it("returns handled when skill is denied", async () => {
+    const { handler } = makeHandler({
+      session: {
+        checkPermission: vi.fn().mockReturnValue({ state: "deny" }),
+      },
+    });
+    const result = await handler.handleInput(
+      makeInputEvent("/skill:librarian"),
+      makeCtx(),
+    );
+    expect(result).toEqual({ action: "handled" });
+  });
+
+  it("shows a warning notification when skill is denied and UI is available", async () => {
+    const ctx = makeCtx({ hasUI: true });
+    const { handler } = makeHandler({
+      session: {
+        checkPermission: vi.fn().mockReturnValue({ state: "deny" }),
+      },
+    });
+    await handler.handleInput(makeInputEvent("/skill:librarian"), ctx);
+    expect(ctx.ui.notify).toHaveBeenCalledWith(
+      expect.stringContaining("librarian"),
+      "warning",
+    );
+  });
+
+  it("does not show a warning notification when skill is denied and UI is absent", async () => {
+    const ctx = makeCtx({ hasUI: false });
+    const { handler } = makeHandler({
+      session: {
+        checkPermission: vi.fn().mockReturnValue({ state: "deny" }),
+      },
+    });
+    await handler.handleInput(makeInputEvent("/skill:librarian"), ctx);
+    expect(ctx.ui.notify).not.toHaveBeenCalled();
+  });
+
+  it("returns handled when skill requires approval but no UI is available", async () => {
+    const { handler } = makeHandler({
+      session: {
+        checkPermission: vi.fn().mockReturnValue({ state: "ask" }),
+      },
+      prompter: {
+        canConfirm: vi.fn().mockReturnValue(false),
+        prompt: vi.fn<GatePrompter["prompt"]>(),
+      },
+    });
+    const result = await handler.handleInput(
+      makeInputEvent("/skill:librarian"),
+      makeCtx(),
+    );
+    expect(result).toEqual({ action: "handled" });
+  });
+
+  it("prompts and returns continue when skill ask is approved", async () => {
+    const approvePrompt = vi
+      .fn<GatePrompter["prompt"]>()
+      .mockResolvedValue({ approved: true, state: "approved" });
+    const { handler, prompter } = makeHandler({
+      session: {
+        checkPermission: vi.fn().mockReturnValue({ state: "ask" }),
+      },
+      prompter: {
+        canConfirm: vi.fn().mockReturnValue(true),
+        prompt: approvePrompt,
+      },
+    });
+    const result = await handler.handleInput(
+      makeInputEvent("/skill:librarian"),
+      makeCtx(),
+    );
+    expect(result).toEqual({ action: "continue" });
+    expect(prompter.prompt).toHaveBeenCalledOnce();
+  });
+
+  it("returns handled when skill ask is denied by user", async () => {
+    const { handler } = makeHandler({
+      session: {
+        checkPermission: vi.fn().mockReturnValue({ state: "ask" }),
+      },
+      prompter: {
+        canConfirm: vi.fn().mockReturnValue(true),
+        prompt: vi
+          .fn<GatePrompter["prompt"]>()
+          .mockResolvedValue({ approved: false, state: "denied" }),
+      },
+    });
+    const result = await handler.handleInput(
+      makeInputEvent("/skill:librarian"),
+      makeCtx(),
+    );
+    expect(result).toEqual({ action: "handled" });
+  });
+
+  it("passes agentName in the prompt permission request", async () => {
+    const approvePrompt = vi
+      .fn<GatePrompter["prompt"]>()
+      .mockResolvedValue({ approved: true, state: "approved" });
+    const { handler, prompter } = makeHandler({
+      session: {
+        checkPermission: vi.fn().mockReturnValue({ state: "ask" }),
+        resolveAgentName: vi.fn().mockReturnValue("code-agent"),
+      },
+      prompter: {
+        canConfirm: vi.fn().mockReturnValue(true),
+        prompt: approvePrompt,
+      },
+    });
+    await handler.handleInput(makeInputEvent("/skill:librarian"), makeCtx());
+    expect(prompter.prompt).toHaveBeenCalledWith(
+      expect.objectContaining({
+        agentName: "code-agent",
+        skillName: "librarian",
+      }),
+    );
+  });
+});