@gotgenes/pi-permission-system 8.0.0 → 8.1.0

package/src/tool-preview-formatter.ts

@@ -0,0 +1,188 @@
+import { getNonEmptyString, toRecord } from "./common";
+import type { PermissionSystemExtensionConfig } from "./extension-config";
+import {
+  formatEditInputForPrompt,
+  formatReadInputForPrompt,
+  formatWriteInputForPrompt,
+  getPromptPath,
+  serializeToolInputPreview,
+  TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH,
+  TOOL_INPUT_PREVIEW_MAX_LENGTH,
+  TOOL_TEXT_SUMMARY_MAX_LENGTH,
+  truncateInlineText,
+} from "./tool-input-preview";
+import type { PermissionCheckResult } from "./types";
+
+export interface ToolPreviewFormatterOptions {
+  toolInputPreviewMaxLength: number;
+  toolTextSummaryMaxLength: number;
+  toolInputLogPreviewMaxLength: number;
+}
+
+type ConfigurablePreviewLimits = Pick<
+  PermissionSystemExtensionConfig,
+  "toolInputPreviewMaxLength" | "toolTextSummaryMaxLength"
+>;
+
+/**
+ * Resolve `ToolPreviewFormatterOptions` from a config object, falling back to
+ * the built-in defaults for any field that is absent.
+ */
+export function resolveToolPreviewLimits(
+  config: ConfigurablePreviewLimits,
+): ToolPreviewFormatterOptions {
+  return {
+    toolInputPreviewMaxLength:
+      config.toolInputPreviewMaxLength ?? TOOL_INPUT_PREVIEW_MAX_LENGTH,
+    toolTextSummaryMaxLength:
+      config.toolTextSummaryMaxLength ?? TOOL_TEXT_SUMMARY_MAX_LENGTH,
+    toolInputLogPreviewMaxLength: TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH,
+  };
+}
+
+/**
+ * Formats tool inputs for permission prompts and review logs.
+ *
+ * Accepts configurable limits in its constructor — the single injection
+ * point for preview-length configuration (#266).
+ */
+export class ToolPreviewFormatter {
+  constructor(private readonly options: ToolPreviewFormatterOptions) {}
+
+  // ── Prompt formatting ───────────────────────────────────────────────────
+
+  /**
+   * Collapse whitespace, trim, and truncate a string to fit inline.
+   * An explicit `maxLength` overrides the constructor default.
+   */
+  sanitizeInlineText(value: string, maxLength?: number): string {
+    const limit = maxLength ?? this.options.toolTextSummaryMaxLength;
+    const normalized = value.replace(/\s+/g, " ").trim();
+    return normalized ? truncateInlineText(normalized, limit) : "empty text";
+  }
+
+  /** Serialize `input` to inline JSON and truncate at `toolInputPreviewMaxLength`. */
+  formatJsonInputForPrompt(input: unknown): string {
+    const inline = serializeToolInputPreview(input);
+    return inline
+      ? `with input ${truncateInlineText(inline, this.options.toolInputPreviewMaxLength)}`
+      : "";
+  }
+
+  /** Format search-tool (grep/find/ls) input for a permission prompt. */
+  formatSearchInputForPrompt(
+    toolName: string,
+    input: Record<string, unknown>,
+  ): string {
+    const parts: string[] = [];
+    const path = getPromptPath(input);
+    const pattern = getNonEmptyString(input.pattern);
+    const glob = getNonEmptyString(input.glob);
+
+    if (pattern) {
+      parts.push(`pattern '${this.sanitizeInlineText(pattern)}'`);
+    }
+    if (glob) {
+      parts.push(`glob '${this.sanitizeInlineText(glob)}'`);
+    }
+    if (path) {
+      parts.push(`path '${path}'`);
+    } else if (
+      toolName === "find" ||
+      toolName === "grep" ||
+      toolName === "ls"
+    ) {
+      parts.push("current working directory");
+    }
+
+    return parts.length > 0 ? `for ${parts.join(", ")}` : "";
+  }
+
+  /**
+   * Format any tool input for display in a permission ask-prompt.
+   *
+   * Dispatches to the appropriate pure formatter for known tools
+   * and falls back to inline JSON for everything else.
+   */
+  formatToolInputForPrompt(toolName: string, input: unknown): string {
+    const inputRecord = toRecord(input);
+
+    switch (toolName) {
+      case "edit":
+        return formatEditInputForPrompt(inputRecord);
+      case "write":
+        return formatWriteInputForPrompt(inputRecord);
+      case "read":
+        return formatReadInputForPrompt(inputRecord);
+      case "find":
+      case "grep":
+      case "ls":
+        return this.formatSearchInputForPrompt(toolName, inputRecord);
+      default:
+        return this.formatJsonInputForPrompt(input);
+    }
+  }
+
+  // ── Log formatting ──────────────────────────────────────────────────────
+
+  /** Serialize `input` to inline JSON and truncate at `toolInputLogPreviewMaxLength`. */
+  formatGenericToolInputForLog(input: unknown): string | undefined {
+    const inline = serializeToolInputPreview(input);
+    return inline
+      ? `input ${truncateInlineText(inline, this.options.toolInputLogPreviewMaxLength)}`
+      : undefined;
+  }
+
+  /** Derive a loggable input preview string for the review log. */
+  getToolInputPreviewForLog(
+    result: PermissionCheckResult,
+    input: unknown,
+    pathBearingTools: ReadonlySet<string>,
+  ): string | undefined {
+    if (
+      result.toolName === "bash" ||
+      result.toolName === "mcp" ||
+      result.source === "mcp"
+    ) {
+      return undefined;
+    }
+
+    if (pathBearingTools.has(result.toolName)) {
+      const inputPreview = this.formatToolInputForPrompt(
+        result.toolName,
+        input,
+      );
+      return inputPreview
+        ? truncateInlineText(
+            inputPreview,
+            this.options.toolInputLogPreviewMaxLength,
+          )
+        : undefined;
+    }
+
+    return this.formatGenericToolInputForLog(input);
+  }
+
+  /** Build the structured log context object for a permission review log entry. */
+  getPermissionLogContext(
+    result: PermissionCheckResult,
+    input: unknown,
+    pathBearingTools: ReadonlySet<string>,
+  ): {
+    command?: string;
+    target?: string;
+    toolInputPreview?: string;
+    origin?: string;
+  } {
+    return {
+      command: result.command,
+      target: result.target,
+      toolInputPreview: this.getToolInputPreviewForLog(
+        result,
+        input,
+        pathBearingTools,
+      ),
+      origin: result.origin,
+    };
+  }
+}

package/test/extension-config.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 
 import {
   detectMisplacedPermissionKeys,
+  normalizeOptionalPositiveInt,
   normalizePermissionSystemConfig,
 } from "#src/extension-config";
 
@@ -74,6 +75,36 @@ describe("detectMisplacedPermissionKeys", () => {
   });
 });
 
+describe("normalizeOptionalPositiveInt", () => {
+  it("returns the value for a valid positive integer", () => {
+    expect(normalizeOptionalPositiveInt(1)).toBe(1);
+    expect(normalizeOptionalPositiveInt(200)).toBe(200);
+    expect(normalizeOptionalPositiveInt(9999)).toBe(9999);
+  });
+
+  it("returns undefined for zero", () => {
+    expect(normalizeOptionalPositiveInt(0)).toBeUndefined();
+  });
+
+  it("returns undefined for negative integers", () => {
+    expect(normalizeOptionalPositiveInt(-1)).toBeUndefined();
+    expect(normalizeOptionalPositiveInt(-100)).toBeUndefined();
+  });
+
+  it("returns undefined for non-integer numbers (floats)", () => {
+    expect(normalizeOptionalPositiveInt(400.5)).toBeUndefined();
+    expect(normalizeOptionalPositiveInt(1.1)).toBeUndefined();
+  });
+
+  it("returns undefined for non-number types", () => {
+    expect(normalizeOptionalPositiveInt("200")).toBeUndefined();
+    expect(normalizeOptionalPositiveInt(true)).toBeUndefined();
+    expect(normalizeOptionalPositiveInt(null)).toBeUndefined();
+    expect(normalizeOptionalPositiveInt(undefined)).toBeUndefined();
+    expect(normalizeOptionalPositiveInt({})).toBeUndefined();
+  });
+});
+
 describe("normalizePermissionSystemConfig", () => {
   it("normalizes a valid config object", () => {
     const result = normalizePermissionSystemConfig({
@@ -122,4 +153,66 @@ describe("normalizePermissionSystemConfig", () => {
       yoloMode: false,
     });
   });
+
+  it("includes toolInputPreviewMaxLength when a valid positive integer is provided", () => {
+    const result = normalizePermissionSystemConfig({
+      toolInputPreviewMaxLength: 400,
+    });
+    expect(result.toolInputPreviewMaxLength).toBe(400);
+  });
+
+  it("omits toolInputPreviewMaxLength when absent", () => {
+    const result = normalizePermissionSystemConfig({});
+    expect("toolInputPreviewMaxLength" in result).toBe(false);
+  });
+
+  it("omits toolInputPreviewMaxLength for invalid values", () => {
+    expect(
+      normalizePermissionSystemConfig({ toolInputPreviewMaxLength: 0 })
+        .toolInputPreviewMaxLength,
+    ).toBeUndefined();
+    expect(
+      normalizePermissionSystemConfig({ toolInputPreviewMaxLength: -1 })
+        .toolInputPreviewMaxLength,
+    ).toBeUndefined();
+    expect(
+      normalizePermissionSystemConfig({ toolInputPreviewMaxLength: 200.5 })
+        .toolInputPreviewMaxLength,
+    ).toBeUndefined();
+    expect(
+      normalizePermissionSystemConfig({ toolInputPreviewMaxLength: "200" })
+        .toolInputPreviewMaxLength,
+    ).toBeUndefined();
+  });
+
+  it("includes toolTextSummaryMaxLength when a valid positive integer is provided", () => {
+    const result = normalizePermissionSystemConfig({
+      toolTextSummaryMaxLength: 120,
+    });
+    expect(result.toolTextSummaryMaxLength).toBe(120);
+  });
+
+  it("omits toolTextSummaryMaxLength when absent", () => {
+    const result = normalizePermissionSystemConfig({});
+    expect("toolTextSummaryMaxLength" in result).toBe(false);
+  });
+
+  it("omits toolTextSummaryMaxLength for invalid values", () => {
+    expect(
+      normalizePermissionSystemConfig({ toolTextSummaryMaxLength: 0 })
+        .toolTextSummaryMaxLength,
+    ).toBeUndefined();
+    expect(
+      normalizePermissionSystemConfig({ toolTextSummaryMaxLength: -1 })
+        .toolTextSummaryMaxLength,
+    ).toBeUndefined();
+    expect(
+      normalizePermissionSystemConfig({ toolTextSummaryMaxLength: 80.1 })
+        .toolTextSummaryMaxLength,
+    ).toBeUndefined();
+    expect(
+      normalizePermissionSystemConfig({ toolTextSummaryMaxLength: true })
+        .toolTextSummaryMaxLength,
+    ).toBeUndefined();
+  });
 });

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

@@ -12,6 +12,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { describe, expect, it, vi } from "vitest";
 
 import { EXTENSION_TAG } from "#src/denial-messages";
+import { DEFAULT_EXTENSION_CONFIG } from "#src/extension-config";
 import { formatExternalDirectoryAskPrompt } from "#src/handlers/gates/external-directory-messages";
 import { PermissionGateHandler } from "#src/handlers/permission-gate-handler";
 import {
@@ -116,6 +117,7 @@ function makeSession(
     getActiveSkillEntries: vi.fn().mockReturnValue([]),
     getInfrastructureDirs: vi.fn().mockReturnValue([]),
     getInfrastructureReadPaths: vi.fn().mockReturnValue([]),
+    config: DEFAULT_EXTENSION_CONFIG,
     canPrompt: vi.fn().mockReturnValue(true),
     prompt: vi.fn().mockResolvedValue({ approved: true, state: "approved" }),
     ...overrides,

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

@@ -11,6 +11,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { describe, expect, it, vi } from "vitest";
 
+import { DEFAULT_EXTENSION_CONFIG } from "#src/extension-config";
 import { PermissionGateHandler } from "#src/handlers/permission-gate-handler";
 import type { PermissionSession } from "#src/permission-session";
 import type { Rule } from "#src/rule";
@@ -139,6 +140,7 @@ function makeStatefulSession(
     getActiveSkillEntries: vi.fn().mockReturnValue([]),
     getInfrastructureDirs: vi.fn().mockReturnValue([]),
     getInfrastructureReadPaths: vi.fn().mockReturnValue([]),
+    config: DEFAULT_EXTENSION_CONFIG,
     canPrompt: vi.fn().mockReturnValue(true),
     prompt: vi
       .fn()

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

@@ -2,10 +2,24 @@ 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",
@@ -38,6 +52,7 @@ describe("describeToolGate", () => {
     const desc = describeToolGate(
       makeTcc({ toolName: "read" }),
       makeCheckResult("ask"),
+      makeFormatter(),
     );
     expect(desc.surface).toBe("read");
     expect(desc.decision.surface).toBe("read");
@@ -47,6 +62,7 @@ describe("describeToolGate", () => {
     const desc = describeToolGate(
       makeTcc({ toolName: "write" }),
       makeCheckResult("ask"),
+      makeFormatter(),
     );
     expect(desc.decision.value).toBe("write");
   });
@@ -59,6 +75,7 @@ describe("describeToolGate", () => {
     const desc = describeToolGate(
       makeTcc({ toolName: "bash", input: { command: "git status" } }),
       check,
+      makeFormatter(),
     );
     expect(desc.surface).toBe("bash");
     expect(desc.decision.surface).toBe("bash");
@@ -73,6 +90,7 @@ describe("describeToolGate", () => {
     const desc = describeToolGate(
       makeTcc({ toolName: "mcp", input: { tool: "server:tool" } }),
       check,
+      makeFormatter(),
     );
     expect(desc.surface).toBe("mcp");
     expect(desc.decision.surface).toBe("mcp");
@@ -81,7 +99,7 @@ describe("describeToolGate", () => {
 
   it("populates denialContext with kind 'tool' and check result", () => {
     const check = makeCheckResult("deny", { toolName: "read" });
-    const desc = describeToolGate(makeTcc(), check);
+    const desc = describeToolGate(makeTcc(), check, makeFormatter());
     expect(desc.denialContext).toEqual({
       kind: "tool",
       check,
@@ -92,7 +110,11 @@ describe("describeToolGate", () => {
 
   it("populates denialContext with agent name when provided", () => {
     const check = makeCheckResult("ask", { toolName: "read" });
-    const desc = describeToolGate(makeTcc({ agentName: "my-agent" }), check);
+    const desc = describeToolGate(
+      makeTcc({ agentName: "my-agent" }),
+      check,
+      makeFormatter(),
+    );
     expect(desc.denialContext.agentName).toBe("my-agent");
   });
 
@@ -101,6 +123,7 @@ describe("describeToolGate", () => {
     const desc = describeToolGate(
       makeTcc({ toolName: "bash", input: { command: "ls" } }),
       check,
+      makeFormatter(),
     );
     expect(desc.denialContext).toMatchObject({
       kind: "tool",
@@ -116,6 +139,7 @@ describe("describeToolGate", () => {
     const desc = describeToolGate(
       makeTcc({ toolName: "bash", input: { command: "git status" } }),
       check,
+      makeFormatter(),
     );
     expect(desc.sessionApproval).toBeDefined();
     expect(desc.sessionApproval!).toHaveProperty("surface", "bash");
@@ -127,6 +151,7 @@ describe("describeToolGate", () => {
     const desc = describeToolGate(
       makeTcc({ toolName: "read", agentName: "my-agent", toolCallId: "tc-42" }),
       check,
+      makeFormatter(),
     );
     expect(desc.promptDetails).toMatchObject({
       source: "tool_call",
@@ -143,6 +168,7 @@ describe("describeToolGate", () => {
     const desc = describeToolGate(
       makeTcc({ toolName: "bash", input: { command: "ls" } }),
       check,
+      makeFormatter(),
     );
     expect(desc.logContext).toMatchObject({
       source: "tool_call",
@@ -155,6 +181,7 @@ describe("describeToolGate", () => {
     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/tool-call-events.test.ts

@@ -4,7 +4,7 @@
  */
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { describe, expect, it, vi } from "vitest";
-
+import { DEFAULT_EXTENSION_CONFIG } from "#src/extension-config";
 import { PermissionGateHandler } from "#src/handlers/permission-gate-handler";
 import type { PermissionDecisionEvent } from "#src/permission-events";
 import { PERMISSIONS_DECISION_CHANNEL } from "#src/permission-events";
@@ -83,6 +83,7 @@ function makeSession(
       .fn()
       .mockReturnValue(["/test/agent", "/test/agent/git"]),
     getInfrastructureReadPaths: vi.fn().mockReturnValue([]),
+    config: DEFAULT_EXTENSION_CONFIG,
     canPrompt: vi.fn().mockReturnValue(true),
     prompt: vi.fn().mockResolvedValue({ approved: true, state: "approved" }),
     ...overrides,

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

@@ -1,6 +1,6 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { describe, expect, it, vi } from "vitest";
-
+import { DEFAULT_EXTENSION_CONFIG } from "#src/extension-config";
 import {
   getEventInput,
   PermissionGateHandler,
@@ -74,6 +74,7 @@ function makeSession(
       .fn()
       .mockReturnValue(["/test/agent", "/test/agent/git"]),
     getInfrastructureReadPaths: vi.fn().mockReturnValue([]),
+    config: DEFAULT_EXTENSION_CONFIG,
     canPrompt: vi.fn().mockReturnValue(true),
     prompt: vi.fn().mockResolvedValue({ approved: true, state: "approved" }),
     ...overrides,

package/test/handlers/validate-requested-tool.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  type RequestedToolValidation,
+  validateRequestedTool,
+} from "#src/handlers/permission-gate-handler";
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function makeTools(names: string[]): { name: string }[] {
+  return names.map((name) => ({ name }));
+}
+
+const TOOLS = makeTools(["read", "bash", "edit"]);
+
+// ── validateRequestedTool ──────────────────────────────────────────────────
+
+describe("validateRequestedTool", () => {
+  describe("missing / unresolvable tool name", () => {
+    it("blocks when event has no name field", () => {
+      const result = validateRequestedTool({ type: "tool_call" }, TOOLS);
+      expect(result.status).toBe("block");
+      expect(
+        (result as Extract<RequestedToolValidation, { status: "block" }>)
+          .reason,
+      ).toBeTruthy();
+    });
+
+    it("blocks when name field is an empty string", () => {
+      const result = validateRequestedTool({ name: "" }, TOOLS);
+      expect(result.status).toBe("block");
+    });
+
+    it("blocks when name field is null", () => {
+      const result = validateRequestedTool({ name: null }, TOOLS);
+      expect(result.status).toBe("block");
+    });
+
+    it("blocks when event is a primitive", () => {
+      const result = validateRequestedTool("not-an-object", TOOLS);
+      expect(result.status).toBe("block");
+    });
+  });
+
+  describe("unregistered tool", () => {
+    it("blocks when the tool name is not in the registered list", () => {
+      const result = validateRequestedTool({ name: "unknown-tool" }, TOOLS);
+      expect(result.status).toBe("block");
+    });
+
+    it("includes available tool names in the block reason", () => {
+      const result = validateRequestedTool({ name: "unknown-tool" }, TOOLS);
+      expect(result.status).toBe("block");
+      const { reason } = result as Extract<
+        RequestedToolValidation,
+        { status: "block" }
+      >;
+      expect(reason).toContain("read");
+      expect(reason).toContain("bash");
+      expect(reason).toContain("edit");
+    });
+
+    it("blocks with empty available list when no tools are registered", () => {
+      const result = validateRequestedTool({ name: "anything" }, []);
+      expect(result.status).toBe("block");
+    });
+  });
+
+  describe("registered tool (ok path)", () => {
+    it("returns ok with the raw tool name for a known tool", () => {
+      const result = validateRequestedTool({ name: "read" }, TOOLS);
+      expect(result).toEqual({ status: "ok", toolName: "read" });
+    });
+
+    it("returns the raw name as it appeared in the event (not normalised)", () => {
+      // If an alias mechanism were to normalise "Read" → "read",
+      // validateRequestedTool still returns the raw value from the event.
+      // Without aliases the raw name and registered name are the same; this
+      // asserts the contract that toolName comes from the event, not from the
+      // registration lookup's normalizedToolName field.
+      const result = validateRequestedTool({ name: "bash" }, TOOLS);
+      expect(result).toEqual({ status: "ok", toolName: "bash" });
+    });
+
+    it("resolves tool name via the `arguments` field naming convention", () => {
+      // getToolNameFromValue reads `.name` then falls back to other fields;
+      // a plain `{ name: "edit" }` event is sufficient here.
+      const result = validateRequestedTool({ name: "edit" }, TOOLS);
+      expect(result).toEqual({ status: "ok", toolName: "edit" });
+    });
+  });
+});