jackherd 1.7.1 → 1.8.1

package/kit/hooks/hooks/shared/program-position.ts

@@ -1,5 +1,5 @@
 import { posix } from 'node:path'
-import type { SimpleCommand, Word } from './shell'
+import { isExpanded, type SimpleCommand, type Word } from './shell'
 
 /**
  * Words Claude Code strips before it matches a Bash rule, so they do not hide the command. Its
@@ -11,10 +11,24 @@ export const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*\+?=/
 const DURATION = /^\d+(\.\d+)?[smhd]?$/
 const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh', 'mksh', 'fish'])
 const SHELL_COMMAND_FLAG = /^-[a-z]*c[a-z]*$/
+const FUNCTION_KEYWORD = 'function'
+/** zsh's precommand, `- eval …`; as a word it is also stdin (`cat -`), so it counts only where a command stands. */
+const ZSH_PRECOMMAND = '-'
+/**
+ * Shell words that run a command after names or counts of their own: `function` opens a body (`function f g {`),
+ * `coproc` may take a name, zsh's `repeat` a count and `nocorrect` none.
+ */
+const SHELL_RUNNERS = [FUNCTION_KEYWORD, 'coproc', 'repeat', 'nocorrect']
+const SHELL_COMMAND_OPENERS = new Set([...SHELL_RUNNERS, ZSH_PRECOMMAND])
+/** The builtin that runs its arguments, joined, as a script in the same shell. */
+const EVAL_BUILTIN = 'eval'
+/** The builtin that runs its action text later in the same shell. */
+const TRAP_BUILTIN = 'trap'
 
 /** Programs that run their arguments as a command, so a program right after them is the one that runs. */
 const COMMAND_RUNNERS = new Set([
   ...RULE_TRANSPARENT_WRAPPERS,
+  ...SHELL_RUNNERS,
   'env',
   'sudo',
   'doas',
@@ -67,16 +81,145 @@ const shellCommandScript = (words: SimpleCommand, shellIndex: number): string |
   return words.slice(flag + 1).find((word) => !isOption(word))?.value
 }
 
+/** The action of `trap <action> <signal>…`: the first word after the options and `--`; the shell runs it later itself. */
+const trapAction = (words: SimpleCommand, trapIndex: number): string | undefined => {
+  const rest = words.slice(trapIndex + 1)
+  const start = rest.findIndex((word) => !isOption(word) || word.value === '--')
+  const action = rest[start]?.value === '--' ? rest[start + 1] : rest[start]
+  return action?.value
+}
+
+/**
+ * Whether a word before a builtin leaves it the command: an option or its value, an assignment, a duration
+ * (`sudo -u me`, `env X=1`, `timeout 30`, `repeat 1`), a reserved word, or the name after `function`.
+ */
+const leadsToBuiltin = (words: SimpleCommand, index: number): boolean => {
+  const { value } = words[index]
+  const previous = words[index - 1]
+  return (
+    isOption(words[index]) ||
+    isOption(previous) ||
+    ASSIGNMENT.test(value) ||
+    DURATION.test(value) ||
+    RESERVED_WORDS.has(value) ||
+    (previous !== undefined && programName(previous) === FUNCTION_KEYWORD)
+  )
+}
+
+/**
+ * Where in a command a builtin runs as the command itself: at the rule start, right after a runner that is itself the
+ * command (with its options), or anywhere after a shell word that opens a command and stands as the command itself,
+ * whatever names or counts follow it (`function f g {`, `coproc NAME {`, `repeat $n`, zsh's `- eval`). No external
+ * runner starts a builtin from a later argument, so `timeout 30 rg eval` searches for the word. One pass per command; each word looks back only to the runner before it.
+ */
+const builtinPositions = (words: SimpleCommand): boolean[] => {
+  const start = ruleStart(words)
+  const positions: boolean[] = []
+  let afterOpener = false
+  for (let index = 0; index < words.length; index++) {
+    let before = index - 1
+    while (before >= 0 && !COMMAND_RUNNERS.has(programName(words[before])) && leadsToBuiltin(words, before)) before--
+    const afterRunner = before >= 0 && COMMAND_RUNNERS.has(programName(words[before])) && positions[before]
+    positions[index] = index === start || afterRunner || afterOpener
+    if (positions[index] && SHELL_COMMAND_OPENERS.has(words[index].value)) afterOpener = true
+  }
+  return positions
+}
+
+/** One pass per command, since every word of it is asked: the positions of a command are its own. */
+const positionsByCommand = new WeakMap<SimpleCommand, boolean[]>()
+
+const isBuiltinPosition = (words: SimpleCommand, index: number): boolean => {
+  const known = positionsByCommand.get(words)
+  if (known) return known[index]
+  const positions = builtinPositions(words)
+  positionsByCommand.set(words, positions)
+  return positions[index]
+}
+
+/** Whether the word runs as `builtin`: named so where a command stands, also quoted (`'trap'`) or escaped (`\trap`). */
+const isBuiltinAt = (words: SimpleCommand, index: number, builtin: string): boolean =>
+  programName(words[index]) === builtin && isBuiltinPosition(words, index)
+
 export const inlineScript = (words: SimpleCommand, index: number): string | undefined => {
-  const word = words[index]
-  if (word.literal && word.value === 'eval') return words.slice(index + 1).map(({ value }) => value).join(' ')
-  return isShell(word) ? shellCommandScript(words, index) : undefined
+  if (isBuiltinAt(words, index, EVAL_BUILTIN))
+    return words
+      .slice(index + 1)
+      .map(({ value }) => value)
+      .join(' ')
+  if (isBuiltinAt(words, index, TRAP_BUILTIN)) return trapAction(words, index)
+  return isShell(words[index]) ? shellCommandScript(words, index) : undefined
 }
 
+/** Interpreters that run program text given on the command line or read from their input. */
+const INTERPRETERS = new Set(['python', 'python3', 'node', 'nodejs', 'bun', 'deno', 'perl', 'ruby', 'php', 'lua'])
+const INLINE_PROGRAM_OPTIONS = new Set(['-c', '-e', '-E', '-p', '-pe', '--eval', '--command', '--print', '-r'])
+const VERSIONED_PYTHON = /^python\d+(\.\d+)*$/
+/** A cluster of short options that ends in the one taking the program text: `python3 -Ic`, `perl -lne`. */
+const INLINE_PROGRAM_CLUSTER = /^-[A-Za-z]*[ce]$/
+/** An operand that names the interpreter's own input as the program file. */
+const INPUT_OPERAND = /^(-|\/dev\/stdin|\/dev\/fd\/0|\/proc\/self\/fd\/0)$/
+/** Options that print and exit, so an interpreter without an operand reads no program. */
+const PRINT_AND_EXIT = new Set(['--version', '-v', '-V', '--help', '-h'])
+/** Interpreters that, without an operand, print their help instead of reading a program; they read one after `run`. */
+const SUBCOMMAND_INTERPRETERS = new Set(['bun'])
+const RUN_SUBCOMMAND = 'run'
+/** An operand that names a script file: the words after it are the script's arguments, not the interpreter's options. */
+const SCRIPT_FILE = /\.(py|js|mjs|cjs|ts|mts|cts|jsx|tsx|rb|pl|pm|php|lua)$/i
+
+const isInterpreter = (word: Word): boolean => {
+  const name = programName(word)
+  return INTERPRETERS.has(name) || VERSIONED_PYTHON.test(name)
+}
+
+const isInlineProgramOption = ({ value }: Word): boolean =>
+  INLINE_PROGRAM_OPTIONS.has(value.split('=')[0]) || INLINE_PROGRAM_CLUSTER.test(value)
+
+/** The operand that names the program: the first one, or for `bun run` the one after `run`; `-` counts as one. */
+const programOperand = (interpreter: Word, rest: Word[]): Word | undefined => {
+  const operands = rest.filter((word) => !isOption(word) || word.value === '-')
+  const afterRun = SUBCOMMAND_INTERPRETERS.has(programName(interpreter)) && operands[0]?.value === RUN_SUBCOMMAND
+  return afterRun ? operands[1] : operands[0]
+}
+
+/**
+ * Whether the interpreter reads its program from its input (`python3 -`, `node` fed by a pipe, `bun -`) or from an
+ * expansion it cannot show (`python3 <(…)`).
+ */
+const readsProgramFromInput = (interpreter: Word, rest: Word[]): boolean => {
+  const operand = programOperand(interpreter, rest)
+  if (operand === undefined) {
+    return (
+      !SUBCOMMAND_INTERPRETERS.has(programName(interpreter)) && !rest.some(({ value }) => PRINT_AND_EXIT.has(value))
+    )
+  }
+  // A quoted operand is still a file name; only an expansion (`$f`, `<(…)`) hides where the program comes from.
+  return isExpanded(operand.value) || INPUT_OPERAND.test(operand.value)
+}
+
+/**
+ * The words up to a script file operand. Only a file name ends them: any other word could be an option's value
+ * (`python3 -W ignore -c …`), and stopping there would miss the `-c` behind it.
+ */
+const interpreterOptions = (rest: Word[]): Word[] => {
+  const scriptFile = rest.findIndex((word) => !isOption(word) && SCRIPT_FILE.test(word.value))
+  return scriptFile === -1 ? rest : rest.slice(0, scriptFile)
+}
+
+/**
+ * An interpreter, anywhere a program can stand, handed program text (`python3 -c`, `node -e`) or reading it from its
+ * input (`python3 - <<EOF`, `… | node`): the program can start any command, and no parse of the shell sees it.
+ */
+export const runsInterpreterProgram = (words: SimpleCommand): boolean =>
+  words.some((word, index) => {
+    if (!isProgramPosition(words, index) || !isInterpreter(word)) return false
+    const rest = words.slice(index + 1)
+    return interpreterOptions(rest).some(isInlineProgramOption) || readsProgramFromInput(word, rest)
+  })
+
 /** A shell at the rule start with no script argument reads its script from stdin: a pipe, a here-document. */
 export const readsScriptFromInput = (words: SimpleCommand): boolean => {
   const start = ruleStart(words)
   const shell = words[start]
   return shell !== undefined && isShell(shell) && words.slice(start + 1).every(isOption)
 }
-

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)
+}