claude-usage-limits 1.18.0 → 1.23.0

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

@@ -27,6 +27,8 @@ const brief = require('./brief.js');
 const host = require('./host.js');
 const activity = require('./activity.js');
 const live = require('./live.js');
+const mode = require('./mode.js');
+const ceiling = require('./ceiling.js');
 
 const SECOND = 1000;
 const DEFAULT_INTERVAL_SECONDS = 120;
@@ -37,9 +39,11 @@ const DEFAULT_INTERVAL_SECONDS = 120;
 const SCAN_BUDGET_MS = 5000;
 
 // One slot per session, same shape and same trimming as the brief's cache.
-// Two keys per session now - the spoken pulse and the quiet subagent refresh -
-// so this is double what it was.
-const KEEP_SESSIONS = 16;
+// Three keys per session now - the spoken pulse, the quiet subagent refresh,
+// and the reading taken before a long call - so this is three times what it
+// started at. Evicting a key only costs one extra scan, but evicting them as
+// fast as they are written would mean nothing is ever throttled.
+const KEEP_SESSIONS = 24;
 
 function stateFile() {
   const dir = usage.isCodex()
@@ -48,12 +52,15 @@ function stateFile() {
   return path.join(dir, 'usage-limits-pulse.json');
 }
 
-function intervalMs() {
+// How often this hook is allowed to do real work. The budget mode owns this
+// number - a mode that says the reading itself costs too much has to be able
+// to take fewer of them - but an explicit environment setting is the user
+// saying it outright, and that still wins.
+function intervalMs(policy) {
   const configured = Number(process.env.USAGE_LIMITS_PULSE_SECONDS);
-  const seconds = Number.isFinite(configured) && configured > 0
-    ? configured
-    : DEFAULT_INTERVAL_SECONDS;
-  return seconds * SECOND;
+  if (Number.isFinite(configured) && configured > 0) return configured * SECOND;
+  const fromMode = policy && Number.isFinite(policy.pulseSeconds) ? policy.pulseSeconds : null;
+  return (fromMode > 0 ? fromMode : DEFAULT_INTERVAL_SECONDS) * SECOND;
 }
 
 function readState() {
@@ -72,15 +79,42 @@ function writeState(all) {
   usage.writeJsonAtomic(stateFile(), all);
 }
 
-function trim(all, sessionId, at) {
+// `extra` carries whatever else the slot has to remember, and it exists for
+// one reason: the re-cost has to know what it said last time. A slot that is
+// only a timestamp can throttle, but it cannot tell "two minutes have passed"
+// from "two minutes have passed and nothing has changed", and those are
+// different questions.
+function trim(all, sessionId, at, extra) {
   const next = Object.assign({}, all);
-  next[sessionId || '_'] = { at };
+  next[sessionId || '_'] = Object.assign({ at }, extra || null);
   const ordered = Object.keys(next).sort((a, b) => (next[b].at || 0) - (next[a].at || 0));
   const kept = {};
   for (const key of ordered.slice(0, KEEP_SESSIONS)) kept[key] = next[key];
   return kept;
 }
 
+// A tool call the agent itself said would run long.
+//
+// PreToolUse now matches Bash, so a build or a test suite can be measured
+// before it starts rather than only after. But sharing the spoken pulse's one
+// throttle slot makes that almost never happen: a tool call finished seconds
+// ago, that PostToolUse pulse claimed the slot, and the one moment that
+// matters - just before the turn goes blind for ten minutes - says nothing.
+// Measured: a PostToolUse pulse at t, then `npm test` with a ten-minute
+// timeout at t+5s, and the pre-call pulse returned empty.
+//
+// The declaration is the agent's own: a Bash call carries the timeout it was
+// given, and anything above the pulse interval is a call that will outlast the
+// next scheduled reading. Nothing is inferred from the command text. A
+// backgrounded call is not this: it returns at once and PostToolUse fires
+// normally, so the turn never goes blind.
+function longCall(toolInput, every) {
+  if (!toolInput || typeof toolInput !== 'object') return false;
+  if (toolInput.run_in_background === true) return false;
+  const declared = Number(toolInput.timeout);
+  return Number.isFinite(declared) && declared > every;
+}
+
 function due(all, sessionId, now, every) {
   const entry = all ? all[sessionId || '_'] : null;
   if (!entry || !Number.isFinite(entry.at)) return true;
@@ -128,13 +162,62 @@ function pulseText(parts) {
   return head + ' Still room; carry on.';
 }
 
+// The two-minute re-cost. The distinguishing feature of `high`, and the reason
+// it is not simply `standard` with a shorter interval.
+//
+// A PostToolUse hook CAN put text in front of the model mid-turn: the hook
+// output contract takes additionalContext on this event, and it has been seen
+// arriving mid-turn in a running session. So this is a real nudge, not a note
+// filed for the next prompt.
+//
+// What it must not do is claim a lever nobody has. Nothing a hook emits can
+// change the running session's own model or effort - there is no such field in
+// the whole hook output contract, and PreModelSwitch is a veto on a switch
+// someone else started rather than a way to start one. So for the main loop
+// this names the command and leaves it with the person, and for what the turn
+// SPAWNS it says the thing that is genuinely the agent's to decide.
+//
+// It is built every two minutes and SAID only when it differs from the last
+// thing said in this session. See the caller: a re-cost that repeats itself is
+// not a re-cost, it is a bill for advice already given.
+function recheckText(parts) {
+  const bits = [];
+  if (parts.fit) {
+    bits.push(
+      'this turn is at ' + parts.fit.effort + ', measured ' + parts.fit.multiple + ' times the cost of ' +
+        parts.fit.cheaper + ' a turn on this account'
+    );
+  }
+  if (parts.escape && parts.escape.kind === 'effort' && parts.escape.to) {
+    bits.push(parts.escape.to + ' would free the window that binds');
+  }
+  if (!bits.length) return '';
+  const command = (parts.fit && parts.fit.command) || (parts.escape && parts.escape.command) || null;
+  return (
+    '[usage-limits] Re-costed: ' + bits.join(', and ') + '. If the stretch in front of you is ' +
+    'mechanical, the tier is bigger than the work' + (command ? ' - the change is ' + command + ', and it is the ' +
+    "user's to make, so say it in one line rather than waiting for it" : '') +
+    (parts.pin
+      ? '. Self-switching is pinned, so this is a report: change nothing on the strength of it.'
+      : '. Size what you spawn the same way: low effort for mechanical stages. Step back up when the work turns hard again.')
+  );
+}
+
 async function run(now, hookInput) {
   if (String(process.env.USAGE_LIMITS_PULSE || '').toLowerCase() === 'off') return '';
-  usage.setHost(host.detect(process.argv.slice(2), process.env));
 
   const sessionId = hookInput && hookInput.session_id ? hookInput.session_id : null;
   const event = hookInput && hookInput.hook_event_name ? String(hookInput.hook_event_name) : 'PostToolUse';
 
+  // The budget mode, settled before anything is read, marked or scanned. In
+  // `off` the hook stops here: no reading, no activity mark, no state write.
+  // That mode's whole promise is that the plugin costs nothing, and a hook
+  // that "returns immediately" after a transcript scan has already broken it.
+  const budget = mode.forSession({ sessionId });
+  if (budget.policy.refreshSeconds === 0) return '';
+
+  usage.setHost(host.detect(process.argv.slice(2), process.env));
+
   // A subagent finishing is the other reason to look, and on a busy afternoon
   // it is the more important one.
   //
@@ -156,6 +239,30 @@ async function run(now, hookInput) {
   // 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);
+
+  // The ceiling, checked before the throttle and before any scan.
+  //
+  // Everything else in this hook is advice, and advice is throttled so it does
+  // not become noise. A refusal that only arrives when the pulse happens to be
+  // due is not a refusal, so this runs on every fan-out regardless, off the two
+  // readings that are already on disk. It is the one thing here that does not
+  // ask the model to agree with it.
+  if (event === 'PreToolUse' && ceiling.isMultiplier(tool)) {
+    try {
+      const at = ceiling.assess({
+        percent: ceilingPercent(now),
+        state: budget.state,
+        env: process.env,
+      });
+      const call = ceiling.verdict(at, tool);
+      if (call.decision === 'deny') return { deny: true, reason: call.reason };
+    } catch (err) {
+      // A ceiling that throws must not block the call it was asked to judge.
+    }
+  }
+  // The other way a turn goes quiet for a long time: one foreground tool call
+  // that runs for minutes. See longCall().
+  const long = event === 'PreToolUse' && !fanout && longCall(hookInput && hookInput.tool_input, intervalMs(budget.policy));
   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.
@@ -163,12 +270,20 @@ async function run(now, hookInput) {
   }
 
   const all = readState();
-  const every = intervalMs();
+  const every = intervalMs(budget.policy);
   // 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;
+  // Same reasoning for the call about to run long: its own slot, so it is
+  // still throttled to one reading per interval and a run of long calls does
+  // not scan before every one of them, but the post-tool pulses cannot use up
+  // the interval and leave the blind stretch unmeasured.
+  const throttleKey = quiet
+    ? (sessionId || '_') + '#subagent'
+    : long
+      ? (sessionId || '_') + '#long'
+      : 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 '';
@@ -222,13 +337,66 @@ async function run(now, hookInput) {
   const runwayMs = brief.RUNWAY_MENTION_MS;
   const pressure = brief.pressure(binding, now, config, turnsLeft);
 
+  // The mode's own mid-turn re-cost, on its own throttle slot.
+  //
+  // Its own slot because the "quiet when roomy" rule below would otherwise
+  // swallow it exactly when it matters most: a turn running a tier far bigger
+  // than the work needs is precisely the case where the budget still looks
+  // roomy and nothing else would say a word.
+  let recheck = '';
+  const recheckMs = (budget.policy.recheckSeconds || 0) * SECOND;
+  const recheckKey = (sessionId || '_') + '#recheck';
+  if (recheckMs > 0 && due(readState(), recheckKey, now, recheckMs)) {
+    // From the per-effort TABLE, which is what report() returns. It was asked
+    // for from `data.events`, a field report() has never had, so the measured
+    // half of the re-cost was null on every call on every machine and `high`
+    // was left emitting its escape clause alone.
+    const fit = usage.fitFromRates(data.effortRates || [], data.effortNow || null, usage.currentHost());
+    // The user's bounds are the user's, and `pin` is one of them: it lives on
+    // bounds, not on the mode's policy, so it has to be handed over here or
+    // the route comes back unable to say it is a report.
+    const route = usage.escapeRoute(data.windows || [binding], binding, data.effortWarning || null, usage.currentHost(), budget.policy, budget.bounds);
+    const allowed = (suggestion) => mode.allows(budget.bounds, suggestion);
+    // The measured half is a recommendation about the user's own setting, so
+    // it goes out through the advice rules rather than around them: never once
+    // muted, never once declined, never below a bound, and not a second time
+    // in a session where the brief has already made it. Filtering only on the
+    // bounds here meant `mode --no-advice` and `mode --decline` were both
+    // routed around every two minutes, in the one mode that speaks mid-turn.
+    const advice = mode.advicePending({ decided: budget, fit, sessionId });
+    const offerFit = advice.ok && !advice.alreadyOffered ? fit : null;
+    const text = recheckText({
+      fit: offerFit,
+      escape: route && route.kind === 'effort' && allowed({ effort: route.to }) ? route : null,
+      pin: budget.bounds && budget.bounds.pin,
+    });
+    // Say it once.
+    //
+    // Nothing this line is built from moves within a turn, so on the throttle
+    // alone it repeated itself verbatim every two minutes: measured, fifteen
+    // identical injections in one half-hour turn at 20 per cent used. That is
+    // the failure this whole feature exists to avoid, arriving in the mode
+    // named for efficiency. `high` re-costs continuously - it takes the
+    // measurement every two minutes - and speaks when the answer CHANGES.
+    const state = readState();
+    const before = state[recheckKey] && state[recheckKey].said;
+    recheck = text && text !== before ? text : '';
+    // Recorded only when it is actually said, and only for the half that is a
+    // recommendation, so that "no, leave it" has something to refuse: without
+    // this, `mode --decline` after a mid-turn re-cost had no id to act on.
+    if (recheck && offerFit && advice.id) mode.adviceOffer(advice.id, sessionId, now, advice.text);
+    // Claimed whether or not it produced a line: the measurement was taken,
+    // and taking it again in ten seconds would cost the same and say the same.
+    writeState(trim(state, recheckKey, now, text ? { said: text } : null));
+  }
+
   // 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 (!fanout && pressure === 'roomy' && String(process.env.USAGE_LIMITS_PULSE || '').toLowerCase() !== 'always') {
-    return '';
+    return recheck;
   }
 
-  return pulseText({
+  const spoken = pulseText({
     label: binding.label,
     percentUsed: binding.percentUsed,
     approximate: Boolean(binding.estimated || binding.adjusted),
@@ -241,6 +409,49 @@ async function run(now, hookInput) {
     pressure,
     fanout,
   });
+  return recheck ? (spoken ? spoken + ' ' + recheck : recheck) : spoken;
+}
+
+// The cheapest percentage 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.
+//
+// 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
+// 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;
+  };
+  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);
+    }
+  } catch (err) {
+    // A missing or unreadable correction just means the snapshot decides.
+  }
+  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));
+      }
+    }
+  } catch (err) {
+    // Same: no snapshot is a reason not to enforce, not a reason to throw.
+  }
+  return worst;
 }
 
 // PostToolUse does not take plain stdout as context the way UserPromptSubmit
@@ -256,6 +467,22 @@ function envelope(text, event) {
   });
 }
 
+// The refusal envelope.
+//
+// Claude Code and Codex document the same PreToolUse shape: a permissionDecision
+// of "deny" with a reason, which is shown to the model in place of the tool
+// result. Exit code stays 0 - exit 2 also blocks, but routes the reason through
+// stderr, and a reason the model can read is the entire point of refusing.
+function refusal(reason) {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  });
+}
+
 function readHookInput() {
   return new Promise((resolve) => {
     if (process.stdin.isTTY) return resolve(null);
@@ -289,8 +516,14 @@ if (require.main === module) {
       return run(Date.now(), input);
     })
     .then(
-      (text) => {
-        if (text) process.stdout.write(envelope(text, hookEvent) + '\n');
+      (result) => {
+        // A refusal, not a line. Claude Code and Codex take the same shape
+        // here; Antigravity's differs and is handled by its own entry point.
+        if (result && typeof result === 'object' && result.deny) {
+          process.stdout.write(refusal(result.reason) + '\n');
+          process.exit(0);
+        }
+        if (result) process.stdout.write(envelope(result, hookEvent) + '\n');
         process.exit(0);
       },
       () => {
@@ -301,6 +534,7 @@ if (require.main === module) {
 }
 
 module.exports = {
+  recheckText,
   DEFAULT_INTERVAL_SECONDS,
   KEEP_SESSIONS,
   stateFile,
@@ -309,7 +543,10 @@ module.exports = {
   writeState,
   trim,
   due,
+  longCall,
   pulseText,
   envelope,
+  refusal,
+  ceilingPercent,
   run,
 };

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

@@ -24,6 +24,8 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
+const drift = require('./drift.js');
+
 // 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.
@@ -71,18 +73,25 @@ function record(binding, now, codexHome) {
   if (binding.stale || binding.estimated || binding.correctionUnreliable) return false;
   try {
     const all = read(codexHome);
-    all[binding.key] = {
-      at: Number.isFinite(now) ? now : Date.now(),
+    const at = Number.isFinite(now) ? now : Date.now();
+    // Whatever was sitting here before is what the cheap readers had been
+    // trusting; this fresh, checked correction is what the meter actually
+    // said. The gap between them is real drift a session just lived through,
+    // and it is worth keeping regardless of what happens to this record next.
+    const previous = all[binding.key];
+    const next = {
+      at,
       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,
     };
+    if (previous) drift.record(binding.key, previous, next, at, codexHome);
+    all[binding.key] = next;
     // 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];

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

@@ -12,9 +12,17 @@ const usage = require('./usage.js');
 const host = require('./host.js');
 const tally = require('./tally.js');
 const activity = require('./activity.js');
+const mode = require('./mode.js');
 
 async function run(now, hookInput) {
   const sessionId = hookInput && hookInput.session_id ? hookInput.session_id : null;
+
+  // The same rule as the Stop hook, for the same reason: `off` promises the
+  // hooks return before reading anything, and this one read the whole
+  // transcript one last time and printed a closing line. See stop.js.
+  const budget = mode.forSession({ sessionId });
+  if (budget.policy.briefStyle === 'none') return '';
+
   // The session is over, so as far as the panel is concerned it is idle.
   activity.mark('idle', sessionId, null, now);
 

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

@@ -16,9 +16,33 @@ const usage = require('./usage.js');
 const host = require('./host.js');
 const tally = require('./tally.js');
 const activity = require('./activity.js');
+const mode = require('./mode.js');
+const drift = require('./drift.js');
 
 async function run(now, hookInput) {
   const sessionId = hookInput && hookInput.session_id ? hookInput.session_id : null;
+
+  // `off` means off here too, and that is the whole reason this check is the
+  // first thing in the hook rather than a filter on the line at the end.
+  //
+  // This hook was the expensive one left running: it read the entire
+  // transcript after every reply - 2.77 MB on the session that measured it -
+  // wrote two state files and printed a line, in the mode documented as "the
+  // hooks return before reading anything: no scan, no state write, no line".
+  // The line goes to the person rather than into the context, so it cost no
+  // tokens; the scan cost exactly what `standard` costs, which is the half of
+  // that promise that was false.
+  //
+  // Two consequences, both stated where the user sets the mode and in the
+  // docs: no end-of-reply cost line in `off`, and no drift-ledger rows tagged
+  // `off` - a mode that injects nothing has no injection to attribute a cost
+  // to, so there is nothing for the ledger to compare.
+  //
+  // USAGE_LIMITS_TALLY stays the independent control, for anyone who wants the
+  // briefing and not the cost line.
+  const budget = mode.forSession({ sessionId });
+  if (budget.policy.briefStyle === 'none') return '';
+
   // The reply is finished: the panel beside the chat can stop animating.
   activity.mark('idle', sessionId, null, now);
 
@@ -34,6 +58,25 @@ async function run(now, hookInput) {
   });
   tally.writeState(tally.trim(all));
 
+  // The mode ledger: what a reply actually cost, tagged with the mode that was
+  // in force while it ran. Modes should be evidence rather than vibes, and this
+  // is the only place that knows both halves at once. Skipped on the first
+  // sighting of a session, where the figures are history rather than this
+  // reply, and never allowed to disturb the hook.
+  try {
+    if (!created) {
+      drift.recordTurns(
+        budget.name,
+        delta.turns,
+        delta.cost,
+        now,
+        usage.isCodex() ? require('./codex.js').homeDir() : null
+      );
+    }
+  } catch (err) {
+    // A ledger entry is worth nothing next to the line this hook exists for.
+  }
+
   // The first time a session is seen, everything read is history rather than
   // the reply that just finished, so only the total is shown.
   return JSON.stringify({