claude-usage-limits 1.18.0 → 1.23.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.18.0",
+  "version": "1.23.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.18.0",
+  "version": "1.23.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/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.18.0",
+  "version": "1.23.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",

package/skills/usage-limits/SKILL.md

@@ -275,6 +275,137 @@ The user can also ask any time with `/usage-limits:session`, or run
 `--sessions` for the history of recent sessions on this machine.
 
 
+## Budget modes
+
+How hard this plugin leans, and what it costs to say it. Four modes, set by the
+user and read by every hook:
+
+```
+node scripts/mode.js                 # which one, where it came from, what it changes
+node scripts/mode.js max             # set it
+node scripts/mode.js --list          # all four, and the aliases
+node scripts/mode.js --explain high  # one mode's full record
+```
+
+| mode | one line |
+| --- | --- |
+| `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-measured every two minutes mid-turn, and said only when the answer changes |
+| `standard` | what the plugin does today, unchanged. The default |
+| `off` | nothing injected at all; every hook returns before reading anything, including the end-of-reply tally |
+
+Aliases: `ultra`, `ultra-efficient`, `maxtoken`, `maxefficient` map to `max`;
+`smart`, `high-efficient` to `high`; `efficient`, `token-efficient`, `default`,
+`on` to `standard`; `none`, `quiet`, `silent`, `ignore` to `off`.
+
+**`normal` is not an alias for either.** To some people it means "the plugin
+working as usual" (`standard`) and to others "the plugin stays out of the way"
+(`off`) - opposite instructions, so a silent guess is wrong half the time. If
+the user says "normal", ask which they meant and say what each one does. The
+script answers the same way.
+
+`auto` picks from how full the binding window is - standard under 50 per cent
+used, high from 50 to 79, max at 80 or above - and always reports itself as
+what it resolved to (`auto -> max`). It reads the snapshot already on disk
+rather than scanning, because the mode has to be settled before anything
+expensive runs, and with no readable window it stays on `standard` rather than
+guessing. It never picks `off`: turning the plugin off is a decision a person
+makes.
+
+`off` means off, including at 100 per cent. That is deliberate. If the user
+wants one line at the wall and nothing else, `node scripts/mode.js off --guard 95`
+is it.
+
+Two rules hold in every mode, and they are not negotiable:
+
+- **A mode never lowers 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.
+- **The modes govern the agent plane only**, and never write `settings.json`.
+
+### Two planes, and the conversation between them
+
+The **user plane** is `settings.json` (`model`, `effortLevel`), the `/effort`
+and `/model` pickers, and `lowpower.js`. It is the user saying what they want
+for themselves. It is theirs.
+
+The **agent plane** is the tier actually running this turn, and the tier of
+everything this turn spawns. That is what costs money.
+
+What is actually yours to move, stated exactly, because a claim beyond this
+would be a lie the user cannot check:
+
+- **The model on an `Agent` call is yours.** `model: "sonnet" | "opus" |
+  "haiku" | "fable"` on any Agent call, and it overrides both the agent
+  definition and the configured default. It is ignored for `subagent_type:
+  "fork"`, which always inherits the parent model.
+- **Model and effort inside a `Workflow` script are yours**, per `agent()`
+  call: `opts.model` and `opts.effort` (`low` | `medium` | `high` | `xhigh` |
+  `max`). The host's own advice is to omit `opts.model` unless you are
+  confident, and to use `opts.effort: 'low'` for mechanical stages - so lean on
+  effort rather than model when sizing what you spawn.
+- **Your own model and effort are NOT yours to change mid-session.** Nothing a
+  hook can emit changes them: there is no such field anywhere in the hook
+  output contract, and `PreModelSwitch` can only veto a switch someone else
+  started. `/model` and `/effort` are typed by a person and
+  `CLAUDE_CODE_EFFORT_LEVEL` is read at launch. So say the exact command in one
+  line and let the user run it. Never imply you changed it yourself.
+- `xhigh` and `max` are refused outright when thinking is disabled, so never
+  point at either without that being true.
+
+The two planes talk to each other, in both directions, through the
+conversation. The whole rule in one line:
+
+**You may RECOMMEND a user-plane change. You may MAKE one when asked. You may
+never make one unasked.**
+
+Recommending, when you do it:
+
+- **Evidence or silence.** Cite a measurement - what this account has actually
+  measured, from `usage.js --recommend`, the fit line in the budget briefing,
+  or `scripts/drift.js`. "Recommended" with no number is nagging.
+- **At most one per session**, and none at all in `off`. The plugin enforces
+  this; do not route around it.
+- **A declined recommendation is not raised again.** When the user says no,
+  record it - `node scripts/mode.js --decline` - and it is never volunteered
+  again, in this session or any later one. `--advice` shows what is pending.
+- **Name the exact command, the plane it changes, and when it takes effect.**
+
+When the user asks you to change something, or says **"change it back"**: read
+`node scripts/mode.js --history` first, say out loud what you are reverting and
+to what, then do it. Never infer a target that is not in the log. `node
+scripts/mode.js undo` reverses the last change the plugin owns and names it
+first; for a change to the user's own settings it names the command and leaves
+the file alone, because that plane is not the plugin's to write.
+
+The surprise to head off, every time: **a user-plane change does not move the
+session already running.** If the user says "turn low power on" and you do it,
+nothing about this session changes - `lowpower.js` says so itself ("Applies to
+new sessions. For the session you are in, run /effort X"). Relay that in your
+own words whenever you make one, and the same in reverse: putting the baseline
+back does not restore this session's tier either.
+
+### Bounds the user can set
+
+```
+node scripts/mode.js --floor sonnet/medium   # never point below this, even in max
+node scripts/mode.js --ceiling opus/xhigh    # nor above it, even on the hard part
+node scripts/mode.js --pin                   # do not self-switch at all: report only
+```
+
+Under `--pin` the plugin reports the gap between the baseline and what is
+running and suggests nothing. Respect it in your own words too: report, do not
+switch.
+
+### Stepping back up
+
+The efficient modes are two-directional, and that matters more than it sounds.
+Having dropped to a cheap tier for a mechanical stretch, say so when the work
+turns hard again and point back at the baseline. A one-way ratchet down is how
+a long session quietly degrades, which is the thing the quality rule forbids.
+
+
 ## 4. Low power
 
 Two halves, and the second one is the half that actually binds.
@@ -404,41 +535,48 @@ waste at 10 per cent used exactly as much as at 80; the only difference is that
 at 80 somebody notices.
 
 It cannot judge how hard your work is. You can. So when you see it, look at what
-is actually in front of you and take one of three levers yourself, saying which
-in one line:
+is actually in front of you and reach for one of three levers, saying which in
+one line. Two of them are yours to pull; the first is not.
 
 1. **Drop the effort** for that stretch - a rename, a docs pass, running tests,
-   applying a fix you have already worked out.
-2. **Hand the stretch to a cheaper model**, and keep the dear one for the
-   decisions that need it.
+   applying a fix you have already worked out. `/effort` and `settings.json` are
+   the user's own baseline, so this one you **offer**: name the command, say why
+   the stretch does not need the tier, and leave the pulling of it to them.
+2. **Hand the stretch to a cheaper model.** Your own model is the user's setting
+   too, so say that in one line rather than switching - but the model on
+   anything you SPAWN is entirely yours: an Agent call takes a model, and a
+   Workflow's `agent()` takes a model and an effort. Size those to the stage.
 3. **Do less of it at this setting** - a fan-out multiplies the setting across
-   every agent, so six agents at ultra is six ultra turns, not one.
+   every agent, so six agents at ultra is six ultra turns, not one. Yours.
 
 Put it back when the work gets hard again. The question is asked once per
 setting per session, not every prompt, and never at all unless there is a real
 measured comparison behind it - a ratio from a price list would have you drop
 effort on a hunch and call it evidence.
 
-**This is a lever you may pull yourself, not only an emergency exit.** Use it
-whenever the current setting is dearer than the work in front of you needs,
-without being asked and long before any window is tight: a mechanical rename,
-a docs pass or a mass find-and-replace does not need the model and effort a
-hard design decision does. Drop it for that stretch, say in one line that you
-did and why, and put it back when the work gets hard again. An agent that only
-ever reads this as a wall notice runs every trivial turn at the top setting and
-then wonders where the window went.
+**This is worth raising early, not only at the wall.** Say it whenever the
+current setting is dearer than the work in front of you needs, long before any
+window is tight: a mechanical rename, a docs pass or a mass find-and-replace
+does not need the model and effort a hard design decision does. An agent that
+only ever reads this as a wall notice runs every trivial turn at the top setting
+and then wonders where the window went.
+
+**And "offer it" is one line, not a stop.** Naming the lever and carrying on is
+the whole action. Waiting for an answer before doing the work would cost more
+than the tier ever did.
 
 The budget line does this arithmetic for you. Once the binding window is half
 gone it says which lever applies, and at the wall it says outright that you are
 not out of budget and must not stop as though you were. When it does, the
-sequence is: switch, say in one line that you switched and why, carry on with
-the whole request at full quality.
+sequence is: say in one line which command frees it and why, and carry on with
+the whole request at full quality. A per-model weekly is not the account's
+budget, and treating it as one is the error.
 
 This is written down because it was got wrong. A session ended with the Fable
 weekly at 89 per cent and the line saying the budget was nearly gone - while the
 5-hour sat at 46 and every other model on the account was untouched. One command
-would have carried it on. Stopping there was not caution; it was quitting with a
-reason that sounded like one.
+would have carried it on, and naming that command costs a line. Stopping there
+was not caution; it was quitting with a reason that sounded like one.
 
 Only when the switch is genuinely unavailable - no other window has room, or the
 user has ruled it out - does the checkpoint below apply.
@@ -540,6 +678,14 @@ of it.
 
 ## Running under Codex
 
+One difference that matters for the budget modes. Every entry in Codex's
+`hooks.json` carries an `additionalContextLimit` - a per-hook cap on how much
+context a hook may inject, which Claude Code has no equivalent of. A long
+briefing can therefore be truncated there without a word. If a line looks cut
+off under Codex, that is why: `node scripts/mode.js max` keeps it to one line,
+and `high` is the verbose one.
+
+
 Everything above works the same. The numbers come from a different place and
 one thing about how they arrive is different, and both are worth knowing.
 
@@ -654,6 +800,7 @@ stop.
 | `scripts/host.js` | Works out which agent this is running inside, so one host's percentages are never reported against the other's turns. |
 | `scripts/codex.js` | The Codex reader: the meter and the pace out of `~/.codex/sessions`, plus the live `--refresh` call. |
 | `scripts/install-codex-hook.js` | `status`, `on`, `off`. Installs the Codex-side instruction, which Claude Code does not need. |
+| `scripts/mode.js` | The budget mode: no arguments to report it, `max`/`high`/`standard`/`off` to set it, `auto`, `off --guard 95`, `--list`, `--explain <name>`, `--floor`/`--ceiling`/`--pin`, `--baseline`, `--advice`/`--no-advice`, `--history`, `undo`, `--ledger`. Reads settings.json and never writes it. |
 | `scripts/lowpower.js` | `status`, `on`, `off`. Restores what it replaced. Claude Code only. |
 | `scripts/recommend.js` | The chooser behind `usage.js --recommend`: posture, then the effort and model commands for each lever. Not meant to be called by hand. |
 | `references/tactics.md` | Every lever that lowers cost, and why it works. |
@@ -661,6 +808,7 @@ stop.
 | `scripts/statusline.js` | `status`, `on`, `off`. Puts the bars under the prompt and restores what was there. |
 | `scripts/feed.js` | The status line command Claude Code runs. Not meant to be called by hand. |
 | `scripts/live.js` | The usage reading itself, taken the way Claude Code takes it for `/usage`, kept in `usage-limits-live.json` where `collect()` prefers it when newer than the cache. |
+| `scripts/drift.js` | How wrong the reading was: each correction written down against the one it replaced. Run it with no arguments for the median and worst gap measured so far, `--json` for the fields. Answer "how far behind does this plugin actually run" from here rather than from memory. |
 | `scripts/view.js`, `scripts/bars.js`, `scripts/activity.js` | The display model, the drawing in Claude's colours, and the working/idle marks the hooks leave for the panel. Not meant to be called by hand. |
 | `scripts/relay.js` | The relay: `status`, `on`/`off`, `at N`, `grace N`, `mode notify\|resume`, `permission MODE`, `thinking off\|resume\|always`, `note "<text>"`, `cancel`, `log`. |
 | `scripts/wake.js` | What the scheduler runs after the reset: re-checks the meter, then notifies or resumes. Never called by hand. |