claude-usage-limits 1.19.0 → 1.23.0

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

@@ -0,0 +1,254 @@
+'use strict';
+
+// A ledger of how wrong the reading was, measured instead of argued about.
+//
+// The known complaint about this plugin is that its numbers lag reality
+// mid-session - reading.js exists because of one measured instance of it (13%
+// shown, 73% actual). But "it lags" is an anecdote until someone can say by
+// how much, how often, and whether it is getting better or worse as the
+// plugin changes. So every time reading.js records a fresh, trustworthy
+// correction for a window, and there was already a figure sitting there for
+// readers to trust, this writes down what that older figure said next to what
+// the new one says. The gap between them is the drift a real session lived
+// through between two corrections.
+//
+// Same constraints as reading.js: cheap, bounded, and it must never be the
+// reason a hook is late or fails.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const host = require('./host.js');
+const codex = require('./codex.js');
+
+// Not "how many windows" but "how many measurements": a busy day produces a
+// handful of corrections per window, and a fixed cap keeps the file the same
+// size whether the plugin has run for a day or a year.
+const MAX_ENTRIES = 200;
+
+function configDir() {
+  return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+}
+
+function driftFile(codexHome) {
+  return path.join(codexHome || configDir(), 'usage-limits-drift.json');
+}
+
+// The other measurement that belongs here: what a turn actually cost while
+// each budget mode was on. Same file, same bounded append, for the same
+// reason - it is an after-the-fact measurement of a prediction, and a second
+// store would be a second thing to keep correct. Modes should be evidence
+// rather than vibes, and this is where the evidence lands.
+const MAX_MODE_ENTRIES = 400;
+
+function read(codexHome) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(driftFile(codexHome), 'utf8'));
+    if (!parsed || typeof parsed !== 'object') return { entries: [] };
+    const state = { entries: Array.isArray(parsed.entries) ? parsed.entries : [] };
+    // The mode ledger is carried only when the file actually has one. A reader
+    // that has never recorded a mode gets back exactly the shape it wrote, so
+    // adding this second ledger did not change what the first one reads.
+    if (Array.isArray(parsed.modes)) state.modes = parsed.modes;
+    return state;
+  } catch (err) {
+    return { entries: [] };
+  }
+}
+
+// One reply, priced, tagged with the mode that was in force while it ran.
+// Called from the Stop hook, which already has the exact figures.
+function recordTurns(mode, turns, cost, now, codexHome) {
+  if (!mode || !Number.isFinite(turns) || turns <= 0) return false;
+  try {
+    const state = read(codexHome);
+    if (!Array.isArray(state.modes)) state.modes = [];
+    state.modes.push({
+      mode: String(mode),
+      at: Number.isFinite(now) ? now : Date.now(),
+      turns,
+      cost: Number.isFinite(cost) ? cost : 0,
+    });
+    if (state.modes.length > MAX_MODE_ENTRIES) state.modes = state.modes.slice(-MAX_MODE_ENTRIES);
+    writeAtomic(driftFile(codexHome), state);
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+// Turns and observed cost per turn, per mode. Only what was measured: a mode
+// nothing has run in is absent rather than shown at zero, because a zero here
+// reads as "free" when it means "unknown".
+function modeSummary(codexHome) {
+  const rows = {};
+  for (const entry of read(codexHome).modes || []) {
+    if (!entry || !entry.mode || !Number.isFinite(entry.turns)) continue;
+    const row = rows[entry.mode] || (rows[entry.mode] = { mode: entry.mode, turns: 0, usd: 0 });
+    row.turns += entry.turns;
+    row.usd += Number.isFinite(entry.cost) ? entry.cost : 0;
+  }
+  return Object.keys(rows)
+    .map((key) => {
+      const row = rows[key];
+      return {
+        mode: row.mode,
+        turns: row.turns,
+        usd: row.usd,
+        usdPerTurn: row.turns > 0 && row.usd > 0 ? row.usd / row.turns : null,
+      };
+    })
+    .sort((a, b) => b.turns - a.turns);
+}
+
+function writeAtomic(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  // Same beside-and-rename as reading.js: the pulse and the prompt hook can
+  // both land here in the same second.
+  const tmp = file + '.' + process.pid + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(data));
+  fs.renameSync(tmp, file);
+}
+
+// `previous` and `next` are both entries in reading.js's own shape - see
+// reading.record(). Called from there, right before it overwrites the slot,
+// so `previous` is what readers were trusting and `next` is what the fresh
+// scan just found for the same window.
+function record(key, previous, next, now, codexHome) {
+  if (!key || !previous || !next) return false;
+  if (!Number.isFinite(previous.percentUsed) || !Number.isFinite(next.percentUsed)) return false;
+  if (!Number.isFinite(previous.at)) return false;
+  const at = Number.isFinite(now) ? now : Date.now();
+  // A window that reset between the two readings did not "drift" - it started
+  // over, and treating the jump as error would swamp every real measurement.
+  if (Number.isFinite(previous.resetsAt) && previous.resetsAt <= next.at) return false;
+  try {
+    const state = read(codexHome);
+    state.entries.push({
+      key,
+      at,
+      // How long the older figure had been sitting in front of readers before
+      // this measurement replaced it - a drift found after two minutes and
+      // one found after twenty are not the same kind of evidence.
+      ageMs: Math.max(0, next.at - previous.at),
+      predictedPercentUsed: previous.percentUsed,
+      actualPercentUsed: next.percentUsed,
+      percentDrift: next.percentUsed - previous.percentUsed,
+      predictedTurnsLeft: Number.isFinite(previous.turnsLeft) ? previous.turnsLeft : null,
+      actualTurnsLeft: Number.isFinite(next.turnsLeft) ? next.turnsLeft : null,
+    });
+    if (state.entries.length > MAX_ENTRIES) state.entries = state.entries.slice(-MAX_ENTRIES);
+    writeAtomic(driftFile(codexHome), state);
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+function median(values) {
+  if (!values.length) return null;
+  const sorted = values.slice().sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+// What the ledger has actually shown: the typical gap and the worst one, in
+// percentage points, over whatever window filter is asked for (default:
+// everything on record). Turns get the same treatment where both sides of a
+// pair have a turns figure to compare.
+function summary(codexHome, options) {
+  const opts = options || {};
+  const state = read(codexHome);
+  let entries = state.entries;
+  if (opts.key) entries = entries.filter((e) => e.key === opts.key);
+  if (!entries.length) return { sample: 0, medianAbsPercent: null, worstAbsPercent: null, medianAbsTurns: null, worstAbsTurns: null };
+
+  const percentAbs = entries.map((e) => Math.abs(e.percentDrift));
+  const turnsAbs = entries
+    .filter((e) => Number.isFinite(e.predictedTurnsLeft) && Number.isFinite(e.actualTurnsLeft))
+    .map((e) => Math.abs(e.actualTurnsLeft - e.predictedTurnsLeft));
+
+  // A number of points on its own says nothing: sixty points off is a scandal
+  // over two minutes and unremarkable over five hours. The gap the figure was
+  // wrong for is what makes it readable, and it is already on every entry.
+  const ages = entries.map((e) => e.ageMs).filter((ms) => Number.isFinite(ms));
+  const worst = entries.reduce(
+    (found, e) => (!found || Math.abs(e.percentDrift) > Math.abs(found.percentDrift) ? e : found),
+    null
+  );
+
+  return {
+    sample: entries.length,
+    medianAbsPercent: median(percentAbs),
+    worstAbsPercent: percentAbs.length ? Math.max(...percentAbs) : null,
+    medianAbsTurns: turnsAbs.length ? median(turnsAbs) : null,
+    worstAbsTurns: turnsAbs.length ? Math.max(...turnsAbs) : null,
+    medianGapMs: ages.length ? median(ages) : null,
+    worstGapMs: worst && Number.isFinite(worst.ageMs) ? worst.ageMs : null,
+  };
+}
+
+// Minutes, because that is the scale a correction interval lives on and the
+// only one anybody compares against the pulse interval.
+function gap(ms) {
+  if (!Number.isFinite(ms)) return null;
+  const minutes = ms / 60000;
+  return (minutes >= 10 ? Math.round(minutes) : Math.round(minutes * 10) / 10) + 'm';
+}
+
+function describe(codexHome) {
+  const stats = summary(codexHome);
+  if (!stats.sample) return 'Drift ledger: no corrections measured against an earlier one yet.';
+  const lines = [];
+  lines.push('Drift ledger: ' + stats.sample + ' measured correction' + (stats.sample === 1 ? '' : 's') + '.');
+  const medianGap = gap(stats.medianGapMs);
+  const worstGap = gap(stats.worstGapMs);
+  lines.push(
+    '  Percent used: median ' + fmt(stats.medianAbsPercent) + ' points off' +
+      (medianGap ? ' over a typical ' + medianGap + ' gap' : '') + ', worst ' +
+      fmt(stats.worstAbsPercent) + ' points off' + (worstGap ? ' over ' + worstGap : '') + '.'
+  );
+  if (stats.medianAbsTurns !== null) {
+    lines.push(
+      '  Turns left: median ' + fmt(stats.medianAbsTurns) + ' off, worst ' + fmt(stats.worstAbsTurns) + ' off.'
+    );
+  }
+  return lines.join('\n');
+}
+
+function fmt(value) {
+  if (!Number.isFinite(value)) return '-';
+  return Math.round(value * 10) / 10;
+}
+
+function activeCodexHome(argv, env) {
+  return host.detect(argv, env) === host.CODEX ? codex.homeDir() : null;
+}
+
+function main(argv) {
+  const args = argv || [];
+  const codexHome = activeCodexHome(args, process.env);
+  if (args[0] === '--json') return JSON.stringify(summary(codexHome, {}), null, 2);
+  return describe(codexHome);
+}
+
+if (require.main === module) {
+  process.stdout.write(main(process.argv.slice(2)) + '\n');
+  process.exit(0);
+}
+
+module.exports = {
+  MAX_ENTRIES,
+  MAX_MODE_ENTRIES,
+  configDir,
+  driftFile,
+  gap,
+  read,
+  record,
+  recordTurns,
+  modeSummary,
+  summary,
+  describe,
+  main,
+};

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

@@ -204,8 +204,18 @@ function line(built, options) {
         : bars.paint(effortName, effort.rgb, mode);
   // The word, in the rainbow, the way Claude Code paints it in the prompt.
   const thinking = built.ultrathink ? ' ' + bars.dim('·', mode) + ' ' + bars.rainbow('ultrathink', tick, { mode, reduced }) : '';
+  // The budget mode, only when it is not the one the plugin has always been
+  // in. `standard` is today's behaviour and today's line, unchanged to the
+  // character; anything else changes what the hooks say, and a line that does
+  // not mention it leaves the user guessing why the briefing went quiet.
+  // It rides on the head so the width ladder drops it with the head, before it
+  // ever costs a percentage its place.
+  const budgetText =
+    built.budget && built.budget.name !== 'standard'
+      ? ' ' + bars.dim('·', mode) + ' ' + bars.dim('budget ' + built.budget.label, mode)
+      : '';
   const head =
-    glyph + ' ' + built.modelLabel + (effortText ? ' ' + bars.dim('·', mode) + ' ' + effortText : '') + thinking;
+    glyph + ' ' + built.modelLabel + (effortText ? ' ' + bars.dim('·', mode) + ' ' + effortText : '') + thinking + budgetText;
 
   const segment = (row, width, shorter) => {
     const label = shortLabel(row, shorter);
@@ -396,6 +406,17 @@ function motionOff(settings, env) {
 
 // Written and flushed before the process is allowed to end: stdout is a pipe
 // here, and a pipe write can still be in flight when process.exit runs.
+// The budget mode, for the token on the line. Wrapped and lazy: the status
+// line must never fail over an optional word, and a machine that has never set
+// a mode should not pay for a require to be told so.
+function budgetNow(sessionId) {
+  try {
+    return require('./mode.js').forSession({ sessionId });
+  } catch (err) {
+    return null;
+  }
+}
+
 function out(text) {
   return new Promise((resolve) => {
     process.stdout.write(text, () => resolve());
@@ -461,6 +482,7 @@ async function main(argv) {
     const built = view.build({
       now,
       agents: usage.liveAgents(now),
+      budget: budgetNow(mine || (slot && slot.sessionId) || null),
       utilization: collected.utilization,
       fetchedAtMs: collected.snapshotFetchedAt,
       source: collected.snapshotSource,

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

@@ -18,6 +18,15 @@ const path = require('path');
 
 const CLAUDE = 'claude';
 const CODEX = 'codex';
+const GEMINI = 'gemini';
+
+function geminiConfigDir() {
+  return process.env.GEMINI_CONFIG_DIR || path.join(os.homedir(), '.gemini');
+}
+
+function geminiHome() {
+  return process.env.GEMINI_HOME || path.join(geminiConfigDir(), 'antigravity-cli');
+}
 
 function codexHome() {
   return process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
@@ -66,16 +75,20 @@ function codexHasSessions() {
   return exists(path.join(codexHome(), 'sessions'));
 }
 
+function geminiHasSessions() {
+  return exists(geminiHome());
+}
+
 function normalise(value) {
   const name = String(value || '').trim().toLowerCase();
+  if (name === GEMINI || name === 'agy' || name === 'antigravity' || name === 'google') return GEMINI;
   if (name === CODEX || name === 'chatgpt' || name === 'openai') return CODEX;
   if (name === CLAUDE || name === 'claude-code' || name === 'anthropic') return CLAUDE;
   return null;
 }
 
-// `--host codex` beats everything, then the environment variable, then what is
-// actually on disk. Claude wins ties: it is the host the hook was written for,
-// and its reader fails loudly rather than silently reporting nothing.
+// `--host gemini` beats everything, then the environment variable, then what is
+// actually on disk.
 function detect(argv, env) {
   const args = argv || [];
   const at = args.indexOf('--host');
@@ -86,6 +99,8 @@ function detect(argv, env) {
   const fromEnv = normalise(environment.USAGE_LIMITS_HOST);
   if (fromEnv) return fromEnv;
 
+  // Set by Antigravity / Gemini CLI
+  if (environment.ANTIGRAVITY_CLI || environment.GEMINI_CLI || environment.GEMINI_WORKSPACE) return GEMINI;
   // Set by Claude Code for plugin hooks and commands.
   if (environment.CLAUDE_PLUGIN_ROOT || environment.CLAUDE_PROJECT_DIR) return CLAUDE;
   // Set by Codex for the processes it launches.
@@ -93,14 +108,19 @@ function detect(argv, env) {
 
   if (claudeHasSnapshot()) return CLAUDE;
   if (codexHasSessions()) return CODEX;
+  if (geminiHasSessions()) return GEMINI;
   return CLAUDE;
 }
 
 module.exports = {
   CLAUDE,
   CODEX,
+  GEMINI,
   detect,
   normalise,
+  geminiHome,
+  geminiConfigDir,
+  geminiHasSessions,
   codexHome,
   claudeConfigDir,
   claudeHasSnapshot,

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

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+'use strict';
+
+// Installs the plugin into Antigravity.
+//
+// Antigravity discovers customizations from ~/.gemini/config/ on a machine, and
+// a plugin there is a directory holding plugin.json, optionally hooks.json,
+// rules/ and skills/. That is documented on the machine itself, in the built-in
+// agy-customizations skill, and this installer follows it rather than guessing:
+//
+//   ~/.gemini/config/plugins/usage-limits/
+//     plugin.json      the marker that makes the directory a plugin
+//     hooks.json       PreInvocation for the budget line, PreToolUse for the ceiling
+//     rules/AGENTS.md  the always-on rules
+//
+// The installed directory is deliberately small. Hooks run with their working
+// directory set to the folder containing hooks.json, so a copied plugin would
+// need the whole script tree copied with it and would then go stale the moment
+// the real one was updated. Instead the commands carry an absolute path back to
+// this checkout, so there is one copy of the code and updating it updates what
+// Antigravity runs.
+//
+//   node install-antigravity.js status
+//   node install-antigravity.js on
+//   node install-antigravity.js off
+//
+// Everything written is confined to that one directory, and `off` removes
+// exactly what `on` created and nothing else.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const host = require('./host.js');
+
+const PLUGIN = 'usage-limits';
+
+function pluginsDir() {
+  return path.join(host.geminiConfigDir(), 'config', 'plugins');
+}
+
+function pluginDir() {
+  return path.join(pluginsDir(), PLUGIN);
+}
+
+// Forward slashes on every platform. They work in Windows paths and keep the
+// command free of escapes in both JSON and the shell that runs it. Antigravity
+// 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, '/') + '"';
+}
+
+function scriptPath(name) {
+  return path.join(__dirname, name);
+}
+
+function hookCommand(event) {
+  return 'node ' + quote(scriptPath('agy-hook.js')) + ' --event ' + event;
+}
+
+function manifest() {
+  return {
+    name: PLUGIN,
+    description:
+      'Puts the remaining usage budget in front of the agent before each turn, and enforces a ' +
+      'ceiling past which fan-out calls are refused.',
+  };
+}
+
+function hooks() {
+  return {
+    'usage-limits-brief': {
+      PreInvocation: [{ type: 'command', command: hookCommand('PreInvocation'), timeout: 10 }],
+    },
+    'usage-limits-ceiling': {
+      PreToolUse: [
+        {
+          matcher: '.*',
+          hooks: [{ type: 'command', command: hookCommand('PreToolUse'), timeout: 10 }],
+        },
+      ],
+    },
+  };
+}
+
+function rulesText() {
+  // Shipped from the repo so there is one copy of the wording, but never fails
+  // the install over a missing file: the hooks are the part that matters.
+  try {
+    return fs.readFileSync(path.join(__dirname, '..', '..', '..', 'rules', 'AGENTS.md'), 'utf8');
+  } catch (err) {
+    return null;
+  }
+}
+
+function writeFile(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = file + '.' + process.pid + '.tmp';
+  fs.writeFileSync(tmp, text, 'utf8');
+  fs.renameSync(tmp, file);
+}
+
+function installed() {
+  try {
+    fs.accessSync(path.join(pluginDir(), 'plugin.json'));
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+// Whether Antigravity is on this machine at all. Its config directory is the
+// evidence; ~/.gemini alone is not, because the Gemini CLI uses that too.
+function present() {
+  return host.exists(path.join(host.geminiConfigDir(), 'antigravity-cli')) ||
+    host.exists(path.join(host.geminiConfigDir(), 'antigravity'));
+}
+
+function status() {
+  const lines = [];
+  lines.push('Antigravity   ' + (present() ? 'found at ' + host.geminiConfigDir() : 'not found on this machine'));
+  lines.push('Plugin        ' + (installed() ? 'installed at ' + pluginDir() : 'not installed'));
+  if (installed()) {
+    let current = null;
+    try {
+      current = JSON.parse(fs.readFileSync(path.join(pluginDir(), 'hooks.json'), 'utf8'));
+    } catch (err) {
+      // An unreadable hooks.json is worth saying rather than throwing.
+    }
+    const events = current ? Object.keys(current).map((name) => Object.keys(current[name]).filter((k) => k !== 'enabled').join(', ')) : [];
+    lines.push('Hooks         ' + (events.length ? events.join(', ') : 'none readable'));
+    lines.push(
+      'Enabled       recorded in ' +
+        path.join(host.geminiConfigDir(), 'config', 'config.json') +
+        ' under plugins.' + PLUGIN + '; a plugin with no entry there is on by default.'
+    );
+  }
+  if (!present()) {
+    lines.push('');
+    lines.push('Nothing to install into. Antigravity keeps its configuration in ~/.gemini/config.');
+  }
+  return lines.join('\n');
+}
+
+function enable() {
+  if (!present()) {
+    return (
+      'Antigravity was not found on this machine, so there is nothing to install into.\n' +
+      'Expected its configuration at ' + host.geminiConfigDir() + '.'
+    );
+  }
+  const dir = pluginDir();
+  writeFile(path.join(dir, 'plugin.json'), JSON.stringify(manifest(), null, 2) + '\n');
+  writeFile(path.join(dir, 'hooks.json'), JSON.stringify(hooks(), null, 2) + '\n');
+  const rules = rulesText();
+  if (rules) writeFile(path.join(dir, 'rules', 'AGENTS.md'), rules);
+
+  return [
+    'Installed into ' + dir + '.',
+    '  PreInvocation  the budget line, as an injected ephemeral message',
+    '  PreToolUse     the ceiling, which refuses fan-out calls past it',
+    rules ? '  rules/AGENTS.md  the always-on rules' : '  (rules/AGENTS.md was not found in this checkout and was skipped)',
+    '',
+    'The hooks run this checkout directly, so updating it updates what Antigravity runs.',
+    'Antigravity picks the plugin up when it next starts. There is no quota figure for it: ' +
+      'Antigravity refreshes its own quota but writes it nowhere readable, so the budget line ' +
+      'reports what it can and says so where it cannot.',
+  ].join('\n');
+}
+
+// Removes only what enable() wrote, one named file at a time, and only takes
+// the directory away when nothing else has been put in it.
+function disable() {
+  const dir = pluginDir();
+  if (!installed()) return 'Not installed. Nothing to remove.';
+  const removed = [];
+  for (const relative of ['plugin.json', 'hooks.json', path.join('rules', 'AGENTS.md')]) {
+    const file = path.join(dir, relative);
+    try {
+      fs.unlinkSync(file);
+      removed.push(relative);
+    } catch (err) {
+      // Already gone is the outcome that was asked for.
+    }
+  }
+  for (const relative of ['rules', '']) {
+    try {
+      fs.rmdirSync(path.join(dir, relative));
+    } catch (err) {
+      // Not empty, or already gone. Either way it is not ours to force.
+    }
+  }
+  return 'Removed ' + (removed.length ? removed.join(', ') : 'nothing') + ' from ' + dir + '.';
+}
+
+function main(argv) {
+  const command = (argv || []).find((arg) => !arg.startsWith('-')) || 'status';
+  if (command === 'status') return status();
+  if (command === 'on') return enable();
+  if (command === 'off') return disable();
+  throw new Error('Expected status, on or off');
+}
+
+if (require.main === module) {
+  try {
+    process.stdout.write(main(process.argv.slice(2)) + '\n');
+    process.exitCode = 0;
+  } catch (err) {
+    process.stderr.write('install-antigravity: ' + (err && err.message ? err.message : String(err)) + '\n');
+    process.exitCode = 1;
+  }
+}
+
+module.exports = { PLUGIN, pluginsDir, pluginDir, hookCommand, manifest, hooks, installed, present, status, enable, disable, main };

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

@@ -53,6 +53,22 @@ const EVENTS = [
   // tool calls of its own for as long as they run. Same quiet refresh as on
   // Claude Code; pulse.js sees the event name and says nothing.
   { event: 'SubagentStop', script: 'pulse.js', status: 'Checking usage limits' },
+  // The ceiling, and the only entry here that can refuse anything.
+  //
+  // Codex is the host where a reported figure demonstrably does not change
+  // behaviour, and the reason is not stubbornness: gpt-6-astra's own system
+  // prompt, shipped in models_cache.json, tells it "do not settle for a partial
+  // or helpful enough solution that does not fully satisfy the user's task to
+  // save time, effort or tokens", and ranks the live user instruction above
+  // anything an AGENTS.md or a skill says. A line asking it to economise is
+  // arguing with its own instructions and losing.
+  //
+  // So this one does not ask. PreToolUse takes a permissionDecision of "deny",
+  // and past the ceiling the fan-out calls get one. The matcher is broad
+  // because ceiling.js decides what is actually a multiplier; a hook that fires
+  // and returns nothing costs a few milliseconds, and a matcher that misses a
+  // renamed tool costs the window.
+  { event: 'PreToolUse', script: 'pulse.js', status: 'Checking usage limits', matcher: '.*' },
 ];
 const EVENT = EVENTS[0].event;
 // Ten seconds is the same budget the Claude hook gets. The brief caches the
@@ -360,7 +376,7 @@ function enable() {
 
   for (const one of EVENTS) {
     const rest = withoutOurs(config.hooks[one.event]);
-    rest.push({
+    const group = {
       hooks: [
         {
           type: 'command',
@@ -369,7 +385,11 @@ function enable() {
           statusMessage: one.status,
         },
       ],
-    });
+    };
+    // Tool-scoped events take a matcher; the others ignore one, and writing a
+    // matcher where none belongs is the kind of thing a strict parser rejects.
+    if (one.matcher) group.matcher = one.matcher;
+    rest.push(group);
     config.hooks[one.event] = rest;
   }
   if (!config.description) {