claude-mem-lite 3.78.0 → 3.80.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.78.0",
+      "version": "3.80.0",
       "source": "./",
       "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark)."
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.78.0",
+  "version": "3.80.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "author": {
     "name": "sdsrss"

package/README.md

@@ -816,6 +816,8 @@ benchmark and A/B harness are calibrated against — changing them invalidates t
 | `CLAUDE_MEM_UPS_TOP_MIN` | Minimum score for the top hit; `0` disables (useful on tiny test corpora). | `50` |
 | `CLAUDE_MEM_UPS_FLOOR_REF_CORPUS` | Reference corpus size the score floors are normalized against, so a fresh install with few rows is not silently gated to zero injections. Shared by every floor-bearing surface, including error-recall below. | `584` |
 | `CLAUDE_MEM_ERROR_RECALL_BM25_MIN` | Relevance floor for the error-recall surface (memories injected after a failed Bash command). **Off by default.** Setting it to `10.5` (the calibrated value) makes the surface stay silent when its best-matching memory is not actually about the failure — the whole set is dropped, never trimmed row-by-row. **It is a real trade, not a free win:** measured on a live database at that threshold, injections fall ~37% and ~39% of firings go silent, concentrated in projects with few memories. Off by default because nothing shows the dropped rows were noise. Explore with `node benchmark/error-recall-suite.mjs --sweep`. | `0` (off) |
+| `CLAUDE_MEM_ERROR_RECALL_RERANK` | `off` restores the flat keyword ordering of the error-recall surface. **On by default**, and unlike the floor above it removes nothing: memories that share only the failed command's vocabulary are demoted below memories that mention the failure itself, and when a project has none of the latter the result is unchanged. Measured on a live database over 52 real failing commands × 15 projects: the lead memory matched no error term in 42.3% of firings before, 21.5% after, with the injected row count identical. | _(on)_ |
+| `CLAUDE_MEM_ERROR_RECALL_ON_FAILURE` | `off` stops the plugin from recalling memories when a Bash command **fails at the host level**. On by default. Claude Code delivers failed tool calls to a separate `PostToolUseFailure` hook event, so before this the surface only ever saw commands that exited `0` while printing error-ish text — a genuinely failing build recalled nothing. Denials from your own guardrails (sandbox, policy hooks, declined permission prompts) and commands you interrupted are never recalled for. | _(on)_ |
 | `CLAUDE_MEM_UPS_IDENTIFIER_BYPASS` | `0` disables the bypass that lets an exact identifier match skip the score floors. | _(on)_ |
 | `CLAUDE_MEM_UPS_PROMPT_FALLBACK_LIMIT` | How many past-prompt rows the fallback arm may return. | `1` |
 | `MEM_COVERAGE_THRESHOLD` | Fraction of query terms a memory must cover to qualify (∈ [0,1]). | `0.4` |

package/bash-utils.mjs

@@ -120,6 +120,58 @@ const ERROR_STOP_WORDS = new Set([
 const ERROR_LINE_RE = /error|fail|exception|cannot|not found|undefined|null/i;
 const ERROR_RECALL_MAX_TERMS = 6;
 
+/**
+ * The token that NAMES the failure: an exception class (`ModuleNotFoundError`,
+ * `JSONDecodeError`), an errno-style code (`ENOENT`, `EACCES`), a signal (`SIGSEGV`),
+ * or Rust's `panicked`.
+ *
+ * WHY THIS EXISTS (D#167). The line scan below takes the FIRST 3 matching lines and the
+ * first 5 tokens of each, and a real failure puts its banner first and its name last:
+ *
+ *     Traceback (most recent call last):        <- matches, contributes `traceback most recent`
+ *       File "<string>", line 3, in <module>
+ *     ModuleNotFoundError: No module named 'x'  <- the only line that says WHAT broke
+ *
+ * Measured over 52 real failing commands pulled from 1110 transcripts: 28 of them name
+ * their failure this way, and in 25 of those 28 (89.3%) THE NAME NEVER REACHED THE
+ * QUERY. The six-term budget went to the banner (`traceback,most,recent`) and to path
+ * fragments from the command (`mnt,data_ssd,dev`). Downstream, 39.2% of injected rows
+ * (764/1947 over 8 projects x 52 shapes on the live DB) matched no error term at all —
+ * they were admitted on command vocabulary alone — and for 42.3% of firing cases that
+ * was true of the TOP-1 row, whose lesson_learned is inlined into the model's context.
+ *
+ * This is deliberately a POSITIVE pattern for the signal, not a stop-list for the noise:
+ * a stop-list of boilerplate ("traceback", "most", "recent", "call", "last", …) grows
+ * once per runtime forever, which is the enumeration the D#136 docblock below warns
+ * against. Matching the shape of an exception name instead covers runtimes nobody has
+ * seen yet, and when nothing matches, extraction is byte-identical to before.
+ *
+ * Note `E[A-Z]{3,}` also matches the literal `ERROR`; it is dropped by ERROR_STOP_WORDS
+ * on the next line, and that interaction is load-bearing rather than incidental.
+ */
+const ERROR_NAMER_RE = /\b(?:[A-Z][A-Za-z]*(?:Error|Exception)|E[A-Z]{3,}|SIG[A-Z]{2,}|panicked)\b/g;
+
+/**
+ * How many names may jump the queue. Each one displaces a scanned term (the 6-term cap
+ * is unchanged), so this trades tail tokens for the identifier.
+ *
+ * ONE, and that is measured rather than argued. Swept on the live DB over the same 52
+ * shapes x 15 projects, reading the share of injected rows that match no error term and
+ * the share of cases whose top row does:
+ *
+ *   MAX=1   434 rows (22.4%)   154 cases (21.5%)
+ *   MAX=2   442 rows (22.8%)   157 cases (22.0%)
+ *   MAX=3   445 rows (22.9%)   157 cases (22.0%)
+ *
+ * The second name never pays: 96.4% of shapes already have their failure named by the
+ * first, so slots 2 and 3 buy a duplicate or a second-order name while still evicting a
+ * scanned term — and the evicted tail is often the most specific token in the list (see
+ * the golden case in tests/error-recall-gate.test.mjs, where a filename is lost). This
+ * shipped at 2 on the reasoning that a chained Python traceback has two real names; the
+ * sweep says that reasoning does not survive contact with the sample.
+ */
+const ERROR_NAMER_MAX = 1;
+
 /**
  * Split a failed command + its output into command-derived and error-derived terms.
  * Shared by extractErrorKeywords (merged view, unchanged contract) and
@@ -137,6 +189,19 @@ function collectErrorTerms(cmd, response) {
     if (!ERROR_STOP_WORDS.has(lw) && !seen.has(lw)) { seen.add(lw); cmdWords.push(lw); }
   }
   const errWords = [];
+  // The failure's NAME goes in first — see ERROR_NAMER_RE for the measurement that put
+  // it here. Prepending rather than re-ordering the LINE scan is deliberate: sorting
+  // namer-bearing lines to the front also promotes their verbose neighbours, which costs
+  // real terms (on npm's ENOENT output it evicts `syscall` in favour of `such`/`file`
+  // from the long "no such file or directory" line). Prepending only ever displaces the
+  // TAIL of what the scan would have produced.
+  for (const m of String(response || '').match(ERROR_NAMER_RE) || []) {
+    if (errWords.length >= ERROR_NAMER_MAX) break;
+    const lt = m.toLowerCase();
+    if (ERROR_STOP_WORDS.has(lt) || seen.has(lt)) continue;
+    seen.add(lt);
+    errWords.push(lt);
+  }
   // The line filter is the TRIGGER's pattern list OR'd with the prose one. Anything
   // that made detectBashSignificance call this a hard error is, by construction, also
   // something we will extract terms from — which closes the "trigger fired, extractor
@@ -163,6 +228,40 @@ function collectErrorTerms(cmd, response) {
   return { cmdWords, errWords };
 }
 
+/**
+ * THE CAP TRUNCATES BY POSITION, AND THAT WAS TESTED AGAINST THE ALTERNATIVE (D#169).
+ *
+ * The alternative looked obviously right. Tokens are scanned line by line, prose comes
+ * before identifiers within a line, so `AssertionError: expected observation-write.mjs
+ * to be defined` yields `assertionerror, expected, observation-write.mjs` — and whatever
+ * the cap removes comes off that end. On a real shape, `npx vitest run
+ * tests/scope-label.test.mjs` failing with an AssertionError kept `fail, tests` and
+ * dropped `scope-label.test.mjs`: a filename traded for a word in thousands of memories.
+ * Keeping identifier-shaped tokens (`[._-]`) first should fix that.
+ *
+ * Measured on the live DB, same 58 real shapes x 15 projects either way:
+ *
+ *                              cmd-only rows     cmd-only at TOP-1
+ *   positional cap (shipped)   493/2184  22.6%   171/801  21.3%
+ *   identifier-first cap        749/2093  35.8%   259/775  33.4%
+ *
+ * Thirteen points WORSE on both, and the mechanism is worth keeping written down:
+ * `[._-]` conflates "discriminative" with "unique to this invocation". The tokens it
+ * promotes are this run's own paths and filenames — `d167-measure.mjs`,
+ * `s-default.json` — whose IDF is so high they match NOTHING in the corpus, and the
+ * tokens it evicts to make room are `enoent`, `syscall`: low-IDF, but present in the
+ * memories that actually explain the failure. A row then survives on command vocabulary
+ * alone, which is the D#167 defect re-created from the other side.
+ *
+ * (A variant that promoted identifiers only among ERROR words, sparing command words,
+ * measured byte-identical: command words sit at low indices, so a positional tiebreak
+ * already keeps them and promotion never decides their fate.)
+ *
+ * The premise "the evicted tail is systematically the good part" is therefore FALSE.
+ * The tail is often hapax. Any future attempt here needs real document frequencies, not
+ * a shape heuristic — and planErrorRecall is pure, with no corpus to count against.
+ */
+
 /**
  * Extract discriminative keywords from a failed command and its error output.
  * Filters out common stop words to produce useful FTS5 search terms.
@@ -172,6 +271,8 @@ function collectErrorTerms(cmd, response) {
  */
 export function extractErrorKeywords(cmd, response) {
   const { cmdWords, errWords } = collectErrorTerms(cmd, response);
+  // Same cap rule as planErrorRecall — the two must not drift into dialects, which is
+  // pinned by a test asserting they emit identical lists.
   const result = [...cmdWords, ...errWords].slice(0, ERROR_RECALL_MAX_TERMS);
   return result.length >= 1 ? result : null;
 }
@@ -231,12 +332,26 @@ export function extractErrorKeywords(cmd, response) {
  *
  * @param {string} cmd The command that was executed
  * @param {string} response The error output text
- * @returns {{terms: string[]}|null} null ⇒ do not inject
+ * @returns {{terms: string[], cmdWords: string[], errWords: string[]}|null}
+ *   null ⇒ do not inject. The two classes are returned ALONGSIDE the merged list, and
+ *   post-cap, so the retrieval surface can rank on "did this row match the failure or
+ *   only the command" without re-deriving the split from the command string — a
+ *   re-derivation is the "second program that merely looks like the first" trap this
+ *   file's consumer (lib/error-recall-core.mjs) is structured to avoid.
  */
 export function planErrorRecall(cmd, response) {
   const { cmdWords, errWords } = collectErrorTerms(cmd, response);
   if (errWords.length === 0) return null;
-  return { terms: [...cmdWords, ...errWords].slice(0, ERROR_RECALL_MAX_TERMS) };
+  const terms = [...cmdWords, ...errWords].slice(0, ERROR_RECALL_MAX_TERMS);
+  // Intersect with the CAPPED list: a term the cap dropped is not in the query, so
+  // reporting it as an error term would have the surface rank on a word it never
+  // matched on.
+  const kept = new Set(terms);
+  return {
+    terms,
+    cmdWords: cmdWords.filter((t) => kept.has(t)),
+    errWords: errWords.filter((t) => kept.has(t)),
+  };
 }
 
 // ─── File Paths ──────────────────────────────────────────────────────────────

package/hook.mjs

@@ -49,6 +49,7 @@ import { readFastSummarySource, insertFastSummary, FAST_SUMMARY_LIMITS } from '.
 import { formatHookError } from './lib/native-binding-hint.mjs';
 import { recordHookError } from './lib/hook-telemetry.mjs';
 import { queueHookContext, queueHookSystemMessage, flushHookStdout } from './lib/hook-stdout.mjs';
+import { shouldRecallOnFailure } from './lib/tool-refusal.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
 import { cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, resolveDefaultMaintainOps, markAutoCompressible, selectFuzzyDedupeIds, stampDedupSuperseded, hardDeleteCandidateCount, purgeStale, recoverOrphanedChildren, recoverBuriedLessons, sweepDeferredWorkOrphans } from './lib/maintain-core.mjs';
 import { snapshotDb } from './lib/db-backup.mjs';
@@ -483,7 +484,18 @@ async function handlePostToolUse() {
 
 // ─── Error-Triggered Recall (Tier 2 G) ─────────────────────────────────────
 
-function triggerErrorRecall(db, toolInput, response) {
+/**
+ * @param {object} db Open handle.
+ * @param {object} toolInput The failed tool's input (needs `.command`).
+ * @param {string} response The failure text.
+ * @param {{eventName?: string, metricEvent?: string}} [opts] Which hook event this is
+ *   answering. The envelope carries exactly one hookEventName and the host rejects a
+ *   mismatch, so the PostToolUseFailure path MUST pass its own — defaulting silently
+ *   would emit a PostToolUse envelope from a PostToolUseFailure hook.
+ */
+function triggerErrorRecall(db, toolInput, response, opts = {}) {
+  const eventName = opts.eventName || 'PostToolUse';
+  const metricEvent = opts.metricEvent || 'error_recall';
   try {
     const project = inferProject();
 
@@ -510,7 +522,7 @@ function triggerErrorRecall(db, toolInput, response) {
       // G13: this surface feeds the citation denominator but had zero metering —
       // the G8 gate change (isError→isHardError) could not be volume-verified
       // from metrics. Counter only; no latency (query is bundled in the hook).
-      recordMetric(join(RUNTIME_DIR, '..'), { event: 'error_recall', returned: rows.length });
+      recordMetric(join(RUNTIME_DIR, '..'), { event: metricEvent, returned: rows.length });
       // MED-3 (full audit 2026-07-16): go through the envelope, NOT raw stdout —
       // a raw multi-line write corrupts a co-emitted episode-flush receipt.
       // The follow-up correction (2026-08-17): "two separate JSON lines each parse
@@ -518,11 +530,118 @@ function triggerErrorRecall(db, toolInput, response) {
       // flushEpisode in one handlePostToolUse, and two documents make the parser
       // fall back to plain text — which the renderer drops entirely for
       // PostToolUse. Both receipts vanished. Queue; one envelope is written at exit.
-      queueHookContext('PostToolUse', out);
+      queueHookContext(eventName, out);
     }
   } catch (e) { debugCatch(e, 'triggerErrorRecall'); }
 }
 
+/**
+ * PostToolUseFailure — the event that carries tool calls the HOST judged failed (D#170).
+ *
+ * WHY A SECOND ENTRY POINT AT ALL. `PostToolUse` does not fire for a failed tool call;
+ * Claude Code routes those here. Registering only `PostToolUse` therefore made this
+ * plugin blind to every host-flagged failure, and the only "failures" error-recall ever
+ * saw were commands that exited 0 while printing error-ish text — the classic shape
+ * being `cmd 2>&1 | tail`, where the pipe launders a failure into a success. Verified on
+ * the 2.1.241 bundle (the event and its schema) and by live probe (two genuinely failing
+ * Bash calls, one with a full stack frame, left zero trace in the episode buffer and the
+ * events table while the successful calls either side were recorded).
+ *
+ * THE PAYLOAD IS NOT PostToolUse'S. There is no `tool_response`; the failure text is in
+ * `error`, and `is_interrupt` marks a user cancellation. Reading `tool_response` here
+ * would find undefined and silently do nothing — which is exactly how this class of
+ * wiring bug stays invisible, so the field names are asserted in the tests.
+ *
+ * DELIBERATELY NARROWER THAN THE EVENT. Only `Bash` (this surface queries on a command
+ * plus its output; no other tool has that shape), only when the failure came from a
+ * PROGRAM rather than from the agent's own tool chain (lib/tool-refusal.mjs — 68.9% of
+ * host-flagged failures on the maintainer's machine were guardrails working), and NOT
+ * feeding the episode buffer. That last exclusion is scope, not oversight: episode
+ * entries flow into LLM summarisation and the bugfix save-nudge, whose behaviour under a
+ * sudden influx of failures has not been measured, and this change is already worth a
+ * 3.5x increase in this surface's firing volume.
+ *
+ * NO `isHardError` GATE HERE, AND THAT IS THE POINT — stated because review found it
+ * unwritten and it is a real semantic difference between the two entry points. On the
+ * PostToolUse path the host says nothing about success, so `isHardError` has to GUESS
+ * from vocabulary whether a command failed; here the host has already ruled, and
+ * re-deriving its verdict from the text would only discard cases. The measurable
+ * consequence: `Segmentation fault (core dumped)` and a Rust `panicked at` both score
+ * `isHardError === false` (the first has no error word, the second loses on `\bpanic\b`'s
+ * word boundary), so until this event they could not reach term extraction at all. They
+ * can now. That is the coverage this event was wired for, not an oversight — but it does
+ * mean ERROR_NAMER_RE's `SIG…`/`panicked` alternatives went live here first.
+ *
+ * Off switch: CLAUDE_MEM_ERROR_RECALL_ON_FAILURE=off.
+ */
+async function handlePostToolFailure() {
+  if (String(process.env.CLAUDE_MEM_ERROR_RECALL_ON_FAILURE || '').toLowerCase() === 'off') return;
+
+  let raw;
+  try { raw = await readStdin(); } catch { return; }
+  let hookData;
+  try { hookData = JSON.parse(raw.text); } catch { return; }
+
+  const { tool_name, tool_input, error, is_interrupt } = hookData || {};
+  // The manifest matcher already scopes this to Bash. Re-checking is not redundancy for
+  // its own sake: install.mjs writes a SECOND registration into the user's settings.json,
+  // and a hand-edited matcher there would otherwise hand this path an Edit or a Read.
+  //
+  // A payload whose SHAPE is wrong is recorded, not just dropped. Tests pin the field
+  // names against a payload we construct; they cannot see the host renaming `error` or
+  // changing `tool_name`'s type, and this whole path fails silently by design — the
+  // v3.60 binding outage ran four days on exactly that combination, and hook-errors/ was
+  // the only window that would have shown it. Volume is bounded by the recorder's
+  // 14-day retention and one short line per fire.
+  if (tool_name !== undefined && typeof tool_name !== 'string') {
+    recordHookError(
+      'post-tool-failure:tool_name-type',
+      new TypeError(`tool_name is ${Array.isArray(tool_name) ? 'array' : typeof tool_name}, expected string`),
+      RUNTIME_DIR,
+    );
+    return;
+  }
+  if (tool_name !== 'Bash') return;
+  if (error !== undefined && typeof error !== 'string') {
+    recordHookError(
+      'post-tool-failure:error-type',
+      new TypeError(`error is ${typeof error}, expected string — host payload shape may have changed`),
+      RUNTIME_DIR,
+    );
+    return;
+  }
+
+  const verdict = shouldRecallOnFailure({ error, is_interrupt });
+  if (!verdict.ok) return;
+
+  const toolInput = typeof tool_input === 'string' ? tryParseJson(tool_input) : (tool_input || {});
+  if (typeof toolInput?.command !== 'string' || !toolInput.command) return;
+
+  let db = null;
+  try {
+    db = openDb();
+    if (!db) return;
+    // Same selection, same rendering, same core as the PostToolUse path — only the event
+    // name on the envelope differs. A second copy of the query here is the twin-drift
+    // defect this project keeps paying for.
+    triggerErrorRecall(db, toolInput, error, {
+      eventName: 'PostToolUseFailure',
+      // A separate counter, so the volume this event adds is readable on its own rather
+      // than merged into the existing surface's total. The citation funnel deliberately
+      // keeps ONE `error_recall` surface: these are the same injections to the model, and
+      // splitting the cite-rate denominator would make both halves too small to read.
+      metricEvent: 'error_recall_failure',
+    });
+  } catch (e) {
+    debugCatch(e, 'handlePostToolFailure');
+  } finally {
+    // No flushHookStdout() here: the single flush after the event switch owns writing
+    // the envelope, and two flush points is how a process ends up emitting two JSON
+    // documents — the degradation that made BOTH receipts vanish in v3.68.
+    if (db) try { db.close(); } catch {}
+  }
+}
+
 // ─── Stop Handler ───────────────────────────────────────────────────────────
 
 async function handleStop() {
@@ -1983,6 +2102,8 @@ function normalizeToolResponse(toolResponse) {
 try {
   switch (event) {
     case 'post-tool-use':    await handlePostToolUse(); break;
+    // Host-flagged tool failures arrive on their own event; PostToolUse never sees them.
+    case 'post-tool-failure': await handlePostToolFailure(); break;
     case 'session-start':    await handleSessionStart(); break;
     case 'pre-compact':      await handlePreCompactDispatch(); break;
     case 'stop':             await handleStop(); break;

package/hooks/hooks.json

@@ -84,6 +84,18 @@
         ]
       }
     ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-launcher.mjs\" hook.mjs post-tool-failure",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "matcher": "*",

package/install.mjs

@@ -718,6 +718,19 @@ const memPostToolRecall = {
   }]
 };
 
+// D#170. A SEPARATE event from PostToolUse, not a variant of it: Claude Code does not
+// fire PostToolUse for a tool call it judged failed, so without this registration the
+// plugin never sees a single host-flagged failure. Matched on Bash alone — the surface
+// it feeds queries on a command plus its output, and no other tool has that shape.
+const memPostToolFailure = {
+  matcher: 'Bash',
+  hooks: [{
+    type: 'command',
+    command: nodeHook('hook.mjs', 'post-tool-failure'),
+    timeout: 5
+  }]
+};
+
 const memSessionStart = {
   matcher: 'startup|clear|compact',
   hooks: [{
@@ -819,6 +832,7 @@ const memPreAgentInject = {
 const hookConfigs = {
   PreToolUse: [memPreToolRecall, memPreSkillBridge, memPreAgentInject],
   PostToolUse: [memPostToolUse, memPostToolRecall],
+  PostToolUseFailure: [memPostToolFailure],
   PreCompact: [memPreCompact],
   SessionStart: [memSessionStart],
   Stop: [memStop],

package/lib/citation-tracker.mjs

@@ -20,9 +20,65 @@ import { readTranscriptEntries } from './transcript-scan.mjs';
 import { TASK_IMPERATIVE_PREFIX } from './task-imperative.mjs';
 
 import { DAY_MS } from './time-constants.mjs';
+/**
+ * The ONE caliber for an observation id appearing in text. Bounded to 1-7 digits to
+ * skip URL fragments, markdown anchors, etc.
+ *
+ * Exported because the offline benchmarks re-derive production's numbers from the same
+ * transcripts, and each had hand-copied its own: `benchmark/cite-recall.mjs` scanned
+ * citations with `{2,6}` while its OWN injected denominator used `{1,7}`, and
+ * `efficacy-observational.mjs` / `adoption-replay.mjs` had a third and fourth caliber
+ * (`{2,6}` / `{2,7}`). A denominator wider than its numerator counts an id as
+ * injected-never-cited that the numerator structurally cannot see, which biases the
+ * measured cite-rate DOWN — and nothing errors when it happens.
+ *
+ * Measured live impact at the time this was unified (2026-08-24, 3692 rows, ids 1..10834):
+ * exactly ZERO. The only ids outside `{2,6}` are four 1-digit rows, and all four have
+ * injection_count = 0, so they never entered a denominator; there are no 7-digit ids.
+ * This is a latent-class fix, not a correction to any published number — do not
+ * re-attribute past readings to it.
+ */
+export const OBS_ID_DIGITS = '\\d{1,7}';
+
+/**
+ * A fresh global matcher for a bare `#NN` citation.
+ *
+ * Returned fresh per call rather than shared: a `/g` regex carries `lastIndex`, so one
+ * exported instance reused by two scanners silently starts mid-string in whichever one
+ * runs second.
+ */
+export function citationIdRe() {
+  return new RegExp(`#(${OBS_ID_DIGITS})\\b`, 'g');
+}
+
+/**
+ * Caliber for an id scraped from UNANCHORED text that is then treated as an INJECTED
+ * (denominator) set.
+ *
+ * `citationIdRe()` above is a NUMERATOR caliber. On the numerator side a spurious `#1`
+ * costs nothing, because a cited id only counts once it intersects an injected set that
+ * WAS anchored — every injected-side extractor in this module matches a row shape
+ * (`INJECTED_ROW_RE`, `FYI_LINE_ID_RE`, `UPS_ID_RE`, `SUBAGENT_INJECT_ID_RE`). On the
+ * denominator side nothing anchors it, so a prose `#1` is a false positive by
+ * construction — it inflates "injected, never cited" and biases the measured rate DOWN.
+ *
+ * The v3.80.0 pre-tag review caught this concretely: pointing
+ * `benchmark/adoption-replay.mjs` at `citationIdRe()` pulled `#1` and `#2` out of a
+ * subagent prompt discussing fixture rows ("with `#1` superseded by `#2` …") straight into
+ * `injectedIds`, on a real transcript. Excluding 1-digit ids costs nothing measurable —
+ * the four 1-digit rows in the live corpus have `injection_count = 0` — and removes the
+ * commonest prose collision.
+ *
+ * This is a stopgap for a caliber symptom, NOT a fix for the cause. The cause is that
+ * adoption-replay scrapes a whole prompt where it should match injected ROWS, the way
+ * production does. Do not reach for this anywhere else; anchor instead.
+ */
+export function unanchoredInjectedIdRe() {
+  return new RegExp('#(\\d{2,7})\\b', 'g');
+}
+
 // `#123` / `#45678` at a word boundary — matches the CLAUDE.md cite pattern.
-// Bounded to 1-7 digits to skip URL fragments, markdown anchors, etc.
-const CITATION_RE = /#(\d{1,7})\b/g;
+const CITATION_RE = citationIdRe();
 
 /**
  * Parse a Claude Code transcript .jsonl and extract unique observation IDs
@@ -147,7 +203,7 @@ export function bumpCitationAccess(db, ids, project) {
 // Matches a pre-tool-recall / error-recall lesson line: `  #NN [type] body...`.
 // Bounded type list mirrors observations.type CHECK + the events table's allowed
 // event_type values these surfaces can emit.
-const INJECTED_RE = /#(\d{1,7})\s+\[(bugfix|decision|change|discovery|feature|refactor|lesson)\]/g;
+const INJECTED_RE = new RegExp(`#(${OBS_ID_DIGITS})\\s+\\[(bugfix|decision|change|discovery|feature|refactor|lesson)\\]`, 'g');
 // Line-anchored variant: a genuine injected ROW begins (after its short indent) with
 // `#NN [type]`. pre-tool-recall AND error-recall inline a lesson_learned body into the
 // row; a body that quotes another obs ("same as #1234 [decision]") must NOT count as
@@ -217,7 +273,7 @@ function eachHookAttachment(transcriptPath, fn, opts = {}) {
 // like "see (#999)" doesn't pollute the injected set (would streak-uncite an
 // obs we never actually displayed as a top-level entry).
 const UPS_LINE_PREFIX = '- [';
-const UPS_ID_RE = /\(#(\d{1,7})\)/g;
+const UPS_ID_RE = new RegExp(`\\(#(${OBS_ID_DIGITS})\\)`, 'g');
 // Quote-normalized (see normalizeHookCommand): real recorded command is
 // `node "/abs/hook.mjs" user-prompt` → normalized to `node /abs/hook.mjs user-prompt`.
 const UPS_COMMAND_SUFFIX = 'hook.mjs user-prompt';
@@ -230,7 +286,7 @@ const UPS_COMMAND_SUFFIX = 'hook.mjs user-prompt';
 const FYI_HEADER = '[mem] FYI — Related memories';
 // Anchored at line start so `P#NN` past-question rows (user_prompts, different id
 // space) and any `#NN` inside lesson text are NOT matched.
-const FYI_LINE_ID_RE = /^#(\d{1,7})\s/;
+const FYI_LINE_ID_RE = new RegExp(`^#(${OBS_ID_DIGITS})\\s`);
 
 /**
  * The injection FACES memory can reach the model through, as stored in
@@ -569,7 +625,7 @@ export function unionSurfaces(bySurface) {
 const SUBAGENT_INJECT_MARKER = /surfaced by your operator's claude-mem-lite/;
 // Row-anchored to the `#NN — ` tag so a #NN quoted inside the lesson body does NOT enter
 // the injected set — same discipline as INJECTED_ROW_RE for the attachment surfaces.
-const SUBAGENT_INJECT_ID_RE = /^\s{0,4}#(\d{1,7})\s+—/;
+const SUBAGENT_INJECT_ID_RE = new RegExp(`^\\s{0,4}#(${OBS_ID_DIGITS})\\s+—`);
 
 /**
  * Extract observation ids injected into a subagent's PROMPT by pre-agent-inject.js

package/lib/cite-back-hint.mjs

@@ -15,6 +15,9 @@ import { basename, join } from 'path';
 import { readFileSync } from 'fs';
 import { readTranscriptEntries } from './transcript-scan.mjs';
 import { EDIT_TOOLS } from '../utils.mjs';
+// One caliber for `#NN`. citation-tracker.mjs does NOT import this module, so the edge
+// is acyclic.
+import { citationIdRe } from './citation-tracker.mjs';
 
 const MAX_FILES = 2;
 
@@ -269,7 +272,9 @@ export function loadCiteBackForEpisode(episode, runtimeDir) {
 // #NN. The Stop handler unions these into the cited set passed to
 // applyCitationDecay (lib/citation-tracker.mjs), so acting on a lesson promotes
 // it and lifts the project's adoption rate. Returns an empty set on missing path.
-const CITE_BACK_ID_RE = /#(\d{1,7})\b/g;
+// The ids collected here are unioned into the SAME cited set applyCitationDecay reads,
+// so this caliber must be the extractor's own — imported, not a sixth hand-copy.
+const CITE_BACK_ID_RE = citationIdRe();
 
 export function extractCiteBackSignals(transcriptPath) {
   const ids = new Set();

package/lib/error-recall-core.mjs

@@ -127,15 +127,26 @@ const ERROR_RECALL_HALF_LIFE_MS = '1209600000.0';
  *   (decay reference) and @floor (|bm25| minimum). Named rather than positional
  *   so the binding cannot silently renumber when the statement is rearranged.
  */
-export function errorRecallSql(limit = ERROR_RECALL_LIMIT) {
-  // Number.isFinite before trunc: `Number('Infinity')` is a number and truncates to
-  // Infinity, which interpolates as `LIMIT Infinity` and throws at prepare(). Not an
-  // injection (every string form coerces to the default) but a crash where a fallback
-  // belongs.
+/**
+ * The row cap, coerced. ONE body, because the SQL builder and the rerank's control flow
+ * both need it and a second copy let them disagree: at `limit: 0` the rerank compared
+ * against the raw value, short-circuited its fallback and became a filter, while the SQL
+ * had already fallen back to 3.
+ *
+ * Number.isFinite before trunc: `Number('Infinity')` is a number and truncates to
+ * Infinity, which interpolates as `LIMIT Infinity` and throws at prepare(). Not an
+ * injection (every string form coerces to the default) but a crash where a fallback
+ * belongs.
+ */
+function sanitizeErrorRecallLimit(limit) {
   const asNum = Number(limit);
-  const n = Number.isFinite(asNum) && asNum >= 1
+  return Number.isFinite(asNum) && asNum >= 1
     ? Math.max(1, Math.trunc(asNum))
     : ERROR_RECALL_LIMIT;
+}
+
+export function errorRecallSql(limit = ERROR_RECALL_LIMIT) {
+  const n = sanitizeErrorRecallLimit(limit);
   // No floor in the SQL: the gate is SET-LEVEL and lives in selectErrorRecall. See
   // its docblock for why. This statement is the pre-floor one plus a bm25_raw column.
   return `
@@ -183,6 +194,40 @@ export function errorRecallFtsQuery(terms) {
   return (terms || []).map((t) => `"${String(t).replace(/"/g, '""')}"`).join(' OR ');
 }
 
+/**
+ * The ERROR-FIRST form of the same expression: a row must carry at least one term that
+ * came from the FAILURE, while every term — command words included — stays in the
+ * expression so bm25 still sums their contribution.
+ *
+ * The redundant-looking second clause is the point. Dropping command words from the
+ * QUERY was measured against the live DB in D#136 and regressed two of five replays:
+ * `database` and `vitest` were carrying domain anchoring, not noise. This keeps them
+ * scoring while denying them the power to admit a row on their own.
+ *
+ * Module-private on purpose: selectErrorRecall is the only caller, and the tests assert
+ * on the expression it REPORTS (`errorFirstQuery`) rather than importing the builder —
+ * a guard through the real path beats one through a side door. Exporting it would add a
+ * name to the knip baseline for no consumer (the #9675 precedent).
+ *
+ * @returns {string|null} null when there is no error term to require.
+ */
+function errorRecallErrorFirstQuery(terms, errWords) {
+  if (!errWords || !errWords.length) return null;
+  const or = (list) => list.map((t) => `"${String(t).replace(/"/g, '""')}"`).join(' OR ');
+  return `(${or(errWords)}) AND (${or(terms)})`;
+}
+
+/**
+ * Rerank kill-switch. Default ON — see selectErrorRecall for the measurement.
+ * `CLAUDE_MEM_ERROR_RECALL_RERANK=off` restores the flat-OR ordering exactly.
+ *
+ * Module-private for the same reason as the builder above; the switch is exercised
+ * end-to-end through selectErrorRecall in the test suite, which is where it has to work.
+ */
+function errorRecallRerankEnabled() {
+  return String(process.env.CLAUDE_MEM_ERROR_RECALL_RERANK || '').toLowerCase() !== 'off';
+}
+
 /**
  * Decide whether error-recall fires, and select its rows.
  *
@@ -219,7 +264,69 @@ export function selectErrorRecall(db, {
   // one. v3.61.0 shipped an unscaled floor and injected 0/8 on fresh installs.
   const effective = base > 0 ? base * corpusFloorScale(db) : 0;
 
-  const rows = db.prepare(errorRecallSql(limit)).all({ q: ftsQuery, project, now });
+  const stmt = db.prepare(errorRecallSql(limit));
+
+  // ── ERROR-FIRST RERANK (D#167) ──────────────────────────────────────────────
+  // The flat OR admits a row on ANY term, so a memory that merely shares the command's
+  // vocabulary competes for the three slots on equal footing with one that names the
+  // failure. Measured on the live DB over 52 real failing commands (with their real
+  // stderr, extracted from 1110 transcripts) x 15 projects, ~715 firing cases. Rows that
+  // match NO error term at all, and cases whose TOP-1 row is one of those — the top row
+  // being the one whose lesson_learned is inlined verbatim into the model's context:
+  //
+  //                                          cmd-only rows      cmd-only at TOP-1
+  //   v3.78.0 (flat OR, banner terms)        764/1947  39.2%    302/714   42.3%
+  //   flat OR + ERROR_NAMER_RE               780/1941  40.2%    301/715   42.1%
+  //   + error-first rerank  (shipped)        434/1941  22.4%    154/715   21.5%
+  //
+  // Read the middle row before reaching for the term fix alone: naming the failure did
+  // NOT reduce command-vocabulary injection, it nudged it up. Better terms are more
+  // specific, so they match fewer rows, so the flat OR has MORE room to fill the three
+  // slots with whatever shares the command's words. Terms and ranking are two
+  // independent defects and only the pair moves this number.
+  //
+  // The obvious alternative — make the error term MANDATORY and stop there — was
+  // measured too: 1499 rows (−22.8%) and 157 of 715 cases (22.0%) injecting nothing,
+  // with the loss concentrated in small projects. That is the magnitude floor's failure
+  // mode wearing a different hat (see errorRecallBm25Floor above), so it is not what
+  // ships. This REORDERS and never removes: rows that only match the command fall to
+  // slots 2-3 instead of being deleted, and when NOTHING in the project matches an
+  // error term the result is byte-identical to the flat OR. The residual ~21.5% is
+  // essentially that set — verified, not assumed: of the cases the mandatory form
+  // silences, 0 had a base set containing an error-matching row.
+  //
+  // Cost is one extra query only when the primary comes up short of the cap. D#136
+  // rejected this shape on the grounds that "the primary always filled its LIMIT 3" —
+  // true of the five cases it replayed, false at 715, where the primary leaves hundreds
+  // of slots for the fallback to fill.
+  let rows;
+  const errorFirst = errorRecallRerankEnabled()
+    ? errorRecallErrorFirstQuery(plan.terms, plan.errWords)
+    : null;
+  const primary = errorFirst ? stmt.all({ q: errorFirst, project, now }) : [];
+  // Compare against the SANITIZED cap, not the raw argument. errorRecallSql coerces
+  // (finite, >= 1, else the default) before interpolating, so the raw value and the one
+  // the SQL used can disagree — and at `limit: 0` the raw comparison short-circuits the
+  // fallback, turning the rerank into the filter this face deliberately rejected.
+  // Unreachable from the hook (it passes no limit), found by fuzzing in review.
+  const cap = sanitizeErrorRecallLimit(limit);
+  if (primary.length >= cap) {
+    rows = primary;
+  } else {
+    // Fallback fills the remaining slots from the unchanged flat-OR result, skipping
+    // what the primary already returned. `rows` therefore has the same LENGTH as the
+    // pre-rerank behaviour in every case, including the case where primary is empty.
+    const flat = stmt.all({ q: ftsQuery, project, now });
+    rows = [...primary];
+    for (const r of flat) {
+      if (rows.length >= cap) break;
+      // The id check is load-bearing, not defensive: the error-first match set is a
+      // SUBSET of the flat one, so every primary row appears again in `flat`. Without
+      // this, the top row is injected twice and one of three slots is wasted. Review
+      // measured the mutant: ids 1,2,3 -> 1,1,2.
+      if (!rows.some((x) => x.id === r.id)) rows.push(r);
+    }
+  }
 
   // SET-LEVEL gate, the shape UPS already uses (read the top row; on failure drop the
   // WHOLE set) rather than filtering row by row.
@@ -247,10 +354,49 @@ export function selectErrorRecall(db, {
   // switched to max(): UPS gates on `ftsRows[0]` the same way, and one face quietly
   // disagreeing with the other about what "the top hit" means is worse than the
   // occasional veto. Stated here because the comment above used to claim otherwise.
+  //
+  // With the rerank above, `rows[0]` is the top row of the ERROR-FIRST result whenever
+  // one exists. The gate is therefore applied to the row it is actually about — the
+  // best row that mentions the failure — instead of to whatever the flat OR floated up.
+  //
+  // AND IT ALSO CHANGES THE SCALE, which the first version of this comment missed and
+  // pre-release review caught. `(errWords) AND (allTerms)` repeats every error term, and
+  // FTS5's bm25() sums over phrase instances, so a PRIMARY row's |bm25_raw| is
+  // systematically larger than the same row's flat-OR score — measured on one row in an
+  // in-memory index, 1.334 -> 1.779. Rows in the same result set can therefore carry two
+  // different scales (primary rows error-first, fallback rows flat).
+  //
+  // What that costs: CALIBRATED_ERROR_RECALL_BM25_FLOOR = 10.5 was derived from the
+  // PRE-RERANK distribution — the gap between filler p75 10.99 and relevant min 10.93 in
+  // the table above. Re-running `benchmark/error-recall-suite.mjs --scores` with the
+  // rerank ON moves filler p75 to 20.27 and relevant min to 21.87, so 10.5 no longer
+  // sits in any gap. The drift is toward a LOOSER gate on sets that have a primary and
+  // an unchanged one on sets that do not (empty primary keeps the flat scale), which may
+  // be an improvement; nothing has measured it.
+  //
+  // This is documented rather than fixed because the floor's default is 0 — nothing
+  // ships gated. Anyone switching it on must re-derive the constant with the rerank in
+  // whatever state they intend to run, NOT reuse the table above.
   if (effective > 0 && rows.length && Math.abs(rows[0].bm25_raw) < effective) {
     return {
-      rows: [], terms: plan.terms, ftsQuery, floor: effective, suppressed: rows.length,
+      rows: [],
+      terms: plan.terms,
+      ftsQuery,
+      // Reported here too: this is the path where knowing which expression ranked the
+      // row the gate just rejected matters MOST, and the first version omitted it.
+      errorFirstQuery: errorFirst,
+      floor: effective,
+      suppressed: rows.length,
     };
   }
-  return { rows, terms: plan.terms, ftsQuery, floor: effective, suppressed: 0 };
+  return {
+    rows,
+    terms: plan.terms,
+    ftsQuery,
+    // The expression that actually ranked the set, so the calibration suite and any
+    // future debugging read the query that ran rather than the one that would have.
+    errorFirstQuery: errorFirst,
+    floor: effective,
+    suppressed: 0,
+  };
 }

package/lib/hook-stdout.mjs

@@ -27,6 +27,40 @@
 let parts = [];
 let queuedEvent = null;
 let systemParts = [];
+let queuedInput = null;
+
+/** Emit the noisy drop notice. stderr is safe: the host never parses it as the envelope. */
+function warnDrop(deps, msg) {
+  const warn = deps.warn || ((m) => { try { process.stderr.write(m); } catch { /* never block on a warning */ } });
+  warn(msg);
+}
+
+/**
+ * Claim this process's single hookEventName, or refuse the contribution.
+ *
+ * Mixed event names cannot be merged — Claude Code throws when
+ * hookSpecificOutput.hookEventName does not match the event it dispatched.
+ * In practice one process serves one event; keep the first and drop the
+ * stragglers rather than emit an envelope the host rejects outright.
+ *
+ * The drop is NOISY on purpose. It is unreachable today (all call sites are
+ * event-consistent), but flushEpisode's hookEventName DEFAULTS to 'PostToolUse',
+ * so a future caller that omits the argument would both mis-tag its receipt and
+ * have it swallowed without a trace. Silently vanishing work is this repo's
+ * most-repeated defect class.
+ *
+ * @returns {boolean} true when the caller may proceed.
+ */
+function claimEvent(hookEventName, what, deps) {
+  if (queuedEvent && queuedEvent !== hookEventName) {
+    warnDrop(deps, `[claude-mem-lite] hook-stdout: dropped a ${hookEventName} ${what} — this process `
+      + `already queued ${queuedEvent}, and one envelope carries exactly one hookEventName. `
+      + 'This is a wiring bug: the contribution is lost.\n');
+    return false;
+  }
+  queuedEvent = hookEventName;
+  return true;
+}
 
 /**
  * Queue a contribution to this process's single stdout envelope.
@@ -40,26 +74,40 @@ export function queueHookContext(hookEventName, text, deps = {}) {
   if (!hookEventName) return;
   const body = String(text ?? '').trim();
   if (!body) return;
-  // Mixed event names cannot be merged — Claude Code throws when
-  // hookSpecificOutput.hookEventName does not match the event it dispatched.
-  // In practice one process serves one event; keep the first and drop the
-  // stragglers rather than emit an envelope the host rejects outright.
-  //
-  // The drop is NOISY on purpose. It is unreachable today (all call sites are
-  // event-consistent), but flushEpisode's hookEventName DEFAULTS to 'PostToolUse',
-  // so a future caller that omits the argument would both mis-tag its receipt and
-  // have it swallowed without a trace. Silently vanishing work is this repo's
-  // most-repeated defect class; stderr is safe here because the host never parses it
-  // as the envelope.
-  if (queuedEvent && queuedEvent !== hookEventName) {
-    const warn = deps.warn || ((m) => { try { process.stderr.write(m); } catch { /* never block on a warning */ } });
-    warn(`[claude-mem-lite] hook-stdout: dropped a ${hookEventName} contribution — this process `
-      + `already queued ${queuedEvent}, and one envelope carries exactly one hookEventName. `
-      + 'This is a wiring bug: the contribution is lost.\n');
+  if (!claimEvent(hookEventName, 'contribution', deps)) return;
+  parts.push(body);
+}
+
+/**
+ * Queue a `hookSpecificOutput.updatedInput` — a REPLACEMENT of the tool's input,
+ * not a contribution to it. PreToolUse is the only event whose schema carries one
+ * (2.1.241 bundle: `{hookEventName: "PreToolUse", permissionDecision?,
+ * permissionDecisionReason?, updatedInput?, additionalContext?}`), and that same
+ * schema is why this belongs here rather than in its own writer: a mutation and a
+ * context line may ride ONE envelope, so a hook that grew both would otherwise
+ * emit two documents and lose both (the v3.70.0 degradation this module exists for).
+ *
+ * FIRST writer wins, and a second is dropped noisily. Unlike additionalContext
+ * there is no merge: two callers each hand over a whole tool_input, so last-wins
+ * would silently discard the earlier mutation — the same vanishing-work shape
+ * claimEvent guards against.
+ *
+ * @param {string} hookEventName Event name for hookSpecificOutput.
+ * @param {object} input Replacement tool_input; non-objects and null are ignored.
+ * @param {{warn?: (msg: string) => void}} [deps]
+ * @returns {void}
+ */
+export function queueHookUpdatedInput(hookEventName, input, deps = {}) {
+  if (!hookEventName) return;
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return;
+  if (!claimEvent(hookEventName, 'updatedInput', deps)) return;
+  if (queuedInput) {
+    warnDrop(deps, '[claude-mem-lite] hook-stdout: dropped a second updatedInput — one envelope '
+      + 'replaces the tool input exactly once, and merging two whole inputs is not defined. '
+      + 'This is a wiring bug: the second mutation is lost.\n');
     return;
   }
-  queuedEvent = hookEventName;
-  parts.push(body);
+  queuedInput = input;
 }
 
 /**
@@ -93,24 +141,25 @@ export function queueHookSystemMessage(text) {
  * @returns {boolean} true when an envelope was written.
  */
 export function flushHookStdout(deps = {}) {
-  const hasContext = queuedEvent && parts.length > 0;
+  const hasContext = Boolean(queuedEvent) && parts.length > 0;
+  const hasInput = Boolean(queuedEvent) && queuedInput !== null;
   const hasSystem = systemParts.length > 0;
-  if (!hasContext && !hasSystem) return false;
+  if (!hasContext && !hasInput && !hasSystem) return false;
   const write = deps.write || ((s) => process.stdout.write(s));
   const envelope = { suppressOutput: true };
   if (hasSystem) envelope.systemMessage = systemParts.join('\n');
-  // Omitted entirely when there is no model-facing context: Stop's schema REJECTS a
-  // hookSpecificOutput block, and an envelope carrying only a user notice must not
-  // invent an event name to hang one on.
-  if (hasContext) {
-    envelope.hookSpecificOutput = {
-      hookEventName: queuedEvent,
-      additionalContext: parts.join('\n\n'),
-    };
+  // Omitted entirely when there is nothing addressed to the host's per-event block:
+  // Stop's schema REJECTS a hookSpecificOutput block, and an envelope carrying only a
+  // user notice must not invent an event name to hang one on.
+  if (hasContext || hasInput) {
+    envelope.hookSpecificOutput = { hookEventName: queuedEvent };
+    if (hasInput) envelope.hookSpecificOutput.updatedInput = queuedInput;
+    if (hasContext) envelope.hookSpecificOutput.additionalContext = parts.join('\n\n');
   }
   parts = [];
   queuedEvent = null;
   systemParts = [];
+  queuedInput = null;
   write(JSON.stringify(envelope) + '\n');
   return true;
 }
@@ -120,9 +169,15 @@ export function resetHookStdout() {
   parts = [];
   queuedEvent = null;
   systemParts = [];
+  queuedInput = null;
 }
 
 /** Test seam: what is queued right now. */
 export function peekHookStdout() {
-  return { hookEventName: queuedEvent, parts: [...parts], systemParts: [...systemParts] };
+  return {
+    hookEventName: queuedEvent,
+    parts: [...parts],
+    systemParts: [...systemParts],
+    updatedInput: queuedInput,
+  };
 }

package/lib/tool-refusal.mjs

@@ -0,0 +1,117 @@
+// Did this tool call fail because a PROGRAM failed, or because the agent's own
+// tool chain said no?
+//
+// WHY THIS EXISTS. Claude Code delivers host-flagged tool failures to the
+// `PostToolUseFailure` event (D#170), which is where error-recall gets its coverage of
+// real failures. But that event fires for EVERY failed call, and a large share of them
+// are not failures at all in the sense that matters here — they are guardrails working:
+// a §8 SAFETY hook denying an `rm -rf $VAR`, a sandbox refusing a syscall, a policy hook
+// steering a `grep` to the AST tool. Measured over 1110 transcripts, 558 of 810
+// host-flagged Bash failures (68.9%) were of that kind — one number, re-measured with the
+// shipped predicate after review found two irreconcilable figures in this file and the
+// CHANGELOG. Reproduce with `node benchmark/error-recall-live-replay.mjs --host-failures`,
+// which now buckets by the gate's own reason instead of lumping refusals with empties.
+//
+// Recalling a past lesson because a permission prompt was declined is noise by
+// construction, and on the lowest-cited injection surface in the system it is the kind of
+// noise that discredits the rest.
+//
+// THE ERROR DIRECTIONS ARE NOT SYMMETRIC, and the list below is tuned accordingly:
+//
+//   false "refusal"  → we stay silent on a real failure. Costs nothing beyond the
+//                      status quo, which is silence for every host-flagged failure.
+//   missed refusal   → we inject three memories about a denied permission prompt.
+//
+// So every entry is anchored on a tool-chain marker — a bracketed plugin tag, a spec
+// section marker, a sandbox syscall name — rather than a generic word like "denied" or
+// "permission", which real programs print constantly (`chmod`, `docker`, `sudo`, HTTP
+// 403 handlers).
+//
+// "NO ORDINARY PROGRAM EMITS THESE" IS TOO STRONG, AND REVIEW MEASURED IT. Over the same
+// 1110-transcript corpus, three sentinels appear in the stdout of SUCCESSFUL commands:
+// `[claudemd]` (21), `No such tool available` (10), `requested permission(s) to use` (7)
+// — mostly this repo's own test runners printing hook output. When such a runner FAILS,
+// the gate swallows a real failure. That is the cheap direction (see above), but the
+// claim is "anchored on a marker real programs rarely emit", not "never".
+//
+// Two of those three (`[claudemd]`, `requested permissions? to use`) had ZERO matches
+// among the 558 actual refusals in that corpus — they are speculative, covering hook
+// stacks other than this one, and today they pay only their false-positive cost. Kept
+// deliberately: a user running those hooks gets the protection, and the cost is silence
+// on a failure that was already silent before this event existed. Delete them if a
+// measurement ever shows them costing more than that.
+//
+// THIS RATIO IS ONE MACHINE'S PROFILE. 68.9% is what the maintainer's own hook stack
+// produces; a user with no policy hooks will see close to 0%. The filter is correctness
+// for whoever has those hooks, not a tuning constant — do not treat the percentage as a
+// property of the product.
+
+/**
+ * Sentinels that identify a refusal emitted by the agent's own tool chain.
+ * Ordered roughly by observed frequency; the array is small enough that order is
+ * cosmetic.
+ */
+export const REFUSAL_SENTINELS = [
+  // Sandbox / seccomp layers refusing to run the command at all.
+  /apply-seccomp: unshare\(/,
+  /sandbox\.excludedCommands/,
+  // Spec / policy hooks (claudemd and friends) denying a command by rule. Anchored on
+  // the SECTION MARKER at the start of the text, not on the one section that was found
+  // first: pre-release review scanned the same corpus and found the family is wider than
+  // `§8` — `§7 Ship-baseline` (a policy hook blocking `git push`), `§11 MEMORY.md`,
+  // `§10-V Specificity`, `§10-V prose scan`. The `§7` shape alone was 13 of 135 firing
+  // cases (9.6%), and it does not merely waste a slot: its own boilerplate becomes the
+  // query, so `git push` blocked by a red-CI rule injected three memories about
+  // statusline adoption. The other three shapes were silent only because
+  // planErrorRecall found no term in them — luck, not this gate.
+  //
+  // `§` followed by a digit at the very start of the failure text is a spec citation. No
+  // compiler, runtime or CLI opens its stderr that way.
+  /^\s*§\s*\d/,
+  /§\d[\w.-]*\s+[A-Z][\w-]*[^\n]{0,60}:\s/,
+  /\[claudemd\]/,
+  // Plugin hooks that deny-and-redirect rather than let the command run.
+  /\[code-graph\][^\n]{0,80}denied/i,
+  // Host-level refusals: the tool was not available in this context.
+  /No such tool available/i,
+  /\bis not available to you as the coordinator\b/i,
+  // The human said no. Not a program failure, and re-asking with a recalled memory
+  // attached is the wrong response to it.
+  /user doesn'?t want to (?:take this action|proceed)/i,
+  /requested permissions? to use/i,
+];
+
+/**
+ * @param {string} text The failure text (`error` on a PostToolUseFailure payload).
+ * @returns {boolean} true when the failure came from the tool chain, not the program.
+ */
+export function isToolChainRefusal(text) {
+  if (typeof text !== 'string' || !text) return false;
+  return REFUSAL_SENTINELS.some((re) => re.test(text));
+}
+
+/**
+ * Should error-recall run for this failed tool call?
+ *
+ * Three reasons to stay silent, each for a different kind of "this is not a program
+ * failure I can recall anything useful about":
+ *
+ *  - `is_interrupt` — the HOST's own flag for "the user stopped it". A cancelled
+ *    command has no failure to explain, and this is the one discriminator that comes
+ *    from the host rather than from pattern-matching its text.
+ *  - a tool-chain refusal (above).
+ *  - nothing to read: an empty or near-empty error string cannot produce query terms,
+ *    and the 10-character floor matches the one PostToolUse already applies to
+ *    `tool_response` so the two entry points do not disagree about what "no output"
+ *    means.
+ *
+ * @param {{error?: string, is_interrupt?: boolean}} payload
+ * @returns {{ok: boolean, reason?: string}}
+ */
+export function shouldRecallOnFailure(payload) {
+  if (payload?.is_interrupt === true) return { ok: false, reason: 'interrupt' };
+  const text = typeof payload?.error === 'string' ? payload.error : '';
+  if (text.length < 10) return { ok: false, reason: 'empty' };
+  if (isToolChainRefusal(text)) return { ok: false, reason: 'refusal' };
+  return { ok: true };
+}

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.78.0",
+  "version": "3.80.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.78.0",
+      "version": "3.80.0",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.26.0",
         "better-sqlite3": "^12.6.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.78.0",
+  "version": "3.80.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -92,6 +92,7 @@
     "lib/keyctx-marker.mjs",
     "lib/inject-search-core.mjs",
     "lib/error-recall-core.mjs",
+    "lib/tool-refusal.mjs",
     "lib/relevance-floor.mjs",
     "lib/get-core.mjs",
     "lib/browse-core.mjs",

package/scripts/post-tool-recall.js

@@ -17,6 +17,11 @@ import { existsSync, readFileSync } from 'fs';
 import { basename, join } from 'path';
 import { resolveDataDir } from '../lib/resolve-data-dir.mjs';
 import { recordHookError } from '../lib/hook-telemetry.mjs';
+// D#154: every envelope on this stdout goes through the one writer. This script has a
+// single emit today, so the change buys nothing on its own — it buys that a SECOND
+// emit added later merges instead of producing two JSON documents, which the host
+// parses as neither (lib/hook-stdout.mjs). Import-free module over no runtime deps.
+import { queueHookContext, flushHookStdout } from '../lib/hook-stdout.mjs';
 
 const SALIENCE_BIND = process.env.CLAUDE_MEM_SALIENCE === 'bind';
 
@@ -69,10 +74,8 @@ async function main() {
   for (const d of dropped.slice(0, 3)) {
     lines.push(`[mem] ⚠ your edit to ${basename(filePath)} dropped \`${d.token}\` flagged by #${d.obsId} — if intentional say so, else re-check before moving on.`);
   }
-  process.stdout.write(JSON.stringify({
-    suppressOutput: true,
-    hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: lines.join('\n') },
-  }));
+  queueHookContext('PostToolUse', lines.join('\n'));
+  flushHookStdout();
 }
 
 // No forced process.exit(0): main() consumes stdin to EOF (or early-returns without

package/scripts/pre-agent-inject.js

@@ -66,15 +66,28 @@ async function main() {
   const { ensureDb } = await import('../schema.mjs');
   const { inferProject } = await import('../utils.mjs');
   const { buildSubagentInjection } = await import('../hook-memory.mjs');
+  // D#154: single envelope writer. Deferred to this line, not hoisted to a static
+  // import, because the file's stated contract is that the default-off path costs one
+  // env check and nothing else — the deferral filed this as "shared module vs
+  // import-free fast path, pick one", but the script already resolves that conflict
+  // three lines up: dynamic import on the enabled path only. The fast path above is
+  // untouched.
+  const { queueHookUpdatedInput, flushHookStdout } = await import('../lib/hook-stdout.mjs');
 
   let db;
   try { db = ensureDb(); } catch (e) { await recordFailure('agent-inject:db-open', e); return; }
   try {
     const updatedInput = buildSubagentInjection(db, hook.tool_input, inferProject());
     if (updatedInput) {
-      process.stdout.write(JSON.stringify({
-        hookSpecificOutput: { hookEventName: 'PreToolUse', updatedInput },
-      }));
+      // Behaviour delta vs the hand-written envelope this replaced: it now carries
+      // top-level `suppressOutput: true`. Verified display-only in the 2.1.241 bundle —
+      // the field is documented "Hide stdout from transcript (default: false)" and is
+      // read at exactly one place, the transcript-render branch
+      // (`if (a6(he) && !he.suppressOutput && …)`); the updatedInput mutation is taken
+      // from the parsed hookSpecificOutput regardless. Hiding it is also the right
+      // audience call: this payload is the whole prompt echoed back, not a message.
+      queueHookUpdatedInput('PreToolUse', updatedInput);
+      flushHookStdout();
     }
   } catch (e) { await recordFailure('agent-inject:query', e); /* never break a dispatch */ } finally {
     try { db.close(); } catch { /* */ }

package/scripts/pre-skill-bridge.js

@@ -11,6 +11,9 @@ import { resolveDataDir } from '../lib/resolve-data-dir.mjs';
 // format-utils.mjs is import-free — pulling three defang helpers keeps this script
 // inside its "lightweight standalone" budget (no heavy transitive deps).
 import { neutralizeContextDelimiters, neutralizeSkillDelimiters, neutralizeSkillBridgeDelimiters } from '../format-utils.mjs';
+// D#154: single envelope writer. Also import-free (no runtime deps), so it stays
+// inside this script's "lightweight standalone" budget.
+import { queueHookContext, flushHookStdout } from '../lib/hook-stdout.mjs';
 
 // CLAUDE_MEM_DIR mirrors pre-tool-recall.js — one env var sandboxes everything.
 const DATA_DIR = resolveDataDir(process.env.CLAUDE_MEM_DIR);
@@ -110,13 +113,8 @@ try {
     } else {
       additionalContext = `<skill-bridge name="${safeName}" source="managed">\n${defang(content)}\n</skill-bridge>\n\nThis skill was loaded from the managed registry. Follow the instructions above.`;
     }
-    process.stdout.write(JSON.stringify({
-      suppressOutput: true,
-      hookSpecificOutput: {
-        hookEventName: 'PreToolUse',
-        additionalContext,
-      },
-    }));
+    queueHookContext('PreToolUse', additionalContext);
+    flushHookStdout();
   } catch (e) {
     // Silent failure — never block Skill tool, but record for self-observation.
     recordHookError('skill-bridge:query', e, RUNTIME_DIR, { skillName });

package/scripts/pre-tool-recall.js

@@ -19,6 +19,25 @@ import { shouldWarnReread, buildRereadWarning, readFileMeta } from '../lib/rerea
 import { recordMetric } from '../lib/metrics.mjs';
 import { presentIdents } from '../lib/lesson-idents.mjs';
 import { neutralizeContextDelimiters } from '../format-utils.mjs';
+// D#154: the one stdout writer. This script has THREE emit sites (Read→Edit ack,
+// repeated-read guard, lesson block) and they stay one document because each branch
+// process.exit()s before reaching the next.
+//
+// Be precise about what routing them through the queue does and does not buy, because an
+// earlier version of this comment claimed "a second write is now impossible by
+// construction" and that is FALSE (pre-tag review, v3.80.0): each site flushes
+// IMMEDIATELY after queueing, and the flush resets the queue — so queue→flush→queue→flush
+// emits two documents exactly like two raw writes would. Merging is a property of
+// DEFERRING the flush (what hook.mjs does with a single flush at the end of its dispatch),
+// not of using the queue.
+//
+// What it does buy: one construction site instead of three, so the "only the writer
+// assembles an envelope" invariant is checkable (tests/hook-script-stdout-contract.test.mjs),
+// and the merge is AVAILABLE to anyone who later defers the flush. The mutual exclusion
+// itself is still control flow — the process.exit(0) below.
+//
+// Import-free module, no runtime deps — nothing added to this script's load cost.
+import { queueHookContext, flushHookStdout } from '../lib/hook-stdout.mjs';
 // Recall queries the SAVE-path project, so this MUST produce the same string as the
 // save path. It used to be a hand-kept copy of the same 6 lines; that copy had already
 // drifted once (missing the process.env.PWD fallback, so a symlinked project dir
@@ -305,16 +324,11 @@ try {
       const wasReadMode = typeof entry === 'object' && entry.mode === 'read';
       if (!isRead && wasReadMode && seenIds.length > 0 && !SALIENCE_LEGACY) {
         const idList = seenIds.map(id => `#${id}`).join(', ');
-        process.stdout.write(JSON.stringify({
-          suppressOutput: true,
-          hookSpecificOutput: {
-            hookEventName: 'PreToolUse',
-            additionalContext: [
-              '[mem] PreToolUse recall — system-injected context, continue your planned action:',
-              `[mem] ⚠ Lessons ${idList} were shown when you Read ${basename(filePath)} — ${ACTIVE_DIRECTIVE}`,
-            ].join('\n'),
-          },
-        }));
+        queueHookContext('PreToolUse', [
+          '[mem] PreToolUse recall — system-injected context, continue your planned action:',
+          `[mem] ⚠ Lessons ${idList} were shown when you Read ${basename(filePath)} — ${ACTIVE_DIRECTIVE}`,
+        ].join('\n'));
+        flushHookStdout();
         cooldown[filePath] = { ...entry, mode: 'edit' };
         writeCooldown(cooldownPath, cooldown, isSessionScoped);
       } else if (isRead && !REREAD_GUARD_OFF && typeof entry === 'object' && entry.reread) {
@@ -322,16 +336,11 @@ try {
         // nudge to reuse what's already in context. Read-only; never throws.
         const meta = readFileMeta(filePath);
         if (shouldWarnReread(entry.reread, meta ? meta.mtimeMs : null, isFullRead, REREAD_MIN_TOKENS)) {
-          process.stdout.write(JSON.stringify({
-            suppressOutput: true,
-            hookSpecificOutput: {
-              hookEventName: 'PreToolUse',
-              additionalContext: [
-                '[mem] PreToolUse recall — system-injected context, continue your planned action:',
-                buildRereadWarning(basename(filePath), entry.reread.tokens),
-              ].join('\n'),
-            },
-          }));
+          queueHookContext('PreToolUse', [
+            '[mem] PreToolUse recall — system-injected context, continue your planned action:',
+            buildRereadWarning(basename(filePath), entry.reread.tokens),
+          ].join('\n'));
+          flushHookStdout();
           recordMetric(DATA_DIR, { event: 'reread_warn' }); // tier-1 firing counter (②)
         }
       }
@@ -605,13 +614,8 @@ try {
     }
 
     if (lines.length > 0) {
-      process.stdout.write(JSON.stringify({
-        suppressOutput: true,
-        hookSpecificOutput: {
-          hookEventName: 'PreToolUse',
-          additionalContext: lines.join('\n'),
-        },
-      }));
+      queueHookContext('PreToolUse', lines.join('\n'));
+      flushHookStdout();
     }
     // Cooldown applies on ALL branches (including silent-Read) so subsequent
     // calls on the same file in the same session don't re-query — preserving

package/source-files.mjs

@@ -153,6 +153,10 @@ export const SOURCE_FILES = [
   // injection) and by benchmark/error-recall-suite.mjs (offline calibration) — the
   // hook is the one that breaks on a missing manifest entry.
   'lib/error-recall-core.mjs',
+  // D#170: the PostToolUseFailure gate. hook.mjs imports it on the failure path and
+  // benchmark/error-recall-live-replay.mjs scores the SAME predicate, so a missing
+  // registration would ship a hook that cannot load its own filter.
+  'lib/tool-refusal.mjs',
   // Corpus-size ramp for absolute relevance floors. Imported by BOTH floor-bearing
   // injection faces: scripts/user-prompt-search.js (standalone hook) and
   // lib/error-recall-core.mjs. Missing here = UserPromptSubmit dies on auto-update.