@gotgenes/pi-permission-system 8.0.0 → 8.1.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v8.0.0...pi-permission-system-v8.1.0) (2026-05-31)
+
+
+### Features
+
+* add toolInputPreviewMaxLength and toolTextSummaryMaxLength config fields ([#266](https://github.com/gotgenes/pi-packages/issues/266)) ([3a7dafb](https://github.com/gotgenes/pi-packages/commit/3a7dafbb0bb8534dabda7eeba6c4d35ba2e8708b))
+* use configured preview limits in permission prompts ([#266](https://github.com/gotgenes/pi-packages/issues/266)) ([83e2829](https://github.com/gotgenes/pi-packages/commit/83e2829175a55f2f0436c742e19e3753ee171e47))
+
+
+### Documentation
+
+* document configurable tool-preview length knobs ([#266](https://github.com/gotgenes/pi-packages/issues/266)) ([6d0b134](https://github.com/gotgenes/pi-packages/commit/6d0b134be4ef4c90ddf582b32058c3ec9d2eb13f))
+
 ## [8.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v7.4.1...pi-permission-system-v8.0.0) (2026-05-30)
 
 

package/config/config.example.json

@@ -5,6 +5,9 @@
   "permissionReviewLog": true,
   "yoloMode": false,
 
+  "toolInputPreviewMaxLength": 400,
+  "toolTextSummaryMaxLength": 120,
+
   "piInfrastructureReadPaths": [],
 
   "permission": {

package/package.json

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

package/schemas/permissions.schema.json

@@ -29,6 +29,18 @@
       "type": "boolean",
       "default": false
     },
+    "toolInputPreviewMaxLength": {
+      "description": "Maximum character length of the inline-JSON tool-input preview shown in permission prompts. Omit to use the default (200). Set to a large value to disable truncation.",
+      "markdownDescription": "Maximum character length of the inline-JSON tool-input preview shown in permission prompts.\n\nOmit to use the default (200). Set to a large value (e.g. `10000`) to effectively disable truncation and see the full input.",
+      "type": "integer",
+      "minimum": 1
+    },
+    "toolTextSummaryMaxLength": {
+      "description": "Maximum character length of inline pattern/path summaries (e.g. grep patterns, find globs, ls paths) in permission prompts. Omit to use the default (80).",
+      "markdownDescription": "Maximum character length of inline pattern/path summaries (e.g. grep patterns, find globs, ls paths) shown in permission prompts.\n\nOmit to use the default (80). Increase this when working with long regexes or deep paths that are being cut off.",
+      "type": "integer",
+      "minimum": 1
+    },
     "piInfrastructureReadPaths": {
       "description": "Additional directories to auto-allow for reads as Pi infrastructure, bypassing the external_directory gate. Supports ~ expansion and wildcard patterns (* and ?).",
       "markdownDescription": "Additional directories to auto-allow for reads as Pi infrastructure, bypassing the `external_directory` gate.\n\nThe extension auto-discovers the global node_modules root (walks up from the extension's install path; falls back to `npm root -g` from a dev checkout), `agentDir`, `agentDir/git`, and project-local `.pi/npm/` and `.pi/git/`. Add entries here for edge cases where auto-discovery is insufficient (e.g. custom `npmCommand` pointing to pnpm).\n\nSupports `~`/`$HOME` expansion. Entries may be plain directory prefixes or wildcard patterns using `*` (matches any characters, including `/`) and `?` (matches exactly one character). `**` and `*` are equivalent — both cross directory boundaries.",

package/src/extension-config.ts

@@ -12,6 +12,10 @@ export interface PermissionSystemExtensionConfig {
   yoloMode: boolean;
   /** Additional directories to auto-allow for reads as Pi infrastructure. */
   piInfrastructureReadPaths?: string[];
+  /** Max length of the inline-JSON input preview shown in permission prompts. Defaults to 200. */
+  toolInputPreviewMaxLength?: number;
+  /** Max length of inline pattern/path summaries (grep/find/ls) in permission prompts. Defaults to 80. */
+  toolTextSummaryMaxLength?: number;
 }
 
 export const DEFAULT_EXTENSION_CONFIG: PermissionSystemExtensionConfig = {
@@ -42,6 +46,13 @@ export function detectMisplacedPermissionKeys(
   return Object.keys(raw).filter((key) => PERMISSION_POLICY_KEYS.has(key));
 }
 
+/** Returns `raw` if it is a positive integer; otherwise `undefined`. */
+export function normalizeOptionalPositiveInt(raw: unknown): number | undefined {
+  return typeof raw === "number" && Number.isInteger(raw) && raw > 0
+    ? raw
+    : undefined;
+}
+
 export function normalizePermissionSystemConfig(
   raw: unknown,
 ): PermissionSystemExtensionConfig {
@@ -60,6 +71,18 @@ export function normalizePermissionSystemConfig(
   if (piInfrastructureReadPaths !== undefined) {
     result.piInfrastructureReadPaths = piInfrastructureReadPaths;
   }
+  const toolInputPreviewMaxLength = normalizeOptionalPositiveInt(
+    record.toolInputPreviewMaxLength,
+  );
+  if (toolInputPreviewMaxLength !== undefined) {
+    result.toolInputPreviewMaxLength = toolInputPreviewMaxLength;
+  }
+  const toolTextSummaryMaxLength = normalizeOptionalPositiveInt(
+    record.toolTextSummaryMaxLength,
+  );
+  if (toolTextSummaryMaxLength !== undefined) {
+    result.toolTextSummaryMaxLength = toolTextSummaryMaxLength;
+  }
   return result;
 }
 

package/src/handlers/gates/tool.ts

@@ -1,7 +1,7 @@
 import { getPathBearingToolPath, PATH_BEARING_TOOLS } from "#src/path-utils";
 import { suggestSessionPattern } from "#src/pattern-suggest";
 import { formatAskPrompt } from "#src/permission-prompts";
-import { getPermissionLogContext } from "#src/tool-input-preview";
+import type { ToolPreviewFormatter } from "#src/tool-preview-formatter";
 import type { PermissionCheckResult } from "#src/types";
 import type { GateDescriptor } from "./descriptor";
 import { deriveDecisionValue } from "./helpers";
@@ -31,8 +31,9 @@ function deriveSuggestionValue(
 export function describeToolGate(
   tcc: ToolCallContext,
   check: PermissionCheckResult,
+  formatter: ToolPreviewFormatter,
 ): GateDescriptor {
-  const permissionLogContext = getPermissionLogContext(
+  const permissionLogContext = formatter.getPermissionLogContext(
     check,
     tcc.input,
     PATH_BEARING_TOOLS,
@@ -48,6 +49,7 @@ export function describeToolGate(
     check,
     tcc.agentName ?? undefined,
     tcc.input,
+    formatter,
   );
 
   return {

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

@@ -16,6 +16,10 @@ import {
   formatUnknownToolReason,
 } from "#src/permission-prompts";
 import type { PermissionSession } from "#src/permission-session";
+import {
+  resolveToolPreviewLimits,
+  ToolPreviewFormatter,
+} from "#src/tool-preview-formatter";
 import {
   checkRequestedToolRegistration,
   getToolNameFromValue,
@@ -23,7 +27,7 @@ import {
 } from "#src/tool-registry";
 import { describeBashExternalDirectoryGate } from "./gates/bash-external-directory";
 import { describeBashPathGate } from "./gates/bash-path";
-import type { GateRunnerDeps } from "./gates/descriptor";
+import type { GateResult, GateRunnerDeps } from "./gates/descriptor";
 import { isGateBypass } from "./gates/descriptor";
 import { describeExternalDirectoryGate } from "./gates/external-directory";
 import { describePathGate } from "./gates/path";
@@ -58,30 +62,13 @@ export class PermissionGateHandler {
   ): Promise<{ block?: true; reason?: string }> {
     this.session.activate(ctx);
 
-    const agentName = this.session.resolveAgentName(ctx);
-    const toolName = getToolNameFromValue(event);
-
-    if (!toolName) {
-      return { block: true, reason: formatMissingToolNameReason() };
-    }
-
-    const registrationCheck = checkRequestedToolRegistration(
-      toolName,
-      this.toolRegistry.getAll(),
-    );
-    if (registrationCheck.status === "missing-tool-name") {
-      return { block: true, reason: formatMissingToolNameReason() };
+    const validation = validateRequestedTool(event, this.toolRegistry.getAll());
+    if (validation.status === "block") {
+      return { block: true, reason: validation.reason };
     }
+    const toolName = validation.toolName;
 
-    if (registrationCheck.status === "unregistered") {
-      return {
-        block: true,
-        reason: formatUnknownToolReason(
-          registrationCheck.requestedToolName,
-          registrationCheck.availableToolNames,
-        ),
-      };
-    }
+    const agentName = this.session.resolveAgentName(ctx);
 
     const input = getEventInput(event);
     const toolCallId =
@@ -126,136 +113,78 @@ export class PermissionGateHandler {
       promptPermission,
     };
 
-    // ── Skill-read gate (descriptor + runner) ───────────────────────────────
-    const skillDescriptor = describeSkillReadGate(tcc, () =>
-      this.session.getActiveSkillEntries(),
-    );
-    if (skillDescriptor) {
-      const skillResult = await runGateCheck(
-        skillDescriptor,
+    // ── Unified gate executor ─────────────────────────────────────────────
+    // Handles the bypass log/emit branch, calls runGateCheck for descriptors,
+    // and returns a block result or undefined (allow / no-op).
+    const runGate = async (
+      gate: GateResult,
+    ): Promise<{ block: true; reason: string } | undefined> => {
+      if (!gate) {
+        return undefined;
+      }
+      if (isGateBypass(gate)) {
+        if (gate.log) {
+          writeReviewLog(gate.log.event, gate.log.details);
+        }
+        if (gate.decision) {
+          emitDecision(gate.decision);
+        }
+        return undefined;
+      }
+      const result = await runGateCheck(
+        gate,
         tcc.agentName,
         tcc.toolCallId,
         runnerDeps,
       );
-      if (skillResult.action === "block") {
-        return { block: true, reason: skillResult.reason };
-      }
-    }
+      return result.action === "block"
+        ? { block: true, reason: result.reason }
+        : undefined;
+    };
 
-    // ── Path gate for tools (descriptor + runner) ────────────────────────────
-    const pathDesc = describePathGate(tcc, checkPermission, getSessionRuleset);
-    if (pathDesc) {
-      if (isGateBypass(pathDesc)) {
-        if (pathDesc.log) {
-          writeReviewLog(pathDesc.log.event, pathDesc.log.details);
-        }
-      } else {
-        const pathResult = await runGateCheck(
-          pathDesc,
-          tcc.agentName,
-          tcc.toolCallId,
-          runnerDeps,
-        );
-        if (pathResult.action === "block") {
-          return { block: true, reason: pathResult.reason };
-        }
-      }
-    }
+    const formatter = new ToolPreviewFormatter(
+      resolveToolPreviewLimits(this.session.config),
+    );
 
-    // ── External-directory gate (descriptor + runner) ────────────────────────
+    // ── Ordered gate pipeline ─────────────────────────────────────────────
+    // infraDirs is computed once, outside the pipeline, exactly as before.
     const infraDirs = [
       ...this.session.getInfrastructureDirs(),
       ...this.session.getInfrastructureReadPaths(),
     ];
-    const extDirDesc = describeExternalDirectoryGate(tcc, infraDirs);
-    if (extDirDesc) {
-      if (isGateBypass(extDirDesc)) {
-        if (extDirDesc.log) {
-          writeReviewLog(extDirDesc.log.event, extDirDesc.log.details);
-        }
-        if (extDirDesc.decision) {
-          emitDecision(extDirDesc.decision);
-        }
-      } else {
-        const extDirResult = await runGateCheck(
-          extDirDesc,
-          tcc.agentName,
-          tcc.toolCallId,
-          runnerDeps,
-        );
-        if (extDirResult.action === "block") {
-          return { block: true, reason: extDirResult.reason };
-        }
-      }
-    }
 
-    // ── Bash external-directory gate (descriptor + runner) ───────────────────
-    const bashExtDesc = await describeBashExternalDirectoryGate(
-      tcc,
-      checkPermission,
-      getSessionRuleset,
-    );
-    if (bashExtDesc) {
-      if (isGateBypass(bashExtDesc)) {
-        if (bashExtDesc.log) {
-          writeReviewLog(bashExtDesc.log.event, bashExtDesc.log.details);
-        }
-      } else {
-        const bashExtResult = await runGateCheck(
-          bashExtDesc,
-          tcc.agentName,
-          tcc.toolCallId,
-          runnerDeps,
+    const gateProducers: Array<() => GateResult | Promise<GateResult>> = [
+      () =>
+        describeSkillReadGate(tcc, () => this.session.getActiveSkillEntries()),
+      () => describePathGate(tcc, checkPermission, getSessionRuleset),
+      () => describeExternalDirectoryGate(tcc, infraDirs),
+      () =>
+        describeBashExternalDirectoryGate(
+          tcc,
+          checkPermission,
+          getSessionRuleset,
+        ),
+      () => describeBashPathGate(tcc, checkPermission, getSessionRuleset),
+      () => {
+        const toolCheck = checkPermission(
+          tcc.toolName,
+          tcc.input,
+          tcc.agentName ?? undefined,
+          getSessionRuleset(),
         );
-        if (bashExtResult.action === "block") {
-          return { block: true, reason: bashExtResult.reason };
-        }
-      }
-    }
+        const toolDescriptor = describeToolGate(tcc, toolCheck, formatter);
+        toolDescriptor.preCheck = toolCheck;
+        return toolDescriptor;
+      },
+    ];
 
-    // ── Bash path gate (descriptor + runner) ────────────────────────────────
-    const bashPathDesc = await describeBashPathGate(
-      tcc,
-      checkPermission,
-      getSessionRuleset,
-    );
-    if (bashPathDesc) {
-      if (isGateBypass(bashPathDesc)) {
-        if (bashPathDesc.log) {
-          writeReviewLog(bashPathDesc.log.event, bashPathDesc.log.details);
-        }
-      } else {
-        const bashPathResult = await runGateCheck(
-          bashPathDesc,
-          tcc.agentName,
-          tcc.toolCallId,
-          runnerDeps,
-        );
-        if (bashPathResult.action === "block") {
-          return { block: true, reason: bashPathResult.reason };
-        }
+    for (const produce of gateProducers) {
+      const blocked = await runGate(await produce());
+      if (blocked) {
+        return blocked;
       }
     }
 
-    // ── Normal tool permission gate (descriptor + runner) ────────────────────
-    const toolCheck = checkPermission(
-      tcc.toolName,
-      tcc.input,
-      tcc.agentName ?? undefined,
-      getSessionRuleset(),
-    );
-    const toolDescriptor = describeToolGate(tcc, toolCheck);
-    toolDescriptor.preCheck = toolCheck;
-    const toolResult = await runGateCheck(
-      toolDescriptor,
-      tcc.agentName,
-      tcc.toolCallId,
-      runnerDeps,
-    );
-    if (toolResult.action === "block") {
-      return { block: true, reason: toolResult.reason };
-    }
-
     return {};
   }
 
@@ -352,7 +281,46 @@ export class PermissionGateHandler {
   }
 }
 
-// ── Pure helpers (re-exported from original modules) ──────────────────────
+// ── Pure helpers ─────────────────────────────────────────────────────────
+
+/** Discriminated result of validating a tool-call event's name and registration. */
+export type RequestedToolValidation =
+  | { status: "ok"; toolName: string }
+  | { status: "block"; reason: string };
+
+/**
+ * Validate the tool name from a raw event against the registered tool list.
+ *
+ * Composes `getToolNameFromValue` + `checkRequestedToolRegistration` + the
+ * two reason formatters and returns a discriminated result so `handleToolCall`
+ * reads as a straight validate → proceed path without nested early-returns.
+ *
+ * Returns the **raw** tool name (not the normalised form) so that
+ * `ToolCallContext.toolName` stays identical to the pre-extraction behaviour.
+ */
+export function validateRequestedTool(
+  event: unknown,
+  availableTools: readonly unknown[],
+): RequestedToolValidation {
+  const toolName = getToolNameFromValue(event);
+  if (!toolName) {
+    return { status: "block", reason: formatMissingToolNameReason() };
+  }
+  const check = checkRequestedToolRegistration(toolName, availableTools);
+  if (check.status === "missing-tool-name") {
+    return { status: "block", reason: formatMissingToolNameReason() };
+  }
+  if (check.status === "unregistered") {
+    return {
+      status: "block",
+      reason: formatUnknownToolReason(
+        check.requestedToolName,
+        check.availableToolNames,
+      ),
+    };
+  }
+  return { status: "ok", toolName };
+}
 
 /**
  * Extract the tool input from an event, checking both `input` and `arguments`

package/src/permission-prompts.ts

@@ -1,5 +1,5 @@
 import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
-import { formatToolInputForPrompt } from "./tool-input-preview";
+import type { ToolPreviewFormatter } from "./tool-preview-formatter";
 import type { PermissionCheckResult } from "./types";
 
 // NOTE: formatDenyReason, formatUserDeniedReason, and
@@ -31,6 +31,7 @@ export function formatAskPrompt(
   result: PermissionCheckResult,
   agentName?: string,
   input?: unknown,
+  formatter?: ToolPreviewFormatter,
 ): string {
   const subject = agentName ? `Agent '${agentName}'` : "Current agent";
 
@@ -51,7 +52,9 @@ export function formatAskPrompt(
   const patternInfo = result.matchedPattern
     ? ` (matched '${result.matchedPattern}')`
     : "";
-  const inputPreview = formatToolInputForPrompt(result.toolName, input);
+  const inputPreview = formatter
+    ? formatter.formatToolInputForPrompt(result.toolName, input)
+    : "";
   const inputSuffix = inputPreview ? ` ${inputPreview}` : "";
   return `${subject} requested tool '${result.toolName}'${patternInfo}${inputSuffix}. Allow this call?`;
 }

package/src/tool-input-preview.ts

@@ -1,6 +1,5 @@
 import { getNonEmptyString, toRecord } from "./common";
 import { safeJsonStringify } from "./logging";
-import type { PermissionCheckResult } from "./types";
 
 export const TOOL_INPUT_PREVIEW_MAX_LENGTH = 200;
 export const TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH = 1000;
@@ -10,14 +9,6 @@ export function truncateInlineText(value: string, maxLength: number): string {
   return value.length > maxLength ? `${value.slice(0, maxLength)}…` : value;
 }
 
-export function sanitizeInlineText(
-  value: string,
-  maxLength = TOOL_TEXT_SUMMARY_MAX_LENGTH,
-): string {
-  const normalized = value.replace(/\s+/g, " ").trim();
-  return normalized ? truncateInlineText(normalized, maxLength) : "empty text";
-}
-
 export function countTextLines(value: string): number {
   if (!value) {
     return 0;
@@ -95,30 +86,6 @@ export function formatReadInputForPrompt(
   return parts.length > 0 ? `for ${parts.join(", ")}` : "";
 }
 
-export function 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 '${sanitizeInlineText(pattern)}'`);
-  }
-  if (glob) {
-    parts.push(`glob '${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(", ")}` : "";
-}
-
 export function serializeToolInputPreview(input: unknown): string {
   const serialized = safeJsonStringify(input);
   if (!serialized || serialized === "{}" || serialized === "null") {
@@ -127,86 +94,3 @@ export function serializeToolInputPreview(input: unknown): string {
 
   return serialized.replace(/\s+/g, " ").trim();
 }
-
-export function formatJsonInputForPrompt(input: unknown): string {
-  const inline = serializeToolInputPreview(input);
-  return inline
-    ? `with input ${truncateInlineText(inline, TOOL_INPUT_PREVIEW_MAX_LENGTH)}`
-    : "";
-}
-
-export function 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 formatSearchInputForPrompt(toolName, inputRecord);
-    default:
-      return formatJsonInputForPrompt(input);
-  }
-}
-
-export function formatGenericToolInputForLog(
-  input: unknown,
-): string | undefined {
-  const inline = serializeToolInputPreview(input);
-  return inline
-    ? `input ${truncateInlineText(inline, TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH)}`
-    : undefined;
-}
-
-export function 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 = formatToolInputForPrompt(result.toolName, input);
-    return inputPreview
-      ? truncateInlineText(inputPreview, TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH)
-      : undefined;
-  }
-
-  return formatGenericToolInputForLog(input);
-}
-
-export function getPermissionLogContext(
-  result: PermissionCheckResult,
-  input: unknown,
-  pathBearingTools: ReadonlySet<string>,
-): {
-  command?: string;
-  target?: string;
-  toolInputPreview?: string;
-  origin?: string;
-} {
-  return {
-    command: result.command,
-    target: result.target,
-    toolInputPreview: getToolInputPreviewForLog(
-      result,
-      input,
-      pathBearingTools,
-    ),
-    origin: result.origin,
-  };
-}