@gotgenes/pi-permission-system 8.2.0 → 8.3.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.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)
+
+
+### Bug Fixes
+
+* remove stale PermissionGateHandler import in tool-call.test.ts ([#288](https://github.com/gotgenes/pi-packages/issues/288)) ([67259f6](https://github.com/gotgenes/pi-packages/commit/67259f666938e15473016edfeafcb718abe304f7))
+
 ## [8.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v8.1.0...pi-permission-system-v8.2.0) (2026-05-31)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "8.2.0",
+  "version": "8.3.0",
   "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/config-loader.ts

@@ -33,74 +33,81 @@ export interface UnifiedConfigLoadResult {
 
 export function stripJsonComments(input: string): string {
   let output = "";
-  let inString = false;
-  let stringQuote: '"' | "'" | "" = "";
-  let escaping = false;
-  let inLineComment = false;
-  let inBlockComment = false;
-
-  for (let i = 0; i < input.length; i++) {
+  let i = 0;
+  while (i < input.length) {
     const char = input[i];
-    const next = input[i + 1] || "";
-
-    if (inLineComment) {
-      if (char === "\n") {
-        inLineComment = false;
-        output += char;
-      }
-      continue;
-    }
+    const next = input[i + 1] ?? "";
 
-    if (inBlockComment) {
-      if (char === "*" && next === "/") {
-        inBlockComment = false;
-        i++;
-      }
+    if (char === "/" && next === "/") {
+      const seg = consumeLineComment(input, i);
+      output += seg.output;
+      i = seg.nextIndex;
       continue;
     }
-
-    if (!inString && char === "/" && next === "/") {
-      inLineComment = true;
-      i++;
+    if (char === "/" && next === "*") {
+      const seg = consumeBlockComment(input, i);
+      output += seg.output;
+      i = seg.nextIndex;
       continue;
     }
-
-    if (!inString && char === "/" && next === "*") {
-      inBlockComment = true;
-      i++;
+    if (char === '"' || char === "'") {
+      const seg = consumeString(input, i);
+      output += seg.output;
+      i = seg.nextIndex;
       continue;
     }
 
     output += char;
+    i++;
+  }
+  return output;
+}
 
-    if (!inString && (char === '"' || char === "'")) {
-      inString = true;
-      stringQuote = char;
-      escaping = false;
-      continue;
-    }
+/** A consumed run of source: the text to emit and the index to resume scanning. */
+interface ScanSegment {
+  output: string;
+  nextIndex: number;
+}
 
-    if (!inString) {
-      continue;
-    }
+/** Consume a `//` line comment starting at `start`; drop the body, keep the newline. */
+function consumeLineComment(input: string, start: number): ScanSegment {
+  const newlineIndex = input.indexOf("\n", start);
+  if (newlineIndex === -1) return { output: "", nextIndex: input.length };
+  return { output: "\n", nextIndex: newlineIndex + 1 };
+}
+
+/** Consume a block comment starting at `start`; drop it entirely. */
+function consumeBlockComment(input: string, start: number): ScanSegment {
+  const closeIndex = input.indexOf("*/", start + 2);
+  if (closeIndex === -1) return { output: "", nextIndex: input.length };
+  return { output: "", nextIndex: closeIndex + 2 };
+}
 
+/**
+ * Consume a string literal starting at the opening quote at `start`.
+ * Honors backslash escapes so an escaped quote does not close the literal.
+ * Emits the opening quote, body, and closing quote verbatim.
+ */
+function consumeString(input: string, start: number): ScanSegment {
+  const quote = input[start];
+  let output = quote;
+  let i = start + 1;
+  let escaping = false;
+  while (i < input.length) {
+    const char = input[i];
+    output += char;
+    i++;
     if (escaping) {
       escaping = false;
       continue;
     }
-
     if (char === "\\") {
       escaping = true;
       continue;
     }
-
-    if (char === stringQuote) {
-      inString = false;
-      stringQuote = "";
-    }
+    if (char === quote) break;
   }
-
-  return output;
+  return { output, nextIndex: i };
 }
 
 function normalizeOptionalBoolean(value: unknown): boolean | undefined {

package/src/handlers/gates/bash-path-extractor.ts

@@ -1,6 +1,10 @@
 import { createRequire } from "node:module";
 import { basename, resolve } from "node:path";
 
+import {
+  classifyTokenAsPathCandidate,
+  classifyTokenAsRuleCandidate,
+} from "#src/handlers/gates/bash-token-classification";
 import {
   isPathWithinDirectory,
   isSafeSystemPath,
@@ -237,6 +241,47 @@ function extractCommandName(node: TSNode): string | undefined {
   return undefined;
 }
 
+/**
+ * Describes what the walker should do when it encounters a flag word inside
+ * a pattern-first command.  Using a discriminated union lets the `switch` in
+ * `collectPatternCommandTokens` narrow `nextArgAction` without a non-null
+ * assertion (which would trigger the Biome/ESLint assertion conflict).
+ */
+type PatternCommandFlagDirective =
+  | { kind: "end-of-flags" }
+  | { kind: "regular-flag" }
+  | {
+      kind: "consume-arg";
+      nextArgAction: "skip" | "extract";
+      setsExplicitScript: boolean;
+    };
+
+/**
+ * Classify a flag word from a pattern-first command into a directive that
+ * tells the walker how to handle the flag and its following argument.
+ */
+function classifyPatternCommandFlag(
+  text: string,
+  config: PatternCommandConfig,
+): PatternCommandFlagDirective {
+  if (text === "--") return { kind: "end-of-flags" };
+  if (config.argConsumingFlags.has(text)) {
+    return {
+      kind: "consume-arg",
+      nextArgAction: "skip",
+      setsExplicitScript: text === "-e" || text === "-f",
+    };
+  }
+  if (config.fileConsumingFlags.has(text)) {
+    return {
+      kind: "consume-arg",
+      nextArgAction: "extract",
+      setsExplicitScript: true,
+    };
+  }
+  return { kind: "regular-flag" };
+}
+
 /**
  * Collect path-candidate tokens from a command known to have
  * pattern/script arguments in leading positional slots.
@@ -254,14 +299,14 @@ function extractCommandName(node: TSNode): string | undefined {
  */
 function collectPatternCommandTokens(
   node: TSNode,
-  tokens: string[],
   config: PatternCommandConfig,
-): void {
+): string[] {
   const patternPositionals = config.patternPositionals ?? 1;
   let hasExplicitScript = false;
   let positionalsSeen = 0;
   let nextArgAction: "skip" | "extract" | null = null;
   let pastEndOfFlags = false;
+  const tokens: string[] = [];
 
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
@@ -274,7 +319,7 @@ function collectPatternCommandTokens(
     // Only process argument-like nodes; recurse into others
     // (e.g. command_substitution) for nested commands.
     if (!ARG_NODE_TYPES.has(child.type)) {
-      collectPathCandidateTokens(child, tokens);
+      tokens.push(...collectPathCandidateTokens(child));
       continue;
     }
 
@@ -298,23 +343,18 @@ function collectPatternCommandTokens(
       text.startsWith("-") &&
       text.length > 1
     ) {
-      if (text === "--") {
-        pastEndOfFlags = true;
-        continue;
-      }
-      if (config.argConsumingFlags.has(text)) {
-        nextArgAction = "skip";
-        if (text === "-e" || text === "-f") {
-          hasExplicitScript = true;
-        }
-        continue;
+      const directive = classifyPatternCommandFlag(text, config);
+      switch (directive.kind) {
+        case "end-of-flags":
+          pastEndOfFlags = true;
+          break;
+        case "consume-arg":
+          nextArgAction = directive.nextArgAction;
+          if (directive.setsExplicitScript) hasExplicitScript = true;
+          break;
+        case "regular-flag":
+          break;
       }
-      if (config.fileConsumingFlags.has(text)) {
-        nextArgAction = "extract";
-        hasExplicitScript = true;
-        continue;
-      }
-      // Regular flag — skip it.
       continue;
     }
 
@@ -327,181 +367,107 @@ function collectPatternCommandTokens(
     // File argument — collect as path candidate.
     tokens.push(text);
   }
+
+  return tokens;
 }
 
 /**
- * Recursively visit the AST and collect resolved text of nodes that
- * represent command arguments or redirect destinations.
- *
- * Skips `heredoc_body`, `heredoc_end`, and `comment` subtrees entirely.
- *
- * For commands in `PATTERN_FIRST_COMMANDS`, uses position-based
- * argument skipping to avoid collecting inline patterns/scripts
- * as path candidates. For all other commands, collects all
- * arguments generically.
+ * Collect all argument tokens from a generic (non-pattern-first) command node,
+ * skipping the command name and variable assignments.
  */
-function collectPathCandidateTokens(node: TSNode, tokens: string[]): void {
-  if (SKIP_SUBTREE_TYPES.has(node.type)) return;
-
-  // Extract arguments from `command` nodes.
-  if (node.type === "command") {
-    const commandName = extractCommandName(node);
-    const patternConfig = commandName
-      ? PATTERN_FIRST_COMMANDS.get(commandName)
-      : undefined;
-
-    if (patternConfig) {
-      collectPatternCommandTokens(node, tokens, patternConfig);
-      return;
-    }
-
-    // Generic extraction: collect all arguments (skip command name).
-    let seenCommandName = false;
-    for (let i = 0; i < node.childCount; i++) {
-      const child = node.child(i);
-      if (!child) continue;
+function collectGenericCommandTokens(node: TSNode): string[] {
+  const tokens: string[] = [];
+  let seenCommandName = false;
 
-      if (child.type === "command_name") {
-        seenCommandName = true;
-        continue;
-      }
-      // Skip variable_assignment nodes (FOO=/bar)
-      if (child.type === "variable_assignment") continue;
-
-      // If there was no explicit command_name node, the first word-like
-      // child is the command name itself — skip it.
-      if (!seenCommandName && ARG_NODE_TYPES.has(child.type)) {
-        seenCommandName = true;
-        continue;
-      }
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
 
-      // Argument nodes: resolve their text and collect.
-      if (ARG_NODE_TYPES.has(child.type)) {
-        tokens.push(resolveNodeText(child));
-        continue;
-      }
+    if (child.type === "command_name") {
+      seenCommandName = true;
+      continue;
+    }
+    // Skip variable_assignment nodes (FOO=/bar)
+    if (child.type === "variable_assignment") continue;
 
-      // Recurse into other children (e.g. command_substitution nested in args)
-      collectPathCandidateTokens(child, tokens);
+    // If there was no explicit command_name node, the first word-like
+    // child is the command name itself — skip it.
+    if (!seenCommandName && ARG_NODE_TYPES.has(child.type)) {
+      seenCommandName = true;
+      continue;
     }
-    return;
-  }
 
-  // Extract redirect destinations from `file_redirect` nodes.
-  if (node.type === "file_redirect") {
-    for (let i = 0; i < node.childCount; i++) {
-      const child = node.child(i);
-      if (!child) continue;
-      if (
-        child.type === "word" ||
-        child.type === "concatenation" ||
-        child.type === "string" ||
-        child.type === "raw_string"
-      ) {
-        tokens.push(resolveNodeText(child));
-      }
+    // Argument nodes: resolve their text and collect.
+    if (ARG_NODE_TYPES.has(child.type)) {
+      tokens.push(resolveNodeText(child));
+      continue;
     }
-    return;
+
+    // Recurse into other children (e.g. command_substitution nested in args)
+    tokens.push(...collectPathCandidateTokens(child));
   }
 
-  // For all other node types, recurse into children.
+  return tokens;
+}
+
+/**
+ * Collect redirect-destination tokens from a `file_redirect` node.
+ */
+function collectRedirectTokens(node: TSNode): string[] {
+  const tokens: string[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child) continue;
-    collectPathCandidateTokens(child, tokens);
+    if (ARG_NODE_TYPES.has(child.type)) {
+      tokens.push(resolveNodeText(child));
+    }
   }
+  return tokens;
 }
 
 /**
- * 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.
+ * Select the collection strategy for a `command` node: pattern-first
+ * commands use `collectPatternCommandTokens`; all others use
+ * `collectGenericCommandTokens`.
  */
-const REGEX_METACHAR_PATTERN = /\.\*|\.\+|\\\||\\\(|\\\)|\[.*?\]|\^\//;
+function collectCommandTokens(node: TSNode): string[] {
+  const commandName = extractCommandName(node);
+  const config = commandName
+    ? PATTERN_FIRST_COMMANDS.get(commandName)
+    : undefined;
+  return config
+    ? collectPatternCommandTokens(node, config)
+    : collectGenericCommandTokens(node);
+}
 
 /**
- * Broader token classification for cross-cutting `path` rules.
+ * Recursively visit the AST and collect resolved text of nodes that
+ * represent command arguments or redirect destinations.
  *
- * Accepts the same rejections as `classifyTokenAsPathCandidate` (empty, flags,
- * env assignments, URLs, @scope/package, bare-slash, regex metacharacters),
- * but also accepts:
- * - Tokens starting with `.` (dot-files: `.env`, `./src`)
- * - Tokens containing `/` (relative paths: `src/foo.ts`)
+ * Skips `heredoc_body`, `heredoc_end`, and `comment` subtrees entirely.
  *
- * Does NOT require the strict "must start with `/` or `~/` or contain `..`"
- * gate that the external-directory classifier uses.
+ * For commands in `PATTERN_FIRST_COMMANDS`, uses position-based
+ * argument skipping to avoid collecting inline patterns/scripts
+ * as path candidates. For all other commands, collects all
+ * arguments generically.
  */
-function classifyTokenAsRuleCandidate(token: string): string | null {
-  if (!token) return null;
-  if (token.startsWith("-")) return null;
-
-  const eqIndex = token.indexOf("=");
-  const slashIndex = token.indexOf("/");
-  if (eqIndex !== -1 && (slashIndex === -1 || eqIndex < slashIndex)) {
-    return null;
-  }
-
-  if (URL_PATTERN.test(token)) return null;
-  if (token.startsWith("@") && !token.startsWith("@/")) return null;
-  if (/^\/+$/.test(token)) return null;
-  if (REGEX_METACHAR_PATTERN.test(token)) return null;
+function collectPathCandidateTokens(node: TSNode): string[] {
+  if (SKIP_SUBTREE_TYPES.has(node.type)) return [];
+  if (node.type === "command") return collectCommandTokens(node);
+  if (node.type === "file_redirect") return collectRedirectTokens(node);
 
-  // Accept: starts with . (dot-files, ./ relative), contains / (paths),
-  // starts with / or ~/ (absolute/home), or contains .. (parent traversal).
-  if (token.startsWith(".")) return token;
-  if (token.includes("/")) return token;
-  if (token.startsWith("~/")) return token;
-  if (token.includes("..")) return token;
-
-  return null;
-}
-
-/**
- * Determines whether a token looks like a path candidate worth resolving.
- * Returns the raw token string if it's a candidate, or null to skip.
- */
-function classifyTokenAsPathCandidate(token: string): string | null {
-  // Skip empty tokens
-  if (!token) return null;
-
-  // Skip flags
-  if (token.startsWith("-")) return null;
-
-  // Skip env assignments (FOO=/bar)
-  const eqIndex = token.indexOf("=");
-  const slashIndex = token.indexOf("/");
-  if (eqIndex !== -1 && (slashIndex === -1 || eqIndex < slashIndex)) {
-    return null;
+  const tokens: string[] = [];
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child) tokens.push(...collectPathCandidateTokens(child));
   }
-
-  // Skip URLs
-  if (URL_PATTERN.test(token)) return null;
-
-  // Skip @scope/package patterns
-  if (token.startsWith("@") && !token.startsWith("@/")) return null;
-
-  // Skip bare-slash tokens (// JS comments, lone /, etc.) — they resolve to root
-  // and are never meaningful path arguments in practice.
-  if (/^\/+$/.test(token)) return null;
-
-  // Skip tokens that contain regex metacharacter sequences — these are almost
-  // certainly grep/sed/awk patterns, not filesystem paths.
-  // Matches: .*, .+, \|, \(, \), [...], or ^/ (anchored regex starting with /)
-  if (REGEX_METACHAR_PATTERN.test(token)) return null;
-
-  // Must look like a path: starts with /, ~/, or contains ..
-  if (token.startsWith("/")) return token;
-  if (token.startsWith("~/")) return token;
-  if (token.includes("..")) return token;
-
-  return null;
+  return tokens;
 }
 
+// Token classification is delegated to bash-token-classification.ts,
+// which exports classifyTokenAsPathCandidate and classifyTokenAsRuleCandidate
+// with a shared rejectNonPathToken predicate eliminating the prior clone.
+
 // ── Leading cd detection ───────────────────────────────────────────────────
 
 /**
@@ -596,10 +562,10 @@ export async function extractExternalPathsFromBashCommand(
   if (!tree) return [];
 
   let cdTarget: string | undefined;
-  const tokens: string[] = [];
+  let tokens: string[] = [];
   try {
     cdTarget = extractLeadingCdTarget(tree.rootNode);
-    collectPathCandidateTokens(tree.rootNode, tokens);
+    tokens = collectPathCandidateTokens(tree.rootNode);
   } finally {
     tree.delete();
   }
@@ -647,9 +613,9 @@ export async function extractTokensForPathRules(
   const tree = parser.parse(command);
   if (!tree) return [];
 
-  const tokens: string[] = [];
+  let tokens: string[] = [];
   try {
-    collectPathCandidateTokens(tree.rootNode, tokens);
+    tokens = collectPathCandidateTokens(tree.rootNode);
   } finally {
     tree.delete();
   }