claude-usage-limits 1.11.7 → 1.13.0

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

@@ -22,6 +22,7 @@ const fs = require('fs');
 const path = require('path');
 
 const usage = require('./usage.js');
+const reading = require('./reading.js');
 const brief = require('./brief.js');
 const host = require('./host.js');
 const activity = require('./activity.js');
@@ -30,8 +31,15 @@ const live = require('./live.js');
 const SECOND = 1000;
 const DEFAULT_INTERVAL_SECONDS = 120;
 
+// Same reasoning as the brief: ten seconds for the hook, four for a live
+// reading, five for the scan, one of slack. This hook interrupts work in
+// progress, so being late is worse here than anywhere else.
+const SCAN_BUDGET_MS = 5000;
+
 // One slot per session, same shape and same trimming as the brief's cache.
-const KEEP_SESSIONS = 8;
+// Two keys per session now - the spoken pulse and the quiet subagent refresh -
+// so this is double what it was.
+const KEEP_SESSIONS = 16;
 
 function stateFile() {
   const dir = usage.isCodex()
@@ -58,14 +66,10 @@ function readState() {
 }
 
 function writeState(all) {
-  try {
-    const file = stateFile();
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, JSON.stringify(all), 'utf8');
-  } catch (err) {
-    // Losing the throttle means one extra scan, which is survivable. Failing
-    // the tool call it runs after is not.
-  }
+  // Never throws. Losing the throttle means one extra scan, which is
+  // survivable; failing the tool call it runs after is not. Atomic because
+  // several sessions' tool calls land on this file within the same second.
+  usage.writeJsonAtomic(stateFile(), all);
 }
 
 function trim(all, sessionId, at) {
@@ -97,7 +101,18 @@ function pulseText(parts) {
   if (parts.sessions > 1) bits.push(parts.sessions + ' sessions sharing it');
   if (!bits.length) return '';
 
-  const head = '[usage-limits] ' + bits.join(', ') + '.';
+  const head = '[usage-limits] ' + (parts.fanout ? 'Before this fan-out: ' : '') + bits.join(', ') + '.';
+  if (parts.fanout) {
+    // 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.
+    return (
+      head + ' Subagents spend this window too and nothing can warn you until they ' +
+      'stop, so size the fan-out to what is left' +
+      (parts.pressure === 'gone' ? ' - which is nothing: do not launch it' : parts.pressure === 'tight' ? ' - a handful, not dozens' : '') +
+      '. Fewer agents with a fresh context beat another turn of a long one.'
+    );
+  }
   if (parts.pressure === 'gone') {
     return head + ' The budget is gone. Stop adding work, save what exists and write the handoff.';
   }
@@ -118,18 +133,49 @@ async function run(now, hookInput) {
   usage.setHost(host.detect(process.argv.slice(2), process.env));
 
   const sessionId = hookInput && hookInput.session_id ? hookInput.session_id : null;
-  // A tool call just finished, so the turn is still running. A few bytes, so
-  // the panel beside the chat keeps animating through a long turn.
-  activity.mark('working', sessionId, null, now);
+  const event = hookInput && hookInput.hook_event_name ? String(hookInput.hook_event_name) : 'PostToolUse';
+
+  // A subagent finishing is the other reason to look, and on a busy afternoon
+  // it is the more important one.
+  //
+  // This hook exists because PostToolUse fires on the MAIN thread's tool calls,
+  // and a turn that hands its work to a workflow makes none for half an hour.
+  // On 2026-09-06 two workflows spent a whole five-hour window between one
+  // prompt and the next, and nothing ran in between to notice: the reading on
+  // disk aged eleven minutes while forty-three agents spent against it, and the
+  // session was cut off at a figure the plugin still believed was 3%.
+  //
+  // So it refreshes and says nothing. The mark is deliberately not written -
+  // a subagent is not a session, and marking one would put it in the list of
+  // windows sharing this budget and split the headroom with a ghost.
+  const quiet = event === 'SubagentStop';
+  // The call about to fan out. Everything it spawns spends this window with no
+  // main-thread tool call to pulse on, so this is the last word before the
+  // bill. On 2026-09-07 a 34-agent workflow took a five-hour window from 28%
+  // to 100% in sixteen minutes, and the session was cut off at a figure the
+  // pulse had last read as 24%.
+  const tool = hookInput && hookInput.tool_name ? String(hookInput.tool_name) : '';
+  const fanout = event === 'PreToolUse' && /^(Workflow|Agent|Task)$/.test(tool);
+  if (!quiet) {
+    // A tool call just finished, so the turn is still running. A few bytes, so
+    // the panel beside the chat keeps animating through a long turn.
+    activity.mark('working', sessionId, null, now);
+  }
 
   const all = readState();
   const every = intervalMs();
-  // The cheap path, and the one taken almost every time.
-  if (!due(all, sessionId, now, every)) return '';
+  // The quiet refresh keeps its own throttle. Sharing one with the spoken
+  // pulse would mean a workflow's subagents used up the interval and the tool
+  // call right after it, the first chance to actually tell Claude, said
+  // nothing because something had already "pulsed" two minutes ago.
+  const throttleKey = quiet ? (sessionId || '_') + '#subagent' : sessionId;
+  // 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 '';
 
   // Claimed before the scan rather than after, so a slow scan cannot let a
   // second tool call start another one.
-  writeState(trim(all, sessionId, now));
+  writeState(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
@@ -151,9 +197,16 @@ async function run(now, hookInput) {
     // The reading on disk is still there.
   }
 
-  const data = await usage.report(now, { sessionId });
+  // Refreshing was the whole errand. The next prompt, or the next tool call on
+  // the main thread, reports the number this just brought up to date.
+  if (quiet) return '';
+
+  const data = await usage.report(now, { sessionId, budgetMs: SCAN_BUDGET_MS });
   const binding = data.binding;
   if (!binding) return '';
+  // This turn paid for the scan, so leave the corrected figure where the
+  // status line and --status can read it without paying for one.
+  reading.recordAll(data.windows || [binding], now, usage.isCodex() ? require('./codex.js').homeDir() : null);
 
   // The same count and the same split as the brief, so the two lines never
   // disagree about how many sessions there are or how much of the budget is
@@ -171,7 +224,7 @@ async function run(now, hookInput) {
 
   // Quiet when there is nothing to act on. A line every two minutes saying the
   // budget is fine is noise that costs the budget it is reporting on.
-  if (pressure === 'roomy' && String(process.env.USAGE_LIMITS_PULSE || '').toLowerCase() !== 'always') {
+  if (!fanout && pressure === 'roomy' && String(process.env.USAGE_LIMITS_PULSE || '').toLowerCase() !== 'always') {
     return '';
   }
 
@@ -186,15 +239,18 @@ async function run(now, hookInput) {
         : null,
     sessions: active,
     pressure,
+    fanout,
   });
 }
 
 // PostToolUse does not take plain stdout as context the way UserPromptSubmit
 // does, so the line is returned in the documented envelope instead.
-function envelope(text) {
+function envelope(text, event) {
+  // PreToolUse and PostToolUse both take additionalContext, each under its own
+  // event name; the wrong name is dropped without a word.
   return JSON.stringify({
     hookSpecificOutput: {
-      hookEventName: 'PostToolUse',
+      hookEventName: event === 'PreToolUse' ? 'PreToolUse' : 'PostToolUse',
       additionalContext: text,
     },
   });
@@ -226,11 +282,15 @@ function readHookInput() {
 }
 
 if (require.main === module) {
+  let hookEvent = null;
   readHookInput()
-    .then((input) => run(Date.now(), input))
+    .then((input) => {
+      hookEvent = input && input.hook_event_name ? String(input.hook_event_name) : null;
+      return run(Date.now(), input);
+    })
     .then(
       (text) => {
-        if (text) process.stdout.write(envelope(text) + '\n');
+        if (text) process.stdout.write(envelope(text, hookEvent) + '\n');
         process.exit(0);
       },
       () => {

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

@@ -0,0 +1,121 @@
+'use strict';
+
+// The freshest corrected percentage, left where the cheap readers can find it.
+//
+// There are two ways to know how much of a window is gone. The snapshot is what
+// the account last told us, and it is free to read. The correction is the spend
+// measured out of the transcripts since that snapshot was taken, and it costs a
+// scan of up to several seconds - far too much for something that redraws under
+// the prompt on every keystroke.
+//
+// So the fast readers used the snapshot alone, and during a heavy session that
+// is not a small error. Measured on a real session: the snapshot said 13 per
+// cent while the same codebase, given a scan, said 73. The status line is the
+// number a person actually looks at, and it was sixty points wrong, in the
+// flattering direction, for twenty minutes.
+//
+// The fix is not to make the cheap path expensive. It is to notice that
+// something already paid for the scan - the prompt hook before every turn, the
+// pulse hook during long ones - and to have it leave the answer here. One small
+// file, one object per window key, and the readers prefer it whenever it is
+// fresher than the snapshot it would otherwise trust.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Older than this and the spend it measured is history: turns have happened
+// since, and a stale correction that says 40 per cent is worse than an honest
+// snapshot that says 13, because it looks authoritative.
+const FRESH_MS = 8 * 60 * 1000;
+
+function configDir() {
+  return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+}
+
+function readingFile(codexHome) {
+  return path.join(codexHome || configDir(), 'usage-limits-reading.json');
+}
+
+function read(codexHome) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(readingFile(codexHome), 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    return parsed;
+  } catch (err) {
+    return {};
+  }
+}
+
+// Every window that has a correction, not just the binding one.
+//
+// The status line prints all three, and only one of them can be binding. So
+// recording the binding window alone left the other two showing their raw
+// snapshots - which is the same bug, on two thirds of the line.
+function recordAll(windows, now, codexHome) {
+  let written = 0;
+  for (const window of Array.isArray(windows) ? windows : [windows]) {
+    if (record(window, now, codexHome)) written += 1;
+  }
+  return written;
+}
+
+// Never throws. This is written from inside hooks, and a hook that fails over a
+// cache file would be worse than the stale number it was trying to fix.
+function record(binding, now, codexHome) {
+  if (!binding || !binding.key) return false;
+  if (binding.percentUsed === null || binding.percentUsed === undefined) return false;
+  // A rebuilt or unreliable figure is not an improvement on the snapshot; it is
+  // a different kind of guess. Only a correction the report itself trusts is
+  // worth putting in front of the cheap readers.
+  if (binding.stale || binding.estimated || binding.correctionUnreliable) return false;
+  try {
+    const all = read(codexHome);
+    all[binding.key] = {
+      at: Number.isFinite(now) ? now : Date.now(),
+      percentUsed: binding.percentUsed,
+      pointsSinceSnapshot: binding.pointsSinceSnapshot || 0,
+      adjusted: Boolean(binding.adjusted),
+      resetsAt: Number.isFinite(binding.resetsAt) ? binding.resetsAt : null,
+      turnsLeft: Number.isFinite(binding.turnsLeft) ? binding.turnsLeft : null,
+    };
+    // One entry per window key, and there are only ever a handful of those, so
+    // this file cannot grow. Anything whose reset has passed describes a window
+    // that no longer exists.
+    const at = Number.isFinite(now) ? now : Date.now();
+    for (const key of Object.keys(all)) {
+      const entry = all[key];
+      if (!entry || !Number.isFinite(entry.at) || at - entry.at > 24 * 60 * 60 * 1000) delete all[key];
+      else if (Number.isFinite(entry.resetsAt) && entry.resetsAt <= at) delete all[key];
+    }
+    fs.mkdirSync(path.dirname(readingFile(codexHome)), { recursive: true });
+    fs.writeFileSync(readingFile(codexHome), JSON.stringify(all));
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+// The corrected percentage for one window, or null when there is nothing better
+// than the snapshot. `snapshotAt` is when the snapshot being compared against
+// was fetched: a correction measured before it is already included in it, and
+// applying it again would double-count the same spend.
+function correctedFor(key, now, snapshotAt, codexHome) {
+  const entry = read(codexHome)[key];
+  if (!entry || !Number.isFinite(entry.at)) return null;
+  const at = Number.isFinite(now) ? now : Date.now();
+  if (at - entry.at > FRESH_MS) return null;
+  if (Number.isFinite(snapshotAt) && entry.at < snapshotAt) return null;
+  if (Number.isFinite(entry.resetsAt) && entry.resetsAt <= at) return null;
+  return entry;
+}
+
+function clear(codexHome) {
+  try {
+    fs.unlinkSync(readingFile(codexHome));
+  } catch (err) {
+    // Already gone is the outcome that was asked for.
+  }
+}
+
+module.exports = { FRESH_MS, configDir, readingFile, read, record, recordAll, correctedFor, clear };

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

@@ -19,7 +19,7 @@
 // judgement in it costs more in rework than it saves; the ladder loses height
 // a step at a time and 'critical' is the only posture that goes straight to
 // the floor.
-const NEXT_LOWER = { max: 'high', xhigh: 'medium', high: 'medium', medium: 'low', low: 'low' };
+const NEXT_LOWER = { ultra: 'xhigh', none: 'none', minimal: 'minimal', max: 'high', xhigh: 'medium', high: 'medium', medium: 'low', low: 'low' };
 
 // Below this share of output, reasoning is not where the money is going, and
 // turning effort down would trade quality for a saving that is not there.
@@ -187,7 +187,7 @@ function decide(inputs) {
       'reasoning is only ' + Math.round(share * 100) +
       '% of output, so effort is not where the money is going';
   } else {
-    const target = base.posture === 'critical' ? 'low' : NEXT_LOWER[effortNow] || 'medium';
+    const target = base.posture === 'critical' ? (['none', 'minimal'].includes(effortNow) ? effortNow : 'low') : NEXT_LOWER[effortNow] || 'medium';
     if (target !== effortNow) {
       base.effort.target = target;
       base.effort.changes = true;
@@ -200,6 +200,19 @@ function decide(inputs) {
     }
   }
 
+  if (inputs.codex) {
+    // Claude's family ladder and slash commands do not describe Codex.
+    base.model.why = 'Keep the current Codex model; select another supported model in the host controls when needed.';
+    if (base.effort.changes) {
+      base.apply.now = 'use the Codex model and effort controls and select ' + base.effort.target;
+      base.apply.next = 'node scripts/lowpower.js on --host codex --effort ' + base.effort.target;
+    }
+    base.notes.push('Saved defaults affect new sessions, not the running task. Profiles and CLI overrides take precedence.');
+    if (Number.isFinite(inputs.sessions) && inputs.sessions > 1)
+      base.notes.push(inputs.sessions + ' sessions share this account budget.');
+    return base;
+  }
+
   // The main model is only worth flipping when things are critical, and even
   // then it lands in settings.json for the next session: switching the running
   // session's model mid-task invalidates the prompt cache, so the change
@@ -321,7 +334,7 @@ function renderRecommend(data, turns) {
     lines.push('            new sessions: ' + decision.apply.next);
   }
   lines.push('  Model     ' + decision.model.why);
-  lines.push('            ' + decision.apply.delegate);
+  if (decision.apply.delegate) lines.push('            ' + decision.apply.delegate);
   if (decision.model.nextSession) {
     lines.push('            new sessions: main model to ' + decision.model.nextSession + ' until the window resets');
   }