@bglocation/tune-context 2.0.1 → 2.1.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "tune-context",
       "source": "./",
       "description": "Context-efficiency configurator for Claude Code: doctrine skills (token-efficiency, caveman, cdd, phase-workflow) plus a tune-context configurator that scaffolds a lean CLAUDE.md, subagents, settings and hooks.",
-      "version": "2.0.1",
+      "version": "2.1.0",
       "author": {
         "name": "Szymon Walczak",
         "url": "https://bglocation.dev"

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "tune-context",
   "displayName": "tune-context",
   "description": "Context-efficiency configurator for Claude Code: doctrine skills (token-efficiency, caveman, cdd, phase-workflow) plus a tune-context configurator that scaffolds a lean CLAUDE.md, subagents, settings and hooks.",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "author": {
     "name": "Szymon Walczak",
     "url": "https://bglocation.dev"

package/CHANGELOG.md

@@ -5,6 +5,48 @@ All notable changes to `@bglocation/tune-context` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] — 2026-07-26
+
+### Changed
+
+- **The context reminder no longer goes silent after a badly-timed crossing.**
+  It now fires a second and final time at **twice** the threshold (240k by
+  default, or 2× `TUNE_CONTEXT_REMIND_TOKENS`). The reminder tells Claude to stay
+  quiet mid-task — correctly, since only the model can see whether a refactor is
+  half-finished — but fire-once was consumed the moment the *model* read it, and
+  re-arming required a compaction. Measured on one real session: it fired at
+  ~166k, Claude stayed silent mid-task, and nothing spoke again until ~346k, 2.9×
+  the threshold. There is deliberately no third notice: this is the only hook
+  that *adds* tokens to the context it exists to shrink, so the cost stays
+  bounded at one extra note per cycle.
+- The text sent to the model now states plainly that the user cannot see the
+  reminder, so silence means they never learn about it.
+
+### Added
+
+- A `systemMessage` alongside the existing `additionalContext`, carrying the size
+  and `/compact` in one line. **Best-effort only** — see below.
+
+### Notes on measurement
+
+The intended fix was to show the user a line directly, removing the model's
+monopoly on whether they hear about a heavy session at all. A two-marker probe
+settled what the docs could not:
+
+- `systemMessage` does **not** render for `UserPromptSubmit` (measured in the
+  VSCode extension), despite the settings schema promising "Display a message to
+  the user (all hooks)". The probe's `additionalContext` marker did arrive, which
+  is what makes this a clean negative rather than a probe that failed to load.
+- `systemMessage` does **not** enter the model's context, so it costs no tokens.
+
+It is therefore emitted but depended on by nothing, and other clients were not
+measured. The escalation above is what actually closes the gap.
+
+The same measurement caught a change that would have made things worse: the
+planned model-facing text said "the user has already been shown this, do not
+repeat it". Shipped unmeasured, it would have suppressed the only channel that
+works.
+
 ## [2.0.1] — 2026-07-26
 
 ### Fixed

package/README.md

@@ -170,15 +170,21 @@ supplies the missing measurement: it reads the tail of the session transcript,
 sums the tokens actually re-sent, and once that passes **120,000** it injects a
 single short note suggesting `/compact`.
 
-- **Once per crossing, not per prompt.** The note itself costs tokens on the turn
-  it appears in, so it re-arms only after a compaction-sized drop. Measured on a
-  12.6-hour session: 4 reminders total.
-- **The model picks the moment.** The reminder tells Claude to stay quiet
-  mid-task and raise it when the thread closes — the hook can measure size, but
-  only the model can see whether you're mid-refactor.
+- **The note goes to Claude, not to your screen.** Hooks can only reach you
+  through the model — a `systemMessage` on this event was measured and does not
+  render — so what you actually see is Claude bringing it up in its reply.
+- **The model picks the moment.** The note tells Claude to stay quiet mid-task
+  and raise it at the first natural break: the hook can measure size, but only
+  the model can see whether you're mid-refactor.
+- **Twice per crossing at most.** Once at the threshold, once more at **240,000**
+  if the context keeps growing — because a note that lands mid-task can be
+  correctly absorbed and then forgotten. Measured on one session: it fired at
+  166k, Claude stayed silent, and nothing spoke again until 346k. The second
+  notice halves that blind spot; there is deliberately no third.
 - **Raise it for a large context window:** `export TUNE_CONTEXT_REMIND_TOKENS=400000`.
   120k is ~60% of a standard 200k window; the transcript doesn't record the window
-  size, so this can't be auto-scaled.
+  size, so this can't be auto-scaled. Both levels scale with the override — the
+  second notice is always at twice the threshold.
 - **Turn it off:** delete the `UserPromptSubmit` entry from `settings.json`.
 
 Depth lives in the `phase-workflow` and `token-efficiency` skills (both installed

package/hooks/context-reminder.mjs

@@ -137,31 +137,94 @@ function pruneState(state, now) {
   return state;
 }
 
+// TASK-080 fallback, chosen by the PO after measurement killed the preferred
+// design (see userNotice()): a SECOND and final notice at twice the threshold.
+//
+// The problem it solves is measured, not hypothetical. Fire-once is consumed
+// when the model reads the reminder, and the reminder itself tells the model to
+// stay quiet mid-task — correctly, since only it can see whether a refactor is
+// half-finished. In session c9329adb that combination cost the user everything
+// between ~166k and ~346k: one firing, silently absorbed, and no re-arm until a
+// compaction that nobody had suggested.
+//
+// Why 2x and not "every +N tokens": periodic nagging would break the rule this
+// hook lives under — it is the only hook that ADDS tokens to the context it
+// exists to shrink. One extra notice per cycle is a bounded, one-off cost that
+// halves the worst-case blind spot; an unbounded series is the feature eating
+// itself. Deliberately NOT a third level.
+const ESCALATION_MULTIPLIER = 2;
+
+/** How many notices this session has earned at `total`: 0, 1 or 2. */
+function levelFor(total, threshold) {
+  if (total >= threshold * ESCALATION_MULTIPLIER) return 2;
+  if (total >= threshold) return 1;
+  return 0;
+}
+
 /**
  * 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.
+ * Fires at most TWICE per crossing (threshold, then 2x threshold), never on
+ * every prompt above the line. 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;
+  // `fired: true` is how state written before TASK-080 recorded a single
+  // firing; read it as level 1 so an in-flight session whose hook is upgraded
+  // mid-run is not re-notified from scratch.
+  let reached = typeof prev?.levels === 'number' ? prev.levels : prev?.fired === true ? 1 : 0;
   // 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;
+  if (prev && typeof prev.last === 'number' && total < prev.last * REARM_DROP_RATIO) reached = 0;
+
+  const level = levelFor(total, threshold);
+  const remind = level > reached;
+  return { remind, escalated: remind && level === 2, next: { last: total, levels: Math.max(reached, level), ts: Date.now() } };
+}
 
-  const remind = !fired && total >= threshold;
-  return { remind, next: { last: total, fired: fired || remind, ts: Date.now() } };
+/**
+ * BEST-EFFORT user-facing channel (`systemMessage`). Emitted because it is free
+ * and correct per the hook schema — NOT because it is known to be shown.
+ *
+ * Measured 2026-07-26, TASK-080, with a two-marker probe: `systemMessage` does
+ * not reach the model's context (so it costs no tokens), and it did not appear
+ * on screen either, in the VSCode extension, for a UserPromptSubmit hook. The
+ * same probe's `additionalContext` marker arrived, which is what makes that a
+ * clean negative rather than a probe that failed to load. Other clients were
+ * not measured, so this stays: a line that costs nothing and may render
+ * somewhere else. **Nothing may depend on it** — in particular reminderText()
+ * must never tell the model the user has already seen the number.
+ *
+ * One sentence, deliberately: the size is the one fact a user cannot get
+ * anywhere else, and /compact is the one action.
+ */
+export function userNotice(total) {
+  const k = Math.round(total / 1000);
+  return `[tune-context] Context is at ~${k}k tokens — consider /compact when the current thread closes.`;
 }
 
-export function reminderText(total) {
+/**
+ * The channel that actually works (`additionalContext`): the model reads it and
+ * relays it. The timing judgement stays here, because only the model can tell
+ * whether the current thread is finished — but see the second sentence: it must
+ * relay eventually, because staying silent forever means the user never learns.
+ */
+export function reminderText(total, { escalated = false } = {}) {
   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.`,
+    // The measured failure this sentence exists to prevent: at ~166k the model
+    // stayed quiet mid-task and simply never came back to it, so the user first
+    // heard about the cost at ~346k.
+    'The user CANNOT see this reminder — it reaches you alone, so if you never mention it they will never know.',
     '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.',
+    'If you are mid-task: stay quiet now, but raise it at the first natural break rather than dropping it.',
     '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.',
+    // Kept short on purpose: it rides ON TOP of the full reminder, inside the
+    // same <700 char budget.
+    ...(escalated ? ['This is the second and final automatic notice — nothing more fires until a compaction.'] : []),
   ].join(' ');
 }
 
@@ -182,7 +245,7 @@ function main() {
     const session = input.session_id || 'unknown';
     const path = stateFile();
     const state = readState(path);
-    const { remind, next } = decide(state[session], total, thresholdTokens());
+    const { remind, escalated, next } = decide(state[session], total, thresholdTokens());
 
     state[session] = next;
     try {
@@ -194,11 +257,14 @@ function main() {
     }
 
     if (!remind) return;
+    // additionalContext is the channel that is known to arrive; systemMessage
+    // is emitted alongside it as a free best-effort (see userNotice()).
     process.stdout.write(
       JSON.stringify({
+        systemMessage: userNotice(total),
         hookSpecificOutput: {
           hookEventName: 'UserPromptSubmit',
-          additionalContext: reminderText(total),
+          additionalContext: reminderText(total, { escalated }),
         },
       }),
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bglocation/tune-context",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Context-efficiency configurator for Claude Code \u2014 token-saving doctrine packaged as skills, plus a tune-context configurator that scaffolds a lean CLAUDE.md, doctrine skills, subagents, settings, hooks and MCP wiring.",
   "type": "module",
   "license": "MIT",