claude-usage-limits 1.19.0 → 1.24.0

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

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+'use strict';
+
+// The ceiling: the one thing in this plugin that is enforced rather than
+// reported.
+//
+// Everything else here tells an agent where the budget stands and trusts it to
+// act on that. For Claude Code that mostly works. For Codex it does not, and
+// the reason is worth stating plainly rather than blaming the model: a number
+// in the context is an input to a decision, and an agent part-way through a
+// plan it was told to finish will weigh "the window is at 80 per cent" against
+// "finish the whole list" and keep going, every time. It is not ignoring the
+// figure. It is trading it off, and losing the trade.
+//
+// So the ceiling does not argue. Above it, the calls that MULTIPLY spend are
+// refused at the hook, before the model's judgement is involved at all.
+//
+// Three rules shape what it refuses, and they are the whole design:
+//
+//   1. It never refuses work, only the expensive WAY of doing it. A fan-out of
+//      eight subagents and doing the same eight things in sequence reach the
+//      same place; only one of them can spend half a window between two
+//      readings with nothing able to speak in between. Refusing the fan-out
+//      leaves the task entirely possible, which is why this is a ceiling and
+//      not a stop button.
+//
+//   2. It never refuses the cheap calls. Reading a file, running a test,
+//      writing an edit - all of it stays allowed at any percentage, because an
+//      agent that cannot save its work is worse than one that overspends.
+//
+//   3. It says why, in terms of what to do instead. A denial that reads "over
+//      budget" gets retried. One that reads "do these sequentially yourself"
+//      gets obeyed.
+//
+// Off by default. A ceiling nobody set is not a ceiling, and this file returns
+// `allow` for every call until someone names a number.
+
+const MULTIPLIERS = [
+  // Claude Code, and the Codex equivalents, which use the same names.
+  'Agent',
+  'Task',
+  'Workflow',
+  // Codex names its fan-out differently depending on build; both have been
+  // seen. Matching the name is cheap and a miss only costs enforcement, never
+  // correctness.
+  'Subagent',
+  'Dispatch',
+];
+
+// Antigravity derives tool names by lowercasing the step type and stripping
+// CORTEX_STEP_TYPE_, so its names are snake_case and cannot be matched by the
+// list above.
+const MULTIPLIER_PATTERN = /^(agent|task|workflow|subagent|dispatch|spawn_[a-z_]*agent|run_[a-z_]*agent)$/i;
+
+// How far below the ceiling the warning starts. Ten points is about one long
+// turn at xhigh on a 5-hour window, which is the last moment a warning can
+// still change what happens next.
+const NEAR_POINTS = 10;
+
+function isMultiplier(tool) {
+  const name = String(tool || '').trim();
+  if (!name) return false;
+  if (MULTIPLIERS.includes(name)) return true;
+  return MULTIPLIER_PATTERN.test(name);
+}
+
+// The number, and who set it. An explicit environment value is the user saying
+// it outright for this one session and beats the file, the same precedence the
+// mode uses.
+function ceilingFrom(state, env) {
+  const environment = env || process.env;
+  const raw = environment.USAGE_LIMITS_CEILING;
+  if (raw !== undefined && raw !== null && String(raw).trim() !== '') {
+    const text = String(raw).trim().toLowerCase();
+    if (text === 'off' || text === 'none' || text === 'no') return { percent: null, source: 'environment' };
+    const value = Number(text.replace(/%$/, ''));
+    if (Number.isFinite(value) && value > 0 && value <= 100) {
+      return { percent: value, source: 'environment' };
+    }
+    // A ceiling that cannot be read is not a ceiling of zero. Fall through to
+    // the file rather than enforcing a number nobody typed.
+  }
+  const stored = state && Number.isFinite(state.ceilingPercent) ? state.ceilingPercent : null;
+  if (stored !== null && stored > 0 && stored <= 100) return { percent: stored, source: 'the file' };
+  return { percent: null, source: null };
+}
+
+// Where the binding window stands against the ceiling.
+//
+// `percent` is the BINDING window's, not the emptiest one's. A ceiling read
+// against whichever window has the most left would never bind at all, which is
+// the same mistake the brief was corrected for.
+function assess(options) {
+  const opts = options || {};
+  const ceiling = ceilingFrom(opts.state, opts.env);
+  const percent = Number.isFinite(opts.percent) ? opts.percent : null;
+  if (ceiling.percent === null || percent === null) {
+    return {
+      set: ceiling.percent !== null,
+      source: ceiling.source,
+      ceiling: ceiling.percent,
+      percent,
+      over: false,
+      near: false,
+      headroomPoints: null,
+    };
+  }
+  const headroomPoints = ceiling.percent - percent;
+  return {
+    set: true,
+    source: ceiling.source,
+    ceiling: ceiling.percent,
+    percent,
+    over: percent >= ceiling.percent,
+    near: headroomPoints > 0 && headroomPoints <= NEAR_POINTS,
+    headroomPoints,
+  };
+}
+
+function round(value) {
+  return Math.round(value * 10) / 10;
+}
+
+// What to do about one tool call.
+//
+// Returns `allow` for everything the ceiling does not cover, which is almost
+// everything. The caller turns a `deny` into whatever its host's hook protocol
+// wants; this file deliberately knows nothing about that.
+function verdict(state, tool) {
+  if (!state || !state.set || !state.over) return { decision: 'allow', reason: null };
+  if (!isMultiplier(tool)) return { decision: 'allow', reason: null };
+  return {
+    decision: 'deny',
+    reason:
+      'Usage ceiling reached: the binding window is ' +
+      round(state.percent) +
+      '% used and the ceiling is ' +
+      state.ceiling +
+      '%. Fan-out calls are refused past the ceiling because subagents spend the same window ' +
+      'in parallel and nothing can report back until they stop. Nothing else is blocked. ' +
+      'Do this work yourself, in this session, one step at a time - that is the same work at ' +
+      'roughly a fifth of the spend. Do not retry this call and do not ask to raise the ' +
+      'ceiling; if the ceiling is genuinely wrong, say so in your reply and let the user change it.',
+  };
+}
+
+// The line for a session that is close but not over. Advice, not enforcement -
+// there is still room, and the point of saying it here is that it arrives
+// BEFORE the expensive call rather than after it.
+function warning(state) {
+  if (!state || !state.set || state.over || !state.near) return null;
+  return (
+    'Usage ceiling in ' +
+    round(state.headroomPoints) +
+    ' points: the binding window is ' +
+    round(state.percent) +
+    '% used against a ceiling of ' +
+    state.ceiling +
+    '%. Past the ceiling, fan-out calls are refused outright. Land what is in flight and ' +
+    'prefer doing the next steps in this session over spawning agents for them.'
+  );
+}
+
+// A short, honest description for the report and the panel.
+function describe(state) {
+  if (!state || !state.set) return 'Ceiling      not set';
+  const where = state.percent === null ? 'no reading' : round(state.percent) + '% used';
+  const status = state.over ? 'REACHED' : state.near ? 'close' : 'clear';
+  return (
+    'Ceiling      ' +
+    state.ceiling +
+    '% (' +
+    status +
+    ', ' +
+    where +
+    ')' +
+    (state.source ? ' - set in ' + state.source : '')
+  );
+}
+
+module.exports = {
+  MULTIPLIERS,
+  MULTIPLIER_PATTERN,
+  NEAR_POINTS,
+  isMultiplier,
+  ceilingFrom,
+  assess,
+  verdict,
+  warning,
+  describe,
+};

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

@@ -35,6 +35,85 @@ function rewrite(text, values) {
   }
   return prepend.join('') + lines.join('');
 }
+// ---------------------------------------------------------------------------
+// The subagent clamp
+//
+// Effort is the biggest lever on Codex and this is the second. Two facts, both
+// read out of the model catalog Codex itself caches at
+// CODEX_HOME/models_cache.json rather than taken from documentation:
+//
+//   gpt-6-astra: default_reasoning_level = "low"
+//                multi_agent_reasoning_effort = "xhigh"
+//
+// So Astra's own default effort is the cheapest one, and its subagents run at
+// the dearest one NO MATTER what the main session is set to. A session at
+// medium that delegates is still paying xhigh for everything it delegates, and
+// the "ultra" level is described in that same catalog as "maximum reasoning
+// with automatic task delegation" - it spawns them on its own.
+//
+// The [agents] table is where that is bounded. It is a table rather than a
+// top-level key, and the line editor above deliberately refuses to be a TOML
+// parser, so this is handled the one way that is safe without one: a marked
+// block appended at the end of the file. A TOML table runs until the next
+// header, so appending at the end is always valid, and the editor above stops
+// at the first '[' so the two never interfere.
+//
+// If the file already has an [agents] table this refuses outright rather than
+// writing a second one, because duplicate tables are a TOML error and a config
+// this tool broke would be worse than a window it failed to save.
+const AGENTS_START = '# >>> usage-limits lowpower: subagent clamp';
+const AGENTS_END = '# <<< usage-limits lowpower';
+
+function hasAgentsTable(text) {
+  // Any [agents] or [agents.x] header that is not inside our own block.
+  const outside = stripAgentsBlock(text);
+  return /^[ \t]*\[\s*agents\s*[.\]]/m.test(outside);
+}
+
+function stripAgentsBlock(text) {
+  const from = text.indexOf(AGENTS_START);
+  if (from === -1) return text;
+  const to = text.indexOf(AGENTS_END, from);
+  if (to === -1) return text;
+  // The block is written after one blank separator line, so removing it has to
+  // take that line too. Leaving it behind meant `off` returned a file one
+  // newline longer than `on` found it - which is not a restore, and the
+  // round-trip tests that guard this editor said so.
+  let start = from;
+  if (text.endsWith('\r\n\r\n', from)) start = from - 2;
+  else if (text.endsWith('\n\n', from)) start = from - 1;
+  const after = to + AGENTS_END.length;
+  // Take the newline that ends the marker line with it.
+  const end = text.startsWith('\r\n', after) ? after + 2 : text.startsWith('\n', after) ? after + 1 : after;
+  return text.slice(0, start) + text.slice(end);
+}
+
+function agentsBlock(newline) {
+  return [
+    AGENTS_START,
+    '# Written by the usage-limits plugin. "lowpower off --host codex" removes it.',
+    '# Astra runs its subagents at xhigh whatever the session is set to, so this',
+    '# is the only place that spend is bounded.',
+    '[agents]',
+    'max_concurrent_threads_per_session = 1',
+    'default_subagent_reasoning_effort = "low"',
+    AGENTS_END,
+  ].join(newline) + newline;
+}
+
+function withAgentsBlock(text, wanted, newline) {
+  const base = stripAgentsBlock(text);
+  if (!wanted) return base;
+  if (hasAgentsTable(base)) {
+    throw new Error(
+      'config.toml already has an [agents] table; the subagent clamp was not written. ' +
+        'Set max_concurrent_threads_per_session and default_subagent_reasoning_effort there yourself.'
+    );
+  }
+  const padded = base.length && !base.endsWith('\n') ? base + newline : base;
+  return padded + (padded.length ? newline : '') + agentsBlock(newline);
+}
+
 function read(file, fallback) {
   try { return fs.readFileSync(file, 'utf8'); } catch (e) { if (e.code === 'ENOENT') return fallback; throw e; }
 }
@@ -65,7 +144,13 @@ function plan(text, options, state) {
   if (state) for (const [key, line] of Object.entries(state.applied)) {
     if (lineOf(key) !== line) throw new Error(key + ' changed outside lowpower; review config and restore state before continuing.');
   }
-  if (options.command === 'off') return { text: state ? rewrite(text, state.previous) : text, state: null };
+  const newline = text.includes('\r\n') ? '\r\n' : '\n';
+  if (options.command === 'off') {
+    const restored = state ? rewrite(text, state.previous) : text;
+    // The clamp is removed on `off` whether or not this run is the one that
+    // wrote it, so a state file lost to a crash cannot strand it in the config.
+    return { text: withAgentsBlock(restored, false, newline), state: null };
+  }
   const effort = options.effort || 'low';
   if (!EFFORTS.includes(effort)) throw new Error('Unknown Codex effort: ' + effort);
   if (options.model !== null && options.model !== undefined && !/^[a-zA-Z0-9][a-zA-Z0-9_.:/-]*$/.test(options.model))
@@ -74,12 +159,18 @@ function plan(text, options, state) {
   if (options.model) wanted.model = options.model;
   const previous = { ...(state && state.previous) };
   const applied = { ...(state && state.applied) };
-  const newline = text.includes('\r\n') ? '\r\n' : '\n';
   for (const [key, value] of Object.entries(wanted)) {
     if (!Object.hasOwn(previous, key)) previous[key] = lineOf(key);
     applied[key] = key + ' = ' + JSON.stringify(value) + newline;
   }
-  return { text: rewrite(text, applied), state: { version: 1, previous, applied } };
+  // On unless explicitly refused. Astra's subagents run at xhigh regardless of
+  // the session's effort, so lowering effort WITHOUT bounding them leaves the
+  // most expensive path in the product untouched.
+  const clampAgents = options.agents !== false;
+  return {
+    text: withAgentsBlock(rewrite(text, applied), clampAgents, newline),
+    state: { version: 1, previous, applied, agentsClamp: clampAgents },
+  };
 }
 function main(args) {
   if (!['status', 'on', 'off'].includes(args.command)) throw new Error('Expected status, on or off');
@@ -132,4 +223,4 @@ function main(args) {
     if (lock !== undefined) { fs.closeSync(lock); fs.unlinkSync(stateFile + '.lock'); }
   }
 }
-module.exports = { scan, rewrite, plan, main, EFFORTS };
+module.exports = { scan, rewrite, plan, main, EFFORTS, AGENTS_START, AGENTS_END, hasAgentsTable, stripAgentsBlock, agentsBlock, withAgentsBlock };

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

@@ -606,12 +606,74 @@ function calibrate(events, key, now) {
   return { usdPerPercent: cost / moved, turns, percent: Math.round(last.percent) };
 }
 
+function limitIdOf(meter) {
+  return meter && typeof meter.limit_id === 'string' ? meter.limit_id : '';
+}
+
+// Whether this payload is a reading of a rolling window at all.
+//
+// Percentages count, and so does Codex saying outright that the window is
+// spent: at a limit hit the slots can come back null with
+// `rate_limit_reached_type` set, and that payload is the truest description of
+// the window there is. Skipping it for an older one that still had numbers
+// would report a window as running when it has already stopped.
+function carriesWindows(meter) {
+  if (!meter || typeof meter !== 'object') return false;
+  if (readingsOf(meter).length) return true;
+  return typeof meter.rate_limit_reached_type === 'string' && meter.rate_limit_reached_type !== '';
+}
+
+// Codex writes more than one meter, and they are not successive readings of one
+// thing. A Plus rollout carries `limit_id: "codex"`, which holds the 5-hour and
+// weekly windows, interleaved with `limit_id: "premium"`, which holds the credit
+// balance and has `primary` and `secondary` set to null.
+//
+// Taking whichever was written last therefore threw the windows away whenever a
+// `premium` payload happened to land last, which on this machine was two of
+// every six rollouts - and the report went blind at exactly the moment it was
+// wanted. On 2026-09-07 the final line of a rollout was a `premium` payload two
+// lines after a `codex` payload reading 99 per cent of the 5-hour window, and
+// what reached the agent was a meter with no windows in it at all. That is the
+// whole of "Codex does not slow down when the limit is close": nothing ever
+// told it the limit was close.
+//
+// So the newest reading of EACH meter is kept, and the one that actually
+// describes a window wins. Nothing is merged and nothing is synthesised: the
+// payload returned is one Codex really wrote, and `at` is when it wrote it, so
+// a stale reading still ages honestly.
+function pickMeter(candidates) {
+  const newestBy = new Map();
+  let newest = null;
+  for (const entry of candidates || []) {
+    if (!entry || !entry.meter || !Number.isFinite(entry.at)) continue;
+    if (!newest || entry.at > newest.at) newest = entry;
+    const id = limitIdOf(entry.meter);
+    const held = newestBy.get(id);
+    if (!held || entry.at > held.at) newestBy.set(id, entry);
+  }
+  let best = null;
+  for (const entry of newestBy.values()) {
+    if (!carriesWindows(entry.meter)) continue;
+    if (!best || entry.at > best.at) best = entry;
+  }
+  // No meter describes a window: that is a real answer too, and the newest
+  // payload is the one that should say it. utilizationFrom then reports it as
+  // unreadable or windowless exactly as before.
+  return best || newest;
+}
+
 // The newest meter reading in the rollouts, and when it was taken.
 function latestMeter(events) {
+  const candidates = [];
   for (let index = events.length - 1; index >= 0; index -= 1) {
-    if (events[index].meter) return { meter: events[index].meter, at: events[index].at };
+    const event = events[index];
+    if (!event || !event.meter) continue;
+    candidates.push({ meter: event.meter, at: event.at });
+    // Newest first, so the first payload that describes a window is the newest
+    // one that does and nothing older can beat it.
+    if (carriesWindows(event.meter)) break;
   }
-  return null;
+  return pickMeter(candidates);
 }
 
 // The meter is written next to every request, so the newest one is always near
@@ -664,6 +726,7 @@ function meterFromLines(text, partial) {
   // The first line of a tail is a fragment of whatever it landed in the middle
   // of, so it is never parsed.
   const floor = partial ? 1 : 0;
+  const candidates = [];
   for (let index = lines.length - 1; index >= floor; index -= 1) {
     const line = lines[index];
     if (!line || line.indexOf('"token_count"') === -1) continue;
@@ -675,22 +738,37 @@ function meterFromLines(text, partial) {
     }
     const meter = parsed && parsed.payload && parsed.payload.rate_limits;
     const at = Date.parse(parsed && parsed.timestamp);
-    if (meter && Number.isFinite(at)) return { meter, at };
+    if (!meter || !Number.isFinite(at)) continue;
+    candidates.push({ meter, at });
+    // Walking backwards, so the first payload that describes a window is the
+    // newest one that does. Stopping there keeps the common case at a handful
+    // of parsed lines rather than the whole tail, which matters on the status
+    // line path.
+    if (carriesWindows(meter)) break;
   }
-  return null;
+  return pickMeter(candidates);
 }
 
 // Scanning only the newest few rollouts, for the meter alone. `collect` runs on
 // the status-line path where a full scan would be far too slow.
+//
+// A rollout whose tail holds only the credit meter is not a reason to stop: the
+// windows are in an older one, and reporting nothing when they are three
+// seconds away on disk is the blindness this whole path exists to avoid. The
+// newest windowless reading is still kept, so an account that genuinely has no
+// rolling window says so instead of saying nothing.
 function meterFromDisk() {
   const files = rolloutFiles(NaN).slice(-12).reverse();
+  let fallback = null;
   for (const entry of files) {
     const tail = readTail(entry.file, TAIL_BYTES);
     if (!tail) continue;
     const found = meterFromLines(tail.text, tail.partial);
-    if (found) return found;
+    if (!found) continue;
+    if (carriesWindows(found.meter)) return found;
+    if (!fallback || found.at > fallback.at) fallback = found;
   }
-  return null;
+  return fallback;
 }
 
 // Where a live reading taken by refreshIfStale() is kept, so the hooks and the
@@ -1013,6 +1091,9 @@ module.exports = {
   utilizationFrom,
   labelFor,
   planFrom,
+  limitIdOf,
+  carriesWindows,
+  pickMeter,
   latestMeter,
   meterFromDisk,
   readTail,