@seanmars/tospec 0.23.0 → 0.24.0

package/assets/claude-mod/tospec-dashboard/hooks/register.ts

@@ -0,0 +1,695 @@
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, Register } from 'claude-code'
+
+import type { HubStatus } from '../types'
+
+/**
+ * Registers this project with the tospec dashboard hub (`tospec dashboard`)
+ * and keeps its snapshot current. The hub reads no project files: this mod
+ * runs the tospec CLI here and relays what it prints, because a mod has no
+ * Node to load tospec with and cannot listen on a port for the hub to call.
+ * Requests the snapshot does not answer, and task writes, wait at the hub
+ * until the long poll below collects them.
+ *
+ * It also reports what the session is doing (see "session activity" below),
+ * and lets the dashboard answer the questions it asks. Nothing else typed
+ * into the dashboard reaches the session.
+ *
+ * The footer shows where the session stands, and `/tospec-dashboard
+ * register|unregister|status` lets the person change it.
+ *
+ * Generated by `tospec init` / `tospec update`; edits here are overwritten.
+ */
+
+const DEFAULT_HUB_URL = 'http://127.0.0.1:5620'
+const COMMAND = 'tospec-dashboard'
+// Between probes of a hub that is not running. A probe is one HTTP request;
+// the tospec CLI only runs once the hub answers.
+const RETRY_MS = 20_000
+// Edits come in bursts (one apply step rewrites several files), so push once
+// the burst settles.
+const PUSH_DEBOUNCE_MS = 1_500
+const CLI_TIMEOUT_MS = 120_000
+const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit'])
+
+// In `$.state`, not module state: the footer redraws on its writes, and a hot
+// reload keeps it, so a session the person unregistered stays unregistered.
+const STATUS = atom({ plugin: 'tospec-dashboard', key: 'status' } as const, 'connecting')
+
+const FOOTER_LABEL: Record<HubStatus, string> = {
+  connecting: 'tospec hub: connecting',
+  connected: 'tospec hub: connected',
+  'hub-offline': 'tospec hub: offline',
+  unregistered: 'tospec hub: unregistered',
+  error: 'tospec hub: error',
+}
+
+type HubCommand =
+  | { id: string; kind: 'query'; request: { method?: string } }
+  | { id: string; kind: 'refresh' }
+
+type CliResult = { ok: true; payload: Record<string, unknown> } | { ok: false; error: string }
+
+type Attempt = 'registered' | 'hub-offline' | 'hub-refused' | 'cli-failed' | 'unregistered'
+
+// Module state: a reload starts it over, and `session.start` fires again then.
+const state = {
+  hubUrl: DEFAULT_HUB_URL,
+  /** The argv prefix that started tospec last time, so the probe runs once. */
+  launcher: undefined as string[] | undefined,
+  /** The hub's key for this project, once it accepted a snapshot. */
+  project: undefined as string | undefined,
+  /** `<tospec root>/tospec/`, lowercased with forward slashes, from the snapshot. */
+  tospecDir: undefined as string | undefined,
+  looping: false,
+  ended: false,
+  /** Set by `/tospec-dashboard unregister`; nothing registers until `register`. */
+  optedOut: false,
+  /** Why the last attempt failed, for `/tospec-dashboard status`. */
+  detail: '',
+  /** The registration in flight, shared by the loop and the command. */
+  attempt: undefined as Promise<Attempt> | undefined,
+  /** Ends the loop's retry wait early. */
+  wake: undefined as (() => void) | undefined,
+  pushTimer: undefined as { cancel: () => void } | undefined,
+  reported: new Set<string>(),
+}
+
+function debug($: EngineInterface, text: string): void {
+  // Once per distinct line: a hub that stays down would otherwise log every retry.
+  if (state.reported.has(text)) return
+  state.reported.add(text)
+  $.ui.log(`tospec-dashboard: ${text}`, { to: 'debug' })
+}
+
+async function setStatus($: EngineInterface, status: HubStatus, detail = ''): Promise<void> {
+  state.detail = detail
+  // Unchanged writes would still redraw the footer.
+  if ((await read($, STATUS)) !== status) await update($, STATUS, () => status)
+}
+
+function sleep($: EngineInterface, ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = $.clock.after(ms, () => {
+      state.wake = undefined
+      resolve()
+    })
+    state.wake = () => {
+      timer.cancel()
+      state.wake = undefined
+      resolve()
+    }
+  })
+}
+
+async function post(
+  $: EngineInterface,
+  path: string,
+  body: unknown
+): Promise<{ status: number; text: string } | undefined> {
+  try {
+    return await $.http.fetch(state.hubUrl + path, {
+      method: 'POST',
+      // JSON is what keeps web pages out: the hub answers no CORS preflight.
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    })
+  } catch {
+    return undefined
+  }
+}
+
+async function hubIsUp($: EngineInterface): Promise<boolean> {
+  try {
+    return (await $.http.fetch(state.hubUrl + '/api/health')).ok
+  } catch {
+    return false
+  }
+}
+
+async function runTospec($: EngineInterface, args: string[], stdin?: string): Promise<CliResult> {
+  const cwd = await $.session.root()
+  const candidates = state.launcher ? [state.launcher] : [['tospec']]
+  if (!state.launcher && (await $.env.get('OS')) === 'Windows_NT') {
+    // npm installs tospec as a .cmd shim on Windows, which only a shell runs.
+    candidates.push(['cmd.exe', '/d', '/s', '/c', 'tospec'])
+  }
+  for (const base of candidates) {
+    let result
+    try {
+      result = await $.process.run([...base, ...args], { cwd, stdin, timeoutMs: CLI_TIMEOUT_MS })
+    } catch {
+      continue
+    }
+    state.launcher = base
+    let payload: Record<string, unknown>
+    try {
+      payload = JSON.parse(result.stdout) as Record<string, unknown>
+    } catch {
+      return {
+        ok: false,
+        error: result.isStdoutTruncated
+          ? 'tospec printed more than a mod can read'
+          : result.stderr.trim() || 'tospec printed no JSON',
+      }
+    }
+    if (result.exitCode === 0) return { ok: true, payload }
+    const status = payload.status as Array<{ message?: string }> | undefined
+    return { ok: false, error: status?.[0]?.message ?? `tospec exited with ${result.exitCode}` }
+  }
+  return { ok: false, error: 'could not start the tospec CLI; is it on PATH?' }
+}
+
+async function leave($: EngineInterface, project: string, session: string): Promise<void> {
+  await post($, '/api/mod/leave', { project, session })
+}
+
+async function push($: EngineInterface): Promise<Attempt> {
+  if (state.optedOut) return 'unregistered'
+  const out = await runTospec($, ['dashboard', 'snapshot'])
+  if (!out.ok) {
+    debug($, `snapshot failed: ${out.error}`)
+    await setStatus($, 'error', `tospec dashboard snapshot failed: ${out.error}`)
+    return 'cli-failed'
+  }
+  const root = (out.payload.root as { path?: string } | undefined)?.path
+  if (root) state.tospecDir = `${root.replace(/\\/g, '/').replace(/\/+$/, '')}/tospec/`.toLowerCase()
+  const session = await $.session.id()
+  const res = await post($, '/api/mod/snapshot', { session, snapshot: out.payload.snapshot })
+  if (!res) {
+    state.project = undefined
+    await setStatus($, 'hub-offline', `no dashboard answered at ${state.hubUrl}`)
+    return 'hub-offline'
+  }
+  if (res.status !== 200) {
+    debug($, `the dashboard refused the snapshot: ${res.text}`)
+    await setStatus($, 'error', `the dashboard refused the snapshot: ${res.text}`)
+    return 'hub-refused'
+  }
+  const project = (JSON.parse(res.text) as { project: string }).project
+  // An unregister that landed while this push was out wins: take it back.
+  if (state.optedOut) {
+    await leave($, project, session)
+    return 'unregistered'
+  }
+  state.project = project
+  await setStatus($, 'connected')
+  return 'registered'
+}
+
+async function registerOnce($: EngineInterface): Promise<Attempt> {
+  if (!(await hubIsUp($))) {
+    await setStatus($, 'hub-offline', `no dashboard answered at ${state.hubUrl}`)
+    return 'hub-offline'
+  }
+  return push($)
+}
+
+/** One registration at a time: the loop and the command share it. */
+function attemptRegistration($: EngineInterface): Promise<Attempt> {
+  state.attempt ??= registerOnce($).finally(() => {
+    state.attempt = undefined
+  })
+  return state.attempt
+}
+
+async function handle($: EngineInterface, command: HubCommand): Promise<void> {
+  try {
+    if (command.kind === 'refresh') {
+      await push($)
+      return
+    }
+    const out = await runTospec($, ['dashboard', 'query'], JSON.stringify(command.request))
+    const response = out.ok
+      ? (out.payload.response as { status: number; body: unknown })
+      : { status: 502, body: { error: `tospec could not answer: ${out.error}` } }
+    await post($, '/api/mod/reply', { id: command.id, ...response })
+    const isWrite = command.request.method === 'POST'
+    if (isWrite && response.status >= 200 && response.status < 300) schedulePush($)
+  } catch (err) {
+    debug($, `a dashboard request failed: ${String(err)}`)
+  }
+}
+
+/**
+ * Registers, then long-polls for as long as the session lives. Ends early when
+ * the person unregisters, or when the CLI itself fails (no tospec on PATH, no
+ * tospec root): retrying that on a timer would start a process every few
+ * seconds for nothing, so the next turn or `register` tries again instead.
+ */
+async function loop($: EngineInterface): Promise<void> {
+  while (!state.ended && !state.optedOut) {
+    try {
+      if (!state.project) {
+        const attempt = await attemptRegistration($)
+        if (attempt === 'cli-failed' || attempt === 'unregistered') break
+        if (attempt !== 'registered') {
+          await sleep($, RETRY_MS)
+          continue
+        }
+      }
+      const project = state.project
+      const session = await $.session.id()
+      const res = await post($, '/api/mod/poll', { project, session })
+      // Unregistered while this poll was out: if it reached the hub after the
+      // leave, it registered the session again, so leave once more.
+      if (state.optedOut) {
+        if (project) await leave($, project, session)
+        break
+      }
+      if (!res) {
+        state.project = undefined
+        await setStatus($, 'hub-offline', `no dashboard answered at ${state.hubUrl}`)
+        await sleep($, RETRY_MS)
+        continue
+      }
+      // The hub restarted and forgot this project: register again at once.
+      if (res.status === 404) {
+        state.project = undefined
+        await setStatus($, 'connecting')
+        continue
+      }
+      if (res.status !== 200) {
+        debug($, `the dashboard refused a poll: ${res.text}`)
+        await sleep($, RETRY_MS)
+        continue
+      }
+      const { commands } = JSON.parse(res.text) as { commands: HubCommand[] }
+      for (const command of commands) void handle($, command)
+    } catch (err) {
+      debug($, `poll loop: ${String(err)}`)
+      await sleep($, RETRY_MS)
+    }
+  }
+  state.looping = false
+}
+
+function ensureLoop($: EngineInterface): void {
+  if (state.looping || state.ended || state.optedOut) return
+  state.looping = true
+  void loop($)
+}
+
+function schedulePush($: EngineInterface): void {
+  if (state.ended || state.optedOut) return
+  // Not registered yet: registering pushes a snapshot anyway.
+  if (!state.project) {
+    ensureLoop($)
+    return
+  }
+  state.pushTimer?.cancel()
+  state.pushTimer = $.clock.after(PUSH_DEBOUNCE_MS, () => {
+    state.pushTimer = undefined
+    void push($)
+  })
+}
+
+function touchesTospec(file: string): boolean {
+  const normalized = file.replace(/\\/g, '/').toLowerCase()
+  return state.tospecDir ? normalized.startsWith(state.tospecDir) : normalized.includes('/tospec/')
+}
+
+function describeStatus(status: HubStatus): string {
+  switch (status) {
+    case 'connected':
+      return `Registered with the tospec dashboard at ${state.hubUrl} (project ${state.project ?? '?'}).`
+    case 'connecting':
+      return `Connecting to the tospec dashboard at ${state.hubUrl}.`
+    case 'hub-offline':
+      return `No tospec dashboard answered at ${state.hubUrl}; retrying every ${RETRY_MS / 1000}s. Start one with: tospec dashboard start`
+    case 'unregistered':
+      return `Not registered with the tospec dashboard. Run /${COMMAND} register to register.`
+    case 'error':
+      return `Could not register with the tospec dashboard: ${state.detail || 'unknown error'}. Run /${COMMAND} register to retry.`
+  }
+}
+
+async function registerCommand($: EngineInterface): Promise<string> {
+  state.optedOut = false
+  state.ended = false
+  // Already registered: push now, so the dashboard shows the files as they are.
+  if (state.project) {
+    await push($)
+    return describeStatus(await read($, STATUS))
+  }
+  await setStatus($, 'connecting')
+  const attempt = attemptRegistration($)
+  // The loop joins this attempt and then polls; wake it if it is waiting out
+  // a retry, or start it if an unregister or a CLI failure ended it.
+  if (state.looping) state.wake?.()
+  else ensureLoop($)
+  await attempt
+  return describeStatus(await read($, STATUS))
+}
+
+async function unregisterCommand($: EngineInterface): Promise<string> {
+  if (state.optedOut) return describeStatus('unregistered')
+  state.optedOut = true
+  state.pushTimer?.cancel()
+  // A loop waiting out a retry ends now; one in a poll ends when it returns,
+  // which the leave below makes immediate.
+  state.wake?.()
+  const project = state.project
+  state.project = undefined
+  if (project) await leave($, project, await $.session.id())
+  await setStatus($, 'unregistered')
+  return project
+    ? `Unregistered from the tospec dashboard at ${state.hubUrl}. It keeps this project's last snapshot; run /${COMMAND} register to register again.`
+    : `Stopped registering with the tospec dashboard. Run /${COMMAND} register to register again.`
+}
+
+async function start($: EngineInterface): Promise<void> {
+  state.ended = false
+  state.hubUrl = ((await $.env.get('TOSPEC_DASHBOARD_URL')) || DEFAULT_HUB_URL).replace(/\/+$/, '')
+  state.optedOut = (await read($, STATUS)) === 'unregistered'
+  ensureLoop($)
+  // After the loop: a command that cannot be added must not cost the session
+  // its registration.
+  try {
+    await $.command.register({
+      name: COMMAND,
+      description: 'Show, register or unregister this session with the tospec dashboard hub',
+      argumentHint: '[status|register|unregister]',
+      immediate: true,
+    })
+  } catch (err) {
+    debug($, `could not add /${COMMAND}: ${String(err)}`)
+  }
+}
+
+async function end($: EngineInterface, reason: string, session: string): Promise<void> {
+  // A /clear ends the conversation, not the process: the loop goes on under
+  // the next session id, which every request reads afresh.
+  if (reason !== 'clear') state.ended = true
+  state.pushTimer?.cancel()
+  if (state.project) await leave($, state.project, session)
+}
+
+// --- session activity ----------------------------------------------------------
+
+/**
+ * What this session is doing, for the dashboard: its status (working from a
+ * turn's start to its end), the tool it is running, and a short log of
+ * prompts, replies and tool calls. Also lets the dashboard answer the session:
+ * an AskUserQuestion and a permission both race the terminal's own dialog,
+ * and whichever is answered first withdraws the other.
+ *
+ * Everything here is best effort: a hub that is down or refuses costs the
+ * session nothing, and every question falls back to the terminal's own dialog.
+ */
+
+type ActivityEvent = { kind: string; text?: string; tool?: string; target?: string; ok?: boolean }
+type AskAnswer = { kind: 'question'; answers: Record<string, string> } | { kind: 'permission'; allow: boolean }
+type AskWait = { answer: AskAnswer } | { pending: true } | { closed: string }
+
+// The hub keeps 500 characters of an event too; cutting here saves the bytes.
+const TEXT_LIMIT = 500
+const TARGET_LIMIT = 160
+// Reports in a burst (a turn's start, its prompt, its first tool) go as one.
+const FLUSH_MS = 250
+
+// Module state: a reload starts it over, losing at most one unsent report.
+const pending = {
+  status: undefined as 'working' | 'idle' | undefined,
+  action: undefined as string | null | undefined,
+  events: [] as ActivityEvent[],
+  timer: undefined as { cancel: () => void } | undefined,
+  root: undefined as string | undefined,
+}
+
+/**
+ * Permissions open on the dashboard, by `<tool> <target>`: the hook that
+ * opened one may not hear that the terminal answered it, but the tool call it
+ * belongs to always ends, and withdraws it then.
+ */
+const permissionAsks = new Map<string, string>()
+
+/** Takes a permission off the dashboard: the terminal settled it. */
+function withdrawPermission($: EngineInterface, key: string): void {
+  const id = permissionAsks.get(key)
+  if (!id) return
+  permissionAsks.delete(key)
+  void post($, '/api/mod/ask/close', { id })
+}
+
+function clip(text: string, max: number): string {
+  const flat = text.trim()
+  return flat.length > max ? flat.slice(0, max - 1) + '…' : flat
+}
+
+function textOf(content: readonly unknown[]): string {
+  return content
+    .map((block) => {
+      const b = block as { type?: string; text?: unknown }
+      return b.type === 'text' && typeof b.text === 'string' ? b.text : ''
+    })
+    .filter(Boolean)
+    .join('\n')
+}
+
+/** A file path as the project names it: relative to the session's root when inside it. */
+function relative(file: string): string {
+  const normalized = file.replace(/\\/g, '/')
+  const root = pending.root?.replace(/\\/g, '/').replace(/\/+$/, '')
+  if (root && normalized.toLowerCase().startsWith(root.toLowerCase() + '/')) return normalized.slice(root.length + 1)
+  return normalized
+}
+
+/** The one argument that says what a tool call is about. */
+function describeTarget(tool: string, input: Record<string, unknown>): string {
+  const pick = (...fields: string[]): string => {
+    for (const field of fields) if (typeof input[field] === 'string' && input[field]) return input[field] as string
+    return ''
+  }
+  let target: string
+  if (tool === 'Bash' || tool === 'PowerShell') target = pick('command').split(/\r?\n/)[0] ?? ''
+  else if (['Read', 'Write', 'Edit', 'MultiEdit', 'NotebookEdit'].includes(tool)) target = relative(pick('file_path', 'notebook_path'))
+  else if (tool === 'WebFetch') target = pick('url')
+  else target = pick('pattern', 'query', 'description', 'skill', 'prompt')
+  return clip(target, TARGET_LIMIT)
+}
+
+function report($: EngineInterface, change: Partial<Pick<typeof pending, 'status' | 'action'>>, event?: ActivityEvent): void {
+  if ('status' in change) pending.status = change.status
+  if ('action' in change) pending.action = change.action
+  if (event) pending.events.push(event)
+  if (pending.timer) return
+  pending.timer = $.clock.after(FLUSH_MS, () => {
+    pending.timer = undefined
+    void flush($)
+  })
+}
+
+async function flush($: EngineInterface): Promise<void> {
+  const body: Record<string, unknown> = { events: pending.events.splice(0) }
+  if (pending.status) body.status = pending.status
+  if (pending.action !== undefined) body.action = pending.action
+  pending.status = undefined
+  pending.action = undefined
+  const project = state.project
+  // Not registered: nobody is watching this session, so the report goes nowhere.
+  if (!project) return
+  await post($, '/api/mod/activity', { project, session: await $.session.id(), ...body })
+}
+
+async function postJson<T>($: EngineInterface, path: string, body: unknown): Promise<T | undefined> {
+  const res = await post($, path, body)
+  if (!res || res.status !== 200) return undefined
+  try {
+    return JSON.parse(res.text) as T
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Waits for the dashboard's answer, one held request at a time. A hook's own
+ * time budget does not run while a `$` call is in flight, so this may wait as
+ * long as the person takes; a timer of its own would spend the budget.
+ */
+async function waitForAnswer($: EngineInterface, id: string): Promise<AskAnswer | undefined> {
+  for (;;) {
+    const result = await postJson<AskWait>($, '/api/mod/ask/wait', { id })
+    if (!result || 'closed' in result) return undefined
+    if ('answer' in result) return result.answer
+  }
+}
+
+async function openAsk($: EngineInterface, ask: unknown): Promise<{ id: string | null; hold: boolean } | undefined> {
+  const project = state.project
+  if (!project) return undefined
+  return postJson($, '/api/mod/ask', { project, session: await $.session.id(), ask })
+}
+
+/** From the mod's `session.start`: tool targets are named relative to this root. */
+async function startActivity($: EngineInterface): Promise<void> {
+  pending.root = await $.session.root()
+}
+
+/** From the mod's `turn.complete`, for the main loop's turn. */
+function reportTurnEnd($: EngineInterface): void {
+  report($, { status: 'idle', action: null })
+}
+
+/**
+ * From the mod's `tool.call`, around the call: the main loop's tool shows as
+ * the session's action while it runs and as a log line once it ends; an
+ * AskUserQuestion is put to the dashboard as well as the terminal.
+ */
+async function aroundToolCall<E extends { tool: unknown; agentId?: string }, R extends { deny?: unknown; isError?: unknown }>(
+  $: EngineInterface,
+  e: E,
+  next: (e: E) => Promise<R>
+): Promise<R> {
+  if (e.agentId !== undefined) return next(e)
+  const tool = String(e.tool)
+  const input = e as unknown as Record<string, unknown>
+  if (tool === 'AskUserQuestion') return askQuestion($, input, () => next(e))
+  const target = describeTarget(tool, input)
+  report($, { action: `${tool} ${target}`.trim() })
+  const result = await next(e)
+  // Allowed or denied, the call is past its permission: a dashboard question
+  // still open for it was answered in the terminal.
+  withdrawPermission($, `${tool} ${target}`)
+  const ok = result.deny === undefined && !result.isError
+  report($, { action: null }, { kind: 'tool', tool, target, ok })
+  return result
+}
+
+/**
+ * AskUserQuestion: the terminal dialog and the dashboard both ask, and the
+ * first answer stands. Answering from the dashboard returns the result while
+ * the dialog is still open, which closes it; answering in the terminal
+ * withdraws the question from the dashboard.
+ */
+async function askQuestion<R>(
+  $: EngineInterface,
+  input: Record<string, unknown>,
+  dialog: () => Promise<R>
+): Promise<R> {
+  const opened = await openAsk($, { kind: 'question', questions: input.questions })
+  if (!opened?.id) return dialog()
+  const id = opened.id
+  const terminal = dialog().then(
+    (result) => ({ from: 'terminal' as const, result }),
+    (error: unknown) => ({ from: 'terminal' as const, error })
+  )
+  const remote = opened.hold
+    ? waitForAnswer($, id).then((answer) => (answer?.kind === 'question' ? { from: 'dashboard' as const, answer } : new Promise<never>(() => {})))
+    : new Promise<never>(() => {})
+  const first = await Promise.race([terminal, remote])
+  if (first.from === 'dashboard') {
+    return { result: { questions: input.questions, answers: first.answer.answers } } as R
+  }
+  void post($, '/api/mod/ask/close', { id })
+  if ('error' in first) throw first.error
+  return first.result
+}
+
+// --- registration ----------------------------------------------------------------
+
+export const register: Register = (on) => {
+  on('session.start', async ($, e, next) => {
+    const started = await next(e)
+    await startActivity($)
+    await start($)
+    return started
+  })
+
+  on('command.run', { command: COMMAND }, async ($, e) => {
+    // A run that passes no arguments can leave `args` out altogether.
+    const action = (e.args ?? '').trim().toLowerCase() || 'status'
+    if (action === 'register') return { text: await registerCommand($) }
+    if (action === 'unregister') return { text: await unregisterCommand($) }
+    if (action === 'status') return { text: describeStatus(await read($, STATUS)) }
+    return { text: `Usage: /${COMMAND} [status|register|unregister]` }
+  })
+
+  // The footer's right side: the engine's own mode labels, plus this one.
+  on('ui.render', { component: 'SessionMode' }, async ($, e, next) => {
+    const label = FOOTER_LABEL[await read($, STATUS)]
+    return next({ ...e, props: { ...e.props, modes: [...e.props.modes, label] } })
+  })
+
+  on('tool.call', async ($, e, next) => {
+    const result = await aroundToolCall($, e, next)
+    // A refused or failed edit changed nothing worth a push.
+    const changed = result.deny === undefined && !result.isError
+    const input = e as unknown as Record<string, unknown>
+    const file = input.file_path ?? input.notebook_path
+    if (changed && WRITE_TOOLS.has(String(e.tool)) && typeof file === 'string' && touchesTospec(file)) {
+      schedulePush($)
+    }
+    return result
+  })
+
+  // Catches what the edit hook cannot see: tospec commands run through Bash
+  // (archive, new change), and anything else that touched the files.
+  on('turn.complete', async ($, e, next) => {
+    const result = await next(e)
+    // A subagent's turn belongs to the main turn, which pushes when it ends.
+    if (e.agentId === undefined) {
+      schedulePush($)
+      reportTurnEnd($)
+    }
+    return result
+  })
+
+  on('session.end', async ($, e, next) => {
+    await end($, e.reason, e.sessionId)
+    return next(e)
+  })
+
+  on('turn.start', async ($, e, next) => {
+    report($, { status: 'working', action: null })
+    return next(e)
+  })
+
+  // The person's prompts and the model's replies, main conversation only: a
+  // subagent's rows are its own conversation, summed up by its tool call.
+  on('session.append', async ($, e, next) => {
+    if (e.agentId === undefined && !e.message.isMeta) {
+      const text = textOf(e.message.content)
+      if (text && e.door === 'prompt' && e.message.role === 'user') {
+        report($, {}, { kind: 'prompt', text: clip(text, TEXT_LIMIT) })
+      } else if (text && e.door === 'response' && e.message.role === 'assistant') {
+        report($, {}, { kind: 'reply', text: clip(text, TEXT_LIMIT) })
+      }
+    }
+    return next(e)
+  })
+
+  // Runs alongside the terminal's permission dialog, which does not wait for
+  // it: the dashboard offers the same question, and the first answer stands.
+  on('classic.PermissionRequest', async ($, e, next) => {
+    const beneath = await next(e)
+    // A settings hook already decided.
+    if (beneath.decision) return beneath
+    const target = describeTarget(e.tool_name, (e.tool_input ?? {}) as Record<string, unknown>)
+    const opened = await openAsk($, { kind: 'permission', tool: e.tool_name, target })
+    if (!opened?.id) return beneath
+    const key = `${e.tool_name} ${target}`
+    permissionAsks.set(key, opened.id)
+    // A read-only dashboard shows the question but cannot answer it.
+    if (!opened.hold) return beneath
+    // The terminal's dialog is open at the same time. When the person answers
+    // there first, this dispatch is abandoned: stop waiting and withdraw the
+    // question, so the dashboard cannot answer it a second time.
+    const abandoned = new Promise<undefined>((resolve) => {
+      if (next.signal.aborted) resolve(undefined)
+      else next.signal.addEventListener('abort', () => resolve(undefined), { once: true })
+    })
+    const answer = await Promise.race([waitForAnswer($, opened.id), abandoned])
+    if (answer?.kind !== 'permission') {
+      withdrawPermission($, key)
+      return beneath
+    }
+    permissionAsks.delete(key)
+    return {
+      ...beneath,
+      decision: answer.allow
+        ? { behavior: 'allow' as const }
+        : { behavior: 'deny' as const, message: 'Denied from the tospec dashboard.' },
+    }
+  })
+}