@bglocation/tune-context 2.3.0 → 2.3.1

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.3.0",
+      "version": "2.3.1",
       "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.3.0",
+  "version": "2.3.1",
   "author": {
     "name": "Szymon Walczak",
     "url": "https://bglocation.dev"

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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.3.1] — 2026-07-28
+
+### Fixed
+
+- **The context reminder no longer goes quiet for 120k tokens at a stretch.** A
+  middle rung at **1.5× the threshold** (180k by default) joins the existing
+  120k and 240k, cutting the worst-case silence between notices from 120k to
+  60k. Reported from use: 120k is often too early to close a work thread, while
+  240k is far enough away that a session has to be dragged out to reach it, and
+  180k is where a phase boundary tends to land. The ladder is expressed as
+  multipliers (1×/1.5×/2×), so `TUNE_CONTEXT_REMIND_TOKENS` still scales all
+  three — a 400k threshold gives 400k/600k/800k.
+- **Each rung is now louder than the last, instead of repeating itself.** The
+  reminder's mid-task sentence is what escalates: wait for a natural break at
+  120k, raise it at the next pause anyway at 180k, say it this turn at 240k. A
+  third identical notice would just be the same coin flipped again. This also
+  fixes a real defect the third rung would otherwise have introduced — the
+  second notice used to call itself "second and final", which on a three-rung
+  ladder is false, and Claude weighs exactly that ("nothing more is coming")
+  when deciding whether to stay quiet.
+- **Docs describing the reminder as firing once.** `README.md` and the
+  `tune-context` skill both still said "a single short note" / "fires once per
+  crossing" — wrong since 2.1.0 added the second notice, not just since this
+  release.
+
+### Notes
+
+- The level-1 text is byte-identical to previous releases. A session live across
+  the upgrade whose state already recorded the old final notice earns one extra
+  notice, once, and then goes quiet — the two-rung and three-rung ladders write
+  the same number for different meanings, and a permanent ladder-version field
+  was not worth one notice.
+- This release touches `hooks/`, so **re-run `tune-context init`** (or the
+  dev-loop sync) after upgrading — `npm i -g` does not refresh hooks already
+  copied into `~/.claude/hooks/`. `tune-context verify` reports the drift.
+
 ## [2.3.0] — 2026-07-28
 
 ### Added
@@ -428,6 +464,7 @@ action needed on upgrade.
   (`explore-cheap`, `reviewer`), the PreCompact / SessionStart / PostToolUse hook
   suite, and the adoption report (`eval/adoption-report.mjs`).
 
+[2.3.1]: https://gitlab.com/bglocation/tune-context/-/tags/v2.3.1
 [2.3.0]: https://gitlab.com/bglocation/tune-context/-/tags/v2.3.0
 [2.2.0]: https://gitlab.com/bglocation/tune-context/-/tags/v2.2.0
 [2.1.0]: https://gitlab.com/bglocation/tune-context/-/tags/v2.1.0

package/README.md

@@ -217,23 +217,27 @@ many tokens it is re-sending, and Claude Code has no timer or context-threshold
 hook event. So `context-reminder.mjs` (registered under `UserPromptSubmit`)
 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`.
+short note suggesting `/compact`.
 
 - **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.
+- **The model picks the moment — at first.** The hook can measure size, but only
+  Claude can see whether you're mid-refactor, so the first note tells it to stay
+  quiet mid-task and raise it at the next natural break. That deference runs out:
+  see the ladder below. A session that never reaches a "natural break" is exactly
+  the one paying the most for the wait.
+- **Three notes per crossing at most — 120,000 / 180,000 / 240,000.** 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. Each rung halves that blind spot, and each one is *louder* than the last:
+  at 120k Claude is told to wait for a natural break, at 180k to raise it at the
+  next pause anyway, at 240k to say it this turn whatever it is doing. There is
+  deliberately no fourth — the reminder costs tokens on the prompt it appears in.
 - **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. Both levels scale with the override — the
-  second notice is always at twice the threshold.
+  size, so this can't be auto-scaled. The whole ladder scales with the override —
+  the rungs are always 1×, 1.5× and 2× the threshold (400k/600k/800k here).
 - **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

@@ -13,9 +13,11 @@
 // 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.
+// and leaves the timing judgment to the model — the first reminder explicitly
+// tells it to stay quiet mid-task. That deference is finite, though: it is
+// exactly what the LADDER below withdraws rung by rung, because a session that
+// never finds a "natural break" is the one paying the most. The phase-boundary
+// half is the `phase-workflow` skill's job, model-side, where judgment lives.
 //
 // The number is real, not a proxy: Claude Code records per-request `usage` in
 // the transcript, and input_tokens + cache_read_input_tokens +
@@ -137,43 +139,93 @@ 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 notice ladder, as multipliers of the threshold: 120k / 180k / 240k by
+// default (TASK-080 added the second rung, TASK-084 the middle one).
 //
 // 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.
+// compaction that nobody had suggested. Each rung halves the worst-case blind
+// spot: one rung left 120k of silence, two left 120k above the threshold, three
+// leave 60k.
 //
-// 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;
+// Why a fixed ladder 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. Three notices per cycle is O(1) and measurable:
+// the text is ~600 chars ≈ 150 tokens, so the third rung costs ~0.1% of the
+// context it appears in. An unbounded series is the feature eating itself; a
+// bounded rung is not. (PO decision 2026-07-28, TASK-084 — the 1.5x point comes
+// from use: 120k is often too early to close a thread, 240k so far that a
+// session has to be dragged out to reach it.)
+//
+// Multipliers rather than absolute numbers so TUNE_CONTEXT_REMIND_TOKENS scales
+// the whole ladder, as the README promises. A hardcoded 180_000 would fall
+// BELOW the first rung the moment someone raises the threshold for a 1M window.
+//
+// Each rung carries its own wording, in ONE structure, deliberately. The
+// escalation IS that sentence tightening — repeating the level-1 text three
+// times would just be the same coin flipped again, which is what would make a
+// third rung not worth its tokens. Splitting trigger from wording into two
+// parallel structures would let them drift: a fourth multiplier with no fourth
+// sentence falls back to the level-1 text, so the LOUDEST rung would print the
+// SOFTEST wording and nothing would fail. One array makes that unrepresentable.
+//
+// The graded sentence REPLACES the mid-task line rather than riding on top of
+// it, and that is a budget fact rather than taste: the rest of the reminder is
+// 490 chars against a <700 ceiling, and the old append-a-sentence shape had
+// already spent that down to 21 chars of headroom (measured 592 / 679 before
+// TASK-084). Swapping keeps every rung inside budget — 592 / 615 / 606.
+const LADDER = [
+  {
+    at: 1,
+    timing: 'If you are mid-task: stay quiet now, but raise it at the first natural break rather than dropping it.',
+  },
+  {
+    at: 1.5,
+    timing:
+      'If you are mid-task: raise it at the next pause anyway — this is no longer early, and silence now costs the user every turn.',
+  },
+  {
+    at: 2,
+    timing:
+      'Final automatic notice — say it this turn whatever you are in the middle of; nothing more fires until a compaction.',
+  },
+];
 
-/** How many notices this session has earned at `total`: 0, 1 or 2. */
+/** How many notices this session has earned at `total`: 0..LADDER.length. */
 function levelFor(total, threshold) {
-  if (total >= threshold * ESCALATION_MULTIPLIER) return 2;
-  if (total >= threshold) return 1;
-  return 0;
+  let level = 0;
+  for (const rung of LADDER) {
+    if (total >= threshold * rung.at) level++;
+  }
+  return level;
 }
 
 /**
  * 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 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.
+ * Fires at most once per rung of LEVEL_MULTIPLIERS, 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.
+ *
+ * `level` rides out with the decision because the TEXT is graded by it — see
+ * reminderText(). Crossing several rungs in one turn (a 100k tool result) fires
+ * once, at the rung actually reached: no level is owed retroactively.
  */
 export function decide(prev, total, threshold) {
   // `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.
+  //
+  // A pre-TASK-084 `levels: 2` means "crossed 2x", which on the new ladder is
+  // level 3 — so a session live across that upgrade earns exactly ONE extra
+  // notice, then goes quiet for good. Accepted rather than fixed: telling old-2
+  // from new-2 needs a ladder version in the state, a permanent cost for one
+  // notice in sessions that happen to span an upgrade.
   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.
@@ -181,7 +233,7 @@ export function decide(prev, total, threshold) {
 
   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() } };
+  return { remind, level, next: { last: total, levels: Math.max(reached, level), ts: Date.now() } };
 }
 
 /**
@@ -207,11 +259,15 @@ export function userNotice(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.
+ * relays it. The timing judgement is the model's on the FIRST rung, because only
+ * it can tell whether the current thread is finished — but that exemption is
+ * what LADDER spends: by the last rung the text asks it to speak regardless,
+ * since staying silent forever means the user never learns at all.
+ *
+ * `level` defaults to 1, so the level-1 text is byte-identical to every release
+ * since TASK-079 and a caller that does not care about rungs keeps working.
  */
-export function reminderText(total, { escalated = false } = {}) {
+export function reminderText(total, { level = 1 } = {}) {
   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.`,
@@ -220,11 +276,10 @@ export function reminderText(total, { escalated = false } = {}) {
     // 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: stay quiet now, but raise it at the first natural break rather than dropping it.',
+    // Position matters: the graded sentence stays 4th of 5, so level 1 is
+    // unchanged from what shipped.
+    (LADDER[level - 1] ?? LADDER[0]).timing,
     '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(' ');
 }
 
@@ -245,7 +300,7 @@ function main() {
     const session = input.session_id || 'unknown';
     const path = stateFile();
     const state = readState(path);
-    const { remind, escalated, next } = decide(state[session], total, thresholdTokens());
+    const { remind, level, next } = decide(state[session], total, thresholdTokens());
 
     state[session] = next;
     try {
@@ -264,7 +319,7 @@ function main() {
         systemMessage: userNotice(total),
         hookSpecificOutput: {
           hookEventName: 'UserPromptSubmit',
-          additionalContext: reminderText(total, { escalated }),
+          additionalContext: reminderText(total, { level }),
         },
       }),
     );

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bglocation/tune-context",
-  "version": "2.3.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.",
+  "version": "2.3.1",
+  "description": "Context-efficiency configurator for Claude Code — 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",
   "author": "Szymon Walczak",

package/skills/tune-context/SKILL.md

@@ -166,10 +166,14 @@ covering the detected build/test/lint commands.
      It reads the **tail** of the session transcript (`transcript_path`, present on
      every hook payload), sums `input_tokens + cache_read + cache_creation` — the
      context actually re-sent — and once that crosses a PO-frozen threshold
-     (120k, override `TUNE_CONTEXT_REMIND_TOKENS`) injects one short reminder to
-     consider `/compact`. Fires **once per crossing**, re-arming only after a
-     compaction-sized drop: the reminder costs tokens on the prompt it appears in,
-     so nagging every turn would spend exactly what the tool saves. It reminds on
+     (120k, override `TUNE_CONTEXT_REMIND_TOKENS`) injects a short reminder to
+     consider `/compact`. Fires at most **three times per crossing**, on a ladder
+     of 1×/1.5×/2× the threshold (120k/180k/240k), re-arming only after a
+     compaction-sized drop. Each rung tightens the wording — wait for a natural
+     break, then raise it at the next pause, then say it this turn — because a
+     note absorbed mid-task is otherwise never repeated. Bounded at three on
+     purpose: the reminder costs tokens on the prompt it appears in, so nagging
+     every turn would spend exactly what the tool saves. It reminds on
      SIZE, not on "phase boundary" — size is measurable from the transcript, a
      phase boundary is a judgment a hook (no model access) cannot make, so the
      reminder hands that timing call to the model and `phase-workflow`.