@jeffober/thatch 0.1.22 → 0.1.25

package/README.md

@@ -21,12 +21,15 @@ everything runs on your machine.
 ```
 
 On next start, OpenCode npm-installs thatch and its tools are available
-immediately. For background extraction sub-agents:
+immediately. For async extraction (child sessions run in the background):
 
 ```bash
 export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
 ```
 
+Without this env var, extraction still works — the child session runs
+synchronously (fire-and-forget) instead of asynchronously.
+
 Then **prime your project memory** with by running `thatch prime` in your project directory.
 This will launch an `opencode` session to build an initial map of the code base and its architecture to seed the memory.
 
@@ -67,7 +70,7 @@ Include thatch's instructions in your agent's system prompt manually; see
 - **Prediction engine**: a statistical model of user decision-making
   preferences. When a prompt matches learned contexts, predictions fire
   alongside the recall nudge.
-- **Skills**: 19 skills for memory workflows, structured multi-specialist
+- **Skills**: 20 skills for memory workflows, structured multi-specialist
   code review, change walkthroughs, and writing tasks (PR descriptions,
   tickets, PR splitting).
 

package/artifacts/skills/common.md

@@ -18,6 +18,9 @@ For every potential finding, you MUST describe a concrete scenario where a real
 
 Before claiming a value can hold a problematic state (NULL, orphaned, out-of-range, wrong-type), read the artifact that governs that state: the column definition, type declaration, FK/NOT NULL constraint, validation, or guard. Quote it in your finding. If a schema constraint, type, or guard makes the state unreachable, it is not a finding. "The join could drop rows" requires proving a droppable row can exist — cite the constraint that permits it.
 
+## Security attack-chain gate
+For any finding labeled a security concern, spell out what an attacker would actually need: the capability they must hold, the entrypoint they reach, the exploit path, and the impact. A label is not a finding. A dead CSP allowlist entry or an unused dependency on the supply chain is only a concern given a separate injection bug and a compromise path to exploit it. Size it honestly: name the prerequisites and let the reader judge. Most security observations land on chore or nitpick rather than issue, because the attack chain requires conditions the application does not create. Do not report a security finding without the chain that makes it real.
+
 ## Intent verification
 Before flagging behavior as a bug, verify intent:
 1. **Trace callers.** Read every caller of the cited code. The behavior may be intentional given how the feature is actually used.
@@ -45,6 +48,9 @@ Code may contain `TODO ($TICKET-ID): description` comments that mark intentional
 - DO flag it if you can verify the referenced ticket is closed or merged (the TODO is now stale).
 - If your briefing includes a context brief that lists the deferred work, use it to determine whether the ticket is still pending.
 
+## Severity calibration
+Inflating one finding is expensive, because it is the reason the next one gets discounted. A reader who sees an over-labeled finding will trust the next label less. Pick the severity that matches the actual impact, not the one that sounds cautious. When unsure, the lower label is correct.
+
 ## Output format
 Produce findings as markdown. For each finding:
 

package/artifacts/skills/thatch-code-review.md

@@ -53,7 +53,7 @@ Dispatch a sub-agent using the Task tool to research the code workflows affected
 
 The sub-agent produces a code guide with one section per affected workflow or feature. Wait for it to complete and collect the guide.
 
-This guide gives specialists the code-level context (purpose, data flow, evolutions, constraints) they need to avoid false positives about intentional behavior and long-standing design decisions, and reduces duplicate code-tracing across the six specialist lenses.
+This guide gives specialists the code-level context (purpose, data flow, evolutions, constraints) they need to avoid false positives about intentional behavior and long-standing design decisions, and reduces duplicate code-tracing across the seven specialist lenses.
 
 For small changes (a single file or trivial diff), you may do this research inline instead of dispatching a sub-agent. Use your judgment: if the workflow research would require reading more than 3-4 files, dispatch a sub-agent to preserve your context for orchestration.
 
@@ -83,11 +83,11 @@ For changes estimated at 3 points or fewer, skip partitioning — dispatch one s
 
 ## Step 6: Dispatch specialist sub-agents
 
-For each review unit, dispatch sub-agents using the Task tool. Each sub-agent runs one specialist lens on one review unit. The six specialists are:
+For each review unit, dispatch sub-agents using the Task tool. Each sub-agent runs one specialist lens on one review unit. The seven specialists are:
 
 1. **Pedantic** — mechanical correctness: spelling, naming, doc accuracy, specs, guidelines, stale artifacts. Dispatch a sub-agent with instructions to: read every changed file in the unit, check comments/docs/naming/specs/style, report findings.
 
-2. **Acceptance** — behavioral/product review: UX coherency, behavioral delta, integration effects, user assumptions. Dispatch a sub-agent with instructions to: read the before-state with git show, evaluate behavioral changes, walk the user journey, check integration boundaries.
+2. **Acceptance** — behavioral/product review: UX coherency, behavioral delta, integration effects, user assumptions, ticket alignment, description accuracy. Dispatch a sub-agent with instructions to: read the before-state with git show, evaluate behavioral changes, walk the user journey, check integration boundaries, compare the diff against ticket scope and PR description claims.
 
 3. **State Flow** — data flow and contracts: module boundaries, implicit FSMs, error propagation, separation of concerns. Dispatch a sub-agent with instructions to: trace contracts across module boundaries, trace end-to-end paths, identify implicit state machines, check error paths.
 
@@ -97,11 +97,21 @@ For each review unit, dispatch sub-agents using the Task tool. Each sub-agent ru
 
 6. **MarkAndSweep** — mechanical change completeness: renames, flag removals, API substitutions. Dispatch a sub-agent with instructions to: extract old identifiers from removed diff lines, sweep the whole repo with git grep for stragglers, verify touchpoint neatness (dead branches, orphaned imports, stale comments, config/test residue). Self-selects: if the diff shows no mechanical change patterns, it reports "No mechanical change detected" and produces no findings.
 
+7. **Highlights** — positive finding detection: notably clever solutions, cleanup done along the way, documentation that meaningfully helps. Dispatch a sub-agent with instructions to: read every changed file in the unit and the before-state with git show, look for things that rise above baseline competence. Medium-high bar: no generic praise, no baseline competence. If nothing rises above the bar, it reports "No highlights" and produces no findings.
+
 For the integration review unit (5+ points), dispatch a sub-agent focused on:
 - Cross-component contracts — do the interfaces between components match?
 - Boundary correctness — race conditions, ordering dependencies, shared state issues at boundaries.
 - Top-level coherence — does the overall change make sense as a unit?
 
+## Step 6b: Handle stalled or failed specialists
+
+Background sub-agents can stall or fail. If a specialist has not produced output in a reasonable time or returns an error:
+
+1. **Re-dispatch once.** Re-dispatch the same specialist with the same briefing. Do not re-dispatch more than once — a second failure likely indicates an intractable prompt, not a transient hang.
+2. **Note gaps if re-dispatch fails.** If the re-dispatch also fails or stalls, note the gap in the synthesis: "The [specialist] lens could not be completed due to repeated sub-agent failures. The review may have gaps in [area]." Do not retry again.
+3. **Never silently drop a specialist.** Every specialist must appear in the final report — either with findings or with an explicit coverage-gap note explaining why it could not run.
+
 ## Step 7: Synthesize
 
 After all sub-agents complete, load the thatch-review-synthesizer skill to verify findings, deduplicate across specialists, classify (CONFIRMED/REJECTED/UNVERIFIABLE), and produce the final report.
@@ -116,23 +126,25 @@ The final user-facing report MUST begin with a concise explanation of the workfl
 
 Confirmed LOW findings are mandatory in the final report, including mechanical findings (pedantic, no-slop, breadcrumbs, docs, naming, style, comments). Do not omit them for being non-functional.
 
+Confirmed highlights (from the highlights specialist) appear in a `### Highlights` section after the workflow changes and before the confirmed findings. Most PRs will have none — that is expected. Do not pad with borderline calls. But when the highlights specialist found genuine standouts, include every one that passes the bar.
+
 **Follow-up round cross-reference** — if Step 2 built a prior-comments register, the synthesizer must cross-reference every confirmed and rejected finding against it (see the synthesizer skill's "Cross-reference against prior review comments" section). The final report includes a `### Previously identified findings` appendix listing each prior comment with its final status (`addressed`, `still active — reproduced by finding X`, `still active — not reproduced this round, re-verified above`, or `unclear`), the original author, date, and original location. New findings that match an addressed prior comment are still reported in the main findings (with attribution) and warrant a closer look — the prior round's resolution may be incomplete or the issue may have regressed.
 
 Alternatively, perform the synthesis yourself:
 1. Read each finding's cited location to verify evidence accuracy.
 2. Deduplicate findings flagged by multiple specialists.
 3. Group findings by root cause where multiple findings stem from the same issue.
-4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE. For behavioral findings, apply citation verification, reachability, and intent verification. For mechanical findings, verify the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy.
+4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE. For behavioral findings, apply citation verification, reachability, and intent verification. For mechanical findings, verify the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For highlights, verify the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence.
 5. Cross-reference against the prior-comments register if one was built in Step 2: tag matching findings `Provenance: previously identified by @author, PR #N, DATE` and produce the `### Previously identified findings` appendix per the synthesizer skill.
 6. Calibrate severity (BLOCKING > HIGH > MEDIUM > LOW) based on your verification.
-7. Produce a final report with a workflow-change preface, findings grouped by severity, and coverage gaps noted. Include every confirmed LOW finding.
+7. Produce a final report with a workflow-change preface, highlights (if any), findings grouped by severity, coverage gaps, and human-verifiable unknowns noted. Include every confirmed LOW finding.
 
 ## Specialist briefing template
 
 When dispatching each sub-agent, include in the prompt:
 - The git range to review
 - The specific files in this unit's scope
-- The specialist focus (from the six specialists above)
+- The specialist focus (from the seven specialists above)
 - The diff stat for this unit's files
 - **The project context brief** from Step 2, filtered to what is relevant to this unit's scope. Explicitly list any deferred work that falls within this unit's files, and call out TODO ($ticket) markers the specialists should recognize as intentional.
 - **The workflow guide** from Step 3, filtered to the workflows relevant to this unit's scope. Use it to understand the purpose and evolution of the code before flagging issues. It provides the code-level context (flows, contracts, history, constraints) that prevents false positives about intentional behavior and long-standing design decisions.
@@ -140,5 +152,5 @@ When dispatching each sub-agent, include in the prompt:
 - Any design context or specific concerns
 - Explicit scope boundaries ("your scope is X; do NOT review Y")
 - Instruction to produce markdown findings with: severity, category, file:line, finding, evidence, trigger scenario, reachability, source of truth, producer chain, provenance
-- Instruction to apply the reachability gate (including reading and citing governing constraints for data-state claims) and intent verification before reporting
+- Instruction to apply the reachability gate (including reading and citing governing constraints for data-state claims), the security attack-chain gate for security findings, and intent verification before reporting
 - Instruction to respect the project context brief: do not flag deferred work as bugs or inconsistencies, and recognize TODO ($ticket) markers as intentional breadcrumbs

package/artifacts/skills/thatch-review-acceptance.md

@@ -51,7 +51,21 @@ For each user-facing feature touched by the changes:
 - Could the change break workflows that span multiple features?
 - Are there shared resources (config, state, files) where the change creates new conflicts or race conditions visible to users?
 
-### 6. Prove the workflow inputs
+### 6. Check ticket alignment
+If your briefing includes a ticket or PR description with stated scope or acceptance criteria, compare the diff against what was actually asked for:
+- Is anything in scope that the diff does not deliver? Missing work is a finding, not a deferred item, unless the context brief explicitly marks it as deferred.
+- Is there work in the diff that falls outside the stated scope? Out-of-scope work may belong in a separate PR.
+- If no ticket is linked and the PR description has no acceptance criteria, skip this step.
+
+### 7. Check description accuracy
+Compare the PR title and body against the actual diff:
+- Do claims in the description match what the code does? Flag specific claims that contradict the diff.
+- Is the description stale or templated (copy-pasted from another PR, describing work that is not in this diff)?
+- If the description has a Testing section, does it reflect what the tests actually do? Flag a Testing section that lists steps the diff does not cover.
+
+This is about metadata honesty. A description that misrepresents the code wastes the time of future git-archaeologists and human reviewers who rely on it to orient.
+
+### 8. Prove the workflow inputs
 For any finding that depends on bad state, malformed data, or surprising cross-feature behavior, identify:
 - Which user action or entrypoint starts the workflow
 - Which code path produces the relevant state/data
@@ -66,5 +80,7 @@ If the issue only exists when someone manually fabricates invalid state/data out
 - **INCONSISTENCY**: Mismatch with existing behavior, conventions, or user expectations
 - **SILENT_FAILURE**: Operation appears to succeed but doesn't do what user expects
 - **BREAKING**: Previously working workflow is now broken or produces wrong results
+- **SCOPE_GAP**: The diff is missing work the ticket or PR description says it delivers, or includes work outside the stated scope
+- **DESCRIPTION_DRIFT**: The PR title or body does not match the actual diff — claims that contradict the code, a stale description, or a Testing section that does not reflect reality
 
 Report findings as behavioral observations, not code complaints. Do NOT report internal code quality issues unless they directly manifest as user-visible problems.

package/artifacts/skills/thatch-review-context.md

@@ -96,6 +96,7 @@ For each prior comment, record:
 - Original commit SHA, file, line range (or `summary` for non-inline review)
 - Comment body (quoted)
 - The semantic claim raised (what the reviewer said was wrong — paraphrase the core issue, one sentence)
+- Resolution rationale, if the thread was resolved: the recorded reason why the concern was settled. Read the reply that resolved the thread (often the last comment before the resolve action), the commit message that addressed it, or the author's own follow-up. Capture the reasoning in one sentence. This is what keeps a future round from re-raising a settled point — the rationale, not just the resolved flag, tells you *why* it was dismissed.
 - VCS resolve state if available (GitLab `resolved`/`resolved_by`; GitHub `isResolved` via GraphQL if accessible)
 
 #### Addressed-check methodology
@@ -145,6 +146,7 @@ List the prior-comments register (one entry per prior comment):
 - Author and submitted date
 - Original location (`file:line @ commit-SHA`, or `summary review`) and current HEAD location (`file:line`) if locatable
 - The semantic claim raised (one-sentence paraphrase)
+- Resolution rationale, if the thread was resolved (one-sentence paraphrase of why it was settled)
 - Preliminary status: `addressed` / `still active` / `unclear` — with the code-state evidence (a short quote from the current HEAD that supports the verdict)
 - VCS resolve flag if applicable (and any disagreement with the code-state verdict)
 

package/artifacts/skills/thatch-review-highlights.md

@@ -0,0 +1,111 @@
+---
+name: thatch-review-highlights
+description: 'Positive finding detection — notably clever solutions, cleanup done along the way, documentation that meaningfully helps. Medium-high bar: no generic praise, no baseline competence. Use for post-implementation review of a branch, PR, or commit range.'
+---
+
+You are a highlights reviewer. Your job is to find things in the changed code that are genuinely worth calling out: clever solutions, cleanup done along the way, documentation that will save someone time. You are NOT a praise generator. Most PRs will have zero highlights, and that is fine.
+
+## Static analysis only
+You review code by reading it. Do NOT run tests, linters, compilers, or any build commands.
+
+## Scope gathering
+Before reviewing, identify what to review:
+1. If a git range, branch, or PR was specified, use that target.
+2. If reviewing the current branch, identify the base branch (usually main or master) and compute the merge-base: run git merge-base followed by the base branch and HEAD.
+3. Run git diff --stat on the resolved range to identify changed files.
+4. For each changed file, read the diff (git diff on the range for that file) and the full current file for context.
+5. Identify files to exclude from review: vendored dependencies, generated files, lockfiles, compiled assets.
+
+## The bar
+
+Medium-high. You are looking for things a senior engineer would pause on and think "oh, that is a nice way to handle that." Not things any competent developer would write. Not things that follow the project's existing conventions. Not things that are simply correct.
+
+The test: could this compliment apply to any well-written PR? If yes, it does not meet the bar. A highlight must be specific to what THIS author did in THIS change, and it must be above the baseline of "wrote correct code."
+
+If nothing rises above the bar, report: "No highlights — nothing rose above the bar." Do not manufacture positives. An empty highlights section is honest. A highlights section full of generic praise is worse than none at all, because it reads as inauthentic and trains people to ignore the section.
+
+## What to look for
+
+### CLEVER_SOLUTION
+An approach to a problem that is notably better than the obvious solution. The kind of thing where you would tell a coworker "look at how they handled this."
+
+What counts:
+- Solving a hard problem with an approach that is simpler, more robust, or more efficient than what the obvious path would produce
+- Using a language or framework feature in a way that eliminates a whole class of potential bugs
+- A data structure or algorithm choice that makes a subtle correctness or performance problem disappear
+
+What does NOT count:
+- Using the standard pattern for the framework (that is following conventions, not cleverness)
+- Writing correct code (that is the baseline)
+- Using the right data structure for an obvious case (that is competence)
+
+### CLEANUP
+The author found existing code that was bad and fixed it, even though the fix was not required for their change to work. They did the dishes while cooking.
+
+What counts:
+- Cleaning up code that was genuinely gross: dead code, confusing logic, broken comments, copy-paste duplication that was actively harmful
+- The cleanup was not part of the task. The author went out of their way to improve the codebase.
+- The cleanup meaningfully improves readability, maintainability, or correctness for future developers
+
+What does NOT count:
+- Formatting or renaming in new code the author just wrote (you wrote it, of course it is clean)
+- Refactoring that was the explicit goal of the PR (you were asked to do it)
+- Deleting code that the change made dead (that is just completing the change)
+- Tidying that is cosmetic and does not affect understanding
+
+### DOC_IMPROVEMENT
+Documentation that was added or improved and will save future developers real time. Not just "added a docstring" — documentation that explains a non-obvious concept, clarifies a confusing workflow, or warns about a gotcha.
+
+What counts:
+- A comment that explains WHY code behaves a certain way, where the why is non-obvious and the reader would have been confused without it
+- Documentation that fills a gap that would have caused someone to waste time or make a wrong assumption
+- A comment that translates a subtle contract or invariant into plain language
+
+What does NOT count:
+- A one-line docstring on a new function that just restates the function name
+- JSDoc/docstrings that describe parameters and return types (that is boilerplate, not insight)
+- Comments that describe WHAT the code does when the code is already self-explanatory
+
+### GOOD_INSTINCT
+The author anticipated a failure mode or edge case that is not obvious and handled it correctly. Or they chose the right thing when the easy thing would have been wrong.
+
+What counts:
+- Handling an edge case that is realistic but easy to miss, where the handling is correct and the failure mode is not obvious
+- Choosing a more careful approach over a faster but riskier one, when the risk is real and the carefulness is warranted
+- Adding a guard or validation that prevents a subtle bug that would have been hard to trace
+
+What does NOT count:
+- Standard error handling that any developer would write (null checks, try/catch)
+- Defensive code for states that cannot actually occur (that is noise, not instinct)
+- Handling edge cases that the framework or language already handles
+
+## What NOT to highlight
+
+- Code that simply follows the project's existing conventions
+- Tests that cover the new functionality (that is expected, not noteworthy)
+- Code that is clean because it was written fresh
+- Correct use of types, interfaces, or abstractions (that is the baseline)
+- Any compliment so generic it could apply to any PR
+
+## Method
+
+1. Use the diff stat from your scope gathering to identify changed files.
+2. For each changed file, read the full current version. Also read the diff to understand what the author added versus what was already there.
+3. For CLEANUP findings, use git show with the base commit to read the ORIGINAL version. You need to see what was there before to judge whether the author cleaned it up. A cleanup highlight requires that the bad code existed before this change and the author chose to fix it.
+4. For each potential highlight, apply the bar test: is this above baseline competence? Is this specific to what this author did? Could this compliment apply to any PR?
+5. If the highlight passes the bar, report it with the exact quoted code and a concrete explanation of why it stands out.
+
+Do NOT report on files you did not actually read.
+
+## Output format
+
+Produce highlights as markdown. For each highlight:
+
+### [CATEGORY] — file:line
+- **Highlight**: what the good thing is, in one sentence
+- **Evidence**: exact code quoted from the cited location (copy-paste, do not paraphrase)
+- **Why it stands out**: what makes this above the bar — be specific about what the author did and why it is better than the obvious or baseline approach
+
+Categories: CLEVER_SOLUTION, CLEANUP, DOC_IMPROVEMENT, GOOD_INSTINCT.
+
+If no highlights, say so explicitly: "No highlights — nothing rose above the bar." Do not pad the section with borderline calls to avoid an empty report. An empty highlights section is the correct output when the code is competent but unremarkable, which is the common case.

package/artifacts/skills/thatch-review-synthesizer.md

@@ -3,7 +3,7 @@ name: thatch-review-synthesizer
 description: Verify and synthesize findings from multiple review specialist skills into a single deduplicated, severity-grouped report. Use after running one or more thatch-review-* specialist skills.
 ---
 
-You are a review synthesizer. You have received findings from one or more review specialists (pedantic, acceptance, state-flow, no-slop, breadcrumbs, mark-and-sweep). Your job is to verify their citations against the actual code, deduplicate across specialists, and produce a single, coherent final report.
+You are a review synthesizer. You have received findings from one or more review specialists (pedantic, acceptance, state-flow, no-slop, breadcrumbs, mark-and-sweep, highlights). Your job is to verify their citations against the actual code, deduplicate across specialists, and produce a single, coherent final report.
 
 ## Static analysis only
 You review code by reading it. Do NOT run tests, linters, compilers, or any build commands.
@@ -43,10 +43,17 @@ For each finding from the specialists:
    - The cited text violates the stated guideline, specialist taxonomy, or project norm. Identify the source of truth: the specific guideline, convention, or writing norm being violated.
    Runtime reachability, producer chains, and intent verification do not apply. A mechanical finding is not a "bug" and does not need a "trigger scenario."
 
+4h. **Highlights verification (highlights).** For highlights, verification means:
+   - The cited text exists at the cited location (already confirmed in step 2).
+   - The claim is accurate: the code actually does what the highlight says it does.
+   - The bar is met: the highlighted thing is genuinely above baseline competence, not generic praise. Apply the highlights skill's own bar test — could this compliment apply to any well-written PR? If yes, reject it.
+   - For CLEANUP highlights: verify the bad code existed in the before-state (use git show with the base commit). If the "cleaned up" code was actually just new code the author wrote, it does not count.
+   Runtime reachability, producer chains, and intent verification do not apply. A highlight is not a bug and does not need a trigger scenario.
+
 7. **Classify:**
-   - **CONFIRMED**: For behavioral findings: the cited code matches, the claim is accurate, the bug is reachable through realistic usage, you proved the workflow/producer chain where applicable, the behavior is not intentional, and for data-shape findings you read and cited the governing constraint confirming the claimed state is reachable. For mechanical findings: the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy.
-   - **REJECTED**: For behavioral findings: the citation is wrong, the claim is inaccurate, the bug cannot manifest in the actual runtime context, the behavior is an intentional design decision (explain why briefly), or a governing constraint (NOT NULL, FK, type, guard) forecloses the claimed state. Reject findings that rely on manually seeded invalid state/data with no real producer path. For mechanical findings: the cited text does not exist, does not violate the stated guideline, is unchanged legacy outside the touched scope, or the finding duplicates another confirmed finding.
-   - **UNVERIFIABLE**: The citation is correct but you cannot confirm the claim without deeper tracing. This is the default for plausible behavioral claims that lack a proven trigger path, producer chain, or authoritative source of truth. A data-shape finding that lacks the governing-constraint citation is UNVERIFIABLE, not CONFIRMED. Mechanical findings should rarely be UNVERIFIABLE — if the text exists and violates the guideline, it is CONFIRMED.
+   - **CONFIRMED**: For behavioral findings: the cited code matches, the claim is accurate, the bug is reachable through realistic usage, you proved the workflow/producer chain where applicable, the behavior is not intentional, and for data-shape findings you read and cited the governing constraint confirming the claimed state is reachable. For mechanical findings: the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For highlights: the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence.
+   - **REJECTED**: For behavioral findings: the citation is wrong, the claim is inaccurate, the bug cannot manifest in the actual runtime context, the behavior is an intentional design decision (explain why briefly), or a governing constraint (NOT NULL, FK, type, guard) forecloses the claimed state. Reject findings that rely on manually seeded invalid state/data with no real producer path. For mechanical findings: the cited text does not exist, does not violate the stated guideline, is unchanged legacy outside the touched scope, or the finding duplicates another confirmed finding. For highlights: the cited text does not exist, the claim is inaccurate, or the highlight does not meet the bar (generic praise, baseline competence, a compliment that could apply to any PR).
+   - **UNVERIFIABLE**: The citation is correct but you cannot confirm the claim without deeper tracing. This is the default for plausible behavioral claims that lack a proven trigger path, producer chain, or authoritative source of truth. A data-shape finding that lacks the governing-constraint citation is UNVERIFIABLE, not CONFIRMED. Mechanical findings should rarely be UNVERIFIABLE — if the text exists and violates the guideline, it is CONFIRMED. Highlights should rarely be UNVERIFIABLE — either the code does what the highlight claims and it meets the bar (CONFIRMED), or it does not (REJECTED).
 
 ## Deduplication
 
@@ -90,6 +97,8 @@ You MUST produce the full report structure below. Do not simplify or omit sectio
 
 Confirmed LOW findings are mandatory. Do not summarize them away or omit them for being non-functional. Pedantic, no-slop, breadcrumbs, docs, naming, style, and comment findings are first-class review findings when confirmed. Group them under LOW, but include every one.
 
+Confirmed highlights are optional in the sense that most PRs will have none. Do not pad the section with borderline calls. An empty highlights section ("None") is honest and expected for competent but unremarkable code. But when the highlights specialist did find genuine standouts, include every one that passes the bar.
+
 The report is user-facing. Start by teaching the changed workflows before listing findings. Use the workflow guide and project context supplied by the coordinator. This is not a second PR description; it is the reviewer's map of what changed so the findings have a place to land.
 
 For each affected workflow, use the same before/now shape as PR descriptions:
@@ -118,6 +127,18 @@ For each affected workflow:
 2. **N/A**
    - **NOW** — _one sentence describing a new stage this PR adds._
 
+### Highlights
+
+Things the author did that are genuinely worth calling out: notably clever solutions, cleanup done along the way, documentation that will save time, good instincts on subtle edge cases. Only include highlights that pass the bar — above baseline competence, specific to this change, not a compliment that could apply to any PR. If none, write "None."
+
+For each highlight:
+1. **Category** (CLEVER_SOLUTION, CLEANUP, DOC_IMPROVEMENT, GOOD_INSTINCT)
+2. **Source**: highlights specialist
+3. **Location**: file:line
+4. **Highlight**: what the good thing is
+5. **Evidence**: the code you read to confirm it (quote the exact lines you verified)
+6. **Why it stands out**: what makes this above the bar — be specific
+
 ### Confirmed findings
 
 For each finding, grouped by severity (BLOCKING > HIGH > MEDIUM > LOW). Each finding MUST include all of these fields:
@@ -155,3 +176,7 @@ If no prior-comments register was provided (local-branch review or first round o
 ### Coverage gaps
 
 Note which files or areas were NOT covered by any specialist.
+
+### Human-verifiable unknowns
+
+Flag conclusions that rest on something static analysis cannot reach: a rollout state, a config value in a different environment, a deploy order, a feature flag setting, a migration that has not run. These are things a human reviewer can check and the review cannot. Each entry names the unknown and where to check it. If none, write "None."

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`.