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

package/hooks/register.tsx

@@ -0,0 +1,329 @@
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, Register } from 'claude-code'
+
+import type { Row, Shown } from '../types'
+import { addStep, count, fmt, latest, nextStep, rowsText, paneLines, rows, spendStatus, types } from './spend'
+import { countCall, localDay, tally, tallyText, turnsStatus } from './turns'
+import { OPEN_AT, bar, fileText, shownOf, shownStatus, usageLines, usageStatus } from './usage'
+
+// subagent-spend, the hooks module: a session's meters in one mod.
+//
+// Three parts, each with its own file folder:
+// - spend (always on): on every model step of a subagent's loop (`turn.step` with an
+//   `agentId`) the engine hands back the response's usage; it is summed per agent, the
+//   session's rows file is rewritten whole under the `dir` option, and a side pane lists
+//   every agent, opened at the first subagent of a session or by /subagent-spend.
+// - usage (option `usageFile`, was the usage-file mod): on `session.measure` the rate-limit
+//   windows, context fill and cost go to `<usageFileDir>/latest.json` and a second pane,
+//   opened by /usage-file or once when a window reaches OPEN_AT percent.
+// - turns (option `turnTally`, was the turn-tally mod): on each main-loop step the steps,
+//   tool calls, tool errors and error streak go to `<turnTallyDir>/<day>.txt`.
+// A part whose option is off passes its events to `next` and returns the result untouched.
+//
+// One status line: three mods each setting the whole line would overwrite each other, so
+// 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
+// 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.
+
+const SPEND_PANE = 'subagent-spend'
+const SPEND_TITLE = 'Subagent spend'
+const USAGE_PANE = 'usage-file'
+const USAGE_TITLE = 'Usage'
+
+// What the panes draw; the module's own Map stays the rows file's source. Change a tag
+// when its type's fields change: it declines what an earlier version stored.
+const shownRows = atom({ plugin: 'subagent-spend', key: 'rows' } as const, [] as Row[], { shape: 'rows-2' })
+const shownUsage = atom({ plugin: 'subagent-spend', key: 'latest' } as const, null as Shown | null, { shape: 'latest-1' })
+
+let spendOpened = false
+let usageOpened = false
+// The session the sums belong to. A /clear goes on under a new session id with no new session.start;
+// session.end fires for it (declarations, SessionEndInput.reason), and there the sums and the panes'
+// opening start over. The first event that sees another id does the same, for a host that sends no end.
+let rowsSession: string | null = null
+// Asks for the id are numbered. An answer asked before the latest switch that names the session just left
+// came back late (asks wait at once); it never switches back. A later ask may name it again (a resume).
+let asks = 0
+let switchedAt = 0
+let leftSession: string | null = null
+
+function startOver(left: string | null) {
+  leftSession = left
+  switchedAt = asks
+  rowsSession = null
+  rows.clear()
+  latest.clear()
+  spendOpened = false
+  usageOpened = false
+}
+
+/** This session's id ('' on a host with none), or null for a late answer naming the session just left. */
+async function sessionNow($: EngineInterface) {
+  const mine = ++asks
+  let id = ''
+  try {
+    id = await $.session.id()
+  } catch {
+    // no session id on this host
+  }
+  if (mine <= switchedAt && id === leftSession) return null
+  if (rowsSession !== null && id !== rowsSession) startOver(rowsSession)
+  rowsSession = id
+  return id
+}
+
+/** One file of one part in this session: whether a write is in flight, whether one is owed, whether
+ * `<dir>/.gitignore` is left alone (a folder not of the mod's own name) or was written, and the newest content to write. */
+type Out = { writing: boolean; owed: boolean; ignore: boolean; ignored: boolean; newest: { name: string; text: () => string } | null }
+const out = (own: boolean): Out => ({ writing: false, owed: false, ignore: !own, ignored: false, newest: null })
+
+/** One write at a time per file, always from the newest content. Two events can wait at once (on
+ * `$.session.id()` or on a write); if the earlier one's write landed last, its older figures would sit on
+ * top of the newer ones. An event that finds a write in flight marks the file as owed and goes on; the
+ * writing one writes again, from the newest content, until nothing is owed. A failed write is made up
+ * by the next event. Before each write, when it is missing: `<dir>/.gitignore` holding `*`, so git
+ * ignores the folder in every project with no step from the user. */
+async function writeLatest($: EngineInterface, dir: string, f: Out) {
+  if (f.writing) {
+    f.owed = true
+    return
+  }
+  f.writing = true
+  try {
+    do {
+      f.owed = false
+      if (!f.ignore) {
+        // checked before every write, not once: a user who deletes the folder mid-session gets it back ignored
+        let has = f.ignored
+        try {
+          has = await $.fs.exists(`${dir}/.gitignore`)
+        } catch {
+          // a host that cannot answer: once per session, as before
+        }
+        if (!has) await $.fs.write(`${dir}/.gitignore`, '*\n')
+        f.ignored = true
+      }
+      const n = f.newest
+      if (n) await $.fs.write(`${dir}/${n.name}`, n.text())
+    } while (f.owed)
+  } finally {
+    f.writing = false
+  }
+}
+
+/** Each part's piece of the status line; undefined until that part has a reading. */
+type Parts = { usage?: string; turns?: string; spend?: string }
+
+/** The one status line: the pieces that have a reading, spend | usage | turns (spend first: a narrow window cuts the end). */
+function showStatus($: EngineInterface, parts: Parts) {
+  const line = [parts.spend, parts.usage, parts.turns].filter(Boolean).join(' | ')
+  try {
+    $.ui.status(line || undefined)
+  } catch {
+    // a surface with no status line; the files still get written
+  }
+}
+
+export const register: Register = (on, options) => {
+  const usageOn = options.usageFile !== false
+  const turnsOn = options.turnTally !== false
+  const spendDir = String(options.dir || '.subagent-spend')
+  const usageDir = String(options.usageFileDir || '.usage-file')
+  const turnsDir = String(options.turnTallyDir || '.turn-tally')
+  // Only a folder of the mod's own name is its own; any other may hold the user's files (even be the
+  // project itself, `.`), so no .gitignore is written there.
+  const own = (dir: string, name: string) => dir.replace(/[\\/]+$/, '').split(/[\\/]/).at(-1) === name
+  const files = { spend: out(own(spendDir, '.subagent-spend')), usage: out(own(usageDir, '.usage-file')), turns: out(own(turnsDir, '.turn-tally')) }
+  const parts: Parts = {}
+  let spendWarned = false
+  // Numbers each measurement in the order the engine raised them; latest.json is written from the newest.
+  let seq = 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' })
+      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
+    }
+    return next(e)
+  })
+
+  on('command.run', { command: 'subagent-spend' }, async $ => {
+    await $.ui.open({ id: SPEND_PANE, title: SPEND_TITLE })
+    return { text: `Subagent spend pane opened. ${spendStatus()}` }
+  })
+
+  on('command.run', { command: 'usage-file' }, async ($, e, next) => {
+    if (!usageOn) return next(e)
+    await $.ui.open({ id: USAGE_PANE, title: USAGE_TITLE })
+    const s = await read($, shownUsage)
+    return { text: `Usage pane opened. ${s ? shownStatus(s) : 'No measurement yet in this session.'}` }
+  })
+
+  on('ui.render', { component: 'Pane', requestId: SPEND_PANE }, async ($, e) => {
+    const { Box, Text } = $.ui.resolve(e)
+    const list = await read($, shownRows)
+    const room = Math.max(1, (e.viewport?.rows ?? 24) - 4)
+    let tok = 0
+    for (const r of list) tok += r.total
+    return (
+      <Box flexDirection="column">
+        <Text bold>
+          {count(list.length, 'subagent')}, {fmt(tok)} tokens
+        </Text>
+        {list.length === 0 && <Text dimColor>No subagent has run in this session yet.</Text>}
+        {paneLines(list)
+          .slice(0, room)
+          .map(line => (
+            <Text>{line}</Text>
+          ))}
+      </Box>
+    )
+  })
+
+  on('ui.render', { component: 'Pane', requestId: USAGE_PANE }, async ($, e, next) => {
+    if (!usageOn) return next(e)
+    const { Box, Text } = $.ui.resolve(e)
+    const s = await read($, shownUsage)
+    if (!s) {
+      return (
+        <Box flexDirection="column">
+          <Text dimColor>No measurement yet in this session.</Text>
+        </Box>
+      )
+    }
+    const now = new Date()
+    return (
+      <Box flexDirection="column">
+        {s.windows.length === 0 && <Text dimColor>No rate-limit windows (not on a subscription).</Text>}
+        {usageLines(s, now).map((line, i) => (
+          <Text color={s.windows[i]!.percentUsed >= OPEN_AT ? 'red' : undefined}>{line}</Text>
+        ))}
+        {s.context !== null && <Text>{`Context     ${bar(s.context)}  ${s.context}%`}</Text>}
+        {s.usd !== null && <Text>{`Cost        $${s.usd.toFixed(2)}`}</Text>}
+        <Text dimColor>{`measured ${s.at.slice(11, 19)} UTC`}</Text>
+      </Box>
+    )
+  })
+
+  on('agent.spawn', async ($, e, next) => {
+    const started = await next(e)
+    if (started.agentId) types.set(started.agentId, e.subagentType)
+    await sessionNow($)
+    if (!spendOpened) {
+      spendOpened = true
+      // a surface that seats no panes refuses; the status line and rows file go on
+      $.ui.open({ id: SPEND_PANE, title: SPEND_TITLE }).catch(() => undefined)
+    }
+    return started
+  }).catch(($, e, next) => next(e)) // an observer: whatever breaks here, the spawn goes on
+
+  on('tool.call', async ($, e, next) => {
+    const ran = await next(e)
+    if (turnsOn) countCall(e.agentId, ran.deny !== undefined, ran.isError === true)
+    return ran
+  })
+
+  on('session.end', async ($, e, next) => {
+    startOver(e.sessionId)
+    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
+    showStatus($, parts)
+    try {
+      await update($, shownRows, () => [])
+      await update($, shownUsage, () => null)
+    } catch {
+      // the panes miss one redraw; the next step or measurement draws them
+    }
+    return next(e)
+  })
+
+  on('session.measure', async ($, e, next) => {
+    if (!usageOn) return next(e)
+    const mine = ++seq
+    parts.usage = usageStatus(e)
+    showStatus($, parts)
+    try {
+      // a newer measurement already shown keeps the pane; this one's figures are behind it
+      await update($, shownUsage, s => (mine !== seq ? s : shownOf(e, new Date())))
+    } catch {
+      // the pane misses one redraw; the file is the record
+    }
+    if (!usageOpened && e.rateLimits.some(w => w.percentUsed >= OPEN_AT)) {
+      usageOpened = true
+      // a surface that seats no panes refuses; the status line and file go on
+      $.ui.open({ id: USAGE_PANE, title: USAGE_TITLE }).catch(() => undefined)
+    }
+    try {
+      let session = ''
+      try {
+        session = await $.session.id()
+      } catch {
+        // no session id on this host: the file says null
+      }
+      // a newer measurement already came while this one waited; its figures are the ones to write
+      if (mine === seq) files.usage.newest = { name: 'latest.json', text: () => fileText(e, session, new Date()) }
+      await writeLatest($, usageDir, files.usage)
+    } catch {
+      // unwritable folder: the file is advisory, the session goes on
+    }
+    return next(e)
+  })
+
+  on('turn.step', async function* ($, e, next) {
+    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
+      // older step can never land on top of a newer one.
+      tally.steps++
+      const now = new Date()
+      parts.turns = turnsStatus()
+      showStatus($, parts)
+      files.turns.newest = { name: `${localDay(now)}.txt`, text: () => tallyText(e.model, e.messageCount, now) }
+      try {
+        await writeLatest($, turnsDir, files.turns)
+      } catch {
+        // unwritable folder: the tally is advisory, the session goes on
+      }
+      return yield* next(e)
+    }
+    const response = yield* next(e)
+    if (!response.usage) return response
+    const agentId = e.agentId
+    const order = nextStep()
+    const sessionId = await sessionNow($)
+    // a step whose id came back after its session ended: its rows file is closed
+    if (sessionId === null) return response
+    addStep(agentId, sessionId, response.usage, e.model, new Date(), order)
+    try {
+      await update($, shownRows, () => [...rows.values()])
+    } catch {
+      // the pane misses one redraw; the rows file is the record
+    }
+    parts.spend = spendStatus()
+    showStatus($, parts)
+    try {
+      // the text is taken now, not at the write: a /clear while a write waits empties the Map it reads
+      const text = rowsText()
+      files.spend.newest = { name: `${sessionId || 'no-session'}.jsonl`, text: () => text }
+      await writeLatest($, spendDir, files.spend)
+    } catch (err) {
+      // unwritable folder: say so once, then the session goes on
+      if (!spendWarned) {
+        spendWarned = true
+        try {
+          $.ui.status(`subagent-spend: rows file not written (${err instanceof Error ? err.message : String(err)})`)
+        } catch {
+          // nothing left to tell it on
+        }
+      }
+    }
+    return response
+  })
+}

package/hooks/spend.ts

@@ -0,0 +1,101 @@
+import type { Row } from '../types'
+
+// The per-subagent sums: what each subagent of the session cost, as the API counts it.
+// Keyed by the exact agent id the engine hands over; two ids that share a prefix or a
+// suffix stay two rows, and a type is carried only from a spawn with that exact id.
+// Sums live in module variables, so a hot reload starts them over; the row's `ts`
+// says when it was last written.
+
+export const rows = new Map<string, Row>()
+export const types = new Map<string, string>()
+/** The order number of the step that last set each row's context, ts and model. */
+export const latest = new Map<string, number>()
+let stepCount = 0
+/** Takes a step's order number when its response arrives, before any wait. */
+export const nextStep = () => ++stepCount
+
+const pad = (n: number) => String(n).padStart(2, '0')
+
+/** Local time with offset, the shape the command hook writes (`2026-10-27T16:40:02-04:00`). */
+export const localIso = (d: Date) => {
+  const off = -d.getTimezoneOffset()
+  const sign = off >= 0 ? '+' : '-'
+  const abs = Math.abs(off)
+  return (
+    `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}` +
+    `T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}` +
+    `${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`
+  )
+}
+
+export const fmt = (n: number) => (n >= 10000 ? `${Math.round(n / 1000)}k` : String(n))
+
+/** The four counts of one step's usage, as the engine hands them over. */
+export type StepUsage = {
+  input_tokens: number
+  output_tokens: number
+  cache_read_input_tokens: number
+  cache_creation_input_tokens: number
+  model?: string
+}
+
+/** Adds one step to the agent's row. Reads the prior row at the moment it adds, never before a wait. A step
+ * that lands after a newer one of the same agent adds its tokens but keeps the newer context, ts and model. */
+export const addStep = (agentId: string, sessionId: string, u: StepUsage, model: string, now: Date, order = nextStep()): Row => {
+  const prior = rows.get(agentId)
+  const older = prior !== undefined && (latest.get(agentId) ?? 0) > order
+  const row: Row = {
+    ts: older ? prior.ts : localIso(now),
+    session_id: sessionId,
+    agent_id: agentId,
+    agent_type: types.get(agentId) ?? prior?.agent_type ?? '',
+    input: (prior?.input ?? 0) + u.input_tokens,
+    output: (prior?.output ?? 0) + u.output_tokens,
+    cache_read: (prior?.cache_read ?? 0) + u.cache_read_input_tokens,
+    cache_create: (prior?.cache_create ?? 0) + u.cache_creation_input_tokens,
+    turns: (prior?.turns ?? 0) + 1,
+    total: 0,
+    context: older ? prior.context : u.input_tokens + u.cache_read_input_tokens + u.cache_creation_input_tokens + u.output_tokens,
+    model: older ? prior.model : u.model || prior?.model || model,
+  }
+  if (!older) latest.set(agentId, order)
+  row.total = row.input + row.output + row.cache_read + row.cache_create
+  rows.set(agentId, row)
+  return row
+}
+
+/** The rows file's whole text: one row per agent, one JSON object per line. */
+export const rowsText = () =>
+  [...rows.values()].map(r => JSON.stringify(r)).join('\n') + (rows.size ? '\n' : '')
+
+/** The status line part: `subagents 2 | tok 7340 (out 120)`. */
+export const spendStatus = () => {
+  let tok = 0
+  let out = 0
+  for (const r of rows.values()) {
+    tok += r.total
+    out += r.output
+  }
+  return `subagents ${rows.size} | tok ${fmt(tok)} (out ${fmt(out)})`
+}
+
+/** The shortest start of `id`, six characters or more, that no other listed id starts with; the whole id
+ * when none is (one id is the start of another). Two agents never share a label. */
+export const label = (id: string, all: readonly string[]) => {
+  for (let n = Math.min(6, id.length); n < id.length; n++) {
+    const head = id.slice(0, n)
+    if (!all.some(o => o !== id && o.startsWith(head))) return head
+  }
+  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)}  ${count(r.turns, 'turn')}  ${fmt(r.total)} (out ${fmt(r.output)}, ctx ${fmt(r.context ?? 0)})  ${r.model}`)
+}

package/hooks/turns.ts

@@ -0,0 +1,45 @@
+// The turns part (option `turnTally`): the main conversation's model steps, tool calls,
+// tool errors and error streak. This file holds the counts and the text; register.tsx
+// holds the hooks. The day file's format is the one turn-tally 0.4.0 wrote, line for line.
+//
+// Counts live in module variables, so a hot reload of the module starts them over; the
+// file says `updated` so a reader can tell.
+
+export const tally = { steps: 0, toolCalls: 0, toolErrors: 0, streak: 0, longestStreak: 0, subagentToolCalls: 0 }
+
+const pad = (n: number) => String(n).padStart(2, '0')
+
+export const localDay = (d: Date) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
+
+const localTime = (d: Date) => `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`
+
+/** Counts one finished tool call. A subagent's call is counted apart. A denied call never ran, so it is
+ * not a tool error; an errored result is. */
+export const countCall = (agentId: string | undefined, denied: boolean, isError: boolean) => {
+  if (agentId) {
+    tally.subagentToolCalls++
+    return
+  }
+  tally.toolCalls++
+  if (!denied && isError) {
+    tally.toolErrors++
+    tally.streak++
+    if (tally.streak > tally.longestStreak) tally.longestStreak = tally.streak
+  } else {
+    tally.streak = 0
+  }
+}
+
+/** The day file's whole text: one fact per line, rewritten whole every step. */
+export const tallyText = (model: string, messageCount: number, now: Date) =>
+  [
+    `steps ${tally.steps}`,
+    `tool calls ${tally.toolCalls} (${tally.subagentToolCalls} by subagents)`,
+    `tool errors ${tally.toolErrors}, current streak ${tally.streak}, longest streak ${tally.longestStreak}`,
+    `model ${model}, messages ${messageCount}`,
+    `updated ${localDay(now)} ${localTime(now)}`,
+    '',
+  ].join('\n')
+
+/** The status line part: `steps 12 | tools 11 | errors 1 (streak 0)`. */
+export const turnsStatus = () => `steps ${tally.steps} | tools ${tally.toolCalls} | errors ${tally.toolErrors} (streak ${tally.streak})`

package/hooks/usage.ts

@@ -0,0 +1,86 @@
+import type { SessionMeasureInput } from 'claude-code'
+
+import type { Shown } from '../types'
+
+// The usage part (option `usageFile`): the session's rate-limit windows, context fill and
+// cost, as the engine's `session.measure` event carries them. This file holds the text;
+// register.tsx holds the hooks. The file format is the one usage-file 0.4.1 wrote, field
+// for field, so a reader of `.usage-file/latest.json` keeps working.
+
+const LABEL: Record<string, string> = { five_hour: '5h', seven_day: '7d', spend_limit: 'spend' }
+const NAME: Record<string, string> = { five_hour: '5-hour', seven_day: 'Weekly', spend_limit: 'Spend limit' }
+
+/** The usage pane opens itself once, the first time any window reaches this percent. */
+export const OPEN_AT = 80
+
+/** A ten-cell bar: `██████░░░░` for 60. */
+export const bar = (pct: number) => {
+  const full = Math.max(0, Math.min(10, Math.round(pct / 10)))
+  return '█'.repeat(full) + '░'.repeat(10 - full)
+}
+
+/** Time left to a reset: `2h 05m`, `3d 4h`, `now`; empty when the engine gave no reset time. */
+export const untilText = (resetsAt: string | null, now: Date) => {
+  if (!resetsAt) return ''
+  const ms = Date.parse(resetsAt) - now.getTime()
+  if (Number.isNaN(ms)) return ''
+  if (ms <= 0) return 'now'
+  const min = Math.floor(ms / 60000)
+  if (min >= 2880) return `${Math.floor(min / 1440)}d ${Math.floor((min % 1440) / 60)}h`
+  return `${Math.floor(min / 60)}h ${String(min % 60).padStart(2, '0')}m`
+}
+
+/** One pane line per window: `5-hour   ██░░░░░░░░  23.5%  resets in 2h 05m`. */
+export const usageLines = (s: Shown, now: Date) =>
+  s.windows.map(w => {
+    const left = untilText(w.resetsAt, now)
+    return `${(NAME[w.kind] ?? w.kind).padEnd(11)} ${bar(w.percentUsed)}  ${w.percentUsed}%${left ? `  resets in ${left}` : ''}`
+  })
+
+/** latest.json's whole text: one JSON object, rewritten whole on every measurement. */
+export const fileText = (e: SessionMeasureInput, session: string, now: Date) =>
+  JSON.stringify(
+    {
+      at: now.toISOString(),
+      session: session || null,
+      changed: e.changed,
+      context: {
+        tokens: e.context.tokens ?? null,
+        window: e.context.window,
+        percent: e.context.percent ?? null,
+      },
+      rateLimits: e.rateLimits.map(w => ({
+        kind: w.kind,
+        percentUsed: w.percentUsed,
+        resetsAt: w.resetsAt ?? null,
+      })),
+      cost: e.cost ? { usd: e.cost.usd } : null,
+    },
+    null,
+    2,
+  ) + '\n'
+
+/** The status line part: only the figures that have a reading; undefined when none has. */
+export const usageStatus = (e: SessionMeasureInput) => {
+  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)}`)
+  return parts.length ? parts.join(' | ') : undefined
+}
+
+/** The usage part again, from what the pane holds (for the command's answer). */
+export const shownStatus = (s: Shown) =>
+  usageStatus({
+    rateLimits: s.windows.map(w => ({ kind: w.kind, percentUsed: w.percentUsed })),
+    context: { window: 0, percent: s.context ?? undefined },
+    cost: s.usd === null ? undefined : { usd: s.usd },
+    changed: [],
+  } as SessionMeasureInput) ?? 'No figures yet.'
+
+/** What the usage pane stores from one measurement. */
+export const shownOf = (e: SessionMeasureInput, now: Date): Shown => ({
+  at: now.toISOString(),
+  windows: e.rateLimits.map(w => ({ kind: w.kind, percentUsed: w.percentUsed, resetsAt: w.resetsAt ?? null })),
+  context: e.context.percent ?? null,
+  usd: e.cost ? e.cost.usd : null,
+})

package/kit/settings-snippet.json

@@ -0,0 +1,8 @@
+{
+  "hooks": {
+    "SubagentStop": [
+      { "hooks": [ { "type": "command", "command": "python3 -I /path/to/subagent_spend.py hook" } ] }
+    ]
+  },
+  "statusLine": { "type": "command", "command": "python3 -I /path/to/subagent_spend.py statusline" }
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@nightlab-agent/subagent-spend",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.3",
+  "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.",
+  "keywords": [
+    "claude-code",
+    "claude-code-mod",
+    "claude-code-plugin",
+    "subagents",
+    "token-usage",
+    "rate-limits",
+    "statusline"
+  ],
+  "homepage": "https://github.com/nightlab-agent/subagent-spend#readme",
+  "bugs": "https://github.com/nightlab-agent/subagent-spend/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nightlab-agent/subagent-spend"
+  },
+  "license": "MIT",
+  "author": "Nightlab",
+  "files": [
+    ".claude-plugin/",
+    "hooks/hooks.json",
+    "hooks/register.tsx",
+    "hooks/spend.ts",
+    "hooks/turns.ts",
+    "hooks/usage.ts",
+    "types/",
+    "kit/",
+    "subagent_spend.py",
+    "CHANGELOG.md"
+  ]
+}