claude-usage-limits 1.26.0 → 1.39.2

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

@@ -124,9 +124,28 @@ function slotFrom(input, previous, now) {
     cwd: typeof input.cwd === 'string' ? input.cwd : prior.cwd || null,
     version: typeof input.version === 'string' ? input.version : prior.version || null,
     fastMode: input.fast_mode === true,
+    cacheMiss: missFrom(input.prompt_cache, prior.cacheMiss),
   };
 }
 
+// The last prompt-cache miss and its diagnosed causes, from the status line's
+// prompt_cache object: last_miss_at is epoch seconds and last_miss_cause is
+// null until the first miss and whenever no cause was found (Claude Code
+// 2.1.260 and later; both per code.claude.com/docs/en/statusline). The moment
+// is what lets the brief tell a new miss from the same one arriving on every
+// refresh. A refresh without the object, or without a diagnosed cause, keeps
+// what the last one said.
+function missFrom(cache, prior) {
+  if (!cache || typeof cache !== 'object') return prior || null;
+  const at = typeof cache.last_miss_at === 'number' && Number.isFinite(cache.last_miss_at) ? cache.last_miss_at * 1000 : null;
+  const cause = cache.last_miss_cause;
+  const causes = cause && typeof cause === 'object' && Array.isArray(cause.causes)
+    ? cause.causes.filter((name) => typeof name === 'string')
+    : [];
+  if (at === null || !causes.length) return prior || null;
+  return { at, causes };
+}
+
 function trim(all, keep) {
   const ordered = Object.keys(all).sort((a, b) => (all[b].at || 0) - (all[a].at || 0));
   const kept = {};
@@ -378,7 +397,13 @@ function runPrevious(command, raw, env, budgetMs) {
       windowsHide: true,
       stdio: ['pipe', 'pipe', 'ignore'],
     });
-    if (result.error || result.status !== 0) return '';
+    // A command that never reads its stdin - echo, most one-line status lines -
+    // can exit before the JSON is written, and the write then fails with EPIPE.
+    // That says nothing about the command, which ran and printed. Measured on a
+    // Linux runner: the whole test took 85 ms, so no timeout was involved, and
+    // the line was dropped anyway. Only the command's own failure drops it.
+    if (result.status !== 0) return '';
+    if (result.error && result.error.code !== 'EPIPE') return '';
     return String(result.stdout || '').replace(/\s+$/, '');
   } catch (err) {
     return '';
@@ -490,14 +515,16 @@ async function main(argv) {
       headersAt: slot ? slot.headersAt : null,
       model: slot ? slot.model : null,
       modelName: slot ? slot.modelName : null,
-      // Claude Code hands this line the effort outright, so the slot is
-      // already current and nothing else need be read. It is only when the
-      // slot has none - the very first update of a session, or a build that
-      // does not send it - that the transcript is worth a look.
+      // Claude Code hands this line the effort outright, and that value is
+      // read first: the slot beside it was loaded from disk before this
+      // update was stored, so on a session's very first line it is empty and
+      // trusting it printed no effort at all until the second update. The
+      // slot still answers for a build that sends none, and only when it has
+      // none either is the transcript worth a look.
       effort:
-        slot && slot.effort
-          ? slot.effort
-          : view.pickEffort(
+        (input && input.effort && typeof input.effort.level === 'string' && input.effort.level)
+          || (slot && slot.effort)
+          || view.pickEffort(
               null,
               usage.liveEffort(mine || (slot && slot.sessionId) || null),
               collected.settings ? collected.settings.effortLevel : null
@@ -559,6 +586,7 @@ module.exports = {
   CHAIN_TIMEOUT_MS,
   feedFile,
   readFeed,
+  missFrom,
   writeFeed,
   slotFrom,
   record,

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

@@ -48,7 +48,8 @@ function pluginDir() {
 // runs hook commands through `cmd /c` on Windows and `sh -c` elsewhere, so the
 // quoting has to survive both.
 function quote(file) {
-  return '"' + String(file).replace(/\\/g, '/') + '"';
+  const normalized = String(file).replace(/\\/g, '/');
+  return normalized.includes(' ') ? '"' + normalized + '"' : normalized;
 }
 
 function scriptPath(name) {

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

@@ -393,6 +393,9 @@ function empty() {
     // means refusing fan-outs on a fresh window for a reason nobody gave. A
     // stored cap with no session here predates this rule and is ignored.
     ceilingSession: null,
+    // Applies to EVERY session, survives a reset, and is only cleared by
+    // asking. The session-scoped cap above lapses on purpose; this does not.
+    ceilingAlways: null,
     setAt: null,
     setBy: null,
     session: null,
@@ -437,6 +440,10 @@ function read() {
   // Anything outside 1-100 is not a ceiling, and enforcing a number that was
   // never a percentage would refuse work over a typo.
   base.ceilingSession = typeof parsed.ceilingSession === 'string' ? parsed.ceilingSession : null;
+  base.ceilingAlways =
+    Number.isFinite(parsed.ceilingAlways) && parsed.ceilingAlways > 0 && parsed.ceilingAlways <= 100
+      ? parsed.ceilingAlways
+      : null;
   base.ceilingPercent =
     Number.isFinite(parsed.ceilingPercent) && parsed.ceilingPercent > 0 && parsed.ceilingPercent <= 100
       ? parsed.ceilingPercent
@@ -1066,12 +1073,39 @@ function tierNow(options) {
     },
     running: {
       model: running,
-      effort: effort ? effort.effort : null,
+      effort: ultracodeName(effort ? effort.effort : null, sessionId, opts.now),
       source: effort ? effort.source : null,
     },
   };
 }
 
+// Ultracode reads as "xhigh" everywhere, and that is technically true and
+// practically wrong.
+//
+// Ultracode RESOLVES to xhigh, so every effort reader - the settings file, the
+// live transcript, CLAUDE_EFFORT - honestly reports xhigh, and the display said
+// xhigh at somebody who had typed ultracode. The two are the same amount of
+// reasoning and a very different amount of everything else, so a person who
+// asked for one and is shown the other has no way to tell it took.
+//
+// The plugin already knows. brief.js sets an ultracode flag on the session's
+// activity mark the moment the word appears in a prompt, and it STICKS for the
+// session because ultracode is a session-level trigger rather than a per-prompt
+// one. Nothing read it back. This does.
+//
+// Only xhigh is renamed. If some future effort is higher, reporting it as
+// ultracode would be a downgrade dressed up as a label, so it is left alone.
+function ultracodeName(effort, sessionId, now) {
+  if (effort !== 'xhigh' || !sessionId) return effort;
+  try {
+    const entry = require('./activity.js').read()[sessionId];
+    return entry && entry.ultracode ? 'ultracode' : effort;
+  } catch (err) {
+    // The real effort is a better answer than no answer.
+    return effort;
+  }
+}
+
 function sameFamily(a, b) {
   const left = modelRank(a);
   const right = modelRank(b);
@@ -1105,10 +1139,58 @@ function tierLine(tier, options) {
   if (opts.terse) {
     return differs ? runningText + source + ', yours ' + baseText : runningText + source;
   }
+  // Reporting the tier is not the same as deciding about it.
+  //
+  // This line has always said what is running and left it there, and the
+  // observed result is that the tier is simply never revisited: a session opens
+  // on the dearest model at the dearest effort and stays there through work
+  // that did not need either. Saying the number is not a prompt to act on it.
+  //
+  // So when the tier IS an expensive one, the line asks for a decision rather
+  // than leaving a fact lying around. Only then: on a cheap tier there is
+  // nothing to decide, and a sentence asking every turn would be exactly the
+  // per-turn cost this plugin exists to avoid.
+  //
+  // Deliberately names no slash command. /model and /effort do not exist in
+  // Codex, and telling Codex to run them is telling it to do nothing while
+  // believing it acted - the mistake levers() already exists to prevent.
+  const dear = topTier(run.model || base.model, run.effort || base.effort);
+  // What the plugin can actually do about the tier, stated exactly.
+  //
+  // Nothing in a hook, a tool or the SDK can change a running session's model
+  // or effort - that was researched to the primary sources on 2026-09-14 and
+  // the answer is a flat no. /model and /effort are the user's, by design. So
+  // the most honest thing this line can do is name the decision and, where it
+  // is cheap, say so: on Fable 5.1 on a subscription an /effort change keeps
+  // the prompt cache (prompt-caching doc, v2.1.260+), which makes stepping
+  // effort down mid-session free. On every other model it rebuilds the cache,
+  // and on a large context that can cost more than a few cheaper turns save -
+  // so there the advice is to choose at the START of a session.
+  const onFable = sameFamily(run.model || base.model, 'fable');
+  const decide = dear
+    ? ' Decide in one line whether the work in front of you needs ' + runningText + '.' +
+      (onFable
+        ? ' On Fable 5.1 an /effort change keeps the cache, so if the next stretch is mechanical, /effort low now costs nothing.'
+        : ' Changing effort or model mid-session rebuilds the cache, so if it does not, say so and choose lower at the next session start rather than switching now.')
+    : '';
   return differs
     ? 'Running ' + runningText + source + '; your baseline is ' + baseText + '. The gap is the ' +
-      'interesting part: your baseline is yours and is not being changed.'
-    : 'Running ' + runningText + source + '.';
+      'interesting part: your baseline is yours and is not being changed.' + decide
+    : 'Running ' + runningText + source + '.' + decide;
+}
+
+// Whether this tier is dear enough to be worth a decision. Opus or above, or an
+// effort at or above xhigh; either alone is enough to be worth asking.
+//
+// MODEL_ORDER runs CHEAPEST first - haiku, sonnet, opus, mythos, fable - so the
+// dear end is a HIGH rank, not a low one. Getting that backwards asked haiku to
+// justify itself and let opus through silently, which is the exact inverse of
+// the point.
+function topTier(model, effort) {
+  const rank = modelRank(model);
+  const dearModel = rank !== null && rank >= MODEL_ORDER.indexOf('opus');
+  const dearEffort = ['xhigh', 'max', 'ultra', 'ultracode'].includes(String(effort || '').toLowerCase());
+  return dearModel || dearEffort;
 }
 
 // ---------------------------------------------------------------------------
@@ -1476,6 +1558,9 @@ function main(argv) {
     if (ceilingArg.error) return ceilingArg.error;
     const state = read();
     const previous = state.ceilingPercent;
+    if (flag('--always')) {
+      state.ceilingAlways = ceilingArg.clear ? null : ceilingArg.percent;
+    }
     state.ceilingPercent = ceilingArg.clear ? null : ceilingArg.percent;
     state.ceilingSession = ceilingArg.clear ? null : sessionId;
     write(state);
@@ -1495,6 +1580,7 @@ function clearCeiling(now) {
   const previous = state.ceilingPercent;
   state.ceilingPercent = null;
   state.ceilingSession = null;
+  state.ceilingAlways = null;
   write(state);
   logChange({ plane: 'mode', key: 'ceiling', from: previous, to: null, by: 'user', reason: null }, now);
 }
@@ -1503,6 +1589,13 @@ function clearCeiling(now) {
 // refusal, because a percentage on its own does not tell anyone what changes.
 function ceilingLine() {
   const state = read();
+  if (Number.isFinite(state.ceilingAlways)) {
+    return (
+      'Standing cap ' + state.ceilingAlways + '%, for this and every future session on this ' +
+      'machine, including after a limit resets. Past it, fan-out calls are refused at the hook; ' +
+      'nothing else is blocked. "mode --cap off --always" removes it.'
+    );
+  }
   if (state.ceilingPercent === null || state.ceilingPercent === undefined) {
     return 'Ceiling off. Nothing is refused; the plugin reports and does not intervene.';
   }
@@ -1641,6 +1734,8 @@ module.exports = {
   adviceDecline,
   adviceMute,
   tierNow,
+  ultracodeName,
+  topTier,
   tierLine,
   ledger,
   explain,

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

@@ -137,6 +137,11 @@ function pulseText(parts) {
 
   const head = '[usage-limits] ' + (parts.fanout ? 'Before this fan-out: ' : '') + bits.join(', ') + '.';
   if (parts.fanout) {
+    // Parallel Agent calls fire this once per call, so the advice sentence was
+    // being said six times in a row for one reading. The reading itself is
+    // never throttled; the advice is said once per session per ten minutes,
+    // through the same state file as every other throttle here.
+    if (parts.advice === false) return head;
     // Said before every Workflow or Agent call. The agents spend this same
     // window, nothing can speak again until they stop, and a main-loop turn
     // with a large context costs more than one whole fresh-context agent.
@@ -147,6 +152,10 @@ function pulseText(parts) {
       '. Fewer agents with a fresh context beat another turn of a long one.'
     );
   }
+  // The tight and gone sentences are advice too, and they were said on every
+  // due pulse - three times in ten minutes on 2026-09-20. Same slot and same
+  // ten minutes as the fan-out advice; the reading itself is never withheld.
+  if ((parts.pressure === 'gone' || parts.pressure === 'tight') && parts.advice === false) return head;
   if (parts.pressure === 'gone') {
     return head + ' The budget is gone. Stop adding work, save what exists and write the handoff.';
   }
@@ -249,8 +258,10 @@ async function run(now, hookInput) {
   // ask the model to agree with it.
   if (event === 'PreToolUse' && ceiling.isMultiplier(tool)) {
     try {
+      const worst = ceilingPercent(now, null, hookInput && hookInput.transcript_path);
       const at = ceiling.assess({
-        percent: ceilingPercent(now),
+        percent: worst ? worst.percent : null,
+        label: worst ? worst.label : null,
         state: budget.state,
         env: process.env,
         // The cap only binds in the session that set it.
@@ -289,10 +300,12 @@ async function run(now, hookInput) {
   // The cheap path, and the one taken almost every time. A fan-out is never
   // throttled: it is said every time, because every time it is about to cost.
   if (!fanout && !due(all, throttleKey, now, every)) return '';
+  const adviceKey = (sessionId || '_') + '#fanout-advice';
+  const sayAdvice = fanout && due(all, adviceKey, now, 10 * 60 * 1000);
 
   // Claimed before the scan rather than after, so a slow scan cannot let a
   // second tool call start another one.
-  writeState(trim(all, throttleKey, now));
+  writeState(sayAdvice ? trim(trim(all, throttleKey, now), adviceKey, now) : trim(all, throttleKey, now));
 
   // A reading as old as the interval is replaced with the one Claude Code
   // would take for /usage, so a turn that runs for an hour is measured
@@ -398,6 +411,11 @@ async function run(now, hookInput) {
     return recheck;
   }
 
+  // The pressure advice shares the fan-out advice's slot and its ten minutes.
+  // Unlike the fan-out's, it is stamped after the fact and only when a line
+  // actually carried it: a pulse with no reading to hang it on says nothing,
+  // and must not spend the slot on nothing.
+  const sayPressureAdvice = !fanout && (pressure === 'tight' || pressure === 'gone') && due(readState(), adviceKey, now, 10 * 60 * 1000);
   const spoken = pulseText({
     label: binding.label,
     percentUsed: binding.percentUsed,
@@ -410,50 +428,82 @@ async function run(now, hookInput) {
     sessions: active,
     pressure,
     fanout,
+    advice: fanout ? sayAdvice : sayPressureAdvice,
   });
+  if (spoken && sayPressureAdvice) writeState(trim(readState(), adviceKey, now));
   return recheck ? (spoken ? spoken + ' ' + recheck : recheck) : spoken;
 }
 
-// The cheapest percentage good enough to enforce a ceiling against.
+// The cheapest reading good enough to enforce a ceiling against.
 //
 // The ceiling is checked before every fan-out, which is far too often to scan
-// transcripts for. Two sources are already paid for: the corrected reading the
-// last scan left behind, and the account snapshot, which is one small file
-// read. The highest of them wins, because a ceiling means "no window past
-// here" - taking the emptiest window would be a ceiling that never binds.
+// transcripts for. snapshotWindows() is the no-scan view every other cheap
+// reader uses: the account snapshot, the corrections the last scan left
+// behind, and whether each window is one this agent can spend into. The
+// fullest of those wins, because a ceiling means "no window past here".
 //
-// Returns null when neither source has anything, and a ceiling with no reading
-// behind it never refuses. Guessing high would block work over a number nobody
+// This used to take the highest number on disk, whatever window it belonged
+// to - including a weekly scoped to a model this session was not running, and
+// the snapshot of a window that had already reset. See ceiling.worstWindow().
+//
+// Returns null when nothing is readable, and a ceiling with no reading behind
+// it never refuses. Guessing high would block work over a number nobody
 // measured; guessing low would not be a ceiling at all.
-function ceilingPercent(now) {
-  let worst = null;
-  const consider = (value) => {
-    if (!Number.isFinite(value)) return;
-    if (worst === null || value > worst) worst = value;
-  };
+function ceilingPercent(now, collected, transcriptPath) {
   const codexHome = usage.isCodex() ? require('./codex.js').homeDir() : null;
   try {
-    const entries = reading.read(codexHome);
-    for (const key of Object.keys(entries)) {
-      const entry = reading.correctedFor(key, now, null, codexHome);
-      if (entry) consider(entry.percentUsed);
-    }
+    const running = lastModel(transcriptPath);
+    return ceiling.worstWindow(
+      usage.snapshotWindows(collected || usage.collect(now), now, codexHome, running ? [running] : [])
+    );
   } catch (err) {
-    // A missing or unreadable correction just means the snapshot decides.
+    // No snapshot is a reason not to enforce, not a reason to throw.
+    return null;
   }
+}
+
+// The model this session's last reply came from, off the tail of its transcript.
+//
+// The setting says what a session started on; /model changes what it runs
+// without touching settings.json. A weekly scoped to the model actually
+// running must count, so the pulse adds this to the setting rather than
+// replacing it - suppressing a window takes both sides agreeing. One read of
+// the last 64 KB, from the end, whole lines only. Null on anything unexpected.
+function lastModel(transcriptPath) {
+  if (!transcriptPath) return null;
+  let fd = null;
   try {
-    const snapshot = usage.collect(now);
-    const utilization = snapshot && snapshot.utilization;
-    if (utilization && typeof utilization === 'object') {
-      for (const key of Object.keys(utilization)) {
-        const window = utilization[key];
-        if (window && typeof window === 'object') consider(Number(window.utilization));
+    fd = fs.openSync(transcriptPath, 'r');
+    const size = fs.fstatSync(fd).size;
+    const length = Math.min(size, 64 * 1024);
+    const buffer = Buffer.alloc(length);
+    fs.readSync(fd, buffer, 0, length, size - length);
+    const lines = buffer.toString('utf8').split('\n');
+    // The first line of a partial read is cut; only a read from the start is whole.
+    if (length < size) lines.shift();
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+      if (!lines[i].includes('"assistant"')) continue;
+      try {
+        const entry = JSON.parse(lines[i]);
+        const model = entry && entry.type === 'assistant' && entry.message && entry.message.model;
+        // "<synthetic>" marks a reply Claude Code wrote itself, not a model.
+        if (model && typeof model === 'string' && !model.startsWith('<')) return model;
+      } catch (err) {
+        // A half-written last line while the transcript is being appended.
       }
     }
+    return null;
   } catch (err) {
-    // Same: no snapshot is a reason not to enforce, not a reason to throw.
+    return null;
+  } finally {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch (err) {
+        // Already closed is fine.
+      }
+    }
   }
-  return worst;
 }
 
 // PostToolUse does not take plain stdout as context the way UserPromptSubmit
@@ -550,5 +600,6 @@ module.exports = {
   envelope,
   refusal,
   ceilingPercent,
+  lastModel,
   run,
 };