jackherd 1.8.1 → 1.9.0

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

@@ -1,14 +1,15 @@
 import type { DialogAnswer } from '../shared/dialog-answer'
 import { ASK_USER_QUESTION_TOOL } from '../shared/dialog-answers'
 import { isFresh } from '../shared/fresh'
-import { laneOfAgent } from '../shared/lane'
+import { isCoordinatorAgent, laneOfAgent } from '../shared/lane'
 import type { PaneAgent } from '../shared/pane-agent'
 import { gateDecision, type GateLabels } from './decision'
 import { type ApprovalRequest, callHash, type GateCall, isStorableInput, newRequest, requestId } from './request'
 import { gateSettingsOf } from './settings'
+import { type SubagentCall, subagentLabel } from './subagent'
 
-/** A call as the client's hook hands it over, before it is known to be a lane's. */
-export type ClientCall = { cwd: string; session: string; tool: string; input: unknown }
+/** A call as the client's hook hands it over, before it is known to be a lane's; `subagent` when a subagent makes it. */
+export type ClientCall = { cwd: string; session: string; tool: string; input: unknown; subagent?: SubagentCall }
 
 /** What the gate decided; null decides nothing, so the client's own dialog stays. */
 export type GateOutcome = { kind: 'allow' } | { kind: 'denied' } | { kind: 'pending' } | null
@@ -18,6 +19,8 @@ export type GateDependencies = {
   /** The agent of the multiplexer pane this session runs in; null outside the multiplexer. */
   paneAgent: () => PaneAgent | null
   mainCheckoutOf: (cwd: string) => string
+  /** Whether a worktree of this name exists below the main checkout's worktree directory. */
+  isLaneName: (main: string, name: string) => boolean
   config: (main: string) => Record<string, unknown>
   readRequests: (main: string) => ApprovalRequest[]
   writeRequest: (main: string, request: ApprovalRequest) => void
@@ -75,11 +78,31 @@ const awaitDecision = async (
 /** A question to the user asks for an answer, not for a permission: the lane asks the coordinator in its text instead. */
 const isHeld = ({ tool, input }: ClientCall): boolean => tool !== ASK_USER_QUESTION_TOOL && isStorableInput(input)
 
+/**
+ * What holds the call: the lane of the pane's agent, else, for a subagent of the coordinator, its own name. The
+ * coordinator's session is the one the hook was called for, and the agent of the pane started in the main checkout
+ * under no lane's name; the subagent's permission dialog would open in that pane.
+ */
+const holderOf = (
+  clientCall: ClientCall,
+  agent: PaneAgent,
+  main: string,
+  worktreeDirectory: string,
+  dependencies: GateDependencies,
+): string | null => {
+  const lane = laneOfAgent({ agent, session: clientCall.session, main, worktreeDirectory })
+  if (lane || !clientCall.subagent) return lane
+  const isLane = (name: string) => dependencies.isLaneName(main, name)
+  const coordinator = isCoordinatorAgent({ agent, session: clientCall.session, main, isLane })
+  return coordinator ? subagentLabel(clientCall.subagent) : null
+}
+
 /**
  * The gate for a call that would open a permission dialog in a lane: it records the call as a request the watcher
  * reports, waits for the user's answer to the coordinator's dialog, and allows or denies. The lane is the agent of the
- * pane, never the directory of the call. Outside a lane, for a question or a call too large to store, and on any failure
- * (the multiplexer or git cannot be asked), it decides nothing, so the dialog stays.
+ * pane, never the directory of the call; a subagent of the coordinator is held like one, under its own name. Outside a
+ * lane, for a question or a call too large to store, and on any failure (the multiplexer or git cannot be asked), it
+ * decides nothing, so the dialog stays.
  */
 export const runGate = async (
   clientCall: ClientCall,
@@ -92,7 +115,7 @@ export const runGate = async (
     if (agent === null || agent.cwd === null) return null
     const main = dependencies.mainCheckoutOf(agent.cwd)
     const { worktreeDirectory, waitMinutes } = gateSettingsOf(dependencies.config(main))
-    const lane = laneOfAgent({ agent, session: clientCall.session, main, worktreeDirectory })
+    const lane = holderOf(clientCall, agent, main, worktreeDirectory, dependencies)
     if (!lane) return null
     const { cwd, tool, input } = clientCall
     const request = openRequest(main, { lane, cwd, tool, input }, dependencies)

package/kit/hooks/hooks/approval-gate/subagent.ts

@@ -0,0 +1,18 @@
+/** The subagent a hook call comes from: Claude Code's `agent_id` and `agent_type`. */
+export type SubagentCall = { id: string; type: string | null }
+
+/** `agent_id` as Claude Code writes it into the subagent's log (`agent-<id>.jsonl`): lower-case hexadecimal. */
+const AGENT_ID = /^[0-9a-f]{8,64}$/
+const AGENT_TYPE = /^[a-z0-9][a-z0-9-]{0,31}$/
+const ID_LENGTH = 8
+
+/**
+ * The name a subagent of the coordinator is held under, in the place of a lane's name: `subagent-<type>-<id start>`.
+ * The type is a plain word or `agent`, so nothing the subagent could choose freely reaches the coordinator's question;
+ * null for an id of another shape. The herd derives the same name from the subagent's log (contract test).
+ */
+export const subagentLabel = ({ id, type }: SubagentCall): string | null => {
+  if (!AGENT_ID.test(id)) return null
+  const word = type !== null && AGENT_TYPE.test(type) ? type : 'agent'
+  return `subagent-${word}-${id.slice(0, ID_LENGTH)}`
+}

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

@@ -62,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[] }
 
@@ -130,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' }
 
 /**
@@ -276,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. */
@@ -314,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 =>

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.

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

@@ -89,6 +89,9 @@ Always contains:
 - what the lane must not do: push a database migration and any write against a shared environment
   (stage, production) without the user's approval, `git reset` or `git stash` on shared refs
 - "ask before every commit (`/pre-commit`); no push, PR or merge without approval"
+- "before you start a task, 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
 - "a new phase starts with its skeleton in the plan (heading, origin, tasks, review gate) before any
   research, so the herd never shows it as not in the plan"
 - "the report at the end of each step goes to `.claude/handover/<lane>-report.md` in the worktree,
@@ -411,13 +414,14 @@ On wake-up:
 | `deploy …` | Result and target as the run states them, to the user; a target `unknown (…)` is reported as unknown, never guessed. A failed run goes to the user as an `AskUserQuestion`: read the logs now or later |
 | `due <when> · <action>` | An open appointment fell due (**An agreed time**, below); the action is cut to 160 characters, the board row holds it whole. Carry it out as agreed, under the approvals it needs (§ 5), then write the outcome into its status cell in the same turn |
 | `appointment unreadable <when> · <action>` | An open appointment row whose time cannot be read, or a table without a column the watcher needs (`missing columns: …`). Correct the row or the header in the board; until then the appointment never falls due |
-| `heartbeat` | One line of status to the user, also when nothing changed |
+| `heartbeat` | One line of status to the user, also when nothing changed; a resting lane carries `waits on: <question>, <n> open questions` from its report, and `for you (<n>): …` names what still waits on the user (**Anything that waits on the user's answer**, below): remind the user of those items in that line |
 | `gh unavailable` | Tell the user once; herdr watching continues |
 | `lane <name> warn` | One line to the user: the lane's fill and that it hands over at a phase boundary if it rises further; no step in the lane |
 | `lane <name> alert` | § 8: send the lane once the request for its hand-over at the end of its current phase |
 | `approval <name> <id> <tool> · <call>` | A call of the lane waits for the user's approval (§ 4, Approvals); the duty line names the question's mark and labels |
 | `model <name> <id> · board <column>` | The lane's last answer came from a model its board row's model column does not name (every model the column names fits). Switch it while it is idle (§ 2 step 6). A column that is wrong goes to the user instead. The watcher reports a deviation once and again only when the model changes |
 | `parallel <name> P<a> ∥ P<b>` | The lane's plan has ready phases whose `{{kit.heading.writes}}` sets do not overlap and that share no `{{kit.heading.serialMarker}}`, read from the plan's `{{kit.heading.dependencies}}` table and its ticks. Propose them to the user in one line, as parallel lanes (§ 2) or as parallel subagents in one lane (`/implement` Step 0b); nothing starts on the event alone. Before proposing, check what the table cannot see: two phases that collide in content stay your judgement. The watcher reports a set once and again only when the set changes |
+| `parallel tasks <name>: "<a>" ∥ "<b>" · ~<n>k tokens for <m> extra agents` | Open tasks that name paths overlapping neither each other nor what the running agents wrote lately or report (your own subagents in the lane's worktree count as running), at a cost under `watch.parallelTasks.maxTokens`; one free task beside a running agent counts. Once per changed situation, at a heartbeat. Nothing starts on the line. Put it to the user at once, never into an open dialog (right after it), the user's note read first: at most three plain lines (which tasks, why they do not collide, the cost: model and token baseline of a new agent, and what they wait for otherwise; no invented time saving), then one `AskUserQuestion` of at most 15 words, "start in parallel" (recommended only under the threshold; `Parallel starten` / `Nacheinander lassen` for a German user) or "keep in sequence". Until the answer it is a `?` row in the user's answers section (**Anything that waits on the user's answer**). No second proposal for the same situation after "keep in sequence". Two tasks that collide in content stay your judgement |
 | `coordinator warn` / `coordinator alert` | § 8, for yourself |
 | `lane added: <name>` | Nothing: the lane is watched. Check that it has its row (§ 2 step 5); a name `<lane>-<purpose>` without a worktree is a helper agent of that lane (§ 1) and needs no row. One the lane did not announce goes to the user |
 | `lane removed: <name>` | Nothing after you closed it (§ 7). Otherwise its agent exited or its worktree is gone: read why, then tell the user |
@@ -454,6 +458,20 @@ watcher reports an open row once when it falls due (`due`, below); an empty stat
 and a reworded or moved row is a new appointment and reports again. Close a reported row through its
 status cell.
 
+**Anything that waits on the user's answer** (a preview or a file sent to them, a question put to them, a
+report handed over for acceptance) goes into the board at once, in the section `## Wartet auf dich` (German
+plans) or `## Waiting for you` (English), one row `Since | Item | Origin | Status` (`Seit | Punkt | Herkunft |
+Stand`) with the time as in **An agreed time**. The section survives a hand-over, which a message in this chat
+does not. Enter the row in the same turn you send the thing, not when you notice it was missed. The herd shows
+every open row on top as `for you`, and the watcher repeats them in each heartbeat and status until the
+row is closed. Close a row in its status cell in the turn the user's answer arrives (also when the answer is "no"),
+or when the thing is withdrawn; an empty status counts as open. A file sent with `SendUserFile` and an Artifact you publish need no row of your own: the kit hook
+`sent-file` records each in `.jackherd/sent/`, and the herd, the heartbeat and the status line list the open
+ones next to the board's rows (by file name, without an id). The herd also shows them as 📎 badges on the lane
+they belong to. Close them after the answer with `jh waiting close <id>` (or `--all`); `jh waiting` lists
+what is open, with the ids. A question that is answered in a dialog needs no row, since the dialog is the wait. A watcher event or a lane's report is no row either, unless the answer to it is
+the user's.
+
 **A new idea during a release** (the user's or your own, while a plan's phases run toward one
 release) is a line in the plan's `## Follow-ups` section, with its origin, and one line to the user:
 no dialog, no new phase. It enters the release at once only when the release would otherwise be
@@ -522,15 +540,21 @@ Question: Retry the failed check, or leave it?
 ```
 
 **A draft for review.** A lane's draft that the user reviews (a README, a page, a plan) goes in
-rounds. Show it where the user can read it: rendered, when this session can publish a page,
-otherwise the file path. Ask through `AskUserQuestion` with `multiSelect`, one option per remark,
-send the chosen remarks to the lane, and show the same place again once the lane has changed it.
-The push waits for the approval of the last round.
+rounds. Show it where the user can read it. When this session has the `Artifact` tool and `preview.publish`
+in `.jackherd/config.json` is not `false` (default `true`), render the draft with `jh preview <file>`
+(GitHub and npm side by side, external images embedded) and publish that page as a private Artifact; every
+later round updates the same URL (`url` on the publish call), so the user keeps one link. Without the tool
+(another provider, Codex) or with `preview.publish` off, send the page as a file card (`SendUserFile`) or
+tell the user to run `jh preview --open`; a bare file path is the last resort. Ask through
+`AskUserQuestion` with `multiSelect`, one option per remark, send the chosen remarks to the lane, and
+show the same place again once the lane has changed it. The push waits for the approval of the last round.
 
 **Approvals.** In a lane, a call that would open a permission dialog (an ask rule) is held by the
 approval gate hook (a project install ships it; a global install has none, and the dialog stays in
 the lane). The hook records the call, the watcher reports `approval <lane> <id> <tool> · <call>`, and
-it waits up to `guard.approvals.waitMinutes` (default 8) for the user's answer. Ask at once, one
+it waits up to `guard.approvals.waitMinutes` (default 8) for the user's answer. A subagent of your own
+session (an `implement` run you started) is held the same way, under the name `subagent-<type>-<id>`
+instead of a lane's; its dialog would otherwise open in your pane and go unnoticed. Ask at once, one
 question per request, through `AskUserQuestion`:
 
 - First read the request, `.jackherd/approvals/<id>.json` in the main checkout, and show its `tool`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jackherd",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "keywords": [
     "claude-code",
     "coding-agents",
@@ -48,6 +48,7 @@
     "!docs/gen",
     "assets",
     "!assets/icons/build.ts",
+    "!assets/icons/version.ts",
     "!assets/branding/outline.ts",
     "recipes",
     "README.md",