@cstart/coldstart 2.1.1 → 2.2.1

package/hooks/kb-elicit.mjs

@@ -1,35 +1,45 @@
 #!/usr/bin/env node
 /**
- * kb-elicit.mjs — Stop + SubagentStop hook. Notebook capture, task-shaped.
+ * kb-elicit.mjs — Stop + SubagentStop hook. Notebook capture, trigger-timed.
  *
- * ALWAYS FIRES when the agent touched ANY repo file this session — the old
- * deep-read gate (whole-file Reads + `gs` only) is gone: read-modality
- * classification proved unwinnable (windowed Reads, Bash cat/sed, MCP readers
- * are all invisible to it — a q8-style session lost real knowledge to a
- * FAST-EXIT). The hook does mechanical extraction only; THE AGENT decides
- * whether anything is worth writing — the prompt's gate and "write NOTHING
- * when" list carry that decision. FAST-EXIT remains only for sessions that
- * touched zero repo files (pure orchestrators / Q&A turns).
+ * v5 (2026-07-17): the always-fire gate is gone. Every Stop updates per-file
+ * EVIDENCE RECORDS (hooks/evidence.mjs — edit/read/gs tiers; mentions and
+ * .coldstartignore'd files never count) and advances the TRIGGER state machine
+ * (hooks/trigger.mjs — score/arm, fire on descent/surge, cap, .git HEAD
+ * drift). Most stops exit silently. When the trigger fires:
  *
- * Merge-vs-new is agent-curated: touched files are annotated with their
- * existing notes (id + note file path, from `coldstart kb status --json`) so
- * the agent can read a candidate and pass --into/--new on its FIRST kb write
- * — the exit-3 candidates bounce is the safety net, not the mechanism.
+ *   descent/surge → NON-BLOCKING: the capture payload is written to a pending
+ *     file; kb-recall.mjs (UserPromptSubmit) delivers it with the user's next
+ *     prompt. The stop itself is never blocked — no more answer-then-homework
+ *     agitation (upstream #76721 sidestepped).
+ *   cap / head-drift → BLOCKING Stop (backlog rescue / commit boundary): the
+ *     payload rides the classic block decision.
+ *   SubagentStop → BLOCKING as before (a subagent has no next prompt); the
+ *     restate-deliverable tail prevents the #61 return-value hijack.
  *
- * SubagentStop fires too (subagents often do the only real reads); duplication
- * is guarded by disjoint transcripts + firsthand-only + SubagentStop preceding
- * Stop (the sub's notes are on disk when the main agent's write runs, so they
- * surface as "candidates → reconcile, don't duplicate").
+ * The payload (hooks/capture-payload.mjs) is the finalized v5 checklist:
+ * worklist + decide-time rules only; spec formats live behind `kb write`.
+ * Worklists annotate per file: evidence tier, existing-note state (from
+ * `kb status --json`), and "no consumers in import graph" (from `coldstart
+ * consumers --json`, fail-open — surfacing the graph's blind spot so agents
+ * know when an observed usage fact is worth recording).
  *
- * Hooks never author or parse markdown — all facts come from `coldstart kb`.
- * Self-contained + fail-open: ANY error → exit 0 → the stop is allowed.
+ * Hooks never author or parse markdown — all note facts come from `coldstart
+ * kb`. Self-contained + fail-open: ANY error → exit 0 → the stop is allowed.
  */
 
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { execFileSync } from "node:child_process";
-import { existsSync, writeFileSync, appendFileSync, readFileSync, mkdirSync, statSync } from "node:fs";
+import { existsSync, writeFileSync, appendFileSync, readFileSync } from "node:fs";
+
+import { extractEvidence, segmentStats } from "./evidence.mjs";
+import { initialState, step } from "./trigger.mjs";
+import { loadIgnore } from "./ignore.mjs";
+import { buildCapturePayload } from "./capture-payload.mjs";
+import {
+  worklistEntries, freshNotedSet, gitHead, logCaptureEvent, writePendingCapture,
+} from "./elicit-core.mjs";
 
 // hooks/ sits beside dist/ in both the repo and the published package.
 const CLI = fileURLToPath(new URL("../dist/index.js", import.meta.url));
@@ -41,232 +51,7 @@ function log(msg) {
   try { appendFileSync(LOG_FILE, `[${new Date().toISOString()}] elicit: ${msg}\n`); } catch { /* never fail logging */ }
 }
 
-// --- Touched-file detection ----------------------------------------------------
-function normRel(root, p) {
-  let s = String(p || "").trim();
-  if (!s) return "";
-  if (s.startsWith("/")) {
-    if (root && s.startsWith(root + "/")) return s.slice(root.length + 1);
-    return "";
-  }
-  return s.replace(/^\.\//, "");
-}
-
-// Path-like tokens inside a shell command: anything with an extension, plus
-// whatever follows `coldstart gs`. Existence under root is checked by the
-// caller — this only extracts candidates.
-const BASH_PATH_RE = /(?:^|[\s"'`=(:;|])((?:\.{1,2}\/|\/)?[A-Za-z0-9_][A-Za-z0-9_.\/-]*\.[A-Za-z0-9]{1,8})(?=$|[\s"'`):;,|>])/gm;
-
-// EVERY repo file the agent touched this run, however it got there: Read
-// (windowed or not), Edit/Write, `coldstart gs`, or a path mentioned in a
-// Bash command (cat/sed/grep/head — the modalities the old deep-read gate was
-// blind to). Whether any of it is WORTH capturing is the agent's call.
-function touchedFiles(transcriptPath, root) {
-  const out = [];
-  const seen = new Set();
-  const add = (rel, mustExist) => {
-    if (!rel || seen.has(rel) || rel.startsWith(".coldstart/")) return;
-    if (mustExist) {
-      try { if (!statSync(join(root, rel)).isFile()) return; } catch { return; }
-    }
-    seen.add(rel);
-    out.push(rel);
-  };
-  let text = "";
-  try { text = readFileSync(transcriptPath, "utf8"); } catch { return out; }
-  for (const line of text.split("\n")) {
-    if (!line.trim() || line[0] !== "{") continue;
-    let rec;
-    try { rec = JSON.parse(line); } catch { continue; }
-    if (rec.type !== "assistant") continue;
-    const content = rec.message?.content;
-    if (!Array.isArray(content)) continue;
-    for (const b of content) {
-      if (!b || b.type !== "tool_use") continue;
-      const inp = b.input || {};
-      if (b.name === "Read" || b.name === "Edit" || b.name === "Write" || b.name === "NotebookEdit") {
-        add(normRel(root, inp.file_path), false);
-      } else if (b.name === "Bash") {
-        const cmd = String(inp.command || "");
-        for (const g of cmd.matchAll(/coldstart\s+gs\s+(\S+)/g)) add(normRel(root, g[1]), false);
-        let n = 0;
-        for (const m of cmd.matchAll(BASH_PATH_RE)) {
-          if (++n > 12) break; // a single huge command must not dominate
-          add(normRel(root, m[1]), true); // shell tokens are guesses — verify on disk
-        }
-      }
-    }
-  }
-  return out;
-}
-
-// --- Per-file annotations from the core (hooks never parse md) -----------------
-function noteAnnotations(root, files) {
-  try {
-    const raw = execFileSync(
-      "node", [CLI, "kb", "status", "--json", "--paths", files.join(","), "--root", root],
-      { encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "ignore"] },
-    );
-    const parsed = JSON.parse(raw);
-    const byPath = new Map();
-    for (const entry of parsed.paths || []) byPath.set(entry.path, entry.notes || []);
-    return byPath;
-  } catch (e) {
-    log(`kb status unavailable (${String(e).split("\n")[0]}) — annotating as no-notes`);
-    return new Map();
-  }
-}
-
-// Always-fire can surface long touch lists; the prompt stays bounded. Files
-// WITH existing notes always make the cut (they carry the merge decision).
-const MAX_PROMPT_FILES = 30;
-
-function filesBlock(root, files) {
-  const notes = noteAnnotations(root, files);
-  let listed = files;
-  if (files.length > MAX_PROMPT_FILES) {
-    const noted = files.filter((f) => (notes.get(f) || []).length);
-    const bare = files.filter((f) => !(notes.get(f) || []).length);
-    listed = [...noted, ...bare].slice(0, MAX_PROMPT_FILES);
-  }
-  const lines = [];
-  for (const rel of listed) {
-    const anchored = notes.get(rel) || [];
-    if (!anchored.length) { lines.push(`- ${rel}   [no notes yet]`); continue; }
-    const parts = anchored.map((n) => {
-      const flag = n.state === "changed" || n.state === "missing"
-        ? ` — FLAGGED STALE: you just read this file, so fix or re-stamp it (list the path in "verified")`
-        : "";
-      return `${n.id} [${n.type} · ${n.state}]${flag} (.coldstart/notebook/notes/${n.id}.md)`;
-    });
-    lines.push(`- ${rel}   has notes: ${parts.join("; ")}`);
-  }
-  if (listed.length < files.length) lines.push(`- …and ${files.length - listed.length} more touched files`);
-  return lines.join("\n");
-}
-
-// --- The capture prompt (v4, 2026-07-07 — user-authored opening; validation-run
-// configuration: gates off via --force, capture-only) ---------------------------
-function buildCapturePrompt(root, block, sid, isSubagent) {
-  return `You have completed a task now and have gathered knowledge as a part of that task or \
-process — knowledge another agent in future could make use of.
-
-But before writing any notes, we need to decide whether the task you completed deserves a note. \
-If you were investigating on an older branch or doing a PR review, we may not need to save notes \
-because that code is not in the present — it's in the past or it's in the future. The notes that \
-we write are backed by the code in the present. This was an example to explain to you. As an \
-agent who worked on the current task, you know its exact intent and are best suited to decide \
-whether this task deserves a note. And if nothing about the current code is worth recording, \
-then no note is the right answer.
-
-Once you decide the task does deserve a note, we store it in a notebook format, and this \
-notebook has to be backed by the codebase you are working on.
-
-We need to save only the working knowledge of the codebase in a specific format so that it can \
-be searched and served to future cold agents. We don't need to store any general interaction you \
-had, just the knowledge about the codebase. As a part of your task, you must have done some \
-investigation, file reading, new file/feature addition or updated existing files or features. It \
-could have been a bug fix or any other operation on the codebase. We need to store it in the \
-below format —
-
-THE NOTEBOOK HAS THREE CONTAINERS. Put each piece of knowledge in its one home:
-
-1. FILE notes (if you decided to write a note for the entire task) — write one for EVERY file \
-you actually read and understood this session. No judgment call about whether it seems obvious. \
-First decide the file's CHARACTER:
-   - hub    = the file has no single purpose (models.py, helpers, utils). Knowledge lives per \
-SYMBOL, as facets: one facet for each symbol you worked with this session. Only symbols you \
-have firsthand knowledge of — never enumerate the rest.
-   - single = the file has one purpose. One summary, 1-3 sentences.
-   The best facet/summary says: what it does that the name doesn't tell you, what to watch out \
-for when changing it, and which tests or checks matter.
-
-2. FLOW notes — RARE. Not "my task touched several files": that is most tasks, and its \
-knowledge belongs in the file notes. A flow exists only when the RELATIONSHIP between files is \
-itself the knowledge — such as an enforcement gap, an asymmetry or inconsistency between files, \
-a dead/unreachable path, or an evolution that explains a surprising present shape. The gate: \
-name, in one sentence, the fact a reader of ALL the file notes would still be missing; if you \
-cannot, there is no flow — put the facts in file notes. That sentence is the FIRST sentence of \
-the flow's summary. Never a flow: a feature's parts-list ("the model, the view, the route, the \
-config, the tests" — an index, not knowledge); a mechanism living in one file (that file's note); a call-chain or \
-version history with no gotcha at the end. Steps are the minimal chain carrying the missing \
-fact — not a tour of every file the task visited. A step never restates what a file note \
-already says — the detail lives in the file's facet; the flow links to it.
-
-3. LESSON notes — rare. Only one thing qualifies:
-   - a confirmed ABSENCE ("there is no X in this repo"), with the search terms that proved it.
-   If it is about one file or one symbol, it is a facet, not a lesson. Repo-wide rules and \
-conventions are the human's to define (CLAUDE.md / coldstart.md / AGENTS.md) — do not mint them here.
-
-Fixed a bug? The actual cause goes into the culpable file's facet, and the SYMPTOM words go \
-into that file note's "aliases" — the symptom is what a future agent will search. If the cause \
-spans files, the story is a flow.
-
-Read a note this session that turned out WRONG? Correct it now — same spec with its "id" \
-(fields merge; yours win), or op "retract" for a wrong claim. You are the warm agent; there is \
-no "next".
-
-RULES:
-- Codebase knowledge only — never the interaction, the user, or your own process.
-- Firsthand only: if it arrived secondhand (e.g. a subagent's report) and you did not verify it \
-yourself, do not store it.
-- Say only what you verified in THIS file, this session: never assert a method, branch, or \
-config key you did not confirm is present, and never describe what a DIFFERENT file does (that \
-is a flow, or that file's own note). A confident whole-file claim from a partial read is the \
-single most common bad note.
-- If a future agent would not act differently for knowing it, do not store it.
-- SEARCH BEFORE YOU WRITE a flow or lesson: run \`node ${CLI} kb search "<your task words>" \
---root ${root}\` once. If an existing flow already tells this mechanism's story, UPDATE it \
-(same spec with its "id") instead of writing a near-duplicate.
-- Note ids are never composed by you. In facet "flows" backlinks, reference a flow by its \
-EXACT title (as written in your flow spec) or by an id copied from kb search output — the \
-tool resolves titles to ids at write time. A typo prints a WARNING (the ref is kept but \
-dangling) — fix any warning the write prints, in this session. Never guess an id.
-- "verified": list every anchor path you actually read THIS session — that re-stamps its \
-freshness. Never list a file you did not open.
-- Paths are join keys: always repo-relative, exactly as they appear in the repo. Fix any path \
-warning the write prints — a wrong path is a silently dangling link.
-
-Files you touched this run, with their existing notes (read one before writing if you need to \
-see what it already says — never create a second note for the same file):
-
-${block}
-
-HOW TO WRITE — ONE Bash block TOTAL: author every spec with a heredoc and
-chain every write in the SAME block, flows before the file notes that
-reference them. Never author specs one-per-message with a file-editing tool —
-that is the single biggest waste of turns here.
-  cat > /tmp/spec-1.json <<'SPEC'
-  { ...flow... }
-SPEC
-  cat > /tmp/spec-2.json <<'SPEC'
-  { ...file note; facets reference the flow by its EXACT title... }
-SPEC
-  node ${CLI} kb write /tmp/spec-1.json --root ${root} --session ${sid} --force && \\
-  node ${CLI} kb write /tmp/spec-2.json --root ${root} --session ${sid} --force
-Chain the writes with && — if a flow write fails, its dependent file notes
-must not run. Never write the same note id twice.
-
-Spec shapes (only include fields you actually have):
-  file (hub):    {"type":"file-hub","path":"src/x.py","aliases":["symptom or search words"],
-                  "facets":[{"symbol":"ClassOrFn","detail":"the non-obvious thing about THIS symbol",
-                             "flows":["<flow-note-id or the flow's exact title>"]}]}
-  file (single): {"type":"file-single","path":"src/x.py",
-                  "summary":"its one purpose + how (1-3 sentences)"}
-  flow:          {"type":"flow","title":"how X happens","aliases":["other words for X"],
-                  "summary":"one paragraph",
-                  "steps":[{"path":"src/a.py","symbols":["entry"],"role":"receives the request"}],
-                  "invariants":["what must hold"],"verified":["src/a.py"]}
-  lesson:        {"type":"lesson","kind":"absence","title":"the absence, e.g. no retry logic",
-                  "body":"what you looked for + that it is not there",
-                  "scope":{"terms":["search","terms"]}}          (the search that proved it)
-
-${isSubagent
-  ? `Once you have handled the notebook — whether you wrote notes or decided none were needed — remember you were spawned as a subagent. The coordinator that spawned you receives ONLY your final message, so your last message must repeat, in full, the result you produced for it — your findings, not the notebook decision.`
-  : `When your notes are written, stop.`}`;
-}
-
-// --- stdin + guards -------------------------------------------------------------
+// --- stdin ---------------------------------------------------------------------
 function readStdin() {
   return new Promise((res) => {
     let data = "";
@@ -283,14 +68,6 @@ function readStdin() {
   });
 }
 
-function logCaptureEvent(root, event) {
-  try {
-    const dir = join(root, ".coldstart", "notebook", ".metrics");
-    mkdirSync(dir, { recursive: true });
-    appendFileSync(join(dir, "capture.jsonl"), JSON.stringify({ ts: new Date().toISOString(), ...event }) + "\n");
-  } catch { /* metrics never wedge a stop */ }
-}
-
 process.on("uncaughtException", (e) => { log(`uncaught ${e?.stack || e}`); process.exit(0); });
 process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); process.exit(0); });
 
@@ -312,25 +89,14 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
     const sid = String(input.session_id || "").replace(/[^A-Za-z0-9_-]/g, "");
     if (!sid) { log("SKIP no-session-id"); process.exit(0); }
 
-    // Guard 2: capture across a long session, but only files not yet offered.
-    // A boolean once-per-(session,agent) marker silently dropped ALL knowledge
-    // after the first Stop; instead we remember which files were already offered
-    // for capture and elicit only the new ones (the delta is computed below,
-    // once the SubagentStop transcript is resolved). Subagents share the parent
-    // session_id, so the record is scoped by agent too.
     const aid = String(input.agent_id || "main").replace(/[^A-Za-z0-9_-]/g, "") || "main";
-    const marker = join(tmpdir(), `coldstart-kb-${sid}-${aid}.json`);
-    let offered = new Set();
-    try { offered = new Set(JSON.parse(readFileSync(marker, "utf8")).files || []); } catch { /* first Stop of this session */ }
+    const isSubagent = input.hook_event_name === "SubagentStop";
 
     // On SubagentStop, transcript_path is the PARENT's transcript (confirmed:
-    // claude-code#11396) — scanning it would elicit the sub off the parent's
-    // reads. The sub's own transcript lives at
-    // <parent-transcript-stem>/subagents/agent-<agent_id>.jsonl (verified on
-    // disk; agent_transcript_path in the payload is still unshipped, #16424).
-    // No sub transcript found → exit; capture falls to the main Stop.
+    // claude-code#11396); the sub's own lives at
+    // <parent-transcript-stem>/subagents/agent-<agent_id>.jsonl.
     let transcriptPath = String(input.transcript_path || "");
-    if (input.hook_event_name === "SubagentStop") {
+    if (isSubagent) {
       const own = String(input.agent_transcript_path || "") ||
         (aid !== "main" && transcriptPath
           ? join(transcriptPath.replace(/\.jsonl$/, ""), "subagents", `agent-${aid}.jsonl`)
@@ -341,29 +107,89 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
       }
       transcriptPath = own;
     }
-    const files = transcriptPath ? touchedFiles(transcriptPath, root) : [];
-    // Delta: only files not already offered on an earlier Stop this session.
-    const newFiles = files.filter((f) => !offered.has(f));
+    if (!transcriptPath || !existsSync(transcriptPath)) { log("SKIP no-transcript"); process.exit(0); }
 
-    // FAST-EXIT when there is nothing NEW to capture — either no repo file was
-    // touched at all (pure orchestration / Q&A) or every touched file was already
-    // offered on a previous Stop. No record is written on this path, so an early
-    // no-op Stop can never burn the session's capture.
-    if (!newFiles.length) {
-      log(`FAST-EXIT no-new-files session=${sid} agent=${aid} touched=${files.length} event=${input.hook_event_name || "?"}`);
+    const ignore = loadIgnore(root);
+    const marker = join(tmpdir(), `coldstart-kb-${sid}-${aid}.json`);
+    let state = null;
+    try {
+      const parsed = JSON.parse(readFileSync(marker, "utf8"));
+      if (parsed && parsed.v === 2) state = parsed;
+    } catch { /* first Stop of this session (or a pre-v5 marker: start fresh) */ }
+    if (!state) state = initialState();
+
+    // This stop's transcript slice (everything since the last processed line).
+    const text = readFileSync(transcriptPath, "utf8");
+    const lines = text.split("\n");
+    // A transcript SHORTER than our stored offset was replaced out from under us
+    // — Claude Code's /compact rewrites it far shorter (also log rotation). The
+    // offset now points past the end, so slice() would return an empty segment
+    // and silently drop this turn's (and every later turn's) evidence until the
+    // line count grows back. Reset to reprocess the new transcript from its start.
+    if (state.lineCount > lines.length) state.lineCount = 0;
+    const segment = lines.slice(state.lineCount).join("\n");
+    state.lineCount = lines.length;
+
+    // Evidence: contentRead tiers only, ignore-filtered. Mentions never count.
+    const raw = extractEvidence(segment, root);
+    const delta = new Map();
+    for (const [rel, r] of raw) {
+      if (r.reads + r.edits + r.gs === 0) continue;
+      if (ignore(rel)) continue;
+      delta.set(rel, r);
+    }
+
+    // --- Subagent path: one-shot, no trigger. Offer once, block-deliver. ------
+    if (isSubagent) {
+      const offered = new Set(Object.keys(state.files));
+      const fresh = [...delta.keys()].filter((rel) => !offered.has(rel));
+      for (const rel of fresh) state.files[rel] = { ...delta.get(rel), captured: true };
+      writeFileSync(marker, JSON.stringify(state));
+      if (!fresh.length) { log(`FAST-EXIT subagent no-new-files session=${sid} agent=${aid}`); process.exit(0); }
+      const entries = worklistEntries(CLI, root, fresh, Object.fromEntries(fresh.map((rel) => [rel, delta.get(rel)])), log);
+      const payload = buildCapturePayload({ root, cli: CLI, sid, entries, envelope: "subagent" });
+      logCaptureEvent(root, { event: "fire", reason: "subagent", session: sid, agent: aid, files: fresh.length });
+      log(`FIRE subagent session=${sid} agent=${aid} files=${fresh.length}`);
+      process.stdout.write(JSON.stringify({ decision: "block", reason: payload }));
       process.exit(0);
     }
 
-    // Record everything now offered BEFORE returning the block, so the post-write
-    // re-Stop and every later Stop skip these files. stop_hook_active (Guard 1)
-    // still short-circuits the immediate re-Stop; this record survives across the
-    // natural turns of a long session.
-    try { writeFileSync(marker, JSON.stringify({ files: [...offered, ...newFiles], ts: Date.now() })); } catch { /* best effort */ }
+    // --- Main path: trigger state machine -------------------------------------
+    const head = gitHead(root);
+    const headDrift = Boolean(state.head && head && head !== state.head);
+    state.head = head || state.head;
+
+    const stats = segmentStats(segment);
+    const freshNoted = freshNotedSet(CLI, root, [...delta.keys()].filter((rel) => !state.files[rel]), log);
 
-    const prompt = buildCapturePrompt(root, filesBlock(root, newFiles), sid, input.hook_event_name === "SubagentStop");
-    logCaptureEvent(root, { event: "elicit", session: sid, agent: aid, touched: files.length, new: newFiles.length, hook: input.hook_event_name });
-    log(`ELICIT session=${sid} agent=${aid} new=${newFiles.length} touched=${files.length} promptBytes=${prompt.length} event=${input.hook_event_name || "?"}`);
-    process.stdout.write(JSON.stringify({ decision: "block", reason: prompt }));
+    const { state: next, decision } = step(state, {
+      delta,
+      synthesis: stats.synthesis,
+      freshNoted,
+      headDrift,
+    });
+    writeFileSync(marker, JSON.stringify(next));
+
+    if (!decision) {
+      log(`TICK session=${sid} stop=${next.stop} active=${next.activeStops} quiet=${next.quietRun} armed=${next.armed} files=${Object.keys(next.files).length} delta=${delta.size}`);
+      process.exit(0);
+    }
+
+    const entries = worklistEntries(CLI, root, decision.files, next.files, log);
+    logCaptureEvent(root, {
+      event: "fire", reason: decision.fire, mode: decision.mode, session: sid,
+      score: decision.score, files: decision.files.length, stop: next.stop, fires: next.fires,
+    });
+    log(`FIRE ${decision.fire} mode=${decision.mode} session=${sid} score=${decision.score} files=${decision.files.length}`);
+
+    if (decision.mode === "block") {
+      const payload = buildCapturePayload({ root, cli: CLI, sid, entries, envelope: "block" });
+      process.stdout.write(JSON.stringify({ decision: "block", reason: payload }));
+    } else {
+      // Non-blocking: kb-recall delivers this with the user's next prompt.
+      const payload = buildCapturePayload({ root, cli: CLI, sid, entries, envelope: "inject" });
+      writePendingCapture(sid, decision.fire, payload);
+    }
   } catch (e) {
     log(`handler ${e?.stack || e}`); // fail-open: no stdout → stop allowed
   }

package/hooks/kb-recall.mjs

@@ -28,6 +28,13 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 
+// Pending-capture delivery (v5 trigger): a descent/surge fire at the previous
+// Stop wrote its worklist payload to a pending file instead of blocking the
+// stop. It rides the SAME next-prompt channel as recall — capture first, then
+// the user's request. Consumed (deleted) on delivery; stale pendings (>24h,
+// e.g. a session resumed days later) are dropped.
+import { takePendingCapture } from "./elicit-core.mjs";
+
 // hooks/ sits beside dist/ in both the repo and the published package.
 const CLI = fileURLToPath(new URL("../dist/index.js", import.meta.url));
 
@@ -71,27 +78,36 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
     if (!root) process.exit(0);
     setLogRoot(root);
 
-    // No notebook → no tax, not even a child process.
-    if (!existsSync(join(root, ".coldstart", "notebook", ".raw"))) process.exit(0);
+    const sid = String(input.session_id || "").replace(/[^\w-]/g, "");
+
+    // A pending capture (non-blocking fire at the previous Stop) is delivered
+    // regardless of recall hits — it must not depend on the notebook existing
+    // (the first capture is what creates it).
+    const pending = takePendingCapture(sid);
 
     const prompt = String(input.prompt || "").slice(0, MAX_QUERY_CHARS).trim();
-    if (!prompt) process.exit(0);
 
     let page = "";
-    try {
-      page = execFileSync("node", [CLI, "kb", "search", "--hook", "--max", "3", "--root", root, prompt], {
-        encoding: "utf8",
-        timeout: SEARCH_TIMEOUT_MS,
-        stdio: ["ignore", "pipe", "ignore"],
-      });
-    } catch (e) {
-      log(`search failed/timed out: ${String(e).split("\n")[0]}`);
-      process.exit(0);
+    // No notebook / no prompt → no recall search, not even a child process.
+    if (prompt && existsSync(join(root, ".coldstart", "notebook", ".raw"))) {
+      try {
+        page = execFileSync("node", [CLI, "kb", "search", "--hook", "--max", "3", "--root", root, prompt], {
+          encoding: "utf8",
+          timeout: SEARCH_TIMEOUT_MS,
+          stdio: ["ignore", "pipe", "ignore"],
+        });
+      } catch (e) {
+        log(`search failed/timed out: ${String(e).split("\n")[0]}`);
+        page = "";
+      }
     }
 
     if (!page.trim() || page.startsWith("No notebook notes match") || page.startsWith("No notebook in")) {
-      log(`no hits (promptChars=${prompt.length})`);
-      process.exit(0);
+      if (!pending) {
+        log(`no hits (promptChars=${prompt.length})`);
+        process.exit(0);
+      }
+      page = "";
     }
 
     // Pointer page (rulings 2026-07-06/08): titles + gists + an OPENABLE note
@@ -101,7 +117,8 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
     // agents never used it). Trust framing: [fresh] content is reliable
     // as-is; the caution that remains is about COMPLETENESS (a note names a
     // finding, not necessarily your whole file set), not about content.
-    let block =
+    let block = "";
+    if (page) block =
       `The repo's notebook (notes written by past agents after real tasks here) has entries ` +
       `matching this request, below — each a title, a gist, and the note's file path. ` +
       `A note is a past agent's verified overview of a file or flow. If one matches your task, ` +
@@ -123,6 +140,16 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
     // never exceed 8.5KB.
     if (block.length > 8500) block = block.slice(0, 8500) + "\n…(truncated)";
 
+    // Pending capture rides FIRST (capture, then the user's request). If the
+    // combination would spill past the host's 10KB hook cap, recall yields —
+    // the capture worklist must arrive whole.
+    if (pending) {
+      block = pending.length + block.length > 9500 || !block
+        ? pending
+        : `${pending}\n\n---\n\n${block}`;
+    }
+    if (!block) process.exit(0);
+
     // Arm the PostToolUse nudge detectors (nudge-handler.mjs gates its spiral
     // detectors on seen_find so it never nags sessions that don't use coldstart).
     // An injected session IS coldstart-aware even if it never runs `find` — the
@@ -130,7 +157,6 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
     // grep-spiral unguarded otherwise. Path/shape must match the handler's state
     // file: literal /tmp + main-agent key = session_id.
     try {
-      const sid = String(input.session_id || "");
       if (sid && /^[\w-]+$/.test(sid)) {
         const sf = `/tmp/find_nudge_${sid}.json`;
         let st = {};
@@ -140,7 +166,7 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
       }
     } catch { /* fail-open: arming is best-effort */ }
 
-    log(`INJECT bytes=${block.length}`);
+    log(`INJECT bytes=${block.length} pending=${pending ? "yes" : "no"}`);
     process.stdout.write(JSON.stringify({
       hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: block },
     }));