@pmelab/gtd 24.1.0 → 24.2.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "24.1.0",
+  "version": "24.2.0",
   "description": "Drive the gtd loop inside Claude Code: agent turns run as subagents, gtd decides every beat",
   "author": {
     "name": "Philipp Melab"

package/README.md

@@ -329,14 +329,17 @@ Then, in any repository:
 ```
 
 That starts a process from your requirements and drives it until it needs you.
-`/gtd fix` and `/gtd review [base]` take the two doors described below. Every
-human rest opens Claude Code's own question dialog, with a link to `gtd ui` for
-the step; review there, then answer **I'm done, continue**. When the process
-finishes, **Yes, open the pull request** (or `/gtd ship`) squashes it into one
-commit and opens it. A process can change hands at any gate: **Hand off to
-someone else** (or `/gtd throw @dev`) opens a draft pull request assigned to
-them, and `/gtd catch <pr>` picks it up exactly where it waits, so whoever wrote
-the requirements can hand the architecture to someone else. See
+`/gtd fix` and `/gtd review [base]` take the two doors described below. At every
+human rest Claude itself takes over: it walks you through the open questions one
+at a time, answers your own questions about the plan or the diff, records what
+you decide in the steering file the way the step asks, and moves the process on
+only when you say so. While a step runs you can keep asking; requests for
+changes wait for the next rest. When the process finishes, Claude offers to
+squash it into one commit and open its pull request (or run `/gtd ship`). A
+process can change hands at any gate: ask Claude to hand it off (or run
+`/gtd throw @dev`) and it opens a draft pull request assigned to them, and
+`/gtd catch <pr>` picks it up exactly where it waits, so whoever wrote the
+requirements can hand the architecture to someone else. See
 [Inside Claude Code](https://github.com/pmelab/gtd/blob/main/docs/driver.md#inside-claude-code-the-gtd-mod).
 
 ### Then let an agent build your own

package/claude/hooks/access.ts

@@ -63,3 +63,28 @@ function searchDenial(raw: unknown, globs: string[] | null, root: string) {
   })
   return inside ? undefined : deny("read", rel || ".", globs)
 }
+
+// What the main session may write while gtd drives: nothing while a step runs
+// (gtd commits the tree when it ends), only the steering file at a rest whose
+// mode is `qa`, anything otherwise. A review rest takes code edits as feedback.
+export type MainPhase = { isRunning: boolean; mode?: string; file?: string }
+
+export const RUNNING_DENIAL =
+  "gtd is running a step and commits the working tree when it ends: don't edit files now. Answer read-only, or record the request with mcp__gtd__note for the next step that waits on the person. /gtd stop stops the run."
+
+export function mainDenial(
+  tool: string,
+  input: Record<string, unknown>,
+  phase: MainPhase,
+  root: string,
+): string | undefined {
+  const key = WRITE[tool]
+  if (!key) return undefined
+  if (phase.isRunning) return RUNNING_DENIAL
+  if (phase.mode !== "qa" || !phase.file) return undefined
+  const raw = input[key]
+  const rel = typeof raw === "string" ? inRepo(raw, root) : undefined
+  return rel === phase.file
+    ? undefined
+    : `At this step only ${phase.file} may change: record the request there, as the step's instructions say.`
+}

package/claude/hooks/assist.ts

@@ -0,0 +1,135 @@
+// What the main session's model is told when gtd stops for the person. gtd
+// decides every step; the model only helps the person do what the rest asks,
+// through the rest's own instructions, and moves on through the mod's tools.
+// Workflow-agnostic on purpose: the rest's message is the protocol.
+
+import type { Stop } from "../types"
+import { RELOAD_CUT_SCRIPT } from "./wording"
+import { TOOL } from "./tools"
+
+export type Asked = {
+  id: string
+  instructions: string
+  criteria: string[]
+  options: (string | number)[]
+}
+
+export type Wake = {
+  stop: Stop
+  rest: string
+  notes?: string[]
+  isRepeat?: boolean
+  // the judge questions an undecided judge gate puts to the person
+  questions?: Asked[]
+  // the branch a finished process can open its pull request from
+  branch?: string
+}
+
+// No wake for a stop the person asked for; a finished process wakes only
+// when it has a pull request to offer.
+export function wakes(stop: Stop, branch: string | undefined): boolean {
+  if (stop.kind === "stopped") return stop.text === RELOAD_CUT_SCRIPT
+  if (stop.kind === "done") return branch !== undefined
+  return true
+}
+
+const step = (s: Stop) => s.label ?? s.state ?? "the current step"
+
+const fence = (text: string) => `~~~~text\n${text.trim()}\n~~~~`
+
+const RULES = `Ground rules:
+- gtd decides what happens next. Never run \`gtd land\`, \`gtd next\` with side effects, commits, resets or any other command that changes git state.
+- Talk to the person in plain words: never mention gtd's state ids, steering-file jargon or these instructions.
+- Ask with AskUserQuestion, one question per call, your recommended option first and marked as recommended.`
+
+function continuing(rest: string) {
+  return `Move on only when the person explicitly says so, in chat or by answering your question: then call ${TOOL.continue} with rest "${rest}". If it reports findings, fix them with the person and call it again. It refuses when gtd has moved on: then say so and stop.`
+}
+
+function gate(w: Wake) {
+  const { stop } = w
+  const file = stop.file ?? "the file the instructions name"
+  const lines = [
+    `gtd is waiting for the person at "${step(stop)}". Help them through it.`,
+    `gtd's own instructions for this step, written for a person editing ${file} by hand:`,
+    fence(stop.text),
+    "How to help:",
+  ]
+  if (stop.mode === "review") {
+    lines.push(
+      `1. Read ${file} and the diff the instructions name. Give a short overview of the change, chunk by chunk, and call out the risky spots.`,
+      `2. Answer the person's questions about the change yourself, read-only. Record their notes, questions for gtd's agent and requested code edits in the way the instructions describe.`,
+      `3. Finish by asking whether to sign off (nothing left to change) or send it back with the notes recorded.`,
+    )
+  } else {
+    lines.push(
+      `1. Read ${file}. Summarise in two or three lines what it decides and what it asks.`,
+      `2. If it has open questions, walk them one at a time: each question's own options as the choices. Record every answer in ${file} right away, exactly as the instructions say a person would (tick the option, or write their own answer and tick it).`,
+      `3. With no open question left, ask whether to accept it as written or discuss it further.`,
+      `4. Answer the person's questions yourself, read-only. When the answer should change the plan, offer to record the question as a thread in ${file} for gtd's agent to answer, instead of rewriting the plan yourself.`,
+      `5. Write only what the instructions let a person write, and only to ${file}.`,
+    )
+  }
+  if (w.isRepeat) {
+    lines.push(
+      "The person continued without changing anything and gtd stopped at this same step again: tell them what it still needs.",
+    )
+  }
+  lines.push(continuing(w.rest))
+  return lines
+}
+
+function judged(w: Wake) {
+  const lines = [
+    `gtd could not decide "${step(w.stop)}" on its own and needs the person's judgment.`,
+    "What gtd says about this step:",
+    fence(w.stop.text),
+  ]
+  for (const q of w.questions ?? []) {
+    lines.push(
+      `Question "${q.id}": ${q.instructions}\n${q.criteria.map((c) => `  - ${c}`).join("\n")}\n  Answers: ${q.options.map((o) => JSON.stringify(o)).join(", ")}`,
+    )
+  }
+  lines.push(
+    "Read whatever the questions are about, then put each one to the person, one at a time, with its answers as the choices and your own reading first.",
+    `Once all are answered and the person agrees, call ${TOOL.continue} with rest "${w.rest}" and verdicts mapping each question id to the chosen answer, exactly as listed. If the person would rather not decide, call it without verdicts: gtd then takes the cautious route.`,
+  )
+  return lines
+}
+
+function trouble(w: Wake) {
+  const { stop } = w
+  const why = stop.kind === "stalled" ? "is stuck" : "stopped on a problem"
+  return [
+    `gtd ${why} at "${step(stop)}":`,
+    fence(stop.text),
+    "Find the cause (read the error, the log it names, the working tree) and explain it in plain words. Propose a fix and make it only with the person's consent.",
+    continuing(w.rest),
+  ]
+}
+
+function finished(w: Wake) {
+  return [
+    `gtd finished the process on branch ${w.branch}.`,
+    `Tell the person in two or three lines what was built (read the branch's commits), then ask whether to combine it into one commit and open its pull request. On yes, call ${TOOL.ship}.`,
+  ]
+}
+
+export function wakePrompt(w: Wake): string {
+  const { stop } = w
+  const body =
+    stop.kind === "done"
+      ? finished(w)
+      : stop.kind === "gate"
+        ? stop.isJudge
+          ? judged(w)
+          : gate(w)
+        : trouble(w)
+  const notes = w.notes?.length
+    ? [
+        `While gtd ran, the person asked for the following. Fold each in now in the way this step allows, or tell them why it does not fit here:\n${w.notes.map((n) => `- ${n}`).join("\n")}`,
+      ]
+    : []
+  const extras = `Only when the person asks: ${TOOL.handoff} hands the process to someone else, ${TOOL.browser} opens gtd's browser view of this step.`
+  return [...body, ...notes, RULES, extras].join("\n\n")
+}

package/claude/hooks/drive.ts

@@ -11,6 +11,7 @@ export type Beat = {
   state?: string
   label?: string
   file?: string
+  mode?: string
   content?: string
   log?: string
   memory?: string
@@ -69,11 +70,15 @@ type Acted = { stop: Stop } | { stop?: undefined; verdict?: string }
 const where = (b: Beat) => ({ state: b.state, label: b.label })
 const failed = (b: Beat, text: string): Acted => ({ stop: { kind: "error", text, ...where(b) } })
 
+// How the opening beat is taken. `landTurn` names a memory scope whose agent
+// turn already ran (a reload cut the loop off while it did): the opening prompt
+// beat lands it, not repeats it. `isAnswered` is a person's answer to an opening
+// judge gate: their `verdict`, or none to land it untouched (the cautious default).
+export type Opening = { landTurn?: string; isAnswered?: boolean; verdict?: string }
+
 // The reference sh driver from docs/driver.md, beat for beat. gtd decides;
 // this only executes what `gtd next` and `gtd land` print.
-// `landTurn` names a memory scope whose agent turn already ran (a reload cut
-// the loop off while it did): the opening prompt beat lands it, not repeats it.
-export async function drive(io: Io, landTurn?: string): Promise<Stop> {
+export async function drive(io: Io, opening: Opening = {}): Promise<Stop> {
   // A judge gate answered on the previous beat that rests on the same state
   // again moved nothing: hand it to the human rather than pay for it twice.
   let judged: string | undefined
@@ -85,7 +90,7 @@ export async function drive(io: Io, landTurn?: string): Promise<Stop> {
     // decision, and an `acceptClean` first step must get to fire.
     if (beat > 1 && isTrue(b.idle)) return { kind: "done", text: await io.plain(), ...where(b) }
 
-    const acted = await act(io, b, beat, judged, beat === 1 ? landTurn : undefined)
+    const acted = await act(io, b, beat, judged, beat === 1 ? opening : {})
     if (acted.stop) return acted.stop
     judged = acted.verdict ? b.state : undefined
     const landed = await land(io, b, acted.verdict, true)
@@ -98,20 +103,22 @@ async function act(
   b: Beat,
   beat: number,
   judged: string | undefined,
-  landTurn: string | undefined,
+  opening: Opening,
 ): Promise<Acted> {
   switch (b.kind) {
     case "stalled":
       return { stop: { kind: "stalled", text: b.content ?? "", ...where(b) } }
     case "message":
-      return message(io, b, beat, judged)
+      return opening.isAnswered && b.judge
+        ? { verdict: opening.verdict }
+        : message(io, b, beat, judged)
     case "capture":
       return {}
     case "script":
       await io.sh(b.content ?? "", b.log)
       return {}
     case "prompt":
-      return agent(io, b, landTurn)
+      return agent(io, b, opening.landTurn)
     default:
       return failed(b, `unknown beat kind '${b.kind}'`)
   }
@@ -126,6 +133,7 @@ async function message(io: Io, b: Beat, beat: number, judged: string | undefined
   const stop: Stop = { kind: "gate", text: b.content ?? "", ...where(b) }
   if (b.judge) stop.isJudge = true
   if (b.file) stop.file = b.file
+  if (b.mode) stop.mode = b.mode
   return { stop }
 }
 

package/claude/hooks/judge.ts

@@ -111,3 +111,30 @@ export function toVerdicts(j: Judgment, reply: unknown): Verdict[] | string {
   }
   return out
 }
+
+// Each question as a person is asked it: its instructions, criteria and the
+// answers it takes; a string is why it cannot be asked.
+export function judgeQuestions(j: Judgment) {
+  return j.questions.map((q) => {
+    const levels = levelsOf(q)
+    if (typeof levels === "string") return levels
+    const meaning = levels.map(([label, text], i) =>
+      q.primitive === "score" ? `${i + 1}: ${text}` : `${label}: ${text}`,
+    )
+    return {
+      id: q.id,
+      instructions: q.instructions,
+      criteria: q.primitive === "noul" ? [q.criteria] : meaning,
+      options: optionsOf(q, levels),
+    }
+  })
+}
+
+// A person's `{ <id>: <answer> }` as gtd's verdicts, held with certainty.
+export function humanVerdicts(j: Judgment, answers: unknown): Verdict[] | string {
+  if (typeof answers !== "object" || answers === null) return "verdicts must be an object"
+  const reply = Object.fromEntries(
+    Object.entries(answers).map(([id, answer]) => [id, { answer, p: 1 }]),
+  )
+  return toVerdicts(j, reply)
+}

package/claude/hooks/register.tsx

@@ -2,39 +2,28 @@ import { atom, read, update } from "claude-code"
 import type { EngineInterface, Register } from "claude-code"
 
 import type { Run, Stop } from "../types"
-import { accessDenial } from "./access"
+import { accessDenial, mainDenial } from "./access"
 import type { AccessDef } from "./access"
+import { wakePrompt, wakes } from "./assist"
 import { afterReload, drive, isTrue } from "./drive"
-import type { Io, Turn, TurnEnd } from "./drive"
+import type { Io, Opening, Turn, TurnEnd } from "./drive"
 import { doors, enter } from "./doors"
 import { subagentModel } from "./models"
 import { personaSpec, resumable } from "./persona"
-import { JUDGE_SYSTEM, judgePrompt, judgeRunEnv, toVerdicts } from "./judge"
+import { JUDGE_SYSTEM, judgePrompt, judgeQuestions, judgeRunEnv, toVerdicts } from "./judge"
 import type { Judgment } from "./judge"
 import { catchFrom, throwTo } from "./handoff"
-import { documents } from "./schema"
+import { documents, readDocument } from "./schema"
 import { READ_ONLY_GIT, ship } from "./ship"
 import type { ShipIo } from "./ship"
+import { decideContinue, restId, TOOLS } from "./tools"
 import {
-  ANYONE,
   beatLine,
-  CANCEL,
-  CLOSE,
-  CONTINUE,
-  gateOptions,
-  HANDOFF,
-  handoffQuestion,
   headline,
-  LATER,
   pushText,
-  runningLine,
-  question,
   restartLine,
   RELOAD_CUT_SCRIPT,
-  SAFE,
-  SHIP,
-  shipQuestion,
-  STALE,
+  runningLine,
   TONE,
 } from "./wording"
 
@@ -53,11 +42,9 @@ const TEN_MINUTES = 600_000
 // gtd refuses outside the repository root; every process runs there.
 let root = "."
 let gateUi: { stop(): void } | undefined
-// bumped per rest, so an answer or hand-back for an older rest is ignored
+// bumped per rest, so a browser view of an older rest is ignored
 let gateToken = 0
 let lastGate: { state?: string; head: string } | undefined
-// the question dialog this mod has open, to mark it stale once gtd moves on
-let openAsk: { token: number; text: string } | undefined
 
 let stopRequested = false
 // when the current step began, for the band's elapsed time
@@ -66,6 +53,8 @@ let stepStartedAt = Date.now()
 // together cannot both pass the isRunning check and start two drivers.
 let isDriving = false
 let isShipping = false
+// bumped by every stop, so a queued continue that was mid-check sees it
+let stopCount = 0
 // subagents answering into a file: what each may touch (see tool.call)
 const delegates = new Map<string, { file: string; mayRun: RegExp | undefined }>()
 const ours = new Set<string>()
@@ -229,15 +218,16 @@ async function head($: $) {
   return (await $.process.run(["git", "rev-parse", "HEAD"], { cwd: root })).stdout.trim()
 }
 
-async function start($: $, landTurn?: string) {
+async function start($: $, opening: Opening = {}) {
   if (isDriving) return
   isDriving = true
   closeUi()
   moveOn($)
   stopRequested = false
   await findRoot($)
-  await update($, run, () => ({ isRunning: true, beat: 0 }))
-  void drive(io($), landTurn)
+  // Requests not yet handed to a rest outlive a restart.
+  await update($, run, (r) => ({ isRunning: true, beat: 0, notes: r.notes }))
+  void drive(io($), opening)
     .catch((err: unknown): Stop => ({ kind: "error", text: String(err) }))
     .then(async (stop) => {
       isDriving = false
@@ -245,14 +235,57 @@ async function start($: $, landTurn?: string) {
       const isRepeat =
         stop.kind === "gate" && at.state === lastGate?.state && at.head === lastGate?.head
       lastGate = at
-      await update($, run, (r) => ({ ...r, isRunning: false, stop, isRepeat }))
+      const rest = restId(at.head, stop.state)
+      await update($, run, (r) => ({ ...r, isRunning: false, stop, rest, isRepeat }))
       $.ui.status(undefined)
       $.ui.toast(headline(stop))
-      if (stop.kind === "gate" || stop.kind === "done") await openGate($)
-      else await push($, stop)
+      await push($, stop)
+      await wake($)
     })
 }
 
+// A rest that needs the person hands the session's model a prompt to help them
+// through it; the model moves gtd on only through the mod's tools.
+async function wake($: $) {
+  const r = await read($, run)
+  const stop = r.stop
+  if (!stop || !r.rest) return
+  const branch = stop.kind === "done" ? await shippable($) : undefined
+  if (!wakes(stop, branch)) return
+  const questions = stop.isJudge ? await openQuestions($) : undefined
+  const text = wakePrompt({
+    stop,
+    rest: r.rest,
+    notes: r.notes,
+    isRepeat: r.isRepeat,
+    questions,
+    branch,
+  })
+  await update($, run, (x) => ({ ...x, notes: undefined }))
+  // Not from inside the hook that started the run: a prompt submitted there
+  // would wait on that hook's own turn.
+  $.clock.after(0, () => void $.prompt.submit({ text }))
+}
+
+async function openQuestions($: $) {
+  try {
+    const j = readDocument<Judgment>("judge --json", await gtd($, ["judge", "--json"]))
+    return judgeQuestions(j).filter((q) => typeof q !== "string")
+  } catch {
+    return undefined
+  }
+}
+
+// The branch a finished process can open its pull request from, if any.
+async function shippable($: $) {
+  const branch = (
+    await $.process.run(["git", "rev-parse", "--abbrev-ref", "HEAD"], { cwd: root })
+  ).stdout.trim()
+  if (["main", "master", "HEAD"].includes(branch)) return undefined
+  const summary = await $.process.run(["gtd", "summary"], { cwd: root })
+  return summary.exitCode === 0 ? branch : undefined
+}
+
 // A new process starts from the requirements written to the steering file an
 // idle rest names; the opening beat captures them like a hand-edit.
 async function begin($: $, requirements: string) {
@@ -318,38 +351,22 @@ function serveUi($: $, token: number) {
   return isReady
 }
 
-// The engine's own question dialog, not a pane: it is the state herdr, the
-// desktop app and Remote Control recognize as "waiting on you".
-async function openGate($: $) {
+// `gtd ui` on request only: the session's model is the main way through a rest.
+async function browse($: $) {
+  const r = await read($, run)
+  if (r.isRunning || r.stop?.kind !== "gate") return "gtd is not waiting at a step right now."
+  if (r.stop.isJudge) return "This step has no browser view."
+  if (r.url) return `Open in your browser: ${r.url}`
   closeUi()
   const token = ++gateToken
-  await update($, run, (r) => ({ ...r, url: undefined, uiNote: undefined }))
-  const stop = (await read($, run)).stop
-  if (stop?.kind === "done") return offerShip($, token)
-  // A judge gate has no screen in gtd ui: it refuses to start there.
-  if (!stop?.isJudge) await Promise.race([serveUi($, token), $.clock.sleep(8000)])
-  const r = await read($, run)
-  if (token !== gateToken || !r.stop) return
-  await push($, r.stop, r.url)
-  // Also a transcript line: Remote Control and the phone show no dialog.
-  if (r.url) $.ui.log(`Open in your browser: ${r.url}`)
-  const answer = await ask($, token, question(r), gateOptions(r.stop))
-  if (token !== gateToken) return
-  if (answer === CONTINUE || answer === SAFE) await proceed($)
-  if (answer === HANDOFF) await askThrow($)
-}
-
-// The engine's own dialog; undefined when dismissed. Remembered, so it can be
-// marked out of date once gtd moves on without it (a mod cannot close it).
-async function ask($: $, token: number, text: string, options: string[]) {
-  openAsk = { token, text }
-  try {
-    return await $.ui.ask(text, { header: "gtd", options })
-  } catch {
-    return undefined
-  } finally {
-    if (openAsk?.text === text) openAsk = undefined
+  await update($, run, (x) => ({ ...x, url: undefined, uiNote: undefined }))
+  await Promise.race([serveUi($, token), $.clock.sleep(8000)])
+  const now = await read($, run)
+  if (now.url) {
+    if (now.stop) await push($, now.stop, now.url)
+    return `Open in your browser: ${now.url}`
   }
+  return `The browser view did not start${now.uiNote ? `: ${now.uiNote}` : "."}`
 }
 
 // A gate is news even when nobody watches the terminal: a push reaches the
@@ -367,13 +384,8 @@ async function push($: $, stop: Stop, url?: string) {
   }
 }
 
-async function askThrow($: $) {
-  const answer = await ask($, gateToken, handoffQuestion, [ANYONE, CANCEL])
-  if (answer && answer !== CANCEL) await throwNow($, answer === ANYONE ? undefined : answer.trim())
-}
-
 async function throwNow($: $, target: string | undefined) {
-  if ((await read($, run)).isRunning) return $.ui.log("Stop the loop first: /gtd stop.")
+  if ((await read($, run)).isRunning) return "Stop the loop first: /gtd stop."
   closeUi()
   moveOn($)
   const b = await docs($).next()
@@ -396,10 +408,8 @@ async function throwNow($: $, target: string | undefined) {
       uiNote: undefined,
       stop: { kind: "stopped" as const, text: thrown.text },
     }))
-  } else if ((await read($, run)).stop?.kind === "gate") {
-    // Nothing left: the person is still at the gate they tried to throw.
-    void openGate($)
   }
+  return thrown.text
 }
 
 async function enterNow($: $, door: string, args: string[]) {
@@ -420,26 +430,17 @@ async function catchNow($: $, ref: string) {
   if (b.kind === "message") {
     const stop: Stop = { kind: "gate", text: b.content ?? "", state: b.state, label: b.label }
     if (b.judge) stop.isJudge = true
-    await update($, run, (r) => ({ ...r, stop, isRepeat: false }))
-    void openGate($)
+    if (b.file) stop.file = b.file
+    if (b.mode) stop.mode = b.mode
+    const rest = restId(await head($), b.state)
+    await update($, run, (r) => ({ ...r, stop, rest, isRepeat: false }))
+    void wake($)
   } else {
     await start($)
   }
   return caught.text
 }
 
-// A finished process on a feature branch is one answer away from its pull request.
-async function offerShip($: $, token: number) {
-  const branch = (
-    await $.process.run(["git", "rev-parse", "--abbrev-ref", "HEAD"], { cwd: root })
-  ).stdout.trim()
-  const summary = await $.process.run(["gtd", "summary"], { cwd: root })
-  if (summary.exitCode !== 0 || ["main", "master", "HEAD"].includes(branch)) return
-  await push($, { kind: "done", text: "", label: `ready to open a pull request for ${branch}` })
-  const answer = await ask($, token, shipQuestion(branch), [SHIP, LATER])
-  if (answer === SHIP && token === gateToken) await shipNow($, false)
-}
-
 // Ship's text turns need git to read the process, so they run as a subagent.
 // Its answer is a file, not its hand-back: a hand-back never reaches a mod.
 // `mayRun`: the only shell commands the subagent may run; none when absent.
@@ -549,7 +550,7 @@ function shipIo($: $): ShipIo {
 }
 
 async function shipNow($: $, isDry: boolean) {
-  if (isShipping) return $.ui.log("A pull request is already being prepared.")
+  if (isShipping) return "A pull request is already being prepared."
   isShipping = true
   await dismiss($)
   $.ui.status(isDry ? "previewing the pull request…" : "opening the pull request…")
@@ -561,6 +562,7 @@ async function shipNow($: $, isDry: boolean) {
   $.ui.status(undefined)
   for (const line of shipped.text.split("\n")) $.ui.log(line)
   $.ui.toast(shipped.ok ? "pull request ready" : "opening the pull request failed")
+  return shipped.text
 }
 
 // Turns a missing CLI or a wrong directory into an instruction, not a stack trace.
@@ -624,17 +626,125 @@ function moveOn($: $) {
   $.ui.invalidate("ui.render")
 }
 
-async function proceed($: $) {
+// The one way on from a rest, for the model's tool and the band's Continue
+// alike; a string is why it did not move.
+// `isInTurn`: asked from the model's own turn. Its subagents would then count
+// as that turn's background work and keep it open, so the loop starts once the
+// turn has ended; until then the continue waits in the run state.
+async function proceed(
+  $: $,
+  rest?: string,
+  verdicts?: unknown,
+  isInTurn = false,
+): Promise<string | undefined> {
+  const r = await read($, run)
+  const go = await decideContinue(r, rest, verdicts, {
+    current: () => currentRest($, r.stop?.state),
+    validate: () => validateRest($),
+    judgment: async () => {
+      const doc = await gtd($, ["judge", "--json"]).catch(() => undefined)
+      return doc === undefined ? undefined : readDocument<Judgment>("judge --json", doc)
+    },
+  })
+  if (go.refuse !== undefined) return go.refuse
+  const opening = r.stop?.isJudge ? { isAnswered: true, verdict: go.verdict } : {}
+  if (isInTurn) {
+    await update($, run, (x) => ({ ...x, pending: { rest: r.rest ?? "", ...opening } }))
+    return undefined
+  }
+  await leaveRest($)
+  await start($, opening)
+  return undefined
+}
+
+// The rest's own `gtd validate` script, run.
+async function validateRest($: $) {
+  const script = await gtd($, ["validate"])
+  if (script.trim().startsWith("nothing to validate")) return { ok: true, out: "" }
+  const v = await $.process.run(["sh", "-c", script], { cwd: root, timeoutMs: TEN_MINUTES })
+  return { ok: v.exitCode === 0, out: `${v.stdout}${v.stderr}`.trim() }
+}
+
+async function tellModel($: $, text: string, stops: number) {
+  if (stops === stopCount) await $.prompt.submit({ text })
+}
+
+async function leaveRest($: $) {
   moveOn($)
   closeUi()
-  await update($, run, (r) => ({ ...r, stop: undefined, url: undefined, uiNote: undefined }))
-  await start($)
+  await update($, run, (x) => ({
+    ...x,
+    stop: undefined,
+    rest: undefined,
+    pending: undefined,
+    url: undefined,
+    uiNote: undefined,
+  }))
+}
+
+// The rest gtd is at now: HEAD and, when the stop named one, its state.
+// Undefined when gtd cannot say, which checks nothing.
+async function currentRest($: $, state: string | undefined) {
+  try {
+    const now = state === undefined ? undefined : (await docs($).next()).state
+    return restId(await head($), now)
+  } catch {
+    return undefined
+  }
+}
+
+// A continue the model asked for, once its turn is over: only if gtd still
+// waits where the person answered, its file still validates (it can change
+// outside this session, or across a reload), and no stop came in meanwhile.
+async function launchPending($: $) {
+  const stops = stopCount
+  const r = await read($, run)
+  const pending = r.pending
+  if (!pending) return
+  await update($, run, (x) => ({ ...x, pending: undefined }))
+  const now = await currentRest($, r.stop?.state)
+  if (now !== undefined && now !== pending.rest) {
+    $.ui.toast("gtd moved on before it could continue: nothing was landed")
+    return
+  }
+  if (r.stop?.kind === "gate" && !r.stop.isJudge) {
+    const v = await validateRest($)
+    if (!v.ok) {
+      const text = `gtd did not continue: the step's file no longer validates.\n${v.out}\nFix it with the person, then call continue again with rest "${pending.rest}".`
+      if (stops === stopCount) $.clock.after(0, () => void tellModel($, text, stops))
+      return
+    }
+  }
+  // Nothing awaited between this check and `start`'s own reset of the stop
+  // flag, so a stop cannot slip in between; `start` also clears the rest.
+  if (stops !== stopCount) return
+  await start($, pending.isAnswered ? { isAnswered: true, verdict: pending.verdict } : {})
+}
+
+async function note($: $, text: string) {
+  const r = await read($, run)
+  if (!r.isRunning && !r.stop) return "No gtd process is underway here."
+  await update($, run, (x) => ({ ...x, notes: [...(x.notes ?? []), text] }))
+  return "Noted for the next step that waits on the person."
+}
+
+async function bandContinue($: $) {
+  const refused = await proceed($)
+  if (!refused) return
+  $.ui.toast(refused.split("\n")[0]!)
+  for (const line of refused.split("\n")) $.ui.log(line)
 }
 
 async function dismiss($: $) {
   moveOn($)
   closeUi()
-  await update($, run, (r) => ({ ...r, stop: undefined, url: undefined, uiNote: undefined }))
+  await update($, run, (r) => ({
+    ...r,
+    stop: undefined,
+    rest: undefined,
+    url: undefined,
+    uiNote: undefined,
+  }))
 }
 
 const DROPPED = "gtd subagent notice"
@@ -643,12 +753,18 @@ async function refreshBand($: $) {
   if ((await read($, run)).isRunning) $.ui.invalidate("ui.render")
 }
 
+// A continue still waiting for the model's turn to end is dropped too.
+async function stopNow($: $) {
+  stopRequested = true
+  stopCount++
+  if (!(await read($, run)).pending) return "Stopping after the current beat."
+  await update($, run, (x) => ({ ...x, pending: undefined }))
+  return "Cancelled the pending continue; gtd stays where it is."
+}
+
 // `/gtd [verb] …`; anything that is not a verb is a new process's requirements.
 async function command($: $, arg: string): Promise<string | undefined> {
-  if (arg === "stop") {
-    stopRequested = true
-    return "Stopping after the current beat."
-  }
+  if (arg === "stop") return stopNow($)
   const problem = await preflight($)
   if (problem) return problem
   const [verb = "", ...rest] = arg.split(/\s+/)
@@ -656,15 +772,15 @@ async function command($: $, arg: string): Promise<string | undefined> {
     case "status":
       return gtd($, ["next"])
     case "throw":
-      void throwNow($, rest[0])
-      return undefined
+      return throwNow($, rest[0])
+    case "ui":
+      return browse($)
     case "catch":
       return rest[0]
         ? catchNow($, rest[0])
         : "Name the pull request or branch: /gtd catch <number|branch>."
     case "ship":
-      void shipNow($, rest[0] === "-n" || rest[0] === "--dry-run")
-      return undefined
+      return shipNow($, rest[0] === "-n" || rest[0] === "--dry-run")
     case "":
       return resume($)
     default:
@@ -703,12 +819,70 @@ async function resumeAfterReload($: $, was: Run) {
       state: was.state,
       label: was.label,
     }
-    await update($, run, (r) => ({ ...r, stop }))
+    const rest = restId(await head($), was.state)
+    await update($, run, (r) => ({ ...r, stop, rest }))
     $.ui.status(undefined)
     $.ui.toast(headline(stop))
+    await wake($)
     return
   }
-  await start($, next === "land" ? inflight?.memory : undefined)
+  await start($, next === "land" ? { landTurn: inflight?.memory } : {})
+}
+
+// Whether an agent is one of gtd's workers or spawned (at any depth) by one;
+// any other agent works for the session's model and shares its limits.
+const lineage = new Map<string, boolean>()
+async function isOurs($: $, id: string) {
+  if (ours.has(id)) return true
+  const known = lineage.get(id)
+  if (known !== undefined) return known
+  const byId = new Map((await $.agent.list()).map((a) => [a.id, a]))
+  let parent = byId.get(id)?.parentId
+  for (let hops = 0; parent && hops < 16; hops++) {
+    if (ours.has(parent)) break
+    parent = byId.get(parent)?.parentId
+  }
+  const isWorker = parent !== undefined && ours.has(parent)
+  lineage.set(id, isWorker)
+  return isWorker
+}
+
+// What a subagent this mod spawned may not do: write outside its step's
+// access, or, answering into a file, anything but that.
+function subagentDenial(agentId: string, e: Record<string, unknown>) {
+  if (!ours.has(agentId)) return undefined
+  const access = accesses.get(agentId)
+  const denial = access && accessDenial(String(e.tool), e, access, root)
+  if (denial) return denial
+  const delegated = delegates.get(agentId)
+  if (!delegated) return undefined
+  if (e.tool === "Write" && e.file_path !== delegated.file) {
+    return `Write only your answer, to ${delegated.file}.`
+  }
+  if (e.tool === "Bash" && !delegated.mayRun?.test(String(e.command).trim())) {
+    return "Only read-only git commands, without shell syntax, are allowed here."
+  }
+  return undefined
+}
+
+// What the main session may write now (see mainDenial).
+async function phase($: $) {
+  const r = await read($, run)
+  const stop = r.stop
+  const atQa = stop?.kind === "gate" && !stop.isJudge
+  // A continue waiting for the turn to end is as good as running: the file
+  // it validated must not change before it lands.
+  const isRunning = r.isRunning || r.pending !== undefined
+  return { isRunning, mode: atQa ? stop.mode : undefined, file: stop?.file }
+}
+
+// A tool's answer. For `continue`, any text is a refusal the model reads as an
+// error; the other tools report what happened either way.
+function answer(text: string | undefined, isReport = false) {
+  if (text === undefined) {
+    return { result: "gtd continues as soon as this turn ends: end your turn now." }
+  }
+  return isReport ? { result: text } : { deny: text }
 }
 
 export const register: Register = (on) => {
@@ -716,16 +890,17 @@ export const register: Register = (on) => {
     // The band's elapsed time ticks while a step runs.
     $.clock.every(10_000, () => void refreshBand($))
     for (const id of await read($, agents)) ours.add(id)
-    // A reload drops the loop mid-beat and closes an open dialog; gtd keeps
-    // its state in git, so pick both up again.
+    // A reload drops the loop mid-beat; gtd keeps its state in git, so pick it
+    // up again. A rest needs nothing: the model already holds its prompt.
     const was = await read($, run)
     if (was.isRunning) void resumeAfterReload($, was)
-    else if (was.stop?.kind === "gate") void findRoot($).then(() => openGate($))
+    else void findRoot($).then(() => launchPending($))
+    for (const tool of TOOLS) await $.tool.register(tool)
     await $.command.register({
       name: "gtd",
       description: "Drive gtd until it rests on you; pass requirements to start a new process",
       argumentHint:
-        "[requirements | <door> [args] | stop | status | ship [-n] | throw [@user] | catch <pr|branch>]",
+        "[requirements | <door> [args] | stop | status | ui | ship [-n] | throw [@user] | catch <pr|branch>]",
       immediate: true,
     })
     return next(e)
@@ -737,6 +912,7 @@ export const register: Register = (on) => {
   }).catch(($, e, next) => ({ text: next.error.message }))
 
   on("turn.complete", ($, e, next) => {
+    if (!e.agentId) void launchPending($)
     if (e.agentId && ours.has(e.agentId)) {
       const end: TurnEnd =
         e.reason === "answer" ? { ok: true } : { ok: false, why: `agent turn ended: ${e.reason}` }
@@ -750,20 +926,13 @@ export const register: Register = (on) => {
 
   // The loop lands a turn when it ends; work left running in the background
   // would still be writing the tree gtd is committing.
-  on("tool.call", ($, e, next) => {
-    if (!e.agentId || !ours.has(e.agentId)) return next(e)
-    const access = accesses.get(e.agentId)
-    const denial = access && accessDenial(String(e.tool), e, access, root)
+  on("tool.call", async ($, e, next) => {
+    const isWorker = e.agentId !== undefined && (await isOurs($, e.agentId))
+    const denial = isWorker
+      ? subagentDenial(e.agentId!, e)
+      : mainDenial(String(e.tool), e, await phase($), root)
     if (denial) return { deny: denial }
-    const delegated = delegates.get(e.agentId)
-    if (delegated) {
-      if (e.tool === "Write" && e.file_path !== delegated.file) {
-        return { deny: `Write only your answer, to ${delegated.file}.` }
-      }
-      if (e.tool === "Bash" && !delegated.mayRun?.test(String(e.command).trim())) {
-        return { deny: "Only read-only git commands, without shell syntax, are allowed here." }
-      }
-    }
+    if (!e.agentId || !ours.has(e.agentId)) return next(e)
     if (e.tool === "Bash") {
       return next({ ...e, run_in_background: false, timeout: e.timeout ?? TEN_MINUTES })
     }
@@ -781,29 +950,19 @@ export const register: Register = (on) => {
     return next(e)
   })
 
-  // A dialog gtd has moved past still waits for an answer; say it is stale.
-  on("ui.render", { component: "AskUserQuestion" }, ($, e, next) => {
-    const [first] = e.props.questions as { question?: string }[]
-    if (!openAsk || openAsk.token === gateToken || first?.question !== openAsk.text) return next(e)
-    return next({
-      ...e,
-      props: {
-        ...e.props,
-        questions: [
-          {
-            ...first,
-            question: STALE,
-            header: "gtd",
-            multiSelect: false,
-            options: [
-              { label: CLOSE, description: "Nothing happens." },
-              { label: LATER, description: "Nothing happens." },
-            ],
-          },
-        ],
-      },
-    })
-  })
+  on("tool.call", { tool: "mcp__gtd__continue" }, async ($, e) =>
+    answer(await proceed($, String(e.rest ?? ""), e.verdicts, true)),
+  )
+  on("tool.call", { tool: "mcp__gtd__note" }, async ($, e) =>
+    answer(await note($, String(e.text ?? "")), true),
+  )
+  on("tool.call", { tool: "mcp__gtd__handoff" }, async ($, e) =>
+    answer(await throwNow($, typeof e.to === "string" && e.to ? e.to : undefined), true),
+  )
+  on("tool.call", { tool: "mcp__gtd__ship" }, async ($, e) =>
+    answer(await shipNow($, e.dryRun === true), true),
+  )
+  on("tool.call", { tool: "mcp__gtd__browser" }, async ($) => answer(await browse($), true))
 
   on("agent.offer", ($, e, next) => (e.agent.startsWith("gtd:") ? { isOffered: false } : next(e)))
 
@@ -832,7 +991,7 @@ export const register: Register = (on) => {
           <Text color={TONE[stop.kind]} bold>
             gtd {headline(stop)}
           </Text>
-          <Button key="go" label="Continue" variant="primary" onPress={() => proceed($)} />
+          <Button key="go" label="Continue" variant="primary" onPress={() => bandContinue($)} />
           <Button key="dismiss" label="Dismiss" role="dismiss" onPress={() => dismiss($)} />
         </Box>
         {ui && <Text dimColor>{ui}</Text>}

package/claude/hooks/tools.ts

@@ -0,0 +1,121 @@
+// The only way the main session's model moves gtd: tools the mod serves. Each
+// checks the run before it acts, so a model cannot skip a rest or answer one
+// gtd has already left.
+
+import type { Run } from "../types"
+import { humanVerdicts } from "./judge"
+import type { Judgment } from "./judge"
+
+export const TOOL = {
+  continue: "mcp__gtd__continue",
+  note: "mcp__gtd__note",
+  handoff: "mcp__gtd__handoff",
+  ship: "mcp__gtd__ship",
+  browser: "mcp__gtd__browser",
+} as const
+
+export const TOOLS = [
+  {
+    name: "continue",
+    description:
+      "Moves the gtd process on from the step it waits at. Call it ONLY after the person explicitly said to continue. `rest` is the rest id gtd gave you for this step. `verdicts` only at a step gtd's judge could not decide: each question id mapped to the person's chosen answer. Refused when gtd has moved on, while a step runs, or when the step's file does not validate; the result says why.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        rest: { type: "string" },
+        verdicts: { type: "object", additionalProperties: { type: ["string", "number"] } },
+      },
+      required: ["rest"],
+    },
+  },
+  {
+    name: "note",
+    description:
+      "Records a request the person makes while gtd runs a step (a change, something to consider), for the next step that waits on them. Use it instead of editing files while gtd runs.",
+    inputSchema: {
+      type: "object",
+      properties: { text: { type: "string" } },
+      required: ["text"],
+    },
+  },
+  {
+    name: "handoff",
+    description:
+      "Hands the gtd process to someone else: pushes the branch and opens or refreshes a draft pull request assigned to them. Call it only when the person asks. `to`: their GitHub username; omit it to leave the process for anyone.",
+    inputSchema: { type: "object", properties: { to: { type: "string" } } },
+  },
+  {
+    name: "ship",
+    description:
+      "Combines the finished gtd process into one commit, pushes it and opens or updates its pull request. Call it only after the person agreed. `dryRun` previews without writing anything.",
+    inputSchema: { type: "object", properties: { dryRun: { type: "boolean" } } },
+  },
+  {
+    name: "browser",
+    description:
+      "Starts gtd's browser view of the step it waits at and returns its address. Call it only when the person wants it.",
+    inputSchema: { type: "object", properties: {} },
+  },
+]
+
+// A rest is the state gtd waits at on a given HEAD: once either moves, an
+// answer meant for it no longer applies. Survives a mod reload, unlike a counter.
+export const restId = (head: string, state: string | undefined) =>
+  `${head.slice(0, 12)}:${state ?? "?"}`
+
+export type Proceed = { refuse: string } | { refuse?: undefined; verdict?: string }
+
+export type ContinueIo = {
+  // the rest gtd is at now; undefined when it cannot say
+  current(): Promise<string | undefined>
+  // the rest's own `gtd validate` script, run; ok when there is nothing to check
+  validate(): Promise<{ ok: boolean; out: string }>
+  judgment(): Promise<Judgment | undefined>
+}
+
+// What `continue` may do from here. `rest` undefined is the band's Continue,
+// which always means the rest on screen.
+export async function decideContinue(
+  run: Run,
+  rest: string | undefined,
+  verdicts: unknown,
+  io: ContinueIo,
+): Promise<Proceed> {
+  if (run.isRunning) return { refuse: "gtd is already running a step." }
+  const stop = run.stop
+  if (!stop) return { refuse: "Nothing is waiting: gtd has no rest open. /gtd drives it." }
+  if (stop.kind === "done") {
+    return { refuse: `The process is finished: ${TOOL.ship} opens its pull request.` }
+  }
+  if (rest !== undefined && rest !== run.rest) {
+    return {
+      refuse: "gtd has moved on from that step; it no longer waits there. Nothing was changed.",
+    }
+  }
+  // Another terminal or a branch switch can move gtd under a waiting answer.
+  const now = await io.current()
+  if (now !== undefined && now !== run.rest) {
+    return {
+      refuse:
+        "gtd is no longer at that step (it changed outside this session): /gtd shows where it is.",
+    }
+  }
+  if (stop.kind === "gate" && stop.isJudge) return judged(verdicts, io)
+  if (verdicts !== undefined) return { refuse: "This step takes no verdicts." }
+  if (stop.kind === "gate") {
+    const v = await io.validate()
+    if (!v.ok) return { refuse: `The step's file does not validate yet:\n${v.out}` }
+  }
+  return {}
+}
+
+// No verdicts lands the gate untouched: the cautious default.
+async function judged(verdicts: unknown, io: ContinueIo): Promise<Proceed> {
+  if (verdicts === undefined) return {}
+  const j = await io.judgment()
+  if (!j) return { refuse: "gtd no longer has a judgment open here." }
+  const v = humanVerdicts(j, verdicts)
+  return typeof v === "string"
+    ? { refuse: `Those verdicts don't fit: ${v}` }
+    : { verdict: JSON.stringify(v) }
+}

package/claude/hooks/wording.ts

@@ -1,46 +1,13 @@
-// Everything the mod says to a person. Plain words: no gtd state ids, no tool
-// names, and options that say what choosing them does.
+// Everything the mod itself shows a person. Plain words: no gtd state ids.
 
-import type { Run, Stop } from "../types"
+import type { Stop } from "../types"
 import type { Beat } from "./drive"
 
-export const CONTINUE = "I'm done, continue"
-export const SAFE = "Continue with the safe choice"
-export const HANDOFF = "Hand off to someone else"
-export const LATER = "Not now"
-export const SHIP = "Yes, open the pull request"
-export const ANYONE = "Anyone on the team"
-export const CANCEL = "Cancel"
-export const CLOSE = "Close"
-
-export const gateOptions = (stop: Stop) => [stop.isJudge ? SAFE : CONTINUE, HANDOFF, LATER]
-
 const step = (s: { label?: string; state?: string }) => s.label ?? s.state ?? "the next step"
 
-export function question(r: Run) {
-  const stop = r.stop as Stop
-  if (stop.isJudge) {
-    return `gtd can't decide this step on its own: ${step(stop)}. Continue with the safe choice, or hand it to someone who can decide?`
-  }
-  const how = r.url
-    ? `Open it in your browser: ${r.url}`
-    : `Make your changes in ${stop.file ?? "the files it names"}.`
-  const again = r.isRepeat ? "You haven't changed anything yet, so gtd is still waiting. " : ""
-  return `${again}gtd needs your input: ${step(stop)}. ${how} Ready to continue?`
-}
-
-export const STALE =
-  "This question is out of date: gtd has already moved on. Choose Close to dismiss it."
-
 export const RELOAD_CUT_SCRIPT =
   "a reload cut a script off mid-run — check the working tree, then Continue to run it again"
 
-export const handoffQuestion =
-  "Who should take over from here? Type their GitHub username, or let anyone on the team pick it up."
-
-export const shipQuestion = (branch: string) =>
-  `gtd has finished the work on ${branch}. Combine it into a single commit and open (or update) its pull request for review?`
-
 export function headline(s: Stop) {
   const where = step(s)
   switch (s.kind) {

package/claude/types/index.d.ts

@@ -6,6 +6,8 @@ export type Stop = {
   isJudge?: boolean
   // the steering file the rest asks a person to edit
   file?: string
+  // the steering file's mode (`qa`, `review`), which bounds what may be written at the rest
+  mode?: string
 }
 
 export type Run = {
@@ -14,6 +16,13 @@ export type Run = {
   state?: string
   label?: string
   stop?: Stop
+  // the rest a person is helped at: HEAD and state, so an answer to an older one is refused
+  rest?: string
+  // a continue the model asked for, started once its turn ends (and only if
+  // gtd still rests at `rest`); kept here so a reload does not lose a verdict
+  pending?: { rest: string; isAnswered?: boolean; verdict?: string | undefined }
+  // requests a person made while a step ran, for the next rest's assistant
+  notes?: string[]
   // `gtd ui`'s address while it serves the current rest
   url?: string
   // why `gtd ui` is not serving it (refused, crashed)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "24.1.0",
+  "version": "24.2.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {