claude-usage-limits 1.18.0 → 1.23.0

package/skills/usage-limits/references/tactics.md

@@ -87,15 +87,46 @@ reason, if none of them are in use.
 
 Cache reads are ten times cheaper than fresh input, and the cache matches on
 an exact prefix. Any byte that changes early invalidates everything after it.
-Things that invalidate it mid-session:
-
-- switching models
-- editing `CLAUDE.md` or project settings
-- connecting or disconnecting an MCP server
-- changing the tool set
-
-None of these are forbidden. Just do them at a session boundary instead of in
-the middle of a long run.
+What actually invalidates it mid-session:
+
+- **switching models** - each model has its own cache, so the next request
+  re-reads the whole conversation even though the content is identical
+- **changing the effort level** - on most models each effort level has its own
+  cache too. This one matters here because dropping effort is the saving this
+  plugin recommends most often. It is still worth doing, but it is not free
+  mid-session: on a large context the one-off rebuild can cost more than a few
+  cheaper turns save. Choose effort at the START of a session where you can
+- **turning on fast mode** - it adds a request header that is part of the cache key
+- **connecting or disconnecting an MCP server, but only when its tools sit in
+  the prefix.** With tool search - the default on supported models - a server
+  connecting, disconnecting or changing its tool list only appends, and the
+  cached prefix survives
+- **enabling or disabling a plugin that provides MCP servers**, by the same
+  rule. A plugin ships skills, commands, agents and hooks by appending them,
+  and those never invalidate anything
+- **adding or removing a bare tool-name deny rule** (`Bash`, `WebFetch`), which
+  takes the tool out of the system prompt. Scoped rules like `Bash(rm *)` do not
+- **compacting**, by design, and **upgrading Claude Code**
+
+What does NOT invalidate it, despite being widely believed to:
+
+- **editing `CLAUDE.md` mid-session.** It is read once at session start and held
+  in memory. The edit does not invalidate the cache - and it also does not
+  apply, until `/clear`, `/compact` or a restart
+- editing files in the repository, changing permission mode, changing output
+  style, invoking a skill or command, and `/recap`
+
+None of the invalidating ones are forbidden. Just do them at a session boundary
+instead of in the middle of a long run.
+
+**`/rewind` rather than `/compact`** when abandoning a path: it truncates back to
+a prefix that is already cached, where compaction builds a new one and pays a
+summarisation call to do it.
+
+**Cache scope is one machine and one directory.** Parallel sessions in the same
+directory read each other cache; different directories do not - and that
+includes two worktrees of the same repository, which is a real and unobvious
+cost of isolating agents that way.
 
 ### 6. Batch tool calls
 

package/skills/usage-limits/scripts/agy-hook.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+'use strict';
+
+// The Antigravity entry point.
+//
+// Antigravity (and the `agy` CLI behind it) has a lifecycle-hook system that is
+// close to Claude Code's in spirit and different from it in every detail that
+// matters to a script:
+//
+//   - Events are PreInvocation, PostInvocation, PreToolUse, PostToolUse and
+//     Stop. PreInvocation is the one that corresponds to UserPromptSubmit.
+//   - Every payload is protojson, so the keys are camelCase: conversationId,
+//     workspacePaths, transcriptPath, modelName, stepIdx, invocationNum.
+//   - Output is JSON on stdout, and each event has its own shape. Plain text
+//     on stdout is not context; it is a parse failure, and a parse failure is
+//     silent. That is the whole reason this file exists rather than pointing
+//     Antigravity at brief.js and hoping.
+//   - PreToolUse takes a decision of allow, deny, ask or force_ask.
+//
+// The contract is documented on the machine itself, in the built-in
+// agy-customizations skill at
+// ~/.gemini/antigravity-cli/builtin/skills/agy-customizations/docs/hooks.md,
+// which is where these shapes were read from rather than guessed.
+//
+//   node agy-hook.js --event PreInvocation
+//   node agy-hook.js --event PreToolUse
+//
+// Nothing here ever exits non-zero. Antigravity runs hooks synchronously and
+// they block the agent loop, so a hook that fails is a hook that stops the
+// user's work, and no budget figure is worth that.
+
+const usage = require('./usage.js');
+const host = require('./host.js');
+const mode = require('./mode.js');
+const ceiling = require('./ceiling.js');
+const brief = require('./brief.js');
+
+const EVENTS = ['PreInvocation', 'PostInvocation', 'PreToolUse', 'PostToolUse', 'Stop'];
+
+function eventFrom(argv, input) {
+  const args = argv || [];
+  const at = args.indexOf('--event');
+  if (at !== -1 && EVENTS.includes(args[at + 1])) return args[at + 1];
+  // Antigravity does not name the event in the payload, so the shape is the
+  // only other evidence. toolCall is only ever present on the two tool events,
+  // and only PreToolUse can act on one.
+  if (input && input.toolCall) return 'PreToolUse';
+  if (input && input.terminationReason !== undefined) return 'Stop';
+  if (input && input.invocationNum !== undefined) return 'PreInvocation';
+  return null;
+}
+
+function readInput() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve(null);
+    let raw = '';
+    let settled = false;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      try {
+        resolve(raw ? JSON.parse(raw) : null);
+      } catch (err) {
+        resolve(null);
+      }
+    };
+    const timer = setTimeout(done, 500);
+    if (timer.unref) timer.unref();
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      raw += chunk;
+    });
+    process.stdin.on('end', done);
+    process.stdin.on('error', done);
+  });
+}
+
+// The tool name, as Antigravity spells it.
+//
+// Tool names there are the step type lowercased with the CORTEX_STEP_TYPE_
+// prefix removed, so they are snake_case: run_command, view_file, browser_*.
+// ceiling.js matches both spellings, so nothing has to be translated here.
+function toolNameOf(input) {
+  if (!input || !input.toolCall) return '';
+  return String(input.toolCall.name || '');
+}
+
+// The cheapest percentage worth enforcing against.
+//
+// Antigravity does not publish remaining quota anywhere this can read - see
+// collectGemini in usage.js, which says so rather than inventing a number - so
+// on a Gemini host this is usually null and the ceiling never fires. It is
+// still wired, because the same hook file runs when USAGE_LIMITS_HOST names a
+// host that DOES have a meter, and because a ceiling that silently does
+// nothing on the day Antigravity starts publishing one would be worse.
+function percentNow(now) {
+  let worst = null;
+  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') continue;
+        const value = Number(window.utilization);
+        if (Number.isFinite(value) && (worst === null || value > worst)) worst = value;
+      }
+    }
+  } catch (err) {
+    // No reading is a reason not to enforce, never a reason to throw.
+  }
+  return worst;
+}
+
+async function run(now, input, argv) {
+  const event = eventFrom(argv, input);
+  if (!event) return {};
+
+  usage.setHost(host.GEMINI);
+  const sessionId = input && input.conversationId ? String(input.conversationId) : null;
+  const budget = mode.forSession({ sessionId });
+  if (budget.policy.briefStyle === 'none') return {};
+
+  if (event === 'PreToolUse') {
+    const tool = toolNameOf(input);
+    if (!ceiling.isMultiplier(tool)) return {};
+    const at = ceiling.assess({ percent: percentNow(now), state: budget.state, env: process.env });
+    const call = ceiling.verdict(at, tool);
+    if (call.decision !== 'deny') return {};
+    return { decision: 'deny', reason: call.reason };
+  }
+
+  if (event === 'PreInvocation') {
+    // The one place a budget line can reach the model. Antigravity takes it as
+    // an injected step rather than as stdout text; an ephemeralMessage is a
+    // transient system message, which is exactly what a per-turn figure is.
+    let text = '';
+    try {
+      text = await brief.run(now, input);
+    } catch (err) {
+      text = '';
+    }
+    const warning = ceiling.warning(
+      ceiling.assess({ percent: percentNow(now), state: budget.state, env: process.env })
+    );
+    const message = [text, warning].filter(Boolean).join(' ');
+    return message ? { injectSteps: [{ ephemeralMessage: message }] } : { injectSteps: [] };
+  }
+
+  // PostToolUse, PostInvocation and Stop all want an object and none of them
+  // wants anything from this plugin. Deliberately NOT returning
+  // terminationBehavior on PostInvocation, and NOT returning decision
+  // "continue" on Stop: both would keep the loop running, which is the
+  // opposite of what a budget plugin should ever do to a user's quota.
+  return {};
+}
+
+if (require.main === module) {
+  readInput()
+    .then((input) => run(Date.now(), input, process.argv.slice(2)))
+    .then(
+      (result) => {
+        process.stdout.write(JSON.stringify(result || {}) + '\n');
+        process.exit(0);
+      },
+      () => {
+        // Hooks block the agent loop here, so a failure has to be silent and
+        // well formed rather than loud.
+        process.stdout.write('{}\n');
+        process.exit(0);
+      }
+    );
+}
+
+module.exports = { EVENTS, eventFrom, toolNameOf, percentNow, run };