@gotgenes/pi-permission-system 23.0.2 → 24.0.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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).
 
+## [24.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v23.0.3...pi-permission-system-v24.0.0) (2026-07-26)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** an authorizer chain link's `allow` on a forwarded subagent ask raised by the `path` or `external_directory` gate is now downgraded to `defer`, so the request falls through to an interactive prompt. This affects only an operator running an allow-capable third-party link named in `authorizerChain`; the first-party model judge is deny-first and is unaffected, as are forwarded `bash` asks and per-tool-gated asks. See packages/pi-permission-system/docs/migration/0635-forwarded-ask-delegation-envelope.md
+
+### Bug Fixes
+
+* **pi-permission-system:** carry forwarded access facts to the Authorizer Chain ([#635](https://github.com/gotgenes/pi-packages/issues/635)) ([c0790ad](https://github.com/gotgenes/pi-packages/commit/c0790ad6d1d15defaba60097d803618b4d8c461c))
+
+## [23.0.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v23.0.2...pi-permission-system-v23.0.3) (2026-07-26)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** preserve tool expansion in inline permission prompts ([6a0d241](https://github.com/gotgenes/pi-packages/commit/6a0d241291f8eefa51493b683e12514a83f295bd))
+
+
+### Documentation
+
+* **pi-permission-system:** document tool expansion during permission prompts ([f4098d3](https://github.com/gotgenes/pi-packages/commit/f4098d331efc72538ee3836ffb4056beee8cbed0))
+
 ## [23.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v23.0.1...pi-permission-system-v23.0.2) (2026-07-26)
 
 

package/README.md

@@ -66,6 +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.
 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/dist/public.d.ts

@@ -195,8 +195,10 @@ interface PromptPermissionDetails {
      * The child-fixed access facts the raising gate computed (surface + match
      * set). Rides through the runner to the escalation edge, which completes
      * them into a `ForwardedAccessIntent` by stamping `requesterCwd` and
-     * `principal`. Absent for a serving-node local prompt reconstructed from a
-     * forwarded request.
+     * `principal`. On a serving node these facts are projected back off the
+     * forwarded request, so a forwarded ask reaches the `Authorizer` chain with
+     * the same evidence as a local one; only a version-skew request that carried
+     * no intent leaves this absent.
      */
     accessIntent?: ForwardedAccessFacts;
 }

package/docs/configuration.md

@@ -127,6 +127,10 @@ 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.
+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.
+
 Non-TUI contexts (RPC / frontend-driven sessions) keep the single-select prompt and are unaffected by `doublePressToConfirm`.
 
 ### `piInfrastructureReadPaths` patterns
@@ -205,6 +209,9 @@ Three invariants govern the chain:
 
 The chain owner caps every link with a **bounded-delegation checkpoint**: a link's `allow` on an excluded surface (`external_directory` or the `path` surface) is downgraded to `defer`, so a buggy or over-eager judge can never approve access outside your policy.
 Deny and defer are never capped.
+The excluded surface is the **gate** surface the rule fired on, not the tool name displayed in the prompt — so a `write` blocked by a `path` rule is capped.
+This holds for an ask forwarded up from a subagent exactly as it does for a local one.
+See [migration/0635-forwarded-ask-delegation-envelope.md](migration/0635-forwarded-ask-delegation-envelope.md).
 
 Extension authors: register a link from a `permissions:ready` handler via `getPermissionsService().registerAuthorizer(name, authorize)`; the callback receives the ask details and a narrow, session-scoped `PermissionQuery` (`checkPermission` / `getToolPermission`) so it can consult the deterministic engine at gate parity.
 Registration returns a disposer, and only one link may hold a given name.

package/docs/migration/0635-forwarded-ask-delegation-envelope.md

@@ -0,0 +1,42 @@
+# Migration guide: forwarded asks and the bounded-delegation checkpoint
+
+Starting with the release that closes #635, a permission request forwarded up from a subagent carries the **child-fixed access facts** through to the authorizer chain.
+As a side effect, the bounded-delegation checkpoint now applies to forwarded asks the same way it already applied to local ones.
+This is a **breaking change** for one narrow configuration.
+
+## Who is affected
+
+You are affected only if **all** of the following hold:
+
+- You name an authorizer chain link in `authorizerChain`, and
+- that link is **allow-capable** (it can return `allow`, not only `deny` / `defer`), and
+- a subagent forwards an `ask` to your session that was raised by the `path` or `external_directory` gate.
+
+If you run no chain link, or run only a deny-first link — including the first-party [`@gotgenes/pi-permission-model-judge`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-model-judge), which only ever denies or defers — **nothing changes for you**.
+
+## What changed
+
+The checkpoint downgrades a link's `allow` to `defer` on the excluded surfaces (`path`, `external_directory`), so the request falls through to an interactive prompt instead.
+It selects the surface from the **gate** surface — the surface the matching rule lives on — falling back to the displayed surface when no gate surface is available.
+
+A forwarded request previously arrived with no gate surface, so the checkpoint fell back to the child's *display* surface, which is the tool name (`write`, `edit`, `read`).
+A tool name is not an excluded surface, so a link's `allow` on a forwarded `path`-gated request was honored.
+The identical request made directly in the same session was capped, because a local request always carries its gate surface.
+
+Forwarding was therefore a way around your own delegation boundary: a link could approve `~/.ssh/config` for a subagent that it could not approve for the main session.
+Now the gate surface crosses the forwarding hop, and both paths behave identically.
+
+Unchanged: a forwarded `bash` ask, and a forwarded tool ask gated by a per-tool rule (`write: ask`), are both already on non-excluded surfaces and are not capped.
+`deny` and `defer` verdicts were never capped and still are not.
+
+## What you need to do
+
+Nothing, unless you run an allow-capable link.
+
+If you do, expect an interactive prompt where that link previously auto-approved a forwarded subagent request for a path.
+To keep such a request from prompting, grant it in policy rather than through the link — the `path` and `external_directory` rules in your config are consulted before the chain runs, so an `allow` there resolves the request without reaching an authorizer at all.
+
+## Related
+
+Issue #620 will replace the whole-`path` exclusion with a narrower secret-shaped one, letting a link allow a non-secret path again while keeping secret-shaped paths capped.
+That refinement applies to local and forwarded asks alike, so the two paths stay aligned.

package/package.json

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

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

@@ -5,6 +5,7 @@ import {
 } from "#src/authority/forwarder-context";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import {
+  type ForwardedAccessFacts,
   type ForwardedAccessIntent,
   type ForwardedPermissionRequest,
   type ForwardedPermissionResponse,
@@ -93,7 +94,14 @@ function formatForwardedPermissionPrompt(
 /**
  * Map a forwarded request onto the escalated ask's details, carrying the
  * forwarded provenance (requester agent/session + the child's original display
- * projection) so `LocalUserAuthorizer` emits a non-degraded broadcast (#292).
+ * projection) so `LocalUserAuthorizer` emits a non-degraded broadcast (#292),
+ * plus the child-fixed access facts so the serving node's `Authorizer` chain
+ * judges a forwarded ask on the same evidence as a local one (ADR 0008; #635).
+ *
+ * The display `surface` and the fact `surface` are distinct and both belong
+ * here: the former is the child's tool name (what the UI shows), the latter the
+ * gate surface the rule fired on (what the bounded-delegation checkpoint
+ * excludes on).
  */
 function buildForwardedAskDetails(
   request: ForwardedPermissionRequest,
@@ -114,6 +122,33 @@ function buildForwardedAskDetails(
     ...(request.sessionApproval
       ? { sessionApproval: request.sessionApproval }
       : {}),
+    // Absent for a version-skew request that carried no intent — which the
+    // delegation envelope reads as "surface undetermined" and fail-safes to
+    // excluded, so absence must stay absence rather than become `undefined`.
+    ...(request.accessIntent
+      ? { accessIntent: toAccessFacts(request.accessIntent) }
+      : {}),
+  };
+}
+
+/**
+ * Project the wire intent down to the child-fixed access facts an `Authorizer`
+ * may see.
+ *
+ * Field-by-field rather than a spread, because this is a disclosure boundary:
+ * `requesterCwd` and `principal` are requester identity for the serving node's
+ * own resolution (ADR 0008 §3) and stay off the ask details. A link that needs
+ * requester identity reads `details.forwarding`. `ForwardedAccessIntent`
+ * extends `ForwardedAccessFacts`, so a spread would type-check while widening
+ * disclosure at runtime; the explicit return type makes any future field on
+ * `ForwardedAccessFacts` a compile error here until it is deliberately
+ * projected or deliberately withheld.
+ */
+function toAccessFacts(intent: ForwardedAccessIntent): ForwardedAccessFacts {
+  return {
+    surface: intent.surface,
+    matchValues: intent.matchValues,
+    boundaryValue: intent.boundaryValue,
   };
 }
 

package/src/authority/permission-prompt-component.ts

@@ -1,6 +1,7 @@
 import type {
   ExtensionContext,
   ExtensionUIContext,
+  KeybindingsManager,
 } from "@earendil-works/pi-coding-agent";
 import {
   type Component,
@@ -35,9 +36,12 @@ import {
 /** The subset of the session UI surface the inline dialog needs. */
 export type PermissionPromptUi = Pick<
   ExtensionUIContext,
-  "select" | "input" | "custom"
+  "select" | "input" | "custom" | "getToolsExpanded" | "setToolsExpanded"
 >;
 
+/** The keybindings surface the dialog consults; only `matches` is read (ISP). */
+type PromptKeybindings = Pick<KeybindingsManager, "matches">;
+
 /** The resolved presentation context selected once per activation. */
 export interface PermissionPromptView {
   mode: ExtensionContext["mode"];
@@ -97,12 +101,13 @@ export function presentInlinePermissionPrompt(
     sessionScope: options?.sessionScope,
   };
   return view.ui.custom<PermissionPromptDecision>(
-    (tui, theme, _keybindings, done) =>
+    (tui, theme, keybindings, done) =>
       new PermissionPromptComponent(
         theme,
         config,
         title,
         message,
+        (data) => handleToolsExpandAction(data, keybindings, view.ui),
         () => {
           tui.requestRender();
         },
@@ -112,6 +117,31 @@ export function presentInlinePermissionPrompt(
   );
 }
 
+/**
+ * Forward Pi's tool-expansion action while the dialog holds keyboard focus.
+ *
+ * A focused `ctx.ui.custom` component consumes every keystroke, so `Ctrl+O`
+ * would otherwise be dead for the duration of an ask — exactly when the user
+ * most needs to see the full pending tool invocation. Returns `true` when the
+ * keystroke was the action (and was handled), so the caller stops before
+ * mapping it to a {@link PromptEvent}; expansion is a display concern and must
+ * never reach the decision model.
+ *
+ * Deliberately does not request a render: `setToolsExpanded` re-renders the
+ * host itself, and the dialog's own lines are unaffected by tool expansion.
+ */
+function handleToolsExpandAction(
+  data: string,
+  keybindings: PromptKeybindings,
+  ui: PermissionPromptUi,
+): boolean {
+  if (!keybindings.matches(data, "app.tools.expand")) {
+    return false;
+  }
+  ui.setToolsExpanded(!ui.getToolsExpanded());
+  return true;
+}
+
 class PermissionPromptComponent implements Component {
   private state: PromptViewState;
   private reasonBuffer = "";
@@ -121,6 +151,7 @@ class PermissionPromptComponent implements Component {
     private readonly config: PromptModelConfig,
     private readonly title: string,
     private readonly message: string,
+    private readonly handleAppAction: (data: string) => boolean,
     private readonly requestRender: () => void,
     private readonly done: (decision: PermissionPromptDecision) => void,
   ) {
@@ -151,6 +182,9 @@ class PermissionPromptComponent implements Component {
       this.handleReasonInput(data);
       return;
     }
+    if (this.handleAppAction(data)) {
+      return;
+    }
     const event = this.toEvent(data);
     if (event) {
       this.apply(event);

package/src/authority/permission-prompter.ts

@@ -53,8 +53,10 @@ export interface PromptPermissionDetails {
    * The child-fixed access facts the raising gate computed (surface + match
    * set). Rides through the runner to the escalation edge, which completes
    * them into a `ForwardedAccessIntent` by stamping `requesterCwd` and
-   * `principal`. Absent for a serving-node local prompt reconstructed from a
-   * forwarded request.
+   * `principal`. On a serving node these facts are projected back off the
+   * forwarded request, so a forwarded ask reaches the `Authorizer` chain with
+   * the same evidence as a local one; only a version-skew request that carried
+   * no intent leaves this absent.
    */
   accessIntent?: ForwardedAccessFacts;
 }