@brainervirus/workit-core 8.7.0 → 8.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.7.0",
+  "version": "8.8.0",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/src/forge/report.ts

@@ -2,6 +2,7 @@
 // forge-neutral status document, the `next` priority, the CI-wait verdict,
 // and rerun planning with the rerun-once rule.
 import { aheadBehind, currentBranch, fetchRefs, hasCommit, headSha, resolveRef } from "../git/rev";
+import { appendObserved, readLedger, type LedgerActor } from "../ledger";
 import type { ResolvedForge } from "./resolve";
 import { rerunCounts, recordReruns, withRerunLock, type RerunRow } from "./reruns";
 import {
@@ -425,11 +426,59 @@ export function buildStatusDoc(
   });
 }
 
-/** Select, read and document one PR/MR. */
+/**
+ * Record what the forge said about a PR as a CLI-observed `pr.status` row
+ * (pr, branch, head, state: open|merged|closed, checks), only when it
+ * differs from the newest row for that PR, so polling never floods the
+ * ledger. Hooks read it without calling the forge: an open PR's checks
+ * (passing|failing|pending; one without gating checks is not recorded), and
+ * a PR merged or closed outside workit (the forge UI). Never fails the verb:
+ * a ledger error only loses the row.
+ */
+export function recordPrStatus(cwd: string, doc: PrStatusDoc, actor: LedgerActor): void {
+  const checks = doc.checks.state;
+  const state = doc.state;
+  if (state !== "open" && state !== "merged" && state !== "closed") return;
+  if (state === "open" && checks !== "passing" && checks !== "failing" && checks !== "pending")
+    return;
+  try {
+    const ledger = readLedger(cwd);
+    if (!ledger.ok) return;
+    const last = ledger.value.rows.findLast(
+      (row) =>
+        row.type === "pr.status" &&
+        row.observer === "workit_cli" &&
+        row.pr === doc.number &&
+        row.repo === doc.repo,
+    );
+    if (
+      last &&
+      last.head === doc.head.sha &&
+      last.checks === checks &&
+      (last.state ?? "open") === state
+    )
+      return;
+    appendObserved(cwd, {
+      type: "pr.status",
+      actor,
+      branch: doc.head.branch,
+      head: doc.head.sha,
+      pr: doc.number,
+      repo: doc.repo,
+      forge: doc.forge,
+      state,
+      checks,
+    });
+  } catch {
+    // The row is an observation for hooks; the verb's answer stands without it.
+  }
+}
+
+/** Select, read and document one PR/MR (recorded as a `pr.status` row when `actor` is given). */
 export function prStatusReport(
   cwd: string,
   resolved: ResolvedForge,
-  options: ReportOptions & { identity?: PrStatusDoc["identity"] } = {},
+  options: ReportOptions & { identity?: PrStatusDoc["identity"]; actor?: LedgerActor } = {},
 ): ForgeResult<{ doc: PrStatusDoc; raw: ForgePrStatus }> {
   const number = selectPr(cwd, resolved, options);
   if (!number.ok) return number;
@@ -441,6 +490,7 @@ export function prStatusReport(
     identity: options.identity,
   });
   if (!doc.ok) return doc;
+  if (options.actor) recordPrStatus(cwd, doc.data, options.actor);
   return success({ doc: doc.data, raw: status.data });
 }
 

package/src/hooks/handle.ts

@@ -22,6 +22,7 @@ import {
   skillReadIn,
   withContextLine,
 } from "./skill-nudge";
+import { stopDecision } from "./stop";
 import { shellWrites, writeGate } from "./write-gate";
 import type { HookDecision, HookEventKind, HookInput, HostAdapter, RenderedHook } from "./protocol";
 
@@ -67,21 +68,35 @@ const subagentSession = (session: string | null, agentId: string): string =>
     .replace(/[^A-Za-z0-9_.:@/+-]/g, "-")
     .slice(0, 128);
 
+/** A Claude Code worktree path: `<repo>/.claude/worktrees/<name>`. */
+const CLAUDE_WORKTREE = /[\\/]\.claude[\\/]worktrees[\\/]/;
+
+/**
+ * Claude Code's worktree isolation refuses any command that wraps git
+ * (`workit git …` included) and cannot be turned off, so an isolated agent
+ * runs git itself and workit for everything else.
+ */
+const ISOLATED_GIT =
+  'Run git as plain, separate commands inside your worktree (`git switch -c <branch> <base>`, `git commit --trailer "Workit-Session=<your session>"`, `git push`; `workit doctor --fix` can install a commit-msg hook that adds the trailer), never `workit git …`: Claude Code\'s worktree isolation refuses a command that wraps git and cannot be turned off (https://code.claude.com/docs/en/worktrees#how-claude-code-enforces-isolation). Never dodge that check by renaming or re-wrapping git. Use workit for the non-git verbs (`workit check`, `workit ledger`, `workit pr`).';
+
 const subagentStartText = (
-  session: string | null,
+  input: HookInput,
   descriptor: HostDescriptor,
   event: Extract<HookInput["event"], { kind: "subagent.start" }>,
 ): string => {
+  const session = input.session.id ?? null;
   const role = workitRole(descriptor, event.agentType);
   const who = `${descriptor.label} subagent ${event.agentId} (${event.agentType})`;
-  if (role === "implementer") {
-    // Only a host that isolates subagents in worktrees has already put it in one.
-    const where =
-      descriptor.subagents.worktreeIsolation === "native"
-        ? "working in its own git worktree: it may edit and commit there"
-        : "as an implementer: it edits and commits only in its own git worktree (the lead makes one with `workit fanout worktree create <slice>`), never in the lead's checkout";
-    return `Workit observed ${who} ${where}, within its brief's scope. Before the first commit, switch to a policy-compliant branch with \`workit git branch <branch> --base <base>\` (e.g. feature/<slug>); branch policy hooks still deny protected or non-compliant branches. Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
-  }
+  const isolated =
+    descriptor.subagents.worktreeIsolation === "native" &&
+    (role === "implementer" || CLAUDE_WORKTREE.test(input.cwd));
+  if (role === "implementer" && isolated)
+    return `Workit observed ${who} working in its own git worktree: it may edit and commit there, within its brief's scope. ${ISOLATED_GIT} Use a policy-compliant branch (e.g. feature/<slug>); branch policy hooks still deny protected or non-compliant branches. Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
+  if (isolated)
+    return `${ISOLATED_GIT}\n${subagentStartText({ ...input, cwd: "" }, descriptor, event)}`;
+  if (role === "implementer")
+    // No host isolation: the lead makes the worktree, and workit git works there.
+    return `Workit observed ${who} as an implementer: it edits and commits only in its own git worktree (the lead makes one with \`workit fanout worktree create <slice>\`), never in the lead's checkout, within its brief's scope. Before the first commit, switch to a policy-compliant branch with \`workit git branch <branch> --base <base>\` (e.g. feature/<slug>); branch policy hooks still deny protected or non-compliant branches. Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
   const readOnly = `Workit observed ${who} as read-only/agent-guided.`;
   if (role !== "judge" || !event.agentId) return readOnly;
   const own = subagentSession(session, event.agentId);
@@ -125,7 +140,7 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
       // Without a post-tool event, the previous raw commit is recorded now.
       const postTool = usable(descriptor.events["shell.post"].support);
       if (!postTool) settlePendingCommit(input);
-      const raw = canDeny ? rawGitPre(input, event.command) : NONE;
+      const raw = canDeny ? rawGitPre(input, event.command, { nudge: false }) : NONE;
       if (raw.kind === "deny") return raw;
       const writes = usable(descriptor.events["write.pre"].support)
         ? shellWrites(event.command)
@@ -139,7 +154,13 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
         event.command,
         postTool ? callKey(event.toolUseId, event.command) : NEXT_COMMAND,
       );
-      return withContextLine(raw, shipNudge(input, event.command));
+      // An in-process plugin shows nudges on the tool result (shellNudge):
+      // spending the once-per-session nudge here would lose it.
+      if (descriptor.transport !== "hook-process") return NONE;
+      return withContextLine(
+        canDeny ? rawGitPre(input, event.command) : NONE,
+        shipNudge(input, event.command),
+      );
     }
     case "shell.post":
       if (usable(descriptor.events["shell.post"].support))
@@ -152,7 +173,7 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
     case "subagent.start":
       return {
         kind: "context",
-        text: subagentStartText(input.session.id ?? null, descriptor, event),
+        text: subagentStartText(input, descriptor, event),
       };
     case "compact.pre":
       return {
@@ -164,11 +185,12 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
       // Host permission policy owns other tools; a skill load is recorded.
       if (event.skill) recordSkillLoad(input, event.skill, "tool");
       return NONE;
-    // Attestation, prompt and stop control arrive with the CLI-observed
-    // evidence model.
+    case "stop":
+      return usable(descriptor.events.stop.support) ? stopDecision(input, descriptor) : NONE;
+    // A subagent's stop is never blocked; attestation and prompt control
+    // arrive with the CLI-observed evidence model.
     case "subagent.stop":
     case "prompt.submit":
-    case "stop":
       return NONE;
   }
 }

package/src/hooks/hosts/claude-code.ts

@@ -44,13 +44,15 @@ export const CLAUDE_CODE_DESCRIPTOR: HostDescriptor = {
     // SubagentStart output is additionalContext only: it cannot block or bind.
     "subagent.start": { support: "native", native: "SubagentStart" },
     "prompt.submit": { support: "native", native: "UserPromptSubmit" },
-    // Claude Code has SubagentStop, PreCompact and Stop, but the plugin
-    // registers none of them: events list what workit registers
-    // (docs/agents/hosts.md, Host parity). Compaction restore runs on
+    // Claude Code has SubagentStop and PreCompact, but the plugin registers
+    // neither: events list what workit registers (docs/agents/hosts.md, Host
+    // parity). A subagent's stop is never blocked; compaction restore runs on
     // SessionStart source=compact.
     "subagent.stop": { support: "none", native: null },
     "compact.pre": { support: "none", native: null },
-    stop: { support: "none", native: null },
+    // `{"decision":"block","reason"}` continues the turn; the input carries
+    // `stop_hook_active` and `last_assistant_message` (claude 2.1.295).
+    stop: { support: "native", native: "Stop" },
   },
   shellPolicy: { deny: "native", channel: "permissionDecision", failClosed: false },
   context: {

package/src/hooks/hosts/codex.ts

@@ -18,7 +18,8 @@ export type CodexHookEvent =
   | "PreToolUse"
   | "PostToolUse"
   | "SubagentStart"
-  | "SubagentStop";
+  | "SubagentStop"
+  | "Stop";
 // The session-start.command.input schema in codex-cli 0.160.1 lists fork as a source.
 type SessionSource = "startup" | "resume" | "clear" | "compact" | "fork";
 
@@ -80,10 +81,12 @@ export const CODEX_DESCRIPTOR: HostDescriptor = {
     "subagent.start": { support: "native", native: "SubagentStart" },
     "subagent.stop": { support: "native", native: "SubagentStop" },
     "prompt.submit": { support: "native", native: "UserPromptSubmit" },
-    // Codex has PreCompact and Stop, but workit registers neither yet: events
-    // list what workit registers (docs/agents/hosts.md, Host parity).
+    // Codex has PreCompact, but workit does not register it: events list what
+    // workit registers (docs/agents/hosts.md, Host parity).
     "compact.pre": { support: "none", native: null },
-    stop: { support: "none", native: null },
+    // stop.command.input (codex-cli 0.160.1): stop_hook_active,
+    // last_assistant_message, turn_id; output `{"decision":"block","reason"}`.
+    stop: { support: "native", native: "Stop" },
   },
   shellPolicy: { deny: "native", channel: "permissionDecision", failClosed: false },
   context: {
@@ -104,7 +107,7 @@ export const CODEX_DESCRIPTOR: HostDescriptor = {
   },
   provenance: { sessionId: "native", agentIdOnTool: "partial", postToolObserve: "native" },
   interaction: { questions: "none", writeBoundary: "partial" },
-  stopControl: "undocumented",
+  stopControl: "native",
   shellAvailable: "native",
   perEventCost: "low",
   capabilities: [
@@ -178,6 +181,7 @@ const EVENTS: Record<CodexHookEvent, HookEventKind> = {
   PostToolUse: "shell.post",
   SubagentStart: "subagent.start",
   SubagentStop: "subagent.stop",
+  Stop: "stop",
 };
 const SHELL_TOOLS = new Set(["bash", "unified-exec"]);
 const isShellTool = (name: unknown) => SHELL_TOOLS.has(String(name).toLowerCase());
@@ -227,6 +231,12 @@ export const parseCodexHookInput = (value: unknown): CodexParseResult => {
       ...(nonEmpty(value.tool_use_id) ? { tool_use_id: value.tool_use_id } : {}),
       ...(nonEmpty(value.agent_id) ? { agent_id: value.agent_id } : {}),
       ...(nonEmpty(value.agent_type) ? { agent_type: value.agent_type } : {}),
+      ...(event === "Stop"
+        ? {
+            last_assistant_message: optionalText(value.last_assistant_message),
+            stop_hook_active: value.stop_hook_active === true,
+          }
+        : {}),
       ...(event === "SubagentStop"
         ? {
             agent_transcript_path: optionalText(value.agent_transcript_path),
@@ -287,6 +297,12 @@ const protocolEvent = (input: CodexHookInput): HookEvent => {
         lastMessage: input.last_assistant_message ?? null,
         stopHookActive: input.stop_hook_active ?? false,
       };
+    case "Stop":
+      return {
+        kind: "stop",
+        lastMessage: input.last_assistant_message ?? null,
+        stopHookActive: input.stop_hook_active ?? false,
+      };
   }
 };
 
@@ -295,7 +311,11 @@ const output = (event: string, extra: Record<string, unknown> = {}) => ({
 });
 
 const render = (decision: HookDecision, native: string | null) => {
-  if (native === "SubagentStop" || native === null) return { json: {}, exitCode: 0 };
+  // stop.command.output takes no hookSpecificOutput: a block with a reason continues.
+  if (native === "Stop" && decision.kind === "continue")
+    return { json: { decision: "block", reason: decision.reason }, exitCode: 0 };
+  if (native === "SubagentStop" || native === "Stop" || native === null)
+    return { json: {}, exitCode: 0 };
   if (decision.kind === "deny")
     return {
       json: output(native, {

package/src/hooks/hosts/cursor.ts

@@ -1,4 +1,5 @@
 // Cursor: command hooks (hooks/hooks-cursor.json) mapped onto the protocol.
+import fs from "node:fs";
 import path from "node:path";
 import type { HostDescriptor } from "../descriptor";
 import type { HookDecision, HookEvent, HookEventKind, HostAdapter } from "../protocol";
@@ -10,7 +11,8 @@ export type CursorHookEvent =
   | "beforeShellExecution"
   | "subagentStart"
   | "subagentStop"
-  | "preCompact";
+  | "preCompact"
+  | "stop";
 
 export type CursorHookInput = {
   hook_event_name: CursorHookEvent;
@@ -26,6 +28,8 @@ export type CursorHookInput = {
   parent_conversation_id?: string;
   task?: string;
   status?: "completed" | "error" | "aborted";
+  loop_count?: number;
+  transcript_path?: string;
 };
 
 export type CursorParseResult = { ok: true; data: CursorHookInput } | { ok: false; error: string };
@@ -53,8 +57,11 @@ export const CURSOR_DESCRIPTOR: HostDescriptor = {
     "prompt.submit": undocumented,
     // preCompact can only show a user message.
     "compact.pre": { support: "partial", native: "preCompact" },
-    // Cursor has a stop hook (followup_message), but workit registers none yet.
-    stop: none,
+    // stop (cursor-agent 2026.09.26): `{"followup_message"}` queues one more
+    // user turn; the input carries loop_count and transcript_path, not the
+    // last message (read from transcript_path). Registered with
+    // `loop_limit: 1`, so the continuation's own stop never runs the hook.
+    stop: { support: "native", native: "stop" },
   },
   shellPolicy: { deny: "native", channel: "exit2+json", failClosed: true },
   context: {
@@ -78,7 +85,7 @@ export const CURSOR_DESCRIPTOR: HostDescriptor = {
     postToolObserve: "undocumented",
   },
   interaction: { questions: "none", writeBoundary: "partial" },
-  stopControl: "undocumented",
+  stopControl: "native",
   shellAvailable: "native",
   // Hooks run the plugin's launcher against a local runtime (bundled dist or a
   // global bin); only an install with neither falls back to a pinned,
@@ -155,6 +162,7 @@ const EVENTS: Record<CursorHookEvent, HookEventKind> = {
   subagentStart: "subagent.start",
   subagentStop: "subagent.stop",
   preCompact: "compact.pre",
+  stop: "stop",
 };
 
 /** Validate the keys each Cursor event needs; unknown keys are ignored. */
@@ -205,6 +213,15 @@ export const parseCursorHookInput = (value: unknown): CursorParseResult => {
         ? { parent_conversation_id: value.parent_conversation_id }
         : {}),
       ...(event === "subagentStart" && nonEmpty(value.task) ? { task: value.task } : {}),
+      ...(event === "stop"
+        ? {
+            ...(nonEmpty(value.status)
+              ? { status: value.status as CursorHookInput["status"] }
+              : {}),
+            ...(typeof value.loop_count === "number" ? { loop_count: value.loop_count } : {}),
+            ...(nonEmpty(value.transcript_path) ? { transcript_path: value.transcript_path } : {}),
+          }
+        : {}),
     },
   };
 };
@@ -244,6 +261,61 @@ const protocolEvent = (input: CursorHookInput): HookEvent => {
       };
     case "preCompact":
       return { kind: "compact.pre", trigger: "auto" };
+    case "stop":
+      return {
+        kind: "stop",
+        // Only a completed turn is continued; an aborted or failed one stops.
+        lastMessage:
+          (input.status ?? "completed") === "completed"
+            ? lastAssistantText(input.transcript_path)
+            : null,
+        // A followup_message turn reports loop_count > 0: one continue per turn.
+        stopHookActive: (input.loop_count ?? 0) > 0,
+      };
+  }
+};
+
+/** The transcript tail read for the last assistant message. */
+const TRANSCRIPT_TAIL_BYTES = 256 * 1024;
+
+/**
+ * The text of the last assistant entry in a Cursor agent transcript
+ * (`{"role":"assistant","message":{"content":[{"type":"text","text":…}]}}`
+ * per line), or null when it cannot be read.
+ */
+export const lastAssistantText = (file: string | null | undefined): string | null => {
+  if (!file || !path.isAbsolute(file)) return null;
+  try {
+    const size = fs.statSync(file).size;
+    const start = Math.max(0, size - TRANSCRIPT_TAIL_BYTES);
+    const buffer = Buffer.alloc(size - start);
+    const fd = fs.openSync(file, "r");
+    try {
+      fs.readSync(fd, buffer, 0, buffer.length, start);
+    } finally {
+      fs.closeSync(fd);
+    }
+    const lines = buffer.toString("utf8").split("\n");
+    for (let index = lines.length - 1; index >= 0; index--) {
+      let entry: unknown;
+      try {
+        entry = JSON.parse(lines[index]);
+      } catch {
+        continue;
+      }
+      if (!isRecord(entry) || entry.role !== "assistant") continue;
+      const content = isRecord(entry.message) ? entry.message.content : entry.content;
+      if (typeof content === "string") return content;
+      if (!Array.isArray(content)) return null;
+      const text = content
+        .filter((part) => isRecord(part) && part.type === "text" && typeof part.text === "string")
+        .map((part) => (part as { text: string }).text)
+        .join("\n");
+      return text || null;
+    }
+    return null;
+  } catch {
+    return null;
   }
 };
 
@@ -291,6 +363,8 @@ const render = (decision: HookDecision, native: string | null) => {
     return { json: { additional_context: decision.text }, exitCode: 0 };
   if (decision.kind === "notice")
     return { json: { user_message: decision.userMessage }, exitCode: 0 };
+  if (decision.kind === "continue" && native === "stop")
+    return { json: { followup_message: decision.reason }, exitCode: 0 };
   return {
     json: native !== null && BLOCKING.has(native) ? { permission: "allow" } : {},
     exitCode: 0,

package/src/hooks/hosts/opencode.ts

@@ -19,8 +19,11 @@ export const OPENCODE_DESCRIPTOR: HostDescriptor = {
     "subagent.stop": { support: "native", native: 'tool.hook("execute.after") subagent' },
     "prompt.submit": { support: "undocumented", native: null },
     "compact.pre": { support: "native", native: 'session.hook("compaction")' },
-    // OpenCode reports session.idle, but the plugin registers no stop hook yet.
-    stop: { support: "none", native: null },
+    // No stop hook: the plugin's event subscription sees session.idle and
+    // resumes the session with `ctx.session.synthetic({resume: true})`
+    // (@opencode/client 2.0.18). Partial: the continuation lands after the
+    // session went idle, and resume semantics are inferred from the schema.
+    stop: { support: "partial", native: 'event("session.idle")' },
   },
   shellPolicy: { deny: "native", channel: "effect", failClosed: false },
   context: {

package/src/hooks/hosts/pi.ts

@@ -19,7 +19,10 @@ export const PI_DESCRIPTOR: HostDescriptor = {
     "subagent.stop": { support: "none", native: null },
     "prompt.submit": { support: "undocumented", native: null },
     "compact.pre": { support: "native", native: "session_before_compact" },
-    stop: { support: "none", native: null },
+    // agent_end carries the run's messages; pi.sendMessage(…, {triggerTurn})
+    // starts one more turn (pi-coding-agent 0.85.1 types.d.ts). The host has
+    // no loop guard: the extension continues at most once per run.
+    stop: { support: "native", native: "agent_end" },
   },
   shellPolicy: { deny: "native", channel: "block", failClosed: false },
   context: {
@@ -41,7 +44,7 @@ export const PI_DESCRIPTOR: HostDescriptor = {
   },
   provenance: { sessionId: "native", agentIdOnTool: "none", postToolObserve: "native" },
   interaction: { questions: "native", writeBoundary: "native" },
-  stopControl: "none",
+  stopControl: "native",
   shellAvailable: "native",
   perEventCost: "low",
   capabilities: [

package/src/hooks/index.ts

@@ -20,6 +20,7 @@ export {
 } from "./context";
 export { shellPolicy } from "./policy";
 export { shellWrites, writeGate } from "./write-gate";
+export { asksUser, stopDecision, stopObligation, type StopObligation } from "./stop";
 export { callKey, noteRawCommit, rawGitPost, rawGitPre } from "./raw-git";
 export { promptNudge, recordSkillLoad, shellNudge, skillFileIn } from "./skill-nudge";
 export { isWriteTool, writePaths } from "./hosts/fields";

package/src/hooks/raw-git.ts

@@ -6,7 +6,8 @@
 //     remote onto a protected branch or the default target, naming the
 //     workit command;
 //   - lets routine raw commands run (`git commit`, a feature-branch push,
-//     `gh pr create|view|checks`, `glab mr create|view`) with a short nudge.
+//     `gh pr create|view|checks`, `glab mr create|view`) with a short nudge,
+//     once per kind per session, and none on a command that runs workit.
 // A raw `git commit` is recorded as the session's `commit.recorded` row so
 // the author's own verdict never reads as independent. The pre-tool hook
 // notes HEAD before the command (a marker in the commit's own repository);
@@ -29,6 +30,7 @@ import { pushRemoteName } from "../git/rev";
 import { appendHookObserved, readLedger } from "../ledger";
 import { resolveStore, resolveTaskKey, type StoreLocation } from "../store/paths";
 import type { HookDecision, HookInput } from "./protocol";
+import { readSessionMarker, sessionMarkerFile, writeSessionMarker } from "./session-marker";
 import { segmentsOf, type ShellDialect } from "./shell-words";
 
 const NONE: HookDecision = { kind: "none" };
@@ -176,6 +178,47 @@ export function rawInvocations(
   return found;
 }
 
+const LAUNCHERS = new Set([
+  "npx",
+  "bunx",
+  "pnpx",
+  "-y",
+  "--yes",
+  "pnpm",
+  "dlx",
+  "exec",
+  "env",
+  "sudo",
+  "command",
+]);
+const WORKIT_BIN = /(?:^|[\\/])workit(?:\.exe)?$|^@brainervirus\/workit-cli$/;
+
+/**
+ * The arguments of every workit CLI invocation in a shell command: past env
+ * assignments and package runners (`npx -y @brainervirus/workit-cli …`), and
+ * inside `bash -c '…'` scripts.
+ */
+export function workitInvocations(
+  command: string,
+  dialect: ShellDialect = "posix",
+  depth = 0,
+): string[][] {
+  const found: string[][] = [];
+  for (const { words } of segmentsOf(command, dialect)) {
+    const at = words.findIndex((word) => !/^\w+=/.test(word) && !LAUNCHERS.has(word));
+    if (at < 0) continue;
+    if (WORKIT_BIN.test(words[at])) {
+      found.push(words.slice(at + 1));
+      continue;
+    }
+    const shell = SHELLS.has(commandName(words[at]));
+    const script = shell && words[at + 1] === "-c" ? words[at + 2] : undefined;
+    if (depth < 3 && script !== undefined)
+      found.push(...workitInvocations(script, "posix", depth + 1));
+  }
+  return found;
+}
+
 /** What one raw invocation means for workit. */
 export type RawAction =
   | { kind: "commit"; amend: boolean }
@@ -336,7 +379,7 @@ const isWorkitWorkspace = (repo: Repo): boolean => {
 };
 
 /** Protected by the branch policy, or the workspace's default target. */
-const guardedBranch = (dir: string, branch: string): boolean => {
+export const guardedBranch = (dir: string, branch: string): boolean => {
   try {
     const policy = resolveBranchPolicyFor(dir);
     return (
@@ -459,16 +502,53 @@ const dialectOf = (input: HookInput): ShellDialect =>
     ? input.event.dialect
     : undefined) ?? "posix";
 
+/** The nudge kind an action shows: each is shown once per session (agent). */
+const nudgeKind = (action: RawAction): string =>
+  action.kind === "commit" && action.amend
+    ? "commit-amend"
+    : action.kind === "push" && action.blindForce
+      ? "push-force"
+      : action.kind;
+
+/**
+ * The nudges a session (or one of its subagents) has not been shown yet,
+ * recorded as shown in the per-session marker. Without a session or a
+ * marker, every nudge shows: the throttle fails open to repeating.
+ */
+const unseenNudges = (input: HookInput, nudges: Map<string, string>, store: string): string[] => {
+  const session = input.session.id;
+  const file = session ? sessionMarkerFile(input, session, store) : null;
+  if (!file) return [...nudges.values()];
+  const marker = readSessionMarker(file);
+  const agent = input.session.agentId ? `${input.session.agentId}:` : "";
+  const fresh = [...nudges.keys()].filter((kind) => !marker.raw.includes(agent + kind));
+  if (fresh.length)
+    writeSessionMarker(file, {
+      ...marker,
+      raw: [...marker.raw, ...fresh.map((kind) => agent + kind)],
+    });
+  return fresh.map((kind) => nudges.get(kind) as string);
+};
+
 /**
  * The pre-tool decision for a shell command: deny a gate bypass inside a
  * Workit workspace, else a nudge (as context) for routine raw delivery
- * commands, else nothing. Never throws, never writes.
+ * commands, else nothing. Each nudge kind is shown once per session, and a
+ * command that runs a workit verb itself gets none (denies still apply).
+ * `nudge: false` asks for the deny alone and spends no nudge. Never throws.
  */
-export function rawGitPre(input: HookInput, command: string): HookDecision {
+export function rawGitPre(
+  input: HookInput,
+  command: string,
+  options: { nudge?: boolean } = {},
+): HookDecision {
   try {
     if (!mentionsRawTool(command)) return NONE;
-    const nudges: string[] = [];
-    for (const { action, repo } of actionsIn(input.cwd, command, dialectOf(input))) {
+    const dialect = dialectOf(input);
+    const nudges = new Map<string, string>();
+    let store: string | null = null;
+    for (const { action, repo } of actionsIn(input.cwd, command, dialect)) {
+      store ??= repo.location.dir;
       if (action.kind === "merge") return deny(refusal(action, null));
       if (action.kind === "push")
         for (const target of action.targets) {
@@ -477,9 +557,12 @@ export function rawGitPre(input: HookInput, command: string): HookDecision {
             return deny(refusal(action, branch));
         }
       const nudge = nudgeFor(action, input.host, input.session.id);
-      if (nudge && !nudges.includes(nudge)) nudges.push(nudge);
+      if (nudge && !nudges.has(nudgeKind(action))) nudges.set(nudgeKind(action), nudge);
     }
-    return nudges.length ? { kind: "context", text: nudges.join("\n") } : NONE;
+    if (options.nudge === false || !store || nudges.size === 0) return NONE;
+    if (workitInvocations(command, dialect).length > 0) return NONE;
+    const shown = unseenNudges(input, nudges, store);
+    return shown.length ? { kind: "context", text: shown.join("\n") } : NONE;
   } catch {
     return NONE;
   }

package/src/hooks/session-marker.ts

@@ -0,0 +1,53 @@
+// The per-session nudge marker in the workspace store
+// (`<store>/hooks/skills-<session hash>.json`): which skills a session was
+// nudged about or loaded, and which raw-git nudge kinds it was shown, so each
+// nudge fires once per session. Each hook is a fresh process, so the marker
+// lives on disk. Every failure reads as an empty marker: hooks fail open.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStore } from "../store/paths";
+import type { HookInput } from "./protocol";
+
+export type SessionMarker = { nudged: string[]; loaded: string[]; raw: string[] };
+
+/**
+ * The marker in the workspace's store (null outside one: nothing is nudged or
+ * recorded there). `store` names the store directly when the command acts in
+ * another checkout than the hook's cwd.
+ */
+export const sessionMarkerFile = (
+  input: HookInput,
+  session: string,
+  store?: string,
+): string | null => {
+  let dir = store;
+  if (dir === undefined) {
+    const location = resolveStore(input.cwd);
+    if (location instanceof Error || !location.shared) return null;
+    dir = location.dir;
+  }
+  const name = createHash("sha256").update(`${input.host}\0${session}`).digest("hex").slice(0, 32);
+  return path.join(dir, "hooks", `skills-${name}.json`);
+};
+
+const list = (value: unknown): string[] =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+
+export const readSessionMarker = (file: string): SessionMarker => {
+  try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
+    return { nudged: list(value.nudged), loaded: list(value.loaded), raw: list(value.raw) };
+  } catch {
+    return { nudged: [], loaded: [], raw: [] };
+  }
+};
+
+export const writeSessionMarker = (file: string, marker: SessionMarker): void => {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(marker));
+  } catch {
+    // Fail open: without a marker a later nudge repeats.
+  }
+};

package/src/hooks/skill-nudge.ts

@@ -11,9 +11,6 @@
 // A session is nudged about one skill at most once (a marker per session
 // in the workspace store), never in a subagent, never once it loaded the skill.
 // Every failure answers "no nudge": hooks fail open.
-import { createHash } from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
 import {
   skillLoadWording,
   WORKIT_METHOD_SKILLS,
@@ -22,9 +19,9 @@ import {
   type WorkitSkill,
 } from "../core/skill-manifests";
 import { appendHookObserved, readLedger } from "../ledger";
-import { resolveStore } from "../store/paths";
 import type { HookDecision, HookInput, HostId } from "./protocol";
-import { inWorkitWorkspace, rawDelivery, rawGitPre } from "./raw-git";
+import { inWorkitWorkspace, rawDelivery, rawGitPre, workitInvocations } from "./raw-git";
+import { readSessionMarker, sessionMarkerFile, writeSessionMarker } from "./session-marker";
 import { segmentsOf, type ShellDialect } from "./shell-words";
 
 /** Skills the user starts; a nudge says to offer them, never to load them. */
@@ -105,35 +102,6 @@ export const promptTrigger = (prompt: string): { skill: WorkitSkill; trigger: st
   return null;
 };
 
-/** Per-session nudge state: skills nudged or loaded, so each nudges once. */
-type Marker = { nudged: string[]; loaded: string[] };
-
-/** The marker in the workspace's store (null outside one: nothing is nudged or recorded there). */
-const markerFile = (input: HookInput, session: string): string | null => {
-  const location = resolveStore(input.cwd);
-  if (location instanceof Error || !location.shared) return null;
-  const name = createHash("sha256").update(`${input.host}\0${session}`).digest("hex").slice(0, 32);
-  return path.join(location.dir, "hooks", `skills-${name}.json`);
-};
-
-const readMarker = (file: string): Marker => {
-  try {
-    const value = JSON.parse(fs.readFileSync(file, "utf8")) as Partial<Marker>;
-    return { nudged: value.nudged ?? [], loaded: value.loaded ?? [] };
-  } catch {
-    return { nudged: [], loaded: [] };
-  }
-};
-
-const writeMarker = (file: string, marker: Marker): void => {
-  try {
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, JSON.stringify(marker));
-  } catch {
-    // Fail open: without a marker a later nudge repeats.
-  }
-};
-
 /** Skills this session already loaded, from its `skill.loaded` rows. */
 const loadedSkills = (cwd: string, session: string): Set<string> => {
   const ledger = readLedger(cwd);
@@ -194,11 +162,11 @@ export function recordSkillLoad(
     const session = input.session.id;
     if (!skill || !session) return;
     if (!inWorkitWorkspace(input.cwd)) return;
-    const file = markerFile(input, session);
+    const file = sessionMarkerFile(input, session);
     if (!file) return;
-    const marker = readMarker(file);
+    const marker = readSessionMarker(file);
     if (marker.loaded.includes(skill)) return;
-    writeMarker(file, { ...marker, loaded: [...marker.loaded, skill] });
+    writeSessionMarker(file, { ...marker, loaded: [...marker.loaded, skill] });
     if (loadedSkills(input.cwd, session).has(skill)) return;
     appendHookObserved(input.cwd, {
       type: "skill.loaded",
@@ -218,12 +186,12 @@ const nudgeOnce = (
   skill: WorkitSkill,
   line: string,
 ): string | null => {
-  const file = markerFile(input, session);
+  const file = sessionMarkerFile(input, session);
   if (!file) return null;
-  const marker = readMarker(file);
+  const marker = readSessionMarker(file);
   if (marker.nudged.includes(skill) || marker.loaded.includes(skill)) return null;
   if (loadedSkills(input.cwd, session).has(skill)) return null;
-  writeMarker(file, { ...marker, nudged: [...marker.nudged, skill] });
+  writeSessionMarker(file, { ...marker, nudged: [...marker.nudged, skill] });
   return line;
 };
 
@@ -240,11 +208,22 @@ const promptLoads = (prompt: string): string | null =>
   /^\s*Load the (workit-[a-z-]+) skill with the skill tool\b/.exec(prompt)?.[1] ??
   null;
 
+/**
+ * A prompt that relays another agent's words, not the user's: Claude Code
+ * delivers subagent hand-backs, teammate messages and background-task
+ * notifications through UserPromptSubmit. A reviewer's report that says
+ * "regressed" is not a request for workit-debug.
+ */
+export const relayedMessage = (prompt: string): boolean =>
+  /^\s*(?:Another Claude session sent a message\b|<agent-message\s+from=|\[SYSTEM NOTIFICATION\b|<task-notification>)/.test(
+    prompt,
+  );
+
 /** A main session's prompt in a Workit workspace: one advisory line naming the skill it asks for. */
 export function promptNudge(input: HookInput, prompt: string | null | undefined): string | null {
   try {
     const session = input.session.id;
-    if (!prompt || !session || input.session.agentId) return null;
+    if (!prompt || !session || input.session.agentId || relayedMessage(prompt)) return null;
     const loads = promptLoads(prompt);
     if (loads) {
       // The prompt already loads its skill; record it, never nudge.
@@ -265,35 +244,13 @@ export function promptNudge(input: HookInput, prompt: string | null | undefined)
 }
 
 const WORKIT_DELIVERY = /^(?:pr (?:create|merge)|ci wait|git push)\b/;
-const SHELLS = new Set(["sh", "bash", "zsh", "dash", "ksh"]);
-const LAUNCHERS = new Set([
-  "npx",
-  "bunx",
-  "pnpx",
-  "-y",
-  "--yes",
-  "pnpm",
-  "dlx",
-  "exec",
-  "env",
-  "sudo",
-  "command",
-]);
-
-/** Does a segment list run a workit delivery verb (also inside `bash -c '…'`)? */
-const runsWorkitDelivery = (command: string, dialect: ShellDialect, depth = 0): boolean =>
-  segmentsOf(command, dialect).some(({ words }) => {
-    // The command word, past env assignments and package runners (`npx -y`).
-    const at = words.findIndex((word) => !/^\w+=/.test(word) && !LAUNCHERS.has(word));
-    if (at >= 0 && /(?:^|[\\/])workit(?:\.exe)?$|^@brainervirus\/workit-cli$/.test(words[at])) {
-      const args = words.slice(at + 1);
-      if (args.some((arg) => arg === "--help" || arg === "-h" || arg === "--dry-run")) return false;
-      return WORKIT_DELIVERY.test(args.join(" "));
-    }
-    const shell = SHELLS.has(words[at]?.split(/[\\/]/).at(-1) ?? "");
-    const script = shell && words[at + 1] === "-c" ? words[at + 2] : undefined;
-    return depth < 3 && script !== undefined && runsWorkitDelivery(script, "posix", depth + 1);
-  });
+/** Does the command run a workit delivery verb (also inside `bash -c '…'`), never help or a dry run? */
+const runsWorkitDelivery = (command: string, dialect: ShellDialect): boolean =>
+  workitInvocations(command, dialect).some(
+    (args) =>
+      !args.some((arg) => arg === "--help" || arg === "-h" || arg === "--dry-run") &&
+      WORKIT_DELIVERY.test(args.join(" ")),
+  );
 
 /**
  * Does the command deliver in a Workit workspace: a push, a PR/MR create or

package/src/hooks/stop.ts

@@ -0,0 +1,308 @@
+// Stop control (ledger decision "stop control: option A, nudge once"): when
+// the main agent ends its turn with an obligation the ledger or git can
+// prove unmet, the host continues it once with a reason naming the
+// obligation and the workit command that clears it. The obligations, for the
+// session's branch (the checked-out branch, on which this session recorded a
+// commit or opened a PR):
+//   (a) unpushed: a commit this session recorded, not on the push remote,
+//       while the effective endpoint is pr, green or merged;
+//   (b) checks: the branch's open PR has failing or pending checks recorded
+//       for its current head (`pr.status` rows) while the endpoint is green
+//       or merged;
+//   (c) verdict: the session opened the PR (or verified delivery) but the
+//       head carries no accepted non-author verdict.
+// A branch that landed owes nothing: a recorded merge (`workit pr merge`, or
+// `pr status`/`ci wait` seeing the forge report it merged) of HEAD or of a
+// head that contains this session's commits, or, with no merge recorded, an
+// upstream that is gone. Its remote branch may be deleted, and an
+// `--unverified` merge was the user's call.
+// A stop is never blocked: in a subagent, outside a Workit workspace, when
+// the host says this stop already follows a continuation (one continue per
+// turn), or when the agent's last message asks the user a question. Reads
+// the ledger and local git only (no forge call), and every failure allows
+// the stop.
+import { spawnSync } from "node:child_process";
+import { resolveAutonomy } from "../autonomy";
+import { currentBranch, pushRemoteName } from "../git/rev";
+import { checkVerdicts, readLedger, type ReadRow } from "../ledger";
+import type { HostDescriptor } from "./descriptor";
+import type { HookDecision, HookInput } from "./protocol";
+import { guardedBranch, inWorkitWorkspace } from "./raw-git";
+
+const NONE: HookDecision = { kind: "none" };
+
+export type StopObligation = {
+  kind: "unpushed" | "checks" | "verdict";
+  /** What is left, with the workit command that clears it. */
+  reason: string;
+};
+
+/** A question mark (Latin, full-width, Arabic) ending a sentence, or Spanish's opening one. */
+const QUESTION = /[?？؟](?=[\s*_`"')\]>]*(?:\s|$))|¿/;
+/** An offer or a request for permission. */
+const OFFER =
+  /\b(?:let me know|want me to|should I|shall I|would you like|do you want|if you(?:'d| would) like|may I|can I go ahead)\b/i;
+/** A `[y/N]`, `(y/n)` or `[Y/n]` prompt. */
+const YES_NO = /[[(]\s*y(?:es)?\s*\/\s*n(?:o)?\s*[\])]/i;
+/** A list item: `- a`, `* a`, `1. a`, `2) a`, `a) a`. */
+const LIST_ITEM = /^\s*(?:[-*+•]|\d+[.)]|[a-z][.)])\s+/i;
+
+/**
+ * Does the message end by asking the user something? The last two
+ * paragraphs (past code blocks and a trailing option list) are read for a
+ * question mark, an offer ("want me to", "shall I", "let me know") or a
+ * yes/no prompt: a stop that waits on the user is never blocked, so this
+ * errs towards "yes".
+ */
+export const asksUser = (message: string | null | undefined): boolean => {
+  if (!message) return false;
+  const paragraphs = message
+    .replace(/```[\s\S]*?(?:```|$)/g, "\n\n")
+    .split(/\n\s*\n/)
+    .map((paragraph) => paragraph.trim())
+    .filter(Boolean);
+  // A trailing option list belongs to the question before it.
+  while (
+    paragraphs.length > 1 &&
+    paragraphs
+      .at(-1)!
+      .split("\n")
+      .every((line) => LIST_ITEM.test(line))
+  )
+    paragraphs.pop();
+  const tail = paragraphs.slice(-2).join("\n");
+  return QUESTION.test(tail) || OFFER.test(tail) || YES_NO.test(tail);
+};
+
+const short = (sha: string | null | undefined) => (sha ?? "?").slice(0, 12);
+
+/** A git command's output lines, or null when it fails. */
+const gitList = (cwd: string, args: string[]): string[] | null => {
+  const run = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    timeout: 3_000,
+    windowsHide: true,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_OPTIONAL_LOCKS: "0", LC_ALL: "C" },
+  });
+  return run.status === 0 ? run.stdout.split("\n").filter(Boolean) : null;
+};
+
+const gitLine = (cwd: string, args: string[]): string | null => gitList(cwd, args)?.[0] ?? null;
+
+const sessionOf = (row: ReadRow): string | null =>
+  (typeof row.session === "string" ? row.session : null) ?? row.actor.session;
+
+/**
+ * The branch's open PR: the newest one the CLI opened or observed
+ * (`pr.created`, `pr.status`), unless it was merged since.
+ */
+/** A `pr.status` row's PR state; rows written before it was recorded are open. */
+const prState = (row: ReadRow): string => (typeof row.state === "string" ? row.state : "open");
+
+/** A CLI row saying the PR ended: `workit pr merge`, or the forge reporting it merged or closed. */
+const ended = (row: ReadRow): boolean =>
+  row.observer === "workit_cli" &&
+  (row.type === "pr.merged" || (row.type === "pr.status" && prState(row) !== "open"));
+
+const openPr = (rows: readonly ReadRow[]): number | null => {
+  const seen = rows.findLast(
+    (row) =>
+      (row.type === "pr.created" || row.type === "pr.status") &&
+      row.observer === "workit_cli" &&
+      typeof row.pr === "number",
+  );
+  if (!seen || ended(seen)) return null;
+  const closed = rows.some((row) => ended(row) && row.pr === seen.pr && row.seq > seen.seq);
+  return closed ? null : (seen.pr as number);
+};
+
+/**
+ * The heads the ledger records as merged: `workit pr merge` (`pr.merged`), or
+ * the forge reporting the PR merged (`pr.status` state merged, as `workit pr
+ * status` and `workit ci wait` record a merge done in the forge UI). A PR
+ * closed without merging is not one. Newest last, at most three.
+ */
+const mergedHeads = (rows: readonly ReadRow[]): string[] =>
+  [
+    ...new Set(
+      rows
+        .filter(
+          (row) =>
+            row.observer === "workit_cli" &&
+            typeof row.head === "string" &&
+            (row.type === "pr.merged" || (row.type === "pr.status" && prState(row) === "merged")),
+        )
+        .map((row) => row.head as string),
+    ),
+  ].slice(-3);
+
+/** Is `sha` a commit in the local object store? */
+const localCommit = (cwd: string, sha: string): boolean =>
+  /^[0-9a-f]{7,64}$/.test(sha) && gitList(cwd, ["cat-file", "-e", `${sha}^{commit}`]) !== null;
+
+/** The branch's configured upstream was deleted on the remote and pruned. */
+const upstreamGone = (cwd: string, branch: string): boolean =>
+  gitLine(cwd, ["for-each-ref", "--format=%(upstream:track)", `refs/heads/${branch}`]) === "[gone]";
+
+/**
+ * Has the branch landed? A recorded merge (`mergedHeads`) of the current
+ * HEAD, or of a head that already contains every commit of this session on
+ * HEAD: the merge record and the branch both say done, so nothing is left to
+ * push (the remote branch may be deleted) or to verify (an `--unverified`
+ * merge was the user's call). With no merge recorded, an upstream that is
+ * gone (the forge deleted the merged branch and a fetch pruned it) says the
+ * same. New commits of this session after a recorded merge are not landed.
+ */
+const landed = (
+  cwd: string,
+  branch: string,
+  rows: readonly ReadRow[],
+  head: string | null,
+  mine: ReadonlySet<string>,
+): boolean => {
+  if (!head) return false;
+  const merged = mergedHeads(rows);
+  if (merged.length === 0) return upstreamGone(cwd, branch);
+  if (merged.includes(head)) return true;
+  if (mine.size === 0) return false;
+  return merged.some((at) => {
+    // Commits on HEAD the merged head lacks; null when it is not a local commit.
+    const after = gitList(cwd, ["rev-list", `--max-count=${UNPUSHED_SCAN}`, "HEAD", "--not", at]);
+    return after !== null && !after.some((sha) => mine.has(sha));
+  });
+};
+
+/** How far back (a) looks for unpushed commits. */
+const UNPUSHED_SCAN = 500;
+
+/**
+ * (a) This session's recorded commits on HEAD that neither the push remote
+ * nor a recorded merge holds. Another session's or the user's commits never
+ * count, nor do commits already merged before the branch was reused.
+ */
+const unpushed = (
+  cwd: string,
+  branch: string,
+  endpoint: string,
+  mine: ReadonlySet<string>,
+  merged: readonly string[],
+): StopObligation | null => {
+  const remote = pushRemoteName(cwd, branch);
+  if (!remote || mine.size === 0) return null;
+  const listed = gitList(cwd, [
+    "rev-list",
+    `--max-count=${UNPUSHED_SCAN}`,
+    "HEAD",
+    "--not",
+    `--remotes=${remote}`,
+    ...merged.filter((sha) => localCommit(cwd, sha)),
+  ]);
+  const count = (listed ?? []).filter((sha) => mine.has(sha)).length;
+  if (count === 0) return null;
+  return {
+    kind: "unpushed",
+    reason: `${branch} has ${count} commit(s) of this session not on ${remote}, and this workspace's endpoint is \`${endpoint}\` (\`workit grant show\`): push them with \`workit git push\`${endpoint === "pr" ? ", then open or update the PR (`workit pr create --fill`)" : ""}.`,
+  };
+};
+
+/** (b) The open PR's checks, as last recorded for the current head. */
+const redChecks = (
+  rows: readonly ReadRow[],
+  pr: number,
+  head: string,
+  endpoint: string,
+): StopObligation | null => {
+  const status = rows.findLast(
+    (row) => row.type === "pr.status" && row.observer === "workit_cli" && row.pr === pr,
+  );
+  const state = status && status.head === head && prState(status) === "open" ? status.checks : null;
+  if (state !== "failing" && state !== "pending") return null;
+  return {
+    kind: "checks",
+    reason: `PR #${pr}'s checks were last seen ${state} at ${short(head)}, and this workspace's endpoint is \`${endpoint}\`: run \`workit ci wait --pr ${pr}\`${state === "failing" ? " after fixing the failures `workit pr status` lists (then push)" : ""}.`,
+  };
+};
+
+/** (c) Delivered by this session, yet no accepted non-author verdict on the head. */
+const unverified = (
+  cwd: string,
+  branch: string,
+  all: readonly ReadRow[],
+  descriptor: HostDescriptor,
+): StopObligation | null => {
+  const check = checkVerdicts(cwd, branch, all);
+  if (check.accepted.accepted || check.accepted.reasons.includes("failing_verdict")) return null;
+  const has = check.review === "self-reviewed" ? "only a self verdict" : "no current verdict";
+  const verifier = `${descriptor.subagents.agentPrefix}verifier`;
+  return {
+    kind: "verdict",
+    reason: `the head ${short(check.head)} of ${branch}, which this session delivered, has ${has}: if no verifier is already running on it, hand it to a session that did not author it (the ${verifier} agent records \`workit ledger verdict <result> --branch ${branch} --how "<evidence>"\`), or tell the user it is unverified. Never record a verdict on your own work.`,
+  };
+};
+
+/** The first unmet obligation for the session's branch, or null. Never throws. */
+export function stopObligation(
+  input: HookInput,
+  descriptor: HostDescriptor,
+): StopObligation | null {
+  try {
+    const session = input.session.id;
+    // Outside a Workit workspace there is no ledger either; the check only
+    // spares every other repository's Stop the git and ledger reads below.
+    if (!session || input.session.agentId || !inWorkitWorkspace(input.cwd)) return null;
+    const branch = currentBranch(input.cwd);
+    if (!branch || guardedBranch(input.cwd, branch)) return null;
+    const ledger = readLedger(input.cwd);
+    if (!ledger.ok) return null;
+    const all = ledger.value.rows;
+    const rows = all.filter((row) => row.branch === branch);
+    const mine = rows.filter((row) => sessionOf(row) === session);
+    const commits = new Set(
+      mine
+        .filter((row) => row.type === "commit.recorded")
+        .map((row) => (typeof row.sha === "string" ? row.sha : row.head))
+        .filter((sha): sha is string => typeof sha === "string"),
+    );
+    const delivered = mine.some(
+      (row) =>
+        row.observer === "workit_cli" &&
+        (row.type === "pr.created" || row.type === "delivery.verified"),
+    );
+    if (commits.size === 0 && !delivered) return null;
+    const head = gitLine(input.cwd, ["rev-parse", "HEAD"]);
+    if (landed(input.cwd, branch, rows, head, commits)) return null;
+    const endpoint = resolveAutonomy(input.cwd).effectiveEndpoint;
+    if (endpoint !== "commit") {
+      const left = unpushed(input.cwd, branch, endpoint, commits, mergedHeads(rows));
+      if (left) return left;
+    }
+    const pr = openPr(rows);
+    if ((endpoint === "green" || endpoint === "merged") && pr !== null && head) {
+      const left = redChecks(rows, pr, head, endpoint);
+      if (left) return left;
+    }
+    return delivered ? unverified(input.cwd, branch, all, descriptor) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The stop decision: continue once with the obligation, or allow. A stop
+ * that follows a continuation (`stopHookActive`), a subagent's stop, and a
+ * stop whose last message asks the user something are always allowed. So is
+ * a stop whose last message is unknown: it may be a question.
+ */
+export function stopDecision(input: HookInput, descriptor: HostDescriptor): HookDecision {
+  const event = input.event;
+  if (event.kind !== "stop" || event.stopHookActive) return NONE;
+  if (!event.lastMessage?.trim() || asksUser(event.lastMessage)) return NONE;
+  const left = stopObligation(input, descriptor);
+  return left
+    ? {
+        kind: "continue",
+        reason: `Workit: before stopping, ${left.reason} If this cannot be done now, say so to the user and stop.`,
+      }
+    : NONE;
+}

package/src/ledger.ts

@@ -1801,6 +1801,9 @@ export function summarizeRow(row: ReadRow): RowSummary {
     case "pr.created":
       summary = `#${row.pr ?? "?"} -> ${text("base")} at ${(row.head ?? "?").slice(0, 12)}${row.created === false ? " (existing)" : ""}`;
       break;
+    case "pr.status":
+      summary = `#${row.pr ?? "?"} ${text("state") && text("state") !== "open" ? `${text("state")} ` : ""}checks ${text("checks") || "?"} at ${(row.head ?? "?").slice(0, 12)}`;
+      break;
     case "pr.merged":
       summary = `#${row.pr ?? "?"} ${text("method")} at ${(row.head ?? "?").slice(0, 12)}${text("mergeSha") ? ` -> ${text("mergeSha").slice(0, 12)}` : ""}`;
       break;