@gotgenes/pi-permission-system 24.0.0 → 25.1.0

package/CHANGELOG.md

@@ -5,6 +5,48 @@ 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.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v25.0.0...pi-permission-system-v25.1.0) (2026-08-13)
+
+
+### Features
+
+* **pi-permission-system:** add a process-global serving-session registry ([2939982](https://github.com/gotgenes/pi-packages/commit/2939982f80669a65df356f17e8110174ff96e68a)), closes [#719](https://github.com/gotgenes/pi-packages/issues/719)
+* **pi-permission-system:** announce the session serving forwarded requests ([74c0259](https://github.com/gotgenes/pi-packages/commit/74c0259141e616b1cb7760427e507fac518ba2e4)), closes [#719](https://github.com/gotgenes/pi-packages/issues/719)
+* **pi-permission-system:** make the forwarding timeout configurable ([fc6190d](https://github.com/gotgenes/pi-packages/commit/fc6190de23eb6347a135bf85e45f3060ac9b6868)), closes [#719](https://github.com/gotgenes/pi-packages/issues/719)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** carry the denial reason into the unavailable block message ([1a0b289](https://github.com/gotgenes/pi-packages/commit/1a0b2894854576d2a171e98a10939c2c4c56794b)), closes [#719](https://github.com/gotgenes/pi-packages/issues/719)
+* **pi-permission-system:** fail fast when no session serves a forwarded request ([5241df0](https://github.com/gotgenes/pi-packages/commit/5241df0d6986fa66e1f21ccab6de956ac9d630ce)), closes [#719](https://github.com/gotgenes/pi-packages/issues/719)
+* **pi-permission-system:** report forwarding failures as unavailable, not user-denied ([6c37d27](https://github.com/gotgenes/pi-packages/commit/6c37d2778c0be51423b9b80569205ce68a0ac977)), closes [#719](https://github.com/gotgenes/pi-packages/issues/719)
+
+
+### Documentation
+
+* **pi-permission-system:** document forwarding liveness and the timeout field ([e493991](https://github.com/gotgenes/pi-packages/commit/e493991d67eb4e305a8a50346b1affed39ecbd96)), closes [#719](https://github.com/gotgenes/pi-packages/issues/719)
+
+## [25.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v24.0.0...pi-permission-system-v25.0.0) (2026-08-11)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** a bash command referencing `$HOME` or `${HOME}` now reaches the `external_directory` gate whether or not the target exists, so a policy with `external_directory: {"*": "ask"}` prompts for commands that previously ran silently. Allow the directory explicitly to restore the old behavior — e.g. `"external_directory": {"~/.cargo/registry/*": "allow"}`. The token shown in prompts, review-log entries, and derived session-approval patterns is now the expanded path rather than the `$HOME/...` spelling; this makes the prompt agree with the approval pattern, which was already derived from the expanded form.
+
+### Features
+
+* **pi-permission-system:** expand ${HOME} alongside $HOME in path patterns ([3ebbd41](https://github.com/gotgenes/pi-packages/commit/3ebbd418e5b85a6dfbc1865c69f62c1f9a3cb144)), closes [#694](https://github.com/gotgenes/pi-packages/issues/694)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** resolve $HOME and $PWD expansions in bash path tokens ([8cbc7ee](https://github.com/gotgenes/pi-packages/commit/8cbc7ee011a3e06dcf047bfe8a467db3aa487721)), closes [#694](https://github.com/gotgenes/pi-packages/issues/694)
+
+
+### Documentation
+
+* **pi-permission-system:** record resolved shell expansions in ADR 0009 and user docs ([caaf5ec](https://github.com/gotgenes/pi-packages/commit/caaf5ec02ef2f7df1e2a922dba0a9afdc121b191)), closes [#694](https://github.com/gotgenes/pi-packages/issues/694)
+
 ## [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)
 
 

package/config/config.example.json

@@ -6,6 +6,8 @@
   "yoloMode": false,
   "doublePressToConfirm": true,
 
+  "forwardingTimeoutMs": 600000,
+
   "toolInputPreviewMaxLength": 400,
   "toolTextSummaryMaxLength": 120,
 

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`) use simple replacement.
+Scalar fields (`debugLog`, `permissionReviewLog`, `yoloMode`, `doublePressToConfirm`, `forwardingTimeoutMs`) 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.
@@ -57,6 +57,7 @@ This clamp is deny-preserving and, like `yoloMode`, applied at composition; when
   "permissionReviewLog": true,
   "yoloMode": false,
   "doublePressToConfirm": true,
+  "forwardingTimeoutMs": 600000,
   "toolInputPreviewMaxLength": 400,
   "toolTextSummaryMaxLength": 120,
   "piInfrastructureReadPaths": [],
@@ -98,16 +99,17 @@ 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.                                                  |
-| `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` 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 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. |
+| `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)).                         |
 
 Both logs write to `~/.pi/agent/extensions/pi-permission-system/logs/`.
 No debug output is printed to the terminal.
@@ -136,7 +138,7 @@ Non-TUI contexts (RPC / frontend-driven sessions) keep the single-select prompt
 ### `piInfrastructureReadPaths` patterns
 
 Each entry is either a plain directory prefix or a wildcard pattern.
-Plain entries match any path that starts with the given directory (after `~`/`$HOME` expansion).
+Plain entries match any path that starts with the given directory (after `~`/`$HOME`/`${HOME}` expansion).
 Wildcard entries use `*` (any characters, including `/`) and `?` (exactly one character).
 `*` and `**` are equivalent — both cross directory boundaries.
 
@@ -587,9 +589,22 @@ The pattern is stored and displayed as written (`~/.cargo/registry/*`) in logs a
 For caches you only ever **read**, `piInfrastructureReadPaths` is a lighter alternative — it auto-allows read-only tools (`read`, `find`, `grep`, `ls`) and bypasses the gate entirely, but it does not cover `write`/`edit` or bash.
 Use `external_directory` when the allowance must apply to every tool.
 
-Bash commands are also covered: the extension extracts path-like tokens from the command string and applies the same gate when any resolve outside `ctx.cwd`.
-Quoted strings are stripped first to reduce false positives.
-This is a best-effort heuristic — variable expansion and escaped quotes are not parsed, and relative paths inside subshells are not yet resolved against a per-subshell working directory. (The separate `bash` command-pattern surface does evaluate commands nested inside substitutions and subshells; see that section.) OS device paths (`/dev/null`, `/dev/stdin`, `/dev/stdout`, `/dev/stderr`) are always excluded.
+Bash commands are also covered: the extension parses the command and applies the same gate to every token that resolves outside `ctx.cwd`.
+Quoting is understood, so `ls "$HOME/x"` and `ls $HOME/x` are treated alike.
+
+What the bash projection resolves:
+
+- Absolute, home-relative (`~/`), parent-traversal (`../`), and separator-bearing tokens, plus redirect targets (`> out.txt`) and values embedded in long options (`--file=/tmp/patterns`).
+- The plain shell variables `$HOME` / `${HOME}` and `$PWD` / `${PWD}`, so `$HOME/x` is gated exactly as `~/x` and the literal absolute spelling, whether or not the target exists.
+- Relative tokens, against the working directory produced by folding literal current-shell `cd` commands.
+- A bare token (`cat id_rsa`) when it names an existing filesystem entry.
+
+What it deliberately does not resolve: any other variable (`$CONFIG_DIR`), a command substitution (`$(cmd)`), an expansion carrying an operator (`${HOME:-/tmp}`), and a variable reached through an assignment (`CURRENT="$HOME"; ls "$CURRENT"`).
+A non-literal `cd` (`cd "$DIR"`) makes the working directory unknown, after which relative tokens are kept literal rather than resolved against a guess.
+Commands whose payload is opaque (`bash -c`, `eval`, `sudo`, `xargs`) are floored to `ask` instead of projected.
+The governing record is [ADR 0009](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0009-bash-path-projection-completeness-contract.md), which states what the projection guarantees and which gaps are accepted residuals rather than bugs.
+
+(The separate `bash` command-pattern surface does evaluate commands nested inside substitutions and subshells; see that section.) OS device paths (`/dev/null`, `/dev/stdin`, `/dev/stdout`, `/dev/stderr`) are always excluded.
 
 #### Symlinked paths
 
@@ -644,8 +659,9 @@ To allow-list such a path, write the rule using the path as typed — for exampl
 
 ### Home Directory Expansion in Patterns
 
-Pattern keys in any permission surface can start with `~/` or `$HOME/` (or be exactly `~` / `$HOME`).
+Pattern keys in any permission surface can start with `~/`, `$HOME/`, or `${HOME}/` (or be exactly `~`, `$HOME`, or `${HOME}`).
 They are expanded to the OS home directory at match time, so configs are portable across machines and users.
+A prefix is recognized only when it stands alone or precedes a separator, so a longer name (`~username`, `$HOMEDIR`) and a braced expansion carrying an operator (`${HOME:-/tmp}`) are left alone.
 
 ```jsonc
 {
@@ -661,7 +677,7 @@ They are expanded to the OS home directory at match time, so configs are portabl
 The pattern is stored and displayed as written (e.g. `~/development/*`) in logs and approval dialogs.
 
 Path **values** supplied by tool calls and bash commands are expanded the same way.
-This means `~/...`, `$HOME/...`, and the fully-expanded absolute form all match a single home-anchored pattern: a `read` tool called with path `~/.ssh/config`, `$HOME/.ssh/config`, or `/Users/me/.ssh/config` is all caught by a `"~/.ssh/*": "deny"` rule.
+This means `~/...`, `$HOME/...`, `${HOME}/...`, and the fully-expanded absolute form all match a single home-anchored pattern: a `read` tool called with path `~/.ssh/config`, `$HOME/.ssh/config`, `${HOME}/.ssh/config`, or `/Users/me/.ssh/config` is all caught by a `"~/.ssh/*": "deny"` rule.
 
 ---
 

package/docs/opencode-compatibility.md

@@ -20,7 +20,7 @@ The following concepts are shared between OpenCode and this extension:
 | Last-match-wins               | When multiple patterns match, the last one in config order wins                                                 |
 | `*` wildcard                  | Matches zero or more of any character (including path separators)                                               |
 | `?` wildcard                  | Matches exactly one character                                                                                   |
-| Home directory expansion      | `~/` and `$HOME/` expand to the OS home directory in patterns                                                   |
+| Home directory expansion      | `~/`, `$HOME/`, and `${HOME}/` expand to the OS home directory in patterns                                      |
 | `external_directory` surface  | Gates access to paths outside the working directory                                                             |
 | `bash` surface                | Command patterns matched against shell commands                                                                 |
 | `skill` surface               | Skill name patterns matched against skill invocations                                                           |

package/docs/subagent-integration.md

@@ -32,6 +32,31 @@ This keeps `ask` policies usable even when the original permission check happens
 
 For in-process child sessions, detection and forwarding use the event-driven registration described above.
 
+### When nobody answers
+
+A forwarded request is only useful if some session is draining the inbox it was written into.
+The polling session publishes the session id it polls, and an in-process child checks that its target is published before committing to a long wait.
+
+If the target is not draining its inbox, the child gives up after a two-second grace window rather than waiting out `forwardingTimeoutMs`, and the tool is blocked with:
+
+```text
+[pi-permission-system] Running bash command 'pwd' requires approval, but no
+interactive UI is available. Reason: Session 'abc123' is not serving forwarded
+permission requests.
+```
+
+The grace window exists so a request that arrives while the parent is switching sessions is not abandoned in the gap.
+A target that *is* draining its inbox is waited on for the full `forwardingTimeoutMs`, however long the human takes to decide.
+
+Every other way the forwarding path can give up — an unresolvable parent session, forwarding directories that cannot be created, a request that cannot be written, an unreadable response, and the timeout itself — is reported the same way: as approval being unavailable, with a reason naming the specific failure.
+None of them is reported as a user denial, because no user was ever asked.
+
+The two sides of the exchange are correlatable in the review log: the serving session writes `forwarded_permission.serving_started` with the id it polls, and the child writes `forwarded_permission.request_created` with the `targetSessionId` it forwarded to.
+When a forwarded request goes unanswered, comparing those two entries distinguishes a parent that was not polling from one polling a different session.
+
+This liveness signal is process-local, so it applies to in-process children only.
+A child running as a separate `pi` process (the `PI_SUBAGENT_PARENT_SESSION` path) cannot observe its parent's polling and still waits the full timeout.
+
 ---
 
 ## Coexistence with Other Subagent Extensions

package/package.json

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

package/schemas/permissions.schema.json

@@ -31,6 +31,14 @@
       "default": true,
       "type": "boolean"
     },
+    "forwardingTimeoutMs": {
+      "description": "How long a subagent waits for the parent session to answer a forwarded permission request, in milliseconds. Omit to use the default (600000, ten minutes).",
+      "markdownDescription": "How long a subagent waits for the parent session to answer a forwarded permission request, in milliseconds.\n\nOmit to use the default (`600000`, ten minutes). A child whose in-process parent is not draining its inbox at all gives up in a couple of seconds regardless of this value, so lower it only to bound how long you are willing to leave an *unanswered* prompt pending.",
+      "default": 600000,
+      "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/node-text.ts

@@ -1,4 +1,5 @@
 import type { TSNode } from "#src/access-intent/bash/parser";
+import { resolvePlainVariableExpansion } from "#src/access-intent/bash/shell-variable-expansion";
 
 /**
  * Node types whose subtrees must never be descended into for
@@ -29,6 +30,8 @@ export const ARG_NODE_TYPES = new Set([
  * - `raw_string`    → strip surrounding single quotes
  * - `string`        → strip surrounding double quotes, concatenate children text
  * - `concatenation` → concatenate resolved children
+ * - expansions      → the resolved value of a plain `$HOME`/`$PWD` reference,
+ *   else `.text` (see `shell-variable-expansion.ts`)
  * - other           → `.text` as fallback
  */
 export function resolveNodeText(node: TSNode): string {
@@ -57,9 +60,10 @@ export function resolveNodeText(node: TSNode): string {
       return result;
     }
     case "string_content":
+      return node.text;
     case "simple_expansion":
     case "expansion":
-      return node.text;
+      return resolvePlainVariableExpansion(node) ?? node.text;
     case "concatenation": {
       let result = "";
       for (let i = 0; i < node.childCount; i++) {

package/src/access-intent/bash/shell-variable-expansion.ts

@@ -0,0 +1,77 @@
+/**
+ * Resolution of the shell variable references the bash path projection can
+ * settle statically.
+ *
+ * Runs at token collection, upstream of classification: by the time a token
+ * reaches `classifyTokenAsPathCandidate` it already carries the expanded path,
+ * so `$HOME/x` is accepted by the ordinary absolute-shape branch and needs no
+ * per-variable knowledge in the classifiers (#694). Keeping the vocabulary here
+ * — rather than teaching each classifier a `$HOME` prefix — is what stops the
+ * two from drifting apart, which is the defect this module closes.
+ *
+ * The resolvable set is deliberately tiny and closed. `HOME` is the spelling
+ * `expandHomePath` already resolves for config patterns and path literals, so
+ * resolving it here removes an inconsistency rather than widening the
+ * determinism boundary; `PWD` reads no environment at all. Every other name
+ * keeps its literal text, so ADR 0003's exclusion of ambient host state stands.
+ * See `docs/decisions/0009-bash-path-projection-completeness-contract.md`.
+ */
+import { homedir } from "node:os";
+
+import type { TSNode } from "#src/access-intent/bash/parser";
+
+/**
+ * The value of a plain `$NAME` / `${NAME}` reference, or `null` when the node
+ * is not a plain reference or names a variable outside the resolvable set.
+ *
+ * Plainness is decided structurally, not by matching the node's text: a plain
+ * reference carries exactly one `variable_name` child and nothing else but
+ * delimiters. An operator form (`${HOME:-/tmp}`, `${#HOME}`, `${HOME%/*}`)
+ * carries additional children and is therefore rejected without this module
+ * needing to enumerate bash's expansion operators.
+ */
+export function resolvePlainVariableExpansion(node: TSNode): string | null {
+  const name = plainVariableName(node);
+  return name === null ? null : (RESOLVABLE_VARIABLES.get(name)?.() ?? null);
+}
+
+/**
+ * How each resolvable variable is spelled as a path.
+ *
+ * `PWD` resolves to the base-relative marker rather than a directory: the
+ * shell's working directory at a given point *is* the projection's effective
+ * base, which the resolver already applies via `resolveBase`. Handing back `.`
+ * therefore lands `$PWD/x` on the same footing as `./x` — correct after any
+ * `cd` folding, conservative under an unknown base (#393), and free of both a
+ * threaded base parameter and a platform branch.
+ */
+const RESOLVABLE_VARIABLES: ReadonlyMap<string, () => string> = new Map([
+  ["HOME", homedir],
+  ["PWD", () => "."],
+]);
+
+/** Node types that delimit an expansion without altering what it evaluates to. */
+const EXPANSION_DELIMITERS: ReadonlySet<string> = new Set(["$", "${", "}"]);
+
+/**
+ * The variable a node plainly references, or `null` when it references none —
+ * because it has no `variable_name` child, has more than one, or carries a
+ * child that is neither the name nor a delimiter (an expansion operator and its
+ * operand, or an assignment's `=` and value).
+ */
+function plainVariableName(node: TSNode): string | null {
+  let name: string | null = null;
+
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (child.type === "variable_name") {
+      if (name !== null) return null;
+      name = child.text;
+      continue;
+    }
+    if (!EXPANSION_DELIMITERS.has(child.type)) return null;
+  }
+
+  return name;
+}

package/src/authority/approval-escalator.ts

@@ -26,11 +26,13 @@ import {
   type ForwardedPromptDisplay,
   type ForwardedSessionApproval,
   PERMISSION_FORWARDING_POLL_INTERVAL_MS,
-  PERMISSION_FORWARDING_TIMEOUT_MS,
+  PERMISSION_FORWARDING_SERVING_GRACE_MS,
   type PermissionForwardingLocation,
-  resolvePermissionForwardingTargetSessionId,
+  type PermissionForwardingTarget,
+  resolvePermissionForwardingTarget,
   SUBAGENT_PARENT_SESSION_ENV_CANDIDATES,
 } from "#src/authority/permission-forwarding";
+import type { ServingLookup } from "#src/authority/serving-registry";
 import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
 import { buildUiPrompt } from "#src/permission-ui-prompt";
 import type { DebugReviewLogger } from "#src/session-logger";
@@ -85,9 +87,30 @@ export interface ParentAuthorizerDeps {
   forwardingDir: string;
   /** In-process subagent session registry for forwarding target resolution. */
   registry?: SubagentSessionRegistry;
+  /** Whether the resolved target is draining its inbox (in-process targets only). */
+  serving: ServingLookup;
+  /** How long to wait for the target's answer, read live so config edits apply. */
+  getTimeoutMs: () => number;
   logger: DebugReviewLogger;
 }
 
+/**
+ * Deny because no authority ever ruled — the request was never delivered,
+ * never answered, or answered unreadably.
+ *
+ * `confirmationUnavailable` is what keeps this out of the "User denied …"
+ * message (#719): a user who was never asked denied nothing. `denialReason`
+ * names which path gave up, and the gate renders it to the model.
+ */
+function abandon(denialReason: string): PermissionPromptDecision {
+  return {
+    approved: false,
+    state: "denied",
+    confirmationUnavailable: true,
+    denialReason,
+  };
+}
+
 /**
  * Authorizer for a subagent session: escalate the ask up the tree to the
  * parent's authority.
@@ -103,6 +126,8 @@ export interface ParentAuthorizerDeps {
 export class ParentAuthorizer implements TerminalAuthorizer {
   private readonly forwardingDir: string;
   private readonly registry: SubagentSessionRegistry | undefined;
+  private readonly serving: ServingLookup;
+  private readonly getTimeoutMs: () => number;
   private readonly logger: DebugReviewLogger;
 
   constructor(
@@ -111,6 +136,8 @@ export class ParentAuthorizer implements TerminalAuthorizer {
   ) {
     this.forwardingDir = deps.forwardingDir;
     this.registry = deps.registry;
+    this.serving = deps.serving;
+    this.getTimeoutMs = deps.getTimeoutMs;
     this.logger = deps.logger;
   }
 
@@ -137,7 +164,7 @@ export class ParentAuthorizer implements TerminalAuthorizer {
     facts: ForwardedRequestFacts,
   ): Promise<PermissionPromptDecision> {
     const requesterSessionId = getSessionId(ctx);
-    const targetSessionId = resolvePermissionForwardingTargetSessionId({
+    const target = resolvePermissionForwardingTarget({
       hasUI: ctx.hasUI,
       // Invariant: selectAuthorizer only selects ParentAuthorizer for a
       // no-UI subagent context, so this is always true — no detection dep
@@ -149,7 +176,7 @@ export class ParentAuthorizer implements TerminalAuthorizer {
       registry: this.registry,
     });
 
-    if (!targetSessionId) {
+    if (!target) {
       logPermissionForwardingError(
         this.logger,
         `Permission forwarding target session could not be resolved. ` +
@@ -158,27 +185,31 @@ export class ParentAuthorizer implements TerminalAuthorizer {
           `ask its maintainer to set PI_SUBAGENT_PARENT_SESSION in the child process environment ` +
           `(see https://github.com/gotgenes/pi-permission-system/issues/143).`,
       );
-      return { approved: false, state: "denied" };
+      return abandon(
+        "Could not resolve a parent session to forward this permission request to",
+      );
     }
 
     const location = ensurePermissionForwardingLocation(
       this.logger,
       this.forwardingDir,
-      targetSessionId,
+      target.sessionId,
     );
     if (!location) {
       logPermissionForwardingError(
         this.logger,
-        `Permission forwarding is unavailable because session-scoped directories could not be prepared for '${targetSessionId}'`,
+        `Permission forwarding is unavailable because session-scoped directories could not be prepared for '${target.sessionId}'`,
+      );
+      return abandon(
+        `Permission forwarding directories could not be prepared for session '${target.sessionId}'`,
       );
-      return { approved: false, state: "denied" };
     }
 
     const request = this.buildForwardedRequest(
       ctx,
       facts,
       requesterSessionId,
-      targetSessionId,
+      target.sessionId,
     );
     const requestPath = join(location.requestsDir, `${request.id}.json`);
     const responsePath = join(location.responsesDir, `${request.id}.json`);
@@ -187,7 +218,7 @@ export class ParentAuthorizer implements TerminalAuthorizer {
       requestId: request.id,
       requesterAgentName: request.requesterAgentName,
       requesterSessionId: request.requesterSessionId,
-      targetSessionId,
+      targetSessionId: target.sessionId,
       requestPath,
       responsePath,
     });
@@ -200,7 +231,8 @@ export class ParentAuthorizer implements TerminalAuthorizer {
         `Failed to write forwarded permission request '${requestPath}'`,
         error,
       );
-      return { approved: false, state: "denied" };
+      cleanupPermissionForwardingLocationIfEmpty(this.logger, location);
+      return abandon("The forwarded permission request could not be written");
     }
 
     return this.pollForForwardedResponse(
@@ -208,6 +240,7 @@ export class ParentAuthorizer implements TerminalAuthorizer {
       request,
       requestPath,
       responsePath,
+      target,
     );
   }
 
@@ -262,9 +295,12 @@ export class ParentAuthorizer implements TerminalAuthorizer {
     request: ForwardedPermissionRequest,
     requestPath: string,
     responsePath: string,
+    target: PermissionForwardingTarget,
   ): Promise<PermissionPromptDecision> {
     const { id: requestId, requesterAgentName, targetSessionId } = request;
-    const deadline = Date.now() + PERMISSION_FORWARDING_TIMEOUT_MS;
+    const timeoutMs = this.getTimeoutMs();
+    const deadline = Date.now() + timeoutMs;
+    let unservedSince: number | null = null;
 
     while (Date.now() < deadline) {
       if (existsSync(responsePath)) {
@@ -281,18 +317,28 @@ export class ParentAuthorizer implements TerminalAuthorizer {
           targetSessionId,
           responsePath,
         });
-        safeDeleteFile(
-          this.logger,
-          responsePath,
-          "forwarded permission response",
+        this.discardRequest(location, requestPath, responsePath);
+        return (
+          response ??
+          abandon("The parent session's permission response could not be read")
         );
-        safeDeleteFile(
-          this.logger,
-          requestPath,
-          "forwarded permission request",
+      }
+
+      unservedSince = this.checkServingLiveness(target, unservedSince);
+      if (
+        unservedSince !== null &&
+        Date.now() - unservedSince >= PERMISSION_FORWARDING_SERVING_GRACE_MS
+      ) {
+        this.logger.review("forwarded_permission.no_serving_session", {
+          requestId,
+          requesterSessionId: request.requesterSessionId,
+          targetSessionId,
+          servingSessionIds: this.serving.servingIds(),
+        });
+        this.discardRequest(location, requestPath);
+        return abandon(
+          `Session '${target.sessionId}' is not serving forwarded permission requests`,
         );
-        cleanupPermissionForwardingLocationIfEmpty(this.logger, location);
-        return response ?? { approved: false, state: "denied" };
       }
 
       await sleep(PERMISSION_FORWARDING_POLL_INTERVAL_MS);
@@ -308,8 +354,51 @@ export class ParentAuthorizer implements TerminalAuthorizer {
       targetSessionId,
       responsePath,
     });
+    this.discardRequest(location, requestPath);
+    return abandon(
+      `Session '${target.sessionId}' did not answer within ${timeoutMs / 1000}s`,
+    );
+  }
+
+  /**
+   * Track how long the target has looked unserved, or `null` while it looks fine.
+   *
+   * Only an in-process target (`source: "registry"`) can be judged: a target in
+   * another process shares no serving registry with this one, so its absence
+   * from the registry says nothing (#719, follow-up in #721).
+   */
+  private checkServingLiveness(
+    target: PermissionForwardingTarget,
+    unservedSince: number | null,
+  ): number | null {
+    if (target.source !== "registry") {
+      return null;
+    }
+    if (this.serving.isServing(target.sessionId)) {
+      return null;
+    }
+    return unservedSince ?? Date.now();
+  }
+
+  /**
+   * Drop this exchange's files and, if nothing else is pending, its directories.
+   *
+   * Deleting the request is what makes an abandonment final: a request left
+   * behind would be answered by the parent long after the child gave up.
+   */
+  private discardRequest(
+    location: PermissionForwardingLocation,
+    requestPath: string,
+    responsePath?: string,
+  ): void {
+    if (responsePath) {
+      safeDeleteFile(
+        this.logger,
+        responsePath,
+        "forwarded permission response",
+      );
+    }
     safeDeleteFile(this.logger, requestPath, "forwarded permission request");
     cleanupPermissionForwardingLocationIfEmpty(this.logger, location);
-    return { approved: false, state: "denied" };
   }
 }

package/src/authority/authorizer.ts

@@ -4,6 +4,7 @@ import type {
   PromptPreferences,
   requestPermissionDecision,
 } from "#src/authority/permission-prompt-component";
+import type { ServingLookup } from "#src/authority/serving-registry";
 import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
 import type { PermissionEventBus } from "#src/permission-events";
 import type { AuthorizerLog, PermissionQuery } from "#src/service";
@@ -72,6 +73,10 @@ export interface AuthorizerSelectionDeps {
   forwardingDir: string;
   /** In-process subagent session registry for forwarding target resolution. */
   registry?: SubagentSessionRegistry;
+  /** Which sessions are draining a forwarded-permission inbox. */
+  servingRegistry: ServingLookup;
+  /** The forwarding timeout, read live so a config edit applies to the next ask. */
+  getForwardingTimeoutMs: () => number;
   logger: DebugReviewLogger;
 }
 
@@ -100,6 +105,8 @@ export function selectAuthorizer(
     return new ParentAuthorizer(ctx, {
       forwardingDir: deps.forwardingDir,
       registry: deps.registry,
+      serving: deps.servingRegistry,
+      getTimeoutMs: deps.getForwardingTimeoutMs,
       logger: deps.logger,
     });
   }

package/src/authority/forwarding-manager.ts

@@ -1,6 +1,9 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { DebugReviewLogger } from "#src/session-logger";
 import type { InboxProcessor } from "./forwarded-request-server";
+import { getSessionId } from "./forwarder-context";
 import { PERMISSION_FORWARDING_POLL_INTERVAL_MS } from "./permission-forwarding";
+import type { ServingAnnouncer } from "./serving-registry";
 import type { SubagentDetector } from "./subagent-detection";
 
 /**
@@ -12,6 +15,17 @@ export interface ForwardingController {
   stop(): void;
 }
 
+/** Constructor config for {@link ForwardingManager}. */
+export interface ForwardingManagerDeps {
+  /** Single owner of subagent detection; gates whether this session may serve. */
+  detection: SubagentDetector;
+  /** Drains this session's forwarded-permission inbox on each tick. */
+  forwarder: InboxProcessor;
+  /** Publishes that this session is draining its inbox, for forwarding children. */
+  serving: ServingAnnouncer;
+  logger: DebugReviewLogger;
+}
+
 /**
  * Encapsulates the forwarded-permission polling lifecycle.
  *
@@ -19,16 +33,20 @@ export interface ForwardingController {
  * lived as 3 mutable fields on `ExtensionRuntime`. Call `start(ctx)` on each
  * session event that may activate forwarding; call `stop()` on session
  * shutdown.
+ *
+ * While polling, it publishes the session id it polls to the `ServingAnnouncer`
+ * so a forwarding child can tell that someone is draining the inbox it wrote
+ * into — and the review log records that id, so a child forwarding to a
+ * *different* id is visible as a one-line diff against its
+ * `forwarded_permission.request_created` entry (#719).
  */
 export class ForwardingManager {
   private timer: NodeJS.Timeout | null = null;
   private context: ExtensionContext | null = null;
   private processing = false;
+  private servingSessionId: string | null = null;
 
-  constructor(
-    private readonly detection: SubagentDetector,
-    private readonly forwarder: InboxProcessor,
-  ) {}
+  constructor(private readonly deps: ForwardingManagerDeps) {}
 
   /**
    * Start polling if `ctx` has UI and is not a subagent execution context.
@@ -37,11 +55,12 @@ export class ForwardingManager {
    * Stops any existing poll when the context does not qualify for forwarding.
    */
   start(ctx: ExtensionContext): void {
-    if (!ctx.hasUI || this.detection.isSubagent(ctx)) {
+    if (!ctx.hasUI || this.deps.detection.isSubagent(ctx)) {
       this.stop();
       return;
     }
     this.context = ctx;
+    this.announceServing(getSessionId(ctx));
     if (this.timer) {
       return;
     }
@@ -50,7 +69,7 @@ export class ForwardingManager {
         return;
       }
       this.processing = true;
-      void this.forwarder.processInbox(this.context).finally(() => {
+      void this.deps.forwarder.processInbox(this.context).finally(() => {
         this.processing = false;
       });
     }, PERMISSION_FORWARDING_POLL_INTERVAL_MS);
@@ -62,7 +81,42 @@ export class ForwardingManager {
       clearInterval(this.timer);
       this.timer = null;
     }
+    this.withdrawServing();
     this.context = null;
     this.processing = false;
   }
+
+  // ── Private methods ────────────────────────────────────────────────
+
+  /**
+   * Publish `sessionId` as the served session, replacing any previous one.
+   *
+   * A no-op when the id is unchanged, since `start` runs on every
+   * `before_agent_start`, `input`, and `tool_call` — the announcement must not
+   * cost a log line per turn.
+   */
+  private announceServing(sessionId: string): void {
+    if (this.servingSessionId === sessionId) {
+      return;
+    }
+    this.withdrawServing();
+    this.servingSessionId = sessionId;
+    this.deps.serving.markServing(sessionId);
+    this.deps.logger.review("forwarded_permission.serving_started", {
+      sessionId,
+    });
+  }
+
+  /** Withdraw the published session, if any. */
+  private withdrawServing(): void {
+    const sessionId = this.servingSessionId;
+    if (sessionId === null) {
+      return;
+    }
+    this.servingSessionId = null;
+    this.deps.serving.clearServing(sessionId);
+    this.deps.logger.review("forwarded_permission.serving_stopped", {
+      sessionId,
+    });
+  }
 }

package/src/authority/permission-dialog.ts

@@ -16,11 +16,14 @@ export type PermissionPromptDecision = {
    */
   autoApproved?: true;
   /**
-   * True when no live authority was reachable and the DenyingAuthorizer denied
-   * this ask (a no-UI, non-subagent session). Consumed by deriveResolution (the
-   * decision-event resolution), the gate (block reason), and PermissionPrompter
-   * (review-entry resolution) to emit "confirmation_unavailable" rather than a
-   * plain user denial.
+   * True when no human ever ruled on this ask: either no live authority was
+   * reachable at all (`DenyingAuthorizer`, a no-UI non-subagent session) or the
+   * forwarding path gave up before reaching one (`ParentAuthorizer` — target
+   * unresolvable, request undeliverable, target not serving, or no answer
+   * within the timeout). Consumed by deriveResolution (the decision-event
+   * resolution), the gate (block reason), and PermissionPrompter (review-entry
+   * resolution) to emit "confirmation_unavailable" rather than a plain user
+   * denial — a user who was never asked denied nothing (#719).
    */
   confirmationUnavailable?: true;
 };

package/src/authority/permission-forwarding.ts

@@ -5,6 +5,17 @@ import type { SubagentSessionRegistry } from "./subagent-registry";
 
 export const PERMISSION_FORWARDING_POLL_INTERVAL_MS = 250;
 export const PERMISSION_FORWARDING_TIMEOUT_MS = 10 * 60 * 1000;
+/**
+ * How long an in-process forwarding target may go unserved before the child
+ * gives up on it — eight poll ticks.
+ *
+ * A window rather than a single check because `ForwardingManager` withdraws and
+ * re-announces across a session switch, and a request that arrives inside that
+ * gap is about to be picked up. Not configurable: the operator-facing knob is
+ * the overall timeout, and this only decides how fast a hopeless wait ends.
+ */
+export const PERMISSION_FORWARDING_SERVING_GRACE_MS =
+  8 * PERMISSION_FORWARDING_POLL_INTERVAL_MS;
 export const SUBAGENT_ENV_HINT_KEYS = [
   // pi-agent-router (original)
   "PI_IS_SUBAGENT",
@@ -204,7 +215,25 @@ export function createPermissionForwardingLocation(
   };
 }
 
-export function resolvePermissionForwardingTargetSessionId(options: {
+/**
+ * How a forwarding target was resolved.
+ *
+ * `"registry"` is the load-bearing value: it means the requester is an
+ * **in-process** child of `sessionId`, so the two share a `globalThis` and the
+ * requester may consult the serving-session registry to decide whether anyone
+ * is draining its inbox. `"env"` means the target lives in another process,
+ * where that signal is unavailable; `"self"` is the UI host owning its own
+ * forwarding location.
+ */
+export type PermissionForwardingTargetSource = "self" | "registry" | "env";
+
+/** The resolved forwarding target together with how it was found. */
+export interface PermissionForwardingTarget {
+  sessionId: string;
+  source: PermissionForwardingTargetSource;
+}
+
+export function resolvePermissionForwardingTarget(options: {
   hasUI: boolean;
   isSubagent: boolean;
   currentSessionId?: string | null;
@@ -213,9 +242,12 @@ export function resolvePermissionForwardingTargetSessionId(options: {
   sessionId?: string;
   /** In-process subagent session registry (checked before env vars). */
   registry?: SubagentSessionRegistry;
-}): string | null {
+}): PermissionForwardingTarget | null {
   if (options.hasUI) {
-    return normalizePermissionForwardingSessionId(options.currentSessionId);
+    const own = normalizePermissionForwardingSessionId(
+      options.currentSessionId,
+    );
+    return own === null ? null : { sessionId: own, source: "self" };
   }
 
   if (!options.isSubagent) {
@@ -228,14 +260,14 @@ export function resolvePermissionForwardingTargetSessionId(options: {
     const resolved = normalizePermissionForwardingSessionId(
       entry?.parentSessionId,
     );
-    if (resolved) return resolved;
+    if (resolved) return { sessionId: resolved, source: "registry" };
   }
 
   // 2. Env vars — process-based subagent extensions.
   const env = options.env ?? process.env;
   for (const key of SUBAGENT_PARENT_SESSION_ENV_CANDIDATES) {
     const resolved = normalizePermissionForwardingSessionId(env[key]);
-    if (resolved) return resolved;
+    if (resolved) return { sessionId: resolved, source: "env" };
   }
   return null;
 }

package/src/authority/serving-registry.ts

@@ -0,0 +1,108 @@
+/**
+ * serving-registry.ts — Which sessions are draining a forwarded-permission inbox.
+ *
+ * A session with a UI that is not itself a subagent polls its own
+ * `<forwardingDir>/sessions/<id>/requests/` directory (see `ForwardingManager`)
+ * and answers whatever a child forwards to it. Nothing else in the process can
+ * observe that, so a child whose parent is *not* polling has no way to tell
+ * "a human is being asked" from "nobody is home", and waits out the full
+ * forwarding timeout before denying (#719).
+ *
+ * This registry publishes that fact: the polling session marks itself while it
+ * polls, and a forwarding child checks whether its resolved target is marked.
+ *
+ * The single instance is stored on `globalThis` (via `Symbol.for()`) for the
+ * same reason `SubagentSessionRegistry` is: each session's `ResourceLoader`
+ * creates its own jiti instance and its own event bus, so the parent's
+ * permission-system instance and an in-process child's instance share no
+ * module state — only process globals. See `getServingSessionRegistry()`.
+ *
+ * The signal is meaningful only for an **in-process** child (one that resolved
+ * its target through `SubagentSessionRegistry`, i.e. a forwarding target with
+ * `source: "registry"`). A child in another process shares no `globalThis` with
+ * its parent and must not read anything into an absent mark.
+ */
+
+/** Process-global key for the shared registry slot. Exported for test teardown. */
+export const SERVING_SESSION_REGISTRY_KEY = Symbol.for(
+  "@gotgenes/pi-permission-system:serving-registry",
+);
+
+/**
+ * Announce-side seam: the polling session marks and clears itself.
+ *
+ * `ForwardingManager` depends on this rather than the concrete registry so it
+ * neither reads the store nor gains a query it has no business making (ISP).
+ */
+export interface ServingAnnouncer {
+  markServing(sessionId: string): void;
+  clearServing(sessionId: string): void;
+}
+
+/**
+ * Query-side seam: a forwarding child asks whether its target is draining.
+ *
+ * `servingIds()` exists for the diagnostic review entry a child writes when it
+ * abandons an unserved request — the mismatch between the id it forwarded to
+ * and the ids actually being served is the whole diagnosis.
+ */
+export interface ServingLookup {
+  isServing(sessionId: string): boolean;
+  servingIds(): readonly string[];
+}
+
+/**
+ * Registry of sessions currently draining a forwarded-permission inbox.
+ *
+ * A process-global singleton — obtain it via {@link getServingSessionRegistry},
+ * never `new` (see that accessor for why). Written exclusively by the owning
+ * session's `ForwardingManager`, keyed by that session's own id, so one
+ * session's shutdown cannot clear another's mark.
+ *
+ * A mark left behind by a session that died without `session_shutdown` makes a
+ * child wait out the full timeout instead of abandoning early — the same
+ * behavior as before this signal existed, which is the safe direction to fail.
+ */
+export class ServingSessionRegistry implements ServingAnnouncer, ServingLookup {
+  private readonly serving = new Set<string>();
+
+  /** Record that `sessionId` is polling its inbox. Idempotent. */
+  markServing(sessionId: string): void {
+    this.serving.add(sessionId);
+  }
+
+  /** Record that `sessionId` has stopped polling. No-op if unmarked. */
+  clearServing(sessionId: string): void {
+    this.serving.delete(sessionId);
+  }
+
+  /** Return `true` when `sessionId` is currently polling its inbox. */
+  isServing(sessionId: string): boolean {
+    return this.serving.has(sessionId);
+  }
+
+  /** Every currently-serving session id, for diagnostics. */
+  servingIds(): readonly string[] {
+    return [...this.serving];
+  }
+}
+
+/**
+ * Return the process-global ServingSessionRegistry, creating it on first call.
+ *
+ * Intentionally has no teardown hook: a child's `session_shutdown` must not be
+ * able to wipe the parent's mark. Entries are added and removed exclusively by
+ * the owning session's `ForwardingManager`.
+ */
+export function getServingSessionRegistry(): ServingSessionRegistry {
+  const store = globalThis as Record<symbol, unknown>;
+  const existing = store[SERVING_SESSION_REGISTRY_KEY] as
+    | ServingSessionRegistry
+    | undefined;
+  if (existing) {
+    return existing;
+  }
+  const registry = new ServingSessionRegistry();
+  store[SERVING_SESSION_REGISTRY_KEY] = registry;
+  return registry;
+}

package/src/config-loader.ts

@@ -221,6 +221,7 @@ export function mergeUnifiedConfigs(
 
   // Number scalars: override replaces base when defined
   for (const key of [
+    "forwardingTimeoutMs",
     "toolInputPreviewMaxLength",
     "toolTextSummaryMaxLength",
   ] as const) {

package/src/config-schema.ts

@@ -187,6 +187,13 @@ export const unifiedConfigSchema = z
         "Require a confirming second press of a decision hotkey (`y`/`s`/`n`/`r`) in the inline permission dialog before it commits — the first press arms the action and shows a `Press y again to approve.` hint.\n\nApplies to interactive **TUI** sessions only; the non-TUI (RPC/frontend) prompt keeps its single-select flow. Set to `false` to commit decisions on the first hotkey press.",
       default: true,
     }),
+    forwardingTimeoutMs: z.number().int().min(1).optional().meta({
+      description:
+        "How long a subagent waits for the parent session to answer a forwarded permission request, in milliseconds. Omit to use the default (600000, ten minutes).",
+      markdownDescription:
+        "How long a subagent waits for the parent session to answer a forwarded permission request, in milliseconds.\n\nOmit to use the default (`600000`, ten minutes). A child whose in-process parent is not draining its inbox at all gives up in a couple of seconds regardless of this value, so lower it only to bound how long you are willing to leave an *unanswered* prompt pending.",
+      default: 600000,
+    }),
     toolInputPreviewMaxLength: z.number().int().min(1).optional().meta({
       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.",

package/src/denial-messages.ts

@@ -76,9 +76,19 @@ export function formatDenyReason(ctx: DenialContext): string {
   return `${EXTENSION_TAG} ${buildDenyBody(ctx)}`;
 }
 
-/** Format the block reason when no interactive UI is available to prompt. */
-export function formatUnavailableReason(ctx: DenialContext): string {
-  return `${EXTENSION_TAG} ${buildUnavailableBody(ctx)}`;
+/**
+ * Format the block reason when no live authority could answer the ask.
+ *
+ * `denialReason` is optional because the plain no-UI case has nothing to add;
+ * an authority that abandoned for a specific reason (a forwarding target that
+ * is not serving, a request that could not be written) supplies one, and the
+ * model sees it (#719).
+ */
+export function formatUnavailableReason(
+  ctx: DenialContext,
+  denialReason?: string,
+): string {
+  return `${EXTENSION_TAG} ${buildUnavailableBody(ctx, denialReason)}`;
 }
 
 /** Format the block reason when the user denies at an interactive prompt. */
@@ -187,7 +197,14 @@ export function matchQualifier(
   return parts.length > 0 ? `(${parts.join(", ")})` : "";
 }
 
-function buildUnavailableBody(ctx: DenialContext): string {
+function buildUnavailableBody(
+  ctx: DenialContext,
+  denialReason?: string,
+): string {
+  return `${buildUnavailableSentence(ctx)}${reasonSuffix(denialReason)}`;
+}
+
+function buildUnavailableSentence(ctx: DenialContext): string {
   switch (ctx.kind) {
     case "tool": {
       const { check } = ctx;

package/src/expand-home.ts

@@ -2,27 +2,41 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 /**
- * Expand `~` and `$HOME` prefixes in a pattern to the OS home directory.
+ * The spellings of the home directory this package resolves, in every pattern
+ * and path literal.
  *
- * Supported forms:
- * - `~`          → `homedir()`
- * - `~/path`     → `homedir()/path`
- * - `~\path`     → `homedir()\path` (Windows)
- * - `$HOME`      → `homedir()`
- * - `$HOME/path` → `homedir()/path`
- * - `$HOME\path` → `homedir()\path` (Windows)
+ * `$HOME` and `${HOME}` are the two spellings of the same shell variable and
+ * must stay interchangeable: a rule keyed on one form has to match a path
+ * written in the other, and the bash path projection classifies a token by the
+ * shape it has *after* this expansion (#694).
+ */
+const HOME_PREFIXES = ["~", "$HOME", "${HOME}"] as const;
+
+/**
+ * Expand a home-directory prefix in a pattern or path value to the OS home
+ * directory.
+ *
+ * A prefix is recognized only when it stands alone or is followed by a path
+ * separator, so a longer name (`~username`, `$HOMEDIR`, `${HOMEDIR}`) and a
+ * braced parameter expansion carrying an operator (`${HOME:-/tmp}`,
+ * `${HOME%/*}`) are both left untouched.
+ *
+ * Supported forms, for each prefix in {@link HOME_PREFIXES}:
+ * - `<prefix>`       → `homedir()`
+ * - `<prefix>/path`  → `homedir()/path`
+ * - `<prefix>\path`  → `homedir()\path` (Windows)
  *
  * All other patterns are returned unchanged.
  */
 export function expandHomePath(pattern: string): string {
-  if (pattern === "~" || pattern === "$HOME") {
-    return homedir();
-  }
-  if (pattern.startsWith("~/") || pattern.startsWith("~\\")) {
-    return join(homedir(), pattern.slice(2));
-  }
-  if (pattern.startsWith("$HOME/") || pattern.startsWith("$HOME\\")) {
-    return join(homedir(), pattern.slice(6));
+  for (const prefix of HOME_PREFIXES) {
+    if (pattern === prefix) return homedir();
+    if (!pattern.startsWith(prefix)) continue;
+
+    const rest = pattern.slice(prefix.length);
+    if (rest.startsWith("/") || rest.startsWith("\\")) {
+      return join(homedir(), rest.slice(1));
+    }
   }
   return pattern;
 }

package/src/extension-config.ts

@@ -20,6 +20,8 @@ export interface PermissionSystemExtensionConfig {
   doublePressToConfirm: boolean;
   /** Additional directories to auto-allow for reads as Pi infrastructure. */
   piInfrastructureReadPaths?: string[];
+  /** How long a subagent waits for the parent's answer to a forwarded ask, in ms. Defaults to 600000. */
+  forwardingTimeoutMs?: number;
   /** Max length of the inline-JSON input preview shown in permission prompts. Defaults to 200. */
   toolInputPreviewMaxLength?: number;
   /** Max length of inline pattern/path summaries (grep/find/ls) in permission prompts. Defaults to 80. */
@@ -71,6 +73,9 @@ export function normalizePermissionSystemConfig(
   if (raw.piInfrastructureReadPaths !== undefined) {
     result.piInfrastructureReadPaths = raw.piInfrastructureReadPaths;
   }
+  if (raw.forwardingTimeoutMs !== undefined) {
+    result.forwardingTimeoutMs = raw.forwardingTimeoutMs;
+  }
   if (raw.toolInputPreviewMaxLength !== undefined) {
     result.toolInputPreviewMaxLength = raw.toolInputPreviewMaxLength;
   }

package/src/handlers/gates/runner.ts

@@ -133,7 +133,11 @@ export class GateRunner {
     // Construct messages from the centralized formatter.
     const messages = {
       denyReason: formatDenyReason(descriptor.denialContext),
-      unavailableReason: formatUnavailableReason(descriptor.denialContext),
+      unavailableReason: (decision: PermissionPromptDecision) =>
+        formatUnavailableReason(
+          descriptor.denialContext,
+          decision.denialReason,
+        ),
       userDeniedReason: (decision: PermissionPromptDecision) =>
         formatUserDeniedReason(descriptor.denialContext, decision.denialReason),
     };

package/src/index.ts

@@ -9,8 +9,10 @@ import {
   type ServingPolicy,
 } from "./authority/forwarded-request-server";
 import { ForwardingManager } from "./authority/forwarding-manager";
+import { PERMISSION_FORWARDING_TIMEOUT_MS } from "./authority/permission-forwarding";
 import { requestPermissionDecision } from "./authority/permission-prompt-component";
 import { PermissionPrompter } from "./authority/permission-prompter";
+import { getServingSessionRegistry } from "./authority/serving-registry";
 import { SubagentDetection } from "./authority/subagent-detection";
 import { subscribeSubagentLifecycle } from "./authority/subagent-lifecycle-events";
 import { getSubagentSessionRegistry } from "./authority/subagent-registry";
@@ -55,6 +57,9 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const hostFlavor = pathFlavorForPlatform(process.platform);
   const sessionRules = new SessionRules();
   const subagentRegistry = getSubagentSessionRegistry();
+  // Process-global, like subagentRegistry: an in-process child reads it from a
+  // separate jiti instance to learn whether its parent is draining its inbox.
+  const servingRegistry = getServingSessionRegistry();
   // Single owner of subagent detection, shared across every consumer instead of
   // threading the (subagentSessionsDir, platform, registry) triple into each.
   const subagentDetection = new SubagentDetection({
@@ -111,6 +116,10 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     requestPermissionDecision,
     forwardingDir: paths.forwardingDir,
     registry: subagentRegistry,
+    servingRegistry,
+    getForwardingTimeoutMs: () =>
+      configStore.current().forwardingTimeoutMs ??
+      PERMISSION_FORWARDING_TIMEOUT_MS,
     logger,
     prompter,
     // The published service is the narrow, session-scoped PermissionQuery a
@@ -160,7 +169,12 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
 
   session = new PermissionSession(
     paths,
-    new ForwardingManager(subagentDetection, requestServer),
+    new ForwardingManager({
+      detection: subagentDetection,
+      forwarder: requestServer,
+      serving: servingRegistry,
+      logger,
+    }),
     permissionManager,
     sessionRules,
     configStore,

package/src/permission-gate.ts

@@ -33,7 +33,7 @@ export interface PermissionGateParams {
   /** Message strings/factories for each outcome. */
   messages: {
     denyReason: string;
-    unavailableReason: string;
+    unavailableReason: (decision: PermissionPromptDecision) => string;
     userDeniedReason: (decision: PermissionPromptDecision) => string;
   };
 }
@@ -65,7 +65,7 @@ export async function applyPermissionGate(
       return {
         action: "block",
         reason: decision.confirmationUnavailable
-          ? messages.unavailableReason
+          ? messages.unavailableReason(decision)
           : messages.userDeniedReason(decision),
       };
     }