jackherd 1.8.1 → 1.10.0

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

@@ -1,17 +1,15 @@
 import { readFileSync } from 'node:fs'
-import { isAbsolute, relative } from 'node:path'
 import { mainCheckoutOf } from '../shared/checkout'
-import { parseTranscript } from '../shared/dialog-answers'
-import { isCoordinatorAgent } from '../shared/lane'
+import { dialogAnswers, parseTranscript } from '../shared/dialog-answers'
+import { isWithinDirectory } from '../shared/files'
 import { once } from '../shared/once'
-import { ownPaneAgent } from '../shared/own-pane'
 import { readShellDefinitions } from '../shared/shell-snapshots'
+import { ALWAYS_ASK_PATHS } from './always-ask'
 import { approvedBranches } from './approval'
-import { allFilesMatch, changedFilesOf } from './check-free'
+import { boardSettingsOf } from './board-settings'
+import { changedFilesOf, isCheckFree } from './check-free'
 import { decideBashCommand, type GuardPolicy, type MergeGuardDecision, type MergeNote, type PlainMerge } from './decision'
-import { isPlanApproved, type PlanVerdict } from './plan-approval'
-import { isLaneIn, planApprovalSources, planBaseOf } from './plan-approval-sources'
-import { planPointersDirectory, readPointers } from './plan-pointers'
+import { planOfBranch } from './lane-plan'
 import {
   checksPassed,
   parseBaseBranch,
@@ -20,12 +18,13 @@ import {
   parseRepositoryFacts,
   viewPullRequest,
 } from './pull-request'
-import { type GuardSettings, readGuardSettings } from './settings'
+import { type GuardSettings, readConfigOrNull, readGuardSettings } from './settings'
+import { standingVerdict, type StandingLabels, standingGrants } from './standing-approval'
 
-type HookInput = { tool_input?: { command?: unknown }; transcript_path?: unknown; cwd?: unknown; session_id?: unknown }
+type HookInput = { tool_input?: { command?: unknown }; transcript_path?: unknown; cwd?: unknown }
 
-/** The exact option labels that approve a merge: the one of the pull request question and the one of a plan question. */
-export type ApprovalLabels = { selfMerge: string; plan: string }
+/** The exact option labels that approve a merge: the one of the pull request question and those of the standing approval. */
+export type ApprovalLabels = { selfMerge: string; standing: StandingLabels }
 
 /** What GitHub says about the pull request a merge names; `files` is asked only when a rule needs it. */
 type MergeFacts = {
@@ -37,44 +36,43 @@ type MergeFacts = {
   files: () => readonly string[] | undefined
 }
 
-type PlanApproval = (facts: MergeFacts & { headCommit: string }) => PlanVerdict
+type StandingApproval = (facts: MergeFacts) => boolean | MergeNote
 
 /** The ways a merge may pass without a question. */
-type MergeApprovals = { branches: ReadonlySet<string>; withoutChecks: readonly string[]; plan: PlanApproval | undefined }
+type MergeApprovals = {
+  branches: ReadonlySet<string>
+  withoutChecks: readonly string[]
+  /** The paths that always ask, which a `withoutChecks` pattern never opens. */
+  alwaysAsk: readonly string[]
+  standing: StandingApproval | undefined
+}
 
 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,
-  })
-}
+/** The transcript of the session that merges, one parsed entry per line; none without one. */
+const transcriptEntries = (transcriptPath: unknown): unknown[] =>
+  typeof transcriptPath === 'string' ? parseTranscript(readFileSync(transcriptPath, 'utf8')) : []
 
-/** 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 approvedBranchesFrom = (entries: unknown[], settings: GuardSettings, label: string): Set<string> => {
+  if (!settings.selfMerge.offer) return new Set()
+  return approvedBranches({ entries, label, now: Date.now(), windowMinutes: settings.selfMerge.approvalMinutes })
 }
 
 /**
- * The user approved the branch and its checks passed, every file needs no checks, or the user approved the plan of the
- * branch's lane; each only for a merge bound to the head commit GitHub reports, so a push after the check is not
- * merged unchecked. A plan approval that no longer covers the plan answers with a note for the question.
+ * The user approved the branch and its checks passed, every file needs no checks, or a standing approval covers the
+ * plan of the branch's lane; each only for a merge bound to the head commit GitHub reports, so a push after the check
+ * is not merged unchecked. A standing approval that does not cover a file answers with a note for the question.
  */
 const approvesMerge = (
-  { branches, withoutChecks, plan }: MergeApprovals,
+  { branches, withoutChecks, alwaysAsk, standing }: MergeApprovals,
   merge: PlainMerge,
   facts: MergeFacts,
 ): boolean | MergeNote => {
   const { headCommit } = facts
   if (headCommit === undefined || merge.headCommit !== headCommit) return false
   if (branches.has(facts.branch) && checksPassed(facts.view, undefined)) return true
-  if (withoutChecks.length > 0 && allFilesMatch(facts.files() ?? [], withoutChecks)) return true
-  return plan === undefined ? false : plan({ ...facts, headCommit })
+  if (withoutChecks.length > 0 && isCheckFree(facts.files() ?? [], withoutChecks, alwaysAsk)) return true
+  return standing === undefined ? false : standing(facts)
 }
 
 /**
@@ -106,25 +104,25 @@ const mergeFactsOf = (pullRequest: number, view: string, directory: string): Mer
 }
 
 /**
- * How to tell whether the user approved the plan of the branch's lane, read in the main checkout; undefined when no
- * plan approval can hold (no label, no transcript, no repository, plan approval off, no pointer, a session that is not
- * the coordinator's), so GitHub is not asked.
+ * How to tell whether a standing approval in this session's transcript covers a merge, with the boards, worktrees and
+ * settings of the main checkout; undefined when none can (no approval still holding, no repository, settings that do
+ * not read), so GitHub is not asked.
  */
-const planApprovalFor = (input: HookInput, label: string, projectDirectory: string): PlanApproval | undefined => {
-  const transcript = input.transcript_path
-  if (label === '' || typeof transcript !== 'string') return undefined
+const standingApprovalFor = (entries: unknown[], labels: StandingLabels, projectDirectory: string): StandingApproval | undefined => {
+  const grants = standingGrants(dialogAnswers(entries), labels, Date.now())
+  if (grants.length === 0) return undefined
   try {
     const main = mainCheckoutOf(projectDirectory)
-    if (readPointers(planPointersDirectory(main)).length === 0) return undefined
-    const base = planBaseOf(main)
-    if (base === undefined) return undefined
-    const isLane = isLaneIn(main, base.settings.worktreeDirectory)
-    if (!isCoordinatorAgent({ agent: ownPaneAgent(), session: input.session_id, main, isLane })) return undefined
-    return ({ branch, baseBranch, headCommit, view, files }) =>
-      baseBranch !== undefined &&
-      isPlanApproved(
-        { pullRequest: { branch, baseBranch, headCommit }, label, now: Date.now(), settings: base.settings },
-        planApprovalSources({ main, base, transcript, label, files, view }),
+    const settings = boardSettingsOf(readConfigOrNull([main]))
+    if (settings === null) return undefined
+    return ({ branch, baseBranch, view, files }) =>
+      standingVerdict(
+        { grants, branch, baseBranch, settingsBaseBranch: settings.baseBranch },
+        {
+          planOfBranch: (name) => planOfBranch(main, settings, name),
+          checksPassed: () => checksPassed(view, settings.requiredChecks),
+          files,
+        },
       )
   } catch {
     return undefined
@@ -134,15 +132,22 @@ const planApprovalFor = (input: HookInput, label: string, projectDirectory: stri
 const policyFor = (input: HookInput, labels: ApprovalLabels, projectDirectory: string): GuardPolicy => {
   const settings = readGuardSettings(projectDirectory)
   const directory = typeof input.cwd === 'string' && input.cwd !== '' ? input.cwd : projectDirectory
-  const branches = once(() => approvedBranchesFrom(input.transcript_path, settings, labels.selfMerge))
-  const plan = once(() => planApprovalFor(input, labels.plan, projectDirectory))
+  const entries = once(() => transcriptEntries(input.transcript_path))
+  const branches = once(() => approvedBranchesFrom(entries(), settings, labels.selfMerge))
+  const standing = once(() => standingApprovalFor(entries(), labels.standing, projectDirectory))
   return {
     commands: settings.commands,
     shellDefinitions: once(() => readShellDefinitions()),
     isMergeApproved: (merge) => {
-      if (!isInside(directory, projectDirectory)) return false
-      const approvals = { branches: branches(), withoutChecks: settings.withoutChecks, plan: plan() }
-      if (approvals.branches.size === 0 && approvals.withoutChecks.length === 0 && approvals.plan === undefined) return false
+      // the same branch name in another checkout is another pull request
+      if (!isWithinDirectory(directory, projectDirectory)) return false
+      const approvals = {
+        branches: branches(),
+        withoutChecks: settings.withoutChecks,
+        alwaysAsk: [...ALWAYS_ASK_PATHS, ...settings.alwaysAsk],
+        standing: standing(),
+      }
+      if (approvals.branches.size === 0 && approvals.withoutChecks.length === 0 && approvals.standing === undefined) return false
       // The branch lookup also proves the pull request is open and from this repository; every path needs that.
       const facts = mergeFactsOf(merge.pullRequest, viewPullRequest(merge.pullRequest, directory) ?? '', directory)
       return facts !== undefined && approvesMerge(approvals, merge, facts)

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

@@ -8,12 +8,18 @@ export type GuardSettings = {
   selfMerge: { offer: boolean; approvalMinutes: number }
   /** Path patterns of a pull request that is merged without checks; empty means every merge waits for them. */
   withoutChecks: string[]
+  /**
+   * The project's own paths that always ask (`guard.alwaysAsk`, and `guard.planApproval.exceptPaths` of a config from
+   * before 1.10.0); they only ever add a question.
+   */
+  alwaysAsk: string[]
 }
 
 export const DEFAULT_SETTINGS: GuardSettings = {
-  commands: ['gh pr merge', 'gh workflow run', 'gh run rerun', 'gh api'],
+  commands: ['gh pr merge', 'gh workflow run'],
   selfMerge: { offer: true, approvalMinutes: 180 },
   withoutChecks: [],
+  alwaysAsk: [],
 }
 
 const CONFIG_PATH = join('.jackherd', 'config.json')
@@ -50,6 +56,10 @@ export const readConfigOrNull = (directories: string[]): Record<string, unknown>
 
 const readConfig = (directories: string[]): Record<string, unknown> => readConfigOrNull(directories) ?? {}
 
+/** Every non-empty string of a list; a path only ever adds a question, so no entry is refused for its form. */
+const pathsOf = (value: unknown): string[] =>
+  Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string' && entry !== '') : []
+
 /**
  * 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.
@@ -59,6 +69,7 @@ export const readGuardSettings = (projectDirectory: string, home: string = homed
   const section = isRecord(config.guard) ? config.guard : {}
   const merge = isRecord(config.merge) ? config.merge : {}
   const selfMerge = isRecord(section.selfMerge) ? section.selfMerge : {}
+  const legacy = isRecord(section.planApproval) ? section.planApproval : {}
   return {
     commands: isCommandList(section.commands) ? section.commands : DEFAULT_SETTINGS.commands,
     selfMerge: {
@@ -68,5 +79,6 @@ export const readGuardSettings = (projectDirectory: string, home: string = homed
         : DEFAULT_SETTINGS.selfMerge.approvalMinutes,
     },
     withoutChecks: isPatternList(merge.withoutChecks) ? merge.withoutChecks : DEFAULT_SETTINGS.withoutChecks,
+    alwaysAsk: [...pathsOf(section.alwaysAsk), ...pathsOf(legacy.exceptPaths)],
   }
 }

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

@@ -0,0 +1,142 @@
+/**
+ * The standing approval: the user's answer to a dialog whose question carries ``Plan `<path>` <until> <YYYY-MM-DD HH:MM>``
+ * lifts the question for the merges of that plan's lanes until that moment, at most 24 hours after the answer. It is
+ * read from the transcript of the session that merges, like the self-merge label, so a new session after a hand-over
+ * holds none and asks again (`claude --resume` keeps the transcript, so there it holds on, at most 24 hours). The newest
+ * answer to a question naming the plan decides; any other label ends the approval, also on a question without an end.
+ * A merge passes only into the base branch, with green checks GitHub can merge, from a branch whose lane links exactly
+ * that plan, and never with a file of `STANDING_ALWAYS_ASK`. Every doubt answers "no", so the guard asks as before.
+ */
+import type { DialogAnswer } from '../shared/dialog-answer'
+import { MS_PER_MINUTE } from '../shared/fresh'
+import { newestVerdict } from '../shared/newest-verdict'
+import { alwaysAskingFiles, STANDING_ALWAYS_ASK } from './always-ask'
+import type { MergeNote } from './decision'
+import { isPlainPath } from './plain-path'
+
+/** The exact option label that approves, and the word before the end in the question, both per response language. */
+export type StandingLabels = { approve: string; until: string }
+
+/** A plan whose lanes merge without a question until `until`, in milliseconds. */
+export type StandingGrant = { plan: string; until: number }
+
+/** Where the facts of a merge come from; each is asked only once the steps before it said yes. */
+export type StandingApprovalSources = {
+  /** The one plan the lane of the branch links on the boards; undefined for none, several, or a branch of no lane. */
+  planOfBranch: (branch: string) => string | undefined
+  /** Whether GitHub can merge the head commit and its checks passed. */
+  checksPassed: () => boolean
+  /** The files of the pull request as GitHub lists them, renames with their old name; undefined when not complete. */
+  files: () => readonly string[] | undefined
+}
+
+export type StandingApprovalQuery = {
+  grants: readonly StandingGrant[]
+  /** The head branch and the branch the pull request merges into, as GitHub says. */
+  branch: string
+  baseBranch: string | undefined
+  /** The project's base branch. */
+  settingsBaseBranch: string
+}
+
+export const MAX_STANDING_MINUTES = 24 * 60
+
+const PLAN_PATH = /^[A-Za-z0-9_./-]+\.md$/
+
+const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/** A plan path as a board links it: a relative markdown file, no empty, `.` or `..` segment. */
+const isPlanPath = (path: string): boolean =>
+  PLAN_PATH.test(path) && path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..')
+
+/** A local moment from its parts; undefined for one the calendar or the clock does not have (Feb 30, 24:00, a DST gap). */
+const localMoment = ([year, month, day, hour, minute]: number[]): number | undefined => {
+  const date = new Date(year, month - 1, day, hour, minute)
+  const exact =
+    date.getFullYear() === year &&
+    date.getMonth() === month - 1 &&
+    date.getDate() === day &&
+    date.getHours() === hour &&
+    date.getMinutes() === minute
+  return exact ? date.getTime() : undefined
+}
+
+/** The plan and the end a question names as ``Plan `<path>` <until> YYYY-MM-DD HH:MM``; none for none or several marks. */
+export const standingMarkOf = (question: string, until: string): StandingGrant | undefined => {
+  if (until === '') return undefined
+  const mark = new RegExp(`\\bPlan \`([^\`]*)\` ${escapeRegExp(until)} (\\d{4})-(\\d{2})-(\\d{2}) (\\d{2}):(\\d{2})(?!\\d)`, 'g')
+  const marks = [...question.matchAll(mark)]
+  if (marks.length !== 1) return undefined
+  const [, plan, ...parts] = marks[0]
+  const end = localMoment(parts.map(Number))
+  return end !== undefined && isPlanPath(plan) ? { plan, until: end } : undefined
+}
+
+const PLAN_MENTION = /\bPlan `([^`]*)`/g
+
+/** The one plan a question names as ``Plan `<path>` ``, with or without an end; none for none or several. */
+const namedPlanOf = (question: string): string | undefined => {
+  const plans = new Set([...question.matchAll(PLAN_MENTION)].map(([, plan]) => plan))
+  const [only] = plans
+  return plans.size === 1 && isPlanPath(only) ? only : undefined
+}
+
+/**
+ * The plan an answer speaks about, and the end its question names; `NaN` for a question that names the plan without
+ * an end, which never approves but, answered with anything else, ends the approval: in doubt it ends.
+ */
+const markOf = (question: string, until: string): StandingGrant | undefined => {
+  const mark = standingMarkOf(question, until)
+  if (mark !== undefined) return mark
+  const plan = namedPlanOf(question)
+  return plan === undefined ? undefined : { plan, until: Number.NaN }
+}
+
+type MarkedAnswer = DialogAnswer & { mark: StandingGrant }
+
+const approves = ({ answer, offered, answeredAt, mark }: MarkedAnswer, label: string): boolean =>
+  label !== '' &&
+  answer === label &&
+  offered.includes(label) &&
+  mark.until > answeredAt &&
+  mark.until - answeredAt <= MAX_STANDING_MINUTES * MS_PER_MINUTE
+
+/** The approval the newest answers about one plan give: all of them approve, and the earliest end is still ahead. */
+const grantOf = (plan: string, answers: readonly MarkedAnswer[], label: string, now: number): StandingGrant[] => {
+  const verdict = newestVerdict(answers, now)
+  if (verdict.length === 0 || !verdict.every((answer) => approves(answer, label))) return []
+  const until = Math.min(...verdict.map(({ mark }) => mark.until))
+  return until > now ? [{ plan, until }] : []
+}
+
+/** The plans the user approved standing in these dialog answers, and until when; only those still holding at `now`. */
+export const standingGrants = (answers: readonly DialogAnswer[], labels: StandingLabels, now: number): StandingGrant[] => {
+  const marked = answers.flatMap((answer): MarkedAnswer[] => {
+    const mark = markOf(answer.question, labels.until)
+    return mark === undefined ? [] : [{ ...answer, mark }]
+  })
+  const plans = [...new Set(marked.map(({ mark }) => mark.plan))]
+  return plans.flatMap((plan) =>
+    grantOf(
+      plan,
+      marked.filter(({ mark }) => mark.plan === plan),
+      labels.approve,
+      now,
+    ),
+  )
+}
+
+const exceptedNote = (plan: string, files: readonly string[]): MergeNote => ({
+  note: `The standing approval of plan \`${plan}\` does not cover ${files.map((file) => `\`${file}\``).join(', ')}: workflows, migrations, env files and the guards' own files always ask.`,
+})
+
+/** `true` lifts the question; `false` asks as before; a note asks and says which files the approval does not cover. */
+export const standingVerdict = (query: StandingApprovalQuery, sources: StandingApprovalSources): boolean | MergeNote => {
+  if (query.grants.length === 0 || query.baseBranch !== query.settingsBaseBranch) return false
+  const plan = sources.planOfBranch(query.branch)
+  if (plan === undefined || !query.grants.some((grant) => grant.plan === plan) || !sources.checksPassed()) return false
+  const files = sources.files()
+  if (files === undefined || files.length === 0 || !files.every(isPlainPath)) return false
+  const excepted = alwaysAskingFiles(files, STANDING_ALWAYS_ASK)
+  return excepted.length === 0 ? true : exceptedNote(plan, excepted)
+}

package/kit/hooks/hooks/open-question/index.ts

@@ -0,0 +1,26 @@
+// Stop hook of Claude Code, shipped by jackherd: records each `AskUserQuestion` question that ended without an answer
+// (the dialog was rejected or interrupted, or answered with "later") in `.jackherd/questions/` of the main checkout, and
+// closes the open records a later answer to the same question settles. The herd, the heartbeat and `jh waiting` show the
+// open ones as something that waits on the user. The whole transcript is read, because a rejected dialog ends its turn
+// without a Stop hook. It prints nothing and never blocks.
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { mainCheckoutOf } from '../shared/checkout'
+import { runOpenQuestion } from './run'
+import { readQuestionRecords, writeQuestionRecord } from './store'
+
+const ID_LENGTH = 12
+
+try {
+  runOpenQuestion(JSON.parse(await Bun.stdin.text()), {
+    mainCheckoutOf,
+    readTranscript: (path) => readFileSync(path, 'utf8'),
+    readRecords: readQuestionRecords,
+    writeRecord: writeQuestionRecord,
+    idOf: (toolUseId, question) =>
+      createHash('sha256').update(`${toolUseId}\n${question}`).digest('hex').slice(0, ID_LENGTH),
+  })
+} catch {
+  // Unreadable input records nothing.
+}
+process.exit(0)

package/kit/hooks/hooks/open-question/record.ts

@@ -0,0 +1,135 @@
+import { ASK_USER_QUESTION_TOOL, contentOf, dialogAnswers, questionsOf } from '../shared/dialog-answers'
+import { isRecord, type JsonObject } from '../shared/json'
+
+/**
+ * A question of a dialog that ended without an answer, as the hook records it: what was asked, when, from where and
+ * when it closed (null while it is open). Written by the hook, read by the herd, the watcher and `jh waiting`.
+ */
+export type QuestionRecord = {
+  id: string
+  question: string
+  askedAt: number
+  cwd: string
+  session: string
+  closedAt: number | null
+}
+
+export type QuestionContext = {
+  cwd: string
+  session: string
+  /** What the dialogs of the transcript have answered, as `answeredQuestionsOf` finds it. */
+  answered: readonly AnsweredQuestion[]
+  /** The id of a question; the same call and text give the same id, so a second run finds the record it wrote. */
+  idOf: (toolUseId: string, question: string) => string
+}
+
+/** A question the user answered for real, with the time of the answer. */
+export type AnsweredQuestion = { question: string; answeredAt: number }
+
+type Ask = { toolUseId: string; question: string; askedAt: number; position: number; messageId: string | null }
+
+const ID = /^[0-9a-f]{12}$/
+const MAX_QUESTION = 200
+const CONTROLS = /[\u0000-\u001f\u007f-\u009f]/g
+/** An answer that puts the question off rather than settling it: later, or not yet. */
+const LATER_WORD = /\b(später|spaeter|later|noch\s+nicht|not\s+yet)\b/i
+
+/** The question as one line without control characters, cut to what a row shows; how records and answers are compared. */
+export const questionTextOf = (value: string): string =>
+  value.replace(CONTROLS, ' ').replace(/\s+/g, ' ').trim().slice(0, MAX_QUESTION)
+
+const messageIdOf = (entry: JsonObject): string | null =>
+  isRecord(entry.message) && typeof entry.message.id === 'string' ? entry.message.id : null
+
+const mainThread = (entries: readonly unknown[]): JsonObject[] =>
+  entries.filter(isRecord).filter((entry) => entry.isSidechain !== true)
+
+/** Every question of every `AskUserQuestion` call of the main thread, with where in the transcript it stands. */
+const asksOf = (entries: readonly JsonObject[]): Ask[] =>
+  entries.flatMap((entry, position) => {
+    const askedAt = typeof entry.timestamp === 'string' ? Date.parse(entry.timestamp) : Number.NaN
+    if (Number.isNaN(askedAt)) return []
+    return contentOf(entry)
+      .filter((block) => block.type === 'tool_use' && block.name === ASK_USER_QUESTION_TOOL)
+      .flatMap((block) =>
+        typeof block.id === 'string'
+          ? questionsOf(block.input).map(({ question }) => ({
+              toolUseId: block.id as string,
+              question,
+              askedAt,
+              position,
+              messageId: messageIdOf(entry),
+            }))
+          : [],
+      )
+  })
+
+/** The answers of each tool result by tool use id; null for a result without answers (a rejection, an error). */
+const resultsOf = (entries: readonly JsonObject[]): Map<string, JsonObject | null> => {
+  const results = new Map<string, JsonObject | null>()
+  for (const entry of entries) {
+    const answers = isRecord(entry.toolUseResult) && isRecord(entry.toolUseResult.answers) ? entry.toolUseResult.answers : null
+    for (const block of contentOf(entry))
+      if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') results.set(block.tool_use_id, answers)
+  }
+  return results
+}
+
+/** Whether the transcript went on after the call, other than with the rest of the message that made it. */
+const wentOnAfter = (ask: Ask, entries: readonly JsonObject[]): boolean =>
+  entries
+    .slice(ask.position + 1)
+    .some((entry) => (entry.type === 'user' || entry.type === 'assistant') && messageIdOf(entry) !== ask.messageId)
+
+/** No answer came back, the answer is not a text for this question, or it only puts the question off. */
+const endedUnanswered = (ask: Ask, results: ReadonlyMap<string, JsonObject | null>, entries: readonly JsonObject[]) => {
+  if (!results.has(ask.toolUseId)) return wentOnAfter(ask, entries)
+  const answer = results.get(ask.toolUseId)?.[ask.question]
+  return typeof answer !== 'string' || LATER_WORD.test(answer)
+}
+
+/** The questions the user answered in a dialog without putting them off, in transcript order. */
+export const answeredQuestionsOf = (entries: readonly unknown[]): AnsweredQuestion[] =>
+  dialogAnswers(entries)
+    .filter(({ answer }) => !LATER_WORD.test(answer))
+    .map(({ question, answeredAt }) => ({ question: questionTextOf(question), answeredAt }))
+
+/** The answer to `question` given after `at`, if a dialog gave one. */
+export const answeredSince = (
+  answered: readonly AnsweredQuestion[],
+  question: string,
+  at: number,
+): AnsweredQuestion | undefined => answered.find((done) => done.question === question && done.answeredAt > at)
+
+/**
+ * The questions of the main thread that stand open: their dialog was rejected or interrupted, or answered with "later",
+ * and no dialog answered the same text since. A call that carries its own answers asked nobody; a sidechain is no dialog
+ * of the user's.
+ */
+export const openQuestionsOf = (entries: readonly unknown[], context: QuestionContext): QuestionRecord[] => {
+  const thread = mainThread(entries)
+  const results = resultsOf(thread)
+  return asksOf(thread)
+    .filter((ask) => endedUnanswered(ask, results, thread))
+    .map((ask) => ({ ask, question: questionTextOf(ask.question) }))
+    .filter(({ ask, question }) => question !== '' && !answeredSince(context.answered, question, ask.askedAt))
+    .map(({ ask, question }) => ({
+      id: context.idOf(ask.toolUseId, question),
+      question,
+      askedAt: ask.askedAt,
+      cwd: context.cwd,
+      session: context.session,
+      closedAt: null,
+    }))
+}
+
+/** A record of the shape the hook writes; the herd reads questions only through this. */
+export const isQuestionRecord = (value: unknown): value is QuestionRecord =>
+  isRecord(value) &&
+  typeof value.id === 'string' &&
+  ID.test(value.id) &&
+  typeof value.question === 'string' &&
+  typeof value.askedAt === 'number' &&
+  typeof value.cwd === 'string' &&
+  typeof value.session === 'string' &&
+  (value.closedAt === null || typeof value.closedAt === 'number')

package/kit/hooks/hooks/open-question/run.ts

@@ -0,0 +1,52 @@
+import { ASK_USER_QUESTION_TOOL, parseTranscript } from '../shared/dialog-answers'
+import { isRecord } from '../shared/json'
+import { answeredQuestionsOf, answeredSince, openQuestionsOf, type QuestionRecord } from './record'
+
+/** Everything with a side effect, passed in so a test reaches the flow without git, files or a clock. */
+export type OpenQuestionDependencies = {
+  mainCheckoutOf: (cwd: string) => string
+  readTranscript: (path: string) => string
+  readRecords: (main: string) => QuestionRecord[]
+  writeRecord: (main: string, record: QuestionRecord) => void
+  idOf: (toolUseId: string, question: string) => string
+}
+
+const MARKERS = [ASK_USER_QUESTION_TOOL, '"answers"', '"is_error":true']
+
+/**
+ * The lines of a transcript that can say anything about a dialog, and its last line: a transcript runs to many
+ * megabytes, and the last line is how a call without a result shows that the session went on after it.
+ */
+export const relevantLines = (text: string): string => {
+  const lines = text.split('\n').filter((line) => line.trim() !== '')
+  return lines
+    .filter((line, index) => index === lines.length - 1 || MARKERS.some((marker) => line.includes(marker)))
+    .join('\n')
+}
+
+/**
+ * Records the questions of the session's dialogs that ended without an answer, and closes the open records of every
+ * session that a dialog in this transcript has answered since. The whole transcript is read, not the last turn: a
+ * rejected dialog ends its turn without a Stop hook, so it is found at the end of the next turn. Claude Code's hook
+ * input: `cwd`, `session_id`, `transcript_path`. Writes nothing on any failure.
+ */
+export const runOpenQuestion = (input: unknown, dependencies: OpenQuestionDependencies): void => {
+  try {
+    if (!isRecord(input)) return
+    const { cwd, session_id: session, transcript_path: transcriptPath } = input
+    if (typeof cwd !== 'string' || typeof session !== 'string' || typeof transcriptPath !== 'string') return
+    const entries = parseTranscript(relevantLines(dependencies.readTranscript(transcriptPath)))
+    const main = dependencies.mainCheckoutOf(cwd)
+    const stored = dependencies.readRecords(main)
+    const answered = answeredQuestionsOf(entries)
+    for (const record of stored.filter(({ closedAt }) => closedAt === null)) {
+      const answer = answeredSince(answered, record.question, record.askedAt)
+      if (answer) dependencies.writeRecord(main, { ...record, closedAt: answer.answeredAt })
+    }
+    const known = new Set(stored.map(({ id }) => id))
+    for (const record of openQuestionsOf(entries, { cwd, session, answered, idOf: dependencies.idOf }))
+      if (!known.has(record.id)) dependencies.writeRecord(main, record)
+  } catch {
+    // A failed record is no record; the herd shows no question.
+  }
+}

package/kit/hooks/hooks/open-question/store.ts

@@ -0,0 +1,39 @@
+import { lstatSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { writePrivateRecord } from '../shared/private-directory'
+import { isQuestionRecord, type QuestionRecord } from './record'
+
+const RECORD_FILE = /^[0-9a-f]{12}\.json$/
+const MAX_RECORD_BYTES = 16 * 1024
+
+/** Where the records lie: in the main checkout beside `.jackherd/sent`, which the herd reads. Ignored by git. */
+export const questionDirectory = (main: string): string => join(main, '.jackherd', 'questions')
+
+const recordAt = (path: string): QuestionRecord[] => {
+  try {
+    const entry = lstatSync(path)
+    if (!entry.isFile() || entry.size > MAX_RECORD_BYTES) return []
+    const record: unknown = JSON.parse(readFileSync(path, 'utf8'))
+    return isQuestionRecord(record) ? [record] : []
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Every well-formed `<id>.json` record of the directory, like the herd reads them: a link and a file over 16 KiB are
+ * skipped. Nothing when the directory is missing or unreadable.
+ */
+export const readQuestionRecords = (main: string): QuestionRecord[] => {
+  const directory = questionDirectory(main)
+  try {
+    return readdirSync(directory)
+      .filter((name) => RECORD_FILE.test(name))
+      .flatMap((name) => recordAt(join(directory, name)))
+  } catch {
+    return []
+  }
+}
+
+export const writeQuestionRecord = (main: string, record: QuestionRecord): void =>
+  writePrivateRecord(questionDirectory(main), record)

package/kit/hooks/hooks/sent-file/index.ts

@@ -0,0 +1,19 @@
+// PostToolUse hook of Claude Code for `SendUserFile` and `Artifact`, shipped by jackherd: records each file a session
+// sends to the user and each artifact it publishes for them, with time and caption, in `.jackherd/sent/` of the main
+// checkout. The herd shows the files as badges on the lane they belong to and as something that waits on the user's
+// answer, until the coordinator closes the record. It prints nothing and never blocks.
+import { mainCheckoutOf } from '../shared/checkout'
+import { runSentFile } from './run'
+import { writeSentRecord } from './store'
+
+try {
+  runSentFile(JSON.parse(await Bun.stdin.text()), {
+    mainCheckoutOf,
+    writeRecord: writeSentRecord,
+    now: () => Date.now(),
+    randomBytes: () => crypto.getRandomValues(new Uint8Array(6)),
+  })
+} catch {
+  // Unreadable input records nothing.
+}
+process.exit(0)