@gotgenes/pi-permission-system 27.0.0 → 27.1.0

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

@@ -3,13 +3,15 @@ import {
   forEachNestedExecution,
 } from "#src/access-intent/bash/nested-execution";
 import type { TSNode } from "#src/access-intent/bash/parser";
+import { redirectMayWriteFile } from "#src/access-intent/bash/redirect-analysis";
 import {
   type CommandWord,
   classifyWrapperWords,
   executedUnitOf,
+  isTransparentWrapper,
   type WrapperKind,
 } from "#src/access-intent/bash/wrapper-analysis";
-import type { BashCommandContext } from "#src/types";
+import type { BashCommandContext, FloorExemption } from "#src/types";
 
 export type { WrapperKind } from "#src/access-intent/bash/wrapper-analysis";
 
@@ -37,25 +39,55 @@ export interface BashCommand {
    */
   readonly wrapperKind?: WrapperKind;
   /**
-   * The command this wrapper unit actually runs (#713). Display-only — it is
-   * never gated on its own, so the wrapper floor still applies. Absent for an
-   * ordinary command, and for a wrapper whose inner command cannot be
-   * established.
+   * The command this wrapper unit actually runs (#713). Absent for an ordinary
+   * command, and for a wrapper whose inner command cannot be established.
+   *
+   * Display-only, and deliberately looks past an `sh -c` layer the gate must
+   * not look past — {@link floorExemption} is the gateable answer, established
+   * by its own walk rather than read off this string (#803).
    */
   readonly executedUnit?: string;
+  /**
+   * Set when this wrapper unit's floor has no reason left to hold, naming the
+   * reason (#803). Only ever present alongside `wrapperKind: "indirection"`
+   * and an established {@link executedUnit}.
+   */
+  readonly floorExemption?: FloorExemption;
+}
+
+/**
+ * What the statement enclosing a command unit establishes about it.
+ *
+ * Both facts flow down the walk together because both are the *statement's*,
+ * not the command's: a subshell's commands run in a subshell however they are
+ * spelled, and a redirected statement writes a file however read-only the
+ * command in front of the operator is.
+ */
+interface UnitScope {
+  /**
+   * Execution context for a nested command (substitution or subshell); absent
+   * for a current-shell (top-level) command.
+   */
+  readonly context?: BashCommandContext;
+  /**
+   * True when the enclosing statement redirects output into a real file, which
+   * withholds the floor exemption from any wrapper unit beneath it.
+   */
+  readonly writesViaRedirect: boolean;
 }
 
+/** A top-level command in the current shell, writing no file. */
+const TOP_LEVEL_SCOPE: UnitScope = { writesViaRedirect: false };
+
 // ── Command enumeration ──────────────────────────────────────────────────────
 
 /**
- * Container node types descended into when enumerating command units.
+ * Container node types descended into with the enclosing scope unchanged.
+ *
+ * `redirected_statement` is descended too, but has its own branch: it is the
+ * node that can establish a write, so it descends with a scope of its own.
  */
-const COMMAND_ENUM_DESCEND = new Set([
-  "program",
-  "list",
-  "pipeline",
-  "redirected_statement",
-]);
+const COMMAND_ENUM_DESCEND = new Set(["program", "list", "pipeline"]);
 
 /**
  * Named node types abandoned during command enumeration: they are neither
@@ -95,13 +127,13 @@ const COMMAND_ENUM_SKIP = new Set(["comment", "heredoc_end"]);
  */
 export function collectCommands(node: TSNode): BashCommand[] {
   const out: BashCommand[] = [];
-  collectCommandsInto(node, undefined, out);
+  collectCommandsInto(node, TOP_LEVEL_SCOPE, out);
   return out;
 }
 
 function collectCommandsInto(
   node: TSNode,
-  context: BashCommandContext | undefined,
+  scope: UnitScope,
   out: BashCommand[],
 ): void {
   // Anonymous tokens (operators `&&`/`;`/`|`, delimiters `$(`/`)`/`` ` ``/`(`)
@@ -110,13 +142,18 @@ function collectCommandsInto(
   if (COMMAND_ENUM_SKIP.has(node.type)) return;
 
   if (node.type === "command") {
-    out.push(makeCommandUnit(node, context));
+    out.push(makeCommandUnit(node, scope));
     // A command's text already contains any substitution; descend its subtree
     // to ALSO emit the inner commands of command/process substitutions.
     collectHostedCommands(node, out);
     return;
   }
 
+  if (node.type === "redirected_statement") {
+    descendCommandChildren(node, redirectedScope(node, scope), out);
+    return;
+  }
+
   if (EXECUTION_HOST_TYPES.has(node.type)) {
     // Not a command itself, but its subtree can host one that really runs
     // (`> $(rm x)`, `< <(rm c)`). Emit only what it hosts (#741).
@@ -125,48 +162,80 @@ function collectCommandsInto(
   }
 
   if (node.type === "subshell") {
-    out.push(makeUnit(node.text, context)); // never-weaker whole emit
-    descendCommandChildren(node, "subshell", out);
+    out.push(makeUnit(node.text, scope)); // never-weaker whole emit
+    descendCommandChildren(node, { ...scope, context: "subshell" }, out);
     return;
   }
 
   if (COMMAND_ENUM_DESCEND.has(node.type)) {
-    descendCommandChildren(node, context, out);
+    descendCommandChildren(node, scope, out);
     return;
   }
 
   // Any other named statement (compound_statement `{ … }`, if/while/for/case,
   // function_definition): emit whole, do not descend — deferred (#306).
-  out.push(makeUnit(node.text, context));
+  out.push(makeUnit(node.text, scope));
+}
+
+/** The wrapper facts a `command` node's words establish about its unit. */
+interface WrapperFacts {
+  readonly wrapperKind?: WrapperKind;
+  readonly executedUnit?: string;
+  readonly floorExemption?: FloorExemption;
 }
 
 function makeUnit(
   text: string,
-  context: BashCommandContext | undefined,
-  wrapperKind?: WrapperKind,
-  executedUnit?: string,
+  scope: UnitScope,
+  wrapper: WrapperFacts = {},
 ): BashCommand {
-  const unit: BashCommand = context ? { text, context } : { text };
-  const flagged = wrapperKind ? { ...unit, wrapperKind } : unit;
-  return executedUnit === undefined ? flagged : { ...flagged, executedUnit };
+  const { wrapperKind, executedUnit, floorExemption } = wrapper;
+  const scoped: BashCommand = scope.context
+    ? { text, context: scope.context }
+    : { text };
+  const flagged = wrapperKind ? { ...scoped, wrapperKind } : scoped;
+  const named =
+    executedUnit === undefined ? flagged : { ...flagged, executedUnit };
+  return floorExemption === undefined ? named : { ...named, floorExemption };
 }
 
 /**
- * Build the unit for a `command` node, reading its words once to answer both
- * wrapper questions: whether the unit is floored, and what it actually runs.
+ * Build the unit for a `command` node, reading its words once to answer all
+ * three wrapper questions: whether the unit is floored, what it actually runs,
+ * and whether the floor still has a reason to hold.
  */
-function makeCommandUnit(
-  node: TSNode,
-  context: BashCommandContext | undefined,
-): BashCommand {
+function makeCommandUnit(node: TSNode, scope: UnitScope): BashCommand {
   const text = commandUnitText(node);
   const words = readCommandWords(node);
-  return makeUnit(
-    text,
-    context,
-    classifyWrapperWords(words),
-    executedUnitOf(text, words) ?? undefined,
-  );
+  return makeUnit(text, scope, {
+    wrapperKind: classifyWrapperWords(words),
+    executedUnit: executedUnitOf(text, words) ?? undefined,
+    floorExemption: isTransparentWrapper(words, scope)
+      ? "core-reader"
+      : undefined,
+  });
+}
+
+/**
+ * The scope a `redirected_statement`'s children run under: the enclosing one,
+ * plus a write unless every one of its redirects provably only reads.
+ *
+ * The redirect belongs to the last element of a pipeline, but it hangs off the
+ * whole statement in the parse tree, so every command beneath it is marked.
+ * Over-attributing is the fail-closed direction — the flag can only withhold an
+ * exemption, never grant one — which is also why the question asked of each
+ * redirect is a refusal rather than a proof.
+ */
+function redirectedScope(node: TSNode, scope: UnitScope): UnitScope {
+  if (scope.writesViaRedirect) return scope;
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child?.type !== "file_redirect") continue;
+    if (redirectMayWriteFile(child)) {
+      return { ...scope, writesViaRedirect: true };
+    }
+  }
+  return scope;
 }
 
 /**
@@ -213,12 +282,12 @@ function commandUnitText(node: TSNode): string {
 
 function descendCommandChildren(
   node: TSNode,
-  context: BashCommandContext | undefined,
+  scope: UnitScope,
   out: BashCommand[],
 ): void {
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
-    if (child) collectCommandsInto(child, context, out);
+    if (child) collectCommandsInto(child, scope, out);
   }
 }
 
@@ -232,6 +301,13 @@ function descendCommandChildren(
  */
 function collectHostedCommands(node: TSNode, out: BashCommand[]): void {
   forEachNestedExecution(node, (contextNode, context) => {
-    descendCommandChildren(contextNode, context, out);
+    // 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.
+    descendCommandChildren(
+      contextNode,
+      { context, writesViaRedirect: false },
+      out,
+    );
   });
 }

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

@@ -1,5 +1,5 @@
-import type { AccessPath } from "#src/access-intent/access-path";
 import {
+  type BashExternalPath,
   BashPathResolver,
   type BashPathRuleCandidate,
 } from "#src/access-intent/bash/bash-path-resolver";
@@ -10,7 +10,7 @@ import {
 import { getParser } from "#src/access-intent/bash/parser";
 import type { PathNormalizer } from "#src/path-normalizer";
 
-export type { BashCommand, BashPathRuleCandidate };
+export type { BashCommand, BashExternalPath, BashPathRuleCandidate };
 
 /**
  * A bash command parsed once into a born-ready representation.
@@ -26,7 +26,7 @@ export class BashProgram {
   private constructor(
     private readonly sourceCommand: string,
     private readonly commandUnits: readonly BashCommand[],
-    private readonly resolvedExternalPaths: readonly AccessPath[],
+    private readonly resolvedExternalAccesses: readonly BashExternalPath[],
     private readonly resolvedRuleCandidates: readonly BashPathRuleCandidate[],
   ) {}
 
@@ -59,14 +59,14 @@ export class BashProgram {
     if (!tree) return new BashProgram(command, [], [], []);
 
     try {
-      const { externalPaths, ruleCandidates } = new BashPathResolver(
+      const { externalAccesses, ruleCandidates } = new BashPathResolver(
         normalizer,
         options?.workdir,
       ).resolve(tree.rootNode);
       return new BashProgram(
         command,
         collectCommands(tree.rootNode),
-        externalPaths,
+        externalAccesses,
         ruleCandidates,
       );
     } finally {
@@ -104,21 +104,25 @@ export class BashProgram {
   }
 
   /**
-   * Deduplicated paths that resolve outside `cwd`, as {@link AccessPath} value
-   * objects holding both the lexical (as-typed) and canonical (symlink-resolved)
-   * forms behind distinct accessors.
+   * Deduplicated accesses that resolve outside `cwd`: each an
+   * {@link AccessPath} value object holding both the lexical (as-typed) and
+   * canonical (symlink-resolved) forms behind distinct accessors, paired with
+   * the effect the command stream proved for it.
    *
    * Resolved eagerly at parse time through the `PathNormalizer` supplied to
    * `parse()` (platform + cwd baked in).
    * Use `.matchValues()` for `external_directory` pattern matching and
    * `.boundaryValue()` for containment checks; `.value()` for display and logs.
+   * Two attributions of the same resolved path fold rather than split, so the
+   * entry count is a function of the paths alone (#807).
    */
-  externalPaths(): AccessPath[] {
-    return [...this.resolvedExternalPaths];
+  externalAccesses(): BashExternalPath[] {
+    return [...this.resolvedExternalAccesses];
   }
 
   /**
-   * Path-rule candidates paired with their policy lookup values.
+   * Path-rule candidates paired with their policy lookup values and the
+   * effect the command stream proved for each (#807).
    *
    * Resolved eagerly at parse time through the `PathNormalizer` supplied to
    * `parse()` (platform + cwd baked in).

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

@@ -0,0 +1,98 @@
+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";
+
+/**
+ * What a redirect node in the parse tree proves.
+ *
+ * `command-effects.ts` owns the operator *table* — which spelling means read,
+ * which means write — and this module owns reading a `file_redirect` node well
+ * enough to consult it: finding the operator among the node's children, and
+ * telling a destination that names a file from one that names a descriptor.
+ *
+ * The split exists because two callers need different answers from the same
+ * read, and — importantly — they need them under different burdens of proof.
+ * The token collector asks what effect to *attribute* to a destination it is
+ * about to emit, so it answers with a proof. The command enumerator asks
+ * 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 effect `redirect` proves for `destination`, or `null` when the redirect
+ * names no file and no token should be collected.
+ *
+ * `>&` 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.
+ */
+export function redirectEffectForDestination(
+  redirect: TSNode,
+  destination: TSNode,
+): TokenEffect | null {
+  return redirectDestinationEffect(
+    redirectOperatorOf(redirect),
+    DESCRIPTOR_NODE_TYPES.has(destination.type),
+  );
+}
+
+/**
+ * True unless `redirect` provably only reads — the fail-closed question the
+ * floor exemption asks.
+ *
+ * Deliberately **not** the negation of a write proof. A destination this module
+ * cannot resolve counts as a write here, because the caller is deciding whether
+ * to remove a guard: `> $OUT`, `>${OUT}`, and `> $(mktemp)` name a file chosen
+ * at run time, and the parse can say nothing about which. Reading those as "no
+ * write proved, therefore no write" would hand the exemption to exactly the
+ * 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.
+ */
+export function redirectMayWriteFile(redirect: TSNode): boolean {
+  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;
+    }
+  }
+  return false;
+}
+
+/**
+ * Destination node types that name a file descriptor rather than a file, so
+ * `>&` / `<&` duplicate a stream instead of touching the filesystem.
+ *
+ * Neither type is in {@link ARG_NODE_TYPES}, so `2>&1`'s `1` is already never
+ * collected; the check is what keeps that true if the argument set widens.
+ */
+const DESCRIPTOR_NODE_TYPES: ReadonlySet<string> = new Set([
+  "file_descriptor",
+  "number",
+]);
+
+/**
+ * The redirect operator of a redirect node.
+ *
+ * tree-sitter-bash emits it as an unnamed child whose `type` is the operator
+ * text itself, and a redirect's only unnamed child is that operator — so the
+ * syntax proof is a lookup on the first one found.
+ */
+function redirectOperatorOf(node: TSNode): string {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child && !child.isNamed) return child.type;
+  }
+  return "";
+}

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

@@ -1,4 +1,5 @@
 import { basename } from "node:path";
+import { proveCommandEffect } from "#src/access-intent/bash/command-effects";
 import {
   EXECUTION_HOST_TYPES,
   forEachNestedExecution,
@@ -10,6 +11,20 @@ import {
   SKIP_SUBTREE_TYPES,
 } from "#src/access-intent/bash/node-text";
 import type { TSNode } from "#src/access-intent/bash/parser";
+import { redirectEffectForDestination } from "#src/access-intent/bash/redirect-analysis";
+import type { TokenEffect } from "#src/access-intent/effect";
+
+/**
+ * A collected path-candidate token paired with the effect its position proved.
+ *
+ * The pairing is made where the token is *produced*, never by mapping a whole
+ * result: a nested execution's tokens carry their own command's attribution
+ * and must not be overwritten by the enclosing one.
+ */
+export interface PathToken {
+  readonly token: string;
+  readonly effect: TokenEffect;
+}
 
 // ── Public surface ─────────────────────────────────────────────────────────
 
@@ -29,7 +44,7 @@ import type { TSNode } from "#src/access-intent/bash/parser";
  * as path candidates. For all other commands, collects all
  * arguments generically.
  */
-export function collectPathCandidateTokens(node: TSNode): string[] {
+export function collectPathCandidateTokens(node: TSNode): PathToken[] {
   if (node.type === "command") return collectCommandTokens(node);
   if (node.type === "file_redirect") return collectRedirectTokens(node);
   if (EXECUTION_HOST_TYPES.has(node.type)) {
@@ -37,7 +52,7 @@ export function collectPathCandidateTokens(node: TSNode): string[] {
   }
   if (SKIP_SUBTREE_TYPES.has(node.type)) return [];
 
-  const tokens: string[] = [];
+  const tokens: PathToken[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (child) tokens.push(...collectPathCandidateTokens(child));
@@ -49,16 +64,25 @@ export function collectPathCandidateTokens(node: TSNode): string[] {
  * Select the collection strategy for a `command` node: pattern-first
  * commands use `collectPatternCommandTokens`; all others use
  * `collectGenericCommandTokens`.
+ *
+ * Every token the command owns carries the effect its head word proves — the
+ * pure-reader core, read through the *raw* head word so a path-qualified
+ * spelling proves nothing. A nested execution collected along the way keeps
+ * its own command's attribution instead.
  */
-export function collectCommandTokens(node: TSNode): string[] {
+export function collectCommandTokens(node: TSNode): PathToken[] {
+  const effect = proveCommandEffect(
+    extractCommandWord(node) ?? "",
+    commandArgumentWords(node),
+  );
   const commandName = extractCommandName(node);
   const config = commandName
     ? PATTERN_FIRST_COMMANDS.get(commandName)
     : undefined;
   const tokens = config
-    ? collectPatternCommandTokens(node, config)
-    : collectGenericCommandTokens(node);
-  return [...tokens, ...collectEmbeddedOptionValues(node)];
+    ? collectPatternCommandTokens(node, config, effect)
+    : collectGenericCommandTokens(node, effect);
+  return [...tokens, ...collectEmbeddedOptionValues(node, effect)];
 }
 
 /**
@@ -72,14 +96,24 @@ export function collectCommandTokens(node: TSNode): string[] {
  * Both passes are needed: a substitution can be the destination outright, or be
  * concatenated into it (`> ${DIR}/$(cmd)`), and a `concatenation` is itself an
  * argument node.
+ *
+ * The operator proves the destination's effect outright, and that proof is
+ * absolute: it overrides whatever the redirected command's own head word
+ * proved, because `> out.txt` writes `out.txt` however read-only the command
+ * in front of it is. A destination the operator names as a file descriptor
+ * (`2>&1`) contributes no token at all.
+ *
+ * Reading the redirect node itself belongs to `redirect-analysis.ts`, which
+ * the command enumerator consults for the same fact (#803).
  */
-export function collectRedirectTokens(node: TSNode): string[] {
-  const tokens: string[] = [];
+export function collectRedirectTokens(node: TSNode): PathToken[] {
+  const tokens: PathToken[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child) continue;
     if (ARG_NODE_TYPES.has(child.type)) {
-      tokens.push(resolveNodeText(child));
+      const effect = redirectEffectForDestination(node, child);
+      if (effect) tokens.push({ token: resolveNodeText(child), effect });
     }
     tokens.push(...collectHostedExecutionTokens(child));
   }
@@ -97,11 +131,11 @@ export function collectRedirectTokens(node: TSNode): string[] {
  * (`> ${DIR}/$(cmd)`); `forEachNestedExecution` searches strictly within a
  * subtree, so the first case is checked here.
  */
-function collectHostedExecutionTokens(node: TSNode): string[] {
+function collectHostedExecutionTokens(node: TSNode): PathToken[] {
   if (NESTED_EXECUTION_CONTEXTS.has(node.type)) {
     return collectPathCandidateTokens(node);
   }
-  const tokens: string[] = [];
+  const tokens: PathToken[] = [];
   forEachNestedExecution(node, (contextNode) => {
     tokens.push(...collectPathCandidateTokens(contextNode));
   });
@@ -112,14 +146,34 @@ function collectHostedExecutionTokens(node: TSNode): string[] {
  * Extract the command name from a `command` node.
  * Returns the basename (e.g. `/usr/bin/sed` → `sed`), or undefined
  * if the command name cannot be determined (e.g. variable expansion).
+ *
+ * The basename is what {@link PATTERN_FIRST_COMMANDS} needs: `/usr/bin/sed`
+ * parses its arguments exactly as `sed` does. It is the wrong question for a
+ * capability claim, where the directory prefix is the whole point — use
+ * {@link extractCommandWord} there.
  */
 export function extractCommandName(node: TSNode): string | undefined {
+  const word = extractCommandWord(node);
+  return word === undefined ? undefined : basename(word);
+}
+
+/**
+ * Extract the head word of a `command` node exactly as it was written, or
+ * undefined when it cannot be determined (e.g. variable expansion).
+ *
+ * Unbasenamed on purpose: `./grep` and `/tmp/evil/grep` name programs the
+ * pure-reader core's audit never saw, so an effect proof must be able to tell
+ * them from a bare `grep` — the Codex lesson the bare-basename rule encodes.
+ * Documented against {@link extractCommandName}, which answers the other
+ * question.
+ */
+export function extractCommandWord(node: TSNode): string | undefined {
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child) continue;
     if (child.type === "command_name") {
       const text = resolveNodeText(child);
-      return text ? basename(text) : undefined;
+      return text === "" ? undefined : text;
     }
   }
   return undefined;
@@ -127,6 +181,25 @@ export function extractCommandName(node: TSNode): string | undefined {
 
 // ── Private helpers and config ─────────────────────────────────────────────
 
+/**
+ * The command's own argument words, which the retraction guards read.
+ *
+ * Reads the argument nodes directly rather than the collected tokens, because
+ * a guard fires on an *option* (`find -delete`) and no collector emits one.
+ */
+function commandArgumentWords(node: TSNode): string[] {
+  const words: string[] = [];
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (child.type === "command_name" || child.type === "variable_assignment")
+      continue;
+    if (!ARG_NODE_TYPES.has(child.type)) continue;
+    words.push(resolveNodeText(child));
+  }
+  return words;
+}
+
 /**
  * A long or short option carrying its value inline: one or two leading dashes,
  * a name containing no `=` or whitespace, then `=` and a non-empty value.
@@ -148,8 +221,11 @@ const OPTION_VALUE_PATTERN = /^-{1,2}[^=\s]+=(.+)$/;
  * here is what lets the projection see option-embedded paths without per-command
  * option tables (ADR 0009, #645).
  */
-function collectEmbeddedOptionValues(node: TSNode): string[] {
-  const values: string[] = [];
+function collectEmbeddedOptionValues(
+  node: TSNode,
+  effect: TokenEffect,
+): PathToken[] {
+  const values: PathToken[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child) continue;
@@ -158,7 +234,7 @@ function collectEmbeddedOptionValues(node: TSNode): string[] {
     if (!ARG_NODE_TYPES.has(child.type)) continue;
 
     const value = OPTION_VALUE_PATTERN.exec(resolveNodeText(child))?.[1];
-    if (value !== undefined) values.push(value);
+    if (value !== undefined) values.push({ token: value, effect });
   }
   return values;
 }
@@ -322,13 +398,14 @@ function classifyPatternCommandFlag(
 function collectPatternCommandTokens(
   node: TSNode,
   config: PatternCommandConfig,
-): string[] {
+  effect: TokenEffect,
+): PathToken[] {
   const patternPositionals = config.patternPositionals ?? 1;
   let hasExplicitScript = false;
   let positionalsSeen = 0;
   let nextArgAction: "skip" | "extract" | null = null;
   let pastEndOfFlags = false;
-  const tokens: string[] = [];
+  const tokens: PathToken[] = [];
 
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
@@ -353,7 +430,7 @@ function collectPatternCommandTokens(
       continue;
     }
     if (nextArgAction === "extract") {
-      tokens.push(text);
+      tokens.push({ token: text, effect });
       nextArgAction = null;
       continue;
     }
@@ -387,7 +464,7 @@ function collectPatternCommandTokens(
     }
 
     // File argument — collect as path candidate.
-    tokens.push(text);
+    tokens.push({ token: text, effect });
   }
 
   return tokens;
@@ -397,8 +474,11 @@ function collectPatternCommandTokens(
  * Collect all argument tokens from a generic (non-pattern-first) command node,
  * skipping the command name and variable assignments.
  */
-function collectGenericCommandTokens(node: TSNode): string[] {
-  const tokens: string[] = [];
+function collectGenericCommandTokens(
+  node: TSNode,
+  effect: TokenEffect,
+): PathToken[] {
+  const tokens: PathToken[] = [];
   let seenCommandName = false;
 
   for (let i = 0; i < node.childCount; i++) {
@@ -421,7 +501,7 @@ function collectGenericCommandTokens(node: TSNode): string[] {
 
     // Argument nodes: resolve their text and collect.
     if (ARG_NODE_TYPES.has(child.type)) {
-      tokens.push(resolveNodeText(child));
+      tokens.push({ token: resolveNodeText(child), effect });
       continue;
     }