@gotgenes/pi-permission-system 23.0.3 → 24.0.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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)
 
 

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

@@ -209,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.3",
+  "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-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;
 }