@bglocation/tune-context 1.0.1 → 2.0.0

package/eval/adoption-report.mjs

@@ -11,9 +11,9 @@
 //     measures *behavior* (a proxy), not dollars. OTEL is the opt-in complement.
 //   • caveman can't be measured: it's an output style, not a tool call.
 import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { parseArgs } from 'node:util';
+import { claudeBaseDir } from '../hooks/config-dir.mjs';
 
 const DOCTRINE_SKILLS = new Set([
   'token-efficiency',
@@ -22,8 +22,39 @@ const DOCTRINE_SKILLS = new Set([
   'phase-workflow',
 ]);
 
+// Minimum distinct sessions before the verdict prints a hard ✓/✗ for the
+// cross-session levers (RAG, doctrine skills). Below it those judgments are
+// withheld ("insufficient signal") — one atypical session can't masquerade as a
+// trend. FROZEN WITH PO (2026-07-24, TASK-070): the model must not choose the
+// sample size at which its own sessions escape a verdict (anti-bias, TASK-062).
+// Churn is exempt — a within-session symptom, readable at any n.
+const MIN_SESSIONS_FOR_VERDICT = 3;
+
+// Two hook processes spawned for the SAME Claude Code event (a script
+// registered on both the plugin channel and settings.json — TASK-072) write
+// near-identical records milliseconds apart. FROZEN WITH PO (2026-07-25,
+// TASK-072; same anti-bias rule as MIN_SESSIONS_FOR_VERDICT above, TASK-062).
+//
+// Measured, not guessed: the gap distribution of same-key adjacent pairs in
+// the real 2026-07-24 log is cleanly bimodal —
+//   ≤14ms   : 159 pairs  (duplicate dispatch: 0,1,2,3,4,5,6,7,8,14ms)
+//   15-359ms:   0 pairs  (empty)
+//   ≥360ms  : 288 pairs  (continuous out to 10s — genuine repeated activity)
+// 100ms sits in the empty band, with maximum margin on both sides. A wider
+// window (the 1000ms first proposed here) reaches past the gap and swallows 8
+// real pairs — suppressing true churn, the exact failure this must avoid.
+const DUPLICATE_LOG_WINDOW_MS = 100;
+
+// Share of all records that must look like duplicate dispatches before the
+// churn verdict is withheld. FROZEN WITH PO (2026-07-25, TASK-072).
+// A doubled registration doubles EVERY event, so the signature is always a
+// large share (28% in the real log — 159 pairs of 559 records), never a
+// stray one. Requiring a share rather than a single pair keeps a couple of
+// coincidentally-fast events from silencing a whole log's verdict.
+const MIN_DUPLICATE_SHARE = 0.1;
+
 function defaultLogPath() {
-  return join(homedir(), '.claude', 'tune-context', 'adoption.jsonl');
+  return join(claudeBaseDir(), 'tune-context', 'adoption.jsonl');
 }
 
 const USAGE = `
@@ -33,7 +64,8 @@ Usage:
   adoption-report [--log <path>]
 
 Options:
-  --log <path>   Path to adoption.jsonl (default: ~/.claude/tune-context/adoption.jsonl)
+  --log <path>   Path to adoption.jsonl (default: <config dir>/tune-context/adoption.jsonl,
+                 where <config dir> is $CLAUDE_CONFIG_DIR if set, else ~/.claude)
   -h, --help     Show this help
 
 The log is written by the adoption-log.mjs PostToolUse hook (installed by
@@ -55,11 +87,53 @@ export function parseLog(text) {
   return out;
 }
 
+// Two (or more) records sharing (session, tool, lever, detail) within
+// DUPLICATE_LOG_WINDOW_MS of each other look like the SAME real event logged
+// twice — the signature of a hook registered on two channels at once
+// (TASK-072), not genuine repeated activity. Runs over every lever, not just
+// reads: a doubled hook doubles all of them equally.
+//
+// Records with an empty `detail` are SKIPPED, and skipped on both sides of
+// the ratio (see `assessable`). classify() gives every non-search Bash call
+// `detail: null`, so they all collapse onto a single key — and Claude Code
+// fires parallel tool calls within one turn, whose hooks land milliseconds
+// apart. Two genuinely different Bash commands would then read as a duplicate
+// pair. Measured on a clean simulated log, parallel Bash alone reached 13.9%
+// and tripped MIN_DUPLICATE_SHARE — a false "undecidable" over a perfectly
+// readable log. Restricting to detail-bearing records removes that vector
+// (0% on the same simulation) and still detects the real thing with a wide
+// margin: 28.9% on the frozen snapshot, 42.8% on a 1605-record live log.
+// Deduplicating the counts themselves stays out of scope (TASK-072): we
+// withhold the verdict, we don't guess which record was "real".
+function countDuplicateRegistrationPairs(records) {
+  const groups = new Map();
+  let assessable = 0;
+  for (const r of records) {
+    const t = Date.parse(r.ts);
+    if (Number.isNaN(t)) continue;
+    if (!r.detail) continue; // ambiguous key — see above
+    assessable++;
+    const key = `${r.session ?? ''}\u0000${r.tool ?? ''}\u0000${r.lever ?? ''}\u0000${r.detail}`;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(t);
+  }
+  let pairs = 0;
+  for (const times of groups.values()) {
+    times.sort((a, b) => a - b);
+    for (let i = 1; i < times.length; i++) {
+      if (times[i] - times[i - 1] <= DUPLICATE_LOG_WINDOW_MS) pairs++;
+    }
+  }
+  return { pairs, assessable };
+}
+
 export function aggregate(records) {
-  const search = { rag: 0, text: 0, glob: 0 };
+  const search = { rag: 0, grepTool: 0, shell: 0, glob: 0 };
   const skills = new Map();
   const subagents = new Map();
-  const readCounts = new Map(); // detail(file) -> times read
+  const readCounts = new Map(); // `${session}\u0000${file}` -> times read in that session
+  const sessionSet = new Set();
+  const cwdSet = new Set();
   let reads = 0;
   let edits = 0;
   let bash = 0;
@@ -68,12 +142,24 @@ export function aggregate(records) {
   const bump = (m, k) => m.set(k, (m.get(k) ?? 0) + 1);
 
   for (const r of records) {
+    if (r.session != null) sessionSet.add(r.session);
+    if (r.cwd != null) cwdSet.add(r.cwd);
     switch (r.lever) {
-      case 'search':
-        if (r.detail === 'rag') search.rag++;
-        else if (r.detail === 'glob') search.glob++;
-        else search.text++;
+      case 'search': {
+        // Split content search by TOOL — the only reliable "is this a codebase
+        // search?" signal. RAG (search_codebase) and the Grep tool are
+        // unambiguous code search; a grep/find inside Bash is usually plumbing
+        // (git … | grep, npm pack | grep) and must NOT compete with RAG. The
+        // record's `tool` field (set by the logger's buildRecord) carries this,
+        // so the split reinterprets existing logs — no format change, hook
+        // untouched. See TASK-069.
+        const tool = typeof r.tool === 'string' ? r.tool : '';
+        if (r.detail === 'rag' || tool.includes('search_codebase')) search.rag++;
+        else if (r.detail === 'glob' || tool === 'Glob') search.glob++;
+        else if (tool === 'Grep') search.grepTool++;
+        else search.shell++; // Bash-grep / ambiguous — reported, excluded from RAG-share
         break;
+      }
       case 'skill':
         bump(skills, r.detail ?? '(unknown)');
         break;
@@ -82,7 +168,11 @@ export function aggregate(records) {
         break;
       case 'read':
         reads++;
-        if (r.detail) bump(readCounts, r.detail);
+        // Key re-read churn by (session, file): the same file opened in two
+        // independent sessions is NOT lost context — only re-opening within one
+        // session is. Per-file-global inflates churn on multi-session logs
+        // (TASK-070). Single-session logs are unchanged (session is constant).
+        if (r.detail) bump(readCounts, `${r.session ?? ''}\u0000${r.detail}`);
         break;
       case 'edit':
         edits++;
@@ -95,8 +185,11 @@ export function aggregate(records) {
     }
   }
 
-  const contentSearches = search.rag + search.text;
-  const ragShare = contentSearches > 0 ? search.rag / contentSearches : null;
+  // RAG-share denominator is ONLY unambiguous code search (RAG + Grep tool);
+  // shell plumbing is excluded. null (not 0) when there was no code search at
+  // all — "n/a", not "✗ weak", so an all-plumbing log stops reading as failure.
+  const codeSearches = search.rag + search.grepTool;
+  const ragShare = codeSearches > 0 ? search.rag / codeSearches : null;
 
   // Re-read churn proxy: files opened more than once, and the extra opens beyond
   // the first. High churn hints the model is re-fetching context it lost — the
@@ -110,8 +203,17 @@ export function aggregate(records) {
     }
   }
 
+  // Both sides of this ratio come from the same population — only records
+  // whose duplicate status is actually assessable (see the function's note).
+  // Using records.length as the denominator instead would let a Bash-heavy
+  // log dilute a genuine doubling below the floor.
+  const { pairs: dedupPairs, assessable: dedupAssessable } = countDuplicateRegistrationPairs(records);
+  const dedupShare = dedupAssessable > 0 ? dedupPairs / dedupAssessable : 0;
+
   return {
     total: records.length,
+    sessions: sessionSet.size,
+    cwds: cwdSet.size,
     search,
     ragShare,
     skills: [...skills.entries()].sort((a, b) => b[1] - a[1]),
@@ -123,6 +225,24 @@ export function aggregate(records) {
     reReadFiles,
     redundantReads,
     reReadRate: reads > 0 ? redundantReads / reads : null,
+    // TASK-072: near-duplicate records within DUPLICATE_LOG_WINDOW_MS,
+    // consistent with a doubled hook registration. dedupSuspected gates the
+    // churn VERDICT line in formatReport — the raw counts above stay as-is
+    // (deduplicating them would be a guess, out of scope). Gated on a SHARE,
+    // not a single pair: doubling affects every event, so a genuine doubled
+    // log is always well past the floor, while a couple of coincidentally
+    // fast events must not silence an otherwise readable verdict.
+    dedupPairs,
+    dedupShare,
+    dedupSuspected: dedupShare >= MIN_DUPLICATE_SHARE,
+    // Doctrine applied as *method* — narrow reads, contracts-first edits,
+    // delegation — leaves no `Skill` tool call, so the skills verdict below
+    // can't see it (same blind spot the report already admits for caveman).
+    // Edits per read is a partial, honest echo of that method: editing without
+    // re-reading first is what narrow-read discipline looks like from the
+    // outside. Not a verdict — a read-heavy exploration session scores low here
+    // for reasons unrelated to doctrine — so it is shown, never graded (TASK-071).
+    editReadRatio: reads > 0 ? edits / reads : null,
   };
 }
 
@@ -130,21 +250,27 @@ function pct(x) {
   return x === null ? 'n/a' : `${Math.round(x * 100)}%`;
 }
 
+function ratio(x) {
+  return x === null ? 'n/a' : `${x.toFixed(1)}:1`;
+}
+
 export function formatReport(a) {
   const L = [];
   L.push('tune-context Adoption Report');
   L.push('============================');
   L.push('');
   L.push(`Tool calls logged: ${a.total}`);
+  L.push(`Sessions: ${a.sessions}   Projects (distinct cwd): ${a.cwds}`);
   L.push('');
 
-  L.push('Search — RAG vs grep:');
-  L.push(`  semantic (RAG):  ${a.search.rag}`);
-  L.push(`  text (grep/find):${String(a.search.text).padStart(2)}`);
-  L.push(`  glob (file find):${String(a.search.glob).padStart(2)}`);
+  L.push('Search — code search vs shell plumbing:');
+  L.push(`  semantic (RAG):     ${a.search.rag}`);
+  L.push(`  code search (Grep): ${a.search.grepTool}`);
+  L.push(`  shell text-search:  ${a.search.shell}  (grep/find in Bash — operational, not in RAG-share)`);
+  L.push(`  glob (file find):   ${a.search.glob}`);
   L.push(
-    `  RAG share of content search: ${pct(a.ragShare)}` +
-      (a.ragShare === null ? '  (no content searches yet)' : ''),
+    `  RAG share of code search: ${pct(a.ragShare)}` +
+      (a.ragShare === null ? '  (no code search — RAG or Grep — observed)' : ''),
   );
   L.push('');
 
@@ -153,7 +279,10 @@ export function formatReport(a) {
     const mark = DOCTRINE_SKILLS.has(name) ? '★' : ' ';
     L.push(`  ${mark} ${String(n).padStart(3)}×  ${name}`);
   }
-  if (a.skills.length === 0) L.push('  (none — doctrine skills unused)');
+  // No forward reference to "the verdict below" here: on a totally empty log
+  // (total === 0) the verdict section only prints "No data yet" and never
+  // mentions skills at all — a "see verdict below" promise would dangle.
+  if (a.skills.length === 0) L.push('  (none via the Skill tool)');
   L.push('');
 
   L.push(`Subagents spawned: ${a.subagents.length} distinct`);
@@ -169,6 +298,10 @@ export function formatReport(a) {
     `  re-read files: ${a.reReadFiles}  redundant opens: ${a.redundantReads}` +
       `  (${pct(a.reReadRate)} of reads)`,
   );
+  L.push(
+    `  edit:read ratio: ${ratio(a.editReadRatio)}  — edits per read; narrow,` +
+      ' contracts-first edits (doctrine-as-method, not tool-call-visible) push this up.',
+  );
   L.push('');
 
   // Verdict — behavioral, not a cost claim. Frozen thresholds so the model
@@ -177,23 +310,68 @@ export function formatReport(a) {
   if (a.total === 0) {
     L.push('  No data yet. Run some sessions with the hook installed, then re-run.');
   } else {
-    if (a.ragShare !== null) {
+    // RAG + doctrine skills are cross-session tendencies: gate them on sample
+    // size so a single atypical session can't read as a trend. Below the
+    // PO-frozen floor, withhold both judgments (TASK-070).
+    if (a.sessions < MIN_SESSIONS_FOR_VERDICT) {
       L.push(
-        a.ragShare >= 0.5
-          ? '  ✓ RAG lever working — semantic search is the default over grep.'
-          : '  ✗ RAG lever weak — grep still dominates content search. Revisit index/skill wiring.',
+        `  ~ RAG/skills verdict withheld — needs ≥${MIN_SESSIONS_FOR_VERDICT} distinct sessions, have ${a.sessions}.` +
+          ' One session is a sample, not a trend; collect more, then re-run.',
+      );
+    } else {
+      if (a.search.rag === 0) {
+        // Availability (Option 1, PO 2026-07-24): search_codebase never observed
+        // → report as unavailable, never ✗ and never ✓. The behavioral log can't
+        // tell "RAG not installed here" from "installed but never reached for",
+        // so it must not accuse — a known, accepted blind spot (TASK-070 notes).
+        L.push(
+          '  · RAG not observed — no search_codebase in these sessions. Not counted' +
+            ' as ✗: can\'t tell "not installed" from "installed but unused".',
+        );
+      } else {
+        // rag > 0 ⇒ denominator (rag + grepTool) > 0 ⇒ ragShare is a number.
+        L.push(
+          a.ragShare >= 0.5
+            ? '  ✓ RAG lever working — semantic search is the default over grep.'
+            : '  ✗ RAG lever weak — grep still dominates code search. Revisit index/skill wiring.',
+        );
+      }
+      // Zero `Skill` calls is NOT proof doctrine is unused — narrow reads,
+      // contracts-first edits, and delegation are the method working *without*
+      // a tool call. A hard ✗ here would penalize exactly the discipline this
+      // project trains toward, so it is replaced with a neutral note pointing
+      // at edit:read (see the churn section above) — a partial, honest proxy,
+      // not a substitute verdict (TASK-071).
+      L.push(
+        a.skills.length > 0
+          ? '  ✓ Doctrine skills are being invoked.'
+          : '  · No explicit Skill invocations — doctrine-as-method (narrow reads,' +
+              ' contracts-first, delegation) isn\'t tool-call-visible. See edit:read above.',
+      );
+    }
+    // Churn is a within-session symptom — valid at any sample size, so NOT gated
+    // on MIN_SESSIONS_FOR_VERDICT. But zero reads is zero churn signal: report
+    // n/a, never "elevated" — that would be a false ✗ over no data (same
+    // "say only what the sample supports" rule as the verdict above).
+    if (a.dedupSuspected) {
+      // TASK-072: withhold the verdict rather than print a fabricated ✓/~ —
+      // a doubled hook registration inflates re-read churn without any real
+      // re-reading happening. "Only say what the data supports" (TASK-070).
+      L.push(
+        `  ~ re-read churn: undecidable — ${a.dedupPairs} near-duplicate event pair(s),` +
+          ` ${pct(a.dedupShare)} of comparable records, consistent with the hook being` +
+          ' registered twice (plugin + settings.json). Every event logs twice, so churn' +
+          ' can\'t be read off this log; see README ("Measuring adoption").',
+      );
+    } else if (a.reReadRate === null) {
+      L.push('  · re-read churn: n/a — no reads logged yet.');
+    } else {
+      L.push(
+        a.reReadRate <= 0.25
+          ? '  ✓ Low re-read churn.'
+          : '  ~ Elevated re-read churn — context may be getting lost (compaction/RAG lever).',
       );
     }
-    L.push(
-      a.skills.length > 0
-        ? '  ✓ Doctrine skills are being invoked.'
-        : '  ✗ Doctrine skills unused — check skill descriptions / discoverability.',
-    );
-    L.push(
-      a.reReadRate !== null && a.reReadRate <= 0.25
-        ? '  ✓ Low re-read churn.'
-        : '  ~ Elevated re-read churn — context may be getting lost (compaction/RAG lever).',
-    );
   }
   L.push('');
   L.push('Cost (dollars) is not measurable from hooks. For hard cost, enable OTEL:');

package/hooks/adoption-log.mjs

@@ -28,8 +28,8 @@ import {
   renameSync,
   statSync,
 } from 'node:fs';
-import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { claudeBaseDir } from './config-dir.mjs';
 
 const MAX_LOG_BYTES = 5 * 1024 * 1024; // rotate to <path>.1 past this (bounded ~2×)
 
@@ -42,7 +42,7 @@ function readStdin() {
 }
 
 export function logFilePath() {
-  return join(homedir(), '.claude', 'tune-context', 'adoption.jsonl');
+  return join(claudeBaseDir(), 'tune-context', 'adoption.jsonl');
 }
 
 // Detect a text-search shell command (grep/rg/find/ag/ack), the grep-side of the

package/hooks/config-dir.mjs

@@ -0,0 +1,12 @@
+// Shared base-dir resolution for hook STATE paths (snapshots, adoption log).
+// Mirrors claudeDirs() in cli/detect.mjs — same rule, but must live here rather
+// than be imported from cli/: syncDoctrine only copies hooks/ into
+// <claudeDir>/hooks/, so an installed hook has no access to cli/ at runtime.
+// eval/adoption-report.mjs imports this too, via a relative path (eval/ is
+// never installed, so that path is safe only in-repo).
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function claudeBaseDir() {
+  return process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+}

package/hooks/context-reminder.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+// UserPromptSubmit hook: measures how much context this session is actually
+// carrying and, once it crosses a threshold, injects a short reminder that it
+// may be time to shed some. See tasks/TASK-079.
+//
+// Why a hook has to do this at all: the model cannot see its own context
+// usage — nothing in a turn tells it how many tokens it is re-sending. The
+// user can see a number but has no reason to watch it. Claude Code exposes no
+// timer and no context-threshold event (verified against the hooks docs), so
+// the only place the measurement can come from is the transcript.
+//
+// Honest scope, and the reason this reminds on SIZE rather than on "phase
+// boundary": a hook is a plain script with no model access, so it cannot know
+// that a work thread just ended. Size is measurable; a phase boundary is a
+// judgment. This hook therefore supplies the measurement the model can't see,
+// and leaves the timing judgment to the model — the reminder explicitly tells
+// it to stay quiet mid-task. The phase-boundary half is the `phase-workflow`
+// skill's job, model-side, where judgment actually lives.
+//
+// The number is real, not a proxy: Claude Code records per-request `usage` in
+// the transcript, and input_tokens + cache_read_input_tokens +
+// cache_creation_input_tokens is exactly the context that was re-sent.
+import { closeSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { claudeBaseDir } from './config-dir.mjs';
+
+// PO decision 2026-07-25 (TASK-079), frozen per the TASK-062 anti-bias rule:
+// a threshold that judges the session's own weight is the PO's call, not the
+// model's. Chosen from a measured 12.6h session (peak 547k tokens, 3
+// compactions): with fire-once-per-crossing, 80k/100k/120k/150k all produce
+// the SAME 4 reminders, so the choice is about how early the warning lands,
+// not about noise. 120k is ~60% of a standard 200k window and sits clearly
+// below the ~165k where that session's user compacted by hand.
+//
+// Override for a larger window (e.g. Opus 1M) — the transcript does NOT carry
+// the context-window size (checked: no such field), so this cannot be
+// auto-scaled and an absolute number is the honest interface.
+const DEFAULT_THRESHOLD_TOKENS = 120_000;
+
+// A drop to below this fraction of the previous reading means the context was
+// compacted or cleared, so the reminder re-arms. Deliberately loose: normal
+// turn-to-turn variation is a few percent, while a compaction cuts context by
+// 60-95% (measured: 166k->58k, 541k->23k, 165k->48k).
+const REARM_DROP_RATIO = 0.6;
+
+// Read only the tail: transcripts reach tens of MB (the session this was
+// built from was 9.4MB after 12.6h) and this runs on EVERY prompt, so parsing
+// the whole file would make the tool's own overhead grow with session length —
+// precisely the cost curve it exists to fight. The last entries are all we
+// need, and 256KB comfortably spans several of them.
+const TAIL_BYTES = 256 * 1024;
+
+export function thresholdTokens(env = process.env) {
+  const raw = env.TUNE_CONTEXT_REMIND_TOKENS;
+  if (raw === undefined) return DEFAULT_THRESHOLD_TOKENS;
+  const parsed = Number(raw);
+  // A malformed override must not silently disable the reminder, nor crash a
+  // prompt — fall back to the frozen default.
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_THRESHOLD_TOKENS;
+}
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/** Last TAIL_BYTES of a file as text, without reading what comes before it. */
+function readTail(path, bytes = TAIL_BYTES) {
+  const size = statSync(path).size;
+  const start = Math.max(0, size - bytes);
+  const length = size - start;
+  if (length === 0) return '';
+  const buf = Buffer.allocUnsafe(length);
+  const fd = openSync(path, 'r');
+  try {
+    readSync(fd, buf, 0, length, start);
+  } finally {
+    closeSync(fd);
+  }
+  return buf.toString('utf8');
+}
+
+/**
+ * Context size (tokens) of the most recent request recorded in the transcript,
+ * or null when the transcript has no usable entry yet.
+ *
+ * Scans backwards so the newest reading wins, and tolerates a partial first
+ * line: a tail read almost always starts mid-line, and that fragment simply
+ * fails JSON.parse and is skipped.
+ */
+export function latestContextTokens(transcriptText) {
+  const lines = transcriptText.split('\n');
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const usage = entry?.message?.usage;
+    if (!usage) continue;
+    const total =
+      (usage.input_tokens || 0) + (usage.cache_read_input_tokens || 0) + (usage.cache_creation_input_tokens || 0);
+    // Guard against the tiny synthetic entries Claude Code also writes.
+    if (total > 0) return total;
+  }
+  return null;
+}
+
+function stateFile() {
+  return join(claudeBaseDir(), 'tune-context', 'context-reminder.json');
+}
+
+function readState(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+// One entry per session id; sessions go stale the moment they end, so old
+// entries are dropped on write rather than accumulating forever (the same
+// hygiene TASK-076 gave state/).
+const STATE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
+function pruneState(state, now) {
+  for (const [key, value] of Object.entries(state)) {
+    if (!value || typeof value.ts !== 'number' || now - value.ts > STATE_MAX_AGE_MS) delete state[key];
+  }
+  return state;
+}
+
+/**
+ * Pure decision: given the previous reading for this session and the current
+ * one, should a reminder fire, and what is the session's next state?
+ *
+ * Fires ONCE per crossing, not on every prompt above the threshold. A reminder
+ * costs tokens on the very prompt it appears in, so a context-efficiency tool
+ * that nagged every turn would be spending the thing it claims to save.
+ */
+export function decide(prev, total, threshold) {
+  let fired = prev?.fired === true;
+  // A large drop means the context was compacted/cleared: arm again so the
+  // NEXT time it grows past the threshold the user hears about it.
+  if (prev && typeof prev.last === 'number' && total < prev.last * REARM_DROP_RATIO) fired = false;
+
+  const remind = !fired && total >= threshold;
+  return { remind, next: { last: total, fired: fired || remind, ts: Date.now() } };
+}
+
+export function reminderText(total) {
+  const k = Math.round(total / 1000);
+  return [
+    `[tune-context] This session is now carrying ~${k}k tokens of context, and every further turn re-sends all of it.`,
+    'If the current work thread is finished: suggest /compact (or /clear when switching to unrelated work).',
+    'If you are mid-task: say nothing now and raise it when the thread closes.',
+    'The PreCompact hook preserves branch, dirty files and recent commits across a compaction — judgment calls and open threads are NOT preserved, so write those down first.',
+  ].join(' ');
+}
+
+// Never fails a prompt: this runs on EVERY UserPromptSubmit, so a broken or
+// unreadable transcript, an unwritable state dir or a malformed payload must
+// cost the user nothing. Same contract as adoption-log.mjs and (since
+// TASK-076) pre-compact-snapshot.mjs. Silence is the correct failure mode —
+// emitting nothing simply means no reminder this turn.
+function main() {
+  try {
+    const input = readStdin();
+    const transcriptPath = input.transcript_path;
+    if (!transcriptPath) return;
+
+    const total = latestContextTokens(readTail(transcriptPath));
+    if (total === null) return;
+
+    const session = input.session_id || 'unknown';
+    const path = stateFile();
+    const state = readState(path);
+    const { remind, next } = decide(state[session], total, thresholdTokens());
+
+    state[session] = next;
+    try {
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, JSON.stringify(pruneState(state, Date.now())));
+    } catch {
+      // Unwritable state only costs us the once-per-crossing memory; the
+      // reminder itself is still correct for this turn.
+    }
+
+    if (!remind) return;
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'UserPromptSubmit',
+          additionalContext: reminderText(total),
+        },
+      }),
+    );
+  } catch {
+    // non-fatal by design — never block a prompt over a reminder
+  }
+}
+
+if (process.argv[1] && process.argv[1].endsWith('context-reminder.mjs')) {
+  main();
+}

package/hooks/hooks.json

@@ -43,6 +43,17 @@
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/context-reminder.mjs\""
+          }
+        ]
+      }
     ]
   }
 }