jackherd 1.8.1 → 1.10.0

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

@@ -0,0 +1,128 @@
+import { isAbsolute, resolve } from 'node:path'
+import { isRecord } from '../shared/json'
+
+/**
+ * A send of files to the user as the hook records it: the files (absolute), the caption, when it happened, from where
+ * (the directory and session of the call, the subagent when one sent it) and when the coordinator closed it, null
+ * while the user's answer is awaited. Written by the hook, read by the herd and the watcher.
+ */
+export type SentRecord = {
+  id: string
+  files: string[]
+  caption: string | null
+  sentAt: number
+  cwd: string
+  session: string
+  agentId: string | null
+  closedAt: number | null
+}
+
+export type SentCall = {
+  /** The tool input of `SendUserFile`: `files`, `caption`, `status`, `display`. */
+  toolInput: unknown
+  cwd: string
+  session: string
+  agentId: string | null
+  now: number
+  id: string
+}
+
+export type ArtifactCall = SentCall & { toolResponse: unknown }
+
+const ID = /^[0-9a-f]{12}$/
+const MAX_FILES = 20
+const MAX_CAPTION = 200
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/
+const CONTROLS = new RegExp(CONTROL.source, 'g')
+/** The address of a published artifact: https on claude.ai, the host a person opens. */
+const ARTIFACT_ADDRESS = /https:\/\/claude\.ai\/(?:code\/)?artifact\/[A-Za-z0-9_-]+/
+const WHOLE_ARTIFACT_ADDRESS = new RegExp(`^${ARTIFACT_ADDRESS.source}$`)
+/** The actions of the Artifact tool that publish; no action means publish. */
+const READING_ACTIONS = new Set(['list', 'read', 'delete', 'open', 'pin', 'unpin', 'quickstart'])
+const MAX_DEPTH = 4
+
+const captionOf = (value: unknown): string | null => {
+  if (typeof value !== 'string') return null
+  const text = value.replace(CONTROLS, ' ').replace(/\s+/g, ' ').trim()
+  return text === '' ? null : text.slice(0, MAX_CAPTION)
+}
+
+/** A file entry the herd can show and open: a non-empty string without a control character. */
+const isFileEntry = (file: unknown): file is string => typeof file === 'string' && file !== '' && !CONTROL.test(file)
+
+/** The fields every record shares: who sent it, when, and still open. */
+const recordOf = (
+  { cwd, session, agentId, now, id }: Omit<SentCall, 'toolInput'>,
+  files: string[],
+  caption: string | null,
+): SentRecord => ({ id, files, caption, sentAt: now, cwd, session, agentId, closedAt: null })
+
+/** The record of a `SendUserFile` call; null when its input names no file or a file with a control character. */
+export const sentRecordOf = ({ toolInput, ...call }: SentCall): SentRecord | null => {
+  const files: unknown[] = isRecord(toolInput) && Array.isArray(toolInput.files) ? toolInput.files : []
+  if (files.length === 0 || !files.every(isFileEntry)) return null
+  const paths = (files as string[])
+    .slice(0, MAX_FILES)
+    .map((file) => (isAbsolute(file) ? file : resolve(call.cwd, file)))
+  return recordOf(call, paths, isRecord(toolInput) ? captionOf(toolInput.caption) : null)
+}
+
+/**
+ * The strings of an answer, wherever it carries them: the answer itself, an object's `url`, `text` and `content`, a
+ * list's entries.
+ */
+const stringsOf = (value: unknown, depth = 0): string[] => {
+  if (typeof value === 'string') return [value]
+  if (depth >= MAX_DEPTH) return []
+  if (Array.isArray(value)) return value.flatMap((entry) => stringsOf(entry, depth + 1))
+  if (!isRecord(value)) return []
+  return [value.url, value.text, value.content].flatMap((entry) => stringsOf(entry, depth + 1))
+}
+
+/** The first artifact address an answer names, whether it is an object with `url` or text. */
+const artifactAddressIn = (toolResponse: unknown): string | null => {
+  for (const text of stringsOf(toolResponse)) {
+    const address = ARTIFACT_ADDRESS.exec(text)?.[0]
+    if (address) return address
+  }
+  return null
+}
+
+/** The title the answer names, else the input's `title` or `label`. */
+const artifactCaptionOf = (toolInput: Record<string, unknown>, toolResponse: unknown): string | null =>
+  captionOf(isRecord(toolResponse) ? toolResponse.title : null) ??
+  captionOf(toolInput.title) ??
+  captionOf(toolInput.label)
+
+/**
+ * The record of an Artifact publish (or update) as a send: its file is the artifact's address, read from the tool's
+ * answer (an object with `url`, or text such as `Published … at <address> (Version 3 …)`), and its caption the
+ * artifact's title. Null for a listing, a read, an asset upload and an answer without such an address.
+ */
+export const artifactRecordOf = ({ toolInput, toolResponse, ...call }: ArtifactCall): SentRecord | null => {
+  if (!isRecord(toolInput)) return null
+  const action = toolInput.action
+  if ((typeof action === 'string' && READING_ACTIONS.has(action)) || toolInput.asset === true) return null
+  const address = artifactAddressIn(toolResponse)
+  if (address === null) return null
+  return recordOf(call, [address], artifactCaptionOf(toolInput, toolResponse))
+}
+
+/** A file entry of a record: an artifact address as a whole, or a path. */
+const isRecordedFile = (file: unknown): boolean =>
+  typeof file === 'string' && (!file.startsWith('https://') || WHOLE_ARTIFACT_ADDRESS.test(file))
+
+/** A record of the shape the hook writes; the herd reads files only through this. */
+export const isSentRecord = (value: unknown): value is SentRecord =>
+  isRecord(value) &&
+  typeof value.id === 'string' &&
+  ID.test(value.id) &&
+  Array.isArray(value.files) &&
+  value.files.length > 0 &&
+  value.files.every(isRecordedFile) &&
+  (value.caption === null || typeof value.caption === 'string') &&
+  typeof value.sentAt === 'number' &&
+  typeof value.cwd === 'string' &&
+  typeof value.session === 'string' &&
+  (value.agentId === null || typeof value.agentId === 'string') &&
+  (value.closedAt === null || typeof value.closedAt === 'number')

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

@@ -0,0 +1,48 @@
+import { isRecord } from '../shared/json'
+import { artifactRecordOf, type SentRecord, sentRecordOf } from './record'
+
+/** Everything with a side effect, passed in so a test reaches the flow without git, files or a clock. */
+export type SentFileDependencies = {
+  mainCheckoutOf: (cwd: string) => string
+  writeRecord: (main: string, record: SentRecord) => void
+  now: () => number
+  randomBytes: () => Uint8Array
+}
+
+/** The tools whose calls are recorded: files sent to the user and artifacts published for them. */
+const SEND_USER_FILE_TOOL = 'SendUserFile'
+const ARTIFACT_TOOL = 'Artifact'
+const ID_BYTES = 6
+
+/** The id from random bytes the caller draws: 12 hex characters. */
+const idFrom = (bytes: Uint8Array): string =>
+  [...bytes.slice(0, ID_BYTES)].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+
+/**
+ * Records the files a session sent to the user and the artifacts it published for them, for the herd and the
+ * watcher, in the main checkout of the call's directory. Claude Code's hook input: `cwd`, `session_id`,
+ * `tool_name`, `tool_input`, and `agent_id` inside a subagent. Records nothing for another tool or a call without
+ * files, and nothing on any failure: the record never stands in the agent's way.
+ */
+export const runSentFile = (input: unknown, dependencies: SentFileDependencies): void => {
+  try {
+    if (!isRecord(input) || (input.tool_name !== SEND_USER_FILE_TOOL && input.tool_name !== ARTIFACT_TOOL)) return
+    const { cwd, session_id: session, agent_id: agentId } = input
+    if (typeof cwd !== 'string' || typeof session !== 'string') return
+    const call = {
+      toolInput: input.tool_input,
+      cwd,
+      session,
+      agentId: typeof agentId === 'string' ? agentId : null,
+      now: dependencies.now(),
+      id: idFrom(dependencies.randomBytes()),
+    }
+    const record =
+      input.tool_name === ARTIFACT_TOOL
+        ? artifactRecordOf({ ...call, toolResponse: input.tool_response })
+        : sentRecordOf(call)
+    if (record) dependencies.writeRecord(dependencies.mainCheckoutOf(cwd), record)
+  } catch {
+    // A failed record is no record; the herd shows no badge.
+  }
+}

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

@@ -0,0 +1,9 @@
+import { join } from 'node:path'
+import { writePrivateRecord } from '../shared/private-directory'
+import type { SentRecord } from './record'
+
+/** Where the records lie: in the main checkout beside `.jackherd/approvals`, which the herd reads. Ignored by git. */
+export const sentDirectory = (main: string): string => join(main, '.jackherd', 'sent')
+
+export const writeSentRecord = (main: string, record: SentRecord): void =>
+  writePrivateRecord(sentDirectory(main), record)

package/kit/hooks/hooks/shared/board-lanes.ts

@@ -72,6 +72,18 @@ const planPathOf = (boardDirectory: string, cell: string): string[] => {
   return href === undefined ? [] : [posix.normalize(posix.join(boardDirectory, href.split('#')[0]))]
 }
 
+/** The rows of one lane since it was last cleaned up: a named row without the mark after a closed one starts it anew. */
+const currentRows = <Row extends { cells: string[] }>(rows: Row[], closedWord: string): Row[] =>
+  rows.reduce<{ closed: boolean; kept: Row[] }>(
+    ({ closed, kept }, row) => {
+      const first = row.cells[0] ?? ''
+      const marked = first.includes(closedWord)
+      const startsAnew = closed && !marked && !first.startsWith(CONTINUATION)
+      return { closed: marked || (closed && !startsAnew), kept: startsAnew ? [row] : [...kept, row] }
+    },
+    { closed: false, kept: [] },
+  ).kept
+
 /** Every lane the lanes table names, in table order. */
 export const laneNamesOf = (markdown: string, language: BoardLanguage): string[] => [
   ...new Set(laneRows(markdown, language).map(({ lane }) => lane)),
@@ -84,8 +96,9 @@ export const lanePlansOf = (
   lane: string,
   language: BoardLanguage,
 ): LanePlans | undefined => {
-  const rows = laneRows(markdown, language).filter((row) => row.lane === lane)
-  if (rows.length === 0) return undefined
+  const all = laneRows(markdown, language).filter((row) => row.lane === lane)
+  if (all.length === 0) return undefined
+  const rows = currentRows(all, BOARD_WORDS[language].laneClosed)
   return {
     closed: rows.some(({ cells }) => (cells[0] ?? '').includes(BOARD_WORDS[language].laneClosed)),
     plans: [...new Set(rows.flatMap(({ cells }) => planPathOf(boardDirectory, cells[PLAN_COLUMN] ?? '')))],

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

@@ -19,3 +19,10 @@ export const readConfig = (directories: readonly string[]): Record<string, unkno
 /** 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] : {}
+
+/**
+ * Whether the hint `key` of the `hints` section is on: off only where the first of `configs` (project before home)
+ * that sets it to a boolean says `false`; a missing or malformed value leaves the next config its say.
+ */
+export const isHintOn = (configs: readonly Record<string, unknown>[], key: string): boolean =>
+  configs.map((config) => sectionOf(config, 'hints')[key]).find((value) => typeof value === 'boolean') !== false

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

@@ -1,3 +1,8 @@
+/**
+ * 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.
+ */
 import type { DialogAnswer } from './dialog-answer'
 import { isRecord, type JsonObject } from './json'
 
@@ -6,13 +11,8 @@ export type { DialogAnswer } from './dialog-answer'
 /** The tool name of the dialog, as hook inputs and transcripts carry it. */
 export const ASK_USER_QUESTION_TOOL = 'AskUserQuestion'
 
-/**
- * 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[] => {
+/** The content blocks of a transcript entry's message; none when it has no list of blocks. */
+export const contentOf = (entry: JsonObject): JsonObject[] => {
   const content = isRecord(entry.message) ? entry.message.content : undefined
   return Array.isArray(content) ? content.filter(isRecord) : []
 }
@@ -34,10 +34,10 @@ const offeredLabels = (question: JsonObject): string[] =>
     ? question.options.flatMap((option) => (isRecord(option) && typeof option.label === 'string' ? [option.label] : []))
     : []
 
-type AskedQuestion = { question: string; offered: string[] }
+export 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[] => {
+export 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'

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

@@ -1,4 +1,11 @@
 import { readFileSync, realpathSync } from 'node:fs'
+import { isAbsolute, relative } from 'node:path'
+
+/** Whether `path` is `directory` or lies below it; a sibling that only shares the prefix does not. */
+export const isWithinDirectory = (path: string, directory: string): boolean => {
+  const inside = relative(directory, path)
+  return inside === '' || (!inside.startsWith('..') && !isAbsolute(inside))
+}
 
 /** The file's text; null when it cannot be read. */
 export const readTextOrNull = (path: string): string | null => {

package/kit/hooks/hooks/shared/lane.ts

@@ -46,7 +46,7 @@ export const laneOfAgent = ({ agent, session, main, worktreeDirectory }: AgentLo
 /**
  * Whether the session that merges is the coordinator: the agent of its pane, in this very session, started in the main
  * checkout and not under a lane's name. A lane's transcript may lie beside the coordinator's when it was started in the
- * main checkout; its name still tells it apart, so the plan approval never covers a lane's own merge.
+ * main checkout; its name still tells it apart, so an approval of the coordinator never covers a lane's own call.
  */
 export const isCoordinatorAgent = ({ agent, session, main, isLane }: MergingSession): boolean =>
   agent !== null &&

package/kit/hooks/hooks/shared/newest-verdict.ts

@@ -0,0 +1,10 @@
+/**
+ * The answers that decide a question asked more than once: the newest ones not from the future. Several given at the
+ * same moment (two questions in one dialog) decide only together; empty when none was given before `now`.
+ */
+export const newestVerdict = <Answer extends { answeredAt: number }>(answers: readonly Answer[], now: number): Answer[] => {
+  const past = answers.filter(({ answeredAt }) => answeredAt <= now)
+  if (past.length === 0) return []
+  const newest = Math.max(...past.map(({ answeredAt }) => answeredAt))
+  return past.filter(({ answeredAt }) => answeredAt === newest)
+}

package/kit/hooks/hooks/shared/private-directory.ts

@@ -1,4 +1,12 @@
-import { chmodSync, existsSync, lstatSync, mkdirSync, type Stats, writeFileSync } from 'node:fs'
+import {
+  chmodSync,
+  lstatSync,
+  mkdirSync,
+  renameSync,
+  type Stats,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
 import { join } from 'node:path'
 
 /** The mode of a file in a private directory: readable by its owner only. */
@@ -14,16 +22,55 @@ const entryAt = (path: string): Stats | null => {
   }
 }
 
+const removeIfPresent = (path: string): void => {
+  try {
+    unlinkSync(path)
+  } catch {
+    // nothing left over
+  }
+}
+
+/** Whether an entry belongs to `uid`; true where the platform has no user ids (`uid` undefined). */
+export const isOwnedBy = (entry: Pick<Stats, 'uid'>, uid: number | undefined): boolean =>
+  uid === undefined || entry.uid === uid
+
+const assertPrivateDirectory = (directory: string, entry: Stats | null): void => {
+  if (!entry || entry.isSymbolicLink() || !entry.isDirectory()) throw new Error(`${directory} is no directory`)
+  if (!isOwnedBy(entry, process.getuid?.())) throw new Error(`${directory} belongs to another user`)
+}
+
 /**
- * A directory only its owner reads, ignored by git: created `0700` when missing; when present it must be a directory
- * and not a link (else this throws, so nothing is written through it), is narrowed to `0700` and gets the `.gitignore`
- * it lacks. An existing `.gitignore` is kept.
+ * A directory only its owner reads, ignored by git: created `0700` when missing; when present (or once created, which
+ * covers a link planted in between) it must be a directory of the current user and not a link (else this throws, so
+ * nothing is written through it), is narrowed to `0700` and gets the `.gitignore` it lacks. An existing `.gitignore`
+ * is kept.
  */
 export const ensurePrivateDirectory = (directory: string): void => {
-  const entry = entryAt(directory)
-  if (entry && (entry.isSymbolicLink() || !entry.isDirectory())) throw new Error(`${directory} is no directory`)
-  if (!entry) mkdirSync(directory, { recursive: true, mode: PRIVATE_DIRECTORY })
+  if (!entryAt(directory)) mkdirSync(directory, { recursive: true, mode: PRIVATE_DIRECTORY })
+  assertPrivateDirectory(directory, entryAt(directory))
   chmodSync(directory, PRIVATE_DIRECTORY)
-  const ignore = join(directory, '.gitignore')
-  if (!existsSync(ignore)) writeFileSync(ignore, '*\n')
+  try {
+    writeFileSync(join(directory, '.gitignore'), '*\n', { flag: 'wx', mode: PRIVATE_FILE })
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+  }
+}
+
+/**
+ * Writes `text` to `path` (inside a directory `ensurePrivateDirectory` has verified) `0600` through a temporary file, so a
+ * reader never sees half of it. A leftover temporary file of an earlier process with the same pid is removed first,
+ * and the new one is created exclusively, so a planted link is never followed.
+ */
+export const writePrivateFile = (path: string, text: string): void => {
+  const temporary = `${path}.${process.pid}.tmp`
+  removeIfPresent(temporary)
+  writeFileSync(temporary, text, { mode: PRIVATE_FILE, flag: 'wx' })
+  chmodSync(temporary, PRIVATE_FILE)
+  renameSync(temporary, path)
+}
+
+/** Writes `<id>.json` into a private directory through a temporary file, so a reader never sees half of it. */
+export const writePrivateRecord = <T extends { id: string }>(directory: string, record: T): void => {
+  ensurePrivateDirectory(directory)
+  writePrivateFile(join(directory, `${record.id}.json`), `${JSON.stringify(record)}\n`)
 }

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

@@ -1,5 +1,5 @@
 import { posix } from 'node:path'
-import { isExpanded, type SimpleCommand, type Word } from './shell'
+import type { SimpleCommand, Word } from './shell'
 
 /**
  * Words Claude Code strips before it matches a Bash rule, so they do not hide the command. Its
@@ -72,7 +72,7 @@ export const isProgramPosition = (words: SimpleCommand, index: number): boolean
 
 export const isOption = (word: Word | undefined): boolean => word?.value.startsWith('-') ?? false
 
-export const isShell = (word: Word): boolean => SHELLS.has(programName(word))
+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 => {
@@ -150,76 +150,3 @@ export const inlineScript = (words: SimpleCommand, index: number): string | unde
   if (isBuiltinAt(words, index, TRAP_BUILTIN)) return trapAction(words, index)
   return isShell(words[index]) ? shellCommandScript(words, index) : undefined
 }
-
-/** Interpreters that run program text given on the command line or read from their input. */
-const INTERPRETERS = new Set(['python', 'python3', 'node', 'nodejs', 'bun', 'deno', 'perl', 'ruby', 'php', 'lua'])
-const INLINE_PROGRAM_OPTIONS = new Set(['-c', '-e', '-E', '-p', '-pe', '--eval', '--command', '--print', '-r'])
-const VERSIONED_PYTHON = /^python\d+(\.\d+)*$/
-/** A cluster of short options that ends in the one taking the program text: `python3 -Ic`, `perl -lne`. */
-const INLINE_PROGRAM_CLUSTER = /^-[A-Za-z]*[ce]$/
-/** An operand that names the interpreter's own input as the program file. */
-const INPUT_OPERAND = /^(-|\/dev\/stdin|\/dev\/fd\/0|\/proc\/self\/fd\/0)$/
-/** Options that print and exit, so an interpreter without an operand reads no program. */
-const PRINT_AND_EXIT = new Set(['--version', '-v', '-V', '--help', '-h'])
-/** Interpreters that, without an operand, print their help instead of reading a program; they read one after `run`. */
-const SUBCOMMAND_INTERPRETERS = new Set(['bun'])
-const RUN_SUBCOMMAND = 'run'
-/** An operand that names a script file: the words after it are the script's arguments, not the interpreter's options. */
-const SCRIPT_FILE = /\.(py|js|mjs|cjs|ts|mts|cts|jsx|tsx|rb|pl|pm|php|lua)$/i
-
-const isInterpreter = (word: Word): boolean => {
-  const name = programName(word)
-  return INTERPRETERS.has(name) || VERSIONED_PYTHON.test(name)
-}
-
-const isInlineProgramOption = ({ value }: Word): boolean =>
-  INLINE_PROGRAM_OPTIONS.has(value.split('=')[0]) || INLINE_PROGRAM_CLUSTER.test(value)
-
-/** The operand that names the program: the first one, or for `bun run` the one after `run`; `-` counts as one. */
-const programOperand = (interpreter: Word, rest: Word[]): Word | undefined => {
-  const operands = rest.filter((word) => !isOption(word) || word.value === '-')
-  const afterRun = SUBCOMMAND_INTERPRETERS.has(programName(interpreter)) && operands[0]?.value === RUN_SUBCOMMAND
-  return afterRun ? operands[1] : operands[0]
-}
-
-/**
- * Whether the interpreter reads its program from its input (`python3 -`, `node` fed by a pipe, `bun -`) or from an
- * expansion it cannot show (`python3 <(…)`).
- */
-const readsProgramFromInput = (interpreter: Word, rest: Word[]): boolean => {
-  const operand = programOperand(interpreter, rest)
-  if (operand === undefined) {
-    return (
-      !SUBCOMMAND_INTERPRETERS.has(programName(interpreter)) && !rest.some(({ value }) => PRINT_AND_EXIT.has(value))
-    )
-  }
-  // A quoted operand is still a file name; only an expansion (`$f`, `<(…)`) hides where the program comes from.
-  return isExpanded(operand.value) || INPUT_OPERAND.test(operand.value)
-}
-
-/**
- * The words up to a script file operand. Only a file name ends them: any other word could be an option's value
- * (`python3 -W ignore -c …`), and stopping there would miss the `-c` behind it.
- */
-const interpreterOptions = (rest: Word[]): Word[] => {
-  const scriptFile = rest.findIndex((word) => !isOption(word) && SCRIPT_FILE.test(word.value))
-  return scriptFile === -1 ? rest : rest.slice(0, scriptFile)
-}
-
-/**
- * An interpreter, anywhere a program can stand, handed program text (`python3 -c`, `node -e`) or reading it from its
- * input (`python3 - <<EOF`, `… | node`): the program can start any command, and no parse of the shell sees it.
- */
-export const runsInterpreterProgram = (words: SimpleCommand): boolean =>
-  words.some((word, index) => {
-    if (!isProgramPosition(words, index) || !isInterpreter(word)) return false
-    const rest = words.slice(index + 1)
-    return interpreterOptions(rest).some(isInlineProgramOption) || readsProgramFromInput(word, rest)
-  })
-
-/** A shell at the rule start with no script argument reads its script from stdin: a pipe, a here-document. */
-export const readsScriptFromInput = (words: SimpleCommand): boolean => {
-  const start = ruleStart(words)
-  const shell = words[start]
-  return shell !== undefined && isShell(shell) && words.slice(start + 1).every(isOption)
-}

package/kit/hooks/hooks/shared/shell-aliases.ts

@@ -6,7 +6,7 @@ export type ShellDefinitions = { aliases: ReadonlyMap<string, string>; functions
 
 const SHELL_DEFINITION_KIND = { alias: 'alias', function: 'function' } as const
 
-export type ShellDefinitionKind = (typeof SHELL_DEFINITION_KIND)[keyof typeof SHELL_DEFINITION_KIND]
+type ShellDefinitionKind = (typeof SHELL_DEFINITION_KIND)[keyof typeof SHELL_DEFINITION_KIND]
 
 /** A word at a program position that an alias or function stands for, whose body runs a watched program. */
 export type ShellDefinitionHit = { kind: ShellDefinitionKind; name: string; body: string }
@@ -23,9 +23,6 @@ const NAME_CHARACTER = /[\w.-]/
 /** The words a body may call: whatever stands between shell punctuation. */
 const BODY_WORD = /[^\s;|&(){}<>"'`$=]+/g
 const SHOWN_BODY_LENGTH = 80
-const ALIAS_BUILTIN = 'alias'
-/** An entry of the shell's own alias or function table, which defines one as an assignment: `functions[x]=…` (zsh). */
-const DEFINITION_TABLE_ENTRY = /^(aliases|galiases|saliases|functions|dis_functions|BASH_ALIASES)\[/
 
 /**
  * Words that are shell builtins or common programs. A word among them is not looked up, so most calls read no
@@ -179,73 +176,6 @@ export const shellDefinitionAt = (
   return undefined
 }
 
-/**
- * An `alias` command anywhere a program can stand, or an entry of the alias or function table: the definition it adds
- * in the script hides its text in a quoted word.
- */
-export const definesShellAlias = (words: SimpleCommand): boolean =>
-  words.some(
-    (word, index) =>
-      (word.value === ALIAS_BUILTIN && isProgramPosition(words, index)) || DEFINITION_TABLE_ENTRY.test(word.value),
-  )
-
-/** A program expanded from a variable or a substitution may name a function; one with a slash is a path. */
-const isExpandedProgram = (words: SimpleCommand, index: number): boolean => {
-  const { value, literal } = words[index]
-  return !literal && isExpanded(value) && !value.includes('/') && isProgramPosition(words, index)
-}
-
-/**
- * The word a parameter expansion falls back to or assigns: `shipit` in `${x:-shipit}`, `${x-shipit}`, `${a[0]:+shipit}`.
- * A nested expansion matches from the innermost one, so `${x:-${y:-shipit}}` yields `shipit`. The name may be empty
- * (`${:-shipit}`), special (`${@:-shipit}`) or an expansion itself (`${${x}:-shipit}`, zsh).
- */
-const EXPANSION_OPERAND = /\$\{(?:[^{}:=+?-]|\$\{[^{}]*\})*:?[-=+?]([^{}]*)\}/g
-
-/** `text` with each expansion operand beside it, so a name after the operator's `-` still stands as a word. */
-const withExpansionOperands = (text: string): string =>
-  [text, ...[...text.matchAll(EXPANSION_OPERAND)].map(([, operand]) => operand)].join('\n')
-
-/**
- * A script that lists the shell's functions can take a function's name from there without writing it out: zsh's
- * `functions`, `dis_functions` and `functions_source` tables or builtin, `compgen -A function`/`-c`/`-A command`
- * (also bundled, `-bA function`), `declare`/`typeset` with `-f`, `-F` or `+f` (`typeset -fm`, `declare -Fp`),
- * `whence`/`which`/`where`/`type -m`, and a bare `set`, which prints the functions in bash.
- */
-const READS_FUNCTION_TABLE = new RegExp(
-  [
-    /(?:^|[^\w.-])(?:dis_)?functions(?:_source)?(?:[^\w.-]|$)/,
-    /\bcompgen\b[^\n;|&]*-(?:[A-Za-z]*A\s*(?:function|command)\b|[A-Za-z]*c)/,
-    /\b(?:declare|typeset)\b[^\n;|&]*\s[+-][A-Za-z]*[fF]/,
-    /(?:^|[\s;|&(`])(?:whence|which|where|type)\s[^\n;|&]*-[A-Za-z]*m/,
-    /(?:^|[^\w.-])set\s*(?:$|[|;&)`])/,
-  ]
-    .map(({ source }) => source)
-    .join('|'),
-  'm',
-)
-
-/**
- * Whether a program expanded from a variable or a substitution (`f=shipit; $f`) may call a function of the snapshot
- * whose body names one of `programs`. Only a function whose name stands as a word in `text` counts: the script as
- * written and its decoded words, where a variable or substitution would take the name from. The shell expands no alias
- * from an expansion. `definitions` is called only when such a program stands in the command.
- */
-export const mayRunDefinedFunction = (
-  words: SimpleCommand,
-  definitions: () => ShellDefinitions,
-  programs: readonly string[],
-  text: string,
-): boolean => {
-  if (!words.some((_word, index) => isExpandedProgram(words, index))) return false
-  const known = definitions()
-  const searched = withExpansionOperands(text)
-  const anyName = READS_FUNCTION_TABLE.test(text)
-  return [...known.functions].some(
-    ([name, body]) => (anyName || namesWord(searched, name)) && runsProgram(known, body, programs, new Set()),
-  )
-}
-
 const shown = (body: string): string => {
   const line = body.trim().replace(/\s+/g, ' ')
   return line.length > SHOWN_BODY_LENGTH ? `${line.slice(0, SHOWN_BODY_LENGTH)}…` : line

package/kit/hooks/hooks/{ask-hint → shared}/transcript.ts

@@ -1,5 +1,13 @@
+import { isRecord } from './json'
+
 export type Turn = { firstPrompt: string; tools: string[] }
 
+/** A lane prompt names the lane in its first line. */
+const LANE_PROMPT = /^\s*(<pasted_content[^>]*>\s*)?(Du bist die Spur|You are the lane)/i
+
+/** Whether the session's first prompt opens a lane (`jh lane prompt`); a lane asks the coordinator, not the user. */
+export const isLanePrompt = (firstPrompt: string): boolean => LANE_PROMPT.test(firstPrompt)
+
 type Entry = {
   type?: unknown
   isMeta?: unknown
@@ -7,7 +15,10 @@ type Entry = {
   message?: { content?: unknown }
 }
 
-type Block = { type?: unknown; text?: unknown; name?: unknown }
+type Block = { type?: unknown; text?: unknown; name?: unknown; input?: unknown }
+
+/** A tool call of the transcript: the tool's name and its input, `{}` when it has none. */
+export type ToolUse = { name: string; input: Record<string, unknown> }
 
 const parseEntries = (jsonl: string): Entry[] =>
   jsonl.split('\n').flatMap((line) => {
@@ -33,11 +44,29 @@ const promptText = (entry: Entry): string | undefined => {
   return texts.length > 0 ? texts.join('\n') : undefined
 }
 
-const toolNames = (entry: Entry): string[] =>
+const toolUses = (entry: Entry): ToolUse[] =>
   entry.type === 'assistant'
-    ? blocks(entry).flatMap((block) => (block.type === 'tool_use' && typeof block.name === 'string' ? [block.name] : []))
+    ? blocks(entry).flatMap((block) =>
+        block.type === 'tool_use' && typeof block.name === 'string'
+          ? [{ name: block.name, input: isRecord(block.input) ? block.input : {} }]
+          : [],
+      )
     : []
 
+/** Every tool call of the transcript lines, in order; a line that does not parse is skipped. */
+export const toolUsesOf = (jsonl: string): ToolUse[] => parseEntries(jsonl).flatMap(toolUses)
+
+const firstPromptAmong = (entries: readonly Entry[]): string => {
+  for (const entry of entries) {
+    const text = promptText(entry)
+    if (text !== undefined) return text
+  }
+  return ''
+}
+
+/** The first prompt typed in the session, `''` without one. */
+export const firstPromptOf = (jsonl: string): string => firstPromptAmong(parseEntries(jsonl))
+
 /**
  * The first prompt of the session and the tools the current turn used. The turn starts at the last prompt carrying
  * `promptId` (the Stop input's `prompt_id`), else at the last prompt of the transcript.
@@ -47,9 +76,11 @@ export const readTurn = (jsonl: string, promptId: string | undefined): Turn => {
   const prompts = entries.flatMap((entry, index) => (promptText(entry) === undefined ? [] : [index]))
   const ofTurn = prompts.filter((index) => promptId !== undefined && entries[index].promptId === promptId)
   const start = (ofTurn.length > 0 ? ofTurn : prompts).at(-1) ?? entries.length
-  const first = prompts[0]
   return {
-    firstPrompt: first === undefined ? '' : (promptText(entries[first]) ?? ''),
-    tools: entries.slice(start).flatMap(toolNames),
+    firstPrompt: firstPromptAmong(entries),
+    tools: entries
+      .slice(start)
+      .flatMap(toolUses)
+      .map(({ name }) => name),
   }
 }