jackherd 1.8.1 → 1.10.0

package/src/shared/stat-cache.ts

@@ -0,0 +1,48 @@
+import { statSync } from 'node:fs'
+
+/** What tells a file changed without reading it: when it was last written and how large it is. */
+export type FileStamp = { mtimeMs: number; size: number }
+
+type Entry<T> = FileStamp & { value: T }
+
+/** What was read from each file, by path, with the stamp it was read at. */
+export type StatCache<T> = Map<string, Entry<T>>
+
+/** A cache and the keys one round of reads asked for; `dropUnused` clears the rest at the end of the round. */
+export type CacheRound<V> = { entries: Map<string, V>; used: Set<string> }
+
+/** A round over a `StatCache`. */
+export type StatRound<T> = CacheRound<Entry<T>>
+
+const isUnchanged = (entry: FileStamp, stamp: FileStamp): boolean =>
+  entry.mtimeMs === stamp.mtimeMs && entry.size === stamp.size
+
+/** Removes what no read of the round used, so a file that is gone does not stay in the cache. */
+export const dropUnused = (cache: Map<string, unknown>, used: ReadonlySet<string>): void => {
+  for (const key of [...cache.keys()]) if (!used.has(key)) cache.delete(key)
+}
+
+const stampOf = (path: string): FileStamp | null => {
+  try {
+    const { mtimeMs, size } = statSync(path)
+    return { mtimeMs, size }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * What `read` makes of the file, asked again only when its modification time or size changed since the cache saw it.
+ * A file that cannot be stat-ed is read every time and not kept. The `key` (the path unless the result also depends
+ * on something else, such as how much of the file is read) is noted in `used`, for `dropUnused`.
+ */
+export const readCached = <T>(round: StatRound<T>, path: string, read: (path: string) => T, key: string = path): T => {
+  round.used.add(key)
+  const stamp = stampOf(path)
+  if (!stamp) return read(path)
+  const kept = round.entries.get(key)
+  if (kept && isUnchanged(kept, stamp)) return kept.value
+  const value = read(path)
+  round.entries.set(key, { ...stamp, value })
+  return value
+}

package/src/sync/kit-source.ts

@@ -9,10 +9,15 @@ import { parseKitPath } from './kit-path'
 
 export type KitLocation = { kitDirectory: string; version: string; packageRoot: string }
 
-/** What one kit module ships: its files and the text of its `hooks.json`, if any. */
-type KitModule = { name: string; files: KitFile[]; hooksText: string | undefined }
+/** What one kit module ships: its files and the texts of its `hooks.json` and `ask-rules.json`, if any. */
+type KitModule = { name: string; files: KitFile[]; hooksText: string | undefined; askRulesText: string | undefined }
 
 const MODULE_HOOKS_FILE = 'hooks.json'
+const MODULE_ASK_RULES_FILE = 'ask-rules.json'
+/** Files a module ships to sync itself, never into `.claude/`. */
+export const MODULE_DATA_FILES: readonly string[] = [MODULE_HOOKS_FILE, MODULE_ASK_RULES_FILE]
+
+const askRulesSchema = z.array(z.string().min(1))
 
 /** A test beside a kit script runs in this package and never ships into a project. */
 const TEST_FILE = /\.test\.ts$/
@@ -68,6 +73,21 @@ const mergeModuleHooks = (modules: KitModule[]): string | undefined => {
   return Object.keys(merged).length > 0 ? JSON.stringify(merged, null, 2) : undefined
 }
 
+/** The `permissions.ask` rules of every module's `ask-rules.json` (a JSON list of rules), each once, in module order. */
+const mergeModuleAskRules = (modules: KitModule[]): string[] => {
+  const rules = modules.flatMap(({ name, askRulesText }) => {
+    if (askRulesText === undefined) return []
+    const invalid = new Error(`Kit ${name}/${MODULE_ASK_RULES_FILE} is not a JSON list of permission rules`)
+    const parsed = askRulesSchema.safeParse(parseJsonOr(askRulesText, invalid))
+    if (!parsed.success) throw invalid
+    return parsed.data
+  })
+  return [...new Set(rules)]
+}
+
+const readOptional = async (moduleDirectory: string, relatives: string[], file: string): Promise<string | undefined> =>
+  relatives.includes(file) ? readFile(join(moduleDirectory, file), 'utf8') : undefined
+
 const listFiles = async (directory: string, prefix = ''): Promise<string[]> => {
   const entries = await readdir(join(directory, prefix), { withFileTypes: true })
   const nested = await Promise.all(
@@ -94,12 +114,11 @@ const readKitFile = async (moduleDirectory: string, relative: string): Promise<K
 const readModule = async (kitDirectory: string, name: string): Promise<KitModule> => {
   const moduleDirectory = join(kitDirectory, name)
   const relatives = (await listFiles(moduleDirectory)).sort()
-  const filePaths = relatives.filter((relative) => relative !== MODULE_HOOKS_FILE && !TEST_FILE.test(relative))
+  const filePaths = relatives.filter((relative) => !MODULE_DATA_FILES.includes(relative) && !TEST_FILE.test(relative))
   const files = await Promise.all(filePaths.map((relative) => readKitFile(moduleDirectory, relative)))
-  const hooksText = relatives.includes(MODULE_HOOKS_FILE)
-    ? await readFile(join(moduleDirectory, MODULE_HOOKS_FILE), 'utf8')
-    : undefined
-  return { name, files, hooksText }
+  const hooksText = await readOptional(moduleDirectory, relatives, MODULE_HOOKS_FILE)
+  const askRulesText = await readOptional(moduleDirectory, relatives, MODULE_ASK_RULES_FILE)
+  return { name, files, hooksText, askRulesText }
 }
 
 const listModuleNames = async (kitDirectory: string): Promise<string[]> => {
@@ -119,8 +138,8 @@ const listModuleNames = async (kitDirectory: string): Promise<string[]> => {
 /**
  * Reads the kit shipped with the package. Every directory under `kit/` is a module that mirrors
  * `.claude/` (`kit/workflow/skills/plan/SKILL.md` → `.claude/skills/plan/SKILL.md`); a module's
- * `hooks.json` holds its hooks by name, `{ "<name>": { event, matcher?, handler } }`, and is not
- * copied, nor is a `*.test.ts`. Files at the kit root, such as a README, belong to no module.
+ * `hooks.json` holds its hooks by name, `{ "<name>": { event, matcher?, handler } }`, and its
+ * `ask-rules.json` the `permissions.ask` rules a project install adds; neither is copied, nor is a `*.test.ts`. Files at the kit root, such as a README, belong to no module.
  *
  * A missing kit directory, or one without modules, is an error, never an empty kit: an empty kit
  * would make sync remove every untouched kit file from the project.
@@ -134,7 +153,7 @@ export const readKitSource = async ({
   const modules = await Promise.all(names.map((name) => readModule(kitDirectory, name)))
   assertUniquePaths(modules)
   const files = modules.flatMap((module) => module.files).sort((left, right) => (left.path < right.path ? -1 : 1))
-  return { version, files, hooksTemplate: mergeModuleHooks(modules) }
+  return { version, files, hooksTemplate: mergeModuleHooks(modules), askRules: mergeModuleAskRules(modules) }
 }
 
 const readPackageJson = async (path: string) => packageJsonSchema.parse(JSON.parse(await readFile(path, 'utf8')))

package/src/sync/kit.ts

@@ -6,4 +6,6 @@ export type KitSource = {
   files: KitFile[]
   /** The unrendered text of `kit/hooks.json`, if the kit ships hooks. */
   hooksTemplate: string | undefined
+  /** The `permissions.ask` rules of the kit's `ask-rules.json` files; none for a global install. */
+  askRules?: readonly string[]
 }

package/src/sync/manifest.ts

@@ -21,6 +21,8 @@ const manifestSchema = z.strictObject({
     z.string().regex(HOOK_NAME),
     z.strictObject({ base: hookDefinitionSchema, pending: sha256.optional() }),
   ),
+  /** The `permissions.ask` rules sync put into `settings.json`, which it removes once the kit drops them. */
+  askRules: z.array(z.string().min(1)).optional(),
   /** Checksum of the `settings.json.kit-new` sync wrote last. */
   settingsKitNew: sha256.optional(),
 })

package/src/sync/plan-ask-rules.ts

@@ -0,0 +1,94 @@
+import { HOOK_OUTCOME, type HookOutcome } from './plan-hooks'
+import type { Settings } from './settings-hooks'
+
+export type AskRulesInput = {
+  /** The `permissions.ask` rules the kit ships. */
+  kit: readonly string[]
+  /** The rules sync put into the settings before, from the lock. */
+  recorded: readonly string[]
+  settings: Settings
+  /** `--accept .claude/settings.json`: put back a kit rule the user removed. */
+  accept: boolean
+}
+
+export type AskRulesPlan = {
+  settings: Settings
+  changed: boolean
+  /** What the lock records next: every kit rule, a removed one included, so it is not added again. */
+  recorded: string[]
+  outcomes: { name: string; outcome: HookOutcome }[]
+  accepted: boolean
+}
+
+/**
+ * Every rule a jackherd kit has ever shipped in an `ask-rules.json`. Only these are ever removed: a lock is a file in
+ * the project, and a rule it lists that no kit shipped (a tampered lock) stays where it is. Add, never remove.
+ */
+export const SHIPPED_ASK_RULES: readonly string[] = [
+  'Bash(gh run rerun *)',
+  'Bash(gh api *pulls/*/merge*)',
+  'Bash(gh api *merges*)',
+  'Bash(gh api *contents/*)',
+  'Bash(gh api *dispatches*)',
+  'Bash(gh api *rerun*)',
+  'Bash(gh api *git/refs*)',
+  'Bash(jh lane close*)',
+  'Bash(jackherd lane close*)',
+  'Bash(bunx jackherd* lane close*)',
+  'Bash(bun */cli.ts lane close*)',
+  'Bash(bunx jh lane close*)',
+  'Bash(bun x jackherd* lane close*)',
+]
+
+/** How a rule shows in the sync report, beside the hooks. */
+export const askRuleName = (rule: string): string => `permissions.ask ${rule}`
+
+const askOf = (settings: Settings): string[] => {
+  const permissions = settings.permissions
+  const ask =
+    typeof permissions === 'object' && permissions !== null ? (permissions as { ask?: unknown }).ask : undefined
+  return Array.isArray(ask) ? ask.filter((rule): rule is string => typeof rule === 'string') : []
+}
+
+/** The settings with this ask list; an emptied list, and permissions it empties, disappear. Returns a copy. */
+const withAsk = (settings: Settings, ask: string[]): Settings => {
+  const { permissions: _old, ...rest } = settings
+  const { ask: _list, ...otherPermissions } = (settings.permissions ?? {}) as Record<string, unknown>
+  const permissions = ask.length > 0 ? { ...otherPermissions, ask } : otherPermissions
+  return Object.keys(permissions).length > 0 ? { ...rest, permissions } : rest
+}
+
+const outcomeOf = (rule: string, input: AskRulesInput, present: ReadonlySet<string>): HookOutcome => {
+  const shipped = input.kit.includes(rule)
+  if (!shipped)
+    return present.has(rule) && SHIPPED_ASK_RULES.includes(rule) ? HOOK_OUTCOME.removed : HOOK_OUTCOME.dropped
+  if (present.has(rule)) return HOOK_OUTCOME.unchanged
+  if (!input.recorded.includes(rule)) return HOOK_OUTCOME.created
+  return input.accept ? HOOK_OUTCOME.accepted : HOOK_OUTCOME.deselected
+}
+
+const ADDING: readonly HookOutcome[] = [HOOK_OUTCOME.created, HOOK_OUTCOME.accepted]
+
+/**
+ * Merges the kit's ask rules into `permissions.ask`, the way `planHooks` merges hooks. Pure. Only a rule the lock
+ * records and some kit shipped (`SHIPPED_ASK_RULES`) is ever removed, and only once the kit stops shipping it; every other entry stays where it is. A kit rule
+ * the user removed is not put back unless `accept` is set.
+ */
+export const planAskRules = (input: AskRulesInput): AskRulesPlan => {
+  const before = askOf(input.settings)
+  const present = new Set(before)
+  const rules = [...new Set([...input.kit, ...input.recorded])]
+  const decided = rules.map((rule) => ({ rule, outcome: outcomeOf(rule, input, present) }))
+  const removed = new Set(decided.filter(({ outcome }) => outcome === HOOK_OUTCOME.removed).map(({ rule }) => rule))
+  const added = decided.filter(({ outcome }) => ADDING.includes(outcome)).map(({ rule }) => rule)
+  const changed = removed.size > 0 || added.length > 0
+  return {
+    settings: changed
+      ? withAsk(input.settings, [...before.filter((rule) => !removed.has(rule)), ...added])
+      : input.settings,
+    changed,
+    recorded: [...input.kit],
+    outcomes: decided.map(({ rule, outcome }) => ({ name: askRuleName(rule), outcome })),
+    accepted: decided.some(({ outcome }) => outcome === HOOK_OUTCOME.accepted),
+  }
+}

package/src/sync/plan-hooks.ts

@@ -47,6 +47,8 @@ export type HooksPlan = {
   kitNewRecorded: string | undefined
   /** `--accept` was given for the settings but no hook was in conflict or deselected. */
   notAcceptable: boolean
+  /** The kit's `permissions.ask` rules the lock records next (`planAskRules`); none outside a project install. */
+  askRules?: string[]
 }
 
 type HookDecision = {

package/src/sync/render.ts

@@ -4,9 +4,9 @@ import {
   ADDRESS_FORM,
   APPROVAL_TEXTS,
   LANGUAGE_NAME,
-  PLAN_APPROVAL_LABELS,
   PLAN_VOCABULARY,
   SELF_MERGE_LABEL,
+  STANDING_APPROVAL_TEXTS,
 } from '../vocabulary'
 
 const PLACEHOLDER = /\{\{\s*(kit\.[A-Za-z0-9_.-]*)\s*\}\}/g
@@ -47,7 +47,7 @@ const placeholderValues = (config: JackherdConfig): Map<string, string> => {
     ...prefixed('board', config.board),
     ['kit.guard.selfMergeLabel', SELF_MERGE_LABEL[config.responseLanguage]],
     ['kit.guard.selfMerge', config.guard.selfMerge.offer ? 'offered' : 'not offered'],
-    ...prefixed('guard.planApproval', PLAN_APPROVAL_LABELS[config.responseLanguage]),
+    ...prefixed('guard.standingApproval', STANDING_APPROVAL_TEXTS[config.responseLanguage]),
     ...prefixed('approval', APPROVAL_TEXTS[config.responseLanguage]),
     ['kit.merge.withoutChecks', checkFreeList(config.merge.withoutChecks)],
     ...prefixed('heading', { ...header, ...sections, ...columns, phase }),
@@ -61,7 +61,7 @@ export const listPlaceholders = (template: string): string[] =>
 /**
  * Fills the kit placeholders from the project config: `{{kit.model.<role>}}`,
  * `{{kit.command.<test|typecheck|lint|format|install|dev>}}`, `{{kit.lanes.<copyCommand|lockFile|verifyInstall>}}`, `{{kit.word.<laneClosed|openSubagents>}}`,
- * `{{kit.board.<pattern|file|term>}}`, `{{kit.guard.<selfMerge|selfMergeLabel>}}`, `{{kit.guard.planApproval.<approve|revoke>}}`, `{{kit.merge.withoutChecks}}`, `{{kit.heading.<key>}}` from the plan
+ * `{{kit.board.<pattern|file|term>}}`, `{{kit.guard.<selfMerge|selfMergeLabel>}}`, `{{kit.guard.standingApproval.<approve|until>}}`, `{{kit.merge.withoutChecks}}`, `{{kit.heading.<key>}}` from the plan
  * vocabulary, the two languages, `{{kit.responseAddress}}`, the plan and worktree directory and the base branch. Other
  * `{{…}}` text is left alone; an unknown `kit.` placeholder throws rather than reaching a project
  * file unrendered. `overrides` win over the config: a global kit renders what each repository decides as

package/src/sync/settings-hooks.ts

@@ -25,7 +25,10 @@ const hookGroupSchema = z.looseObject({
   hooks: z.array(z.record(z.string(), z.unknown())),
 })
 
-const settingsSchema = z.looseObject({ hooks: z.record(z.string(), z.array(hookGroupSchema)).optional() })
+const settingsSchema = z.looseObject({
+  hooks: z.record(z.string(), z.array(hookGroupSchema)).optional(),
+  permissions: z.looseObject({ ask: z.array(z.string()).optional() }).optional(),
+})
 
 export const parseSettings = (raw: unknown): SettingsResult => {
   const parsed = settingsSchema.safeParse(raw)

package/src/sync/sync-plan.ts

@@ -115,6 +115,7 @@ export const nextManifest = (kitVersion: string, files: FilePlan[], hooks: Hooks
     kitVersion,
     files: Object.fromEntries(files.flatMap(({ path, entry }) => (entry ? [[path, entry]] : []))),
     hooks: hooks.entries,
+    ...(hooks.askRules !== undefined && hooks.askRules.length > 0 ? { askRules: hooks.askRules } : {}),
   }
   return hooks.kitNewRecorded === undefined ? manifest : { ...manifest, settingsKitNew: hooks.kitNewRecorded }
 }

package/src/sync/sync.ts

@@ -15,6 +15,7 @@ import type { KitSource } from './kit'
 import { kitNewPath, toolRootPath } from './kit-path'
 import { moveGlobalLegacyFiles, moveProjectLegacyFiles, removeEmptyLegacyDirectories } from './legacy-files'
 import { EMPTY_MANIFEST, type Manifest, parseManifest, serializeManifest } from './manifest'
+import { planAskRules } from './plan-ask-rules'
 import { FILE_MODE, FILE_OUTCOME, type FileEffect, type FilePlan, planFile, type RenderedFile } from './plan-file'
 import { type HooksPlan, planHooks } from './plan-hooks'
 import {
@@ -191,11 +192,29 @@ const buildPlan = async ({
   return { files, hooks, manifest: nextManifest(kit.version, files, hooks), manifestText }
 }
 
-/** Merges the kit's hooks into the project's `settings.json`. */
+/** The hooks plan with the kit's ask rules merged into the settings it writes, and their outcomes beside the hooks'. */
+const withAskRules = (hooks: HooksPlan, kit: KitSource, manifest: Manifest, accept: AcceptRequest): HooksPlan => {
+  const rules = planAskRules({
+    kit: kit.askRules ?? [],
+    recorded: manifest.askRules ?? [],
+    settings: hooks.settings,
+    accept: accept.settings,
+  })
+  return {
+    ...hooks,
+    settings: rules.settings,
+    changed: hooks.changed || rules.changed,
+    outcomes: [...hooks.outcomes, ...rules.outcomes],
+    notAcceptable: hooks.notAcceptable && !rules.accepted,
+    askRules: rules.recorded,
+  }
+}
+
+/** Merges the kit's hooks and ask rules into the project's `settings.json`. */
 const projectHooks =
   (claudeDirectory: string, kit: KitSource, config: JackherdConfig) =>
-  async (manifest: Manifest, accept: AcceptRequest): Promise<HooksPlan> =>
-    planHooks({
+  async (manifest: Manifest, accept: AcceptRequest): Promise<HooksPlan> => {
+    const hooks = planHooks({
       kit: renderKitHooks(kit, (template) => renderTemplate(template, config)),
       entries: manifest.hooks,
       settings: await readSettings(claudeDirectory),
@@ -203,6 +222,8 @@ const projectHooks =
       kitNewRecorded: manifest.settingsKitNew,
       accept: accept.settings,
     })
+    return withAskRules(hooks, kit, manifest, accept)
+  }
 
 /** A global install ships no hooks and never reads the user's `settings.json`. */
 const noHooks = async (_manifest: Manifest, accept: AcceptRequest): Promise<HooksPlan> =>

package/src/task-signals/agent.ts

@@ -0,0 +1,15 @@
+import { cleanAgentName } from './text'
+
+const WORKTREE = /[\\/]\.claude[\\/]worktrees[\\/]([^\\/]+)/
+
+const MAIN_AGENT = 'main'
+
+/**
+ * Who is reporting: the herdr pane when `HERDR_PANE_ID` is set (an agent has its own pane), else the worktree the
+ * directory lies in (`.claude/worktrees/<name>`), else `main`.
+ */
+export const agentIdentity = (environment: Record<string, string | undefined>, cwd: string): string => {
+  const pane = cleanAgentName(environment.HERDR_PANE_ID ?? '')
+  if (pane) return `pane ${pane}`
+  return WORKTREE.exec(cwd)?.[1] ?? MAIN_AGENT
+}

package/src/task-signals/claude-read.ts

@@ -0,0 +1,89 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { readTailLines } from '../context/session-log'
+import { isRecord } from '../shared/is-record'
+import { readCached, type StatRound } from '../shared/stat-cache'
+import { claudeSignalsOf } from './claude-signals'
+import { cleanAgentName } from './text'
+import type { TaskSignal } from './types'
+
+const SUBAGENT_LOG = /^(agent-[A-Za-z0-9]+)\.jsonl$/
+
+/** How much of the end of a log is read by default: sessions grow to hundreds of megabytes. */
+const SIGNAL_TAIL_BYTES = 8 * 1024 * 1024
+
+/** The signals of each log by path, kept while its modification time and size stay; `used` collects the paths of one round. */
+export type SignalCache = StatRound<TaskSignal[]>
+
+export type ReadOptions = {
+  /** Kept between reads, so a log that did not change is not parsed again. */
+  cache?: SignalCache
+  /** How many bytes from the end of each log are read; a task created before that is unknown, so it gives no signal. */
+  tailBytes?: number
+  /** Subagent logs last written before this (epoch milliseconds) are left out. */
+  notOlderThan?: number
+}
+
+const linesOf = (path: string, tailBytes: number): string[] => {
+  try {
+    return readTailLines(path, tailBytes)
+  } catch {
+    return []
+  }
+}
+
+/** The subagent's own description when its `.meta.json` has one, else the log's name. */
+const agentNameOf = (directory: string, stem: string): string => {
+  try {
+    const meta: unknown = JSON.parse(readFileSync(join(directory, `${stem}.meta.json`), 'utf8'))
+    const description = isRecord(meta) ? meta.description : null
+    const name = typeof description === 'string' ? cleanAgentName(description) : ''
+    return name || stem
+  } catch {
+    return stem
+  }
+}
+
+const isRecent = (path: string, notOlderThan: number): boolean => {
+  try {
+    return statSync(path).mtimeMs >= notOlderThan
+  } catch {
+    return false
+  }
+}
+
+const named = (signals: TaskSignal[], agent: string): TaskSignal[] => signals.map((signal) => ({ ...signal, agent }))
+
+const subagentSignals = (
+  directory: string,
+  signalsOf: (path: string) => TaskSignal[],
+  notOlderThan: number,
+): TaskSignal[] => {
+  try {
+    return readdirSync(directory)
+      .sort()
+      .flatMap((name) => {
+        const stem = SUBAGENT_LOG.exec(name)?.[1]
+        const path = join(directory, name)
+        return stem && isRecent(path, notOlderThan) ? named(signalsOf(path), agentNameOf(directory, stem)) : []
+      })
+  } catch {
+    return []
+  }
+}
+
+/**
+ * The tasks in progress in a Claude Code session log and in every `<session>/subagents/agent-*.jsonl` beside it.
+ * With a `cache`, a log whose modification time and size are as at the last read is not read and parsed again.
+ */
+export const readClaudeSignals = (
+  sessionLogPath: string,
+  { tailBytes = SIGNAL_TAIL_BYTES, notOlderThan = 0, cache }: ReadOptions = {},
+): TaskSignal[] => {
+  const parsed = (path: string): TaskSignal[] => claudeSignalsOf(linesOf(path, tailBytes), '')
+  const signalsOf = cache ? (path: string) => readCached(cache, path, parsed, `${path}\0${tailBytes}`) : parsed
+  return [
+    ...named(signalsOf(sessionLogPath), 'session'),
+    ...subagentSignals(join(sessionLogPath.replace(/\.jsonl$/, ''), 'subagents'), signalsOf, notOlderThan),
+  ]
+}

package/src/task-signals/claude-signals.ts

@@ -0,0 +1,112 @@
+import { parseLogEntry } from '../context/session-log'
+import { isRecord } from '../shared/is-record'
+import { cleanTaskText } from './text'
+import type { TaskSignal } from './types'
+
+type Block = Record<string, unknown>
+
+type TaskDraft = { subject?: unknown; activeForm?: unknown; description?: unknown }
+
+type TrackedTask = { text: string; startedAt: number | null }
+
+type Tracker = {
+  pending: Map<string, TaskDraft>
+  tasks: Map<string, TrackedTask>
+  todos: Map<string, number>
+  cwd: string
+  time: number
+}
+
+const TASK_STATUS = {
+  pending: 'pending',
+  inProgress: 'in_progress',
+  completed: 'completed',
+  deleted: 'deleted',
+} as const
+
+const recordsIn = (values: unknown): Block[] => (Array.isArray(values) ? values.filter(isRecord) : [])
+
+const firstText = (...candidates: unknown[]): string =>
+  candidates.map((candidate) => (typeof candidate === 'string' ? cleanTaskText(candidate) : '')).find(Boolean) ?? ''
+
+const blocksOf = (entry: Record<string, unknown>): Block[] => {
+  return recordsIn(isRecord(entry.message) ? entry.message.content : undefined)
+}
+
+const createdIdOf = (entry: Record<string, unknown>, block: Block): string | null => {
+  const task = isRecord(entry.toolUseResult) ? entry.toolUseResult.task : undefined
+  const id = isRecord(task) ? task.id : undefined
+  if (typeof id === 'string' || typeof id === 'number') return String(id)
+  const match = typeof block.content === 'string' ? /^Task #(\S+) created/.exec(block.content) : null
+  return match ? match[1] : null
+}
+
+const onResult = (tracker: Tracker, entry: Record<string, unknown>, block: Block): void => {
+  const draft = typeof block.tool_use_id === 'string' ? tracker.pending.get(block.tool_use_id) : undefined
+  if (!draft) return
+  const id = createdIdOf(entry, block)
+  if (id === null) return
+  tracker.tasks.set(id, { text: firstText(draft.subject, draft.activeForm, draft.description), startedAt: null })
+}
+
+const onTaskUpdate = (tracker: Tracker, input: Record<string, unknown>): void => {
+  const id = typeof input.taskId === 'string' || typeof input.taskId === 'number' ? String(input.taskId) : null
+  const task = id === null ? undefined : tracker.tasks.get(id)
+  if (id === null || !task) return
+  if (input.status === TASK_STATUS.completed || input.status === TASK_STATUS.deleted) {
+    tracker.tasks.delete(id)
+    return
+  }
+  const renamed = firstText(input.subject)
+  if (renamed) task.text = renamed
+  if (input.status === TASK_STATUS.inProgress && task.startedAt === null) task.startedAt = tracker.time
+  if (input.status === TASK_STATUS.pending) task.startedAt = null
+}
+
+const onTodoWrite = (tracker: Tracker, input: Record<string, unknown>): void => {
+  const todos = recordsIn(input.todos)
+  const active = new Map<string, number>()
+  for (const todo of todos) {
+    const text = todo.status === TASK_STATUS.inProgress ? firstText(todo.content, todo.activeForm) : ''
+    if (text) active.set(text, tracker.todos.get(text) ?? tracker.time)
+  }
+  tracker.todos = active
+}
+
+const onToolUse = (tracker: Tracker, block: Block): void => {
+  const input = block.input
+  if (!isRecord(input)) return
+  if (block.name === 'TaskCreate' && typeof block.id === 'string') tracker.pending.set(block.id, input)
+  if (block.name === 'TaskUpdate') onTaskUpdate(tracker, input)
+  if (block.name === 'TodoWrite') onTodoWrite(tracker, input)
+}
+
+const visit = (tracker: Tracker, entry: Record<string, unknown>): void => {
+  const time = typeof entry.timestamp === 'string' ? Date.parse(entry.timestamp) : Number.NaN
+  if (!Number.isNaN(time)) tracker.time = time
+  if (typeof entry.cwd === 'string') tracker.cwd = entry.cwd
+  for (const block of blocksOf(entry)) {
+    if (block.type === 'tool_use') onToolUse(tracker, block)
+    if (block.type === 'tool_result') onResult(tracker, entry, block)
+  }
+}
+
+/**
+ * The tasks one Claude Code session log (or subagent log), given as its lines, has in progress at its end: a
+ * `TaskCreate` whose `TaskUpdate` set `in_progress` and none completed or deleted, plus the `in_progress` entries of
+ * the last `TodoWrite`. A line that is no JSON is skipped. Oldest first.
+ */
+export const claudeSignalsOf = (lines: readonly string[], agent: string): TaskSignal[] => {
+  const tracker: Tracker = { pending: new Map(), tasks: new Map(), todos: new Map(), cwd: '', time: 0 }
+  for (const line of lines) {
+    const entry = parseLogEntry(line)
+    if (entry) visit(tracker, entry)
+  }
+  const started = [...tracker.tasks.values()].flatMap(({ text, startedAt }) =>
+    startedAt === null || !text ? [] : [{ text, startedAt }],
+  )
+  const todos = [...tracker.todos].map(([text, startedAt]) => ({ text, startedAt }))
+  return [...started, ...todos]
+    .sort((left, right) => left.startedAt - right.startedAt)
+    .map(({ text, startedAt }) => ({ agent, source: 'claude', text, startedAt, cwd: tracker.cwd }))
+}

package/src/task-signals/command.ts

@@ -0,0 +1,71 @@
+import { mainCheckout } from '../plans/git'
+import { CLI_NAME } from '../version/release'
+import { agentIdentity } from './agent'
+import type { TaskRecord } from './record'
+import { buildTaskId } from './record'
+import { finishTask, openTaskOf, startTask } from './record-store'
+import { cleanTaskText } from './text'
+
+export const USAGE = `usage: ${CLI_NAME} task start "<task text>"
+       ${CLI_NAME} task done ["<task text>"]
+
+start  report the task you begin; the herd shows it as the one being worked on
+done   report it finished; with text, only when it names the open task
+One task per agent: a new start replaces the previous one.`
+
+export type TaskCommand =
+  | { kind: 'start'; text: string }
+  | { kind: 'done'; text: string }
+  | { kind: 'help' }
+  | { kind: 'usage' }
+
+/** The command line as a command: the words after `start` or `done` are the task text, whether quoted or not. */
+export const parseTaskCommand = (args: readonly string[]): TaskCommand => {
+  const [name, ...words] = args
+  if (name === '--help' || name === '-h') return { kind: 'help' }
+  const text = cleanTaskText(words.join(' '))
+  if (name === 'start' && text !== '') return { kind: 'start', text }
+  if (name === 'done') return { kind: 'done', text }
+  return { kind: 'usage' }
+}
+
+export type DoneReport = { exitCode: number; message: string | null }
+
+/** What `jh task done` says: nothing without an open task (a second call is no error), else the closed task or why the text did not close it. */
+export const doneReport = (open: TaskRecord | null, closed: TaskRecord | null): DoneReport => {
+  if (open === null) return { exitCode: 0, message: null }
+  if (closed === null) return { exitCode: 1, message: `the open task is: ${open.text}` }
+  return { exitCode: 0, message: `done: ${closed.text}` }
+}
+
+const newId = (): string => buildTaskId(crypto.getRandomValues(new Uint8Array(6)))
+
+/**
+ * `jh task start "<text>"` reports the task the calling agent begins, `jh task done ["<text>"]` that it is finished.
+ * Exit 0; 1 on a wrong command line or when the text of `done` names another task than the open one. `done` without
+ * an open task is silent and exits 0.
+ */
+export const run = (args: string[]): number => {
+  const command = parseTaskCommand(args)
+  if (command.kind === 'help') {
+    console.log(USAGE)
+    return 0
+  }
+  if (command.kind === 'usage') {
+    console.error(USAGE)
+    return 1
+  }
+  const cwd = process.cwd()
+  const root = mainCheckout(cwd)
+  const agent = agentIdentity(process.env, cwd)
+  const now = Date.now()
+  if (command.kind === 'start') {
+    const record = startTask(root, { agent, text: command.text, cwd, newId }, now)
+    console.log(`started: ${record.text}`)
+    return 0
+  }
+  const open = openTaskOf(root, agent)
+  const { exitCode, message } = doneReport(open, finishTask(root, agent, command.text, now))
+  if (message !== null) (exitCode === 0 ? console.log : console.error)(message)
+  return exitCode
+}

package/src/task-signals/fixtures/session.jsonl

@@ -0,0 +1,7 @@
+{"type":"assistant","timestamp":"1999-04-03T10:00:00.000Z","cwd":"/work/project","message":{"content":[{"type":"tool_use","id":"toolu_A","name":"TaskCreate","input":{"subject":"Write the parser","activeForm":"Writing the parser","description":"Parse the input"}}]}}
+{"type":"user","timestamp":"1999-04-03T10:00:01.000Z","cwd":"/work/project","toolUseResult":{"task":{"id":"1","subject":"Write the parser"}},"message":{"content":[{"type":"tool_result","tool_use_id":"toolu_A","content":"Task \u00231 created successfully: Write the parser"}]}}
+{"type":"assistant","timestamp":"1999-04-03T10:00:02.000Z","cwd":"/work/project","message":{"content":[{"type":"tool_use","id":"toolu_B","name":"TaskCreate","input":{"subject":"Add the tests","activeForm":"Adding the tests"}}]}}
+{"type":"user","timestamp":"1999-04-03T10:00:03.000Z","cwd":"/work/project","message":{"content":[{"type":"tool_result","tool_use_id":"toolu_B","content":"Task \u00232 created successfully: Add the tests"}]}}
+{"type":"assistant","timestamp":"1999-04-03T10:00:04.000Z","cwd":"/work/project","message":{"content":[{"type":"tool_use","id":"toolu_C","name":"TaskUpdate","input":{"taskId":"1","status":"in_progress"}},{"type":"tool_use","id":"toolu_D","name":"TaskUpdate","input":{"taskId":"2","status":"in_progress"}}]}}
+{"type":"assistant","timestamp":"1999-04-03T10:00:09.000Z","cwd":"/work/project","message":{"content":[{"type":"tool_use","id":"toolu_E","name":"TaskUpdate","input":{"taskId":"2","status":"completed"}}]}}
+not json