@nightlab-agent/subagent-spend 0.0.0-stage → 0.7.2

package/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "nightlab",
+  "owner": {
+    "name": "Nightlab"
+  },
+  "plugins": [
+    {
+      "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",
+      "category": "productivity"
+    }
+  ],
+  "description": "One mod: per-subagent tokens, usage limits and turn counts for Claude Code sessions, by Nightlab."
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,57 @@
+{
+  "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).",
+  "author": {
+    "name": "Nightlab"
+  },
+  "homepage": "https://github.com/nightlab-agent/subagent-spend",
+  "repository": "https://github.com/nightlab-agent/subagent-spend",
+  "license": "MIT",
+  "keywords": [
+    "hooks",
+    "mod",
+    "claude-code-mod",
+    "pane",
+    "statusline",
+    "subagents",
+    "token-usage",
+    "rate-limits",
+    "usage",
+    "headless",
+    "max-turns",
+    "budget"
+  ],
+  "userConfig": {
+    "dir": {
+      "type": "string",
+      "title": "Rows folder",
+      "description": "Folder for the per-session rows file. A relative path is under the project the session runs in; give an absolute path to keep every project in one place.",
+      "default": ".subagent-spend"
+    },
+    "usageFile": {
+      "type": "boolean",
+      "title": "Usage file and pane",
+      "description": "Show the rate-limit windows, context fill and cost in the status line and a Usage pane, and write them to latest.json. Off: none of that.",
+      "default": true
+    },
+    "usageFileDir": {
+      "type": "string",
+      "title": "Usage file folder",
+      "description": "Folder for latest.json. A relative path is under the project the session runs in; give an absolute path to keep one file for every project.",
+      "default": ".usage-file"
+    },
+    "turnTally": {
+      "type": "boolean",
+      "title": "Turn counts",
+      "description": "Count the main conversation's steps, tool calls and tool errors in the status line and a file for each day. Off: none of that.",
+      "default": true
+    },
+    "turnTallyDir": {
+      "type": "string",
+      "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"
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,181 @@
+# Changelog
+
+The form is Keep a Changelog; versions follow SemVer.
+
+## 0.7.2 - 2026-10-30
+
+### Added
+- The mod is also on npm as `@nightlab-agent/subagent-spend` (package.json; no install scripts).
+
+### Changed
+- The README's preview picture is linked by its full GitHub address, so the npm page can show it too.
+
+## 0.7.1 - 2026-10-30
+
+### Fixed
+- When a step of a subagent's earlier run was counted after a step of its newer run (its session lookup came back
+  late), the row's context, time and model went back to the earlier run's. Its tokens are still added; the context,
+  time and model now stay the newer run's. One failing test and two comparison cases in hooks/review-late.test.tsx.
+
+## 0.7.0 - 2026-10-29 - absorbs usage-file and turn-tally
+
+Three separate mods (subagent-spend, usage-file, turn-tally) measured one session from three sides; one install now does all three. Minor, not patch: new
+options, new files written and a new status line.
+
+### Fixed
+- A /clear while a rows-file write was waiting on the disk emptied the old session's file: the text is now taken
+  when the step is counted. After a /clear the subagent pane and the Usage pane went on showing the old session (the
+  command already said 0); both now start empty, and the usage part of the status line waits for the new reading.
+- The by-hand script named the rows file `unknown.jsonl` when Claude Code gave no session id; it is now
+  `no-session.jsonl`, as the mod and the README name it.
+- Each `.gitignore` is written only in a folder of the mod's own name: with `dir` set to `.`, it replaced the
+  project's own `.gitignore` with `*`. The by-hand script keeps the same rule for `SUBAGENT_SPEND_DIR`.
+- After a `/clear` (a new session id with no new session start) the old session's subagents no longer land in the
+  new session's rows file; `/subagent-spend` and the usage pane's one-time opening start over at the session's end,
+  even when no subagent runs after it. A late answer naming the session just left does not switch back to it; a
+  later resume into that session counts there again.
+- On a host with no session id, a subagent step is still counted (rows file `no-session.jsonl`).
+- A deleted folder came back in the same session without its `.gitignore`, so git saw the rows file: the
+  `.gitignore` is now checked before every write.
+- Tests for the `/clear` (old rows kept apart, the pane and the command starting over, a late session id, a
+  resume), a deleted folder, a host with no session id, and the by-hand script's `.gitignore` rule, and a write still waiting across a /clear; 62 module tests in all.
+
+### Changed
+- plugin.json and marketplace.json say the usage pane is not yet seen on a screen (the subagent pane was seen at 150 columns).
+- README: Install comes right after the opening paragraph and names the Claude Code versions it needs
+  (2.1.275 for `/plugin install --marketplace`, 2.1.292 for the shell form, from Claude Code's CHANGELOG); the
+  notice is shown as a terminal drew it, with the `⚠ subagent-spend:` Claude Code puts in front; claude-hud's
+  features are named from its README instead of left unchecked.
+- `subagent_spend.py --help` prints the commands; an unknown command or extra arguments print them to stderr
+  and exit 2 (before, they ran the report and created `.subagent-spend` in the current folder). Run bare from a
+  terminal, it prints them instead of waiting on stdin.
+- `tests/planted_bug_test.py`: the fixture test must fail on four planted bugs; `tests/release.sh` runs it.
+- One notice under the prompt holds all three parts, subagent figures first: at 120 columns Claude Code cut a
+  line that put them last after "tok 27" (seen in a terminal preview, 2026-10-29).
+- One status line for the three parts, `subagents | usage | turns`, each piece as its mod showed it. Each status call
+  sets the whole line, so three parts setting it in turn would have replaced each other.
+- The pane shows an agent id by its first six characters, longer where two listed ids start the same; before, two
+  agents whose ids shared six characters showed the same label.
+- Every file is written one write at a time from the newest figures. turn-tally 0.4.0 could write an older step's
+  message count over a newer one when its first write was slow; found by the new out-of-order test.
+- README rewritten for the three parts.
+- `tests/typecheck.sh` no longer falls back to a folder on the maintainer's machine. It uses `TSC` and `CC_TYPES`
+  when set, else `npx --no-install tsc` or `tsc` on PATH, and the declarations Claude Code writes beside the mod
+  (`.claude-plugin/types/claude-code/index.d.ts`); a missing one still fails, now with what to install.
+- Notes in `CLAUDE.md`, `00-catalog/`, and `01-context/`, and this file, rewritten in plain words.
+
+### Added
+- The usage part, from usage-file 0.4.1, behind the `usageFile` option (default on): the rate-limit windows, context
+  fill and cost in a Usage pane (`/usage-file`, or by itself once at 80 percent) and in `<usageFileDir>/latest.json`.
+  The default folder is `.usage-file` and the file's format is unchanged, so a script that read usage-file's file
+  keeps working.
+- The turn counts, from turn-tally 0.4.0, behind the `turnTally` option (default on): main-conversation steps, tool
+  calls, tool errors and error streak in `<turnTallyDir>/<YYYY-MM-DD>.txt`, same folder and lines as turn-tally
+  but one: `tool calls 11 (subagents 30)` now reads `tool calls 11 (30 by subagents)` (in a terminal preview the
+  old form was read as a count of subagents).
+- Options `usageFileDir` and `turnTallyDir` (the two mods' `dir` options under new names; this mod's `dir` stays the
+  subagent rows folder).
+- Tests: the 14 of usage-file and the 6 of turn-tally, adapted; one per option turned off and its control; one for the combined status
+  line; four for events that finish out of order, two subagents stepping while the main turn is open, and ids that look
+  alike.
+- A look-alike test for two agents of the same type: they stay two rows with their own counts (it fails if rows are
+  keyed by type).
+- README: a "Remove it" section (uninstall, and the folders and files to delete).
+
+## 0.6.0 - 2026-10-29 - the folder is kept out of git
+
+### Added
+- Before its first write in a session the mod writes `<dir>/.gitignore` holding one line, `*`, so git ignores the
+  folder in every project with no step from you (an outside review of the repo pointed it out, 2026-10-29).
+- A test for it, which failed before the change. The by-hand script `subagent_spend.py` writes the same `.gitignore`
+  when it makes the folder (checked by the fixture test).
+- `docs/finding.md`: the subagent-token finding written up from every row recorded before 2026-10-29 01:10 (26
+  subagents, 16 sessions), with the method, the three hand checks and what it does not say. The README's six-row table said "every row" when it was the first six
+  measured; it now says so and points at the full set.
+
+### Changed
+- README rewritten in plain words: what it measures, how to install it, what it writes and how to delete it. It no
+  longer carries a version history (this file does), and no longer advertises other products.
+
+## 0.5.3 - 2026-10-28 - a README section on making your own mod
+
+### Added
+- README: a Build your own section pointing to a mod template (the section is gone since 0.7.0).
+
+## 0.5.2 - 2026-10-28 - what the subagent figure leaves out
+
+### Added
+- README: "Measured", six live runs from the maintainer's own rows files comparing the `subagent_tokens` figure Claude Code prints with the tokens each subagent ran through (3.6 to 14.8 times), with the cache-read share and how to check it on your own subagents. No behaviour change.
+
+### Changed
+- The release check runs the plugin directory checklist (`tests/checklist.py`, from mod-ready); a FAIL stops a release, including a `publishConfig` or a package.json repository that is not the plugin's own GitHub repo.
+- `tests/typecheck.sh` fails when `TSC` is neither an executable nor a command on PATH (before, it fell back to PATH), or when there is no hooks module file to check (before, it passed).
+
+## 0.5.1 - 2026-10-28 - the release check type-checks
+
+### Changed
+- The release check type-checks the hooks module, its tests and the state contract with `tsc --noEmit` against the
+  engine's own declarations (`tests/typecheck.sh`, the compiler options the declarations' header gives a hooks module).
+  No `tsc` or no declarations fails the release check; it never skips.
+
+### Fixed
+- Test inputs are now complete to the engine's types (the full `command.run`, `agent.spawn` or `turn.step` shapes the tests left out). No behaviour change.
+
+## 0.5.0 - 2026-10-28 - the rows folder is an option; the module reads no environment
+
+### Changed
+- The rows folder is the `dir` option (`userConfig`, set in `/config`), default `.subagent-spend` under the project the session runs in. It was `~/.subagent-spend` or `SUBAGENT_SPEND_DIR`; the hooks module no longer reads `HOME` or any other environment variable. To keep the old place, set `dir` to the absolute path of your old folder.
+- `subagent_spend.py` (the by-hand hook and `report`) defaults to `.subagent-spend` under the current folder; `SUBAGENT_SPEND_DIR` still overrides it there.
+- README: the credit line names the agent's creator, xnfinite.
+
+## 0.4.2 - 2026-10-28 - says what each hook does, and that nothing leaves the machine
+
+### Changed
+- README: a table of each hook, what it does, what it changes (nothing) and the one file the mod writes; it says plainly that no data leaves the machine.
+- The design comment and CLAUDE.md say what the module reads (only the events the engine hands it) instead of listing what it does not read.
+- plugin.json: the `types` field is gone (not part of the plugin manifest; the `types/` folder stays for the module).
+
+## 0.4.1 - 2026-10-28 - ctx matches Claude Code's own figure
+
+- `context` now adds the last step's reply to its prompt. That is the number Claude Code prints as `subagent_tokens` when a subagent returns: checked live, a one-word subagent read 18,028 in both (0.4.0 said 18,024, short by its 4-token reply) and a five-tool reader 50,279 (0.4.0 said 48,801).
+- The by-hand hook computes it the same way. Tests expect the new sums.
+
+## 0.4.0 - 2026-10-28 - how full each one got
+
+- Each row gains `context`: the last step's prompt (input + cache read + cache creation), the size of the subagent's context when it ended. `total` sums every step, so a subagent that re-reads a long prefix for eight steps shows a total several times its context; the two answer different questions (what it spent, how full it got).
+- The pane row adds it: `8 turns  41k (out 2104, ctx 24k)`. `report` prints a `context` column; rows from earlier versions show `-`.
+- The by-hand hook writes the same field from the transcript's newest step.
+- Tests: the module tests and the fixture check the field; against 0.3.1 they fail 3 and 1.
+- Minor, not patch: a new field in the rows.
+
+## 0.3.1 - 2026-10-28 - the README tells the truth
+
+- CLAUDE.md described the 0.1 design (one SubagentStop script) and named a path on the maintainer's machine; it now describes the hooks module and the pane, and names no outside path. No code change.
+
+## 0.3.0 - 2026-10-28 - a pane
+
+- A side pane, "Subagent spend", lists every subagent of the session, biggest spender first: type, the first six characters of its id, turns, total tokens, output tokens, model. It redraws on each subagent step.
+- The pane opens by itself at the first subagent a session starts, once; `/subagent-spend` opens it at any time and answers with the running total. A surface that seats no panes is left alone; the rows file and status line go on.
+- The module is now `hooks/register.tsx` with a state contract in `types/index.d.ts`; the rows file, its rows and the status line are unchanged.
+- Tests: 11 checks (was 7), the four new ones on the pane, the command, opening once, and a value an earlier version stored.
+- Minor, not patch: the module draws now and registers a command.
+
+## 0.2.0 - 2026-10-27 - hooks module
+
+- The plugin is now a hooks module (`hooks/register.ts`): on every model step of a subagent it reads the usage the API reported for that step and sums it per agent. Live per step, not at the subagent's end, and no transcript is read.
+- The rows file and its rows are unchanged (`~/.subagent-spend/<session_id>.jsonl`, one JSON row per agent; `SUBAGENT_SPEND_DIR` overrides the folder), so `subagent_spend.py report` and `subagent_spend.py statusline` read it as before. The module rewrites the file whole after each step instead of appending.
+- The running total is also put in the status line by the module itself (`subagents 2 | tok 7340 (out 120)`).
+- A rows file that cannot be written is named once in the status line; the session goes on.
+- The `SubagentStop` command hook is no longer registered by the plugin; it stays as the by-hand install in `kit/settings-snippet.json` for a Claude Code that loads no hooks modules. Install one of the two, not both, or every agent is counted twice.
+- Tests: `hooks/register.test.ts` (6 checks under `claude plugin test`) beside the fixture test; `tests/release.sh` runs validate, both test sets and the version check, and is the release check.
+- Minor, not patch: which hook the plugin registers changed.
+
+## 0.1.1 - 2026-10-27
+
+- Readers keep one row per `agent_id` (the last write wins), so a repeated `SubagentStop` for one agent is counted once.
+- Plugin and marketplace manifests, `hooks/hooks.json`, an icon; the one-line install.
+- Release check: `nightlab-release.json` names the fixture test.
+
+## 0.1.0 - 2026-10-27
+
+- First version: `SubagentStop` command hook summing a subagent's transcript, statusline, report, fixture test.

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Nightlab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,362 @@
-# Temporary Holding Version
+# subagent-spend
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+panes: the subagent pane is seen below; the Usage pane is not yet seen on a
+real screen. Nothing leaves your machine.
+
+![Claude Code after three subagents ran: the subagent pane lists the three with their turns and tokens, and the line under the prompt reads subagents 3, tok 218k, then the usage windows, cost and step counts](https://raw.githubusercontent.com/nightlab-agent/subagent-spend/c676e8c3462af96a5b8d581b0adb479fa706f470/docs/preview.png)
+
+Seen in a Claude Code 2.1.312 terminal (150 columns) on 2026-10-29, after
+three subagents ran: the subagent pane opened by itself and the whole line
+fits. `tok` counts every token the subagents sent and got, cache reads
+included, so it is larger than the token figure each subagent reports when it
+returns. At 120 columns the same session drew no pane and the end of the line
+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):
+
+```
+/plugin install subagent-spend --marketplace nightlab-agent/subagent-spend
+```
+
+Answer `y` to add the marketplace, then pick a scope. The same from a shell
+(Claude Code 2.1.292 or later):
+
+```
+claude plugin install subagent-spend --marketplace nightlab-agent/subagent-spend
+```
+
+The same files are on npm as
+[`@nightlab-agent/subagent-spend`](https://www.npmjs.com/package/@nightlab-agent/subagent-spend),
+so a marketplace of your own can list it with
+`"source": {"source": "npm", "package": "@nightlab-agent/subagent-spend"}`.
+For one run without installing, clone the repo and start Claude Code with
+`--plugin-dir <path to the clone>`.
+
+If you had usage-file or turn-tally installed, uninstall them first. Kept
+beside this mod, each would write the same file as its part here.
+
+By hand, for a Claude Code that cannot load this mod's code (subagent spend
+only, three steps):
+
+1. Copy `subagent_spend.py` somewhere stable in your home folder.
+2. In your Claude Code user settings JSON, add a `SubagentStop` hook of type
+   `command` whose command is `python3 -I <path>/subagent_spend.py hook`, and
+   a `statusLine` of type `command` whose command is
+   `python3 -I <path>/subagent_spend.py statusline`. The exact JSON is in
+   `kit/settings-snippet.json`; merge it with what you already have.
+3. Start a session that uses a subagent. The status line reads
+   `Opus | subagents 2 | tok 7340 (out 120)`. The script writes under
+   `.subagent-spend` in the folder Claude Code runs in, or under
+   `$SUBAGENT_SPEND_DIR` if you set it; `report` reads (and creates) the
+   same folder in the folder you run it from.
+
+Install the mod or the script, not both: both write rows for the same
+subagents into the same file, the mod rewriting it whole and the script
+appending, so the two sets collide. The script's `statusline` command also
+creates the folder (and its `.gitignore`) in whatever project Claude Code
+runs in.
+
+If a figure looks wrong, open an issue with the file it came from and your
+Claude Code version.
+
+claude-hud (about 29k stars on GitHub) already shows the usage limits, how
+full the context is, the running agents with their model, and the session's
+token totals, and it can write the limits to a JSON file (its README,
+read 2026-10-29). Its README lists no token count per subagent and no file
+per subagent. If the limits are all you want, claude-hud does more. What this
+one adds, as its code shows (`hooks/spend.ts`, `hooks/register.tsx`): it sums
+each subagent's tokens from the usage of every model step that subagent
+takes, keeps how full its context ended apart from how many tokens went
+through the model, and writes one local row per subagent that a script can
+read.
+
+It has three parts. The usage and turn parts were the separate mods
+usage-file and turn-tally; each can be turned off on its own.
+
+| Part | Shows | Writes |
+|---|---|---|
+| Subagent spend | every subagent's tokens, turns and model, in a pane | `.subagent-spend/<session_id>.jsonl` |
+| Usage (`usageFile`) | rate-limit windows, context fill and cost, in a pane (not yet seen on a screen) | `.usage-file/latest.json` |
+| Turn counts (`turnTally`) | main-conversation steps, tool calls and tool errors | `.turn-tally/<YYYY-MM-DD>.txt` |
+
+What the panes and the status line hold, written out. In the previews of
+this version (Claude Code 2.1.312), the 120-column ones drew no pane and the
+150-column one opened the subagent pane by itself; the Usage pane has not
+been seen. The two pane examples below are what the code draws, not a capture.
+
+```
+2 subagents, 53k tokens
+Explore  a1b2c3  8 turns  41k (out 2104, ctx 24k)  claude-opus-5-5
+claude   d4e5f6  3 turns  12k (out 640, ctx 9k)  claude-opus-5-5
+```
+
+```
+5-hour      ████████░░  81%  resets in 1h 12m
+Weekly      ██████░░░░  61%  resets in 3d 4h
+Context     ██░░░░░░░░  20%
+Cost        $1.23
+measured 14:02:11 UTC
+```
+
+Notice under the prompt, as the code writes it: `subagents 2 | tok 53k (out 2744) | 5h 81% | 7d 61% | ctx 20% | $1.23 | steps 12 | tools 11 | errors 1 (streak 0)`.
+Claude Code puts the mod's name in front. The subagent figures come first:
+at 120 columns Claude Code cut the end of the line with "…". A terminal
+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 …
+```
+
+## 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
+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
+characters, longer where two ids start the same, so two agents never share
+a label.
+
+**Usage.** The five-hour and seven-day windows with their percent used and
+time to reset, the context window's fill, and the session's cost so far, as
+Claude Code's own measurement event reports them (after each turn of the
+main conversation, and when a window moves a whole point). `/usage-file`
+opens the Usage pane (not yet seen on a real screen, so its bars and cost
+figure are not either). It also asks to open itself once, the first time any
+window reaches 80 percent; Claude Code places a pane nobody asked for only
+when the terminal is at least 144 columns wide; the self-opening at 80
+percent has not been tried at any width. A window at 80 percent or
+more is drawn in red (not yet seen on a real screen).
+
+**Turn counts.** A step is one model request on the main conversation.
+Steps inside a subagent are not counted, and a subagent's tool calls are
+counted apart. A tool error is a tool call whose result came back as an
+error; a call a hook denied never ran and is not one. The streak is the run
+of consecutive main-conversation tool errors.
+
+**The status line** is one line for all three. Each part keeps its own
+piece, and the line shows the pieces that have a reading, in the order
+subagents, usage, turns. A part that is off, or has nothing yet, adds
+nothing. One line rather than three because each call a mod makes sets its
+whole status line: three parts each setting it would replace each other.
+
+## Options
+
+Set them in `/config`.
+
+| Option | Default | What it does |
+|---|---|---|
+| `dir` | `.subagent-spend` | Folder for the subagent rows. |
+| `usageFile` | on | The usage part. Off: no Usage pane, no `/usage-file`, no usage figures in the status line, no `latest.json`. |
+| `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. |
+
+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
+passes its events through untouched.
+
+## What it writes
+
+Each folder gets a `.gitignore` holding one line, `*`, before anything else,
+so git ignores the folder in every project with no step from you. That holds for
+a folder of the mod's own name (the defaults, or a path ending in one). A folder
+of another name may hold your own files (it could even be `.`), so the mod
+leaves git alone there: if it is inside a project, add it to that project's
+`.gitignore`.
+
+- `.subagent-spend/<session_id>.jsonl`: one JSON row per subagent,
+  rewritten whole after every subagent step. A row holds the counts, the
+  agent's id and type, the session id, the model name and a time. The
+  by-hand hook adds a row each time a subagent stops; a repeated stop adds
+  a repeated row, which `report` and `statusline` count once.
+  Where Claude Code gives no session id, the file is `no-session.jsonl`.
+- `.usage-file/latest.json`: the same path and the same format usage-file
+  wrote, so a script that read it keeps working. Rewritten whole each time a
+  figure moves:
+
+  ```json
+  {
+    "at": "2026-10-27T21:03:12.481Z",
+    "session": "9c1d4e2a-…",
+    "changed": ["context", "rateLimits"],
+    "context": { "tokens": 41230, "window": 200000, "percent": 20 },
+    "rateLimits": [
+      { "kind": "five_hour", "percentUsed": 23.5, "resetsAt": "2026-10-27T22:00:00Z" },
+      { "kind": "seven_day", "percentUsed": 61, "resetsAt": "2026-11-01T04:00:00Z" }
+    ],
+    "cost": { "usd": 1.23 }
+  }
+  ```
+
+  `changed` names which figures differ from the last measurement.
+  `rateLimits` is empty off a subscription and before Claude Code's first
+  reading of the windows.
+  `cost` is `null` where Claude Code keeps no cost figure;
+  `context.tokens` and `context.percent` are `null` until the first
+  response reports a fill; `session` is `null` on a host that has none.
+- `.turn-tally/<YYYY-MM-DD>.txt`: the same path and lines turn-tally
+  wrote, except the tool calls line now ends `(30 by subagents)`, not
+  `(subagents 30)`; rewritten whole on every main-conversation step. The
+  counts run from the start of the session, so a session that goes past
+  midnight carries them into the new day's file:
+
+  ```
+  steps 12
+  tool calls 11 (30 by subagents)
+  tool errors 1, current streak 0, longest streak 1
+  model claude-opus-5-5, messages 41
+  updated 2026-10-27 16:40:12
+  ```
+
+No prompt, reply or tool input text is stored. To forget, end the session
+and delete a file or a folder: a running session writes it again at its
+next event. Nothing reads the files but this repo's `report` and
+`statusline` commands, and you, or a runner you point at them.
+
+Each file is written one write at a time, always from the newest figures,
+so an older event that finishes late never lands on top of a newer one.
+Claude Code makes no promise that a write is atomic, so a reader that finds
+a file unparsable should read it again. Two sessions in the same project
+write the same `latest.json` and the same day file; the last one wins, and
+`session` or `updated` says which.
+
+## Measured: what the subagent figure leaves out
+
+When a subagent returns, the Agent tool's result gives the parent a
+`subagent_tokens` figure. It reads as the last step's prompt plus its
+reply: roughly how full the subagent's context was at the end, not how many
+tokens went through the model. Three subagents were checked by hand, and in
+one of the three the stored `context` equalled the figure (25,590). The
+other two rows came from an older version that stored the prompt alone: one
+matched once its 4-token reply was added (18,024 + 4 = 18,028), and one fell
+1,478 short (48,801 against 50,279), a gap that may be its reply, which was
+not stored. So one check is an exact match and two are not.
+
+[docs/finding.md](docs/finding.md) holds every row this mod recorded with a
+`context` value in the maintainer's own sessions before 2026-10-29 01:10 local:
+26 subagents in 16 sessions, all general-purpose on Claude Opus 5.5, none
+left out. The tokens through the model were 1.0 (a one-step subagent) to
+14.8 times the figure, median 6.6. Most of each total is cache reads, and
+the API prices each kind of token differently, so this is a token count
+(one machine, one account, one agent type), not a cost or a benchmark.
+
+Check it on your own subagents: run one, find `subagent_tokens` in the
+result the Agent tool returns, then find the row with the same `agent_id`
+in the file. `context` should equal the figure; `total` is what went
+through. The table, for one session or all of them:
+
+```
+python3 -I subagent_spend.py report --all
+```
+
+## What each hook does
+
+The mod makes no network request and sends nothing anywhere. It only reads
+the events Claude Code hands it and its own options; it reads no
+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. |
+| `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.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. |
+
+## 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
+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.
+
+The sums and counts live in memory: reloading the plugin in a running
+session starts them over. A folder that cannot be written is named once in
+the status line for the subagent rows, and passed over in silence for the
+other two; the session goes on. A subagent step whose response carried no
+usage (a failed or aborted request) adds nothing.
+
+## Remove it
+
+1. Uninstall the mod: `/plugin uninstall subagent-spend` at the Claude Code
+   prompt, or `claude plugin uninstall subagent-spend` from a shell. To drop
+   the marketplace too: `claude plugin marketplace remove nightlab`. (These
+   are the commands Claude Code 2.1.312 lists in its help; the uninstall has
+   not yet been run on a real install of this mod.)
+2. In each project where a session ran with it, delete the folders it wrote,
+   with everything in them (each holds a `.gitignore` with `*`, so git never
+   tracked them):
+   - `.subagent-spend/` (the subagent rows, `<session_id>.jsonl`), or the
+     folder you set in `dir`;
+   - `.usage-file/` (`latest.json`), or the folder you set in `usageFileDir`;
+   - `.turn-tally/` (`<YYYY-MM-DD>.txt`), or the folder you set in
+     `turnTallyDir`.
+   A folder you set as an absolute path is in that one place, not per project.
+3. If you installed by hand: remove the `SubagentStop` hook and the
+   `statusLine` entry you added to your Claude Code user settings, delete
+   your copy of `subagent_spend.py`, and delete `.subagent-spend/` in each
+   folder Claude Code ran in (or `$SUBAGENT_SPEND_DIR` if you set it).
+4. If you ran it from a clone with `--plugin-dir`, delete the clone. Claude
+   Code writes its own declarations into the clone's
+   `.claude-plugin/types/`; that folder is ignored by the repo's
+   `.gitignore` and goes with the clone.
+
+Nothing else is written: no settings, and nothing outside those folders (the module's writes are only `<folder>/.gitignore` and the
+three files above; `tests/checklist.py` checks every write path is fixed text
+or under an option folder).
+
+## Tests
+
+```
+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
+(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
+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
+once, or carry ids or types that look alike); a type check with
+`tsc --noEmit` against Claude Code's declarations; a checklist of rules Anthropic's plugin
+directory raised on earlier submissions of these mods (submitted, not
+approved); the by-hand script's test on a made-up session
+(`tests/fixture_test.py`), which also checks `--help` and an unknown
+command; a planted-bug test that breaks a copy of the script four ways
+(streamed steps counted twice, cache reads dropped, a repeated stop
+counted again, an unknown command running the report) and fails unless the
+fixture test fails on each (`tests/planted_bug_test.py`); and a check that the version string agrees in
+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)).
+
+MIT license.

package/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }