@nightlab-agent/subagent-spend 0.7.2 → 0.8.0

package/.claude-plugin/marketplace.json

@@ -7,8 +7,8 @@
     {
       "name": "subagent-spend",
       "source": "./",
-      "description": "Per-subagent tokens, rate-limit windows, context fill, cost, steps, tool calls and tool errors of a Claude Code session, in a notice under the prompt, local files and panes (the usage pane not yet seen on a screen).",
-      "version": "0.7.2",
+      "description": "A spend cap for interactive sessions, and per-subagent tokens, rate-limit windows, context fill, cost, steps, tool calls and tool errors of a Claude Code session, in a notice under the prompt, local files and panes (the usage pane not yet seen on a screen).",
+      "version": "0.8.0",
       "category": "productivity"
     }
   ],

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "subagent-spend",
-  "version": "0.7.2",
-  "description": "Per-subagent tokens, rate-limit windows, context fill, cost, steps, tool calls and tool errors of a Claude Code session, in a notice under the prompt, local files and panes (the usage pane not yet seen on a screen).",
+  "version": "0.8.0",
+  "description": "A spend cap for interactive sessions, and per-subagent tokens, rate-limit windows, context fill, cost, steps, tool calls and tool errors of a Claude Code session, in a notice under the prompt, local files and panes (the usage pane not yet seen on a screen).",
   "author": {
     "name": "Nightlab"
   },
@@ -20,7 +20,8 @@
     "usage",
     "headless",
     "max-turns",
-    "budget"
+    "budget",
+    "spend-cap"
   ],
   "userConfig": {
     "dir": {
@@ -52,6 +53,12 @@
       "title": "Turn counts folder",
       "description": "Folder for the day's counts file. A relative path is under the project the session runs in; give an absolute path to keep every project in one place.",
       "default": ".turn-tally"
+    },
+    "capUsd": {
+      "type": "number",
+      "title": "Spend cap (dollars)",
+      "description": "Stop sending requests once the session reaches this cost, by Claude Code's own estimate: at 80 percent a notice, at the cap the next model step is answered by the mod with no request made, until /spend-cap raises or lifts it. 0 is off.",
+      "default": 0
     }
   }
 }

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 The form is Keep a Changelog; versions follow SemVer.
 
+## 0.8.0 - 2026-11-01
+
+### Added
+- A spend cap for interactive sessions (`capUsd`, off by default). Claude Code's own `--max-budget-usd` works only
+  in print mode (`claude -p`). At 80 percent of the cap a notice says so, once. At the cap, the next model step
+  (the main conversation's or a subagent's) is answered by the mod and no request goes out, until `/spend-cap`
+  raises the cap (`/spend-cap 5`) or lifts it (`/spend-cap off`). A step already running finishes, so its cost can
+  pass the cap. The figure is Claude Code's own client-side estimate, which can differ from your bill. Eight tests;
+  with the hold taken out, five of them fail. The cost is read before every step, not only after a turn, so a
+  tool loop or a subagent inside one turn is held too (two more tests, each beside a comparison case).
+- With the cap on, the status line shows the cost the cap holds on, so it moves inside a turn too. When two
+  subagents step at once and a cost reading comes back late, the highest reading in the session is kept: a late,
+  lower one cannot set the count back under the cap, and a read still out when a session ends does not land in
+  the next one.
+
+## 0.7.3 - 2026-10-31
+
+### Fixed
+- The pane read "1 subagents" and "1 turns" when there was one; it now reads "1 subagent" and "1 turn". Three tests
+  had the old wording written into them and now expect the singular; one new test checks one and two of each.
+
+### Changed
+- The README says the pane was seen updating step by step on a screen (a preview recording on 2026-10-31).
+
 ## 0.7.2 - 2026-10-30
 
 ### Added

package/README.md

@@ -5,7 +5,8 @@ Claude Code meters: subagent tokens, usage limits and turn counts.
 This mod (a plugin that adds behaviour to Claude Code) shows three things in
 one line under the prompt and writes each to a small local file a script can
 read: the tokens each subagent used, summed per subagent; the usage limits;
-and a running count of steps, tool calls and tool errors. It also has side
+and a running count of steps, tool calls and tool errors. If you set one, a
+spend cap stops sending requests once an interactive session's cost reaches it. It also has side
 panes: the subagent pane is seen below; the Usage pane is not yet seen on a
 real screen. Nothing leaves your machine.
 
@@ -21,7 +22,7 @@ was cut with "…".
 ## Install
 
 One line at the Claude Code prompt (Claude Code 2.1.275 or later; the tests
-run on 2.1.310 and the previews on 2.1.312):
+and previews run on 2.1.312):
 
 ```
 /plugin install subagent-spend --marketplace nightlab-agent/subagent-spend
@@ -116,12 +117,34 @@ preview showed, after one turn with one subagent:
 ⚠ subagent-spend: subagents 1 | tok 18k (out 1068) | 5h 49% | 7d 26% | ctx 4% | $0.17 | steps 3 | tools 1 | errors …
 ```
 
+## Spend cap
+
+Claude Code's own cap, `--max-budget-usd`, works only in print mode
+(`claude -p`, per its [CLI reference](https://code.claude.com/docs/en/cli-reference)).
+For an interactive session, set `capUsd` in `/config` to a number of dollars.
+At 80 percent of it a notice says so, once. At the cap, the next model step,
+the main conversation's or a subagent's, is answered by the mod and no request
+goes out, until you raise it (`/spend-cap 5`) or lift it (`/spend-cap off`)
+for the session. `/spend-cap` alone shows the cap and the cost so far.
+
+![Claude Code with a $0.10 cap: asked to read every file and describe each, Claude reads four files; the next step is answered by the mod's line saying the session cost $0.11 of the $0.10 cap and no request was sent](https://raw.githubusercontent.com/nightlab-agent/subagent-spend/bcb368556c20a40c62ce952574e5a1bec5210923/docs/spend-cap-midturn.png)
+
+Seen in a Claude Code 2.1.312 terminal on 2026-10-31 with the cap set to
+$0.10: one prompt asked Claude to read every file and describe each; after
+it had read four files the cost was $0.11, and the next step, inside the
+same turn, got the line above instead of a request. In an earlier run with
+a $0.05 cap, the first prompt cost $0.06 and the second got the same line in
+0 seconds, with no tool call. The figure is Claude Code's own client-side
+estimate, which can differ from your bill. A step already running finishes,
+so the cost can pass the cap: leave headroom. The 80 percent notice is
+tested, not yet seen on a screen.
+
 ## What each part shows
 
 **Subagent spend.** For each subagent: model turns (one request each), and
 the input, output, cache-read and cache-creation tokens the API reported for
-each of its steps, summed as the steps happen (the pane updating step by
-step is not yet seen on a real screen). `context` is the last step's
+each of its steps, summed as the steps happen (seen in a terminal preview recording on
+2026-10-31: three subagents' total climbing from 66k to 209k tokens as they ran). `context` is the last step's
 prompt (input, cache read and cache creation) plus its reply: how full the
 subagent's context was when it ended. The pane opens by itself at the first subagent of a session and lists them, biggest spender first, as many as its height holds;
 `/subagent-spend` opens it again. An agent id is shown by its first six
@@ -162,6 +185,7 @@ Set them in `/config`.
 | `usageFileDir` | `.usage-file` | Folder for `latest.json`. |
 | `turnTally` | on | The turn counts. Off: nothing is counted, no counts in the status line, no day file. |
 | `turnTallyDir` | `.turn-tally` | Folder for the day files. |
+| `capUsd` | 0 (off) | The spend cap in dollars (see Spend cap). |
 
 A relative folder is under the project the session runs in; an absolute
 path keeps every project's files in one place. An option that is off
@@ -269,19 +293,20 @@ environment variable. Everything stays on your machine.
 
 | Hook | What it does | What it changes |
 |---|---|---|
-| `session.start` | Registers `/subagent-spend`, and `/usage-file` when the usage part is on. | Nothing. |
-| `command.run` | Opens the pane the command names. | Nothing. |
+| `session.start` | Registers `/subagent-spend` and `/spend-cap`, and `/usage-file` when the usage part is on. | Nothing. |
+| `command.run` | Opens the pane the command names; `/spend-cap` shows, sets or lifts the cap for the session. | Nothing. |
 | `ui.render` (its own panes) | Draws the subagent rows, or the usage bars, from memory. | Nothing. |
 | `agent.spawn` | Notes the subagent's type; opens the spend pane at the first one. | Nothing: the spawn goes on as asked, even if the mod fails. |
 | `tool.call` | Counts the call, and whether it came back as an error (turn counts). | Nothing: the call runs as asked and its result passes through. |
-| `session.measure` | Updates the usage figures, the status line and `latest.json`; opens the Usage pane once at 80 percent. | Nothing: the event passes through untouched. |
+| `session.measure` | Updates the usage figures, the status line and `latest.json`; opens the Usage pane once at 80 percent; notes the cost for the spend cap and shows its 80 percent notice. | Nothing: the event passes through untouched. |
 | `session.end` | At a `/clear` or a resume: the subagent rows, the panes' one-time opening and `/subagent-spend` start over for the next session. | Nothing: the event passes through untouched. |
-| `turn.step` | Main conversation: counts the step and rewrites the day file. Subagent: adds the step's tokens to its row and rewrites the rows file. | Nothing: the request and the response pass through untouched. |
+| `turn.step` | Main conversation: counts the step and rewrites the day file. Subagent: adds the step's tokens to its row and rewrites the rows file. | Nothing, unless a spend cap you set is reached: then the step is answered with the cap's line and no request goes out. |
 
 ## What it does not do
 
 No dollars per subagent (plans have no price per token; use the counts).
-No cloud or remote sessions. It never denies or rewrites a request, and it
+No cloud or remote sessions. Apart from a spend cap you set, it never denies or
+rewrites a request, and it
 does not poll: with no event from Claude Code there is no write. It keeps no
 history beyond the files it leaves, and it does not say which model a usage
 window is for; Claude Code reports the windows as the account's.
@@ -328,13 +353,14 @@ sh tests/release.sh
 ```
 
 It needs `claude` on PATH, Python 3, TypeScript (`tsc` on PATH, or set
-`TSC` to a `tsc`) and Claude Code's type declarations
+`TSC` to a `tsc`; the check has passed on 5.9.3, 6.0.3 and 7.0.2, and no other
+version has been tried) and Claude Code's type declarations
 (written to `.claude-plugin/types/claude-code/index.d.ts` when you start one
 session with `claude --plugin-dir .` from the clone, or set `CC_TYPES` to
 that file). A missing compiler or missing declarations fails the check with
 what to install; it never skips.
 
-That runs `claude plugin validate .`; `claude plugin test .`, 62 tests
+That runs `claude plugin validate .`; `claude plugin test .`, 78 tests
 through the test runner Claude Code ships for plugins, with a mocked file
 system and mocked Claude Code events (the tests of the three former mods, one per
 option turned off, and tests where events finish out of order, arrive two at
@@ -350,13 +376,8 @@ fixture test fails on each (`tests/planted_bug_test.py`); and a check that the v
 plugin.json, marketplace.json, subagent_spend.py and CHANGELOG.md. It exits
 non-zero if any step fails. Changes are listed in [CHANGELOG.md](CHANGELOG.md).
 
-It needs the `claude` command, Python 3, and for the type check two more
-things, each failing with an install hint when missing: TypeScript
-(`tsc` on PATH, or set `TSC`; the check has passed on
-5.9.3, 6.0.3 and 7.0.2, and no other version has been tried), and the
-declarations Claude Code writes beside a mod it loads from a folder (run
-`claude --plugin-dir .` once in the clone, or set `CC_TYPES` to that file).
-
 Built and maintained by Nightlab, an AI agent created by xnfinite ([@xnfinite](https://github.com/xnfinite)).
 
+Nightlab on YouTube: [@NightlabBC](https://www.youtube.com/@NightlabBC).
+
 MIT license.

package/hooks/register.tsx

@@ -1,9 +1,10 @@
 import { atom, read, update } from 'claude-code'
-import type { EngineInterface, Register } from 'claude-code'
+import type { EngineInterface, Register, SessionMeasureInput } from 'claude-code'
 
 import type { Row, Shown } from '../types'
-import { addStep, fmt, latest, nextStep, rowsText, paneLines, rows, spendStatus, types } from './spend'
+import { addStep, count, fmt, latest, nextStep, rowsText, paneLines, rows, spendStatus, types } from './spend'
 import { countCall, localDay, tally, tallyText, turnsStatus } from './turns'
+import { cap, capCommand, capOf, heldText, reached, warnNow } from './cap'
 import { OPEN_AT, bar, fileText, shownOf, shownStatus, usageLines, usageStatus } from './usage'
 
 // subagent-spend, the hooks module: a session's meters in one mod.
@@ -24,8 +25,11 @@ import { OPEN_AT, bar, fileText, shownOf, shownStatus, usageLines, usageStatus }
 // each part keeps its own piece and the line shows the pieces that have a reading, in the
 // order spend | usage | turns.
 //
-// DESIGN NOTE, deliberately narrow: it never denies, never rewrites a request or an event,
-// reads only the events the engine hands it and sends nothing off the machine. A failed
+// - cap (option `capUsd`, off by default): at the cap the next model step is answered by the
+//   mod with no request made (./cap.ts).
+//
+// DESIGN NOTE, deliberately narrow: apart from the cap the user sets, it never denies, never rewrites a
+// request or an event, reads only the events the engine hands it and sends nothing off the machine. A failed
 // write is swallowed (the spend part names it once in the status line): the files are
 // advisory, and a gauge that stops the engine would be worse than no gauge.
 
@@ -130,6 +134,9 @@ function showStatus($: EngineInterface, parts: Parts) {
 
 export const register: Register = (on, options) => {
   const usageOn = options.usageFile !== false
+  cap.usd = capOf(options.capUsd)
+  cap.spent = null
+  cap.warned = false
   const turnsOn = options.turnTally !== false
   const spendDir = String(options.dir || '.subagent-spend')
   const usageDir = String(options.usageFileDir || '.usage-file')
@@ -142,10 +149,17 @@ export const register: Register = (on, options) => {
   let spendWarned = false
   // Numbers each measurement in the order the engine raised them; latest.json is written from the newest.
   let seq = 0
+  /** The last measurement, whose windows and context the status line keeps between measurements. */
+  let measured: SessionMeasureInput | undefined
+  // A session's cost only grows (SessionCost: summed over every priced response), so the highest
+  // reading is the newest: a read that answers late with a lower figure never brings it back. Each
+  // session end starts a new count, and a read still out for the session left is dropped.
+  let costSession = 0
 
   on('session.start', async ($, e, next) => {
     try {
       await $.command.register({ name: 'subagent-spend', description: 'Show what each subagent of this session costs, in a pane' })
+      await $.command.register({ name: 'spend-cap', description: 'Show, set (/spend-cap 5) or lift (/spend-cap off) the spend cap of this session' })
       if (usageOn) await $.command.register({ name: 'usage-file', description: 'Show the rate-limit windows, context and cost of this session, in a pane' })
     } catch {
       // a surface with no commands; the panes still open by themselves
@@ -153,6 +167,8 @@ export const register: Register = (on, options) => {
     return next(e)
   })
 
+  on('command.run', { command: 'spend-cap' }, async (_, e) => ({ text: capCommand(e.args ?? '') }))
+
   on('command.run', { command: 'subagent-spend' }, async $ => {
     await $.ui.open({ id: SPEND_PANE, title: SPEND_TITLE })
     return { text: `Subagent spend pane opened. ${spendStatus()}` }
@@ -174,7 +190,7 @@ export const register: Register = (on, options) => {
     return (
       <Box flexDirection="column">
         <Text bold>
-          {list.length} subagents, {fmt(tok)} tokens
+          {count(list.length, 'subagent')}, {fmt(tok)} tokens
         </Text>
         {list.length === 0 && <Text dimColor>No subagent has run in this session yet.</Text>}
         {paneLines(list)
@@ -231,9 +247,14 @@ export const register: Register = (on, options) => {
 
   on('session.end', async ($, e, next) => {
     startOver(e.sessionId)
+    // the next session's first measurement brings its own cost; the cap the user set stays
+    cap.spent = null
+    cap.warned = false
+    costSession++
     parts.spend = undefined
     // cost and context belong to the session left: the panes and the line wait for the new one's first reading
     parts.usage = undefined
+    measured = undefined
     showStatus($, parts)
     try {
       await update($, shownRows, () => [])
@@ -245,8 +266,18 @@ export const register: Register = (on, options) => {
   })
 
   on('session.measure', async ($, e, next) => {
+    if (e.cost) cap.spent = Math.max(cap.spent ?? 0, e.cost.usd)
+    const warning = warnNow()
+    if (warning) {
+      try {
+        $.ui.toast(warning)
+      } catch {
+        // a surface with no toasts: the cap still holds
+      }
+    }
     if (!usageOn) return next(e)
     const mine = ++seq
+    measured = e
     parts.usage = usageStatus(e)
     showStatus($, parts)
     try {
@@ -277,6 +308,30 @@ export const register: Register = (on, options) => {
   })
 
   on('turn.step', async function* ($, e, next) {
+    if (cap.usd !== null) {
+      // session.measure comes after a turn, not after each step: a tool loop or a subagent inside one
+      // turn is held only if the cost is read here, before each step
+      const session = costSession
+      try {
+        const usage = await $.session.usage()
+        const usd = session === costSession ? usage.cost?.usd : undefined
+        if (usd !== undefined && usd >= (cap.spent ?? 0)) cap.spent = usd
+        if (usd !== undefined && usd === cap.spent && usageOn && measured) {
+          // the line's dollar figure is the one the cap holds on, not the last turn's
+          parts.usage = usageStatus(measured, usd)
+          showStatus($, parts)
+        }
+      } catch {
+        // no cost here: the last measurement stands
+      }
+    }
+    if (reached()) {
+      // answered here, no request made: the turn (or the subagent) ends on this text
+      const text = heldText()
+      yield { kind: 'text' as const, index: 0, text }
+      yield { kind: 'stop' as const, stopReason: 'end_turn' as const, usage: null }
+      return { turnId: e.turnId, index: e.index, answer: text, toolUses: [], stopReason: 'end_turn' as const, usage: null }
+    }
     if (!e.agentId) {
       if (!turnsOn) return yield* next(e)
       // A main-loop step: counted as it starts, its file named and filled before any wait, so an

package/hooks/spend.ts

@@ -89,10 +89,13 @@ export const label = (id: string, all: readonly string[]) => {
   return id
 }
 
+/** `1 turn`, `2 turns`: a count with its word, singular for one. */
+export const count = (n: number, word: string) => `${n} ${word}${n === 1 ? '' : 's'}`
+
 /** The pane's lines, biggest spender first: `Explore  a1b2c3  8 turns  41k (out 2104, ctx 24k)  claude-opus-5-5`. */
 export const paneLines = (list: Row[]) => {
   const ids = list.map(r => r.agent_id)
   return [...list]
     .sort((a, b) => b.total - a.total)
-    .map(r => `${r.agent_type || 'agent'}  ${label(r.agent_id, ids)}  ${r.turns} turns  ${fmt(r.total)} (out ${fmt(r.output)}, ctx ${fmt(r.context ?? 0)})  ${r.model}`)
+    .map(r => `${r.agent_type || 'agent'}  ${label(r.agent_id, ids)}  ${count(r.turns, 'turn')}  ${fmt(r.total)} (out ${fmt(r.output)}, ctx ${fmt(r.context ?? 0)})  ${r.model}`)
 }

package/hooks/usage.ts

@@ -61,10 +61,12 @@ export const fileText = (e: SessionMeasureInput, session: string, now: Date) =>
   ) + '\n'
 
 /** The status line part: only the figures that have a reading; undefined when none has. */
-export const usageStatus = (e: SessionMeasureInput) => {
+export const usageStatus = (e: SessionMeasureInput, usd?: number) => {
   const parts = e.rateLimits.map(w => `${LABEL[w.kind] ?? w.kind} ${w.percentUsed}%`)
   if (e.context.percent !== undefined) parts.push(`ctx ${e.context.percent}%`)
-  if (e.cost) parts.push(`$${e.cost.usd.toFixed(2)}`)
+  // `usd`: a cost read since that measurement (before a step, for the cap) replaces its figure
+  const shown = usd ?? e.cost?.usd
+  if (shown !== undefined) parts.push(`$${shown.toFixed(2)}`)
   return parts.length ? parts.join(' | ') : undefined
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nightlab-agent/subagent-spend",
-  "version": "0.7.2",
-  "description": "Claude Code mod: per-subagent tokens, rate-limit windows, context fill, cost, steps, tool calls and tool errors of a session, in a notice under the prompt, local files and panes.",
+  "version": "0.8.0",
+  "description": "Claude Code mod: a spend cap for interactive sessions, and per-subagent tokens, rate-limit windows, context fill, cost, steps, tool calls and tool errors of a session, in a notice under the prompt, local files and panes (the usage pane not yet seen on a screen).",
   "keywords": [
     "claude-code",
     "claude-code-mod",
@@ -9,7 +9,10 @@
     "subagents",
     "token-usage",
     "rate-limits",
-    "statusline"
+    "statusline",
+    "spend-cap",
+    "budget",
+    "max-budget-usd"
   ],
   "homepage": "https://github.com/nightlab-agent/subagent-spend#readme",
   "bugs": "https://github.com/nightlab-agent/subagent-spend/issues",

package/subagent_spend.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""subagent-spend 0.7.2: attribute Claude Code token usage to each subagent.
+"""subagent-spend 0.8.0: attribute Claude Code token usage to each subagent.
 
   subagent_spend.py hook        SubagentStop hook: reads the hook JSON on stdin, sums the usage
                                 in the subagent transcript, appends one line to the session's rows file.