@gotgenes/pi-permission-system 8.2.0 → 8.3.0

package/src/handlers/gates/bash-token-classification.ts

@@ -0,0 +1,105 @@
+/**
+ * Pure, synchronous token-classification helpers for bash path extraction.
+ *
+ * Exports two classifiers consumed by `bash-path-extractor.ts`:
+ *   - `classifyTokenAsPathCandidate` — strict gate for the external-directory guard.
+ *   - `classifyTokenAsRuleCandidate` — broader gate for cross-cutting `path` rules.
+ *
+ * Both classifiers share the private `rejectNonPathToken` predicate that captures
+ * the seven rejection cases common to both (the production clone this module was
+ * extracted to eliminate).
+ */
+
+// ── Public classifiers ─────────────────────────────────────────────────────
+
+/**
+ * Strict path-candidate classifier for the external-directory guard.
+ *
+ * Accepts tokens that unambiguously look like filesystem paths:
+ * - Absolute paths (starting with `/`)
+ * - Home-relative paths (starting with `~/`)
+ * - Parent-traversal paths (containing `..`)
+ *
+ * Returns the raw token string if it qualifies, or `null` to skip.
+ */
+export function classifyTokenAsPathCandidate(token: string): string | null {
+  if (rejectNonPathToken(token)) return null;
+
+  if (token.startsWith("/")) return token;
+  if (token.startsWith("~/")) return token;
+  if (token.includes("..")) return token;
+
+  return null;
+}
+
+/**
+ * Broader token classifier for cross-cutting `path` permission rules.
+ *
+ * Accepts the same shapes as `classifyTokenAsPathCandidate`, plus:
+ * - Dot-files and `./`-relative paths (starting with `.`)
+ * - Any relative path containing `/` (e.g. `src/foo.ts`)
+ *
+ * The `~/foo` case is covered by `includes("/")` — no separate `~/` branch needed.
+ *
+ * Does NOT require the strict "must start with `/` or `~/` or contain `..`"
+ * gate that the external-directory classifier uses.
+ *
+ * Returns the raw token string if it qualifies, or `null` to skip.
+ */
+export function classifyTokenAsRuleCandidate(token: string): string | null {
+  if (rejectNonPathToken(token)) return null;
+
+  if (token.startsWith(".")) return token;
+  if (token.includes("/")) return token; // covers ~/ paths and all relative paths with /
+  if (token.includes("..")) return token; // bare ".." (no slash)
+
+  return null;
+}
+
+// ── Private rejection predicate ────────────────────────────────────────────
+
+/**
+ * URL pattern to skip tokens that look like URLs rather than paths.
+ */
+const URL_PATTERN = /^[a-z][a-z0-9+.-]*:\/\//i;
+
+/**
+ * Regex metacharacter sequences that are never found in real filesystem paths.
+ * If a token contains any of these, it is almost certainly a regex pattern
+ * (e.g. a grep argument) rather than a path.
+ */
+const REGEX_METACHAR_PATTERN = /\.\*|\.\+|\\\||\\\(|\\\)|\[.*?\]|\^\//;
+
+/**
+ * Shared rejection prelude: returns `true` when a token can never be a
+ * filesystem path, regardless of which classifier is asking.
+ *
+ * Rejects: empty tokens, flags (leading `-`), env assignments (`FOO=/bar`),
+ * URLs, `@scope/package` patterns, bare-slash tokens, and regex metacharacter
+ * sequences.
+ */
+function rejectNonPathToken(token: string): boolean {
+  if (!token) return true;
+  if (token.startsWith("-")) return true;
+
+  // Env assignment: = appears before any /  (FOO=/bar is an assignment,
+  // /foo=bar is not because the slash comes first).
+  const eqIndex = token.indexOf("=");
+  const slashIndex = token.indexOf("/");
+  if (eqIndex !== -1 && (slashIndex === -1 || eqIndex < slashIndex))
+    return true;
+
+  if (URL_PATTERN.test(token)) return true;
+
+  // @scope/package patterns (npm scoped packages) — but @/ is allowed through
+  // since it looks like an absolute-rooted path, not an npm scope.
+  if (token.startsWith("@") && !token.startsWith("@/")) return true;
+
+  // Bare-slash tokens (/, //, ///) resolve to filesystem root and are never
+  // meaningful path arguments in practice.
+  if (/^\/+$/.test(token)) return true;
+
+  if (REGEX_METACHAR_PATTERN.test(token)) return true;
+
+  return false;
+}

package/src/handlers/permission-gate-handler.ts

@@ -16,6 +16,7 @@ import {
   formatUnknownToolReason,
 } from "#src/permission-prompts";
 import type { PermissionSession } from "#src/permission-session";
+import type { ToolInputFormatterLookup } from "#src/tool-input-formatter-registry";
 import {
   resolveToolPreviewLimits,
   ToolPreviewFormatter,
@@ -54,6 +55,7 @@ export class PermissionGateHandler {
     private readonly session: PermissionSession,
     private readonly events: PermissionEventBus,
     private readonly toolRegistry: ToolRegistry,
+    private readonly customFormatters?: ToolInputFormatterLookup,
   ) {}
 
   async handleToolCall(
@@ -145,6 +147,7 @@ export class PermissionGateHandler {
 
     const formatter = new ToolPreviewFormatter(
       resolveToolPreviewLimits(this.session.config),
+      this.customFormatters,
     );
 
     // ── Ordered gate pipeline ─────────────────────────────────────────────

package/src/index.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerBuiltinToolInputFormatters } from "./builtin-tool-input-formatters";
 import { registerPermissionSystemCommand } from "./config-modal";
 import { getGlobalConfigPath } from "./config-paths";
 import type { PermissionForwardingDeps } from "./forwarded-permissions/polling";
@@ -29,6 +30,7 @@ import { createSessionLogger } from "./session-logger";
 import { isSubagentExecutionContext } from "./subagent-context";
 import { subscribeSubagentLifecycle } from "./subagent-lifecycle-events";
 import { SubagentSessionRegistry } from "./subagent-registry";
+import { ToolInputFormatterRegistry } from "./tool-input-formatter-registry";
 import {
   canResolveAskPermissionRequest,
   shouldAutoApprovePermissionState,
@@ -37,6 +39,8 @@ import {
 export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const runtime = createExtensionRuntime();
   const subagentRegistry = new SubagentSessionRegistry();
+  const formatterRegistry = new ToolInputFormatterRegistry();
+  registerBuiltinToolInputFormatters(formatterRegistry);
 
   const prompter = new PermissionPrompter({
     getConfig: () => runtime.config,
@@ -121,6 +125,9 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     getToolPermission(toolName, agentName) {
       return runtime.permissionManager.getToolPermission(toolName, agentName);
     },
+    registerToolInputFormatter(toolName, formatter) {
+      return formatterRegistry.register(toolName, formatter);
+    },
   };
   publishPermissionsService(permissionsService);
 
@@ -145,7 +152,12 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     unpublishPermissionsService();
   });
   const agentPrep = new AgentPrepHandler(session, toolRegistry);
-  const gates = new PermissionGateHandler(session, pi.events, toolRegistry);
+  const gates = new PermissionGateHandler(
+    session,
+    pi.events,
+    toolRegistry,
+    formatterRegistry,
+  );
 
   pi.on("session_start", (event, ctx) =>
     lifecycle.handleSessionStart(event, ctx),

package/src/permission-prompts.ts

@@ -46,7 +46,11 @@ export function formatAskPrompt(
     const patternInfo = result.matchedPattern
       ? ` (matched '${result.matchedPattern}')`
       : "";
-    return `${subject} requested MCP target '${result.target}'${patternInfo}. Allow this call?`;
+    const mcpPreview = formatter
+      ? formatter.formatToolInputForPrompt("mcp", input)
+      : "";
+    const previewSuffix = mcpPreview ? ` ${mcpPreview}` : "";
+    return `${subject} requested MCP target '${result.target}'${patternInfo}${previewSuffix}. Allow this call?`;
   }
 
   const patternInfo = result.matchedPattern

package/src/service.ts

@@ -11,9 +11,10 @@
  * reference — this ensures resilience across `/reload` and load-order edge cases.
  */
 
+import type { ToolInputFormatter } from "./tool-input-formatter-registry";
 import type { PermissionCheckResult, PermissionState } from "./types";
 
-export type { PermissionCheckResult, PermissionState };
+export type { PermissionCheckResult, PermissionState, ToolInputFormatter };
 
 /** Process-global key for the service slot. */
 const SERVICE_KEY = Symbol.for("@gotgenes/pi-permission-system:service");
@@ -43,6 +44,25 @@ export interface PermissionsService {
     agentName?: string,
   ): PermissionCheckResult;
 
+  /**
+   * Register a custom preview formatter for a specific tool name.
+   *
+   * The formatter is consulted first inside `ToolPreviewFormatter.formatToolInputForPrompt`;
+   * returning `undefined` falls through to the built-in switch (and ultimately
+   * the JSON default).
+   *
+   * Only one formatter may be registered per tool name — a second call for the
+   * same name throws.  The returned disposer unregisters the formatter.
+   *
+   * @param toolName  - Exact tool name to register for (e.g. `"mcp"`, `"my-server:run"`).
+   * @param formatter - Receives the raw `input` record; return a string to use
+   *                    as the prompt preview, or `undefined` to decline.
+   */
+  registerToolInputFormatter(
+    toolName: string,
+    formatter: ToolInputFormatter,
+  ): () => void;
+
   /**
    * Query the tool-level permission state for pre-filtering tools before
    * creating a child session.

package/src/tool-input-formatter-registry.ts

@@ -0,0 +1,57 @@
+/**
+ * Registry for custom tool-input preview formatters.
+ *
+ * Allows extensions to register a formatter for a specific tool name so
+ * permission prompts can show a human-readable summary instead of raw JSON.
+ * One formatter per tool name; duplicate registration throws.
+ */
+
+/** A custom preview formatter for one tool's input. Returns `undefined` to decline. */
+export type ToolInputFormatter = (
+  input: Record<string, unknown>,
+) => string | undefined;
+
+/**
+ * Read-only lookup used by `ToolPreviewFormatter` (ISP — exposes only the
+ * read side, not the registration surface).
+ */
+export interface ToolInputFormatterLookup {
+  get(toolName: string): ToolInputFormatter | undefined;
+}
+
+/**
+ * Persistent registry mapping tool names to custom preview formatters.
+ *
+ * Owned by the extension factory (`index.ts`) so it survives across the
+ * per-tool-call `ToolPreviewFormatter` construction cycle.
+ * Exposed to sibling extensions via `PermissionsService.registerToolInputFormatter`.
+ */
+export class ToolInputFormatterRegistry implements ToolInputFormatterLookup {
+  private readonly formatters = new Map<string, ToolInputFormatter>();
+
+  /**
+   * Register a formatter for `toolName`.
+   *
+   * Throws if a formatter is already registered for that name — keeps
+   * resolution deterministic (a pi-permission-system package priority).
+   * Returns a disposer that removes the formatter; the disposer is
+   * identity-guarded so a stale call cannot evict a later registration.
+   */
+  register(toolName: string, formatter: ToolInputFormatter): () => void {
+    if (this.formatters.has(toolName)) {
+      throw new Error(
+        `A tool input formatter is already registered for '${toolName}'.`,
+      );
+    }
+    this.formatters.set(toolName, formatter);
+    return () => {
+      if (this.formatters.get(toolName) === formatter) {
+        this.formatters.delete(toolName);
+      }
+    };
+  }
+
+  get(toolName: string): ToolInputFormatter | undefined {
+    return this.formatters.get(toolName);
+  }
+}

package/src/tool-preview-formatter.ts

@@ -1,5 +1,6 @@
 import { getNonEmptyString, toRecord } from "./common";
 import type { PermissionSystemExtensionConfig } from "./extension-config";
+import type { ToolInputFormatterLookup } from "./tool-input-formatter-registry";
 import {
   formatEditInputForPrompt,
   formatReadInputForPrompt,
@@ -47,7 +48,10 @@ export function resolveToolPreviewLimits(
  * point for preview-length configuration (#266).
  */
 export class ToolPreviewFormatter {
-  constructor(private readonly options: ToolPreviewFormatterOptions) {}
+  constructor(
+    private readonly options: ToolPreviewFormatterOptions,
+    private readonly customFormatters?: ToolInputFormatterLookup,
+  ) {}
 
   // ── Prompt formatting ───────────────────────────────────────────────────
 
@@ -107,6 +111,14 @@ export class ToolPreviewFormatter {
   formatToolInputForPrompt(toolName: string, input: unknown): string {
     const inputRecord = toRecord(input);
 
+    const custom = this.customFormatters?.get(toolName);
+    if (custom) {
+      const rendered = custom(inputRecord);
+      if (rendered !== undefined) {
+        return rendered;
+      }
+    }
+
     switch (toolName) {
       case "edit":
         return formatEditInputForPrompt(inputRecord);
@@ -118,6 +130,11 @@ export class ToolPreviewFormatter {
       case "grep":
       case "ls":
         return this.formatSearchInputForPrompt(toolName, inputRecord);
+      case "mcp":
+        // The MCP target is already surfaced in formatAskPrompt's MCP branch.
+        // When no custom formatter is registered (or it declines), produce no
+        // additional preview rather than leaking the raw event JSON.
+        return "";
       default:
         return this.formatJsonInputForPrompt(input);
     }

package/test/builtin-tool-input-formatters.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, test } from "vitest";
+
+import {
+  formatMcpInputForPrompt,
+  registerBuiltinToolInputFormatters,
+} from "#src/builtin-tool-input-formatters";
+import { ToolInputFormatterRegistry } from "#src/tool-input-formatter-registry";
+
+// ── formatMcpInputForPrompt ───────────────────────────────────────────────
+
+describe("formatMcpInputForPrompt", () => {
+  test("returns undefined when arguments is absent", () => {
+    expect(formatMcpInputForPrompt({ tool: "exa:search" })).toBeUndefined();
+  });
+
+  test("returns undefined when arguments is an empty object", () => {
+    expect(
+      formatMcpInputForPrompt({ tool: "exa:search", arguments: {} }),
+    ).toBeUndefined();
+  });
+
+  test("returns a summary for a single string argument", () => {
+    const result = formatMcpInputForPrompt({
+      tool: "exa:search",
+      arguments: { query: "typescript generics" },
+    });
+    expect(result).toBeDefined();
+    expect(result).toContain("query");
+    expect(result).toContain("typescript generics");
+    expect(result).toMatch(/^with /);
+  });
+
+  test("returns a comma-separated summary for multiple arguments", () => {
+    const result = formatMcpInputForPrompt({
+      tool: "exa:search",
+      arguments: { query: "test", numResults: 5 },
+    });
+    expect(result).toContain("query");
+    expect(result).toContain("numResults");
+    expect(result).toContain("5");
+  });
+
+  test("renders number arguments without quotes", () => {
+    const result = formatMcpInputForPrompt({
+      arguments: { count: 42 },
+    });
+    expect(result).toContain("42");
+    expect(result).not.toContain('"42"');
+  });
+
+  test("renders boolean arguments without quotes", () => {
+    const result = formatMcpInputForPrompt({
+      arguments: { verbose: true },
+    });
+    expect(result).toContain("true");
+  });
+
+  test("renders array arguments as '[N items]'", () => {
+    const result = formatMcpInputForPrompt({
+      arguments: { ids: [1, 2, 3] },
+    });
+    expect(result).toContain("[3 items]");
+  });
+
+  test("renders nested object arguments as '{…}'", () => {
+    const result = formatMcpInputForPrompt({
+      arguments: { filter: { type: "file" } },
+    });
+    expect(result).toContain("{…}");
+  });
+
+  test("truncates the full summary when it exceeds the limit", () => {
+    // Need multiple long-valued args so the joined summary exceeds 160 chars
+    const result = formatMcpInputForPrompt({
+      arguments: {
+        first: "x".repeat(80),
+        second: "y".repeat(80),
+        third: "z".repeat(80),
+      },
+    });
+    expect(result).toBeDefined();
+    expect(result!.endsWith("…")).toBe(true);
+  });
+
+  test("truncates long string argument values", () => {
+    const result = formatMcpInputForPrompt({
+      arguments: { query: "x".repeat(100) },
+    });
+    expect(result).toBeDefined();
+    // Should not include the full 100-char string verbatim
+    expect(result).not.toContain("x".repeat(100));
+  });
+});
+
+// ── registerBuiltinToolInputFormatters ────────────────────────────────────
+
+describe("registerBuiltinToolInputFormatters", () => {
+  test("registers the mcp formatter in the registry", () => {
+    const registry = new ToolInputFormatterRegistry();
+    registerBuiltinToolInputFormatters(registry);
+    expect(registry.get("mcp")).toBe(formatMcpInputForPrompt);
+  });
+
+  test("throws if called twice (duplicate registration guard)", () => {
+    const registry = new ToolInputFormatterRegistry();
+    registerBuiltinToolInputFormatters(registry);
+    expect(() => registerBuiltinToolInputFormatters(registry)).toThrow("mcp");
+  });
+});

package/test/config-loader.test.ts

@@ -7,8 +7,90 @@ import {
   loadAndMergeConfigs,
   loadUnifiedConfig,
   mergeUnifiedConfigs,
+  stripJsonComments,
 } from "#src/config-loader";
 
+describe("stripJsonComments", () => {
+  it("returns empty string for empty input", () => {
+    expect(stripJsonComments("")).toBe("");
+  });
+
+  it("passes through plain JSON unchanged", () => {
+    const input = '{"key": true}';
+    expect(stripJsonComments(input)).toBe(input);
+  });
+
+  it("drops a line comment body and preserves the trailing newline", () => {
+    // The space before // is emitted; the comment body is dropped; \n is kept.
+    expect(stripJsonComments('{ // comment\n"k": 1}')).toBe('{ \n"k": 1}');
+  });
+
+  it("drops a line comment that runs to EOF with no trailing newline", () => {
+    expect(stripJsonComments('{"k": 1} // trailing')).toBe('{"k": 1} ');
+  });
+
+  it("drops a block comment and nothing else", () => {
+    expect(stripJsonComments('{ /* block */ "k": 1}')).toBe('{  "k": 1}');
+  });
+
+  it("drops an unterminated block comment to EOF", () => {
+    expect(stripJsonComments("{ /* no close")).toBe("{ ");
+  });
+
+  it("preserves // inside a double-quoted string", () => {
+    expect(stripJsonComments('{"url": "http://example.com"}')).toBe(
+      '{"url": "http://example.com"}',
+    );
+  });
+
+  it("preserves block-comment markers inside a double-quoted string", () => {
+    expect(stripJsonComments('{"v": "a /* b */ c"}')).toBe(
+      '{"v": "a /* b */ c"}',
+    );
+  });
+
+  it("preserves // inside a single-quoted string", () => {
+    expect(stripJsonComments("{'url': 'http://x.com'}")).toBe(
+      "{'url': 'http://x.com'}",
+    );
+  });
+
+  it("preserves block-comment markers inside a single-quoted string", () => {
+    expect(stripJsonComments("{'v': 'a /* b */ c'}")).toBe(
+      "{'v': 'a /* b */ c'}",
+    );
+  });
+
+  it("honors a backslash-escaped quote so it does not close the string", () => {
+    // The string value is: a\"b (backslash-escaped double quote)
+    expect(stripJsonComments('{"k": "a\\"b"}')).toBe('{"k": "a\\"b"}');
+  });
+
+  it("emits an unterminated string to EOF verbatim", () => {
+    expect(stripJsonComments('{"k": "unterminated')).toBe(
+      '{"k": "unterminated',
+    );
+  });
+
+  it("preserves a lone slash that is not part of // or /*", () => {
+    expect(stripJsonComments('{"v": 1/2}')).toBe('{"v": 1/2}');
+  });
+
+  it("handles a combined JSONC document that round-trips to valid JSON", () => {
+    const jsonc = [
+      "{",
+      '  "debugLog": true, // runtime knob',
+      '  "permission": { /* the policy */ "*": "ask" }',
+      "}",
+    ].join("\n");
+    const stripped = stripJsonComments(jsonc);
+    // Must parse without throwing
+    const parsed = JSON.parse(stripped) as Record<string, unknown>;
+    expect(parsed.debugLog).toBe(true);
+    expect(parsed.permission).toEqual({ "*": "ask" });
+  });
+});
+
 describe("loadUnifiedConfig", () => {
   let tempDir: string;
 

package/test/handlers/before-agent-start.test.ts

@@ -1,4 +1,3 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { describe, expect, it, vi } from "vitest";
 
 import {
@@ -8,6 +7,8 @@ import {
 import type { PermissionSession } from "#src/permission-session";
 import type { ToolRegistry } from "#src/tool-registry";
 
+import { makeCtx } from "#test/helpers/handler-fixtures";
+
 // ── SDK stubs ──────────────────────────────────────────────────────────────
 vi.mock("@earendil-works/pi-coding-agent", async (importOriginal) => {
   const original =
@@ -20,25 +21,6 @@ vi.mock("@earendil-works/pi-coding-agent", async (importOriginal) => {
 
 // ── helpers ────────────────────────────────────────────────────────────────
 
-function makeCtx(overrides: Partial<ExtensionContext> = {}): ExtensionContext {
-  return {
-    cwd: "/test/project",
-    hasUI: true,
-    ui: {
-      setStatus: vi.fn(),
-      notify: vi.fn(),
-      select: vi.fn(),
-      input: vi.fn(),
-    },
-    sessionManager: {
-      getEntries: vi.fn().mockReturnValue([]),
-      getSessionDir: vi.fn().mockReturnValue("/sessions/test"),
-      addEntry: vi.fn(),
-    },
-    ...overrides,
-  } as unknown as ExtensionContext;
-}
-
 function makeEvent(systemPrompt = "You are an assistant.") {
   return { systemPrompt };
 }