@gotgenes/pi-permission-system 8.2.1 → 8.3.1

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [8.3.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v8.3.0...pi-permission-system-v8.3.1) (2026-06-01)
+
+
+### Bug Fixes
+
+* add process-global SubagentSessionRegistry accessor ([#296](https://github.com/gotgenes/pi-packages/issues/296)) ([d3fd3b0](https://github.com/gotgenes/pi-packages/commit/d3fd3b04223b2d276873094ad8c14f239654b8c8))
+* share SubagentSessionRegistry across parent and child sessions ([#296](https://github.com/gotgenes/pi-packages/issues/296)) ([fed676a](https://github.com/gotgenes/pi-packages/commit/fed676aaa485abe8db158e522ba898705f3dff94))
+
+
+### Documentation
+
+* explain process-global subagent registry across session buses ([#296](https://github.com/gotgenes/pi-packages/issues/296)) ([1804dbb](https://github.com/gotgenes/pi-packages/commit/1804dbbb766d7b7fbc0e49da877f3238f5c3e8dc))
+* use ADR-NNNN with links docs-wide ([c6b6431](https://github.com/gotgenes/pi-packages/commit/c6b6431c004f324931f23be46cf2e47e8fdac919))
+
+## [8.3.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v8.2.1...pi-permission-system-v8.3.0) (2026-06-01)
+
+
+### Features
+
+* add built-in MCP input summarizer ([#283](https://github.com/gotgenes/pi-packages/issues/283)) ([2d47e36](https://github.com/gotgenes/pi-packages/commit/2d47e360b475c72c76026ea5ea4ebf6446b58c3e))
+* add ToolInputFormatterRegistry ([#283](https://github.com/gotgenes/pi-packages/issues/283)) ([c2c2b3d](https://github.com/gotgenes/pi-packages/commit/c2c2b3d64664b03cf6715e630e0bb59c4d1b650c))
+* consult custom formatter registry in ToolPreviewFormatter ([#283](https://github.com/gotgenes/pi-packages/issues/283)) ([9a0d756](https://github.com/gotgenes/pi-packages/commit/9a0d75600f7aa364c06bee7c0419c64d9a5325e9))
+* expose registerToolInputFormatter on PermissionsService ([#283](https://github.com/gotgenes/pi-packages/issues/283)) ([2287484](https://github.com/gotgenes/pi-packages/commit/2287484e24392fffac37962e41ad985446e75d2d))
+
+
+### Documentation
+
+* add authoring guide for tool input formatters ([#283](https://github.com/gotgenes/pi-packages/issues/283)) ([6d154a1](https://github.com/gotgenes/pi-packages/commit/6d154a14a7a1f26ded4f1d77d50b52d200b70a27))
+* document tool input formatter seam ([#283](https://github.com/gotgenes/pi-packages/issues/283)) ([2fc9ff1](https://github.com/gotgenes/pi-packages/commit/2fc9ff1df97341b8825ef13c99a3ffd651dcd8e0))
+
 ## [8.2.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v8.2.0...pi-permission-system-v8.2.1) (2026-05-31)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "8.2.1",
+  "version": "8.3.1",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

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

@@ -0,0 +1,82 @@
+/**
+ * Built-in tool input formatters registered through the public seam at startup.
+ *
+ * Each formatter here dogfoods `ToolInputFormatterRegistry.register` — it goes
+ * through exactly the same path a third-party extension would use.
+ */
+
+import { toRecord } from "./common";
+import type {
+  ToolInputFormatter,
+  ToolInputFormatterRegistry,
+} from "./tool-input-formatter-registry";
+import { truncateInlineText } from "./tool-input-preview";
+
+/** Maximum total length of the generated argument summary (before "with " prefix). */
+const MCP_ARGS_SUMMARY_MAX_LENGTH = 160;
+
+/** Maximum length of a single string argument value (before quoting). */
+const MCP_ARG_VALUE_MAX_LENGTH = 60;
+
+/**
+ * Render a single MCP argument value as a compact, readable fragment.
+ *
+ * - Strings: quoted and truncated.
+ * - Numbers / booleans: plain string conversion.
+ * - Arrays: `[N items]`.
+ * - Objects: `{…}`.
+ * - Everything else: plain string conversion.
+ */
+function renderArgValue(value: unknown): string {
+  if (typeof value === "string") {
+    return `"${truncateInlineText(value, MCP_ARG_VALUE_MAX_LENGTH)}"`;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.length} items]`;
+  }
+  if (typeof value === "object" && value !== null) {
+    return "{…}";
+  }
+  return String(value);
+}
+
+/**
+ * Format an MCP tool call's `arguments` payload as a human-readable summary.
+ *
+ * Returns `undefined` when `arguments` is absent or empty — the MCP ask-prompt
+ * is then left unchanged (no suffix appended).
+ *
+ * Intended to be registered as the `"mcp"` formatter via
+ * `registerBuiltinToolInputFormatters`.
+ */
+export const formatMcpInputForPrompt: ToolInputFormatter = (
+  input: Record<string, unknown>,
+): string | undefined => {
+  const args = toRecord(input.arguments);
+  const entries = Object.entries(args);
+  if (entries.length === 0) return undefined;
+
+  const parts = entries.map(
+    ([key, value]) => `${key}: ${renderArgValue(value)}`,
+  );
+  const summary = truncateInlineText(
+    parts.join(", "),
+    MCP_ARGS_SUMMARY_MAX_LENGTH,
+  );
+  return `with ${summary}`;
+};
+
+/**
+ * Register all built-in tool input formatters into `registry`.
+ *
+ * Called once from the extension factory (`index.ts`) immediately after the
+ * registry is constructed, before any third-party registration can occur.
+ */
+export function registerBuiltinToolInputFormatters(
+  registry: ToolInputFormatterRegistry,
+): void {
+  registry.register("mcp", formatMcpInputForPrompt);
+}

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";
@@ -28,7 +29,8 @@ import {
 import { createSessionLogger } from "./session-logger";
 import { isSubagentExecutionContext } from "./subagent-context";
 import { subscribeSubagentLifecycle } from "./subagent-lifecycle-events";
-import { SubagentSessionRegistry } from "./subagent-registry";
+import { getSubagentSessionRegistry } from "./subagent-registry";
+import { ToolInputFormatterRegistry } from "./tool-input-formatter-registry";
 import {
   canResolveAskPermissionRequest,
   shouldAutoApprovePermissionState,
@@ -36,7 +38,9 @@ import {
 
 export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const runtime = createExtensionRuntime();
-  const subagentRegistry = new SubagentSessionRegistry();
+  const subagentRegistry = getSubagentSessionRegistry();
+  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/subagent-registry.ts

@@ -10,8 +10,45 @@
  * The registry is keyed by session directory path, which is unique per
  * session and available to both producer and consumer via
  * `ctx.sessionManager.getSessionDir()`.
+ *
+ * The single registry instance is stored on `globalThis` (via `Symbol.for()`)
+ * so that the parent's permission-system instance (which registers children
+ * on the parent's event bus) and each child's separate jiti instance (which
+ * reads the registry to detect itself and resolve its forwarding target) share
+ * one store across per-session event buses. See `getSubagentSessionRegistry()`.
  */
 
+/** Process-global key for the shared registry slot. */
+const SUBAGENT_SESSION_REGISTRY_KEY = Symbol.for(
+  "@gotgenes/pi-permission-system:subagent-registry",
+);
+
+/**
+ * Return the process-global SubagentSessionRegistry, creating it on first call.
+ *
+ * Backed by `globalThis` + `Symbol.for()` so the parent's permission-system
+ * instance (which registers children on the parent event bus) and each child's
+ * separate jiti instance (which reads the registry to detect itself and resolve
+ * its forwarding target) share one store across per-session event buses.
+ *
+ * Intentionally has no shutdown/unpublish hook — a child's `session_shutdown`
+ * must not be able to wipe the parent's registrations. Entries are added and
+ * removed exclusively by the parent's `subagents:child:session-created` /
+ * `subagents:child:disposed` subscription.
+ */
+export function getSubagentSessionRegistry(): SubagentSessionRegistry {
+  const store = globalThis as Record<symbol, unknown>;
+  const existing = store[SUBAGENT_SESSION_REGISTRY_KEY] as
+    | SubagentSessionRegistry
+    | undefined;
+  if (existing) {
+    return existing;
+  }
+  const registry = new SubagentSessionRegistry();
+  store[SUBAGENT_SESSION_REGISTRY_KEY] = registry;
+  return registry;
+}
+
 /** Signal stored per registered in-process subagent session. */
 export interface SubagentSessionInfo {
   /** Parent session ID for permission forwarding. Omit when unknown. */

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/permission-prompts.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test } from "vitest";
-
 import {
   formatAskPrompt,
   formatMissingToolNameReason,
@@ -8,6 +7,7 @@ import {
   formatUnknownToolReason,
 } from "#src/permission-prompts";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
+import type { ToolInputFormatterLookup } from "#src/tool-input-formatter-registry";
 import {
   TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH,
   TOOL_INPUT_PREVIEW_MAX_LENGTH,
@@ -16,12 +16,21 @@ import {
 import { ToolPreviewFormatter } from "#src/tool-preview-formatter";
 import type { PermissionCheckResult } from "#src/types";
 
-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 makeFormatter(
+  lookup?: ToolInputFormatterLookup,
+): ToolPreviewFormatter {
+  return new ToolPreviewFormatter(
+    {
+      toolInputPreviewMaxLength: TOOL_INPUT_PREVIEW_MAX_LENGTH,
+      toolTextSummaryMaxLength: TOOL_TEXT_SUMMARY_MAX_LENGTH,
+      toolInputLogPreviewMaxLength: TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH,
+    },
+    lookup,
+  );
+}
+
+function makeMcpLookup(preview: string): ToolInputFormatterLookup {
+  return { get: (name) => (name === "mcp" ? () => preview : undefined) };
 }
 
 function toolResult(
@@ -163,6 +172,43 @@ describe("formatAskPrompt", () => {
     expect(result).toContain("matched 'server:*'");
   });
 
+  test("appends MCP argument summary when the formatter has an mcp formatter registered", () => {
+    const result = formatAskPrompt(
+      mcpResult("exa:search"),
+      undefined,
+      { tool: "exa:search", arguments: { query: "typescript" } },
+      makeFormatter(makeMcpLookup('with query: "typescript"')),
+    );
+    expect(result).toContain("exa:search");
+    expect(result).toContain('with query: "typescript"');
+    expect(result).toContain("Allow this call?");
+  });
+
+  test("MCP prompt is unchanged when the formatter returns undefined (no arguments)", () => {
+    const noArgsLookup: ToolInputFormatterLookup = {
+      get: (name) => (name === "mcp" ? () => undefined : undefined),
+    };
+    const result = formatAskPrompt(
+      mcpResult("exa:search"),
+      undefined,
+      { tool: "exa:search" },
+      makeFormatter(noArgsLookup),
+    );
+    expect(result).toContain("exa:search");
+    expect(result).not.toMatch(/with /);
+    expect(result).toContain("Allow this call?");
+  });
+
+  test("MCP prompt is unchanged when no formatter is provided", () => {
+    const result = formatAskPrompt(mcpResult("exa:search"), undefined, {
+      tool: "exa:search",
+      arguments: { query: "test" },
+    });
+    expect(result).toContain("exa:search");
+    expect(result).not.toMatch(/with /);
+    expect(result).toContain("Allow this call?");
+  });
+
   test("includes real input preview for non-bash non-mcp tools", () => {
     const result = formatAskPrompt(
       toolResult("read"),

package/test/service.test.ts

@@ -6,6 +6,7 @@ import {
   publishPermissionsService,
   unpublishPermissionsService,
 } from "#src/service";
+import { ToolInputFormatterRegistry } from "#src/tool-input-formatter-registry";
 import type { PermissionCheckResult } from "#src/types";
 
 // ── helpers ────────────────────────────────────────────────────────────────
@@ -16,6 +17,7 @@ function makeService(
   return {
     checkPermission: vi.fn(),
     getToolPermission: vi.fn(),
+    registerToolInputFormatter: vi.fn(),
     ...overrides,
   };
 }
@@ -136,6 +138,7 @@ describe("service adapter delegation", () => {
       getToolPermission(toolName, agentName) {
         return getToolPermissionFn(toolName, agentName);
       },
+      registerToolInputFormatter: vi.fn(),
     };
 
     publishPermissionsService(service);
@@ -157,6 +160,7 @@ describe("service adapter delegation", () => {
       getToolPermission(toolName, agentName) {
         return getToolPermissionFn(toolName, agentName);
       },
+      registerToolInputFormatter: vi.fn(),
     };
 
     publishPermissionsService(service);
@@ -182,3 +186,51 @@ describe("service adapter delegation", () => {
     expect(checkPermission).toHaveBeenCalledWith("read", {}, undefined, []);
   });
 });
+
+// ── registerToolInputFormatter delegation ─────────────────────────────────
+
+describe("registerToolInputFormatter delegation", () => {
+  afterEach(() => {
+    unpublishPermissionsService();
+  });
+
+  it("delegates to the registry and returns its disposer", () => {
+    const registry = new ToolInputFormatterRegistry();
+    const formatter = () => "preview";
+
+    const service = makeService({
+      registerToolInputFormatter(toolName, fmt) {
+        return registry.register(toolName, fmt);
+      },
+    });
+
+    publishPermissionsService(service);
+    const dispose = getPermissionsService()!.registerToolInputFormatter(
+      "my-tool",
+      formatter,
+    );
+
+    // Registry received the registration
+    expect(registry.get("my-tool")).toBe(formatter);
+
+    // Disposer returned from service removes it from the registry
+    dispose();
+    expect(registry.get("my-tool")).toBeUndefined();
+  });
+
+  it("throws when a formatter is already registered for the tool name", () => {
+    const registry = new ToolInputFormatterRegistry();
+    registry.register("my-tool", () => undefined);
+
+    const service = makeService({
+      registerToolInputFormatter(toolName, fmt) {
+        return registry.register(toolName, fmt);
+      },
+    });
+
+    publishPermissionsService(service);
+    expect(() =>
+      getPermissionsService()!.registerToolInputFormatter("my-tool", () => ""),
+    ).toThrow("my-tool");
+  });
+});

package/test/subagent-registry.test.ts

@@ -1,9 +1,14 @@
-import { describe, expect, test } from "vitest";
+import { afterEach, describe, expect, test } from "vitest";
 import {
+  getSubagentSessionRegistry,
   type SubagentSessionInfo,
   SubagentSessionRegistry,
 } from "#src/subagent-registry";
 
+const REGISTRY_KEY = Symbol.for(
+  "@gotgenes/pi-permission-system:subagent-registry",
+);
+
 function makeInfo(
   overrides: Partial<SubagentSessionInfo> = {},
 ): SubagentSessionInfo {
@@ -92,3 +97,42 @@ describe("SubagentSessionRegistry", () => {
     expect(registry.has("/sessions/task-2")).toBe(true);
   });
 });
+
+// ── process-global accessor ────────────────────────────────────────────────
+
+describe("getSubagentSessionRegistry (process-global accessor)", () => {
+  afterEach(() => {
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- Symbol-keyed global property; Map.delete() is not applicable
+    delete (globalThis as Record<symbol, unknown>)[REGISTRY_KEY];
+  });
+
+  test("returns a SubagentSessionRegistry instance", () => {
+    const registry = getSubagentSessionRegistry();
+    expect(registry).toBeInstanceOf(SubagentSessionRegistry);
+  });
+
+  test("returns the same instance on repeated calls", () => {
+    const first = getSubagentSessionRegistry();
+    const second = getSubagentSessionRegistry();
+    expect(first).toBe(second);
+  });
+
+  test("state registered through one call is visible through another call", () => {
+    const writer = getSubagentSessionRegistry();
+    writer.register("/sessions/child-tasks", {
+      agentName: "Explore",
+      parentSessionId: "parent-abc",
+    });
+
+    const reader = getSubagentSessionRegistry();
+    expect(reader.has("/sessions/child-tasks")).toBe(true);
+    expect(reader.get("/sessions/child-tasks")?.parentSessionId).toBe(
+      "parent-abc",
+    );
+  });
+
+  test("starts empty on first call", () => {
+    const registry = getSubagentSessionRegistry();
+    expect(registry.has("/sessions/any-key")).toBe(false);
+  });
+});

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

@@ -0,0 +1,75 @@
+import { describe, expect, test } from "vitest";
+
+import {
+  type ToolInputFormatter,
+  ToolInputFormatterRegistry,
+} from "#src/tool-input-formatter-registry";
+
+const noopFormatter: ToolInputFormatter = () => "preview";
+
+describe("ToolInputFormatterRegistry", () => {
+  describe("register", () => {
+    test("stores a formatter so get() returns it", () => {
+      const registry = new ToolInputFormatterRegistry();
+      registry.register("my-tool", noopFormatter);
+      expect(registry.get("my-tool")).toBe(noopFormatter);
+    });
+
+    test("returns a disposer that removes the formatter", () => {
+      const registry = new ToolInputFormatterRegistry();
+      const dispose = registry.register("my-tool", noopFormatter);
+      dispose();
+      expect(registry.get("my-tool")).toBeUndefined();
+    });
+
+    test("throws when a formatter is already registered for the same tool name", () => {
+      const registry = new ToolInputFormatterRegistry();
+      registry.register("my-tool", noopFormatter);
+      expect(() => registry.register("my-tool", () => undefined)).toThrow(
+        "my-tool",
+      );
+    });
+
+    test("allows registering different tool names independently", () => {
+      const registry = new ToolInputFormatterRegistry();
+      const formatterA: ToolInputFormatter = () => "a";
+      const formatterB: ToolInputFormatter = () => "b";
+      registry.register("tool-a", formatterA);
+      registry.register("tool-b", formatterB);
+      expect(registry.get("tool-a")).toBe(formatterA);
+      expect(registry.get("tool-b")).toBe(formatterB);
+    });
+  });
+
+  describe("disposer identity guard", () => {
+    test("stale disposer does not evict a later registration", () => {
+      const registry = new ToolInputFormatterRegistry();
+      const first: ToolInputFormatter = () => "first";
+      const second: ToolInputFormatter = () => "second";
+
+      const disposeFirst = registry.register("my-tool", first);
+      disposeFirst(); // removes first
+
+      registry.register("my-tool", second); // second registration is now valid
+      disposeFirst(); // calling stale disposer again — must not remove second
+
+      expect(registry.get("my-tool")).toBe(second);
+    });
+  });
+
+  describe("get", () => {
+    test("returns undefined for an unregistered tool name", () => {
+      const registry = new ToolInputFormatterRegistry();
+      expect(registry.get("unknown")).toBeUndefined();
+    });
+
+    test("the registered formatter is callable and returns its result", () => {
+      const registry = new ToolInputFormatterRegistry();
+      const fmt: ToolInputFormatter = (input) =>
+        typeof input.cmd === "string" ? `runs ${input.cmd}` : undefined;
+      registry.register("run", fmt);
+      expect(registry.get("run")?.({ cmd: "ls" })).toBe("runs ls");
+      expect(registry.get("run")?.({ other: true })).toBeUndefined();
+    });
+  });
+});

package/test/tool-preview-formatter.test.ts

@@ -1,5 +1,7 @@
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 
+import type { ToolInputFormatterLookup } from "#src/tool-input-formatter-registry";
+
 // Mock logging collaborator before importing the module under test.
 vi.mock("../src/logging.js", () => ({
   safeJsonStringify: vi.fn((value: unknown) => JSON.stringify(value)),
@@ -201,6 +203,77 @@ describe("ToolPreviewFormatter.formatToolInputForPrompt", () => {
   });
 });
 
+// ── formatToolInputForPrompt (custom formatter seam) ───────────────────────
+
+describe("ToolPreviewFormatter.formatToolInputForPrompt — custom formatter seam", () => {
+  function makeLookup(
+    toolName: string,
+    result: string | undefined,
+  ): ToolInputFormatterLookup {
+    return {
+      get: (name) => (name === toolName ? () => result : undefined),
+    };
+  }
+
+  test("uses a custom formatter's string result verbatim, bypassing the switch", () => {
+    const lookup = makeLookup("my-tool", "custom preview");
+    const f = new ToolPreviewFormatter(
+      {
+        toolInputPreviewMaxLength: TOOL_INPUT_PREVIEW_MAX_LENGTH,
+        toolTextSummaryMaxLength: TOOL_TEXT_SUMMARY_MAX_LENGTH,
+        toolInputLogPreviewMaxLength: TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH,
+      },
+      lookup,
+    );
+    expect(f.formatToolInputForPrompt("my-tool", {})).toBe("custom preview");
+  });
+
+  test("falls through to the built-in switch when custom formatter returns undefined", () => {
+    mockedStringify.mockReturnValue('{"x":1}');
+    const lookup = makeLookup("unknown-tool", undefined);
+    const f = new ToolPreviewFormatter(
+      {
+        toolInputPreviewMaxLength: TOOL_INPUT_PREVIEW_MAX_LENGTH,
+        toolTextSummaryMaxLength: TOOL_TEXT_SUMMARY_MAX_LENGTH,
+        toolInputLogPreviewMaxLength: TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH,
+      },
+      lookup,
+    );
+    // Falls through to JSON default for unknown tools
+    expect(f.formatToolInputForPrompt("unknown-tool", { x: 1 })).toContain(
+      '{"x":1}',
+    );
+  });
+
+  test("custom formatter for a built-in tool overrides the built-in preview", () => {
+    const lookup = makeLookup("read", "custom read summary");
+    const f = new ToolPreviewFormatter(
+      {
+        toolInputPreviewMaxLength: TOOL_INPUT_PREVIEW_MAX_LENGTH,
+        toolTextSummaryMaxLength: TOOL_TEXT_SUMMARY_MAX_LENGTH,
+        toolInputLogPreviewMaxLength: TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH,
+      },
+      lookup,
+    );
+    // Would normally use formatReadInputForPrompt; custom overrides it
+    expect(f.formatToolInputForPrompt("read", { path: "/foo.ts" })).toBe(
+      "custom read summary",
+    );
+  });
+
+  test("absent lookup preserves current behaviour for all tool types", () => {
+    const f = new ToolPreviewFormatter({
+      toolInputPreviewMaxLength: TOOL_INPUT_PREVIEW_MAX_LENGTH,
+      toolTextSummaryMaxLength: TOOL_TEXT_SUMMARY_MAX_LENGTH,
+      toolInputLogPreviewMaxLength: TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH,
+    });
+    // Built-in path still works
+    expect(f.formatToolInputForPrompt("read", { path: "/foo.ts" })).toContain(
+      "/foo.ts",
+    );
+  });
+});
+
 // ── formatGenericToolInputForLog ──────────────────────────────────────────
 
 describe("ToolPreviewFormatter.formatGenericToolInputForLog", () => {