jackherd 1.7.0 → 1.8.0

package/kit/hooks/hooks/shared/shell-aliases.ts

@@ -0,0 +1,258 @@
+import { isProgramPosition } from './program-position'
+import { isExpanded, type SimpleCommand, type Word } from './shell'
+
+/** The aliases and functions of a shell, by name, with the text each one stands for. */
+export type ShellDefinitions = { aliases: ReadonlyMap<string, string>; functions: ReadonlyMap<string, string> }
+
+const SHELL_DEFINITION_KIND = { alias: 'alias', function: 'function' } as const
+
+export type ShellDefinitionKind = (typeof SHELL_DEFINITION_KIND)[keyof typeof SHELL_DEFINITION_KIND]
+
+/** A word at a program position that an alias or function stands for, whose body runs a watched program. */
+export type ShellDefinitionHit = { kind: ShellDefinitionKind; name: string; body: string }
+
+export const NO_DEFINITIONS: ShellDefinitions = { aliases: new Map(), functions: new Map() }
+
+/** `alias -- name=value` (zsh) or `alias name='value'` (bash), also indented inside an `if`. */
+const ALIAS_LINE = /^\s*alias\s+(?:--\s+)?(.+)$/
+/** `name () {` (zsh), `name () ` with `{` on the next line (bash), or `function name {`. */
+const FUNCTION_HEADER = /^(?:function\s+([^\s(){}]+)\s*(?:\(\))?|([^\s(){}=]+)\s*\(\))\s*\{?\s*$/
+const FUNCTION_END = '}'
+/** The characters a program name is made of, so `git` inside `git_branch` or `$GIT_DIR` is no mention. */
+const NAME_CHARACTER = /[\w.-]/
+/** The words a body may call: whatever stands between shell punctuation. */
+const BODY_WORD = /[^\s;|&(){}<>"'`$=]+/g
+const SHOWN_BODY_LENGTH = 80
+const ALIAS_BUILTIN = 'alias'
+/** An entry of the shell's own alias or function table, which defines one as an assignment: `functions[x]=…` (zsh). */
+const DEFINITION_TABLE_ENTRY = /^(aliases|galiases|saliases|functions|dis_functions|BASH_ALIASES)\[/
+
+/**
+ * Words that are shell builtins or common programs. A word among them is not looked up, so most calls read no
+ * snapshot; an alias that shadows one of them is not seen (accepted: such aliases rarely run git).
+ */
+const KNOWN_PROGRAMS = new Set([
+  ...['.', ':', '[', '[[', '!', '{', '}', 'if', 'then', 'elif', 'else', 'fi', 'for', 'while', 'until', 'do', 'done'],
+  ...['case', 'esac', 'function', 'time', 'source', 'cd', 'echo', 'printf', 'export', 'unset', 'set', 'test', 'true'],
+  ...['false', 'read', 'local', 'return', 'exit', 'eval', 'exec', 'command', 'builtin', 'type', 'which', 'whence'],
+  ...['alias', 'unalias', 'shift', 'wait', 'trap', 'kill', 'jobs', 'fg', 'bg', 'pwd', 'pushd', 'popd', 'let'],
+  ...['declare', 'typeset', 'readonly', 'getopts', 'hash', 'ulimit', 'umask', 'print', 'setopt', 'unsetopt'],
+  ...['noglob', 'nohup', 'nice', 'sleep', 'env', 'sudo', 'xargs', 'timeout', 'watch', 'cat', 'ls', 'grep', 'rg'],
+  ...['sed', 'awk', 'head', 'tail', 'wc', 'sort', 'uniq', 'cut', 'tr', 'tee', 'find', 'mkdir', 'rmdir', 'rm', 'cp'],
+  ...['mv', 'ln', 'touch', 'chmod', 'chown', 'stat', 'file', 'diff', 'tar', 'gzip', 'zip', 'unzip', 'curl', 'wget'],
+  ...['jq', 'date', 'ps', 'pgrep', 'pkill', 'df', 'du', 'uname', 'whoami', 'id', 'basename', 'dirname', 'realpath'],
+  ...['readlink', 'mktemp', 'seq', 'sh', 'bash', 'zsh', 'git', 'gh', 'bun', 'bunx', 'node', 'npm', 'npx', 'pnpm'],
+  ...['yarn', 'deno', 'python', 'python3', 'pip', 'make', 'docker', 'kubectl', 'tsc', 'biome', 'turbo', 'less'],
+  ...['ssh', 'scp', 'rsync', 'openssl', 'base64', 'sha256sum', 'column', 'paste', 'comm', 'xxd', 'od', 'tput'],
+])
+
+const aliasDefinitionOf = (line: string): string | undefined => line.match(ALIAS_LINE)?.[1]
+
+/** Removes the shell quoting of a value: `'…'`, `"…"` and backslash escapes. */
+const unquote = (text: string): string => {
+  let result = ''
+  for (let index = 0; index < text.length; index++) {
+    const character = text[index]
+    if (character === "'") {
+      const close = text.indexOf("'", index + 1)
+      const end = close === -1 ? text.length : close
+      result += text.slice(index + 1, end)
+      index = end
+    } else if (character === '\\') result += text[++index] ?? ''
+    else if (character !== '"') result += character
+  }
+  return result
+}
+
+/** `name=value` with either side quoted; the first unquoted `=` splits them. */
+const splitAlias = (definition: string): [string, string] | undefined => {
+  let quoted = false
+  for (let index = 0; index < definition.length; index++) {
+    if (definition[index] === "'") quoted = !quoted
+    if (definition[index] === '=' && !quoted)
+      return [unquote(definition.slice(0, index)), unquote(definition.slice(index + 1))]
+  }
+  return undefined
+}
+
+const functionName = (line: string): string | undefined => {
+  const match = line.match(FUNCTION_HEADER)
+  return match?.[1] ?? match?.[2]
+}
+
+/**
+ * Reads the aliases and functions of a Claude Code shell snapshot (zsh or bash). A function body runs from its header
+ * to the next line that is a lone `}`; every other line is ignored.
+ */
+export const parseShellDefinitions = (text: string): ShellDefinitions => {
+  const aliases = new Map<string, string>()
+  const functions = new Map<string, string>()
+  const lines = text.split('\n')
+  for (let index = 0; index < lines.length; index++) {
+    const name = functionName(lines[index])
+    if (name !== undefined) {
+      const end = lines.indexOf(FUNCTION_END, index + 1)
+      const last = end === -1 ? lines.length : end
+      functions.set(name, lines.slice(index + 1, last).join('\n'))
+      index = last
+      continue
+    }
+    const definition = aliasDefinitionOf(lines[index])
+    const alias = definition === undefined ? undefined : splitAlias(definition)
+    if (alias) aliases.set(alias[0], alias[1])
+  }
+  return { aliases, functions }
+}
+
+const mergeMaps = (maps: ReadonlyMap<string, string>[]): Map<string, string> => {
+  const merged = new Map<string, string>()
+  for (const map of maps) {
+    for (const [name, body] of map) merged.set(name, merged.has(name) ? `${merged.get(name)}\n${body}` : body)
+  }
+  return merged
+}
+
+/** One set of definitions from several snapshots: a name defined differently in two of them keeps both bodies. */
+export const mergeShellDefinitions = (list: ShellDefinitions[]): ShellDefinitions => ({
+  aliases: mergeMaps(list.map(({ aliases }) => aliases)),
+  functions: mergeMaps(list.map(({ functions }) => functions)),
+})
+
+/** Whether `name` stands in `text` as a whole word, not as part of a longer name. */
+const namesWord = (text: string, name: string): boolean => {
+  if (name === '') return false
+  for (let at = text.indexOf(name); at !== -1; at = text.indexOf(name, at + 1)) {
+    const before = text[at - 1] ?? ' '
+    const after = text[at + name.length] ?? ' '
+    if (!NAME_CHARACTER.test(before) && !NAME_CHARACTER.test(after)) return true
+  }
+  return false
+}
+
+const bodiesOf = ({ aliases, functions }: ShellDefinitions, name: string): string[] =>
+  [aliases.get(name), functions.get(name)].filter((body) => body !== undefined)
+
+/** Whether the text names a program, itself or through another alias or function it calls. */
+const runsProgram = (
+  definitions: ShellDefinitions,
+  text: string,
+  programs: readonly string[],
+  seen: Set<string>,
+): boolean => {
+  if (programs.some((program) => namesWord(text, program))) return true
+  return (text.match(BODY_WORD) ?? []).some((word) => {
+    if (seen.has(word)) return false
+    seen.add(word)
+    return bodiesOf(definitions, word).some((body) => runsProgram(definitions, body, programs, seen))
+  })
+}
+
+/** An alias whose value ends in a blank makes the shell expand the next word as well, as if it stood first. */
+const aliasText = (body: string, following: Word[]): string =>
+  /\s$/.test(body) ? `${body}${following.map(({ value }) => value).join(' ')}` : body
+
+const mayBeDefined = ({ value }: Word): boolean =>
+  value !== '' && !value.includes('/') && !isExpanded(value) && !KNOWN_PROGRAMS.has(value)
+
+/**
+ * The alias or function the word at `index` calls, when it stands at a program position and its body names one of
+ * `programs`, also through the aliases and functions it calls in turn. The shell expands an alias only for an
+ * unquoted word, and finds a function for a quoted one too. `definitions` is called only for a word that is no known
+ * program, so most commands read no snapshot.
+ */
+export const shellDefinitionAt = (
+  words: SimpleCommand,
+  index: number,
+  definitions: () => ShellDefinitions,
+  programs: readonly string[],
+): ShellDefinitionHit | undefined => {
+  const word = words[index]
+  if (!isProgramPosition(words, index) || !mayBeDefined(word)) return undefined
+  const known = definitions()
+  const runs = (text: string): boolean => runsProgram(known, text, programs, new Set([word.value]))
+  const alias = word.literal ? known.aliases.get(word.value) : undefined
+  if (alias !== undefined && runs(aliasText(alias, words.slice(index + 1)))) {
+    return { kind: SHELL_DEFINITION_KIND.alias, name: word.value, body: alias }
+  }
+  const body = known.functions.get(word.value)
+  if (body !== undefined && runs(body)) return { kind: SHELL_DEFINITION_KIND.function, name: word.value, body }
+  return undefined
+}
+
+/**
+ * An `alias` command anywhere a program can stand, or an entry of the alias or function table: the definition it adds
+ * in the script hides its text in a quoted word.
+ */
+export const definesShellAlias = (words: SimpleCommand): boolean =>
+  words.some(
+    (word, index) =>
+      (word.value === ALIAS_BUILTIN && isProgramPosition(words, index)) || DEFINITION_TABLE_ENTRY.test(word.value),
+  )
+
+/** A program expanded from a variable or a substitution may name a function; one with a slash is a path. */
+const isExpandedProgram = (words: SimpleCommand, index: number): boolean => {
+  const { value, literal } = words[index]
+  return !literal && isExpanded(value) && !value.includes('/') && isProgramPosition(words, index)
+}
+
+/**
+ * The word a parameter expansion falls back to or assigns: `shipit` in `${x:-shipit}`, `${x-shipit}`, `${a[0]:+shipit}`.
+ * A nested expansion matches from the innermost one, so `${x:-${y:-shipit}}` yields `shipit`. The name may be empty
+ * (`${:-shipit}`), special (`${@:-shipit}`) or an expansion itself (`${${x}:-shipit}`, zsh).
+ */
+const EXPANSION_OPERAND = /\$\{(?:[^{}:=+?-]|\$\{[^{}]*\})*:?[-=+?]([^{}]*)\}/g
+
+/** `text` with each expansion operand beside it, so a name after the operator's `-` still stands as a word. */
+const withExpansionOperands = (text: string): string =>
+  [text, ...[...text.matchAll(EXPANSION_OPERAND)].map(([, operand]) => operand)].join('\n')
+
+/**
+ * A script that lists the shell's functions can take a function's name from there without writing it out: zsh's
+ * `functions`, `dis_functions` and `functions_source` tables or builtin, `compgen -A function`/`-c`/`-A command`
+ * (also bundled, `-bA function`), `declare`/`typeset` with `-f`, `-F` or `+f` (`typeset -fm`, `declare -Fp`),
+ * `whence`/`which`/`where`/`type -m`, and a bare `set`, which prints the functions in bash.
+ */
+const READS_FUNCTION_TABLE = new RegExp(
+  [
+    /(?:^|[^\w.-])(?:dis_)?functions(?:_source)?(?:[^\w.-]|$)/,
+    /\bcompgen\b[^\n;|&]*-(?:[A-Za-z]*A\s*(?:function|command)\b|[A-Za-z]*c)/,
+    /\b(?:declare|typeset)\b[^\n;|&]*\s[+-][A-Za-z]*[fF]/,
+    /(?:^|[\s;|&(`])(?:whence|which|where|type)\s[^\n;|&]*-[A-Za-z]*m/,
+    /(?:^|[^\w.-])set\s*(?:$|[|;&)`])/,
+  ]
+    .map(({ source }) => source)
+    .join('|'),
+  'm',
+)
+
+/**
+ * Whether a program expanded from a variable or a substitution (`f=shipit; $f`) may call a function of the snapshot
+ * whose body names one of `programs`. Only a function whose name stands as a word in `text` counts: the script as
+ * written and its decoded words, where a variable or substitution would take the name from. The shell expands no alias
+ * from an expansion. `definitions` is called only when such a program stands in the command.
+ */
+export const mayRunDefinedFunction = (
+  words: SimpleCommand,
+  definitions: () => ShellDefinitions,
+  programs: readonly string[],
+  text: string,
+): boolean => {
+  if (!words.some((_word, index) => isExpandedProgram(words, index))) return false
+  const known = definitions()
+  const searched = withExpansionOperands(text)
+  const anyName = READS_FUNCTION_TABLE.test(text)
+  return [...known.functions].some(
+    ([name, body]) => (anyName || namesWord(searched, name)) && runsProgram(known, body, programs, new Set()),
+  )
+}
+
+const shown = (body: string): string => {
+  const line = body.trim().replace(/\s+/g, ' ')
+  return line.length > SHOWN_BODY_LENGTH ? `${line.slice(0, SHOWN_BODY_LENGTH)}…` : line
+}
+
+/** What a guard tells the agent about an alias or function: what it stands for, and to call the command written out. */
+export const shellDefinitionHint = ({ kind, name, body }: ShellDefinitionHit): string =>
+  kind === SHELL_DEFINITION_KIND.alias
+    ? `\`${name}\` is a shell alias for \`${shown(body)}\`, which hides the command from the permission rules. Run the command written out instead, as \`${shown(body)} …\`.`
+    : `\`${name}\` is a shell function, which hides the commands it runs from the permission rules. Run them written out instead.`

package/kit/hooks/hooks/shared/shell-snapshots.ts

@@ -0,0 +1,68 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { mergeShellDefinitions, NO_DEFINITIONS, parseShellDefinitions, type ShellDefinitions } from './shell-aliases'
+
+/** `snapshot-<shell>-<milliseconds>-<random>.sh`, as Claude Code names the shell snapshot of a session. */
+const SNAPSHOT_FILE = /^snapshot-[a-z]+-(\d+)-[A-Za-z0-9]+\.sh$/
+/** Enough for every session that may still run; a bound, so a directory nobody cleans cannot slow the guard down. */
+const MAX_SNAPSHOTS = 32
+const MAX_SNAPSHOT_BYTES = 4 * 1024 * 1024
+/** How far a snapshot's time may lie ahead of the clock; a later one is no session's and could push the real ones out. */
+const CLOCK_SLACK_MILLISECONDS = 60_000
+
+/** Where Claude Code keeps the shell snapshots its Bash tool sources: in its config directory, which CLAUDE_CONFIG_DIR moves. */
+export const snapshotDirectory = (
+  env: Record<string, string | undefined> = process.env,
+  home: string = homedir(),
+): string => join(env.CLAUDE_CONFIG_DIR || join(home, '.claude'), 'shell-snapshots')
+
+const snapshotCandidates = (names: string[], now: number): { name: string; created: number }[] =>
+  names.flatMap((name) => {
+    const created = Number(name.match(SNAPSHOT_FILE)?.[1])
+    return Number.isNaN(created) || created > now + CLOCK_SLACK_MILLISECONDS ? [] : [{ name, created }]
+  })
+
+/** A regular file: a directory or a named pipe with a snapshot's name is skipped, and a pipe would block the read. */
+const isRegularFile = (path: string): boolean => {
+  try {
+    return statSync(path).isFile()
+  } catch {
+    return false
+  }
+}
+
+const newestSnapshots = (directory: string, names: string[], now: number): string[] =>
+  snapshotCandidates(names, now)
+    .sort((left, right) => right.created - left.created)
+    .filter(({ name }) => isRegularFile(join(directory, name)))
+    .slice(0, MAX_SNAPSHOTS)
+    .map(({ name }) => join(directory, name))
+
+const readSnapshot = (path: string): ShellDefinitions[] => {
+  try {
+    if (statSync(path).size > MAX_SNAPSHOT_BYTES) return []
+    return [parseShellDefinitions(readFileSync(path, 'utf8'))]
+  } catch {
+    return []
+  }
+}
+
+/**
+ * The aliases and functions of every recent snapshot together. The hook input does not say which snapshot the session's
+ * Bash tool sourced, so a name defined in any of them counts. A missing directory or an unreadable snapshot adds
+ * nothing, and the guards decide as they would without aliases. A snapshot whose time lies after `now` is skipped.
+ */
+export const readShellDefinitions = (
+  directory: string = snapshotDirectory(),
+  now: number = Date.now(),
+): ShellDefinitions => {
+  let names: string[]
+  try {
+    names = readdirSync(directory)
+  } catch {
+    return NO_DEFINITIONS
+  }
+  const snapshots = newestSnapshots(directory, names, now).flatMap(readSnapshot)
+  return snapshots.length === 0 ? NO_DEFINITIONS : mergeShellDefinitions(snapshots)
+}

package/kit/hooks/hooks/shared/shell.ts

@@ -27,6 +27,22 @@ type Handler = (cursor: Cursor, state: ListState) => boolean
 
 export class ShellParseError extends Error {}
 
+/** What a guard tells the agent when it refuses or asks for a script `parseShell` cannot read. */
+export const UNREADABLE_ADVICE =
+  'Avoid quotes, substitutions and operators inside `${…}` and `$((…))`, close every quote and here-document, or put the script in a file and run that.'
+
+/** `<<EOF` or `<<-EOF` with an unquoted delimiter, not a here-string. */
+const EXPANDING_HERE_DOCUMENT = /(^|[^<])<<-?[ \t]*[A-Za-z_]/
+
+/**
+ * What a guard adds when the script holds a here-document with an unquoted delimiter: the shell runs `$(…)` and
+ * backticks in its body, which plain text such as Markdown rarely means. Empty for any other script.
+ */
+export const expandingHereDocumentAdvice = (script: string): string =>
+  EXPANDING_HERE_DOCUMENT.test(script)
+    ? "The shell runs `$(…)` and backticks in a here-document with an unquoted delimiter; for plain text, quote it (`<<'EOF'`)."
+    : ''
+
 const BLANKS = ' \t'
 const OPERATORS = '&;|'
 const REDIRECTION_CHARS = '<>&|'
@@ -35,6 +51,9 @@ const DELIMITER_END = ' \t\n;&|<>()'
 /** Marks where an expansion stood in a word (`$z` keeps its name after it): the value is unknown before the shell runs. */
 const EXPANSION = '$'
 
+/** Whether an expansion stood in the word's value, so the shell decides the text only when it runs. */
+export const isExpanded = (value: string): boolean => value.includes(EXPANSION)
+
 const peek = (cursor: Cursor, offset = 0): string => cursor.source[cursor.index + offset] ?? ''
 
 /** Whether the character is one of `chars`; the empty string past the end of input never is. */
@@ -68,10 +87,13 @@ const appendShaped = (state: ListState, text: string): void => {
 /** `{a,b}` and `{a..b}` expand into other words before the program sees them. */
 const BRACE_EXPANSION = /\{[^}]*(,|\.\.)[^}]*\}/
 
+/** Whether the shell would expand braces in the word's value into several words. */
+export const expandsBraces = (value: string): boolean => BRACE_EXPANSION.test(value)
+
 const endWord = (state: ListState): void => {
   const { word } = state
   if (!word) return
-  if (BRACE_EXPANSION.test(word.value)) word.literal = false
+  if (expandsBraces(word.value)) word.literal = false
   state.word = undefined
   if (state.dropNextWord) state.dropNextWord = false
   else state.words.push(word)
@@ -90,11 +112,21 @@ const endCommand = (state: ListState): void => {
  */
 const MAYBE_COMMAND = /\$\(|[<>]\(|[`'";&|\n\\]/
 
+/**
+ * `${(e)x}` (zsh flags) and `${x@P}` (bash prompt expansion) evaluate the variable's value as shell text, so a
+ * substitution stored in it runs.
+ */
+const EVALUATING_EXPANSION = /^\$\{\(|@P/
+
 /** Rather than parse a command inside an expansion, the whole text is refused as unparsable. */
 const assertNoHiddenCommand = (text: string): void => {
   if (MAYBE_COMMAND.test(text)) throw new ShellParseError('a command or quote inside an expansion')
 }
 
+const assertNotEvaluating = (text: string): void => {
+  if (EVALUATING_EXPANSION.test(text)) throw new ShellParseError('an expansion that evaluates its value')
+}
+
 const skipBalanced = (cursor: Cursor, open: string, close: string): void => {
   const start = cursor.index
   let depth = 0
@@ -107,19 +139,60 @@ const skipBalanced = (cursor: Cursor, open: string, close: string): void => {
   throw new ShellParseError(`missing ${close}`)
 }
 
-const SUBSTITUTION = /\$\(|`/
+/** Where the line at the cursor ends: at its newline, or at the end of input. */
+const lineEnd = (cursor: Cursor): number => {
+  const newline = cursor.source.indexOf('\n', cursor.index)
+  return newline === -1 ? cursor.source.length : newline
+}
+
+const isDelimiterLine = (cursor: Cursor, { delimiter, stripTabs }: Heredoc): boolean => {
+  const line = cursor.source.slice(cursor.index, lineEnd(cursor))
+  return (stripTabs ? line.replace(/^\t+/, '') : line) === delimiter
+}
 
-/** Skips the body. A substitution in an expanding body runs, so it is refused as unparsable. */
-const readHeredocBody = (cursor: Cursor, { delimiter, stripTabs, expands }: Heredoc): void => {
+/**
+ * Reads the commands of an expanding body. A backslash escapes the next character, so `\`` and `\$`
+ * stay text; `$(…)` and backticks run. The body ends at its delimiter line before the shell expands
+ * it, so a substitution that does not close inside the body is unparsable.
+ */
+const readExpandingBody = (body: string): SimpleCommand[] => {
+  const cursor: Cursor = { source: body, index: 0 }
+  const state = newListState()
   while (!atEnd(cursor)) {
-    const newline = cursor.source.indexOf('\n', cursor.index)
-    const lineEnd = newline === -1 ? cursor.source.length : newline
-    const line = cursor.source.slice(cursor.index, lineEnd)
-    cursor.index = lineEnd + 1
-    if ((stripTabs ? line.replace(/^\t+/, '') : line) === delimiter) return
-    if (expands && SUBSTITUTION.test(line)) throw new ShellParseError('a command inside a here-document')
+    if (!BODY_HANDLERS.some((handle) => handle(cursor, state))) cursor.index++
   }
-  throw new ShellParseError(`here-document without its ${delimiter} line`)
+  return state.commands
+}
+
+const skipLine = (cursor: Cursor): void => {
+  cursor.index = lineEnd(cursor) + 1
+}
+
+/** An odd number of backslashes at the end of the line: the last one joins the next line to it. */
+const CONTINUED_LINE = /(?:^|[^\\])(?:\\\\)*\\$/
+
+/**
+ * In an expanding body `\⏎` joins two lines before the shell looks for the delimiter, so `EO\⏎F` ends the body
+ * where the parse would not: such a body is refused as unparsable.
+ */
+const assertNotContinued = (cursor: Cursor): void => {
+  if (CONTINUED_LINE.test(cursor.source.slice(cursor.index, lineEnd(cursor)))) {
+    throw new ShellParseError('a line continuation in a here-document body')
+  }
+}
+
+/** Skips the body; in an expanding body the commands of its substitutions run, so they are kept. */
+const readHeredocBody = (cursor: Cursor, heredoc: Heredoc, commands: SimpleCommand[]): void => {
+  const start = cursor.index
+  while (!atEnd(cursor)) {
+    if (isDelimiterLine(cursor, heredoc)) {
+      if (heredoc.expands) commands.push(...readExpandingBody(cursor.source.slice(start, cursor.index)))
+      return skipLine(cursor)
+    }
+    if (heredoc.expands) assertNotContinued(cursor)
+    skipLine(cursor)
+  }
+  throw new ShellParseError(`here-document without its ${heredoc.delimiter} line`)
 }
 
 const readHeredocHeader = (cursor: Cursor, stripTabs: boolean): Heredoc => {
@@ -161,7 +234,7 @@ const newline: Handler = (cursor, state) => {
   if (peek(cursor) !== '\n') return false
   endCommand(state)
   cursor.index++
-  for (const heredoc of state.heredocs) readHeredocBody(cursor, heredoc)
+  for (const heredoc of state.heredocs) readHeredocBody(cursor, heredoc, state.commands)
   state.heredocs = []
   return true
 }
@@ -181,7 +254,16 @@ const singleQuoted: Handler = (cursor, state) => {
   return true
 }
 
-const ANSI_C_ESCAPES: Record<string, string> = { n: '\n', t: '\t', r: '\r', e: '\u001b', a: '\u0007', b: '\b', f: '\f', v: '\v' }
+const ANSI_C_ESCAPES: Record<string, string> = {
+  n: '\n',
+  t: '\t',
+  r: '\r',
+  e: '\u001b',
+  a: '\u0007',
+  b: '\b',
+  f: '\f',
+  v: '\v',
+}
 const MAX_CODE_POINT = 0x10ffff
 const ANSI_C_NUMERIC = /^(x[0-9a-fA-F]{1,2}|u[0-9a-fA-F]{1,4}|U[0-9a-fA-F]{1,8}|[0-7]{1,3})/
 
@@ -217,15 +299,41 @@ const ansiCQuoted: Handler = (cursor, state) => {
   return true
 }
 
+/**
+ * A backtick substitution ends at its first unescaped backtick, and inside it `` \` `` opens a nested one that the
+ * parse would read as text: such a substitution is refused as unparsable. The cursor stands after the opening one.
+ */
+const assertNoNestedBacktick = ({ source, index }: Cursor): void => {
+  for (let at = index; at < source.length && source[at] !== '`'; at++) {
+    if (source[at] !== '\\') continue
+    if (source[at + 1] === '`') throw new ShellParseError('an escaped backtick inside backticks')
+    at++
+  }
+}
+
+/**
+ * Parses a substitution's list up to its terminator. A `case` in it is refused as unparsable: the
+ * `)` of its patterns would close the substitution early and leave the rest of its commands unread.
+ */
+const parseSubstitution = (cursor: Cursor, terminator: Terminator): SimpleCommand[] => {
+  if (terminator === '`') assertNoNestedBacktick(cursor)
+  const commands = parseList(cursor, terminator)
+  if (commands.some(([program]) => program.value === 'case')) throw new ShellParseError('a case inside a substitution')
+  return commands
+}
+
 const substitute = (cursor: Cursor, state: ListState, skip: number, terminator: Terminator): void => {
   cursor.index += skip
-  state.commands.push(...parseList(cursor, terminator))
+  state.commands.push(...parseSubstitution(cursor, terminator))
   appendShaped(state, EXPANSION)
 }
 
 const startsCommandSubstitution = (cursor: Cursor): boolean =>
   peek(cursor) === '$' && peek(cursor, 1) === '(' && peek(cursor, 2) !== '('
 
+const startsArithmetic = (cursor: Cursor): boolean =>
+  peek(cursor) === '$' && peek(cursor, 1) === '(' && peek(cursor, 2) === '('
+
 const readDoubleQuotedEscape = (cursor: Cursor, state: ListState): void => {
   const next = peek(cursor, 1)
   if (next !== '\n') appendShaped(state, isOneOf('$`"\\', next) ? next : `\\${next}`)
@@ -238,10 +346,32 @@ const backtick: Handler = (cursor, state) => {
   return true
 }
 
-const arithmetic: Handler = (cursor, state) => {
-  if (peek(cursor) !== '$' || peek(cursor, 1) !== '(' || peek(cursor, 2) !== '(') return false
+/** Whether the inner parenthesis of `((…))` closes right before the outer one, as arithmetic does. */
+const innerClosesLast = (text: string): boolean => {
+  let depth = 0
+  for (let at = 1; at < text.length; at++) {
+    if (text[at] === '(') depth++
+    if (text[at] === ')' && --depth === 0) return at === text.length - 2
+  }
+  return false
+}
+
+/**
+ * Skips `$((…))` from the cursor on its `$`. Text that opens like it but closes differently, such
+ * as `$((cmd) )`, is a command substitution of a subshell and is refused as unparsable.
+ */
+const skipArithmetic = (cursor: Cursor): void => {
   cursor.index++
+  const start = cursor.index
   skipBalanced(cursor, '(', ')')
+  if (!innerClosesLast(cursor.source.slice(start, cursor.index))) {
+    throw new ShellParseError('a command substitution that opens with a subshell')
+  }
+}
+
+const arithmetic: Handler = (cursor, state) => {
+  if (!startsArithmetic(cursor)) return false
+  skipArithmetic(cursor)
   appendShaped(state, EXPANSION)
   return true
 }
@@ -252,8 +382,22 @@ const commandSubstitution: Handler = (cursor, state) => {
   return true
 }
 
-/** Inside double quotes only these two still open a command. */
-const QUOTED_HANDLERS: Handler[] = [backtick, commandSubstitution]
+/**
+ * Inside double quotes and here-document bodies a `${…}` stays text the parse does not follow, so this only refuses
+ * one that evaluates its value; it never consumes the text and leaves it to the next handler.
+ */
+const evaluatingExpansion: Handler = (cursor) => {
+  if (peek(cursor) !== '$' || peek(cursor, 1) !== '{') return false
+  const close = cursor.source.indexOf('}', cursor.index)
+  assertNotEvaluating(cursor.source.slice(cursor.index, close === -1 ? undefined : close + 1))
+  return false
+}
+
+/** Inside double quotes only substitutions still open a command. */
+const QUOTED_HANDLERS: Handler[] = [evaluatingExpansion, backtick, commandSubstitution]
+
+/** In an expanding here-document body an escape keeps the next character text; substitutions run. */
+const BODY_HANDLERS: Handler[] = [escapedChar, evaluatingExpansion, backtick, arithmetic, commandSubstitution]
 
 const doubleQuoted: Handler = (cursor, state) => {
   if (peek(cursor) !== '"') return false
@@ -284,8 +428,10 @@ const localeQuoted: Handler = (cursor, state) => {
 const parameterExpansion: Handler = (cursor, state) => {
   if (peek(cursor) !== '$') return false
   if (peek(cursor, 1) === '{') {
+    const start = cursor.index
     cursor.index++
     skipBalanced(cursor, '{', '}')
+    assertNotEvaluating(cursor.source.slice(start, cursor.index))
   } else cursor.index++
   appendShaped(state, EXPANSION)
   return true
@@ -317,7 +463,8 @@ const hereDocument: Handler = (cursor, state) => {
   return true
 }
 
-const isFileDescriptor = (word: Word | undefined): boolean => word !== undefined && word.literal && /^\d+$/.test(word.value)
+const isFileDescriptor = (word: Word | undefined): boolean =>
+  word !== undefined && word.literal && /^\d+$/.test(word.value)
 
 const redirection: Handler = (cursor, state) => {
   const char = peek(cursor)
@@ -402,6 +549,6 @@ const parseList = (cursor: Cursor, terminator: Terminator): SimpleCommand[] => {
  * Splits a shell script into its simple commands, the way a permission rule sees them: at `&&`,
  * `||`, `;`, `|`, `&` and newlines, and into subshells, command substitutions and process
  * substitutions. Here-document bodies, comments and redirection targets are not commands and are
- * dropped. Throws `ShellParseError` on an unterminated quote or substitution.
+ * dropped, except the substitutions in the body of a here-document with an unquoted delimiter, which run. Throws `ShellParseError` on an unterminated quote or substitution.
  */
 export const parseShell = (script: string): SimpleCommand[] => parseList({ source: script, index: 0 }, undefined)

package/kit/hooks/hooks.json

@@ -39,7 +39,7 @@
     "matcher": "Bash",
     "handler": {
       "type": "command",
-      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/merge-guard/index.ts '{{kit.guard.selfMergeLabel}}' || exit 2",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/merge-guard/index.ts '{{kit.guard.selfMergeLabel}}' '{{kit.guard.planApproval.approve}}' || exit 2",
       "timeout": 10,
       "onFailure": "block"
     }
@@ -61,12 +61,21 @@
       "timeout": 10
     }
   },
+  "plan-approval": {
+    "event": "PostToolUse",
+    "matcher": "AskUserQuestion",
+    "handler": {
+      "type": "command",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/merge-guard/plan-approval-record.ts '{{kit.guard.planApproval.approve}}' '{{kit.guard.planApproval.revoke}}'",
+      "timeout": 10
+    }
+  },
   "watch-guard": {
     "event": "PreToolUse",
     "matcher": "Bash",
     "handler": {
       "type": "command",
-      "command": "input=$(cat); case \"$input\" in *watch*) printf '%s' \"$input\" | bun \"$CLAUDE_PROJECT_DIR/.claude/hooks/watch-guard/index.ts\";; esac",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && { input=$(cat); case \"$input\" in *watch*) printf '%s' \"$input\" | bun .claude/hooks/watch-guard/index.ts;; esac; }",
       "timeout": 10
     }
   }