@gotgenes/pi-permission-system 7.4.1 → 8.1.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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)
+
+
+### ⚠ BREAKING CHANGES
+
+* `registerSubagentSession` and `unregisterSubagentSession` are removed from the `PermissionsService` interface and its implementation. The `SubagentSessionInfo` type is no longer re-exported from the public service module.
+
+### Features
+
+* remove inbound subagent-registration methods from PermissionsService ([#267](https://github.com/gotgenes/pi-packages/issues/267)) ([552735a](https://github.com/gotgenes/pi-packages/commit/552735a97eec939fc06130bce059c78f03eb8e58))
+
+
+### Documentation
+
+* **pi-permission-system:** describe event-driven subagent registration ([#267](https://github.com/gotgenes/pi-packages/issues/267)) ([8c39b87](https://github.com/gotgenes/pi-packages/commit/8c39b8785aa389d96b5f38996711d8aa3dbeb284))
+
 ## [7.4.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v7.4.0...pi-permission-system-v7.4.1) (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": "7.4.1",
+  "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/index.ts

@@ -118,12 +118,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
         sessionRules,
       );
     },
-    registerSubagentSession(sessionKey, info) {
-      subagentRegistry.register(sessionKey, info);
-    },
-    unregisterSubagentSession(sessionKey) {
-      subagentRegistry.unregister(sessionKey);
-    },
     getToolPermission(toolName, agentName) {
       return runtime.permissionManager.getToolPermission(toolName, agentName);
     },

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/service.ts

@@ -11,10 +11,9 @@
  * reference — this ensures resilience across `/reload` and load-order edge cases.
  */
 
-import type { SubagentSessionInfo } from "./subagent-registry";
 import type { PermissionCheckResult, PermissionState } from "./types";
 
-export type { PermissionCheckResult, PermissionState, SubagentSessionInfo };
+export type { PermissionCheckResult, PermissionState };
 
 /** Process-global key for the service slot. */
 const SERVICE_KEY = Symbol.for("@gotgenes/pi-permission-system:service");
@@ -44,27 +43,6 @@ export interface PermissionsService {
     agentName?: string,
   ): PermissionCheckResult;
 
-  /**
-   * Register an in-process subagent session.
-   *
-   * Call this before `bindExtensions()` so that `isSubagentExecutionContext()`
-   * and permission-forwarding target resolution can detect the child session.
-   * Always pair with `unregisterSubagentSession()` in a `finally` block.
-   *
-   * @param sessionKey - Unique session identifier (use the session directory path).
-   * @param info       - Agent name and optional parent session ID.
-   */
-  registerSubagentSession(sessionKey: string, info: SubagentSessionInfo): void;
-
-  /**
-   * Remove a previously registered in-process subagent session.
-   *
-   * Safe to call even if `registerSubagentSession` was never called for this key.
-   *
-   * @param sessionKey - The same key passed to `registerSubagentSession`.
-   */
-  unregisterSubagentSession(sessionKey: string): void;
-
   /**
    * Query the tool-level permission state for pre-filtering tools before
    * creating a child session.

package/src/subagent-registry.ts

@@ -23,9 +23,9 @@ export interface SubagentSessionInfo {
 /**
  * Registry of active in-process subagent sessions.
  *
- * Owned by `ExtensionRuntime`; exposed to external callers through the
- * `PermissionsService` interface (`registerSubagentSession` /
- * `unregisterSubagentSession`).
+ * Owned by `ExtensionRuntime`; written exclusively by `subscribeSubagentLifecycle`
+ * via the `subagents:child:session-created` / `subagents:child:disposed` event
+ * subscription (ADR 0002 — the core publishes, consumers observe).
  *
  * Concurrent background agents are safe because each session has a unique
  * directory path as its key — no scalar global flag is needed.