diff --git a/src/core/auto-approval/__tests__/commands.spec.ts b/src/core/auto-approval/__tests__/commands.spec.ts
index ade53c2b20..30f9e1abcb 100644
--- a/src/core/auto-approval/__tests__/commands.spec.ts
+++ b/src/core/auto-approval/__tests__/commands.spec.ts
@@ -98,6 +98,531 @@ describe("getCommandDecision — integration with dangerous substitution checks"
 	it("should ask user for dangerous parameter expansion even when command is allowed", () => {
 		expect(getCommandDecision('echo "${var@P}"', allowedCommands)).toBe("ask_user")
 	})
+
+	it("does not auto-approve a substitution embedded in a parameter expansion", () => {
+		// The shell runs $(rm -rf ~/work) when x is unset. The inner command must
+		// therefore match the lists on its own. Allowing `echo` must not approve
+		// the payload.
+		expect(getCommandDecision("echo ${x:-$(rm -rf ~/work)}", ["echo"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve a process substitution embedded in a parameter expansion", () => {
+		// With x unset, bash expands the alternate word and runs `rm a`. bash
+		// substitutes a device path for it. The inner command must match the
+		// lists on its own. Allowing `echo` must not approve the payload.
+		expect(getCommandDecision("echo ${x:-<(rm a)}", ["echo"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve a nested substitution riding outer allowlist entries", () => {
+		// `$(foo $(rm -rf /) bar)` must decompose so that the innermost
+		// `rm -rf /` is evaluated on its own. A cut at the first ")" would let
+		// the payload share the allowlist match of the `foo` and `bar` entries.
+		expect(getCommandDecision("ls $(foo $(rm -rf /) bar)", ["ls", "foo", "bar"])).toBe("ask_user")
+	})
+
+	it("asks user when a heredoc opened inside a parameter expansion carries a substitution", () => {
+		// With x unset, bash expands the alternate word. That runs the heredoc
+		// body's $(evil), even though the expansion itself stays one segment.
+		expect(getCommandDecision("cat ${x:-y <<EOF\n$(evil)\nEOF\n}", ["cat"])).toBe("ask_user")
+	})
+
+	it("fails closed on a NUL byte gluing a substitution to an allowed command", () => {
+		// bash drops the NUL and runs the glued substitution. The placeholder
+		// degradation must not leave `git status$(whoami)` looking like one
+		// allowed word. The parser rejects the input as malformed instead.
+		expect(getCommandDecision("git status\x00$(whoami)", ["git"])).toBe("malformed_command")
+	})
+
+	it("asks user for a substitution on the heredoc opener line after the delimiter", () => {
+		// The shell expands the opener line's remainder even when the delimiter
+		// is quoted. The $(whoami) there therefore matches the lists on its own.
+		expect(getCommandDecision("cat <<EOF $(whoami)\nbody\nEOF", ["cat"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve a denied command chained after a heredoc delimiter", () => {
+		// bash pipes the heredoc into `rm x`: the text after the delimiter word
+		// is live syntax, so `rm` must match the denylist on its own instead of
+		// riding the heredoc head's allowlist match.
+		expect(getCommandDecision("echo $(cat <<E | rm x\nhi\nE\n)", ["cat", "echo"], ["rm"])).toBe("auto_deny")
+		// The same rejection at the top level, without the surrounding expansion.
+		expect(getCommandDecision("cat <<E | rm x\nhi\nE", ["cat", "echo"], ["rm"])).toBe("auto_deny")
+		// An unlisted right-hand command costs a prompt, never an approval.
+		expect(getCommandDecision("echo $(cat <<E | grep x\nhi\nE\n)", ["cat", "echo"], [])).toBe("ask_user")
+	})
+
+	it("does not auto-approve a denied command after a mid-word # in the opener remainder", () => {
+		// bash treats the `#` inside `f#g` as an ordinary character and still
+		// pipes into `rm x`. The remainder masking keeps the tail visible to
+		// the lists instead of letting a comment swallow it.
+		expect(getCommandDecision("echo $(cat <<E f#g | rm x\nhi\nE\n)", ["cat", "echo"], ["rm"])).toBe("auto_deny")
+	})
+
+	it("does not auto-approve a denied command glued to the heredoc delimiter", () => {
+		// bash ends the delimiter word at `|`, so the body never terminates and
+		// `rm x` runs live. The parser cannot account for the construct and
+		// reports it malformed, which costs a rejection, never an approval.
+		expect(getCommandDecision("echo $(cat <<E|rm x\nhi\nE|rm\n)", ["cat", "echo"], ["rm"])).toBe(
+			"malformed_command",
+		)
+	})
+
+	it("auto-approves a heredoc pipeline whose every stage is allowlisted (no over-reject)", () => {
+		// A split the denylist never sees must not over-fire: an operator-free
+		// opener and an all-allowlisted right-hand command both stay approved.
+		expect(getCommandDecision("echo $(cat <<E\nhi\nE\n)", ["cat", "echo"], [])).toBe("auto_approve")
+		expect(getCommandDecision("echo $(cat <<E | grep x\nhi\nE\n)", ["cat", "echo", "grep"], [])).toBe(
+			"auto_approve",
+		)
+	})
+
+	it("denies a command chained after a # glued to a substitution closer", () => {
+		// bash keeps `$(ls)#x` as one word, so the chained `rm y` executes.
+		// The closer-aware remainder keeps it visible to the denylist instead
+		// of swallowing the tail as comment text.
+		expect(getCommandDecision("echo $(cat <<E $(ls)#x ; rm y\nhi\nE\n)", ["cat", "echo", "ls"], ["rm"])).toBe(
+			"auto_deny",
+		)
+	})
+
+	it("denies a command chained after a # glued to a process-substitution closer", () => {
+		// `<(...)` continues the word exactly like `$(...)`.
+		expect(getCommandDecision("echo $(cat <<E <(ls)#x ; rm y\nhi\nE\n)", ["cat", "echo", "ls"], ["rm"])).toBe(
+			"auto_deny",
+		)
+	})
+
+	it("denies a command glued directly after a # that follows a substitution closer", () => {
+		// The operator needs no blanks: bash still runs `rm y`, so the denylist
+		// must see it.
+		expect(getCommandDecision("echo $(cat <<E $(ls)#x|rm y\nhi\nE\n)", ["cat", "echo", "ls"], ["rm"])).toBe(
+			"auto_deny",
+		)
+	})
+
+	it("rejects a delimiter glued to a subshell paren instead of approving it", () => {
+		// bash refuses `cat <<E(rm x)` as a syntax error. The parser must fail
+		// the construct closed like the base parser, never approve input whose
+		// parenthesized remainder hides commands from the lists.
+		expect(getCommandDecision("cat <<E(rm x)\nhi\nE", ["cat", "echo"], ["rm"])).toBe("malformed_command")
+	})
+
+	it("fails closed on a word-start pipe with no delimiter word", () => {
+		// bash reads `|` as the operator token where the delimiter word
+		// belongs and rejects the command outright. The no-word mask must not
+		// turn that syntax error into an approved opaque word. The deny head
+		// never reaches the lists: the whole command is rejected.
+		expect(getCommandDecision("cat <<|rm x\nhi\nE", ["cat", "echo", "ls"], ["rm"])).toBe("malformed_command")
+	})
+
+	it("fails closed on a word-start paren with no delimiter word", () => {
+		// `(` is the same operator-token shape as the pipe: bash rejects the
+		// command before executing anything, so the mask must not approve it.
+		expect(getCommandDecision("cat <<(x)\nhi\nE", ["cat", "echo", "ls"], ["rm"])).toBe("malformed_command")
+	})
+
+	it("denies a command chained after a # riding a group-frame closer", () => {
+		// bash balances the `(ls)` group before the `$( … )` closer, so the
+		// glued `#` continues the word and `rm y` really executes. It must
+		// reach the denylist as its own segment instead of being swallowed as
+		// comment text by a frame that popped at the group's closer.
+		expect(getCommandDecision("cat <<E $( (ls) )#x ; rm y\nhi\nE", ["cat", "echo", "ls"], ["rm"])).toBe("auto_deny")
+	})
+
+	it("auto-approves the blanks-only no-word mask (posture control)", () => {
+		// `<<` followed only by blanks before end of line is the shape the
+		// no-word mask is the accepted policy for: bash never executes it, so
+		// the mask's approval is not a policy over-approximation gap.
+		expect(getCommandDecision("cat << \nEOF\nrm -rf /\n", ["cat", "echo", "ls"], ["rm"])).toBe("auto_approve")
+	})
+
+	it("auto-approves a word-initial comment after a spaced substitution closer", () => {
+		// A blank before the `#` is a real word start: bash starts a comment
+		// there and never runs the tail, so approval stays bash-faithful.
+		expect(getCommandDecision("echo $(cat <<E $(ls) #x ; rm y\nhi\nE\n)", ["cat", "echo", "ls"], ["rm"])).toBe(
+			"auto_approve",
+		)
+	})
+
+	it("asks user when a heredoc body with an unquoted delimiter contains a substitution", () => {
+		// The shell expands $(whoami) inside an unquoted-delimiter heredoc body.
+		// The inner command must therefore match the lists, even though the
+		// heredoc is one host segment.
+		const heredoc = "cat <<EOF\n$(whoami)\nEOF"
+		expect(getCommandDecision(heredoc, ["cat"])).toBe("ask_user")
+	})
+
+	it("asks user for a substitution inside the deprecated $[…] arithmetic form", () => {
+		// bash expands `$[ … ]` interiors before it evaluates them. `touch` must
+		// therefore match the lists on its own. It must not share the allowlist
+		// match of `echo`.
+		expect(getCommandDecision("echo $[1+$(touch /tmp/pwn; echo 1)]", ["echo"])).toBe("ask_user")
+	})
+
+	it("asks user for the line after a double-quoted-delimiter heredoc whose backslash bash keeps", () => {
+		// bash keeps `\` before `q`. The heredoc therefore ends at the `a\q`
+		// line, and `rm -rf /` is an ordinary following command the lists must
+		// see.
+		expect(getCommandDecision('cat <<"a\\q"\na\\q\nrm -rf /\naq\n', ["cat"])).toBe("ask_user")
+	})
+
+	it("asks user for the line after a heredoc whose terminator bash joins from continued lines", () => {
+		// `EO\` plus `F` joins into the `EOF` terminator before bash matches
+		// it. `rm -rf /` therefore runs as a following command. It is not
+		// masked body text.
+		expect(getCommandDecision("cat <<EOF\nEO\\\nF\nrm -rf /\n", ["cat"])).toBe("ask_user")
+	})
+
+	it("asks user when a <<- tabbed continuation pair does not join into the terminator", () => {
+		// Tabs join before stripping, so `\tEO\` plus `\tF` stays `EO\tF`. The
+		// heredoc runs to the real `EOF` line, and `rm -rf /` follows it as a
+		// live command. An allowlisted `cat` must not carry that command.
+		expect(getCommandDecision("cat <<-EOF\n\tEO\\\n\tF\ncat <<X\nEOF\nrm -rf /\nX\n", ["cat"])).toBe("ask_user")
+	})
+
+	it("fails closed on a CRLF heredoc whose backslash-CRLF pair only the msys read layer joins", () => {
+		// The msys/Cygwin read layer is the reference shell on the Windows
+		// target. It strips the CR from every line it reads. The line therefore
+		// ends with the lone backslash and continues. `EO\` plus `F` joins into
+		// the terminator, and the commands after it are live. POSIX bash reads
+		// `\<CR>` as an escaped CR and joins nothing, so the two models close
+		// on different lines. A join that consumes a CRLF makes the boundary
+		// model-dependent, and the parser rejects the input as malformed.
+		expect(getCommandDecision("cat <<EOF\r\nEO\\\r\nF\r\ntouch x\r\nEOF\r\n", ["cat"])).toBe("malformed_command")
+	})
+
+	it("never auto-approves the command a bare-CR heredoc terminator candidate exposes", () => {
+		// The msys read layer strips the bare CR. The body line then arrives as
+		// the terminator `EOF`, and `curl evil` would run live after it. POSIX
+		// bash keeps the CR and masks that line. A CR inside a scanned body
+		// line makes the mask boundary model-dependent. The parser therefore
+		// rejects the whole input as malformed. The cost is a prompt or a
+		// rejection, never an approval.
+		expect(getCommandDecision("cat <<EOF\nEO\rF\ncurl evil.example/x\nEOF\ncat ok", ["cat"])).toBe(
+			"malformed_command",
+		)
+	})
+
+	it("never auto-approves a bare-CR early close that re-exposes a masking heredoc opener", () => {
+		// The msys model closes the first heredoc at `EO<CR>F`. The scanner
+		// would then read the body line `cat <<X` as a live opener whose body
+		// masks `rm -rf /`. That decomposition is unaccountable. An
+		// allowlisted `cat` must never carry it to execution.
+		expect(getCommandDecision("cat <<EOF\nEO\rF\ncat <<X\nEOF\nrm -rf /\nX\n", ["cat"], [])).not.toBe(
+			"auto_approve",
+		)
+		expect(getCommandDecision("cat <<EOF\nEO\rF\ncat <<X\nEOF\nrm -rf /\nX\n", ["cat"], [])).toBe(
+			"malformed_command",
+		)
+	})
+
+	it("never auto-approves a CRLF-joined late close that masks a POSIX-executed command", () => {
+		// The msys join of `x\` plus the CRLF keeps the heredoc open past the
+		// line where POSIX bash ends it. There the delimiter word is `EOF<CR>`,
+		// and bash executes the line that msys masks. The two models diverge,
+		// so the input must cost a rejection. It must not auto-approve one
+		// masked `cat` command.
+		expect(getCommandDecision("cat <<EOF\r\nx\\\r\nEOF\r\nrm -rf /\r\nEOF\r\n", ["cat"], [])).not.toBe(
+			"auto_approve",
+		)
+		expect(getCommandDecision("cat <<EOF\r\nx\\\r\nEOF\r\nrm -rf /\r\nEOF\r\n", ["cat"], [])).toBe(
+			"malformed_command",
+		)
+	})
+
+	it("never auto-approves a CR-free body whose CRLF opener line splits the delimiter word", () => {
+		// The opener line's CRLF leaves msys reading the delimiter as `EOF`
+		// while POSIX bash reads `EOF<CR>`. The CR-free `EOF` line then closes
+		// the heredoc for msys only. The following `cat <<X` opener masks
+		// `rm -rf /` under that model. An allowlisted `cat` must never carry
+		// that decomposition to execution.
+		expect(getCommandDecision("cat <<EOF\r\nbody\nEOF\ncat <<X\nrm -rf /\nX\n", ["cat"], [])).not.toBe(
+			"auto_approve",
+		)
+		expect(getCommandDecision("cat <<EOF\r\nbody\nEOF\ncat <<X\nrm -rf /\nX\n", ["cat"], [])).toBe(
+			"malformed_command",
+		)
+	})
+
+	it("never auto-approves the masking heredoc exposed by a CRLF-terminated terminator line", () => {
+		// With an LF opener, both models read the delimiter as `EOF`. The CR on
+		// the terminator candidate is ordinary content for POSIX bash. The msys
+		// read layer strips that CR and closes the body there. That re-exposes
+		// `cat <<X` as a live opener masking `rm -rf /`. The divergence must
+		// cost a rejection, never an approval.
+		expect(getCommandDecision("cat <<EOF\nEOF\r\ncat <<X\nEOF\nrm -rf /\nX\n", ["cat"], [])).not.toBe(
+			"auto_approve",
+		)
+		expect(getCommandDecision("cat <<EOF\nEOF\r\ncat <<X\nEOF\nrm -rf /\nX\n", ["cat"], [])).toBe(
+			"malformed_command",
+		)
+	})
+
+	it("asks user for the inner commands of process substitutions", () => {
+		expect(getCommandDecision("diff <(sort a) <(sort b)", ["diff"])).toBe("ask_user")
+	})
+
+	it("auto-approves an unbalanced delimiter inside single quotes", () => {
+		// A shell never parses delimiter characters inside single quotes, so an
+		// unbalanced "$(" there is ordinary argument text, not a syntax error.
+		expect(getCommandDecision("echo 'a $(b'", ["echo"])).toBe("auto_approve")
+	})
+
+	it("fails closed on an unmatched closer even when the first word is allowed", () => {
+		// A "}" with no matching "{" leaves the parser unable to account for
+		// the structure. The decision stays a rejection. An allowlisted first
+		// word must not carry it straight to execution.
+		expect(getCommandDecision("echo }", ["echo"])).toBe("malformed_command")
+		// bash reads "<<" inside "${...}" as an arithmetic shift. It runs
+		// "evil" and "E" as command lines, and refuses the trailing "}".
+		// Treating the "<<" as a heredoc opener would mask those lines and
+		// auto-approve the whole command. The closed frame rejects it instead.
+		const shift = "echo ${x:1<<E }\nevil\nE\n}"
+		expect(getCommandDecision(shift, ["echo"], [])).toBe("malformed_command")
+		expect(getCommandDecision(shift, ["echo", "evil", "E"], [])).toBe("malformed_command")
+	})
+
+	it("routes words with balanced braces or a bare closer through the normal approval flow", () => {
+		// bash runs all three commands. `find -exec {} \;` is a placeholder,
+		// `src/{a,b}` is brace expansion, and a depth-0 ")" cannot hide a
+		// substitution. None is malformed, so the allowlisted first word
+		// decides.
+		expect(getCommandDecision("find . -exec rm {} \\;", ["find"], [])).toBe("auto_approve")
+		expect(getCommandDecision("mkdir -p src/{a,b}", ["mkdir"], [])).toBe("auto_approve")
+		expect(getCommandDecision("git show HEAD@{1}", ["git"], [])).toBe("auto_approve")
+		expect(getCommandDecision("echo )", ["echo"], [])).toBe("auto_approve")
+	})
+
+	it("fails closed on an unclosed arithmetic opener even when the first word is allowed", () => {
+		// bash refuses an unclosed "$((" . The masked remainder must not let
+		// the allowlisted "echo" carry a never-closed "$(" straight to
+		// execution.
+		expect(getCommandDecision("echo $(( $(evil)", ["echo"])).toBe("malformed_command")
+	})
+
+	it("fails closed on a CR-only heredoc opener even when the first word is allowed", () => {
+		// A lone CR does not terminate the opener line, so the heredoc is
+		// unterminated. The input must not look well-formed to the allowlists.
+		expect(getCommandDecision("cat <<EOF\r$(evil)\rEOF", ["cat"])).toBe("malformed_command")
+	})
+
+	it("fails closed on a CR immediately after a bare-<< opener", () => {
+		// A lone CR is not a line terminator for bash, so the opener line never
+		// ends. The parser reports the heredoc as unterminated. The allowlisted
+		// `cat` must not carry the masked remainder.
+		expect(getCommandDecision("cat <<\rEOF\nEOF\nrm -rf /\n", ["cat"], [])).toBe("malformed_command")
+	})
+
+	it("fails closed on a bare-<< heredoc whose opener line ends CRLF", () => {
+		// The CR inside the masked span leaves the msys and POSIX read layers
+		// reading different bytes. The mask cannot then be verified in a
+		// model-independent way, so it fails closed. The decision is a
+		// rejection, never the approval an opaque `cat` word would otherwise
+		// earn.
+		expect(getCommandDecision("cat << \r\nEOF\n\r\nrm -rf /\n", ["cat"], [])).not.toBe("auto_approve")
+		expect(getCommandDecision("cat << \r\nEOF\n\r\nrm -rf /\n", ["cat"], [])).toBe("malformed_command")
+	})
+
+	it("fails closed on a bare-<< heredoc whose CR rides against the opener", () => {
+		// This is the same decision-level rejection with the CR directly after
+		// `<<`. One CR byte inside the masked region is enough to fail the
+		// heredoc closed.
+		expect(getCommandDecision("cat <<\r\nEOF\nrm -rf /\n", ["cat"], [])).not.toBe("auto_approve")
+		expect(getCommandDecision("cat <<\r\nEOF\nrm -rf /\n", ["cat"], [])).toBe("malformed_command")
+	})
+
+	it("auto-approves a CR-free bare-<< heredoc (no over-fire)", () => {
+		// The masked span here is byte-identical under both read layers. The
+		// accepted masking policy for this never-runnable shape is therefore
+		// unchanged. A CR-free bare-<< opener still masks through end of input
+		// and stays approved under an allowlisted `cat`.
+		expect(getCommandDecision("cat <<\nEOF\nrm -rf /\n", ["cat"], [])).toBe("auto_approve")
+	})
+
+	it("asks user when a quoted-empty heredoc delimiter lets a later command escape", () => {
+		// bash's quote removal makes `<<''` terminate at the first blank line,
+		// so `rm -rf /` really executes as its own command. Now that the parser
+		// splits it out, the unallowed segment costs a prompt. It must not
+		// share the allowlist match of `cat`.
+		expect(getCommandDecision("cat <<''\nbody\n\nrm -rf /", ["cat"])).toBe("ask_user")
+	})
+
+	it("fails closed on an unclosed delimiter quote hiding an executable tail", () => {
+		// bash carries the open quote across the newline and runs `; rm -rf /`
+		// as a separate command. The parser rejects the input as malformed, so
+		// no partial decomposition can auto-approve it.
+		expect(getCommandDecision("cat <<'X\r\n'; rm -rf /\nX\r\n", ["cat"])).toBe("malformed_command")
+	})
+
+	it("does not approve a deny command joined onto the opener line by a backslash", () => {
+		// `'a'` closes before the trailing backslash, so bash joins the body's
+		// `; rm -rf /` line onto the opener line as live syntax the remainder
+		// cut never sees. The heredoc fails closed, and the deny payload never
+		// reaches tokenization: an allowlisted `cat` must not carry it.
+		expect(getCommandDecision("cat <<E 'a'\\\n; rm -rf /\nE\n", ["cat"], [])).not.toBe("auto_approve")
+		expect(getCommandDecision("cat <<E 'a'\\\n; rm -rf /\nE\n", ["cat"], ["rm"])).toBe("malformed_command")
+	})
+
+	it("fails closed on deny commands joined by backslash runs the remainder quote walk must track", () => {
+		// Two more crafted joins reach the same decision through different walk
+		// branches. `\'` keeps the `'` escaped, so the run there is unquoted;
+		// `"a\"b'` ends with an open single quote that the double-quote branch
+		// must step over. Both joins must fail closed before the deny payload
+		// tokenizes. `"a"b'` additionally pins the accept side: an open single
+		// quote at the run keeps the guard silent, and a walk that loses that
+		// state rejects this ordinary heredoc instead of approving it.
+		expect(getCommandDecision("cat <<E a\\'\\\n; rm -rf /\nE\n", ["cat"], [])).not.toBe("auto_approve")
+		expect(getCommandDecision("cat <<E a\\'\\\n; rm -rf /\nE\n", ["cat"], ["rm"])).toBe("malformed_command")
+		expect(getCommandDecision('cat <<E "a\\"b\'\\\n; rm -rf /\nE\n', ["cat"], [])).not.toBe("auto_approve")
+		expect(getCommandDecision('cat <<E "a\\"b\'\\\n; rm -rf /\nE\n', ["cat"], ["rm"])).toBe("malformed_command")
+		expect(getCommandDecision('cat <<E "a"b\'\\\n; rm -rf /\nE\n', ["cat"], [])).toBe("auto_approve")
+	})
+
+	it("decides opener-remainder quote, procsub-chain, and redirect shapes by their decomposition", () => {
+		// Decision-layer mirror of the remainder-walk pins: a quote region
+		// only closes on its own character, so the cross-quoted remainders
+		// drop the `#c` tail inside the still-open region and leave a
+		// heredoc whose every command is allowlisted; the closer-boundary
+		// shapes keep `#c` as word content and stay approved; a `>(…)`
+		// chain makes its payloads match the lists on their own, so an
+		// unlisted payload costs a prompt; and a plain `>`/`<` redirect
+		// stays host text that never masks a command from the lists.
+		expect(getCommandDecision("cat <<E \"a'b'#c\nbody\nE\n", ["cat"], ["rm"])).toBe("auto_approve")
+		expect(getCommandDecision('cat <<E \'a"b"#c\nbody\nE\n', ["cat"], ["rm"])).toBe("auto_approve")
+		expect(getCommandDecision('cat <<E "a\'b"#c\nbody\nE\n', ["cat"], ["rm"])).toBe("auto_approve")
+		expect(getCommandDecision("cat <<E 'a\"b'#c\nbody\nE\n", ["cat"], ["rm"])).toBe("auto_approve")
+		expect(getCommandDecision("cat <<E >(a)>(b)#c\nbody\nE\n", ["cat"], [])).toBe("ask_user")
+		expect(getCommandDecision("cat <<E >out\nbody\nE\n", ["cat"], ["rm"])).toBe("auto_approve")
+		expect(getCommandDecision("cat <<E <in\nbody\nE\n", ["cat"], ["rm"])).toBe("auto_approve")
+	})
+
+	it("decides a # riding an inner frame closer by the comment bash starts at it", () => {
+		// While an outer frame stays open, a `#` at an inner closer is frame
+		// content and bash comments the `; rm -rf /]d` tail, so an allowlisted
+		// head carries nothing the deny list names. Marking the closer at the
+		// inner pop instead keeps " #c" in the host and fabricates
+		// "rm -rf /]d" as its own segment, flipping the decision to a deny.
+		// The counterpart with the `#` at the pop that empties the frames
+		// keeps `rm -rf /` live, so it must cost the deny and the prompt.
+		expect(getCommandDecision("cat <<E $[a$(b)#c; rm -rf /]d\nbody\nE\n", ["cat", "b"], ["rm"])).toBe(
+			"auto_approve",
+		)
+		expect(getCommandDecision("cat <<E $[a$(b)#c; rm -rf /]d\nbody\nE\n", ["cat", "b"], [])).toBe("auto_approve")
+		expect(getCommandDecision("cat <<E $[a$(b)]#c; rm -rf /\nbody\nE\n", ["cat", "b"], ["rm"])).toBe("auto_deny")
+		expect(getCommandDecision("cat <<E $[a$(b)]#c; rm -rf /\nbody\nE\n", ["cat", "b"], [])).toBe("ask_user")
+	})
+
+	it("does not reject a subshell group inside a command substitution as malformed", () => {
+		// `$( (echo safe) )` is ordinary syntax that bash runs. A top-level
+		// bare `(` stays host grouping, as segmentation worked before this
+		// change. The extracted group starts with `(`, so it matches neither
+		// list and the decision is `ask_user`, never `malformed_command`.
+		expect(getCommandDecision("$( (echo safe) )", ["echo"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve the group of a mis-nested $(( … ) … )", () => {
+		// bash runs the group inside `echo $((rm -rf /) )`, so the group must
+		// be checked on its own instead of riding the allowlisted `echo`.
+		// The extracted group starts with `(`, so neither list prefix matches
+		// it; the decision is `ask_user`, never `auto_approve`.
+		expect(getCommandDecision("echo $((rm -rf /) )", ["echo"], ["rm"])).toBe("ask_user")
+		expect(getCommandDecision("echo $((rm -rf /) )", ["echo"], [])).toBe("ask_user")
+	})
+
+	it("asks user for the payload of a >() process substitution", () => {
+		// bash runs the inner command unconditionally. Its output becomes the
+		// device file that the outer command writes to. `evil` is therefore
+		// evaluated against the lists on its own, even though the outer `cat`
+		// is allowed.
+		expect(getCommandDecision("cat >(evil)", ["cat"])).toBe("ask_user")
+	})
+
+	it("auto-approves a well-formed mid-word-quoted delimiter (no over-fire)", () => {
+		// `<<EOF'x'` closes its quote before the line end. After bash's quote
+		// removal, the terminator is the literal word EOFx. This stays a single
+		// ordinary heredoc that an allowlisted `cat` may run.
+		expect(getCommandDecision("cat <<EOF'x'\nbody\nEOFx\n", ["cat"])).toBe("auto_approve")
+	})
+
+	it("does not auto-approve a heredoc-body frame tail riding a mis-sliced group prefix", () => {
+		// bash runs `curl evil` from this body line. An allowlist that covers
+		// the host and the quoted-quote group prefix must not carry the tail.
+		// The frame keeps its full payload, `curl evil` is its own segment, and
+		// no segment matches. The decision is a prompt, never an approval.
+		expect(getCommandDecision('cat <<EOF\n$( (echo ")") ; curl evil)\nEOF', ["cat", "( echo"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve the single-quoted variant of a heredoc-body frame tail", () => {
+		expect(getCommandDecision("cat <<EOF\n$( (echo ')') ; curl evil)\nEOF", ["cat", "( echo"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve a heredoc-body frame tail hidden behind a comment", () => {
+		// bash skips the comment to end of line. Its `)` therefore never closes
+		// the frame, and `curl evil` really executes inside the same
+		// substitution. An allowlist that covers the host and the first inner
+		// command must not carry the tail. The tail is its own segment and
+		// costs a prompt.
+		expect(getCommandDecision("cat <<EOF\n$( echo ok # )\ncurl evil)\nEOF", ["cat", "echo"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve the CRLF variant of a comment-hidden frame tail", () => {
+		// msys strips every CR while POSIX keeps it. The CRs here leave the two
+		// read layers on different bytes, so the close cannot be verified in a
+		// model-independent way. The parser fails the heredoc closed even
+		// though the models for this uniformly-CRLF input happen to agree. The
+		// decision is a rejection rather than the LF variant's prompt. Neither
+		// case is an approval.
+		expect(getCommandDecision("cat <<EOF\r\n$( echo ok # )\r\ncurl evil)\r\nEOF\r\n", ["cat", "echo"])).toBe(
+			"malformed_command",
+		)
+	})
+
+	it("does not auto-approve a frame tail behind a comment at the frame start", () => {
+		expect(getCommandDecision("cat <<EOF\n$(# ok )\ncurl evil)\nEOF", ["cat"])).toBe("ask_user")
+	})
+
+	it("fails closed when a frame comment swallows the frame's only closer", () => {
+		// bash refuses the input outright with an unterminated-command-
+		// substitution error, so no partial decomposition may carry an
+		// approval.
+		expect(getCommandDecision("cat <<EOF\n$( echo # )\nEOF", ["cat", "echo"])).toBe("malformed_command")
+	})
+
+	it("asks user for a mid-word # argument whose separator hides an unallowed tail", () => {
+		// `x=a#b` is one bash argument, because a comment starts only at a word
+		// boundary. The tail after `;` runs separately. It must not share the
+		// allowlist match of `echo`.
+		expect(getCommandDecision("cat <<EOF\n$( echo x=a#b ; curl evil )\nEOF", ["cat", "echo"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve a frame tail after a quoted # region", () => {
+		// The `#` inside the quotes is literal. The frame therefore keeps its
+		// full payload, and `curl evil` splits out as an unallowed segment.
+		expect(getCommandDecision('cat <<EOF\n$( echo "a # b" ; curl evil)\nEOF', ["cat", "echo"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve a tail riding after a # at a word-embedded expansion closer", () => {
+		// bash ends the expansion at `)` but not the word. The adjacent `#` is
+		// therefore word content, and `; curl evil` is a second executed
+		// command. An allowlist that covers the host and the substitution must
+		// not carry the tail. The tail is its own segment and costs a prompt.
+		expect(getCommandDecision("echo x=$(echo ok)#;curl evil", ["echo"])).toBe("ask_user")
+		expect(getCommandDecision("echo $((1))#;curl evil", ["echo"])).toBe("ask_user")
+		expect(getCommandDecision("echo x=`echo ok`#;curl evil", ["echo"])).toBe("ask_user")
+		expect(getCommandDecision("cat <(echo ok)#;curl evil", ["cat", "echo"])).toBe("ask_user")
+	})
+
+	it("does not auto-approve a tail riding after a # at the end of an escape pair", () => {
+		// bash treats an escaped character as word content. The `#` directly
+		// after the `\c` pair therefore never starts a comment, and
+		// `; curl evil` really executes. Each tail must cost a prompt, despite
+		// the `echo` allowlist. A real space before the `#` puts it at a word
+		// start instead. There bash comments the line, and the same shape stays
+		// approved.
+		expect(getCommandDecision("echo a\\)#;curl evil", ["echo"])).toBe("ask_user")
+		expect(getCommandDecision("echo a\\;#;curl evil", ["echo"])).toBe("ask_user")
+		expect(getCommandDecision("echo a\\ #;curl evil", ["echo"])).toBe("ask_user")
+		expect(getCommandDecision("echo a\\) #c;curl evil", ["echo"])).toBe("auto_approve")
+	})
 })
 
 describe("getCommandDecision — multi-line script wrapped in a quoted argument", () => {
@@ -197,6 +722,18 @@ describe("getCommandDecisionDetailed", () => {
 		expect(getCommandDecisionDetailed("   ", ["git"])).toEqual({ decision: "auto_approve" })
 	})
 
+	it("reports malformed_command for an unclosed command substitution", () => {
+		// An opened "$(" that the scanner cannot close leaves the input's
+		// structure unaccounted for. The parser reports the raw, unsplit command
+		// so that no fragment of a partial decomposition can be approved on its
+		// own.
+		const result = getCommandDecisionDetailed("echo $(whoami", ["echo"])
+
+		expect(result.decision).toBe("malformed_command")
+		expect(result.offendingCommand).toBe("echo $(whoami")
+		expect(result.parseError).toContain("command substitution")
+	})
+
 	it("returns the same decision as getCommandDecision across representative inputs", () => {
 		const cases: Array<[string, string[], string[] | undefined]> = [
 			["git status", ["git"], []],
diff --git a/src/core/auto-approval/commands.ts b/src/core/auto-approval/commands.ts
index 4d28e0fe1b..faf76cd8f8 100644
--- a/src/core/auto-approval/commands.ts
+++ b/src/core/auto-approval/commands.ts
@@ -114,7 +114,18 @@ export function findLongestPrefixMatch(command: string, prefixes: string[]): str
 }
 
 /**
- * Command approval decision types
+ * Command approval decision types.
+ *
+ * `malformed_command` is the fail-closed outcome. The parser cannot fully
+ * account for the command's structure. The parser reports it for an
+ * unterminated quote or heredoc. It also reports it for an expansion
+ * delimiter ($(), ${}, backtick, <( or >() or an arithmetic expression
+ * ($(( or $[) that never closes. A stray "}" with no matching "{", a raw
+ * NUL byte, and substitution nesting deeper than the re-scan depth cap
+ * also produce this outcome. No approval may use a partial decomposition
+ * of the command.
+ * A shell never parses delimiters inside quoted regions, so unbalanced
+ * delimiters there do not qualify.
  */
 export type CommandDecision = "auto_approve" | "auto_deny" | "ask_user" | "malformed_command"
 
@@ -136,7 +147,15 @@ export type CommandDecision = "auto_approve" | "auto_deny" | "ask_user" | "malfo
  * - `"auto_approve"`: All sub-commands are explicitly allowed and no dangerous patterns detected
  * - `"auto_deny"`: At least one sub-command is explicitly denied
  * - `"ask_user"`: Mixed or no matches found, requires user decision, or contains dangerous patterns
- * - `"malformed_command"`: Command contains an unterminated quote -- a shell syntax error that must not be auto-approved
+ * - `"malformed_command"`: The parser cannot fully account for the command's
+ *   structure. Causes: an unterminated quote or heredoc, an expansion
+ *   delimiter ($(...), ${...}, backtick, <( or >()) or arithmetic expression
+ *   ($(( or $[) that never closes, a stray "}" with no matching "{", a raw
+ *   NUL byte, or substitution nesting deeper than the parser's re-scan depth
+ *   cap. The parser must not approve a command whose structure is unproven
+ *   based on a partial decomposition. A shell never parses delimiter
+ *   characters inside quoted regions, so unbalanced delimiters there stay
+ *   parseable.
  *
  * **Examples:**
  * ```typescript
@@ -214,15 +233,19 @@ export function getCommandDecisionDetailed(
 	}
 
 	// Parse into sub-commands (split by &&, ||, ;, |). parseCommand also
-	// detects shell syntax errors (unterminated quotes, unclosed heredocs) and
-	// returns a non-null parseError in that case.
+	// detects input it cannot account for. That covers unterminated quotes
+	// or heredocs, expansion delimiters ($(), ${}, backticks, <( or >() or
+	// arithmetic expressions ($(( or $[) that never close, a stray closer,
+	// a raw NUL byte, and substitution nesting that is too deep. In that
+	// case parseCommand returns a non-null parseError.
 	const { commands: subCommands, parseError } = parseCommand(command)
 
-	// Reject commands with a shell syntax error. An unterminated quote means
-	// the shell would report a parse error; in a compound command it may
-	// partially execute the well-formed prefix before aborting. Returning a
-	// distinct decision lets callers surface a useful message to the agent
-	// rather than silently presenting the command for user approval.
+	// Reject commands whose structure the parser cannot fully account for.
+	// The shell reports a parse error for such input. In a compound command
+	// the shell may partially execute the well-formed prefix before it
+	// stops. A distinct decision lets callers show the agent a useful
+	// message. It also avoids presenting the command silently for user
+	// approval.
 	if (parseError !== null) {
 		return { decision: "malformed_command", offendingCommand: command, parseError: parseError.message }
 	}
diff --git a/src/eslint-suppressions.json b/src/eslint-suppressions.json
index 0dd477ab2d..2d90ccf448 100644
--- a/src/eslint-suppressions.json
+++ b/src/eslint-suppressions.json
@@ -1604,11 +1604,6 @@
 			"count": 1
 		}
 	},
-	"shared/parse-command.ts": {
-		"@typescript-eslint/no-explicit-any": {
-			"count": 1
-		}
-	},
 	"shared/support-prompt.ts": {
 		"@typescript-eslint/no-explicit-any": {
 			"count": 5
diff --git a/src/shared/__tests__/parse-command.spec.ts b/src/shared/__tests__/parse-command.spec.ts
index fa41d31c6c..504214f689 100644
--- a/src/shared/__tests__/parse-command.spec.ts
+++ b/src/shared/__tests__/parse-command.spec.ts
@@ -323,6 +323,32 @@ describe("parseCommand", () => {
 			expect(result).toHaveLength(2)
 			expect(result[result.length - 1]).toBe("echo world")
 		})
+
+		it("fails closed on CRLF heredocs of every delimiter form", () => {
+			// The msys read layer strips every CR in the construct. The strip
+			// reaches the delimiter word and the terminator line too. POSIX bash
+			// keeps every CR. A CR anywhere from the opener line through the
+			// closing terminator line therefore leaves the two layers reading
+			// different bytes. The close cannot then be verified in a
+			// model-independent way, so every such heredoc fails closed. This
+			// includes uniformly-CRLF heredocs whose two models agree. That is
+			// the accepted cost of never picking a model.
+			const input = "cat <<EOF\r\n$(whoami)\r\nEOF\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+			expect(findUnterminatedQuote("cat <<-EOF\r\n\techo C\r\n\tEOF\r\n")?.quoteType).toBe("heredoc")
+			expect(findUnterminatedQuote("cat <<'EOF'\r\nbody\r\nEOF\r\n")?.quoteType).toBe("heredoc")
+			expect(findUnterminatedQuote('cat <<"EOF"\r\nbody\r\nEOF\r\n')?.quoteType).toBe("heredoc")
+			expect(findUnterminatedQuote("cat <<\\EOF\r\nbody\r\nEOF\r\n")?.quoteType).toBe("heredoc")
+			// A delimiter quote left open does not end at the CR. bash spans
+			// the newline with the quote. It reads a delimiter that can never
+			// match a body line, and it keeps executing the opener line's tail.
+			// An unclosed delimiter quote therefore fails closed instead of
+			// masking the body.
+			expect(findUnterminatedQuote("cat <<'EOF\r\nbody\r\nEOF\r\n")?.quoteType).toBe("heredoc")
+			expect(findUnterminatedQuote('cat <<"EOF\r\nbody\r\nEOF\r\n')?.quoteType).toBe("heredoc")
+		})
 	})
 
 	describe("herestring (<<<)", () => {
@@ -498,10 +524,2387 @@ describe("parseCommand", () => {
 		})
 
 		it("returns null for a balanced <<- heredoc with an indented terminator", () => {
-			// stripTabs must be true for <<- so the indented terminator line is
-			// recognized; without the fix every terminator line was unconditionally
-			// stripped of tabs, making <<- and << behave identically.
+			// The <<- form alone enables tab stripping. Unconditional stripping
+			// would make << and <<- indistinguishable at the terminator.
 			expect(findUnterminatedQuote("sh <<-EOF\n\techo hello\n\tEOF")).toBeNull()
 		})
 	})
+
+	describe("command substitution extraction", () => {
+		// Every command substitution must be extracted with balanced-paren
+		// awareness wherever it sits, so each inner command matches the
+		// allow/deny lists on its own.
+
+		it("extracts the inner payload of a nested substitution as its own segment", () => {
+			// A non-balanced parser truncates the payload at the first ')' and hides
+			// the inner command from the lists.
+			expect(parseCommand("echo $(foo $(bar))").commands).toEqual(["echo", "foo", "bar"])
+		})
+
+		it("extracts a substitution embedded inside a parameter expansion", () => {
+			// ${x:-$(cmd)} falls back to running the substitution when x is
+			// unset, so the payload must be matched independently even though
+			// the expansion itself stays verbatim in its host segment.
+			const input = "echo ${x:-$(rm -rf ~/work)}"
+			expect(parseCommand(input).commands).toEqual([input, "rm -rf ~/work"])
+		})
+
+		it("extracts a substitution inside a parameter expansion inside a substitution", () => {
+			// Recursion: the outer $() payload is re-scanned, which finds the
+			// ${b:-$(c)} expansion and extracts c from inside it.
+			expect(parseCommand("$(a ${b:-$(c)} d)").commands).toEqual(["a ${b:-$(c)} d", "c"])
+		})
+
+		it("extracts a process substitution written inside a parameter expansion", () => {
+			// bash parses `<(` inside `${…}` as a process substitution. bash
+			// replaces it with a device path, so the inner command may run. It
+			// must match the allowlists on its own. It must not share the
+			// allowlist match of the expansion word.
+			const input = "echo ${x:-<(rm a)}"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "rm a"])
+		})
+
+		it("extracts a process substitution nested inside a command substitution", () => {
+			// bash expands `<(` inside `$(…)`. The inner command runs with the
+			// payload. It must match the allowlists on its own.
+			const { commands, parseError } = parseCommand("echo $(cat <(rm a))")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "cat", "rm a"])
+		})
+
+		it("extracts both sides of a process substitution pair", () => {
+			expect(parseCommand("diff <(sort a) <(sort b)").commands).toEqual(["diff", "sort a", "sort b"])
+		})
+
+		it("extracts a nested process substitution", () => {
+			expect(parseCommand("cat <(a <(b))").commands).toEqual(["cat", "a", "b"])
+		})
+
+		it("closes a backtick region at the next backtick (backticks do not nest)", () => {
+			// The second ` closes the first region. The third ` opens a second
+			// region. The text between the two regions stays in its host word.
+			expect(parseCommand("echo `a`b`c`").commands).toEqual(["echo", "a", "b", "c"])
+		})
+
+		it("masks arithmetic without emitting segments from inside it", () => {
+			// $((...)) and $[...] are not command substitutions. The whole
+			// arithmetic stays inside the host word. It never balances as an
+			// extraction delimiter.
+			expect(parseCommand("echo $((1+2))").commands).toEqual(["echo $((1+2))"])
+			expect(parseCommand("echo $[1+2]").commands).toEqual(["echo $[1+2]"])
+		})
+
+		it("extracts substitutions from an unquoted-delimiter heredoc body while the heredoc stays one segment", () => {
+			// The shell expands $(...) inside such bodies, so the payload must
+			// match the lists on its own. The heredoc itself stays opaque.
+			const input = "cat <<EOF\n$(whoami)\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "whoami"])
+		})
+
+		it("extracts a substitution inside a closed $((…)) as its own segment", () => {
+			// bash performs command substitutions inside $((…)) before it
+			// evaluates the arithmetic. The payload must therefore match the
+			// lists on its own. It must not share the allowlist match of the
+			// host word.
+			const input = "echo $(( $(rm -rf /) ))"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "rm -rf /"])
+		})
+
+		it("extracts a substitution inside a closed $[…] as its own segment", () => {
+			// `$[ … ]` is the deprecated arithmetic form. Like $((…)), it expands
+			// command substitutions before it evaluates. The payload must
+			// therefore match the lists on its own. It must not share the
+			// allowlist match of the host word.
+			const input = "echo $[1+$(whoami)]"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "whoami"])
+		})
+
+		it("fails closed on an unclosed $[ whose interior holds a substitution", () => {
+			// bash reports a syntax error when the `]` never arrives, so the
+			// input must not look well-formed to the allowlists.
+			const input = "echo $[1+$(whoami)"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("arithmetic")
+		})
+
+		it("fails closed when a nested ] slices a $[…] payload open", () => {
+			// bash tracks bracket nesting through its arithmetic grammar. The
+			// scanner ends `$[…]` at the first `]`. The truncated payload then
+			// leaves its `$(` unclosed. That fails closed, like the shell's own
+			// arithmetic syntax error for the same input. This holds at top
+			// level and inside a heredoc body.
+			const input = "echo $[1+$(echo ])]"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+			const body = "cat <<EOF\n$[1+$(echo ])]\nEOF"
+			const bodyResult = parseCommand(body)
+			expect(bodyResult.commands).toEqual([body])
+			expect(bodyResult.parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("does not extract from a quoted-delimiter heredoc body (the shell suppresses expansion there)", () => {
+			const input = "cat <<'EOF'\n$(whoami)\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input])
+		})
+
+		it("extracts a substitution from the alternate word of a parameter expansion", () => {
+			// With x unset, bash expands the alternate word and runs $(evil).
+			// `<<EOF` inside `${…}` is literal word text, not a heredoc opener.
+			// The substitution therefore stays live. It must surface as its own
+			// segment even though the expansion host stays verbatim.
+			const input = "cat ${x:-y <<EOF\n$(evil)\nEOF\n}"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "evil"])
+		})
+
+		it("extracts a substitution from a quoted-delimiter shape inside a parameter expansion", () => {
+			// bash runs the `$(evil)` here: `<<'EOF'` inside `${…}` is not a
+			// heredoc operator, so the alternate word expands the substitution
+			// like any other word text. Masking it as heredoc body would skip
+			// allowlisting a command bash actually executes.
+			const input = "cat ${x:-y <<'EOF'\n$(evil)\nEOF\n}"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "evil"])
+		})
+
+		it("extracts a substitution after the delimiter on a heredoc opener line", () => {
+			// The opener line's remainder is expanded regardless of delimiter quoting:
+			// bash runs the substitution sitting between the delimiter and the newline.
+			const { commands, parseError } = parseCommand("cat <<EOF $(whoami)\nbody\nEOF")
+			expect(parseError).toBeNull()
+			// The remainder is live host text: the masked region keeps the
+			// delimiter word, body, and terminator, and the substitution is
+			// reassembled by the tokenizer and routed to its own segment.
+			expect(commands).toEqual(["cat <<EOF\nbody\nEOF $ ( whoami )", "whoami"])
+		})
+
+		it("extracts opener-line substitutions for quoted and <<- delimiters too", () => {
+			// Quoting suppresses expansion in the body only, never on the opener
+			// line, so <<'EOF' and <<- carry the same remainder obligation as <<.
+			expect(parseCommand("cat <<'EOF' $(whoami)\nbody\nEOF").commands).toEqual([
+				"cat <<'EOF'\nbody\nEOF $ ( whoami )",
+				"whoami",
+			])
+			expect(parseCommand("cat <<-EOF\t$(whoami)\nbody\nEOF").commands).toEqual([
+				"cat <<-EOF\nbody\nEOF $ ( whoami )",
+				"whoami",
+			])
+		})
+
+		it("splits a chain operator after the delimiter out of the heredoc segment", () => {
+			// The text after the delimiter word is live syntax: bash pipes the
+			// heredoc into `rm x`, so the operator's right-hand command must
+			// match the lists on its own instead of riding the heredoc head.
+			const { commands, parseError } = parseCommand("echo $(cat <<E | rm x\nhi\nE\n)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "cat <<E\nhi\nE", "rm x"])
+			// The split respects quoting: a `|` inside the argument stays word text.
+			const quoted = parseCommand('echo $(cat <<E | grep "a|b"\nhi\nE\n)')
+			expect(quoted.parseError).toBeNull()
+			expect(quoted.commands).toEqual(["echo", "cat <<E\nhi\nE", "grep a|b"])
+		})
+
+		it("keeps an operator-free opener remainder in one segment (no over-split)", () => {
+			// Without an operator the remainder is just more words of the
+			// opener's command; the heredoc stays a single segment.
+			expect(parseCommand("cat <<E arg\nhi\nE").commands).toEqual(["cat <<E\nhi\nE arg"])
+			// The same split applies at the top level: a second pipeline stage
+			// after the delimiter must not share the heredoc head's word.
+			expect(parseCommand("cat <<E | rm x\nhi\nE").commands).toEqual(["cat <<E\nhi\nE", "rm x"])
+		})
+
+		it("keeps a mid-word # in the opener remainder from swallowing the tail", () => {
+			// bash treats a mid-word `#` as an ordinary character. The tokenizer
+			// would drop everything after it as comment text. The remainder
+			// emission masks that `#` like the live-text scan does, so the
+			// `rm x` after the pipe reaches a segment of its own.
+			const input = "echo $(cat <<E f#g | rm x\nhi\nE\n)"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "cat <<E\nhi\nE f#g", "rm x"])
+		})
+
+		it("keeps a word-initial # remainder as the comment bash sees", () => {
+			// At a word start the tokenizer and bash agree: the `#` opens a
+			// comment that runs to end of line, and nothing after it executes.
+			const { commands, parseError } = parseCommand("cat <<E # note\nhi\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nhi\nE"])
+		})
+
+		it("fails closed on an odd backslash run at the end of the opener remainder", () => {
+			// bash joins the `\`+LF pair, so `| rm x` executes from the opener
+			// line. The remainder cut stops at that LF, so it cannot account
+			// for the joined bytes. The heredoc fails closed instead of
+			// approving a command the decomposition never surfaced.
+			const input = "echo $(cat <<E \\\n| rm x\nhi\nE\n)"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("ends the delimiter word at an unquoted operator so the tail splits", () => {
+			// bash tokenizes `cat <<EOF|grep y` as the word `EOF` plus a live
+			// pipe, exactly like the spaced idiom. The terminator comparison
+			// must use `EOF`, not `EOF|grep`, so the well-terminated body
+			// closes and the tail splits into its own segment.
+			const input = "cat <<EOF|grep y\nhi\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF\nhi\nEOF", "grep y"])
+		})
+
+		it("fails closed when a glued-operator delimiter hides the real terminator", () => {
+			// bash takes `E` as the delimiter word for `cat <<E|rm x`, so the
+			// body runs to end of input: the line `E|rm` never terminates it
+			// and `rm x` executes live. The parser must not match that line as
+			// a terminator, so the construct fails closed.
+			const input = "echo $(cat <<E|rm x\nhi\nE|rm\n)"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("keeps a # glued to a command-substitution closer from swallowing the tail", () => {
+			// bash ends `$(ls)` but not the word: the `#` is mid-word content
+			// and `; rm y` stays live. A word-initial reading would drop the
+			// tail as comment text, so the closer takes the placeholder channel.
+			const { commands, parseError } = parseCommand("echo $(cat <<E $(ls)#x ; rm y\nhi\nE\n)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "cat <<E\nhi\nE $ ( ls ) #x", "ls", "rm y"])
+		})
+
+		it("keeps a # glued to a command-substitution closer at the top level too", () => {
+			// The same closer rule without the surrounding expansion: the deny
+			// head after the operator must reach its own segment.
+			const { commands, parseError } = parseCommand("cat <<E $(ls)#x ; rm y\nhi\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nhi\nE $ ( ls ) #x", "ls", "rm y"])
+		})
+
+		it("keeps a # glued to a process-substitution closer from swallowing the tail", () => {
+			// `<(...)` closes a word-continuing region exactly like `$(...)`.
+			const { commands, parseError } = parseCommand("echo $(cat <<E <(ls)#x ; rm y\nhi\nE\n)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "cat <<E\nhi\nE <( ls ) #x", "ls", "rm y"])
+		})
+
+		it("keeps a # glued to a substitution closer working against a glued pipe", () => {
+			// The operator needs no surrounding blanks: bash still runs the
+			// right-hand command, so it must split into its own segment.
+			const { commands, parseError } = parseCommand("echo $(cat <<E $(ls)#x|rm y\nhi\nE\n)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "cat <<E\nhi\nE $ ( ls ) #x", "ls", "rm y"])
+		})
+
+		it("keeps a # glued to a backtick closer from swallowing the tail", () => {
+			// The backtick region closes the expansion but not the word, like
+			// every other closer, in the split and the glued-operator shape.
+			const split = parseCommand("echo $(cat <<E `ls`#x ; rm y\nhi\nE\n)")
+			expect(split.parseError).toBeNull()
+			expect(split.commands).toEqual(["echo", "cat <<E\nhi\nE `ls`#x", "ls", "rm y"])
+			const glued = parseCommand("echo $(cat <<E `ls`#x|rm y\nhi\nE\n)")
+			expect(glued.parseError).toBeNull()
+			expect(glued.commands).toEqual(["echo", "cat <<E\nhi\nE `ls`#x", "ls", "rm y"])
+		})
+
+		it("keeps a # glued to a parameter or arithmetic closer from swallowing the tail", () => {
+			// `${x}` and `$((1))` end an expansion, not the word: bash treats
+			// the `#` as ordinary content and runs the tail. The arithmetic
+			// frame must close at its second `)`, never the first.
+			const param = parseCommand("cat <<E ${x}#y ; rm z\nhi\nE")
+			expect(param.parseError).toBeNull()
+			expect(param.commands).toEqual(["cat <<E\nhi\nE #y", "rm z"])
+			const arith = parseCommand("cat <<E $((1))#y ; rm z\nhi\nE")
+			expect(arith.parseError).toBeNull()
+			expect(arith.commands).toEqual(["cat <<E\nhi\nE $ ( ( 1 ) ) #y", "rm z"])
+		})
+
+		it("keeps a # glued to a closed quote in the remainder on the placeholder path", () => {
+			// Quotes pass through the walk unmasked, so the quote-then-`#`
+			// word keeps the behavior the escaped-hash control established:
+			// the tail survives tokenization.
+			const dq = parseCommand('echo $(cat <<E "a"#x ; rm y\nhi\nE\n)')
+			expect(dq.parseError).toBeNull()
+			expect(dq.commands).toEqual(["echo", "cat <<E\nhi\nE a#x", "rm y"])
+			const sq = parseCommand("echo $(cat <<E 'a'#x ; rm y\nhi\nE\n)")
+			expect(sq.parseError).toBeNull()
+			expect(sq.commands).toEqual(["echo", "cat <<E\nhi\nE a#x", "rm y"])
+		})
+
+		it("keeps a spaced # after a closer in the remainder as the comment bash sees", () => {
+			// A blank before the `#` puts it at a real word start: bash starts
+			// a comment there and never runs the tail. The closer rule must not
+			// widen past a `#` directly after the closer.
+			const { commands, parseError } = parseCommand("echo $(cat <<E $(ls) #x ; rm y\nhi\nE\n)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "cat <<E\nhi\nE $ ( ls )", "ls"])
+		})
+
+		it("fails closed on a delimiter glued to a subshell paren", () => {
+			// bash refuses `cat <<E(rm x)`: a `(` after a completed word token
+			// is a syntax error, never a delimiter break. The word keeps the
+			// parens, no body line matches it, and the construct fails closed
+			// exactly like the base parser instead of approving unexecutable
+			// input whose remainder hides the parenthesized text unsplit.
+			const input = "cat <<E(rm x)\nhi\nE"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a delimiter glued to a subshell paren inside a substitution", () => {
+			// The embedding expansion changes nothing: the opener line is
+			// still bash-illegal at the glued `(`.
+			const input = "echo $(cat <<E(rm x)\nhi\nE\n)"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a delimiter glued to a subshell paren through a tab", () => {
+			// A tab after the glued parens is still inside the illegal token.
+			const input = "cat <<E(rm x)\t\nhi\nE"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("splits a spaced parenthesized remainder as before (no over-reject)", () => {
+			// A blank before the `(` ends the delimiter word the way bash's
+			// token boundary does: the heredoc closes and the group reaches
+			// the host text unsplit, approved at base and now alike.
+			const { commands, parseError } = parseCommand("cat <<E (rm x)\nhi\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nhi\nE ( rm x )"])
+		})
+
+		it("keeps braces and mid-word parens as delimiter word characters", () => {
+			// `{` is no metacharacter: `E{rm x;}` is one word whose body never
+			// terminates. A `(` after a nonempty word is illegal in bash, so
+			// `x=1(y)` keeps the paren inside the word and the heredoc closes
+			// at `E` with the remainder as live host text.
+			const glued = parseCommand("cat <<E{rm x;}\nhi\nE")
+			expect(glued.commands).toEqual(["cat <<E{rm x;}\nhi\nE"])
+			expect(glued.parseError?.quoteType).toBe("heredoc")
+			const midword = parseCommand("cat <<E x=1(y)\nhi\nE")
+			expect(midword.parseError).toBeNull()
+			expect(midword.commands).toEqual(["cat <<E\nhi\nE x=1 ( y )"])
+		})
+
+		it("fails closed on a delimiter glued to a closing paren", () => {
+			// `)` is a metacharacter only at token start; glued after the word
+			// `E` it is a syntax error in bash, so the word keeps it, the body
+			// never terminates, and the base rejection is restored.
+			const input = "cat <<E)rm x\nhi\nE"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed when a metacharacter starts the delimiter word", () => {
+			// A `(` or `)` can only start a metacharacter, never a word: with
+			// the word absent, the opener breaks on the metacharacter and the
+			// no-word metacharacter guard fails the construct closed. bash needs a
+			// word token after the redirection operator and rejects this input
+			// outright, so no rejection here can cost an executable command. A body
+			// line that matches the metacharacter word (the terminator-matching
+			// variant of each shape) fails closed too: the guard cannot tell the
+			// body apart, and bash never executes this input either way.
+			const cases: string[] = ["cat <<(x)\nhi\n(x)", "cat <<(x)\nhi\nE", "cat <<)x\nhi\nE"]
+			for (const input of cases) {
+				const { commands, parseError } = parseCommand(input)
+				expect(commands).toEqual([input])
+				expect(parseError?.quoteType).toBe("heredoc")
+			}
+		})
+
+		it("fails closed on every word-start operator shape", () => {
+			// One assert per word-start metacharacter in the delimiter break
+			// set, including the `<<-` and spaced-`<` variants. bash ends the
+			// absent word at the operator token and rejects the whole command
+			// before executing anything, so each shape fails closed with the
+			// raw input.
+			const cases: string[] = [
+				"cat <<|rm x\nhi\nE",
+				"cat <<&rm x\nhi\nE",
+				"cat <<;rm x\nhi\nE",
+				"cat <<(x)\nhi\nE",
+				"cat <<)x\nhi\nE",
+				"cat <<>f\nhi\nE",
+				"cat << <f\nhi\nE",
+				"cat <<-|rm x\nhi\nE",
+			]
+			for (const input of cases) {
+				const { commands, parseError } = parseCommand(input)
+				expect(commands).toEqual([input])
+				expect(parseError?.quoteType).toBe("heredoc")
+			}
+		})
+
+		it("fails closed on a word-start operator inside a substitution frame", () => {
+			// The expansion-frame call site shares the guard: a heredoc opened
+			// inside `$(…)` with an operator instead of a delimiter word fails
+			// closed the same way. The guard fires at the opener, so a body
+			// line matching the metacharacter word never reaches the
+			// terminator search.
+			for (const input of ["echo $(cat <<(x)\nhi\nE\n)", "echo $(cat <<(x)\nhi\n(x)\n)"]) {
+				const { commands, parseError } = parseCommand(input)
+				expect(commands).toEqual([input])
+				expect(parseError?.quoteType).toBe("heredoc")
+			}
+		})
+
+		it("keeps # a delimiter word character and controls the no-word paths", () => {
+			// `#` never enters the delimiter break sets: the word keeps it, so
+			// a non-matching body fails like any unmatched delimiter and a
+			// matching body closes -- unchanged by the metacharacter guard.
+			const unmatched = parseCommand("cat <<#x\nhi\nE")
+			expect(unmatched.commands).toEqual(["cat <<#x\nhi\nE"])
+			expect(unmatched.parseError?.quoteType).toBe("heredoc")
+			const matched = parseCommand("cat <<#x\nhi\n#x")
+			expect(matched.parseError).toBeNull()
+			expect(matched.commands).toEqual(["cat <<#x\nhi\n#x"])
+			// End-of-input control for the guard's boundary clause: with no
+			// line ending at all the opener still fails closed, whether the
+			// guard or the opener-line check reports it.
+			const atEof = parseCommand("cat <<")
+			expect(atEof.commands).toEqual(["cat <<"])
+			expect(atEof.parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("splits a chain after a group closer glued to # in the opener remainder", () => {
+			// bash balances the inner `(ls)` group before the `$( … )` closer,
+			// so the closer ends the region, the glued `#` takes the
+			// placeholder, and `rm y` stays live. Dropping the group tracking
+			// pops the frame at the inner `)`, lands the closer early, and lets
+			// the `#` read as a word-initial comment that swallows the tail.
+			const { commands, parseError } = parseCommand("cat <<E $( (ls) )#x ; rm y\nhi\nE")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nhi\nE $ ( ( ls ) ) #x", "( ls )", "rm y"])
+		})
+	})
+
+	describe("heredoc opener-remainder walk and backslash-run guard", () => {
+		// The text after the delimiter word on the opener line is live syntax
+		// the outer scan never revisits: a dedicated walk applies the comment,
+		// region, and escape policy to it, and a trailing backslash-run guard
+		// decides whether an odd unquoted run joins the body onto the opener
+		// line. Each pin below walks a branch of one of the two mechanisms and
+		// pins bytes only that branch produces.
+
+		it("emits an escaped # in the opener remainder verbatim", () => {
+			// The escape-pair branch forwards `\<char>` whole, so the `#` is
+			// word content and no comment starts. Shortening or reversing the
+			// emitted pair shifts every later index, which the exact host
+			// bytes here catch.
+			const { commands, parseError } = parseCommand("cat <<E \\#x\nbody\nE\n")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE #x"])
+		})
+
+		it("keeps a # directly after an escaped blank on the placeholder path", () => {
+			// The escape pair ends one index past the blank, so the `#`
+			// continues the word and takes the opaque placeholder instead of
+			// opening a comment. Moving the tracked escape end two bytes
+			// earlier makes the `#` word-initial and drops the `#b` tail.
+			const { commands, parseError } = parseCommand("cat <<E a\\ #b\nbody\nE\n")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE a #b"])
+		})
+
+		it("treats a backtick region in the opener remainder as opaque until its closer", () => {
+			// Backticks do not nest: the walk treats the region as opaque until
+			// the closer, and the closer ends the frame. The extracted payload
+			// plus the split host bytes pin the frame's open, opacity, and
+			// close together.
+			const { commands, parseError } = parseCommand("cat <<E `a#b`\nbody\nE\n")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE `a", "a#b"])
+		})
+
+		it("starts the opener-remainder comment at a # after a bare (", () => {
+			// A bare `(` with no region open is host grouping, so the `#` sits
+			// at a word start and opens the comment bash sees: the host stops
+			// right after the paren. Inspecting the character after the `#`
+			// instead of before it reads the `#` as mid-word and keeps the
+			// tail.
+			const { commands, parseError } = parseCommand("cat <<E x(#y\nbody\nE\n")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<E\nbody\nE x ("])
+		})
+
+		const guardRows: Array<{ name: string; input: string; commands: string[]; error: "heredoc" | null }> = [
+			{
+				name: "fails closed on an odd unquoted backslash run",
+				input: "cat <<E x\\\nbody\nE\n",
+				commands: ["cat <<E x\\\nbody\nE\n"],
+				error: "heredoc",
+			},
+			{
+				name: "joins nothing after an even unquoted run and closes at the terminator",
+				input: "cat <<E x\\\\\nbody\nE\nbody2\nE\n",
+				commands: ["cat <<E\nbody\nE x\\", "body2", "E"],
+				error: null,
+			},
+			{
+				name: "keeps a single-quoted backslash literal at the run",
+				input: "cat <<E 'x\\\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE x"],
+				error: null,
+			},
+			{
+				name: "fails closed on an odd run inside double quotes",
+				input: 'cat <<E "x\\\nbody\nE\n',
+				commands: ['cat <<E "x\\\nbody\nE\n'],
+				error: "heredoc",
+			},
+			{
+				name: "fails closed on an odd run after a closed double quote",
+				input: 'cat <<E "a"\\\nbody\nE\n',
+				commands: ['cat <<E "a"\\\nbody\nE\n'],
+				error: "heredoc",
+			},
+			{
+				name: "fails closed on an odd run after an escaped backslash inside double quotes",
+				input: 'cat <<E "\\\\"\\\nbody\nE\n',
+				commands: ['cat <<E "\\\\"\\\nbody\nE\n'],
+				error: "heredoc",
+			},
+			{
+				name: "fails closed on an odd run after a closed single quote",
+				input: "cat <<E 'a'\\\nbody\nE\n",
+				commands: ["cat <<E 'a'\\\nbody\nE\n"],
+				error: "heredoc",
+			},
+			{
+				name: "keeps a run covered by an open single quote silent",
+				input: "cat <<E 'a\\\\\\\nbody\nE\nbody2\nE\n",
+				commands: ["cat <<E\nbody\nE a\\", "body2", "E"],
+				error: null,
+			},
+			{
+				name: "fails closed on an odd run after an escaped double quote",
+				input: 'cat <<E \\"\\\nbody\nE\n',
+				commands: ['cat <<E \\"\\\nbody\nE\n'],
+				error: "heredoc",
+			},
+			{
+				// `\'` keeps the following `'` escaped, so the run is unquoted
+				// and joins the body's `; rm -rf /` line onto the opener. The
+				// guard's unquoted escape-advance branch decides this; losing
+				// it reads the run as single-quoted and accepts the join.
+				name: "fails closed on an odd run after an escaped single quote",
+				input: "cat <<E a\\'\\\n; rm -rf /\nE\n",
+				commands: ["cat <<E a\\'\\\n; rm -rf /\nE\n"],
+				error: "heredoc",
+			},
+			{
+				// The `\"` pairs inside the double quote, the following `'`
+				// starts a single-quote region that the double-quote branch's
+				// advance never skips, and the run joins the deny line. Walking
+				// the `'` as double-quote content accepts the construct.
+				name: "fails closed on an odd run started after a double-quoted region ends in an open single quote",
+				input: 'cat <<E "a\\"b\'\\\n; rm -rf /\nE\n',
+				commands: ['cat <<E "a\\"b\'\\\n; rm -rf /\nE\n'],
+				error: "heredoc",
+			},
+			{
+				// `"a"` closes, then `b'` opens a single quote that stays open
+				// into the run: the guard must see the single-quote state at
+				// the run and stay silent. A walk that skips the post-quote
+				// bare text enters the wrong branch and rejects this opener.
+				name: "keeps an open single quote silent over the run after a closed double quote",
+				input: 'cat <<E "a"b\'\\\n; rm -rf /\nE\n',
+				commands: ["cat <<E\n; rm -rf /\nE ab "],
+				error: null,
+			},
+			{
+				// Host parens with no region open are ordinary text; only a
+				// real `$` opener pushes a frame. Reading every character as a
+				// potential opener (or any `$` as one) rebalances the frames
+				// here and shifts the masked comment bytes.
+				name: "keeps bare host parens in the remainder as ordinary text",
+				input: "cat <<E x()#y\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE x ( )"],
+				error: null,
+			},
+			{
+				// A `$` followed by a plain letter is not an opener: it stays
+				// ordinary text and only the real `$(a)` region masks. An
+				// opener test that ignores the next character pushes a phantom
+				// frame for `$x` and rewrites the word-continuation `#`.
+				name: "keeps a $ before a plain letter ordinary in the remainder",
+				input: "cat <<E $x$(a)#y\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE $ ( a ) #y", "a"],
+				error: null,
+			},
+			{
+				// The `#` sits directly at the region closer, so it continues
+				// the word as a placeholder and the `; rm y` tail stays live
+				// syntax the decomposition surfaces. Losing the closer index
+				// reads the `#` as a comment start and swallows the tail.
+				name: "continues the word at a # directly after a region closer",
+				input: "cat <<E $a$(b)#; rm y\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE $ ( b ) #", "b", "rm y"],
+				error: null,
+			},
+			{
+				// Inside the `(`-closing frame, the `[` frame's own `]` closer
+				// is the only one that pops it: the `)` in between is a group
+				// paren. Swapping the `[` detection for the wrong closer (or
+				// dropping it) ends the outer region at the inner `)` and
+				// changes every byte after it.
+				name: "keeps a [ frame inside a ( frame closed only by its ]",
+				input: "cat <<E $(a$[b)c]d)#x\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE $ ( a$[b ) c]d ) #x", "a$[b)c]d"],
+				error: null,
+			},
+			{
+				// A `{` frame closes at its `}`, so the following `$(b)` opens
+				// and closes as its own region and the `#` after its closer
+				// continues the word. A closer picked as `)` or `]` for the
+				// `{` frame never pops it, changing the masked bytes and the
+				// split.
+				name: "closes a { frame at its } closer in the remainder",
+				input: "cat <<E ${a}$(b)#c\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE $ ( b ) #c", "b"],
+				error: null,
+			},
+			{
+				// Symmetric to the `{` frame row: the `[` frame's closer is
+				// `]`, and mis-picking `}` or `)` rebalances the following
+				// `$(b)` region. The masked host bytes plus the split payload
+				// pin the exact closer character.
+				name: "closes a [ frame at its ] closer in the remainder",
+				input: "cat <<E $[a]$(b)#c\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE $[a]$ ( b ) #c", "b"],
+				error: null,
+			},
+			{
+				// Unmatched host parens before a region stay ordinary text;
+				// the walk's frame bookkeeping starts at the `$(`. Reading the
+				// double-paren detection from the wrong index here (or the
+				// wrong distance) treats the leading `((` differently and
+				// shifts every following host byte.
+				name: "keeps unmatched host parens around a region live in the remainder",
+				input: "cat <<E ((x$(b))#y\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE ( ( x$ ( b ) )", "b"],
+				error: null,
+			},
+			{
+				// Two nested `(`-closing frames pop one at a time on the two
+				// `)`, so the `#` after the outer closer continues the word.
+				// A frame that consumes both closers (or a group depth started
+				// for a non-`$((` opener) leaves the frames unbalanced and
+				// rewrites the tail.
+				name: "closes nested ( frames one at a time in the remainder",
+				input: "cat <<E $(a$(b))#y\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE $ ( a$ ( b ) ) #y", "a", "b"],
+				error: null,
+			},
+			{
+				// Only the opener's own character closes a quote region, so
+				// the inner apostrophes stay double-quote content and the
+				// region never closes. The `#` inside the open region is
+				// ordinary content and the tail rides the quotes into the
+				// dropped bytes. Any walk whose quote state diverges here
+				// leaves `#c` in the emitted host instead of dropping it.
+				name: "keeps an inner apostrophe from closing a double-quoted remainder region",
+				input: "cat <<E \"a'b'#c\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE ab"],
+				error: null,
+			},
+			{
+				// Symmetric to the double-quote row: a `"` inside a
+				// single-quote region is literal, the region stays open, and
+				// the `#` inside it is never a mask or comment decision the
+				// walk takes. Closing on the wrong character keeps `#c`.
+				name: "keeps an inner double quote from closing a single-quoted remainder region",
+				input: 'cat <<E \'a"b"#c\nbody\nE\n',
+				commands: ["cat <<E\nbody\nE ab"],
+				error: null,
+			},
+			{
+				// The closer test compares against the opener's character:
+				// the closing `"` ends the region and the `#` riding at the
+				// close continues the word as a placeholder, so the tail
+				// survives. A walk that ends the region at the inner
+				// apostrophe re-opens it at the closer and swallows `#c`.
+				name: "continues the word at a # after a closed double quote",
+				input: 'cat <<E "a\'b"#c\nbody\nE\n',
+				commands: ["cat <<E\nbody\nE a'b#c"],
+				error: null,
+			},
+			{
+				// Symmetric closer-boundary row on a single-quote region:
+				// only `'` closes `'`. Mis-testing the character leaves the
+				// walk in the wrong quote state at the `#` and drops `#c`.
+				name: "continues the word at a # after a closed single quote",
+				input: "cat <<E 'a\"b'#c\nbody\nE\n",
+				commands: ['cat <<E\nbody\nE a"b#c'],
+				error: null,
+			},
+			{
+				// `>(…)` pushes a `)`-closing frame exactly like `<(…)`, so
+				// the chain's final `)` is a region closer and the `#`
+				// directly at it continues the word. A walk that never opens
+				// the frame reads the `#` after a bare `)` as word-initial
+				// and drops `#c` as a comment.
+				name: "keeps a # after a chained >(…) closer as word content",
+				input: "cat <<E >(a)>(b)#c\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE >( a ) >( b ) #c", "a", "b"],
+				error: null,
+			},
+			{
+				// `>` only opens a process-substitution frame when `(`
+				// follows immediately; here it is an ordinary redirect that
+				// the walk forwards as host text. A walk that opens the
+				// frame regardless of the next character swallows the
+				// target's first character into the frame bytes.
+				name: "keeps a plain > redirect out of the process-substitution frame",
+				input: "cat <<E >out\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE > out"],
+				error: null,
+			},
+			{
+				// The `<` counterpart: without an immediately following `(`
+				// the redirect stays ordinary text. The frame-misfire bytes
+				// differ from these pins in the character right after `<`.
+				name: "keeps a plain < redirect out of the process-substitution frame",
+				input: "cat <<E <in\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE < in"],
+				error: null,
+			},
+			{
+				// The `#` rides the inner `$(b)` pop while the outer `$[ ]`
+				// frame stays open, so it is ordinary frame content and bash
+				// drops the `; rm -rf /]d` tail as a comment. Marking the
+				// closer at an inner pop instead keeps " #c" in the host and
+				// exposes the tail as a fabricated word segment.
+				name: "keeps a # riding an inner closer inside an open outer frame as frame content",
+				input: "cat <<E $[a$(b)#c; rm -rf /]d\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE $[a$ ( b )", "b"],
+				error: null,
+			},
+			{
+				// Same class without the deny tail: the `#c` stays inside the
+				// still-open `$[ ]` frame and the `]d` bytes ride the frame's
+				// masked host. Closer bookkeeping fired on the inner pop
+				// emits " #c" into the emitted bytes instead.
+				name: "keeps a # riding an inner closer out of the host bytes of an open outer frame",
+				input: "cat <<E $[a$(b)#c]d\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE $[a$ ( b )", "b"],
+				error: null,
+			},
+			{
+				// The `#` rides the pop that empties the frames: the word
+				// continues, the glued `#c` takes the placeholder, and
+				// `; rm -rf /` stays live syntax the decomposition surfaces.
+				// Only the pop leaving no frames marks the closer; inner
+				// pops must not, or this tail reads as a comment.
+				name: "marks the closer only on the pop that empties the frames",
+				input: "cat <<E $[a$(b)]#c; rm -rf /\nbody\nE\n",
+				commands: ["cat <<E\nbody\nE $[a$ ( b ) ]#c", "b", "rm -rf /"],
+				error: null,
+			},
+		]
+
+		it.each(guardRows)("$name", ({ input, commands, error }) => {
+			// The quote-tracking walk decides whether the trailing odd run
+			// opens a join: only a single-quote region keeps the backslash
+			// literal. Each row pins one state or advance branch of the walk;
+			// the double-quote and escape rows additionally pin the walk's
+			// advance steps, which a stalled step would hang on.
+			const result = parseCommand(input)
+			expect(result.commands).toEqual(commands)
+			expect(result.parseError?.quoteType ?? null).toBe(error)
+		})
+
+		it("fails closed on the crafted closed-quote backslash join", () => {
+			// `'a'` closes before the run, so the trailing backslash joins the
+			// body's `; rm -rf /` line onto the opener line as live syntax.
+			// The remainder cut stops at its own newline and cannot account
+			// for the joined bytes, so the heredoc fails closed. A walk that
+			// loses the single-quote state accepts the construct instead and
+			// masks the joined line out of the decomposition.
+			const input = "cat <<E 'a'\\\n; rm -rf /\nE\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+	})
+
+	describe("fail-closed on unaccountable structure", () => {
+		// A command whose structure the scan cannot fully account for must cost
+		// a prompt (parseError -> malformed_command), never an approval built on
+		// a partial decomposition.
+
+		it("reports an unclosed command substitution", () => {
+			const input = "echo $(foo"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("reports an unclosed parameter expansion", () => {
+			const input = "echo ${x"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("parameter-expansion")
+		})
+
+		it("reports an unclosed backtick region", () => {
+			const input = "echo `foo"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("backtick")
+		})
+
+		it("reports an unclosed process substitution", () => {
+			const input = "diff <(sort"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("process-substitution")
+		})
+
+		it("treats a closing paren at depth zero as host text", () => {
+			// bash closes `case` patterns with `)`, so a bare `)` is not reliably
+			// a syntax error. With the frame stack empty it cannot mask a
+			// substitution, so it stays an ordinary word character.
+			const input = "echo )"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo )"])
+		})
+
+		it("reports a stray closing brace at depth zero", () => {
+			const input = "echo }"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("stray-closer")
+		})
+
+		it("parses words whose braces balance at depth zero", () => {
+			// bash accepts all three: `find -exec {} \;` (placeholder),
+			// `src/{a,b}` (brace expansion), and `HEAD@{1}` (revspec). A `}`
+			// matching an open `{` is not a stray closer.
+			expect(parseCommand("find . -exec rm {} \\;").parseError).toBeNull()
+			expect(parseCommand("mkdir -p src/{a,b}").parseError).toBeNull()
+			expect(parseCommand("git show HEAD@{1}").parseError).toBeNull()
+		})
+
+		it("parses a PowerShell script-block argument under bash brace rules", () => {
+			// The splitter parses bash-style shell syntax only. It does not
+			// parse PowerShell script blocks as such. bash reads this line the
+			// same way: the braces balance as host words and the pipe splits
+			// the command.
+			const { commands, parseError } = parseCommand("Get-Process | Where-Object { $_.CPU -gt 10 }")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["Get-Process", "Where-Object { $_.CPU -gt 10 }"])
+		})
+
+		it("reads a bare trailing backtick as an unclosed substitution", () => {
+			// In bash a backtick opens a command substitution, so an unmatched
+			// one fails closed. PowerShell uses the backtick as an escape
+			// character. The splitter keeps the bash reading.
+			const input = "Write-Host a`"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("backtick")
+		})
+
+		it("parses a case-pattern closer at depth zero", () => {
+			// bash closes a `case` pattern with `)` and there is no matching
+			// opener, so the closer must stay host text.
+			const { commands, parseError } = parseCommand("case x in a) foo ;; esac")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["case x in a ) foo ;; esac"])
+		})
+
+		it("still extracts a substitution behind a depth-0 closer and fails on an unmatched brace", () => {
+			// The relaxation cannot hide a substitution: the payload after the
+			// `)` is still extracted and allowlist-checked on its own.
+			expect(parseCommand("echo ) ; $(rm -rf /)").commands).toEqual(["echo )", "rm -rf /"])
+			// A `}` with no opener stays fail-closed even after a balanced pair.
+			const unmatched = "echo {a} ; }"
+			expect(parseCommand(unmatched).parseError?.quoteType).toBe("stray-closer")
+		})
+
+		it("keeps a literal << inside a parameter expansion out of the heredoc scan", () => {
+			// bash reads `<<` inside `${…}` as an arithmetic shift, never as a
+			// heredoc opener. `${x:1<<0 }` shifts by zero and expands normally,
+			// so the expansion stays one host word and no body is masked.
+			const input = "echo ${x:1<<0 }"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input])
+		})
+
+		it("extracts a substitution written after a literal << inside a parameter expansion", () => {
+			// `<<EOF` inside `${…}` opens no heredoc. The `$(evil)` on the next
+			// line therefore stays live syntax. A heredoc mask here would hide
+			// the payload inside an opaque host word. Allowlisting would then
+			// skip it.
+			const input = "echo ${x:-<<EOF\n$(evil)\nEOF\n}"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "evil"])
+		})
+
+		it("fails closed when a shift-shaped expansion leaves an unpaired closing brace", () => {
+			// bash runs `evil` and `E` as their own command lines. bash then
+			// refuses the trailing `}`. The shift inside `${…}` never pairs it.
+			// Reading `<<` as a heredoc opener would mask all three lines as
+			// body text and auto-approve the command. The closed frame reports
+			// the stray closer instead.
+			const input = "echo ${x:1<<E }\nevil\nE\n}"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("stray-closer")
+		})
+
+		it("still parses heredocs opened inside command- and process-substitution frames", () => {
+			// The shell tokenizes a command context inside `$(…)` and `<(`, so a
+			// heredoc opened there is real and keeps masking its body.
+			const cmd = parseCommand("echo $(cat <<EOF\nfoo\nEOF\n)")
+			expect(cmd.parseError).toBeNull()
+			expect(cmd.commands).toEqual(["echo", "cat <<EOF\nfoo\nEOF"])
+			const proc = parseCommand("diff <(cat <<EOF\nfoo\nEOF\n) <(sort b)")
+			expect(proc.parseError).toBeNull()
+			expect(proc.commands).toEqual(["diff", "cat <<EOF\nfoo\nEOF", "sort b"])
+			// An unterminated body inside such a frame stays fail-closed. bash
+			// refuses the input outright.
+			expect(parseCommand("echo $(cat <<EOF\nfoo\n)").parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("treats a non-matching closer inside an open region as literal and still fails at end of input", () => {
+			// '}' cannot close $( ... . That matches the shell: the character
+			// is literal content. The substitution never closes, so the command
+			// fails at end of input.
+			const input = "echo $(a}"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("reports the widened expansion kinds with the opening index", () => {
+			expect(findUnterminatedQuote("echo $(x")).toEqual(
+				expect.objectContaining({ quoteType: "command-substitution", openIndex: 5 }),
+			)
+			expect(findUnterminatedQuote("echo `x")).toEqual(
+				expect.objectContaining({ quoteType: "backtick", openIndex: 5 }),
+			)
+		})
+
+		it("fails closed on a raw NUL byte anywhere in the input", () => {
+			// NUL is the scan's placeholder sentinel. A raw NUL next to a
+			// substitution would degrade the masked placeholder to inert text.
+			// That would hide the payload. The parser therefore rejects the
+			// whole command before tokenizing.
+			const glued = "git status\x00$(whoami)"
+			const { commands, parseError } = parseCommand(glued)
+			expect(commands).toEqual([glued])
+			expect(parseError?.quoteType).toBe("nul-byte")
+
+			const backtickGlue = parseCommand("echo ok\x00`whoami`")
+			expect(backtickGlue.parseError?.quoteType).toBe("nul-byte")
+
+			const loneNul = parseCommand("\x00")
+			expect(loneNul.parseError?.quoteType).toBe("nul-byte")
+		})
+
+		it("caps substitution re-scan depth at the documented boundary, failing closed past it", () => {
+			// Unbounded payload re-scanning spends quadratic time on generated
+			// nesting. It finally overflows the call stack. The cap turns deep
+			// nesting into a parse error at exactly MAX_PAYLOAD_SCAN_DEPTH + 1
+			// layers. Anything a hand-written command could contain stays
+			// parseable.
+			const nest = (layers: number) => "echo " + "$(a ".repeat(layers) + "x" + ")".repeat(layers)
+			expect(parseCommand(nest(64)).parseError).toBeNull()
+			expect(parseCommand(nest(65)).parseError?.quoteType).toBe("nesting-too-deep")
+			expect(parseCommand(nest(8000)).parseError?.quoteType).toBe("nesting-too-deep")
+		})
+
+		it("fails on an unclosed substitution inside an unquoted-delimiter heredoc body", () => {
+			// The scan finds the terminator line. The shell would never finish
+			// expanding the body, so whatever follows the $( is unaccountable.
+			const input = "cat <<EOF\n$(x\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		// bash itself refuses an unclosed `$((`/`$[` and a CR-only heredoc line
+		// ending. Each must fail closed. Masking such text away could hide a
+		// never-closed substitution behind an allowlisted first word.
+		it("fails closed on an unclosed $(( hiding an embedded substitution", () => {
+			const input = "echo $(( $(evil)"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("arithmetic")
+		})
+
+		it("fails closed on an unclosed $(( that would swallow a later statement", () => {
+			// Routing the masked remainder to the host instead would split the
+			// input into two segments. Each segment could then match the
+			// allowlist. bash rejects the input outright, so failing closed costs
+			// a tool error, never an approval. The lone depth-1 closer makes bash
+			// read the opener as a command substitution, so the unclosed frame
+			// that swallows the later line is reported as one.
+			const swallowed = "echo $((1 )\nevilcmd arg"
+			const { commands, parseError } = parseCommand(swallowed)
+			expect(commands).toEqual([swallowed])
+			expect(parseError?.quoteType).toBe("command-substitution")
+			// The matching control input keeps its extraction behavior.
+			const control = "echo $(( $(evil) ))"
+			expect(parseCommand(control).commands).toEqual([control, "evil"])
+		})
+
+		it("reports an unclosed $(( nested in a parameter expansion by its own kind", () => {
+			// The error must name the arithmetic opener. Letting the outer
+			// region fail at end of input would report the wrong construct. It
+			// would also silently drop the arithmetic's interior payloads.
+			const input = "echo ${x:-$(( $(evil) }"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("arithmetic")
+		})
+
+		it("fails closed on an unclosed $(( inside a heredoc body", () => {
+			// A lone depth-1 closer converts the opener to a command
+			// substitution; unclosed at the body end, the frame fails closed
+			// under its own kind.
+			const input = "cat <<EOF\n$((1 )\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("fails closed on an unclosed $[ at top level and inside a heredoc body", () => {
+			// `$[` is the deprecated sibling of `$((`: bash errors on a missing
+			// `]`, so an unclosed opener must fail closed exactly like `$((`.
+			const top = "echo $[ $(evil)"
+			expect(parseCommand(top).commands).toEqual([top])
+			expect(parseCommand(top).parseError?.quoteType).toBe("arithmetic")
+			expect(parseCommand("cat <<EOF\n$[ $(evil)\nEOF").parseError?.quoteType).toBe("arithmetic")
+		})
+
+		it("rejects a CR-only heredoc opener line as unterminated", () => {
+			// A lone CR is not a bash line terminator, so the opener line never
+			// ends: the shell reports an unterminated heredoc.
+			const input = "cat <<EOF\r$(evil)\rEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("rejects a CR-only heredoc opener even when the body ends with LF", () => {
+			const input = "cat <<EOF\r$(evil)\nEOF\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("rejects a CR-only-bounded heredoc terminator line", () => {
+			// With an LF opener and CR-only line endings in the body, "EOF\r" is
+			// body text to bash. Accepting it as the terminator would validate a
+			// heredoc that the shell reports as unterminated.
+			const input = "cat <<EOF\nbody\rEOF\r"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a CRLF heredoc with an unquoted-body substitution", () => {
+			// The opener line's CRLF already puts a CR inside the region where
+			// the two layers read different bytes. The close cannot then be
+			// verified in a model-independent way. The heredoc fails closed
+			// before any body payload is extracted. This over-rejects even this
+			// uniformly-CRLF input, whose two models happen to agree.
+			const input = "cat <<EOF\r\n$(evil)\r\nEOF\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+	})
+
+	describe("stays parseable inside opaque regions", () => {
+		// Unbalanced delimiter characters a shell never looks at inside quoted
+		// regions stay parseable rather than failing closed.
+
+		it("does not fail on an unbalanced substitution inside single quotes", () => {
+			const input = "echo '$(x'"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input])
+		})
+
+		it("does not fail on unbalanced delimiters inside double quotes", () => {
+			const input = 'echo "$(}"'
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input])
+		})
+
+		it("ignores a stray closer inside a comment and a substitution text inside a quoted-delimiter heredoc body", () => {
+			const input = "echo hi # )\ncat <<'EOF'\n$(x\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			// The comment's stray `)` is dropped with the comment; the quoted
+			// delimiter makes the body opaque, so `$(x` stays inside the
+			// heredoc host word and is never extracted.
+			expect(commands).toEqual(["echo hi", "cat <<'EOF'\n$(x\nEOF"])
+		})
+	})
+
+	describe("empty-quoted heredoc delimiter terminates at the blank line", () => {
+		// Quote removal makes `<<''`/`<<""` an empty delimiter word, which bash
+		// terminates at the first blank body line. Masking those openers to end
+		// of input would hide every later command behind one allowlisted word
+		// while bash runs it as a separate command.
+
+		it("splits the command after the blank-line terminator of a <<'' heredoc", () => {
+			const { commands, parseError } = parseCommand("cat <<''\nbody\n\nrm -rf /")
+			expect(parseError).toBeNull()
+			// The scan masks the opener through the blank line as one word. What
+			// follows is a separate command, and bash really does execute it.
+			expect(commands).toEqual(["cat <<''\nbody\n", "rm -rf /"])
+		})
+
+		it('splits after the blank-line terminator of a <<"" heredoc too', () => {
+			const { commands, parseError } = parseCommand('cat <<""\nbody\n\nrm -rf /')
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<""\nbody\n', "rm -rf /"])
+		})
+
+		it("fails closed on a CRLF <<'' heredoc at its CRLF blank line", () => {
+			// The blank-line terminator carries a CR inside the region from the
+			// opener through the terminator line, so even the empty-delimiter
+			// form fails closed rather than trusting a model-dependent close.
+			const input = "cat <<''\r\nbody\r\n\r\nrm -rf /\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed when a <<'' heredoc body never reaches a blank line", () => {
+			// Without the blank line nothing terminates the body, so nothing
+			// after the opener can be accounted for.
+			const input = "cat <<''\nbody\nrm -rf /"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("keeps masking a bare-<< opener (no delimiter word) through end of input", () => {
+			// A bare `<<` before end of line has no delimiter token at all. bash
+			// rejects this input with a syntax error and never executes it, so
+			// masking the opener through end of input over-approximates a
+			// never-runnable construct and cannot hide a live command.
+			const input = "cat <<\n$(whoami)\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input])
+		})
+
+		it("fails closed on a bare-<< heredoc whose opener line ends CRLF", () => {
+			// The delimiter word stops at the unquoted CR. No delimiter token is
+			// present, so the opener masks through end of input. The masked span
+			// carries that CR. The msys read layer strips it, and POSIX bash
+			// keeps it as ordinary content. The two layers would mask different
+			// bytes, so the mask fails closed instead of picking one.
+			const input = "cat << \r\nEOF\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a bare-<< heredoc with a lone-CR body line", () => {
+			// The lone CR terminates a line for one read layer and is stripped
+			// content for the other, so the masked span again spans bytes the two
+			// layers do not read identically, and the mask fails closed.
+			const input = "cat << \r\nEOF\n\r\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a bare-<< heredoc whose CR rides directly against the opener", () => {
+			// Same shape with no blank between `<<` and the CR: the word break
+			// lands on the CR itself, and the CR is still inside the masked span.
+			const input = "cat <<\r\nEOF\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed when a CR sits in a bare-<< mask away from the opener", () => {
+			// The check spans the whole masked region, not just the bytes next
+			// to `<<`. The opener line here is pure LF, and the CR opens the
+			// first masked line. Both read layers make this construct
+			// never-runnable. Failing it closed over-rejects. That is the
+			// accepted cost of keeping one region rule for every masked heredoc
+			// span.
+			const input = "cat <<\nEOF\r\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a <<- heredoc with no delimiter word and a CRLF opener line", () => {
+			// The dashed form strips tabs before reaching the same no-delimiter
+			// masking, so the emission check covers it identically.
+			const input = "cat <<- \r\nEOF\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("keeps masking a CR-free bare-<< opener through end of input", () => {
+			// Accept-path control: a CR-free masked span is byte-identical under
+			// both read layers, so the bare-<< masking policy is unchanged and a
+			// CR-free opener still masks through end of input.
+			const input = "cat <<\nEOF\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input])
+		})
+
+		it("accepts a CR on the line before a heredoc's opener line", () => {
+			// The masking check spans only the opener-through-terminator region,
+			// not the whole command: a CR before the opener is ordinary content
+			// of an earlier line and both read layers agree on the CR-free
+			// region, so the heredoc masks and the surrounding commands split.
+			const input = "printf x\r\ncat <<EOF\nbody\nEOF\ncat ok\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["printf x", "cat <<EOF\nbody\nEOF", "cat ok"])
+		})
+
+		it("accepts a CR after a heredoc's terminator line", () => {
+			// This is the opposite case of the pin above. A CR past the closing
+			// terminator sits outside the masked region. The region stays
+			// byte-identical under both read layers. The heredoc masks, and the
+			// trailing CRLF line still splits as its own command.
+			const input = "cat <<EOF\nbody\nEOF\nprintf y\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF\nbody\nEOF", "printf y"])
+		})
+	})
+
+	describe("grouping parentheses inside substitution frames", () => {
+		// A subshell group `$( ( … ) )` is ordinary syntax: the shell balances
+		// the group's parens independently of the substitution frame, so a bare
+		// `(` inside a frame must be tracked and the group's `)` must not pop
+		// the frame (which would strand the frame's own closer as a stray).
+
+		it("parses a subshell group inside a command substitution and extracts the group payload", () => {
+			const { commands, parseError } = parseCommand("echo $( (echo safe) )")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "( echo safe )"])
+		})
+
+		it("parses subshell groups inside both sides of a process-substitution pair", () => {
+			const { commands, parseError } = parseCommand("diff >( (echo a) ) <( (echo b) )")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["diff", "( echo a )", "( echo b )"])
+		})
+
+		it("extracts a nested substitution through an enclosing group", () => {
+			const { commands, parseError } = parseCommand("echo $( (echo $(whoami)) )")
+			expect(parseError).toBeNull()
+			// The group's text is sliced at the nested substitution's closer,
+			// so the group's shell-word remnants flank the payload segment.
+			expect(commands).toEqual(["echo", "( echo", "whoami", ")"])
+		})
+
+		it("fails closed on a group left unclosed inside a substitution", () => {
+			// bash refuses this input with "unexpected EOF". The parser still
+			// reports the open frames. The cost is a prompt, never a free pass.
+			const input = "echo $( (echo x"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("extracts the group of a mis-nested $(( … ) … ) as its own segment", () => {
+			// bash reads a `$((` whose depth-1 closer is not doubled as a
+			// command substitution containing a subshell group, and runs the
+			// group's command. The payload must surface as its own segment
+			// instead of hiding inside the host word the way arithmetic does.
+			const { commands, parseError } = parseCommand("echo $((rm -rf /) )")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "( rm -rf / )"])
+		})
+
+		it("keeps closed $(( … )) and $[ … ] arithmetic masked", () => {
+			// Non-regression controls: the closer-adjacency guard must not
+			// touch well-formed arithmetic, where the depth-1 closer is the
+			// first character of the `))` token by construction.
+			expect(parseCommand("echo $((1+2))").commands).toEqual(["echo $((1+2))"])
+			expect(parseCommand("echo $(( (1) ))").commands).toEqual(["echo $(( (1) ))"])
+			expect(parseCommand("echo $[1+2]").commands).toEqual(["echo $[1+2]"])
+			expect(findUnterminatedQuote("echo $(( x")?.quoteType).toBe("arithmetic")
+		})
+
+		it("extracts a mis-nested $(( … ) … ) group from an unquoted heredoc body", () => {
+			// The body walk re-routes the opener the same way the main scan
+			// does, so a group hidden behind an allowlisted `cat` still gets
+			// its own segment.
+			const input = "cat <<EOF\n$((rm -rf /) )\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "( rm -rf / )"])
+		})
+
+		it("routes a nested mis-nested $(( through the frame and fails unclosed forms closed", () => {
+			const { commands, parseError } = parseCommand("echo $( $((rm -rf /) ) )")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "( rm -rf / )"])
+			// Without any depth-1 closer the opener stays arithmetic, as before.
+			const unclosed = parseCommand("echo $((rm -rf /")
+			expect(unclosed.commands).toEqual(["echo $((rm -rf /"])
+			expect(unclosed.parseError?.quoteType).toBe("arithmetic")
+			// With a closer that never doubles, the converted frame is the
+			// outermost construct that cannot close.
+			const halfClosed = parseCommand("echo $((rm -rf /) ")
+			expect(halfClosed.commands).toEqual(["echo $((rm -rf /) "])
+			expect(halfClosed.parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("extracts a grouped substitution whole from an unquoted heredoc body", () => {
+			// The body walk balances groups inside an expansion frame the way
+			// the main scan does. It treats quotes inside the frame as shell
+			// syntax. If a group's closer sliced the frame here, it would
+			// truncate the payload.
+			const input = "cat <<EOF\n$( (echo safe) )\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "( echo safe )"])
+		})
+
+		it("parses multiple groups in one frame and keeps parens literal inside a parameter expansion", () => {
+			// `(…)` inside `${…}` is literal word content, not a group, so the
+			// expansion host stays verbatim and no frame tracking applies.
+			const { commands, parseError } = parseCommand("echo $( (echo a) && (echo b) ) ${x:-(lit)}")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "( echo a )", "( echo b )", "${x:-(lit)}"])
+		})
+	})
+
+	describe("quotes inside an expansion frame in a heredoc body", () => {
+		// The shell tokenizes inside a substitution frame. A quote there is
+		// therefore shell syntax. Its region masks the frame's closer and any
+		// group test. A frame walk that reads a quoted `)` as the frame's
+		// closer slices the payload. That leaves the bash-executed tail
+		// unaccounted for. The main scan already blocks this shape through
+		// quote-state gating.
+
+		it("does not slice the frame at a quoted closer: the tail is its own segment", () => {
+			// bash runs both `echo ")"` and `curl evil` from this body line.
+			// Both must therefore surface as independent segments. Neither may
+			// hide inside the frame's host word without its own check.
+			const { commands, parseError } = parseCommand('cat <<EOF\n$( (echo ")") ; curl evil)\nEOF')
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<EOF\n$( (echo ")") ; curl evil)\nEOF', '( echo ")" )', "curl evil"])
+		})
+
+		it("masks a single-quoted closer in the frame and extracts the tail separately", () => {
+			const { commands, parseError } = parseCommand("cat <<EOF\n$( (echo ')') ; curl evil)\nEOF")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF\n$( (echo ')') ; curl evil)\nEOF", "( echo ')' )", "curl evil"])
+		})
+
+		it("fails closed on a quoted closer in the frame under CRLF line endings", () => {
+			// Every CR from the opener line through the closing terminator line
+			// sits in a region the two read layers treat differently. msys
+			// strips each CR, and POSIX keeps it as content. The body boundary
+			// cannot then be proven in a model-independent way. The heredoc
+			// fails closed before the frame walk ever runs. This over-rejects
+			// even a uniformly-CRLF heredoc whose two models would agree.
+			const input = 'cat <<EOF\r\n$( (echo ")") ; curl evil)\r\nEOF\r\n'
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("treats a quoted ( in the frame as text, not a group opener", () => {
+			// If `(` inside the quotes opened a group, the frame's own `)` would
+			// be swallowed balancing it and the payload slice would shift.
+			const { commands, parseError } = parseCommand('cat <<EOF\n$( echo "a(b" ; curl evil)\nEOF')
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<EOF\n$( echo "a(b" ; curl evil)\nEOF', 'echo "a(b"', "curl evil"])
+		})
+
+		it("fails closed when a quote opened inside a frame never closes before the terminator", () => {
+			// The open region swallows the rest of the body (and the terminator is
+			// still body text to bash), so nothing after it can be accounted for.
+			const input = 'cat <<EOF\n$( echo "unclosed\nEOF\n'
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("masks a quoted closer in an opener-remainder frame too", () => {
+			// The opener line's remainder shares the body walk, so it must carry
+			// the same quote gating.
+			const { commands, parseError } = parseCommand('cat <<EOF $( (echo ")") ; curl evil)\nbody\nEOF')
+			expect(parseError).toBeNull()
+			// The remainder stays live host text, so the frame's tail also
+			// splits as host segments on top of the routed payload segments.
+			expect(commands).toEqual([
+				"cat <<EOF\nbody\nEOF $ ( ( echo ) )",
+				'( echo ")" )',
+				"curl evil",
+				"curl evil )",
+			])
+		})
+	})
+
+	describe("comments inside an expansion frame in a heredoc body", () => {
+		// A word-initial `#` inside a `$(…)` frame opens a comment. The shell
+		// skips the comment to end of line. A frame walk that reads the `#` as
+		// ordinary text pops the frame at a `)` inside that comment. It then
+		// slices the payload. That leaves the bash-executed continuation lines
+		// hidden inside the opaque heredoc host word. The quote gating above
+		// already blocks this shape.
+
+		it("keeps a frame open across its comment and extracts the continuation tail", () => {
+			// bash runs BOTH `echo ok` and `curl evil` from this body: the
+			// comment's `)` never closes the frame, the real closer is the later
+			// `)`, and each executed command becomes its own segment.
+			const input = "cat <<EOF\n$( echo ok # )\ncurl evil)\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "echo ok", "curl evil"])
+		})
+
+		it("fails closed on a comment frame under CRLF line endings", () => {
+			// A CR between the opener line and the closing terminator line
+			// leaves the two layers reading different bytes. The close cannot
+			// then be verified in a model-independent way. The heredoc fails
+			// closed before the frame walk ever runs. This over-rejects even
+			// this uniformly-CRLF input, whose two models happen to agree.
+			const input = "cat <<EOF\r\n$( echo ok # )\r\ncurl evil)\r\nEOF\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("treats a # inside a quoted frame region as literal text", () => {
+			// A comment starts only outside a quote, so the quoted `#)` masks the
+			// closer exactly as an unquoted `)` would and the tail stays in the
+			// payload.
+			const { commands, parseError } = parseCommand('cat <<EOF\n$( echo "#)" ; curl evil)\nEOF')
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<EOF\n$( echo "#)" ; curl evil)\nEOF', 'echo "#)"', "curl evil"])
+		})
+
+		it("treats a space-preceded # inside a quoted frame region as literal text", () => {
+			// The `#` sits at a word boundary yet inside double quotes, where the
+			// shell keeps it literal: only the quote frame's opacity separates it
+			// from the comment rule, and the tail must still surface.
+			const { commands, parseError } = parseCommand('cat <<EOF\n$( echo "a # b" ; curl evil)\nEOF')
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<EOF\n$( echo "a # b" ; curl evil)\nEOF', 'echo "a # b"', "curl evil"])
+		})
+
+		it("treats a # attached to a word as part of the word, not a comment", () => {
+			// bash starts a comment only at a word boundary, so `x=a#b` is one
+			// argument and the `;` still separates a second executed command.
+			const { commands, parseError } = parseCommand("cat <<EOF\n$( echo x=a#b ; curl evil )\nEOF")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF\n$( echo x=a#b ; curl evil )\nEOF", "echo x=a#b", "curl evil"])
+		})
+
+		it("preserves a mid-word # in a top-level argument instead of commenting it out", () => {
+			// The argument survives whole so a later separator can never hide
+			// behind a tokenizer comment: bash runs `echo x=a#b`, and the tail
+			// after `;` still splits into its own segment.
+			expect(parseCommand("echo x=a#b").commands).toEqual(["echo x=a#b"])
+			expect(parseCommand("echo x=a#b ; curl evil").commands).toEqual(["echo x=a#b", "curl evil"])
+		})
+
+		it("treats a # at the frame's content start as a comment", () => {
+			// A `#` right after `(` sits at a word boundary. bash comments out the
+			// `)` on that line. The frame closes at the later `)`, and that runs
+			// `curl evil`.
+			const { commands, parseError } = parseCommand("cat <<EOF\n$(# ok )\ncurl evil)\nEOF")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF\n$(# ok )\ncurl evil)\nEOF", "curl evil"])
+		})
+
+		it("keeps a group's comment-blind closer from slicing the frame", () => {
+			// The group's `)` sits inside the comment, so the group never closes
+			// inside the frame. Whatever the re-scan makes of the rest, the
+			// bash-executed `curl evil` must surface as its own segment.
+			const input = "cat <<EOF\n$( (echo x # )\n) ; curl evil)\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "( echo x", ")", "curl evil"])
+		})
+
+		it("fails closed when a comment swallows the frame's only closer", () => {
+			// bash refuses this input with an unexpected-EOF error for the
+			// missing `)`. The open frame must therefore fail the whole command
+			// closed. It must never approve it.
+			const input = "cat <<EOF\n$( echo # )\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("fails closed on the same comment shape in the opener-line remainder", () => {
+			// The walk of the remainder stops at the line end. The comment
+			// therefore leaves the frame open at that boundary, and the heredoc
+			// fails closed. bash also refuses the input outright.
+			const input = "cat <<EOF $( echo a # )\ncurl evil)\nbody\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("keeps a # literal inside a parameter expansion (length and trim operators)", () => {
+			// `${#var}` and `${x#pat}` are operator syntax, never comments. The
+			// expansion host therefore stays verbatim, and nothing fails closed.
+			expect(parseCommand("cat <<EOF\n${#var}\nEOF").commands).toEqual(["cat <<EOF\n${#var}\nEOF"])
+			expect(parseCommand("cat <<EOF\n${x#pat}\nEOF").commands).toEqual(["cat <<EOF\n${x#pat}\nEOF"])
+		})
+
+		it("parses the non-heredoc equivalent at top level (main-scan parity)", () => {
+			// The same payload outside a body reaches a `)` at depth 0 once the
+			// comment hides the context of its matching closer. A depth-0 `)`
+			// cannot hide a substitution, so the closer stays host text and the
+			// second line still segments on its own.
+			const input = "$( echo ok # )\ncurl evil)"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo ok", "curl evil )"])
+		})
+	})
+
+	describe("# riding at an expansion closer continues the word", () => {
+		// bash starts a comment only at a word start. An expansion's closer ends
+		// the expansion but not the surrounding word. A `#` directly after `)`,
+		// `}`, a backtick, or a `]]`-style closer is therefore word content. A
+		// later `;` still separates a command that bash executes. The tokenizer
+		// starts a comment at any unquoted `#`, so the character must travel
+		// through tokenization in masked form. A space before the `#` puts it at
+		// a word start, and there the shell's comment behavior applies.
+
+		it("extracts the tail after a # riding at a command-substitution closer", () => {
+			// bash runs `curl evil` as its own command from this line. The
+			// tail's segment makes the decision a prompt, never an approval.
+			const { commands, parseError } = parseCommand("echo x=$(echo ok)#;curl evil")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo x=", "echo ok", "#", "curl evil"])
+		})
+
+		it("extracts the tail after a # riding at an arithmetic closer", () => {
+			// `$((…))` and the deprecated `$[…]` both end at their closer. The
+			// word continues past it, so the tail after `;` splits in both cases.
+			expect(parseCommand("echo $((1))#;curl evil").commands).toEqual(["echo $((1))#", "curl evil"])
+			expect(parseCommand("echo $[1]#;curl evil").commands).toEqual(["echo $[1]#", "curl evil"])
+		})
+
+		it("extracts the tail after a # riding at a backtick closer", () => {
+			const { commands, parseError } = parseCommand("echo x=`echo ok`#;curl evil")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo x=", "echo ok", "#", "curl evil"])
+		})
+
+		it("extracts the tail after a # riding at a process-substitution closer", () => {
+			// bash expands `<(…)` to a path. The word continues past the closer,
+			// so the tail after `;` really executes.
+			const { commands, parseError } = parseCommand("cat <(echo ok)#;curl evil")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat", "echo ok", "#", "curl evil"])
+		})
+
+		it("extracts the tail after a # riding at a parameter-expansion closer", () => {
+			expect(parseCommand("echo ${x:-a}#;curl evil").commands).toEqual(["echo ${x:-a}#", "curl evil"])
+		})
+
+		it("extracts the tail after a # riding at a closing quote", () => {
+			// Quote removal still leaves the word unbroken. `echo "a"#` runs
+			// `echo a#`, and the tail after `;` is a separate command.
+			expect(parseCommand('echo "a"#;curl evil').commands).toEqual(['echo "a"#', "curl evil"])
+		})
+
+		it("keeps a space-preceded # after a closer a comment (tail absent)", () => {
+			// With whitespace between the closer and the `#`, the `#` begins a
+			// word. The shell then comments out the rest of the line. The tail
+			// never runs, so it must not surface as a segment.
+			const { commands, parseError } = parseCommand("echo x=$(echo ok) # comment")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo x=", "echo ok"])
+		})
+
+		it("leaves # operators inside a parameter expansion untouched", () => {
+			// `${x#pat}` and `${#var}` use operator syntax inside the expansion.
+			// The expansion host stays verbatim as one segment. The closer rule
+			// adds no extra masking or splitting inside it.
+			expect(parseCommand("echo ${x#pat}").commands).toEqual(["echo ${x#pat}"])
+			expect(parseCommand("echo ${#var}").commands).toEqual(["echo ${#var}"])
+			expect(parseCommand("echo ${x#pat};curl evil").commands).toEqual(["echo ${x#pat}", "curl evil"])
+		})
+	})
+
+	describe("# riding at the end of a backslash escape pair continues the word", () => {
+		// To bash, an escaped character is ordinary word content. The word
+		// therefore continues past a `\c` pair, whatever `c` is. Whitespace or a
+		// metacharacter in the raw text does not put a following `#` at a word
+		// start. The tokenizer starts a comment at any unquoted `#`, so this
+		// position must travel through tokenization in masked form, as in the
+		// expansion-closer case. A real space, not an escaped one, before the
+		// `#` puts it at a word start, and there the shell's comment behavior
+		// applies.
+
+		it("extracts the tail after a # riding at any escaped-character end", () => {
+			// bash runs `curl evil` as its own command from each of these lines.
+			// The escaped character keeps the word open, the `#` is word
+			// content, and the `;` after it separates a second command.
+			expect(parseCommand("echo a\\)#;curl evil").commands).toEqual(["echo a)#", "curl evil"])
+			expect(parseCommand("echo a\\;#;curl evil").commands).toEqual(["echo a;#", "curl evil"])
+			expect(parseCommand("echo a\\ #;curl evil").commands).toEqual(["echo a #", "curl evil"])
+			expect(parseCommand("echo a\\|#;curl evil").commands).toEqual(["echo a|#", "curl evil"])
+			expect(parseCommand("echo a\\&#;curl evil").commands).toEqual(["echo a&#", "curl evil"])
+			expect(parseCommand("echo a\\<#;curl evil").commands).toEqual(["echo a<#", "curl evil"])
+			expect(parseCommand("echo a\\}#;curl evil").commands).toEqual(["echo a}#", "curl evil"])
+		})
+
+		it("keeps a # after an escaped ordinary character literal (mid-word control)", () => {
+			// `a\bc#c` is one word to bash. The `#` was already mid-word here,
+			// without the escape-end rule. This case is pinned so that a future
+			// narrowing of either word-content rule shows up here.
+			expect(parseCommand("echo a\\bc#c;curl evil").commands).toEqual(["echo abc#c", "curl evil"])
+		})
+
+		it("keeps an escaped # literal and never a comment", () => {
+			// `\#` is an escaped character like any other. bash prints the hash
+			// character, and a `;` directly after the pair still separates a
+			// command.
+			expect(parseCommand("echo a\\#b").commands).toEqual(["echo a#b"])
+			expect(parseCommand("echo a\\#;curl evil").commands).toEqual(["echo a#", "curl evil"])
+		})
+
+		it("keeps a real-space-preceded # after an escape pair a comment (tail absent)", () => {
+			// `echo a\) #c` ends the word at the unescaped space. bash therefore
+			// comments out the rest of the line. The tail never runs, so it must
+			// not surface as a segment.
+			expect(parseCommand("echo a\\) #c;curl evil").commands).toEqual(["echo a)"])
+		})
+
+		it("extracts the tail after a # joined by a line continuation", () => {
+			// The continuation joins `a` and `#c` into one word before the shell
+			// tokenizes, so bash runs `curl evil`. The split segments keep that
+			// tail accountable either way.
+			expect(parseCommand("echo a\\\n#c;curl evil").commands).toEqual(["echo a", "#c", "curl evil"])
+		})
+	})
+
+	describe("unclosed quote in a heredoc delimiter fails closed", () => {
+		// A quote character inside the delimiter word opens a quote region. bash
+		// carries that region across newlines until its closing quote. A word
+		// that still has a region open at end of input is a delimiter that no
+		// body line can ever match. The opener line's tail keeps executing as
+		// ordinary syntax. This is exactly where a mask to end of input would
+		// hand bash's separate commands to the allowlists unaccounted for.
+
+		it("fails closed on the CR-delimited unclosed-quote delimiter (the approval-bypass shape)", () => {
+			// bash closes the delimiter's quote on the second line. It then runs
+			// `; rm -rf /` as its own command. Masking would auto-approve it.
+			const input = "cat <<'X\r\n'; rm -rf /\nX\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on an LF-terminated unclosed single-quoted delimiter", () => {
+			const input = "cat <<'X\n'; rm -rf /\nX\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on an unclosed double-quoted delimiter", () => {
+			const input = 'cat <<"X\n"; rm -rf /\nX\n'
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a quote opened mid-word in an otherwise unquoted delimiter", () => {
+			// bash starts a quote anywhere in a word. `<<EOF'` therefore swallows
+			// the rest of the input just like `<<'EOF`. A fix for only the
+			// leading-quote forms would leave this sibling case open.
+			const input = "cat <<EOF'\n'; rm -rf /\nX\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("parses a closed mid-word quote as the literal concatenated terminator", () => {
+			// `<<EOF'x'` is well-formed bash. After quote removal, the terminator
+			// is the literal word EOFx. Rejecting it would over-fire.
+			const { commands, parseError } = parseCommand("cat <<EOF'x'\nbody\nEOFx\n")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF'x'\nbody\nEOFx"])
+		})
+
+		it("propagates a malformed delimiter from a heredoc opened inside a substitution", () => {
+			const input = "echo $(cat <<'X\ny\n)"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+	})
+
+	describe("process substitution >(…) extraction", () => {
+		// `>(…)` shares the frames with `<(…)`. It writes where `<(…)` reads. The
+		// inner command runs unconditionally, and its output goes to a device
+		// file. Its payload must therefore match the lists on its own.
+
+		it("extracts the payload of a >() process substitution as its own segment", () => {
+			const { commands, parseError } = parseCommand("cat >(evil)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat", "evil"])
+		})
+
+		it("reports an unclosed >() region", () => {
+			const input = "cat >(evil"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("process-substitution")
+		})
+
+		it("extracts both payloads of a >() nested inside <()", () => {
+			expect(parseCommand("cat >(a <(b))").commands).toEqual(["cat", "a", "b"])
+		})
+
+		it("keeps >(…) inside double quotes opaque (no extraction, no split)", () => {
+			// Quoted text is never shell syntax. bash prints it literally.
+			const input = 'cat ">(evil)"'
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input])
+		})
+	})
+
+	describe("body-walk and masking edge coverage", () => {
+		// The structural tests above reach some scan regions only partially. Each
+		// input here pins one masking or extraction branch of the body walk, the
+		// opener-line remainder, or the redirection/variable scanners.
+
+		it("extracts a backtick payload from an unquoted heredoc body", () => {
+			const input = "cat <<EOF\n`echo x`\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			// Backticks do not nest, but a pair still delimits an expansion the
+			// shell runs inside an unquoted body.
+			expect(commands).toEqual([input, "echo x"])
+		})
+
+		it("extracts a substitution inside $[…] within a heredoc body", () => {
+			// bash expands command substitutions inside `$[ … ]`, the deprecated
+			// arithmetic form, before it evaluates it. This works exactly like
+			// `$(( … ))`. The payload must match the lists on its own.
+			const input = "cat <<EOF\n$[1 + $(whoami)]\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "whoami"])
+		})
+
+		it("extracts both process substitutions from a heredoc body", () => {
+			const input = "cat <<EOF\ndiff <(sort a) <(sort b)\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "sort a", "sort b"])
+		})
+
+		it("keeps an empty-quoted delimiter inside a parameter expansion as literal text and leaks no placeholder", () => {
+			const input = "echo ${x:-y <<''\nbody\n\n}"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			// `<<` inside `${…}` is literal word text, so no heredoc mask is
+			// emitted. The expansion host keeps its verbatim text, and no
+			// sentinel leaks into it.
+			expect(commands).toEqual([input])
+			expect(commands.join("")).not.toContain("\x00")
+		})
+
+		it("fails closed on an unclosed substitution in the heredoc opener-line remainder", () => {
+			const input = "cat <<EOF $(unclosed\nbody\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("masks redirections without splitting them or their host command", () => {
+			const { commands, parseError } = parseCommand("echo a 2>&1 && echo b 1>&2")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo a 2>&1", "echo b 1>&2"])
+		})
+
+		it("masks special-parameter variables into one host word", () => {
+			const { commands, parseError } = parseCommand("echo $? $$ $! x")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo $? $$ $! x"])
+		})
+
+		it("restores arithmetic and heredoc placeholders in the shell-quote fallback path", () => {
+			forceShellQuoteFailure = true
+			try {
+				const { commands } = parseCommand("echo $((1+1)) && cat <<EOF\nbody\nEOF")
+				// Every masked placeholder must round-trip to its raw text so the
+				// fallback never surfaces internal markers.
+				expect(commands).toEqual(["echo $((1+1))", "cat <<EOF\nbody\nEOF"])
+				expect(commands.join("")).not.toContain("\x00")
+			} finally {
+				forceShellQuoteFailure = false
+			}
+		})
+
+		it("fails closed on an unclosed substitution riding a later line of the host", () => {
+			const input = "echo a\ncat <<EOF\n$(unclosed\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("masks a closed $[…] at top level as one host word", () => {
+			const { commands, parseError } = parseCommand("echo $[1+2]")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo $[1+2]"])
+		})
+	})
+
+	describe("scanner primitives and frame internals", () => {
+		// Each masking scanner owns an accept/reject boundary. The structural
+		// tests above reach those boundaries only indirectly. Each input here
+		// pins one branch.
+
+		it("treats a lone $ and $ before a space as literal host text", () => {
+			// A `$` with nothing name-like after it is not a variable reference:
+			// bash passes it through, and so must the scanner.
+			expect(parseCommand("echo $").commands).toEqual(["echo $"])
+			expect(parseCommand("echo $ x").commands).toEqual(["echo $ x"])
+		})
+
+		it("masks a $name reference into its host word", () => {
+			const { commands, parseError } = parseCommand("echo $HOME")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo $HOME"])
+		})
+
+		it("masks a bare >& redirection without splitting the host", () => {
+			const { commands, parseError } = parseCommand("echo a >&2")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo a >&2"])
+		})
+
+		it("keeps nested quotes opaque inside a command substitution payload", () => {
+			const { commands, parseError } = parseCommand('echo $(a "b c" d)')
+			expect(parseError).toBeNull()
+			// The payload is one inner command: the quoted space does not split it.
+			expect(commands).toEqual(["echo", 'a "b c" d'])
+		})
+
+		it("extracts a backtick expansion nested inside a command substitution", () => {
+			const { commands, parseError } = parseCommand("echo $(a `b` c)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "a", "b", "c"])
+		})
+
+		it("keeps a lone $ inside a substitution host as literal payload text", () => {
+			const { commands, parseError } = parseCommand("echo $(a $ b)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "a $ b"])
+		})
+
+		it("extracts a substitution nested inside arithmetic within a substitution", () => {
+			// The shell performs $(( … )) expansions inside $( … ), so `y` must
+			// match the lists on its own.
+			const { commands, parseError } = parseCommand("echo $(x $((1+$(y))))")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "x $((1+$(y)))", "y"])
+		})
+
+		it("names the backtick when it is opened inside arithmetic inside a substitution", () => {
+			// The arithmetic interior walk owns the error so it names the
+			// backtick, not the outer frame it would otherwise be blamed on.
+			const input = "echo $(x $(( ` ))"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("backtick")
+		})
+
+		it("names the backtick when it is opened inside arithmetic at top level", () => {
+			const input = "echo $(( `a ))"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("backtick")
+		})
+
+		it("keeps an empty substitution payload from becoming an empty segment", () => {
+			const { commands, parseError } = parseCommand("echo $( )")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo"])
+		})
+
+		it("splits a multi-line substitution payload on its blank-separated lines", () => {
+			const { commands, parseError } = parseCommand("echo $(a\n\nb)")
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["echo", "a", "b"])
+		})
+
+		it("fails closed on an unbalanced quote inside a substitution payload", () => {
+			const input = 'echo $("x)'
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			// End of input reports the outermost frame: the substitution that
+			// can never close because its quoted payload swallowed the closer.
+			expect(parseError?.quoteType).toBe("command-substitution")
+		})
+
+		it("honours a backslash-escaped character inside a double-quoted delimiter", () => {
+			// `<<"a\$b"` undergoes quote removal to the literal word `a$b`, so
+			// the body terminates at the line `a$b`.
+			const input = 'cat <<"a\\$b"\na$b\n'
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<"a\\$b"\na$b'])
+		})
+
+		it("drops a backslash-newline line continuation inside a quoted delimiter", () => {
+			// bash removes the backslash-newline pair inside double quotes, so
+			// the delimiter word is the concatenation `ab`.
+			const input = 'cat <<"a\\\nb"\nab\n'
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<"a\\\nb"\nab'])
+		})
+
+		it("keeps a backslash before a non-escapable character in a double-quoted delimiter", () => {
+			// Inside double quotes, bash drops a backslash only before `$ ` " \
+			// and newline. Before `q` it stays part of the word. The terminator
+			// line is therefore `a\q`, and everything after it is live syntax
+			// again rather than masked body text.
+			const input = 'cat <<"a\\q"\na\\q\nrm -rf /\naq\n'
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<"a\\q"\na\\q', "rm -rf /", "aq"])
+		})
+
+		it("drops a backslash before $ inside a double-quoted delimiter", () => {
+			// `$` is in the escapable set, so the delimiter is the three-char
+			// word `a$q` and the matching body line terminates the heredoc.
+			const input = 'cat <<"a\\$q"\na$q\nrm -rf /\n'
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<"a\\$q"\na$q', "rm -rf /"])
+		})
+
+		it("keeps backslashes verbatim in a single-quoted delimiter", () => {
+			// Single quotes suppress all escaping, so the delimiter is the
+			// literal `a\q` and the terminator line carries the backslash.
+			const input = "cat <<'a\\q'\na\\q\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<'a\\q'\na\\q", "rm -rf /"])
+		})
+
+		it("terminates a double-quoted-delimiter heredoc after a continuation-joined word", () => {
+			// Backslash-newline inside double quotes joins the word, so the
+			// delimiter is `aq` and the following line is already live syntax.
+			const input = 'cat <<"a\\\nq"\naq\nrm -rf /\n'
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(['cat <<"a\\\nq"\naq', "rm -rf /"])
+		})
+
+		it("terminates an unquoted heredoc whose delimiter is split by line continuation", () => {
+			// bash joins backslash-newline pairs before testing a body line
+			// against the terminator, so `EO\` + `F` ends the heredoc there and
+			// the following line executes rather than staying masked body text.
+			const input = "cat <<EOF\nEO\\\nF\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF\nEO\\\nF", "rm -rf /"])
+		})
+
+		it("does not join backslash-newline inside a quoted-delimiter body", () => {
+			// A quoted delimiter makes every body backslash literal, so `EO\`
+			// + `F` is ordinary body text and only the real `EOF` line ends the
+			// heredoc.
+			const input = "cat <<'EOF'\nEO\\\nF\nrm -rf /\nEOF\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<'EOF'\nEO\\\nF\nrm -rf /\nEOF"])
+		})
+
+		it("strips the joined <<- terminator line's leading tabs after joining continuations", () => {
+			// The join assembles the candidate from raw physical lines first;
+			// tab stripping then applies once to that joined line, so the
+			// tab-indented `EO\` + `F` pair still matches `EOF`.
+			const input = "cat <<-EOF\n\tEO\\\nF\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<-EOF\n\tEO\\\nF", "rm -rf /"])
+		})
+
+		it("strips every leading tab of the <<- terminator line", () => {
+			// Indentation depth is irrelevant: all leading tabs are stripped,
+			// so a multiply tabbed terminator still matches the delimiter.
+			const input = "cat <<-EOF\nbody\n\t\tEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input])
+		})
+
+		it("keeps a continuation line's tab inside the <<- terminator candidate", () => {
+			// Stripping after joining leaves `EO\tF` for the pair with a tab on
+			// both lines. The heredoc therefore runs to the real `EOF` line
+			// instead of closing early. The commands after it stay visible for
+			// approval checks, exactly as bash executes them.
+			const input = "cat <<-EOF\n\tEO\\\n\tF\ncat <<X\nEOF\nrm -rf /\nX\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<-EOF\n\tEO\\\n\tF\ncat <<X\nEOF", "rm -rf /", "X"])
+		})
+
+		it("strips a tab that joins into the front of the <<- terminator", () => {
+			// A continuation-only backslash leaves the candidate starting at
+			// the next physical line, so the tab that opens it is the joined
+			// line's leading tab and stripping removes it: the terminator
+			// matches and the following command is live.
+			const input = "cat <<-EOF\n\t\\\n\tEOF\ntouch x\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<-EOF\n\t\\\n\tEOF", "touch x"])
+		})
+
+		it("leaves a <<- heredoc unterminated when the joined candidate differs from the delimiter", () => {
+			// `EO\` + `\tF` joins to `EO\tF`, which stays unequal to `EOF`
+			// after stripping the joined line's leading tab: bash finds no
+			// terminator and reads the body to end of input, so the scan
+			// fails closed rather than validating the construct.
+			const input = "cat <<-EOF\nEO\\\n\tF\nrm -rf /\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("does not join a line ending in an even number of backslashes", () => {
+			// Two trailing backslashes escape each other, so the line ends
+			// literally and the body runs to the real terminator.
+			const input = "cat <<EOF\nX\\\\\nrm -rf /\nEOF\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF\nX\\\\\nrm -rf /\nEOF"])
+		})
+
+		it("closes the heredoc after an even backslash run and keeps the following command live", () => {
+			// bash joins only odd backslash runs before matching the
+			// terminator. The two backslashes escape each other, so the line
+			// is ordinary body text and the next `EOF` closes the heredoc.
+			// bash then runs `touch x`. A join over the even run would merge
+			// the terminator into the body text, hide the live line as body,
+			// and report the whole command unterminated.
+			const input = "cat <<EOF\nX\\\\\nEOF\ntouch x"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual(["cat <<EOF\nX\\\\\nEOF", "touch x"])
+		})
+
+		it("fails closed on a heredoc whose continuation joins over a CRLF line ending", () => {
+			// The msys/Cygwin read layer is the reference shell on the Windows
+			// target. It strips the CR from every line it reads. The logical
+			// line therefore ends with the lone backslash and continues into
+			// the `F` line. That joins the candidate into the `EOF` terminator.
+			// POSIX bash reads `\<CR>` as an escaped CR, with no join, so the
+			// two models close on different lines. A continuation that consumes
+			// a CRLF makes the mask boundary model-dependent. The heredoc
+			// therefore fails closed for review instead of guessing which model
+			// decides it.
+			const input = "cat <<EOF\r\nEO\\\r\nF\r\ntouch x\r\nEOF\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a heredoc body line carrying a lone CR", () => {
+			// The read-layer CR strip leaves `EO\F`: no continuation, and the
+			// body runs to the real terminator. POSIX bash reads the backslash
+			// as escaping the CR. Here the models happen to agree. The CR still
+			// leaves the two layers reading different bytes, so the close cannot
+			// be verified in a model-independent way. Such a heredoc fails
+			// closed. That is the accepted cost of never picking a model.
+			const input = "cat <<EOF\nEO\\\rF\ntouch x\nEOF\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on an unquoted heredoc at a bare-CR-concatenated terminator candidate", () => {
+			// The msys/Cygwin read layer strips the bare CR. The body line then
+			// arrives as the terminator `EOF`, and the heredoc closes early.
+			// That leaves `curl evil` live. POSIX bash keeps the CR and does
+			// not close here. An early close feeds the remaining body back to
+			// the scanner as live syntax. The divergence therefore fails closed
+			// instead of choosing a model.
+			const input = "cat <<EOF\nEO\rF\ncurl evil\nEOF\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a <<- heredoc at a bare-CR-concatenated tabbed terminator candidate", () => {
+			// Tab stripping applies to the CR-stripped logical line, so the
+			// tab-indented `EO<CR>F` pair still matches `EOF` under the msys
+			// read layer while POSIX bash keeps the CR. The model-dependent
+			// close fails closed.
+			const input = "cat <<-EOF\n\tEO\rF\ncurl evil\nEOF\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a quoted-delimiter heredoc at a bare-CR-concatenated terminator candidate", () => {
+			// The CR strip happens in the shell's read layer before quoting is
+			// considered, so a quoted delimiter does not protect the body: the
+			// msys model closes early at the `EO<CR>F` line while POSIX bash
+			// keeps the body open. The divergence fails closed.
+			const input = "cat <<'EOF'\nEO\rF\ncurl evil\nEOF\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a heredoc body line whose stripped content only contains the delimiter", () => {
+			// Stripping yields `EOFx`, which is not the terminator. The msys
+			// read line therefore keeps the body open until the real `EOF`
+			// line. POSIX bash keeps `EOF<CR>x` as ordinary body content. Both
+			// models close at the same final `EOF` line. The CR inside the
+			// opener-through-terminator region still leaves the two layers
+			// reading different bytes. The close cannot then be verified in a
+			// model-independent way, so the input fails closed for review. That
+			// over-rejection is accepted, because confirming the agreement
+			// would mean modeling both read layers.
+			const input = "cat <<EOF\nEOF\rx\ncurl evil\nEOF\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed when an early CR close would re-expose a fake heredoc opener", () => {
+			// The msys read layer strips the bare CR from `EO<CR>F`. That closes
+			// the first heredoc early. The scanner would then read the body
+			// line `cat <<X` as a live opener whose body masks `rm -rf /`.
+			// POSIX bash keeps the CR and runs the line after the real `EOF`.
+			// The region CR test fails this closed instead of choosing a model.
+			const input = "cat <<EOF\nEO\rF\ncat <<X\nEOF\nrm -rf /\nX\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed when a CRLF-joined close exposes a second masking heredoc", () => {
+			// Under the msys read layer, `EO\` plus the CRLF joins into the
+			// `EOF` terminator. The body text this exposes opens a second
+			// heredoc that masks `printf`. POSIX bash executes that `printf`:
+			// there `\<CR>` escapes the CR, and no join happens. The models
+			// diverge, so the input fails closed.
+			const input = "cat <<EOF\r\nEO\\\r\nF\r\ncat <<X\r\nEOF\r\nprintf 'MARKER\\n' #\r\nX\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed when a CRLF-joined terminator candidate masks a following command", () => {
+			// The msys read layer joins `x\` with the next line across the CRLF
+			// into `xEOF`. The heredoc therefore matches only the final `EOF`
+			// and masks the line in between. POSIX bash reads the delimiter
+			// word as `EOF<CR>` and ends the body two lines earlier. It then
+			// executes the masked line. The divergence fails closed.
+			const input = "cat <<EOF\r\nx\\\r\nEOF\r\nrm -rf /\r\nEOF\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a CRLF opener line whose CR leaves the scanned body CR-free", () => {
+			// The opener line's CRLF makes msys read the delimiter `EOF` while
+			// POSIX bash reads `EOF<CR>`, so the CR-free `EOF` body line closes
+			// the heredoc for msys only and the following `cat <<X` opener would
+			// mask `rm -rf /` under one model. The CR sits on the consumed opener
+			// line ending, yet it is inside the opener-through-terminator region,
+			// so the heredoc fails closed.
+			const input = "cat <<EOF\r\nbody\nEOF\ncat <<X\nrm -rf /\nX\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a CRLF opener line of a <<- heredoc", () => {
+			// Tab stripping is orthogonal to the region test: the opener line's
+			// CR already makes the delimiter word model-dependent.
+			const input = "cat <<-EOF\r\nbody\nEOF\ncat <<X\nrm -rf /\nX\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a CRLF opener line of a quoted-delimiter heredoc", () => {
+			// Quoting suppresses body expansion, not the read-layer CR strip, so
+			// the delimiter word still diverges between the models.
+			const input = "cat <<'EOF'\r\nbody\nEOF\ncat <<X\nrm -rf /\nX\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed when the terminator line itself carries a CRLF the opener lacks", () => {
+			// With an LF-terminated opener, both models read the delimiter as
+			// `EOF`. The CR inside the terminator candidate is ordinary content
+			// for POSIX bash, so there `EOF<CR>` never matches. The msys read
+			// layer strips that CR and closes the body at that line. That
+			// exposes the `cat <<X` opener, which masks `rm -rf /`. The CR sits
+			// inside the region at the match, so the heredoc fails closed.
+			const input = "cat <<EOF\nEOF\r\ncat <<X\nEOF\nrm -rf /\nX\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a quoted-delimiter heredoc whose terminator line carries a CRLF", () => {
+			// The read-layer strip runs before quoting is considered, so the
+			// quoted form diverges the same way at the terminator line.
+			const input = "cat <<'EOF'\nEOF\r\ncat <<X\nEOF\nrm -rf /\nX\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("fails closed on a heredoc whose opener and terminator CR placement mirrors across models", () => {
+			// The first heredoc's opener ends with CRLF, and its terminator line
+			// ends with LF. The masking heredoc below shows the reversed pair.
+			// Each CR sits inside its construct's opener-through-terminator
+			// region, so no model-dependent close can be picked.
+			const input = "cat <<EOF\r\nEOF\ncat <<X\nEOF\r\nrm -rf /\r\nX\r\n"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("treats a backslash at end of input as part of the delimiter word", () => {
+			// Nothing follows the backslash to escape, so the word keeps it and
+			// no body line can match: the heredoc is unterminated.
+			const input = "cat <<EOF\\"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("heredoc")
+		})
+
+		it("honours a backslash-escaped closer inside a substitution in a heredoc body", () => {
+			// In an unquoted body `\)` escapes the closer, so the region runs to
+			// its real `)` and the payload keeps the literal `)`.
+			const input = "cat <<EOF\n$(a \\) b)\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "a ) b"])
+		})
+
+		it("keeps a backslash-escaped $ in a heredoc body literal", () => {
+			const input = "cat <<EOF\n\\$(x)\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			// The escaped $ is data, not an opener: nothing is extracted.
+			expect(commands).toEqual([input])
+		})
+
+		it("keeps a bare $ prefixing a name in a heredoc body as host text", () => {
+			const input = "cat <<EOF\n$HOME\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input])
+		})
+
+		it("routes a body-walk parameter expansion payload out of its frame", () => {
+			const input = "cat <<EOF\n${y:-$(evil)}\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "evil"])
+		})
+
+		it("routes payloads through nested parameter expansions in a heredoc body", () => {
+			const input = "cat <<EOF\n${y:-${x:-$(evil)}} $z\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			// Both expansions are expansion-active when y is unset, so `evil`
+			// is evaluated independently of the allowlisted `cat`.
+			expect(commands).toEqual([input, "evil"])
+		})
+
+		it("extracts a substitution inside arithmetic within a heredoc body", () => {
+			const input = "cat <<EOF\n$((1+$(whoami)))\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(parseError).toBeNull()
+			expect(commands).toEqual([input, "whoami"])
+		})
+
+		it("fails closed on unclosed arithmetic inside a heredoc body", () => {
+			const input = "cat <<EOF\n$((1+2\nEOF"
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("arithmetic")
+		})
+
+		it("fails closed when body-walk arithmetic nesting exceeds the scan bound", () => {
+			// Recursing through 65 nested arithmetic interiors would expand the
+			// generated input without bound. The walk stops and fails closed.
+			const body = "$((".repeat(65) + "x" + "))".repeat(65)
+			const input = `cat <<EOF\n${body}\nEOF`
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("nesting-too-deep")
+		})
+
+		it("fails closed when substitution re-scan nesting exceeds the depth bound", () => {
+			const input = `echo${" $(a".repeat(70)}${")".repeat(70)}`
+			const { commands, parseError } = parseCommand(input)
+			expect(commands).toEqual([input])
+			expect(parseError?.quoteType).toBe("nesting-too-deep")
+		})
+
+		it("restores a substitution placeholder on the crude-split fallback path", () => {
+			forceShellQuoteFailure = true
+			try {
+				const { commands } = parseCommand("echo $(whoami) && cat <<EOF\nbody\nEOF")
+				// The fallback has no payload re-scan, so the masked substitution
+				// is restored inline into its host word instead of dropped, and
+				// the heredoc placeholder round-trips to its raw text.
+				expect(commands).toEqual(["echo whoami", "cat <<EOF\nbody\nEOF"])
+				expect(commands.join("")).not.toContain("\x00")
+			} finally {
+				forceShellQuoteFailure = false
+			}
+		})
+	})
 })
diff --git a/src/shared/parse-command.ts b/src/shared/parse-command.ts
index edaebcb81a..feb9efe3ce 100644
--- a/src/shared/parse-command.ts
+++ b/src/shared/parse-command.ts
@@ -3,29 +3,72 @@ import { parse } from "shell-quote"
 export type ShellToken = string | { op: string } | { command: string }
 
 /**
- * The style of quoting that opened a region.
+ * The kind of structural region a malformed-command error refers to.
  *
- * - `posix-single` and `ansi-c` share the `'` delimiter but follow different
- *   escaping rules, so they must be distinguished.
- * - `locale` and `double` share the `"` delimiter but `locale` is prefixed with
- *   `$` (like ANSI-C), making `$"..."` a distinct token for accurate restoration.
- * - `heredoc` covers `<<WORD`, `<<'WORD'`, `<<"WORD"`, and `<<\WORD` openers
- *   whose body extends through the terminator line.
+ * Quote and heredoc kinds describe regions that open and never close:
+ *
+ * - `posix-single` and `ansi-c` share the `'` delimiter. They follow different
+ *   escaping rules, so the parser must tell them apart.
+ * - `locale` and `double` share the `"` delimiter. A `$` prefix marks
+ *   `locale`. The `$"..."` form is therefore a distinct token, and
+ *   restoration stays accurate.
+ * - `heredoc` covers `<<WORD`, `<<'WORD'`, `<<"WORD"`, and `<<\WORD` openers.
+ *   Their body extends through the terminator line.
+ *
+ * Expansion kinds describe delimiters the scanner balances while it extracts
+ * command substitutions. `stray-closer` is the opposite failure: a `}` with
+ * no matching opener.
+ *
+ * - `command-substitution`: a `$(` that never closes.
+ * - `process-substitution`: a `<(…` or `>(…` that never closes.
+ * - `parameter-expansion`: a `${` that never closes.
+ * - `backtick`: a backtick region that never closes.
+ * - `arithmetic`: an arithmetic expression (`$((` or `$[`) that never
+ *   closes.
+ * - `stray-closer`: a `}` at nesting depth 0 with no matching `{`. The scan
+ *   reports it outside any quoted region, comment, or heredoc body. A
+ *   depth-0 `)` is host text instead. bash closes `case` patterns with `)`.
+ *
+ * Rejection kinds describe input the scan refuses outright. The scan never
+ * tokenizes such input. Neither kind can grant an approval: the tool call
+ * fails with an error instead of reaching the approval prompt:
+ *
+ * - `nul-byte`: a raw NUL byte anywhere in the command. NUL is the scan's
+ *   placeholder sentinel. An input that contains one could corrupt the
+ *   masked-text round trip.
+ * - `nesting-too-deep`: the scan re-scans substitution payloads beyond
+ *   `MAX_PAYLOAD_SCAN_DEPTH` levels. Such input is generated, not a human
+ *   command.
  */
-export type QuoteType = "posix-single" | "ansi-c" | "double" | "locale" | "heredoc"
+export type QuoteType =
+	| "posix-single"
+	| "ansi-c"
+	| "double"
+	| "locale"
+	| "heredoc"
+	| "command-substitution"
+	| "process-substitution"
+	| "parameter-expansion"
+	| "backtick"
+	| "arithmetic"
+	| "stray-closer"
+	| "nul-byte"
+	| "nesting-too-deep"
 
 /**
  * The result of parsing a command string.
  *
- * `commands` is the list of individual sub-commands produced by splitting on
- * unquoted newlines and chain operators. When `parseError` is non-null the
- * command string is syntactically malformed (e.g. an unterminated quote) and
- * `commands` contains the raw input as a single opaque token so callers can
+ * `commands` is the list of individual sub-commands. The splitter cuts on
+ * unquoted newlines and chain operators. When `parseError` is non-null, the
+ * command string is malformed. Causes: an unterminated quote or heredoc, an
+ * expansion delimiter or arithmetic expression that never closes, a stray
+ * closer, a raw NUL byte, or substitution nesting beyond the re-scan depth
+ * cap. `commands` then holds the raw input as one opaque token. Callers can
  * surface the error without splitting unsafe fragments.
  *
  * Callers that only need the sub-command list can destructure `{ commands }`.
- * Callers that need to distinguish a parse error from a normal single-command
- * result should also inspect `parseError`.
+ * A caller that must tell a parse error from a normal single-command result
+ * also inspects `parseError`.
  */
 export interface ParseResult {
 	commands: string[]
@@ -33,15 +76,16 @@ export interface ParseResult {
 }
 
 /**
- * Describes the opening of a quoted region that is never closed.
+ * The scan could not account for the delimiter this object describes. The
+ * delimiter is a quote, heredoc, or expansion region that never closes, or a
+ * `}` at depth 0 with no matching `{`.
  *
- * - `quoteType`: the style of the unterminated quote. `"heredoc"` means a
- *   `<<WORD` opener whose terminator line was never found.
- * - `openIndex`: the index in the original command string of the character that
- *   opened the region. For ANSI-C and locale quoting this points at the leading
- *   `$`. For heredocs this points at the first `<`. This position lets a future
- *   caller emit a located error (e.g. "unterminated heredoc near ...") instead
- *   of a generic message.
+ * - `quoteType`: the kind of the offending construct.
+ * - `openIndex`: the index, in the scanned command string, of the character
+ *   that opened the region. For ANSI-C and locale quoting it points at the
+ *   leading `$`. For heredocs it points at the first `<`. For a stray closer
+ *   it points at the closer itself. The position lets a caller report a
+ *   located error instead of a generic message.
  */
 export interface UnterminatedQuote {
 	quoteType: QuoteType
@@ -51,9 +95,10 @@ export interface UnterminatedQuote {
 }
 
 /**
- * Build the human-readable error message for an unterminated quote.
- * Includes a short excerpt of the command around the opening delimiter
- * so the agent has enough context to locate and fix the problem.
+ * Build the human-readable error message for a structural parse failure.
+ * The message includes a short excerpt of the command around the offending
+ * character. The excerpt gives the agent enough context to locate and fix the
+ * problem.
  */
 function unterminatedQuoteMessage(quoteType: QuoteType, openIndex: number, command: string): string {
 	const labels: Record<QuoteType, string> = {
@@ -62,698 +107,2018 @@ function unterminatedQuoteMessage(quoteType: QuoteType, openIndex: number, comma
 		double: 'double quote (")',
 		locale: 'locale quote ($")',
 		heredoc: "heredoc (<<)",
+		"command-substitution": "command substitution ($(...))",
+		"process-substitution": "process substitution (<(...) or >(...))",
+		"parameter-expansion": "parameter expansion (${...})",
+		backtick: "backtick (`)",
+		arithmetic: "arithmetic expression ($(( or $[)",
+		"stray-closer": `closing delimiter '${command[openIndex] ?? ""}' with no matching opener`,
+		"nul-byte": "NUL byte (control characters cannot appear in a shell command)",
+		"nesting-too-deep": `substitution nesting deeper than ${MAX_PAYLOAD_SCAN_DEPTH} levels`,
 	}
+	const problem =
+		quoteType === "stray-closer" || quoteType === "nul-byte" || quoteType === "nesting-too-deep"
+			? labels[quoteType]
+			: `unterminated ${labels[quoteType]}`
 	const snippetStart = Math.max(0, openIndex - 10)
 	const snippetEnd = Math.min(command.length, openIndex + 20)
 	const prefix = snippetStart > 0 ? "..." : ""
 	const suffix = snippetEnd < command.length ? "..." : ""
 	const excerpt = prefix + command.slice(snippetStart, snippetEnd).replace(/\r?\n/g, "\\n") + suffix
-	return `Malformed command: unterminated ${labels[quoteType]} at position ${openIndex} -- near: \`${excerpt}\`. `
+	return `Malformed command: ${problem} at position ${openIndex} -- near: \`${excerpt}\`. `
 }
 
 /**
- * Scan a command string left-to-right with a small state machine and report the
- * first quoted region that is never closed, or `null` when every quoted region
- * is properly terminated.
+ * Report the first structural problem in `command`. Return `null` when every
+ * quoted region, heredoc, and expansion delimiter closes properly and no
+ * closer appears without its opener.
  *
- * A regex cannot reliably answer "is this command well-quoted?" because quoting
- * is context-sensitive: a backslash escapes the next character outside single
- * quotes, `#` may begin a comment that should be ignored, and an apostrophe
- * inside double quotes (or vice versa) is literal text rather than a delimiter.
- * This walk mirrors how a POSIX shell tokenizes quoting so that legitimate
- * multi-line quoted arguments are accepted while genuinely unterminated quotes
- * (a shell syntax error) are detected.
+ * A regex cannot answer "can a shell parse this?" because shell syntax is
+ * context-sensitive. Outside single quotes a backslash escapes the next
+ * character. A `#` may begin a comment that the parser must ignore. A quote
+ * inside double quotes is literal text. Nesting must be balanced. The shared
+ * state-machine walk in `scanShellSyntax` mirrors POSIX tokenization. It
+ * accepts legitimate multi-line quoted arguments and detects genuinely
+ * malformed input.
  *
- * Rules implemented:
- * - Outside any quote, a backslash escapes the following character, so `\'` and
- *   `\"` are literal and do not open a region.
- * - Outside any quote, `#` begins a comment when it is at the start of the input
- *   or preceded by whitespace; the remainder of that line is ignored. A `#` that
- *   is attached to a word (e.g. `foo#bar`) is an ordinary character.
- * - Single quotes are opaque: no escapes apply, and the region ends only at the
- *   next `'`.
- * - Double quotes honor backslash escapes, so `\"` does not close the region.
- * - ANSI-C quoting ($'...') behaves like a single-quoted region for delimiter
- *   purposes but honors backslash escapes, so `\'` does not close it.
- * - Locale quoting ($"...") behaves like double quotes but is opened by `$"` so
- *   the leading `$` is part of the token (same pattern as ANSI-C).
- * - Heredoc (`<<WORD`, `<<'WORD'`, `<<"WORD"`, `<<\WORD`, `<<-WORD`) is a
- *   multi-line quoted region. The body extends from the character after the
- *   opener line's newline through the line that is exactly the terminator word
- *   (after stripping leading tabs for `<<-`). If no terminator line is found the
- *   heredoc is unterminated.
+ * A shell never looks at unbalanced delimiter characters inside ordinary
+ * quoted regions, so this check does not look at them either. They stay
+ * parseable.
  *
  * @internal
  */
 export function findUnterminatedQuote(command: string): UnterminatedQuote | null {
-	return scanTopLevelQuotes(command).unterminatedQuote
+	return scanShellSyntax(command).error
 }
 
+/** The kinds of region the scanner tracks on its open-delimiter stack. */
+type FrameKind =
+	| "posix-single"
+	| "ansi-c"
+	| "double"
+	| "locale"
+	| "command-substitution"
+	| "process-substitution"
+	| "parameter-expansion"
+	| "backtick"
+
+const QUOTE_FRAME_KINDS: FrameKind[] = ["posix-single", "ansi-c", "double", "locale"]
+
 /**
- * Describes a contiguous quoted region found at the top level of a command
- * string (outside any other quoted region and outside `#` comments).
+ * The characters a backslash escapes inside double quotes. Before any other
+ * character the backslash is itself literal and stays part of the word.
  */
-interface QuoteSpan {
-	/** Index of the first character of the opening delimiter (e.g. `$` for `$'...'`). */
-	start: number
-	/** Index one past the last character of the closing delimiter. */
-	end: number
-	/** The style of quoting. */
-	quoteType: QuoteType
+const DOUBLE_QUOTE_ESCAPABLE = '$`"\\\n'
+
+/** An open region the scanner is inside. One entry per unclosed delimiter. */
+interface RegionFrame {
+	kind: FrameKind
+	/** Index of the first character of the opening delimiter. */
+	openIndex: number
+	/** The single character that closes this region. */
+	closer: string
+	/** Index just after the opening delimiter. The region's content starts there. */
+	contentStart: number
+	/** Whether a backslash inside the region escapes the next character. */
+	escaped: boolean
+	/**
+	 * For command/process-substitution frames: the number of bare `(` grouping
+	 * parentheses that are open inside the region. A subshell group balances
+	 * independently of the frame's own closer. While this counter is positive,
+	 * a `)` matches the group and must not pop the frame.
+	 */
+	groupDepth: number
+	/**
+	 * For parameter-expansion frames: every command substitution the scan
+	 * closed inside the expansion, at any nesting depth. A parameter expansion
+	 * hides its text from the tokenizer. It must not stop substitution
+	 * extraction, because the shell expands `${x:-$(cmd)}` exactly like
+	 * `$(cmd)`.
+	 */
+	payloads: string[] | null
 }
 
 /**
- * Result returned by the single shared state-machine walk.
- *
- * `spans` contains every well-formed top-level quoted region found.
- * `unterminatedQuote` is non-null when the walk ended inside an open region.
+ * One open region in the heredoc opener-line remainder walk. Mirrors just the
+ * closer-balancing state of `RegionFrame`: enough to know when a top-level
+ * region closes, which decides whether a following `#` continues the word.
+ * `backtick` marks the opaque backtick kind: a backtick region balances only
+ * against its own closer, never against a nested opener.
  */
-interface ScanResult {
-	spans: QuoteSpan[]
-	unterminatedQuote: UnterminatedQuote | null
+interface RemainderFrame {
+	/** The single character that closes this region. */
+	closer: string
+	/** Bare `(` grouping opened inside a `)`-closing region, not yet closed. */
+	groupDepth: number
+	/** Whether this is the opaque backtick kind. */
+	backtick: boolean
 }
 
 /**
- * Parse a heredoc delimiter word starting at position `start` in `command`.
- * The delimiter may be:
- * - Unquoted:        `EOF`     -- bare identifier characters
- * - Single-quoted:   `'EOF'`   -- literal body, strip outer quotes
- * - Double-quoted:   `"EOF"`   -- expandable body, strip outer quotes
- * - Backslash-escaped: `\EOF`  -- literal body, strip leading backslash
- *
- * Returns the bare delimiter word (for terminator line matching) and the index
- * of the first character after the delimiter token.
+ * One scan fills this object. It holds the masked host text, the structural
+ * error if one exists, and the masked-away constructs. The tokenizer restores
+ * those constructs or recurses into them.
  */
-function parseHeredocDelimiter(command: string, start: number): { delimiter: string; endIndex: number } {
-	let i = start
-	let delimiter = ""
+interface ScanOutcome {
+	/**
+	 * The scan replaces every quoted region, heredoc, parameter expansion,
+	 * arithmetic expression, variable, and redirection with an opaque
+	 * placeholder word. It replaces every command substitution with a boundary
+	 * placeholder. The result contains no active shell syntax, so
+	 * `shell-quote` can tokenize it safely.
+	 */
+	host: string
+	error: UnterminatedQuote | null
+	/** Inner text of each `$()`/backtick/`<()`/`>()` region, in order. */
+	substitutions: string[]
+	/** Raw text of each quoted region, restored verbatim. */
+	quotes: string[]
+	/** Raw text of each `${...}` region, restored verbatim. */
+	params: string[]
+	/** For each parameter expansion: raw inner substitutions to extract. */
+	paramPayloads: string[][]
+	/** Raw text (redirect operator and delimiter word through terminator) of each heredoc. */
+	heredocs: string[]
+	/** For each heredoc with an unquoted delimiter: body substitutions. */
+	heredocPayloads: string[][]
+	variables: string[]
+	redirections: string[]
+	/** Masked arithmetic expressions: `$((...))` and `$[...]`. */
+	arithmetic: string[]
+	/** For each `$((...))`: substitutions the shell expands inside it. */
+	arithmeticPayloads: string[][]
+}
 
-	if (command[i] === "'") {
-		i++ // skip opening '
-		while (i < command.length && command[i] !== "'" && command[i] !== "\n") {
-			delimiter += command[i++]
-		}
-		if (command[i] === "'") i++ // consume closing '
-	} else if (command[i] === '"') {
-		i++ // skip opening "
-		while (i < command.length && command[i] !== '"' && command[i] !== "\n") {
-			delimiter += command[i++]
-		}
-		if (command[i] === '"') i++ // consume closing "
-	} else if (command[i] === "\\") {
-		i++ // skip backslash
-		while (i < command.length && command[i] !== "\n" && command[i] !== " " && command[i] !== "\t") {
-			delimiter += command[i++]
-		}
-	} else {
-		while (i < command.length && command[i] !== "\n" && command[i] !== " " && command[i] !== "\t") {
-			delimiter += command[i++]
-		}
-	}
+/**
+ * This sentinel separates placeholder names in masked host text. The scan
+ * rejects any input that contains a raw NUL (`nul-byte`) up front. A
+ * placeholder name can therefore never collide with command text. A printable
+ * `__NAME_0__` marker could collide, because an input can contain it
+ * literally.
+ */
+const NUL = "\x00"
+
+/**
+ * Cap on payload re-scan depth. The scan re-scans every substitution payload
+ * through the full path. With no cap, a few tens of KB of generated input
+ * consumes minutes of CPU through quadratic suffix re-scans. The call stack
+ * finally overflows. The cap fails closed instead. No hand-written command
+ * nests a substitution 64 deep.
+ */
+const MAX_PAYLOAD_SCAN_DEPTH = 64
 
-	return { delimiter, endIndex: i }
+const IDENT_START = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_"
+const IDENT_CHARS = `${IDENT_START}0123456789`
+/** `$` followed by one of these is a complete special variable. */
+const SPECIAL_VAR_CHARS = "?!#$@*-0123456789"
+
+function isIdentStart(char: string): boolean {
+	return IDENT_START.includes(char)
+}
+
+function isIdentChar(char: string): boolean {
+	return IDENT_CHARS.includes(char)
 }
 
 /**
- * Single shared state-machine walk used by both `findUnterminatedQuote` and
- * `maskTopLevelQuotes`. Walks `command` left-to-right, identifies every
- * top-level quoted region (outside any other quote and outside `#` comments),
- * and returns the list of spans together with an unterminated-quote descriptor
- * if the walk ends inside an open region.
+ * Scan `text` once, from left to right, with quote awareness. The scan tracks
+ * quote state, delimiter depth, and heredoc state at the same time. One pass
+ * emits masked host text, extracted substitution payloads, and a structural
+ * error.
  *
- * Rules (match POSIX shell tokenization):
- * - Outside any quote, `\X` escapes the next character so a quote after `\`
- *   is literal and does not open a region.
- * - `#` that follows whitespace (or is at position 0) starts a comment to end
- *   of line; quotes inside a comment are ignored.
- * - `<<<` is a herestring (single-line redirect), not a heredoc -- skip it.
- * - `<<` opens a heredoc whose body runs through the terminator line.
- * - `$'...'` is ANSI-C quoting (escape-aware single quote).
- * - `$"..."` is locale quoting (escape-aware double quote with `$` prefix).
- * - `'...'` is POSIX single quoting (fully opaque, no escapes).
- * - `"..."` is double quoting (escape-aware).
+ * Shell scope: the scan parses bash/POSIX-style shell syntax only. The
+ * reference shell on the Windows target is msys/Cygwin bash. The scan does
+ * not parse other shells as such. It reads their input with the same bash
+ * rules. PowerShell input shows two consequences. A backtick is PowerShell's
+ * escape character. The scan reads a backtick as a command-substitution
+ * opener. A backtick that never closes fails closed (`backtick`). `{ ... }`
+ * is a PowerShell script block. The scan applies bash brace rules. Balanced
+ * braces stay ordinary word content. An unmatched `}` at depth 0 fails closed
+ * (`stray-closer`).
  *
- * Supported quote styles reported in spans/unterminatedQuote:
- * - `ansi-c`       $'...'
- * - `locale`       $"..."
- * - `posix-single` '...'
- * - `double`       "..."
- * - `heredoc`      <<WORD...WORD
+ * Invariants the rest of the file depends on:
+ *
+ * - Quoted regions (`'…'`, `"…"`, `$'…'`, `$"…"`) are opaque to extraction.
+ *   The scan masks their contents whole and returns them verbatim. An
+ *   unbalanced delimiter inside one is never an error. A shell never parses
+ *   them there. A shell does expand `"$(cmd)"`. Extraction inside quoted
+ *   regions is deliberately out of scope, so such payloads stay masked.
+ * - The scan extracts `$(…)`, backticks, `<(`, and `>(`. When one closes, its
+ *   raw inner text becomes a payload segment. The host keeps only an opaque
+ *   boundary placeholder. The inner commands then match the allow/deny lists
+ *   on their own. The scan re-scans payloads, so nesting yields independent
+ *   segments.
+ * - `${…}` masks its text. The scan restores it verbatim into the host
+ *   segment. The scan still descends into it. Substitutions inside a parameter
+ *   expansion are still extracted and balance-checked. This includes
+ *   substitutions inside a heredoc body opened within the expansion. Those
+ *   payloads go to the expansion's payload list.
+ * - `$((…))` masks the expression as one host word. It never balances as an
+ *   extraction delimiter. The scan extracts substitutions inside a closed
+ *   `$((…))` and balance-checks them, because the shell expands them there. An
+ *   unclosed `$((` or `$[` fails closed (`arithmetic`). bash refuses the
+ *   input. Masking the remainder to end of input could hide an unclosed `$(`
+ *   inside it. The scan only masks the interior of a bare `$[…]`. It never
+ *   looks for substitutions there. Bare `(`…`)` grouping (subshell groups,
+ *   array assignments) also stays host text. An unclosed one is never an
+ *   error. A stray `)` is never an error either. bash closes `case` patterns
+ *   with `)`. The scan tracks a bare `{` so that brace expansion, `@{1}`
+ *   revspecs, and `find -exec {}` placeholders balance instead of erroring.
+ * - Fail-closed rule: an error results when the scan opens one of the four
+ *   extraction delimiters and cannot close it. An unclosed arithmetic opener
+ *   (`$((`/`$[`), a `}` at depth 0 with no matching `{`, and a raw NUL byte
+ *   anywhere in the input are errors too. So is payload re-scanning deeper
+ *   than `MAX_PAYLOAD_SCAN_DEPTH`. A closer that does not match the open
+ *   region's kind is literal content. That matches the shell. The still-open
+ *   region then fails at end of input.
+ * - Heredocs: the scan masks the redirect operator and delimiter word, the
+ *   body, and the terminator line as one opaque host word. The masked
+ *   construct stays a single segment
+ *   however many lines it spans. The text after the delimiter word on the
+ *   opener line is live host text: it stays out of the mask and splits at
+ *   operator characters like any other host text. Lines end only at a line
+ *   feed (LF). A carriage return (CR)
+ *   counts only as the CR of a CR-and-LF pair (CRLF) on the opener line. A
+ *   CR-only-separated opener does not validate a heredoc. bash reports such a
+ *   construct as unterminated. The scan matches body lines against the
+ *   delimiter with every CR removed. The msys/Cygwin read layer strips CR
+ *   before parsing. That layer is the reference shell on the Windows target.
+ *   The strip reaches every CR in the construct, the delimiter word and the
+ *   terminator line included. POSIX bash keeps every CR as ordinary content.
+ *   The two models can place the terminator on different lines. Either
+ *   direction of divergence is unsafe. An early close hands the remaining
+ *   body back to the scanner as live syntax. There it can open a new heredoc
+ *   that masks commands the other model executes. A late close masks them
+ *   outright. A CR anywhere in the region from the opener line through the
+ *   closing terminator line means the two layers do not read the same bytes.
+ *   The parser cannot verify that both models close at the same line. Such
+ *   heredocs fail closed for review. The parser does not guess which model
+ *   decides the boundary. It over-rejects even a uniformly-CRLF construct
+ *   whose models happen to agree. That is the accepted cost of never picking
+ *   a model. The scan parses only heredocs whose region has no CR. There both
+ *   models read byte-identical text. An unquoted-delimiter body is
+ *   expansion-active. A substitution opened inside it is extracted and must
+ *   balance before the terminator. A quoted or backslash-escaped delimiter
+ *   suppresses expansion entirely in the body. The shell does not expand
+ *   those. Such a body stays opaque and is never balance-checked. A body
+ *   carries no comments and is not tokenized outside an expansion region. A
+ *   `"` or `#` there is literal text. Inside an expansion region, quotes and
+ *   word-initial `#` comments follow the shell's rules there. A comment ends
+ *   at the newline, not at the region end. The scan walks the opener line's
+ *   remainder (the text after the delimiter word) for substitutions even when
+ *   the delimiter is quoted. Quoting suppresses expansion in the body only.
+ *   `cat <<'EOF' $(cmd)` still runs `cmd`.
  */
-function scanTopLevelQuotes(command: string): ScanResult {
-	const spans: QuoteSpan[] = []
-	let i = 0
+function scanShellSyntax(text: string): ScanOutcome {
+	const outcome: ScanOutcome = {
+		host: "",
+		error: null,
+		substitutions: [],
+		quotes: [],
+		params: [],
+		paramPayloads: [],
+		heredocs: [],
+		heredocPayloads: [],
+		variables: [],
+		redirections: [],
+		arithmetic: [],
+		arithmeticPayloads: [],
+	}
+	const stack: RegionFrame[] = []
+	// Counts the parameter-expansion frames open on `stack`. While this count
+	// is 0, `innermostParam` returns without walking the stack.
+	let paramFramesOpen = 0
+	// Counts bare `(` grouping (subshell groups, array assignments). Grouping
+	// stays host text. It is not one of the extraction/fail-closed delimiters.
+	// An unclosed `(` is never an error. A `)` is never an error either, with
+	// or without an opener. The counter only tracks the grouping depth. Both
+	// `)` cases reach the host.
+	let parenDepth = 0
+	// A bare `{` (brace expansion, `@{1}` revspec, `find -exec {}` placeholder)
+	// also stays host text. The scan tracks the depth so that a `}` matching
+	// an open bare `{` is not reported as a stray closer. The balance tracking
+	// is deliberately coarse. This code has no shell-context reading of `{`,
+	// only a pair.
+	let braceDepth = 0
+	// Index just past the most recent expansion or quote region that the scan
+	// closed at host level, or -1. This includes `$((…))`/`$[…]`. The shell
+	// ends the expansion at such a closer but not the surrounding word. A `#`
+	// directly there is word content, never a comment start.
+	let expansionCloseEnd = -1
+	// Index just past the most recent `\c` escape pair that the scan emitted
+	// at host level, or -1. To the shell, the escaped character is an ordinary
+	// word character. The word continues past the pair. A `#` directly at this
+	// index is word content, even when the escaped character is whitespace or
+	// a metacharacter in the raw text.
+	let escapedWordCharEnd = -1
 
-	while (i < command.length) {
-		const char = command[i]
+	const mark = (name: string): string => `${NUL}${name}${NUL}`
 
-		// Outside any quoted region: handle backslash, comments, and quote openers.
-		if (char === "\\") {
-			// Backslash escapes the next character; a quote after it is literal.
-			i += 2
-			continue
+	const errorAt = (kind: QuoteType, openIndex: number): UnterminatedQuote => ({
+		quoteType: kind,
+		openIndex,
+		message: unterminatedQuoteMessage(kind, openIndex, text),
+	})
+
+	// Reject a raw NUL before any masking. NUL is this scan's placeholder
+	// sentinel. An input containing one could degrade a masked placeholder
+	// into inert literal text. That would hide a substitution from the lists.
+	// Rejecting at the scan head also covers `findUnterminatedQuote`, which
+	// shares this scan.
+	const nulIndex = text.indexOf(NUL)
+	if (nulIndex !== -1) {
+		outcome.error = errorAt("nul-byte", nulIndex)
+		return outcome
+	}
+
+	const endOfLine = (from: number): number => {
+		let j = from
+		while (j < text.length && text[j] !== "\n" && text[j] !== "\r") {
+			j++
 		}
+		return j
+	}
 
-		if (char === "#" && (i === 0 || /\s/.test(command[i - 1]))) {
-			// Comment: skip to end of line. Quotes inside are not shell quoting.
-			while (i < command.length && command[i] !== "\n" && command[i] !== "\r") {
-				i++
+	/** Open the quoted region starting at `i`, or return null if none. */
+	const openQuote = (i: number): RegionFrame | null => {
+		if (text[i] === "$" && text[i + 1] === "'") {
+			return {
+				kind: "ansi-c",
+				openIndex: i,
+				closer: "'",
+				contentStart: i + 2,
+				escaped: true,
+				groupDepth: 0,
+				payloads: null,
+			}
+		}
+		if (text[i] === "$" && text[i + 1] === '"') {
+			return {
+				kind: "locale",
+				openIndex: i,
+				closer: '"',
+				contentStart: i + 2,
+				escaped: true,
+				groupDepth: 0,
+				payloads: null,
 			}
-			continue
 		}
+		if (text[i] === "'") {
+			return {
+				kind: "posix-single",
+				openIndex: i,
+				closer: "'",
+				contentStart: i + 1,
+				escaped: false,
+				groupDepth: 0,
+				payloads: null,
+			}
+		}
+		if (text[i] === '"') {
+			return {
+				kind: "double",
+				openIndex: i,
+				closer: '"',
+				contentStart: i + 1,
+				escaped: true,
+				groupDepth: 0,
+				payloads: null,
+			}
+		}
+		return null
+	}
 
-		// Herestring (<<<): single-line stdin redirect -- no body or terminator.
-		if (char === "<" && command[i + 1] === "<" && command[i + 2] === "<") {
-			i += 3
-			continue
+	/**
+	 * Return the innermost parameter-expansion frame on `frames`, if any.
+	 * `paramOpen` is the caller's count of open parameter-expansion frames.
+	 * When it is 0, this function returns without walking the stack. Deep
+	 * non-expansion nesting then pays no stack scan per frame close.
+	 */
+	const innermostParam = (frames: RegionFrame[], paramOpen: number): RegionFrame | undefined => {
+		if (paramOpen === 0) {
+			return undefined
 		}
+		for (let f = frames.length - 1; f >= 0; f--) {
+			if (frames[f].kind === "parameter-expansion") {
+				return frames[f]
+			}
+		}
+		return undefined
+	}
 
-		// Heredoc opener: <<[-]? followed by an optional-quoted delimiter word.
-		if (char === "<" && command[i + 1] === "<") {
-			const start = i
-			i += 2 // skip <<
-			const stripTabs = command[i] === "-"
-			if (stripTabs) i++
-			// Skip horizontal whitespace between << and the delimiter word.
-			while (i < command.length && (command[i] === " " || command[i] === "\t")) {
+	/**
+	 * Consume an entire heredoc at `i`: the opener line, the body, and the
+	 * terminator. The redirect operator and delimiter word through the
+	 * terminator mask to one host word; the opener-line remainder after the
+	 * delimiter word stays live host text. Return the index just past the
+	 * terminator text. Return an error for an unterminated heredoc or for an
+	 * unbalanced delimiter inside an expansion-active body.
+	 */
+	const skipHeredoc = (i: number, frames: RegionFrame[]): { end: number } | { error: UnterminatedQuote } => {
+		const start = i
+		i += 2 // consume <<
+		const stripTabs = text[i] === "-"
+		if (stripTabs) {
+			i++
+		}
+		while (i < text.length && (text[i] === " " || text[i] === "\t")) {
+			i++
+		}
+		const { delimiter, endIndex, quoted, wordPresent, malformed } = parseHeredocDelimiter(text, i)
+		if (malformed) {
+			// The delimiter word still has an open quote region at end of
+			// input. bash reads it as a multi-line word that can never match a
+			// body line. The opener line's tail keeps executing as ordinary
+			// syntax. The body and everything after it are unaccountable, so
+			// fail closed.
+			return { error: errorAt("heredoc", start) }
+		}
+		if (!wordPresent && endIndex < text.length && text[endIndex] !== "\n" && text[endIndex] !== "\r") {
+			// The blank-skipping loop consumed every blank, so an unclaimed
+			// character here is a metacharacter: bash reads it as an operator
+			// token where the delimiter word belongs, and rejects the whole
+			// command before executing anything. The no-word mask below is the
+			// policy for `<<` plus blanks only; this shape fails closed.
+			return { error: errorAt("heredoc", start) }
+		}
+		const payloads: string[] = []
+		// This is the only place a heredoc mask is emitted. Every non-error
+		// outcome of skipHeredoc returns through here, so every masked span
+		// carries the same check. A CR byte anywhere in the construct from the
+		// opener through the terminator leaves the two read layers reading
+		// different bytes. msys strips each CR before parsing, and POSIX keeps
+		// it as ordinary content. A close that one layer sees may not be the
+		// close the other sees. A close that only one layer sees would hand
+		// that model's remainder back to the scanner as live syntax. The parser
+		// cannot verify that both layers close the construct the same way. The
+		// heredoc fails closed instead of picking a model. The check spans the
+		// whole construct, opener-line remainder included, even though the
+		// remainder masks out below. A uniformly-CRLF construct whose layers
+		// happen to agree is over-rejected. That is the accepted cost.
+		/**
+		 * Append the opener-line remainder `[from, to)` to the host text. These
+		 * bytes are live syntax that the outer scan loop never revisits, so the
+		 * walk applies that loop's live-text policy here: a mid-word `#`
+		 * becomes an opaque placeholder (the tokenizer would otherwise start a
+		 * comment there and drop the rest of the line, hiding live commands), a
+		 * word-initial `#` passes through as the comment bash sees, a `#`
+		 * directly after the closer of an expansion or process substitution
+		 * continues the word and takes the placeholder, and a backslash escape
+		 * pair stays verbatim. Quote characters pass through too; the walk only
+		 * tracks the regions so a quoted `#` stays literal.
+		 */
+		const emitRemainder = (from: number, to: number): void => {
+			let i = from
+			// Index just past the most recent `\c` escape pair, or -1. The
+			// escaped character is word content to the shell, so a `#` directly
+			// after the pair continues the word.
+			let escapedEnd = -1
+			let quote: "'" | '"' | null = null
+			// Mirrors the scan loop's expansion state: the closers this walk
+			// must balance before a top-level region ends, and the index just
+			// past the most recent top-level region closer. The shell ends the
+			// region at its closer but not the surrounding word, so a `#`
+			// directly at that index is word content, never a comment start.
+			// An unclosed region cannot reach this walk: `walkBodyPayloads`
+			// has already balance-checked the remainder and fails the heredoc
+			// closed on a region left open.
+			const frames: RemainderFrame[] = []
+			let closerEnd = -1
+			while (i < to) {
+				const char = text[i]
+				if (char === "\\" && quote !== "'") {
+					// Inside single quotes a backslash is literal, so only an
+					// unquoted or double-quoted backslash pairs with the next
+					// character.
+					outcome.host += text.slice(i, i + 2)
+					escapedEnd = i + 2
+					i += 2
+					continue
+				}
+				if (char === "'" || char === '"') {
+					if (quote === null) {
+						quote = char
+					} else if (quote === char) {
+						quote = null
+					}
+					outcome.host += char
+					i++
+					continue
+				}
+				if (quote === null) {
+					const top = frames[frames.length - 1]
+					if (top?.backtick) {
+						// A backtick region is opaque except for its closer:
+						// backticks do not nest and the shell re-scans nothing
+						// inside that would rebalance it.
+						if (char === "`") {
+							frames.pop()
+							if (frames.length === 0) {
+								closerEnd = i + 1
+							}
+						}
+						outcome.host += char
+						i++
+						continue
+					}
+					if (top && char === top.closer) {
+						if (top.groupDepth > 0) {
+							// This closer matches an inner grouping paren, not
+							// the region's own opener.
+							top.groupDepth--
+						} else {
+							frames.pop()
+							if (frames.length === 0) {
+								closerEnd = i + 1
+							}
+						}
+						outcome.host += char
+						i++
+						continue
+					}
+					if (top?.closer === ")" && char === "(") {
+						// A bare `(` inside a `)`-closing region opens a group
+						// the shell balances before the region's closer, so the
+						// group's `)` cannot end the region. `(`/`)` inside a
+						// `}`- or `]`-closing region stay literal.
+						top.groupDepth++
+						outcome.host += char
+						i++
+						continue
+					}
+					if (char === "$" && (text[i + 1] === "(" || text[i + 1] === "{" || text[i + 1] === "[")) {
+						// A `$((` region starts with one inner group pending, so
+						// it closes past its second `)`, like the loop's
+						// arithmetic end.
+						// Stryker disable next-line StringLiteral: either literal's erasure only leaves `doubleArith` false, and the walk re-counts the second `(` as an ordinary group paren at the same depth, so no reachable remainder emits different host bytes or splits.
+						const doubleArith = text[i + 1] === "(" && text[i + 2] === "("
+						const closer = text[i + 1] === "(" ? ")" : text[i + 1] === "[" ? "]" : "}"
+						frames.push({ closer, groupDepth: doubleArith ? 1 : 0, backtick: false })
+						outcome.host += char
+						outcome.host += text[i + 1]
+						if (doubleArith) {
+							outcome.host += text[i + 2]
+						}
+						i += doubleArith ? 3 : 2
+						continue
+					}
+					if (char === "`") {
+						frames.push({ closer: "`", groupDepth: 0, backtick: true })
+						outcome.host += char
+						i++
+						continue
+					}
+					if ((char === "<" || char === ">") && text[i + 1] === "(") {
+						frames.push({ closer: ")", groupDepth: 0, backtick: false })
+						outcome.host += `${char}(`
+						i += 2
+						continue
+					}
+				}
+				if (char === "#" && quote === null) {
+					if (i === closerEnd) {
+						// A `#` directly after a region closer continues the
+						// word: the shell ends the region at its closer but not
+						// the word, and starts a comment only at a word start.
+						// The placeholder keeps the rest of the line
+						// tokenizable, as the mid-word case below does.
+						const id = outcome.variables.push("#") - 1
+						outcome.host += mark(`V${id}`)
+						i++
+						continue
+					}
+					const wordStart = i === from || /\s/.test(text[i - 1]) || /[;&()|<>]/.test(text[i - 1])
+					if (wordStart && i !== escapedEnd) {
+						// A comment starts only at a word start. The tokenizer
+						// and bash agree here: both drop the text from the `#`
+						// to end of line.
+						outcome.host += text.slice(i, to)
+						return
+					}
+					// Mid-word `#`: an ordinary character to the shell, a
+					// comment start to the tokenizer. Mask it to an opaque
+					// placeholder so the rest of the line survives tokenization.
+					const id = outcome.variables.push("#") - 1
+					outcome.host += mark(`V${id}`)
+					i++
+					continue
+				}
+				outcome.host += char
 				i++
 			}
-			const { delimiter, endIndex } = parseHeredocDelimiter(command, i)
-			i = endIndex
-			// Advance past the remainder of the opener line.
-			while (i < command.length && command[i] !== "\n") i++
-			if (i < command.length) i++ // consume newline
-			if (delimiter.length > 0) {
-				let found = false
-				while (i < command.length) {
+		}
+		const emitMask = (end: number): { end: number } | { error: UnterminatedQuote } => {
+			const fullSpan = text.slice(start, end)
+			if (fullSpan.includes("\r")) {
+				return { error: errorAt("heredoc", start) }
+			}
+			// The shell expands the text after the delimiter word on the opener
+			// line. That remainder is live syntax, not opaque body: the mask
+			// covers the redirect operator and delimiter word through the
+			// terminator, while the opener-line remainder stays out of the
+			// region and reaches the host text through the same masking the scan
+			// applies to live text. A no-word opener masks through end of input
+			// instead. The metacharacter guard in `skipHeredoc` fails a no-word
+			// opener whose break was metacharacter-caused closed before any mask
+			// is emitted, so the openers reaching this mask are `<<` plus blanks:
+			// their line remainder is nothing but those blanks.
+			const region = wordPresent ? text.slice(start, endIndex) + text.slice(remainderEnd, end) : fullSpan
+			const id = outcome.heredocs.push(region) - 1
+			outcome.heredocPayloads[id] = payloads
+			// Inside an expansion region, the host is masked wholesale anyway.
+			// Only top-level heredocs need a placeholder in the host text. The
+			// emission appends the opener-line remainder as live host text; the
+			// split at chain operators happens later, when `parseLine`
+			// tokenizes. Inside a frame, the payload re-scan runs this emission
+			// at top level.
+			if (frames.length === 0) {
+				outcome.host += mark(`H${id}`)
+				if (wordPresent) {
+					emitRemainder(endIndex, remainderEnd)
+				}
+			}
+			return { end }
+		}
+		// The shell expands the opener line's remainder after the delimiter,
+		// even when the delimiter is quoted. Quoting suppresses expansion in
+		// the body only. Walk the remainder unconditionally. An error there
+		// fails the whole heredoc closed, like a body error does.
+		const remainderEnd = endOfLine(endIndex)
+		// bash joins a backslash-newline pair before tokenizing, even inside
+		// double quotes. An odd unquoted backslash run at the end of the
+		// remainder therefore joins the rest of the opener line's syntax onto
+		// the first body line, while the remainder cut here stops blindly at
+		// that newline. The remainder cannot account for the joined bytes, so
+		// the heredoc fails closed. Inside single quotes a backslash is
+		// literal and no joining happens, so the guard stays silent there.
+		if (wordPresent) {
+			let backslashRun = 0
+			while (remainderEnd - 1 - backslashRun >= endIndex && text[remainderEnd - 1 - backslashRun] === "\\") {
+				backslashRun++
+			}
+			if (backslashRun % 2 === 1) {
+				// Decide whether the backslash run opens the join: walk the
+				// remainder's quote state up to the run. Only a single-quote
+				// region keeps the backslash literal.
+				let quote: "'" | '"' | null = null
+				let j = endIndex
+				while (j < remainderEnd - backslashRun) {
+					const char = text[j]
+					if (quote === "'") {
+						if (char === "'") {
+							quote = null
+						}
+						j++
+						continue
+					}
+					if (quote === '"') {
+						if (char === "\\") {
+							j += 2
+							continue
+						}
+						if (char === '"') {
+							quote = null
+						}
+						j++
+						continue
+					}
+					if (char === "\\") {
+						j += 2
+						continue
+					}
+					if (char === "'" || char === '"') {
+						quote = char
+					}
+					j++
+				}
+				if (quote !== "'") {
+					return { error: errorAt("heredoc", start) }
+				}
+			}
+		}
+		const remainderError = walkBodyPayloads(endIndex, remainderEnd, payloads, 0)
+		if (remainderError) {
+			return { error: remainderError }
+		}
+		// The opener line must end at LF so that the body starts on the next
+		// line. A CR is valid only as the CR of a CRLF pair. A lone CR is not a
+		// bash line terminator. Accepting one as the opener's end would
+		// validate CR-separated input that the shell refuses as an unterminated
+		// heredoc.
+		i = remainderEnd
+		if (text[i] === "\r") {
+			i++
+		}
+		if (text[i] !== "\n") {
+			return { error: errorAt("heredoc", start) }
+		}
+		i++
+		let bodyEnd = text.length
+		if (wordPresent) {
+			let found = false
+			const bodyStart = i
+			// Raw scan index at the terminator match. The mask-emission guard
+			// tests the region [start, rawIndex). Use this index, not the scan
+			// index: at the match, the back-step adjustments shift the scan
+			// index off the terminator line's line ending.
+			let rawIndex = bodyStart
+			// The terminator search emulates the shell's read layer. A line
+			// runs to LF, or to end of input. POSIX bash keeps every CR as
+			// ordinary content. The msys/Cygwin read layer strips every CR
+			// before parsing. That layer is the reference shell on the Windows
+			// target. `EO<CR>F` therefore arrives as the terminator `EOF` and
+			// closes the heredoc early there. The strip also reaches the
+			// delimiter word. After a CRLF opener line, POSIX reads the
+			// delimiter `EOF<CR>` where msys reads `EOF`. A CR from the opener
+			// line through the closing terminator line leaves the two layers
+			// reading different bytes. The close then cannot be verified in a
+			// model-independent way. The mask-emission guard above tests every
+			// masked span against this region, so such heredocs fail closed for
+			// review. This over-rejects even a uniformly-CRLF construct whose
+			// models happen to agree. That is the accepted cost. A CR-free
+			// region is byte-identical under both models, so it parses. bash
+			// joins a backslash-newline pair before it matches the delimiter.
+			// An unquoted logical line whose stripped content ends in an odd
+			// number of backslashes therefore flows into the next physical
+			// line. A quoted delimiter makes the backslash literal, so no
+			// joining happens. The CR strip happens in the read layer and
+			// quoting does not affect it. `<<-` strips leading tabs from the
+			// fully joined line afterwards. It never strips from a physical
+			// line on its own.
+			search: while (i < text.length) {
+				const groupStart = i
+				let candidate = ""
+				for (;;) {
 					const lineStart = i
-					while (i < command.length && command[i] !== "\n" && command[i] !== "\r") {
+					while (i < text.length && text[i] !== "\n") {
 						i++
 					}
-					// Strip leading tabs only for <<- heredocs.
-					const rawLine = command.slice(lineStart, i)
-					const line = stripTabs ? rawLine.replace(/^\t*/, "") : rawLine
-					// Do NOT advance past the terminator's newline -- leave it as a
-					// separator for any command that follows the heredoc.
-					if (line === delimiter) {
-						found = true
-						break
+					const logicalLine = text.slice(lineStart, i).replace(/\r/g, "")
+					const trailingBackslashes = logicalLine.match(/\\*$/)?.[0].length ?? 0
+					if (!quoted && text[i] === "\n" && trailingBackslashes % 2 === 1) {
+						candidate += logicalLine.slice(0, -1) // drop the continuation backslash
+						i++ // consume the newline of the continued line
+						continue
 					}
-					if (i < command.length) i++ // consume newline of a body line
-				}
-				if (!found) {
-					return {
-						spans,
-						unterminatedQuote: {
-							quoteType: "heredoc",
-							openIndex: start,
-							message: unterminatedQuoteMessage("heredoc", start, command),
-						},
+					candidate += logicalLine
+					// `<<-` strips leading tabs from the fully joined logical
+					// line. The strip runs after continuation joining, and only
+					// once. A tab that opens a continuation line stays inside
+					// the candidate. An early-terminator match therefore cannot
+					// hide live commands.
+					const candidateText = stripTabs ? candidate.replace(/^\t+/, "") : candidate
+					if (candidateText === delimiter) {
+						rawIndex = i
+						found = true
+						bodyEnd = groupStart
+						// The match is on the CR-stripped logical line. The raw
+						// line-ending byte that the scan would have stopped at
+						// sits back before the strip point. It is the CR of a
+						// CRLF-terminated terminator line. It is also a lone CR
+						// that is the whole raw terminator text: that line
+						// strips to empty and matches an empty delimiter right
+						// after a line break.
+						if (i > 0 && text[i] === "\n" && text[i - 1] === "\r") {
+							i--
+						}
+						if (i > 0 && text[i] === "\r" && i - 1 >= bodyStart && text[i - 1] === "\n") {
+							i--
+						}
+						break search
 					}
+					break
+				}
+				if (i < text.length) {
+					i++ // consume the newline of a body line
 				}
 			}
-			spans.push({ start, end: i, quoteType: "heredoc" })
-			continue
+			if (!found) {
+				// The body never ends. Nothing after the opener can be trusted.
+				return { error: errorAt("heredoc", start) }
+			}
+			if (!quoted) {
+				const bodyError = walkBodyPayloads(bodyStart, bodyEnd, payloads, 0)
+				if (bodyError) {
+					return { error: bodyError }
+				}
+			}
+			if (frames.length > 0) {
+				// Inside an expansion, no H placeholder is emitted. Without this
+				// routing, the collected payloads would never reach a re-scan.
+				// Hand them to the innermost parameter-expansion ancestor,
+				// exactly as a directly nested substitution close does. A
+				// heredoc opened inside $(…)/backtick/<( has no such ancestor.
+				// The enclosing substitution's payload is re-scanned whole and
+				// recovers them there.
+				innermostParam(frames, paramFramesOpen)?.payloads?.push(...payloads)
+			}
+			return emitMask(rawIndex)
 		}
+		// No delimiter token appeared, and the break was not metacharacter-caused
+		// -- the metacharacter guard above already fails those shapes closed: a
+		// bare `<<`, or `<<` followed only by blanks, before end of line. bash
+		// rejects such input with a syntax error and never executes it. The
+		// opener therefore masks through end of input as one opaque word, over a
+		// construct that can never run. The mask is sound only while both read
+		// layers see the same bytes. The region test at the mask-emission guard
+		// above fails the mask closed when a CR enters the span. This
+		// over-rejects the CR-touched shapes whose layers happen to agree. That
+		// is the accepted cost of keeping one region rule.
+		return emitMask(text.length)
+	}
 
-		// ANSI-C quoting: $'...', escape-aware.
-		if (char === "$" && command[i + 1] === "'") {
-			const start = i
-			i += 2 // skip $'
-			let closed = false
-			while (i < command.length) {
-				if (command[i] === "\\") {
-					i += 2 // skip escaped char
-				} else if (command[i] === "'") {
-					i++ // consume closing '
-					closed = true
-					break
-				} else {
+	/**
+	 * Walk the heredoc body region `[start, end)`. Collect the command
+	 * substitutions that the shell would expand there.
+	 *
+	 * Outside an expansion region, this walk tracks only the expansion
+	 * delimiters and backslash escapes. A heredoc body is not tokenized, so a
+	 * `"` or `#` in the body is literal text. Inside an expansion region the
+	 * shell does tokenize. A quote there opens a region exactly as the main
+	 * scan treats it. The region masks the frame's closer and the group tests.
+	 * A region still open at the end of the body fails closed, like any other
+	 * unclosed delimiter. A word-initial `#` begins a comment, and the shell
+	 * skips it to end of line. A closer with no opener inside the body is
+	 * literal data, and the shell prints it. A delimiter still open when the
+	 * terminator line is reached is a structural error. The shell would never
+	 * finish expanding the body, so whatever follows it is unaccountable.
+	 *
+	 * `depth` bounds the recursion through nested `$((…))` interiors. Beyond
+	 * `MAX_PAYLOAD_SCAN_DEPTH`, the region fails closed instead of recursing
+	 * into generated input.
+	 */
+	const walkBodyPayloads = (
+		start: number,
+		end: number,
+		collect: string[],
+		depth: number,
+	): UnterminatedQuote | null => {
+		if (depth > MAX_PAYLOAD_SCAN_DEPTH) {
+			return errorAt("nesting-too-deep", start)
+		}
+		const frames: RegionFrame[] = []
+		let localParamOpen = 0
+		let i = start
+		while (i < end) {
+			const char = text[i]
+			const top = frames[frames.length - 1]
+			if (top) {
+				if (top.escaped && char === "\\") {
+					i += 2
+					continue
+				}
+				// A `#` at the start of a word inside a `$(…)`/`<(` frame
+				// begins a comment. The shell skips the comment to end of line.
+				// Body regions span lines, so the comment ends at the newline,
+				// not at the frame's end. A `)` inside the comment never closes
+				// the frame, and the continuation lines stay inside the same
+				// substitution. Quote and backtick frames keep `#` literal.
+				// Their regions reach this test too. Parameter expansions also
+				// keep it literal: `${#var}` is the length operator. Only
+				// substitution frames take the comment. The word-boundary set
+				// is the top-level comment rule's whitespace plus the
+				// metacharacters that end a word. A missed comment lets its `)`
+				// slice the payload, so the boundary must be exact.
+				if (
+					char === "#" &&
+					(top.kind === "command-substitution" || top.kind === "process-substitution") &&
+					/[\s;&()|<>]/.test(text[i - 1])
+				) {
+					// Clamp at the region end. A comment that runs past it
+					// leaves the frame open, and the still-open frame fails
+					// closed.
+					i = Math.min(endOfLine(i), end)
+					continue
+				}
+				if (char === top.closer) {
+					if (top.groupDepth > 0) {
+						// This closer matches an inner grouping paren that
+						// opened inside the region. It does not match the
+						// region's own opener.
+						top.groupDepth--
+						i++
+						continue
+					}
+					const closed = frames.pop() as RegionFrame
+					if (QUOTE_FRAME_KINDS.includes(closed.kind)) {
+						// Quote regions are opaque. Nothing inside them is
+						// extracted. The enclosing frame resumes after the
+						// closing quote.
+						i++
+						continue
+					}
+					if (closed.kind === "parameter-expansion") {
+						localParamOpen--
+						if (frames.length === 0) {
+							collect.push(...(closed.payloads ?? []))
+						} else {
+							innermostParam(frames, localParamOpen)?.payloads?.push(...(closed.payloads ?? []))
+						}
+					} else {
+						// Slice the inner text only where a consumer exists. A
+						// nested close with no parameter-expansion ancestor is
+						// recovered when the enclosing payload is re-scanned.
+						// Slicing every close eagerly would cost O(n²) on
+						// adversarial nesting.
+						const paramAncestor = innermostParam(frames, localParamOpen)
+						if (frames.length === 0 || paramAncestor) {
+							const inner = text.slice(closed.contentStart, i).trim()
+							if (paramAncestor) {
+								paramAncestor.payloads?.push(inner)
+							} else {
+								collect.push(inner)
+							}
+						}
+					}
+					i++
+					continue
+				}
+				// A quote frame is opaque except for its own closer and its
+				// escapes. A backtick region is opaque except for its closer.
+				// Backticks do not nest. Only expansion frames descend for
+				// nested constructs.
+				if (QUOTE_FRAME_KINDS.includes(top.kind) || top.kind === "backtick") {
+					i++
+					continue
+				}
+				// A bare `(` inside a substitution region opens a subshell
+				// group. The shell balances that group independently of the
+				// region's closer. Only its depth matters here, so the group's
+				// `)` cannot slice the payload.
+				if ((top.kind === "command-substitution" || top.kind === "process-substitution") && char === "(") {
+					top.groupDepth++
 					i++
+					continue
+				}
+				// Inside an expansion frame, a quote is shell syntax, not body
+				// text. The region it opens masks everything up to its closer.
+				// A `)` or `(` inside quotes is therefore neither a closer nor
+				// a group-opener. An unclosed region fails at the end of the
+				// walk, like any other unclosed frame.
+				const nestedQuote = openQuote(i)
+				if (nestedQuote) {
+					frames.push(nestedQuote)
+					i = nestedQuote.contentStart
+					continue
 				}
 			}
-			if (!closed) {
-				return {
-					spans,
-					unterminatedQuote: {
-						quoteType: "ansi-c",
-						openIndex: start,
-						message: unterminatedQuoteMessage("ansi-c", start, command),
-					},
+			if (char === "\\") {
+				i += 2
+				continue
+			}
+			if (char === "`") {
+				frames.push({
+					kind: "backtick",
+					openIndex: i,
+					closer: "`",
+					contentStart: i + 1,
+					escaped: true,
+					groupDepth: 0,
+					payloads: null,
+				})
+				i++
+				continue
+			}
+			if (char === "$") {
+				if (text[i + 1] === "(") {
+					if (text[i + 2] === "(") {
+						const arith = skipArithmetic(i)
+						if (arith.commandSubstitution) {
+							// bash reads this opener as `$(` plus a group, not
+							// arithmetic. The loop re-reads the group's `(` as
+							// a group paren, like the adjacent `$(` push.
+							frames.push({
+								kind: "command-substitution",
+								openIndex: i,
+								closer: ")",
+								contentStart: i + 2,
+								escaped: true,
+								groupDepth: 0,
+								payloads: null,
+							})
+							i += 2
+							continue
+						}
+						// An unclosed opener fails closed. The shell refuses the
+						// input, and masking the rest of the body would hide it.
+						if (!arith.closed) {
+							return errorAt("arithmetic", i)
+						}
+						// $((…)) is expansion-active. The shell performs the
+						// substitutions inside it, so they must balance and be
+						// collected.
+						const arithError = walkBodyPayloads(i + 3, arith.end - 2, collect, depth + 1)
+						if (arithError) {
+							return arithError
+						}
+						i = arith.end
+						continue
+					}
+					frames.push({
+						kind: "command-substitution",
+						openIndex: i,
+						closer: ")",
+						contentStart: i + 2,
+						escaped: true,
+						groupDepth: 0,
+						payloads: null,
+					})
+					i += 2
+					continue
+				}
+				if (text[i + 1] === "{") {
+					frames.push({
+						kind: "parameter-expansion",
+						openIndex: i,
+						closer: "}",
+						contentStart: i + 2,
+						escaped: true,
+						groupDepth: 0,
+						payloads: [],
+					})
+					localParamOpen++
+					i += 2
+					continue
+				}
+				if (text[i + 1] === "[") {
+					const arith = skipArithmetic(i)
+					// An unclosed opener fails closed. The shell refuses the
+					// input, and masking the rest of the body would hide it.
+					if (!arith.closed) {
+						return errorAt("arithmetic", i)
+					}
+					// $[…] is expansion-active, exactly like $((…)). The shell
+					// performs the substitutions inside it, so they must balance
+					// and be collected.
+					const arithError = walkBodyPayloads(i + 2, arith.end - 1, collect, depth + 1)
+					if (arithError) {
+						return arithError
+					}
+					i = arith.end
+					continue
 				}
+				i++
+				continue
 			}
-			spans.push({ start, end: i, quoteType: "ansi-c" })
-			continue
+			if ((char === "<" || char === ">") && text[i + 1] === "(") {
+				frames.push({
+					kind: "process-substitution",
+					openIndex: i,
+					closer: ")",
+					contentStart: i + 2,
+					escaped: true,
+					groupDepth: 0,
+					payloads: null,
+				})
+				i += 2
+				continue
+			}
+			i++
 		}
+		if (frames.length > 0) {
+			// Report the outermost unclosed delimiter. It is the first construct
+			// the shell could never finish expanding.
+			const outermost = frames[0]
+			return errorAt(outermost.kind, outermost.openIndex)
+		}
+		return null
+	}
 
-		// Locale quoting: $"...", escape-aware like double quotes.
-		if (char === "$" && command[i + 1] === '"') {
-			const start = i
-			i += 2 // skip $"
-			let closed = false
-			while (i < command.length) {
-				if (command[i] === "\\") {
-					i += 2 // skip escaped char
-				} else if (command[i] === '"') {
-					i++ // consume closing "
-					closed = true
-					break
-				} else {
-					i++
+	/**
+	 * Consume a `$((…))` or `$[…]` arithmetic expression. `closed` reports
+	 * whether the scan found the closing delimiter. Callers fail closed when
+	 * it is missing, because bash refuses an unclosed opener. The scan walks
+	 * only a closed expression's interior for expansions. `commandSubstitution`
+	 * marks a `$((` that bash does not read as arithmetic at all: arithmetic
+	 * syntax requires the two closers to be adjacent (`))`), so when the
+	 * depth-1 `)` is not immediately followed by another `)`, bash reads `$(`
+	 * plus a subshell group instead. Such callers must open a
+	 * command-substitution frame rather than mask the region as arithmetic.
+	 */
+	const skipArithmetic = (i: number): { end: number; closed: boolean; commandSubstitution?: boolean } => {
+		if (text[i + 1] === "[") {
+			const close = text.indexOf("]", i + 2)
+			return close === -1 ? { end: text.length, closed: false } : { end: close + 1, closed: true }
+		}
+		// $(( … )) balances plain parens. An unbalanced scan runs to end of input.
+		let depth = 2 // the two opening parens
+		let j = i + 3
+		while (j < text.length && depth > 0) {
+			if (text[j] === "(") {
+				depth++
+			} else if (text[j] === ")") {
+				depth--
+				// Inside valid arithmetic the depth-1 `)` is by construction
+				// the first character of the `))` token. Anything else is a
+				// command substitution whose group closes at this `)`.
+				if (depth === 1 && text[j + 1] !== ")") {
+					return { end: i + 2, closed: false, commandSubstitution: true }
 				}
 			}
-			if (!closed) {
-				return {
-					spans,
-					unterminatedQuote: {
-						quoteType: "locale",
-						openIndex: start,
-						message: unterminatedQuoteMessage("locale", start, command),
-					},
-				}
+			j++
+		}
+		return { end: j, closed: depth === 0 }
+	}
+
+	/** End index just past a `$name` or `$<special>` token at `i`, or null. */
+	const scanVariable = (i: number): number | null => {
+		const next = text[i + 1]
+		if (next === undefined) {
+			return null
+		}
+		if (isIdentStart(next)) {
+			let j = i + 1
+			while (j < text.length && isIdentChar(text[j])) {
+				j++
 			}
-			spans.push({ start, end: i, quoteType: "locale" })
-			continue
+			return j
+		}
+		if (SPECIAL_VAR_CHARS.includes(next)) {
+			return i + 2
+		}
+		return null
+	}
+
+	/** End index past a `2>&1`-style redirection at `i`, or null. */
+	const scanRedirection = (i: number): number | null => {
+		let j = i
+		if (text[j] === ">" && text[j + 1] === "&") {
+			j += 2
+			while (j < text.length && "0123456789".includes(text[j])) {
+				j++
+			}
+			return j
 		}
+		while (j < text.length && "0123456789".includes(text[j])) {
+			j++
+		}
+		if (j > i && text[j] === ">" && text[j + 1] === "&") {
+			j += 2
+			while (j < text.length && "0123456789".includes(text[j])) {
+				j++
+			}
+			return j
+		}
+		return null
+	}
+
+	let i = 0
+	while (i < text.length) {
+		const char = text[i]
+		const top = stack[stack.length - 1]
 
-		// POSIX single quote: fully opaque, ends at the next literal '.
-		if (char === "'") {
-			const start = i
-			i++ // skip opening '
-			while (i < command.length && command[i] !== "'") {
+		if (top) {
+			if (top.escaped && char === "\\") {
+				i += 2
+				continue
+			}
+			if (char === top.closer) {
+				if (top.groupDepth > 0) {
+					// This closer matches an inner grouping paren that opened
+					// inside the region. It does not match the region's own
+					// opener. The subshell group balances before the
+					// substitution frame does.
+					top.groupDepth--
+					i++
+					continue
+				}
+				const closeEnd = i + 1
+				const closed = stack.pop() as RegionFrame
+				if (closed.kind === "parameter-expansion") {
+					paramFramesOpen--
+				}
+				if (QUOTE_FRAME_KINDS.includes(closed.kind)) {
+					// Quote regions restore verbatim. At the top level they mask
+					// to a single opaque word, so their contents can never
+					// tokenize as syntax.
+					if (stack.length === 0) {
+						const id = outcome.quotes.push(text.slice(closed.openIndex, closeEnd)) - 1
+						outcome.host += mark(`Q${id}`)
+					}
+					i = closeEnd
+					continue
+				}
+				if (stack.length === 0) {
+					if (closed.kind === "parameter-expansion") {
+						// The expansion's text stays verbatim in the host segment.
+						// Its inner substitutions are extracted independently.
+						const id = outcome.params.push(text.slice(closed.openIndex, closeEnd)) - 1
+						outcome.paramPayloads[id] = closed.payloads ?? []
+						outcome.host += mark(`P${id}`)
+					} else {
+						const id = outcome.substitutions.push(text.slice(closed.contentStart, i).trim()) - 1
+						outcome.host += mark(`S${id}`)
+					}
+					expansionCloseEnd = closeEnd
+				} else {
+					// The frame is nested inside an expansion region. A
+					// substitution inside a parameter expansion belongs to that
+					// expansion's payload list. Anything deeper is recovered
+					// when the enclosing payload is re-scanned. Slice its inner
+					// text only where a consumer exists. Otherwise deep nesting
+					// would cost O(n²).
+					const paramAncestor = innermostParam(stack, paramFramesOpen)
+					if (closed.kind === "parameter-expansion") {
+						paramAncestor?.payloads?.push(...(closed.payloads ?? []))
+					} else if (paramAncestor) {
+						paramAncestor.payloads?.push(text.slice(closed.contentStart, i).trim())
+					}
+				}
+				i = closeEnd
+				continue
+			}
+			// A quote frame is opaque except for its own closer and its
+			// escapes. A backtick region is opaque except for its closer.
+			// Backticks do not nest. Only expansion frames descend for nested
+			// constructs.
+			if (QUOTE_FRAME_KINDS.includes(top.kind) || top.kind === "backtick") {
+				i++
+				continue
+			}
+			// A bare `(` inside a substitution region opens a subshell group.
+			// The shell balances that group independently of the region's
+			// closer. Tracking its depth keeps the group's `)` from popping the
+			// substitution frame. `(`/`)` inside a parameter expansion stay
+			// literal word characters.
+			if ((top.kind === "command-substitution" || top.kind === "process-substitution") && char === "(") {
+				top.groupDepth++
+				i++
+				continue
+			}
+			// Inside an expansion region, balance nested constructs and never
+			// emit host text. When the region closes, it is replaced by one
+			// placeholder.
+			const nestedQuote = openQuote(i)
+			if (nestedQuote) {
+				stack.push(nestedQuote)
+				i = nestedQuote.contentStart
+				continue
+			}
+			if (char === "$") {
+				if (text[i + 1] === "(") {
+					if (text[i + 2] === "(") {
+						const arith = skipArithmetic(i)
+						if (arith.commandSubstitution) {
+							// bash reads this opener as `$(` plus a group, not
+							// arithmetic. The loop re-reads the group's `(` as
+							// a group paren, like the adjacent `$(` push.
+							stack.push({
+								kind: "command-substitution",
+								openIndex: i,
+								closer: ")",
+								contentStart: i + 2,
+								escaped: true,
+								groupDepth: 0,
+								payloads: null,
+							})
+							i += 2
+							continue
+						}
+						// Fail closed here instead of letting the outer region
+						// error at end of input. That would name the wrong
+						// opener and silently drop the arithmetic's interior
+						// payloads.
+						if (!arith.closed) {
+							outcome.error = errorAt("arithmetic", i)
+							return outcome
+						}
+						const arithPayloads: string[] = []
+						const arithError = walkBodyPayloads(i + 3, arith.end - 2, arithPayloads, 0)
+						if (arithError) {
+							outcome.error = arithError
+							return outcome
+						}
+						// The enclosing region is masked wholesale. Route the
+						// substitutions to the innermost expansion ancestor, like
+						// a nested close does.
+						innermostParam(stack, paramFramesOpen)?.payloads?.push(...arithPayloads)
+						i = arith.end
+						continue
+					}
+					stack.push({
+						kind: "command-substitution",
+						openIndex: i,
+						closer: ")",
+						contentStart: i + 2,
+						escaped: true,
+						groupDepth: 0,
+						payloads: null,
+					})
+					i += 2
+					continue
+				}
+				if (text[i + 1] === "{") {
+					stack.push({
+						kind: "parameter-expansion",
+						openIndex: i,
+						closer: "}",
+						contentStart: i + 2,
+						escaped: true,
+						groupDepth: 0,
+						payloads: [],
+					})
+					paramFramesOpen++
+					i += 2
+					continue
+				}
 				i++
+				continue
 			}
-			if (i >= command.length) {
-				// No closing quote found.
-				return {
-					spans,
-					unterminatedQuote: {
-						quoteType: "posix-single",
-						openIndex: start,
-						message: unterminatedQuoteMessage("posix-single", start, command),
-					},
+			if (char === "`") {
+				stack.push({
+					kind: "backtick",
+					openIndex: i,
+					closer: "`",
+					contentStart: i + 1,
+					escaped: true,
+					groupDepth: 0,
+					payloads: null,
+				})
+				i++
+				continue
+			}
+			if ((char === "<" || char === ">") && text[i + 1] === "(") {
+				stack.push({
+					kind: "process-substitution",
+					openIndex: i,
+					closer: ")",
+					contentStart: i + 2,
+					escaped: true,
+					groupDepth: 0,
+					payloads: null,
+				})
+				i += 2
+				continue
+			}
+			// Inside a parameter expansion, bash reads `<<` as an arithmetic
+			// shift, or as literal word text. It never reads it as a heredoc
+			// opener. There, the scan consumes `<<` as an ordinary character.
+			// Only command-substitution and process-substitution frames reach
+			// the heredoc scan. The shell tokenizes those as command contexts,
+			// and a heredoc opened there is real. Quote and backtick frames are
+			// opaque before this point.
+			if (char === "<" && text[i + 1] === "<" && text[i + 2] !== "<" && top.kind !== "parameter-expansion") {
+				const result = skipHeredoc(i, stack)
+				if ("error" in result) {
+					outcome.error = result.error
+					return outcome
 				}
+				i = result.end
+				continue
 			}
-			i++ // consume closing '
-			spans.push({ start, end: i, quoteType: "posix-single" })
+			i++
 			continue
 		}
 
-		// Double quote: escape-aware, ends at the next unescaped ".
-		if (char === '"') {
-			const start = i
-			i++ // skip opening "
-			let closed = false
-			while (i < command.length) {
-				if (command[i] === "\\") {
-					i += 2 // skip escaped char
-				} else if (command[i] === '"') {
-					i++ // consume closing "
-					closed = true
-					break
-				} else {
-					i++
+		// Nothing is open. Scan fully and emit host text.
+		if (char === "\\") {
+			// A backslash escapes the next character. A quote after it is
+			// literal.
+			outcome.host += text.slice(i, i + 2)
+			escapedWordCharEnd = i + 2
+			i += 2
+			continue
+		}
+		if (char === "#" && i === expansionCloseEnd) {
+			// A `#` directly after the closer of an expansion or quote region
+			// continues the surrounding word. The shell ends the expansion at
+			// its closer but not the word. It starts a comment only at a word
+			// start. The tokenizer starts a comment at any unquoted `#`. Send
+			// the character through tokenization as an opaque placeholder, as
+			// the mid-word case below does. It expands back verbatim. The rest
+			// of the line stays parseable instead of dropping as comment text.
+			const id = outcome.variables.push("#") - 1
+			outcome.host += mark(`V${id}`)
+			i++
+			continue
+		}
+		if (char === "#" && (i === 0 || (/\s/.test(text[i - 1]) && i !== escapedWordCharEnd))) {
+			// Comment: pass the rest of the line through untouched. Quotes and
+			// delimiters inside a comment are not shell syntax. shell-quote drops
+			// the comment text when it tokenizes. This branch also excludes a `#`
+			// at the end of a `\c` escape pair, even when the escaped character
+			// is whitespace. The escape makes it word content, so that `#`
+			// continues the word and the masking branch below handles it.
+			const end = endOfLine(i)
+			outcome.host += text.slice(i, end)
+			i = end
+			continue
+		}
+		if (char === "#" && (!/[;&()|<>]/.test(text[i - 1]) || i === escapedWordCharEnd)) {
+			// A `#` inside a word is an ordinary character to the shell. A
+			// comment starts only at a word start. The tokenizer starts a comment
+			// at any `#`. Send a mid-word `#` through tokenization as an opaque
+			// placeholder so it expands back verbatim. Otherwise it would drop
+			// the rest of the line, including a real separator after it. The
+			// character right after a `\c` escape pair is also word interior. An
+			// escaped character is a literal word character to the shell. A `#`
+			// at that position therefore uses the placeholder channel, even when
+			// the raw character before it is whitespace or a metacharacter. What
+			// reaches the tokenizer unmasked sits at a real word start: index 0,
+			// after whitespace, or after a bare metacharacter. There the shell
+			// starts a comment too.
+			const id = outcome.variables.push("#") - 1
+			outcome.host += mark(`V${id}`)
+			i++
+			continue
+		}
+		if (char === "<" && text[i + 1] === "<" && text[i + 2] === "<") {
+			// Herestring (<<<): a single-line stdin redirect with no body and no
+			// terminator. The word after it is an ordinary shell word.
+			outcome.host += "<<<"
+			i += 3
+			continue
+		}
+		if (char === "<" && text[i + 1] === "<") {
+			const result = skipHeredoc(i, stack)
+			if ("error" in result) {
+				outcome.error = result.error
+				return outcome
+			}
+			i = result.end
+			continue
+		}
+		if ((char === "<" || char === ">") && text[i + 1] === "(") {
+			stack.push({
+				kind: "process-substitution",
+				openIndex: i,
+				closer: ")",
+				contentStart: i + 2,
+				escaped: true,
+				groupDepth: 0,
+				payloads: null,
+			})
+			i += 2
+			continue
+		}
+		if (char === "(") {
+			// A bare grouping or array-assignment paren is host text. It is
+			// never extracted, and it is never an error, closed or not. The
+			// depth counter exists only so that a matching `)` is not read as a
+			// stray closer.
+			parenDepth++
+			outcome.host += char
+			i++
+			continue
+		}
+		if (char === ")" && parenDepth > 0) {
+			parenDepth--
+			outcome.host += char
+			i++
+			continue
+		}
+		if (char === "{") {
+			// A bare brace (brace expansion, `@{1}` revspec, `find -exec {}`
+			// placeholder) is host text. It is never extracted, and it is never
+			// an error. The depth counter exists only so that a matching `}` is
+			// not read as a stray closer.
+			braceDepth++
+			outcome.host += char
+			i++
+			continue
+		}
+		if (char === "}" && braceDepth > 0) {
+			braceDepth--
+			outcome.host += char
+			i++
+			continue
+		}
+		if (char === "}") {
+			// A `}` at depth 0 with no matching `{` stays fail-closed. The
+			// parser cannot tell a literal brace word from a decomposition whose
+			// opener it lost. An unaccountable closer never reaches approval: the
+			// tool call fails with an error. Rejecting a literal `}` argument is
+			// the accepted cost.
+			outcome.error = errorAt("stray-closer", i)
+			return outcome
+		}
+		// A `)` at depth 0 is host text. bash closes `case` patterns with `)`.
+		// With the frame stack empty, a closer cannot hide a substitution: any
+		// `$(…)` after it is still extracted and allowlist-checked.
+		if (char === "`") {
+			stack.push({
+				kind: "backtick",
+				openIndex: i,
+				closer: "`",
+				contentStart: i + 1,
+				escaped: true,
+				groupDepth: 0,
+				payloads: null,
+			})
+			i++
+			continue
+		}
+		if (char === "$") {
+			const dollarQuote = openQuote(i)
+			if (dollarQuote) {
+				stack.push(dollarQuote)
+				i = dollarQuote.contentStart
+				continue
+			}
+			if (text[i + 1] === "(") {
+				if (text[i + 2] === "(") {
+					const arith = skipArithmetic(i)
+					if (arith.commandSubstitution) {
+						// bash reads this opener as `$(` plus a group, not
+						// arithmetic. The loop re-reads the group's `(` as a
+						// group paren, like the adjacent `$(` push, so the
+						// group's command is extracted independently.
+						stack.push({
+							kind: "command-substitution",
+							openIndex: i,
+							closer: ")",
+							contentStart: i + 2,
+							escaped: true,
+							groupDepth: 0,
+							payloads: null,
+						})
+						i += 2
+						continue
+					}
+					// An unclosed opener fails closed. Masking the remainder to
+					// end of input would hide its text behind the host word.
+					if (!arith.closed) {
+						outcome.error = errorAt("arithmetic", i)
+						return outcome
+					}
+					// The shell performs command substitutions inside a $((…))
+					// exactly like anywhere else. Extract them as independent
+					// segments, and make them balance.
+					const arithPayloads: string[] = []
+					const arithError = walkBodyPayloads(i + 3, arith.end - 2, arithPayloads, 0)
+					if (arithError) {
+						outcome.error = arithError
+						return outcome
+					}
+					const id = outcome.arithmetic.push(text.slice(i, arith.end)) - 1
+					outcome.arithmeticPayloads[id] = arithPayloads
+					outcome.host += mark(`A${id}`)
+					expansionCloseEnd = arith.end
+					i = arith.end
+					continue
 				}
+				stack.push({
+					kind: "command-substitution",
+					openIndex: i,
+					closer: ")",
+					contentStart: i + 2,
+					escaped: true,
+					groupDepth: 0,
+					payloads: null,
+				})
+				i += 2
+				continue
 			}
-			if (!closed) {
-				return {
-					spans,
-					unterminatedQuote: {
-						quoteType: "double",
-						openIndex: start,
-						message: unterminatedQuoteMessage("double", start, command),
-					},
+			if (text[i + 1] === "{") {
+				stack.push({
+					kind: "parameter-expansion",
+					openIndex: i,
+					closer: "}",
+					contentStart: i + 2,
+					escaped: true,
+					groupDepth: 0,
+					payloads: [],
+				})
+				paramFramesOpen++
+				i += 2
+				continue
+			}
+			if (text[i + 1] === "[") {
+				const arith = skipArithmetic(i)
+				// An unclosed opener fails closed. Masking the remainder to
+				// end of input would hide its text behind the host word.
+				if (!arith.closed) {
+					outcome.error = errorAt("arithmetic", i)
+					return outcome
+				}
+				// The shell performs command substitutions inside a $[…] exactly
+				// like anywhere else. Extract them as independent segments, and
+				// make them balance.
+				const arithPayloads: string[] = []
+				const arithError = walkBodyPayloads(i + 2, arith.end - 1, arithPayloads, 0)
+				if (arithError) {
+					outcome.error = arithError
+					return outcome
 				}
+				const id = outcome.arithmetic.push(text.slice(i, arith.end)) - 1
+				outcome.arithmeticPayloads[id] = arithPayloads
+				outcome.host += mark(`A${id}`)
+				expansionCloseEnd = arith.end
+				i = arith.end
+				continue
+			}
+			const varEnd = scanVariable(i)
+			if (varEnd !== null) {
+				const id = outcome.variables.push(text.slice(i, varEnd)) - 1
+				outcome.host += mark(`V${id}`)
+				i = varEnd
+				continue
 			}
-			spans.push({ start, end: i, quoteType: "double" })
+			outcome.host += "$"
+			i++
 			continue
 		}
-
-		// Ordinary character -- advance.
+		const quote = openQuote(i)
+		if (quote) {
+			stack.push(quote)
+			i = quote.contentStart
+			continue
+		}
+		if (char === ">" || "0123456789".includes(char)) {
+			const redirEnd = scanRedirection(i)
+			if (redirEnd !== null) {
+				const id = outcome.redirections.push(text.slice(i, redirEnd)) - 1
+				outcome.host += mark(`R${id}`)
+				i = redirEnd
+				continue
+			}
+		}
+		outcome.host += char
 		i++
 	}
 
-	return { spans, unterminatedQuote: null }
+	if (stack.length > 0) {
+		// Delimiters are still open at end of input. Report the outermost one.
+		// It is the first construct the shell could never finish reading.
+		const outermost = stack[0]
+		outcome.error = errorAt(outermost.kind, outermost.openIndex)
+	}
+
+	return outcome
 }
 
 /**
- * Walk `command` and replace every top-level quoted region with a placeholder
- * token. Returns the masked string and the array of original quoted substrings
- * so callers can restore them later.
+ * Parse a heredoc delimiter word. The word starts at position `start` in
+ * `command`. The walk applies bash's quoting rules. A quote character opens a
+ * quote region anywhere in the word, mid-word as well as at the start. A
+ * quote region spans newlines until its closing quote. A backslash escapes the
+ * next character. Inside double quotes, only the characters in
+ * `DOUBLE_QUOTE_ESCAPABLE` are escapable. Outside quotes, anything is. A
+ * backslash-newline pair drops the newline as a line continuation everywhere.
+ * Quote removal produces the bare word. A terminator line must equal that word
+ * exactly.
  *
- * Delegates all state-machine logic to `scanTopLevelQuotes`, ensuring
- * consistent quoting rules with `findUnterminatedQuote`. An unterminated quote
- * is treated as a span that runs to the end of the string so the masked output
- * is always well-formed and the subsequent split never exposes a fragment of
- * a malformed command.
+ * Returns:
+ * - `delimiter`: the word after quote removal. It is the terminator text. It
+ *   is empty for `<<''`, which bash terminates at the first blank body line.
+ * - `endIndex`: index of the first character after the delimiter token.
+ * - `quoted`: whether any quoting construct appeared. A quoted or escaped
+ *   delimiter suppresses all expansion in the body.
+ * - `wordPresent`: whether any delimiter token appeared at all. A bare `<<`
+ *   before end of line has none.
+ * - `malformed`: whether the word reached end of input with a quote region
+ *   still open. bash then reads the delimiter as a multi-line word that can
+ *   never match a body line. The opener line's tail keeps executing as
+ *   ordinary syntax. No body can be accounted for.
  */
-function maskTopLevelQuotes(command: string): { masked: string; quotes: string[] } {
-	const { spans, unterminatedQuote } = scanTopLevelQuotes(command)
-
-	// If the command has an unterminated quote, treat the unclosed region as a
-	// span running to the end of the string. This is safe because parseCommand
-	// already guards against unterminated quotes and returns the raw command as
-	// a single token before calling maskTopLevelQuotes -- but the fallback
-	// ensures maskTopLevelQuotes is robust even when called directly.
-	const effectiveSpans: QuoteSpan[] =
-		unterminatedQuote !== null
-			? [
-					...spans,
-					{ start: unterminatedQuote.openIndex, end: command.length, quoteType: unterminatedQuote.quoteType },
-				]
-			: spans
-
-	const quotes: string[] = []
-	let result = ""
-	let pos = 0
-
-	for (const span of effectiveSpans) {
-		// Copy the unquoted text between the previous span end and this span start.
-		result += command.slice(pos, span.start)
-		// Replace the quoted span with a placeholder.
-		quotes.push(command.slice(span.start, span.end))
-		result += `__TOPLEVEL_QUOTE_${quotes.length - 1}__`
-		pos = span.end
+function parseHeredocDelimiter(
+	command: string,
+	start: number,
+): {
+	delimiter: string
+	endIndex: number
+	quoted: boolean
+	wordPresent: boolean
+	malformed: boolean
+} {
+	let i = start
+	let delimiter = ""
+	let quoted = false
+	// The quote region currently open inside the word, if any.
+	let quote: "'" | '"' | null = null
+
+	while (i < command.length) {
+		const char = command[i]
+		if (quote) {
+			if (char === quote) {
+				quote = null
+			} else if (quote === '"' && char === "\\" && i + 1 < command.length) {
+				// Inside double quotes, only `DOUBLE_QUOTE_ESCAPABLE` is
+				// escapable. The backslash drops before those characters.
+				// Before anything else it stays literal text of the word. A
+				// backslash-newline pair drops both characters (line
+				// continuation).
+				if (command[i + 1] !== "\n") {
+					const next = command[i + 1]
+					delimiter += DOUBLE_QUOTE_ESCAPABLE.includes(next) ? next : char + next
+				}
+				i += 2
+				continue
+			} else {
+				// Inside a quote, newlines and blanks are ordinary word
+				// content. bash closes the word only at the matching quote.
+				delimiter += char
+			}
+			i++
+			continue
+		}
+		if (char === "'" || char === '"') {
+			quote = char
+			quoted = true
+			i++
+			continue
+		}
+		if (char === "\\") {
+			quoted = true
+			if (i + 1 < command.length) {
+				if (command[i + 1] !== "\n") {
+					delimiter += command[i + 1]
+				}
+				i += 2
+				continue
+			}
+			i++
+			continue
+		}
+		// An unquoted blank, line ending, or shell metacharacter ends the word.
+		// bash tokenizes `cat <<E|grep x` as the delimiter word `E` followed by
+		// a live operator, exactly like `cat <<E | grep x`. The msys read layer
+		// strips CR, so there the CR is line-ending content, not part of the
+		// delimiter word. A CR-bounded delimiter word leaves its CR inside the
+		// construct's region. The region test at mask emission in skipHeredoc
+		// then fails such a heredoc closed, whether or not a terminator line
+		// matches. A `(` or `)` breaks the word only at word start. bash
+		// recognizes a metacharacter only at token start; glued after a
+		// nonempty word token it is a syntax error, never a separator. Breaking
+		// there would turn input bash rejects into an approvable heredoc whose
+		// live remainder swallows the parenthesized text without splitting it.
+		// A metacharacter at word start leaves the word empty, and the no-word
+		// path then accounts for the opener instead.
+		const breakSet = i === start ? " \t\n\r|&;()<>" : " \t\n\r|&;<>"
+		if (breakSet.includes(char)) {
+			break
+		}
+		delimiter += char
+		i++
 	}
 
-	// Copy any remaining text after the last span (or the whole string if no spans).
-	result += command.slice(pos)
+	return {
+		delimiter,
+		endIndex: i,
+		quoted,
+		wordPresent: i > start,
+		malformed: quote !== null,
+	}
+}
 
-	return { masked: result, quotes }
+/** Look up the raw text that a placeholder name stands for, or undefined. */
+function lookupPlaceholder(name: string, outcome: ScanOutcome, includeSubstitutions: boolean): string | undefined {
+	const index = Number(name.slice(1))
+	switch (name[0]) {
+		case "Q":
+			return outcome.quotes[index]
+		case "H":
+			return outcome.heredocs[index]
+		case "P":
+			return outcome.params[index]
+		case "V":
+			return outcome.variables[index]
+		case "R":
+			return outcome.redirections[index]
+		case "A":
+			return outcome.arithmetic[index]
+		case "S":
+			// The crude-split fallback path is the only path that restores
+			// substitutions inline. The normal path turns them into independent
+			// segments.
+			return includeSubstitutions ? outcome.substitutions[index] : undefined
+		default:
+			return undefined
+	}
 }
 
 /**
- * Split a command string into individual sub-commands by
- * chaining operators (&&, ||, ;, |, or &) and unquoted newlines.
- *
- * Uses shell-quote to properly handle:
- * - Quoted strings (preserves quotes, including multi-line quoted strings)
- * - Subshell commands ($(cmd), `cmd`, <(cmd), >(cmd))
- * - PowerShell redirections (2>&1)
- * - Chain operators (&&, ||, ;, |, &)
- * - Newlines as command separators (only when outside quoted strings)
- *
- * Key invariant: newlines that appear inside a quoted string (single or double)
- * are part of that string argument and must NOT be treated as command separators.
- * Only unquoted newlines split commands. For example:
- *
- *   sh -c 'python3 -c "
- *   import sys
- *   print(sys.version)
- *   "'
+ * Replace every sentinel-delimited placeholder in `text` with its raw text.
+ * Split on the sentinel rather than with a regex. By construction, a
+ * placeholder name is everything between two sentinels. The scan rejects a raw
+ * NUL in the input up front (see QuoteType "nul-byte"), so no input can carry
+ * a sentinel that collides with the ones used here.
+ */
+function expandPlaceholders(text: string, outcome: ScanOutcome, includeSubstitutions: boolean): string {
+	if (!text.includes(NUL)) {
+		return text
+	}
+	const parts = text.split(NUL)
+	let out = ""
+	for (let p = 0; p < parts.length; p++) {
+		if (p % 2 === 0) {
+			out += parts[p]
+			continue
+		}
+		const value = lookupPlaceholder(parts[p], outcome, includeSubstitutions)
+		if (value !== undefined) {
+			out += value
+		}
+	}
+	return out
+}
+
+/**
+ * Split a command string into individual sub-commands. The splitter cuts on
+ * chaining operators (&&, ||, ;, |, or &) and on unquoted newlines.
  *
- * ...is a single command, not multiple commands split at each newline.
+ * One quote-aware scan (`scanShellSyntax`) does all structure analysis in a
+ * single left-to-right pass. `shell-quote` then tokenizes the masked host
+ * text:
+ * - Quoted strings stay opaque. That includes multi-line quoted strings. That
+ *   is why only unquoted newlines split commands. The key invariant: a newline
+ *   inside a quoted string is argument text, never a separator.
+ * - The scan extracts every command substitution with balanced-paren
+ *   awareness, wherever it sits: nested, inside a `${…}` expansion, inside a
+ *   process substitution, or inside a heredoc with an unquoted delimiter. Each
+ *   becomes its own segment, so each inner command matches the allow/deny
+ *   lists on its own. Parameter-expansion and heredoc hosts keep their
+ *   verbatim text as one segment.
+ * - PowerShell-style redirections (2>&1), variables, and arithmetic stay
+ *   inside their host word.
  *
- * Returns a `ParseResult` containing the list of sub-commands and an optional
- * `parseError` that is non-null when the input contains a shell syntax error
- * (currently: an unterminated quote or heredoc). When `parseError` is set the
- * `commands` array contains the raw input as a single opaque token; callers
- * should surface the error rather than proceeding with auto-approval.
+ * The result is a `ParseResult`. It contains the list of sub-commands and an
+ * optional `parseError`. The error is non-null when the input cannot be
+ * accounted for: an unterminated quote or heredoc, an expansion delimiter or
+ * arithmetic expression opened but never closed, a stray closer, a raw NUL
+ * byte, or substitution nesting beyond the re-scan depth cap. When
+ * `parseError` is set, the `commands` array contains the raw input as a single
+ * opaque token. A command whose structure the parser cannot fully account for
+ * must never reach approval: the tool call fails with an error instead. It
+ * must not get a free pass built on a partial decomposition.
  */
 export function parseCommand(command: string): ParseResult {
+	// A NUL byte is not whitespace. A NUL-bearing command therefore still
+	// reaches the scan, where the nul-byte guard rejects it.
 	if (!command?.trim()) {
 		return { commands: [], parseError: null }
 	}
 
-	// Run the shared state-machine scan once. It gives us both the list of
-	// top-level quoted spans (used by maskTopLevelQuotes) and the parse-error
-	// descriptor (used here to detect malformed input) in a single pass.
-	const { unterminatedQuote } = scanTopLevelQuotes(command)
-
-	// Reject syntactically malformed input -- an unterminated quote is a shell
-	// syntax error. Return the raw input as a single opaque token so callers
-	// can surface the error to the agent rather than splitting unsafe fragments
-	// that might be auto-approved in isolation.
-	if (unterminatedQuote !== null) {
-		return { commands: [command], parseError: unterminatedQuote }
+	// Run the shared state-machine scan once. One pass yields the masked host
+	// text, the extracted substitution payloads, and the structural-error
+	// descriptor.
+	const outcome = scanShellSyntax(command)
+
+	// Reject syntactically malformed input. Return the raw input as a single
+	// opaque token. Callers then surface the error to the agent instead of
+	// splitting unsafe fragments that might be auto-approved in isolation.
+	if (outcome.error !== null) {
+		return { commands: [command], parseError: outcome.error }
 	}
 
-	// Pre-escape any literal __ sequences present in the raw command so they
-	// cannot collide with the internal placeholder tokens (e.g. __QUOTE_0__)
-	// used during masking and splitting. \x00 (the null byte, U+0000) is the
-	// sentinel: it encodes end-of-string at the C/OS level, so the OS terminates
-	// any command string at the first \x00 -- meaning a real shell command can
-	// never contain one. It therefore cannot appear in any command text the
-	// parser receives and will never match a placeholder regex. The post-unescape
-	// step at the return converts \x00 back to __ in every output command.
-	const escapedCommand = command.replace(/__/g, "\x00")
-
-	// Mask quoted strings before splitting on newlines so that newlines embedded
-	// inside a quoted argument are not mistaken for command separators. The
-	// masker delegates to scanTopLevelQuotes internally, ensuring identical
-	// quoting rules with the check above.
-	const { masked, quotes: topLevelQuotes } = maskTopLevelQuotes(escapedCommand)
-
-	// Split on unquoted newlines (all line-ending formats).
-	const lines = masked.split(/\r\n|\r|\n/)
 	const allCommands: string[] = []
 
-	for (const line of lines) {
+	for (const line of outcome.host.split(/\r\n|\r|\n/)) {
 		if (!line.trim()) {
 			continue
 		}
-
-		// Restore top-level quote placeholders before per-line parsing so that
-		// parseCommandLine sees the original quoted content and can apply its own
-		// masking for operator splitting.
-		const restoredLine = line.replace(/__TOPLEVEL_QUOTE_(\d+)__/g, (_, i) => topLevelQuotes[parseInt(i)])
-
-		// If the restored line contains embedded newlines it means a top-level
-		// quote (e.g. a heredoc) spanned multiple lines. The entire restored
-		// string is a single atomic command -- passing it through parseCommandLine
-		// would let shell-quote split on the embedded newlines and << operators.
-		if (restoredLine.includes("\n")) {
-			allCommands.push(restoredLine)
-			continue
+		allCommands.push(...parseLine(line, outcome, 0))
+		if (outcome.error !== null) {
+			return { commands: [command], parseError: outcome.error }
 		}
-
-		const lineCommands = parseCommandLine(restoredLine)
-		allCommands.push(...lineCommands)
 	}
 
-	// Unescape \x00 back to __ in every output command. This reverses the
-	// pre-escape applied above to prevent literal __ tokens in the input from
-	// colliding with internal placeholder names. split/join is used instead of
-	// a regex literal to avoid triggering the no-control-regex lint rule.
-	return { commands: allCommands.map((cmd) => cmd.split("\x00").join("__")), parseError: null }
+	return { commands: allCommands, parseError: null }
 }
 
 /**
- * Parse a single line of commands.
+ * Tokenize one masked host line into segments.
+ *
+ * A chain operator flushes the current segment. A substitution placeholder
+ * also flushes, and it takes the place of its payload's own segments. The
+ * payload is re-scanned through the same path, so nested substitutions become
+ * independent segments. Placeholders that do not force a split join the
+ * current word and are restored verbatim. Those are quotes, parameter
+ * expansions, heredocs, variables, redirections, and arithmetic. A parameter
+ * expansion, heredoc, or closed `$((…))` also queues its extracted inner
+ * substitutions. They flush right after the host segment that still contains
+ * their verbatim text.
+ *
+ * The scan records structural errors found while it recurses into payloads on
+ * `outcome` (fail-closed). The caller checks `outcome` after every line.
+ * `depth` counts payload re-entries, and `scanPayloadSegments` caps it.
  */
-function parseCommandLine(command: string): string[] {
-	if (!command?.trim()) return []
-
-	// Storage for replaced content
-	const redirections: string[] = []
-	const subshells: string[] = []
-	const quotes: string[] = []
-	const singleQuotes: string[] = []
-	const arithmeticExpressions: string[] = []
-	const variables: string[] = []
-	const parameterExpansions: string[] = []
-
-	// First handle PowerShell redirections by temporarily replacing them
-	let processedCommand = command.replace(/\d*>&\d*/g, (match) => {
-		redirections.push(match)
-		return `__REDIR_${redirections.length - 1}__`
-	})
-
-	// Handle arithmetic expressions: $((...)) pattern
-	// Match the entire arithmetic expression including nested parentheses
-	processedCommand = processedCommand.replace(/\$\(\([^)]*(?:\)[^)]*)*\)\)/g, (match) => {
-		arithmeticExpressions.push(match)
-		return `__ARITH_${arithmeticExpressions.length - 1}__`
-	})
-
-	// Handle $[...] arithmetic expressions (alternative syntax)
-	processedCommand = processedCommand.replace(/\$\[[^\]]*\]/g, (match) => {
-		arithmeticExpressions.push(match)
-		return `__ARITH_${arithmeticExpressions.length - 1}__`
-	})
-
-	// Handle parameter expansions: ${...} patterns (including array indexing)
-	// This covers ${var}, ${var:-default}, ${var:+alt}, ${#var}, ${var%pattern}, etc.
-	processedCommand = processedCommand.replace(/\$\{[^}]+\}/g, (match) => {
-		parameterExpansions.push(match)
-		return `__PARAM_${parameterExpansions.length - 1}__`
-	})
-
-	// Handle process substitutions: <(...) and >(...)
-	processedCommand = processedCommand.replace(/[<>]\(([^)]+)\)/g, (_, inner) => {
-		subshells.push(inner.trim())
-		return `__SUBSH_${subshells.length - 1}__`
-	})
-
-	// Handle locale quoting: $"...". This must run before variable masking for
-	// the same reason as ANSI-C: without it the generic double-quote masker would
-	// strip the outer quotes leaving a bare $ that the variable regex absorbs,
-	// corrupting the placeholder. The whole token (including $") is stored in the
-	// double-quote bucket so it is restored verbatim.
-	processedCommand = processedCommand.replace(/\$"(?:[^"\\]|\\.)*"/g, (match) => {
-		quotes.push(match)
-		return `__QUOTE_${quotes.length - 1}__`
-	})
-
-	// Handle ANSI-C quoting: $'...'. This must run before variable masking so the
-	// leading $ is captured as part of the quoted unit rather than being treated
-	// as a variable expansion (which would corrupt a following placeholder).
-	// ANSI-C strings interpret backslash escapes, so the pattern is escape-aware.
-	// The whole token (including the $ and quotes) is preserved in the single-
-	// quote bucket so it is restored verbatim.
-	processedCommand = processedCommand.replace(/\$'(?:[^'\\]|\\.)*'/g, (match) => {
-		singleQuotes.push(match)
-		return `__SQUOTE_${singleQuotes.length - 1}__`
-	})
-
-	// Handle simple variable references: $varname pattern
-	// This prevents shell-quote from splitting $count into separate tokens
-	processedCommand = processedCommand.replace(/\$[a-zA-Z_][a-zA-Z0-9_]*/g, (match) => {
-		variables.push(match)
-		return `__VAR_${variables.length - 1}__`
-	})
-
-	// Handle special bash variables: $?, $!, $#, $$, $@, $*, $-, $0-$9
-	processedCommand = processedCommand.replace(/\$[?!#$@*\-0-9]/g, (match) => {
-		variables.push(match)
-		return `__VAR_${variables.length - 1}__`
-	})
-
-	// Then handle subshell commands $() and back-ticks
-	processedCommand = processedCommand
-		.replace(/\$\((.*?)\)/g, (_, inner) => {
-			subshells.push(inner.trim())
-			return `__SUBSH_${subshells.length - 1}__`
-		})
-		.replace(/`(.*?)`/g, (_, inner) => {
-			subshells.push(inner.trim())
-			return `__SUBSH_${subshells.length - 1}__`
-		})
-
-	// Mask quoted strings (single and double) so their contents -- including
-	// operators like &&, |, ; and any embedded newlines -- are not treated as
-	// command separators. A single left-to-right scan with an alternation is used
-	// so that whichever quote opens first wins, preventing a quote of one style
-	// inside a string of the other style from starting a spurious match.
-	//
-	// Single quotes are matched literally (POSIX single quotes are fully opaque,
-	// no escaping inside them). Double quotes use an escape-aware pattern so that
-	// an escaped quote (\") does not prematurely terminate the match. Negated
-	// character classes match newlines, so multi-line quoted strings are captured
-	// as a single token.
-	processedCommand = processedCommand.replace(/'[^']*'|"(?:[^"\\]|\\.)*"/g, (match) => {
-		if (match.startsWith("'")) {
-			singleQuotes.push(match)
-			return `__SQUOTE_${singleQuotes.length - 1}__`
-		}
-		quotes.push(match)
-		return `__QUOTE_${quotes.length - 1}__`
-	})
-
+function parseLine(line: string, outcome: ScanOutcome, depth: number): string[] {
 	let tokens: ShellToken[]
 	try {
-		tokens = parse(processedCommand) as ShellToken[]
-	} catch (error: any) {
-		// If shell-quote fails to parse, fall back to simple splitting
-		console.warn("shell-quote parse error:", error.message, "for command:", processedCommand)
+		tokens = parse(line) as ShellToken[]
+	} catch (error) {
+		// If shell-quote fails to parse, fall back to simple splitting. This
+		// path does not recurse into payloads. Every placeholder restores to
+		// its raw text (for substitutions: the inner text), so callers never
+		// see internal markers.
+		const message = error instanceof Error ? error.message : String(error)
+		console.warn("shell-quote parse error:", message, "for command:", line)
 
-		// Simple fallback: split by common operators
-		const fallbackCommands = processedCommand
+		return line
 			.split(/(?:&&|\|\||;|\||&)/)
-			.map((cmd) => cmd.trim())
+			.map((cmd) => expandPlaceholders(cmd.trim(), outcome, true))
 			.filter((cmd) => cmd.length > 0)
-
-		// Restore all placeholders for each command
-		return fallbackCommands.map((cmd) =>
-			restorePlaceholders(
-				cmd,
-				quotes,
-				singleQuotes,
-				redirections,
-				arithmeticExpressions,
-				parameterExpansions,
-				variables,
-				subshells,
-			),
-		)
 	}
 
 	const commands: string[] = []
-	let currentCommand: string[] = []
+	let current: string[] = []
+	let pendingPayloads: string[] = []
+
+	const flush = (): void => {
+		if (current.length > 0) {
+			commands.push(expandPlaceholders(current.join(" "), outcome, false))
+			current = []
+		}
+		for (const raw of pendingPayloads) {
+			commands.push(...scanPayloadSegments(raw, outcome, depth + 1))
+		}
+		pendingPayloads = []
+	}
 
 	for (const token of tokens) {
 		if (typeof token === "object" && "op" in token) {
-			// Chain operator - split command
 			if (["&&", "||", ";", "|", "&"].includes(token.op)) {
-				if (currentCommand.length > 0) {
-					commands.push(currentCommand.join(" "))
-					currentCommand = []
-				}
+				flush()
 			} else {
-				// Other operators (>) are part of the command
-				currentCommand.push(token.op)
-			}
-		} else if (typeof token === "string") {
-			// Check if it's a subshell placeholder
-			const subshellMatch = token.match(/__SUBSH_(\d+)__/)
-			if (subshellMatch) {
-				if (currentCommand.length > 0) {
-					commands.push(currentCommand.join(" "))
-					currentCommand = []
-				}
-				commands.push(subshells[parseInt(subshellMatch[1])])
-			} else {
-				currentCommand.push(token)
+				// Other operators (>, <) are part of the command word.
+				current.push(token.op)
 			}
+			continue
+		}
+		if (typeof token !== "string") {
+			continue
+		}
+		if (!token.includes(NUL)) {
+			current.push(token)
+			continue
+		}
+		// This word carries placeholders. Reconstruct the non-substitution
+		// placeholders for verbatim restoration. Treat substitution
+		// placeholders as segment boundaries.
+		const parts = token.split(NUL)
+		let buf = ""
+		for (let p = 0; p < parts.length; p++) {
+			const part = parts[p]
+			if (p % 2 === 0) {
+				buf += part
+				continue
+			}
+			const index = Number(part.slice(1))
+			if (part[0] === "S") {
+				if (buf) {
+					current.push(buf)
+					buf = ""
+				}
+				flush()
+				commands.push(...scanPayloadSegments(outcome.substitutions[index] ?? "", outcome, depth + 1))
+				continue
+			}
+			if (part[0] === "P") {
+				pendingPayloads.push(...(outcome.paramPayloads[index] ?? []))
+			}
+			if (part[0] === "H") {
+				pendingPayloads.push(...(outcome.heredocPayloads[index] ?? []))
+			}
+			if (part[0] === "A") {
+				pendingPayloads.push(...(outcome.arithmeticPayloads[index] ?? []))
+			}
+			buf += `${NUL}${part}${NUL}`
+		}
+		if (buf) {
+			current.push(buf)
 		}
 	}
+	flush()
 
-	// Add any remaining command
-	if (currentCommand.length > 0) {
-		commands.push(currentCommand.join(" "))
-	}
-
-	// Restore all placeholders
-	return commands.map((cmd) =>
-		restorePlaceholders(
-			cmd,
-			quotes,
-			singleQuotes,
-			redirections,
-			arithmeticExpressions,
-			parameterExpansions,
-			variables,
-			subshells,
-		),
-	)
+	return commands
 }
 
 /**
- * Helper function to restore placeholders in a command string.
+ * Re-scan an extracted substitution payload through the same scan and
+ * tokenize path, so nested substitutions become independent segments. The scan
+ * records structural errors on `outcome`, and the outer command then fails
+ * closed. Each re-entry increments `depth`. Past `MAX_PAYLOAD_SCAN_DEPTH`, the
+ * command fails closed as `nesting-too-deep`. It does not re-scan generated
+ * nesting until the call stack overflows.
  */
-function restorePlaceholders(
-	command: string,
-	quotes: string[],
-	singleQuotes: string[],
-	redirections: string[],
-	arithmeticExpressions: string[],
-	parameterExpansions: string[],
-	variables: string[],
-	subshells: string[],
-): string {
-	let result = command
-	// Restore double-quoted strings
-	result = result.replace(/__QUOTE_(\d+)__/g, (_, i) => quotes[parseInt(i)])
-	// Restore single-quoted strings
-	result = result.replace(/__SQUOTE_(\d+)__/g, (_, i) => singleQuotes[parseInt(i)])
-	// Restore redirections
-	result = result.replace(/__REDIR_(\d+)__/g, (_, i) => redirections[parseInt(i)])
-	// Restore arithmetic expressions
-	result = result.replace(/__ARITH_(\d+)__/g, (_, i) => arithmeticExpressions[parseInt(i)])
-	// Restore parameter expansions
-	result = result.replace(/__PARAM_(\d+)__/g, (_, i) => parameterExpansions[parseInt(i)])
-	// Restore variable references
-	result = result.replace(/__VAR_(\d+)__/g, (_, i) => variables[parseInt(i)])
-	result = result.replace(/__SUBSH_(\d+)__/g, (_, i) => subshells[parseInt(i)])
-	return result
+function scanPayloadSegments(raw: string, outcome: ScanOutcome, depth: number): string[] {
+	if (!raw.trim()) {
+		return []
+	}
+	if (depth > MAX_PAYLOAD_SCAN_DEPTH) {
+		outcome.error = {
+			quoteType: "nesting-too-deep",
+			openIndex: 0,
+			message: unterminatedQuoteMessage("nesting-too-deep", 0, raw),
+		}
+		return []
+	}
+	const nested = scanShellSyntax(raw)
+	if (nested.error !== null) {
+		outcome.error = nested.error
+		return []
+	}
+	const parts: string[] = []
+	for (const line of nested.host.split(/\r\n|\r|\n/)) {
+		if (!line.trim()) {
+			continue
+		}
+		parts.push(...parseLine(line, nested, depth))
+		if (nested.error !== null) {
+			outcome.error = nested.error
+			return []
+		}
+	}
+	return parts
 }
diff --git a/webview-ui/src/utils/__tests__/command-parser.spec.ts b/webview-ui/src/utils/__tests__/command-parser.spec.ts
index 0316e2b328..d37dd1f309 100644
--- a/webview-ui/src/utils/__tests__/command-parser.spec.ts
+++ b/webview-ui/src/utils/__tests__/command-parser.spec.ts
@@ -52,8 +52,12 @@ describe("extractPatternsFromCommand", () => {
 	})
 
 	it("should handle null/undefined", () => {
-		expect(extractPatternsFromCommand(null as any)).toEqual([])
-		expect(extractPatternsFromCommand(undefined as any)).toEqual([])
+		// The runtime guard under test (`command?.trim()`) is exactly what
+		// makes a non-string caller value safe. Route the nullish values
+		// through one typed choke point instead of an untyped cast.
+		const asString = (value: unknown): string => value as string
+		expect(extractPatternsFromCommand(asString(null))).toEqual([])
+		expect(extractPatternsFromCommand(asString(undefined))).toEqual([])
 	})
 
 	it("should handle scripts", () => {
@@ -174,5 +178,38 @@ describe("extractPatternsFromCommand", () => {
 			expect(patterns).not.toContain("EOF")
 			expect(patterns).not.toContain("hello")
 		})
+
+		it("extracts split segments from a heredoc pipeline inside a substitution", () => {
+			// The parser splits this input into single-line segments: the
+			// heredoc token, `echo`, and `rm x`. The extractor takes its
+			// full-token path for single-line segments, so the pipeline's
+			// right-hand `rm` surfaces instead of hiding inside one opaque
+			// multi-line token.
+			const input = "echo $(cat <<E | rm x\nhi\nE\n)"
+			const patterns = extractPatternsFromCommand(input)
+			expect(patterns).toEqual(["cat", "echo", "rm", "rm x"])
+		})
+	})
+
+	it("should extract patterns from a command substitution segment", () => {
+		const patterns = extractPatternsFromCommand("echo $(whoami)")
+		expect(patterns).toContain("echo")
+		expect(patterns).toContain("whoami")
+	})
+
+	it("should extract only the leading command from an unclosed command substitution", () => {
+		// The parser fails closed here. It cannot close the $( … ) it opened,
+		// so it keeps the whole input as one opaque token. Nothing inside the
+		// malformed expansion can then surface as a pattern the lists approve.
+		const patterns = extractPatternsFromCommand("echo $(date\nfoo")
+		expect(patterns).toEqual(["echo"])
+		expect(patterns).not.toContain("date")
+		expect(patterns).not.toContain("foo")
+	})
+
+	it("should extract patterns from a process substitution segment", () => {
+		const patterns = extractPatternsFromCommand("diff <(sort a)")
+		expect(patterns).toContain("diff")
+		expect(patterns).toContain("sort")
 	})
 })