@gotgenes/pi-permission-system 32.0.3 → 32.0.5

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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).
 
+## [32.0.5](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v32.0.4...pi-permission-system-v32.0.5) (2026-09-16)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** tell the operator when a configured chain link is missing ([3662541](https://github.com/gotgenes/pi-packages/commit/3662541d4ebc555d54faf2934085d22b36ee618e)), closes [#861](https://github.com/gotgenes/pi-packages/issues/861)
+
+### Documentation
+
+* **pi-permission-system:** record the unregistered-link warning ([f70b1e3](https://github.com/gotgenes/pi-packages/commit/f70b1e3ce52a38744da2a07880878efb61dfae00)), closes [#861](https://github.com/gotgenes/pi-packages/issues/861)
+* **pi-permission-system:** state the resolved skip in the boundary test comment ([9cd18f1](https://github.com/gotgenes/pi-packages/commit/9cd18f1ef6bd8f9dbabf6fc6ce6b9dfa58d64764)), closes [#861](https://github.com/gotgenes/pi-packages/issues/861)
+
+## [32.0.4](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v32.0.3...pi-permission-system-v32.0.4) (2026-09-16)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** evaluate bash rules against a command a partial parse dropped ([28cedc4](https://github.com/gotgenes/pi-packages/commit/28cedc45dd4a11ee9189f41ee661a051d2b13936)), closes [#875](https://github.com/gotgenes/pi-packages/issues/875)
+* **pi-permission-system:** gate the paths a command dropped by a partial parse reads ([6f1d032](https://github.com/gotgenes/pi-packages/commit/6f1d0328f8151da8716641f0ee0c25341699cd75)), closes [#875](https://github.com/gotgenes/pi-packages/issues/875)
+* **pi-permission-system:** keep the whole-command deny reachable when a salvage recovers the only units ([ab91a66](https://github.com/gotgenes/pi-packages/commit/ab91a660eafb879a3370104cb6f68353041a7cbb)), closes [#875](https://github.com/gotgenes/pi-packages/issues/875)
+
+### Documentation
+
+* **pi-permission-system:** record the salvage of a bash command a partial parse dropped ([17a3684](https://github.com/gotgenes/pi-packages/commit/17a3684f182467c19e1ca56664e1adf900980f11))
+
 ## [32.0.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v32.0.2...pi-permission-system-v32.0.3) (2026-09-15)
 
 

package/README.md

@@ -19,7 +19,7 @@ Permission enforcement extension for the [Pi](https://pi.mariozechner.at/) codin
 - **Gates MCP and skill access** at server, tool, and skill-name granularity
 - **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once, matching both the path as referenced and its symlink-resolved form so a deny cannot be evaded through a symlink alias
 - **Guards external paths** — prompts before file tools or bash commands reach outside `cwd`
-- **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry and a matching `permissions:decision` broadcast), and a bash command the parser could not resolve, in whole or in part — or an indirection wrapper that hides the gated command (`bash -c`/`eval`, `sudo`, `env`, `xargs`, `find -exec`, …) — prompts (`ask`) rather than passing silently, unless the wrapped command is a pure reader whose direction is provable whatever it is fed (`xargs grep -l foo`)
+- **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry and a matching `permissions:decision` broadcast), and a bash command the parser could not resolve, in whole or in part — or an indirection wrapper that hides the gated command (`bash -c`/`eval`, `sudo`, `env`, `xargs`, `find -exec`, …) — prompts (`ask`) rather than passing silently, unless the wrapped command is a pure reader whose direction is provable whatever it is fed (`xargs grep -l foo`); where a partial parse failure's own region re-parses cleanly on its own, the commands and paths it holds are recovered and gated rather than merely prompted for
 - **Forwards prompts from subagents** — `ask` policies work even in non-UI execution contexts
 - **Broadcasts UI prompt events** — `permissions:ui_prompt` fires only when the permission system is about to invoke the active user-facing permission UI, and every prompt it announces — including one forwarded up from a subagent — is answered by a `permissions:decision` on the same bus
 - **Native [`@gotgenes/pi-subagents`](https://github.com/gotgenes/pi-subagents) integration** — in-process child sessions register with the permission system automatically, enabling per-agent policy enforcement and `ask`-state forwarding to the parent UI without configuration

package/docs/configuration.md

@@ -226,9 +226,11 @@ Three invariants govern the chain:
 
 1. **Config order wins, never registration order.**
    The order in `authorizerChain` — not the order extensions happen to register in — fixes the security-relevant chain order.
-2. **A missing link is skipped fail-safe.**
-   A name with no registered link is skipped with a logged warning; the `ask` still reaches the terminal.
+2. **A missing link is skipped fail-safe, and you are told.**
+   A name with no registered link is skipped; the `ask` still reaches the terminal.
    Absence of a judge means *more* prompting, never less.
+   Because you asked for that judge and did not get it, the skip also raises a warning naming the link — once per session per name, beside the per-ask review record.
+   Three things leave the identical absence, so the warning names the likeliest and admits the others: the extension providing the link is not loaded in this session (a subagent child's `excludedExtensionPackages` does this), it failed to load, or it declined to register because it has no configuration of its own.
 3. **Registration alone grants no authority.**
    Installing a judge extension gives it nothing; a link decides nothing until you name it here (opt-in activation).
 
@@ -244,12 +246,12 @@ The subagent itself resolves no links (an extension cannot register one in a chi
 
 Three review-log records make the chain observable, all keyed by the ask's `requestId`:
 
-| Record                               | Meaning                                                                                                  |
-| ------------------------------------ | -------------------------------------------------------------------------------------------------------- |
-| `authorizer_chain_resolved`          | the links consulted on this ask, recorded before they run — a link that defers otherwise leaves no trace |
-| `authorizer_chain_delegated`         | the ask came from a relaying subagent node; the named links were deliberately not run here               |
-| `authorizer_chain_unregistered_link` | a configured name had no registered link — a real misconfiguration; the ask still reaches the terminal   |
-| `authorizer_link_vacant`             | a link was registered on a relaying node, which runs no chain — accepted and recorded, never consulted   |
+| Record                               | Meaning                                                                                                                                                |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `authorizer_chain_resolved`          | the links consulted on this ask, recorded before they run — a link that defers otherwise leaves no trace                                               |
+| `authorizer_chain_delegated`         | the ask came from a relaying subagent node; the named links were deliberately not run here                                                             |
+| `authorizer_chain_unregistered_link` | a configured name had no registered link — a real misconfiguration; the ask still reaches the terminal, and the first skip of that name also warns you |
+| `authorizer_link_vacant`             | a link was registered on a relaying node, which runs no chain — accepted and recorded, never consulted                                                 |
 
 Extension authors: register a link from a `permissions:ready` handler via `getPermissionsService(sessionId).registerAuthorizer(name, authorize)`, taking `sessionId` from that event's payload; 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.
@@ -429,11 +431,13 @@ The bash gate fails closed: when in doubt it blocks or prompts, never silently a
 - If the permission gate throws an internal error (for example a transient tree-sitter parser-init failure), the tool call is **blocked** rather than passed ungated, and a `gate_error` entry is written to the review log naming the failure.
 - A non-empty command that cannot be parsed into command units resolves to **`ask`** (the synthetic `<unparseable-bash-command>` pattern in the review log) instead of falling through to a permissive top-level `*`.
   A `deny` rule covering the whole command still denies outright — the synthetic `ask` never masks a hard deny into an approvable prompt.
+  That whole-command check runs whenever the parse itself matched nothing, including when the recovery below went on to recover a command from the wreckage, so a rule naming the command in context (`"* rm -rf *"`) is still consulted.
   An empty, whitespace-only, or comment-only command has nothing to gate and is resolved normally.
 - A command the parser could only *partly* resolve is floored the same way (the synthetic `<unparsed-bash-subtree>` pattern in the review log).
   Recovered structure is not evidence of what runs, so any command unit at or beneath the statement holding the unresolved region has its `allow` clamped up to `ask`; an explicit `deny` or `ask` on that unit still decides.
-  The prompt names the **whole** command rather than the unit, because a partial failure can drop a command from the parse entirely and the fragment that did parse is not what you need to see.
+  The prompt names the **whole** command rather than the unit, because the fragment that did parse is not what you need to see.
   A statement beside the failed one keeps its own rule.
+  Where the unresolved region's own text parses cleanly on its own, the commands and paths inside it are recovered and gated too, so a `deny` covering one of them still denies rather than prompting — a region whose own text does not re-parse is left to the floor, since error recovery invents the structure inside one and inventions do not re-parse.
   Most such commands are simply malformed, and the shell would refuse them too — but not all: `git commit -F - <<'MSG' 2>&1 | tail -4` is valid bash that `tree-sitter-bash` cannot parse, because a heredoc redirect combined with `2>&1` **and** a pipe defeats the grammar though each pairing alone is fine.
 - An opaque-payload wrapper — `bash`/`sh`/`dash`/`zsh`/`ksh` invoked with `-c`, or `eval` — carries its inner program in a quoted argument that is not re-parsed, so its decision is floored to at least **`ask`** (the synthetic `<opaque-bash-wrapper>` pattern in the review log).
   An `allow` (including a permissive top-level `*`) is clamped up to `ask`, while an explicit `deny` rule on the wrapper still denies.

package/package.json

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

package/src/access-intent/bash/bash-path-resolver.ts

@@ -127,13 +127,31 @@ export class BashPathResolver {
    * itself is added to the external paths when it resolves outside the cwd.
    * Containment is always measured against the session cwd baked into the
    * normalizer, so a `workdir` outside the cwd does not widen the sandbox.
+   *
+   * `salvagedRoots` are regions the primary parse could not resolve, re-parsed
+   * cleanly on their own (`unresolved-salvage.ts`, #875). Their candidates are
+   * collected into the same array before projection runs, so a path both a
+   * salvaged region and the primary parse name folds to one entry rather than
+   * showing twice in the prompt. Each is walked under the **unknown** base: a
+   * fragment carries no record of the `cd` in force where it sat, and
+   * resolving `cat rel.txt` against the session cwd after `cd /outside` would
+   * name a different file than the one that runs — a rule for that other path
+   * could then allow this access. #393's unknown base declines the claim
+   * instead, keeping an absolute token literal-only and unconditionally
+   * external while a relative one is not projected at all.
    */
-  resolve(rootNode: TSNode): ResolvedBashPaths {
+  resolve(
+    rootNode: TSNode,
+    salvagedRoots: readonly TSNode[] = [],
+  ): ResolvedBashPaths {
     const initialBase =
       this.workdir === undefined
         ? CWD_BASE
         : this.deriveBaseFromCdTarget(CWD_BASE, this.workdir);
     const candidates = this.collectPathCandidates(rootNode, initialBase);
+    for (const salvaged of salvagedRoots) {
+      this.walkForCandidates(salvaged, UNKNOWN_BASE, candidates);
+    }
     return {
       externalAccesses: this.withWorkdirExternal(
         this.projectExternalPaths(candidates),

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

@@ -57,6 +57,19 @@ export interface BashCommand {
    * 0013 §10's fail-closed base case (#840).
    */
   readonly parseUnresolved?: true;
+  /**
+   * Set when this unit came from a region re-parsed out of a subtree the
+   * primary parse could not resolve, rather than from the primary parse
+   * itself (#875).
+   *
+   * Narrower than {@link parseUnresolved}, which a primary unit also carries
+   * when its enclosing statement failed. The verdict fold needs the
+   * distinction to tell whether the *primary* parse found anything: when it
+   * found nothing, the whole command string is the only surface an explicit
+   * `deny` can reach (#452), and salvaging a unit must not make that check
+   * unreachable.
+   */
+  readonly salvaged?: true;
 }
 
 /**
@@ -83,12 +96,34 @@ interface UnitScope {
    * resolve, so every unit beneath it is floored rather than trusted (#840).
    */
   readonly parseUnresolved: boolean;
+  /**
+   * True when the walk started from a salvaged region rather than the primary
+   * parse tree (#875). Relayed unchanged, including into nested executions:
+   * everything found inside a salvaged region is salvaged.
+   */
+  readonly salvaged: boolean;
 }
 
 /** A top-level command in the current shell, writing no file, fully parsed. */
 const TOP_LEVEL_SCOPE: UnitScope = {
   writesViaRedirect: false,
   parseUnresolved: false,
+  salvaged: false,
+};
+
+/**
+ * The scope a salvaged region's own units run under.
+ *
+ * Marked unresolved because the region reached the salvage only by failing in
+ * the primary parse, so the verdict fold floors what it recovers rather than
+ * trusting it. `writesViaRedirect` starts false for the same reason
+ * {@link collectHostedCommands} resets it: a redirect established outside the
+ * region is the enclosing statement's, not the region's.
+ */
+const SALVAGED_SCOPE: UnitScope = {
+  writesViaRedirect: false,
+  parseUnresolved: true,
+  salvaged: true,
 };
 
 // ── Node-type vocabulary ─────────────────────────────────────────────────────
@@ -212,6 +247,22 @@ export function collectCommands(node: TSNode): BashCommand[] {
   return out;
 }
 
+/**
+ * Enumerate the command units of a region the primary parse could not resolve,
+ * re-parsed cleanly on its own (`unresolved-salvage.ts`, #875).
+ *
+ * The same walk as {@link collectCommands}, differing only in the scope it
+ * starts from: every unit is marked {@link BashCommand.parseUnresolved}, so a
+ * command the primary parse dropped is matched against the bash rules — an
+ * explicit `deny` fires — while its `allow` is still floored to `ask` by the
+ * verdict fold (#840).
+ */
+export function collectSalvagedCommands(node: TSNode): BashCommand[] {
+  const out: BashCommand[] = [];
+  collectCommandsInto(node, SALVAGED_SCOPE, out);
+  return out;
+}
+
 function collectCommandsInto(
   node: TSNode,
   inherited: UnitScope,
@@ -228,7 +279,7 @@ function collectCommandsInto(
     out.push(makeCommandUnit(node, scope));
     // A command's text already contains any substitution; descend its subtree
     // to ALSO emit the inner commands of command/process substitutions.
-    collectHostedCommands(node, out);
+    collectHostedCommands(node, scope, out);
     return;
   }
 
@@ -240,7 +291,7 @@ function collectCommandsInto(
   if (EXECUTION_HOST_TYPES.has(node.type)) {
     // Not a command itself, but its subtree can host one that really runs
     // (`> $(rm x)`, `< <(rm c)`). Emit only what it hosts (#741).
-    collectHostedCommands(node, out);
+    collectHostedCommands(node, scope, out);
     return;
   }
 
@@ -281,7 +332,7 @@ function collectCommandsInto(
   // really run (`local x=$(rm y)`, `[[ $(rm x) ]]`), so those are enumerated
   // in addition to the statement (#742).
   out.push(makeUnit(node.text, scope));
-  collectHostedCommands(node, out);
+  collectHostedCommands(node, scope, out);
 }
 
 /**
@@ -328,9 +379,10 @@ function makeUnit(
     executedUnit === undefined ? flagged : { ...flagged, executedUnit };
   const exempted =
     floorExemption === undefined ? named : { ...named, floorExemption };
-  return scope.parseUnresolved
+  const marked: BashCommand = scope.parseUnresolved
     ? { ...exempted, parseUnresolved: true }
     : exempted;
+  return scope.salvaged ? { ...marked, salvaged: true } : marked;
 }
 
 /**
@@ -450,7 +502,7 @@ function descendStatementChildren(
     const child = node.child(i);
     if (!child?.isNamed) continue;
     if (STATEMENT_TYPES.has(child.type)) collectCommandsInto(child, scope, out);
-    else collectHostedCommands(child, out);
+    else collectHostedCommands(child, scope, out);
   }
 }
 
@@ -465,7 +517,11 @@ function descendStatementChildren(
  * `node` may be a context outright or merely host one, so the traversal is the
  * root-inclusive `forEachExecutionIn`.
  */
-function collectHostedCommands(node: TSNode, out: BashCommand[]): void {
+function collectHostedCommands(
+  node: TSNode,
+  scope: UnitScope,
+  out: BashCommand[],
+): void {
   forEachExecutionIn(node, (contextNode, context) => {
     // A nested execution starts fresh: an enclosing statement's redirect is
     // that statement's, not the substitution's, exactly as #807 attributes a
@@ -475,7 +531,12 @@ function collectHostedCommands(node: TSNode, out: BashCommand[]): void {
     // units carry the mark regardless, so the verdict is unchanged (#840).
     descendCommandChildren(
       contextNode,
-      { context, writesViaRedirect: false, parseUnresolved: false },
+      {
+        context,
+        writesViaRedirect: false,
+        parseUnresolved: false,
+        salvaged: scope.salvaged,
+      },
       out,
     );
   });

package/src/access-intent/bash/parser.ts

@@ -79,16 +79,32 @@ export function parseUnresolvedAt(node: TSNode): boolean {
  * fact about redirects, not about statements: a statement whose *predecessor*
  * failed is not itself unparsed, and borrowing the wider predicate here would
  * condemn every statement following a failed one.
+ *
+ * `unresolved-salvage.ts` asks the same question twice over: to locate the
+ * innermost region worth re-parsing, and to refuse the re-parse's own result
+ * when it failed too (#875).
  */
 export function parseUnresolvedWithin(node: TSNode): boolean {
   return node.hasError;
 }
 
 /**
- * Minimal subset of web-tree-sitter's Parser used by this module.
+ * The one parse capability a consumer needs to re-parse a fragment of a
+ * command on its own.
+ *
+ * Narrower than {@link TSParser} on purpose: that interface also carries the
+ * parser's own `delete()`, which destroys the process-wide memoized parser for
+ * every later command. A consumer re-parsing a fragment has no business
+ * holding that, so it takes this instead (`unresolved-salvage.ts`, #875).
  */
-interface TSParser {
+export interface BashReparser {
   parse(input: string): { rootNode: TSNode; delete(): void } | null;
+}
+
+/**
+ * Minimal subset of web-tree-sitter's Parser used by this module.
+ */
+interface TSParser extends BashReparser {
   delete(): void;
 }
 

package/src/access-intent/bash/program.ts

@@ -4,8 +4,13 @@ import {
   BashPathResolver,
   type BashPathRuleCandidate,
 } from "./bash-path-resolver";
-import { type BashCommand, collectCommands } from "./command-enumeration";
+import {
+  type BashCommand,
+  collectCommands,
+  collectSalvagedCommands,
+} from "./command-enumeration";
 import { getParser } from "./parser";
+import { withSalvagedRoots } from "./unresolved-salvage";
 
 export type { BashCommand, BashExternalPath, BashPathRuleCandidate };
 
@@ -56,16 +61,21 @@ export class BashProgram {
     if (!tree) return new BashProgram(command, [], [], []);
 
     try {
-      const { externalAccesses, ruleCandidates } = new BashPathResolver(
-        normalizer,
-        options?.workdir,
-      ).resolve(tree.rootNode);
-      return new BashProgram(
-        command,
-        collectCommands(tree.rootNode),
-        externalAccesses,
-        ruleCandidates,
-      );
+      return withSalvagedRoots(tree.rootNode, parser, (salvaged) => {
+        const { externalAccesses, ruleCandidates } = new BashPathResolver(
+          normalizer,
+          options?.workdir,
+        ).resolve(tree.rootNode, salvaged);
+        return new BashProgram(
+          command,
+          [
+            ...collectCommands(tree.rootNode),
+            ...salvaged.flatMap(collectSalvagedCommands),
+          ],
+          externalAccesses,
+          ruleCandidates,
+        );
+      });
     } finally {
       tree.delete();
     }

package/src/access-intent/bash/sync-commands.ts

@@ -1,5 +1,10 @@
-import { type BashCommand, collectCommands } from "./command-enumeration";
+import {
+  type BashCommand,
+  collectCommands,
+  collectSalvagedCommands,
+} from "./command-enumeration";
 import { getWarmBashParser } from "./parser";
+import { withSalvagedRoots } from "./unresolved-salvage";
 
 /**
  * Synchronously enumerate the command-pattern units of a bash command using the
@@ -21,7 +26,10 @@ export function parseBashCommandsSync(command: string): BashCommand[] | null {
   const tree = parser.parse(command);
   if (!tree) return [];
   try {
-    return collectCommands(tree.rootNode);
+    return withSalvagedRoots(tree.rootNode, parser, (salvaged) => [
+      ...collectCommands(tree.rootNode),
+      ...salvaged.flatMap(collectSalvagedCommands),
+    ]);
   } finally {
     tree.delete();
   }

package/src/access-intent/bash/unresolved-salvage.ts

@@ -0,0 +1,97 @@
+import {
+  type BashReparser,
+  parseUnresolvedWithin,
+  type TSNode,
+} from "./parser";
+
+/**
+ * Run `use` over the roots of every region the primary parse could not resolve
+ * but which re-parses cleanly on its own, then delete the trees it created.
+ *
+ * `tree-sitter-bash` 0.25.1 cannot parse a heredoc redirect combined with
+ * `2>&1` **and** a pipe, though each pairing alone is fine. Its recovery hangs
+ * an `ERROR` node holding only the `|` under `heredoc_redirect → file_redirect`
+ * and leaves the piped command's words as plain siblings of it — and
+ * `heredoc_redirect` is an execution host, descended for the substitutions it
+ * may carry and never read for text. So `git commit -F - <<'MSG' 2>&1 | rm -rf
+ * /tmp/x` enumerates `git commit -F` and nothing else, and a configured
+ * `bash: {"rm -rf *": "deny"}` is never evaluated against a command that
+ * really runs (#875).
+ *
+ * Re-parsing the dropped region's own source text recovers it, because the
+ * grammar gap is in the *combination* — `2>&1 | rm -rf /tmp/x` parses
+ * perfectly on its own.
+ *
+ * The roots are handed to a callback rather than returned because each belongs
+ * to a tree that must outlive its use and be released afterwards, exactly as
+ * the primary parse's caller already does for its own tree.
+ *
+ * Salvaging is purely additive: a caller enumerates these roots *in addition
+ * to* the primary one, so the result can only ever be more restrictive.
+ */
+export function withSalvagedRoots<T>(
+  primary: TSNode,
+  reparser: BashReparser,
+  use: (salvaged: readonly TSNode[]) => T,
+): T {
+  const trees: { rootNode: TSNode; delete(): void }[] = [];
+  try {
+    for (const candidate of unresolvedRegionsWithin(primary)) {
+      const tree = reparser.parse(candidate.text);
+      if (!tree) continue;
+      // The whole safety argument: tree-sitter's error recovery *invents* the
+      // structure inside an unresolved region (#742), and invented structure
+      // does not re-parse. Without this check `cat <> rw.txt` salvages a
+      // command unit whose text is `">"`, matched against the bash rules like
+      // any real command.
+      if (parseUnresolvedWithin(tree.rootNode)) {
+        tree.delete();
+        continue;
+      }
+      trees.push(tree);
+    }
+    return use(trees.map(({ rootNode }) => rootNode));
+  } finally {
+    for (const tree of trees) tree.delete();
+  }
+}
+
+/**
+ * The innermost nodes beneath `root` whose subtree the parser could not
+ * resolve, in source order.
+ *
+ * Three exclusions shape the answer.
+ *
+ * An `ERROR` node is never a candidate and is never descended in search of
+ * one: its interior is recovery's invention rather than anything observed
+ * (#742), so the region worth re-parsing is the node that *holds* it.
+ *
+ * Only the innermost such node is offered. An enclosing statement reports the
+ * error too, and its text re-parses to the same failure, so offering it
+ * salvages nothing while burying the fragment that would have worked.
+ *
+ * `root` itself is never a candidate, for the same reason taken to its limit:
+ * re-parsing the whole source reproduces the whole failure by construction.
+ */
+function unresolvedRegionsWithin(root: TSNode): TSNode[] {
+  const found: TSNode[] = [];
+  collectInnermostUnresolved(root, root, found);
+  return found;
+}
+
+function collectInnermostUnresolved(
+  node: TSNode,
+  root: TSNode,
+  found: TSNode[],
+): void {
+  if (!parseUnresolvedWithin(node)) return;
+  const before = found.length;
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child && child.type !== "ERROR") {
+      collectInnermostUnresolved(child, root, found);
+    }
+  }
+  const foundDeeper = found.length > before;
+  if (!foundDeeper && node !== root && node.type !== "ERROR") found.push(node);
+}

package/src/authority/authorizer-chain-audit.ts

@@ -0,0 +1,99 @@
+/**
+ * authorizer-chain-audit.ts — Report a configured `authorizerChain` link this
+ * node's registry could not resolve.
+ *
+ * Registrations are node-local (ADR 0012 decision 1), and a link produces a
+ * *verdict* rather than a fact, so live authority stays converged at the
+ * adjudicating node and a link is never inherited from an ancestor. A node that
+ * adjudicates locally therefore runs whatever links loaded in it, and skips the
+ * rest fail-safe (ADR 0007 §4 invariant 2) — the ask still reaches the
+ * terminal. That resolution is deliberate; its silence was not. The operator
+ * named a judge in config, did not get it, and the only trace was a line in a
+ * JSONL file.
+ *
+ * The two halves of the alarm fire at different rates on purpose, for two
+ * different readers. The review entry is the auditor's durable record and must
+ * be complete, so it is written for every skipped ask. The visible warning is
+ * for the operator about to answer the prompt the link should have answered, so
+ * it is latched: one per configured name, whose count is bounded by
+ * `authorizerChain.length`.
+ *
+ * A relaying node cannot reach this audit at all. `AuthorizerSelection` returns
+ * from `linksFor` before resolving anything, recording
+ * `authorizer_chain_delegated` instead — its ask is adjudicated one hop up
+ * (ADR 0007 §7), where an absent link is the design rather than a
+ * misconfiguration.
+ */
+
+/** The narrow log seam this audit needs (ISP): a durable record and a warning. */
+export interface AuthorizerChainAuditLog {
+  review(event: string, details?: Record<string, unknown>): void;
+  warn(message: string): void;
+}
+
+/** A configured chain link this node's registry could not resolve. */
+export interface UnregisteredLink {
+  /** The operator-configured name, exactly as written in `authorizerChain`. */
+  name: string;
+  /** The ask whose chain resolution skipped it. */
+  requestId: string;
+}
+
+/** The audit seam `AuthorizerSelection` drives when it skips a name (ISP). */
+export interface UnregisteredLinkAuditor {
+  auditUnregisteredLink(link: UnregisteredLink): void;
+}
+
+/**
+ * The agent-facing text for a configured link that is not registered here.
+ *
+ * Three causes leave the identical absence — the provider was excluded from
+ * this session's extensions, it failed to load, or it declined to register
+ * because it has no configuration of its own (the shape
+ * `@gotgenes/pi-permission-model-judge` uses to let an operator opt out
+ * per project). The message names the likeliest and admits the others, rather
+ * than accusing the operator of a contradiction it cannot prove.
+ *
+ * Every clause is a statement of what already happened. It deliberately does
+ * not claim later asks will skip the link too: registration is honored any time
+ * before an ask (ADR 0007 §4), so a link may yet arrive.
+ */
+export function unregisteredLinkMessage(name: string): string {
+  return (
+    `pi-permission-system: authorizerChain names "${name}", but no link with ` +
+    "that name is registered in this session, so this ask is being decided " +
+    "without it. Most often the extension providing the link is not loaded " +
+    "here (a subagent child's excludedExtensionPackages does this); it may " +
+    "also have failed to load, or declined to register because it has no " +
+    "configuration of its own. Every skipped ask is recorded in the " +
+    "permission review log as authorizer_chain_unregistered_link."
+  );
+}
+
+/**
+ * Records each skipped chain link, and warns the operator once per name.
+ *
+ * The latch is a plain field with no re-arm hook, because the extension factory
+ * is re-invoked per session generation — a `/new`, `/resume`, `/fork`, or
+ * `/import` switch builds a fresh audit. A `session_start` with
+ * `reason: "reload"` reuses this instance and deliberately does not re-warn for
+ * a name already reported; a name newly added to `authorizerChain` by that same
+ * reload has no entry yet, so it warns on its first skip.
+ */
+export class AuthorizerChainAudit implements UnregisteredLinkAuditor {
+  private readonly warned = new Set<string>();
+
+  constructor(private readonly log: AuthorizerChainAuditLog) {}
+
+  auditUnregisteredLink(link: UnregisteredLink): void {
+    this.log.review("authorizer_chain_unregistered_link", {
+      requestId: link.requestId,
+      name: link.name,
+    });
+    if (this.warned.has(link.name)) {
+      return;
+    }
+    this.warned.add(link.name);
+    this.log.warn(unregisteredLinkMessage(link.name));
+  }
+}

package/src/authority/authorizer-selection.ts

@@ -7,6 +7,7 @@ import {
   selectAuthorizer,
 } from "./authorizer";
 import { composeAuthorizerChain } from "./authorizer-chain";
+import type { UnregisteredLinkAuditor } from "./authorizer-chain-audit";
 import type { AuthorizerLookup } from "./authorizer-registry";
 import { encloseInDelegationEnvelope } from "./delegation-envelope";
 import type { PermissionPromptDecision } from "./permission-dialog";
@@ -61,6 +62,28 @@ export interface AdjudicationRole {
   adjudicatesLocally(): boolean;
 }
 
+/**
+ * Everything {@link AuthorizerSelection} is constructed with: the
+ * {@link AuthorizerSelectionDeps} `selectAuthorizer` itself needs, plus the
+ * collaborators only the class uses to resolve and run the chain.
+ *
+ * Named rather than left anonymous on the constructor because the test
+ * fixtures mirror it: an addition here is otherwise an addition in two places.
+ * `selectAuthorizer` keeps the narrower parameter type (ISP) — it resolves no
+ * links and must not see the chain collaborators.
+ */
+export type AuthorizerSelectionConstructorDeps = AuthorizerSelectionDeps & {
+  prompter: PermissionPrompterApi;
+  /** The session-scoped query injected into each chain link (ADR 0007 §3). */
+  getPermissionQuery: () => PermissionQuery;
+  /** Read-only lookup of registered links by name. */
+  authorizerRegistry: AuthorizerLookup;
+  /** The operator's configured link names, read live per ask. */
+  getAuthorizerChain: () => string[];
+  /** Told about each configured name the registry could not resolve. */
+  chainAudit: UnregisteredLinkAuditor;
+};
+
 /**
  * Context-owning selection root for the Authorizer spine.
  *
@@ -79,17 +102,7 @@ export class AuthorizerSelection
   private authority: SelectedAuthority | null = null;
   private relayTarget: PermissionForwardingTarget | null = null;
 
-  constructor(
-    private readonly deps: AuthorizerSelectionDeps & {
-      prompter: PermissionPrompterApi;
-      /** The session-scoped query injected into each chain link (ADR 0007 §3). */
-      getPermissionQuery: () => PermissionQuery;
-      /** Read-only lookup of registered links by name. */
-      authorizerRegistry: AuthorizerLookup;
-      /** The operator's configured link names, read live per ask. */
-      getAuthorizerChain: () => string[];
-    },
-  ) {}
+  constructor(private readonly deps: AuthorizerSelectionConstructorDeps) {}
 
   /**
    * Select the live authority for `ctx` and store it. The non-terminal
@@ -165,10 +178,11 @@ export class AuthorizerSelection
 
   /**
    * Resolve the operator's `authorizerChain` names to registered links, in
-   * config order (ADR 0007 invariant 1). An unregistered name is skipped with a
-   * warning (invariant 2 — more prompting, never less); each resolved link is
-   * wrapped in the bounded-delegation envelope so an `allow` on an excluded
-   * surface cannot exceed the operator's policy.
+   * config order (ADR 0007 invariant 1). An unregistered name is skipped
+   * fail-safe (invariant 2 — more prompting, never less) and handed to the
+   * chain audit, which records it and tells the operator once per name; each
+   * resolved link is wrapped in the bounded-delegation envelope so an `allow`
+   * on an excluded surface cannot exceed the operator's policy.
    *
    * The resolved names are recorded against the ask before any link runs — a
    * link that defers decides nothing and would otherwise leave no evidence it
@@ -184,10 +198,7 @@ export class AuthorizerSelection
     for (const name of configured) {
       const authorize = this.deps.authorizerRegistry.get(name);
       if (authorize === undefined) {
-        this.deps.logger.review("authorizer_chain_unregistered_link", {
-          requestId,
-          name,
-        });
+        this.deps.chainAudit.auditUnregisteredLink({ requestId, name });
         continue;
       }
       resolved.push(name);

package/src/handlers/gates/bash-command.ts

@@ -30,15 +30,19 @@ import type { PermissionCheckResult } from "#src/types";
  * from riding a permissive rule; an explicit `deny`/`ask` on the wrapper is left
  * untouched (`deny > ask > allow`).
  *
- * When `commands` is empty there are two cases. A trivially-empty command (an
- * empty, whitespace-only, or comment-only line) has genuinely nothing to gate,
- * so the whole `command` is resolved as before. A non-empty command that parsed
- * to zero command units (a parse anomaly or an opaque program) fails closed to
- * a synthetic `ask` so a permissive top-level `*` cannot silently allow an
+ * A trivially-empty command (an empty, whitespace-only, or comment-only line)
+ * has genuinely nothing to gate, so the whole `command` is resolved as before.
+ *
+ * When the *primary* parse matched nothing, the whole command string is the
+ * only surface an explicit `deny` can reach, so it is resolved first and a
+ * `deny` covering it denies outright rather than being masked into an
+ * approvable prompt (#712). With no units at all the result also fails closed
+ * to a synthetic `ask`, so a permissive top-level `*` cannot silently allow an
  * unparseable command (e.g. `cd /repo && git push` riding a top-level allow on
- * the empty-parse path) — #452. The whole command is still resolved first so an
- * explicit `deny` covering it denies outright rather than being masked into an
- * approvable prompt (#712).
+ * the empty-parse path) — #452. A command whose units are *all* salvaged
+ * (#875) takes the same whole-string check, because its primary parse matched
+ * nothing either; only the synthetic `ask` is skipped, since the recovered
+ * units now carry the verdict.
  *
  * A *partial* parse failure is the other half of that clause: the units the
  * recovery produced are enumerated normally, and any one the enumerator marked
@@ -70,22 +74,32 @@ export function resolveBashCommandCheck(
   agentName: string | undefined,
   resolver: ScopedPermissionResolver,
 ): PermissionCheckResult {
-  if (commands.length === 0) {
-    if (isTriviallyEmptyCommand(command)) {
-      return resolveOnBashSurface(command, agentName, resolver);
-    }
+  if (isTriviallyEmptyCommand(command)) {
+    return resolveOnBashSurface(command, agentName, resolver);
+  }
+
+  if (!commands.some((cmd) => cmd.salvaged !== true)) {
+    // The primary parse matched nothing, so the whole command string is the
+    // only surface an explicit `deny` can reach (#452, #712) — a rule naming
+    // the command in context (`"* rm -rf *"`) matches the string and not the
+    // fragment. This runs whether or not the salvage went on to recover units
+    // from the wreckage: `> f <<'M' 2>&1 | rm -rf /tmp/x` has zero primary
+    // units and one salvaged one, and keying the check on the combined list
+    // would silently drop a `deny` the pre-salvage gate reached (#875).
     const whole = resolveOnBashSurface(command, agentName, resolver);
     if (whole.state === "deny") {
       return whole;
     }
-    return {
-      state: "ask",
-      toolName: "bash",
-      source: "bash",
-      origin: "builtin",
-      command,
-      matchedPattern: "<unparseable-bash-command>",
-    };
+    if (commands.length === 0) {
+      return {
+        state: "ask",
+        toolName: "bash",
+        source: "bash",
+        origin: "builtin",
+        command,
+        matchedPattern: "<unparseable-bash-command>",
+      };
+    }
   }
 
   const results = commands.map((cmd) =>

package/src/index.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getAgentDir, getPackageDir } from "@earendil-works/pi-coding-agent";
 import { warmBashParser } from "#src/access-intent/bash/parser";
 import { buildResolvedIntentFromMatchValues } from "#src/access-intent/input-normalizer";
+import { AuthorizerChainAudit } from "#src/authority/authorizer-chain-audit";
 import {
   AuthorizerRegistry,
   ObservedAuthorizerRegistrar,
@@ -168,6 +169,10 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     // resolved in config order at activation.
     authorizerRegistry,
     getAuthorizerChain: () => configStore.current().authorizerChain ?? [],
+    // Records each configured name this node could not resolve, and tells the
+    // operator once per name — the ask is decided without the judge they
+    // asked for, and the review log alone never said so (#861).
+    chainAudit: new AuthorizerChainAudit(logger),
   });
 
   // Resolver composes the manager + session ruleset and owns the