moshcode 0.59.0 → 0.60.0

package/src/cli-schema.mjs

@@ -95,6 +95,11 @@ export const CORE_CLI_COMMANDS = [
       ["# driving one without attaching", ""],
       ["moshcode herd prompt api \"run the tests\" --wait", "hand it work, block until it lands"],
       ["moshcode herd read api --lines 40", "read its screen"],
+      ["", ""],
+      ["# what happened while you slept", ""],
+      ["moshcode herd hooks install claude", "state from the engine, not from its screen"],
+      ["moshcode herd tasks api", "every prompt, and how long each one waited on you"],
+      ["moshcode herd remote add research https://agents.do-ai.run/…/production", "a deployed agent, same verbs"],
     ],
     seeAlso: ["ps", "attach", "wait", "restore", "start"],
     note: "`start` is for the engines moshcode installs; `run` and `shell` take anything else, "
@@ -134,9 +139,12 @@ export const CORE_CLI_COMMANDS = [
       + "codex's rollout token counts, opencode's per-message cost, aider's chat history. a figure marked "
       + "`~` was worked out from published rates and is what the tokens WOULD cost on the api; unmarked "
       + "figures are the engine's own arithmetic. models with no rate show tokens and no cost — add yours "
-      + "to ~/.moshcode/pricing.json. gemini, kimi, qwen, deepseek and openagents log nothing readable, "
+      + "to ~/.moshcode/pricing.json. gemini, kimi, deepseek and openagents log nothing readable, "
       + "so they report no cost rather than zero.",
   },
+  // Everyone who has used a coding agent's own `/usage` types that word first,
+  // and tokens-and-spend is exactly what `cost` already answers.
+  { name: "usage", aliasOf: "cost", description: "alias for cost" },
   {
     name: "attach",
     group: "runtime",
@@ -165,15 +173,25 @@ export const CORE_CLI_COMMANDS = [
     name: "wait",
     group: "runtime",
     description: "block until a session is blocked, done, or idle",
-    synopsis: [["moshcode wait <name> [--state blocked,done] [--timeout 30m]", ""]],
+    synopsis: [
+      ["moshcode wait <name> [--state blocked,done] [--timeout 30m]", ""],
+      ["moshcode wait --any <a> <b> …", "the first one there wins"],
+      ["moshcode wait --all <a> <b> …", "join the whole fan-out"],
+    ],
     flags: [
       ["--state <list>", "states to wait for, comma-separated", "blocked,done"],
+      ["--any", "return as soon as one of them reaches the state", ""],
+      ["--all", "return when every one of them has", "implied by naming several"],
       ["--timeout <dur>", "give up after this long (30s, 10m, 2h)", "30m"],
       ["--json", "machine-readable", ""],
     ],
-    examples: [["moshcode wait api --state blocked --timeout 1h", "exit 0 matched · 2 timed out · 3 gone"]],
+    examples: [
+      ["moshcode wait api --state blocked --timeout 1h", "exit 0 matched · 2 timed out · 3 gone"],
+      ["moshcode wait --any api web docs", "--json names the winner"],
+    ],
     seeAlso: ["herd", "ps"],
-    note: "exit codes are the point: 0 matched, 2 timed out, 3 no such session.",
+    note: "exit codes are the point: 0 matched, 2 timed out, 3 no such session. "
+      + "--any/--all are what fan-in scripts used to spell out as a polling loop; a remote member waits the same way a local one does.",
   },
   {
     name: "restore",
@@ -963,11 +981,21 @@ export const HERD_VERBS = [
   { name: "send-keys", description: "send raw keys (Enter, Escape, C-c, literal text)",
     synopsis: [["moshcode herd send-keys <name> <keys…>", ""]] },
   { name: "wait", description: "block until a session reaches a state",
-    synopsis: [["moshcode herd wait <name> [--state blocked,done]", ""]],
+    synopsis: [
+      ["moshcode herd wait <name> [--state blocked,done]", ""],
+      ["moshcode herd wait --any <a> <b> …", "returns on the first one to get there"],
+      ["moshcode herd wait --all <a> <b> …", "returns when every one of them has"],
+    ],
     flags: [
       ["--state <list>", "states to wait for", "blocked,done"],
+      ["--any", "return on the first session to reach the state", ""],
+      ["--all", "return when every named session has", "implied by naming several"],
       ["--timeout <dur>", "give up after this long", "30m"],
       ["--json", "machine-readable", ""],
+    ],
+    examples: [
+      ["moshcode wait --any api web docs", "whichever finishes first"],
+      ["moshcode wait --all api web --state done", "join the whole fan-out"],
     ] },
   { name: "restore", description: "rebuild remembered sessions after a reboot",
     synopsis: [["moshcode herd restore [--resume] [--dry-run]", ""]],
@@ -988,6 +1016,72 @@ export const HERD_VERBS = [
   { name: "stop", description: "stop the whole runtime and everything in it",
     synopsis: [["moshcode herd stop --yes", ""]],
     flags: [["--yes, -y", "required when sessions are running", ""]] },
+
+  // PRD 0011 — the engine speaks, the herd remembers, and the roster reaches
+  // past this box.
+  { name: "hooks", description: "install the engine's own lifecycle hooks, so state comes from it and not from its screen",
+    synopsis: [["moshcode herd hooks <install|remove|status> [<engine>|all]", ""]],
+    flags: [
+      ["--dry-run", "print the change to the engine's settings file and write nothing", ""],
+      ["--json", "machine-readable", ""],
+    ],
+    examples: [
+      ["moshcode herd hooks install claude", "3 hooks: stop, notification, prompt-submit"],
+      ["moshcode herd hooks status", "per-engine, and which events are current"],
+    ],
+    note: "the file is merged, never clobbered, and remove takes out only what moshcode put in. "
+      + "a hook fired outside a herd session does nothing and exits 0, so installing one cannot break an engine you run by hand. "
+      + "screen rules stay as the fallback." },
+  { name: "doctor", description: "check the things that actually go wrong: substrate, manifest drift, stale reports, rules.json",
+    synopsis: [["moshcode herd doctor [--json]", ""]],
+    flags: [["--json", "machine-readable, for provisioning scripts", ""]],
+    note: "a broken ~/.moshcode/herd/rules.json is ignored silently everywhere else by design — this is where it gets to be loud." },
+  { name: "tasks", description: "every prompt submitted to a session, and what came of it",
+    synopsis: [["moshcode herd tasks <session> [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "task", description: "one task: its state transitions and its output",
+    synopsis: [["moshcode herd task <id> [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "log", description: "the timestamped state history of a session",
+    synopsis: [["moshcode herd log <session> [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "stats", description: "time in state, including how long things sat blocked waiting on you",
+    synopsis: [["moshcode herd stats [session] [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "remote", description: "put a deployed agent on the roster — A2A, or a bare POST endpoint",
+    synopsis: [["moshcode herd remote <list|add|remove|ping|card> [args…]", ""]],
+    flags: [
+      ["--kind <a2a|run>", "A2A JSON-RPC, or a plain POST {prompt}", "run"],
+      ["--json", "machine-readable", ""],
+    ],
+    examples: [
+      ["moshcode herd remote add research https://agents.do-ai.run/…/production --kind run", ""],
+      ["moshcode herd prompt research \"summarise the week\"", "the same verb as a local session"],
+    ],
+    note: "auth comes from MOSHCODE_REMOTE_<NAME>_TOKEN in the environment — never written to the manifest, never synced. "
+      + "a remote's state is the remote's claim, and `ps` says `remote` in the from column so nobody mistakes it for something this box verified." },
+  { name: "serve", description: "expose the herd over A2A v0.3.0, behind your moshcode login",
+    synopsis: [["moshcode herd serve [--port 7683] [--bind 127.0.0.1]", ""]],
+    flags: [
+      ["--port <n>", "port to listen on", "7683"],
+      ["--bind <addr>", "interface to bind", "127.0.0.1"],
+      ["--expose-autonomous", "also serve sessions started with --agent", "off"],
+    ],
+    note: "message/send is keystrokes into a real pty. there is no unauthenticated mode, loopback included, and sessions "
+      + "started with --agent are withheld unless you ask for them: an engine with approvals bypassed plus a network prompt "
+      + "is the worst pairing on the menu." },
+  { name: "eval", description: "run a dataset through several engines and score them",
+    synopsis: [["moshcode herd eval --dataset <file> --engines a,b [--judge <engine>|rules]", ""]],
+    flags: [
+      ["--dataset <file>", "jsonl, json or csv of { prompt, expect | rubric }", ""],
+      ["--engines <list>", "engines to compare", ""],
+      ["--judge <engine>|rules", "score with an engine, or with the dataset's own patterns", "rules"],
+      ["--threshold <0-1>", "the score every engine has to reach", "0.8"],
+      ["--keep", "leave the eval sessions running afterwards", ""],
+      ["--json", "machine-readable", ""],
+    ],
+    note: "exit codes are distinct on purpose: 0 pass, 4 below the threshold, 5 the harness could not run — "
+      + "CI has to tell a worse agent from a broken box." },
 ];
 
 export const VERB_TABLES = {
@@ -1027,7 +1121,7 @@ export const PIT_COMMANDS = [
     description: "sessions that keep running when you leave" },
   { name: "ps", cli: "ps",
     description: "what the herd is running, and which one wants you" },
-  { name: "cost", args: "[name] [--all]", cli: "cost",
+  { name: "cost", aliases: ["usage"], args: "[name] [--all]", cli: "cost",
     description: "what the herd is spending, from the engines' own logs" },
   { name: "attach", args: "<name>", cli: "attach",
     description: "step into a herd session (detach leaves it running)" },

package/src/commands.mjs

@@ -18,8 +18,9 @@ import { spawn, spawnSync } from "node:child_process";
 import { createRegistry } from "./registry.mjs";
 import { cliVerb, aiVerb, runMoshcode } from "./cli.mjs";
 import { ingestApproval, pollApproval } from "./notify.mjs";
-import { capture, killSession, sendPrompt } from "./herd.mjs";
-import { herdStart, roster, waitFor } from "./herd-cli.mjs";
+import { capture, killSession, remoteStatus, sendPrompt } from "./herd.mjs";
+import { herdStart, isRemoteMember, roster, waitForMany, waitMember } from "./herd-cli.mjs";
+import { endTask, findTask, readTasks, startTask } from "./herd-tasks.mjs";
 import { shellInvocation } from "./shell.mjs";
 import { identity, loginAuto, logout as forgetCreds } from "./auth.mjs";
 import { expandAlias, getAlias, loadAliases, removeAlias, setAlias } from "./aliases.mjs";
@@ -511,29 +512,62 @@ const COMMANDS = [
   },
   {
     name: "herdPrompt",
-    summary: "type a prompt into a herd session",
+    summary: "type a prompt into a herd session (local or remote)",
     usage: "herdPrompt(name, text)",
-    detail: "returns { ok }; does not wait — use herdWait() to join",
+    detail: "returns { ok, task }; does not wait — use herdWait() to join",
     run(ctx, name, ...words) {
       const text = words.join(" ");
       if (!name || !text) throw new Error("moshscript: herdPrompt(name, text) requires both");
       if (ctx.dryRun) { ctx.out(`  💬 herdPrompt(${name}) → would send: ${text}`); return { ok: true, dryRun: true }; }
       ctx.out(`  💬 herdPrompt(${name}) → ${text.slice(0, 60)}${text.length > 60 ? "…" : ""}`);
-      const sent = sendPrompt(String(name), text);
-      return { ok: Boolean(sent.ok) };
+      const session = String(name);
+
+      // A remote member takes the same call with the same arguments — the point
+      // of PRD 0011 R12 is that a script fanning across a local pty and a
+      // deployed agent contains no `if (remote)`. This one stays synchronous
+      // like every other local verb, so the no-`await` style keeps working: the
+      // request is in flight when it returns, and herdWait() is how a script
+      // joins on it, exactly as for a local session.
+      if (isRemoteMember(session)) {
+        const task = startTask(session, text, { screen: "" });
+        import("./herd-remote.mjs")
+          .then((remote) => remote.promptRemote(session, text)
+            .then((sent) => endTask(session, task, { state: sent.state || "done", artifact: sent.artifact || String(sent.error?.message || "") })))
+          .catch(() => endTask(session, task, { state: "done", artifact: "the request never left this machine" }));
+        return { ok: true, task, remote: true };
+      }
+
+      const task = startTask(session, text, { screen: capture(session, { lines: 60 }) });
+      const sent = sendPrompt(session, text);
+      if (!sent.ok) endTask(session, task, { state: "done", artifact: String(sent.error?.message || sent.error) });
+      return { ok: Boolean(sent.ok), task };
     },
   },
   {
     name: "herdWait",
     summary: "BLOCK until a herd session is blocked, done, or idle",
-    usage: "herdWait(name, { states, timeout })",
-    detail: "returns the state it reached. needs await",
+    usage: "herdWait(name | [names], { states, timeout, any })",
+    detail: "one name returns the state it reached; a list returns the winner's name (any) or every result (all). needs await",
     async run(ctx, name, opts = {}) {
       if (!name) throw new Error("moshscript: herdWait(name) requires a session name");
       const states = opts.states || ["blocked", "done", "idle"];
+      const timeout = opts.timeout ? { timeoutMs: Number(opts.timeout) } : {};
+
+      // A list of names is a join (PRD 0011 R8) — the thing every fan-out
+      // script so far has spelled out by hand as a polling loop.
+      if (Array.isArray(name)) {
+        const names = name.map(String);
+        const mode = opts.any ? "any" : "all";
+        if (ctx.dryRun) { ctx.out(`  ⏳ herdWait([${names.join(", ")}]) → would wait for ${mode} of them to reach ${states.join("/")}`); return mode === "any" ? names[0] : names.map((n) => ({ name: n, state: "idle" })); }
+        ctx.out(`  ⏳ herdWait([${names.join(", ")}]) → waiting for ${mode}…`);
+        const result = await waitForMany(names, states, { mode, ...timeout });
+        ctx.out(`     ${result.outcome === "matched" ? "✅" : "⌛"} ${mode === "any" ? `${result.winner} first` : `${result.outcome}`}`);
+        return mode === "any" ? result.winner : result.results;
+      }
+
       if (ctx.dryRun) { ctx.out(`  ⏳ herdWait(${name}) → would wait for ${states.join("/")}`); return "idle"; }
       ctx.out(`  ⏳ herdWait(${name}) → waiting for ${states.join("/")}…`);
-      const result = await waitFor(String(name), states, opts.timeout ? { timeoutMs: Number(opts.timeout) } : {});
+      const result = await waitMember(String(name), states, timeout);
       ctx.out(`     ${result.outcome === "matched" ? "✅" : "⌛"} ${name} is ${result.state}`);
       return result.state;
     },
@@ -546,7 +580,11 @@ const COMMANDS = [
     run(ctx, name, opts = {}) {
       if (!name) throw new Error("moshscript: herdRead(name) requires a session name");
       if (ctx.dryRun) { ctx.out(`  📖 herdRead(${name}) → would read its screen`); return ""; }
-      return capture(String(name), { lines: Number(opts.lines) || 60 });
+      const session = String(name);
+      // A remote has no screen; what it has is the last thing it said, and
+      // that is what `read` means for it (PRD 0011 R12).
+      if (isRemoteMember(session)) return String(remoteStatus(session)?.artifact || "");
+      return capture(session, { lines: Number(opts.lines) || 60 });
     },
   },
   {
@@ -572,6 +610,41 @@ const COMMANDS = [
     },
   },
 
+  // The ledger (PRD 0011 R6). Same contract as herdRead/herdList and for the
+  // same reason: a script fans work out and then has to read what came back.
+  // `[]`/`null` on anything missing, never a throw — a script joining on four
+  // agents must not die because one of them has no history yet.
+  //
+  //   herdPrompt("api", "port the auth routes");
+  //   await herdWait("api");
+  //   const [last] = herdTasks("api").slice(-1);
+  //   say(herdTask(last.id).artifact);
+  {
+    name: "herdTasks",
+    summary: "every prompt submitted to a session, and what came of it",
+    usage: "herdTasks(name)",
+    detail: "returns [{ id, text, state, status, submitted, durationMs }, …], oldest first",
+    run(ctx, name) {
+      if (!name) throw new Error("moshscript: herdTasks(name) requires a session name");
+      if (ctx.dryRun) { ctx.out(`  📒 herdTasks(${name}) → would read the ledger`); return []; }
+      try {
+        return readTasks(String(name)).map(({ id, text, state, status, submitted, endedAt, durationMs }) =>
+          ({ id, text, state, status, submitted, endedAt, durationMs }));
+      } catch { return []; }
+    },
+  },
+  {
+    name: "herdTask",
+    summary: "one task by id — its transitions and its output",
+    usage: "herdTask(id)",
+    detail: "returns { id, session, text, transitions, artifact, state } or null",
+    run(ctx, id) {
+      if (!id) throw new Error("moshscript: herdTask(id) requires a task id");
+      if (ctx.dryRun) { ctx.out(`  📒 herdTask(${id}) → would read the ledger`); return null; }
+      try { return findTask(String(id)); } catch { return null; }
+    },
+  },
+
   // CLI verbs — each is `moshcode <name> ...args`. This is the whole point:
   // scripting the CLI. Add a capability by adding a line here.
   //
@@ -601,6 +674,7 @@ const COMMANDS = [
   cliVerb("supabase", "drive the Supabase CLI (local stack, migrations, functions)"),
   cliVerb("doppler", "drive the Doppler CLI (secrets, env injection)"),
   cliVerb("doctl", "drive the DigitalOcean CLI (droplets, apps, databases)"),
+  cliVerb("gradient", "drive the DigitalOcean Gradient ADK (init, run, deploy, logs, evaluate)"),
   cliVerb("turso", "drive the Turso CLI (auth, databases, replicas)"),
   cliVerb("tailscale", "drive the Tailscale CLI (mesh VPN: up, status, ssh, serve)"),
   cliVerb("coral", "drive the Coral CLI (SQL over APIs, databases, and internal systems)"),

package/src/cost.mjs

@@ -2,7 +2,8 @@
 //
 // Every engine moshcode wraps already writes down what it used — Claude Code
 // keeps a per-message `usage` block in ~/.claude/projects/**/<session>.jsonl,
-// Codex emits cumulative `token_count` events into ~/.codex/sessions/…, and
+// Codex emits cumulative `token_count` events into ~/.codex/sessions/…, qwen
+// appends a record per request to ~/.qwen/usage/token-usage-YYYY-MM.jsonl, and
 // opencode stores a per-message `cost` it computed itself in SQLite. Nobody has
 // to be instrumented and nothing has to be proxied: the numbers are on disk
 // because the CLI put them there. This module reads them, normalises them into
@@ -408,6 +409,123 @@ async function opencodeRuns(engine, { since, cwd } = {}) {
   return [...bySession.values()];
 }
 
+// ---------------------------------------------------------------------------
+// qwen — ~/.qwen/usage/token-usage-YYYY-MM.jsonl, one record per request
+// ---------------------------------------------------------------------------
+
+const qwenUsageDir = () => path.join(home(), ".qwen", "usage");
+const qwenProjectsDir = () => path.join(home(), ".qwen", "projects");
+
+/** Only the monthly usage logs; the directory also holds unrelated state. */
+const QWEN_USAGE_FILE = /^token-usage-\d{4}-\d{2}\.jsonl$/;
+
+/**
+ * sessionId → the directory qwen was started in.
+ *
+ * The usage log records no path, so on its own it can say what was spent but
+ * not where. qwen writes a tiny `<sessionId>.runtime.json` beside each chat
+ * with the `work_dir` in it, and that is the only exact answer on disk — the
+ * project directory those chats sit in is a lossy dash-slug of the same path,
+ * so it can group sessions but cannot be turned back into a directory.
+ */
+function qwenSessionDirs() {
+  const dirs = new Map();
+  const root = qwenProjectsDir();
+  for (const project of listDir(root)) {
+    if (!project.isDirectory()) continue;
+    const chats = path.join(root, project.name, "chats");
+    for (const entry of listDir(chats)) {
+      if (!entry.isFile() || !entry.name.endsWith(".runtime.json")) continue;
+      let meta;
+      try { meta = parseJson(fs.readFileSync(path.join(chats, entry.name), "utf8")); }
+      catch { continue; }
+      if (meta?.session_id && meta.work_dir) dirs.set(String(meta.session_id), String(meta.work_dir));
+    }
+  }
+  return dirs;
+}
+
+/**
+ * One usage record → the shape every engine normalises into.
+ *
+ * `inputTokens` is the whole prompt and `cachedTokens` is the part of it that
+ * was a cache hit, so the fresh input is the difference — counting both would
+ * bill the cache twice at the full input rate.
+ *
+ * `thoughtsTokens` is the subtle one. On the OpenAI-compatible path — which is
+ * what `authType: "openai"` marks, and what qwen's own DashScope endpoint uses
+ * — `outputTokens` is `completion_tokens`, which already *contains* the
+ * reasoning tokens, and adding them would double-count the thinking. The native
+ * path reports Gemini's `candidatesTokenCount`, which excludes them, so that is
+ * the only case where they have to be added back.
+ */
+function qwenUsageOf(record) {
+  const cached = num(record.cachedTokens);
+  const thoughts = num(record.thoughtsTokens);
+  return {
+    input: Math.max(0, num(record.inputTokens) - cached),
+    output: num(record.outputTokens) + (record.authType === "openai" ? 0 : thoughts),
+    cacheRead: cached,
+    cacheWrite5m: 0,
+    cacheWrite1h: 0,
+  };
+}
+
+/**
+ * Every qwen session in the window, one run per session.
+ *
+ * The log is per-request and flat, so the session id is what makes a run: a
+ * subagent's requests carry the same one (`source` names the subagent) and
+ * belong to the session that spawned them.
+ */
+export function qwenRuns({ since, cwd } = {}) {
+  const dirs = qwenSessionDirs();
+  const sessions = new Map();
+
+  for (const entry of listDir(qwenUsageDir())) {
+    if (!entry.isFile() || !QWEN_USAGE_FILE.test(entry.name)) continue;
+    const file = path.join(qwenUsageDir(), entry.name);
+    const stat = safeStat(file);
+    // A month untouched since before the window holds nothing inside it.
+    if (!stat || (since != null && stat.mtimeMs < since)) continue;
+
+    let text;
+    try { text = fs.readFileSync(file, "utf8"); } catch { continue; }
+    for (const line of text.split("\n")) {
+      if (!line || line.charCodeAt(0) !== 123) continue; // fast reject: not "{"
+      const record = parseJson(line);
+      if (!record?.sessionId) continue;
+      const at = stamp(record.timestamp);
+      if (at != null && since != null && at < since) continue;
+
+      const id = String(record.sessionId);
+      const where = dirs.get(id) || "";
+      // A session whose directory is unknown cannot be claimed for the one that
+      // was asked for — reporting it there would invent an attribution.
+      if (cwd && !samePath(where, cwd)) continue;
+
+      let run = sessions.get(id);
+      if (!run) {
+        run = {
+          engine: "qwen", id, cwd: where,
+          usage: { ...EMPTY_USAGE }, byModel: new Map(),
+          start: null, end: null, engineCost: null,
+        };
+        sessions.set(id, run);
+      }
+      const one = qwenUsageOf(record);
+      const model = record.model || "unknown";
+      run.usage = addUsage(run.usage, one);
+      run.byModel.set(model, addUsage(run.byModel.get(model) || EMPTY_USAGE, one));
+      if (at != null) {
+        run.start = run.start == null ? at : Math.min(run.start, at);
+        run.end = run.end == null ? at : Math.max(run.end, at);
+      }
+    }
+  }
+  return [...sessions.values()];
+}
+
 // ---------------------------------------------------------------------------
 // aider — it prints the running total into its own chat history
 // ---------------------------------------------------------------------------
@@ -486,11 +604,12 @@ export const COST_READERS = {
   codex: (opts) => codexRuns(opts),
   opencode: (opts) => opencodeRuns("opencode", opts),
   privacycode: (opts) => opencodeRuns("privacycode", opts),
+  qwen: (opts) => qwenRuns(opts),
   aider: (opts) => aiderRuns(opts),
 };
 
 /** Engines moshcode can launch but cannot cost — named so the report can say so. */
-export const UNCOSTED_ENGINES = ["gemini", "kimi", "qwen", "deepseek", "openagents"];
+export const UNCOSTED_ENGINES = ["gemini", "kimi", "deepseek", "openagents"];
 
 /**
  * Finish a run: price it, and record where the price came from.

package/src/engines.mjs

@@ -19,6 +19,14 @@
 // repeating; only put a pattern here when it is this engine's own wording.
 // Every pattern is matched against the bottom of the screen with ANSI stripped.
 //
+// `hooks` (optional) is how this engine reports its own state, so the herd can
+// stop reading paint (PRD 0011 R1). It sits here for the same reason `state`
+// does — and because the two are the same fact at different confidence: a hook
+// spec supersedes the screen rules below it, so an engine that gains one should
+// keep its rules rather than delete them. A missing `hooks` is not a gap to
+// paper over with a guess; it means this engine is classified from its screen,
+// which is what every engine did before.
+//
 // `resume` (optional) is the argv that reopens this engine's last conversation,
 // used by `moshcode restore --resume` after a reboot. Omit it rather than guess:
 // a session that starts fresh is a small disappointment, and one that starts
@@ -82,6 +90,30 @@ export const ENGINES = {
       "CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT", "CLAUDE_CODE_SESSION_ID", "CLAUDE_CODE_CHILD_SESSION",
     ],
     resume: ["--continue"],
+    // The engine speaking for itself (PRD 0011 R1). Claude Code's lifecycle
+    // hooks are documented and stable, which is why it is the one engine that
+    // ships a spec here rather than a promise to write one: a hook schema we
+    // guessed at would be a rule that rots with no screen to fall back to.
+    //
+    // `file` is a function, not a path, because the whole install is a write to
+    // the user's home and the only honest way to test that is to move HOME.
+    hooks: {
+      format: "claude-settings",
+      file: () => path.join(homedir(), ".claude", "settings.json"),
+      // Stop fires when the turn ends, which is the end of the *task* — A2A
+      // calls the same moment `completed`. Notification covers both halves of
+      // blocked (a permission request and a plain question). UserPromptSubmit
+      // is the cheapest honest `working`: PreToolUse would also do it, at the
+      // cost of forking a moshcode per tool call for a state it is already in.
+      // `label` is what moshcode calls the event; `event` is what the engine
+      // calls it. They differ because one is a sentence and the other is a
+      // schema key, and printing the schema key at someone is not an answer.
+      events: [
+        { event: "Stop", state: "done", label: "stop" },
+        { event: "Notification", state: "blocked", label: "notification" },
+        { event: "UserPromptSubmit", state: "working", label: "prompt-submit" },
+      ],
+    },
     state: {
       // The permission dialog's own heading, and the selector on its first
       // option — the generic numbered-menu pattern would catch the second only