@gotgenes/pi-permission-system 25.2.2 → 25.4.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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).
 
+## [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)
+
+
+### Features
+
+* **pi-permission-system:** adopt the requester's request id as the forwarded request id ([3f8d3fd](https://github.com/gotgenes/pi-packages/commit/3f8d3fd69940211c6a92b99f8eae0396936afedf)), closes [#752](https://github.com/gotgenes/pi-packages/issues/752)
+* **pi-permission-system:** carry the request id on permissions:decision ([95c001c](https://github.com/gotgenes/pi-packages/commit/95c001cf6b35c68991143826d8621b1e94fc0b32)), closes [#752](https://github.com/gotgenes/pi-packages/issues/752)
+* **pi-permission-system:** give the gate-error review entry a request id ([172bc68](https://github.com/gotgenes/pi-packages/commit/172bc689ea0f18c88672a22c0b5e84c0f3576fd1)), closes [#752](https://github.com/gotgenes/pi-packages/issues/752)
+* **pi-permission-system:** mint a permission request id at request creation ([336842d](https://github.com/gotgenes/pi-packages/commit/336842de6c34e96bd90ed411eaca9649c4b9fac2)), closes [#752](https://github.com/gotgenes/pi-packages/issues/752)
+
+
+### Documentation
+
+* **pi-permission-system:** record the minted request id in the API and architecture docs ([84f5856](https://github.com/gotgenes/pi-packages/commit/84f5856868a548c9454ef3e23ca75c608ce3f308)), closes [#752](https://github.com/gotgenes/pi-packages/issues/752)
+
+## [25.3.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v25.2.2...pi-permission-system-v25.3.0) (2026-08-15)
+
+
+### Features
+
+* **pi-permission-system:** add promptMaxRows and promptFieldMaxWidth ([8dbca30](https://github.com/gotgenes/pi-packages/commit/8dbca303f55769222f6a829d3fc7a1d7461cd334)), closes [#710](https://github.com/gotgenes/pi-packages/issues/710)
+* **pi-permission-system:** expand the permission dialog to the complete request on Ctrl+O ([b741513](https://github.com/gotgenes/pi-packages/commit/b7415137236d6245a41f95255d17425127739a97)), closes [#710](https://github.com/gotgenes/pi-packages/issues/710)
+* **pi-permission-system:** render permission prompts as bounded, aligned fact lines ([2bd18c5](https://github.com/gotgenes/pi-packages/commit/2bd18c57003bdfbd0f95ad2c309e5387031164a0))
+
+
+### Documentation
+
+* **pi-permission-system:** distinguish the redundancy rule from elision ([5b26a46](https://github.com/gotgenes/pi-packages/commit/5b26a466191e5cc4395c2cebba22732c3d867bff)), closes [#710](https://github.com/gotgenes/pi-packages/issues/710)
+* **pi-permission-system:** document the bounded permission dialog ([68fcf58](https://github.com/gotgenes/pi-packages/commit/68fcf583f740cbcd8c5224db96fff85a74a2b0f2)), closes [#710](https://github.com/gotgenes/pi-packages/issues/710)
+
 ## [25.2.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v25.2.1...pi-permission-system-v25.2.2) (2026-08-15)
 
 

package/README.md

@@ -66,7 +66,7 @@ All permissions use one of three states:
 
 When the dialog prompts, you can approve once or approve a pattern for the rest of the session.
 In an interactive TUI session the prompt is an inline keybind dialog — `y` approve, `s` approve for this session, `n` deny, `r` deny with a reason — where each hotkey arms and a second press confirms (configurable via `doublePressToConfirm`).
-Pi's tool-expansion binding (`app.tools.expand`, `Ctrl+O` by default) keeps working while the dialog is open, so you can expand a truncated tool preview before deciding.
+The prompt shows one fact per line — who is asking, the tool, the matched rule, the value being decided — within a row budget, so a large tool input cannot take over the transcript; `Ctrl+O` (`app.tools.expand`) expands it to the complete request.
 See [docs/configuration.md](docs/configuration.md#inline-permission-dialog-tui) for the hotkeys and [docs/session-approvals.md](docs/session-approvals.md) for session-scoped rules and pattern suggestions.
 
 The `path` surface is a cross-cutting gate that applies to **all** file access — Pi tools, bash commands, MCP calls, and extension tools alike.

package/config/config.example.json

@@ -8,6 +8,9 @@
 
   "forwardingTimeoutMs": 600000,
 
+  "promptMaxRows": 24,
+  "promptFieldMaxWidth": 400,
+
   "toolInputPreviewMaxLength": 400,
   "toolTextSummaryMaxLength": 120,
 

package/dist/public.d.ts

@@ -1,5 +1,153 @@
 import { z } from 'zod';
 
+declare const permissionStateSchema: z.ZodUnion<readonly [z.ZodLiteral<"allow">, z.ZodLiteral<"deny">, z.ZodLiteral<"ask">]>;
+/** A permission decision. */
+type PermissionState = z.infer<typeof permissionStateSchema>;
+
+/**
+ * Provenance of a rule — which source contributed it.
+ *
+ * Config scopes: "global", "project", "agent", "project-agent".
+ * Synthesized:   "builtin" (universal default / evaluate() fallback),
+ *                "baseline" (conditional MCP metadata auto-allow).
+ * Runtime:       "session" (session approvals).
+ * Rewrite:       "yolo" (composition-stage ask→allow rewrite under yolo mode),
+ *                "fail-closed" (composition-stage allow→ask floor when an
+ *                invalid non-global config scope is detected).
+ */
+type RuleOrigin = "global" | "project" | "agent" | "project-agent" | "builtin" | "baseline" | "session" | "yolo" | "fail-closed";
+
+/**
+ * Execution context of a bash command nested inside a substitution or subshell.
+ * Absent for current-shell (top-level) commands.
+ */
+type BashCommandContext = "command_substitution" | "process_substitution" | "subshell";
+interface PermissionCheckResult {
+    toolName: string;
+    state: PermissionState;
+    /** Custom denial reason from a deny-with-reason pattern, when present. */
+    reason?: string;
+    matchedPattern?: string;
+    command?: string;
+    target?: string;
+    source: "tool" | "bash" | "mcp" | "skill" | "special" | "default" | "session";
+    /** Which source contributed the winning rule. */
+    origin: RuleOrigin;
+    /**
+     * Execution context of the offending nested command, when the winning bash
+     * unit came from a substitution or subshell. Absent for current-shell
+     * (top-level) commands.
+     */
+    commandContext?: BashCommandContext;
+    /**
+     * The command the winning bash unit actually runs, when it is a wrapper whose
+     * inner command differs from the unit text (#713). Display-only: the gate
+     * still decides on `command`, so this never widens or narrows a decision.
+     */
+    executedUnit?: string;
+}
+
+/**
+ * The complete, structured description of a permission ask (ADR 0011 §2).
+ *
+ * A gate emits one of these instead of a sentence. It is complete by contract:
+ * it never truncates and never decides what a human will see. Every consumer is
+ * a renderer over it, eliding under its own budget — so elision is a property
+ * of a render, never of the payload.
+ */
+interface PromptPayload {
+    readonly kind: PromptPayloadKind;
+    readonly request: PromptRequestFacts;
+    /** Complete; each renderer elides to fit its own budget. */
+    readonly evidence: readonly PromptEvidence[];
+    /** Supplied by registered annotators; always marked as model-generated. */
+    readonly annotations: readonly PromptAnnotation[];
+}
+/**
+ * Which ask this payload describes — the renderers' dispatch discriminant.
+ *
+ * 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.
+ */
+type PromptPayloadKind = "bash" | "mcp" | "tool" | "path" | "external_directory" | "bash_external_directory" | "skill" | "skill_read" | "forwarded";
+/**
+ * The invariant core (ADR 0011 §3): the facts visible in every render, that no
+ * renderer's budget may elide.
+ *
+ * Named for what it holds — the permission request's own facts, matching the
+ * package's `PermissionRequest` / `ForwardedPermissionRequest` vocabulary —
+ * rather than for its contract, which this comment states instead.
+ */
+interface PromptRequestFacts {
+    /** Who is asking, and whether the ask arrived from a subagent. */
+    readonly requester: PromptRequester;
+    /** The gate surface the rule fired on. */
+    readonly surface: string;
+    /** The gated tool name; `null` when the ask is not tool-shaped. */
+    readonly toolName: string | null;
+    /**
+     * The invoked tool name when a shell alias re-exposes bash under another
+     * name (#574) — "gated as bash, invoked as exec_command" is two facts.
+     * `null` when it adds nothing.
+     */
+    readonly invokedToolName: string | null;
+    /** The decision-relevant value: the command, path, MCP target, or skill name. */
+    readonly value: string;
+    /** The matched rule, including a sentinel such as `<indirection-bash-wrapper>`. */
+    readonly matchedPattern: string | null;
+    /**
+     * Where the offending bash unit runs, when it came from a substitution or a
+     * subshell. A fact rather than a rendered clause: it is what makes the
+     * matched rule intelligible, and how it reads is the renderer's choice.
+     */
+    readonly commandContext: BashCommandContext | null;
+    /**
+     * For bash, the unit that will actually run — including inside an unstrippable
+     * wrapper (#713). `null` when it adds nothing over {@link value}.
+     */
+    readonly executedUnit: string | null;
+}
+/** Who is asking, one hop below when the ask was forwarded. */
+interface PromptRequester {
+    readonly agentName: string | null;
+    readonly forwarded: boolean;
+    /** The requesting session, for a forwarded ask; `null` for a local one. */
+    readonly sessionId: string | null;
+}
+/**
+ * One piece of decision evidence.
+ *
+ * Complete on the payload; each renderer elides entries and orders them under
+ * its own budget (ADR 0011 §4).
+ */
+interface PromptEvidence {
+    readonly label: string;
+    readonly text: string;
+    /**
+     * A secondary fact bound to this entry that a renderer may show alongside
+     * {@link text} or elide independently — a path's symlink-resolved alias, for
+     * instance. Bound to the entry rather than listed as a second one so an
+     * elision cannot separate the two.
+     */
+    readonly detail: string | null;
+}
+/**
+ * A model-generated advisory (ADR 0011 §8).
+ *
+ * The slot owns the attribution and the model-generated marking, so marking is
+ * a property of the payload rather than a discipline each annotator must
+ * remember. Structurally separate from any verdict: an annotation cannot allow,
+ * deny, defer, or suppress.
+ */
+interface PromptAnnotation {
+    readonly source: string;
+    readonly text: string;
+}
+
 /** 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. */
@@ -59,6 +207,12 @@ interface PermissionUiPromptEvent {
 type PermissionDecisionResolution = "policy_allow" | "policy_deny" | "session_approved" | "infrastructure_auto_allowed" | "user_approved" | "user_approved_for_session" | "user_denied" | "auto_approved" | "confirmation_unavailable";
 /** Payload emitted on `permissions:decision`. */
 interface PermissionDecisionEvent {
+    /**
+     * Identifies the permission request this decision resolves, minted when the
+     * request was created. Distinct from the host's tool-call id: one tool call
+     * runs several gates and so raises several requests.
+     */
+    requestId: string;
     /** Permission surface: "bash", "read", "mcp", "skill", "external_directory", etc. */
     surface: string;
     /** The value that was evaluated (command, tool name, skill name, path). */
@@ -75,47 +229,6 @@ interface PermissionDecisionEvent {
     matchedPattern: string | null;
 }
 
-declare const permissionStateSchema: z.ZodUnion<readonly [z.ZodLiteral<"allow">, z.ZodLiteral<"deny">, z.ZodLiteral<"ask">]>;
-/** A permission decision. */
-type PermissionState = z.infer<typeof permissionStateSchema>;
-
-/**
- * Provenance of a rule — which source contributed it.
- *
- * Config scopes: "global", "project", "agent", "project-agent".
- * Synthesized:   "builtin" (universal default / evaluate() fallback),
- *                "baseline" (conditional MCP metadata auto-allow).
- * Runtime:       "session" (session approvals).
- * Rewrite:       "yolo" (composition-stage ask→allow rewrite under yolo mode),
- *                "fail-closed" (composition-stage allow→ask floor when an
- *                invalid non-global config scope is detected).
- */
-type RuleOrigin = "global" | "project" | "agent" | "project-agent" | "builtin" | "baseline" | "session" | "yolo" | "fail-closed";
-
-/**
- * Execution context of a bash command nested inside a substitution or subshell.
- * Absent for current-shell (top-level) commands.
- */
-type BashCommandContext = "command_substitution" | "process_substitution" | "subshell";
-interface PermissionCheckResult {
-    toolName: string;
-    state: PermissionState;
-    /** Custom denial reason from a deny-with-reason pattern, when present. */
-    reason?: string;
-    matchedPattern?: string;
-    command?: string;
-    target?: string;
-    source: "tool" | "bash" | "mcp" | "skill" | "special" | "default" | "session";
-    /** Which source contributed the winning rule. */
-    origin: RuleOrigin;
-    /**
-     * Execution context of the offending nested command, when the winning bash
-     * unit came from a substitution or subshell. Absent for current-shell
-     * (top-level) commands.
-     */
-    commandContext?: BashCommandContext;
-}
-
 /**
  * The child's session-approval suggestion, relayed to the serving node so a
  * human who grants "the whole session" records the same pattern the child
@@ -169,6 +282,14 @@ interface PromptPermissionDetails {
     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.
+     */
+    payload: PromptPayload;
     toolCallId?: string;
     toolName?: string;
     skillName?: string;

package/docs/configuration.md

@@ -36,7 +36,7 @@ See [migration/0644-project-trust-gating.md](migration/0644-project-trust-gating
 4. Project agent frontmatter
 
 The `permission` object uses deep-shallow merge: string-vs-string replaces; both-object shallow-merges pattern maps; string-vs-object the override wins entirely.
-Scalar fields (`debugLog`, `permissionReviewLog`, `yoloMode`, `doublePressToConfirm`, `forwardingTimeoutMs`) use simple replacement.
+Scalar fields (`debugLog`, `permissionReviewLog`, `yoloMode`, `doublePressToConfirm`, `forwardingTimeoutMs`, `promptMaxRows`, `promptFieldMaxWidth`) use simple replacement.
 
 **Invalid higher-precedence scope fails closed.**
 If a non-global scope (project config, global agent frontmatter, or project agent frontmatter) is present but fails to load or validate, it no longer contributes an empty scope that silently inherits the lower scope's rules.
@@ -106,6 +106,8 @@ This clamp is deny-preserving and, like `yoloMode`, applied at composition; when
 | `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 (`*`, `?`).                                     |
@@ -129,10 +131,23 @@ Arrow keys / `j`/`k` move the highlight, `enter` confirms the highlighted option
 With `doublePressToConfirm` enabled (the default), a letter hotkey **arms** its action and shows a `Press y again to approve.` hint; press the same key again to commit.
 Set `doublePressToConfirm` to `false` to commit on the first press.
 
-Pi's tool-expansion binding (`app.tools.expand`, `Ctrl+O` by default) stays live while the dialog is open, so you can expand a truncated tool preview before deciding.
+Pi's tool-expansion binding (`app.tools.expand`, `Ctrl+O` by default) stays live while the dialog is open.
+It expands both the prompt itself — to the complete request, unbounded by `promptMaxRows` and `promptFieldMaxWidth` — and the host's pending tool call, so one keystroke shows you everything before you decide.
 It only toggles the display — it never resolves, commits, or arms the pending decision.
 While you are typing a denial reason it is not intercepted, so a rebound printable key still reaches the reason editor.
 
+### What a prompt shows
+
+The prompt renders one fact per line, with the requesting agent (and, for a forwarded subagent ask, its session), the tool, the gate surface, the matched rule, the decision-relevant value, and — for a wrapper such as `xargs` — the command that will actually run.
+Those facts are always present: a budget may shorten a long one, never drop it.
+A fact the line above already states is not repeated — a bash ask shows `tool : bash` without a second `surface : bash` line, and a path ask's `path :` line names the surface itself.
+
+Everything else is evidence — the full command a gated sub-command came from, the working directory a path escaped, the tool-input preview — and it is what gives way when the render does not fit.
+A shortened field or a dropped entry is marked with an ellipsis, and `Ctrl+O` shows the complete request.
+Raise `promptMaxRows` to see more evidence inline; raise `promptFieldMaxWidth` to see more of a long command.
+
+Non-TUI contexts render the same facts under the same budget, without the colour or the expansion.
+
 Non-TUI contexts (RPC / frontend-driven sessions) keep the single-select prompt and are unaffected by `doublePressToConfirm`.
 
 ### `piInfrastructureReadPaths` patterns

package/docs/cross-extension-api.md

@@ -336,15 +336,15 @@ pi.events.on("permissions:ui_prompt", (raw) => {
 
 ### Payload Fields
 
-| Field        | Type                             | Description                                                            |
-| ------------ | -------------------------------- | ---------------------------------------------------------------------- |
-| `requestId`  | `string`                         | Unique ID for the permission request being prompted                    |
-| `source`     | `PermissionUiPromptSource`       | Prompt origin: `"tool_call"`, `"skill_input"`, or `"skill_read"`       |
-| `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                             |
-| `forwarding` | `ForwardedPromptContext \| null` | Forwarding context, or `null` for a direct prompt                      |
+| Field        | Type                             | Description                                                             |
+| ------------ | -------------------------------- | ----------------------------------------------------------------------- |
+| `requestId`  | `string`                         | Id of the permission request being prompted, minted when it was created |
+| `source`     | `PermissionUiPromptSource`       | Prompt origin: `"tool_call"`, `"skill_input"`, or `"skill_read"`        |
+| `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                              |
+| `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.
 
@@ -367,6 +367,10 @@ The stability guarantee is additive, so any can be reintroduced in a later minor
 Every permission gate resolution emits a `permissions:decision` event, regardless of outcome.
 This is useful for dashboards, telemetry, or audit overlays.
 
+The `requestId` is the same id the request's review-log entries carry, and the same one `permissions:ui_prompt` carried if the request reached a prompt — so a prompt and its outcome are joinable, as are two concurrent prompts for the same command.
+It identifies a permission *request*, not a tool call: one tool call runs several gates and so raises several requests, each with its own id.
+Use the review log's `toolCallId` to join back to the Pi transcript.
+
 ```typescript
 pi.events.on("permissions:decision", (raw) => {
   const event = raw as import("@gotgenes/pi-permission-system").PermissionDecisionEvent;
@@ -379,6 +383,7 @@ pi.events.on("permissions:decision", (raw) => {
 
 | Field            | Type                | Description                                                                               |
 | ---------------- | ------------------- | ----------------------------------------------------------------------------------------- |
+| `requestId`      | `string`            | Id of the permission request this decision resolves                                       |
 | `surface`        | `string`            | Permission surface (`"bash"`, `"read"`, `"mcp"`, `"skill"`, `"external_directory"`, etc.) |
 | `value`          | `string`            | Value evaluated (command, tool name, skill name, path)                                    |
 | `result`         | `"allow" \| "deny"` | Final outcome                                                                             |

package/package.json

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

package/schemas/permissions.schema.json

@@ -39,6 +39,22 @@
       "minimum": 1,
       "maximum": 9007199254740991
     },
+    "promptMaxRows": {
+      "description": "Maximum rows a permission prompt renders before eliding its evidence. Omit to use the default (24).",
+      "markdownDescription": "Maximum rows a permission prompt renders before eliding its evidence.\n\nOmit to use the default (24). The request's own facts — the requesting agent, the tool, the matched rule, the decision-relevant value — are never elided by this budget; what gives way is the supporting evidence, and `Ctrl+O` expands the prompt to the complete request.",
+      "default": 24,
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "promptFieldMaxWidth": {
+      "description": "Maximum characters of any one field shown in a permission prompt. Omit to use the default (400).",
+      "markdownDescription": "Maximum characters of any one field shown in a permission prompt.\n\nOmit to use the default (400). This is what bounds a single pathological field — a long here-string command, say — that would otherwise fill the prompt through wrapping. A shortened field is marked with an ellipsis, and `Ctrl+O` shows it in full.",
+      "default": 400,
+      "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.",

package/src/access-intent/bash/command-enumeration.ts

@@ -3,8 +3,16 @@ import {
   forEachNestedExecution,
 } from "#src/access-intent/bash/nested-execution";
 import type { TSNode } from "#src/access-intent/bash/parser";
+import {
+  type CommandWord,
+  classifyWrapperWords,
+  executedUnitOf,
+  type WrapperKind,
+} from "#src/access-intent/bash/wrapper-analysis";
 import type { BashCommandContext } from "#src/types";
 
+export type { WrapperKind } from "#src/access-intent/bash/wrapper-analysis";
+
 // ── Command type ─────────────────────────────────────────────────────────────
 
 /**
@@ -15,16 +23,6 @@ import type { BashCommandContext } from "#src/types";
  * The type is the stable extension point: #306 adds an execution `context`,
  * #307 adds per-command path candidates and an effective working directory.
  */
-/**
- * Why a command unit's decision is floored to at least `ask`.
- * `"opaque-payload"` — an inline-shell payload (`bash -c`/`eval`) whose inner
- * program is not re-parsed (#481).
- * `"indirection"` — a prefix/exec wrapper (`sudo`/`env`/`xargs`/`find -exec`/…)
- * whose inner command is a visible argument but is not gated on its own (#490).
- * The kind selects the audit sentinel; both floor identically.
- */
-export type WrapperKind = "opaque-payload" | "indirection";
-
 export interface BashCommand {
   readonly text: string;
   /**
@@ -38,6 +36,13 @@ export interface BashCommand {
    * Absent for an ordinary command.
    */
   readonly wrapperKind?: WrapperKind;
+  /**
+   * The command this wrapper unit actually runs (#713). Display-only — it is
+   * never gated on its own, so the wrapper floor still applies. Absent for an
+   * ordinary command, and for a wrapper whose inner command cannot be
+   * established.
+   */
+  readonly executedUnit?: string;
 }
 
 // ── Command enumeration ──────────────────────────────────────────────────────
@@ -105,9 +110,7 @@ function collectCommandsInto(
   if (COMMAND_ENUM_SKIP.has(node.type)) return;
 
   if (node.type === "command") {
-    out.push(
-      makeUnit(commandUnitText(node), context, classifyWrapperCommand(node)),
-    );
+    out.push(makeCommandUnit(node, context));
     // A command's text already contains any substitution; descend its subtree
     // to ALSO emit the inner commands of command/process substitutions.
     collectHostedCommands(node, out);
@@ -141,125 +144,50 @@ function makeUnit(
   text: string,
   context: BashCommandContext | undefined,
   wrapperKind?: WrapperKind,
+  executedUnit?: string,
 ): BashCommand {
   const unit: BashCommand = context ? { text, context } : { text };
-  return wrapperKind ? { ...unit, wrapperKind } : unit;
+  const flagged = wrapperKind ? { ...unit, wrapperKind } : unit;
+  return executedUnit === undefined ? flagged : { ...flagged, executedUnit };
 }
 
 /**
- * Shell command names whose `-c` flag introduces an opaque inline program.
- */
-const SHELL_WRAPPER_NAMES = new Set(["bash", "sh", "dash", "zsh", "ksh"]);
-
-/**
- * Indirection wrappers that always invoke a following command, so the wrapper
- * (not the inner command) is what a bash rule matches. Floored by command-name
- * basename alone. Extend this set to cover another always-invoking wrapper.
- */
-const INDIRECTION_WRAPPER_NAMES = new Set([
-  "sudo",
-  "env",
-  "xargs",
-  "time",
-  "nohup",
-  "timeout",
-  "nice",
-  // Exec-capable rewrites and prefix wrappers surveyed in #575: parallelizers
-  // (parallel/rust-parallel/rush), a sudo rewrite (doas), and prefix wrappers
-  // (setsid/stdbuf/watch/flock) that all always invoke a following command.
-  "parallel",
-  "rust-parallel",
-  "rush",
-  "doas",
-  "setsid",
-  "stdbuf",
-  "watch",
-  "flock",
-]);
-
-/**
- * Search tools that invoke a command per result only when an exec flag is
- * present; a bare search runs no subcommand. Floored only when an argument
- * exactly matches one of the tool's exec flags. Extend by adding a tool with
- * its exec-flag set.
- */
-const EXEC_CONDITIONAL_WRAPPERS = new Map<string, ReadonlySet<string>>([
-  ["find", new Set(["-exec", "-execdir", "-ok", "-okdir"])],
-  ["fd", new Set(["-x", "--exec", "-X", "--exec-batch"])],
-]);
-
-/**
- * Classify a `command` node as a floored wrapper, or `undefined` for an
- * ordinary command. Reads only the node's own named children (a shallow walk),
- * skipping any leading `variable_assignment` prefix, and matches the command
- * name on its basename (so `/bin/bash -c …` counts).
- *
- * `"opaque-payload"`: `eval`, or a shell (`bash`/`sh`/`dash`/`zsh`/`ksh`) with a
- * `-c` short-flag cluster (`-c`, `-ec`, `-xc`) — the inner program is a quoted
- * argument the enumerator does not re-parse (#481).
- *
- * `"indirection"`: an always-invoking prefix/exec wrapper
- * (`INDIRECTION_WRAPPER_NAMES`), or a search tool (`EXEC_CONDITIONAL_WRAPPERS`,
- * `find`/`fd`) carrying a per-result exec flag — the inner command is a visible
- * argument that a `<cmd> *` rule would otherwise never match (#490). A bare
- * `find`/`fd` search runs no subcommand and is not flagged.
+ * Build the unit for a `command` node, reading its words once to answer both
+ * wrapper questions: whether the unit is floored, and what it actually runs.
  */
-function classifyWrapperCommand(node: TSNode): WrapperKind | undefined {
-  const { commandName, args } = readWrapperCommand(node);
-  if (commandName === undefined) return undefined;
-  if (commandName === "eval") return "opaque-payload";
-  if (SHELL_WRAPPER_NAMES.has(commandName) && hasShortFlagC(args)) {
-    return "opaque-payload";
-  }
-  if (INDIRECTION_WRAPPER_NAMES.has(commandName)) return "indirection";
-  const execFlags = EXEC_CONDITIONAL_WRAPPERS.get(commandName);
-  if (execFlags && args.some((arg) => execFlags.has(arg))) return "indirection";
-  return undefined;
+function makeCommandUnit(
+  node: TSNode,
+  context: BashCommandContext | undefined,
+): BashCommand {
+  const text = commandUnitText(node);
+  const words = readCommandWords(node);
+  return makeUnit(
+    text,
+    context,
+    classifyWrapperWords(words),
+    executedUnitOf(text, words) ?? undefined,
+  );
 }
 
 /**
- * A `command` node's name basename and its argument texts, skipping any leading
- * `variable_assignment` prefix (matching `commandUnitText`). `commandName` is
- * `undefined` for a pure assignment with no `command_name`.
+ * A `command` node's words — its `command_name` followed by its arguments — each
+ * carrying its offset into the unit text `commandUnitText` produces.
+ *
+ * A leading `variable_assignment` prefix is skipped (matching
+ * `commandUnitText`), so offsets are relative to the `command_name`. An empty
+ * list means a pure assignment with no `command_name`.
  */
-function readWrapperCommand(node: TSNode): {
-  commandName: string | undefined;
-  args: string[];
-} {
-  let commandName: string | undefined;
-  const args: string[] = [];
+function readCommandWords(node: TSNode): CommandWord[] {
+  const words: CommandWord[] = [];
+  let unitStart: number | undefined;
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child?.isNamed) continue;
     if (child.type === "variable_assignment") continue;
-    if (commandName === undefined) {
-      commandName = basename(child.text);
-      continue;
-    }
-    args.push(child.text);
+    unitStart ??= child.startIndex;
+    words.push({ text: child.text, offset: child.startIndex - unitStart });
   }
-  return { commandName, args };
-}
-
-/**
- * True when an argument list has a short-flag cluster containing `c` before any
- * `--` end-of-options marker (`-c`, `-ec`, `-xc`) — the inline-shell payload
- * flag for `bash`/`sh`/`dash`/`zsh`/`ksh`.
- */
-function hasShortFlagC(args: string[]): boolean {
-  for (const arg of args) {
-    if (arg === "--") return false;
-    if (arg.startsWith("-") && !arg.startsWith("--") && arg.includes("c")) {
-      return true;
-    }
-  }
-  return false;
-}
-
-/** The final path segment of a command name (`/bin/bash` → `bash`). */
-function basename(name: string): string {
-  const slash = name.lastIndexOf("/");
-  return slash === -1 ? name : name.slice(slash + 1);
+  return words;
 }
 
 /**