@pmelab/gtd 17.2.0 → 18.0.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "17.2.0",
+  "version": "18.0.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

@@ -28,8 +28,9 @@ Git history; keep secrets in an environment setting (see
 Also install all three skill sources the bundled workflow names in its prompts —
 none is optional. See
 [Setup](https://github.com/pmelab/gtd/blob/main/docs/setup.md) for the list, the
-install flags, and the never-install-the-plugin caveat. Each bundled agent step
-has its own addressable `.gtdrc` `skills:` entry — see
+install flags, and the never-install-the-plugin caveat. Skills are declared per
+scope, and restricted per turn where the driver can; each bundled scope has its
+own addressable `.gtdrc` `skills:` entry — see
 [Configuration](https://github.com/pmelab/gtd/blob/main/docs/configuration.md#the-skills-key)
 to repoint one to a set your own harness has instead.
 
@@ -468,7 +469,8 @@ thread: a footnote holding a `H:`/`A:` conversation. Threads show as a
 conversation under their block, question, chunk, or hunk, and one the agent
 answered last carries a "waiting on you" badge. Tap it to reply — your reply is
 added as a new `H:` entry; while the agent has yet to answer, reopening it edits
-your last entry instead. See
+your last entry instead. Tap an already-answered question to leave a note on it;
+the agent may overturn the answer. See
 [Configuration](https://github.com/pmelab/gtd/blob/main/docs/configuration.md)
 for its `ui:` settings.
 

package/claude/hooks/drive.ts

@@ -13,6 +13,7 @@ export type Beat = {
   memory?: string
   model?: string
   system?: string
+  skills?: string[]
   validate?: string
   judge?: unknown
   changes?: { status: string; path: string }[]
@@ -33,6 +34,8 @@ export type Turn = {
   label?: string
   model?: string
   system?: string
+  skills: readonly string[]
+  scope: string
 }
 
 export type TurnEnd = { ok: true } | { ok: false; why: string }
@@ -131,6 +134,8 @@ async function agent(io: Io, b: Beat, landTurn: string | undefined): Promise<Act
           label: b.label,
           model: b.model || undefined,
           system: b.system || undefined,
+          skills: b.skills ?? [],
+          scope: memory.split("#")[0]!,
         })
   if (!t.ok) return failed(b, t.why)
   return b.validate ? validated(io, b, b.validate, memory) : {}

package/claude/hooks/persona.ts

@@ -0,0 +1,28 @@
+import type { Turn } from "./drive"
+
+const NEUTRAL = "You are a coding agent working on the task you are given."
+
+// `general-purpose` cannot carry a restriction, so every prompt turn gets a
+// registered persona. The name hashes everything the spec depends on: a
+// `.gtdrc` change or gtd upgrade mid-session must register a fresh one.
+export async function personaSpec(t: Pick<Turn, "scope" | "system" | "skills">) {
+  const key = JSON.stringify([t.scope, t.system ?? "", t.skills])
+  const digest = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(key)),
+  )
+  const name =
+    "p-" + Array.from(digest.slice(0, 6), (b) => b.toString(16).padStart(2, "0")).join("")
+  return {
+    name,
+    prompt: t.system || NEUTRAL,
+    skills: [...t.skills],
+    disallowedTools: ["Skill"],
+    permissionMode: "bypassPermissions",
+  }
+}
+
+export function resumable(entry: unknown, persona: string): string | undefined {
+  if (typeof entry !== "object" || entry === null) return undefined
+  const e = entry as { agentId?: unknown; persona?: unknown }
+  return typeof e.agentId === "string" && e.persona === persona ? e.agentId : undefined
+}

package/claude/hooks/register.tsx

@@ -3,9 +3,10 @@ import type { EngineInterface, Register } from "claude-code"
 
 import type { Run, Stop } from "../types"
 import { afterReload, drive, isTrue } from "./drive"
-import type { Beat, Io, Landing, TurnEnd } from "./drive"
+import type { Beat, Io, Landing, Turn, TurnEnd } from "./drive"
 import { enter } from "./entry"
 import { subagentModel } from "./models"
+import { personaSpec, resumable } from "./persona"
 import { JUDGE_SYSTEM, judgePrompt, toVerdicts } from "./judge"
 import type { Judgment } from "./judge"
 import { catchFrom, throwTo } from "./handoff"
@@ -25,6 +26,7 @@ import {
   pushText,
   runningLine,
   question,
+  restartLine,
   RELOAD_CUT_SCRIPT,
   SAFE,
   SHIP,
@@ -37,7 +39,10 @@ type $ = EngineInterface
 
 const run = atom({ plugin: "gtd", key: "run" } as const, { isRunning: false, beat: 0 } as Run)
 // memory scope (`<scope>#<hash7>`) -> the subagent holding that conversation
-const scopes = atom({ plugin: "gtd", key: "scopes" } as const, {} as Record<string, string>)
+const scopes = atom(
+  { plugin: "gtd", key: "scopes" } as const,
+  {} as Record<string, { agentId: string; persona: string }>,
+)
 const agents = atom({ plugin: "gtd", key: "agents" } as const, [] as string[])
 
 const TEN_MINUTES = 600_000
@@ -82,23 +87,19 @@ async function gtd($: $, args: string[], stdin?: string) {
   return r.stdout
 }
 
-// One agent type per system prompt. A registered type's prompt replaces the
-// session's system prompt, as `--system-prompt` does for the sh driver.
-async function persona($: $, system: string) {
-  const bytes = new TextEncoder().encode(system)
-  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))
-  const name =
-    "p-" + Array.from(digest.slice(0, 6), (b) => b.toString(16).padStart(2, "0")).join("")
-  if (!personas.has(name)) {
+// One agent type per scope, system prompt and skill list. A registered type's
+// prompt replaces the session's system prompt, as `--system-prompt` does for
+// the sh driver.
+async function persona($: $, t: Pick<Turn, "scope" | "system" | "skills">) {
+  const spec = await personaSpec(t)
+  if (!personas.has(spec.name)) {
     await $.agent.register({
-      name,
+      ...spec,
       description: "gtd workflow persona, spawned by the gtd driver only",
-      prompt: system,
-      permissionMode: "bypassPermissions",
     })
-    personas.add(name)
+    personas.add(spec.name)
   }
-  return `gtd:${name}`
+  return `gtd:${spec.name}`
 }
 
 async function send($: $, agentId: string, text: string) {
@@ -162,7 +163,10 @@ function io($: $): Io {
       }
     },
     turn: async (t) => {
-      const known = (await read($, scopes))[t.memory]
+      const entry = (await read($, scopes))[t.memory]
+      const name = (await personaSpec(t)).name
+      const known = resumable(entry, name)
+      if (t.resume && entry && !known) $.ui.log(restartLine(t.scope))
       if (t.resume && known) {
         const end = send($, known, t.prompt)
         await update($, run, (r) => ({ ...r, inflight: { agentId: known, memory: t.memory } }))
@@ -172,7 +176,7 @@ function io($: $): Io {
       // No live conversation for this scope (fresh scope, or this session never
       // held it): start one, as the sh driver falls back to `--session-id`.
       const spawned = await $.agent.spawn({
-        subagentType: t.system ? await persona($, t.system) : "general-purpose",
+        subagentType: await persona($, t),
         prompt: t.prompt,
         description: t.label || "gtd",
         model: subagentModel(t.model, {
@@ -185,12 +189,12 @@ function io($: $): Io {
       if (!id) return { ok: false, why: spawned.deny ?? "subagent spawn refused" }
       ours.add(id)
       await update($, agents, (list) => [...list, id].slice(-200))
-      await update($, scopes, (s) => ({ ...s, [t.memory]: id }))
+      await update($, scopes, (s) => ({ ...s, [t.memory]: { agentId: id, persona: name } }))
       await update($, run, (r) => ({ ...r, inflight: { agentId: id, memory: t.memory } }))
       return settle($, await turnEnd(id))
     },
     resume: async (memory, text) => {
-      const id = (await read($, scopes))[memory]
+      const id = (await read($, scopes))[memory]?.agentId
       const end = id ? await send($, id, text) : undefined
       return end ?? { ok: false, why: `no live subagent for ${memory}` }
     },

package/claude/hooks/wording.ts

@@ -77,6 +77,9 @@ export function runningLine(label: string, beat: number, elapsedMs: number) {
 // One line per beat, for the status line and the transcript.
 export const beatLine = (beat: number, b: Beat) => `▸ ${step(b)} · step ${beat}`
 
+export const restartLine = (scope: string) =>
+  `${scope}: skills or system changed — started a fresh subagent`
+
 // What a push to a phone says when gtd stops: the step, and where to act on it.
 export function pushText(stop: Stop, repo: string, url?: string) {
   const at = `${repo}: ${headline(stop).replace(/^\S+ /, "")}`

package/claude/types/index.d.ts

@@ -28,6 +28,10 @@ export type Run = {
 
 declare module "claude-code" {
   interface PluginState {
-    gtd: { run: Run; scopes: Record<string, string>; agents: string[] }
+    gtd: {
+      run: Run
+      scopes: Record<string, { agentId: string; persona: string }>
+      agents: string[]
+    }
   }
 }