@gotgenes/pi-permission-system 39.1.1 → 40.0.0

package/src/access-intent/bash/token-collection.ts

@@ -39,6 +39,19 @@ export interface PathToken {
   readonly token: string;
   readonly effect: TokenEffect;
   readonly role: TokenRole;
+  /**
+   * The source span of the argument node, set only when {@link token} is that
+   * whole node's resolved text. A token read from part of an argument (an
+   * option's embedded value, a script file glued to its flag) carries none, so
+   * nothing keyed on the span can mistake it for the whole word.
+   */
+  readonly span?: SourceSpan;
+}
+
+/** Where a node sits in the parsed source: `startIndex` to `endIndex`. */
+export interface SourceSpan {
+  readonly start: number;
+  readonly end: number;
 }
 
 // ── Public surface ─────────────────────────────────────────────────────────
@@ -160,7 +173,7 @@ export function collectRedirectTokens(
           i === target && provesTarget(effect, child, token, words)
             ? "redirect-destination"
             : "operand";
-        tokens.push({ token, effect, role });
+        tokens.push(wholeArgumentToken(child, token, effect, role));
       }
     }
     tokens.push(...collectHostedExecutionTokens(child, words));
@@ -271,11 +284,9 @@ function collectStatementOperandTokens(
       tokens.push(...collectPathCandidateTokens(child, words));
       continue;
     }
-    tokens.push({
-      token: words.text(child),
-      effect: UNPROVEN_EFFECT,
-      role: "operand",
-    });
+    tokens.push(
+      wholeArgumentToken(child, words.text(child), UNPROVEN_EFFECT, "operand"),
+    );
     tokens.push(...collectHostedExecutionTokens(child, words));
   }
   return tokens;
@@ -833,7 +844,12 @@ function collectPatternCommandTokens(
         tokens.push(...collectPathCandidateTokens(child, words));
         continue;
       }
-      const discharge = dischargePendingConsumption(consumption, text, effect);
+      const discharge = dischargePendingConsumption(
+        consumption,
+        child,
+        text,
+        effect,
+      );
       if (discharge.token) tokens.push(discharge.token);
       if (discharge.consumed) continue;
     }
@@ -907,7 +923,7 @@ function collectPatternCommandTokens(
     if (!hasExplicitScript && positionalsSeen < patternPositionals) {
       positionalsSeen++; // Skip: this is an inline pattern/script.
     } else {
-      tokens.push({ token: text, effect, role: "operand" });
+      tokens.push(wholeArgumentToken(child, text, effect, "operand"));
     }
     // A quoted token that did not act as a flag above has its embedded value
     // split here instead.
@@ -957,6 +973,7 @@ interface ConsumptionDischarge {
 /** Apply a pending consumption to the argument text that follows its flag. */
 function dischargePendingConsumption(
   role: PatternFlagRole,
+  argument: TSNode,
   text: string,
   effect: TokenEffect,
 ): ConsumptionDischarge {
@@ -964,7 +981,7 @@ function dischargePendingConsumption(
     case "script-file":
       return {
         consumed: true,
-        token: { token: text, effect, role: "operand" },
+        token: wholeArgumentToken(argument, text, effect, "operand"),
       };
     case "script":
     case "value":
@@ -1015,7 +1032,9 @@ function collectGenericCommandTokens(
 
     // Argument nodes: resolve their text and collect.
     if (ARG_NODE_TYPES.has(child.type)) {
-      tokens.push({ token: words.text(child), effect, role: "operand" });
+      tokens.push(
+        wholeArgumentToken(child, words.text(child), effect, "operand"),
+      );
       continue;
     }
 
@@ -1025,3 +1044,21 @@ function collectGenericCommandTokens(
 
   return tokens;
 }
+
+/**
+ * A token that is `node`'s whole resolved text, carrying the node's source span
+ * so a reader of the span knows the token stands for the entire word.
+ */
+function wholeArgumentToken(
+  node: TSNode,
+  token: string,
+  effect: TokenEffect,
+  role: TokenRole,
+): PathToken {
+  return {
+    token,
+    effect,
+    role,
+    span: { start: node.startIndex, end: node.endIndex },
+  };
+}

package/src/authority/forwarded-request-server.ts

@@ -57,7 +57,9 @@ export interface InboxProcessor {
  * used as-is, never re-derived through this session's `PathNormalizer`/cwd.
  *
  * The answer honors the floor the child raised (`intent.floor`): a serving
- * `allow` rule does not answer an ask the child's own gate floored.
+ * `allow` rule does not answer an ask the child's own gate floored. A bash
+ * chain is judged on every unit the child left asking (`intent.askingUnits`),
+ * each with its own floor, since this answer approves the whole tool call.
  *
  * Narrow by design (ISP): the server needs one decision, not the whole
  * resolver. The composition root satisfies it with `ResolverServingPolicy`
@@ -155,6 +157,9 @@ function toAccessFacts(intent: ForwardedAccessIntent): ForwardedAccessFacts {
     matchValues: intent.matchValues,
     boundaryValue: intent.boundaryValue,
     ...(intent.floor === undefined ? {} : { floor: intent.floor }),
+    ...(intent.askingUnits === undefined
+      ? {}
+      : { askingUnits: intent.askingUnits }),
   };
 }
 

package/src/authority/forwarding-io.ts

@@ -19,6 +19,7 @@ import {
   type ApprovalGrant,
   isSessionGrantWidth,
 } from "#src/session/approval-grant";
+import type { AskingBashUnit } from "#src/types";
 import { asDecisionSource } from "./decision-source";
 import { isPermissionDecisionState } from "./permission-dialog";
 import {
@@ -125,6 +126,7 @@ function asForwardedAccessIntent(
     matchValues?: unknown;
     boundaryValue?: unknown;
     floor?: unknown;
+    askingUnits?: unknown;
     requesterCwd?: unknown;
     principal?: unknown;
   };
@@ -139,6 +141,12 @@ function asForwardedAccessIntent(
     // A malformed floor drops the whole intent, which escalates: it must
     // never read as "no floor".
     !(candidate.floor === undefined || typeof candidate.floor === "string") ||
+    // Likewise a malformed unit list: it must never read as "no units", which
+    // would judge the chain's winner alone.
+    !(
+      candidate.askingUnits === undefined ||
+      isWellFormedAskingUnits(candidate.askingUnits)
+    ) ||
     typeof candidate.requesterCwd !== "string" ||
     typeof candidate.principal !== "object" ||
     candidate.principal === null
@@ -160,6 +168,9 @@ function asForwardedAccessIntent(
     matchValues: [...candidate.matchValues],
     boundaryValue: candidate.boundaryValue,
     ...(candidate.floor === undefined ? {} : { floor: candidate.floor }),
+    ...(isWellFormedAskingUnits(candidate.askingUnits)
+      ? { askingUnits: copyAskingUnits(candidate.askingUnits) }
+      : {}),
     requesterCwd: candidate.requesterCwd,
     principal: {
       sessionId: principal.sessionId,
@@ -168,6 +179,39 @@ function asForwardedAccessIntent(
   };
 }
 
+/**
+ * True for a non-empty list of `{ command: string, floor?: string }` units.
+ *
+ * Empty is malformed: a child stamps the list only when it holds a unit, so an
+ * empty one says nothing a well-formed request would.
+ */
+function isWellFormedAskingUnits(
+  value: unknown,
+): value is readonly { command: string; floor?: string }[] {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.every(
+      (unit: unknown) =>
+        typeof unit === "object" &&
+        unit !== null &&
+        typeof (unit as { command?: unknown }).command === "string" &&
+        ((unit as { floor?: unknown }).floor === undefined ||
+          typeof (unit as { floor?: unknown }).floor === "string"),
+    )
+  );
+}
+
+/** Rebuild each unit field by field, so no unread key rides through. */
+function copyAskingUnits(
+  units: readonly { command: string; floor?: string }[],
+): AskingBashUnit[] {
+  return units.map((unit) => ({
+    command: unit.command,
+    ...(unit.floor === undefined ? {} : { floor: unit.floor }),
+  }));
+}
+
 export function formatUnknownErrorMessage(error: unknown): string {
   if (error instanceof Error && error.message) {
     return error.message;

package/src/authority/permission-forwarding.ts

@@ -5,6 +5,7 @@ import type {
   ApprovalGrant,
   SessionGrantWidth,
 } from "#src/session/approval-grant";
+import type { AskingBashUnit } from "#src/types";
 import type { DecisionSource } from "./decision-source";
 import type { PermissionDecisionState } from "./permission-dialog";
 import type { SubagentSessionRegistry } from "./subagent-registry";
@@ -131,6 +132,14 @@ export interface ForwardedAccessFacts {
    * than recomputing it. Absent when no floor was raised.
    */
   floor?: string;
+  /**
+   * Every unit of a bash chain the child left asking, each with its own floor.
+   * `matchValues` names only the chain's winner, and the serving node's answer
+   * approves the whole tool call, so it judges each of these instead. Absent
+   * for a non-bash ask and for a bash ask raised without a chain (the empty
+   * parse), where `matchValues` is the whole command.
+   */
+  askingUnits?: AskingBashUnit[];
 }
 
 /**

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

@@ -115,7 +115,30 @@ export function resolveBashCommandCheck(
   const winner =
     pickMostRestrictive(results) ??
     resolveOnBashSurface(command, [], agentName, resolver);
-  return withChainFloor(winner, results);
+  return withAskingUnits(withChainFloor(winner, results), results);
+}
+
+/**
+ * List on an asking winner every unit of the chain the gate left asking.
+ *
+ * The winner names one command, but a forwarded ask's answer approves the
+ * whole tool call, so the serving node has to judge every unit the child could
+ * not resolve, each with its own floor (#1030). A unit the child's rules
+ * allowed stays home, and so does one the session already granted: the user
+ * approved exactly that command.
+ */
+function withAskingUnits(
+  winner: PermissionCheckResult,
+  results: readonly PermissionCheckResult[],
+): PermissionCheckResult {
+  if (winner.state !== "ask") return winner;
+  const askingUnits = results
+    .filter((result) => result.state === "ask" && result.source !== "session")
+    .map((result) => ({
+      command: result.command ?? "",
+      ...(result.floor === undefined ? {} : { floor: result.floor }),
+    }));
+  return askingUnits.length === 0 ? winner : { ...winner, askingUnits };
 }
 
 /**
@@ -205,14 +228,16 @@ function floorUnparsedUnit(
  * it.
  *
  * Spreads `resolved`, so a `source: "session"` grant survives to `GateRunner`'s
- * session fast path.
+ * session fast path. Drops `matchedSpelling`: it names what the replaced rule
+ * matched, and beside the sentinel it would name a match that did not decide.
  */
 function floorToAsk(
   resolved: PermissionCheckResult,
   sentinel: string,
 ): PermissionCheckResult {
+  const { matchedSpelling: _replaced, ...unspelled } = resolved;
   return {
-    ...resolved,
+    ...unspelled,
     state: "ask",
     matchedPattern: sentinel,
     floor: sentinel,

package/src/handlers/gates/tool.ts

@@ -14,7 +14,7 @@ import {
 import { buildToolAskPayload } from "#src/presentation/tool-ask-payload";
 import { SessionApproval } from "#src/session/session-approval";
 import type { ToolPreviewFormatter } from "#src/tool-input/tool-preview-formatter";
-import type { PermissionCheckResult } from "#src/types";
+import type { AskingBashUnit, PermissionCheckResult } from "#src/types";
 import type { GateDescriptor } from "./descriptor";
 import {
   accessFactsFromPath,
@@ -180,6 +180,7 @@ export function describeToolGate(
     : {
         ...accessFactsFromValue(gateSurface, decisionValue),
         ...floorFact(check),
+        ...askingUnitsFact(check),
       };
 
   return {
@@ -241,3 +242,16 @@ function floorExemptionFact(
 function floorFact(check: PermissionCheckResult): { floor?: string } {
   return check.floor === undefined ? {} : { floor: check.floor };
 }
+
+/**
+ * Every unit of a bash chain the child left asking, as a child-fixed fact for
+ * the wire, so the serving node judges each command rather than the winner
+ * alone (#1030). Absent when the check lists none.
+ */
+function askingUnitsFact(check: PermissionCheckResult): {
+  askingUnits?: AskingBashUnit[];
+} {
+  return check.askingUnits === undefined
+    ? {}
+    : { askingUnits: [...check.askingUnits] };
+}

package/src/logging/command-redaction.ts

@@ -42,6 +42,7 @@ import { isSensitiveName, REDACTED_PLACEHOLDER } from "./log-redaction";
 export const COMMAND_BEARING_LOG_KEYS: ReadonlySet<string> = new Set([
   "command",
   "executedUnit",
+  "matchedSpelling",
 ]);
 
 /** A range of the command to replace, and what to put in its place. */

package/src/policy/permission-manager.ts

@@ -376,7 +376,7 @@ export class PermissionManager implements ScopedPermissionManager {
         intent.command,
         intent.spellings,
       );
-      return buildCheckResult(
+      const { result, matchedValue } = evaluateCheck(
         surface,
         values,
         resultExtras,
@@ -385,6 +385,12 @@ export class PermissionManager implements ScopedPermissionManager {
         fullRules,
         this.flavor,
       );
+      // `values[0]` is the unit as typed, and the evaluator reports the first
+      // value the winning rule matches, so any other value is a spelling the
+      // typed text did not match.
+      return matchedValue === values[0]
+        ? result
+        : { ...result, matchedSpelling: matchedValue };
     }
 
     // kind === "tool"
@@ -423,6 +429,30 @@ function buildCheckResult(
   fullRules: Ruleset,
   flavor: PathFlavor,
 ): PermissionCheckResult {
+  return evaluateCheck(
+    surface,
+    values,
+    resultExtras,
+    normalizedToolName,
+    toolName,
+    fullRules,
+    flavor,
+  ).result;
+}
+
+/**
+ * {@link buildCheckResult}, plus the candidate value the decision was reported
+ * under — for a caller that knows what that value means on its own surface.
+ */
+function evaluateCheck(
+  surface: string,
+  values: string[],
+  resultExtras: Record<string, unknown>,
+  normalizedToolName: string,
+  toolName: string,
+  fullRules: Ruleset,
+  flavor: PathFlavor,
+): { result: PermissionCheckResult; matchedValue: string } {
   const { rule, value } = evaluateAnyValue(surface, values, fullRules, flavor);
 
   // For MCP, replace the normalizer's fallback target with the actual
@@ -433,16 +463,19 @@ function buildCheckResult(
       : resultExtras;
 
   return {
-    toolName,
-    state: rule.action,
-    reason: rule.reason,
-    matchedPattern:
-      rule.layer === "config" || rule.layer === "session"
-        ? rule.pattern
-        : undefined,
-    source: deriveSource(rule, normalizedToolName),
-    origin: rule.origin,
-    ...extras,
+    result: {
+      toolName,
+      state: rule.action,
+      reason: rule.reason,
+      matchedPattern:
+        rule.layer === "config" || rule.layer === "session"
+          ? rule.pattern
+          : undefined,
+      source: deriveSource(rule, normalizedToolName),
+      origin: rule.origin,
+      ...extras,
+    },
+    matchedValue: value,
   };
 }
 

package/src/policy/serving-policy.ts

@@ -1,8 +1,9 @@
 import { buildResolvedIntentFromMatchValues } from "#src/access-intent/input-normalizer";
 import type { ServingPolicy } from "#src/authority/forwarded-request-server";
 import type { ForwardedAccessIntent } from "#src/authority/permission-forwarding";
-import type { PermissionCheckResult } from "#src/types";
+import type { AskingBashUnit, PermissionCheckResult } from "#src/types";
 import type { PermissionResolver } from "./permission-resolver";
+import { mostRestrictiveOf } from "./restrictiveness";
 
 /**
  * The serving node's recorded authority over a forwarded request: the
@@ -10,6 +11,12 @@ import type { PermissionResolver } from "./permission-resolver";
  * agent-scoped to the requester (`principal.agentName`, §3), with the floor the
  * child raised honored.
  *
+ * A bash chain is judged unit by unit: the child names its winner in
+ * `matchValues`, but this answer approves the whole tool call, so every unit the
+ * child left asking (`askingUnits`) is resolved with its own floor and the most
+ * restrictive answer decides (#1030). A request without units (an older child,
+ * or an ask raised without a chain) is judged on its single value.
+ *
  * The `matchValues` are used as the child fixed them, never re-derived through
  * this session's `PathNormalizer`/cwd. The resolver's surface-family fold is
  * what keeps a parent's bare `path` deny answering a child's request, which is
@@ -22,6 +29,38 @@ export class ResolverServingPolicy implements ServingPolicy {
   ) {}
 
   resolve(intent: ForwardedAccessIntent): PermissionCheckResult {
+    const units = intent.askingUnits ?? [];
+    const first = units.at(0);
+    if (first === undefined) return this.resolveValue(intent);
+    const judge = (unit: AskingBashUnit): PermissionCheckResult =>
+      this.resolveUnit(unit, intent.principal.agentName);
+    return mostRestrictiveOf([judge(first), ...units.slice(1).map(judge)]);
+  }
+
+  /**
+   * Judge one unit the child left asking, with that unit's own floor.
+   *
+   * Resolved as the same `bash-command` intent the child's gate emitted for
+   * it, so a serving rule matches the unit exactly as a local one would.
+   */
+  private resolveUnit(
+    unit: AskingBashUnit,
+    agentName: string,
+  ): PermissionCheckResult {
+    const check = this.resolver.resolve({
+      kind: "bash-command",
+      surface: "bash",
+      command: unit.command,
+      spellings: [],
+      agentName,
+    });
+    return honorChildFloor(check, unit.floor, this.isYoloEnabled());
+  }
+
+  /**
+   * Judge the intent's single child-fixed value, with the chain-level floor.
+   */
+  private resolveValue(intent: ForwardedAccessIntent): PermissionCheckResult {
     const check = this.resolver.resolve(
       buildResolvedIntentFromMatchValues(
         intent.surface,

package/src/presentation/dialog-renderer.ts

@@ -222,6 +222,9 @@ function coreFacts(payload: PromptPayload): Fact[] {
   if (request.matchedPattern !== null) {
     facts.push({ label: "rule", text: request.matchedPattern });
   }
+  if (request.matchedSpelling !== null) {
+    facts.push({ label: "matched as", text: request.matchedSpelling });
+  }
   if (request.value !== "" && request.value !== request.toolName) {
     facts.push({ label, text: request.value });
   }

package/src/presentation/forwarded-ask-payload.ts

@@ -56,6 +56,7 @@ function degradedForwardedPayload(
       value: request.value ?? "",
       matchedPattern: null,
       commandContext: null,
+      matchedSpelling: null,
       executedUnit: null,
     },
     // Nothing to carry: the wire no longer relays a sentence, and inventing

package/src/presentation/path-ask-payload.ts

@@ -82,6 +82,7 @@ export function buildBashExternalDirectoryAskPayload(
       value: facts.command,
       matchedPattern: facts.matchedPattern ?? null,
       commandContext: null,
+      matchedSpelling: null,
       executedUnit: null,
     },
     evidence: [
@@ -113,6 +114,7 @@ function pathPayload(
       value: facts.pathValue,
       matchedPattern: facts.matchedPattern ?? null,
       commandContext: null,
+      matchedSpelling: null,
       executedUnit: null,
     },
     evidence,

package/src/presentation/prompt-payload.ts

@@ -63,6 +63,12 @@ export interface PromptRequestFacts {
   readonly value: string;
   /** The matched rule, including a sentinel such as `<indirection-bash-wrapper>`. */
   readonly matchedPattern: string | null;
+  /**
+   * For bash, the spelling of the unit the matched rule matched when it did not
+   * match {@link value} as typed — the absolute spelling of a relative path
+   * argument, say. `null` when the typed text decided.
+   */
+  readonly matchedSpelling: string | null;
   /**
    * Where the offending bash unit runs, when it came from a substitution or a
    * subshell. A fact rather than a rendered clause: it is what makes the
@@ -172,6 +178,9 @@ function asPromptRequestFacts(value: unknown): PromptRequestFacts | undefined {
     candidate.commandContext,
     BASH_COMMAND_CONTEXTS,
   );
+  // Absent from a request a node built before the fact existed, which states
+  // no spelling rather than a malformed one.
+  const matchedSpelling = candidate.matchedSpelling ?? null;
   if (
     !requester ||
     commandContext === undefined ||
@@ -180,6 +189,7 @@ function asPromptRequestFacts(value: unknown): PromptRequestFacts | undefined {
     !isNullableString(candidate.toolName) ||
     !isNullableString(candidate.invokedToolName) ||
     !isNullableString(candidate.matchedPattern) ||
+    !isNullableString(matchedSpelling) ||
     !isNullableString(candidate.executedUnit)
   ) {
     return undefined;
@@ -192,6 +202,7 @@ function asPromptRequestFacts(value: unknown): PromptRequestFacts | undefined {
     invokedToolName: candidate.invokedToolName,
     value: candidate.value,
     matchedPattern: candidate.matchedPattern,
+    matchedSpelling,
     commandContext: commandContext.value,
     executedUnit: candidate.executedUnit,
   };

package/src/presentation/review-log-renderer.ts

@@ -25,6 +25,7 @@ export function renderReviewLogFacts(
   return {
     surface: request.surface,
     ...present("matchedPattern", request.matchedPattern),
+    ...present("matchedSpelling", request.matchedSpelling),
     ...present("executedUnit", request.executedUnit),
     ...present("commandContext", request.commandContext),
     ...present("invokedToolName", request.invokedToolName),

package/src/presentation/skill-ask-payload.ts

@@ -42,6 +42,7 @@ function skillPayload(
       value: skillName,
       matchedPattern: null,
       commandContext: null,
+      matchedSpelling: null,
       executedUnit: null,
     },
     evidence,

package/src/presentation/tool-ask-payload.ts

@@ -44,6 +44,7 @@ export function buildToolAskPayload(facts: ToolAskFacts): PromptPayload {
       invokedToolName: distinctInvokedName(facts),
       value: askValue(check, bash, mcp),
       matchedPattern: check.matchedPattern ?? null,
+      matchedSpelling: check.matchedSpelling ?? null,
       commandContext: check.commandContext ?? null,
       executedUnit: check.executedUnit ?? null,
     },

package/src/service/bash-advisory-check.ts

@@ -1,5 +1,6 @@
-import { parseBashCommandsSync } from "#src/access-intent/bash/sync-commands";
+import { BashProgram } from "#src/access-intent/bash/program";
 import { resolveBashCommandCheck } from "#src/handlers/gates/bash-command";
+import type { PathNormalizer } from "#src/path/path-normalizer";
 import type { ScopedPermissionResolver } from "#src/policy/permission-resolver";
 import type { PermissionCheckResult } from "#src/types";
 
@@ -14,7 +15,11 @@ import type { PermissionCheckResult } from "#src/types";
  * 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
+ * The command is parsed by `BashProgram.parseSync` over the session's
+ * `normalizer`, the same builder the gate's program comes from, so every slice
+ * the gate resolves a unit with is resolved here too.
+ *
+ * In the pre-warm window (`parseSync` returns `null`) it falls back
  * to the pre-#309 whole-string match, so the advisory answer is never *weaker*
  * than before — only strengthened once warm.
  *
@@ -25,9 +30,10 @@ export function resolveBashAdvisoryCheck(
   command: string,
   agentName: string | undefined,
   resolver: ScopedPermissionResolver,
+  normalizer: PathNormalizer,
 ): PermissionCheckResult {
-  const commands = parseBashCommandsSync(command);
-  if (commands === null) {
+  const program = BashProgram.parseSync(command, normalizer);
+  if (program === null) {
     return resolver.resolve({
       kind: "tool",
       surface: "bash",
@@ -35,5 +41,10 @@ export function resolveBashAdvisoryCheck(
       agentName,
     });
   }
-  return resolveBashCommandCheck(command, commands, agentName, resolver);
+  return resolveBashCommandCheck(
+    command,
+    program.commands(),
+    agentName,
+    resolver,
+  );
 }

package/src/service/permissions-service.ts

@@ -67,7 +67,12 @@ export class LocalPermissionsService implements PermissionsService {
     // the enforcement gate enforces (#309). A cold parser falls back to the
     // whole-string match inside resolveBashAdvisoryCheck.
     if (surface === "bash") {
-      return resolveBashAdvisoryCheck(value ?? "", agentName, this.resolver);
+      return resolveBashAdvisoryCheck(
+        value ?? "",
+        agentName,
+        this.resolver,
+        this.session.getPathNormalizer(),
+      );
     }
     const intent = buildAccessIntentForSurface(
       surface,

package/src/types.ts

@@ -83,6 +83,13 @@ export interface PermissionCheckResult {
    * {@link floorExemption} says the wrapper's floor has no reason to hold.
    */
   executedUnit?: string;
+  /**
+   * The spelling of the bash unit the winning rule matched, when the rule did
+   * not also match the unit as typed — the absolute spelling of a relative
+   * path argument, say (#910). Display-only: absent whenever the typed text
+   * decided, and dropped by a floor that replaces {@link matchedPattern}.
+   */
+  matchedSpelling?: string;
   /**
    * Set when the winning bash unit is a wrapper the floor no longer covers,
    * naming why (#803, #963). Recorded in the review log so an allow the floor would
@@ -96,6 +103,22 @@ export interface PermissionCheckResult {
    * node to clamp its own `allow` with.
    */
   floor?: string;
+  /**
+   * Every unit of the bash chain that resolved to `ask` and was not
+   * session-granted, in chain order, each with its own floor. Set only on an
+   * asking chain winner: the serving node of a forwarded ask judges each one,
+   * since the winner alone would approve commands it never saw.
+   */
+  askingUnits?: readonly AskingBashUnit[];
+}
+
+/**
+ * One unit of a bash chain the gate left asking, as the serving node of a
+ * forwarded ask needs it: the unit as typed, and the floor that raised it.
+ */
+export interface AskingBashUnit {
+  command: string;
+  floor?: string;
 }
 
 export function isPermissionState(value: unknown): value is PermissionState {