claude-usage-limits 1.7.1 → 1.8.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.7.1",
+  "version": "1.8.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.7.1",
+  "version": "1.8.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

@@ -307,7 +307,7 @@ one line into Claude's context:
 
 ```
 [usage-limits] binding window is 5-hour 47% used, about 75 turns of headroom,
-resets in 3h 52m. Other windows: weekly 16%. This session: 229 turns, $64.16.
+resets in 3h 52m. Other windows: weekly 16%. This session: 229 turns, 14.2M tokens, $64.16.
 ```
 
 It names the window that will stop the work first and hangs the figures off
@@ -344,12 +344,67 @@ minute, so it costs about 400ms cold and 120ms warm.
 
 | Variable | Default | Effect |
 | --- | --- | --- |
-| `USAGE_LIMITS_BRIEF` | on | Set to `off` to turn the line off entirely. |
-| `USAGE_LIMITS_NEAR` | 80 | Percent used that always counts as tight. |
-| `USAGE_LIMITS_FLOOR` | 40 | Below this, pace is ignored. |
-| `USAGE_LIMITS_AHEAD` | 15 | Points ahead of pace that count as burning fast. |
+| `USAGE_LIMITS_BRIEF` | on | Set to `off` to turn the before-prompt line off entirely. |
+| `USAGE_LIMITS_NEAR` | 90 | Percent used at which the budget counts as tight. Nothing below it is discouraged. |
+| `USAGE_LIMITS_FEW_TURNS` | 10 | Turns of headroom at or below which the budget counts as tight. |
+| `USAGE_LIMITS_RUNWAY` | 10 | Minutes of runway at the current pace below which the budget counts as tight. |
 | `USAGE_LIMITS_CACHE` | 60 | Seconds the measured half stays good for. |
-| `USAGE_LIMITS_FEW_TURNS` | 20 | Turn count at or below which the budget counts as tight. |
+| `USAGE_LIMITS_FLOOR`, `USAGE_LIMITS_AHEAD` | 40, 15 | Only feed the reported pace figure; they no longer change the wording. |
+| `USAGE_LIMITS_PULSE` | on | `off` silences the mid-turn line; `always` prints it even when there is room. |
+| `USAGE_LIMITS_PULSE_SECONDS` | 120 | How often the mid-turn line can fire. |
+| `USAGE_LIMITS_TALLY` | on | Set to `off` to turn off the after-reply tally, the closing line and the session history. |
+
+## What a session cost
+
+The other half of the question. After every reply, a `Stop` hook shows you one
+line with what that reply cost and what the session has cost so far, tokens
+first because that is what people ask:
+
+```
+[usage-limits] this reply: 6 turns, 210k tokens, $0.95. This session: 9 prompts,
+48 turns, 3.1M tokens (2.9M cache read, 61k output), about $12.40, roughly 31
+points of the 5-hour window. Context is now about 130k tokens.
+```
+
+It goes to you, not into the context, so it costs the model nothing. It reads
+only the bytes of the transcript written since the previous reply, including
+any subagent transcripts under the session's own folder, so it takes a few
+milliseconds however long the session has run. When the session closes, a
+`SessionEnd` hook prints the closing line:
+
+```
+[usage-limits] session closed after 1h 42m: 9 prompts, 48 turns, 3.1M tokens, about $12.40.
+```
+
+Claude is also asked to end finished work with the total in its own words, one
+plain line, and to skip it on partial progress. The before-prompt line carries
+the session's tokens, what the last reply cost, and how large the context has
+become, with one clause of advice once it passes 150k tokens, because the
+context is re-sent on every call and past a point it is the cost of the session.
+
+The history is kept in `usage-limits-sessions.json` beside the other caches:
+
+```
+node skills/usage-limits/scripts/usage.js --sessions
+node skills/usage-limits/scripts/usage.js --session last
+```
+
+```
+  Id        When        Project                 Prompts    Turns   Tokens     Cost
+  4940f126  9m ago      C--Users-OWNER                1       16     2.8M   $11.36  open
+  380e664a  9m ago      C--Users-OWNER               10   112+35    51.0M   $93.11  open
+```
+
+`--session last` (or an id, or a unique prefix of one) shows one session in
+full: the token split, the model mix, the subagent calls and the context size.
+Installed as a plugin, `/usage-limits:session` reads the same thing back.
+Turns are main-thread calls; `+N` is what subagents made on top. Set
+`USAGE_LIMITS_TALLY=off` to turn all of this off.
+
+If you installed the plain skill rather than the plugin, add the two hooks
+beside the first one in `settings.json`: `Stop` running `scripts/stop.js` and
+`SessionEnd` running `scripts/sessionend.js`.
+
 
 ## What would this job cost
 
@@ -528,6 +583,12 @@ Good enough to plan with, not a bill. The honest caveats:
   doubling the limits. If demand-based limits ever return, the numbers here
   follow automatically, because they are calibrated from what your traffic did
   to the meter rather than from an assumption about the clock.
+- Subagent transcripts, written under the session's own folder, are read too.
+  Their calls count in the money and the tokens and are reported apart from
+  the turns, because a turn is one main-thread call.
+- The account's own list of limits is read as well as the per-window buckets,
+  so a per-model weekly such as `weekly (Fable)` shows up as a window of its
+  own, priced from that model's calls alone.
 - The turn cost behind "turns of headroom" is a median over at least five
   turns, so one compaction cannot define your pace.
 - What a point of a window costs is learned once from the best sample seen and
@@ -565,12 +626,15 @@ names, the formulas, and the rest of it.
 agents/openai.yaml                how Codex lists the plugin
 skills/usage-limits/SKILL.md      what the agent reads
 skills/usage-limits/agents/       how Codex lists the skill
-skills/usage-limits/scripts/      usage.js, brief.js, pulse.js, codex.js,
-                                  host.js, lowpower.js, install-codex-hook.js
+skills/usage-limits/scripts/      usage.js, brief.js, pulse.js, stop.js,
+                                  sessionend.js, tally.js, codex.js, host.js,
+                                  lowpower.js, install-codex-hook.js
 skills/usage-limits/references/   the longer notes
-hooks/hooks.json                  runs brief.js before each prompt, and
-                                  pulse.js during long turns
+hooks/hooks.json                  runs brief.js before each prompt, pulse.js
+                                  during long turns, stop.js after each reply
+                                  and sessionend.js when the session closes
 commands/check.md                 the /usage-limits:check command
+commands/session.md               the /usage-limits:session command
 bin/cli.js                        the npx entry point
 tools/sync-version.js             keeps the manifest version in step
 test/                             node --test, no dependencies
@@ -582,8 +646,8 @@ test/                             node --test, no dependencies
 node --test
 ```
 
-248 tests over the pricing, the window arithmetic, plan and credit detection,
-the status line, the before-prompt line, the mid-turn pulse, job forecasting,
+308 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.
 

package/bin/cli.js

@@ -11,6 +11,8 @@ const HELP = `claude-usage-limits - how much agent usage is left, and whether th
   claude-usage-limits --json              the same numbers, machine readable
   claude-usage-limits --status            one short line, for a status line
   claude-usage-limits --forecast 15       what a 15 turn job would cost
+  claude-usage-limits --sessions          what recent sessions cost
+  claude-usage-limits --session last      one session in full, or give its id
 
   claude-usage-limits --host codex        read Codex's limits instead
   claude-usage-limits --host codex --refresh   ask Codex for a live reading

package/commands/session.md

@@ -0,0 +1,13 @@
+---
+description: Report what this session has cost so far in prompts, turns, tokens and money
+---
+
+Run `node "${CLAUDE_PLUGIN_ROOT}/skills/usage-limits/scripts/usage.js" --session last`
+and read it back to me in one or two plain lines: prompts, turns (and subagent
+turns if any), tokens with the split, the cost, and how large the context is now.
+
+`last` is the most recently active session on this machine, which is normally
+this one. If more than one window is open and the project named does not look
+like this one, run `--sessions` and pick the right id.
+
+Report the numbers and stop. Do not start other work as part of this command.

package/hooks/hooks.json

@@ -1,6 +1,28 @@
 {
-  "description": "Tells Claude how much usage budget is left: once before each prompt, and again during long turns so the figure it is working from does not go stale.",
+  "description": "Tells Claude how much usage budget is left: once before each prompt, and again during long turns so the figure it is working from does not go stale. Tells you what each reply and each session cost, after the reply and when the session closes.",
   "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/skills/usage-limits/scripts/stop.js\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/skills/usage-limits/scripts/sessionend.js\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.7.1",
+  "version": "1.8.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

@@ -225,6 +225,31 @@ context grows.
 
 Reach for it whenever the answer to "will this finish" is not obvious.
 
+## Closing with what it cost
+
+The budget line opens the reply; the cost closes it. When a reply completes
+what was asked, or wraps up the session, end it with one plain line:
+
+> Spent this session: 48 turns, 3.1M tokens, about $12.40.
+
+The figures come from the `This session:` part of the budget line, so there is
+nothing to run. They are exact as of the start of this turn, and the Stop hook
+prints the up-to-date figure to the user the moment you finish, so do not go
+and re-measure for the closing line.
+
+Three rules keep it useful rather than noisy:
+
+- **Finished work only.** A progress note mid-task, a clarifying question, or
+  a reply that ends with "shall I go on" is not the moment. The line marks a
+  goal reached or a session wrapped up.
+- **One line, at the end.** It is a footer, not a section, and it never
+  replaces the recap of what was actually done.
+- **Plain text.** No symbols, no formatting tricks. The number is the point.
+
+The user can also ask any time with `/usage-limits:session`, or run
+`node scripts/usage.js --session last` for the full breakdown and
+`--sessions` for the history of recent sessions on this machine.
+
 
 ## 4. Low power
 
@@ -359,9 +384,12 @@ a turn, which is the thing it is trying to save.
 
 | Path | What it is |
 | --- | --- |
-| `scripts/usage.js` | The report. `--json` for raw fields, `--status` for a one-line readout that skips the transcript scan, `--forecast N` for what an N turn job would cost, `--host codex` to read Codex's limits, `--refresh` to ask Codex for a live figure. |
+| `scripts/usage.js` | The report. `--json` for raw fields, `--status` for a one-line readout that skips the transcript scan, `--forecast N` for what an N turn job would cost, `--sessions` for what recent sessions cost, `--session last` (or an id) for one session in full, `--host codex` to read Codex's limits, `--refresh` to ask Codex for a live figure. |
 | `scripts/brief.js` | What the hook runs before each prompt. Not meant to be called by hand. |
 | `scripts/pulse.js` | What runs after tool calls, to re-check the budget during a long turn. Not meant to be called by hand. |
+| `scripts/stop.js` | What runs after each reply: shows the user what the reply and the session have cost. Not meant to be called by hand. |
+| `scripts/sessionend.js` | What runs when the session closes: the closing line, and the session marked closed in the history. Not meant to be called by hand. |
+| `scripts/tally.js` | The running per-session total behind those two, kept in `usage-limits-sessions.json` and read incrementally. |
 | `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. |

package/skills/usage-limits/references/how-it-works.md

@@ -28,6 +28,14 @@ the report includes them when they are present.
 If the key is missing, run `/usage` once inside Claude Code. That is what
 populates it.
 
+The same object carries a `limits` array: one entry per limit the account
+enforces, each with `kind` (`session`, `weekly_all`, `weekly_scoped`),
+`percent`, `severity`, `resets_at`, `is_active`, and for the scoped weeklies
+which model they cover. The report reads it too. A scoped weekly becomes a
+window of its own, labelled `weekly (Fable)` and priced from that model's
+calls alone; `is_active` breaks ties in the binding choice; and a bucket that
+quotes `limit_dollars` is priced from that directly instead of being calibrated.
+
 The plan name comes from `oauthAccount.organizationType` in the same file.
 Current effort and model come from `settings.json` in the config directory.
 
@@ -64,6 +72,13 @@ Assistant turns carry a usage record:
 }
 ```
 
+Subagents write their own transcripts under
+`<project>/<session id>/subagents/agent-*.jsonl`, with `isSidechain: true` and
+the parent's `sessionId`. They are read too: their calls count in the money and
+the tokens, and are kept apart from the turns, because a turn is one main-thread
+call. Lines from a model called `<synthetic>` are interrupts and client-side
+errors, not calls, and are skipped.
+
 Files whose modification time predates the window are skipped. Turns are keyed
 by `message.id` plus `requestId` and counted once, because resuming or forking
 a session copies earlier turns into a new file.

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

@@ -47,7 +47,7 @@ Per million tokens, input and output:
 | Model | Input | Output |
 | --- | --- | --- |
 | Opus 5 | $5 | $25 |
-| Sonnet 5 | $3 | $15 |
+| Sonnet 5 | $2 | $10 |
 | Haiku 4.5 | $1 | $5 |
 
 Renaming symbols, writing boilerplate tests, formatting, mechanical

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

@@ -15,6 +15,7 @@ const path = require('path');
 
 const usage = require('./usage.js');
 const host = require('./host.js');
+const tally = require('./tally.js');
 
 const SECOND = 1000;
 const DAY = 24 * 60 * 60 * 1000;
@@ -133,6 +134,20 @@ function liveSessions(all, now, windowMs, exceptId) {
   return count;
 }
 
+// How many sessions are sharing the budget, and how much of it is this one's.
+// One place for both hooks. The pulse once counted only sessions that had
+// spent while the brief also counted those that had merely prompted, and the
+// two lines disagreed about how many sessions there were minutes apart. The
+// spend-derived count is the accurate one when it has caught up; the
+// open-session count is the one that is right immediately. Take whichever is
+// higher, because under-counting is what makes the headroom read as more
+// yours than it is.
+function activeShare(sessions, slots, now, sessionId) {
+  const spent = sessions || [];
+  const active = Math.max(spent.length, liveSessions(slots, now, LIVE_WINDOW_MS, sessionId) + 1);
+  return { active, share: active > 1 ? usage.shareOf(spent, sessionId, active) : 1 };
+}
+
 // Keep the newest few so a machine with many sessions does not grow the file
 // without bound.
 function mergeCache(all, sessionId, entry, keep) {
@@ -252,6 +267,7 @@ const CACHED_BINDING_FIELDS = [
   'adjusted',
   'pointsSinceSnapshot',
   'correctionUnreliable',
+  'pointsBeyondSnapshot',
   'resetsAt',
   'verdict',
   'windowStart',
@@ -332,7 +348,10 @@ function briefText(parts) {
   // the binding window is named and its figures are attached to it.
   const bound = [];
   const described = describeWindow(parts.binding);
-  if (described) bound.push(described + (parts.binding.stale ? '' : ' used'));
+  // When spending since the snapshot has outrun what the snapshot said was
+  // left, the percentage is the last real reading, not the current one, and
+  // the headline has to say so or every later prompt repeats a stale number.
+  if (described) bound.push(described + (parts.binding.stale ? '' : (parts.correctionUnreliable ? ' used at the last real reading' : ' used')));
   if (Number.isFinite(parts.turnsLeft)) {
     // Another session spending the same budget means fewer of those turns are
     // yours, so say both numbers rather than the flattering one.
@@ -387,6 +406,16 @@ function briefText(parts) {
         parts.snapshotAge + ' old, so run /usage before trusting the rest.'
     );
   }
+  if (parts.correctionUnreliable) {
+    // A reading three hours old that has been spent past its own remainder is
+    // not 82%; it is unknown, with 82% as the floor. Say exactly that.
+    sentences.push(
+      'That percentage is a floor, not a current reading: the last real snapshot is ' +
+        parts.snapshotAge + ' old and about ' + parts.pointsBeyondSnapshot +
+        ' points have been spent since, more than it said was left. Either the window is ' +
+        'already exhausted or the snapshot is wrong; /usage refreshes it.'
+    );
+  }
   // Work having actually been stopped is the most useful thing that can be said
   // about a budget, and the percentages stop showing it the moment the window
   // turns over. Saying it plainly is what stops the next session opening with
@@ -412,9 +441,45 @@ function briefText(parts) {
   if (parts.session) {
     sentences.push(
       'This session: ' + parts.session.turns + ' turns, ' +
+        (Number.isFinite(parts.session.tokens) ? usage.formatTokens(parts.session.tokens) + ' tokens, ' : '') +
         usage.formatUSD(parts.session.cost) + '.'
     );
   }
+  // From the tally the Stop hook keeps, so these are exact as of the last reply.
+  if (parts.lastReply && Number.isFinite(parts.lastReply.cost)) {
+    sentences.push('Last reply ' + usage.formatMoney(parts.lastReply.cost) + '.');
+  }
+  if (Number.isFinite(parts.context) && parts.context > 0) {
+    // The context is re-sent on every call, so past a point it is the cost of
+    // the session. One clause, once it is large; no advice while it is not.
+    sentences.push(
+      'Context about ' + usage.formatTokens(parts.context) + ' tokens' +
+        (parts.context >= LARGE_CONTEXT_TOKENS
+          ? '; each turn re-reads that, so a fresh session or /compact at the next clean boundary cuts per-turn cost.'
+          : '.')
+    );
+  }
+  // Said once, on a session's first prompt, because the previous session's
+  // total is the one figure nothing else ever shows.
+  if (parts.lastSession && parts.lastSession.turns) {
+    const last = parts.lastSession;
+    sentences.push(
+      'Last session: ' + last.turns + ' turns, ' + usage.formatTokens(last.tokens) + ' tokens, ' +
+        roundMoney(last.cost) +
+        (last.project || last.endedAgo
+          ? ' (' +
+            [
+              last.project,
+              last.endedAgo
+                ? (last.open ? 'still open, last active ' : 'ended ') + last.endedAgo + ' ago'
+                : null,
+            ]
+              .filter(Boolean)
+              .join(', ') +
+            ')'
+          : '') + '.'
+    );
+  }
 
   // Three states, and only the last one stops anything.
   //
@@ -451,7 +516,72 @@ function briefText(parts) {
     'and reset time above belong to the binding window alone; do not read them ' +
     'against another window percentage.';
 
-  return sentences.join(' ') + '\n' + instruction + care;
+  // Finished work closes with what it cost. Not every reply: a progress note
+  // mid-task is not the moment, and once the budget is gone nothing further
+  // runs, so there is no reply to close.
+  const closing =
+    parts.pressure === 'gone'
+      ? ''
+      : ' When this reply completes what was asked, or wraps up the session, end it ' +
+        'with one plain line giving the session total above (turns, tokens and cost). ' +
+        'Skip it on partial progress; the hook prints the exact figure after you stop.';
+
+  return sentences.join(' ') + '\n' + instruction + closing + care;
+}
+
+// Past this the context is the cost of the session, not a detail of it.
+const LARGE_CONTEXT_TOKENS = 150000;
+
+// A previous session's total reads better in whole dollars once it is large.
+function roundMoney(value) {
+  if (!Number.isFinite(value)) return '-';
+  return value >= 10 ? '$' + Math.round(value) : usage.formatMoney(value);
+}
+
+function isTallyEntry(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+// What the Stop hook's tally can add to the line: this session's last reply
+// and context when it is a session the tally has seen, or the previous
+// session's total when it has not, which is how a first prompt gets told what
+// the last session cost.
+function tallyContext(all, sessionId, now) {
+  const none = { lastReply: null, context: null, lastSession: null };
+  if (!all || typeof all !== 'object') return none;
+
+  const mine = sessionId && isTallyEntry(all[sessionId]) ? all[sessionId] : null;
+  if (mine) {
+    return {
+      lastReply: mine.lastReply || null,
+      context: Number.isFinite(mine.context) ? mine.context : null,
+      lastSession: null,
+    };
+  }
+
+  const others = Object.keys(all)
+    .filter((key) => key !== tally.IDS_KEY && isTallyEntry(all[key]))
+    .map((key) => all[key])
+    .sort((a, b) => (b.lastAt || 0) - (a.lastAt || 0));
+  const last = others[0];
+  if (!last || !last.turns) return none;
+
+  const open = !Number.isFinite(last.endedAt);
+  const ended = open ? last.lastAt : last.endedAt;
+  return {
+    lastReply: null,
+    context: null,
+    lastSession: {
+      turns: last.turns,
+      tokens: tally.totalTokens(last.tokens),
+      cost: last.cost,
+      project: last.project || null,
+      // Another window may still be in it, so say when it was last active
+      // rather than claiming it ended.
+      open,
+      endedAgo: Number.isFinite(ended) ? usage.formatDuration(now - ended) : null,
+    },
+  };
 }
 
 async function run(now, hookInput) {
@@ -498,14 +628,7 @@ async function run(now, hookInput) {
   }
 
   const binding = view.binding;
-  const sessions = view.sessions || [];
-  // The spend-derived count is the accurate one when it has caught up; the
-  // open-session count is the one that is right immediately. Take whichever is
-  // higher rather than the one that happens to be handy, because under-counting
-  // is what makes the headroom read as more yours than it is.
-  const active = Math.max(sessions.length, liveSessions(all, now, LIVE_WINDOW_MS, sessionId) + 1);
-  const share =
-    sessions.length > 1 ? usage.shareOf(sessions, sessionId) : active > 1 ? 1 / active : 1;
+  const { active, share } = activeShare(view.sessions, all, now, sessionId);
   const yourTurnsLeft = Number.isFinite(view.turnsLeft)
     ? Math.max(1, Math.round(view.turnsLeft * share))
     : null;
@@ -514,7 +637,12 @@ async function run(now, hookInput) {
   const shortRunway =
     binding && Number.isFinite(binding.headroomMs) &&
     binding.headroomMs <= RUNWAY_MENTION_MS;
+  // Outside the cache on purpose: the tally moves after every reply.
+  const found = tallyContext(tally.readState(), sessionId, now);
   return briefText({
+    lastReply: found.lastReply,
+    context: found.context,
+    lastSession: found.lastSession,
     sessions: active,
     yourTurnsLeft,
     runsOutIn: shortRunway ? usage.formatDuration(binding.headroomMs) : null,
@@ -537,6 +665,8 @@ async function run(now, hookInput) {
     planChanged: Boolean(view.planChanged),
     critical: view.critical || [],
     pointsSinceSnapshot: (binding && binding.pointsSinceSnapshot) || 0,
+    correctionUnreliable: Boolean(binding && binding.correctionUnreliable),
+    pointsBeyondSnapshot: (binding && binding.pointsBeyondSnapshot) || 0,
     snapshotAge: view.snapshotAge,
     // The turn count that matters for this session is its share of a shared
     // budget, not the whole window's. Escalating on the whole window meant a
@@ -574,11 +704,15 @@ module.exports = {
   describeWindow,
   summariseOthers,
   briefText,
+  tallyContext,
+  LARGE_CONTEXT_TOKENS,
   settings,
   keepSlots,
   pickCached,
   mergeCache,
   liveSessions,
+  activeShare,
+  readCache,
   cacheableBinding,
   pressureInputs,
   CACHED_BINDING_FIELDS,

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

@@ -129,10 +129,12 @@ async function run(now, hookInput) {
   const binding = data.binding;
   if (!binding) return '';
 
-  const sessions = data.sessions || [];
-  const share = usage.shareOf(sessions, sessionId);
+  // The same count and the same split as the brief, so the two lines never
+  // disagree about how many sessions there are or how much of the budget is
+  // this one's.
+  const { active, share } = brief.activeShare(data.sessions, brief.readCache(), now, sessionId);
   const turnsLeft = Number.isFinite(binding.turnsLeft)
-    ? sessions.length > 1
+    ? active > 1
       ? Math.max(1, Math.round(binding.turnsLeft * share))
       : binding.turnsLeft
     : null;
@@ -156,7 +158,7 @@ async function run(now, hookInput) {
       Number.isFinite(binding.headroomMs) && binding.headroomMs <= runwayMs
         ? usage.formatDuration(binding.headroomMs)
         : null,
-    sessions: sessions.length,
+    sessions: active,
     pressure,
   });
 }

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

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+'use strict';
+
+// The closing line.
+//
+// Runs as the SessionEnd hook. Brings the session's total up to date one last
+// time, marks it closed, and prints one line saying how long it ran and what
+// it cost. SessionEnd shows plain stdout to the user and gives hooks a short
+// shared budget, which the incremental read fits inside comfortably.
+
+const usage = require('./usage.js');
+const host = require('./host.js');
+const tally = require('./tally.js');
+
+async function run(now, hookInput) {
+  if (String(process.env.USAGE_LIMITS_TALLY || '').toLowerCase() === 'off') return '';
+  usage.setHost(host.detect(process.argv.slice(2), process.env));
+
+  const sessionId = hookInput && hookInput.session_id ? hookInput.session_id : null;
+  const transcript = hookInput && hookInput.transcript_path ? hookInput.transcript_path : null;
+  if (!sessionId || !transcript) return '';
+
+  const all = tally.readState();
+  const { session } = tally.update(all, sessionId, transcript, now, { cwd: hookInput.cwd || null });
+  session.endedAt = now;
+  session.reason = typeof hookInput.reason === 'string' ? hookInput.reason : null;
+  tally.writeState(tally.trim(all));
+
+  return tally.formatClosed(session, now);
+}
+
+if (require.main === module) {
+  tally
+    .readHookInput()
+    .then((input) => run(Date.now(), input))
+    .then(
+      (text) => {
+        if (text) process.stdout.write(text + '\n');
+        process.exit(0);
+      },
+      () => {
+        process.exit(0);
+      }
+    );
+}
+
+module.exports = { run };

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

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+'use strict';
+
+// The end-of-reply tally.
+//
+// Runs as the Stop hook, after Claude has finished a reply, and puts one line
+// in front of the user saying what that reply cost and what the session has
+// cost so far. It costs the model nothing: the line goes to the person, not
+// into the context, and the numbers come from bytes of the transcript that
+// have already been written.
+//
+// It must never exit with code 2. On this event that would stop Claude from
+// stopping.
+
+const usage = require('./usage.js');
+const host = require('./host.js');
+const tally = require('./tally.js');
+
+async function run(now, hookInput) {
+  if (String(process.env.USAGE_LIMITS_TALLY || '').toLowerCase() === 'off') return '';
+  usage.setHost(host.detect(process.argv.slice(2), process.env));
+
+  const sessionId = hookInput && hookInput.session_id ? hookInput.session_id : null;
+  const transcript = hookInput && hookInput.transcript_path ? hookInput.transcript_path : null;
+  if (!sessionId || !transcript) return '';
+
+  const all = tally.readState();
+  const { session, delta, created } = tally.update(all, sessionId, transcript, now, {
+    cwd: hookInput.cwd || null,
+  });
+  tally.writeState(tally.trim(all));
+
+  // The first time a session is seen, everything read is history rather than
+  // the reply that just finished, so only the total is shown.
+  return JSON.stringify({
+    systemMessage: tally.formatTally(session, created ? null : delta, tally.pricing(now)),
+  });
+}
+
+if (require.main === module) {
+  tally
+    .readHookInput()
+    .then((input) => run(Date.now(), input))
+    .then(
+      (text) => {
+        if (text) process.stdout.write(text + '\n');
+        process.exit(0);
+      },
+      () => {
+        process.exit(0);
+      }
+    );
+}
+
+module.exports = { run };