claude-usage-limits 1.19.0 → 1.24.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.19.0",
+  "version": "1.24.0",
   "description": "Puts your remaining Claude Code usage limit into Claude's context before every prompt, so it opens with what fits in the budget instead of starting work that gets cut off. Reports headroom as turns rather than percentages, prices a job before you start it, and detects your plan tier.",
   "author": {
     "name": "Ridelink",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "usage-limits",
-  "version": "1.19.0",
+  "version": "1.24.0",
   "description": "Reports how much of your Codex usage limit is left as turns of work rather than a percentage, prices a job before you start it, and counts the other agents sharing the same budget.",
   "author": {
     "name": "Ridelink",

package/README.md

@@ -839,6 +839,109 @@ and are counted together. On this machine the transcripts carry both `cli` and
 Windows, macOS, and Linux all work. `CLAUDE_CONFIG_DIR` is honoured if you have
 moved the config directory.
 
+## Budget modes
+
+This plugin is not free. It puts a line into the model's context before every
+prompt, refreshes readings after tool calls, and keeps a status line alive. A
+mode called "save tokens" that still injects four hundred tokens of advice per
+turn is not saving anything - it is charging you for the advice about saving.
+
+So a mode changes two things, not one: what the plugin tells the agent to do,
+and what it costs to say it.
+
+```
+claude-usage-limits mode                  which one, where it came from
+claude-usage-limits mode max              set it
+claude-usage-limits mode off --guard 95   off, except one line near the wall
+claude-usage-limits mode auto             pick from pressure, always reported
+claude-usage-limits mode --list           all four, and the aliases
+claude-usage-limits mode --ledger         measured cost per turn, per mode
+```
+
+| mode | what it does | what it costs |
+| --- | --- | --- |
+| `max` | fewest tokens that can still finish the job | one terse line, readings every 10 minutes, silent while nothing a decision depends on has moved |
+| `high` | full capability, re-costed every two minutes mid-turn | the normal line, **plus a standing directive on every prompt** (about 650 characters, so a `high` briefing runs roughly 40% longer than `standard`), plus a short re-cost the first time a cheaper tier would do the same job - re-measured every two minutes, said only when the answer changes |
+| `standard` | what the plugin has always done | today's line, today's cadences, unchanged |
+| `off` | nothing at all | every hook returns before reading anything: no scan, no state write, no line, no end-of-reply tally |
+
+`high` is the mode that spends a little more to waste a lot less: it carries a
+standing directive and re-measures mid-turn, so its own line is longer than
+`standard`'s. `max` is the one that costs less to say. Picking `high` because
+the word sounds efficient and expecting a shorter line is the one
+misunderstanding worth heading off.
+
+Aliases, because people ask for these in their own words: `ultra`,
+`ultra-efficient`, `maxtoken`, `maxefficient` for `max`; `smart`,
+`high-efficient` for `high`; `efficient`, `token-efficient`, `default`, `on`
+for `standard`; `none`, `quiet`, `silent`, `ignore` for `off`.
+
+**`normal` is deliberately not an alias.** To some people it means "the plugin
+working as usual" (`standard`); to others it means "the plugin stays out of the
+way" (`off`). Those are opposite instructions, so guessing is wrong half the
+time. Ask for `normal` and you get a question back, not a setting.
+
+`off` means off, including at 100 per cent used. That is what it says and it is
+honoured literally - which is also the failure this plugin exists to prevent,
+so setting it prints the consequence once and offers `--guard 95`: one short
+line when the window is nearly spent, and nothing else, ever. The default guard
+is none. Discoverable, not imposed.
+
+The one thing a mode never does is lower the quality of the work. When things
+are tight you change the ORDER of the work, never the amount or the quality.
+The savings come from ceremony - speculative reads, re-reads, preamble,
+subagents nobody needed, workflows that cost more context than they save - and
+the directives say that outright, because a model reading "use fewer tokens"
+will otherwise quietly decide to skip the hard part. There is a test for it,
+and another one that checks the `max` line is never longer than the `standard`
+line for the same reading.
+
+### Two planes, and which one is whose
+
+There are two separate things people mean by "change the model":
+
+- **The user plane** is your `settings.json` (`model`, `effortLevel`), the
+  `/effort` and `/model` pickers, and `lowpower.js`. It is you saying what you
+  want for yourself. The plugin reads it, shows it, and **never writes it on
+  its own initiative.** Claude may recommend a change, and make one if you ask;
+  it may not make one unasked. There is a test that exercises every mode, every
+  alias, `auto`, the bounds and the guard, and then checks `settings.json` is
+  byte-identical.
+- **The agent plane** is the tier actually running the turn, and the tier of
+  everything the turn spawns. That is what costs money, and that is what the
+  modes govern.
+
+`claude-usage-limits mode --baseline` shows both side by side. The budget line
+now says the tier as well, and where the reading came from, because the number
+that decides what a turn costs was the one number the line never printed.
+
+What Claude can genuinely move, stated without embroidery: the model on an
+`Agent` call, and the model and effort inside a `Workflow` script. Its own
+model and effort it cannot change mid-session - no hook output field exists for
+it, on either host - so the plugin names the exact command and leaves it with
+you. It does not pretend otherwise.
+
+You can bound what it may suggest:
+
+```
+claude-usage-limits mode --floor sonnet/medium   # never point below this
+claude-usage-limits mode --ceiling opus/xhigh    # nor above it
+claude-usage-limits mode --pin                   # report only, suggest nothing
+claude-usage-limits mode --decline               # no, and stop suggesting that
+```
+
+And when you say "put it back", there is something to put it back to:
+
+```
+claude-usage-limits mode --history   what changed, when, at whose instruction
+claude-usage-limits mode undo        reverse the last change, naming it first
+```
+
+`undo` reverses what the plugin owns. For a change to your own settings it
+names the entry and the command that undoes it and leaves the file alone -
+which is the same rule as everywhere else, and the reason the byte-identical
+test can never go green by accident.
+
 ## Working cheaply on purpose
 
 Half the problem is measurement. The other half is that a high effort setting
@@ -972,7 +1075,8 @@ skills/usage-limits/scripts/      usage.js, brief.js, pulse.js, stop.js,
                                   lowpower.js, install-codex-hook.js,
                                   recommend.js, panel.js, feed.js,
                                   statusline.js, live.js, view.js, bars.js,
-                                  activity.js
+                                  activity.js, reading.js, drift.js,
+                                  mode.js, voice.js, relay.js, wake.js
 skills/usage-limits/references/   the longer notes
 hooks/hooks.json                  runs brief.js before each prompt, pulse.js
                                   during long turns, stop.js after each reply
@@ -981,6 +1085,7 @@ commands/check.md                 the /usage-limits:check command
 commands/session.md               the /usage-limits:session command
 commands/panel.md                 the /usage-limits:panel command
 commands/statusline.md            the /usage-limits:statusline command
+commands/usage-mode.md            the /usage-mode command
 bin/cli.js                        the npx entry point
 tools/sync-version.js             keeps the manifest version in step
 vscode/                           the VS Code extension; build.js copies the
@@ -994,11 +1099,18 @@ test/                             node --test, no dependencies
 node --test
 ```
 
-480 tests over the pricing, the window arithmetic, plan and credit detection,
+712 tests over the pricing, the window arithmetic, plan and credit detection,
 the status line, the before-prompt line, the mid-turn pulse, the after-reply tally and the session history, job forecasting,
 per-project attribution, the Codex reader and its installer, the CLI,
 packaging, and the settings save/restore.
 
+The budget modes are checked as rules rather than examples: the whole stopping
+matrix is walked in every mode (640 lines), `off` must inject nothing at any
+percentage and any pressure, the `max` line must never be longer than the
+`standard` line for the same reading, no line may tell the agent to do the work
+worse, and every mode path, alias, bound and guard is exercised before
+`settings.json` is compared byte for byte.
+
 ## Status
 
 It works and I use it daily.
@@ -1040,3 +1152,109 @@ This exists because of a real session. The Fable weekly hit 89 per cent, the
 line said the budget was nearly gone, and the work stopped - with the 5-hour
 window at 46 and every other model untouched. One command would have carried it
 on.
+
+## 1.23.0 - the ceiling, and three hosts that can be told no
+
+Everything before this release reported. This one intervenes.
+
+### The Codex meter was going blind about a third of the time
+
+Codex writes more than one meter into its rollouts, and they are not successive
+readings of one thing. A ChatGPT Plus session 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`.
+The reader took whichever was written last.
+
+On the machine this was found on, two of every six rollouts ended on a `premium`
+payload - and when one did, the plugin reported no windows at all. Measured on a
+real session: the final line 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 nothing in it.
+
+That is the whole of "Codex does not slow down when the limit is close": nothing
+ever told it the limit was close. The reader now keeps the newest reading of each
+meter and prefers the one that actually describes a window. Nothing is merged or
+synthesised - the payload returned is one Codex really wrote.
+
+### An old snapshot is a floor, not a reading
+
+There was already a warning for a reading spent past its own remainder. It could
+never fire for a snapshot taken at the start of a window, because everything
+spent since is still inside the remainder.
+
+So a session ran for most of an hour being told **7 per cent** while the account
+was at **41**: Claude Code's own cache had not moved in fifty minutes, the
+plugin's live reading was rate-limited into backoff, and the correction was
+quietly carrying the entire difference on its own. A correction is a good
+adjustment to a recent snapshot and a bad substitute for an old one, because the
+pricing error compounds with every point it has to bridge. Past fifteen minutes
+the brief now says the figure is a floor and points at `/usage`.
+
+### The ceiling
+
+    node bin/cli.js mode --cap 60
+    node bin/cli.js mode --cap off
+
+Past the ceiling, **fan-out calls are refused at the hook** - `Agent`, `Task`,
+`Workflow` and their equivalents on each host. Everything else keeps working at
+any percentage: reads, edits, tests, commands. The work still finishes, just
+sequentially, in one session, which is where the saving is. A measured fan-out
+costs between 2.6x and 5.9x the same work done in sequence, because every agent
+warms its own cache from cold and none can report back until they all stop.
+
+It is off until you set a number, it never fires without a reading behind it, and
+the refusal says what to do instead - a denial that only says "over budget" gets
+retried.
+
+**Why a refusal rather than a sentence.** On Codex the 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`, says: *"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.
+
+### The Codex subagent clamp
+
+`lowpower on --host codex` now also bounds `[agents]`. Two facts read out of the
+model catalog Codex itself caches, not out of documentation:
+
+    gpt-6-astra: default_reasoning_level    = "low"
+                 multi_agent_reasoning_effort = "xhigh"
+
+Astra's own default effort is the cheapest one, and its subagents run at the
+dearest one **no matter what the session is set to**. Lowering effort without
+bounding them leaves the most expensive path in the product untouched. The clamp
+is a marked block, removed exactly by `lowpower off`, and it refuses outright
+rather than writing a second `[agents]` table over one you wrote yourself.
+`--no-agents` declines just that half.
+
+### Antigravity
+
+    node skills/usage-limits/scripts/install-antigravity.js on
+
+Installs into `~/.gemini/config/plugins/usage-limits/`. `PreInvocation` carries
+the budget line as an injected ephemeral message; `PreToolUse` carries the
+ceiling, which Antigravity implements as a real `decision: "deny"`.
+
+One thing is said plainly rather than papered over: **Antigravity publishes no
+remaining quota anywhere readable on disk.** It refreshes quota - its own log
+says so - and keeps it in memory. A previous version filled that gap by reporting
+*Claude's* meter under a `cross-agent-claude` source, next to a hardcoded plan
+and a model name invented for a settings file that has no model key in it. All of
+that is gone. Where there is nothing to read, the report says the quota is
+unreadable.
+
+### Caveman, and why it is not here
+
+It was on the list for this release and it is not in it. JetBrains ran a
+controlled A/B of the caveman skill - 86 tasks, paired, ~240 billed trials - and
+measured output tokens down **8.5 per cent** against an advertised 65, with
+quality differences indistinguishable from noise (p=0.82). An independent
+benchmark found the literal instruction `be brief.` matched or beat it, and
+because agentic cost is input-dominated, the skill's own rules riding along every
+turn can cost more than they save. Its engine is also BSL-licensed, not open.
+
+Claude Code already ships a built-in **Concise** output style that does the same
+job in the cached system-prompt layer at no marginal cost. Use that. This plugin
+will not ship a measured 8 per cent as a 65 per cent saving.

package/bin/cli.js

@@ -26,6 +26,16 @@ const HELP = `claude-usage-limits - how much agent usage is left, and whether th
   claude-usage-limits statusline on       bars under the Claude Code prompt
   claude-usage-limits statusline off      put back what was there
 
+  claude-usage-limits mode                which budget mode the hooks are in
+  claude-usage-limits mode max            fewest tokens that still finish the job
+  claude-usage-limits mode high           full capability, re-costed every two minutes
+  claude-usage-limits mode standard       what the plugin does today
+  claude-usage-limits mode off            inject nothing; hooks return immediately
+  claude-usage-limits mode off --guard 95 off, except one line when nearly spent
+  claude-usage-limits mode auto           pick from pressure, always reported
+  claude-usage-limits mode --list         the four modes and their aliases
+  claude-usage-limits mode --ledger       measured cost per mode
+
   claude-usage-limits lowpower status     show the current effort setting
   claude-usage-limits lowpower on         lower effortLevel, remembering the old value
   claude-usage-limits lowpower on --effort medium --model sonnet
@@ -59,6 +69,12 @@ function run(argv) {
     return Promise.resolve(0);
   }
 
+  if (args[0] === 'mode') {
+    const budget = require('../skills/usage-limits/scripts/mode.js');
+    process.stdout.write(budget.main(args.slice(1)) + '\n');
+    return Promise.resolve(0);
+  }
+
   if (args[0] === 'lowpower') {
     const lowpower = require('../skills/usage-limits/scripts/lowpower.js');
     return Promise.resolve(lowpower.main(args.slice(1)));

package/commands/defer.md

@@ -0,0 +1,47 @@
+---
+description: Put this work off until a time you name, and start nothing now
+---
+
+Do not start the work in this message. Schedule it, confirm in one line, and stop.
+
+Run, from the plugin's skill directory:
+
+```
+node skills/usage-limits/scripts/defer.js "$ARGUMENTS" --work "<the work, one item per line>"
+```
+
+Where `$ARGUMENTS` is the time the user gave. Accepted forms:
+
+- `9:50pm`, `21:50`, `9pm`, `09:05` - a clock time. A time already past today
+  means tomorrow.
+- `in 90m`, `in 2h`, `in 45 minutes`
+- `reset` - when the binding usage window resets, plus a few minutes for the
+  meter to turn over
+
+Pass the work itself in `--work`: the list of things the user asked for, one per
+line, written so a session with none of this conversation's context can act on
+it. That text is saved to disk and handed to the run when it fires. If the user
+gave no list, summarise the pending work from this session instead.
+
+Then print the single line the script returns and **write nothing else**. Do not
+start any of the work, do not read files "to prepare", do not draft a plan in
+the reply. The whole point of the command is that this turn is cheap and
+nothing happens yet.
+
+Other forms:
+
+- `node skills/usage-limits/scripts/defer.js status` - what is deferred and when
+  it fires
+- `node skills/usage-limits/scripts/defer.js cancel` - call it off
+
+## What actually happens
+
+The work is saved as a continuation and a real scheduled task is registered
+(Windows Task Scheduler, or `at`/launchd elsewhere). At the named time the same
+wake script the usage relay uses starts a fresh session in the original
+directory and hands it the saved plan. If the launch fails - a machine whose
+network is not up yet is the common one - it retries rather than giving up.
+
+If the time is unreadable or ambiguous, the script refuses and says so. It never
+picks a reading: a deferral that fires at the wrong hour while nobody is awake
+is worse than one that was never set.

package/commands/usage-mode.md

@@ -0,0 +1,64 @@
+---
+description: Show or set the budget mode - how hard the plugin leans, and what it costs to say it
+---
+
+Run `node "${CLAUDE_PLUGIN_ROOT}/skills/usage-limits/scripts/mode.js" $ARGUMENTS`
+and report the answer back. Then stop; do not start other work as part of this
+command.
+
+The plugin is not free. It puts a line into your context before every prompt,
+refreshes readings after tool calls, and keeps a status line alive. A mode
+changes two things at once: what the plugin tells you to do, and what it costs
+to say it.
+
+| mode | what it is |
+| --- | --- |
+| `max` | fewest tokens that can still finish the job: one terse line, readings every ten minutes, silent when nothing a decision depends on has moved |
+| `high` | full capability, re-costed every two minutes mid-turn: the normal line plus a directive to keep checking whether the tier is bigger than the task. The mid-turn re-cost is re-measured on that cadence and said only when the answer changes |
+| `standard` | what the plugin does today, unchanged |
+| `off` | nothing is injected at all, and every hook returns before reading anything - including the end-of-reply cost line and the closing line |
+
+Aliases: `ultra`, `ultra-efficient`, `maxefficient` and friends for `max`;
+`smart`, `high-efficient` for `high`; `efficient`, `token-efficient`,
+`default`, `on` for `standard`; `none`, `quiet`, `silent`, `ignore` for `off`.
+
+**`normal` is deliberately not an alias for either `standard` or `off`.** To
+some people it means "the plugin working as usual" and to others "the plugin
+stays out of the way", and those are opposite instructions. The script answers
+it with a question. Ask which was meant; never guess.
+
+Commands:
+
+- (no arguments) - the current mode, where it came from, and what it changes.
+- `<name>` - set it. `<name> --session --session-id <id>` sets it for one
+  session only.
+- `auto` / `auto off` - pick from pressure. Under 50 per cent used it is
+  standard, 50 to 79 high, 80 or over (or tight, or gone) max. It is always
+  reported as what it resolved to (`auto -> max`) and it never picks `off`.
+- `off --guard 95` - off, except one short line when the window is nearly
+  spent. `off` on its own is silent even at 100 per cent; that is what it means
+  and it is honoured literally, so the guard exists and is offered once.
+- `--list`, `--explain <name>` - the modes, and one mode's full record.
+- `--floor sonnet/medium`, `--ceiling opus/xhigh`, `--pin` - the user's own
+  bounds on what the plugin may suggest. `--pin` means report only: the gap
+  between the baseline and what is running is stated and nothing is suggested.
+- `--baseline` - the user's own setting and the tier actually running, side by
+  side.
+- `--advice` / `--no-advice` / `--advice-on` - the recommendation channel.
+- `--decline [id]` - the user said no. That recommendation is remembered as
+  declined and is never raised again, in this session or any later one. With no
+  id it declines whatever is pending.
+- `--history`, `undo` - what changed, when, at whose instruction; and reverse
+  the last one, naming it first.
+- `--ledger` - measured turns and cost per turn, per mode, from what replies
+  actually cost.
+
+Two rules that hold in every mode:
+
+1. **The modes govern the agent plane only.** `settings.json`, `/effort`,
+   `/model` and `lowpower.js` are the user's own baseline. The plugin reads
+   them, shows them, and never writes them on its own initiative. Recommend a
+   change freely; make one when asked; never make one unasked.
+2. **A mode never lowers the quality of the work.** The savings come from
+   ceremony - speculative reads, re-reads, preamble, subagents nobody needed -
+   and never from doing the job less well.

package/hooks/hooks.json

@@ -58,7 +58,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Workflow|Agent|Task",
+        "matcher": "Workflow|Agent|Task|Bash",
         "hooks": [
           {
             "type": "command",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.19.0",
+  "version": "1.24.0",
   "description": "Puts your remaining Claude Code usage limit into Claude's context before every prompt, so it opens with what fits in the budget instead of starting work that gets cut off. Reports headroom as turns rather than percentages, prices a job before you start it, and detects your plan tier.",
   "keywords": [
     "claude",