@gotgenes/pi-permission-system 25.2.1 → 25.3.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.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)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** gate commands hosted in bash redirect targets ([1015bb8](https://github.com/gotgenes/pi-packages/commit/1015bb879234d1d96595b9f995ca88037588e16f)), closes [#741](https://github.com/gotgenes/pi-packages/issues/741)
+* **pi-permission-system:** gate commands hosted in interpolating heredoc bodies ([48978d2](https://github.com/gotgenes/pi-packages/commit/48978d2016c67aa90f291db55d98908ba930f0d1)), closes [#741](https://github.com/gotgenes/pi-packages/issues/741)
+* **pi-permission-system:** project path operands of heredoc-hosted nested commands ([8e2fbee](https://github.com/gotgenes/pi-packages/commit/8e2fbee404677d02c7cc565cf23d1e778994d5f0)), closes [#741](https://github.com/gotgenes/pi-packages/issues/741)
+* **pi-permission-system:** project path operands of redirect-hosted nested commands ([12164f3](https://github.com/gotgenes/pi-packages/commit/12164f3b61b6a4b50281d84b6d741a3736516991)), closes [#741](https://github.com/gotgenes/pi-packages/issues/741)
+
+
+### Documentation
+
+* **pi-permission-system:** document hosted nested-command evaluation ([f24b338](https://github.com/gotgenes/pi-packages/commit/f24b338a42855f96038fdf2efdfe440cef8501c8)), closes [#741](https://github.com/gotgenes/pi-packages/issues/741)
+
 ## [25.2.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v25.2.0...pi-permission-system-v25.2.1) (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. */
@@ -75,47 +223,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 +276,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
@@ -328,6 +343,11 @@ Quotes are respected (an operator inside `'…'` or `"…"` does not split the c
 Commands nested inside command substitution (`$(…)`, backticks), process substitution (`<(…)`/`>(…)`), and subshells (`( … )`) are evaluated against the bash patterns too, in addition to their enclosing command — since those inner commands really execute.
 So `echo $(rm -rf foo)` evaluates both `echo $(rm -rf foo)` and the inner `rm -rf foo`; if `rm *` is denied, the whole invocation is denied.
 The deny reason and the approval prompt note the nested origin (e.g. `inside command substitution`).
+
+This holds wherever the substitution appears, not only in argument position.
+A substitution in a **redirect target** (`echo hi > $(rm *.txt)`, `cat < <(rm c)`, ``echo hi 2> `rm d` ``) and one in an **interpolating heredoc body** (`cat <<EOF` with `$(rm e)` in the body) are evaluated the same way.
+A quoted heredoc delimiter (`<<'EOF'` or `<<"EOF"`) does not interpolate, so its body is literal text and nothing in it is evaluated as a command.
+The enclosing command is still matched without its redirect, so a rule like `npm install` keeps matching `npm install > out.txt`.
 Control-flow bodies (`if`/`while`/`for`/`case`) and `{ … }` brace groups are not descended into; their contents are matched as part of the enclosing statement's text.
 
 A leading environment-variable assignment prefix is stripped before matching, so the rule gates the underlying command rather than the prefix.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "25.2.1",
+  "version": "25.3.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.",