jackherd 1.9.0 → 1.10.0

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

package/kit/hooks/hooks/{merge-guard → shared}/xargs-program.ts

@@ -1,5 +1,5 @@
-import { programName, ruleStart } from '../shared/program-position'
-import { expandsBraces, isExpanded, type SimpleCommand, type Word } from '../shared/shell'
+import { programName, ruleStart } from './program-position'
+import { expandsBraces, isExpanded, type SimpleCommand, type Word } from './shell'
 
 /**
  * What an `xargs` call is told to run: the program word (absent when it runs `echo`) and where it stands among the
@@ -11,10 +11,11 @@ type XargsCall = { program: Word | undefined; at: number; replaceStrings: string
 /** One option word read: the words it used up, and the replace string it set, if any. */
 type OptionRead = { width: number; replaceString?: string }
 
-const XARGS = 'xargs'
+export const XARGS = 'xargs'
 const END_OF_OPTIONS = '--'
 const DEFAULT_REPLACE_STRING = '{}'
-const GLOB = /[*?[]/
+/** The characters that make a shell word a glob. */
+export const GLOB = /[*?[]/
 const ECHO: Word = { value: 'echo', literal: true }
 
 /** GNU and BSD short options: with a value (attached or the next word), with a value only when attached, without one. */
@@ -50,7 +51,7 @@ const LONG_REPLACE = '--replace'
  * Programs that read or write the files their arguments name and start nothing, whatever the arguments say: input
  * handed to them by `xargs` stays arguments. A program that runs text or a program its arguments name stays out (`git`
  * with `-c alias.…`, `sed` with `e`, `awk` with `system()`, `rg --pre`, `sort --compress-program`), as does every
- * program not listed: the list is closed, so an unknown program keeps the search of the whole text.
+ * program not listed: the list is closed, so an unknown program keeps every word after `xargs` at a program position.
  */
 const PLAIN_PROGRAMS = new Set([
   'basename',
@@ -166,9 +167,10 @@ const isPlainProgram = (program: Word, replaceStrings: string[], guardedPrograms
 /**
  * An `xargs` at the start of the command that runs a fixed program starting nothing (D77) becomes that program's
  * call, the words before `xargs` kept: its input then only adds arguments, so the program counts like any other call
- * and the text around it is no sign. Without a program it becomes `echo`, which `xargs` then runs. Every other
- * command comes back as it is, so `xargs` stays opaque for a program from an expansion or a replace string, a glob,
- * a guarded program, a starter (a shell, `env`, `xargs`, `timeout`, an interpreter) and any program not on the list.
+ * and its arguments stand at no program position. Without a program it becomes `echo`, which `xargs` then runs. Every
+ * other command comes back as it is, so every word after `xargs` keeps a program position for a program from an
+ * expansion or a replace string, a glob, a guarded program, a starter (a shell, `env`, `xargs`, `timeout`, an
+ * interpreter) and any program not on the list. Used by the merge guard and the git guard (D77, D108).
  */
 export const resolvePlainXargs = (words: SimpleCommand, guardedPrograms: readonly string[]): SimpleCommand => {
   const start = ruleStart(words)

package/kit/hooks/hooks/task-hint/decision.ts

@@ -0,0 +1,49 @@
+import { isRecord } from '../shared/json'
+import { toolUsesOf } from '../shared/transcript'
+
+/**
+ * Whether the hint is on, the session is a lane, a task signal is open, this task was hinted already, and the call
+ * started a subagent.
+ */
+export type TaskHintInput = { enabled: boolean; lane: boolean; signalled: boolean; hinted: boolean; subagent: boolean }
+
+/** Whether to hint now, and the mark to keep: set once hinted, cleared by a signal so the next task is hinted again. */
+export type TaskHintDecision = { hint: boolean; hinted: boolean }
+
+const IN_PROGRESS = 'in_progress'
+
+/** The hint the lane reads: a reminder, never a block. */
+export const TASK_HINT_TEXT =
+  'No task signal is open: report the task you work on with `jh task start "<task>"` (and `jh task done` when it is finished), so the herd shows it.'
+
+/** The hint after a subagent started: a review runs as one, and the herd shows it as active only with a signal. */
+export const TASK_HINT_SUBAGENT_TEXT =
+  'A subagent started without an open task signal: report what it works on, a review by its gate item, with `jh task start "<item>"` (and `jh task done` when it is finished), so the herd shows it as active.'
+
+/**
+ * Hint a lane once per task while no signal is open, and at every subagent it starts without one; the coordinator and a
+ * switched-off hint never.
+ */
+export const decideTaskHint = ({ enabled, lane, signalled, hinted, subagent }: TaskHintInput): TaskHintDecision => {
+  if (signalled) return { hint: false, hinted: false }
+  if (!enabled || !lane) return { hint: false, hinted }
+  return { hint: subagent || !hinted, hinted: true }
+}
+
+const todosInProgress = (input: Record<string, unknown>): boolean =>
+  Array.isArray(input.todos) && input.todos.some((todo) => isRecord(todo) && todo.status === IN_PROGRESS)
+
+/**
+ * Whether the session's own task list has a task in progress at the end of `lines` (the transcript's tail): an entry of
+ * the last `TodoWrite` in progress, or a `TaskUpdate` that set a task in progress and none after it that moved it on.
+ */
+export const hasTaskInProgress = (lines: readonly string[]): boolean => {
+  let todos = false
+  const tasks = new Map<string, boolean>()
+  for (const { name, input } of toolUsesOf(lines.join('\n'))) {
+    if (name === 'TodoWrite') todos = todosInProgress(input)
+    if (name === 'TaskUpdate' && input.taskId !== undefined && input.status !== undefined)
+      tasks.set(String(input.taskId), input.status === IN_PROGRESS)
+  }
+  return todos || [...tasks.values()].some(Boolean)
+}

package/kit/hooks/hooks/task-hint/index.ts

@@ -0,0 +1,79 @@
+// PostToolUse hook of Claude Code for Edit, Write and Agent, shipped by jackherd: in a lane without an open task signal
+// it adds the reminder to report the task with `jh task start`, once per task and at every subagent it starts
+// (`additionalContext`, never a block; a subagent in the background starts the hook right after its launch).
+// Anything else, and any failure, answers nothing.
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs'
+import { mainCheckoutOf, projectAndHomeConfigs, repositoryRootOf } from '../shared/checkout'
+import { isRecord } from '../shared/json'
+import { runTaskHint, type TaskHintCall, type TaskHintDependencies } from './run'
+import { openTaskDirectories, readHintMark, writeHintMark } from './store'
+
+const HOOK_EVENT = 'PostToolUse'
+/** The first prompt sits at the start of a transcript; a pasted prompt is rarely longer. */
+const HEAD_BYTES = 256 * 1024
+/** The task list's latest state is near the end; a long turn without one falls back to the hint. */
+const TAIL_BYTES = 2 * 1024 * 1024
+
+/** The lines of at most `bytes` bytes of the file, from the offset `startOf(size, length)`, and whether that is all of it. */
+const readRange = (
+  path: string,
+  bytes: number,
+  startOf: (size: number, length: number) => number,
+): { lines: string[]; whole: boolean } => {
+  const descriptor = openSync(path, 'r')
+  try {
+    const { size } = fstatSync(descriptor)
+    const length = Math.min(size, bytes)
+    const buffer = Buffer.alloc(length)
+    readSync(descriptor, buffer, 0, length, startOf(size, length))
+    return { lines: buffer.toString('utf8').split('\n'), whole: length === size }
+  } finally {
+    closeSync(descriptor)
+  }
+}
+
+/** The whole lines of the first `bytes` bytes of the file; a line cut at the end is dropped. */
+const readHeadLines = (path: string, bytes: number): string[] => {
+  const { lines, whole } = readRange(path, bytes, () => 0)
+  return whole ? lines : lines.slice(0, -1)
+}
+
+/** The whole lines of the last `bytes` bytes of the file; a line cut at the start is dropped. */
+const readTailLines = (path: string, bytes: number): string[] => {
+  const { lines, whole } = readRange(path, bytes, (size, length) => size - length)
+  return whole ? lines : lines.slice(1)
+}
+
+const dependencies: TaskHintDependencies = {
+  mainCheckoutOf,
+  repositoryRootOf,
+  configs: projectAndHomeConfigs,
+  readHead: (path) => readHeadLines(path, HEAD_BYTES),
+  readTail: (path) => readTailLines(path, TAIL_BYTES),
+  openTaskDirectories,
+  readMark: readHintMark,
+  writeMark: writeHintMark,
+}
+
+/** Claude Code's hook input: `session_id`, `cwd` and `transcript_path`. */
+const callOf = (text: string): TaskHintCall | null => {
+  const input: unknown = JSON.parse(text)
+  if (!isRecord(input)) return null
+  const { session_id: session, cwd, transcript_path: transcriptPath, tool_name: tool } = input
+  return typeof session === 'string' && typeof cwd === 'string' && typeof transcriptPath === 'string'
+    ? { session, cwd, transcriptPath, tool: typeof tool === 'string' ? tool : '' }
+    : null
+}
+
+const decide = async (): Promise<string | null> => {
+  try {
+    const call = callOf(await Bun.stdin.text())
+    return call ? runTaskHint(call, dependencies) : null
+  } catch {
+    return null
+  }
+}
+
+const hint = await decide()
+if (hint) console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: HOOK_EVENT, additionalContext: hint } }))
+process.exit(0)