@jeffober/thatch 0.1.22 → 0.1.25

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,12 +222,13 @@ 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
@@ -149,20 +254,28 @@ export const server: Plugin = async ({ client, worktree }) => {
       if (input.tool === "thatch_memory_remember") {
         extraction.consume(input.sessionID);
         missedNudges.delete(input.sessionID);
-        // If this is a child session, 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 (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);
         }
@@ -186,6 +299,15 @@ export const server: Plugin = async ({ client, worktree }) => {
         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,
@@ -224,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;
@@ -272,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}`);
@@ -290,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}`);
@@ -300,40 +448,130 @@ 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).
     //
-    // The accepted-buffer lifecycle completes or requeues on child lifecycle
-    // events: idle means the extractor finished (a no-save run writes no
-    // memory but still processed the payload); error or deletion before
-    // completion means the facts were never extracted, so the entries go
-    // back to pending. session.deleted also 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) extraction.requeueAccepted(parentID);
+        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 childID = event.properties.sessionID;
-        const parentID = childID ? childToParent.get(childID) : undefined;
-        if (parentID) {
-          extraction.completeAccepted(parentID);
-          missedNudges.delete(parentID);
+        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;
       }
@@ -341,11 +579,17 @@ export const server: Plugin = async ({ client, worktree }) => {
         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);
+        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).
@@ -432,6 +437,23 @@ export function extractionNudge(
     `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
@@ -489,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",