claude-usage-limits 1.40.4 → 1.40.5

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.40.4",
+  "version": "1.40.5",
   "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.40.4",
+  "version": "1.40.5",
   "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/README.md

@@ -1120,7 +1120,23 @@ There are two separate things people mean by "change the model":
 
 `claude-usage-limits mode --baseline` shows both side by side. The budget line
 now says the tier as well, and where the reading came from, because the number
-that decides what a turn costs was the one number the line never printed.
+that decides what a turn costs was the one number the line never printed. It
+names the version, not only the family (`opus 5.5/xhigh`, not `opus/xhigh`),
+read from the newest assistant message in the session's transcript: a settings
+alias such as `opus` cannot say which Opus answered.
+
+When the model running is an older release of a family that has a newer one at
+a lower price - Opus 5 or 4.8 against Opus 5.5 ($4/$20, cache reads $0.20
+against $0.50), Fable 5 against Fable 5.1 (reads $0.25 against $1) - the brief
+says so once per session, with the prices and how many turns the one-off cache
+rebuild takes to repay. In Claude Code it offers `/model <id>`, which switches
+the session and saves the model as the default for new sessions; elsewhere it
+offers the host's own model setting and names no slash command. A relay whose
+own `model` is pinned to the older release is named too, since a wake starts
+with that `--model` whatever the session switched to. Releases on
+either side of the 4.7 tokenizer change are not compared, because a price per
+token is not like for like across it. `mode --no-advice` mutes this with the
+rest of the advice.
 
 What Claude can genuinely move, stated without embroidery: the model on an
 `Agent` call, and the model and effort inside a `Workflow` script. Its own

package/commands/relay.md

@@ -29,6 +29,9 @@ The rest:
   (or whichever mode you want) as well: a resume does **not** inherit the
   session's permission mode, so without one it will sit waiting for an
   approval nobody is there to give. `show off` makes it a headless run instead.
+- `model <id>` - the `--model` a resumed run starts with; `model` alone goes
+  back to the default. It is separate from `/model` in the session, so a wake
+  pinned to an older model stays on it until this is changed.
 - `voice on|off` - carry how you write in the hand-off, so the resumed session
   answers in your voice without being reminded. On by default.
 - `bugcheck on|always|off` - the hand-off asks for two bug passes before anything

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.40.4",
+  "version": "1.40.5",
   "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/references/how-it-works.md

@@ -256,8 +256,9 @@ A bracketed suffix on a model id (`claude-sonnet-5[1m]`) is stripped before
 the lookup: it marks a context-window variant of the same model, not a new
 one. Cache reads price at a tenth of the input rate unless a row carries a
 `cacheRead` figure of its own - Fable and Mythos 5.1 price reads outright at
-$0.25 per million, far under the tenth rule, and reads are the dominant input
-in exactly the long sessions where the difference matters.
+$0.25 per million (0.025x input) and Opus 5.5 at $0.20 (0.05x its $4 input),
+all under the tenth rule, and reads are the dominant input in exactly the long
+sessions where the difference matters.
 
 Until someone does, a model this table has not seen is priced at the average of
 the family its name contains: an unreleased `claude-opus-5-2` is charged at the

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

@@ -160,7 +160,7 @@ function readSaid() {
   }
 }
 function keepSaidFor(key) {
-  return /#(standing|cachemiss|stale|relaylast)$/.test(key) ? 24 * 60 * 60 * 1000 : 60 * 60 * 1000;
+  return /#(standing|cachemiss|stale|relaylast|newer)$/.test(key) ? 24 * 60 * 60 * 1000 : 60 * 60 * 1000;
 }
 
 // A plugin update takes effect when Claude Code restarts, so a session that
@@ -202,6 +202,30 @@ function staleVersionFor(sessionId, now, dir) {
   return 'usage-limits ' + installed + ' is installed but this session still runs ' + running +
     ', because a plugin update applies at the next start; a relay or cap set here follows the older rules until then.';
 }
+// A newer model of the same family at a lower price, said once a session.
+// Once is the rule every recommendation here keeps: the fact does not change
+// from prompt to prompt, and repeating it would be the plugin charging for its
+// own presence. Keyed on the pair, so a session that moves to a different model
+// with its own newer sibling hears about that one.
+function newerModelFor(sessionId, advice, now) {
+  if (!advice || !advice.text) return null;
+  const at = Number.isFinite(now) ? now : Date.now();
+  const key = String(sessionId || '_') + '#newer';
+  const all = readSaid();
+  const entry = all[key];
+  if (entry && entry.seen === advice.id && Number.isFinite(entry.at) && at - entry.at < keepSaidFor(key)) return null;
+  all[key] = { at, seen: advice.id };
+  writeSaid(all, at);
+  return advice.text;
+}
+// The model the relay resumes with, when one is set: wake.js passes it as --model.
+function relayModelNow() {
+  try {
+    return relay.settings(relay.read()).model || null;
+  } catch (err) {
+    return null;
+  }
+}
 // How the last relay ended is news once. It used to ride along for six hours
 // after any relay ended, on every prompt of every session: on 2026-09-22 a wake
 // lost at 5:53 AM was repeated in two sessions' briefs all afternoon, about
@@ -784,6 +808,7 @@ function briefText(input) {
   if (parts.tier) sentences.push(parts.tier);
   // Once per session, and only when the installed version is not this one.
   if (parts.staleVersion) sentences.push(parts.staleVersion);
+  if (parts.newerModel) sentences.push(parts.newerModel);
   const bounded = mode.boundsNote(bounds);
   if (bounded) sentences.push(bounded);
   if (parts.planChanged) {
@@ -1403,7 +1428,7 @@ function briefText(input) {
     // The one recommendation this session is allowed, in its short form. It
     // still cites the measurement, still names the command: terse is fewer
     // words, not less evidence.
-    const adviceText = parts.adviceText ? ' ' + parts.adviceText : '';
+    const adviceText = (parts.adviceText ? ' ' + parts.adviceText : '') + (parts.newerModel ? ' ' + parts.newerModel : '');
     return (
       sentences[0] + caveat + (parts.tier ? ' ' + parts.tier : '') + (bounded ? ' ' + bounded : '') + adviceText +
       (escapeSentence ? ' ' + escapeSentence : '') +
@@ -1904,7 +1929,10 @@ async function run(now, hookInput, opts) {
   // What tier is producing this turn, and what the user's own baseline is.
   // Read, displayed, never written.
   const terse = budget.policy.briefStyle === 'terse';
-  const tier = mode.tierLine(mode.tierNow({ sessionId, now, usage, env: process.env }), { terse });
+  const tierReading = mode.tierNow({ sessionId, now, usage, env: process.env, transcriptPath: hookInput && hookInput.transcript_path });
+  const tier = mode.tierLine(tierReading, { terse });
+  // Muted advice is muted for this too: it is a recommendation like the others.
+  const newerAdvice = budget.advice && budget.advice.off ? null : mode.newerModelAdvice(tierReading, { usage, host: usage.currentHost(), bounds: budget.bounds, relayModel: relayModelNow() });
 
   // The recommendation channel. The measured fit sentence IS the
   // recommendation - it cites this account's own numbers and names the exact
@@ -1959,6 +1987,7 @@ async function run(now, hookInput, opts) {
     standingShort,
     cacheMissWhy: cacheMissWhyFor(sessionId, now),
     staleVersion: staleVersionFor(sessionId, now),
+    newerModel: newerModelFor(sessionId, newerAdvice, now),
     adviceText: terse && offering ? advice.text : null,
     relay: carry,
     voiceNote,
@@ -2065,7 +2094,7 @@ function withBugcheck(text) {
   return text;
 }
 
-module.exports = { wallFeatures, sweepDebris, withBugcheck, sayOnce, shapeOf, saidFile, REPEAT_MS, staleVersionFor, relayNewsFor, installedVersion, runningVersion,
+module.exports = { wallFeatures, sweepDebris, withBugcheck, sayOnce, shapeOf, saidFile, REPEAT_MS, staleVersionFor, newerModelFor, relayNewsFor, installedVersion, runningVersion,
   readSaid, standingSaid, markStanding, standingShortFor, STANDING_SHORT, cacheMissWhyFor, missReason, MISS_RECENT_MS,
   DEFAULTS,
   HOOK_BUDGET_MS,

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

@@ -1057,9 +1057,15 @@ function tierNow(options) {
     settings = null;
   }
 
+  // The newest assistant message is the model that actually answered, which a
+  // settings alias ('opus') cannot say. The hook's own transcript_path is read
+  // first when the caller has it: it is the file this very turn is written to,
+  // where the session-id lookup has to find it under the config directory.
   let running = null;
   try {
-    const seen = sessionId ? usage.liveModel(sessionId) : null;
+    let seen = null;
+    if (opts.transcriptPath && typeof usage.transcriptModel === 'function') seen = usage.transcriptModel(opts.transcriptPath);
+    if (!(seen && seen.model) && sessionId) seen = usage.liveModel(sessionId);
     running = seen && seen.model ? seen.model : null;
   } catch (err) {
     running = null;
@@ -1112,6 +1118,150 @@ function sameFamily(a, b) {
   return left === right;
 }
 
+// The model as the brief names it: the family and the version. It used to be
+// the family alone, so claude-opus-5 and claude-opus-5-5 both printed "opus"
+// and a switch between them - a 20% price change, 60% on cache reads - was
+// invisible in the one line that exists to say what is producing the turn. A
+// bare alias ('opus') has no version to show and is shown as it is.
+function modelLabel(name) {
+  if (!name) return null;
+  let parsed = null;
+  try {
+    parsed = require('./usage.js').parseModelId(name);
+  } catch (err) {
+    parsed = null;
+  }
+  if (parsed) return parsed.version.length ? parsed.family + ' ' + parsed.version.join('.') : parsed.family;
+  const rank = modelRank(name);
+  return rank === null ? name : MODEL_ORDER[rank];
+}
+
+// Same model for the purpose of "is the running tier the baseline". Same
+// family, and where both sides carry a version, the same version: opus 5 and
+// opus 5.5 are different models at different prices, but a baseline of the
+// bare alias 'opus' says nothing about which Opus, so it disagrees with none.
+function sameModel(a, b) {
+  if (!sameFamily(a, b)) return false;
+  let left = null;
+  let right = null;
+  try {
+    const usage = require('./usage.js');
+    left = usage.parseModelId(a);
+    right = usage.parseModelId(b);
+  } catch (err) {
+    return true;
+  }
+  if (!left || !right || !left.version.length || !right.version.length) return true;
+  return left.version.join('.') === right.version.join('.');
+}
+
+function money(value) {
+  return Number.isInteger(value) ? '$' + value : '$' + value.toFixed(2);
+}
+
+// A newer model in the SAME family at a lower price is the cheapest saving
+// there is: no step down in tier, nothing given up, only the price. The advice
+// channel above only ever says "choose lower"; this says "choose newer", once
+// per session (brief.js keeps the count), and only from prices on record.
+//
+// What the user can do differs by host, and the sentence says only what is
+// real where it is read. In Claude Code, `/model <id>` switches the session and
+// saves the model as the default for new sessions (the picker's `s` key is the
+// this-session-only form), per code.claude.com/docs/en/model-config, read
+// 2026-09-25. A subagent with no model of its own falls through to the main
+// conversation's model (docs/en/sub-agents, same day), so a switch reaches
+// those from their next dispatch. Codex has no /model of that kind, so there
+// the only lever named is its config.
+//
+// The payback figure is exact arithmetic on the two rows, not an estimate of
+// the session: switching costs one write of the context at the new model's
+// write price instead of one read at the old read price, and every later turn
+// saves the difference in read price on that context. The context size cancels
+// out of the ratio, so the number of turns holds for any session. It counts the
+// reads alone; the cheaper input and output only shorten it.
+function newerModelAdvice(tier, options) {
+  const opts = options || {};
+  if (!tier) return null;
+  const usage = opts.usage || require('./usage.js');
+  if (typeof usage.newerSibling !== 'function') return null;
+  const base = tier.baseline || {};
+  const run = tier.running || {};
+  const hostName = opts.host || host.CLAUDE;
+  // A bound the user set outranks the price: nothing said points outside it.
+  const sibling = (model) => {
+    const found = model ? usage.newerSibling(model) : null;
+    return found && allows(opts.bounds, { model: found.to }) ? found : null;
+  };
+  const current = run.model || base.model;
+  const found = sibling(current);
+  // The relay resumes with its own --model when one is set (wake.js), so a
+  // session moved to the newer model still wakes on the old one. Claude Code
+  // only: that is where `relay model` feeds a Claude CLI.
+  const relayFound = hostName === host.CLAUDE && opts.relayModel ? sibling(opts.relayModel) : null;
+  if (!found && !relayFound) return null;
+
+  const name = (family, version) => family.charAt(0).toUpperCase() + family.slice(1) + ' ' + version.join('.');
+  const pct = (was, now) => Math.round((1 - now / was) * 100);
+  const prices = (pair) => {
+    const a = pair.fromRate;
+    const b = pair.toRate;
+    const bits = [];
+    if (b.input < a.input || b.output < a.output) {
+      bits.push(money(b.input) + '/' + money(b.output) + ' per million tokens in and out against ' + money(a.input) + '/' + money(a.output));
+    }
+    if (b.cacheRead < a.cacheRead) {
+      bits.push('cache reads ' + money(b.cacheRead) + ' against ' + money(a.cacheRead) + ', ' + pct(a.cacheRead, b.cacheRead) +
+        '% less on the reads that are most of what a long session spends');
+    }
+    return bits.join('; ');
+  };
+  const family = (pair) => pair.family.charAt(0).toUpperCase() + pair.family.slice(1);
+
+  const sentences = [];
+  if (found) {
+    const a = found.fromRate;
+    const b = found.toRate;
+    sentences.push(name(found.family, found.toVersion) + ' is a newer ' + family(found) + ' at a lower price than the ' +
+      name(found.family, found.fromVersion) + ' running here. At first-party API prices: ' + prices(found) +
+      '. Same tier and a newer release, so no step down.');
+    const pinnedAlready = base.model && String(base.model).toLowerCase().replace(/\[[^\]]*\]\s*$/, '').trim() === found.to;
+    if (hostName === host.CLAUDE) {
+      sentences.push('It is the user\'s switch, not yours: offer `/model ' + found.to + '`, which moves this session and saves it as the ' +
+        'default for new sessions' + (pinnedAlready ? ' (settings.json already names it, so new sessions start on it either way)' : '') +
+        '. Subagents given no model of their own (and no CLAUDE_CODE_SUBAGENT_MODEL) run on the session\'s model, so they follow from their next dispatch.');
+      // Only where the switch can be made mid-session is its one-off cost
+      // worth a number; elsewhere the offer is a pin for new sessions, which
+      // rebuild anyway.
+      if (b.cacheRead < a.cacheRead) {
+        const turns = (write) => Math.ceil(Math.round(((write * b.input - a.cacheRead) / (a.cacheRead - b.cacheRead)) * 100) / 100);
+        sentences.push('Switching rebuilds the prompt cache once; the cheaper reads alone repay that in about ' + turns(1.25) +
+          ' turns (' + turns(2) + ' on the one-hour cache).');
+      } else {
+        sentences.push('Switching rebuilds the prompt cache once, so on a large context it is worth making at the next session start rather than now.');
+      }
+    } else if (hostName === host.CODEX) {
+      sentences.push('It is the user\'s setting, not yours: offer pinning model = "' + found.to + '" in config.toml for new sessions.');
+    } else {
+      sentences.push('It is the user\'s setting, not yours: offer choosing ' + found.to + ' in this host\'s own model setting.');
+    }
+  }
+  if (relayFound) {
+    const same = found && found.to === relayFound.to && found.from === relayFound.from;
+    sentences.push('Relay wakes are pinned to ' + opts.relayModel + ' on their own' +
+      (same ? '' : ', and ' + name(relayFound.family, relayFound.toVersion) + ' is a newer ' + family(relayFound) +
+        ' at a lower price (' + prices(relayFound) + ')') +
+      ', so a resumed run starts on the older model even after this session switches: offer `/usage-limits:relay model ' + relayFound.to +
+      '`, which is the user\'s setting too.');
+  }
+  const id = (found ? found.from + '->' + found.to : '') + (relayFound ? '|relay:' + relayFound.from + '->' + relayFound.to : '');
+  return {
+    id,
+    from: found ? found.from : null,
+    to: found ? found.to : null,
+    relay: relayFound ? { from: relayFound.from, to: relayFound.to } : null,
+    text: sentences.join(' '),
+  };
+}
 // One clause for the brief, or two lines for `--baseline`.
 //
 // Where the baseline and the running tier agree there is nothing interesting
@@ -1124,16 +1274,12 @@ function tierLine(tier, options) {
   if (!tier) return null;
   const base = tier.baseline || {};
   const run = tier.running || {};
-  const shortModel = (name) => {
-    const rank = modelRank(name);
-    return rank === null ? name : MODEL_ORDER[rank];
-  };
-  const runningText = [shortModel(run.model) || shortModel(base.model), run.effort || base.effort].filter(Boolean).join('/');
+  const runningText = [modelLabel(run.model) || modelLabel(base.model), run.effort || base.effort].filter(Boolean).join('/');
   if (!runningText) return null;
-  const baseText = [shortModel(base.model), base.effort].filter(Boolean).join('/');
+  const baseText = [modelLabel(base.model), base.effort].filter(Boolean).join('/');
   const differs =
     baseText && runningText !== baseText &&
-    (!sameFamily(run.model || base.model, base.model) || (run.effort || base.effort) !== base.effort);
+    (!sameModel(run.model || base.model, base.model) || (run.effort || base.effort) !== base.effort);
   const source = run.source ? ' (' + run.source + ')' : '';
   if (opts.terse) {
     return differs ? runningText + source + ', yours ' + baseText : runningText + source;
@@ -1876,6 +2022,9 @@ module.exports = {
   ultracodeName,
   topTier,
   tierLine,
+  modelLabel,
+  sameModel,
+  newerModelAdvice,
   ledger,
   explain,
   list,

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

@@ -62,6 +62,10 @@ const RATES = {
   'claude-mythos-5-1': { input: 10, output: 50, cacheRead: 0.25 },
   'claude-fable-5': { input: 10, output: 50 },
   'claude-mythos-5': { input: 10, output: 50 },
+  // Opus 5.5 prices reads outright: $0.20 is 0.05x its input, half the tenth
+  // rule every other Opus follows (platform.claude.com/docs/en/about-claude/pricing,
+  // read 2026-09-25). Left to the multiplier it would be priced at $0.40.
+  'claude-opus-5-5': { input: 4, output: 20, cacheRead: 0.2 },
   'claude-opus-5': { input: 5, output: 25 },
   'claude-opus-4-8': { input: 5, output: 25 },
   'claude-opus-4-7': { input: 5, output: 25 },
@@ -129,6 +133,83 @@ const CACHE_WRITE_5M = 1.25;
 const CACHE_WRITE_1H = 2;
 const CACHE_READ = 0.1;
 
+// The effective cache-read price of a row, in $/MTok.
+function readRateOf(rate) {
+  return Number.isFinite(rate.cacheRead) ? rate.cacheRead : rate.input * CACHE_READ;
+}
+
+// A model id taken apart into the family word and the version numbers:
+// 'claude-opus-5-5' is opus [5, 5], 'us.anthropic.claude-opus-5-v1:0' is
+// opus [5]. A dated snapshot suffix (20250929) is not part of the version, and a
+// bare alias such as 'opus' has no version at all, so nothing is claimed about
+// which release it resolved to. Mythos stays mythos here: it is priced with
+// Fable, but it is not the same model line.
+function parseModelId(model) {
+  const id = normalizeModel(model);
+  const found = id.match(/(haiku|sonnet|opus|mythos|fable)((?:-\d+)*)/);
+  if (!found) return null;
+  const version = [];
+  for (const part of found[2].split('-').filter(Boolean)) {
+    if (part.length > 2) break;
+    version.push(Number(part));
+  }
+  return { family: found[1], version };
+}
+
+function compareVersions(a, b) {
+  const length = Math.max(a.length, b.length);
+  for (let i = 0; i < length; i += 1) {
+    const diff = (a[i] || 0) - (b[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+// Claude 4.7 and later count text with a newer tokenizer that produces about
+// 30% more tokens for the same text (pricing page, read 2026-09-25). A price per
+// token across that line is not a like-for-like price, so a sibling on the other
+// side of it is never offered as the cheaper one.
+function sameTokenizer(a, b) {
+  return (compareVersions(a, [4, 7]) >= 0) === (compareVersions(b, [4, 7]) >= 0);
+}
+
+// The newest release of the SAME family that is newer than this one and no
+// dearer on any rate - input, output or cache reads - and cheaper on at least
+// one. That is a saving with no step down in tier. Only a model whose own price
+// is on record qualifies: comparing against a family average would be
+// comparing against a guess.
+function newerSibling(model, table) {
+  const rates = table || RATES;
+  const me = parseModelId(model);
+  if (!me || !me.version.length) return null;
+  const from = 'claude-' + me.family + '-' + me.version.join('-');
+  const mine = rates[from];
+  if (!mine) return null;
+  let best = null;
+  for (const id of Object.keys(rates)) {
+    const other = parseModelId(id);
+    if (!other || other.family !== me.family || !other.version.length) continue;
+    if (compareVersions(other.version, me.version) <= 0) continue;
+    if (!sameTokenizer(other.version, me.version)) continue;
+    const theirs = rates[id];
+    const noDearer = theirs.input <= mine.input && theirs.output <= mine.output && readRateOf(theirs) <= readRateOf(mine);
+    const cheaper = theirs.input < mine.input || theirs.output < mine.output || readRateOf(theirs) < readRateOf(mine);
+    if (!noDearer || !cheaper) continue;
+    if (!best || compareVersions(other.version, best.version) > 0) best = { id, version: other.version, rate: theirs };
+  }
+  if (!best) return null;
+  const shape = (rate) => ({ input: rate.input, output: rate.output, cacheRead: readRateOf(rate) });
+  return {
+    family: me.family,
+    from,
+    fromVersion: me.version,
+    fromRate: shape(mine),
+    to: best.id,
+    toVersion: best.version,
+    toRate: shape(best.rate),
+  };
+}
+
 // `family` marks a window that caps one model family rather than the account
 // as a whole. It is what tells the rest of the file that a window cannot stop
 // work which does not use that family.
@@ -4282,6 +4363,8 @@ module.exports = {
   WINDOWS,
   rateFor,
   familyOf,
+  parseModelId,
+  newerSibling,
   familyAverage,
   familiesInUse,
   appliesTo,