@jeffober/thatch 0.1.21 → 0.1.24

package/docs/dev/README.md

@@ -54,7 +54,7 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `tool-defs.ts` | **Single source of truth** for all tools. Each tool has a name, description, zod schema (args), and execute function. Framework-agnostic — neither opencode nor MCP specific. |
 | `tools.ts` | Thin opencode wrappers. Imports tool-defs, wraps each in opencode's `tool()` with a `thatch_` prefix. |
 | `mcp.ts` | Stdio JSON-RPC 2.0 server. Compiles zod schemas to JSON Schema via `z.toJSONSchema()` for `tools/list`. Validates args via `z.object().parse()` in `tools/call`. All logging to stderr (stdout is the transport). |
-| `index.ts` | OpenCode plugin entry. Wires DB, model, extraction; registers tools and hooks; installs skills. |
+| `index.ts` | OpenCode plugin entry. Wires DB, model, extraction; registers tools and hooks; installs skills. Internal state beyond the extraction pipeline: `extracting` set (parent IDs with an active direct-extraction child), `childMetrics` map (new/updated/deleted counts per child session), and `triggerExtraction(parentID)` (creates a child session via the SDK client and prompts it with the extraction payload). |
 | `setup.ts` | `thatch setup --claude` installer. Writes .mcp.json, appends to CLAUDE.md (idempotent), installs hooks in settings.json, installs skills. |
 | `hygiene.ts` | Hygiene report: pending dedup pairs, stale count, orphaned branch memories. Shared by the plugin's session-start hook and the CLI's `thatch reminder` command. |
 | `git.ts` | Parse `owner/repo` from git remote. Worktree-safe fallback chain. |
@@ -64,7 +64,7 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `extract-queue.ts` | File-backed per-session JSONL queue (caps 20, oldest dropped). Shared by the Claude Code and Cursor hook paths, which fire one-shot per event with no cross-call state. This is the MCP-side equivalent of `extraction.ts`. |
 | `sideband.ts` | Unix domain socket server + client. The MCP server (long-lived, warm model) runs `SidebandServer` so one-shot hook processes can ask it to embed a prompt and search for matches without loading the model themselves. Handles two methods: `match` (recall nudge) and `predictions` (prediction auto-fire). Socket path is a hash of the DB path — both processes compute it independently. |
 | `prompts.ts` | Text constants: opencode system prompt, compaction context, session-start reminder, prompt-aware recall nudge (`recallNudge` / `claudeRecallNudge`), Claude Code CLAUDE.md instructions, Cursor AGENTS.md instructions, Claude Code hook text. |
-| `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (18 skills: fact-extractor, dedup-classifier, project-primer, 6 review specialists, review synthesizer, review context, workflow research, change walkthrough, code walkthrough, session reflection, pr-description, ticket-description, split-overlarge-pr — work on both opencode and Claude Code) and `OPENCODE_ONLY_SKILLS` (1 skill: code-review coordinator — requires sub-agent support, not installed for Claude Code). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
+| `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (19 skills: fact-extractor, dedup-classifier, project-primer, 7 review specialists, review synthesizer, review context, workflow research, change walkthrough, code walkthrough, session reflection, pr-description, ticket-description, split-overlarge-pr — work on both opencode and Claude Code) and `OPENCODE_ONLY_SKILLS` (1 skill: code-review coordinator — requires sub-agent support, not installed for Claude Code). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
 
 ## Plugin hooks
 
@@ -75,9 +75,9 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `experimental.chat.system.transform` | Appends the thatch system prompt (store names, usage rules). |
 | `experimental.session.compacting` | Marks the session as compacting and appends re-familiarization context so a compacted session still knows thatch exists. |
 | `experimental.compaction.autocontinue` | Clears the compacting flag so `chat.message` nudges resume. Without this, nudges that instruct tool calls would fire during summary generation where tools are blocked. The `chat.message` hook also clears the flag if it fires for a session still in the compacting set but the incoming message has no compaction-type part — this handles compaction failure, where the session would otherwise be stuck with nudges off forever. |
-| `tool.execute.after` | Buffers every non-`thatch_*`, non-`skill`, non-`task` tool call into the session's extraction buffer. (Skill/task are excluded — buffering them creates a feedback loop where the nudge triggers a skill load, which gets buffered, which triggers another nudge.) Memory writes (`thatch_memory_remember`) and `thatch_extraction_done` drain the buffer and reset the missed-nudge counter. This is a plugin hook, NOT a bus event — do not move it into the `event` handler; the event bus has no such event and it will silently never fire. |
-| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions, **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge + JSON payload — the buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (b) otherwise, embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). The same embedding also feeds the prediction auto-fire: `db.scorePredictionNudge` scores the prompt against prediction matchers and injects a separate `[thatch] User decision model` nudge if any matchers clear the 0.45 threshold. Recall and prediction nudges fire independently (separate try/catch blocks, separate synthetic parts). Skipped entirely while the session is compacting (tool calls are blocked during summary generation). |
-| `event` (`session.created`) | Sends the session-start reminder via `client.session.prompt`, carrying the hygiene heartbeat (pending dedup pairs, stale count, orphaned branch memories) when any signal is non-zero. The session id is at `event.properties.info.id`. |
+| `tool.execute.after` | Buffers every non-`thatch_*`, non-`skill`, non-`task` tool call into the session's extraction buffer. (Skill/task are excluded — buffering them creates a feedback loop where the nudge triggers a skill load, which gets buffered, which triggers another nudge.) Memory writes (`thatch_memory_remember`) and `thatch_extraction_done` drain the buffer and reset the missed-nudge counter. For child sessions (`childToParent.has(sessionID)`), also tracks metrics: `remember` with `overwrite:false` → new++, `overwrite:true` → updated++, `forget` → deleted++. This is a plugin hook, NOT a bus event — do not move it into the `event` handler; the event bus has no such event and it will silently never fire. |
+| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions and the session is NOT in the `extracting` set (direct extraction in progress), **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge + JSON payload — the buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (b) otherwise, embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). The same embedding also feeds the prediction auto-fire: `db.scorePredictionNudge` scores the prompt against prediction matchers and injects a separate `[thatch] User decision model` nudge if any matchers clear the 0.45 threshold. Recall and prediction nudges fire independently (separate try/catch blocks, separate synthetic parts). Skipped entirely while the session is compacting (tool calls are blocked during summary generation). |
+| `event` | Subscribes to all session bus events. `session.created`: records `childToParent` + `parentSnapshots` (shallow copy of the parent's buffer for snapshot-aware drain), then sends the session-start reminder via `client.session.prompt` carrying the hygiene heartbeat (pending dedup pairs, stale count, orphaned branch memories) when any signal is non-zero. `session.status` (idle): if the session is a child, drains its snapshot, fires a toast with `childMetrics`, and deletes the child session; if the session is a parent with pending tool interactions and not already extracting, calls `triggerExtraction` to create a direct-extraction child. `session.error`: requeues the parent's buffer (child died without draining). `session.deleted`: cleans up `childToParent`, `parentSnapshots`, `childMetrics`, and `extracting`. `session.compacted`: clears the compacting flag so `chat.message` nudges resume. |
 | `dispose` | Closes the DB. |
 
 Hook failures are logged with a `[thatch]` prefix — never swallowed silently.
@@ -168,16 +168,45 @@ dedup cycle (agent-driven)
   → thatch_dedup_mark_checked records verdicts for surviving pairs
   (overwriting or forgetting an entry clears its verdicts → can re-flag)
 
-extraction cycle (agent-driven)
+extraction cycle
   → tool.execute.after buffers non-thatch, non-skill, non-task tool calls
-    per session (max 20)
-  → next chat.message peeks the buffer (does NOT drain it) and injects a
-    nudge part with JSON payload; missed nudges escalate (polite → insistent
-    → ALL-CAPS) via the missedNudges counter
-  → drain: thatch_memory_remember in the session (or a child sub-agent via
-    the childToParent Map) OR thatch_extraction_done — both clear the buffer
-    and reset the missed-nudge counter
-  → agent loads thatch-fact-extractor skill, saves facts via thatch_memory_remember
+    per session (max 20); for child sessions, also tracks new/updated/deleted
+    metrics
+  → direct extraction (primary path, opencode-only):
+    parent goes idle (session.status idle) with pending tool interactions
+    → triggerExtraction adds parentID to the `extracting` set (suppresses
+      nudge in chat.message), creates a child session via
+      client.session.create, and prompts it with the extraction payload
+    → child runs the fact-extractor skill, writes memories via
+      thatch_memory_remember → consumeSnapshot drains the parent's buffer
+      (snapshot-aware: removes only entries captured at dispatch time by
+      reference identity, preserving interleaved-turn entries)
+    → child goes idle → event handler drains remaining snapshot entries,
+      fires a toast with childMetrics, deletes the child session
+  → nudge path (fallback): if triggerExtraction throws (create or prompt
+    fails), the `extracting` set clears and the next chat.message sees
+    pending entries with no extracting flag → peeks the buffer and injects
+    a nudge part with JSON payload; missed nudges escalate (polite →
+    insistent → ALL-CAPS) via the missedNudges counter
+    → drain: thatch_memory_remember (or thatch_extraction_done) clears the
+      buffer and resets the missed-nudge counter
+    → agent loads thatch-fact-extractor skill, saves facts via
+      thatch_memory_remember
+  → MCP path (Claude Code/Cursor): unchanged — no SDK client, no child
+    sessions; extract-queue.ts + flush-tools drives the nudge via hooks
+
+toast notifications (opencode-only, TUI-rendered)
+  → client.tui.showToast — best-effort, silently ignored if TUI not
+    connected (headless mode); model-invisible (goes to the user only,
+    not the conversation history — the inverse of synthetic nudge parts,
+    which are model-visible but TUI-hidden)
+  → extraction metrics: `[thatch] new: N, updated: M, deleted: K` (success
+    variant, 4s) — fires when an extraction child goes idle; no-save runs
+    show `[thatch] extraction complete — nothing to save` (info variant)
+  → recall matches: `[thatch] recalled N memories` (info variant, 3s) —
+    fires when chat.message matches stored memories
+  → prediction matches: `[thatch] N predictions surfaced` (info variant,
+    3s) — fires when chat.message matches decision-model patterns
 
 prompt-aware recall nudge (both paths)
   → opencode: chat.message hook embeds prompt text with warm in-process model,

package/docs/dev/gotchas.md

@@ -65,15 +65,37 @@ here first. These are the things that have already cost time.
   agent writes a memory or calls `thatch_extraction_done`. Ignored nudges
   accumulate; the `missedNudges` counter escalates the tone (polite at 0-1
   misses, insistent at 2, ALL-CAPS at 3+). The counter resets when the
-  buffer drains.
+  buffer drains. The primary opencode path doesn't use the nudge at all:
+  `triggerExtraction` creates a child session directly, and the `extracting`
+  set suppresses the nudge in `chat.message` while a direct-extraction child
+  is active. The peek-not-drain semantics still hold for the fallback nudge
+  path (MCP hosts and any `triggerExtraction` failure).
 - **A child sub-agent's `thatch_memory_remember` drains the parent's buffer**
   via the `childToParent` Map (`index.ts:65` declaration, `index.ts:131`
-  lookup). Without this, dispatching the fact-extractor as a background task
-  would write memories in the child but never clear the parent's queue — the
-  nudge would replay every turn. `thatch_extraction_done` is the
-  belt-and-suspenders explicit acknowledgment: it drains the buffer without
-  requiring a memory write (covers cases where the sub-agent errors out or the
-  host doesn't expose parent-child session relationships).
+  lookup). Two paths reach this machinery: (a) the **plugin-initiated child
+  session** — `triggerExtraction` calls `client.session.create` with a
+  `parentID`, the primary opencode path; (b) the **agent-initiated background
+  task** — the model dispatches the fact-extractor via the `task` tool after
+  receiving the nudge, the fallback path still used by MCP hosts. Both use
+  the same `childToParent`/`parentSnapshots`/`consumeSnapshot` plumbing.
+  Without this, either path would write memories in the child but never
+  clear the parent's queue — the nudge would replay every turn.
+  `thatch_extraction_done` is the belt-and-suspenders explicit
+  acknowledgment: it drains the buffer without requiring a memory write
+  (covers cases where the sub-agent errors out or the host doesn't expose
+  parent-child session relationships).
+- **The no-save drain runs in the child-idle handler regardless of writes.**
+  When the extraction child goes idle after a no-save run (nothing worth
+  extracting), the parent's snapshot entries must still be drained from the
+  buffer. Without this, entries linger in pending and the nudge fires as a
+  synthetic (TUI-hidden) part on the next `chat.message`. The child-idle
+  handler drains the snapshot only if it still exists (the child wrote no
+  memories). If the child did write memories, `tool.execute.after` already
+  consumed the snapshot — the idle handler skips the drain so interleaved-turn
+  entries survive.
+- **`client.tui.showToast` is best-effort.** The toast call is wrapped in a
+  catch-and-ignore — if the TUI is not connected (headless mode), it silently
+  does nothing. The toast is TUI-rendered (in-app), not an OS notification.
 
 ## Hooks (Claude Code / Cursor)
 

package/docs/dev/mcp-parity.md

@@ -22,7 +22,8 @@ This document maps the feature parity and documents the remaining gaps.
 | **System prompt** (store names, usage rules) | `experimental.chat.system.transform` — dynamic, repo baked in at runtime | CLAUDE.md static text appended by `thatch setup`; repo auto-detected by the MCP server at startup | AGENTS.md static text appended by `thatch setup`; repo auto-detected at startup | **Approximate** — static text persists through compaction, so the agent retains the usage instructions, but the dynamic per-turn refresh is lost |
 | **Session-start reminder** (recall nudge + hygiene heartbeat) | `session.created` event → `client.session.prompt` injects a synthetic message | `SessionStart` hook → `thatch reminder`; stdout becomes context | `sessionStart` hook → `thatch reminder --json`; output is `additional_context` JSON | **Full** |
 | **Compaction context** (re-familiarize after compaction) | `experimental.session.compacting` hook appends context to the compaction output | `PostCompact` hook — side-effects only, **cannot inject context** | No equivalent hook | **Gapped** — see below |
-| **Extraction nudge** (buffer tool calls, inject JSON payload) | `tool.execute.after` buffers non-thatch, non-skill, non-task tool calls in-process; `chat.message` peeks the buffer (does not drain it) and injects a synthetic text part | `PostToolBatch` → `thatch buffer-batch` (file-backed JSONL queue); `UserPromptSubmit` → `thatch flush-tools` peeks the queue and prints the nudge (does not drain — the queue persists until a memory write or `extraction_done`) | `postToolUse` → `thatch buffer-tool` (single-tool, file-backed queue); `beforeSubmitPrompt` → `thatch flush-tools --json` | **Full** (file-backed) — timing differs: the nudge arrives at the **start** of the next turn in Claude Code/Cursor, not at the end of the current one like opencode's `chat.message` |
+| **Extraction** (buffer tool calls, extract durable facts) | `tool.execute.after` buffers non-thatch, non-skill, non-task tool calls in-process; **direct extraction** is the primary path — when the parent session goes idle with pending buffer entries, the plugin creates a child session via the SDK (`client.session.create` with `parentID`) and prompts it with the extraction payload (nudge suppressed via the `extracting` set); the `chat.message` nudge path is a **fallback** used when direct extraction throws | `PostToolBatch` → `thatch buffer-batch` (file-backed JSONL queue); `UserPromptSubmit` → `thatch flush-tools` peeks the queue and prints the nudge (does not drain — the queue persists until a memory write or `extraction_done`) | `postToolUse` → `thatch buffer-tool` (single-tool, file-backed queue); `beforeSubmitPrompt` → `thatch flush-tools --json` | **Partial** — opencode uses direct extraction (parent idle → child session) as the primary path, with the nudge as fallback; MCP hosts are nudge-only. Both paths produce the same JSON shape via `buildExtractionPayload()`. Nudge timing differs: the nudge arrives at the **start** of the next turn in Claude Code/Cursor; opencode's direct extraction fires at **end of turn** (session idle), and the nudge fallback fires at the start of the next turn like MCP |
+| **Extraction feedback** (toast notifications) | `client.tui.showToast` fires when the extraction child goes idle — shows `[thatch] new: N, updated: M, deleted: K` (success) or `extraction complete — nothing to save` (info); best-effort, silently ignored in headless mode | No TUI connection — MCP hosts have no equivalent | No TUI connection | **Gapped** — MCP hosts cannot show toast notifications |
 | **Prompt-aware recall nudge** | `chat.message` hook embeds the prompt with the in-process warm model, searches `db.search()`, pushes a nudge part if matches ≥ threshold | `UserPromptSubmit` hook → `thatch flush-tools` connects to the MCP server's sideband socket; the warm server embeds + searches; hook prints the nudge or falls back to the write nudge | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — sideband socket gives cold hook processes access to the warm MCP server's model |
 | **Prediction auto-fire** (user decision model) | `chat.message` hook scores the prompt embedding against prediction matchers; injects a `[thatch] User decision model` nudge alongside the recall nudge (separate synthetic part, same embedding call) | `UserPromptSubmit` hook → `thatch flush-tools` fires prediction query via the sideband socket's `predictions` method in parallel with the recall nudge | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — same `scorePredictionNudge` entry point in both paths |
 | **Skills** | Installed to `$XDG_CONFIG_HOME/opencode/skills` at plugin init (shared **+** opencode-only) | Installed to `$CLAUDE_CONFIG_DIR/skills/` by `thatch setup` (shared only) | Installed to `~/.cursor/skills/` by `thatch setup` (shared only) | **Full** — same SKILL.md format; the code-review coordinator is opencode-only (needs sub-agents) |
@@ -61,18 +62,37 @@ through compaction, so the agent retains the usage instructions. The
 compaction in Claude Code, so the recall reminder runs again. There is no
 explicit "re-familiarization" nudge for hosts without a compaction hook.
 
-### Extraction nudge timing
+### Extraction timing
 
-OpenCode's extraction pipeline works by:
+OpenCode's extraction pipeline has two paths — direct extraction (primary)
+and the nudge (fallback):
+
+**Direct extraction (primary path):**
 
 1. `tool.execute.after` buffers every non-thatch, non-skill, non-task tool
    call into a per-session in-memory array (max 20 interactions).
-2. On the next `chat.message`, the buffer is **peeked** (not drained) and a
-   synthetic text part carrying the JSON payload is injected into the
-   conversation. The buffer persists until the agent writes a memory or calls
-   `thatch_extraction_done`, so ignored nudges repeat and escalate (polite →
-   insistent → ALL-CAPS) via the `missedNudges` counter.
-3. The agent sees the nudge, loads the `thatch-fact-extractor` skill, and saves
+2. When the parent session goes idle (`session.status` idle event) with pending
+   buffer entries, the plugin calls `triggerExtraction`: creates a child session
+   via `client.session.create` (with `parentID`), then prompts it via
+   `client.session.promptAsync` (or `prompt`) with the extraction payload. The
+   `extracting` set suppresses the nudge in `chat.message` while the child runs.
+3. The child session runs the `thatch-fact-extractor` skill, writes memories via
+   `thatch_memory_remember`. A memory write in the child drains the parent's
+   buffer snapshot (via the `childToParent` Map and `consumeSnapshot`) and
+   resets the missed-nudge counter.
+4. When the child goes idle, the handler drains any remaining snapshot entries
+   (covers no-save runs), deletes the child session, and fires a toast via
+   `client.tui.showToast`.
+
+**Nudge (fallback path):**
+
+1. If `triggerExtraction` throws (session creation or prompt fails), the catch
+   block clears the `extracting` flag. On the next `chat.message`, the buffer is
+   **peeked** (not drained) and a synthetic text part carrying the JSON payload
+   is injected into the conversation. The buffer persists until the agent writes
+   a memory or calls `thatch_extraction_done`, so ignored nudges repeat and
+   escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter.
+2. The agent sees the nudge, loads the `thatch-fact-extractor` skill, and saves
    durable facts via `thatch_memory_remember`. A memory write in the session
    (or a child sub-agent via the `childToParent` Map) or `thatch_extraction_done`
    drains the buffer and resets the missed-nudge counter.

package/docs/dev/setup-and-hooks.md

@@ -19,14 +19,25 @@ The plugin entry (`src/index.ts`) registers these hooks in code:
 | `experimental.chat.system.transform` | `{}` | `{ system: string[] }` | Pushes the system prompt (store names, usage rules). |
 | `experimental.session.compacting` | `{ sessionID }` | `{ context: string[] }` | Marks the session as compacting, pushes re-familiarization context. |
 | `experimental.compaction.autocontinue` | `{ sessionID }` | `{ enabled: boolean }` | Clears the compacting flag so `chat.message` nudges resume post-compaction. |
-| `tool.execute.after` | `{ tool, sessionID, callID, args }` | `{ title, output, metadata }` | Buffers non-`thatch_`, non-`skill`, non-`task` tool calls into the in-memory extraction ring buffer (max 20). |
-| `chat.message` | `{ sessionID, messageID }` | `{ message, parts }` | Two tiers: extraction nudge if pending, else prompt-aware recall nudge. Skipped while the session is compacting. |
-| `event` (`session.created`) | `{ event: { type, properties: { info: { id } } } }` | — | Calls `client.session.prompt` with the reminder + hygiene heartbeat. |
+| `tool.execute.after` | `{ tool, sessionID, callID, args }` | `{ title, output, metadata }` | Buffers non-`thatch_`, non-`skill`, non-`task` tool calls into the in-memory extraction ring buffer (max 20). In child sessions, also tracks new/updated/deleted counts via `childMetrics` for the extraction toast. |
+| `chat.message` | `{ sessionID, messageID }` | `{ message, parts }` | Two tiers: extraction nudge if pending and not already extracting (fallback — direct extraction via the `event` hook is the primary path), else prompt-aware recall nudge. Suppressed while compacting or while `extracting` is set. |
+| `event` | `{ event: { type, properties } }` | — | Dispatches on `event.type`: `session.created` (top-level) → `client.session.prompt` with reminder + hygiene heartbeat; `session.created` (child with `parentID`) → records `childToParent` + snapshots parent's pending buffer. `session.status` idle (parent, pending interactions) → `triggerExtraction` (direct child-session extraction); idle (child) → complete/drain, `showToast` with metrics, delete child. `session.error` (child) → requeue parent's accepted entries. `session.deleted` → requeue if child, drop accepted if parent, clean maps. `session.compacted` → clear compacting flag. |
 | `dispose` | — | — | Closes the DB. |
 
 Skills install to `$XDG_CONFIG_HOME/opencode/skills` at plugin init — shared
 **and** opencode-only (the coordinator needs sub-agents).
 
+Direct extraction is the primary path for opencode: when a parent session goes
+idle with pending tool interactions, the `event` hook creates a child session
+and prompts it directly via `triggerExtraction`. The `chat.message` extraction
+nudge is a fallback — it fires only if direct extraction was never triggered or
+threw an error (the `extracting` set is cleared on failure).
+
+`client.tui.showToast` is called from the `event` hook (on child idle, with
+extraction metrics: new/updated/deleted counts) and from `chat.message` (on
+recall and prediction matches). Best-effort — silently ignored if the TUI is
+not connected (headless mode).
+
 ## Claude Code (MCP server + hooks)
 
 `thatch setup --claude` (project-local) or `thatch setup --claude --global`.

package/docs/dev/skills.md

@@ -21,9 +21,9 @@ description: Extract durable project facts ... Use when ...
 - `description` drives when the agent loads the skill (both opencode and
   Cursor auto-discover skills and use the description for relevance).
 
-## The 19 skills
+## The 20 skills
 
-**Shared (18)** — installed everywhere; no sub-agents required:
+**Shared (19)** — installed everywhere; no sub-agents required:
 
 | Skill | Role |
 |-------|------|
@@ -36,6 +36,7 @@ description: Extract durable project facts ... Use when ...
 | `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth-wall breaks, em dashes, filler. |
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of behavior? |
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
+| `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar against generic praise. |
 | `thatch-review-synthesizer` | Verify specialist findings against code, dedupe, classify, calibrate severity. Starts the final report with a workflow-change preface, then cross-references findings against prior review comments when a follow-up round register is provided. |
 | `thatch-review-context` | Gather project/feature context (PR descriptions, git archaeology, ticket references, memory) before fan-out. Prevents false positives about intentionally deferred work. Also fetches prior review comments on a connected PR/MR for follow-up-round detection and builds a register with preliminary addressed-check status per comment. |
 | `thatch-workflow-research` | Research code workflows/features affected by a change or planned change. Reads code flows, comments, git history, memories, docs. Produces a guide to the code for reviewers or planners. |
@@ -50,11 +51,11 @@ description: Extract durable project facts ... Use when ...
 
 | Skill | Role |
 |-------|------|
-| `thatch-code-review` | Resolve review target (incl. VCS detection and connected PR/MR lookup for follow-up round detection), gather project context, research affected workflows, estimate complexity, partition, dispatch the 6 specialists in parallel, synthesize with a workflow-change preface and prior-comment cross-reference. |
+| `thatch-code-review` | Resolve review target (incl. VCS detection and connected PR/MR lookup for follow-up round detection), gather project context, research affected workflows, estimate complexity, partition, dispatch the 7 specialists in parallel, synthesize with a workflow-change preface and prior-comment cross-reference. |
 
 ## REVIEW_COMMON
 
-The six review specialists share a framework interpolated via `${REVIEW_COMMON}`:
+The six problem-finding review specialists share a framework interpolated via `${REVIEW_COMMON}` (the seventh specialist, highlights, finds positive things and uses its own structure):
 
 - **Static analysis only** — no running tests/linters/compilers.
 - **Scope gathering** — resolve the git range, `git diff --stat`, read changed
@@ -84,7 +85,7 @@ The synthesizer reuses the same verification rigor but has its own structure
 ## The two arrays
 
 ```ts
-const SHARED_SKILLS: SkillDef[] = [ /* 18 skills above */ ];
+const SHARED_SKILLS: SkillDef[] = [ /* 19 skills above */ ];
 const OPENCODE_ONLY_SKILLS: SkillDef[] = [ /* code-review coordinator */ ];
 ```
 
@@ -107,7 +108,7 @@ and `--cursor` pass only the shared set.
 
 ## Adding a skill
 
-1. Write `artifacts/skills/thatch-<name>.md` with YAML frontmatter. If it's a review specialist, include `${REVIEW_COMMON}` (interpolated from `artifacts/skills/common.md`).
+1. Write `artifacts/skills/thatch-<name>.md` with YAML frontmatter. If it's a problem-finding review specialist, include `${REVIEW_COMMON}` (interpolated from `artifacts/skills/common.md`). The highlights specialist does not use REVIEW_COMMON — it finds positive things, not problems, so the problem-finding framework does not apply.
 2. Add the skill name to the `names` array in `loadSharedSkills()` (or `loadOpencodeOnlySkills()` if sub-agents are needed). The loader in `src/skills.ts` reads `.md` files at init.
 3. If the skill name appears in a tool's workflow (e.g. `thatch-fact-extractor`), update `src/prompts.ts`.
 4. Run `mise run check` — tests verify counts; `installSkills` picks up new files on next init.
@@ -115,7 +116,7 @@ and `--cursor` pass only the shared set.
 ## Memory review skills in practice
 
 - **Quick single lens**: load any specialist directly and point it at a branch.
-- **Full review on opencode**: load `thatch-code-review` — it gathers project context, researches affected workflows, dispatches all 6 specialists in parallel (with both the context brief and workflow guide injected into each briefing), then synthesizes a report that starts with the workflow changes before findings.
+- **Full review on opencode**: load `thatch-code-review` — it gathers project context, researches affected workflows, dispatches all 7 specialists in parallel (with both the context brief and workflow guide injected into each briefing), then synthesizes a report that starts with the workflow changes before findings.
 - **Full review on Claude Code/Cursor**: run each specialist in sequence, then
   run `thatch-review-synthesizer` to verify and aggregate.
 

package/docs/qa/use-cases/README.md

@@ -22,13 +22,13 @@ file/IPC/CLI contracts ready to graduate into `bun:test` integration tests.
 | [UC-011](UC-011-write-time-similarity-warning.md) | Write-time warning never blocks; merge or mark-distinct reconciliation |
 | [UC-012](UC-012-model-migration.md) | `THATCH_MODEL` change: old memories skipped (not corrupted) until re-saved |
 | [UC-013](UC-013-compaction-context.md) | Compaction context re-familiarization (opencode-only) |
-| [UC-014](UC-014-skill-install-drift.md) | Skill install: 18 shared vs 19 opencode; drift overwritten on re-setup |
+| [UC-014](UC-014-skill-install-drift.md) | Skill install: 19 shared vs 20 opencode; drift overwritten on re-setup |
 | [UC-015](UC-015-env-override-matrix.md) | `THATCH_DB_PATH`, `XDG_CONFIG_HOME`, `CLAUDE_CONFIG_DIR`, `THATCH_QUEUE_DIR`, `THATCH_RECALL_THRESHOLD`, `THATCH_MODEL` |
 | [UC-016](UC-016-concurrent-session-isolation.md) | Per-session extraction isolation (in-memory + file queue); shared stateless sideband |
 | [UC-017](UC-017-buffer-tool-vs-buffer-batch.md) | `buffer-batch` (Claude, `tool_calls[]`+`session_id`) vs `buffer-tool` (Cursor, single+`conversation_id`) |
 | [UC-018](UC-018-mcp-startup-setup-detection.md) | MCP startup detects missing/broken setup instructions and warns the agent |
 | [UC-019](UC-019-archived-memory-lifecycle.md) | Archive, search exclusion, update guard, unarchive |
-| [UC-020](UC-020-extraction-escalation.md) | Nudge escalation (polite → insistent → ALL-CAPS), buffer persistence, `extraction_done` drain |
+| [UC-020](UC-020-extraction-escalation.md) | Nudge escalation (polite → insistent → ALL-CAPS), buffer persistence, `extraction_done` accept/complete |
 | [UC-021](UC-021-prediction-autofire.md) | Prediction auto-fire: matcher scores prompt, prediction nudge injected alongside recall |
 | [UC-022](UC-022-prediction-dedup.md) | Prediction create-on-existing: dedup finds match, links edge without disconfirming |
 | [UC-023](UC-023-prediction-confidence-model.md) | Bayesian confidence math: create, confirm, soft (weak disconfirm), disconfirm signals |

package/docs/qa/use-cases/UC-003-extraction-nudge.md

@@ -9,24 +9,46 @@ client and a synthetic tool call sequence._
 **Steps**
 1. Do some real work: have the agent read files, run commands, edit code —
    any non-`thatch_*`, non-`skill`, non-`task` tool activity.
-2. Send your next message (anything).
+2. The agent's turn ends and the session goes idle.
 
-**Expected**
-- The agent's context for that message includes a `[thatch]` nudge carrying a
-  JSON payload summarizing the buffered tool interactions (tool name, title,
-  truncated args/output).
-- The agent loads `thatch-fact-extractor` and saves durable facts via
+**Expected (opencode — direct extraction, primary path)**
+- The plugin's `event` hook catches `session.status` idle with pending tool
+  interactions and calls `triggerExtraction`: creates a child session via
+  `client.session.create({ parentID })` and prompts it via
+  `client.session.promptAsync` (or `client.session.prompt` fire-and-forget
+  if the env var is unset).
+- The `extracting` set suppresses the nudge in `chat.message` while the
+  child runs — no nudge text appears in the user's conversation.
+- The child loads `thatch-fact-extractor` and saves durable facts via
   `thatch_memory_remember` — or saves nothing if the activity was routine.
-- The buffer is **not** drained on nudge delivery — it persists until the agent
-  writes a memory or calls `thatch_extraction_done`. If the nudge is ignored,
-  the next message carries a repeat nudge, escalating in urgency:
+- A `thatch_memory_remember` call in the child drains the parent's snapshot
+  entries from the buffer (via `consumeSnapshot` with `parentSnapshots`).
+- When the child goes idle, the parent's snapshot entries are drained
+  (covering no-save runs where no memory was written), the child session is
+  deleted, and a toast notification fires with the extraction metrics
+  (`[thatch] new: N, updated: M, deleted: K`, or
+  `[thatch] extraction complete — nothing to save`).
+- If `triggerExtraction` throws, the `extracting` set is cleared and the
+  nudge fires as a fallback on the next `chat.message` (see below).
+
+**Expected (fallback nudge path — opencode when direct extraction fails,
+and all MCP hosts)**
+- The agent's context for the next message includes a `[thatch]` nudge
+  carrying a JSON payload summarizing the buffered tool interactions (tool
+  name, title, truncated args/output).
+- The buffer is **not** drained on nudge delivery — it persists until the
+  agent writes a memory or accepts it by calling `thatch_extraction_done`.
+  Accepting quiets the nudge while holding the entries until the extractor
+  completes; a child extractor that errors or is deleted requeues them. If
+  the nudge is ignored, the next message carries a repeat nudge, escalating
+  in urgency:
   - 1st-2nd miss: polite tone
   - 3rd consecutive miss (missedCount=2): insistent (directive) tone
   - 4th+ consecutive miss (missedCount>=3): ALL-CAPS tone
-  The counter resets when the buffer drains (memory write or
-  `thatch_extraction_done`).
-- A `thatch_memory_remember` call in a child sub-agent session also drains the
-  parent's buffer (via the `childToParent` Map), so dispatching the
+  The counter resets when the buffer drains (memory write) or is accepted
+  (`thatch_extraction_done`).
+- A `thatch_memory_remember` call in a child sub-agent session also drains
+  the parent's buffer (via the `childToParent` Map), so dispatching the
   fact-extractor as a background task clears the parent's queue.
 - Two concurrent sessions never see each other's interactions in a nudge.
 - The agent's own `thatch_*` tool calls never appear in a payload (no

package/docs/qa/use-cases/UC-005-setup-install.md

@@ -17,12 +17,12 @@
   appends a thatch block to `CLAUDE.md` bracketed by start/end markers (replaced, not
   duplicated, on re-run), writes `.claude/settings.json` hooks (`SessionStart` -> `thatch reminder`,
   `PostToolBatch` -> `thatch buffer-batch`, `UserPromptSubmit` -> `thatch flush-tools`), and installs
-  **18 shared skills** (no code-review coordinator) to `$CLAUDE_CONFIG_DIR/skills/` — user-scoped
+  **19 shared skills** (no code-review coordinator) to `$CLAUDE_CONFIG_DIR/skills/` — user-scoped
   even in project-local mode.
 - `--cursor` project-local writes `.cursor/mcp.json`, appends to `AGENTS.md`, writes
   `.cursor/hooks.json` in the **flat format** (`{version:1, hooks:{...}}`): `sessionStart` ->
   `thatch reminder --json`, `postToolUse` -> `thatch buffer-tool`, `beforeSubmitPrompt` ->
-  `thatch flush-tools --json`; and installs 18 shared skills to `~/.cursor/skills/`.
+  `thatch flush-tools --json`; and installs 19 shared skills to `~/.cursor/skills/`.
 - Re-run is idempotent: instructions are not duplicated, thatch hooks are replaced (not appended),
   and non-thatch hooks are preserved. A legacy `thatch echo` hook is replaced with `flush-tools`.
 - `--global` (Claude) writes `~/.claude/CLAUDE.md` + `~/.claude/settings.json` but **no project

package/docs/qa/use-cases/UC-014-skill-install-drift.md

@@ -13,16 +13,16 @@
 5. Check whether the `thatch-code-review` coordinator skill is present.
 
 **Expected**
-- Claude Code and Cursor install exactly **18 shared skills** to the skills
+- Claude Code and Cursor install exactly **19 shared skills** to the skills
   dir — the coordinator (`thatch-code-review`) is **absent** (it needs
   sub-agents, which those hosts lack).
-- opencode installs **19** — the 18 shared plus the coordinator.
+- opencode installs **20** — the 19 shared plus the coordinator.
 - The locally edited `SKILL.md` is **overwritten** with the canonical content
   on the next `setup`/init (drift detection: a file is only rewritten when its
   content differs from the definition). Unrelated skill files are untouched.
 - Skills never land in the worktree — always under the user-scoped config dir
   (`~/.claude/skills`, `~/.cursor/skills`, `$XDG_CONFIG_HOME/opencode/skills`).
 
-_Automatable: yes — file presence, count (18 vs 19), content-diff-overwrite, and
+_Automatable: yes — file presence, count (19 vs 20), content-diff-overwrite, and
 coordinator host-gating are all file assertions (`setup.test.ts` already covers
 the unit contract)._

package/docs/qa/use-cases/UC-020-extraction-escalation.md

@@ -1,6 +1,6 @@
 # UC-020: Extraction nudge escalation and acknowledgment
 
-_Automatable: missedNudges counter + escalation tiers + extraction_done drain
+_Automatable: missedNudges counter + escalation tiers + extraction_done accept
 are testable with the mock client and a synthetic tool call sequence._
 
 **Preconditions**
@@ -27,12 +27,26 @@ are testable with the mock client and a synthetic tool call sequence._
   persists until a memory is written or `extraction_done` is called. The nudge
   repeats each turn with escalated tone (and the payload grows if new tool
   activity adds entries between nudges).
-- Step 6: `thatch_extraction_done` drains the buffer and resets the
-  `missedNudges` counter. The tool returns `"[acknowledged] extraction buffer
-  drained"`.
-- Step 7: no extraction nudge appears (buffer is empty). If the user prompt
+- Step 6: `thatch_extraction_done` in the parent accepts the buffer (moves it
+  to a holding area) and resets the `missedNudges` counter. The tool returns
+  `"[acknowledged]"`. Held entries drop when the extractor completes (child
+  memory write, child `extraction_done`, or child idle); if the child errors
+  or is deleted first, the entries requeue and the nudge replays.
+- Step 7: no extraction nudge appears (buffer is accepted). If the user prompt
   semantically matches existing memories, a recall nudge may appear instead.
-- Alternative drain path: if a child sub-agent (dispatched via the `task`
-  tool) writes a memory via `thatch_memory_remember`, the parent's buffer is
-  also drained via the `childToParent` Map — the `missedNudges` counter resets
-  for the parent session.
+- Alternative drain path (opencode direct extraction): when the parent session
+  goes idle with pending tool interactions, the plugin calls
+  `triggerExtraction` — creates a child session via the SDK client and prompts
+  it directly. The `extracting` set suppresses the nudge in `chat.message`
+  while the child runs. The child writes memories via
+  `thatch_memory_remember`, which drains the parent's snapshot entries via
+  `consumeSnapshot`. When the child goes idle, the snapshot is drained
+  (covering no-save runs), the child session is deleted, and a toast fires
+  with the metrics. This path bypasses the nudge-and-acknowledge cycle
+  entirely — no `missedNudges` counter, no escalation. The nudge path is
+  fallback only (when `triggerExtraction` throws).
+- Alternative drain path (agent-initiated): if a child sub-agent (dispatched
+  via the `task` tool in the fallback nudge path) writes a memory via
+  `thatch_memory_remember`, the parent's buffer is also drained via the
+  `childToParent` Map — the `missedNudges` counter resets for the parent
+  session.

package/docs/user/README.md

@@ -20,16 +20,15 @@ Publish to npm and add thatch to your opencode config:
 
 OpenCode installs the plugin and its dependencies automatically on next start.
 
-Set this environment variable so the extraction nudge can dispatch the
-fact-extractor as a **background** sub-agent instead of blocking your turn:
+For async extraction (child sessions run in the background):
 
 ```bash
 export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
 ```
 
-Without it, opencode hides the task tool's `background` parameter and the
-extraction nudge runs synchronously. Put it in your shell rc, `mise.toml`
-`[env]`, or `.envrc`.
+Without this env var, extraction still works — the child session runs
+fire-and-forget instead of asynchronously. Put it in your shell rc,
+`mise.toml` `[env]`, or `.envrc`.
 
 For local development before publishing, use a file path:
 
@@ -106,7 +105,7 @@ Stores are created automatically — no setup required.
 
 | Tool | What it does |
 |------|-------------|
-| `thatch_extraction_done` | Acknowledge that the extraction nudge was dispatched to a sub-agent. Drains the buffer so the nudge does not replay. Called after dispatching a background task to run the fact-extractor skill. |
+| `thatch_extraction_done` | Acknowledge extraction buffer work. In the nudge fallback path, quiets the nudge while holding entries until the extractor completes. In a child extractor session, marks entries complete. Called by the model after dispatching the fact-extractor skill. |
 
 ### Prediction tools
 
@@ -133,13 +132,21 @@ Beyond the tools, thatch hooks into opencode itself:
 - **Write-time similarity warning.** Saving a memory that closely resembles an
   existing one succeeds, but the response warns the agent and lists the
   similar entries so it can merge them or record that they're distinct.
-- **Fact-extraction nudges.** Thatch buffers the session's recent tool calls
-  (up to 20, per session). On your next message, the agent receives a summary
-  payload and is prompted to save any durable facts it reveals. The nudge
-  repeats and escalates (polite to insistent to ALL-CAPS) each turn it's
-  ignored — the buffer drains only when the agent writes a memory or
-  acknowledges via `thatch_extraction_done`. The agent does the writing —
-  thatch never saves memories on its own.
+- **Fact extraction.** Thatch buffers the session's recent tool calls (up
+  to 20, per session). When the session goes idle, the plugin creates a
+  child session and prompts it to run the fact-extractor skill directly —
+  no nudge text in your conversation. The child writes memories via
+  `thatch_memory_remember` and is cleaned up when it finishes. A toast
+  notification shows the results (`[thatch] new: 2, updated: 1`). If the
+  direct path fails, a nudge is injected into the next message as a
+  fallback. On Claude Code and Cursor, the nudge-and-acknowledge path is
+  the only mechanism (no SDK client to create child sessions). The agent
+  does the writing — thatch never saves memories on its own.
+- **Recall and prediction toasts.** When your prompt matches stored
+  memories or learned decision patterns, thatch injects a synthetic nudge
+  (invisible to you, visible to the agent) and fires a toast notification
+  (`[thatch] recalled 3 memories` or `[thatch] 2 predictions surfaced`).
+  The toast is ephemeral — it fades after a few seconds.
 - **Compaction context.** When opencode compacts a long session, thatch injects
   a reminder so the summarized session still knows memory tools exist.
 - **Prediction auto-fire.** When a prompt matches learned contexts, thatch
@@ -179,7 +186,7 @@ With `thatch setup --claude`, skills install to `~/.claude/skills/` (or
 
 ### Code review skills
 
-Six specialist review lenses, each a self-contained static-analysis pass:
+Seven specialist review lenses, each a self-contained static-analysis pass:
 
 | Skill | Focus |
 |-------|-------|
@@ -189,7 +196,8 @@ Six specialist review lenses, each a self-contained static-analysis pass:
 | `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth wall breaks, em dashes, hedging, filler. |
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of the code's behavior? |
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
-| `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a report that starts with workflow changes, then deduplicated severity-grouped findings. |
+| `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar against generic praise. |
+| `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a report that starts with workflow changes, then highlights, then deduplicated severity-grouped findings. |
 | `thatch-review-context` | Gathers project context (PR descriptions, git archaeology, ticket references, memory) before a review. Prevents false positives about intentionally deferred work. |
 | `thatch-workflow-research` | Researches code workflows and features affected by a change or planned change. Reads code flows, comments, git history, and produces a guide for reviewers or planners. |
 | `thatch-change-walkthrough` | Explains a change to the user as a teaching walkthrough: researches each affected workflow at the merge-base, teaches current behavior, then overlays the modifications with file:line citations. |
@@ -214,7 +222,7 @@ Six specialist review lenses, each a self-contained static-analysis pass:
 | Skill | opencode | Claude Code | Cursor |
 |-------|----------|-------------|--------|
 | Memory skills (4) | Yes | Yes | Yes |
-| Review specialists (6) | Yes | Yes | Yes |
+| Review specialists (7) | Yes | Yes | Yes |
 | Review synthesizer | Yes | Yes | Yes |
 | Review context + workflow research | Yes | Yes | Yes |
 | Walkthrough skills (2) | Yes | Yes | Yes |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.21",
+  "version": "0.1.24",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",