jackherd 1.6.0 → 1.7.0

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

@@ -1,74 +1,19 @@
 /**
- * What the user approved, read from the session transcript. The transcript is written by Claude Code,
- * not by the agent: a dialog answer sits in it as the tool result of an `AskUserQuestion` call, with
- * the question the agent put and the label the user picked. Nothing an agent says in a message,
- * a file or a command counts, so a text cannot stand in for the click.
+ * What the user approved, read from the session transcript through `dialogAnswers`: a dialog answer sits in it as the
+ * tool result of an `AskUserQuestion` call, with the question the agent put and the label the user picked. Nothing an
+ * agent says in a message, a file or a command counts, so a text cannot stand in for the click.
  *
  * The limit: an agent that runs as the user could still write to the transcript file. This guards
  * against a mistake, not against an agent that sets out to get around it.
  */
+import { type DialogAnswer, dialogAnswers } from '../shared/dialog-answers'
+import { isFresh } from '../shared/fresh'
 
-type Record_ = Record<string, unknown>
-
-const MS_PER_MINUTE = 60_000
 const BRANCH_MENTION = /\bBranch `([^`]*)`/g
 
 /** A branch name as git takes it from a shell word: no leading dash, no space, no `..`, no shell character. */
 const BRANCH_NAME = /^(?![-/.])(?!.*(?:\.\.|\/\/|@\{))[A-Za-z0-9._/-]+$/
 
-const isRecord = (value: unknown): value is Record_ => typeof value === 'object' && value !== null && !Array.isArray(value)
-
-const contentOf = (entry: Record_): Record_[] => {
-  const content = isRecord(entry.message) ? entry.message.content : undefined
-  return Array.isArray(content) ? content.filter(isRecord) : []
-}
-
-const isMainThread = (entry: Record_): boolean => entry.isSidechain !== true
-
-/** One JSON value per line; a line that is not JSON is skipped. */
-export const parseTranscript = (text: string): unknown[] =>
-  text.split('\n').flatMap((line) => {
-    try {
-      return line.trim() === '' ? [] : [JSON.parse(line)]
-    } catch {
-      return []
-    }
-  })
-
-/** Whether the question offers `label` as one option among single choices: a multi-select joins its picks into one text. */
-const offersLabel = (question: Record_, label: string): boolean =>
-  question.multiSelect !== true &&
-  Array.isArray(question.options) &&
-  question.options.some((option) => isRecord(option) && option.label === label)
-
-const questionTexts = (input: unknown, label: string): string[] => {
-  if (!isRecord(input) || 'answers' in input || !Array.isArray(input.questions)) return []
-  return input.questions.flatMap((question) =>
-    isRecord(question) && typeof question.question === 'string' && offersLabel(question, label)
-      ? [question.question]
-      : [],
-  )
-}
-
-/**
- * The questions of each `AskUserQuestion` call that offer `label`, by tool use id. A call that carries its own
- * `answers` asked nobody.
- */
-const askedQuestions = (entries: Record_[], label: string): Map<string, string[]> =>
-  new Map(
-    entries
-      .filter(isMainThread)
-      .flatMap(contentOf)
-      .filter((block) => block.type === 'tool_use' && block.name === 'AskUserQuestion' && typeof block.id === 'string')
-      .map((block): [string, string[]] => [block.id as string, questionTexts(block.input, label)]),
-  )
-
-const isFresh = (timestamp: unknown, now: number, windowMinutes: number): boolean => {
-  const answeredAt = typeof timestamp === 'string' ? Date.parse(timestamp) : Number.NaN
-  const age = now - answeredAt
-  return age >= 0 && age <= windowMinutes * MS_PER_MINUTE
-}
-
 /** The one branch a question names as ``Branch `name` ``; a question that names none or several approves none. */
 const namedBranch = (question: string): string | undefined => {
   const names = new Set([...question.matchAll(BRANCH_MENTION)].map(([, name]) => name))
@@ -76,16 +21,7 @@ const namedBranch = (question: string): string | undefined => {
   return names.size === 1 && BRANCH_NAME.test(only) ? only : undefined
 }
 
-/** The branches one result entry approves: the questions of its `AskUserQuestion` call that the user answered with `label`. */
-const branchesApprovedIn = (entry: Record_, asked: Map<string, string[]>, label: string): string[] => {
-  const answers = isRecord(entry.toolUseResult) ? entry.toolUseResult.answers : undefined
-  if (!isRecord(answers)) return []
-  return contentOf(entry)
-    .filter((block) => block.type === 'tool_result')
-    .flatMap((block) => asked.get(String(block.tool_use_id)) ?? [])
-    .filter((question) => answers[question] === label)
-    .flatMap((question) => namedBranch(question) ?? [])
-}
+const approves = (answer: DialogAnswer, label: string): boolean => answer.answer === label && answer.offered.includes(label)
 
 export type ApprovalQuery = {
   entries: unknown[]
@@ -100,8 +36,9 @@ export type ApprovalQuery = {
 /** The branches whose question the user answered with `label` within the window. */
 export const approvedBranches = ({ entries, label, now, windowMinutes }: ApprovalQuery): Set<string> => {
   if (label === '') return new Set()
-  const records = entries.filter(isRecord)
-  const asked = askedQuestions(records, label)
-  const fresh = records.filter((entry) => isMainThread(entry) && isFresh(entry.timestamp, now, windowMinutes))
-  return new Set(fresh.flatMap((entry) => branchesApprovedIn(entry, asked, label)))
+  return new Set(
+    dialogAnswers(entries)
+      .filter((answer) => approves(answer, label) && isFresh(answer.answeredAt, now, windowMinutes))
+      .flatMap((answer) => namedBranch(answer.question) ?? []),
+  )
 }

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

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs'
 import { isAbsolute, relative } from 'node:path'
-import { approvedBranches, parseTranscript } from './approval'
+import { parseTranscript } from '../shared/dialog-answers'
+import { approvedBranches } from './approval'
 import { allFilesMatch, changedFilesOf } from './check-free'
 import { decideBashCommand, type GuardPolicy, type MergeGuardDecision } from './decision'
 import { parseHeadBranch, parseRepositoryFacts, type RepositoryFacts, viewPullRequest } from './pull-request'

package/kit/hooks/hooks/model-gate/agent-definition.ts

@@ -0,0 +1,13 @@
+// Claude Code's agent definitions: a Markdown file per agent whose frontmatter may fix its `model`.
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/
+const FRONTMATTER_MODEL = /^model:\s*['"]?([^'"\s#]+)['"]?\s*$/m
+/** An agent name that is one plain file name: lower-case letters, digits and dashes. */
+const AGENT_NAME = /^[a-z0-9-]+$/
+
+export const isAgentName = (name: string): boolean => AGENT_NAME.test(name)
+
+/** The `model` of an agent definition's frontmatter; null without one. */
+export const frontmatterModel = (definition: string): string | null => {
+  const frontmatter = FRONTMATTER.exec(definition)?.[1]
+  return frontmatter ? (FRONTMATTER_MODEL.exec(frontmatter)?.[1] ?? null) : null
+}

package/kit/hooks/hooks/model-gate/index.ts

@@ -0,0 +1,58 @@
+// PreToolUse hook of Claude Code for the Agent tool, shipped by jackherd: the client adapter of the model gate. Before an
+// implementing subagent starts, it compares the call's model (else the agent definition's) with the plan's
+// recommendation for the phase the prompt names: a weaker model is denied with the recommendation, a stronger one gets
+// a note. Anything else, and any failure, answers nothing, so the call runs.
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { projectAndHomeConfigs, repositoryRootOf } from '../shared/checkout'
+import { readTextOrNull, realPathOrNull } from '../shared/files'
+import { isRecord } from '../shared/json'
+import { frontmatterModel, isAgentName } from './agent-definition'
+import { MODEL_GATE, type ModelGateDependencies, type ModelGateOutcome, runModelGate, type SubagentCall } from './run'
+
+const HOOK_EVENT = 'PreToolUse'
+
+/** Claude Code's agent definitions: the project's `.claude/agents/<name>.md`, then the home directory's. */
+const agentModel = (root: string, agentType: string): string | null =>
+  [join(root, '.claude', 'agents'), join(homedir(), '.claude', 'agents')]
+    .map((directory) => readTextOrNull(join(directory, `${agentType}.md`)))
+    .map((definition) => (definition === null ? null : frontmatterModel(definition)))
+    .find((model) => model !== null) ?? null
+
+const dependencies: ModelGateDependencies = {
+  repositoryRootOf,
+  configs: projectAndHomeConfigs,
+  realPath: realPathOrNull,
+  readText: readTextOrNull,
+  agentModel,
+}
+
+/** Claude Code's hook input: `cwd` and the Agent tool's `subagent_type`, `model` and `prompt`. */
+const subagentCallOf = (text: string): SubagentCall | null => {
+  const input: unknown = JSON.parse(text)
+  if (!isRecord(input) || typeof input.cwd !== 'string' || !isRecord(input.tool_input)) return null
+  const { subagent_type: agentType, model, prompt } = input.tool_input
+  if (typeof agentType !== 'string' || !isAgentName(agentType) || typeof prompt !== 'string') return null
+  return { cwd: input.cwd, agentType, model: typeof model === 'string' && model !== '' ? model : null, prompt }
+}
+
+const decide = async (): Promise<ModelGateOutcome | null> => {
+  try {
+    const call = subagentCallOf(await Bun.stdin.text())
+    return call ? runModelGate(call, dependencies) : null
+  } catch {
+    return null
+  }
+}
+
+const hookOutput = (outcome: ModelGateOutcome): Record<string, unknown> | null => {
+  if (outcome.kind === MODEL_GATE.deny)
+    return { hookEventName: HOOK_EVENT, permissionDecision: 'deny', permissionDecisionReason: outcome.reason }
+  if (outcome.kind === MODEL_GATE.note) return { hookEventName: HOOK_EVENT, additionalContext: outcome.context }
+  return null
+}
+
+const outcome = await decide()
+const output = outcome ? hookOutput(outcome) : null
+if (output) console.log(JSON.stringify({ hookSpecificOutput: output }))
+process.exit(0)

package/kit/hooks/hooks/model-gate/run.ts

@@ -0,0 +1,63 @@
+import { compareModels, familyOf, rankedFamiliesIn, MODEL_COMPARISON, type ModelComparison } from '../shared/model-family'
+import { type PhaseRecommendation, type PlanFiles, phaseRecommendation, subagentSettingsOf } from '../shared/subagent-phase'
+
+/** A subagent's start as the client hands it over: its directory, agent, model (null when the call names none) and prompt. */
+export type SubagentCall = { cwd: string; agentType: string; model: string | null; prompt: string }
+
+export const MODEL_GATE = { pass: 'pass', deny: 'deny', note: 'note' } as const
+
+export type ModelGateOutcome =
+  | { kind: typeof MODEL_GATE.pass }
+  | { kind: typeof MODEL_GATE.deny; reason: string }
+  | { kind: typeof MODEL_GATE.note; context: string }
+
+/** Everything with a side effect, passed in so a test reaches the flow without git, files or a home directory. */
+export type ModelGateDependencies = PlanFiles & {
+  repositoryRootOf: (cwd: string) => string
+  /** The parsed configs, the project's first, then the home directory's. */
+  configs: (root: string) => Record<string, unknown>[]
+  /** The `model` of the agent's definition, the project's before the home directory's; null without one. */
+  agentModel: (root: string, agentType: string) => string | null
+}
+
+const PASS: ModelGateOutcome = { kind: MODEL_GATE.pass }
+
+/** The situation in families only: the plan's cell and the call's model are text a lane wrote, never quoted. */
+const situation = ({ phase, plan, cell }: PhaseRecommendation, agentType: string, model: string): string =>
+  `Phase P${phase} of ${plan} recommends ${rankedFamiliesIn(cell ?? '').join(' or ')}, and this call starts ${agentType} on ${familyOf(model)}`
+
+/** Deny below the recommendation, a note above it, nothing within it or when either side names no family. */
+const outcomeOf = (comparison: ModelComparison, situationText: string): ModelGateOutcome => {
+  if (comparison.kind === MODEL_COMPARISON.weaker)
+    return { kind: MODEL_GATE.deny, reason: `${situationText}. Start it again with model: "${comparison.recommended}".` }
+  if (comparison.kind === MODEL_COMPARISON.stronger)
+    return {
+      kind: MODEL_GATE.note,
+      context: `${situationText}, a stronger model. Start it with model: "${comparison.recommended}" unless the stronger one is intended.`,
+    }
+  return PASS
+}
+
+const gate = (call: SubagentCall, dependencies: ModelGateDependencies): ModelGateOutcome => {
+  const root = dependencies.repositoryRootOf(call.cwd)
+  const settings = subagentSettingsOf(dependencies.configs(root))
+  if (!settings.agentNames.includes(call.agentType)) return PASS
+  const found = phaseRecommendation(root, call.prompt, settings.planDirectory, dependencies)
+  const model = call.model ?? dependencies.agentModel(root, call.agentType)
+  if (!found?.cell || !model) return PASS
+  return outcomeOf(compareModels(found.cell, model), situation(found, call.agentType, model))
+}
+
+/**
+ * The model gate for the start of an implementing subagent: the phase its prompt names (`Phase P<n>`), that phase's
+ * row in the model table of the plan the prompt names, and the model of the call, else of the agent definition.
+ * A weaker model is denied with the recommendation, a stronger one passes with a note. Without a phase, a plan, a
+ * row or a model, and on any failure, the call passes: the gate never raises a false alarm.
+ */
+export const runModelGate = (call: SubagentCall, dependencies: ModelGateDependencies): ModelGateOutcome => {
+  try {
+    return gate(call, dependencies)
+  } catch {
+    return PASS
+  }
+}

package/kit/hooks/hooks/model-log/index.ts

@@ -0,0 +1,60 @@
+// SubagentStop hook of Claude Code, shipped by jackherd: the client adapter of the model log. When an implementing
+// subagent ends, it records the model of its last answer against the phase and plan its prompt names, in
+// `.jackherd/models/` of the main checkout, for the herd. It prints nothing and never blocks.
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs'
+import { mainCheckoutOf, projectAndHomeConfigs, repositoryRootOf } from '../shared/checkout'
+import { readTextOrNull, realPathOrNull } from '../shared/files'
+import { isRecord } from '../shared/json'
+import { type ModelLogDependencies, runModelLog, type SubagentStop, type TranscriptEnds } from './run'
+import { writeRecord } from './store'
+
+/** The prompt is the transcript's first line; one long prompt still fits. */
+const HEAD_BYTES = 1024 * 1024
+/** The last answers lie at the end; a long run's transcript grows to many megabytes. */
+const TAIL_BYTES = 4 * 1024 * 1024
+
+/** The first and the last bytes of the transcript; a cut line at either edge is skipped by the parser. */
+const readTranscript = (path: string): TranscriptEnds => {
+  const descriptor = openSync(path, 'r')
+  try {
+    const size = fstatSync(descriptor).size
+    const read = (length: number, position: number): string => {
+      const buffer = Buffer.alloc(length)
+      readSync(descriptor, buffer, 0, length, position)
+      return buffer.toString('utf8')
+    }
+    const tailLength = Math.min(size, TAIL_BYTES)
+    return { head: read(Math.min(size, HEAD_BYTES), 0), tail: read(tailLength, size - tailLength) }
+  } finally {
+    closeSync(descriptor)
+  }
+}
+
+const dependencies: ModelLogDependencies = {
+  repositoryRootOf,
+  mainCheckoutOf,
+  configs: projectAndHomeConfigs,
+  realPath: realPathOrNull,
+  readText: readTextOrNull,
+  readTranscript,
+  writeRecord,
+  now: () => Date.now(),
+}
+
+/** Claude Code's hook input: `cwd`, `agent_type` and `agent_transcript_path`. */
+const subagentStopOf = (text: string): SubagentStop | null => {
+  const input: unknown = JSON.parse(text)
+  if (!isRecord(input)) return null
+  const { cwd, agent_type: agentType, agent_transcript_path: transcriptPath } = input
+  return typeof cwd === 'string' && typeof agentType === 'string' && typeof transcriptPath === 'string'
+    ? { cwd, agentType, transcriptPath }
+    : null
+}
+
+try {
+  const stop = subagentStopOf(await Bun.stdin.text())
+  if (stop) runModelLog(stop, dependencies)
+} catch {
+  // Unreadable input records nothing.
+}
+process.exit(0)

package/kit/hooks/hooks/model-log/run.ts

@@ -0,0 +1,57 @@
+import { compareModels, MODEL_COMPARISON } from '../shared/model-family'
+import { type PlanFiles, phaseRecommendation, subagentSettingsOf } from '../shared/subagent-phase'
+import type { PhaseModelRecord } from './store'
+import { lastModelOf, promptOf } from './transcript'
+
+/** A subagent's end as the client hands it over: the session's directory, the agent and its transcript. */
+export type SubagentStop = { cwd: string; agentType: string; transcriptPath: string }
+
+/** A transcript's start, where the prompt is, and its end, where the last answer is. */
+export type TranscriptEnds = { head: string; tail: string }
+
+/** Everything with a side effect, passed in so a test reaches the flow without git, files or a clock. */
+export type ModelLogDependencies = PlanFiles & {
+  repositoryRootOf: (cwd: string) => string
+  mainCheckoutOf: (cwd: string) => string
+  /** The parsed configs, the project's first, then the home directory's. */
+  configs: (root: string) => Record<string, unknown>[]
+  readTranscript: (path: string) => TranscriptEnds
+  writeRecord: (main: string, record: PhaseModelRecord) => void
+  now: () => number
+}
+
+const recordOf = (stop: SubagentStop, dependencies: ModelLogDependencies): PhaseModelRecord | null => {
+  const root = dependencies.repositoryRootOf(stop.cwd)
+  const settings = subagentSettingsOf(dependencies.configs(root))
+  if (!settings.agentNames.includes(stop.agentType)) return null
+  const { head, tail } = dependencies.readTranscript(stop.transcriptPath)
+  const prompt = promptOf(head)
+  const answered = lastModelOf(tail)
+  const found = prompt ? phaseRecommendation(root, prompt, settings.planDirectory, dependencies) : null
+  if (!found || !answered) return null
+  const comparison = found.cell ? compareModels(found.cell, answered.model) : null
+  const known = comparison && comparison.kind !== MODEL_COMPARISON.unknown ? comparison : null
+  return {
+    plan: found.plan,
+    phase: found.phase,
+    model: answered.model,
+    used: answered.family,
+    recommended: known?.recommended ?? null,
+    fits: known ? known.kind === MODEL_COMPARISON.fits : null,
+    at: dependencies.now(),
+  }
+}
+
+/**
+ * Records the model an implementing subagent ran on against the phase and plan its prompt names, in the main checkout,
+ * for the herd. Records nothing for another agent, a prompt without phase or plan, or a transcript without a model,
+ * and nothing on any failure: the log never stands in the agent's way.
+ */
+export const runModelLog = (stop: SubagentStop, dependencies: ModelLogDependencies): void => {
+  try {
+    const record = recordOf(stop, dependencies)
+    if (record) dependencies.writeRecord(dependencies.mainCheckoutOf(stop.cwd), record)
+  } catch {
+    // A failed record is no record; the herd shows the phase without its model.
+  }
+}

package/kit/hooks/hooks/model-log/store.ts

@@ -0,0 +1,40 @@
+import { createHash } from 'node:crypto'
+import { chmodSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ModelFamily } from '../shared/model-family'
+import { ensurePrivateDirectory, PRIVATE_FILE } from '../shared/private-directory'
+
+/**
+ * The model an implementing subagent of a phase ran on: the plan (from the repository root, `/`-separated), the phase,
+ * the model id of its last answer and its family, the family the plan recommends with whether the model fits it (both
+ * null when the plan's row names none), and when it ended.
+ */
+export type PhaseModelRecord = {
+  plan: string
+  phase: string
+  model: string
+  used: ModelFamily
+  recommended: ModelFamily | null
+  fits: boolean | null
+  at: number
+}
+
+const KEY_LENGTH = 16
+
+/** Where the records lie: in the main checkout beside `.jackherd/approvals`, which the herd reads. Ignored by git. */
+export const modelsDirectory = (main: string): string => join(main, '.jackherd', 'models')
+
+/** One file per plan and phase, so a later run of the phase replaces the record of the earlier one. */
+const recordFileName = ({ plan, phase }: Pick<PhaseModelRecord, 'plan' | 'phase'>): string =>
+  `${createHash('sha256').update(`${plan}\n${phase}`).digest('hex').slice(0, KEY_LENGTH)}.json`
+
+/** Writes the record through a temporary file, so a reader never sees half of it. */
+export const writeRecord = (main: string, record: PhaseModelRecord): void => {
+  const directory = modelsDirectory(main)
+  ensurePrivateDirectory(directory)
+  const path = join(directory, recordFileName(record))
+  const temporary = `${path}.${process.pid}.tmp`
+  writeFileSync(temporary, `${JSON.stringify(record)}\n`, { mode: PRIVATE_FILE })
+  chmodSync(temporary, PRIVATE_FILE)
+  renameSync(temporary, path)
+}

package/kit/hooks/hooks/model-log/transcript.ts

@@ -0,0 +1,37 @@
+import { parseTranscript } from '../shared/dialog-answers'
+import { isRecord, type JsonObject } from '../shared/json'
+import { familyOf, type ModelFamily } from '../shared/model-family'
+
+const USER_ENTRY = 'user'
+const ASSISTANT_ENTRY = 'assistant'
+const TEXT_BLOCK = 'text'
+
+const messageOf = (entry: unknown): JsonObject | null =>
+  isRecord(entry) && isRecord(entry.message) ? entry.message : null
+
+const textOf = (content: unknown): string | null => {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return null
+  const texts = content.flatMap((block) =>
+    isRecord(block) && block.type === TEXT_BLOCK && typeof block.text === 'string' ? [block.text] : [],
+  )
+  return texts.length > 0 ? texts.join('\n') : null
+}
+
+/** The subagent's prompt: the text of the first user entry of its transcript; null without one. */
+export const promptOf = (head: string): string | null => {
+  const first = parseTranscript(head).find((entry) => isRecord(entry) && entry.type === USER_ENTRY)
+  return textOf(messageOf(first)?.content)
+}
+
+/** A model id with its family. */
+export type AnsweredModel = { model: string; family: ModelFamily }
+
+const answeredModel = (entry: unknown): AnsweredModel[] => {
+  const model = isRecord(entry) && entry.type === ASSISTANT_ENTRY ? messageOf(entry)?.model : undefined
+  const family = typeof model === 'string' ? familyOf(model) : null
+  return typeof model === 'string' && family ? [{ model, family }] : []
+}
+
+/** The model of the last answer that names a model family (`<synthetic>` names none); null without one. */
+export const lastModelOf = (tail: string): AnsweredModel | null => parseTranscript(tail).flatMap(answeredModel).at(-1) ?? null

package/kit/hooks/hooks/shared/checkout.ts

@@ -0,0 +1,22 @@
+import { homedir } from 'node:os'
+import { basename, dirname } from 'node:path'
+import { commandOutput } from './command'
+import { readConfig } from './config'
+
+const gitOutput = (cwd: string, ...args: string[]): string => commandOutput(['git', ...args], cwd)
+
+/** The main checkout: the directory that holds the repository's common git directory. Throws outside a repository. */
+export const mainCheckoutOf = (cwd: string): string => {
+  const common = gitOutput(cwd, 'rev-parse', '--path-format=absolute', '--git-common-dir')
+  if (basename(common) !== '.git') throw new Error('no main checkout')
+  return dirname(common)
+}
+
+/** The top of the checkout `cwd` lies in, a worktree's own top for a worktree. Throws outside a repository. */
+export const repositoryRootOf = (cwd: string): string => gitOutput(cwd, 'rev-parse', '--show-toplevel')
+
+/** The parsed configs of the main checkout and of the home directory, in that order: a lane's worktree has no say. */
+export const projectAndHomeConfigs = (root: string): Record<string, unknown>[] => [
+  readConfig([mainCheckoutOf(root)]),
+  readConfig([homedir()]),
+]

package/kit/hooks/hooks/shared/command.ts

@@ -0,0 +1,6 @@
+/** The trimmed stdout of a command run without a shell; throws when it fails, so the caller gives up. */
+export const commandOutput = (command: string[], cwd?: string): string => {
+  const result = Bun.spawnSync(command, { cwd, stdout: 'pipe', stderr: 'ignore' })
+  if (result.exitCode !== 0) throw new Error(`${command[0]} failed`)
+  return result.stdout.toString().trim()
+}

package/kit/hooks/hooks/shared/config.ts

@@ -0,0 +1,21 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { isRecord } from './json'
+
+const CONFIG_PATH = join('.jackherd', 'config.json')
+
+/** The first `.jackherd/config.json` of the directories that exists, as an object; `{}` when none or unreadable. A hook has no schema library, `jh` validates the file. */
+export const readConfig = (directories: readonly 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) ? config : {}
+  } catch {
+    return {}
+  }
+}
+
+/** The object under `key`, `{}` when it is missing or no object. */
+export const sectionOf = (config: Record<string, unknown>, key: string): Record<string, unknown> =>
+  isRecord(config[key]) ? config[key] : {}

package/kit/hooks/hooks/shared/dialog-answer.ts

@@ -0,0 +1,5 @@
+/**
+ * One question the user answered in a dialog, whatever client wrote it down. `offered` holds the labels of a
+ * single-choice question; a multi-select joins its picks into one text and offers none.
+ */
+export type DialogAnswer = { question: string; answer: string; offered: string[]; answeredAt: number }

package/kit/hooks/hooks/shared/dialog-answers.ts

@@ -0,0 +1,74 @@
+import type { DialogAnswer } from './dialog-answer'
+import { isRecord, type JsonObject } from './json'
+
+export type { DialogAnswer } from './dialog-answer'
+
+/**
+ * The answers of the user's dialogs, read from a session transcript. The transcript is written by the agent's own
+ * client, not by the agent: a dialog answer sits in it as the result of an `AskUserQuestion` call, with the question the
+ * agent put and the label the user picked. Nothing an agent says in a message, a file or a command is one.
+ */
+
+const contentOf = (entry: JsonObject): JsonObject[] => {
+  const content = isRecord(entry.message) ? entry.message.content : undefined
+  return Array.isArray(content) ? content.filter(isRecord) : []
+}
+
+const isMainThread = (entry: JsonObject): boolean => entry.isSidechain !== true
+
+/** One JSON value per line; a line that is not JSON is skipped. */
+export const parseTranscript = (text: string): unknown[] =>
+  text.split('\n').flatMap((line) => {
+    try {
+      return line.trim() === '' ? [] : [JSON.parse(line)]
+    } catch {
+      return []
+    }
+  })
+
+const offeredLabels = (question: JsonObject): string[] =>
+  question.multiSelect !== true && Array.isArray(question.options)
+    ? question.options.flatMap((option) => (isRecord(option) && typeof option.label === 'string' ? [option.label] : []))
+    : []
+
+type AskedQuestion = { question: string; offered: string[] }
+
+/** The questions of an `AskUserQuestion` input; a call that carries its own `answers` asked nobody. */
+const questionsOf = (input: unknown): AskedQuestion[] => {
+  if (!isRecord(input) || 'answers' in input || !Array.isArray(input.questions)) return []
+  return input.questions.flatMap((question) =>
+    isRecord(question) && typeof question.question === 'string'
+      ? [{ question: question.question, offered: offeredLabels(question) }]
+      : [],
+  )
+}
+
+/** The questions of each `AskUserQuestion` call of the main thread, by tool use id. */
+const askedQuestions = (entries: JsonObject[]): Map<string, AskedQuestion[]> =>
+  new Map(
+    entries
+      .filter(isMainThread)
+      .flatMap(contentOf)
+      .filter((block) => block.type === 'tool_use' && block.name === 'AskUserQuestion' && typeof block.id === 'string')
+      .map((block): [string, AskedQuestion[]] => [block.id as string, questionsOf(block.input)]),
+  )
+
+const answersIn = (entry: JsonObject, asked: Map<string, AskedQuestion[]>): DialogAnswer[] => {
+  const answers = isRecord(entry.toolUseResult) ? entry.toolUseResult.answers : undefined
+  const answeredAt = typeof entry.timestamp === 'string' ? Date.parse(entry.timestamp) : Number.NaN
+  if (!isRecord(answers) || Number.isNaN(answeredAt)) return []
+  return contentOf(entry)
+    .filter((block) => block.type === 'tool_result')
+    .flatMap((block) => asked.get(String(block.tool_use_id)) ?? [])
+    .flatMap(({ question, offered }) => {
+      const answer = answers[question]
+      return typeof answer === 'string' ? [{ question, answer, offered, answeredAt }] : []
+    })
+}
+
+/** Every question of the main thread the user answered in a dialog, in transcript order. */
+export const dialogAnswers = (entries: readonly unknown[]): DialogAnswer[] => {
+  const records = entries.filter(isRecord)
+  const asked = askedQuestions(records)
+  return records.filter(isMainThread).flatMap((entry) => answersIn(entry, asked))
+}

package/kit/hooks/hooks/shared/files.ts

@@ -0,0 +1,19 @@
+import { readFileSync, realpathSync } from 'node:fs'
+
+/** The file's text; null when it cannot be read. */
+export const readTextOrNull = (path: string): string | null => {
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+/** Where the path resolves with every link followed; null when it does not exist. */
+export const realPathOrNull = (path: string): string | null => {
+  try {
+    return realpathSync(path)
+  } catch {
+    return null
+  }
+}

package/kit/hooks/hooks/shared/fresh.ts

@@ -0,0 +1,4 @@
+export const MS_PER_MINUTE = 60_000
+
+/** Whether a moment lies within the last `minutes` before `now`; one from the future never does. */
+export const isFresh = (at: number, now: number, minutes: number): boolean => at <= now && now - at <= minutes * MS_PER_MINUTE

package/kit/hooks/hooks/shared/json.ts

@@ -0,0 +1,4 @@
+export type JsonObject = Record<string, unknown>
+
+export const isRecord = (value: unknown): value is JsonObject =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)