@gotgenes/pi-permission-system 8.0.0 → 8.2.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v8.1.0...pi-permission-system-v8.2.0) (2026-05-31)
+
+
+### Features
+
+* add SessionApproval value object and SessionRules.record ([8f98d92](https://github.com/gotgenes/pi-packages/commit/8f98d9223a424b0993d51c2d9106e7d01c6819d7))
+* centralize decision-event construction in buildDecisionEvent ([19c2c83](https://github.com/gotgenes/pi-packages/commit/19c2c837b1907a4c302105ee86715533477247d4))
+
+## [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.2.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/bash-external-directory.ts

@@ -1,5 +1,6 @@
 import { getNonEmptyString, toRecord } from "#src/common";
 import type { Rule } from "#src/rule";
+import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { PermissionCheckResult } from "#src/types";
 import { extractExternalPathsFromBashCommand } from "./bash-path-extractor";
@@ -106,10 +107,7 @@ export async function describeBashExternalDirectoryGate(
       cwd: tcc.cwd,
       agentName: tcc.agentName ?? undefined,
     },
-    sessionApproval: {
-      surface: "external_directory",
-      patterns,
-    },
+    sessionApproval: SessionApproval.multiple("external_directory", patterns),
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,

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

@@ -1,5 +1,6 @@
 import { getNonEmptyString, toRecord } from "#src/common";
 import type { Rule } from "#src/rule";
+import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { PermissionCheckResult } from "#src/types";
 import { extractTokensForPathRules } from "./bash-path-extractor";
@@ -117,10 +118,7 @@ export async function describeBashPathGate(
       pathValue: worstToken,
       agentName: tcc.agentName ?? undefined,
     },
-    sessionApproval: {
-      surface: "path",
-      pattern,
-    },
+    sessionApproval: SessionApproval.single("path", pattern),
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,

package/src/handlers/gates/descriptor.ts

@@ -3,6 +3,7 @@ import type { PermissionPromptDecision } from "#src/permission-dialog";
 import type { PermissionDecisionEvent } from "#src/permission-events";
 import type { PromptPermissionDetails } from "#src/permission-prompter";
 import type { Rule } from "#src/rule";
+import type { SessionApproval } from "#src/session-approval";
 import type { PermissionCheckResult, PermissionState } from "#src/types";
 
 // ── Descriptor types ───────────────────────────────────────────────────────
@@ -22,12 +23,11 @@ export interface GateDescriptor {
   /** Structured denial context — the runner formats messages from this. */
   denialContext: DenialContext;
   /**
-   * Session-approval suggestion for "for this session" option.
-   * Single pattern or multiple patterns (bash external-directory gate).
+   * Session-approval suggestion for the "for this session" option.
+   * Wraps either a single pattern or multiple patterns behind a unified
+   * interface — the runner never needs to know which case applies.
    */
-  sessionApproval?:
-    | { surface: string; pattern: string }
-    | { surface: string; patterns: string[] };
+  sessionApproval?: SessionApproval;
   /** Details passed to the interactive permission prompt (requestId is added by the runner). */
   promptDetails: Omit<PromptPermissionDetails, "requestId">;
   /** Extra context fields written to the review log alongside gate outcomes. */
@@ -87,7 +87,7 @@ export interface GateRunnerDeps {
     sessionRules?: Rule[],
   ): PermissionCheckResult;
   getSessionRuleset(): Rule[];
-  approveSessionRule(surface: string, pattern: string): void;
+  recordSessionApproval(approval: SessionApproval): void;
   writeReviewLog(event: string, details: Record<string, unknown>): void;
   emitDecision(event: PermissionDecisionEvent): void;
   canConfirm(): boolean;

package/src/handlers/gates/external-directory.ts

@@ -4,6 +4,7 @@ import {
   isPiInfrastructureRead,
   normalizePathForComparison,
 } from "#src/path-utils";
+import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { GateResult } from "./descriptor";
 import { formatExternalDirectoryAskPrompt } from "./external-directory-messages";
@@ -83,10 +84,7 @@ export function describeExternalDirectoryGate(
       cwd: tcc.cwd,
       agentName: tcc.agentName ?? undefined,
     },
-    sessionApproval: {
-      surface: "external_directory",
-      pattern,
-    },
+    sessionApproval: SessionApproval.single("external_directory", pattern),
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,

package/src/handlers/gates/helpers.ts

@@ -1,4 +1,7 @@
-import type { PermissionDecisionResolution } from "#src/permission-events";
+import type {
+  PermissionDecisionEvent,
+  PermissionDecisionResolution,
+} from "#src/permission-events";
 import type { PermissionCheckResult } from "#src/types";
 
 /**
@@ -17,6 +20,32 @@ export function deriveDecisionValue(
   return toolName;
 }
 
+/**
+ * Build a `PermissionDecisionEvent` from the gate's inputs.
+ *
+ * Centralises the `origin / agentName / matchedPattern ?? null` normalization
+ * that is otherwise duplicated across the session-hit path and the gate-result
+ * path in `runGateCheck`.
+ */
+export function buildDecisionEvent(
+  decision: { surface: string; value: string },
+  check: Pick<PermissionCheckResult, "origin" | "matchedPattern">,
+  agentName: string | null,
+  result: "allow" | "deny",
+  resolution: PermissionDecisionResolution,
+): PermissionDecisionEvent {
+  return {
+    surface: decision.surface,
+    value: decision.value,
+    result,
+    resolution,
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- ?? null normalises undefined to null for the log record
+    origin: check.origin ?? null,
+    agentName: agentName ?? null,
+    matchedPattern: check.matchedPattern ?? null,
+  };
+}
+
 /**
  * Map the gate outcome back to a PermissionDecisionResolution.
  *

package/src/handlers/gates/path.ts

@@ -1,5 +1,6 @@
 import { getPathBearingToolPath } from "#src/path-utils";
 import type { Rule } from "#src/rule";
+import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { PermissionCheckResult } from "#src/types";
 import type { GateDescriptor, GateResult } from "./descriptor";
@@ -55,10 +56,7 @@ export function describePathGate(
       pathValue: filePath,
       agentName: tcc.agentName ?? undefined,
     },
-    sessionApproval: {
-      surface: "path",
-      pattern,
-    },
+    sessionApproval: SessionApproval.single("path", pattern),
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,

package/src/handlers/gates/runner.ts

@@ -7,7 +7,7 @@ import type { PermissionPromptDecision } from "#src/permission-dialog";
 import { applyPermissionGate } from "#src/permission-gate";
 import type { PermissionCheckResult } from "#src/types";
 import type { GateDescriptor, GateRunnerDeps } from "./descriptor";
-import { deriveResolution } from "./helpers";
+import { buildDecisionEvent, deriveResolution } from "./helpers";
 import type { GateOutcome } from "./types";
 
 /**
@@ -56,37 +56,21 @@ export async function runGateCheck(
       resolution: "session_approved",
       sessionApprovalPattern: check.matchedPattern,
     });
-    deps.emitDecision({
-      surface: descriptor.decision.surface,
-      value: descriptor.decision.value,
-      result: "allow",
-      resolution: "session_approved",
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- ?? null normalises undefined to null for the log record
-      origin: check.origin ?? null,
-      agentName: agentName ?? null,
-      matchedPattern: check.matchedPattern ?? null,
-    });
+    deps.emitDecision(
+      buildDecisionEvent(
+        descriptor.decision,
+        check,
+        agentName,
+        "allow",
+        "session_approved",
+      ),
+    );
     return { action: "allow" };
   }
 
   // 3. Apply the deny/ask/allow gate
   const canConfirm = deps.canConfirm();
 
-  // Resolve the first pattern for applyPermissionGate's sessionApproval param
-  const singleSessionApproval = descriptor.sessionApproval
-    ? "pattern" in descriptor.sessionApproval
-      ? {
-          surface: descriptor.sessionApproval.surface,
-          pattern: descriptor.sessionApproval.pattern,
-        }
-      : descriptor.sessionApproval.patterns.length > 0
-        ? {
-            surface: descriptor.sessionApproval.surface,
-            pattern: descriptor.sessionApproval.patterns[0],
-          }
-        : undefined
-    : undefined;
-
   // Construct messages from the centralized formatter.
   const messages = {
     denyReason: formatDenyReason(descriptor.denialContext),
@@ -99,7 +83,7 @@ export async function runGateCheck(
   const gateResult = await applyPermissionGate({
     state: check.state,
     canConfirm,
-    sessionApproval: singleSessionApproval,
+    sessionApproval: descriptor.sessionApproval?.toGateApproval(),
     promptForApproval: async () => {
       const decision = await deps.promptPermission({
         requestId: toolCallId,
@@ -119,37 +103,26 @@ export async function runGateCheck(
     gateResult.action === "allow" && gateResult.sessionApproval !== undefined;
 
   // 5. Emit decision event
-  deps.emitDecision({
-    surface: descriptor.decision.surface,
-    value: descriptor.decision.value,
-    result: gateResult.action === "allow" ? "allow" : "deny",
-    resolution: deriveResolution(
-      check.state,
-      gateResult.action,
-      hasSessionApproval,
-      canConfirm,
-      autoApproved,
+  deps.emitDecision(
+    buildDecisionEvent(
+      descriptor.decision,
+      check,
+      agentName,
+      gateResult.action === "allow" ? "allow" : "deny",
+      deriveResolution(
+        check.state,
+        gateResult.action,
+        hasSessionApproval,
+        canConfirm,
+        autoApproved,
+      ),
     ),
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- ?? null normalises undefined to null for the log record
-    origin: check.origin ?? null,
-    agentName: agentName ?? null,
-    matchedPattern: check.matchedPattern ?? null,
-  });
+  );
 
-  // 6. Record session approval(s)
-  if (gateResult.action === "allow" && hasSessionApproval) {
-    if (descriptor.sessionApproval) {
-      if ("patterns" in descriptor.sessionApproval) {
-        for (const pattern of descriptor.sessionApproval.patterns) {
-          deps.approveSessionRule(descriptor.sessionApproval.surface, pattern);
-        }
-      } else {
-        deps.approveSessionRule(
-          descriptor.sessionApproval.surface,
-          descriptor.sessionApproval.pattern,
-        );
-      }
-    }
+  // 6. Record session approval — tell the store; it owns the per-pattern loop
+  // hasSessionApproval already implies gateResult.action === "allow"
+  if (hasSessionApproval && descriptor.sessionApproval) {
+    deps.recordSessionApproval(descriptor.sessionApproval);
   }
 
   if (gateResult.action === "block") {

package/src/handlers/gates/tool.ts

@@ -1,7 +1,8 @@
 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 { SessionApproval } from "#src/session-approval";
+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 +32,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 +50,7 @@ export function describeToolGate(
     check,
     tcc.agentName ?? undefined,
     tcc.input,
+    formatter,
   );
 
   return {
@@ -59,10 +62,10 @@ export function describeToolGate(
       agentName: tcc.agentName ?? undefined,
       input: tcc.input,
     },
-    sessionApproval: {
-      surface: suggestion.surface,
-      pattern: suggestion.pattern,
-    },
+    sessionApproval: SessionApproval.single(
+      suggestion.surface,
+      suggestion.pattern,
+    ),
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,