claude-usage-limits 1.19.0 → 1.24.0

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) {

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

@@ -61,6 +61,8 @@ function parseArgs(argv) {
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--dry-run') args.dryRun = true;
+    // Codex only: leave the [agents] subagent clamp alone.
+    else if (arg === '--no-agents') args.agents = false;
     else if (arg === '--host') args.host = argv[++i];
     else if (arg.startsWith('--host=')) args.host = arg.slice(7);
     else if (arg === '--effort') args.effort = argv[++i];
@@ -169,6 +171,50 @@ function describe(settings, state) {
   return lines.join('\n');
 }
 
+// Write down what was changed here, so "change my effort back" has a referent.
+//
+// This script is the ONLY thing in the plugin that writes settings.json, and
+// it was the only change the log could not name: mode.js recorded fourteen
+// kinds of mode-plane change and nothing ever wrote a user-plane entry, so
+// `mode --history` answered "nothing has been changed through this plugin yet"
+// immediately after this had rewritten the user's baseline, and undo's whole
+// user-plane branch was unreachable code.
+//
+// Required lazily and inside a try: a settings write that already succeeded
+// must not be reported as a failure because a log line could not be added, and
+// this file otherwise depends on nothing.
+//
+// `by` is a reading of the environment, not a claim about intent. Claude Code
+// and Codex both put a session id into the environment of everything they
+// launch, so a run from inside an agent session is recorded as the agent's and
+// a run from the user's own shell as theirs. It is the honest half of "at
+// whose instruction": who typed it, not who wanted it.
+function logSettingsChange(changes, direction, env) {
+  if (!changes || !changes.length) return;
+  const e = env || process.env;
+  const by = e.CLAUDE_SESSION_ID || e.CODEX_SESSION_ID ? 'claude' : 'user';
+  try {
+    const mode = require('./mode.js');
+    for (const change of changes) {
+      // "effortLevel: xhigh -> low", as planApply and planRestore build them.
+      const at = change.indexOf(': ');
+      const key = at === -1 ? change : change.slice(0, at);
+      const rest = at === -1 ? '' : change.slice(at + 2);
+      const arrow = rest.indexOf(' -> ');
+      mode.logChange({
+        plane: 'user',
+        key,
+        from: arrow === -1 ? null : rest.slice(0, arrow),
+        to: arrow === -1 ? rest || null : rest.slice(arrow + 4),
+        by,
+        reason: direction === 'off' ? 'lowpower off' : 'lowpower on',
+      });
+    }
+  } catch (err) {
+    // A record of the change is worth less than the change itself.
+  }
+}
+
 function main(argv) {
   const args = parseArgs(argv);
   const host = require('./host.js');
@@ -196,6 +242,7 @@ function main(argv) {
     if (!state && fs.existsSync(file)) fs.copyFileSync(file, file + '.usage-limits-backup');
     writeJson(file, plan.settings);
     writeJson(stateFile(), plan.state);
+    logSettingsChange(plan.changes, 'on');
     process.stdout.write(
       'Low power on.\n  ' + (plan.changes.join('\n  ') || '(nothing to change)') + '\n' +
         'Applies to new sessions. For the session you are in, run /effort ' +
@@ -216,6 +263,7 @@ function main(argv) {
     }
     writeJson(file, plan.settings);
     fs.unlinkSync(stateFile());
+    logSettingsChange(plan.changes, 'off');
     process.stdout.write(
       'Low power off.\n  ' + (plan.changes.join('\n  ') || '(nothing to change)') + '\n'
     );