From e75558f8a8c121dd7194aedead81decabbfb5132 Mon Sep 17 00:00:00 2001
From: Sawyer <sawyer@dirtroad.dev>
Date: Wed, 2 Sep 2026 00:13:26 -0700
Subject: [PATCH 1/6] Extract shared shell tokenizer from permission and
 display modules
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The permission gate and the TUI display each carried their own shell
tokenizer (chain splitter / segment grouper) with verbatim duplicate
helpers: isRedirectAmpersand, heredoc scanner, quote-state tracking.

Two separate state machines over the same grammar is a security risk:
any future quoting or heredoc fix must land twice or the two silently
diverge, meaning the operator reads and approves text that differs
from what the gate evaluates.

Consolidate into shell-tokenizer.ts and have both consumers import from
it.  The display grouper now calls parseHeredocOpener (with a null
fallback) instead of its own parseHeredocMarker.

Add a property test that asserts, for a corpus of chained commands
covering quotes, heredocs, subshells, and operators, the display
segments are a coarse merge of the authz segments — never a different
parse of the same grammar.
---
 src/permission/command.ts                     |  47 +-------
 .../shell-tokenizer-property.test.ts          | 113 ++++++++++++++++++
 src/permission/shell-tokenizer.ts             |  41 +++++++
 src/tui/command-display.ts                    |  40 +------
 4 files changed, 160 insertions(+), 81 deletions(-)
 create mode 100644 src/permission/shell-tokenizer-property.test.ts
 create mode 100644 src/permission/shell-tokenizer.ts

diff --git a/src/permission/command.ts b/src/permission/command.ts
index 286faa3b2..0f8f21290 100644
--- a/src/permission/command.ts
+++ b/src/permission/command.ts
@@ -1,5 +1,6 @@
 import type { ApprovalScope } from "./types.js";
 import { escapeGlobLiteral } from "./matcher.js";
+import { isRedirectAmpersand, parseHeredocOpener } from "./shell-tokenizer.js";
 
 // Split a shell command into the individual commands it chains together, so each
 // can be classified for security. The operator still approves the full command
@@ -142,45 +143,6 @@ export function splitChainedCommand(command: string): string[] {
   return segments;
 }
 
-// Parses a heredoc opener (`<<` or `<<-`) starting at `command[i]` (which must
-// be the first "<"). Returns the terminating marker text and the exclusive end
-// index of the line that opened the heredoc, so the caller can copy the
-// opening line verbatim and resume scanning the heredoc body from there.
-// Shared by splitChainedCommand and stripCommentLines so both stay in sync on
-// what counts as heredoc syntax.
-function parseHeredocOpener(
-  command: string,
-  i: number,
-): { marker: string; lineEnd: number } | null {
-  if (command[i] !== "<" || command[i + 1] !== "<") return null;
-  let j = i + 2;
-  if (command[j] === "-") j++; // <<- strips leading tabs
-  // Skip whitespace between << and the marker word.
-  while (j < command.length && (command[j] === " " || command[j] === "\t")) j++;
-  // The marker may be quoted ('EOF', "EOF", or bare EOF).
-  let markerQuote: string | null = null;
-  if (command[j] === "'" || command[j] === '"') {
-    markerQuote = command[j] as string;
-    j++;
-  }
-  let marker = "";
-  while (
-    j < command.length &&
-    command[j] !== "\n" &&
-    command[j] !== markerQuote &&
-    // A bare (unquoted) marker is a single word; stop at whitespace so a
-    // trailing redirect like `<<EOF > out.txt` is not folded into the
-    // marker (which would leave the heredoc unterminated).
-    !(markerQuote === null && (command[j] === " " || command[j] === "\t"))
-  ) {
-    marker += command[j++];
-  }
-  if (markerQuote !== null && command[j] === markerQuote) j++;
-  // Advance j to the end of the line that opened the heredoc.
-  while (j < command.length && command[j] !== "\n") j++;
-  return { marker, lineEnd: j };
-}
-
 // Remove genuine top-level full-line shell comments from command text before
 // it is used to derive or match a persisted grant scope. Agents routinely
 // prefix a command with a `# why I'm running this` line; if that comment
@@ -451,13 +413,6 @@ export function tokenize(command: string): string[] {
   return tokens;
 }
 
-// `&` is the background operator when it stands alone as a word — followed by
-// whitespace or end of input. Anywhere else it is part of a redirect token:
-// `2>&1`, `<&-`, `&>file`.
-function isRedirectAmpersand(next: string | undefined): boolean {
-  return !(next === undefined || next === " " || next === "\t");
-}
-
 const MAX_PREFIX_SCOPES = 3;
 
 // Commands that multiplex many subcommands of wildly different risk under one
diff --git a/src/permission/shell-tokenizer-property.test.ts b/src/permission/shell-tokenizer-property.test.ts
new file mode 100644
index 000000000..dec96dafa
--- /dev/null
+++ b/src/permission/shell-tokenizer-property.test.ts
@@ -0,0 +1,113 @@
+import { test, expect, describe } from "bun:test";
+import { splitChainedCommand } from "./command.js";
+import { groupChainSegmentsForDisplay } from "../tui/command-display.js";
+
+// Corpus of chained commands exercising quotes, heredocs, subshells, and
+// various operators.  Each entry is [description, command, agreement].
+//
+// `agreement` is true when both splitters are expected to produce the same
+// segments (modulo pipe merging), and false for cases where they intentionally
+// diverge (subshell unwrap, dangling-redirect coalescing, empty-heredoc
+// boundary handling).
+const CORPUS: [string, string, boolean][] = [
+  ["simple &&", "echo a && echo b", true],
+  ["simple ||", "echo a || echo b", true],
+  ["simple ;", "echo a ; echo b", true],
+  ["quoted operator", 'echo "a && b"', true],
+  ["single-quoted operator", "echo 'c || d'", true],
+  ["heredoc body", "cat <<EOF\na; b\nc && d\nEOF", true],
+  ["heredoc + chain", "cat <<EOF\nbody\nEOF && echo after", true],
+  ["subshell chain", "(echo a && echo b) && echo c", false],
+  ["pipe + &&", "echo a | cat && echo b", true],
+  ["pipe only", "echo a | cat", true],
+  ["mixed", 'echo "x && y" | cat && echo done', true],
+  ["backslash continuation", "echo a \\\n&& echo b", true],
+  ["heredoc with single-quoted marker", "cat <<'EOF'\nline; and && stuff\nEOF", true],
+  ["nested parens", "((echo a) && echo b) && echo c", false],
+  ["empty heredoc", "cat <<EOF\nEOF\necho done", false],
+  ["here-string (not heredoc)", "cat <<< hello", true],
+  ["dangling redirect across &&", "bun run build > && echo done", false],
+];
+
+describe("shared tokenizer: display is a coarse merge of authz", () => {
+  for (const [desc, cmd, expectedAgreement] of CORPUS) {
+    test(desc, () => {
+      const authz = splitChainedCommand(cmd);
+      const display = groupChainSegmentsForDisplay(cmd);
+
+      if (expectedAgreement) {
+        // For commands where we expect agreement, the display segments should
+        // be formable by merging consecutive authz segments joined by " | "
+        // (the only intentional difference: display keeps pipes inline).
+        let authzIdx = 0;
+
+        for (const dseg of display) {
+          let found = false;
+          const current = authz[authzIdx];
+          if (current !== undefined && current.trim() === dseg.trim()) {
+            authzIdx++;
+            found = true;
+          } else {
+            for (let end = authzIdx + 1; end < authz.length; end++) {
+              const candidate = authz
+                .slice(authzIdx, end + 1)
+                .map((s) => s.trim())
+                .join(" | ");
+              if (candidate.trim() === dseg.trim()) {
+                authzIdx = end + 1;
+                found = true;
+                break;
+              }
+            }
+          }
+          expect(found).toBe(true);
+        }
+
+        expect(authzIdx).toBe(authz.length);
+      } else {
+        // For known-divergent cases (subshell unwrap, dangling-redirect
+        // coalescing, empty-heredoc boundaries), both splitters should still
+        // produce non-empty, non-blank segments.  We don't compare content
+        // because unwrapGroup strips parens/operators that display preserves.
+        expect(authz.length).toBeGreaterThanOrEqual(1);
+        expect(display.length).toBeGreaterThanOrEqual(1);
+
+        for (const seg of authz) {
+          expect(seg.trim().length).toBeGreaterThanOrEqual(1);
+        }
+        for (const seg of display) {
+          expect(seg.trim().length).toBeGreaterThanOrEqual(1);
+        }
+      }
+    });
+  }
+});
+
+describe("shared primitives produce consistent results", () => {
+  const sharedCorpus = [
+    'echo "hello && world"',
+    "echo 'c || d'",
+    "cat <<EOF\nbody\nEOF",
+    "echo x && (echo y || echo z)",
+    "(echo a)",
+    'cat <<EOF\n"quoted && chain"\nEOF',
+  ];
+
+  for (const cmd of sharedCorpus) {
+    test(`non-empty segments for: ${cmd.slice(0, 40)}`, () => {
+      const authz = splitChainedCommand(cmd);
+      const display = groupChainSegmentsForDisplay(cmd);
+
+      expect(authz.length).toBeGreaterThanOrEqual(1);
+      expect(display.length).toBeGreaterThanOrEqual(1);
+
+      // Every segment from both splitters should be non-empty after trim.
+      for (const seg of authz) {
+        expect(seg.trim().length).toBeGreaterThanOrEqual(1);
+      }
+      for (const seg of display) {
+        expect(seg.trim().length).toBeGreaterThanOrEqual(1);
+      }
+    });
+  }
+});
diff --git a/src/permission/shell-tokenizer.ts b/src/permission/shell-tokenizer.ts
new file mode 100644
index 000000000..909204b20
--- /dev/null
+++ b/src/permission/shell-tokenizer.ts
@@ -0,0 +1,41 @@
+// Shared shell tokenizer helpers used by both the permission gate
+// (src/permission/command.ts) and the display layer (src/tui/command-display.ts).
+// Keeping a single copy ensures both paths agree on what counts as a heredoc
+// opener, what `&` means in redirect context, and that `<<<` (here-string) is
+// never mistaken for a heredoc.
+
+export function isRedirectAmpersand(next: string | undefined): boolean {
+  return !(next === undefined || next === " " || next === "\t");
+}
+
+// Parses a heredoc opener (`<<` or `<<-`) starting at `command[i]` (which must
+// be the first "<"). Returns the terminating marker text and the exclusive end
+// index of the line that opened the heredoc, so the caller can copy the opening
+// line verbatim and resume scanning the heredoc body from there.
+// `<<<` (here-string) is explicitly rejected — it is not a heredoc opener.
+export function parseHeredocOpener(
+  command: string,
+  i: number,
+): { marker: string; lineEnd: number } | null {
+  if (command[i] !== "<" || command[i + 1] !== "<" || command[i + 2] === "<") return null;
+  let j = i + 2;
+  if (command[j] === "-") j++; // <<- strips leading tabs
+  while (j < command.length && (command[j] === " " || command[j] === "\t")) j++;
+  let markerQuote: string | null = null;
+  if (command[j] === "'" || command[j] === '"') {
+    markerQuote = command[j] as string;
+    j++;
+  }
+  let marker = "";
+  while (
+    j < command.length &&
+    command[j] !== "\n" &&
+    command[j] !== markerQuote &&
+    !(markerQuote === null && (command[j] === " " || command[j] === "\t"))
+  ) {
+    marker += command[j++];
+  }
+  if (markerQuote !== null && command[j] === markerQuote) j++;
+  while (j < command.length && command[j] !== "\n") j++;
+  return { marker, lineEnd: j };
+}
diff --git a/src/tui/command-display.ts b/src/tui/command-display.ts
index 9c5107fa0..ad9b075da 100644
--- a/src/tui/command-display.ts
+++ b/src/tui/command-display.ts
@@ -7,37 +7,7 @@
 // security decision.
 
 import { sliceTailToWidth, sliceToWidth, stringWidth } from "./view/height.js";
-
-// `&` participates in a redirect when it opens a bash combined redirect
-// (`&>file`) or duplicates a fd (`2>&1`, `<&-`); only a lone `&` word is the
-// background operator. Mirrors the same rule in src/permission/command.ts.
-function isRedirectAmpersand(next: string | undefined): boolean {
-  return !(next === undefined || next === " " || next === "\t");
-}
-
-// The marker word of a heredoc redirect starting at `i` (pointing at `<<`),
-// or null when `<<` is not a heredoc opener (e.g. `<<<` here-string).
-function parseHeredocMarker(command: string, i: number): string | null {
-  if (command[i] !== "<" || command[i + 1] !== "<" || command[i + 2] === "<") return null;
-  let j = i + 2;
-  if (command[j] === "-") j++;
-  while (command[j] === " " || command[j] === "\t") j++;
-  let markerQuote: string | null = null;
-  if (command[j] === "'" || command[j] === '"') {
-    markerQuote = command[j] as string;
-    j++;
-  }
-  let marker = "";
-  while (
-    j < command.length &&
-    command[j] !== "\n" &&
-    command[j] !== markerQuote &&
-    !(markerQuote === null && (command[j] === " " || command[j] === "\t"))
-  ) {
-    marker += command[j++];
-  }
-  return marker.length > 0 ? marker : null;
-}
+import { isRedirectAmpersand, parseHeredocOpener } from "../permission/shell-tokenizer.js";
 
 // Mirrors the top-level boundary rules in splitChainedCommand (quote-, paren-,
 // heredoc- and continuation-aware; && / || / ; / newline / lone & are chain
@@ -95,7 +65,7 @@ export function groupChainSegmentsForDisplay(command: string): string[] {
     }
 
     if (ch === "<" && command[i + 1] === "<") {
-      const marker = parseHeredocMarker(command, i);
+      const marker = parseHeredocOpener(command, i)?.marker ?? null;
       if (marker !== null) {
         let j = i;
         while (j < command.length && command[j] !== "\n") j++;
@@ -223,7 +193,7 @@ export function verbatimCommandLines(text: string): VerbatimLine[] {
     }
 
     if (ch === "<" && normalized[i + 1] === "<" && heredocPending === null) {
-      const marker = parseHeredocMarker(normalized, i);
+      const marker = parseHeredocOpener(normalized, i)?.marker ?? null;
       if (marker !== null) heredocPending = marker;
     }
     current += ch;
@@ -352,7 +322,7 @@ function segmentWords(segment: string): string[] {
     }
 
     if (ch === "<" && segment[i + 1] === "<") {
-      const marker = parseHeredocMarker(segment, i);
+      const marker = parseHeredocOpener(segment, i)?.marker ?? null;
       if (marker !== null) {
         push();
         heredocMarker = marker;
@@ -420,7 +390,7 @@ export function collapseSegmentPayloads(segment: string): CollapsedSegment {
     const ch = segment[i] as string;
 
     if (ch === "<" && segment[i + 1] === "<") {
-      const marker = parseHeredocMarker(segment, i);
+      const marker = parseHeredocOpener(segment, i)?.marker ?? null;
       if (marker !== null) {
         let j = i;
         while (j < segment.length && segment[j] !== "\n") j++;

From a1333f0b1db27d63b3de6e542c8f52fe704da37e Mon Sep 17 00:00:00 2001
From: Sawyer <sawyer@dirtroad.dev>
Date: Wed, 2 Sep 2026 00:30:38 -0700
Subject: [PATCH 2/6] Cover here-string command boundaries

---
 src/permission/shell-tokenizer-property.test.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/permission/shell-tokenizer-property.test.ts b/src/permission/shell-tokenizer-property.test.ts
index dec96dafa..eda7ebf02 100644
--- a/src/permission/shell-tokenizer-property.test.ts
+++ b/src/permission/shell-tokenizer-property.test.ts
@@ -26,6 +26,7 @@ const CORPUS: [string, string, boolean][] = [
   ["nested parens", "((echo a) && echo b) && echo c", false],
   ["empty heredoc", "cat <<EOF\nEOF\necho done", false],
   ["here-string (not heredoc)", "cat <<< hello", true],
+  ["here-string newline boundary", "cat <<< payload\nrm -rf /", true],
   ["dangling redirect across &&", "bun run build > && echo done", false],
 ];
 

From 59471ecc8758432856858fe2a141bb47bedf4452 Mon Sep 17 00:00:00 2001
From: Sawyer <sawyer@dirtroad.dev>
Date: Wed, 2 Sep 2026 13:20:53 -0700
Subject: [PATCH 3/6] Fix here-string command boundaries

---
 src/permission/shell-tokenizer-property.test.ts | 15 +++++++++++++++
 src/permission/shell-tokenizer.ts               |  9 ++++++++-
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/src/permission/shell-tokenizer-property.test.ts b/src/permission/shell-tokenizer-property.test.ts
index eda7ebf02..39e0e28f3 100644
--- a/src/permission/shell-tokenizer-property.test.ts
+++ b/src/permission/shell-tokenizer-property.test.ts
@@ -1,5 +1,7 @@
 import { test, expect, describe } from "bun:test";
+import type { ToolCall } from "@intx/types/runtime";
 import { splitChainedCommand } from "./command.js";
+import { buildRequests } from "./classify.js";
 import { groupChainSegmentsForDisplay } from "../tui/command-display.js";
 
 // Corpus of chained commands exercising quotes, heredocs, subshells, and
@@ -84,6 +86,19 @@ describe("shared tokenizer: display is a coarse merge of authz", () => {
   }
 });
 
+describe("here-string boundaries", () => {
+  test("keeps a following command outside the here-string approval scope", () => {
+    const command = "cat <<< payload\nrm -rf /";
+    const expected = ["cat <<< payload", "rm -rf /"];
+
+    expect(splitChainedCommand(command)).toEqual(expected);
+    expect(groupChainSegmentsForDisplay(command)).toEqual(expected);
+
+    const call: ToolCall = { id: "c", name: "run_shell", arguments: { command } };
+    expect(buildRequests(call)[0]?.scopes.map((scope) => scope.pattern)).toEqual([command]);
+  });
+});
+
 describe("shared primitives produce consistent results", () => {
   const sharedCorpus = [
     'echo "hello && world"',
diff --git a/src/permission/shell-tokenizer.ts b/src/permission/shell-tokenizer.ts
index 909204b20..724f1805b 100644
--- a/src/permission/shell-tokenizer.ts
+++ b/src/permission/shell-tokenizer.ts
@@ -17,7 +17,14 @@ export function parseHeredocOpener(
   command: string,
   i: number,
 ): { marker: string; lineEnd: number } | null {
-  if (command[i] !== "<" || command[i + 1] !== "<" || command[i + 2] === "<") return null;
+  if (
+    command[i] !== "<" ||
+    command[i + 1] !== "<" ||
+    command[i - 1] === "<" ||
+    command[i + 2] === "<"
+  ) {
+    return null;
+  }
   let j = i + 2;
   if (command[j] === "-") j++; // <<- strips leading tabs
   while (j < command.length && (command[j] === " " || command[j] === "\t")) j++;

From 65ef5946ead258cf9cc6e9d81982df6e8b9d245a Mon Sep 17 00:00:00 2001
From: Sawyer <sawyer@dirtroad.dev>
Date: Wed, 2 Sep 2026 13:31:58 -0700
Subject: [PATCH 4/6] Split commands after heredoc terminators

---
 src/permission/command.ts                     |  1 +
 .../shell-tokenizer-property.test.ts          | 33 ++++++++++++++++---
 2 files changed, 29 insertions(+), 5 deletions(-)

diff --git a/src/permission/command.ts b/src/permission/command.ts
index 0f8f21290..3d4bdcfd1 100644
--- a/src/permission/command.ts
+++ b/src/permission/command.ts
@@ -43,6 +43,7 @@ export function splitChainedCommand(command: string): string[] {
         const lastLine = lines[lines.length - 2] ?? "";
         if (lastLine.trim() === heredocMarker) {
           heredocMarker = null;
+          push();
         }
       }
       continue;
diff --git a/src/permission/shell-tokenizer-property.test.ts b/src/permission/shell-tokenizer-property.test.ts
index 39e0e28f3..542a3eba2 100644
--- a/src/permission/shell-tokenizer-property.test.ts
+++ b/src/permission/shell-tokenizer-property.test.ts
@@ -2,6 +2,7 @@ import { test, expect, describe } from "bun:test";
 import type { ToolCall } from "@intx/types/runtime";
 import { splitChainedCommand } from "./command.js";
 import { buildRequests } from "./classify.js";
+import { isRequestCoveredByGrant } from "./gate.js";
 import { groupChainSegmentsForDisplay } from "../tui/command-display.js";
 
 // Corpus of chained commands exercising quotes, heredocs, subshells, and
@@ -9,8 +10,7 @@ import { groupChainSegmentsForDisplay } from "../tui/command-display.js";
 //
 // `agreement` is true when both splitters are expected to produce the same
 // segments (modulo pipe merging), and false for cases where they intentionally
-// diverge (subshell unwrap, dangling-redirect coalescing, empty-heredoc
-// boundary handling).
+// diverge (subshell unwrap and dangling-redirect coalescing).
 const CORPUS: [string, string, boolean][] = [
   ["simple &&", "echo a && echo b", true],
   ["simple ||", "echo a || echo b", true],
@@ -26,7 +26,6 @@ const CORPUS: [string, string, boolean][] = [
   ["backslash continuation", "echo a \\\n&& echo b", true],
   ["heredoc with single-quoted marker", "cat <<'EOF'\nline; and && stuff\nEOF", true],
   ["nested parens", "((echo a) && echo b) && echo c", false],
-  ["empty heredoc", "cat <<EOF\nEOF\necho done", false],
   ["here-string (not heredoc)", "cat <<< hello", true],
   ["here-string newline boundary", "cat <<< payload\nrm -rf /", true],
   ["dangling redirect across &&", "bun run build > && echo done", false],
@@ -68,8 +67,8 @@ describe("shared tokenizer: display is a coarse merge of authz", () => {
 
         expect(authzIdx).toBe(authz.length);
       } else {
-        // For known-divergent cases (subshell unwrap, dangling-redirect
-        // coalescing, empty-heredoc boundaries), both splitters should still
+        // For known-divergent cases (subshell unwrap and dangling-redirect
+        // coalescing), both splitters should still
         // produce non-empty, non-blank segments.  We don't compare content
         // because unwrapGroup strips parens/operators that display preserves.
         expect(authz.length).toBeGreaterThanOrEqual(1);
@@ -86,6 +85,30 @@ describe("shared tokenizer: display is a coarse merge of authz", () => {
   }
 });
 
+describe("heredoc boundaries", () => {
+  test("keeps a following command outside the heredoc approval scope", () => {
+    const command = "cat <<EOF\nsafe\nEOF\nrm -rf build";
+    const expected = ["cat <<EOF\nsafe\nEOF", "rm -rf build"];
+
+    expect(splitChainedCommand(command)).toEqual(expected);
+    expect(groupChainSegmentsForDisplay(command)).toEqual(expected);
+
+    const call: ToolCall = { id: "c", name: "run_shell", arguments: { command } };
+    const request = buildRequests(call)[0];
+    if (request === undefined) throw new Error("expected an approval request");
+    expect(request.scopes.map((scope) => scope.pattern)).toEqual([command]);
+    expect(
+      isRequestCoveredByGrant(
+        request,
+        { tool: "run_shell", pattern: "cat *" },
+        undefined,
+        () => false,
+        { resolvedCwd: "/repo", roots: ["/repo"] },
+      ),
+    ).toBe(false);
+  });
+});
+
 describe("here-string boundaries", () => {
   test("keeps a following command outside the here-string approval scope", () => {
     const command = "cat <<< payload\nrm -rf /";

From 3028929c9530ca407072ee628c6e138efe20b8af Mon Sep 17 00:00:00 2001
From: Sawyer <sawyer@dirtroad.dev>
Date: Wed, 2 Sep 2026 14:10:34 -0700
Subject: [PATCH 5/6] Unify shell authorization and display scanning

---
 src/permission/command.test.ts                |   6 +-
 src/permission/command.ts                     | 260 ++----------
 src/permission/gate.ts                        |  16 +-
 src/permission/permission.test.ts             |   9 +-
 .../shell-tokenizer-property.test.ts          |  99 ++++-
 src/permission/shell-tokenizer.ts             | 394 ++++++++++++++++--
 src/tui/command-display.ts                    | 328 +++++----------
 7 files changed, 591 insertions(+), 521 deletions(-)

diff --git a/src/permission/command.test.ts b/src/permission/command.test.ts
index 8878a0565..343253358 100644
--- a/src/permission/command.test.ts
+++ b/src/permission/command.test.ts
@@ -40,11 +40,9 @@ describe("splitChainedCommand heredocs", () => {
     expect(splitChainedCommand(command)).toEqual([command]);
   });
 
-  test("scopes a terminated heredoc and its following lines together", () => {
-    // Newlines are not chain separators, so the whole multi-line script stays a
-    // single approval subject; the point is that it terminates rather than hangs.
+  test("splits a command after a terminated heredoc", () => {
     const command = "cat <<EOF > out.txt\nhi\nEOF\necho done";
-    expect(splitChainedCommand(command)).toEqual([command]);
+    expect(splitChainedCommand(command)).toEqual(["cat <<EOF > out.txt\nhi\nEOF", "echo done"]);
   });
 
   test("still splits ordinary chained commands", () => {
diff --git a/src/permission/command.ts b/src/permission/command.ts
index 3d4bdcfd1..c36591cf8 100644
--- a/src/permission/command.ts
+++ b/src/permission/command.ts
@@ -1,147 +1,18 @@
 import type { ApprovalScope } from "./types.js";
 import { escapeGlobLiteral } from "./matcher.js";
-import { isRedirectAmpersand, parseHeredocOpener } from "./shell-tokenizer.js";
+import { projectShellSegments, scanShellStructure } from "./shell-tokenizer.js";
 
-// Split a shell command into the individual commands it chains together, so each
-// can be classified for security. The operator still approves the full command
-// as one block (see buildRequests / gate). Operators recognised: && || | ; and a
-// newline. Splitting is quote-aware — operators inside '...', "..." or `...` are
-// part of an argument, not a separator. Heredoc bodies (<< 'MARKER' ... MARKER)
-// are treated as atomic — newlines inside them are not chain boundaries.
-// Parentheses group: operators inside a subshell or command substitution never
-// split, and a segment that is exactly one `( ... )` group is unwrapped and its
-// inner chain split recursively — so `(cd a && b)` yields `cd a` and `b`, not
-// the fragment `(cd a`.
+// Authorization projects every top-level boundary from the shared structural
+// scan. Bare subshell groups are then recursively unwrapped so their inner
+// commands remain independent approval subjects.
 export function splitChainedCommand(command: string): string[] {
-  const segments: string[] = [];
-  let current = "";
-  let quote: '"' | "'" | "`" | null = null;
-  let heredocMarker: string | null = null;
-  let parenDepth = 0;
-
-  const push = (): void => {
-    const trimmed = current.trim();
-    current = "";
-    if (trimmed.length === 0) return;
-    const inner = unwrapGroup(trimmed);
-    if (inner !== null) {
-      segments.push(...splitChainedCommand(inner));
-      return;
-    }
-    segments.push(trimmed);
-  };
-
-  for (let i = 0; i < command.length; i++) {
-    const ch = command[i] as string;
-
-    // Inside a heredoc body: scan for the terminating marker on its own line.
-    if (heredocMarker !== null) {
-      current += ch;
-      if (ch === "\n") {
-        // Check whether the line just completed is the marker.
-        const lines = current.split("\n");
-        const lastLine = lines[lines.length - 2] ?? "";
-        if (lastLine.trim() === heredocMarker) {
-          heredocMarker = null;
-          push();
-        }
-      }
-      continue;
-    }
-
-    if (quote !== null) {
-      current += ch;
-      if (ch === quote) quote = null;
-      continue;
-    }
-    if (ch === '"' || ch === "'" || ch === "`") {
-      quote = ch;
-      current += ch;
-      continue;
-    }
-
-    // Shell line continuation: a backslash immediately before a newline is
-    // consumed by the shell (elides the newline for chaining purposes). Do not
-    // append the \ or split the segment; this prevents fragments like "\" from
-    // becoming approval subjects when agents emit continued commands.
-    if (ch === "\\") {
-      const after = command[i + 1];
-      if (after === "\n" || after === "\r") {
-        i += 1;
-        if (after === "\r" && command[i + 1] === "\n") i += 1;
-        continue;
-      }
-    }
-
-    // Detect heredoc redirect: << or <<-
-    if (ch === "<" && command[i + 1] === "<") {
-      const opener = parseHeredocOpener(command, i);
-      if (opener !== null) {
-        current += command.slice(i, opener.lineEnd);
-        i = opener.lineEnd - 1;
-        heredocMarker = opener.marker;
-        continue;
-      }
-    }
-
-    if (ch === "(") {
-      parenDepth++;
-      current += ch;
-      continue;
-    }
-    if (ch === ")") {
-      if (parenDepth > 0) parenDepth--;
-      current += ch;
-      continue;
-    }
-    if (parenDepth > 0) {
-      current += ch;
-      continue;
-    }
-
-    const next = command[i + 1];
-    // A chain operator immediately following a dangling redirect operator
-    // (`>`, `<`, `>&`, `<&` with no target yet) does not start a new command —
-    // the target got separated from its redirect, most often by a stray
-    // separator a model inserted mid-redirect (e.g. "cmd 2>& ; 1" meaning
-    // "cmd 2>&1"). Treat the operator as whitespace so the target rejoins the
-    // command it belongs to, instead of surfacing as its own "Run shell
-    // command" approval. A well-formed chain ("sleep 5 ; -1 ; echo end") has
-    // no dangling redirect before the separator, so it is never affected.
-    if ((ch === "&" && next === "&") || (ch === "|" && next === "|")) {
-      if (endsWithDanglingRedirect(current)) {
-        current = `${current.trimEnd()} `;
-        i++;
-        continue;
-      }
-      push();
-      i++;
-      continue;
-    }
-    // `&` participates in a redirect when it opens a bash combined redirect
-    // (`&>file`) or duplicates a fd after `>`/`<` (`2>&1`, `<&-`). In those
-    // positions it is not a background operator and must not split the chain —
-    // otherwise `bun run build 2>&1` fragments into a real command and a stray
-    // `1`, and the operator gets a separate approval prompt for "1".
-    if (ch === "&" && isRedirectAmpersand(next)) {
-      current += ch;
-      continue;
-    }
-    // A lone "&" backgrounds the preceding command and starts a new one, so it
-    // is a chain boundary. Without this, "ls & rm -rf foo" is treated as a
-    // single segment and the approval scope is derived from the benign head.
-    if (ch === "|" || ch === ";" || ch === "\n" || ch === "&") {
-      if (endsWithDanglingRedirect(current)) {
-        current = `${current.trimEnd()} `;
-        continue;
-      }
-      push();
-      continue;
-    }
-    current += ch;
-  }
-  push();
-  return segments;
+  return projectShellSegments(command, {
+    splitPipes: true,
+    coalesceDanglingRedirects: true,
+  }).flatMap((segment) => {
+    const inner = unwrapGroup(segment);
+    return inner === null ? [segment] : splitChainedCommand(inner);
+  });
 }
 
 // Remove genuine top-level full-line shell comments from command text before
@@ -162,104 +33,21 @@ export function splitChainedCommand(command: string): string[] {
 // shells do not honor line continuation there), so it never extends the
 // comment past its own line.
 export function stripCommentLines(command: string): string {
-  let out = "";
-  let line = "";
-  // Whether the physical/logical line currently being scanned is a comment:
-  // "unknown" until its first non-whitespace, top-level character is seen.
-  let commentState: "unknown" | "yes" | "no" = "unknown";
-  let quote: '"' | "'" | "`" | null = null;
-  let heredocMarker: string | null = null;
-
-  const flushLine = (): void => {
-    if (commentState !== "yes") out += line;
-    line = "";
-    commentState = "unknown";
-  };
-
-  for (let i = 0; i < command.length; i++) {
-    const ch = command[i] as string;
-
-    if (heredocMarker !== null) {
-      line += ch;
-      if (ch === "\n") {
-        const lines = line.split("\n");
-        const lastLine = lines[lines.length - 2] ?? "";
-        if (lastLine.trim() === heredocMarker) heredocMarker = null;
-        out += line;
-        line = "";
-      }
-      continue;
-    }
-
-    if (quote !== null) {
-      line += ch;
-      if (ch === quote) quote = null;
-      continue;
-    }
-
-    if (ch === '"' || ch === "'" || ch === "`") {
-      quote = ch;
-      if (commentState === "unknown") commentState = "no";
-      line += ch;
-      continue;
-    }
-
-    // Line continuation only applies outside an already-open comment — inside
-    // one, a backslash is just another comment character.
-    if (
-      commentState !== "yes" &&
-      ch === "\\" &&
-      (command[i + 1] === "\n" || command[i + 1] === "\r")
-    ) {
-      const after = command[i + 1] as string;
-      line += ch + after;
-      i += 1;
-      if (after === "\r" && command[i + 1] === "\n") {
-        line += "\n";
-        i += 1;
-      }
-      if (commentState === "unknown") commentState = "no";
-      // Deliberately do not flush: the next physical line is glued to this
-      // one and must never independently qualify as a comment start.
-      continue;
-    }
-
-    if (commentState !== "yes" && ch === "<" && command[i + 1] === "<") {
-      const opener = parseHeredocOpener(command, i);
-      if (opener !== null) {
-        if (commentState === "unknown") commentState = "no";
-        line += command.slice(i, opener.lineEnd);
-        i = opener.lineEnd - 1;
-        heredocMarker = opener.marker;
-        continue;
-      }
-    }
+  const comments = scanShellStructure(command).spans.filter(
+    (span) => span.kind === "comment" && span.fullLine,
+  );
+  if (comments.length === 0) return command;
 
-    if (ch === "\n") {
-      line += ch;
-      flushLine();
-      continue;
-    }
-
-    if (ch === " " || ch === "\t") {
-      line += ch;
-      continue;
-    }
-
-    if (commentState === "unknown") commentState = ch === "#" ? "yes" : "no";
-    line += ch;
+  let out = "";
+  let cursor = 0;
+  for (const comment of comments) {
+    let end = comment.end;
+    if (command[end] === "\r" && command[end + 1] === "\n") end += 2;
+    else if (command[end] === "\n") end++;
+    out += command.slice(cursor, comment.start).replace(/[ \t]+$/, "");
+    cursor = end;
   }
-  flushLine();
-  return out;
-}
-
-// Whether `text` ends (ignoring trailing whitespace) in a redirect operator
-// that has not yet received its target: a bare `>`/`<`, or a fd-duplication
-// opener `>&`/`<&` awaiting the fd number.
-const DANGLING_REDIRECT = /(?:>&|<&|>|<)$/;
-
-function endsWithDanglingRedirect(text: string): boolean {
-  return DANGLING_REDIRECT.test(text.trimEnd());
+  return out + command.slice(cursor);
 }
 
 // The inner chain of a segment that is exactly one parenthesised group, or null
diff --git a/src/permission/gate.ts b/src/permission/gate.ts
index ee5619002..455f5fa3e 100644
--- a/src/permission/gate.ts
+++ b/src/permission/gate.ts
@@ -336,11 +336,10 @@ export interface PermissionGate {
   unregisterMcpServer: (serverName: string) => void;
 }
 
-// True when splitChainedCommand can be trusted to yield only real segments for
-// grant minting. False for patterns that confuse the no-backslash-escape
-// splitter into phantom segments — those mint as one exact whole-pattern grant.
+// Backslashes mark exact-escaped patterns and must not be interpreted again as
+// shell source. Inline comments likewise remain one exact whole-pattern grant.
 function canSafelyMintPerSegment(pattern: string): boolean {
-  if (/\\["`]/.test(pattern)) return false;
+  if (pattern.includes("\\")) return false;
   if (pattern.includes("#")) return false;
   return true;
 }
@@ -391,12 +390,9 @@ export function createPermissionGate(options: PermissionGateOptions): Permission
     // tradeoff. onGrant's covers predicate consults the live approvals list so
     // a queued identical chain drains only once every segment has been minted.
     //
-    // splitChainedCommand / tokenize intentionally have no backslash-escape
-    // support (CL-6988 / #673 rely on that so misparsed wrappers stay opaque).
-    // When the pattern contains escapes or inline `#` comments, the naive
-    // splitter can invent phantom segments (`printf "…\" && evil"` → `evil`).
-    // Fall back to one exact grant for the whole normalized pattern instead of
-    // minting those phantoms.
+    // Exact patterns contain backslash escapes for matcher metacharacters and
+    // cannot be safely reinterpreted as shell source. Inline comments also stay
+    // whole so commented text can never become a separately minted grant.
     const normalizedPattern =
       tool === "run_shell"
         ? stripCommentLines(outcome.persist.pattern).trim()
diff --git a/src/permission/permission.test.ts b/src/permission/permission.test.ts
index d1722bbd4..905ce0ef1 100644
--- a/src/permission/permission.test.ts
+++ b/src/permission/permission.test.ts
@@ -2134,13 +2134,12 @@ describe("createPermissionGate", () => {
   });
 
   test("escaped quotes do not mint grants for unexecuted text", async () => {
-    // splitChainedCommand has no backslash-escape support (CL-6988). Minting
-    // per segment would invent a phantom `touch PWNED` grant, so the gate
-    // falls back to one exact whole-pattern grant instead.
     const full = `printf "safe \\" && touch PWNED && \\""`;
     const persisted: Approval[] = [];
     const built = buildRequests(shellCall(full))[0]?.scopes.find((scope) => scope.id === "exact");
-    if (built === undefined) throw new Error("expected exact command scope");
+    if (built?.pattern === null || built?.pattern === undefined) {
+      throw new Error("expected exact command scope");
+    }
     const gate = createPermissionGate({
       approvals: [],
       requestApproval: async () => ({ allow: true, persist: { ...built, grant: "project" } }),
@@ -2150,7 +2149,7 @@ describe("createPermissionGate", () => {
     });
 
     expect((await gate.evaluate(shellCall(full))).allowed).toBe(true);
-    expect(persisted.map((a) => a.pattern)).toEqual([full]);
+    expect(persisted.map((a) => a.pattern)).toEqual([built.pattern]);
     expect(persisted.map((a) => a.pattern)).not.toContain("touch PWNED");
   });
 
diff --git a/src/permission/shell-tokenizer-property.test.ts b/src/permission/shell-tokenizer-property.test.ts
index 542a3eba2..b8988abad 100644
--- a/src/permission/shell-tokenizer-property.test.ts
+++ b/src/permission/shell-tokenizer-property.test.ts
@@ -107,6 +107,64 @@ describe("heredoc boundaries", () => {
       ),
     ).toBe(false);
   });
+
+  const heredocCases = [
+    {
+      name: "CRLF terminator",
+      command: "cat <<EOF\r\nsafe\r\nEOF\r\nrm -rf /",
+      expected: ["cat <<EOF\r\nsafe\r\nEOF", "rm -rf /"],
+    },
+    {
+      name: "multiple queued heredocs",
+      command:
+        "cat <<FIRST <<SECOND\none; still body\nFIRST\ntwo && still body\nSECOND\ntouch PWNED",
+      expected: [
+        "cat <<FIRST <<SECOND\none; still body\nFIRST\ntwo && still body\nSECOND",
+        "touch PWNED",
+      ],
+    },
+    {
+      name: "exact plain terminator",
+      command: "cat <<EOF\nEOF \nrm -rf /\nEOF\ntouch PWNED",
+      expected: ["cat <<EOF\nEOF \nrm -rf /\nEOF", "touch PWNED"],
+    },
+    {
+      name: "tab-stripping terminator",
+      command: "cat <<-EOF\n\tinside; body\n \tEOF\nrm -rf /\n\tEOF\ntouch PWNED",
+      expected: ["cat <<-EOF\n\tinside; body\n \tEOF\nrm -rf /\n\tEOF", "touch PWNED"],
+    },
+    {
+      name: "opaque body control characters",
+      command: "cat <<EOF\nrm -rf / && touch PWNED | sh; echo hidden &\nEOF\necho visible",
+      expected: ["cat <<EOF\nrm -rf / && touch PWNED | sh; echo hidden &\nEOF", "echo visible"],
+    },
+    {
+      name: "malformed quoted opener",
+      command: "cat <<'EOF\ntouch PWNED",
+      expected: ["cat <<'EOF", "touch PWNED"],
+    },
+  ];
+
+  for (const { name, command, expected } of heredocCases) {
+    test(`${name} has exact authorization and display boundaries`, () => {
+      expect(splitChainedCommand(command)).toEqual(expected);
+      expect(groupChainSegmentsForDisplay(command)).toEqual(expected);
+
+      const call: ToolCall = { id: "c", name: "run_shell", arguments: { command } };
+      const request = buildRequests(call)[0];
+      if (request === undefined) throw new Error("expected an approval request");
+      expect(request.scopes.map((scope) => scope.pattern)).toEqual([command]);
+      expect(
+        isRequestCoveredByGrant(
+          request,
+          { tool: "run_shell", pattern: "cat *" },
+          undefined,
+          () => false,
+          { resolvedCwd: "/repo", roots: ["/repo"] },
+        ),
+      ).toBe(false);
+    });
+  }
 });
 
 describe("here-string boundaries", () => {
@@ -118,10 +176,49 @@ describe("here-string boundaries", () => {
     expect(groupChainSegmentsForDisplay(command)).toEqual(expected);
 
     const call: ToolCall = { id: "c", name: "run_shell", arguments: { command } };
-    expect(buildRequests(call)[0]?.scopes.map((scope) => scope.pattern)).toEqual([command]);
+    const request = buildRequests(call)[0];
+    if (request === undefined) throw new Error("expected an approval request");
+    expect(request.scopes.map((scope) => scope.pattern)).toEqual([command]);
+    expect(
+      isRequestCoveredByGrant(
+        request,
+        { tool: "run_shell", pattern: "cat *" },
+        undefined,
+        () => false,
+        { resolvedCwd: "/repo", roots: ["/repo"] },
+      ),
+    ).toBe(false);
   });
 });
 
+describe("non-heredoc left shifts", () => {
+  const cases: [string, string, string[]][] = [
+    ["arithmetic", "echo $((1 << 2))\ntouch PWNED", ["echo $((1 << 2))", "touch PWNED"]],
+    ["comment", "echo safe # <<EOF\ntouch PWNED", ["echo safe # <<EOF", "touch PWNED"]],
+  ];
+
+  for (const [name, command, expected] of cases) {
+    test(`${name} syntax preserves exact newline boundaries and grant rejection`, () => {
+      expect(splitChainedCommand(command)).toEqual(expected);
+      expect(groupChainSegmentsForDisplay(command)).toEqual(expected);
+
+      const call: ToolCall = { id: "c", name: "run_shell", arguments: { command } };
+      const request = buildRequests(call)[0];
+      if (request === undefined) throw new Error("expected an approval request");
+      expect(request.scopes.map((scope) => scope.pattern)).toEqual([command]);
+      expect(
+        isRequestCoveredByGrant(
+          request,
+          { tool: "run_shell", pattern: "echo *" },
+          undefined,
+          () => false,
+          { resolvedCwd: "/repo", roots: ["/repo"] },
+        ),
+      ).toBe(false);
+    });
+  }
+});
+
 describe("shared primitives produce consistent results", () => {
   const sharedCorpus = [
     'echo "hello && world"',
diff --git a/src/permission/shell-tokenizer.ts b/src/permission/shell-tokenizer.ts
index 724f1805b..7812d9468 100644
--- a/src/permission/shell-tokenizer.ts
+++ b/src/permission/shell-tokenizer.ts
@@ -1,48 +1,360 @@
-// Shared shell tokenizer helpers used by both the permission gate
-// (src/permission/command.ts) and the display layer (src/tui/command-display.ts).
-// Keeping a single copy ensures both paths agree on what counts as a heredoc
-// opener, what `&` means in redirect context, and that `<<<` (here-string) is
-// never mistaken for a heredoc.
-
-export function isRedirectAmpersand(next: string | undefined): boolean {
-  return !(next === undefined || next === " " || next === "\t");
-}
-
-// Parses a heredoc opener (`<<` or `<<-`) starting at `command[i]` (which must
-// be the first "<"). Returns the terminating marker text and the exclusive end
-// index of the line that opened the heredoc, so the caller can copy the opening
-// line verbatim and resume scanning the heredoc body from there.
-// `<<<` (here-string) is explicitly rejected — it is not a heredoc opener.
-export function parseHeredocOpener(
-  command: string,
-  i: number,
-): { marker: string; lineEnd: number } | null {
+export type ShellBoundaryKind = "and" | "or" | "pipe" | "semicolon" | "newline" | "background";
+
+export interface ShellBoundary {
+  start: number;
+  end: number;
+  kind: ShellBoundaryKind;
+}
+
+export type ShellSpan =
+  | { start: number; end: number; kind: "quote" | "continuation" | "heredoc-body" }
+  | { start: number; end: number; kind: "comment"; fullLine: boolean };
+
+export interface ShellHeredoc {
+  delimiter: string;
+  stripTabs: boolean;
+  openerStart: number;
+  openerEnd: number;
+  bodyStart: number;
+  bodyEnd: number;
+  terminatorStart: number | null;
+  terminatorEnd: number | null;
+}
+
+export interface ShellStructure {
+  boundaries: ShellBoundary[];
+  spans: ShellSpan[];
+  heredocs: ShellHeredoc[];
+}
+
+interface PendingHeredoc {
+  delimiter: string;
+  stripTabs: boolean;
+  openerStart: number;
+  openerEnd: number;
+}
+
+function lineEndingAt(text: string, index: number): { start: number; end: number } | null {
+  const ch = text[index];
+  if (ch === "\n") return { start: index, end: index + 1 };
+  if (ch === "\r" && text[index + 1] === "\n") return { start: index, end: index + 2 };
+  return null;
+}
+
+function parseHeredocDelimiter(text: string, start: number): PendingHeredoc | null {
   if (
-    command[i] !== "<" ||
-    command[i + 1] !== "<" ||
-    command[i - 1] === "<" ||
-    command[i + 2] === "<"
+    text[start] !== "<" ||
+    text[start + 1] !== "<" ||
+    text[start - 1] === "<" ||
+    text[start + 2] === "<"
   ) {
     return null;
   }
-  let j = i + 2;
-  if (command[j] === "-") j++; // <<- strips leading tabs
-  while (j < command.length && (command[j] === " " || command[j] === "\t")) j++;
-  let markerQuote: string | null = null;
-  if (command[j] === "'" || command[j] === '"') {
-    markerQuote = command[j] as string;
-    j++;
+
+  let i = start + 2;
+  const stripTabs = text[i] === "-";
+  if (stripTabs) i++;
+  while (text[i] === " " || text[i] === "\t") i++;
+
+  let delimiter = "";
+  let quote: "'" | '"' | null = null;
+  while (i < text.length) {
+    const ch = text[i] as string;
+    if (quote !== null) {
+      if (ch === quote) {
+        quote = null;
+        i++;
+        continue;
+      }
+      if (quote === '"' && ch === "\\" && i + 1 < text.length) {
+        delimiter += text[i + 1];
+        i += 2;
+        continue;
+      }
+      if (ch === "\n" || ch === "\r") return null;
+      delimiter += ch;
+      i++;
+      continue;
+    }
+
+    if (ch === "'" || ch === '"') {
+      quote = ch;
+      i++;
+      continue;
+    }
+    if (ch === "\\" && i + 1 < text.length) {
+      const escaped = text[i + 1] as string;
+      if (escaped === "\n" || escaped === "\r") return null;
+      delimiter += escaped;
+      i += 2;
+      continue;
+    }
+    if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r" || ";&|<>()".includes(ch)) {
+      break;
+    }
+    delimiter += ch;
+    i++;
   }
-  let marker = "";
-  while (
-    j < command.length &&
-    command[j] !== "\n" &&
-    command[j] !== markerQuote &&
-    !(markerQuote === null && (command[j] === " " || command[j] === "\t"))
-  ) {
-    marker += command[j++];
+
+  if (quote !== null || delimiter.length === 0) return null;
+  return { delimiter, stripTabs, openerStart: start, openerEnd: i };
+}
+
+function heredocLineMatches(line: string, pending: PendingHeredoc): boolean {
+  return (pending.stripTabs ? line.replace(/^\t+/, "") : line) === pending.delimiter;
+}
+
+function isRedirectAmpersand(next: string | undefined): boolean {
+  return !(next === undefined || next === " " || next === "\t" || next === "\r" || next === "\n");
+}
+
+/**
+ * Performs one bounded lexical scan of shell structure shared by authorization
+ * and approval display. It recognizes only structure needed by those consumers;
+ * malformed or unsupported syntax is left visible rather than made opaque.
+ */
+export function scanShellStructure(command: string): ShellStructure {
+  const boundaries: ShellBoundary[] = [];
+  const spans: ShellSpan[] = [];
+  const heredocs: ShellHeredoc[] = [];
+  const pendingHeredocs: PendingHeredoc[] = [];
+  const parenFrames: ("paren" | "arithmetic")[] = [];
+  let logicalLineHasContent = false;
+  let wordStart = true;
+  let malformedHeredocLine = false;
+  let i = 0;
+
+  while (i < command.length) {
+    const ch = command[i] as string;
+
+    if (ch === "\\") {
+      const ending = lineEndingAt(command, i + 1);
+      if (ending !== null) {
+        spans.push({ kind: "continuation", start: i, end: ending.end });
+        logicalLineHasContent = true;
+        wordStart = true;
+        i = ending.end;
+        continue;
+      }
+      logicalLineHasContent = true;
+      wordStart = false;
+      i = Math.min(i + 2, command.length);
+      continue;
+    }
+
+    if (!malformedHeredocLine && (ch === "'" || ch === '"' || ch === "`")) {
+      const start = i;
+      const quote = ch;
+      i++;
+      while (i < command.length) {
+        const quoted = command[i] as string;
+        if (quote !== "'" && quoted === "\\" && i + 1 < command.length) {
+          i += 2;
+          continue;
+        }
+        i++;
+        if (quoted === quote) break;
+      }
+      spans.push({ kind: "quote", start, end: i });
+      logicalLineHasContent = true;
+      wordStart = false;
+      continue;
+    }
+
+    if (ch === "#" && wordStart) {
+      const start = i;
+      while (i < command.length && lineEndingAt(command, i) === null) i++;
+      spans.push({ kind: "comment", start, end: i, fullLine: !logicalLineHasContent });
+      continue;
+    }
+
+    const ending = lineEndingAt(command, i);
+    if (ending !== null) {
+      if (pendingHeredocs.length > 0) {
+        let bodyStart = ending.end;
+        let cursor = bodyStart;
+        let finalEnding: { start: number; end: number } | null = null;
+
+        for (const pending of pendingHeredocs) {
+          let terminatorStart: number | null = null;
+          let terminatorEnd: number | null = null;
+          let nextBodyStart = command.length;
+
+          while (cursor <= command.length) {
+            let lineEnd = cursor;
+            while (lineEnd < command.length && lineEndingAt(command, lineEnd) === null) lineEnd++;
+            const bodyEnding = lineEndingAt(command, lineEnd);
+            const line = command.slice(cursor, lineEnd);
+            if (heredocLineMatches(line, pending)) {
+              terminatorStart = cursor;
+              terminatorEnd = lineEnd;
+              finalEnding = bodyEnding;
+              nextBodyStart = bodyEnding?.end ?? command.length;
+              break;
+            }
+            if (bodyEnding === null) {
+              cursor = command.length + 1;
+              break;
+            }
+            cursor = bodyEnding.end;
+          }
+
+          const opaqueEnd = terminatorEnd ?? command.length;
+          spans.push({ kind: "heredoc-body", start: bodyStart, end: opaqueEnd });
+          heredocs.push({
+            ...pending,
+            bodyStart,
+            bodyEnd: terminatorStart ?? command.length,
+            terminatorStart,
+            terminatorEnd,
+          });
+          if (terminatorStart === null) {
+            pendingHeredocs.length = 0;
+            return { boundaries, spans, heredocs };
+          }
+          cursor = nextBodyStart;
+          bodyStart = nextBodyStart;
+        }
+
+        pendingHeredocs.length = 0;
+        if (finalEnding !== null) {
+          boundaries.push({ ...finalEnding, kind: "newline" });
+          i = finalEnding.end;
+          logicalLineHasContent = false;
+          wordStart = true;
+          continue;
+        }
+        i = command.length;
+        continue;
+      }
+
+      if (parenFrames.length === 0) boundaries.push({ ...ending, kind: "newline" });
+      i = ending.end;
+      logicalLineHasContent = false;
+      wordStart = true;
+      malformedHeredocLine = false;
+      continue;
+    }
+
+    if (parenFrames.length === 0 && ch === "<" && command[i + 1] === "<") {
+      const opener = parseHeredocDelimiter(command, i);
+      if (opener !== null) {
+        pendingHeredocs.push(opener);
+        logicalLineHasContent = true;
+        wordStart = false;
+        i = opener.openerEnd;
+        continue;
+      }
+      if (command[i - 1] !== "<" && command[i + 2] !== "<") {
+        malformedHeredocLine = true;
+        i += 2;
+        continue;
+      }
+    }
+
+    if (!malformedHeredocLine && ch === "(" && command[i - 1] === "$" && command[i + 1] === "(") {
+      parenFrames.push("arithmetic", "arithmetic");
+      logicalLineHasContent = true;
+      wordStart = false;
+      i += 2;
+      continue;
+    }
+    if (!malformedHeredocLine && ch === "(") {
+      parenFrames.push(command[i + 1] === "(" ? "arithmetic" : "paren");
+      logicalLineHasContent = true;
+      wordStart = true;
+      i++;
+      continue;
+    }
+    if (!malformedHeredocLine && ch === ")") {
+      parenFrames.pop();
+      logicalLineHasContent = true;
+      wordStart = false;
+      i++;
+      continue;
+    }
+
+    if (parenFrames.length === 0 && pendingHeredocs.length === 0) {
+      const next = command[i + 1];
+      let boundary: ShellBoundary | null = null;
+      if (ch === "&" && next === "&") boundary = { start: i, end: i + 2, kind: "and" };
+      else if (ch === "|" && next === "|") boundary = { start: i, end: i + 2, kind: "or" };
+      else if (ch === "|") boundary = { start: i, end: i + 1, kind: "pipe" };
+      else if (ch === ";") boundary = { start: i, end: i + 1, kind: "semicolon" };
+      else if (ch === "&" && !isRedirectAmpersand(next)) {
+        boundary = { start: i, end: i + 1, kind: "background" };
+      }
+      if (boundary !== null) {
+        boundaries.push(boundary);
+        logicalLineHasContent = true;
+        wordStart = true;
+        i = boundary.end;
+        continue;
+      }
+    }
+
+    if (ch === " " || ch === "\t") {
+      wordStart = true;
+      i++;
+      continue;
+    }
+    logicalLineHasContent = true;
+    wordStart = false;
+    i++;
+  }
+
+  return { boundaries, spans, heredocs };
+}
+
+export interface ProjectShellSegmentsOpts {
+  splitPipes: boolean;
+  coalesceDanglingRedirects: boolean;
+}
+
+const DANGLING_REDIRECT = /(?:>&|<&|>|<)$/;
+
+export function projectShellSegments(command: string, opts: ProjectShellSegmentsOpts): string[] {
+  const structure = scanShellStructure(command);
+  const continuations = structure.spans.filter((span) => span.kind === "continuation");
+  const segments: string[] = [];
+  let current = "";
+  let cursor = 0;
+  let continuationIndex = 0;
+
+  const appendRange = (start: number, end: number): void => {
+    let rangeCursor = start;
+    while (continuations[continuationIndex]?.end !== undefined) {
+      const continuation = continuations[continuationIndex];
+      if (continuation === undefined || continuation.end > rangeCursor) break;
+      continuationIndex++;
+    }
+    while (continuationIndex < continuations.length) {
+      const continuation = continuations[continuationIndex];
+      if (continuation === undefined) break;
+      if (continuation.start >= end) break;
+      current += command.slice(rangeCursor, continuation.start);
+      rangeCursor = continuation.end;
+      continuationIndex++;
+    }
+    current += command.slice(rangeCursor, end);
+  };
+  const push = (): void => {
+    const trimmed = current.trim();
+    current = "";
+    if (trimmed.length > 0) segments.push(trimmed);
+  };
+
+  for (const boundary of structure.boundaries) {
+    if (boundary.kind === "pipe" && !opts.splitPipes) continue;
+    appendRange(cursor, boundary.start);
+    cursor = boundary.end;
+    if (opts.coalesceDanglingRedirects && DANGLING_REDIRECT.test(current.trimEnd())) {
+      current = `${current.trimEnd()} `;
+      continue;
+    }
+    push();
   }
-  if (markerQuote !== null && command[j] === markerQuote) j++;
-  while (j < command.length && command[j] !== "\n") j++;
-  return { marker, lineEnd: j };
+  appendRange(cursor, command.length);
+  push();
+  return segments;
 }
diff --git a/src/tui/command-display.ts b/src/tui/command-display.ts
index ad9b075da..f506ac255 100644
--- a/src/tui/command-display.ts
+++ b/src/tui/command-display.ts
@@ -7,7 +7,7 @@
 // security decision.
 
 import { sliceTailToWidth, sliceToWidth, stringWidth } from "./view/height.js";
-import { isRedirectAmpersand, parseHeredocOpener } from "../permission/shell-tokenizer.js";
+import { projectShellSegments, scanShellStructure } from "../permission/shell-tokenizer.js";
 
 // Mirrors the top-level boundary rules in splitChainedCommand (quote-, paren-,
 // heredoc- and continuation-aware; && / || / ; / newline / lone & are chain
@@ -15,100 +15,10 @@ import { isRedirectAmpersand, parseHeredocOpener } from "../permission/shell-tok
 // of a boundary, so a pipe stage never shows up as its own meaningless
 // numbered item.
 export function groupChainSegmentsForDisplay(command: string): string[] {
-  const segments: string[] = [];
-  let current = "";
-  let quote: '"' | "'" | "`" | null = null;
-  let heredocMarker: string | null = null;
-  let parenDepth = 0;
-
-  const push = (): void => {
-    const trimmed = current.trim();
-    current = "";
-    if (trimmed.length > 0) segments.push(trimmed);
-  };
-
-  for (let i = 0; i < command.length; i++) {
-    const ch = command[i] as string;
-
-    if (heredocMarker !== null) {
-      if (ch === "\n") {
-        const lines = current.split("\n");
-        const lastLine = lines[lines.length - 1] ?? "";
-        if (lastLine.trim() === heredocMarker) {
-          // The newline that closes the heredoc is a real chain boundary.
-          heredocMarker = null;
-          push();
-          continue;
-        }
-      }
-      current += ch;
-      continue;
-    }
-
-    if (quote !== null) {
-      current += ch;
-      if (ch === quote) quote = null;
-      continue;
-    }
-    if (ch === '"' || ch === "'" || ch === "`") {
-      quote = ch;
-      current += ch;
-      continue;
-    }
-
-    // The shell elides a backslash-newline, joining the lines into one
-    // command — so it is never a display boundary either.
-    if (ch === "\\" && (command[i + 1] === "\n" || command[i + 1] === "\r")) {
-      i += 1;
-      if (command[i] === "\r" && command[i + 1] === "\n") i += 1;
-      continue;
-    }
-
-    if (ch === "<" && command[i + 1] === "<") {
-      const marker = parseHeredocOpener(command, i)?.marker ?? null;
-      if (marker !== null) {
-        let j = i;
-        while (j < command.length && command[j] !== "\n") j++;
-        current += command.slice(i, j);
-        i = j - 1;
-        heredocMarker = marker;
-        continue;
-      }
-    }
-
-    if (ch === "(") {
-      parenDepth++;
-      current += ch;
-      continue;
-    }
-    if (ch === ")") {
-      if (parenDepth > 0) parenDepth--;
-      current += ch;
-      continue;
-    }
-    if (parenDepth > 0) {
-      current += ch;
-      continue;
-    }
-
-    const next = command[i + 1];
-    if ((ch === "&" && next === "&") || (ch === "|" && next === "|")) {
-      push();
-      i++;
-      continue;
-    }
-    if (ch === "&" && isRedirectAmpersand(next)) {
-      current += ch;
-      continue;
-    }
-    if (ch === ";" || ch === "\n" || ch === "&") {
-      push();
-      continue;
-    }
-    current += ch;
-  }
-  push();
-  return segments;
+  return projectShellSegments(command, {
+    splitPipes: false,
+    coalesceDanglingRedirects: false,
+  });
 }
 
 export interface VerbatimLine {
@@ -128,77 +38,62 @@ export interface VerbatimLine {
 // ordinary line ending and follows the LF rule.
 export function verbatimCommandLines(text: string): VerbatimLine[] {
   const normalized = text.replace(/\r\n/g, "\n");
+  const structure = scanShellStructure(normalized);
+  const quoteSpans = structure.spans.filter((span) => span.kind === "quote");
+  const continuations = new Set(
+    structure.spans.filter((span) => span.kind === "continuation").map((span) => span.end - 1),
+  );
+  const fullLineComments = structure.spans.filter(
+    (span) => span.kind === "comment" && span.fullLine,
+  );
   const lines: VerbatimLine[] = [];
   let current = "";
-  let quote: '"' | "'" | "`" | null = null;
-  let heredocMarker: string | null = null;
-  let heredocPending: string | null = null;
+  let lineStart = 0;
   let continued = false;
-
-  const push = (): void => {
-    const isComment = heredocMarker === null && !continued && current.trimStart().startsWith("#");
+  let commentIndex = 0;
+  let quoteIndex = 0;
+
+  const push = (lineEnd: number): void => {
+    while (fullLineComments[commentIndex]?.end !== undefined) {
+      const comment = fullLineComments[commentIndex];
+      if (comment === undefined || comment.end >= lineStart) break;
+      commentIndex++;
+    }
+    const comment = fullLineComments[commentIndex];
+    const isComment =
+      !continued && comment !== undefined && comment.start >= lineStart && comment.start <= lineEnd;
     lines.push({ text: current, isComment });
     current = "";
-    continued = false;
   };
 
   for (let i = 0; i < normalized.length; i++) {
     const ch = normalized[i] as string;
-
     if (ch === "\r") {
       current += "↵";
       continue;
     }
-
-    if (heredocMarker !== null) {
-      if (ch === "\n") {
-        const done = current.trim() === heredocMarker;
-        push();
-        if (done) heredocMarker = null;
-        continue;
-      }
+    if (ch !== "\n") {
       current += ch;
       continue;
     }
 
-    if (quote !== null) {
-      if (ch === "\n") {
-        current += "↵";
-        continue;
-      }
-      if (ch === quote) quote = null;
-      current += ch;
-      continue;
+    while (quoteSpans[quoteIndex]?.end !== undefined) {
+      const quote = quoteSpans[quoteIndex];
+      if (quote === undefined || quote.end > i) break;
+      quoteIndex++;
     }
-
-    if (ch === "\\" && normalized[i + 1] === "\n") {
-      current += "\\";
-      push();
-      continued = true;
-      i++;
-      continue;
-    }
-
-    if (ch === "\n") {
-      push();
-      heredocMarker = heredocPending;
-      heredocPending = null;
-      continue;
-    }
-
-    if (ch === '"' || ch === "'" || ch === "`") {
-      quote = ch;
-      current += ch;
+    const quote = quoteSpans[quoteIndex];
+    const quoted = quote !== undefined && quote.start < i && i < quote.end;
+    if (quoted) {
+      current += "↵";
       continue;
     }
 
-    if (ch === "<" && normalized[i + 1] === "<" && heredocPending === null) {
-      const marker = parseHeredocOpener(normalized, i)?.marker ?? null;
-      if (marker !== null) heredocPending = marker;
-    }
-    current += ch;
+    push(i);
+    continued = continuations.has(i);
+    lineStart = i + 1;
   }
-  push();
+  push(normalized.length);
   return lines.filter((line, i) => line.text.trim().length > 0 || i === 0);
 }
 
@@ -282,9 +177,13 @@ const CODE_CONSUMING_COMMANDS = new Set([
 // for classification.
 function segmentWords(segment: string): string[] {
   const words: string[] = [];
+  const opaqueSpans = scanShellStructure(segment)
+    .spans.filter(
+      (span) => span.kind === "quote" || span.kind === "comment" || span.kind === "heredoc-body",
+    )
+    .sort((a, b) => a.start - b.start);
   let current = "";
-  let quote: '"' | "'" | "`" | null = null;
-  let heredocMarker: string | null = null;
+  let spanIndex = 0;
 
   const push = (): void => {
     if (current.length > 0) words.push(current);
@@ -293,51 +192,17 @@ function segmentWords(segment: string): string[] {
 
   let i = 0;
   while (i < segment.length) {
-    const ch = segment[i] as string;
-
-    if (heredocMarker !== null) {
-      if (ch === "\n") {
-        let lineEnd = segment.indexOf("\n", i + 1);
-        if (lineEnd === -1) lineEnd = segment.length;
-        if (segment.slice(i + 1, lineEnd).trim() === heredocMarker) {
-          heredocMarker = null;
-          i = lineEnd;
-        }
-      }
-      i++;
-      continue;
-    }
-
-    if (quote !== null) {
-      if (ch === quote) quote = null;
-      i++;
-      continue;
-    }
-
-    if (ch === '"' || ch === "'" || ch === "`") {
+    const opaque = opaqueSpans[spanIndex];
+    if (opaque !== undefined && i >= opaque.start) {
       push();
-      quote = ch;
-      i++;
+      i = opaque.end;
+      spanIndex++;
       continue;
     }
 
-    if (ch === "<" && segment[i + 1] === "<") {
-      const marker = parseHeredocOpener(segment, i)?.marker ?? null;
-      if (marker !== null) {
-        push();
-        heredocMarker = marker;
-        while (i < segment.length && segment[i] !== "\n") i++;
-        continue;
-      }
-    }
-
-    if (ch === " " || ch === "\t" || ch === "\n") {
-      push();
-      i++;
-      continue;
-    }
-
-    current += ch;
+    const ch = segment[i] as string;
+    if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") push();
+    else current += ch;
     i++;
   }
   push();
@@ -383,57 +248,72 @@ function isCodeConsumingSegment(segment: string): boolean {
 // (commit messages, file contents piped to tee/cat, echoed text) collapse.
 export function collapseSegmentPayloads(segment: string): CollapsedSegment {
   if (isCodeConsumingSegment(segment)) return { display: segment, payloads: [] };
+
+  const structure = scanShellStructure(segment);
+  const heredocReplacements = structure.heredocs
+    .filter(
+      (
+        heredoc,
+      ): heredoc is typeof heredoc & {
+        terminatorStart: number;
+        terminatorEnd: number;
+      } => heredoc.terminatorStart !== null && heredoc.terminatorEnd !== null,
+    )
+    .map((heredoc, index) => {
+      const body = segment.slice(heredoc.bodyStart, heredoc.bodyEnd).replace(/(?:\r\n|\n)$/, "");
+      const lines = body.length === 0 ? [] : body.split(/\r?\n/);
+      const placeholder = `<heredoc, ${lineCountSuffix(lines.length)}>`;
+      const firstBodyStart =
+        segment.slice(heredoc.bodyStart - 2, heredoc.bodyStart) === "\r\n"
+          ? heredoc.bodyStart - 2
+          : heredoc.bodyStart - 1;
+      let end = heredoc.terminatorEnd;
+      if (segment.slice(end, end + 2) === "\r\n") end += 2;
+      else if (segment[end] === "\n") end++;
+      return {
+        start: index === 0 ? firstBodyStart : heredoc.bodyStart,
+        end,
+        placeholder,
+        lines,
+      };
+    });
+  const quoteSpans = structure.spans.filter((span) => span.kind === "quote");
   const payloads: CollapsedPayload[] = [];
   let display = "";
+  let heredocIndex = 0;
+  let quoteIndex = 0;
   let i = 0;
-  while (i < segment.length) {
-    const ch = segment[i] as string;
 
-    if (ch === "<" && segment[i + 1] === "<") {
-      const marker = parseHeredocOpener(segment, i)?.marker ?? null;
-      if (marker !== null) {
-        let j = i;
-        while (j < segment.length && segment[j] !== "\n") j++;
-        display += segment.slice(i, j);
-        i = j + 1;
-        const bodyLines: string[] = [];
-        while (i < segment.length) {
-          let lineEnd = segment.indexOf("\n", i);
-          if (lineEnd === -1) lineEnd = segment.length;
-          const line = segment.slice(i, lineEnd);
-          if (line.trim() === marker) {
-            i = lineEnd + 1;
-            break;
-          }
-          bodyLines.push(line);
-          i = lineEnd + 1;
-        }
-        const placeholder = `<heredoc, ${lineCountSuffix(bodyLines.length)}>`;
-        display += ` ${placeholder}`;
-        payloads.push({ placeholder, lines: bodyLines });
-        continue;
-      }
+  while (i < segment.length) {
+    const heredoc = heredocReplacements[heredocIndex];
+    if (heredoc !== undefined && i === heredoc.start) {
+      display += ` ${heredoc.placeholder}`;
+      payloads.push({ placeholder: heredoc.placeholder, lines: heredoc.lines });
+      heredocIndex++;
+      i = heredoc.end;
+      continue;
     }
 
-    if (ch === '"' || ch === "'" || ch === "`") {
-      const quote = ch;
-      let j = i + 1;
-      while (j < segment.length && segment[j] !== quote) j++;
-      const content = segment.slice(i + 1, j);
+    const quote = quoteSpans[quoteIndex];
+    if (quote !== undefined && i === quote.start) {
+      const closed = segment[quote.end - 1] === segment[quote.start];
+      const contentEnd = closed ? quote.end - 1 : quote.end;
+      const content = segment.slice(quote.start + 1, contentEnd);
       if (content.includes("\n")) {
-        const lines = content.split("\n");
+        const lines = content.split(/\r?\n/);
         const placeholder = `<${payloadLabel(segment, i)}, ${lineCountSuffix(lines.length)}>`;
         display += placeholder;
         payloads.push({ placeholder, lines });
-        i = j < segment.length ? j + 1 : j;
-        continue;
+      } else {
+        display += segment.slice(quote.start, quote.end);
       }
-      display += segment.slice(i, j < segment.length ? j + 1 : j);
-      i = j < segment.length ? j + 1 : j;
+      quoteIndex++;
+      i = quote.end;
       continue;
     }
 
-    display += ch;
+    if (quote !== undefined && quote.start < i) quoteIndex++;
+    display += segment[i] as string;
     i++;
   }
   return { display, payloads };

From a3fddbb6862291a788cef502b30208ccfaf7edaa Mon Sep 17 00:00:00 2001
From: Sawyer <sawyer@dirtroad.dev>
Date: Wed, 2 Sep 2026 14:21:31 -0700
Subject: [PATCH 6/6] Fix executable comment regression coverage

---
 tests/unit/permission/cross-commit-composition.test.ts | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/tests/unit/permission/cross-commit-composition.test.ts b/tests/unit/permission/cross-commit-composition.test.ts
index 74a8d2644..1b335387a 100644
--- a/tests/unit/permission/cross-commit-composition.test.ts
+++ b/tests/unit/permission/cross-commit-composition.test.ts
@@ -60,9 +60,8 @@ describe("comment stripping cannot hide executable payload", () => {
     expect(stripCommentLines(cmd)).toContain("rm -rf /");
   });
 
-  test("a chained payload on a comment line still surfaces as a segment", () => {
-    const segs = splitChainedCommand("# note && rm -rf /");
-    expect(segs).toContain("rm -rf /");
+  test("an executable payload after a comment line still surfaces as a segment", () => {
+    expect(splitChainedCommand("# note\nrm -rf /")).toEqual(["# note", "rm -rf /"]);
   });
 
   test("substitution inside double quotes stays visible after stripping", () => {