@gotgenes/pi-permission-system 34.0.1 → 35.0.1

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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).
 
+## [35.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v35.0.0...pi-permission-system-v35.0.1) (2026-09-27)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** check the words after a heredoc against the command's own rules ([0a88264](https://github.com/gotgenes/pi-packages/commit/0a882643bb5b1be1f546842e75ca3fac5cff1930)), closes [#979](https://github.com/gotgenes/pi-packages/issues/979)
+* **pi-permission-system:** gate the commands and redirects written after a heredoc ([b7b2709](https://github.com/gotgenes/pi-packages/commit/b7b27095606c07f684eca353c253b59ebdec4cb4)), closes [#979](https://github.com/gotgenes/pi-packages/issues/979)
+
+## [35.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v34.0.1...pi-permission-system-v35.0.0) (2026-09-26)
+
+
+### Features
+
+* **pi-permission-system:** **breaking:** stop appending a tool list and rules to an operator's custom system prompt ([672a64c](https://github.com/gotgenes/pi-packages/commit/672a64c0844ec2fff8e113130109919623158107)), closes [#980](https://github.com/gotgenes/pi-packages/issues/980)
+
+### Documentation
+
+* **pi-permission-system:** record that a custom system prompt gets no appended tool surface ([7e0816d](https://github.com/gotgenes/pi-packages/commit/7e0816d28ab5377de011b5558b034c5b2bdaca4d))
+
 ## [34.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v34.0.0...pi-permission-system-v34.0.1) (2026-09-26)
 
 

package/docs/configuration.md

@@ -1246,11 +1246,11 @@ permission:
 
 The extension integrates via Pi's lifecycle hooks:
 
-| Hook                 | Behavior                                                                                                                                             |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `before_agent_start` | Filters the active tool set (restrict-only), restates the tool list and guidelines at the end of the system prompt to match, and hides denied skills |
-| `tool_call`          | Enforces permissions for every tool invocation                                                                                                       |
-| `input`              | Intercepts `/skill:<name>` requests and enforces skill policy                                                                                        |
+| Hook                 | Behavior                                                                                                                                                                                                      |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `before_agent_start` | Filters the active tool set (restrict-only), restates the tool list and guidelines at the end of the system prompt to match (except under a custom system prompt outside a subagent), and hides denied skills |
+| `tool_call`          | Enforces permissions for every tool invocation                                                                                                                                                                |
+| `input`              | Intercepts `/skill:<name>` requests and enforces skill policy                                                                                                                                                 |
 
 Additional behaviors:
 
@@ -1262,8 +1262,10 @@ Additional behaviors:
 - 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 tool list and guidelines are **relocated** rather than edited in place: the copies pi wrote are removed, and this session's own are rendered at the end of the system prompt, after the working directory pi states last.
   They take the shape pi writes them in: `Available tools:` and `Guidelines:` sections after a `Current working directory:` footer through pi 0.85, and `<tools>` and `<rules>` sections after a `<cwd>` section from pi 0.86.
-  Each session states its own tool surface, which is what keeps a subagent child's inherited prompt byte-identical to its parent's (see [ADR 0014](decisions/0014-tool-surface-is-node-local-prose.md)); the tool list moves to the end of the prompt for every session, whether or not anything is denied.
-  Only the copies pi wrote are removed: a custom system prompt (`.pi/SYSTEM.md`, `~/.pi/agent/SYSTEM.md`, `--system-prompt`) keeps its own text untouched, sections and all, because pi writes no tool surface of its own under one — so a prompt that lists tools itself is shown alongside this session's block rather than replaced by it.
+  Each session states its own tool surface, which is what keeps a subagent child's inherited prompt byte-identical to its parent's (see [ADR 0014](decisions/0014-tool-surface-is-node-local-prose.md)); the tool list moves to the end of the prompt for every session on pi's default prompt, whether or not anything is denied.
+  A custom system prompt (`.pi/SYSTEM.md`, `~/.pi/agent/SYSTEM.md`, `--system-prompt`) is left exactly as pi built it: pi writes no tool list or rules under one, and this extension adds none either, so the prompt describes tools only if you wrote that yourself.
+  Tool filtering and enforcement still apply, and the model still receives only the allowed tools in the request's tool list.
+  A subagent child is the exception: its prompt is always a custom one assembled by the subagent extension, so it still gets its own tool list and rules at the end, while any custom text it inherited stays untouched.
 - The rendered sections follow pi's own rules: a tool is listed only when pi supplied a one-line description for it, and the guideline bullets are the allowed tools' own contributions, then any rules another extension added to `systemPromptOptions.promptGuidelines`, around pi's built-in ones
 - The prompt is recomputed and returned on every turn but is stable across turns 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.

package/package.json

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

package/src/access-intent/bash/heredoc-tails.ts

@@ -0,0 +1,277 @@
+import {
+  childrenOf,
+  rewriteStatements,
+  rewrittenNode,
+  type Source,
+  sourceOf,
+} from "./parse-view";
+import type { TSNode } from "./parser";
+
+/**
+ * `tree-sitter-bash`'s parse with the rest of each heredoc's line moved out of
+ * the heredoc, to where the grammar puts it when the heredoc is written as a
+ * plain input redirect.
+ *
+ * The grammar (0.25.1) lets a `heredoc_redirect` carry whatever follows its
+ * delimiter on the same line: further redirects (`cat <<EOF > /tmp/o`), a
+ * `| …` statement, or an `&& …` / `|| …` statement. They parse as children of
+ * the heredoc, which every walker reads only for the substitutions it hosts, so
+ * `cat <<EOF | rm -rf /tmp/x` would enumerate as `cat` alone and
+ * `cat <<EOF > /tmp/o` would project no path (#979).
+ *
+ * The corrected tree is the grammar's own parse of the same line with `< in` in
+ * place of `<<EOF`: a redirect becomes a sibling after the heredoc, and a
+ * `| …` or `&& …` statement is joined to the redirected statement the way the
+ * grammar joins it to `cat < in`. That reproduces the grammar's groupings
+ * rather than bash's where the two differ (a redirect on a list's last command
+ * hangs off the whole list), because every walker is already built to read
+ * those groupings.
+ *
+ * Words after the delimiter (`git <<EOF push --force`) stay in the heredoc:
+ * `reattachRedirectArguments` hands them to the command, exactly as it does for
+ * the words after a file redirect's target. The heredoc keeps its body, which
+ * is written after the rest of the line, so it ends after the nodes moved out
+ * of it.
+ *
+ * Returns `root` itself when no heredoc carries such a tail.
+ */
+export function hoistHeredocTails(root: TSNode): TSNode {
+  return rewriteStatements(root, hoistStatement);
+}
+
+/**
+ * `statement` with its heredoc's tail moved out, or `undefined` when no
+ * heredoc among `children` carries one.
+ */
+function hoistStatement(
+  statement: TSNode,
+  children: readonly TSNode[],
+): TSNode | undefined {
+  const heredocIndex = children.findIndex(
+    (child) => child.type === "heredoc_redirect" && tailOf(child) !== undefined,
+  );
+  const heredoc = children.at(heredocIndex);
+  const tail = heredoc && tailOf(heredoc);
+  if (!tail) return undefined;
+
+  const after = children.slice(heredocIndex + 1);
+  // A statement tail runs to the end of the line, so nothing of the statement
+  // can follow it; anything that does is a shape this correction does not know.
+  if (tail.joined && after.some((child) => child.isNamed)) return undefined;
+
+  const source = sourceOf(statement);
+  const redirected = rewrittenNode(
+    statement,
+    [
+      ...children.slice(0, heredocIndex),
+      rewrittenNode(
+        heredoc,
+        tail.kept,
+        heredoc.startIndex,
+        heredoc.endIndex,
+        source,
+      ),
+      ...tail.redirects,
+      ...after,
+    ],
+    statement.startIndex,
+    statement.endIndex,
+    source,
+  );
+  if (!tail.joined) return redirected;
+  return join(
+    redirected,
+    tail.joined.operator,
+    withTrailingRedirectsOutermost(tail.joined.statement, source),
+    source,
+  );
+}
+
+/**
+ * `statement` with a redirect written at its end hung off all of it, as the
+ * grammar hangs it when the same text is not a heredoc's tail.
+ *
+ * At the top level `a | b | c > o` parses as `(a | b | c) > o`, but in a
+ * heredoc's tail the grammar parses it as `a | ((b | c) > o)`. Left that way,
+ * the joined write would not reach the heredoc's own command, so
+ * `xargs grep foo <<EOF && a | b | c > o` would keep a floor exemption that
+ * `xargs grep foo < in && a | b | c > o` withholds.
+ */
+function withTrailingRedirectsOutermost(
+  statement: TSNode,
+  source: Source,
+): TSNode {
+  if (statement.type === "redirected_statement") return statement;
+  const detached = detachTrailingRedirects(statement, source);
+  if (!detached) return statement;
+  return rewrittenNode(
+    { type: "redirected_statement", isNamed: true },
+    [detached.body, ...detached.redirects],
+    statement.startIndex,
+    statement.endIndex,
+    source,
+  );
+}
+
+/**
+ * `node` without the `redirected_statement` that ends it, plus that
+ * statement's redirects, or `undefined` when `node` does not end in one.
+ *
+ * The walk follows the last element of each `list` and `pipeline`, and a
+ * pipeline left holding a pipeline is flattened into one, as the grammar
+ * parses `a | b | c`.
+ */
+function detachTrailingRedirects(
+  node: TSNode,
+  source: Source,
+): { body: TSNode; redirects: TSNode[] } | undefined {
+  const children = childrenOf(node);
+  if (node.type === "redirected_statement") {
+    const bodyIndex = children.findIndex((child) => child.isNamed);
+    return {
+      body: children[bodyIndex],
+      redirects: children.slice(bodyIndex + 1),
+    };
+  }
+  if (!GROUPING_TYPES.has(node.type)) return undefined;
+  const lastIndex = children.findLastIndex((child) => child.isNamed);
+  const inner = detachTrailingRedirects(children[lastIndex], source);
+  if (!inner) return undefined;
+  const replaced =
+    node.type === "pipeline" && inner.body.type === "pipeline"
+      ? [...children.slice(0, lastIndex), ...childrenOf(inner.body)]
+      : children.with(lastIndex, inner.body);
+  return {
+    body: rewrittenNode(
+      node,
+      replaced,
+      node.startIndex,
+      inner.body.endIndex,
+      source,
+    ),
+    redirects: inner.redirects,
+  };
+}
+
+/** The groupings whose last element a trailing redirect is written after. */
+const GROUPING_TYPES: ReadonlySet<string> = new Set(["list", "pipeline"]);
+
+/** What a heredoc carries after its delimiter, split by where each part goes. */
+interface HeredocTail {
+  /** The heredoc's own children: operator, delimiter, any words, and body. */
+  readonly kept: readonly TSNode[];
+  /** Redirects written after the delimiter. */
+  readonly redirects: readonly TSNode[];
+  /** A `| …`, `|& …`, `&& …`, or `|| …` statement after them, if any. */
+  readonly joined?: {
+    readonly operator: TSNode;
+    readonly statement: TSNode;
+  };
+}
+
+/**
+ * `heredoc`'s tail, or `undefined` when it carries neither a redirect nor a
+ * statement after its delimiter.
+ *
+ * The grammar spells a `| …` tail as one `pipeline` child holding the operator
+ * and the statement, and an `&& …` / `|| …` tail as the operator token and the
+ * statement as two children of the heredoc itself. That statement can be a
+ * pipeline too (`cat <<EOF && ls | rm x`), so a `pipeline` child is the `| …`
+ * form only when no operator came before it.
+ */
+function tailOf(heredoc: TSNode): HeredocTail | undefined {
+  const kept: TSNode[] = [];
+  const redirects: TSNode[] = [];
+  let operator: TSNode | undefined;
+  let statement: TSNode | undefined;
+  for (const child of childrenOf(heredoc)) {
+    if (TAIL_REDIRECT_TYPES.has(child.type)) {
+      redirects.push(child);
+    } else if (child.type === "pipeline" && !operator) {
+      const [pipe] = childrenOf(child);
+      operator = pipe;
+      statement = childrenOf(child).find((node) => node.isNamed);
+    } else if (LIST_OPERATORS.has(child.type) && !child.isNamed) {
+      operator = child;
+    } else if (operator && !statement && child.isNamed) {
+      statement = child;
+    } else {
+      kept.push(child);
+    }
+  }
+  if (operator && !statement) return undefined;
+  const joined = operator && statement ? { operator, statement } : undefined;
+  if (redirects.length === 0 && !joined) return undefined;
+  return joined ? { kept, redirects, joined } : { kept, redirects };
+}
+
+/** The redirects a heredoc can carry after its delimiter. */
+const TAIL_REDIRECT_TYPES: ReadonlySet<string> = new Set([
+  "file_redirect",
+  "herestring_redirect",
+]);
+
+/** The operators that join an `&& …` / `|| …` tail. */
+const LIST_OPERATORS: ReadonlySet<string> = new Set(["&&", "||"]);
+
+/** The operators that join a `| …` tail. */
+const PIPE_OPERATORS: ReadonlySet<string> = new Set(["|", "|&"]);
+
+/**
+ * `redirected` joined to `statement` by `operator`, grouped as the grammar
+ * groups `cat < in <operator> <statement>`.
+ *
+ * The grammar hangs a redirect off everything before it, so a joined
+ * `redirected_statement` keeps its redirects outermost. That holds inside a
+ * pipeline too: `cat < in && a > o | b` parses as `(cat < in && a > o) | b`,
+ * so a pipeline whose first stage is redirected is joined at that stage. A
+ * `list` is left-associative and binds looser than a pipe, so the join reaches
+ * its first element. A pipe tail onto any other pipeline extends it. Anything
+ * else becomes the operator's own two-element node.
+ *
+ * Each rebuilt node spans from `redirected`'s start to the furthest end beneath
+ * it, which is the heredoc's, since its body is written after the tail.
+ */
+function join(
+  redirected: TSNode,
+  operator: TSNode,
+  statement: TSNode,
+  source: Source,
+): TSNode {
+  const isPipe = PIPE_OPERATORS.has(operator.type);
+  const children = childrenOf(statement);
+  const end = Math.max(redirected.endIndex, statement.endIndex);
+  const rebuild = (type: Pick<TSNode, "type" | "isNamed">, kids: TSNode[]) =>
+    rewrittenNode(type, kids, redirected.startIndex, end, source);
+
+  const first = children.findIndex((child) => child.isNamed);
+  if (joinsAtFirstElement(statement, children[first])) {
+    return rebuild(
+      statement,
+      children.with(first, join(redirected, operator, children[first], source)),
+    );
+  }
+  if (isPipe && statement.type === "pipeline") {
+    return rebuild(statement, [redirected, operator, ...children]);
+  }
+  return rebuild({ type: isPipe ? "pipeline" : "list", isNamed: true }, [
+    redirected,
+    operator,
+    statement,
+  ]);
+}
+
+/**
+ * Whether the grammar joins what precedes `statement` to its first element
+ * rather than to `statement` as a whole.
+ */
+function joinsAtFirstElement(
+  statement: TSNode,
+  first: TSNode | undefined,
+): boolean {
+  if (statement.type === "redirected_statement") return true;
+  if (statement.type === "list") return true;
+  return (
+    statement.type === "pipeline" && first?.type === "redirected_statement"
+  );
+}

package/src/access-intent/bash/parse-view.ts

@@ -0,0 +1,180 @@
+import { parseUnresolvedWithin } from "./parse-health";
+import type { TSNode } from "./parser";
+
+/**
+ * A view of `tree-sitter-bash`'s parse tree that a correction pass can rewrite.
+ *
+ * The grammar hangs command-line material on the wrong node in more than one
+ * production (#977, #979), and each correction is a pass that rewrites the
+ * `redirected_statement`s it recognizes. Each pass builds its nodes from the
+ * primitives here, so a later pass reads an earlier one's output as the same
+ * kind of view and can re-parent its nodes in turn.
+ *
+ * A view reads its text from the source by absolute offsets, so every caller's
+ * `startIndex`/`endIndex` slicing still holds.
+ */
+
+/**
+ * `root` with each `redirected_statement` whose parse resolved replaced by what
+ * `rewrite` returns for it, or `root` itself when nothing beneath it changed.
+ *
+ * The walk is bottom-up: `rewrite` receives the statement's children already
+ * rewritten, and returns `undefined` to leave the statement as it is.
+ *
+ * A statement whose parse failed is never handed to `rewrite`. Its units are
+ * floored already, and moving a node out of an unresolvable region would hand it
+ * a proof in place of that region's refusal to prove one (#814).
+ */
+export function rewriteStatements(
+  root: TSNode,
+  rewrite: (
+    statement: TSNode,
+    children: readonly TSNode[],
+  ) => TSNode | undefined,
+): TSNode {
+  return rewriteBeneath(root, rewrite) ?? root;
+}
+
+/** The rewritten node, or `undefined` when nothing beneath `node` changed. */
+function rewriteBeneath(
+  node: TSNode,
+  rewrite: (
+    statement: TSNode,
+    children: readonly TSNode[],
+  ) => TSNode | undefined,
+): TSNode | undefined {
+  const children: TSNode[] = [];
+  let changed = false;
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    const rewritten = rewriteBeneath(child, rewrite);
+    if (rewritten) changed = true;
+    children.push(rewritten ?? child);
+  }
+
+  if (node.type === "redirected_statement" && !parseUnresolvedWithin(node)) {
+    const rewritten = rewrite(node, children);
+    if (rewritten) return rewritten;
+  }
+  return changed
+    ? adoptingView(node, children, parseUnresolvedWithin(node))
+    : undefined;
+}
+
+/** A node a correction built, reading its text from the statement's source. */
+export function rewrittenNode(
+  original: Pick<TSNode, "type" | "isNamed">,
+  children: readonly TSNode[],
+  startIndex: number,
+  endIndex: number,
+  source: Source,
+): TSNode {
+  return adoptingView(
+    {
+      type: original.type,
+      isNamed: original.isNamed,
+      startIndex,
+      endIndex,
+      text: source(startIndex, endIndex),
+    },
+    children,
+    false,
+  );
+}
+
+/** A slice of the command by absolute offsets. */
+export type Source = (startIndex: number, endIndex: number) => string;
+
+/** The source slicer for every node within `statement`. */
+export function sourceOf(statement: TSNode): Source {
+  return (startIndex, endIndex) =>
+    statement.text.slice(
+      startIndex - statement.startIndex,
+      endIndex - statement.startIndex,
+    );
+}
+
+export function childrenOf(node: TSNode): TSNode[] {
+  const children: TSNode[] = [];
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child) children.push(child);
+  }
+  return children;
+}
+
+export function lastNamedChild(node: TSNode): TSNode | undefined {
+  return childrenOf(node).findLast((child) => child.isNamed);
+}
+
+/**
+ * A view whose children are views too, so each one's `previousSibling` is its
+ * neighbor in the rewritten tree rather than the one the grammar gave it.
+ */
+function adoptingView(
+  fields: NodeFields,
+  children: readonly TSNode[],
+  hasError: boolean,
+): TSNode {
+  return new NodeView(fields, children.map(asView), hasError);
+}
+
+/**
+ * `node` as a view, so a new parent can give it a new previous sibling.
+ *
+ * Its own children stay the grammar's nodes: nothing beneath it moved, so their
+ * siblings are still the grammar's too.
+ */
+function asView(node: TSNode): TSNode {
+  return node instanceof NodeView
+    ? node
+    : new NodeView(node, childrenOf(node), parseUnresolvedWithin(node));
+}
+
+/** The fields a {@link NodeView} copies from the node it stands for. */
+interface NodeFields {
+  readonly type: string;
+  readonly isNamed: boolean;
+  readonly startIndex: number;
+  readonly endIndex: number;
+  readonly text: string;
+}
+
+/**
+ * A parse-tree node a correction presents in place of the grammar's.
+ *
+ * Adopting its children sets each view child's `previousSibling` to the child
+ * before it, which is what lets a redirect moved into a command ask
+ * `parseUnresolvedAt` about its new neighbor.
+ */
+class NodeView implements TSNode {
+  readonly type: string;
+  readonly isNamed: boolean;
+  readonly startIndex: number;
+  readonly endIndex: number;
+  readonly text: string;
+  readonly childCount: number;
+  previousSibling: TSNode | null = null;
+
+  constructor(
+    fields: NodeFields,
+    private readonly children: readonly TSNode[],
+    readonly hasError: boolean,
+  ) {
+    this.type = fields.type;
+    this.isNamed = fields.isNamed;
+    this.startIndex = fields.startIndex;
+    this.endIndex = fields.endIndex;
+    this.text = fields.text;
+    this.childCount = children.length;
+    children.forEach((child, i) => {
+      if (child instanceof NodeView)
+        child.previousSibling = children[i - 1] ?? null;
+    });
+  }
+
+  child(index: number): TSNode | null {
+    return this.children[index] ?? null;
+  }
+}

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

@@ -1,5 +1,6 @@
 import { createRequire } from "node:module";
 import { memoizeAsyncWithRetry } from "./async-cache";
+import { hoistHeredocTails } from "./heredoc-tails";
 import { reattachRedirectArguments } from "./redirect-arguments";
 
 /**
@@ -69,11 +70,19 @@ async function initParser(): Promise<TSParser> {
 /**
  * The parser every consumer reads the bash grammar through.
  *
- * Its trees are the grammar's with one correction applied where they enter the
- * package: a word `tree-sitter-bash` hung on a redirect is handed back to the
- * command it belongs to (`reattachRedirectArguments`, #977). Every walker, the
- * salvage re-parse, and the log masker read that corrected tree, so none of
- * them has to learn the grammar's quirk on its own.
+ * Its trees are the grammar's with two corrections applied where they enter the
+ * package, each moving command-line material `tree-sitter-bash` hangs on a
+ * redirect to where bash gives it:
+ *
+ * 1. `hoistHeredocTails` moves the redirects and the `| …` / `&& …` statement
+ *    written after a heredoc's delimiter out of the heredoc (#979).
+ * 2. `reattachRedirectArguments` hands the words a redirect carries, a file
+ *    redirect's or a heredoc's, back to the command (#977).
+ *
+ * The order matters: a redirect hoisted out of a heredoc can itself carry the
+ * command's words (`cat <<EOF 2>/dev/null arg`), which the second pass then
+ * hands back. Every walker, the salvage re-parse, and the log masker read the
+ * corrected tree, so none of them has to learn the grammar's quirks on its own.
  */
 export const getParser = memoizeAsyncWithRetry(async () =>
   correctingParser(await getGrammarParser()),
@@ -85,7 +94,7 @@ function correctingParser(grammar: TSParser): TSParser {
       const tree = grammar.parse(input);
       if (!tree) return null;
       return {
-        rootNode: reattachRedirectArguments(tree.rootNode),
+        rootNode: reattachRedirectArguments(hoistHeredocTails(tree.rootNode)),
         delete: () => {
           tree.delete();
         },

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

@@ -138,18 +138,49 @@ export function redirectTargetIndex(redirect: TSNode): number | undefined {
  * The child index of the first word the grammar appended after `redirect`'s
  * own target, or `undefined` when none follows.
  *
- * Every named child from there on is a word bash passes to the redirected
- * command rather than a destination of the redirect: `f.txt` in
+ * Every {@link LITERAL_NODE_TYPES} child from there on is a word bash passes to
+ * the redirected command rather than a destination of the redirect: `f.txt` in
  * `grep pat 2>/dev/null f.txt`, and `arg` in `cmd >&- arg`, where the close
  * operator has no target at all (#977).
+ *
+ * A heredoc carries them the same way: `git <<EOF push --force` hangs `push`
+ * and `--force` after its delimiter, where its own target would be. Its body
+ * follows them and is not a word, and neither is any other tail the grammar
+ * lets a heredoc carry (a redirect, a `| …` or `&& …` statement), so the first
+ * child after the target counts only when it is a literal (#979).
  */
 export function trailingArgumentIndex(redirect: TSNode): number | undefined {
   const operator = redirectOperatorIndex(redirect);
   if (operator === undefined) return undefined;
   const target = redirectTargetIndex(redirect);
-  return namedChildIndexAfter(redirect, target ?? operator);
+  const index = namedChildIndexAfter(redirect, target ?? operator);
+  if (index === undefined) return undefined;
+  return LITERAL_NODE_TYPES.has(redirect.child(index)?.type ?? "")
+    ? index
+    : undefined;
 }
 
+/**
+ * The node types `tree-sitter-bash` 0.25.1 parses a literal word as: its
+ * `_literal` rule, which a file redirect's destinations and a heredoc's
+ * trailing words are both declared as.
+ */
+export const LITERAL_NODE_TYPES: ReadonlySet<string> = new Set([
+  "concatenation",
+  "word",
+  "string",
+  "raw_string",
+  "translated_string",
+  "ansi_c_string",
+  "number",
+  "expansion",
+  "simple_expansion",
+  "command_substitution",
+  "process_substitution",
+  "arithmetic_expansion",
+  "brace_expression",
+]);
+
 /** Operators that close a descriptor, naming no file (`>&-`, `<&-`). */
 const CLOSE_OPERATORS: ReadonlySet<string> = new Set([">&-", "<&-"]);
 

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

@@ -1,6 +1,13 @@
-import { parseUnresolvedWithin } from "./parse-health";
+import {
+  childrenOf,
+  lastNamedChild,
+  rewriteStatements,
+  rewrittenNode,
+  type Source,
+  sourceOf,
+} from "./parse-view";
 import type { TSNode } from "./parser";
-import { trailingArgumentIndex } from "./redirect-analysis";
+import { LITERAL_NODE_TYPES, trailingArgumentIndex } from "./redirect-analysis";
 
 /**
  * `tree-sitter-bash`'s parse with each word it hung on a redirect handed back
@@ -21,6 +28,11 @@ import { trailingArgumentIndex } from "./redirect-analysis";
  * followed by its words; a redirect after the last word stays at the
  * statement, and a statement left with no redirect gives way to its body.
  *
+ * A heredoc carries words the same way (`git <<EOF push --force`), and they
+ * move into the command after it; its body stays in the heredoc, which is
+ * written after the words and so ends after them (#979). Every other tail a
+ * heredoc can carry is `heredoc-tails.ts`'s to move.
+ *
  * Three kinds of statement are left exactly as the grammar produced them:
  *
  * - One whose parse failed. Its units are floored already, and moving a word
@@ -35,28 +47,7 @@ import { trailingArgumentIndex } from "./redirect-analysis";
  * stay positions in the command string every caller already slices.
  */
 export function reattachRedirectArguments(root: TSNode): TSNode {
-  return correct(root) ?? root;
-}
-
-/** The corrected node, or `undefined` when nothing beneath `node` changed. */
-function correct(node: TSNode): TSNode | undefined {
-  const children: TSNode[] = [];
-  let changed = false;
-  for (let i = 0; i < node.childCount; i++) {
-    const child = node.child(i);
-    if (!child) continue;
-    const corrected = correct(child);
-    if (corrected) changed = true;
-    children.push(corrected ?? child);
-  }
-
-  if (node.type === "redirected_statement" && !parseUnresolvedWithin(node)) {
-    const reattached = reattachStatement(node, children);
-    if (reattached) return reattached;
-  }
-  return changed
-    ? adoptingView(node, children, parseUnresolvedWithin(node))
-    : undefined;
+  return rewriteStatements(root, reattachStatement);
 }
 
 /**
@@ -74,7 +65,7 @@ function reattachStatement(
 
   const lastCarrier = children.findLastIndex(
     (child) =>
-      child.type === "file_redirect" &&
+      WORD_CARRYING_TYPES.has(child.type) &&
       trailingArgumentIndex(child) !== undefined,
   );
   if (lastCarrier === -1) return undefined;
@@ -112,23 +103,34 @@ function reachesCommand(body: TSNode): boolean {
 /** The bodies whose last element a statement-level redirect belongs to. */
 const GROUPING_TYPES: ReadonlySet<string> = new Set(["list", "pipeline"]);
 
+/** The redirects the grammar can hang a command's words on. */
+const WORD_CARRYING_TYPES: ReadonlySet<string> = new Set([
+  "file_redirect",
+  "heredoc_redirect",
+]);
+
 /**
- * `redirect` as it belongs in the command: truncated after its own target and
- * followed by the words the grammar appended to it. A redirect carrying no
- * words, or a node that is not a file redirect, moves as it is.
+ * `redirect` as it belongs in the command: without the words the grammar
+ * appended to it, and followed by them. A redirect carrying no words, or a node
+ * that cannot carry any, moves as it is.
+ *
+ * A file redirect's words are the rest of its children, so it is truncated
+ * after its target. A heredoc keeps its body and delimiter, which follow the
+ * words in the source, so it keeps its own end.
  */
 function splitRedirect(redirect: TSNode, source: Source): TSNode[] {
-  const trailing =
-    redirect.type === "file_redirect"
-      ? trailingArgumentIndex(redirect)
-      : undefined;
+  const trailing = WORD_CARRYING_TYPES.has(redirect.type)
+    ? trailingArgumentIndex(redirect)
+    : undefined;
   if (trailing === undefined) return [redirect];
 
   const kept: TSNode[] = [];
   const words: TSNode[] = [];
   for (let i = 0; i < redirect.childCount; i++) {
     const child = redirect.child(i);
-    if (child) (i < trailing ? kept : words).push(child);
+    if (!child) continue;
+    const isWord = i >= trailing && LITERAL_NODE_TYPES.has(child.type);
+    (isWord ? words : kept).push(child);
   }
   const end = kept.at(-1)?.endIndex ?? redirect.startIndex;
   return [
@@ -139,8 +141,9 @@ function splitRedirect(redirect: TSNode, source: Source): TSNode[] {
 
 /**
  * `body` with `moved` appended to its rightmost command: the command itself,
- * or the last element of a `list` or `pipeline`, recursively. Each node on the way grows to
- * the end of the last moved node.
+ * or the last element of a `list` or `pipeline`, recursively. Each node on the
+ * way grows to the furthest end among the moved nodes, which is a heredoc's
+ * when one moved, since its body is written after the words that follow it.
  */
 function appendToRightmostCommand(
   body: TSNode,
@@ -148,7 +151,7 @@ function appendToRightmostCommand(
   source: Source,
 ): TSNode {
   const children = childrenOf(body);
-  const end = moved.at(-1)?.endIndex ?? body.endIndex;
+  const end = Math.max(body.endIndex, ...moved.map((node) => node.endIndex));
   if (body.type === "command") {
     return rewrittenNode(
       body,
@@ -166,120 +169,3 @@ function appendToRightmostCommand(
   );
   return rewrittenNode(body, replaced, body.startIndex, end, source);
 }
-
-/** A node the correction built, reading its text from the statement's source. */
-function rewrittenNode(
-  original: TSNode,
-  children: readonly TSNode[],
-  startIndex: number,
-  endIndex: number,
-  source: Source,
-): TSNode {
-  return adoptingView(
-    {
-      type: original.type,
-      isNamed: original.isNamed,
-      startIndex,
-      endIndex,
-      text: source(startIndex, endIndex),
-    },
-    children,
-    false,
-  );
-}
-
-/**
- * A view whose children are views too, so each one's `previousSibling` is its
- * neighbor in the corrected tree rather than the one the grammar gave it.
- */
-function adoptingView(
-  fields: NodeFields,
-  children: readonly TSNode[],
-  hasError: boolean,
-): TSNode {
-  return new NodeView(fields, children.map(asView), hasError);
-}
-
-/** A slice of the command by absolute offsets. */
-type Source = (startIndex: number, endIndex: number) => string;
-
-/** The source slicer for every node within `statement`. */
-function sourceOf(statement: TSNode): Source {
-  return (startIndex, endIndex) =>
-    statement.text.slice(
-      startIndex - statement.startIndex,
-      endIndex - statement.startIndex,
-    );
-}
-
-function childrenOf(node: TSNode): TSNode[] {
-  const children: TSNode[] = [];
-  for (let i = 0; i < node.childCount; i++) {
-    const child = node.child(i);
-    if (child) children.push(child);
-  }
-  return children;
-}
-
-function lastNamedChild(node: TSNode): TSNode | undefined {
-  return childrenOf(node).findLast((child) => child.isNamed);
-}
-
-/**
- * `node` as a view, so a new parent can give it a new previous sibling.
- *
- * Its own children stay the grammar's nodes: nothing beneath it moved, so their
- * siblings are still the grammar's too.
- */
-function asView(node: TSNode): TSNode {
-  return node instanceof NodeView
-    ? node
-    : new NodeView(node, childrenOf(node), parseUnresolvedWithin(node));
-}
-
-/** The fields a {@link NodeView} copies from the node it stands for. */
-interface NodeFields {
-  readonly type: string;
-  readonly isNamed: boolean;
-  readonly startIndex: number;
-  readonly endIndex: number;
-  readonly text: string;
-}
-
-/**
- * A parse-tree node the correction presents in place of the grammar's.
- *
- * Adopting its children sets each view child's `previousSibling` to the child
- * before it, which is what lets a redirect moved into a command ask
- * `parseUnresolvedAt` about its new neighbor.
- */
-class NodeView implements TSNode {
-  readonly type: string;
-  readonly isNamed: boolean;
-  readonly startIndex: number;
-  readonly endIndex: number;
-  readonly text: string;
-  readonly childCount: number;
-  previousSibling: TSNode | null = null;
-
-  constructor(
-    fields: NodeFields,
-    private readonly children: readonly TSNode[],
-    readonly hasError: boolean,
-  ) {
-    this.type = fields.type;
-    this.isNamed = fields.isNamed;
-    this.startIndex = fields.startIndex;
-    this.endIndex = fields.endIndex;
-    this.text = fields.text;
-    this.childCount = children.length;
-    children.forEach((child, i) => {
-      if (child instanceof NodeView)
-        child.previousSibling = children[i - 1] ?? null;
-    });
-  }
-
-  child(index: number): TSNode | null {
-    return this.children[index] ?? null;
-  }
-}

package/src/handlers/before-agent-start.ts

@@ -2,6 +2,7 @@ import type {
   BeforeAgentStartEventResult,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import type { SubagentDetector } from "#src/authority/subagent-detection";
 import { resolveSkillPromptEntries } from "#src/exposure/skill-prompt-sanitizer";
 import {
   type RegisteredTools,
@@ -23,7 +24,8 @@ interface BeforeAgentStartPayload {
    * handler render the session's own tool list instead of editing the one Pi
    * wrote — including in a child, whose inherited identity carries none.
    * `customPrompt` says whether Pi wrote a preamble at all: under one, it
-   * writes no tool surface, so there is nothing of Pi's to remove.
+   * writes no tool surface, so there is nothing of Pi's to remove, and a root
+   * node adds none either.
    * `promptGuidelines` carries rules other extensions added, which removing
    * Pi's own rules section would otherwise drop.
    */
@@ -60,6 +62,9 @@ export function shouldExposeTool(
  *
  * The tool surface is relocated rather than edited in place, so a subagent
  * child's inherited identity stays byte-identical to its parent's (#890).
+ * A root node whose prompt Pi built from a custom one states no tool surface,
+ * matching Pi, which writes none there; a subagent child's prompt is always a
+ * custom one, and it still states its own tools.
  *
  * Constructor deps:
  * - `turnPrep` — brings the node up to date for the turn before anything reads
@@ -68,6 +73,8 @@ export function shouldExposeTool(
  * - `resolver` — owns permission-query surface: `isToolFullyDenied`, skill check
  * - `toolRegistry` — Pi tool API subset (getAll + getActive + setActive)
  * - `logger` — records each change to the effective tool surface
+ * - `detector` — tells a subagent child from a root, which decides whether a
+ *   custom prompt gets this node's 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).
@@ -79,6 +86,7 @@ export class AgentPrepHandler {
     private readonly resolver: PermissionResolver,
     private readonly toolRegistry: ToolRegistry,
     private readonly logger: DebugLogger,
+    private readonly detector: SubagentDetector,
   ) {}
 
   // eslint-disable-next-line @typescript-eslint/require-await
@@ -108,15 +116,15 @@ export class AgentPrepHandler {
       });
     }
 
-    const toolSurfacePrompt = renderToolSurface(event.systemPrompt, {
-      allowedTools,
-      toolSnippets: event.systemPromptOptions?.toolSnippets ?? {},
-      guidelinesByTool: registered.guidelinesByTool,
-      promptGuidelines: event.systemPromptOptions?.promptGuidelines ?? [],
-      // Pi's own `if (customPrompt)` test, so an empty string reads here the
-      // way it reads there: as no custom prompt at all.
-      piAuthoredPreamble: !event.systemPromptOptions?.customPrompt,
-    });
+    const toolSurfacePrompt = this.statesOwnToolSurface(event, ctx)
+      ? renderToolSurface(event.systemPrompt, {
+          allowedTools,
+          toolSnippets: event.systemPromptOptions?.toolSnippets ?? {},
+          guidelinesByTool: registered.guidelinesByTool,
+          promptGuidelines: event.systemPromptOptions?.promptGuidelines ?? [],
+          piAuthoredPreamble: !hasCustomPrompt(event),
+        })
+      : event.systemPrompt;
     const skillPromptResult = resolveSkillPromptEntries(
       toolSurfacePrompt,
       this.resolver,
@@ -129,6 +137,21 @@ export class AgentPrepHandler {
       : {};
   }
 
+  /**
+   * Whether this node renders its own tool surface into the prompt.
+   *
+   * Every node does except a root whose prompt Pi built from a custom one:
+   * there Pi writes no tool list or rules, and the operator's prompt is left
+   * as Pi built it. A subagent child's prompt is always a custom one, and its
+   * inherited identity carries no tool list, so it still states its own.
+   */
+  private statesOwnToolSurface(
+    event: BeforeAgentStartPayload,
+    ctx: ExtensionContext,
+  ): boolean {
+    return !hasCustomPrompt(event) || this.detector.isSubagent(ctx);
+  }
+
   private observeToolSurface(
     registered: RegisteredTools,
   ): ToolSurfaceObservation {
@@ -138,3 +161,11 @@ export class AgentPrepHandler {
     };
   }
 }
+
+/**
+ * Whether Pi built the prompt from a custom one, by Pi's own `if (customPrompt)`
+ * test, so an empty string reads here the way it reads there: as none.
+ */
+function hasCustomPrompt(event: BeforeAgentStartPayload): boolean {
+  return Boolean(event.systemPromptOptions?.customPrompt);
+}

package/src/index.ts

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