@gotgenes/pi-permission-system 33.1.1 → 34.0.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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).
 
+## [34.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v33.1.1...pi-permission-system-v34.0.0) (2026-09-25)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** **breaking:** check a redirect's target against path rules even when the file does not exist yet ([aa88e23](https://github.com/gotgenes/pi-packages/commit/aa88e23be9d6d994728855000eae95e00e0ca03e)), closes [#609](https://github.com/gotgenes/pi-packages/issues/609)
+
+### Documentation
+
+* **pi-permission-system:** record that a redirect's target is projected by its role ([c709401](https://github.com/gotgenes/pi-packages/commit/c70940154c63bb8d1c0b92ca1ef262ec22215102)), closes [#609](https://github.com/gotgenes/pi-packages/issues/609)
+
 ## [33.1.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v33.1.0...pi-permission-system-v33.1.1) (2026-09-24)
 
 

package/docs/configuration.md

@@ -739,7 +739,7 @@ Quoting is understood, so `ls "$HOME/x"` and `ls $HOME/x` are treated alike.
 
 What the bash projection resolves:
 
-- Absolute, home-relative (`~/`), parent-traversal (`../`), and separator-bearing tokens, plus redirect targets (`> out.txt`) and values embedded in long options (`--file=/tmp/patterns`).
+- Absolute, home-relative (`~/`), parent-traversal (`../`), and separator-bearing tokens, plus redirect targets (`> out.txt`, including a file the redirect creates) and values embedded in long options (`--file=/tmp/patterns`).
 - The plain shell variables `$HOME` / `${HOME}` and `$PWD` / `${PWD}`, so `$HOME/x` is gated exactly as `~/x` and the literal absolute spelling, whether or not the target exists.
 - Relative tokens, against the working directory produced by folding literal current-shell `cd` commands.
 - A bare token (`cat id_rsa`) when it names an existing filesystem entry.
@@ -860,6 +860,9 @@ 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's target reaches its surface whether or not the file exists yet, so a `path_write` pattern governs what a command may create through `>`, not only what it may overwrite.
+Only the redirect's literal target counts: a computed one (`> "$OUT"`) is not resolved, as for any other computed path.
+
 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.

package/package.json

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

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

@@ -20,6 +20,7 @@ import {
   collectRedirectTokens,
   extractCommandName,
   type PathToken,
+  type TokenRole,
 } from "./token-collection";
 
 // ── Internal types ───────────────────────────────────────────────────────────
@@ -40,13 +41,14 @@ type EffectiveBase =
 
 /**
  * A path-candidate token paired with the effective working directory projected
- * onto the point in the command stream where it appears, and the effect its
- * position proved.
+ * onto the point in the command stream where it appears, the effect its
+ * position proved, and the role its collector gave it.
  */
 interface PathCandidate {
   readonly token: string;
   readonly base: EffectiveBase;
   readonly effect: TokenEffect;
+  readonly role: TokenRole;
 }
 
 /** A promoted bare token and its resolved path, before an effect is attached. */
@@ -101,9 +103,12 @@ const UNKNOWN_BASE: EffectiveBase = { kind: "unknown" };
  * decision — so no walk step re-reads the platform or threads the cwd.
  *
  * A bare token that fails both shape gates is admitted when the normalizer's
- * existence probe says it names a real filesystem entry (ADR 0009, #645). The
- * resolver consults no ruleset: candidacy is a filesystem question, and the
- * policy decision belongs to the gates downstream.
+ * existence probe says it names a real filesystem entry (ADR 0009, #645). A
+ * redirect's own target needs neither: its collector proved it names a file,
+ * so its `redirect-destination` role admits it whether or not the file exists
+ * yet (#609). The resolver consults no ruleset: candidacy is a syntax and
+ * filesystem question, and the policy decision belongs to the gates
+ * downstream.
  *
  * Tell-don't-ask: callers hand it a parsed tree and receive the resolved
  * {@link ResolvedBashPaths} slices in one {@link resolve} call; the AST walk,
@@ -448,7 +453,8 @@ export class BashPathResolver {
    * Project the collected candidates into deduplicated external paths.
    *
    * Filters candidates through the strict path classifier
-   * (`classifyTokenAsPathCandidate`), resolves each against its effective working
+   * (`classifyTokenAsPathCandidate`) unless their role already admits them,
+   * resolves each against its effective working
    * directory base, and returns only paths that resolve outside the baked cwd in
    * their lexical (as-typed, normalized but not symlink-resolved) form.
    *
@@ -462,8 +468,10 @@ export class BashPathResolver {
     const seen = new Map<string, number>();
     const externalPaths: BashExternalPath[] = [];
 
-    for (const { token, base, effect } of candidates) {
-      const candidate = classifyTokenAsPathCandidate(token);
+    for (const { token, base, effect, role } of candidates) {
+      const candidate = admittedByRole(role)
+        ? token
+        : classifyTokenAsPathCandidate(token);
       if (!candidate) {
         // A bare token the strict shape gate rejects can still escape the tree
         // through a symlink, so probe it and apply the ordinary boundary
@@ -542,7 +550,8 @@ export class BashPathResolver {
    * Filters candidates through the broad path classifier
    * (`classifyTokenAsRuleCandidate`), falling back to {@link probeBareToken}
    * for a bare token the broad classifier rejects for shape — admitted only
-   * when it names an existing filesystem entry (#645).
+   * when it names an existing filesystem entry (#645). A token its role
+   * admits skips both (#609).
    * On win32 the broad classifier is told to treat a backslash as a path
    * separator, so a backslash-relative token (`dir\file`) is recognized as a
    * rule candidate the same as its forward-slash equivalent (#520); on POSIX
@@ -558,11 +567,10 @@ export class BashPathResolver {
     const seen = new Map<string, number>();
     const result: BashPathRuleCandidate[] = [];
 
-    for (const { token, base, effect } of candidates) {
-      const shaped = classifyTokenAsRuleCandidate(
-        token,
-        this.normalizer.flavor,
-      );
+    for (const { token, base, effect, role } of candidates) {
+      const shaped = admittedByRole(role)
+        ? token
+        : classifyTokenAsRuleCandidate(token, this.normalizer.flavor);
       const probed =
         shaped === null
           ? this.probeBareToken(token, base)
@@ -677,7 +685,18 @@ function tagTokens(
   base: EffectiveBase,
   out: PathCandidate[],
 ): void {
-  for (const { token, effect } of tokens) out.push({ token, base, effect });
+  for (const { token, effect, role } of tokens) {
+    out.push({ token, base, effect, role });
+  }
+}
+
+/**
+ * Whether a candidate's role settles its candidacy, so neither shape gate nor
+ * the existence probe is consulted: a redirect's own target is proven by
+ * syntax to name a file, including one the command is about to create.
+ */
+function admittedByRole(role: TokenRole): boolean {
+  return role === "redirect-destination";
 }
 
 /**

package/src/access-intent/bash/node-text.ts

@@ -27,6 +27,42 @@ export const ARG_NODE_TYPES = new Set([
   "raw_string",
 ]);
 
+/**
+ * Whether an argument node's value is decided at run time: it contains a
+ * command or process substitution, an arithmetic expansion, or a variable
+ * expansion {@link resolvePlainVariableExpansion} cannot resolve.
+ *
+ * The complement of what {@link resolveNodeText} can spell exactly. A plain
+ * `$HOME` / `$PWD` reference resolves, so `"$HOME/out"` is not computed; any
+ * other expansion falls back to its own source text there, which names a file
+ * that is not the one the shell will touch (ADR 0009's computed-path residual).
+ * A single-quoted `'$x'` is a literal.
+ */
+export function hasComputedPart(node: TSNode): boolean {
+  if (COMPUTED_NODE_TYPES.has(node.type)) return true;
+  if (VARIABLE_EXPANSION_TYPES.has(node.type)) {
+    return resolvePlainVariableExpansion(node) === null;
+  }
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child && hasComputedPart(child)) return true;
+  }
+  return false;
+}
+
+/** Node types whose value only running the command can produce. */
+const COMPUTED_NODE_TYPES: ReadonlySet<string> = new Set([
+  "command_substitution",
+  "process_substitution",
+  "arithmetic_expansion",
+]);
+
+/** Variable references, computed unless they resolve as a plain reference. */
+const VARIABLE_EXPANSION_TYPES: ReadonlySet<string> = new Set([
+  "simple_expansion",
+  "expansion",
+]);
+
 /**
  * Resolve the "shell value" of an argument node — the string the shell
  * would pass to the command after quote removal.

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

@@ -7,8 +7,9 @@ import { parseUnresolvedAt, type TSNode } from "./parser";
  *
  * `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.
+ * enough to consult it: finding the operator among the node's children,
+ * telling a destination that names a file from one that names a descriptor,
+ * and naming which destination is the redirect's own target.
  *
  * The split exists because two callers need different answers from the same
  * read, and — importantly — they need them under different burdens of proof.
@@ -92,6 +93,34 @@ export function redirectMayWriteFile(redirect: TSNode): boolean {
   return false;
 }
 
+/**
+ * The child index of the node `redirect` reads or writes (its first named
+ * child after the operator), or `undefined` when it names none (`>&-`).
+ *
+ * The operator is the redirect's only unnamed child, and a source descriptor
+ * (`2` in `2>`) precedes it, so the first named child after it is the
+ * target without asking its type.
+ *
+ * Only the first: tree-sitter-bash 0.25.1 declares the destination
+ * `repeat1`, so the words after it in `grep pat 2>/dev/null f.txt` parse as
+ * further destinations, while bash passes them to the redirected command as
+ * arguments (#977). An index rather than a node, because a caller iterating
+ * the children compares positions rather than wrapper identity.
+ */
+export function redirectTargetIndex(redirect: TSNode): number | undefined {
+  let seenOperator = false;
+  for (let i = 0; i < redirect.childCount; i++) {
+    const child = redirect.child(i);
+    if (!child) continue;
+    if (!child.isNamed) {
+      seenOperator = true;
+      continue;
+    }
+    if (seenOperator) return i;
+  }
+  return undefined;
+}
+
 /**
  * Destination node types that name a file descriptor rather than a file, so
  * `>&` / `<&` duplicate a stream instead of touching the filesystem.

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

@@ -4,14 +4,31 @@ import { proveCommandEffect } from "./command-effects";
 import { EXECUTION_HOST_TYPES, forEachExecutionIn } from "./nested-execution";
 import {
   ARG_NODE_TYPES,
+  hasComputedPart,
   resolveNodeText,
   SKIP_SUBTREE_TYPES,
 } from "./node-text";
 import type { TSNode } from "./parser";
-import { redirectEffectForDestination } from "./redirect-analysis";
+import {
+  redirectEffectForDestination,
+  redirectTargetIndex,
+} from "./redirect-analysis";
+
+/**
+ * What a collected token is, as the collector that produced it established.
+ *
+ * The role decides candidacy and the effect decides direction; both are
+ * stamped at the same site and never re-derived downstream.
+ */
+export type TokenRole =
+  /** An operand of unknown path-hood: shape and the existence probe decide. */
+  | "operand"
+  /** A redirect's own target, which the syntax proves names a file. */
+  | "redirect-destination";
 
 /**
- * A collected path-candidate token paired with the effect its position proved.
+ * A collected path-candidate token paired with the effect its position proved
+ * and the role its collector gave it.
  *
  * 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
@@ -20,6 +37,7 @@ import { redirectEffectForDestination } from "./redirect-analysis";
 export interface PathToken {
   readonly token: string;
   readonly effect: TokenEffect;
+  readonly role: TokenRole;
 }
 
 // ── Public surface ─────────────────────────────────────────────────────────
@@ -108,23 +126,55 @@ export function collectCommandTokens(node: TSNode): PathToken[] {
  * in front of it is. A destination the operator names as a file descriptor
  * (`2>&1`) contributes no token at all.
  *
+ * The redirect's own target carries the `redirect-destination` role when the
+ * syntax proves it names a file, so the projection admits it whether or not
+ * the file exists yet (#609). Every other child is an `operand`: a word the
+ * grammar appends after the target belongs to the redirected command (#977).
+ *
  * 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): PathToken[] {
+  const target = redirectTargetIndex(node);
   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)) {
       const effect = redirectEffectForDestination(node, child);
-      if (effect) tokens.push({ token: resolveNodeText(child), effect });
+      if (effect) {
+        const token = resolveNodeText(child);
+        const role: TokenRole =
+          i === target && provesTarget(effect, child, token)
+            ? "redirect-destination"
+            : "operand";
+        tokens.push({ token, effect, role });
+      }
     }
     tokens.push(...collectHostedExecutionTokens(child));
   }
   return tokens;
 }
 
+/**
+ * Whether a redirect's target is proven to name this literal file.
+ *
+ * The operator must have proved an effect: a redirect the parse could not
+ * resolve proves nothing (#814). The value must be literal: a computed one
+ * names a file only running the command decides (ADR 0009's computed-path
+ * residual). And it must be non-empty, since bash refuses `> ""` rather than
+ * writing anything.
+ */
+function provesTarget(
+  effect: TokenEffect,
+  destination: TSNode,
+  token: string,
+): boolean {
+  return (
+    effect.source === "syntax" && !hasComputedPart(destination) && token !== ""
+  );
+}
+
 /**
  * Collect the path-candidate tokens of every command nested inside `node`'s
  * execution contexts, reading none of the host subtree's own text.
@@ -204,7 +254,11 @@ function collectStatementOperandTokens(
       tokens.push(...collectPathCandidateTokens(child));
       continue;
     }
-    tokens.push({ token: resolveNodeText(child), effect: UNPROVEN_EFFECT });
+    tokens.push({
+      token: resolveNodeText(child),
+      effect: UNPROVEN_EFFECT,
+      role: "operand",
+    });
     tokens.push(...collectHostedExecutionTokens(child));
   }
   return tokens;
@@ -323,7 +377,9 @@ function collectEmbeddedOptionValues(
     if (!ARG_NODE_TYPES.has(child.type)) continue;
 
     const value = OPTION_VALUE_PATTERN.exec(resolveNodeText(child))?.[1];
-    if (value !== undefined) values.push({ token: value, effect });
+    if (value !== undefined) {
+      values.push({ token: value, effect, role: "operand" });
+    }
   }
   return values;
 }
@@ -334,7 +390,7 @@ function embeddedOptionValueToken(
   effect: TokenEffect,
 ): PathToken[] {
   const value = OPTION_VALUE_PATTERN.exec(text)?.[1];
-  return value === undefined ? [] : [{ token: value, effect }];
+  return value === undefined ? [] : [{ token: value, effect, role: "operand" }];
 }
 
 /**
@@ -802,7 +858,11 @@ function collectPatternCommandTokens(
             break;
           case "inline-value":
             if (directive.role === "script-file")
-              tokens.push({ token: directive.value, effect });
+              tokens.push({
+                token: directive.value,
+                effect,
+                role: "operand",
+              });
             if (suppliesScript(directive.role)) hasExplicitScript = true;
             break;
           case "regular-flag":
@@ -819,7 +879,7 @@ function collectPatternCommandTokens(
     if (!hasExplicitScript && positionalsSeen < patternPositionals) {
       positionalsSeen++; // Skip: this is an inline pattern/script.
     } else {
-      tokens.push({ token: text, effect });
+      tokens.push({ token: text, effect, role: "operand" });
     }
     // A quoted token that did not act as a flag above has its embedded value
     // split here instead.
@@ -874,7 +934,10 @@ function dischargePendingConsumption(
 ): ConsumptionDischarge {
   switch (role) {
     case "script-file":
-      return { consumed: true, token: { token: text, effect } };
+      return {
+        consumed: true,
+        token: { token: text, effect, role: "operand" },
+      };
     case "script":
     case "value":
       return { consumed: true };
@@ -923,7 +986,7 @@ function collectGenericCommandTokens(
 
     // Argument nodes: resolve their text and collect.
     if (ARG_NODE_TYPES.has(child.type)) {
-      tokens.push({ token: resolveNodeText(child), effect });
+      tokens.push({ token: resolveNodeText(child), effect, role: "operand" });
       continue;
     }