@bglocation/tune-context 2.3.0 → 2.4.0

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.4.0",
+  "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`.