@jeffober/thatch 0.1.21 → 0.1.24

package/src/extraction.ts

@@ -91,6 +91,7 @@ export function buildExtractionPayload(
  */
 export class ExtractionPipeline {
   #buffers = new Map<string, ToolInteraction[]>();
+  #accepted = new Map<string, ToolInteraction[]>();
   #maxBuffer = 20;
 
   /** Record a tool execution for later extraction. */
@@ -110,6 +111,46 @@ export class ExtractionPipeline {
     this.#buffers.delete(sessionID);
   }
 
+  /**
+   * Accept the session's buffer: move it to a holding area so the nudge
+   * stops replaying while a dispatched extractor works. AMQP-style accept —
+   * the entries are not dropped until a completion signal arrives (the
+   * extractor writes a memory, calls extraction_done, or goes idle). If the
+   * extractor dies first, requeueAccepted puts them back.
+   */
+  accept(sessionID: string): void {
+    const buf = this.#buffers.get(sessionID) ?? [];
+    if (buf.length === 0) return;
+    this.#buffers.delete(sessionID);
+    const existing = this.#accepted.get(sessionID) ?? [];
+    this.#accepted.set(sessionID, [...existing, ...buf]);
+  }
+
+  /** Drop accepted entries: the extractor finished (save or no-save). */
+  completeAccepted(sessionID: string): void {
+    this.#accepted.delete(sessionID);
+  }
+
+  /**
+   * Move accepted entries back to pending: the extractor errored or its
+   * session was deleted before completing, so the facts were never
+   * processed. Prepended so they replay in original order. Not capped at
+   * maxBuffer — a silent drop here would defeat the point of requeueing;
+   * the next push trims back to the cap.
+   */
+  requeueAccepted(sessionID: string): void {
+    const accepted = this.#accepted.get(sessionID);
+    if (!accepted || accepted.length === 0) return;
+    this.#accepted.delete(sessionID);
+    const buf = this.#buffers.get(sessionID) ?? [];
+    this.#buffers.set(sessionID, [...accepted, ...buf]);
+  }
+
+  /** Returns the session's accepted (held) interactions. Test/introspection. */
+  peekAccepted(sessionID: string): ToolInteraction[] {
+    return this.#accepted.get(sessionID) ?? [];
+  }
+
   /**
    * Remove entries that were in the snapshot (by reference identity), keeping
    * any that arrived after the snapshot was taken. Used by the child-parent

package/src/index.ts

@@ -10,6 +10,7 @@ import {
   sessionStartReminder,
   recallNudge,
   extractionNudge,
+  extractionDirectPrompt,
   predictionNudge,
   type NudgeMatch,
 } from "./prompts";
@@ -81,6 +82,32 @@ export const server: Plugin = async ({ client, worktree }) => {
   // any tool calls the parent made concurrently with the sub-agent.
   const parentSnapshots = new Map<string, ToolInteraction[]>();
 
+  // Parent sessions with an active direct-extraction child. When the parent
+  // goes idle with pending tool interactions, the plugin creates a child
+  // session and prompts it directly (via the SDK client) instead of injecting
+  // a nudge into the next user message. This set suppresses the nudge path
+  // while the child runs, and prevents re-triggering if the parent goes idle
+  // again before the child finishes. Cleared when the child goes idle, errors,
+  // or is deleted. If direct extraction fails, the set is cleared so the nudge
+  // path takes over as a fallback on the next chat.message.
+  const extracting = new Set<string>();
+
+  // Child session IDs created by triggerExtraction (direct extraction only).
+  // The child idle handler uses this to distinguish plugin-created extraction
+  // children from task-dispatched sub-agents (code review specialists, the
+  // nudge-path fact-extractor, any model-dispatched task). Only extraction
+  // children get the full cleanup: buffer drain, session deletion, toast.
+  // Non-extraction children get the old behavior (completeAccepted +
+  // missedNudges.reset) so their sessions are not deleted out from under the
+  // task tool that dispatched them.
+  const extractionChildren = new Set<string>();
+
+  // Per-child-session extraction metrics for the toast notification. When the
+  // child session goes idle, these counts are formatted into a toast that
+  // shows the user thatch is working without polluting the conversation.
+  // Keyed by child session ID. Cleaned up on child idle, error, or deletion.
+  const childMetrics = new Map<string, { new: number; updated: number; deleted: number }>();
+
   // Skills always install to the global opencode config — installing into the
   // worktree would mutate the user's repo (untracked files in git status).
   // A failed install degrades the nudge workflow but must not kill the plugin.
@@ -96,6 +123,83 @@ export const server: Plugin = async ({ client, worktree }) => {
   const sys = systemPrompt(repo);
   const compact = compactionContext(repo);
 
+  // Direct extraction: create a child session linked to the parent and prompt
+  // it with the extraction payload. The child runs the fact-extractor skill,
+  // writes memories, and goes idle. The existing childToParent / snapshot
+  // drain machinery handles buffer cleanup. The nudge path is a fallback if
+  // this throws.
+  //
+  // Does NOT call extraction.accept — entries stay in pending so consumeSnapshot
+  // can drain them by reference identity when the child writes a memory. The
+  // extracting set (not accept) suppresses the nudge in chat.message.
+  //
+  // The child ID is added to extractionChildren so the idle handler can
+  // distinguish plugin-created extraction children from task-dispatched
+  // sub-agents. Only extraction children get the full cleanup (buffer drain,
+  // session deletion, toast).
+  async function triggerExtraction(parentID: string): Promise<void> {
+    extracting.add(parentID);
+
+    const batch = extraction.peek(parentID);
+    const payload = extraction.buildPayload(batch, repo);
+    const promptText = extractionDirectPrompt(batch.length, payload);
+
+    const result = await client.session.create({
+      body: { parentID, title: "thatch-extraction" },
+    });
+    // session.created event fires here, setting childToParent and
+    // parentSnapshots (snapshot of the full pending buffer, since we
+    // have not called accept).
+    const childId = result.data!.id;
+    extractionChildren.add(childId);
+
+    // Clean up the child session and all map entries if prompting fails.
+    // Without this, the child exists on the server but was never prompted,
+    // so it never goes idle and the maps leak.
+    const cleanupChild = () => {
+      extracting.delete(parentID);
+      extractionChildren.delete(childId);
+      childToParent.delete(childId);
+      parentSnapshots.delete(childId);
+      childMetrics.delete(childId);
+      try { client.session.delete({ path: { id: childId } }); } catch {}
+    };
+
+    const bgEnabled =
+      process.env.OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS === "true" ||
+      process.env.OPENCODE_EXPERIMENTAL === "true";
+
+    if (bgEnabled) {
+      try {
+        await client.session.promptAsync({
+          path: { id: childId },
+          body: {
+            parts: [{ type: "text", text: promptText }],
+          },
+        });
+      } catch (err) {
+        console.error(`[thatch] extraction promptAsync failed: ${err}`);
+        cleanupChild();
+        throw err;
+      }
+    } else {
+      // Fire and forget — the parent is already idle, so blocking the event
+      // handler would only delay other event processing. The child runs to
+      // completion and its idle event triggers cleanup.
+      client.session
+        .prompt({
+          path: { id: childId },
+          body: {
+            parts: [{ type: "text", text: promptText }],
+          },
+        })
+        .catch((err: unknown) => {
+          console.error(`[thatch] extraction child failed: ${err}`);
+          cleanupChild();
+        });
+    }
+  }
+
   return {
     tool: createTools(db, model, repo),
 
@@ -118,57 +222,92 @@ export const server: Plugin = async ({ client, worktree }) => {
       compacting.delete(input.sessionID);
     },
 
-    // 3. Tool buffering — feeds the extraction nudge. Excluded tools:
+    // 3. Tool buffering — feeds the extraction pipeline (direct extraction
+    //    via SDK or nudge fallback). Excluded tools:
     //    - thatch_*: extracting facts from memory ops would echo the store
     //    - skill/task: meta-tools that orchestrate agent behavior (loading
     //      skills, dispatching sub-agents). Buffering them creates a feedback
-    //      loop — the nudge triggers a skill load, which gets buffered, which
-    //      triggers another nudge on the next turn.
+    //      loop — extraction triggers a skill load, which gets buffered, which
+    //      triggers another extraction on the next turn.
     //    Memory writes consume the buffer and reset the missed-nudge counter.
     //    The buffer is NOT drained on nudge delivery — it persists until the
     //    agent writes a memory, so ignored nudges accumulate and the payload
     //    grows with each missed cycle.
     //
-    //    A memory_remember call in a child session (sub-agent) also drains
-    //    the parent's buffer — but only the entries that existed at dispatch
-    //    time (the snapshot). Entries from interleaved turns survive so their
-    //    facts aren't silently dropped. Without this, dispatching the
-    //    fact-extractor as a background task writes memories in the child but
-    //    never clears the parent's queue — the nudge replays every turn.
+    //    Buffer lifecycle is AMQP-style accept/complete, so a failed
+    //    extractor does not silently drop unprocessed interactions:
+    //    - thatch_extraction_done in the parent ACCEPTS the buffer: it moves
+    //      to a holding area and the nudge quiets, but entries are not
+    //      dropped yet.
+    //    - COMPLETE drops the held entries. Signals: a memory_remember or
+    //      extraction_done call in a child session of that parent (the
+    //      extractor confirming it processed them), or the child going idle
+    //      (a no-save run that never acks still counts as processed).
+    //    - REQUEUE returns the held entries to pending. Signals: the child
+    //      session errors or is deleted before completing.
     //
-    //    thatch_extraction_done is an explicit acknowledgment tool the model
-    //    calls in the parent session after dispatching. Covers the case where
-    //    the sub-agent errors out or the host doesn't expose parent-child
-    //    session relationships.
+    //    A memory_remember call in a child session (sub-agent) also drains
+    //    the parent's pending buffer — but only the entries that existed at
+    //    dispatch time (the snapshot). Entries from interleaved turns survive
+    //    so their facts aren't silently dropped.
     "tool.execute.after": async (input, output) => {
       if (input.tool === "thatch_memory_remember") {
         extraction.consume(input.sessionID);
         missedNudges.delete(input.sessionID);
-        // If this is a child session, drain only the parent's snapshot entries
-        // (those present at dispatch time). Interleaved-turn entries survive.
-        // If no snapshot was recorded (e.g. session.created event never
-        // arrived), fall back to draining the entire parent buffer.
+        // Track extraction metrics for toast display. Counted for any
+        // child session (both direct-extraction and nudge-path sub-agents)
+        // since childToParent covers both. The toast only fires for
+        // extraction children (extractionChildren set) on idle.
         const parentID = childToParent.get(input.sessionID);
         if (parentID) {
+          const metrics = childMetrics.get(input.sessionID) ?? { new: 0, updated: 0, deleted: 0 };
+          if (input.args?.overwrite) metrics.updated++;
+          else metrics.new++;
+          childMetrics.set(input.sessionID, metrics);
+          // Complete the parent's accepted entries (the extractor confirmed
+          // it is alive and saving) and drain the parent's snapshot entries
+          // from the pending buffer. If no snapshot was recorded (unreachable
+          // when childToParent has the entry, since both are set together in
+          // session.created), skip the drain rather than dropping the entire
+          // buffer — interleaved-turn entries that arrived while the child
+          // was running must survive for the next extraction cycle.
+          extraction.completeAccepted(parentID);
           const snapshot = parentSnapshots.get(input.sessionID);
           if (snapshot) {
             extraction.consumeSnapshot(parentID, snapshot);
             parentSnapshots.delete(input.sessionID);
-          } else {
-            extraction.consume(parentID);
           }
           missedNudges.delete(parentID);
         }
         return;
       }
-      // Explicit acknowledgment tool drains the buffer without requiring a
-      // memory write. The model calls this after dispatching the
-      // fact-extractor to a sub-agent.
+      // thatch_extraction_done has two roles depending on the session:
+      // - parent, after dispatching the fact-extractor: ACCEPT the buffer
+      //   (quiet the nudge, hold the entries for completion).
+      // - child extractor, at the end of its run: COMPLETE the parent's
+      //   accepted entries, including no-save runs that write no memory,
+      //   and drop the child's own buffer (its work is done).
       if (input.tool === "thatch_extraction_done") {
-        extraction.consume(input.sessionID);
+        const parentID = childToParent.get(input.sessionID);
+        if (parentID) {
+          extraction.completeAccepted(parentID);
+          missedNudges.delete(parentID);
+          extraction.consume(input.sessionID);
+        } else {
+          extraction.accept(input.sessionID);
+        }
         missedNudges.delete(input.sessionID);
         return;
       }
+      // Track memory deletions in child sessions for the toast metrics.
+      // Same scoping as the remember handler above — only child sessions,
+      // not the parent or manual memory writes from the user's session.
+      if (input.tool === "thatch_memory_forget" && childToParent.has(input.sessionID)) {
+        const metrics = childMetrics.get(input.sessionID) ?? { new: 0, updated: 0, deleted: 0 };
+        metrics.deleted++;
+        childMetrics.set(input.sessionID, metrics);
+        return;
+      }
       if (input.tool.startsWith("thatch_") || input.tool === "skill" || input.tool === "task") return;
       extraction.push({
         tool: input.tool,
@@ -207,7 +346,11 @@ export const server: Plugin = async ({ client, worktree }) => {
         if (isCompactionMsg) return;
         compacting.delete(input.sessionID);
       }
-      if (extraction.pending(input.sessionID)) {
+      // Extraction nudge (fallback path). Skipped when the extracting set
+      // is active — that means a direct-extraction child session is running
+      // and the plugin is handling extraction via the SDK. The nudge fires
+      // here only when direct extraction was never triggered or threw.
+      if (!extracting.has(input.sessionID) && extraction.pending(input.sessionID)) {
         const batch = extraction.peek(input.sessionID);
         const payload = extraction.buildPayload(batch, repo);
         const missed = missedNudges.get(input.sessionID) ?? 0;
@@ -255,6 +398,17 @@ export const server: Plugin = async ({ client, worktree }) => {
               text: recallNudge(matches),
               synthetic: true,
             });
+            try {
+              await client.tui.showToast({
+                body: {
+                  message: `\u{1F4AD} recalled ${matches.length} memor${matches.length === 1 ? "y" : "ies"}`,
+                  variant: "info",
+                  duration: 3000,
+                },
+              });
+            } catch {
+              // TUI may not be connected. Best-effort.
+            }
           }
         } catch (err) {
           console.error(`[thatch] recall nudge failed: ${err}`);
@@ -273,6 +427,17 @@ export const server: Plugin = async ({ client, worktree }) => {
               text: predictionNudge(predItems),
               synthetic: true,
             });
+            try {
+              await client.tui.showToast({
+                body: {
+                  message: `\u{1F4AD} ${predItems.length} prediction${predItems.length === 1 ? "" : "s"} surfaced`,
+                  variant: "info",
+                  duration: 3000,
+                },
+              });
+            } catch {
+              // TUI may not be connected. Best-effort.
+            }
           }
         } catch (err) {
           console.error(`[thatch] prediction nudge failed: ${err}`);
@@ -283,25 +448,148 @@ export const server: Plugin = async ({ client, worktree }) => {
     },
 
     // 5. Session-start reminder, carrying the hygiene heartbeat. Hygiene is
-    // best-effort: a failure there must not cost the reminder itself.
+    //    best-effort: a failure there must not cost the reminder itself.
     //
     // Also tracks parent-child session relationships for cross-session buffer
     // drain. session.created with a parentID records the mapping AND
-    // snapshots the parent's current buffer — so the child's later
+    // snapshots the parent's current buffer so the child's later
     // memory_remember drains only those snapshot entries, not the parent's
     // entire buffer (which may have grown from interleaved turns).
-    // session.deleted cleans both maps to avoid unbounded growth.
+    //
+    // Child lifecycle events: idle means the extractor finished; error or
+    // deletion before completion means the facts were never extracted, so
+    // entries go back to pending. Only extraction children (created by
+    // triggerExtraction, tracked in extractionChildren) get the full cleanup
+    // (buffer drain, session deletion, toast). Task-dispatched sub-agents
+    // get the old behavior (completeAccepted + missedNudges.reset) so their
+    // sessions are not deleted out from under the task tool.
     event: async ({ event }) => {
       if (event.type === "session.created") {
         const info = event.properties.info;
         if (info.parentID) {
           childToParent.set(info.id, info.parentID);
           parentSnapshots.set(info.id, [...extraction.peek(info.parentID)]);
+          // Child sessions don't need the session-start reminder — only
+          // top-level sessions do. Returning here prevents extraction
+          // children from receiving the hygiene report and tool overview.
+          return;
+        }
+      }
+      if (event.type === "session.error") {
+        const childID = event.properties.sessionID;
+        const parentID = childID ? childToParent.get(childID) : undefined;
+        if (parentID && childID) {
+          extraction.requeueAccepted(parentID);
+          extracting.delete(parentID);
+          childToParent.delete(childID);
+          parentSnapshots.delete(childID);
+          childMetrics.delete(childID);
+          extractionChildren.delete(childID);
+        }
+        return;
+      }
+      if (event.type === "session.status" && event.properties.status?.type === "idle") {
+        const sessionID = event.properties.sessionID;
+        const parentID = sessionID ? childToParent.get(sessionID) : undefined;
+        if (parentID && sessionID) {
+          // A child session went idle. Two cases:
+          // - Extraction child (created by triggerExtraction, tracked in
+          //   extractionChildren): drain the parent's snapshot, fire a toast
+          //   with metrics, delete the child session, clean up all maps.
+          // - Task-dispatched sub-agent (code review specialist, nudge-path
+          //   fact-extractor, any model-dispatched task): complete the
+          //   parent's accepted entries and reset missedNudges. Do NOT drain
+          //   the buffer or delete the session — the task tool that
+          //   dispatched the sub-agent needs to read its output.
+          if (extractionChildren.has(sessionID)) {
+            // Drain the parent's snapshot entries from the pending buffer.
+            // If the child wrote memories, consumeSnapshot already ran in
+            // tool.execute.after and the snapshot is gone — nothing to
+            // drain. If the child did a no-save run, the snapshot entries
+            // are still in the buffer and need to be drained here so they
+            // don't replay as a nudge on the next chat.message. Never drain
+            // the entire buffer — interleaved-turn entries must survive.
+            const snapshot = parentSnapshots.get(sessionID);
+            if (snapshot) {
+              extraction.consumeSnapshot(parentID, snapshot);
+            }
+
+            // Fire a toast with the extraction metrics. Only show a toast
+            // when memories were actually written — no toast for no-save
+            // runs to avoid notification fatigue.
+            const metrics = childMetrics.get(sessionID);
+            const parts: string[] = [];
+            if (metrics) {
+              if (metrics.new > 0) parts.push(`new: ${metrics.new}`);
+              if (metrics.updated > 0) parts.push(`updated: ${metrics.updated}`);
+              if (metrics.deleted > 0) parts.push(`deleted: ${metrics.deleted}`);
+            }
+            if (parts.length > 0) {
+              try {
+                await client.tui.showToast({
+                  body: { message: `\u{1F4AD} ${parts.join(", ")}`, variant: "success", duration: 4000 },
+                });
+              } catch {
+                // TUI may not be connected (e.g. headless mode).
+              }
+            }
+
+            extraction.completeAccepted(parentID);
+            missedNudges.delete(parentID);
+            extracting.delete(parentID);
+            childToParent.delete(sessionID);
+            parentSnapshots.delete(sessionID);
+            childMetrics.delete(sessionID);
+            extractionChildren.delete(sessionID);
+            extraction.consume(sessionID);
+            // Delete the child session to avoid clutter.
+            try {
+              await client.session.delete({ path: { id: sessionID } });
+            } catch {
+              // Best-effort — the child is idle and harmless if not deleted.
+            }
+          } else {
+            // Task-dispatched sub-agent went idle. Complete the parent's
+            // accepted entries (from the nudge-path extraction_done accept)
+            // and reset missedNudges. Retained for the nudge fallback path.
+            extraction.completeAccepted(parentID);
+            missedNudges.delete(parentID);
+          }
+          return;
         }
+        // Parent went idle — trigger direct extraction if there are pending
+        // tool interactions and no extraction is already running. Falls
+        // back to the nudge path on the next chat.message if this throws.
+        if (
+          sessionID &&
+          !compacting.has(sessionID) &&
+          !extracting.has(sessionID) &&
+          extraction.pending(sessionID)
+        ) {
+          try {
+            await triggerExtraction(sessionID);
+          } catch (err) {
+            console.error(`[thatch] direct extraction trigger failed: ${err}`);
+            extracting.delete(sessionID);
+          }
+        }
+        return;
       }
       if (event.type === "session.deleted") {
-        childToParent.delete(event.properties.info.id);
-        parentSnapshots.delete(event.properties.info.id);
+        const id = event.properties.info.id;
+        // A child deleted before completing never processed its payload.
+        const parentID = childToParent.get(id);
+        if (parentID) {
+          extraction.requeueAccepted(parentID);
+          extracting.delete(parentID);
+        }
+        childToParent.delete(id);
+        parentSnapshots.delete(id);
+        childMetrics.delete(id);
+        extractionChildren.delete(id);
+        // A deleted parent takes its accepted entries with it.
+        extraction.completeAccepted(id);
+        extracting.delete(id);
         return;
       }
 

package/src/prompts.ts

@@ -37,7 +37,7 @@ you're working in. Prior sessions may have already investigated it.
 Thatch ships skills for code review, project investigation, and memory
 workflows. The host auto-discovers them, but reach for them proactively:
 
-- \`thatch-code-review\` — full multi-agent code review (dispatches 6 specialists + synthesizer). Requires sub-agent support.
+- \`thatch-code-review\` — full multi-agent code review (dispatches 7 specialists + synthesizer). Requires sub-agent support.
 - \`thatch-workflow-research\` — research code workflows affected by a change or planned change, before reviewing or planning.
 - \`thatch-change-walkthrough\` — produces a teaching walkthrough of a diff with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + change overlay mirroring the same numbers) and calibrated prose rules. Load the skill for the format and prose rules, not just for the research method.
 - \`thatch-code-walkthrough\` — produces a teaching walkthrough for a feature/workflow as it stands today with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + Key files) and calibrated prose rules. Also use proactively to draft high-level docs for new or undocumented features (suitable for pkg/README.md or docs/features/<name>.md). Load the skill for the format and prose rules, not just for the research method.
@@ -76,6 +76,11 @@ that thread. If the user's last message has been fully addressed, stop and
 wait. Do not treat the completion as a trigger to advance work the user has
 not greenlit.
 
+If a background task was cancelled after timing out, re-dispatch it once with
+the same prompt. If the re-dispatch also fails or times out, note the gap and
+move on. Do not retry more than once — repeated failures indicate an
+intractable prompt, not a transient hang.
+
 ## User Decision Model
 
 A statistical model of the user's decision-making preferences is maintained by
@@ -238,7 +243,7 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-change-walkthrough\` — produces a teaching walkthrough of a diff with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + change overlay mirroring the same numbers) and calibrated prose rules. Load the skill for the format and prose rules, not just for the research method.
 - \`thatch-code-walkthrough\` — produces a teaching walkthrough for a feature/workflow as it stands today with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + Key files) and calibrated prose rules. Also use proactively to draft high-level docs for new or undocumented features (suitable for pkg/README.md or docs/features/<name>.md). Load the skill for the format and prose rules, not just for the research method.
 - \`thatch-review-context\` — gather project context (PRs, tickets, TODOs, deferred work) before a review.
-- \`thatch-review-pedantic\` / \`-acceptance\` / \`-state-flow\` / \`-no-slop\` / \`-breadcrumbs\` / \`-mark-and-sweep\` — six specialist review lenses. Run individually, then \`thatch-review-synthesizer\` to verify and aggregate.
+- \`thatch-review-pedantic\` / \`-acceptance\` / \`-state-flow\` / \`-no-slop\` / \`-breadcrumbs\` / \`-mark-and-sweep\` / \`-highlights\` — seven specialist review lenses. Run individually, then \`thatch-review-synthesizer\` to verify and aggregate.
 - \`thatch-project-primer\` — investigate a new project and write foundational memories.
 - \`thatch-session-reflection\` — record what you learned at end of session.
 - \`thatch-fact-extractor\` — extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).
@@ -426,10 +431,29 @@ export function extractionNudge(
   return `[thatch] ${dispatch} to run the thatch-fact-extractor skill ` +
     `on ${count} queued tool interaction${plural}. ` +
     `${acknowledge} ` +
-    `Then answer the user. ` +
+    `This is a system nudge, not user input. After dispatching and acknowledging, ` +
+    `stop: do not advance pending work on this nudge's account. If you are ` +
+    `waiting for the user to respond, continue waiting. ` +
     `Use ${toolName} to save durable facts from this payload:\n${payload}`;
 }
 
+/**
+ * Prompt text sent directly to a child session the plugin created for
+ * extraction. Unlike extractionNudge (which tells the model to dispatch a
+ * sub-agent and call extraction_done), this prompt is already inside the
+ * child — the model just runs the fact-extractor skill and saves facts.
+ * The payload format is identical to the nudge path so the skill receives
+ * the same contract either way.
+ */
+export function extractionDirectPrompt(count: number, payload: string): string {
+  const plural = count === 1 ? "" : "s";
+  return `Run the thatch-fact-extractor skill to extract durable facts from ` +
+    `${count} queued tool interaction${plural}. ` +
+    `Use thatch_memory_remember to save any durable facts you find. ` +
+    `Call thatch_extraction_done when finished, even if nothing was worth saving.\n` +
+    `Payload:\n${payload}`;
+}
+
 /**
  * Backwards-compatible wrapper for the Claude Code/Cursor CLI path.
  * Maintained for any external callers; bin/thatch should use extractionNudge
@@ -487,7 +511,7 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-change-walkthrough\` — produces a teaching walkthrough of a diff with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + change overlay mirroring the same numbers) and calibrated prose rules. Load the skill for the format and prose rules, not just for the research method.
 - \`thatch-code-walkthrough\` — produces a teaching walkthrough for a feature/workflow as it stands today with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + Key files) and calibrated prose rules. Also use proactively to draft high-level docs for new or undocumented features (suitable for pkg/README.md or docs/features/<name>.md). Load the skill for the format and prose rules, not just for the research method.
 - \`thatch-review-context\` — gather project context (PRs, tickets, TODOs, deferred work) before a review.
-- \`thatch-review-pedantic\` / \`-acceptance\` / \`-state-flow\` / \`-no-slop\` / \`-breadcrumbs\` / \`-mark-and-sweep\` — six specialist review lenses. Run individually, then \`thatch-review-synthesizer\` to verify and aggregate.
+- \`thatch-review-pedantic\` / \`-acceptance\` / \`-state-flow\` / \`-no-slop\` / \`-breadcrumbs\` / \`-mark-and-sweep\` / \`-highlights\` — seven specialist review lenses. Run individually, then \`thatch-review-synthesizer\` to verify and aggregate.
 - \`thatch-project-primer\` — investigate a new project and write foundational memories.
 - \`thatch-session-reflection\` — record what you learned at end of session.
 - \`thatch-fact-extractor\` — extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).

package/src/skills.ts

@@ -39,6 +39,7 @@ function loadSharedSkills(): SkillDef[] {
     "thatch-review-no-slop",
     "thatch-review-breadcrumbs",
     "thatch-review-mark-and-sweep",
+    "thatch-review-highlights",
     "thatch-review-synthesizer",
     "thatch-review-context",
     "thatch-workflow-research",

package/src/tool-defs.ts

@@ -352,29 +352,35 @@ const markCheckedDef: ToolDef = {
 };
 
 /**
- * Acknowledge that the extraction nudge has been handled. Drains the
- * extraction buffer so the nudge does not replay on the next turn.
+ * Extraction-buffer acknowledgment, with AMQP-style accept/complete roles.
  *
- * The actual draining happens in the host's post-tool hook
+ * Called in a PARENT session after dispatching the fact-extractor, it accepts
+ * the buffer: entries move to a holding area and the nudge quiets, but they
+ * are not dropped until the extractor completes. Called in a CHILD extractor
+ * at the end of its run, it completes the parent's accepted entries —
+ * including no-save runs that write no memory. If the child errors or is
+ * deleted before either signal, the host requeues the entries so the facts
+ * are not lost.
+ *
+ * The actual state changes happen in the host's post-tool hook
  * (tool.execute.after for opencode, PostToolBatch/appendBatch for MCP) —
  * this tool's execute function is a no-op confirmation. The tool exists so
- * the model can call it in the parent session after dispatching the
- * fact-extractor to a sub-agent, giving the hook a recognizable tool name
- * to key on. Without it, the buffer only drains when a memory_remember
- * call lands in the same session (or a tracked child session), which fails
- * if the sub-agent errors out or the host doesn't expose parent-child
- * session relationships.
+ * the model has a recognizable tool name to key on. In the MCP path the
+ * file-backed queue is consumed on this call (or on any memory_remember),
+ * which is durable across interruption because the queue persists on disk
+ * until then.
  */
 const extractionDoneDef: ToolDef = {
   name: "extraction_done",
   description:
-    "Acknowledge that the extraction nudge has been dispatched to a sub-agent. " +
-    "Drains the extraction buffer so the nudge does not replay. " +
-    "Call this in the parent session after dispatching a background task " +
-    "to run the thatch-fact-extractor skill.",
+    "Acknowledge extraction-buffer work. In a parent session, call after " +
+    "dispatching the fact-extractor to a sub-agent: accepts the buffer " +
+    "(quiets the nudge) while keeping entries until the extractor completes. " +
+    "In the fact-extractor sub-agent, call at the end of the run to mark the " +
+    "entries complete, even when nothing was worth saving.",
   args: {},
   async execute() {
-    return "[acknowledged] extraction buffer drained";
+    return "[acknowledged]";
   },
 };