jackherd 1.8.0 → 1.9.0

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

@@ -26,6 +26,7 @@ import {
   shellDefinitionAt,
   shellDefinitionHint,
 } from '../shared/shell-aliases'
+import { resolvePlainXargs } from './xargs-program'
 
 export type MergeGuardDecision = { kind: 'pass' } | { kind: 'ask'; reason: string }
 
@@ -61,6 +62,9 @@ type Finding = { command: string; merge: PlainMerge | undefined; definition?: Sh
 /** What the search looks for: the guarded commands, and the shell definitions that may stand for one of them. */
 type Search = { commands: readonly string[]; definitions: () => ShellDefinitions }
 
+/** A whole token of a script's text; `joined` when only blanks, quotes, commas and brackets stand before it. */
+type TextToken = { value: string; end: number; joined: boolean }
+
 /** The parts of a `gh api` call that decide whether it writes, and where. */
 type ApiCall = { method: Word | undefined; fields: boolean; override: boolean; endpoints: Word[] }
 
@@ -129,6 +133,16 @@ const DANGEROUS_MENTION = /\b(merges?|contents|dispatches|rerun|refs)\b/
 const EXPANDED_FUNCTION_NOTE =
   'The program is expanded from a variable or a substitution and may name a shell function that runs one of guard.commands in .jackherd/config.json, so the user confirms it.'
 
+/** A run of characters that no quote, comma, bracket, backslash, `+`, blank or shell operator ends. */
+const TEXT_TOKEN = /[^\s'"`,()[\]{}\\+;&|<>]+/g
+/** What may stand between two command words in program text: `"gh", "workflow"`, `"gh workflow " + "run"`, `\"gh`. */
+const WORD_GAP = /^[\s'"`,()[\]{}\\+]*$/
+/**
+ * Options and their values a command word may be separated by (`workflow -R o/r run`; gh takes flags before the
+ * subcommand, too); more ends the search, so a long run of options cannot stall it.
+ */
+const MAX_TOKENS_BETWEEN_WORDS = 16
+
 const PASS: MergeGuardDecision = { kind: 'pass' }
 
 /**
@@ -275,10 +289,10 @@ const apiArguments = (words: SimpleCommand, index: number): Word[] => {
 const isGuardedUse = (command: string, words: SimpleCommand, programIndex: number): boolean =>
   command !== API_COMMAND || writesDangerously(apiArguments(words, programIndex))
 
-/** In text the parse cannot see, `api` followed by the end of a dangerous endpoint is the sign; the method is unknown. */
-const mentionsDangerousApiCall = (script: string): boolean => {
-  const at = findWord(script, API_WORD, 0)
-  return at !== -1 && DANGEROUS_MENTION.test(script.slice(at))
+/** In text the parse cannot see, the token `api` followed by the end of a dangerous endpoint is the sign; the method is unknown. */
+const mentionsDangerousApiCall = (script: string, tokens: TextToken[]): boolean => {
+  const api = tokens.find(({ value }) => value === API_WORD)
+  return api !== undefined && DANGEROUS_MENTION.test(script.slice(api.end))
 }
 
 /** `sole`: the script is this one simple command, written plainly, the only shape an approval can lift. */
@@ -313,33 +327,67 @@ const callsOfWord = (words: SimpleCommand, index: number, search: Search, sole:
   return guarded.flatMap((command) => findingOf(command, words, index, sole && index === 0) ?? [])
 }
 
-const isWordCharacter = (character: string | undefined): boolean => character !== undefined && /\w/.test(character)
-
-const findWord = (script: string, word: string, from: number): number => {
-  for (let at = script.indexOf(word, from); at !== -1; at = script.indexOf(word, at + 1)) {
-    if (!isWordCharacter(script[at - 1]) && !isWordCharacter(script[at + word.length])) return at
+/**
+ * The script cut into whole tokens: a path (`kit/workflow/skills`) or a dotted name (`subprocess.run`) is one token,
+ * while quotes, commas, brackets and shell operators end one, so `["gh", "workflow", "run"]` gives three.
+ */
+const textTokens = (script: string): TextToken[] => {
+  const tokens: TextToken[] = []
+  let previousEnd = 0
+  for (const match of script.matchAll(TEXT_TOKEN)) {
+    const end = match.index + match[0].length
+    const joined = WORD_GAP.test(script.slice(previousEnd, match.index))
+    tokens.push({ value: match[0], end, joined })
+    previousEnd = end
   }
-  return -1
+  return tokens
 }
 
-/** Whether the script names the words as whole words in this order; a linear search, so a long script cannot stall it. */
-const namesInOrder = (script: string, words: string[]): boolean => {
-  let from = 0
+const isOptionToken = (value: string): boolean => value.length > 1 && value.startsWith('-')
+
+/**
+ * Whether the tokens from `start` on spell the words, each joined to the one before: only quotes, commas, brackets and
+ * blanks between them, and options such as `-R o/r` that `gh` takes between its command words. From the first option
+ * on, any joined token may follow, since brackets and braces cut a value such as `"${REPO}"` or `REPOS[0]` into
+ * several tokens; without an option before it, a word between the command words ends the match. A bounded walk, so a
+ * long script cannot stall it.
+ */
+const spellsFrom = (tokens: TextToken[], start: number, words: string[]): boolean => {
+  let index = start
   for (const word of words) {
-    const at = findWord(script, word, from)
-    if (at === -1) return false
-    from = at + word.length
+    let skipped = 0
+    let optionSeen = false
+    while (tokens[index]?.joined && tokens[index].value !== word && skipped < MAX_TOKENS_BETWEEN_WORDS) {
+      optionSeen ||= isOptionToken(tokens[index].value)
+      if (!optionSeen) return false
+      skipped++
+      index++
+    }
+    if (!tokens[index]?.joined || tokens[index].value !== word) return false
+    index++
   }
   return true
 }
 
-/** Where the program is hidden or the words are handed over as text, the command words after the program are the sign. */
-const mentionedCommandWords = (script: string, commands: readonly string[]): Finding[] =>
-  commands
+/** Whether the words stand adjacent somewhere in the tokens, in this order. */
+const spellsWords = (tokens: TextToken[], [first, ...rest]: string[]): boolean =>
+  first === undefined || tokens.some(({ value }, index) => value === first && spellsFrom(tokens, index + 1, rest))
+
+/**
+ * Where the program is hidden or the words are handed over as text, the command words after the program, standing
+ * adjacent as whole tokens, are the sign: `$g workflow run` and `["gh", "workflow", "run"]` count, a path segment
+ * `workflow` and a `run` elsewhere in the script do not.
+ */
+const mentionedCommandWords = (script: string, commands: readonly string[]): Finding[] => {
+  const tokens = textTokens(script)
+  return commands
     .filter((command) =>
-      command === API_COMMAND ? mentionsDangerousApiCall(script) : namesInOrder(script, command.split(' ').slice(1)),
+      command === API_COMMAND
+        ? mentionsDangerousApiCall(script, tokens)
+        : spellsWords(tokens, command.split(' ').slice(1)),
     )
     .map((command) => ({ command, merge: undefined }))
+}
 
 /** A program expanded from a variable or a substitution could be the guarded one. */
 const runsExpandedProgram = (words: SimpleCommand): boolean =>
@@ -423,7 +471,8 @@ const callsInScriptWide = (whole: string, parsed: SimpleCommand[], commands: rea
 
 /** `whole` is the text of the outermost script: a nested script's input comes from there, so the words are searched in it. */
 const callsIn = (script: string, search: Search, top: boolean, whole: string): Finding[] => {
-  const parsed = parseShell(script)
+  const guardedPrograms = programsOf(search.commands)
+  const parsed = parseShell(script).map((words) => resolvePlainXargs(words, guardedPrograms))
   const sole = top && parsed.length === 1 && !script.trimStart().startsWith('(')
   const text = searchableText(whole, parsed)
   return [

package/kit/hooks/hooks/merge-guard/xargs-program.ts

@@ -0,0 +1,182 @@
+import { programName, ruleStart } from '../shared/program-position'
+import { expandsBraces, isExpanded, type SimpleCommand, type Word } from '../shared/shell'
+
+/**
+ * What an `xargs` call is told to run: the program word (absent when it runs `echo`) and where it stands among the
+ * words after `xargs`, and the strings `-I`, `-i`, `--replace` or BSD's `-J` replace with the input, which may stand
+ * anywhere, the program included.
+ */
+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'
+const END_OF_OPTIONS = '--'
+const DEFAULT_REPLACE_STRING = '{}'
+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. */
+const SHORT_WITH_VALUE = new Set(['a', 'd', 'E', 'I', 'J', 'L', 'n', 'P', 'R', 's', 'S'])
+const SHORT_WITH_ATTACHED_VALUE = new Set(['e', 'i', 'l'])
+const SHORT_FLAGS = new Set(['0', 'o', 'p', 'r', 't', 'x'])
+const SHORT_REPLACE = new Set(['I', 'J'])
+const SHORT_OLD_REPLACE = 'i'
+
+const LONG_WITH_VALUE = new Set([
+  '--arg-file',
+  '--delimiter',
+  '--max-args',
+  '--max-chars',
+  '--max-procs',
+  '--process-slot-var',
+])
+const LONG_WITH_ATTACHED_VALUE = new Set(['--eof', '--max-lines', '--replace'])
+const LONG_FLAGS = new Set([
+  '--exit',
+  '--help',
+  '--interactive',
+  '--no-run-if-empty',
+  '--null',
+  '--open-tty',
+  '--show-limits',
+  '--verbose',
+  '--version',
+])
+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.
+ */
+const PLAIN_PROGRAMS = new Set([
+  'basename',
+  'cat',
+  'chmod',
+  'dirname',
+  'du',
+  'echo',
+  'egrep',
+  'fgrep',
+  'file',
+  'grep',
+  'head',
+  'jq',
+  'ls',
+  'md5sum',
+  'mkdir',
+  'printf',
+  'readlink',
+  'realpath',
+  'rm',
+  'rmdir',
+  'sha1sum',
+  'sha256sum',
+  'shasum',
+  'stat',
+  'tail',
+  'touch',
+  'tr',
+  'uniq',
+  'wc',
+])
+
+/**
+ * A word the shell hands over as written, quotes and escapes aside: an expansion, a glob or braces could become
+ * several words, or none, and shift which word is the program.
+ */
+const isFixed = ({ value }: Word): boolean => !isExpanded(value) && !GLOB.test(value) && !expandsBraces(value)
+
+/** A value in the next word must be there and fixed. */
+const nextValue = (words: Word[], index: number): Word | undefined => {
+  const next = words[index + 1]
+  return next !== undefined && isFixed(next) ? next : undefined
+}
+
+const readLongOption = (words: Word[], index: number): OptionRead | undefined => {
+  const { value } = words[index]
+  const at = value.indexOf('=')
+  const name = at === -1 ? value : value.slice(0, at)
+  const attached = at === -1 ? undefined : value.slice(at + 1)
+  if (LONG_WITH_VALUE.has(name)) {
+    if (attached !== undefined) return { width: 1 }
+    return nextValue(words, index) ? { width: 2 } : undefined
+  }
+  if (LONG_WITH_ATTACHED_VALUE.has(name)) {
+    const replaceString = name === LONG_REPLACE ? (attached ?? DEFAULT_REPLACE_STRING) : undefined
+    return { width: 1, replaceString }
+  }
+  return LONG_FLAGS.has(name) && attached === undefined ? { width: 1 } : undefined
+}
+
+/** A short option that takes a value: the rest of its word, or the next word when nothing is attached. */
+const readShortValue = (words: Word[], index: number, letter: string, attached: string): OptionRead | undefined => {
+  if (attached !== '') return { width: 1, replaceString: SHORT_REPLACE.has(letter) ? attached : undefined }
+  const separate = nextValue(words, index)
+  if (separate === undefined) return undefined
+  return { width: 2, replaceString: SHORT_REPLACE.has(letter) ? separate.value : undefined }
+}
+
+/** A cluster of short options (`-0rn1`, `-tI{}`): flags, then at most one option that takes the rest as its value. */
+const readShortOptions = (words: Word[], index: number): OptionRead | undefined => {
+  const { value } = words[index]
+  for (let at = 1; at < value.length; at++) {
+    const letter = value[at]
+    if (SHORT_FLAGS.has(letter)) continue
+    const attached = value.slice(at + 1)
+    if (SHORT_WITH_VALUE.has(letter)) return readShortValue(words, index, letter, attached)
+    if (!SHORT_WITH_ATTACHED_VALUE.has(letter)) return undefined
+    const replaceString = letter === SHORT_OLD_REPLACE ? attached || DEFAULT_REPLACE_STRING : undefined
+    return { width: 1, replaceString }
+  }
+  return { width: 1 }
+}
+
+const readOption = (words: Word[], index: number): OptionRead | undefined =>
+  words[index].value.startsWith('--') ? readLongOption(words, index) : readShortOptions(words, index)
+
+/**
+ * Reads the words after `xargs` up to its program. An option this guard does not know, or a word before the program
+ * that is not fixed, makes the call unreadable: undefined.
+ */
+const readXargsCall = (args: Word[]): XargsCall | undefined => {
+  const replaceStrings: string[] = []
+  for (let index = 0; index < args.length; ) {
+    const word = args[index]
+    if (!isFixed(word)) return undefined
+    if (word.value === END_OF_OPTIONS) return { program: args[index + 1], at: index + 1, replaceStrings }
+    if (!word.value.startsWith('-') || word.value === '-') return { program: word, at: index, replaceStrings }
+    const option = readOption(args, index)
+    if (option === undefined) return undefined
+    if (option.replaceString !== undefined) replaceStrings.push(option.replaceString)
+    index += option.width
+  }
+  return { program: undefined, at: args.length, replaceStrings }
+}
+
+const isPlainProgram = (program: Word, replaceStrings: string[], guardedPrograms: readonly string[]): boolean =>
+  isFixed(program) &&
+  !replaceStrings.some((replaceString) => program.value.includes(replaceString)) &&
+  PLAIN_PROGRAMS.has(program.value) &&
+  !guardedPrograms.includes(program.value)
+
+/**
+ * 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.
+ */
+export const resolvePlainXargs = (words: SimpleCommand, guardedPrograms: readonly string[]): SimpleCommand => {
+  const start = ruleStart(words)
+  if (words[start] === undefined || programName(words[start]) !== XARGS) return words
+  const call = readXargsCall(words.slice(start + 1))
+  if (call === undefined) return words
+  const prefix = words.slice(0, start)
+  if (call.program === undefined) return [...prefix, ECHO]
+  if (!isPlainProgram(call.program, call.replaceStrings, guardedPrograms)) return words
+  return [...prefix, ...words.slice(start + 1 + call.at)]
+}

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)

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,18 @@
+import { chmodSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { ensurePrivateDirectory, PRIVATE_FILE } 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')
+
+/** Writes the record through a temporary file, so a reader never sees half of it. */
+export const writeSentRecord = (main: string, record: SentRecord): void => {
+  const directory = sentDirectory(main)
+  ensurePrivateDirectory(directory)
+  const path = join(directory, `${record.id}.json`)
+  const temporary = `${path}.${process.pid}.tmp`
+  writeFileSync(temporary, `${JSON.stringify(record)}\n`, { mode: PRIVATE_FILE })
+  chmodSync(temporary, PRIVATE_FILE)
+  renameSync(temporary, path)
+}

package/kit/hooks/hooks/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.json

@@ -70,6 +70,15 @@
       "timeout": 10
     }
   },
+  "sent-file": {
+    "event": "PostToolUse",
+    "matcher": "SendUserFile|Artifact",
+    "handler": {
+      "type": "command",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/sent-file/index.ts",
+      "timeout": 10
+    }
+  },
   "watch-guard": {
     "event": "PreToolUse",
     "matcher": "Bash",

package/kit/hooks/statusline.sh

@@ -52,7 +52,7 @@ worktrees='.claude/worktrees'
 [ -n "$config" ] && worktrees=$(jq -r '.worktreeDirectory // ".claude/worktrees"' "$config" 2>/dev/null)
 case "${cwd:-$PWD}/" in
   */"$worktrees"/*) block='.plans.context'; warn_at=250000; alert_at=350000 ;;
-  *) block='.plans.context.coordinator'; warn_at=200000; alert_at=300000 ;;
+  *) block='.plans.context.coordinator'; warn_at=350000; alert_at=500000 ;;
 esac
 if [ -n "$config" ]; then
   warn=$(jq -r "$block.warnTokens // empty | floor" "$config" 2>/dev/null)

package/kit/workflow/skills/implement/SKILL.md

@@ -48,6 +48,8 @@ Before you write a single line:
 
 ## Step 2: Implement
 
+**Report each task before you start it.** Mark it in progress in your own task list; without one, run `jh task start "<task text>"`, and `jh task done` when it is finished. The herd shows the task you work on from that signal.
+
 **Money, identifiers, state transitions: the test comes first** — write it, run it, see it red, then implement. `.claude/rules/kit/testing.md` → Test-first carries the reason.
 
 Follow `.claude/rules/kit/code-style.md`: types → pure functions → higher-order functions, names that reveal intent, no section-label comments.