@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/agent-hooks/src/rules/shell/split.ts

@@ -0,0 +1,179 @@
+/**
+ * Splitting a command line into separately-walked pieces.
+ *
+ * Ported from `.agents/hooks/pre-tool-use/utils/shell-parser.mjs:345-456`.
+ * Unlike `nestedSources` (substitution.ts), this quote handling is
+ * deliberately unchanged from the original: a quoted region here only needs
+ * to know where it *ends*, not what control characters it contains, because
+ * everything between matching quotes is one literal word regardless of `;`,
+ * `|`, `&` or a `$(...)` inside it. Command substitutions are still tracked
+ * (via `splitSubstitution`) so that a `;` inside `$(...)` — quoted or not —
+ * does not end the piece early; substitution *content* is re-scanned for
+ * denial once by `nestedSources`, which the fix in substitution.ts already
+ * reaches inside double quotes.
+ */
+
+import { findMatchingBacktick, findMatchingParen } from './substitution.ts'
+
+interface SplitState {
+  current: string
+  quote: '"' | "'" | null
+  escaped: boolean
+  wordStart: boolean
+  /** The previous character was an unquoted, unescaped `<` or `>` — so a following `|`/`&` is part of `>|`, `>&`, `<&`. */
+  afterAngle: boolean
+}
+
+function consumeSplitQuote(state: SplitState, char: string): boolean {
+  if (state.escaped) {
+    state.current += char
+    state.escaped = false
+    state.wordStart = false
+    return true
+  }
+  if (state.quote) {
+    state.current += char
+    if (char === '\\' && state.quote === '"') state.escaped = true
+    else if (char === state.quote) state.quote = null
+    state.wordStart = false
+    return true
+  }
+  if (char === '\\') {
+    state.current += char
+    state.escaped = true
+    state.wordStart = false
+    return true
+  }
+  if (char === "'" || char === '"') {
+    state.current += char
+    state.quote = char
+    state.wordStart = false
+    return true
+  }
+  return false
+}
+
+type SplitSubstitution = { readonly error: string } | { readonly closeIndex: number; readonly text: string }
+
+function splitSubstitution(command: string, index: number, char: string): SplitSubstitution | null {
+  const isParenSubstitution = (char === '$' || char === '<' || char === '>') && command[index + 1] === '('
+  if (isParenSubstitution) {
+    const closeIndex = findMatchingParen(command, index + 1)
+    return closeIndex < 0 ? { error: 'unclosed shell substitution' } : { closeIndex, text: command.slice(index, closeIndex + 1) }
+  }
+  if (char !== '`') return null
+  const closeIndex = findMatchingBacktick(command, index)
+  return closeIndex < 0 ? { error: 'unclosed backtick substitution' } : { closeIndex, text: command.slice(index, closeIndex + 1) }
+}
+
+function splitCommentEnd(command: string, index: number, wordStart: boolean): number | null {
+  if (command[index] !== '#' || !wordStart) return null
+  let nextIndex = index
+  while (nextIndex + 1 < command.length && command[nextIndex + 1] !== '\n') nextIndex += 1
+  return nextIndex
+}
+
+function splitGroupBoundary(command: string, index: number, char: string): boolean {
+  const isGroupBrace =
+    (char === '{' && (index + 1 >= command.length || /\s/.test(command[index + 1] as string))) ||
+    (char === '}' && (index === 0 || /[\s;]/.test(command[index - 1] as string)))
+  return (char === '(' || char === ')' || isGroupBrace) && command[index - 1] !== '$'
+}
+
+function consumeSplitStructure(
+  state: SplitState,
+  command: string,
+  index: number,
+  char: string,
+  flush: (pipe?: boolean) => void,
+): { nextIndex?: number } {
+  // `>|`, `>&`, `<&` and bash's `&>`/`&>>` are redirection operators, not separators (token.ts tokenizes them).
+  const redirectionPart = (char === '|' || char === '&') && state.afterAngle
+  state.afterAngle = (char === '<' || char === '>') && !redirectionPart
+  const commentEnd = splitCommentEnd(command, index, state.wordStart)
+  if (commentEnd !== null) return { nextIndex: commentEnd }
+  if (char === '\n') {
+    flush()
+    return {}
+  }
+  if (/\s/.test(char)) {
+    state.current += char
+    state.wordStart = true
+    return {}
+  }
+  const ampersandRedirect = char === '&' && command[index + 1] === '>'
+  if (redirectionPart || ampersandRedirect) {
+    state.current += char
+    state.wordStart = false
+    return {}
+  }
+  if (char === ';' || char === '|' || char === '&') {
+    const pipe = char === '|' && command[index + 1] !== '|'
+    flush(pipe)
+    const nextIndex = (char === '&' || char === '|') && command[index + 1] === char ? index + 1 : index
+    return { nextIndex }
+  }
+  if (splitGroupBoundary(command, index, char)) {
+    flush()
+    return {}
+  }
+  state.current += char
+  state.wordStart = false
+  return {}
+}
+
+/**
+ * How a piece's stdin is fed: `piece` when the previous piece pipes straight into it (`a | b`), `group` when the
+ * pipe comes from a closing group or subshell (`{ a; } | b`), otherwise `none`.
+ */
+export type PieceFeed = 'none' | 'piece' | 'group'
+
+export interface SplitResult {
+  readonly pieces: readonly string[]
+  /** Parallel to `pieces`. */
+  readonly feeds: readonly PieceFeed[]
+  readonly invalid: boolean
+  readonly reason?: string
+}
+
+/** Break a command line into pieces at unquoted `;`, `|`, `&`, newlines and group boundaries. */
+export function splitShell(command: string): SplitResult {
+  const pieces: string[] = []
+  const feeds: PieceFeed[] = []
+  let nextFeed: PieceFeed = 'none'
+  const state: SplitState = { current: '', quote: null, escaped: false, wordStart: true, afterAngle: false }
+  const flush = (pipe = false): void => {
+    const pushed = state.current.trim() !== ''
+    if (pushed) {
+      pieces.push(state.current)
+      feeds.push(nextFeed)
+      nextFeed = 'none'
+    }
+    if (pipe) nextFeed = pushed ? 'piece' : 'group'
+    state.current = ''
+    state.wordStart = true
+  }
+
+  for (let index = 0; index < command.length; index += 1) {
+    const char = command[index] as string
+    if (consumeSplitQuote(state, char)) {
+      state.afterAngle = false
+      continue
+    }
+    const substitution = splitSubstitution(command, index, char)
+    if (substitution) {
+      if ('error' in substitution) return { pieces, feeds, invalid: true, reason: substitution.error }
+      state.current += substitution.text
+      state.wordStart = false
+      state.afterAngle = false
+      index = substitution.closeIndex
+      continue
+    }
+    const result = consumeSplitStructure(state, command, index, char, flush)
+    if (result.nextIndex !== undefined) index = result.nextIndex
+  }
+
+  if (state.quote || state.escaped) return { pieces, feeds, invalid: true, reason: 'unclosed shell quote' }
+  flush()
+  return { pieces, feeds, invalid: false }
+}

package/packages/agent-hooks/src/rules/shell/substitution.ts

@@ -0,0 +1,394 @@
+/**
+ * Command-substitution and here-document scanning.
+ *
+ * Ported from `.agents/hooks/pre-tool-use/utils/shell-parser.mjs:219-343`,
+ * with one deliberate behaviour change from the original: see `nestedSources`
+ * below.
+ */
+
+interface ParenState {
+  depth: number
+  quote: '"' | "'" | null
+  escaped: boolean
+}
+
+function advanceParenState(state: ParenState, char: string): void {
+  if (state.escaped) {
+    state.escaped = false
+    return
+  }
+  if (state.quote) {
+    if (char === '\\' && state.quote === '"') state.escaped = true
+    else if (char === state.quote) state.quote = null
+    return
+  }
+  if (char === "'" || char === '"') {
+    state.quote = char
+    return
+  }
+  if (char === '(') state.depth += 1
+  if (char === ')') state.depth -= 1
+}
+
+/** Index of the `)` matching the `(` at `openIndex`, or -1 if unclosed. */
+export function findMatchingParen(command: string, openIndex: number): number {
+  const state: ParenState = { depth: 0, quote: null, escaped: false }
+  for (let index = openIndex; index < command.length; index += 1) {
+    advanceParenState(state, command[index] as string)
+    if (state.depth === 0) return index
+  }
+  return -1
+}
+
+/**
+ * Close index of the arithmetic construct whose outer `(` is at `openIndex`:
+ * `((` ... `))` where the inner `(` closes immediately before the outer one.
+ * `$((a) && (b))` is a command substitution of two subshells, not arithmetic,
+ * and returns -1.
+ */
+export function arithmeticClose(command: string, openIndex: number): number {
+  if (command[openIndex] !== '(' || command[openIndex + 1] !== '(') return -1
+  const close = findMatchingParen(command, openIndex)
+  if (close < 0) return -1
+  return findMatchingParen(command, openIndex + 1) === close - 1 ? close : -1
+}
+
+/** Index of the closing backtick matching the one at `openIndex`, or -1 if unclosed. */
+export function findMatchingBacktick(command: string, openIndex: number): number {
+  const state = { quote: null as '"' | "'" | null, escaped: false }
+  for (let index = openIndex + 1; index < command.length; index += 1) {
+    const char = command[index] as string
+    if (consumeNestedQuote(state, char)) continue
+    if (char === '`') return index
+  }
+  return -1
+}
+
+/**
+ * Advance quote state for one character of `nestedSources`' top-level scan.
+ *
+ * BUG FIX (shell-parser.mjs:261-269, flagged as out-of-scope at
+ * tests/self-test.mjs:299-304): the original swallowed every character
+ * inside a double quote unconditionally, so `$(...)` and `` `...` `` inside
+ * `"..."` were never recognised as substitutions — `echo "$(rm -rf dist)"`
+ * and `sh -c "$(...)"` were both silently ALLOWED. A real shell still expands
+ * `$(...)` and backticks inside double quotes; only single quotes suppress
+ * substitution. So here, while `state.quote === '"'`, a substitution-leading
+ * character (`$`, `` ` ``, and the `<`/`>` process-substitution spellings the
+ * original also scanned for) returns `false` instead of being swallowed,
+ * handing control back to the caller's `nestedSubstitution` check. Backslash
+ * escapes and the closing quote are still handled here first, so `\$` and
+ * `\"` inside a double-quoted string behave exactly as before.
+ */
+export function consumeNestedQuote(state: { quote: '"' | "'" | null; escaped: boolean }, char: string): boolean {
+  if (state.escaped) {
+    state.escaped = false
+    return true
+  }
+  if (state.quote === "'") {
+    if (char === "'") state.quote = null
+    return true
+  }
+  if (state.quote === '"') {
+    if (char === '\\') {
+      state.escaped = true
+      return true
+    }
+    if (char === '"') {
+      state.quote = null
+      return true
+    }
+    if (char === '$' || char === '`' || char === '<' || char === '>') return false
+    return true
+  }
+  if (char === '\\') {
+    state.escaped = true
+    return true
+  }
+  if (char === "'" || char === '"') {
+    state.quote = char
+    return true
+  }
+  return false
+}
+
+type Substitution =
+  | { readonly arithmetic: true }
+  | { readonly invalid: true; readonly reason: string }
+  | { readonly invalid: false; readonly closeIndex: number; readonly source: string }
+
+function nestedSubstitution(command: string, index: number, char: string): Substitution | null {
+  const isParenSubstitution = (char === '$' || char === '<' || char === '>') && command[index + 1] === '('
+  // `$(( ... ))` is arithmetic, not a command: its text is scanned in place, so only a `$(...)` nested inside it is a source.
+  if (char === '$' && arithmeticClose(command, index + 1) >= 0) return { arithmetic: true }
+  if (isParenSubstitution) {
+    const closeIndex = findMatchingParen(command, index + 1)
+    return closeIndex < 0
+      ? { invalid: true, reason: 'unclosed shell substitution' }
+      : { invalid: false, closeIndex, source: command.slice(index + 2, closeIndex) }
+  }
+  if (char !== '`') return null
+  const closeIndex = findMatchingBacktick(command, index)
+  return closeIndex < 0
+    ? { invalid: true, reason: 'unclosed backtick substitution' }
+    : { invalid: false, closeIndex, source: command.slice(index + 1, closeIndex) }
+}
+
+export interface NestedSourcesResult {
+  readonly sources: readonly string[]
+  readonly invalid: boolean
+  readonly reason?: string
+}
+
+/** Extract every top-level `$(...)`/backtick payload, recursing into neither (the caller does). */
+export function nestedSources(command: string): NestedSourcesResult {
+  const sources: string[] = []
+  const state: { quote: '"' | "'" | null; escaped: boolean } = { quote: null, escaped: false }
+  for (let index = 0; index < command.length; index += 1) {
+    const char = command[index] as string
+    if (consumeNestedQuote(state, char)) continue
+    const substitution = nestedSubstitution(command, index, char)
+    if (!substitution) continue
+    if ('arithmetic' in substitution) {
+      index += 1
+      continue
+    }
+    if (substitution.invalid) return { sources, invalid: true, reason: substitution.reason }
+    sources.push(substitution.source)
+    index = substitution.closeIndex
+  }
+  if (state.quote || state.escaped) return { sources, invalid: true, reason: 'unclosed shell quote' }
+  return { sources, invalid: false }
+}
+
+/** One here-document: its body (after `<<-` tab stripping) and whether its delimiter was quoted. */
+export interface HereDocument {
+  readonly body: string
+  /** Any quoting in the delimiter word (`'EOF'`, `"EOF"`, `\EOF`, `E"O"F`) suppresses expansion of the body. */
+  readonly quoted: boolean
+}
+
+export interface HereDocumentScan {
+  /** The command with every body removed and every marker replaced by `replacement(n)`. */
+  readonly text: string
+  readonly documents: readonly HereDocument[]
+  readonly invalid: boolean
+  readonly reason?: string
+}
+
+/**
+ * The delimiter word invocation.ts substitutes for here-document `n`, so the
+ * walked command knows which body it reads. NUL-delimited: no shell word
+ * produced by a real command line contains one.
+ */
+export function hereDocumentPlaceholder(index: number): string {
+  return `\u0000heredoc:${index}\u0000`
+}
+export function hereDocumentPlaceholderIndex(word: string): number | null {
+  const match = /^\u0000heredoc:(\d+)\u0000$/.exec(word)
+  return match ? Number(match[1]) : null
+}
+
+type ScanContext =
+  | { readonly kind: 'top' | 'sq' | 'dq' | 'bt' }
+  | { readonly kind: 'sub'; depth: number; readonly arithmetic: boolean }
+
+interface Marker {
+  readonly end: number
+  readonly terminator: string
+  readonly quoted: boolean
+  readonly stripTabs: boolean
+}
+
+/** Read the `<<`/`<<-` marker at `index`, or null if no delimiter word follows it. */
+function readMarker(command: string, index: number): Marker | null {
+  let cursor = index + 2
+  const stripTabs = command[cursor] === '-'
+  if (stripTabs) cursor += 1
+  while (command[cursor] === ' ' || command[cursor] === '\t') cursor += 1
+  let terminator = ''
+  let quoted = false
+  while (cursor < command.length) {
+    const char = command[cursor] as string
+    if (char === "'" || char === '"') {
+      const close = command.indexOf(char, cursor + 1)
+      if (close < 0) return null
+      terminator += command.slice(cursor + 1, close)
+      quoted = true
+      cursor = close + 1
+      continue
+    }
+    if (char === '\\' && cursor + 1 < command.length) {
+      terminator += command[cursor + 1]
+      quoted = true
+      cursor += 2
+      continue
+    }
+    if (/[\s;|&()<>]/.test(char)) break
+    terminator += char
+    cursor += 1
+  }
+  if (!terminator || terminator.includes('\n')) return null
+  return { end: cursor, terminator, quoted, stripTabs }
+}
+
+/** Body lines from `start` up to (and consuming) the terminator line; null if never terminated. */
+function readBody(command: string, start: number, marker: Marker): { readonly body: string; readonly next: number } | null {
+  const lines: string[] = []
+  let cursor = start
+  // Terminates: every iteration either returns or advances `cursor` past a newline that exists.
+  for (;;) {
+    const newline = command.indexOf('\n', cursor)
+    const lineEnd = newline < 0 ? command.length : newline
+    const raw = command.slice(cursor, lineEnd)
+    const line = marker.stripTabs ? raw.replace(/^\t+/, '') : raw
+    cursor = lineEnd + 1
+    if (line === marker.terminator) return { body: lines.join('\n'), next: cursor }
+    if (newline < 0) return null
+    lines.push(line)
+  }
+}
+
+const isCommandContext = (context: ScanContext): boolean =>
+  context.kind === 'top' || context.kind === 'bt' || (context.kind === 'sub' && !context.arithmetic)
+
+const atWordStart = (command: string, index: number): boolean => index === 0 || /[\s;&|(]/.test(command[index - 1] as string)
+
+/**
+ * Find every here-document the shell itself would read, with quote and
+ * substitution awareness: a `<<` inside single or plain double quotes is
+ * literal text (so `bash -c "bash <<'EOF' ..."` leaves the marker to the
+ * recursive parse of the `-c` script), while one inside `$(...)` or backticks
+ * — even within double quotes — is a real marker. `<<<` is a here-string,
+ * `$((a << b))` is arithmetic, and a `#` comment is skipped. Bodies start
+ * after the newline ending the marker's line, read in marker order. A marker
+ * whose word is already a placeholder (text re-scanned by a recursive parse)
+ * is left alone.
+ */
+export function scanHereDocuments(command: string, replacement: (index: number) => string): HereDocumentScan {
+  const documents: HereDocument[] = []
+  const pending: (Marker & { readonly index: number })[] = []
+  const stack: ScanContext[] = [{ kind: 'top' }]
+  let text = ''
+  let index = 0
+  const emit = (count: number): void => {
+    text += command.slice(index, index + count)
+    index += count
+  }
+
+  while (index < command.length) {
+    const char = command[index] as string
+    const next = command[index + 1]
+    const context = stack[stack.length - 1] as ScanContext
+
+    if (char === '\n' && pending.length > 0) {
+      let cursor = index + 1
+      for (const marker of pending) {
+        const read = readBody(command, cursor, marker)
+        if (read === null) return { text: command, documents, invalid: true, reason: 'unterminated here-document' }
+        documents[marker.index] = { body: read.body, quoted: marker.quoted }
+        cursor = read.next
+      }
+      pending.length = 0
+      if (cursor <= command.length) text += '\n'
+      index = cursor
+      continue
+    }
+    if (context.kind === 'sq') {
+      if (char === "'") stack.pop()
+      emit(1)
+      continue
+    }
+    if (char === '\\') {
+      emit(2)
+      continue
+    }
+    if (next === '(' && (char === '$' || (context.kind !== 'dq' && (char === '<' || char === '>')))) {
+      stack.push({ kind: 'sub', depth: 1, arithmetic: char === '$' && arithmeticClose(command, index + 1) >= 0 })
+      emit(2)
+      continue
+    }
+    // An arithmetic command `(( ... ))` in command position: its `<<` is a shift, not a here-document.
+    if (char === '(' && isCommandContext(context) && atWordStart(command, index) && arithmeticClose(command, index) >= 0) {
+      stack.push({ kind: 'sub', depth: 1, arithmetic: true })
+      emit(1)
+      continue
+    }
+    if (char === '`') {
+      if (context.kind === 'bt') stack.pop()
+      else stack.push({ kind: 'bt' })
+      emit(1)
+      continue
+    }
+    if (context.kind === 'dq') {
+      if (char === '"') stack.pop()
+      emit(1)
+      continue
+    }
+    if (char === "'" || char === '"') {
+      stack.push({ kind: char === "'" ? 'sq' : 'dq' })
+      emit(1)
+      continue
+    }
+    if (context.kind === 'sub' && (char === '(' || char === ')')) {
+      context.depth += char === '(' ? 1 : -1
+      if (context.depth === 0) stack.pop()
+      emit(1)
+      continue
+    }
+    if (char === '#' && isCommandContext(context) && atWordStart(command, index)) {
+      const newline = command.indexOf('\n', index)
+      emit((newline < 0 ? command.length : newline) - index)
+      continue
+    }
+    const isMarker = char === '<' && next === '<' && command[index + 2] !== '<' && command[index - 1] !== '<'
+    const marker = isMarker && isCommandContext(context) ? readMarker(command, index) : null
+    if (marker !== null && hereDocumentPlaceholderIndex(marker.terminator) === null) {
+      pending.push({ ...marker, index: documents.length })
+      documents.push({ body: '', quoted: marker.quoted })
+      text += replacement(documents.length - 1)
+      index = marker.end
+      continue
+    }
+    emit(1)
+  }
+  if (pending.length > 0) return { text: command, documents, invalid: true, reason: 'unterminated here-document' }
+  return { text, documents, invalid: false }
+}
+
+export interface HereDocumentResult {
+  readonly text: string
+  readonly invalid: boolean
+  readonly reason?: string
+}
+
+/**
+ * Remove here-document bodies and markers. The REST of a marker's line is
+ * kept, so a redirection or pipe after it (`cat <<'EOF' > .git/HEAD`) is
+ * still inspected. An unquoted delimiter is reported invalid.
+ */
+export function stripHereDocumentBodies(command: string): HereDocumentResult {
+  const scan = scanHereDocuments(command, () => '')
+  if (scan.documents.some((document) => !document.quoted)) {
+    return { text: command, invalid: true, reason: 'unparsed unquoted here-document' }
+  }
+  if (scan.invalid) return { text: command, invalid: true, reason: scan.reason ?? 'unparsed here-document' }
+  return { text: scan.text, invalid: false }
+}
+
+/**
+ * Every here-document BODY found in `command` (third independent review,
+ * 2026-09-29 — "heredoc-fed interpreters"): a coarse, whole-command
+ * scanner that only ever inspects an interpreter's inline `-c`/`-e`
+ * argument misses `python3 - <<'EOF' ... EOF`/`node - <<EOF ... EOF`/
+ * `bun - <<EOF ... EOF` entirely — the actual code is the heredoc BODY,
+ * not any command-line argument at all. Best-effort: even a scan that
+ * later hits an unterminated/unquoted heredoc still returns whatever
+ * bodies were found before that point — this is a coarse detector adding
+ * one more text source to inspect, not a parser a caller depends on for
+ * correctness.
+ */
+export function heredocBodies(command: string): readonly string[] {
+  const scan = scanHereDocuments(command, () => '')
+  return scan.documents.map((document) => document.body)
+}