jackherd 1.2.0 → 1.4.0

package/kit/hooks/hooks/merge-guard/decision.ts

@@ -0,0 +1,286 @@
+import {
+  inlineScript,
+  isOption,
+  isProgramPosition,
+  isShell,
+  programName,
+} from '../shared/program-position'
+import { parseShell, ShellParseError, type SimpleCommand, type Word } from '../shared/shell'
+
+export type MergeGuardDecision = { kind: 'pass' } | { kind: 'ask'; reason: string }
+
+export type GuardPolicy = {
+  /** The guarded commands as words: a program and the plain words after it, such as `gh pr merge`. */
+  commands: readonly string[]
+  /**
+   * Whether the user approved the merge of this pull request; asked only for a plain `gh pr merge <number>`.
+   * A throw counts as not approved.
+   */
+  isMergeApproved: (pullRequest: number) => boolean
+}
+
+/** A guarded command the script runs or could run, and the pull request a merge names, when it names one plainly. */
+type Finding = { command: string; pullRequest: number | undefined }
+
+/** The one command whose guard an approval can lift. Every other guarded command asks each time. */
+const MERGE_COMMAND = 'gh pr merge'
+
+/** gh options that take the next word, so it is not a command word. */
+const OPTIONS_WITH_VALUE = new Set(['-R', '--repo', '--hostname'])
+
+/**
+ * The only words a merge may carry besides `gh pr merge <number>` and still count as "pull request <number> of this
+ * repository, after its checks". Anything else (another repository, a flag with a value, `--admin`, `--auto`) asks.
+ */
+const APPROVABLE_FLAGS = new Set(['--squash', '-s', '--merge', '-m', '--rebase', '-r', '--delete-branch', '-d'])
+const PULL_REQUEST_NUMBER = /^[1-9]\d*$/
+const GLOB = /[*?[]/
+
+/** Programs that run text they are given or read from elsewhere, so the words may not stand at the program. */
+const OPAQUE_RUNNERS = new Set([
+  'xargs',
+  'find',
+  'trap',
+  'coproc',
+  'repeat',
+  'script',
+  'su',
+  'flock',
+  'ssh',
+  'parallel',
+  'ionice',
+  'chrt',
+  'taskset',
+  'strace',
+  'unbuffer',
+  'chroot',
+  'runuser',
+  'systemd-run',
+  'nsenter',
+  'unshare',
+  'firejail',
+  'pkexec',
+  'entr',
+  'watchexec',
+  'busybox',
+])
+
+const SOURCING = new Set(['source', '.'])
+
+/** Interpreters that run program text given on the command line, and the options that give it. */
+const INTERPRETERS = new Set(['python', 'python3', 'node', 'bun', 'deno', 'perl', 'ruby', 'php', 'lua'])
+const INLINE_PROGRAM_OPTIONS = new Set(['-c', '-e', '-E', '-p', '-pe', '--eval', '--command', '-r'])
+const INPUT_PATH = /^(\/dev\/stdin|\/dev\/fd\/|\/proc\/self\/fd\/)/
+
+const PASS: MergeGuardDecision = { kind: 'pass' }
+
+/**
+ * The words after the program that are not options, nor the value of one. A word right after an option this guard
+ * does not know could be its value (`kubectl -n prod delete`), so a second list leaves out every such word.
+ */
+const operandLists = (words: SimpleCommand): Word[][] => {
+  const all: Word[] = []
+  const withoutPossibleValues: Word[] = []
+  for (let index = 0; index < words.length; index++) {
+    if (isOption(words[index])) {
+      if (OPTIONS_WITH_VALUE.has(words[index].value)) index++
+      else if (index + 1 < words.length && !isOption(words[index + 1])) {
+        all.push(words[index + 1])
+        index++
+      }
+    } else {
+      all.push(words[index])
+      withoutPossibleValues.push(words[index])
+    }
+  }
+  return [all, withoutPossibleValues]
+}
+
+/** A word the shell expands or globs could be any word, or several, or none. */
+const isWildcard = ({ literal, value }: Word): boolean => !literal || GLOB.test(value)
+
+/** Whether the operands, from their start, can be the expected words: a wildcard stands for any number of them. */
+const matchesFrom = (operands: Word[], expected: string[]): boolean => {
+  if (expected.length === 0) return true
+  const [operand, ...rest] = operands
+  if (operand === undefined) return false
+  if (isWildcard(operand)) return matchesFrom(rest, expected) || matchesFrom(operands, expected.slice(1))
+  return operand.value === expected[0] && matchesFrom(rest, expected.slice(1))
+}
+
+/** The number of `gh pr merge <number>` in its plain form: literal words only, merge-method and delete-branch flags. */
+const plainPullRequest = (words: SimpleCommand, expected: string[]): number | undefined => {
+  const after = words.slice(1)
+  const [first, second, ...rest] = after
+  if (after.some(isWildcard) || first?.value !== expected[0] || second?.value !== expected[1]) return undefined
+  const numbers = rest.filter(({ value }) => !APPROVABLE_FLAGS.has(value))
+  const only = numbers.length === 1 && PULL_REQUEST_NUMBER.test(numbers[0].value) ? numbers[0].value : undefined
+  return only === undefined ? undefined : Number(only)
+}
+
+/** `sole`: the script is this one simple command, written plainly, the only shape an approval can lift. */
+const findingOf = (command: string, words: SimpleCommand, index: number, sole: boolean): Finding | undefined => {
+  const expected = command.split(' ').slice(1)
+  if (!operandLists(words.slice(index + 1)).some((operands) => matchesFrom(operands, expected))) return undefined
+  const plain = sole && words[index].literal && words[index].value === 'gh'
+  return { command, pullRequest: plain ? plainPullRequest(words.slice(index), expected) : undefined }
+}
+
+const callsOfWord = (words: SimpleCommand, index: number, commands: readonly string[], sole: boolean): Finding[] => {
+  if (!isProgramPosition(words, index)) return []
+  const program = programName(words[index])
+  return commands
+    .filter((command) => command.split(' ')[0] === program)
+    .flatMap((command) => findingOf(command, words, index, sole && index === 0) ?? [])
+}
+
+const isWordCharacter = (character: string | undefined): boolean => character !== undefined && /\w/.test(character)
+
+const findWord = (script: string, word: string, from: number): number => {
+  for (let at = script.indexOf(word, from); at !== -1; at = script.indexOf(word, at + 1)) {
+    if (!isWordCharacter(script[at - 1]) && !isWordCharacter(script[at + word.length])) return at
+  }
+  return -1
+}
+
+/** Whether the script names the words as whole words in this order; a linear search, so a long script cannot stall it. */
+const namesInOrder = (script: string, words: string[]): boolean => {
+  let from = 0
+  for (const word of words) {
+    const at = findWord(script, word, from)
+    if (at === -1) return false
+    from = at + word.length
+  }
+  return true
+}
+
+const callsNaming = (script: string, commands: readonly string[], wordsOf: (command: string) => string[]): Finding[] =>
+  commands
+    .filter((command) => namesInOrder(script, wordsOf(command)))
+    .map((command) => ({ command, pullRequest: undefined }))
+
+/** Where the script cannot be parsed, a guarded program named as a whole word is enough to ask. */
+const namedPrograms = (script: string, commands: readonly string[]): Finding[] =>
+  callsNaming(script, commands, (command) => command.split(' ').slice(0, 1))
+
+/** Where the program is hidden or the words are handed over as text, the command words after the program are the sign. */
+const mentionedCommandWords = (script: string, commands: readonly string[]): Finding[] =>
+  callsNaming(script, commands, (command) => command.split(' ').slice(1))
+
+/** A program expanded from a variable or a substitution could be the guarded one. */
+const runsExpandedProgram = (words: SimpleCommand): boolean =>
+  words.some((word, index) => !word.literal && isProgramPosition(words, index))
+
+const runsOpaquely = (words: SimpleCommand): boolean =>
+  words.some((word, index) => isProgramPosition(words, index) && OPAQUE_RUNNERS.has(programName(word)))
+
+/**
+ * A shell, anywhere a program can stand, that reads its script from stdin (no operand, or `-s`), from a process
+ * substitution or from a file descriptor; or `source` of such a thing: the text comes from somewhere else.
+ */
+const readsScriptFromElsewhere = (words: SimpleCommand): boolean =>
+  words.some((word, index) => {
+    if (!isProgramPosition(words, index)) return false
+    const shell = isShell(word)
+    if (!shell && !SOURCING.has(programName(word))) return false
+    const rest = words.slice(index + 1)
+    const operands = rest.filter((each) => !isOption(each))
+    const fromInput = shell && (operands.length === 0 || rest.some(({ value }) => value === '-s'))
+    return fromInput || operands.some((each) => !each.literal || INPUT_PATH.test(each.value))
+  })
+
+/** An interpreter handed program text (`python3 -c`, `node -e`) or git handed an alias runs text the parse cannot see. */
+const runsProgramText = (words: SimpleCommand): boolean =>
+  words.some((word, index) => {
+    if (!isProgramPosition(words, index)) return false
+    const rest = words.slice(index + 1)
+    if (programName(word) === 'git') return rest.some(({ value }) => value.startsWith('alias.'))
+    return INTERPRETERS.has(programName(word)) && rest.some(({ value }) => INLINE_PROGRAM_OPTIONS.has(value))
+  })
+
+/** An inline script that is itself an expansion (`eval "$X"`) hides its text from the parse of the call. */
+const runsInlineExpansion = (words: SimpleCommand): boolean =>
+  words.some((_word, index) => inlineScript(words, index)?.includes('$') === true)
+
+/**
+ * Whether the command's words contain the guarded command's words in this order, anything between them: the
+ * fallback for a wrapper nobody listed (`mise exec -- gh pr merge 5`), which hides the program from the position test.
+ */
+const containsInOrder = (words: SimpleCommand, command: string): boolean => {
+  const [program, ...rest] = command.split(' ')
+  const at = words.findIndex((word) => programName(word) === program)
+  let from = at + 1
+  if (at === -1) return false
+  for (const expected of rest) {
+    const next = words.findIndex((word, index) => index >= from && word.literal && word.value === expected)
+    if (next === -1) return false
+    from = next + 1
+  }
+  return true
+}
+
+const callsInCommand = (words: SimpleCommand, commands: readonly string[], sole: boolean, whole: string): Finding[] => {
+  const direct = words.flatMap((_word, index) => {
+    const script = inlineScript(words, index)
+    return script === undefined ? callsOfWord(words, index, commands, sole) : callsIn(script, commands, false, whole)
+  })
+  const found = new Set(direct.map(({ command }) => command))
+  const byWords = commands
+    .filter((command) => !found.has(command) && containsInOrder(words, command))
+    .map((command) => ({ command, pullRequest: undefined }))
+  return [...direct, ...byWords]
+}
+
+/** Each check reads the whole script: a shell that reads stdin, an expanded program or an opaque runner hides what runs. */
+const hidesWhatRuns = (words: SimpleCommand): boolean =>
+  runsExpandedProgram(words) ||
+  runsOpaquely(words) ||
+  readsScriptFromElsewhere(words) ||
+  runsInlineExpansion(words) ||
+  runsProgramText(words)
+
+const callsInScriptWide = (whole: string, parsed: SimpleCommand[], commands: readonly string[]): Finding[] =>
+  parsed.some(hidesWhatRuns) ? mentionedCommandWords(whole, commands) : []
+
+/** `whole` is the text of the outermost script: a nested script's input comes from there, so the words are searched in it. */
+const callsIn = (script: string, commands: readonly string[], top: boolean, whole: string): Finding[] => {
+  try {
+    const parsed = parseShell(script)
+    const sole = top && parsed.length === 1 && !script.trimStart().startsWith('(')
+    return [
+      ...parsed.flatMap((words) => callsInCommand(words, commands, sole, whole)),
+      ...callsInScriptWide(whole, parsed, commands),
+    ]
+  } catch (error) {
+    if (error instanceof ShellParseError) return namedPrograms(whole, commands)
+    throw error
+  }
+}
+
+const isApproved = ({ command, pullRequest }: Finding, policy: GuardPolicy): boolean => {
+  if (command !== MERGE_COMMAND || pullRequest === undefined) return false
+  try {
+    return policy.isMergeApproved(pullRequest)
+  } catch {
+    return false
+  }
+}
+
+const askBecause = (commands: string[]): MergeGuardDecision => ({
+  kind: 'ask',
+  reason: `${commands.map((command) => `\`${command}\``).join(' and ')} is on the project's guarded list (guard.commands in .jackherd/config.json), so the user confirms it.`,
+})
+
+/**
+ * Decides on a Bash command before it runs: `ask` when it runs, or could run, a guarded command (`gh pr merge`,
+ * `gh workflow run` by default), also behind options before the verb, a chain, a wrapper, `sh -c`, `eval`, a
+ * script piped into a shell or a program held in a variable. A script that is exactly
+ * `gh pr merge <number>` with merge-method and delete-branch flags passes when the user approved it
+ * (`isMergeApproved`); any other shape of the merge, and every other guarded command, asks. A command that merely names the words (an argument, a commit message) is none.
+ */
+export const decideBashCommand = (command: string, policy: GuardPolicy): MergeGuardDecision => {
+  const findings = callsIn(command, policy.commands, true, command)
+  if (findings.length === 0) return PASS
+  const unapproved = findings.filter((finding) => !isApproved(finding, policy))
+  return unapproved.length === 0 ? PASS : askBecause([...new Set(unapproved.map(({ command: name }) => name))])
+}

package/kit/hooks/hooks/merge-guard/index.ts

@@ -0,0 +1,56 @@
+// PreToolUse hook for Bash, shipped by jackherd. Reads the hook input on stdin and answers with an ask
+// decision on stdout when the command runs a guarded one, or with nothing to leave the call to the
+// permission rules. Any failure asks: a guard that crashes, or takes too long, must not wave the command through.
+// The decision runs in a worker that is ended after DEADLINE_MS, because Claude Code lets a call through when a hook
+// runs into its own timeout. argv[2] is the exact option label that approves a merge, rendered into the hook entry by `sync`.
+import type { MergeGuardDecision } from './decision'
+import { failureDecision } from './run'
+
+/** Below the 10 s the hook entry allows, with room for the start of Bun and for printing. */
+const DEADLINE_MS = 7000
+
+type Job = { text: string; label: string; projectDirectory: string }
+
+const timeoutDecision: MergeGuardDecision = {
+  kind: 'ask',
+  reason: 'The merge guard hook did not finish in time, so it cannot tell whether this command is guarded. Confirm it only if you know it is harmless.',
+}
+
+const decideWithin = (job: Job, deadline: number): Promise<MergeGuardDecision> =>
+  new Promise((resolve) => {
+    const worker = new Worker(new URL('./worker.ts', import.meta.url).href)
+    const finish = (decision: MergeGuardDecision): void => {
+      clearTimeout(timer)
+      worker.terminate()
+      resolve(decision)
+    }
+    const timer = setTimeout(() => finish(timeoutDecision), deadline)
+    worker.onmessage = ({ data }: MessageEvent<MergeGuardDecision>) => finish(data)
+    worker.onerror = (event) => finish(failureDecision(event.error ?? event.message))
+    worker.postMessage(job)
+  })
+
+const decide = async (): Promise<MergeGuardDecision> => {
+  try {
+    const text = await Bun.stdin.text()
+    const projectDirectory = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
+    return await decideWithin({ text, label: process.argv[2] ?? '', projectDirectory }, DEADLINE_MS)
+  } catch (error) {
+    return failureDecision(error)
+  }
+}
+
+const decision = await decide()
+
+if (decision.kind === 'ask') {
+  console.log(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'ask',
+        permissionDecisionReason: decision.reason,
+      },
+    }),
+  )
+}
+process.exit(0)

package/kit/hooks/hooks/merge-guard/pull-request.ts

@@ -0,0 +1,33 @@
+/**
+ * The branch a pull request comes from, asked of GitHub. The approval of a merge hangs on the branch the
+ * user saw in the question; the pull request does not exist yet at that point, so GitHub, not the agent,
+ * says which branch pull request <number> carries.
+ */
+
+const LOOKUP_TIMEOUT_MS = 4000
+
+type PullRequestView = { headRefName?: unknown; isCrossRepository?: unknown; state?: unknown }
+
+/** The head branch of an open pull request from this repository; a fork's branch name proves nothing. */
+export const parseHeadBranch = (json: string): string | undefined => {
+  try {
+    const view: unknown = JSON.parse(json)
+    if (typeof view !== 'object' || view === null) return undefined
+    const { headRefName, isCrossRepository, state } = view as PullRequestView
+    const ours = state === 'OPEN' && isCrossRepository === false
+    return ours && typeof headRefName === 'string' ? headRefName : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** Runs `gh pr view <number>` in `directory`, the directory the command itself runs in, without a shell; any failure answers nothing. */
+export const headBranchOf = (pullRequest: number, directory: string): string | undefined => {
+  const result = Bun.spawnSync(['gh', 'pr', 'view', String(pullRequest), '--json', 'headRefName,isCrossRepository,state'], {
+    cwd: directory,
+    timeout: LOOKUP_TIMEOUT_MS,
+    stdout: 'pipe',
+    stderr: 'ignore',
+  })
+  return result.exitCode === 0 ? parseHeadBranch(result.stdout.toString()) : undefined
+}

package/kit/hooks/hooks/merge-guard/run.ts

@@ -0,0 +1,60 @@
+import { readFileSync } from 'node:fs'
+import { isAbsolute, relative } from 'node:path'
+import { approvedBranches, parseTranscript } from './approval'
+import { decideBashCommand, type GuardPolicy, type MergeGuardDecision } from './decision'
+import { headBranchOf } from './pull-request'
+import { type GuardSettings, readGuardSettings } from './settings'
+
+type HookInput = { tool_input?: { command?: unknown }; transcript_path?: unknown; cwd?: unknown }
+
+const PASS: MergeGuardDecision = { kind: 'pass' }
+
+const approvedBranchesFrom = (transcriptPath: unknown, settings: GuardSettings, label: string): Set<string> => {
+  if (!settings.selfMerge.offer || typeof transcriptPath !== 'string') return new Set()
+  return approvedBranches({
+    entries: parseTranscript(readFileSync(transcriptPath, 'utf8')),
+    label,
+    now: Date.now(),
+    windowMinutes: settings.selfMerge.approvalMinutes,
+  })
+}
+
+/** Where the command runs must lie in the project: the same branch name in another checkout is another pull request. */
+const isInside = (directory: string, project: string): boolean => {
+  const path = relative(project, directory)
+  return path === '' || (!path.startsWith('..') && !isAbsolute(path))
+}
+
+const policyFor = (input: HookInput, label: string, projectDirectory: string): GuardPolicy => {
+  const settings = readGuardSettings(projectDirectory)
+  const directory = typeof input.cwd === 'string' && input.cwd !== '' ? input.cwd : projectDirectory
+  const headBranches = new Map<number, string | undefined>()
+  const headBranch = (pullRequest: number): string | undefined => {
+    if (!headBranches.has(pullRequest)) headBranches.set(pullRequest, headBranchOf(pullRequest, directory))
+    return headBranches.get(pullRequest)
+  }
+  let approved: Set<string> | undefined
+  return {
+    commands: settings.commands,
+    isMergeApproved: (pullRequest) => {
+      if (!isInside(directory, projectDirectory)) return false
+      const branches = (approved ??= approvedBranchesFrom(input.transcript_path, settings, label))
+      if (branches.size === 0) return false
+      const branch = headBranch(pullRequest)
+      return branch !== undefined && branches.has(branch)
+    },
+  }
+}
+
+/** Reads the hook input and decides; throws on input it cannot read. */
+export const decideInput = (text: string, label: string, projectDirectory: string): MergeGuardDecision => {
+  const input = JSON.parse(text) as HookInput
+  const command = input.tool_input?.command
+  if (typeof command !== 'string') return PASS
+  return decideBashCommand(command, policyFor(input, label, projectDirectory))
+}
+
+export const failureDecision = (error: unknown): MergeGuardDecision => ({
+  kind: 'ask',
+  reason: `The merge guard hook failed (${error instanceof Error ? error.message : String(error)}), so it cannot tell whether this command is guarded. Confirm it only if you know it is harmless.`,
+})

package/kit/hooks/hooks/merge-guard/settings.ts

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+export type GuardSettings = {
+  commands: string[]
+  selfMerge: { offer: boolean; approvalMinutes: number }
+}
+
+export const DEFAULT_SETTINGS: GuardSettings = {
+  commands: ['gh pr merge', 'gh workflow run'],
+  selfMerge: { offer: true, approvalMinutes: 180 },
+}
+
+const CONFIG_PATH = join('.jackherd', 'config.json')
+export const GUARDED_COMMAND = /^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*){1,3}$/
+export const MAX_MINUTES = 1440
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const isCommandList = (value: unknown): value is string[] =>
+  Array.isArray(value) && value.every((entry) => typeof entry === 'string' && GUARDED_COMMAND.test(entry))
+
+const isMinutes = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= MAX_MINUTES
+
+/** The `guard` section of the first config that exists; the hook has no schema library, `jh` validates the file. */
+const readGuardSection = (directories: string[]): Record<string, unknown> => {
+  const path = directories.map((directory) => join(directory, CONFIG_PATH)).find((candidate) => existsSync(candidate))
+  if (!path) return {}
+  try {
+    const config: unknown = JSON.parse(readFileSync(path, 'utf8'))
+    return isRecord(config) && isRecord(config.guard) ? config.guard : {}
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * The guard settings of the project's `.jackherd/config.json`, else of the home one. Whatever is missing or
+ * malformed keeps its default, so a broken config guards more, never less; only an empty list switches the guard off.
+ */
+export const readGuardSettings = (projectDirectory: string, home: string = homedir()): GuardSettings => {
+  const section = readGuardSection([projectDirectory, home])
+  const selfMerge = isRecord(section.selfMerge) ? section.selfMerge : {}
+  return {
+    commands: isCommandList(section.commands) ? section.commands : DEFAULT_SETTINGS.commands,
+    selfMerge: {
+      offer: typeof selfMerge.offer === 'boolean' ? selfMerge.offer : DEFAULT_SETTINGS.selfMerge.offer,
+      approvalMinutes: isMinutes(selfMerge.approvalMinutes)
+        ? selfMerge.approvalMinutes
+        : DEFAULT_SETTINGS.selfMerge.approvalMinutes,
+    },
+  }
+}

package/kit/hooks/hooks/merge-guard/worker.ts

@@ -0,0 +1,14 @@
+// Runs the decision off the main thread, so index.ts can end it when it takes too long.
+import { decideInput, failureDecision } from './run'
+
+type Job = { text: string; label: string; projectDirectory: string }
+
+declare const self: Worker
+
+self.onmessage = ({ data }: MessageEvent<Job>) => {
+  try {
+    self.postMessage(decideInput(data.text, data.label, data.projectDirectory))
+  } catch (error) {
+    self.postMessage(failureDecision(error))
+  }
+}

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

@@ -0,0 +1,82 @@
+import { posix } from 'node:path'
+import type { SimpleCommand, Word } from './shell'
+
+/**
+ * Words Claude Code strips before it matches a Bash rule, so they do not hide the command. Its
+ * permission matching also reaches into control-flow bodies, which the reserved words open.
+ */
+const RULE_TRANSPARENT_WRAPPERS = new Set(['time', 'nohup', 'nice', 'command', 'builtin', 'noglob'])
+const RESERVED_WORDS = new Set(['!', '{', '}', 'if', 'then', 'elif', 'else', 'fi', 'do', 'done', 'while', 'until'])
+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]*$/
+
+/** 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,
+  'env',
+  'sudo',
+  'doas',
+  'exec',
+  'xargs',
+  'timeout',
+  'stdbuf',
+  'setsid',
+  'watch',
+])
+
+const transparentWidth = (words: SimpleCommand, index: number): number => {
+  const { value, literal } = words[index]
+  if (ASSIGNMENT.test(value)) return 1
+  if (!literal) return 0
+  if (RESERVED_WORDS.has(value) || RULE_TRANSPARENT_WRAPPERS.has(value)) return 1
+  return value === 'timeout' && DURATION.test(words[index + 1]?.value ?? '') ? 2 : 0
+}
+
+/** The index of the word a permission rule compares against: past assignments and stripped wrappers. */
+export const ruleStart = (words: SimpleCommand): number => {
+  let index = 0
+  while (index < words.length) {
+    const width = transparentWidth(words, index)
+    if (width === 0) break
+    index += width
+  }
+  return index
+}
+
+/** The program a word names, as a case-insensitive file system would find it. */
+export const programName = (word: Word): string =>
+  posix
+    .basename(word.value.replace(/^=/, ''))
+    .toLowerCase()
+    .replace(/\.exe$/, '')
+
+/** At the rule start, or anywhere after a runner such as `sudo -u me` or `env FOO=1`: the program runs there. */
+export const isProgramPosition = (words: SimpleCommand, index: number): boolean =>
+  index === ruleStart(words) || words.slice(0, index).some((word) => COMMAND_RUNNERS.has(programName(word)))
+
+export const isOption = (word: Word | undefined): boolean => word?.value.startsWith('-') ?? false
+
+export const isShell = (word: Word): boolean => SHELLS.has(programName(word))
+
+/** The script word after `-c`: the first one that is neither an option nor `--`. */
+const shellCommandScript = (words: SimpleCommand, shellIndex: number): string | undefined => {
+  const flag = words.findIndex((word, position) => position > shellIndex && SHELL_COMMAND_FLAG.test(word.value))
+  if (flag === -1) return undefined
+  return words.slice(flag + 1).find((word) => !isOption(word))?.value
+}
+
+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
+}
+
+/** 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/watch-guard/shell-input.ts

@@ -1,4 +1,4 @@
-import { parseShell } from '../git-guard/shell'
+import { parseShell } from '../shared/shell'
 
 /** Programs that run their `-c` argument as a command line; the names of shells among them also read stdin as a script. */
 export const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh', 'fish'])

package/kit/hooks/hooks/watch-guard/starts.ts

@@ -1,5 +1,5 @@
 import { basename } from 'node:path'
-import { parseShell } from '../git-guard/shell'
+import { parseShell } from '../shared/shell'
 import { hasBackgroundJob } from './background'
 import { SHELLS, shellHeredocBodies, shellHereStrings, withoutHeredocBodies } from './shell-input'
 

package/kit/hooks/hooks.json

@@ -1,4 +1,12 @@
 {
+  "ask-hint": {
+    "event": "Stop",
+    "handler": {
+      "type": "command",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/ask-hint/index.ts",
+      "timeout": 10
+    }
+  },
   "format-on-edit": {
     "event": "PostToolUse",
     "matcher": "Edit|Write",
@@ -18,6 +26,16 @@
       "onFailure": "block"
     }
   },
+  "merge-guard": {
+    "event": "PreToolUse",
+    "matcher": "Bash",
+    "handler": {
+      "type": "command",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/merge-guard/index.ts '{{kit.guard.selfMergeLabel}}' || exit 2",
+      "timeout": 10,
+      "onFailure": "block"
+    }
+  },
   "watch-guard": {
     "event": "PreToolUse",
     "matcher": "Bash",