claude-usage-limits 1.17.0 → 1.19.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.17.0",
+  "version": "1.19.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.17.0",
+  "version": "1.19.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.17.0",
+  "version": "1.19.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

@@ -666,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.
@@ -969,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
@@ -1003,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));
   }
 
@@ -1070,6 +1097,9 @@ async function run(now, hookInput) {
     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,133 @@ function criticalOthers(windows, bindingKey, threshold) {
   );
 }
 
+// What effort is ACTUALLY running, and how we know.
+//
+// This looked like a plugin bug and is not one. Ultracode is not a separate
+// effort level: Claude Code's own words are "ultracode: xhigh + dynamic
+// workflow orchestration (this session only)". So a session in ultracode has
+// effortLevel xhigh in settings.json and writes effort "xhigh" into every
+// transcript line - both correct, and both unable to say which MODE is on.
+// "This session only" means it is never written to disk at all.
+//
+// So the honest answer is a chain, and every reading says where it came from,
+// because "xhigh" from a stale settings file and "xhigh" from a live override
+// deserve different confidence:
+//
+//   1. CLAUDE_CODE_EFFORT_LEVEL - Claude Code's own session override. Hooks
+//      inherit the environment, so this is live and authoritative.
+//   2. An override recorded here by hand, for the one case nothing can see:
+//      /effort ultracode typed in the UI, which touches neither disk nor env.
+//   3. settings.effortLevel - the persisted default.
+//   4. The transcript - stamped at session start and never re-stamped.
+const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'ultracode'];
+
+function effortOverrideFile() {
+  return path.join(configDir(), 'usage-limits-effort.json');
+}
+
+function readEffortOverride() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(effortOverrideFile(), 'utf8'));
+    if (!parsed || !EFFORT_LEVELS.includes(parsed.effort)) return null;
+    // A hand-set override describes one session. Left lying around it would
+    // outlive the session it was true for, so it expires.
+    if (!Number.isFinite(parsed.at) || Date.now() - parsed.at > 12 * 60 * 60 * 1000) return null;
+    return parsed;
+  } catch (err) {
+    return null;
+  }
+}
+
+function writeEffortOverride(level, now) {
+  if (level === null) {
+    try {
+      fs.unlinkSync(effortOverrideFile());
+    } catch (err) {
+      // Already gone is the outcome asked for.
+    }
+    return { ok: true, cleared: true };
+  }
+  if (!EFFORT_LEVELS.includes(level)) return { ok: false, error: 'effort must be one of: ' + EFFORT_LEVELS.join(', ') };
+  try {
+    fs.mkdirSync(configDir(), { recursive: true });
+    writeJsonAtomic(effortOverrideFile(), { effort: level, at: Number.isFinite(now) ? now : Date.now() });
+    return { ok: true, effort: level };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+function effortNow(sessionId, env) {
+  const environment = env || process.env;
+  const fromEnv = String(environment.CLAUDE_CODE_EFFORT_LEVEL || '').trim().toLowerCase();
+  if (EFFORT_LEVELS.includes(fromEnv)) return { effort: fromEnv, source: 'environment', live: true };
+
+  const override = readEffortOverride();
+  if (override) return { effort: override.effort, source: 'set by hand', live: true };
+
+  let configured = null;
+  try {
+    configured = collect(Date.now()).settings;
+  } catch (err) {
+    configured = null;
+  }
+  const level = configured && configured.effortLevel;
+  if (EFFORT_LEVELS.includes(level)) return { effort: level, source: 'settings', live: false };
+
+  const seen = liveEffort(sessionId);
+  if (seen && EFFORT_LEVELS.includes(seen.effort)) return { effort: seen.effort, source: 'transcript', live: false };
+  return null;
+}
+
+// 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
@@ -3746,6 +3873,42 @@ async function main(argv) {
     }
     return 0;
   }
+  // `--effort ultracode` records what nothing on the machine can see: the
+  // picker's choice is session-only and touches neither disk nor environment.
+  // `--effort clear` forgets it again.
+  const effortAt = argv.indexOf('--effort');
+  if (effortAt !== -1) {
+    const wanted = String(argv[effortAt + 1] || '').trim().toLowerCase();
+    const say = (text) => {
+      process.stdout.write(text + '\n');
+      return 0;
+    };
+    if (!wanted) {
+      const found = effortNow();
+      if (!found) return say('No effort reading available.');
+      const guess = found.source === 'settings' || found.source === 'transcript';
+      return say(
+        'Effort reads as ' + found.effort + ' (' + found.source + ').' +
+          (guess
+            ? '\nIf you picked ultracode in the session, nothing on disk says so - Claude Code calls it' +
+              ' "xhigh + dynamic workflow orchestration (this session only)".' +
+              ' Tell this: usage.js --effort ultracode'
+            : '')
+      );
+    }
+    if (wanted === 'clear' || wanted === 'off') {
+      writeEffortOverride(null);
+      return say('Effort override cleared; back to the environment, then settings.');
+    }
+    const done = writeEffortOverride(wanted, Date.now());
+    return say(
+      done.ok
+        ? 'Effort recorded as ' + done.effort +
+          '. It expires after twelve hours, and CLAUDE_CODE_EFFORT_LEVEL still wins.'
+        : done.error
+    );
+  }
+
   const recommendAt = argv.indexOf('--recommend');
   if (recommendAt !== -1) {
     // The turn count is optional: with one the verdict is about that job,
@@ -3837,6 +4000,12 @@ module.exports = {
   bindingWindow,
   criticalOthers,
   escapeRoute,
+  settingFit,
+  effortNow,
+  readEffortOverride,
+  writeEffortOverride,
+  effortOverrideFile,
+  EFFORT_LEVELS,
   levers,
   betterCalibration,
   calibrationForPlan,