@gotgenes/pi-permission-system 25.4.0 → 26.0.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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).
 
+## [26.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v25.4.0...pi-permission-system-v26.0.0) (2026-08-16)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** the `message` field is removed from every `permission_request.*` review-log entry. A consumer parsing it should read the structured fields instead: `surface`, `matchedPattern`, `executedUnit`, `commandContext`, `invokedToolName`, `forwarded`, and `requesterSessionId`, alongside the existing `toolName`, `command`, `path`, `target`, and `toolInputPreview`.
+* **pi-permission-system:** values in the permission review log are now truncated at `reviewLogFieldMaxWidth` (default 1000) with a trailing ellipsis, where a bash `command` was previously written whole. Raise `reviewLogFieldMaxWidth` to keep longer values. `ToolPreviewFormatterOptions.toolInputLogPreviewMaxLength` and `TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH` are removed, superseded by that setting.
+* **pi-permission-system:** `toolInputPreviewMaxLength` and `toolTextSummaryMaxLength` are still accepted but ignored, and a config setting either now logs a deprecation warning at session start. Remove them; use `promptMaxRows` and `promptFieldMaxWidth` to bound what a permission prompt renders.
+* **pi-permission-system:** `PermissionUiPromptEvent.message` is removed. Read `request.value` for the decision-relevant value and `request.matchedPattern` for the rule that fired; `surface`, `value`, `agentName`, and `forwarding` are unchanged. `DirectPromptInput.message` likewise becomes `payload: PromptPayload`.
+* **pi-permission-system:** `ForwardedPermissionRequest.message` is removed and replaced by `payload: PromptPayload`, which carries the ask's complete structured facts. A serving node on this version accepts an older child's `message`-only request and renders it from `surface`, `value`, and the requester provenance; an older *parent* rejects a newer child's request, so upgrade the parent session first.
+
+### Features
+
+* **pi-permission-system:** bound review-log field width with reviewLogFieldMaxWidth ([#746](https://github.com/gotgenes/pi-packages/issues/746)) ([dceb931](https://github.com/gotgenes/pi-packages/commit/dceb93197e5f0e16287d63a68fcb2cad0bec2e97))
+* **pi-permission-system:** carry the prompt payload on the forwarded-request wire ([bf67cd6](https://github.com/gotgenes/pi-packages/commit/bf67cd6673d1e4bf57c339873d8642295bd643c0)), closes [#745](https://github.com/gotgenes/pi-packages/issues/745)
+* **pi-permission-system:** ignore the deprecated tool-preview caps and notice their use ([47d7610](https://github.com/gotgenes/pi-packages/commit/47d7610d1217ebd6c0a968999dbfff4ad426af88)), closes [#745](https://github.com/gotgenes/pi-packages/issues/745)
+* **pi-permission-system:** narrow the ui_prompt broadcast to the request facts ([fcdb174](https://github.com/gotgenes/pi-packages/commit/fcdb17494f73d7a506fe1ab967cf2db8f815b50a)), closes [#745](https://github.com/gotgenes/pi-packages/issues/745)
+* **pi-permission-system:** render a forwarded ask from the child's own payload ([8587269](https://github.com/gotgenes/pi-packages/commit/8587269a066e87007b8e8dea4b85649d0240b697)), closes [#745](https://github.com/gotgenes/pi-packages/issues/745)
+* **pi-permission-system:** render the review log from the prompt payload ([#746](https://github.com/gotgenes/pi-packages/issues/746)) ([b373876](https://github.com/gotgenes/pi-packages/commit/b3738761e572b91a3388b0681d2a34862b11859d))
+* **pi-permission-system:** replace the forwarded-request message with the structured payload ([1af41a9](https://github.com/gotgenes/pi-packages/commit/1af41a9a18cf5850da3bc787c9e0ed0db493921a)), closes [#745](https://github.com/gotgenes/pi-packages/issues/745)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** stop echoing tool input in agent-facing denial text ([#746](https://github.com/gotgenes/pi-packages/issues/746)) ([525b7e4](https://github.com/gotgenes/pi-packages/commit/525b7e4b19cfa997029a178b413a2838b3834021))
+
+
+### Documentation
+
+* **pi-permission-system:** document the payload contracts and mark Phase 13 Step 3 complete ([a2381ac](https://github.com/gotgenes/pi-packages/commit/a2381ac700e08c80c415b31f732a481367226264)), closes [#745](https://github.com/gotgenes/pi-packages/issues/745)
+* **pi-permission-system:** record the agent and review-log renderers ([#746](https://github.com/gotgenes/pi-packages/issues/746)) ([af88cc1](https://github.com/gotgenes/pi-packages/commit/af88cc11e31e98c0fa43d3629c64f31d6b73de05))
+* **pi-permission-system:** retire references to the dissolved denial module ([#746](https://github.com/gotgenes/pi-packages/issues/746)) ([53647b2](https://github.com/gotgenes/pi-packages/commit/53647b2b0930737940714378d8421cd2ce76e66f))
+
 ## [25.4.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v25.3.0...pi-permission-system-v25.4.0) (2026-08-15)
 
 

package/README.md

@@ -139,18 +139,20 @@ If you relied on the old permissive behavior for bash, set an explicit permissiv
 
 ## Documentation
 
-| Document                                                                                                                       | Contents                                                                                      |
-| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
-| [docs/configuration.md](docs/configuration.md)                                                                                 | Full policy reference, runtime knobs, per-agent overrides, recipes                            |
-| [docs/session-approvals.md](docs/session-approvals.md)                                                                         | Session-scoped rules, pattern suggestions, bash arity table                                   |
-| [docs/cross-extension-api.md](docs/cross-extension-api.md)                                                                     | Cross-extension service accessor, event bus integration, prompt and decision broadcasts       |
-| [docs/subagent-integration.md](docs/subagent-integration.md)                                                                   | Permission forwarding, coexistence with subagent extensions                                   |
-| [docs/guides/permission-frontmatter-for-subagent-extensions.md](docs/guides/permission-frontmatter-for-subagent-extensions.md) | Convention guide for subagent extension authors                                               |
-| [docs/opencode-compatibility.md](docs/opencode-compatibility.md)                                                               | OpenCode compatibility — shared concepts, divergences, porting guide                          |
-| [docs/troubleshooting.md](docs/troubleshooting.md)                                                                             | Common issues, diagnostic logging, threat model                                               |
-| [docs/migration/legacy-to-flat.md](docs/migration/legacy-to-flat.md)                                                           | Migration from pre-v2 config layout                                                           |
-| [docs/migration/strict-config-validation.md](docs/migration/strict-config-validation.md)                                       | Strict config validation (breaking) — rejected configs, and the cross-scope fail-closed clamp |
-| [docs/migration/0644-project-trust-gating.md](docs/migration/0644-project-trust-gating.md)                                     | Project-trust gating (breaking) — project config loads only after project trust               |
+| Document                                                                                                                       | Contents                                                                                                             |
+| ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| [docs/configuration.md](docs/configuration.md)                                                                                 | Full policy reference, runtime knobs, per-agent overrides, recipes                                                   |
+| [docs/session-approvals.md](docs/session-approvals.md)                                                                         | Session-scoped rules, pattern suggestions, bash arity table                                                          |
+| [docs/cross-extension-api.md](docs/cross-extension-api.md)                                                                     | Cross-extension service accessor, event bus integration, prompt and decision broadcasts                              |
+| [docs/subagent-integration.md](docs/subagent-integration.md)                                                                   | Permission forwarding, coexistence with subagent extensions                                                          |
+| [docs/guides/permission-frontmatter-for-subagent-extensions.md](docs/guides/permission-frontmatter-for-subagent-extensions.md) | Convention guide for subagent extension authors                                                                      |
+| [docs/opencode-compatibility.md](docs/opencode-compatibility.md)                                                               | OpenCode compatibility — shared concepts, divergences, porting guide                                                 |
+| [docs/troubleshooting.md](docs/troubleshooting.md)                                                                             | Common issues, diagnostic logging, threat model                                                                      |
+| [docs/migration/legacy-to-flat.md](docs/migration/legacy-to-flat.md)                                                           | Migration from pre-v2 config layout                                                                                  |
+| [docs/migration/strict-config-validation.md](docs/migration/strict-config-validation.md)                                       | Strict config validation (breaking) — rejected configs, and the cross-scope fail-closed clamp                        |
+| [docs/migration/0644-project-trust-gating.md](docs/migration/0644-project-trust-gating.md)                                     | Project-trust gating (breaking) — project config loads only after project trust                                      |
+| [docs/migration/0745-prompt-payload-contracts.md](docs/migration/0745-prompt-payload-contracts.md)                             | Prompt payload contracts (breaking) — the forwarded wire, the `ui_prompt` broadcast, and the deprecated preview caps |
+| [docs/migration/0746-review-log-fields.md](docs/migration/0746-review-log-fields.md)                                           | Review-log fields (breaking) — `message` replaced by request facts, and the `reviewLogFieldMaxWidth` bound           |
 
 ## Development
 

package/config/config.example.json

@@ -11,8 +11,7 @@
   "promptMaxRows": 24,
   "promptFieldMaxWidth": 400,
 
-  "toolInputPreviewMaxLength": 400,
-  "toolTextSummaryMaxLength": 120,
+  "reviewLogFieldMaxWidth": 1000,
 
   "piInfrastructureReadPaths": [],
 

package/dist/public.d.ts

@@ -68,10 +68,10 @@ interface PromptPayload {
  *
  * Present because the ask shapes are not separable by surface alone: a tool
  * external-directory ask and a bash one share the `external_directory` surface,
- * and the `path` gate and the per-tool gate differ only in wording. It mirrors
- * `DenialContext`'s discriminated union, the shape ADR 0011 §7 names as already
- * correct, and gives every renderer an exhaustive switch rather than a set of
- * string comparisons a new variant sails past.
+ * and the `path` gate and the per-tool gate differ only in wording. It gives
+ * every renderer an exhaustive switch rather than a set of string comparisons a
+ * new variant sails past — which is what let the parallel denial-context union
+ * ADR 0011 §7 described dissolve into this one (#746).
  */
 type PromptPayloadKind = "bash" | "mcp" | "tool" | "path" | "external_directory" | "bash_external_directory" | "skill" | "skill_read" | "forwarded";
 /**
@@ -148,6 +148,16 @@ interface PromptAnnotation {
     readonly text: string;
 }
 
+/**
+ * Permission event channel — public contract.
+ *
+ * Exports channel name constants, TypeScript types for all emitted events,
+ * and thin emit helpers.
+ *
+ * Stability guarantee: fields may be added, but existing fields will not be
+ * removed or renamed without a semver-major version bump.
+ */
+
 /** Emitted at `session_start`, after the service is published. */
 declare const PERMISSIONS_READY_CHANNEL = "permissions:ready";
 /** Emitted when a permission request is committed to the active UI prompt path. */
@@ -198,8 +208,19 @@ interface PermissionUiPromptEvent {
     value: string | null;
     /** Agent name (when known). */
     agentName: string | null;
-    /** Message displayed to the user. */
-    message: string;
+    /**
+     * The ask's invariant core (ADR 0011 §3), verbatim from the prompt payload.
+     *
+     * Nested rather than flattened so the event and the payload share one shape:
+     * a fact added to `PromptRequestFacts` reaches the bus without a second
+     * hand-maintained declaration. Carries no evidence and no annotations — the
+     * bus is the narrowest renderer (ADR 0011 §6), observable by any loaded
+     * extension without the operator having named it.
+     *
+     * `request.surface` is the *gate* surface the rule fired on; the top-level
+     * `surface` is the display projection. Both are here on purpose.
+     */
+    request: PromptRequestFacts;
     /** Forwarding context, or null for a direct prompt. */
     forwarding: ForwardedPromptContext | null;
 }
@@ -281,13 +302,13 @@ interface PromptPermissionDetails {
     requestId: string;
     source: PermissionReviewSource;
     agentName: string | null;
-    message: string;
     /**
      * The complete structured description of this ask (ADR 0011 §2).
      *
      * Required: every ask carries one, and the type is what guarantees it rather
-     * than a convention each gate has to remember. `message` is a render over it
-     * for the duration of the transition, so the two cannot disagree.
+     * than a convention each gate has to remember. Every consumer — the dialog,
+     * the wire, the broadcast, the review log, the agent-facing denial text — is
+     * a render over it, so no two of them can disagree.
      */
     payload: PromptPayload;
     toolCallId?: string;
@@ -529,4 +550,4 @@ declare function getPermissionsService(): PermissionsService | undefined;
 declare function unpublishPermissionsService(service: PermissionsService): void;
 
 export { PERMISSIONS_DECISION_CHANNEL, PERMISSIONS_READY_CHANNEL, PERMISSIONS_UI_PROMPT_CHANNEL, getPermissionsService, publishPermissionsService, unpublishPermissionsService };
-export type { Authorizer, AuthorizerLog, AuthorizerVerdict, ForwardedPromptContext, PermissionCheckResult, PermissionDecisionEvent, PermissionQuery, PermissionState, PermissionUiPromptEvent, PermissionUiPromptSource, PermissionsReadyEvent, PermissionsService, PromptPermissionDetails, ToolInputFormatter };
+export type { Authorizer, AuthorizerLog, AuthorizerVerdict, ForwardedPromptContext, PermissionCheckResult, PermissionDecisionEvent, PermissionQuery, PermissionState, PermissionUiPromptEvent, PermissionUiPromptSource, PermissionsReadyEvent, PermissionsService, PromptAnnotation, PromptEvidence, PromptPayload, PromptPayloadKind, PromptPermissionDetails, PromptRequestFacts, PromptRequester, ToolInputFormatter };

package/docs/configuration.md

@@ -58,8 +58,6 @@ This clamp is deny-preserving and, like `yoloMode`, applied at composition; when
   "yoloMode": false,
   "doublePressToConfirm": true,
   "forwardingTimeoutMs": 600000,
-  "toolInputPreviewMaxLength": 400,
-  "toolTextSummaryMaxLength": 120,
   "piInfrastructureReadPaths": [],
 
   // Non-bash tools that carry shell semantics
@@ -99,19 +97,20 @@ This clamp is deny-preserving and, like `yoloMode`, applied at composition; when
 
 ## Runtime Knobs
 
-| Key                         | Default  | Description                                                                                                                                                                                        |
-| --------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `debugLog`                  | `false`  | Enables verbose diagnostic logging to `logs/pi-permission-system-debug.jsonl`                                                                                                                      |
-| `permissionReviewLog`       | `true`   | Enables the permission request/denial review log at `logs/pi-permission-system-permission-review.jsonl`. Records bash command strings verbatim — see [Log file sensitivity](#log-file-sensitivity) |
-| `yoloMode`                  | `false`  | Auto-approves `ask` results instead of prompting when yolo mode is enabled                                                                                                                         |
-| `doublePressToConfirm`      | `true`   | Requires a confirming second press of a decision hotkey in the inline TUI dialog (see below). TUI sessions only; set to `false` for single-press.                                                  |
-| `forwardingTimeoutMs`       | `600000` | How long a subagent waits for the parent session to answer a forwarded permission request, in milliseconds. A child whose in-process parent is not draining its inbox gives up in ~2 s regardless. |
-| `promptMaxRows`             | `24`     | Max rows a permission prompt renders before eliding its evidence. The request's own facts are never elided by this budget; `Ctrl+O` expands the prompt to the complete request.                    |
-| `promptFieldMaxWidth`       | `400`    | Max characters of any one field shown in a permission prompt. This is what bounds a single long field (a here-string command, say) that would otherwise fill the prompt through wrapping.          |
-| `toolInputPreviewMaxLength` | `200`    | Max characters of inline JSON shown in permission prompts for tool inputs. Omit to use the default. Set to a large value to disable truncation.                                                    |
-| `toolTextSummaryMaxLength`  | `80`     | Max characters of inline pattern/path summaries (grep patterns, find globs, ls paths) in permission prompts. Omit to use the default.                                                              |
-| `piInfrastructureReadPaths` | `[]`     | Extra directories to auto-allow for reads, bypassing the `external_directory` gate. Supports `~`/`$HOME`/`${HOME}` expansion and wildcard patterns (`*`, `?`).                                     |
-| `authorizerChain`           | `[]`     | Ordered names of registered live-authority chain links to consult before the terminal authorizer (see [Authorizer chain](#authorizer-chain--case-by-case-decision-links)).                         |
+| Key                         | Default  | Description                                                                                                                                                                                          |
+| --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `debugLog`                  | `false`  | Enables verbose diagnostic logging to `logs/pi-permission-system-debug.jsonl`                                                                                                                        |
+| `permissionReviewLog`       | `true`   | Enables the permission request/denial review log at `logs/pi-permission-system-permission-review.jsonl`. Records bash command strings unredacted — see [Log file sensitivity](#log-file-sensitivity) |
+| `yoloMode`                  | `false`  | Auto-approves `ask` results instead of prompting when yolo mode is enabled                                                                                                                           |
+| `doublePressToConfirm`      | `true`   | Requires a confirming second press of a decision hotkey in the inline TUI dialog (see below). TUI sessions only; set to `false` for single-press.                                                    |
+| `forwardingTimeoutMs`       | `600000` | How long a subagent waits for the parent session to answer a forwarded permission request, in milliseconds. A child whose in-process parent is not draining its inbox gives up in ~2 s regardless.   |
+| `promptMaxRows`             | `24`     | Max rows a permission prompt renders before eliding its evidence. The request's own facts are never elided by this budget; `Ctrl+O` expands the prompt to the complete request.                      |
+| `promptFieldMaxWidth`       | `400`    | Max characters of any one field shown in a permission prompt. This is what bounds a single long field (a here-string command, say) that would otherwise fill the prompt through wrapping.            |
+| `reviewLogFieldMaxWidth`    | `1000`   | Max characters of any one value written to the review log. A longer value is stored shortened, marked with an ellipsis. Raise it to keep longer values; this is a length bound, not redaction.       |
+| `toolInputPreviewMaxLength` | —        | **Deprecated and ignored.** Superseded by `promptMaxRows` / `promptFieldMaxWidth`. Still accepted so an existing config is not rejected, but the value no longer applies; setting it logs a warning. |
+| `toolTextSummaryMaxLength`  | —        | **Deprecated and ignored.** Superseded by `promptMaxRows` / `promptFieldMaxWidth`. Still accepted so an existing config is not rejected, but the value no longer applies; setting it logs a warning. |
+| `piInfrastructureReadPaths` | `[]`     | Extra directories to auto-allow for reads, bypassing the `external_directory` gate. Supports `~`/`$HOME`/`${HOME}` expansion and wildcard patterns (`*`, `?`).                                       |
+| `authorizerChain`           | `[]`     | Ordered names of registered live-authority chain links to consult before the terminal authorizer (see [Authorizer chain](#authorizer-chain--case-by-case-decision-links)).                           |
 
 Both logs write to `~/.pi/agent/extensions/pi-permission-system/logs/`.
 No debug output is printed to the terminal.
@@ -962,16 +961,16 @@ Additional behaviors:
 - The narrowed prompt is recomputed and returned on every turn but is byte-stable for a stable policy/agent, so the provider's prompt cache (tools + system prefix) is preserved rather than rewritten each turn
 - Extension-provided tools like `task`, `mcp`, and third-party tools are handled by exact registered name
 - Generic extension-tool approval prompts include a bounded input preview; built-in file tools use concise human-readable summaries
-- Permission review logs include bounded `toolInputPreview` values for non-bash/non-MCP tool calls, with sensitive-keyed values masked (see [Log file sensitivity](#log-file-sensitivity))
+- Permission review logs include `toolInputPreview` values for non-bash/non-MCP tool calls, with sensitive-keyed values masked and every value bounded by `reviewLogFieldMaxWidth` (see [Log file sensitivity](#log-file-sensitivity))
 
 ---
 
 ## Log file sensitivity
 
-The review log is enabled by default and records what the agent actually did, which means it records payload as well as decisions: the complete bash command string for every bash decision, and a bounded JSON preview of the tool input for other tools.
+The review log is enabled by default and records what the agent actually did, which means it records payload as well as decisions: the bash command string for every bash decision, and a JSON preview of the tool input for other tools.
 The debug log carries the same payload when `debugLog` is on.
 
-Two protections apply.
+Three protections apply.
 
 Both logs are created **owner-only** (`0600`, in a `0700` directory), and a log created by an earlier version is tightened on the next write.
 The permission-forwarding request and response files are written the same way.
@@ -984,9 +983,14 @@ The boundary is worth stating exactly, because it is easy to over-read:
 
 > A value bound to a sensitive key name is masked; a secret embedded in a bash command string is not.
 
-A command string has no keys, so `deploy --token abc123` is logged verbatim.
+A command string has no keys, so `deploy --token abc123` is logged unredacted.
 The extension deliberately does not try to guess which parts of a command look secret-shaped — see [ADR 0010] for the measured reasoning.
 
+Every value the **review** log writes is narrowed to `reviewLogFieldMaxWidth` (1000 characters by default) and marked with an ellipsis, so a single pathological command cannot put tens of kilobytes in one entry.
+This is a length bound, not redaction: it never inspects a value to decide what to hide, and it applies to every field alike.
+The two compose — a sensitive-keyed value is masked whole however long it was.
+The debug log is left unbounded, since it is opt-in and exists to be read in full.
+
 Practical guidance:
 
 - Treat both log files as sensitive when sharing them: scrub before pasting into an issue or a chat.

package/docs/cross-extension-api.md

@@ -320,17 +320,21 @@ Forwarded prompts that do reach the human are not degraded: the parent emits the
 The payload is lean by design — `surface`/`value` are the normalized display projection a notification consumer reads, not a mirror of the internal review log.
 Read defensively rather than version-gating: broadcast payloads carry no `protocolVersion`.
 
+The event carries no assembled sentence.
+It carries `request`, the permission ask's invariant core, verbatim from the prompt payload — no evidence and no annotations.
+The bus is the narrowest renderer: any loaded extension can observe it without the operator having named that extension, whereas every other route to an ask's evidence requires that consent (a registered tool-input formatter, or an `Authorizer` link the operator lists in `authorizerChain`).
+
 ```typescript
 import type { PermissionUiPromptEvent } from "@gotgenes/pi-permission-system";
 
 pi.events.on("permissions:ui_prompt", (raw) => {
   const event = raw as PermissionUiPromptEvent;
   // Defensive read: tolerate any shape skew between sibling extensions.
-  if (typeof event.value !== "string" && typeof event.message !== "string") {
+  if (typeof event.value !== "string") {
     return;
   }
-  notify(event.surface, event.value, event.message);
-  // e.g. "bash" "git push" "Allow git push?"
+  notify(event.surface, event.value, event.request.matchedPattern);
+  // e.g. "bash" "git push" "git *"
 });
 ```
 
@@ -343,11 +347,33 @@ pi.events.on("permissions:ui_prompt", (raw) => {
 | `surface`    | `string \| null`                 | Normalized display surface (e.g. `"bash"`, `"skill"`), when known       |
 | `value`      | `string \| null`                 | Normalized display value (command, path, skill name, etc.), when known  |
 | `agentName`  | `string \| null`                 | Active/requesting agent name, when known                                |
-| `message`    | `string`                         | Message displayed in the permission prompt                              |
+| `request`    | `PromptRequestFacts`             | The ask's invariant core — no evidence, no annotations                  |
 | `forwarding` | `ForwardedPromptContext \| null` | Forwarding context, or `null` for a direct prompt                       |
 
 Forwarding is orthogonal to origin: a forwarded subagent prompt keeps its original `source` and is identified by a non-null `forwarding` field, not by a dedicated source value.
 
+#### `PromptRequestFacts`
+
+The facts every render of the ask shows, that no renderer's budget may elide.
+Nested rather than flattened so the event and the prompt payload share one shape: a fact added here reaches the bus without a second hand-maintained declaration.
+
+| Field             | Type                         | Description                                                                                      |
+| ----------------- | ---------------------------- | ------------------------------------------------------------------------------------------------ |
+| `requester`       | `PromptRequester`            | Who is asking, and whether the ask arrived from a subagent                                       |
+| `surface`         | `string`                     | The **gate** surface the rule fired on — `"external_directory"`, `"path"`, `"bash"`, a tool name |
+| `toolName`        | `string \| null`             | The gated tool name; `null` when the ask is not tool-shaped                                      |
+| `invokedToolName` | `string \| null`             | The invoked name when a shell alias re-exposes bash under another name                           |
+| `value`           | `string`                     | The decision-relevant value: the command, path, MCP target, or skill name                        |
+| `matchedPattern`  | `string \| null`             | The matched rule, including a sentinel such as `<indirection-bash-wrapper>`                      |
+| `commandContext`  | `BashCommandContext \| null` | Where the offending bash unit runs, when it came from a substitution or subshell                 |
+| `executedUnit`    | `string \| null`             | For bash, the unit that will actually run, including inside an unstrippable wrapper              |
+
+`PromptRequester` carries `agentName` (`string | null`), `forwarded` (`boolean`), and `sessionId` (`string | null`, the requesting session for a forwarded ask).
+
+The top-level `surface` and `request.surface` are two different facts and both belong on the event.
+The top-level one is the **display** projection — the child's tool name, what a notification shows.
+`request.surface` is the **gate** surface the rule fired on: a `read` of a path outside the working directory displays as `"read"` and gates on `"external_directory"`.
+
 #### `ForwardedPromptContext`
 
 Present only when the prompt was forwarded from a non-UI subagent.

package/docs/migration/0745-prompt-payload-contracts.md

@@ -0,0 +1,68 @@
+# Migration guide: the prompt payload replaces the assembled message
+
+Starting with the release that closes #745, a permission ask crosses two boundaries as **structured facts** rather than as a pre-rendered sentence: the forwarded-permission-request file a subagent writes for its parent, and the `permissions:ui_prompt` broadcast.
+A third change deprecates the two tool-preview cap config fields.
+
+This is a **breaking change** on three surfaces.
+Each is independent — you may be affected by one and not the others.
+
+| Surface                                                  | Break                              | Who is affected                                                   |
+| -------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------- |
+| `ForwardedPermissionRequest` (on-disk wire)              | `message` removed; `payload` added | Anyone running **out-of-process** subagents across mixed versions |
+| `PermissionUiPromptEvent` (`permissions:ui_prompt`)      | `message` removed; `request` added | Any extension reading `event.message`                             |
+| `toolInputPreviewMaxLength` / `toolTextSummaryMaxLength` | Accepted but ignored               | Anyone who set either in `config.json`                            |
+
+## Upgrade the parent session first
+
+The forwarded-request wire is the only surface with an ordering constraint, and it only exists for an **out-of-process** subagent (one whose parent session is resolved through `PI_SUBAGENT_PARENT_SESSION` or a sibling env var).
+An in-process child shares its parent's loaded extension, so the two can never skew.
+
+A serving node on this version accepts an older child's `message`-only request: the field is no longer required, and the ask is rendered from the `surface`, `value`, and requester provenance the request does carry.
+The reverse does not hold.
+An **older** parent still demands `message` and rejects a newer child's request outright, deleting the file; the child then waits out its forwarding timeout (ten minutes by default) and reports the block as `confirmationUnavailable` rather than as a user denial.
+
+So: upgrade the session that serves prompts before the sessions that forward to it.
+Carrying both fields indefinitely was declined deliberately — it would keep the child's un-budgeted prose alive on the wire, which is the defect this change exists to remove.
+
+## What changed on the wire
+
+The child used to assemble a sentence under **its** configuration and write it into the request file; the serving node carried that string forward as a single evidence entry, so the parent's own render budget never applied to it.
+A forwarded ask therefore could not be made consistent with a local one.
+
+Now the child writes its complete `PromptPayload`, and the serving node renders the child's own facts under the **parent's** budget.
+A forwarded bash ask reads `command : …` exactly as a local one does, because the serving node holds the child's real payload kind.
+
+The request files are still mode-restricted and still not redacted — the parent reads them to render the ask.
+The payload's evidence is the same disclosure class the `message` string already was, so this is not a widening.
+
+## What changed on the broadcast
+
+`permissions:ui_prompt` drops `message` and gains `request`, the ask's invariant core, verbatim from the prompt payload.
+
+```typescript
+// Before
+notify(event.surface, event.value, event.message);
+
+// After
+notify(event.surface, event.value, event.request.matchedPattern);
+```
+
+`request.value` is the decision-relevant value (the command, path, MCP target, or skill name) and `request.matchedPattern` is the rule that fired, including a sentinel such as `<indirection-bash-wrapper>`.
+See the [`PromptRequestFacts` table](../cross-extension-api.md#promptrequestfacts) for every field.
+
+`surface`, `value`, `agentName`, `source`, `requestId`, and `forwarding` are unchanged — what narrows here is evidence, never correlation.
+A forwarded ask's broadcast still carries its full `forwarding.requesterAgentName` / `forwarding.requesterSessionId` provenance.
+
+For a `write`, an `edit`, or an MCP call this is a **net narrowing** of what the bus discloses: an incidental tool-input preview of up to 200 characters used to ride `message`, and now nothing from the payload's evidence reaches the bus at all.
+That is deliberate — the bus is the narrowest renderer, observable by any loaded extension without the operator having named it, whereas every other route to an ask's evidence requires that consent.
+
+## The deprecated tool-preview caps
+
+`toolInputPreviewMaxLength` and `toolTextSummaryMaxLength` are still accepted by the config schema but **no longer take effect**.
+Setting either logs a deprecation notice through the ordinary config-issue channel at session start.
+
+They bounded one preview *inside* a prompt, never the prompt itself — which is why they never bounded it.
+Use `promptMaxRows` (default `24`) and `promptFieldMaxWidth` (default `400`) instead: those bound what a permission prompt renders, and `Ctrl+O` still expands the prompt to the complete request.
+
+Remove both fields from your `config.json`.
+They remain valid so that an existing config is not rejected fail-closed — which would empty that scope's whole policy — but they will be removed in a later major.

package/docs/migration/0746-review-log-fields.md

@@ -0,0 +1,69 @@
+# Review-log fields and width bound (breaking)
+
+Two changes to the permission review log (`logs/pi-permission-system-permission-review.jsonl`) take effect on upgrade without a config edit.
+Both come from [ADR 0011] §6, which makes the log a renderer over the prompt payload with its own configured limits, rather than a place the assembled prompt sentence happened to land.
+
+Nothing about **redaction** changes.
+Key-name masking applies exactly as before, and the boundary is unchanged: a value bound to a sensitive key name is masked; a secret embedded in a bash command string is not.
+See [ADR 0010].
+
+## The `message` field is removed
+
+Every `permission_request.*` entry previously carried `message`, the same assembled sentence the prompt showed.
+It is gone.
+What the log accumulated was a side effect of how a prompt happened to be worded, and the sentence duplicated facts the entry already carried in structured form.
+
+In its place each entry carries the ask's own request facts:
+
+| Field                | Present when                                  | Meaning                                                                                         |
+| -------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `surface`            | always                                        | The gate surface the rule fired on (`bash`, `path`, `external_directory`, `skill`, a tool name) |
+| `matchedPattern`     | a rule matched                                | The rule that fired, including a sentinel such as `<indirection-bash-wrapper>`                  |
+| `executedUnit`       | a wrapper hides an inner command              | The unit that will actually run, e.g. `grep foo` inside `xargs grep foo`                        |
+| `commandContext`     | the unit came from a substitution or subshell | `command_substitution`, `process_substitution`, or `subshell`                                   |
+| `invokedToolName`    | a shell alias re-exposed bash                 | The tool name the agent actually called, e.g. `exec_command`                                    |
+| `forwarded`          | the ask arrived from a subagent               | `true`                                                                                          |
+| `requesterSessionId` | the ask arrived from a subagent               | The requesting session's id                                                                     |
+
+A field the ask does not carry is omitted rather than written as `null`.
+
+The existing structured columns are unchanged: `requestId`, `source`, `agentName`, `toolCallId`, `toolName`, `skillName`, `path`, `command`, `target`, `toolInputPreview`, `resolution`, and `denialReason`.
+
+If you parse the log, read those fields instead of `message`.
+Two of the new ones close gaps a `message` reader never had: a `permission_request.blocked` entry recorded that policy denied the call but never which rule, and `executedUnit` had not reached the log at all.
+
+## Every review-log value is bounded
+
+Each string the review log writes is now narrowed to `reviewLogFieldMaxWidth` characters and marked with a trailing ellipsis.
+The default is `1000` — the width that already bounded `toolInputPreview`, applied to every field so the log has one limit rather than one limit and an unbounded remainder.
+
+The practical effect is on `command`: a bash command longer than the width is stored shortened, where it was previously written whole.
+On a real 9,484-entry log, 188 of 4,325 command entries (4.3%) exceed the default.
+
+To keep longer values, raise the setting:
+
+```jsonc
+{
+  "reviewLogFieldMaxWidth": 8000
+}
+```
+
+There is no "unbounded" value by design — the point of the bound is that log growth is a decision rather than an accident.
+The **debug** log is unaffected: it is opt-in and exists to be read in full.
+
+This bound is a length cap, not redaction.
+It narrows by length alone and never inspects a value to decide what to hide, and the two compose independently: a sensitive-keyed value is masked whole however long it was.
+
+## Removed exports
+
+`ToolPreviewFormatterOptions.toolInputLogPreviewMaxLength` and `TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH` are removed, superseded by `reviewLogFieldMaxWidth`.
+`ToolPreviewFormatter` no longer truncates what it produces for the log; the writer bounds it instead.
+
+## Agent-facing denial text
+
+Not a contract, but visible: the text returned to the agent when a call is refused no longer echoes the bash command or the tool input.
+It names the surface, the tool, the rule that fired, the flagged path or MCP target or skill, and the operator's or human's reason.
+[ADR 0011] §7 states the rule — the agent renderer identifies the call; it does not reproduce it — and the agent already holds its own arguments, which the harness keeps beside the refusal.
+
+[ADR 0010]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0010-permission-log-secret-exposure.md
+[ADR 0011]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0011-prompt-presentation-contract.md

package/docs/troubleshooting.md

@@ -51,8 +51,9 @@ This makes it easy to verify which files the extension actually loaded:
 
 - If a dangerous action is possible via an allowed tool, policy must explicitly restrict it
 - This is a permission decision layer, not a sandbox — for true isolation see [Agent Sandboxes](https://engine.build/lab/agent-sandboxes)
-- The review log records bash command strings verbatim.
+- The review log records bash command strings unredacted.
   Log files are created owner-only (`0600`), and values bound to a sensitive key name (`authorization`, `token`, `password`, …) are masked — but a secret embedded in a command string is not.
+  Review-log values are shortened at `reviewLogFieldMaxWidth` (1000 characters by default), which bounds the file's growth but is a length cap, not redaction.
   See [Log file sensitivity](configuration.md#log-file-sensitivity) and [ADR 0010].
 
 [ADR 0010]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0010-permission-log-secret-exposure.md

package/package.json

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

package/schemas/permissions.schema.json

@@ -55,16 +55,26 @@
       "minimum": 1,
       "maximum": 9007199254740991
     },
+    "reviewLogFieldMaxWidth": {
+      "description": "Maximum characters of any one value written to the permission review log. Omit to use the default (1000).",
+      "markdownDescription": "Maximum characters of any one value written to the permission review log.\n\nOmit to use the default (1000). Every string the review log writes is narrowed to this width and marked with an ellipsis, so the log's growth is a decision you make rather than a side effect of how long a command happened to be. Raise it to keep longer values — a bash command exceeding the width is stored shortened.\n\nThis is a length bound, not redaction: it never inspects a value to decide what to hide. Key-name masking is unchanged and applies independently.",
+      "default": 1000,
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
     "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.",
+      "deprecated": true,
+      "description": "Deprecated and ignored. Superseded by promptMaxRows and promptFieldMaxWidth, which bound the whole prompt rather than one preview. Still accepted so an existing config is not rejected; remove it.",
+      "markdownDescription": "**Deprecated and ignored.** Superseded by `promptMaxRows` and `promptFieldMaxWidth`, which bound the whole permission prompt rather than one preview inside it.\n\nStill accepted so an existing config is not rejected fail-closed, but the value no longer takes effect. Remove it.",
       "type": "integer",
       "minimum": 1,
       "maximum": 9007199254740991
     },
     "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.",
+      "deprecated": true,
+      "description": "Deprecated and ignored. Superseded by promptMaxRows and promptFieldMaxWidth, which bound the whole prompt rather than one summary. Still accepted so an existing config is not rejected; remove it.",
+      "markdownDescription": "**Deprecated and ignored.** Superseded by `promptMaxRows` and `promptFieldMaxWidth`, which bound the whole permission prompt rather than one summary inside it.\n\nStill accepted so an existing config is not rejected fail-closed, but the value no longer takes effect. Remove it.",
       "type": "integer",
       "minimum": 1,
       "maximum": 9007199254740991

package/src/access-intent/tool-kind.ts

@@ -10,7 +10,7 @@ import { PATH_BEARING_TOOLS } from "./path-surfaces";
  * `toolName === "bash"`/`"mcp"` re-derivation across the extraction consumers
  * (`input-normalizer`, `tool-input-path`, the tool-call gate pipeline, and
  * `permission-manager`'s source derivation) and the presentation consumers
- * (`tool-preview-formatter`, `permission-prompts`, `denial-messages`, and
+ * (`tool-preview-formatter`, `permission-prompts`, the payload builders, and
  * `deriveDecisionValue`), which dispatch on {@link classifyToolKind} or
  * {@link isMcpCheck}. Adding a tool kind means editing {@link classifyToolKind}
  * plus the exhaustive switches the compiler flags — an OCP win over silent

package/src/authority/approval-escalator.ts

@@ -36,6 +36,7 @@ import type { ServingLookup } from "#src/authority/serving-registry";
 import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
 import { createPermissionRequestId } from "#src/permission-request-id";
 import { buildUiPrompt } from "#src/permission-ui-prompt";
+import type { PromptPayload } from "#src/presentation/prompt-payload";
 import type { DebugReviewLogger } from "#src/session-logger";
 import { toRecord } from "#src/value-guards";
 import type { TerminalAuthorizer } from "./authorizer";
@@ -68,7 +69,7 @@ function getContextSystemPrompt(ctx: ForwarderContext): string | undefined {
 
 /**
  * The facts a forwarded request relays unchanged from the child's ask: the
- * prompt message, the optional display projection, and the optional
+ * prompt payload, the optional display projection, and the optional
  * session-approval suggestion.
  *
  * Bundled into one object so the two-hop private chain
@@ -82,7 +83,8 @@ interface ForwardedRequestFacts {
    * decision instead of a third being minted here.
    */
   requestId: string;
-  message: string;
+  /** The child's complete prompt payload, relayed for the serving node to render. */
+  payload: PromptPayload;
   display?: ForwardedPromptDisplay;
   sessionApproval?: ForwardedSessionApproval;
   /** The child-fixed access facts; the edge completes them into a `ForwardedAccessIntent`. */
@@ -171,7 +173,7 @@ export class ParentAuthorizer implements TerminalAuthorizer {
     const uiPrompt = buildUiPrompt(details);
     return this.waitForForwardedApproval(this.ctx, {
       requestId: details.requestId,
-      message: details.message,
+      payload: details.payload,
       display: {
         source: uiPrompt.source,
         surface: uiPrompt.surface,
@@ -300,7 +302,7 @@ export class ParentAuthorizer implements TerminalAuthorizer {
       requesterSessionId,
       targetSessionId,
       requesterAgentName,
-      message: facts.message,
+      payload: facts.payload,
       ...(facts.display
         ? {
             source: facts.display.source,

package/src/authority/authorizer.ts

@@ -49,9 +49,9 @@ export interface Authorizer {
  * ADR 0007's terminal-cannot-defer invariant.
  *
  * One method, one responsibility. `DenyingAuthorizer` ignores `details`;
- * `LocalUserAuthorizer` reads `message`/`sessionLabel` and derives the UI
- * event from it; `ParentAuthorizer` reads `message` and derives the
- * forwarded display from it.
+ * `LocalUserAuthorizer` renders `payload` for the human and derives the UI
+ * event from the request facts; `ParentAuthorizer` ships `payload` over the
+ * wire so the serving node renders it under its own budget.
  */
 export interface TerminalAuthorizer {
   authorize(

package/src/authority/forwarded-request-server.ts

@@ -14,7 +14,6 @@ import {
 } from "#src/authority/permission-forwarding";
 import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
 import { buildForwardedAskPayload } from "#src/presentation/forwarded-ask-payload";
-import { renderLegacyMessage } from "#src/presentation/legacy-message";
 import { SessionApproval } from "#src/session-approval";
 import type { SessionApprovalRecorder } from "#src/session-approval-recorder";
 import type { DebugReviewLogger } from "#src/session-logger";
@@ -100,7 +99,6 @@ function buildForwardedAskDetails(
     requestId: request.id,
     source: request.source ?? "tool_call",
     agentName: request.requesterAgentName || null,
-    message: renderLegacyMessage(payload),
     payload,
     surface: request.surface ?? null,
     value: request.value ?? null,