claude-usage-limits 1.16.1 → 1.18.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.16.1",
+  "version": "1.18.0",
   "description": "Puts your remaining Claude Code usage limit into Claude's context before every prompt, so it opens with what fits in the budget instead of starting work that gets cut off. Reports headroom as turns rather than percentages, prices a job before you start it, and detects your plan tier.",
   "author": {
     "name": "Ridelink",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "usage-limits",
-  "version": "1.16.1",
+  "version": "1.18.0",
   "description": "Reports how much of your Codex usage limit is left as turns of work rather than a percentage, prices a job before you start it, and counts the other agents sharing the same budget.",
   "author": {
     "name": "Ridelink",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.16.1",
+  "version": "1.18.0",
   "description": "Puts your remaining Claude Code usage limit into Claude's context before every prompt, so it opens with what fits in the budget instead of starting work that gets cut off. Reports headroom as turns rather than percentages, prices a job before you start it, and detects your plan tier.",
   "keywords": [
     "claude",

package/skills/usage-limits/SKILL.md

@@ -395,6 +395,30 @@ and cannot change one already running. The budget line prints whichever
 vocabulary the host it is running in actually understands, so use the command
 it gives you rather than the one you remember.
 
+**Check the setting against the work, not against the window.** Once there is
+evidence for it, the budget line tells you what your current effort actually
+costs against the cheapest level measured on this account - "ultra, measured at
+6 times the cost of medium a turn (8 turns against 6)". It says this from the
+first prompt, at any percentage, because a mechanical hour at the top setting is
+waste at 10 per cent used exactly as much as at 80; the only difference is that
+at 80 somebody notices.
+
+It cannot judge how hard your work is. You can. So when you see it, look at what
+is actually in front of you and take one of three levers yourself, saying which
+in one line:
+
+1. **Drop the effort** for that stretch - a rename, a docs pass, running tests,
+   applying a fix you have already worked out.
+2. **Hand the stretch to a cheaper model**, and keep the dear one for the
+   decisions that need it.
+3. **Do less of it at this setting** - a fan-out multiplies the setting across
+   every agent, so six agents at ultra is six ultra turns, not one.
+
+Put it back when the work gets hard again. The question is asked once per
+setting per session, not every prompt, and never at all unless there is a real
+measured comparison behind it - a ratio from a price list would have you drop
+effort on a hunch and call it evidence.
+
 **This is a lever you may pull yourself, not only an emergency exit.** Use it
 whenever the current setting is dearer than the work in front of you needs,
 without being asked and long before any window is tight: a mechanical rename,

package/skills/usage-limits/scripts/brief.js

@@ -552,8 +552,12 @@ function briefText(parts) {
           // The command, in the host's own vocabulary. /effort does not exist
           // in Codex, and naming it there is telling Codex to do nothing while
           // believing it acted.
+          // The host this line is being written FOR, not whatever the process
+          // happens to be set to. Reading global state here meant the sentence
+          // was only accidentally right, and a caller that built a line for
+          // the other host got a command that does not exist there.
           (warning.cheaper && warning.cheaper.effort
-            ? ' To drop it: ' + usage.levers(usage.currentHost()).effort(warning.cheaper.effort) + '.'
+            ? ' To drop it: ' + usage.levers(parts.host || usage.currentHost()).effort(warning.cheaper.effort) + '.'
             : '')
       );
     }
@@ -662,6 +666,27 @@ function briefText(parts) {
     );
   }
 
+  // Is the setting bigger than the work needs? Asked from the setting, not
+  // from the budget: a mechanical hour at the top setting is waste at 10 per
+  // cent used exactly as much as at 80. The plugin supplies the measured half
+  // and asks for the judgement, because only the reader knows what is coming.
+  //
+  // Said once per setting per session. Every prompt would be nagging, and the
+  // question only changes when the setting does.
+  if (parts.fit) {
+    sentences.push(
+      'Your effort is ' + parts.fit.effort + ', measured at ' + parts.fit.multiple +
+        ' times the cost of ' + parts.fit.cheaper + ' a turn on this account (' +
+        parts.fit.sample + ' turns against ' + parts.fit.cheaperSample + '). Judge what is ' +
+        'actually in front of you before the next stretch: mechanical work - a rename, a docs ' +
+        'pass, running tests, applying a fix you have already worked out - does not need it. ' +
+        'If this stretch is that, take one of the three levers yourself and say which in one ' +
+        'line: drop the effort (' + parts.fit.command + '), hand the stretch to a cheaper ' +
+        'model, or do less of it at this setting - a fan-out multiplies the setting across ' +
+        'every agent. Put it back when the work gets hard again.'
+    );
+  }
+
   if (parts.voiceNote) sentences.push('How this user wants to be written to: ' + parts.voiceNote);
 
   // What the relay changes about all of this.
@@ -965,6 +990,10 @@ async function run(now, hookInput) {
   if (!base.utilization) return '';
 
   const all = readCache();
+  // Which setting the fit question was already asked for, read BEFORE anything
+  // rewrites the slot. Reading it afterwards meant comparing the new answer
+  // against itself, so the question could never be asked at all.
+  const askedFitFor = all && all[sessionId || '_'] ? all[sessionId || '_'].fitFor || null : null;
   let view = pickCached(all, sessionId, now, config.cacheSeconds * SECOND);
 
   // Everything shown has to come from one pass. Deriving the turns from a
@@ -999,7 +1028,9 @@ async function run(now, hookInput) {
       snapshotAge: usage.formatDuration(data.snapshotAgeMs),
       binding: cacheableBinding(binding),
       effortWarning: data.effortWarning || null,
+      fit: usage.settingFit(data.events || null, data.effortNow || null, usage.currentHost()),
     };
+    view.fitFor = view.fit ? view.fit.effort : askedFitFor;
     writeCache(mergeCache(all, sessionId, view, KEEP_SESSIONS));
   }
 
@@ -1063,8 +1094,12 @@ async function run(now, hookInput) {
         : null,
     othersSummary: view.othersSummary,
     escape: view.escape || null,
+    host: usage.currentHost(),
     turnsLeft: view.turnsLeft,
     effortWarning: view.effortWarning || null,
+    // Once per setting. The slot below records which effort it was said for,
+    // so a change of setting asks the question again and a repeat does not.
+    fit: view.fit && askedFitFor !== view.fit.effort ? view.fit : null,
     // Outside the cache: it is cheap, and it belongs to the other agent's
     // clock rather than this session's.
     codex: codexSummary(now),

package/skills/usage-limits/scripts/usage.js

@@ -2160,6 +2160,54 @@ function criticalOthers(windows, bindingKey, threshold) {
   );
 }
 
+// Is the setting bigger than the work needs?
+//
+// Everything else here is budget-triggered: it speaks when a window is filling.
+// That is the wrong trigger for this question, because a mechanical hour at the
+// top setting is waste at 10 per cent used exactly as much as at 80 - the only
+// difference is that at 80 somebody notices. The trigger is the SETTING, not
+// the window.
+//
+// The plugin cannot judge how hard the work is; only the agent reading this
+// can. So this supplies the half that is measurable - what the current effort
+// actually costs against the cheapest level with real evidence behind it, on
+// this account - and the brief asks for the judgement.
+//
+// Returns null unless there is a measured alternative. A ratio invented from a
+// price list would be worse than silence: it would have an agent drop effort on
+// a hunch and call it evidence.
+function settingFit(events, effortNow, which) {
+  // Guarded here rather than trusted from the caller: a cache hit has no event
+  // list to hand over, and dominantEffort iterates without checking.
+  const list = Array.isArray(events) ? events : [];
+  const current = effortNow || dominantEffort(list);
+  if (!current) return null;
+  const rates = effortRates(list);
+  const here = rates.find((row) => row.effort === current);
+  if (!here || here.turns < MIN_EFFORT_SAMPLE) return null;
+  const measure = (row) => (Number.isFinite(row.outputPerTurn) && row.outputPerTurn > 0 ? row.outputPerTurn : row.perTurn);
+  const mine = measure(here);
+  if (!Number.isFinite(mine) || mine <= 0) return null;
+  let best = null;
+  for (const row of rates) {
+    if (row.effort === current || row.turns < MIN_EFFORT_SAMPLE) continue;
+    const theirs = measure(row);
+    if (!Number.isFinite(theirs) || theirs <= 0) continue;
+    const multiple = mine / theirs;
+    if (multiple < EFFORT_DEARER_BY) continue;
+    if (!best || multiple > best.multiple) best = { effort: row.effort, multiple, sample: row.turns };
+  }
+  if (!best) return null;
+  return {
+    effort: current,
+    sample: here.turns,
+    cheaper: best.effort,
+    cheaperSample: best.sample,
+    multiple: Number(best.multiple.toFixed(1)),
+    command: levers(which || currentHost()).effort(best.effort),
+  };
+}
+
 // The way out that is not stopping.
 //
 // This exists because of a session that ended for no reason. The Fable weekly
@@ -3837,6 +3885,7 @@ module.exports = {
   bindingWindow,
   criticalOthers,
   escapeRoute,
+  settingFit,
   levers,
   betterCalibration,
   calibrationForPlan,