followups

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Flag, Item, Status } from '../types'
5import { doneResult, startLine } from './texts'
6
7// ---------- state ----------
8
9const pending = atom({ plugin: 'followups', key: 'pending' } as const, [] as Flag[])
10const items = atom({ plugin: 'followups', key: 'items' } as const, [] as Item[])
11const exported = atom({ plugin: 'followups', key: 'exported' } as const, '')
12const skipped = atom({ plugin: 'followups', key: 'skipped' } as const, [] as string[])
13// The list as this session last loaded or saved it, to merge with another session's saves.
14const base = atom({ plugin: 'followups', key: 'base' } as const, [] as Item[])
15
16const PANE = 'followups'
17const PANE_TITLE = 'To-do'
18const TOOL = 'mcp__followups__flag'
19const DONE_TOOL = 'mcp__followups__done'
20
21// One accent for the header; status colors for the rows (all read on light and dark themes).
22const ACCENT = '#4f7cff'
23const COLOR = { open: '#e08a1e', in_progress: '#2a9fd6', done: '#1f9d6b', bug: '#e5484d' } as const
24const MARK = { open: '○', in_progress: '◐', done: '✓' } as const
25
26// The model reads this in every request: when to flag, and when not to.
27const GUIDANCE = `# Follow-ups
28While you work you may notice things outside the task at hand that need attention later: a bug or broken behavior in nearby code, a failing or flaky test you didn't cause, a missing or stale doc, a TODO/FIXME, a security or performance concern, a config that looks wrong, or a step you skipped. The person tends to lose these if they aren't written down.
29Before you end a turn, look back over it: anything you noticed, worked around, left unverified or put off for later that the person would want to come back to gets flagged now, even when you also mention it in your reply. Findings in a subagent's or worker's report count too: flag them before your final reply.
30When you notice one, call ${TOOL} once for it, with a short imperative title ("Fix the flaky upload test") and a one-line detail; add \`where\` (file:line, command, URL) when there is one. Set kind to "bug" when the thing is broken behavior (a bug, a failing test, a crash, wrong output); leave kind out for ordinary tasks. The tool stops and asks the person in a dialog whether to keep it and returns their answer, so don't ask them yourself. Don't fix it unless they asked, and keep going with the task. Don't flag the task you were asked to do, its normal next steps, or something you are about to fix anyway.
31When a message says it started a to-do item and gives its id, do that work, and when it is finished call ${DONE_TOOL} with that id (and a short note of what you did). Call ${DONE_TOOL} only for items started that way; never for unrelated work, and not before the work is actually done.`
32
33// Words that mark a reply as leaving something open. Narrow on purpose (a false stop costs a turn),
34// so extend it one phrase at a time. Left out as too common: "בהמשך" ("later", but also "following
35// that") and "follow-up" / "follow up" (this mod's own word, in nearly every reply about it).
36export const STOP_PHRASES = [
37  'not verified', 'unverified', 'not tested', 'untested', 'no coverage', 'left open', 'still open', 'known gap',
38  'open question', 'open questions', 'unsure about', 'unsure-about',
39  'לא אומת', 'לא נבדק', 'לא נבדקו', 'פער', 'פריט המשך', 'שאלה פתוחה', 'שאלות פתוחות',
40]
41export const STOP_MESSAGE = 'You mentioned items that need follow-up. Call mcp__followups__flag for each, or say there are none.'
42
43// What the after-answer check asks a small model: what in this answer was left open.
44export const SWEEP_RULES = `You read the final reply an AI coding assistant just gave, with any reports its sub-agents handed it this turn, and list the follow-ups in them: problems or loose ends mentioned but left open, which the person could lose track of.
45Count: a bug or broken behavior, a failing or flaky test, a missing or stale doc, a TODO or FIXME, a security or performance concern, a config that looks wrong, a step that was skipped, something left unverified or untested, something put off for later, or an open question or decision that came up and wasn't settled.
46Don't count: the work that was done, a yes/no question about going ahead with the very next step, an offer to do the next step now, or anything in the already-tracked list.
47Answer with a JSON array only, at most 3 entries, each {"title": "short imperative, under 80 characters", "detail": "one line, under 160 characters", "where": "file:line, command or URL, or empty", "kind": "bug" or "task"}. Answer [] when there is nothing.`
48// Answers shorter than this rarely leave anything open; skipping them saves a call per short turn.
49const SWEEP_MIN_CHARS = 200
50
51// Where each export goes, and the heading its section gets there.
52const TARGETS = {
53  memory: { label: 'Memory', path: 'CLAUDE.md', heading: '## Open follow-ups', note: 'Claude reads this at the start of every session.' },
54  docs: { label: 'Docs', path: 'docs/FOLLOW-UPS.md', heading: '# Follow-ups', note: '' },
55  readme: { label: 'README', path: 'README.md', heading: '## Known issues & follow-ups', note: '' },
56} as const
57type Target = keyof typeof TARGETS
58
59const START = '<!-- followups:start -->'
60const END = '<!-- followups:end -->'
61
62// ---------- helpers ----------
63
64const clip = (s: string, n: number) => (s.length > n ? `${s.slice(0, n - 1)}…` : s)
65const norm = (s: string) => s.trim().toLowerCase().replace(/\s+/g, ' ')
66export const isStatus = (s: unknown): s is Status => s === 'open' || s === 'in_progress' || s === 'done'
67
68// Items saved before statuses existed carry isDone; map them to a status.
69export function migrate(saved: unknown): Item[] {
70  if (!Array.isArray(saved)) return []
71  return saved.map((raw: Record<string, unknown>) => {
72    const { isDone, ...rest } = raw
73    const status: Status = isStatus(raw.status) ? raw.status : isDone === true ? 'done' : 'open'
74    return { ...rest, status, kind: raw.kind === 'bug' ? 'bug' : 'task' } as Item
75  })
76}
77
78// The reply without fenced code blocks (an unclosed fence runs to the end) and inline code.
79export function prose(text: string): string {
80  return outsideFences(text).join('\n').replace(/``[^\n]*?``/g, ' ').replace(/`[^`\n]*`/g, ' ')
81}
82
83// The lines of a reply outside fenced code blocks (an unclosed fence runs to the end).
84function outsideFences(text: string): string[] {
85  const out: string[] = []
86  let fence = ''
87  for (const line of text.split('\n')) {
88    const m = /^\s*(`{3,}|~{3,})/.exec(line)
89    if (fence) {
90      if (m && m[1]!.startsWith(fence[0]!) && m[1]!.length >= fence.length) fence = ''
91    } else if (m) fence = m[1]!
92    else out.push(line)
93  }
94  return out
95}
96
97// The names a report gives what it leaves open (the model router's routed-worker writes Unsure-about,
98// with its Open questions there), and the other sections a label heading may name.
99const OPEN_SECTIONS = ['open questions', 'open question', 'open items', 'unsure-about', 'unsure about', 'שאלות פתוחות']
100const LABEL_SECTIONS = [...OPEN_SECTIONS, 'findings', 'files', 'changes', 'summary', 'notes', 'next steps', 'deliverable']
101const NONE = /^(?:none|nothing|n\/?a|no|אין|ללא)\.?$/iu
102// "Open questions: none" says nothing is open: the stop check reads past it.
103const OPEN_NONE = /(?:open questions?|open items|unsure[- ]about|שאלות פתוחות|שאלה פתוחה)\**\s*[:—-]?\s*\**\s*(?:none|nothing|n\/?a|אין|ללא)(?![\p{L}\p{N}])\.?/giu
104
105// A section heading: "## Name" (any name), or a label of a known section ("**Name:**", "Name:", "3. Name:"),
106// with whatever follows its colon on the same line.
107function headingOf(line: string): { name: string; rest: string } | null {
108  const hash = /^\s*#{1,6}\s+\**([^*:]+?)\**\s*:?\s*$/u.exec(line)
109  if (hash) return { name: hash[1]!.trim().toLowerCase(), rest: '' }
110  const label = /^\s*(?:\d+\.\s+)?\**([\p{L}][\p{L} -]{1,30}?)\**\s*:\**\s*(.*)$/u.exec(line)
111  if (label && LABEL_SECTIONS.includes(label[1]!.trim().toLowerCase())) {
112    return { name: label[1]!.trim().toLowerCase(), rest: label[2]!.replace(/\*+$/, '').trim() }
113  }
114  return null
115}
116
117// The items under a report's open-questions section, one per bullet or numbered line (or the text
118// after its label); "none" and its kin give nothing. At most 5.
119export function openItems(text: string): string[] {
120  const out: string[] = []
121  const add = (raw: string) => {
122    const item = raw.replace(/^\s*(?:[-*•]|\d+[.)])\s+/, '').replace(/\*\*/g, '').trim()
123    if (item && !NONE.test(item)) out.push(clip(item, 200))
124  }
125  let isOpen = false
126  for (const line of outsideFences(text)) {
127    const h = headingOf(line)
128    if (h) {
129      isOpen = OPEN_SECTIONS.includes(h.name)
130      if (isOpen && h.rest) add(h.rest)
131    } else if (isOpen && line.trim()) add(line)
132  }
133  return out.slice(0, 5)
134}
135
136// Phrases as whole words in the prose of a reply, any case. Subagent reports relayed in it count too.
137export function leftOpen(text: string, phrases: string[] = STOP_PHRASES): string[] {
138  const body = prose(text).replace(OPEN_NONE, ' ')
139  return phrases.filter(p => {
140    const src = p.trim().replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+')
141    return !!src && new RegExp(`(?<![\\p{L}\\p{N}_])${src}(?![\\p{L}\\p{N}_])`, 'iu').test(body)
142  })
143}
144
145export function sweepPrompt(answer: string, known: string[], reports: string[] = []): string {
146  return [
147    'Already tracked (skip these):',
148    ...(known.length ? known.map(t => `- ${t}`) : ['- (none)']),
149    '',
150    ...reports.flatMap(r => ['A sub-agent\'s report:', '<report>', r.slice(-6_000), '</report>', '']),
151    'The reply:',
152    '<reply>',
153    answer.slice(-12_000),
154    '</reply>',
155  ].join('\n')
156}
157
158// The small model's answer, read leniently: the first JSON array in it, only well-formed entries.
159export function parseFindings(text: string): Omit<Flag, 'id' | 'at'>[] {
160  const a = text.indexOf('[')
161  const b = text.lastIndexOf(']')
162  if (a === -1 || b < a) return []
163  let raw: unknown
164  try {
165    raw = JSON.parse(text.slice(a, b + 1))
166  } catch {
167    return []
168  }
169  if (!Array.isArray(raw)) return []
170  return raw
171    .filter((f): f is Record<string, unknown> => !!f && typeof f === 'object' && typeof (f as { title?: unknown }).title === 'string')
172    .map(f => ({
173      title: clip(String(f.title).trim(), 120),
174      detail: clip(String(f.detail ?? '').trim(), 300),
175      where: clip(String(f.where ?? '').trim(), 160),
176      kind: f.kind === 'bug' ? ('bug' as const) : ('task' as const),
177    }))
178    .filter(f => f.title)
179    .slice(0, 3)
180}
181
182// Everything already flagged, kept or turned down, normalised for comparing titles.
183async function knownTitles($: EngineInterface): Promise<Set<string>> {
184  const all = [...(await read($, pending)), ...(await read($, items))].map(f => norm(f.title))
185  return new Set([...all, ...(await read($, skipped))])
186}
187
188// Reads a finished answer for loose ends Claude mentioned but didn't flag, and offers them in the band.
189// The look runs quietly; when it can't run at all, the person is told once per session.
190let isWarned = false
191function warn($: EngineInterface, why: string) {
192  if (isWarned) return
193  isWarned = true
194  $.ui.log(`followups: the look for loose ends after each answer couldn't run (${why}), so they aren't offered above the prompt. Claude's own flags and the end-of-turn check still work.`)
195}
196
197async function sweep($: EngineInterface, answer: string, reports: string[]) {
198  const known = await knownTitles($)
199  let r
200  try {
201    r = await $.model.complete({ model: 'haiku', system: SWEEP_RULES, prompt: sweepPrompt(answer, [...known], reports), maxTokens: 600, effort: 'low', timeoutMs: 20_000 })
202  } catch (err) {
203    return warn($, err instanceof Error ? err.message : String(err))
204  }
205  if (!r.isAnswered) {
206    // An interrupted look (the person moved on) isn't a fault worth a line.
207    if (r.reason !== 'aborted') warn($, r.reason === 'api-error' ? `api-error ${r.status ?? ''}`.trim() : r.reason)
208    return
209  }
210  const fresh = await knownTitles($)
211  const found = parseFindings(r.text).filter(f => !fresh.has(norm(f.title)))
212  if (!found.length) return
213  const at = await $.clock.now()
214  await update($, pending, l => [...l, ...found.map(f => ({ ...f, id: newId(at), at }))])
215  $.ui.toast(found.length === 1 ? 'Claude noticed a possible follow-up: see above the prompt' : `Claude noticed ${found.length} possible follow-ups: see above the prompt`)
216}
217
218// A sub-agent's report that names open questions has them offered in the band at once: read
219// straight from its section, no model, so it works where the after-answer look can't run.
220// Resolves how many it offered.
221async function offerOpenItems($: EngineInterface, report: string): Promise<number> {
222  const known = await knownTitles($)
223  const fresh = openItems(report).filter(t => !known.has(norm(clip(t, 120))))
224  if (!fresh.length) return 0
225  const at = await $.clock.now()
226  const flags: Flag[] = fresh.map(t => ({ id: newId(at), kind: 'task', title: clip(t, 120), detail: "From a sub-agent's open questions", where: '', at }))
227  await update($, pending, l => [...l, ...flags])
228  $.ui.toast(fresh.length === 1 ? 'A sub-agent left an open question: see above the prompt' : `A sub-agent left ${fresh.length} open questions: see above the prompt`)
229  return fresh.length
230}
231
232const newId = (at: number) => `${at.toString(36)}-${Math.random().toString(36).slice(2, 7)}`
233
234// Exports and the saved list belong to the project, so both key on its root.
235const storeKey = async ($: EngineInterface) => `items:${await $.session.root()}`
236
237// A three-way merge with what another session in the same project saved meanwhile. `base` is the
238// list as this session last loaded or saved it: what changed here since wins, what changed only
239// there is taken, and an item either side deleted stays deleted.
240export function mergeLists<T extends { id: string }>(base: T[], mine: T[], stored: T[]): T[] {
241  const was = new Map(base.map(i => [i.id, JSON.stringify(i)]))
242  const there = new Map(stored.map(i => [i.id, i]))
243  const held = new Set(mine.map(i => i.id))
244  const kept = mine.flatMap(i => {
245    if (was.get(i.id) !== JSON.stringify(i)) return [i]
246    const other = there.get(i.id)
247    return other ? [other] : []
248  })
249  return [...kept, ...stored.filter(i => !held.has(i.id) && !was.has(i.id))]
250}
251
252async function save($: EngineInterface) {
253  const key = await storeKey($)
254  const saved = await $.store.get(key)
255  const from = await read($, base)
256  const stored = Array.isArray(saved) ? migrate(saved) : from
257  const merged = await update($, items, mine => mergeLists(from, mine, stored))
258  await $.store.set(key, merged)
259  await update($, base, () => merged)
260}
261
262// What the person turned down, kept per project like the list, so it isn't offered again later.
263const skippedKey = async ($: EngineInterface) => `skipped:${await $.session.root()}`
264
265async function turnDown($: EngineInterface, title: string) {
266  const t = norm(title)
267  // Another session in the folder may have turned things down meanwhile: the list only grows, so join them.
268  const key = await skippedKey($)
269  const saved = await $.store.get(key)
270  const there = Array.isArray(saved) ? saved.filter((s): s is string => typeof s === 'string') : []
271  const list = await update($, skipped, l => [...new Set([...there, ...l, t])])
272  await $.store.set(key, list)
273}
274
275const ADD = 'Add to to-do'
276const SKIP = 'Not needed'
277
278// Stops the turn on the engine's own question dialog and answers the tool with what the person
279// chose. Typing under "Other" keeps it under their wording. A dismissed dialog (or a run with
280// no one to ask) leaves the flag in the band above the prompt, so it is never lost.
281async function ask($: EngineInterface, flag: Flag): Promise<string> {
282  const extra = [flag.detail, flag.where].filter(Boolean).join(' · ')
283  let answer: string
284  try {
285    answer = await $.ui.ask(`Claude noticed${flag.kind === 'bug' ? ' a bug' : ''}: "${flag.title}"${extra ? ` (${extra})` : ''}. Add it to your follow-ups?`, {
286      header: 'Follow-up',
287      options: [ADD, SKIP],
288    })
289  } catch {
290    answer = ''
291  }
292  if (!answer.trim()) {
293    await update($, pending, list => [...list, flag])
294    return `The person didn't answer; "${flag.title}" waits above the prompt for them. Carry on with the task.`
295  }
296  if (answer === SKIP) {
297    await turnDown($, flag.title)
298    return `The person skipped "${flag.title}". Don't flag or raise it again. Carry on with the task.`
299  }
300  const kept = answer === ADD ? flag : { ...flag, title: clip(answer.trim(), 120) }
301  await keep($, [kept])
302  return `The person added "${kept.title}" to their follow-ups. Don't fix it now unless they ask. Carry on with the task.`
303}
304
305async function keep($: EngineInterface, flags: Flag[]) {
306  if (!flags.length) return
307  const ids = new Set(flags.map(f => f.id))
308  await update($, pending, list => list.filter(f => !ids.has(f.id)))
309  // By id, inside the update: two presses before a redraw both carry the same flag.
310  await update($, items, list => {
311    const have = new Set(list.map(i => i.id))
312    return [...list, ...flags.filter(f => !have.has(f.id)).map(f => ({ ...f, kind: f.kind ?? 'task', status: 'open' as const }))]
313  })
314  await save($)
315  void $.ui.open({ id: PANE, title: PANE_TITLE })
316}
317
318// The message that starts an item: names it, carries the id, and says how to report back.
319export function startPrompt(list: Item[]): string {
320  return [
321    list.length === 1 ? 'Start this item from my to-do list:' : `Start these ${list.length} items from my to-do list, one after the other:`,
322    ...list.map(startLine),
323    `Do the work. When an item is finished, call ${DONE_TOOL} with its id (and a short note). Don't call it for anything else.`,
324  ].join('\n')
325}
326
327async function setStatus($: EngineInterface, ids: Set<string>, status: Status) {
328  await update($, items, l => l.map(i => (ids.has(i.id) ? { ...i, status } : i)))
329  await save($)
330}
331
332async function start($: EngineInterface, which: Item[]) {
333  if (!which.length) return
334  await setStatus($, new Set(which.map(i => i.id)), 'in_progress')
335  // A turn of its own once the session is idle; it may not resolve until then, so not awaited. If
336  // it can't be sent, the items go back to open, where their Start button is.
337  $.prompt.submit({ text: startPrompt(which) }).catch(() => setStatus($, new Set(which.map(i => i.id)), 'open'))
338}
339
340// The markdown an export writes: the items as a checklist between two markers.
341export function section(target: Target, list: Item[]): string {
342  const t = TARGETS[target]
343  const lines = list.map(i => {
344    const extra = [i.detail, i.where && `\`${i.where}\``].filter(Boolean).join(' · ')
345    const tags = `${i.kind === 'bug' ? ' _(bug)_' : ''}${i.status === 'in_progress' ? ' _(in progress)_' : ''}`
346    return `- [${i.status === 'done' ? 'x' : ' '}] ${i.title}${tags}${extra ? ` — ${extra}` : ''}`
347  })
348  return [START, t.heading, '', ...(t.note ? [`_${t.note}_`, ''] : []), ...lines, END].join('\n')
349}
350
351// Puts the section in the file: in place of an earlier export, else at the end. Only a START…END
352// pair counts (END after START); a stray END before it is ignored, so a re-export stays one block.
353export function upsert(text: string, block: string): string {
354  const first = text.indexOf(START)
355  const b = first === -1 ? -1 : text.indexOf(END, first + START.length)
356  const a = b === -1 ? -1 : text.lastIndexOf(START, b)
357  if (a !== -1 && b !== -1) return text.slice(0, a) + block + text.slice(b + END.length)
358  return text.trim() ? `${text.replace(/\s*$/, '')}\n\n${block}\n` : `${block}\n`
359}
360
361async function exportTo($: EngineInterface, target: Target) {
362  const list = await read($, items)
363  const t = TARGETS[target]
364  if (!list.length) return update($, exported, () => 'Nothing to export yet.')
365  try {
366    const path = `${(await $.session.root()).replace(/[\\/]$/, '')}/${t.path}`
367    const before = (await $.fs.exists(path)) ? await $.fs.read(path) : ''
368    await $.fs.write(path, upsert(typeof before === 'string' ? before : '', section(target, list)))
369    await update($, exported, () => `Exported ${list.length} to ${t.path}`)
370    $.ui.toast(`Follow-ups exported to ${t.path}`)
371  } catch (err) {
372    await update($, exported, () => `Couldn't write ${t.path}: ${err instanceof Error ? err.message : String(err)}`)
373  }
374}
375
376export const register: Register = (on, options) => {
377  const autoDetect = String(options.autoDetect ?? 'on') !== 'off'
378  const openOnStart = String(options.openOnStart ?? 'on') !== 'off'
379  const stopCheck = String(options.stopCheck ?? 'on') !== 'off'
380  // The module's own, per turn: a person is at the prompt, flag was called, the check already stopped once.
381  let isInteractive = false
382  let isFlagged = false
383  let isBlocked = false
384  // Sub-agents' final reports since the main loop's last answer: the work, and its loose ends, is often there.
385  let reports: string[] = []
386
387  on('session.start', async ($, e, next) => {
388    isInteractive = e.isInteractive
389    await $.tool.register({
390      name: 'flag',
391      description: 'Flag something you noticed that needs attention later, outside the current task: a bug or broken behavior, a failing or flaky test, a missing or stale doc, a TODO/FIXME, a security or performance concern, a step you skipped, or something you left unverified or put off. Call it as soon as you notice one (once per item), and before ending a turn for any you mention in your reply; the person tends to lose these otherwise. Not for the task itself or its normal next steps. The person is asked in a dialog whether to add it to their follow-up to-do list; the result is their answer.',
392      inputSchema: {
393        type: 'object',
394        properties: {
395          title: { type: 'string', description: 'Short imperative title, e.g. "Fix the flaky upload test"' },
396          detail: { type: 'string', description: 'One line: what is wrong and why it matters' },
397          where: { type: 'string', description: 'Optional file:line, command or URL' },
398          kind: { type: 'string', enum: ['bug', 'task'], description: 'bug for broken behavior; task (default) for anything else' },
399        },
400        required: ['title'],
401      },
402      isDeferred: false,
403    })
404    await $.tool.register({
405      name: 'done',
406      description: 'Mark a to-do item finished. Call it when you finish an item the person started from their to-do list (the message gave its id), never for unrelated work.',
407      inputSchema: {
408        type: 'object',
409        properties: {
410          id: { type: 'string', description: 'The item id from the start message' },
411          note: { type: 'string', description: 'Optional: what you did' },
412        },
413        required: ['id'],
414      },
415      isDeferred: false,
416    })
417    await $.command.register({ name: 'followups', description: 'Show the follow-up to-do list' })
418    await $.command.register({ name: 'followup', description: 'Add a follow-up to the to-do list', argumentHint: '<what to do>' })
419    // $.state outlives a reload, so a list an older version held is migrated in place too.
420    const held = await read($, items)
421    if (held.some(i => !isStatus((i as { status?: unknown }).status))) await update($, items, l => migrate(l))
422    // Items kept in this folder before carry over to a new session.
423    if (!held.length) {
424      const saved = await $.store.get(await storeKey($))
425      if (Array.isArray(saved) && saved.length) {
426        const list = migrate(saved)
427        await update($, items, () => list)
428        await update($, base, () => list)
429      }
430    }
431    const turnedDown = await $.store.get(await skippedKey($))
432    if (Array.isArray(turnedDown)) {
433      const fromStore = turnedDown.filter((t): t is string => typeof t === 'string')
434      await update($, skipped, l => [...new Set([...fromStore, ...l])])
435    }
436    // Open work left from an earlier session is shown, so it isn't forgotten.
437    if (openOnStart && (await read($, items)).some(i => i.status !== 'done')) void $.ui.open({ id: PANE, title: PANE_TITLE })
438    return next(e)
439  })
440
441  on('prompt.compose', async ($, e, next) => {
442    const r = await next(e)
443    if (e.traits.includes('bare')) return r
444    return { sections: [...r.sections, { id: 'followups:guidance', text: GUIDANCE, scope: 'session' as const }] }
445  })
446
447  // A new turn from the person (a continuation after a stop has no text) starts the check afresh.
448  on('turn.start', async ($, e, next) => {
449    if (e.agentId === undefined && e.text !== '') {
450      isFlagged = false
451      isBlocked = false
452    }
453    return next(e)
454  })
455
456  on('tool.call', { tool: TOOL }, async ($, e) => {
457    isFlagged = true // any call counts, even one the person turns down
458    const input = e as unknown as { title?: unknown; detail?: unknown; where?: unknown; kind?: unknown }
459    const title = clip(String(input.title ?? '').trim(), 120)
460    if (!title) return { deny: 'A follow-up needs a title.' }
461    if ((await read($, skipped)).includes(norm(title))) {
462      return { result: `The person already said "${title}" isn't needed. Don't raise it again.` }
463    }
464    const known = [...(await read($, pending)), ...(await read($, items))]
465    if (known.some(f => norm(f.title) === norm(title))) {
466      return { result: `Already flagged: "${title}". No need to flag it again.` }
467    }
468    const at = await $.clock.now()
469    const flag: Flag = {
470      id: newId(at),
471      kind: input.kind === 'bug' ? 'bug' : 'task',
472      title,
473      detail: clip(String(input.detail ?? '').trim(), 300),
474      where: clip(String(input.where ?? '').trim(), 160),
475      at,
476    }
477    return { result: await ask($, flag) }
478  })
479
480  on('tool.call', { tool: DONE_TOOL }, async ($, e) => {
481    const input = e as unknown as { id?: unknown; note?: unknown }
482    const ref = String(input.id ?? '').trim()
483    const list = await read($, items)
484    const item = list.find(i => i.id === ref) ?? list.find(i => ref && norm(i.title) === norm(ref))
485    if (!item) return { deny: `No to-do item with id "${ref}". Use the id from the start message.` }
486    if (item.status === 'done') return { result: `"${item.title}" is already done. Nothing to change.` }
487    await setStatus($, new Set([item.id]), 'done')
488    const note = clip(String(input.note ?? '').trim(), 200)
489    $.ui.toast(`Done: ${item.title}`)
490    return { result: doneResult(item.title, note) }
491  })
492
493  // After a main-loop answer, look it over for loose ends Claude didn't flag. Run from a timer so
494  // the end of the turn never waits on the extra model call.
495  on('turn.complete', async ($, e, next) => {
496    const r = await next(e)
497    if (e.agentId !== undefined) {
498      if (e.reason === 'answer' && e.answer.trim()) {
499        reports = [...reports, e.answer.trim()].slice(-4)
500        // Offered in the band: the stop check needn't send Claude back to flag them again.
501        if (await offerOpenItems($, e.answer)) isFlagged = true
502      }
503      return r
504    }
505    const taken = reports
506    reports = []
507    // A turn the Stop check sent back has had Claude go over its own reply: a second reading would
508    // only offer the same loose ends again under other titles.
509    const chars = [e.answer, ...taken].join('\n').trim().length
510    if (autoDetect && !isBlocked && e.reason === 'answer' && chars >= SWEEP_MIN_CHARS) {
511      const answer = e.answer
512      $.clock.after(0, () => sweep($, answer, taken).catch(err => warn($, err instanceof Error ? err.message : String(err))))
513    }
514    return r
515  })
516
517  // The end of the main loop's turn: when the reply names something left open and flag wasn't called,
518  // stop it once with a nudge. classic.Stop is the one event that can send Claude back to work
519  // (`block`); turn.complete only reads. Without a person at the prompt, nobody could answer, so no check.
520  on('classic.Stop', async ($, e, next) => {
521    const r = await next(e)
522    if (!stopCheck || !isInteractive || isFlagged || isBlocked || e.stop_hook_active || r.block) return r
523    if (!leftOpen(e.last_assistant_message ?? '').length) return r
524    isBlocked = true
525    return { ...r, block: STOP_MESSAGE }
526  }).catch(($, e, next) => (next.called ? next(e) : {}))
527
528  on('command.run', { command: 'followups' }, async $ => {
529    await $.ui.open({ id: PANE, title: PANE_TITLE })
530    return { text: 'Follow-ups pane opened.' }
531  })
532
533  on('command.run', { command: 'followup' }, async ($, e) => {
534    const title = clip(e.args.trim(), 120)
535    if (!title) return { text: 'Usage: /followup <what to do>' }
536    const tracked = (await read($, items)).find(i => norm(i.title) === norm(title))
537    if (tracked) return { text: `Already in your follow-ups: "${tracked.title}".` }
538    // A flag still waiting in the band is what the person means: keep it, detail and all.
539    const waiting = (await read($, pending)).find(f => norm(f.title) === norm(title))
540    if (waiting) {
541      await keep($, [waiting])
542      return { text: `Added to follow-ups: ${waiting.title}` }
543    }
544    const at = await $.clock.now()
545    await keep($, [{ id: newId(at), kind: 'task', title, detail: '', where: '', at }])
546    return { text: `Added to follow-ups: ${title}` }
547  })
548
549  // ---------- the band: Claude asks ----------
550
551  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
552    const list = await read($, pending)
553    const flag = list[0]
554    if (e.props.hasSurvey || !flag) return next(e)
555    const { Box, Button, Text } = $.ui.resolve(e)
556    const below = await next(e)
557    const more = list.length - 1
558    return (
559      <Box flexDirection="column">
560        <Box flexDirection="column" paddingX={1}>
561          <Box flexDirection="row" gap={1}>
562            <Text color="#e08a1e" bold>◆ Claude noticed something. Track it?</Text>
563            {more ? <Text dimColor>{`(+${more} more)`}</Text> : null}
564          </Box>
565          <Text bold wrap="truncate-end">{`  ${flag.title}`}</Text>
566          {flag.detail ? <Text dimColor wrap="truncate-end">{`  ${flag.detail}`}</Text> : null}
567          {flag.where ? <Text dimColor wrap="truncate-end">{`  ${flag.where}`}</Text> : null}
568          <Box flexDirection="row" gap={1}>
569            <Button key="add" label="Add to to-do" hotkey="a" variant="primary" onPress={() => keep($, [flag])} />
570            <Button key="skip" label="Skip" hotkey="s" onPress={async () => {
571              await update($, pending, l => l.filter(f => f.id !== flag.id))
572              await turnDown($, flag.title)
573            }} />
574            {more ? <Button key="add-all" label={`Add all ${list.length}`} onPress={async () => keep($, await read($, pending))} /> : null}
575          </Box>
576        </Box>
577        {below}
578      </Box>
579    )
580  })
581
582  // ---------- the pane: the to-do and its export ----------
583
584  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
585    const { Box, Button, Text } = $.ui.resolve(e)
586    const list = await read($, items)
587    const note = await read($, exported)
588    const count = (st: Status) => list.filter(i => i.status === st).length
589    const [open, doing, done] = [count('open'), count('in_progress'), count('done')]
590    const toggle = (id: string) => async () => {
591      await update($, items, l => l.map(i => (i.id === id ? { ...i, status: i.status === 'done' ? ('open' as const) : ('done' as const) } : i)))
592      await save($)
593    }
594    const remove = (id: string) => async () => {
595      await update($, items, l => l.filter(i => i.id !== id))
596      await save($)
597    }
598
599    return (
600      <Box flexDirection="column" gap={1}>
601        <Box flexDirection="row" gap={2}>
602          <Text bold color={ACCENT}>☑ To-do</Text>
603          <Text dimColor>{list.length ? `${open} open · ${doing} in progress · ${done} done` : ''}</Text>
604          {open > 1 ? <Button key="start-all" label="▶ Start all open" plain onPress={() => start($, list.filter(i => i.status === 'open'))} /> : null}
605        </Box>
606        {list.length ? (
607          <Box flexDirection="column">
608            {list.map(i => (
609              <Box key={`row-${i.id}`} flexDirection="column">
610                <Box flexDirection="row" justifyContent="space-between" gap={1}>
611                  <Box flexDirection="row" gap={1}>
612                    {i.kind === 'bug' ? <Text color={COLOR.bug} bold>🐞</Text> : null}
613                    <Text color={COLOR[i.status]}>{MARK[i.status]}</Text>
614                    <Text color={COLOR[i.status]} dimColor={i.status === 'done'} strikethrough={i.status === 'done'} wrap="truncate-end">{i.title}</Text>
615                  </Box>
616                  <Box flexDirection="row" gap={1}>
617                    {i.status === 'open' ? <Button key={`s-${i.id}`} label="▶ Start" plain onPress={() => start($, [i])} /> : null}
618                    <Button key={`t-${i.id}`} label={i.status === 'done' ? '↺ Reopen' : '✓ Done'} plain onPress={toggle(i.id)} />
619                    <Button key={`x-${i.id}`} label="✕" plain onPress={remove(i.id)} />
620                  </Box>
621                </Box>
622                {i.status !== 'done' && (i.detail || i.where) ? (
623                  <Text dimColor wrap="truncate-end">{`   ${[i.detail, i.where].filter(Boolean).join(' · ')}`}</Text>
624                ) : null}
625              </Box>
626            ))}
627          </Box>
628        ) : (
629          <Text dimColor>Nothing tracked yet. When Claude spots something, it asks above the prompt. /followup adds one by hand.</Text>
630        )}
631        <Box flexDirection="column">
632          <Box flexDirection="row" gap={1} flexWrap="wrap">
633            <Text bold>Export to</Text>
634            {(Object.keys(TARGETS) as Target[]).map(t => (
635              <Button key={`export-${t}`} label={TARGETS[t].label} onPress={() => exportTo($, t)} />
636            ))}
637            {list.some(i => i.status === 'done') ? (
638              <Button key="clear-done" label="Clear done" plain onPress={async () => {
639                await update($, items, l => l.filter(i => i.status !== 'done'))
640                await save($)
641              }} />
642            ) : null}
643          </Box>
644          <Text dimColor>{note || 'Memory → CLAUDE.md · Docs → docs/FOLLOW-UPS.md · README → README.md'}</Text>
645        </Box>
646      </Box>
647    )
648  })
649}
650

1// GENERATED from shared/texts.ts by tools/sync-texts.mjs: edit that file, not this one.
2// Wording one mod writes and another reads: followups' Start prompt and done result, goal-run's
3// start prompt, reached-goal toast and result. Edit it here, then run `node tools/sync-texts.mjs`:
4// a mod can import nothing outside its own folder, so each one keeps a copy in hooks/texts.ts.
5
6export type StartItem = { id: string; title: string; isBug?: boolean }
7
8// followups: one line per item it hands Claude when the person presses Start.
9export const startLine = (i: { id: string; title: string; kind?: string; detail?: string; where?: string }) =>
10  `- id ${i.id}: ${i.title}${i.kind === 'bug' ? ' (bug)' : ''}${i.detail ? ` — ${i.detail}` : ''}${i.where ? ` [where: ${i.where}]` : ''}`
11
12export function parseStartPrompt(text: string): StartItem[] {
13  const out: StartItem[] = []
14  for (const line of text.split('\n')) {
15    const m = /^- id (\S+): (.+?)( \(bug\))?(?: — .*?)?(?: \[where: .*\])?$/.exec(line.trim())
16    if (m) out.push({ id: m[1]!, title: m[2]!.trim().slice(0, 120), ...(m[3] ? { isBug: true } : {}) })
17  }
18  return out
19}
20
21// A tool's answer as text, however it arrives: a string, MCP content blocks, or `{ content }`
22// (what a classic PostToolUse hook gets as tool_response).
23export function toolText(response: unknown): string {
24  if (typeof response === 'string') return response
25  const blocks = Array.isArray(response) ? response : (response as { content?: unknown } | null)?.content
26  if (Array.isArray(blocks)) return blocks.map(b => String((b as { text?: unknown })?.text ?? '')).join('\n')
27  return response == null ? '' : JSON.stringify(response)
28}
29
30// followups: what its done tool answers.
31export const doneResult = (title: string, note: string) => `Marked "${title}" done${note ? ` (${note})` : ''}.`
32
33export function parseDoneResult(text: string): { title: string; note: string } | null {
34  const m = /^Marked "(.+)" done(?: \((.*)\))?\.$/.exec(text)
35  return m ? { title: m[1]!, note: m[2] ?? '' } : null
36}
37
38// goal-run: the prompt that hands Claude the goal, the toast when it is reached (on every path), and
39// the update tool's words for it.
40export const goalPrompt = (text: string) => `My goal for this session: ${text}`
41export const parseGoalPrompt = (text: string) => /^My goal for this session: (.+)$/m.exec(text)?.[1]?.trim() ?? null
42export const goalReachedToast = (text: string) => `Goal reached: ${text}`
43export const GOAL_REACHED = 'The goal is reached.'
44// goal-run: the note it adds to followups' done result when that to-do item closed the goal's last task.
45export const goalClosedNote = (text: string) => `That closed the last task of the session goal "${text}". ${GOAL_REACHED}`
46export const parseGoalClosedNote = (text: string) => /^That closed the last task of the session goal "(.+)"\. /.exec(text)?.[1] ?? null
47
48// goal-run ↔ factory: a plan the factory's spec-writer wrote is submitted with source "factory".
49// goal-run then lets the factory's builder do the work, and answers the plan tool in these words;
50// the factory reads them to go on to the build or back to the spec. A plan approved later in the
51// Goal pane is passed on with the command /factory plan-approved.
52export const FACTORY_SOURCE = 'factory' as const
53export const FACTORY_PLAN_APPROVED_ARG = 'plan-approved'
54export const PLAN_APPROVED_FOR_FACTORY = "Approved. The factory's builder does the work: don't start the tasks yourself, and don't propose another plan."
55export const planChangesForFactory = (said: string) => `The person wants changes: ${said}\nThe factory's spec-writer revises the spec; don't propose a plan yourself.`
56export const PLAN_WAITING_FOR_FACTORY = "The person hasn't answered; the plan waits for approval in the Goal pane, and the factory waits with it."
57// The person has a goal of their own: goal-run keeps it, and the factory asks for approval itself.
58export const PLAN_KEPT_FOR_FACTORY = "The person has a session goal of their own, so the factory's plan is not set as the goal. The factory asks the person to approve it in its own band; don't propose a plan or start the tasks."
59
60// Only the factory's own wording counts: a regular plan's "Approved. …" or "The person wants changes
61// to the plan" is the main loop's, not the factory's.
62export function parsePlanOutcome(text: string): { approved: true } | { changes: string } | { kept: true } | null {
63  if (text.startsWith(PLAN_APPROVED_FOR_FACTORY)) return { approved: true }
64  if (text.startsWith(PLAN_KEPT_FOR_FACTORY)) return { kept: true }
65  const m = /^The person wants changes: ([\s\S]*?)\nThe factory's spec-writer revises the spec/.exec(text)
66  return m ? { changes: m[1]!.trim() } : null
67}
68

1export type Status = 'open' | 'in_progress' | 'done'
2export type Kind = 'bug' | 'task'
3export type Flag = { id: string; title: string; detail: string; where: string; at: number; kind?: Kind }
4export type Item = Flag & { status: Status }
5
6declare module 'claude-code' {
7  interface PluginState {
8    followups: {
9      // What Claude flagged and the person hasn't answered yet.
10      pending: Flag[]
11      // What the person chose to keep.
12      items: Item[]
13      // The last export's outcome, shown under the buttons.
14      exported: string
15      // Titles (normalised) the person said aren't needed, so they aren't suggested again.
16      skipped: string[]
17      // The list as this session last loaded or saved it, to merge with another session's saves.
18      base: Item[]
19    }
20  }
21}
22