kira-glasses-bridge 2.31.0 → 2.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-glasses-bridge",
-  "version": "2.31.0",
+  "version": "2.34.0",
   "description": "Connects your Mac to Kira, the assistant for Even G2 glasses: Claude Code sessions, files, folders and apps, by voice.",
   "type": "module",
   "bin": {

package/src/agents/agent-usage.mjs

@@ -0,0 +1,87 @@
+// A run's usage, whichever agent it is: how full its thread's context is ({ used, window }) and the
+// person's plan limits (AgentLimits, packages/genui/src/wire/agentUsage.ts), as the protocol's `usage`
+// event, and the words a run fails with when a limit stops it: which limit, and when it resets (and that
+// window, as the run's stats.limitHit, for the card that offers the other agent). Each
+// agent reads its own reports into these shapes (claude-usage.mjs, codex-usage.mjs).
+
+/** A window's name: "5-hour", "weekly", "weekly Opus". */
+function windowName({ minutes, model }) {
+  const length = lengthName(minutes)
+  return model ? `${length} ${model}` : length
+}
+
+function lengthName(minutes) {
+  if (minutes === 7 * 24 * 60) return 'weekly'
+  if (minutes && minutes < 24 * 60) return `${Math.round(minutes / 60)}-hour`
+  return minutes ? `${Math.round(minutes / (24 * 60))}-day` : 'usage'
+}
+
+/** Every window the limits have: the plan's two, then each model's own. */
+const windowsOf = limits => [limits?.primary, limits?.secondary, ...(limits?.models ?? [])].filter(Boolean)
+
+/** The fullest window, the one that most likely stopped a run. */
+export const fullestOf = limits => windowsOf(limits).sort((a, b) => b.usedPercent - a.usedPercent)[0] ?? null
+
+/** "at 3:10 PM" today, "on Tue at 9:05 AM" otherwise, in this Mac's own way of saying times. */
+function resetWords(resetsAt, now) {
+  const at = new Date(resetsAt * 1000)
+  const time = at.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })
+  if (at.toDateString() === new Date(now).toDateString()) return `at ${time}`
+  return `on ${at.toLocaleDateString([], { weekday: 'short', month: 'short', day: 'numeric' })} at ${time}`
+}
+
+/**
+ * Which limit is used up and when it resets: "your 5-hour ChatGPT limit is used up (100%). It resets
+ * at 3:10 PM." (`plan` names whose: "ChatGPT", "Claude"; a model's own window names the model instead.)
+ */
+export function usedUpWords(window, plan, now = Date.now()) {
+  const when = window.resetsAt ? resetWords(window.resetsAt, now) : 'later'
+  const whose = window.model ? windowName(window) : `${windowName(window)} ${plan}`
+  return `your ${whose} limit is used up (${Math.round(window.usedPercent)}%). It resets ${when}.`
+}
+
+const pctOf = c => (c ? Math.round((c.used / c.window) * 100) : null)
+
+/**
+ * A run's usage feed: given the context and limits as they change, it emits a `usage` event with the
+ * latest of both, only when what a person sees changes (a whole percent of context, a limit), not on
+ * every token count.
+ */
+export function usageFeed(emit) {
+  let context = null
+  let limits = null
+  let limitHit = null
+  let sent = ''
+  const send = () => {
+    if (!context && !limits) return
+    const key = JSON.stringify([pctOf(context), limits])
+    if (key === sent) return
+    sent = key
+    emit({ kind: 'usage', context, limits })
+  }
+  return {
+    /** The context now (null: not known, the last one stands). */
+    context(next) {
+      context = next ?? context
+      send()
+    },
+    /** The limits now, whole (null: not known, the last ones stand). */
+    limits(next) {
+      limits = next ?? limits
+      if (limits) send()
+    },
+    /** The limits known so far, to merge an update over and for the words a run fails with. */
+    get known() {
+      return limits
+    },
+    /** A run stopped ({ error, hit } from an agent's stoppedBy): keeps the window that stopped it. */
+    stopped({ error, hit }) {
+      limitHit = hit ?? limitHit
+      return error
+    },
+    /** What the run ends with, for its stats: `limitHit` is the window that stopped it, if one did. */
+    get stats() {
+      return { ...(context ? { context } : {}), ...(limits ? { limits } : {}), ...(limitHit ? { limitHit } : {}) }
+    },
+  }
+}

package/src/agents/claude-calls.mjs

@@ -58,6 +58,7 @@ export function describeAction(name, input, cwd) {
       return act('fetch', 'Fetch', short(i.url, 200))
     case 'WebSearch':
       return act('fetch', 'Search the web', short(i.query, 160))
+    case 'Agent':
     case 'Task':
       return act('delegate', 'Subtask', short(i.description ?? i.prompt, 160))
     case 'TodoWrite':

package/src/agents/claude-local.mjs

@@ -1,7 +1,11 @@
-// Claude Code on this Mac, as the person signed in to it: which account it uses, the permission
-// rules in their own settings, and one piece of text written with that sign-in (complete.mjs).
+// Claude Code on this Mac, as the person signed in to it: which account it uses, its plan's usage
+// limits, the permission rules in their own settings, and one piece of text written with that sign-in
+// (complete.mjs).
 import { execFile } from 'node:child_process'
 import { readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { query } from '@anthropic-ai/claude-agent-sdk'
+import { limitsFromUsage } from './claude-usage.mjs'
 import { FOLDERS } from '../config-folders.mjs'
 import { completeText } from './complete.mjs'
 
@@ -28,6 +32,43 @@ async function claudeAccount() {
   )
 }
 
+/**
+ * The person's plan limits as a Claude Code session reads them: the data behind its /usage (the SDK's
+ * experimental structured answer; an older SDK or CLI without it gives none). No model call.
+ */
+export async function planLimits(q) {
+  const ask = q.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET
+  if (typeof ask !== 'function') return null
+  return limitsFromUsage(await ask.call(q, { skipBehaviors: true }).catch(() => null))
+}
+
+const LIMITS_MS = 15_000
+
+/**
+ * Their plan limits outside a run, for the composer: a session opened only to ask (its prompt never
+ * comes, so nothing is sent to a model), closed once it has answered.
+ */
+async function claudeLimits() {
+  let release
+  const never = (async function* () {
+    await new Promise(resolve => (release = resolve))
+  })()
+  const abortController = new AbortController()
+  const timer = setTimeout(() => abortController.abort(), LIMITS_MS)
+  const env = { ...process.env, ENABLE_CLAUDEAI_MCP_SERVERS: 'false' }
+  const bin = process.env.KIRA_CLAUDE_BIN ? { pathToClaudeCodeExecutable: process.env.KIRA_CLAUDE_BIN } : {}
+  // None of their settings or MCP servers: it only asks (a second, not three).
+  const quiet = { settingSources: [], strictMcpConfig: true }
+  const q = query({ prompt: never, options: { cwd: homedir(), env, abortController, ...quiet, ...bin } })
+  try {
+    return { limits: await planLimits(q) }
+  } finally {
+    clearTimeout(timer)
+    release?.()
+    q.close()
+  }
+}
+
 /** The permissions block of a Claude Code settings file, as written there (nothing when it has none). */
 export function permissionsIn(settings) {
   const p = settings?.permissions ?? {}
@@ -48,6 +89,7 @@ async function claudePermissions() {
 
 export const claudeTools = {
   claude_account: claudeAccount,
+  claude_limits: claudeLimits,
   claude_permissions: claudePermissions,
   complete_text: completeText,
 }

package/src/agents/claude-usage.mjs

@@ -0,0 +1,116 @@
+// How full a Claude Code session is and how much of the person's Claude plan is left, from the Agent
+// SDK: `getContextUsage()` (the context, as /context counts it), the structured /usage answer (the
+// plan, its 5-hour and weekly windows, each model's own weekly window, extra usage) and
+// `rate_limit_event` messages as a run goes. Read into the shapes every agent sends (agent-usage.mjs),
+// and the words a run fails with when a limit stops it. Pure.
+import { fullestOf, usedUpWords } from './agent-usage.mjs'
+
+const FIVE_HOURS = 300
+const WEEK = 7 * 24 * 60
+
+/** The context the session fills: its tokens out of the window Claude Code measures against. */
+export function contextFrom(usage) {
+  const window = usage?.rawMaxTokens || usage?.maxTokens
+  return window > 0 && typeof usage.totalTokens === 'number' ? { used: usage.totalTokens, window } : null
+}
+
+/** A /usage window ({ utilization: 0-100, resets_at: ISO }) as Kira sends it. */
+function windowOf(w, minutes, model = null) {
+  if (typeof w?.utilization !== 'number') return null
+  const at = w.resets_at ? Date.parse(w.resets_at) : NaN
+  const resetsAt = Number.isNaN(at) ? null : Math.round(at / 1000)
+  return { usedPercent: w.utilization, resetsAt, minutes, ...(model ? { model } : {}) }
+}
+
+/** Each model's own weekly window: the server's list, else the older Opus and Sonnet fields. */
+function modelWindows(r) {
+  const listed = Array.isArray(r.model_scoped) ? r.model_scoped : null
+  const named = listed
+    ? listed.map(w => windowOf(w, WEEK, w.display_name || 'Model'))
+    : [windowOf(r.seven_day_opus, WEEK, 'Opus'), windowOf(r.seven_day_sonnet, WEEK, 'Sonnet')]
+  return named.filter(Boolean)
+}
+
+/** Extra usage, from minor units (cents) to the currency's own. */
+function extraOf(x) {
+  if (!x) return null
+  const unit = 10 ** (Number.isInteger(x.decimal_places) ? x.decimal_places : 2)
+  const major = n => (typeof n === 'number' ? n / unit : null)
+  const currency = x.currency ?? null
+  return { enabled: !!x.is_enabled, used: major(x.used_credits), limit: major(x.monthly_limit), currency }
+}
+
+/** The /usage answer (`usage_EXPERIMENTAL…()`) as Kira's limits; null when no plan limits apply (an API key). */
+export function limitsFromUsage(answer) {
+  const r = answer?.rate_limits
+  if (!answer?.rate_limits_available || !r) return null
+  return {
+    account: 'claude',
+    primary: windowOf(r.five_hour, FIVE_HOURS),
+    secondary: windowOf(r.seven_day, WEEK),
+    models: modelWindows(r),
+    credits: null,
+    extra: extraOf(r.extra_usage),
+    plan: answer.subscription_type ?? null,
+  }
+}
+
+/** Where each `rateLimitType` of an event goes in Kira's limits. */
+const SLOTS = {
+  five_hour: { slot: 'primary', minutes: FIVE_HOURS },
+  seven_day: { slot: 'secondary', minutes: WEEK },
+  seven_day_opus: { slot: 'models', minutes: WEEK, model: 'Opus' },
+  seven_day_sonnet: { slot: 'models', minutes: WEEK, model: 'Sonnet' },
+}
+
+const EMPTY = { account: 'claude', primary: null, secondary: null, models: [], credits: null, extra: null, plan: null }
+
+/** One window of an event (utilization 0-1, resetsAt in seconds) set into the limits. */
+function setWindow(limits, type, { utilization, resetsAt, rejected }) {
+  const at = SLOTS[type]
+  if (!at) return limits
+  const prev = at.slot === 'models' ? limits.models.find(w => w.model === at.model) : limits[at.slot]
+  const said = typeof utilization === 'number' ? Math.round(utilization * 100) : rejected ? 100 : null
+  // An event's fraction is coarser than /usage's percent: within a point of the same window, what's known stands.
+  const same = prev && (resetsAt ?? prev.resetsAt) === prev.resetsAt
+  const usedPercent = said === null || (same && Math.abs(said - prev.usedPercent) <= 1) ? prev?.usedPercent : said
+  if (typeof usedPercent !== 'number') return limits
+  const window = { usedPercent, resetsAt: resetsAt ?? prev?.resetsAt ?? null, minutes: at.minutes }
+  if (at.slot !== 'models') return { ...limits, [at.slot]: window }
+  return { ...limits, models: [...limits.models.filter(w => w.model !== at.model), { ...window, model: at.model }] }
+}
+
+/**
+ * A `rate_limit_event` merged over what was known: the windows it carries (its `unifiedWindows` when
+ * the CLI sends them, and the one its `rateLimitType` names), the rest as they were.
+ */
+export function limitsFromEvent(info, prev = null) {
+  if (!info) return prev
+  let limits = { ...EMPTY, ...prev, models: prev?.models ?? [] }
+  for (const [type, w] of Object.entries(info.unifiedWindows ?? {})) limits = setWindow(limits, type, w ?? {})
+  if (info.rateLimitType) {
+    const rejected = info.status === 'rejected'
+    limits = setWindow(limits, info.rateLimitType, { ...info, rejected })
+  }
+  return limits
+}
+
+/** The window an event says is used up, to name it when the run stops. */
+export function rejectedWindow(info, limits) {
+  if (info?.status !== 'rejected' || !SLOTS[info.rateLimitType]) return null
+  const at = SLOTS[info.rateLimitType]
+  return at.slot === 'models' ? limits?.models?.find(w => w.model === at.model) : limits?.[at.slot]
+}
+
+/**
+ * What a run says when it ends on an error (`error`): for a usage limit (Claude Code's words start with
+ * one of `limitPrefixes`), which one and when it resets; else Claude Code's own words. `hit`: the
+ * window that stopped it, when a limit did and it's known.
+ */
+export function stoppedBy(said, { limits, rejected, limitPrefixes = [] }, now = Date.now()) {
+  const text = String(said ?? 'error').trim()
+  if (!limitPrefixes.some(p => text.startsWith(p))) return { error: `Claude stopped: ${text.slice(0, 300)}`, hit: null }
+  const full = rejected ?? fullestOf(limits)
+  if (!full) return { error: `Claude stopped: ${text}`, hit: null }
+  return { error: `Claude stopped: ${usedUpWords(full, 'Claude', now)}`, hit: full }
+}

package/src/agents/claude.mjs

@@ -1,6 +1,7 @@
 // Claude Code as an agent, through the Agent SDK. Runs in this process on the
 // user's Mac with their own Claude login; files never leave the machine.
-import { query } from '@anthropic-ai/claude-agent-sdk'
+import { USAGE_LIMIT_ERROR_PREFIXES, query } from '@anthropic-ai/claude-agent-sdk'
+import { usageFeed } from './agent-usage.mjs'
 import {
   NOT_ANOTHER_WAY,
   TEXT_CAP,
@@ -10,8 +11,12 @@ import {
   toRequest,
 } from './claude-calls.mjs'
 import { kiraDecides } from './checks.mjs'
+import { planLimits } from './claude-local.mjs'
+import { contextFrom, limitsFromEvent, rejectedWindow, stoppedBy } from './claude-usage.mjs'
 import { sdkOptionsFor } from './settings.mjs'
 import { kiraPluginOptions } from '../kira-plugin.mjs'
+import { git } from '../git.mjs'
+import { isAgentCall, subagentFeed } from './subagents.mjs'
 
 /** Kira's MCP server as Claude Code connects to it: Streamable HTTP, the token as the bearer. */
 const kiraServer = ({ url, token }) => ({ type: 'http', url, headers: { Authorization: `Bearer ${token}` } })
@@ -42,6 +47,11 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
   let error = null
   /** What Kira's rules said about each tool call, by its id, for the question if Claude Code asks. */
   const verdicts = new Map()
+  /** How full the session is and the person's limits, as they change (claude-usage.mjs). */
+  const usage = usageFeed(e => io.emit(e))
+  /** The limit a rate_limit_event said is used up, and the last turn whose context was read. */
+  let rejected = null
+  let turn = null
 
   /** Refused before it runs: the job shows why, and Claude is told (`told`, when it needs more). */
   const refuse = (tool, reason, told = reason) => {
@@ -92,6 +102,9 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
   const env = { ...process.env, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: '1', ENABLE_CLAUDEAI_MCP_SERVERS: 'false' }
   /** Background tasks the model still managed to start (an older CLI ignoring the flag): tool_use id -> description. */
   const orphans = new Map()
+  /** The agents it starts, each with where it works (subagents.mjs). */
+  const branchOf = async path => (await git(path, ['branch', '--show-current']))?.trim() || null
+  const agents = subagentFeed(e => io.emit(e), branchOf)
 
   try {
     const q = query({
@@ -127,15 +140,34 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
       if (m.type === 'system' && m.subtype === 'init') {
         session = m.session_id ?? session
         io.emit({ kind: 'session', sessionId: session, model: m.model ?? null })
+        // The plan's windows, each model's own and extra usage (events carry only some of them).
+        void planLimits(q).then(limits => usage.limits(limits))
+      } else if (m.type === 'rate_limit_event') {
+        usage.limits(limitsFromEvent(m.rate_limit_info, usage.known))
+        rejected = rejectedWindow(m.rate_limit_info, usage.known) ?? rejected
       } else if (m.type === 'system' && m.subtype === 'task_started') {
         if (m.is_backgrounded && m.tool_use_id) orphans.set(m.tool_use_id, m.description ?? m.subagent_type ?? 'task')
       } else if (m.type === 'system' && m.subtype === 'task_notification') {
         if (m.tool_use_id) orphans.delete(m.tool_use_id)
+        if (m.tool_use_id) agents.ended(m.tool_use_id, m.status, m.summary)
+      } else if (m.type === 'system' && m.subtype === 'task_progress') {
+        if (m.tool_use_id) agents.progress(m.tool_use_id, m.summary)
       } else if (m.type === 'assistant') {
+        // A new turn of the main thread: how full the context is now, as /context counts it (no model call).
+        if (!nested && m.message?.id && m.message.id !== turn) {
+          turn = m.message.id
+          usage.context(contextFrom(await q.getContextUsage({ detail: 'summary' }).catch(() => null)))
+        }
         for (const b of m.message?.content ?? []) {
           // A subagent's narration is for its parent, not the user; its actions still show what is going on while the Subtask runs.
           if (b.type === 'text' && b.text?.trim() && !nested) io.emit({ kind: 'message', text: short(b.text, TEXT_CAP) })
-          else if (b.type === 'tool_use') io.emit({ kind: 'action', id: b.id, tool: b.name, ...describeAction(b.name, b.input, cwd) })
+          else if (b.type === 'tool_use') {
+            // A step inside an agent says whose it is.
+            const whose = nested ? { agent: m.parent_tool_use_id } : {}
+            io.emit({ kind: 'action', id: b.id, tool: b.name, ...describeAction(b.name, b.input, cwd), ...whose })
+            if (isAgentCall(b.name)) agents.called(b.id, b.input, m.parent_tool_use_id)
+            if (nested) agents.touched(m.parent_tool_use_id, b.input)
+          }
         }
       } else if (m.type === 'user') {
         for (const b of m.message?.content ?? []) {
@@ -143,18 +175,24 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
             const t = typeof b.content === 'string' ? b.content : Array.isArray(b.content) ? b.content.map(c => (c.type === 'text' ? c.text : '')).join('\n') : ''
             if (/^Async agent launched successfully/.test(t.trim()) && !orphans.has(b.tool_use_id)) orphans.set(b.tool_use_id, 'subagent')
             io.emit({ kind: 'action_result', id: b.tool_use_id, ok: !b.is_error, preview: short(t.trim(), 240) })
+            if (agents.has(b.tool_use_id)) agents.returned(b.tool_use_id, m.tool_use_result, b.is_error)
           }
         }
       } else if (m.type === 'result') {
         session = m.session_id ?? session
-        if (m.subtype === 'success') text = String(m.result ?? '')
+        agents.stopAll()
+        // A turn that ended on an API error (a usage limit among them) is a success carrying the error.
+        const limit = { limits: usage.known, rejected, limitPrefixes: USAGE_LIMIT_ERROR_PREFIXES }
+        if (m.subtype === 'success' && !m.is_error) text = String(m.result ?? '')
+        else if (m.subtype === 'success') error = usage.stopped(stoppedBy(m.result, limit))
         else error = `Claude stopped: ${m.subtype}${Array.isArray(m.errors) && m.errors.length ? ` (${m.errors.join('; ').slice(0, 300)})` : ''}`
         // Work left running in the background dies with this process; say so rather than let "still running" stand as the outcome.
         if (orphans.size) {
           const note = `${orphans.size} background ${orphans.size === 1 ? 'task was' : 'tasks were'} still running when Claude ended its turn (${[...orphans.values()].slice(0, 5).join(', ')}); they were stopped with the session and their findings are not in this report. Send a follow-up to have that work done inline.`
           text = text ? `${text}\n\n(${note})` : `(${note})`
         }
-        const stats = { durationMs: m.duration_ms, turns: m.num_turns, costUsd: m.total_cost_usd }
+        // How full the session ended and the limits it last saw (claude-usage.mjs), beside the run's own.
+        const stats = { durationMs: m.duration_ms, turns: m.num_turns, costUsd: m.total_cost_usd, ...usage.stats }
         io.emit({ kind: 'result', ok: !error, text: short(text, TEXT_CAP), error, sessionId: session, stats })
         return { ok: !error, text, error, sessionId: session, stats }
       }

package/src/agents/codex-items.mjs

@@ -79,6 +79,8 @@ export function itemAction(item, cwd) {
     case 'plan':
       return act('plan', 'Plan', short(item.text, 160), { tool: 'Plan' })
     case 'collabAgentToolCall':
+      // Spawning one is a step; waiting on or messaging its agents moves the agent's row (codex-subagents.mjs).
+      if (item.tool !== 'spawnAgent') return null
       return act('delegate', 'Subtask', short(item.prompt ?? '', 160), { tool: 'Subtask' })
     case 'enteredReviewMode':
       return act('read', 'Review', short(item.review ?? '', 160), { tool: 'Review' })

package/src/agents/codex-subagents.mjs

@@ -0,0 +1,60 @@
+// The agents Codex spawns inside a turn (its collab tools), as protocol `agent` events, the way
+// subagents.mjs does Claude Code's. A spawn is a collabAgentToolCall naming the new agent's thread;
+// that thread's items then arrive on the same app server, so each one says whose it is (`whose`), and
+// later collab calls and subAgentActivity items say how each agent stands. Codex's agents work in the
+// turn's own folder.
+import { short } from './claude-calls.mjs'
+
+const STATES = {
+  completed: 'done',
+  errored: 'failed',
+  interrupted: 'stopped',
+  shutdown: 'stopped',
+  notFound: 'stopped',
+}
+const ACTIVITY = { completed: 'done', interrupted: 'stopped' }
+
+/** The last part of an agent's path ("/root/explorer" → "explorer"): the name Codex gave it. */
+const nameOf = path => String(path ?? '').split('/').filter(Boolean).pop() || null
+
+export function codexAgentFeed(emit) {
+  const agents = new Map()
+  /** Each agent's thread, to the spawn call that made it. */
+  const threads = new Map()
+  const send = a => {
+    agents.set(a.id, a)
+    emit(a)
+  }
+  const settle = (threadId, status, name) => {
+    const a = agents.get(threads.get(threadId))
+    if (!a) return
+    const named = name && !a.name ? { name } : {}
+    if (status && a.status === 'running') send({ ...a, status, ...named })
+    else if (named.name) send({ ...a, ...named })
+  }
+  return {
+    /** The agent a thread's items belong to, if the thread is one Codex spawned. */
+    whose: threadId => threads.get(threadId) ?? null,
+    started(item) {
+      if (item.type !== 'collabAgentToolCall' || item.tool !== 'spawnAgent') return
+      const description = short(item.prompt ?? '', 200)
+      send({ kind: 'agent', id: item.id, type: 'agent', description, status: 'running' })
+    },
+    completed(item) {
+      if (item.type === 'subAgentActivity') {
+        return settle(item.agentThreadId, ACTIVITY[item.kind], nameOf(item.agentPath))
+      }
+      if (item.type !== 'collabAgentToolCall') return
+      if (item.tool === 'spawnAgent') {
+        for (const t of item.receiverThreadIds ?? []) threads.set(t, item.id)
+        const a = agents.get(item.id)
+        if (a && item.status === 'failed') send({ ...a, status: 'failed' })
+      }
+      for (const [t, state] of Object.entries(item.agentsStates ?? {})) settle(t, STATES[state?.status])
+    },
+    /** The turn ended: what still runs ended with it (`status`: done, or stopped when it was cut short). */
+    endAll(status) {
+      for (const a of agents.values()) if (a.status === 'running') send({ ...a, status })
+    },
+  }
+}

package/src/agents/codex-usage.mjs

@@ -1,7 +1,8 @@
 // How full a Codex thread is and how much of the person's ChatGPT plan is left, from Codex's app
 // server: `thread/tokenUsage/updated` (the context), `account/rateLimits/read` and
 // `account/rateLimits/updated` (the limits). Becomes the protocol's `usage` event, and the words a run
-// fails with when a limit stops it: which limit, and when it resets.
+// fails with when a limit stops it: which limit, and when it resets (agent-usage.mjs).
+import { fullestOf, usageFeed as agentUsageFeed, usedUpWords } from './agent-usage.mjs'
 
 /** A window as Kira sends it: { usedPercent, resetsAt (Unix seconds), minutes }. */
 const windowOf = w =>
@@ -28,6 +29,7 @@ export function limitsOf(snapshot, prev = null) {
   const c = snapshot.credits
   const credits = c ? { has: !!c.hasCredits, unlimited: !!c.unlimited, balance: c.balance ?? null } : null
   return {
+    account: 'chatgpt',
     primary: windowOf(snapshot.primary) ?? prev?.primary ?? null,
     secondary: windowOf(snapshot.secondary) ?? prev?.secondary ?? null,
     credits: credits ?? prev?.credits ?? null,
@@ -35,67 +37,35 @@ export function limitsOf(snapshot, prev = null) {
   }
 }
 
-/** A window's name: "5-hour", "weekly". */
-function windowName(minutes) {
-  if (minutes === 7 * 24 * 60) return 'weekly'
-  if (minutes && minutes < 24 * 60) return `${Math.round(minutes / 60)}-hour`
-  return minutes ? `${Math.round(minutes / (24 * 60))}-day` : 'usage'
-}
-
 const LIMIT_ERRORS = new Set(['usageLimitExceeded', 'rateLimitExceeded'])
 
-/** What a run says when it stops: which limit stopped it and when it resets, else Codex's own words. */
+/**
+ * What a run says when it stops (`error`): which limit stopped it and when it resets, else Codex's own
+ * words; and the window that stopped it (`hit`), when a limit did and it's known.
+ */
 export function stoppedBy(turnError, limits, now = Date.now()) {
   const said = `Codex stopped: ${turnError?.message ?? 'error'}`
-  if (!LIMIT_ERRORS.has(turnError?.codexErrorInfo)) return said
-  const full = [limits?.primary, limits?.secondary].filter(Boolean).sort((a, b) => b.usedPercent - a.usedPercent)[0]
-  if (!full) return `Codex stopped: you've reached your ChatGPT usage limit. ${turnError.message ?? ''}`.trim()
-  const when = full.resetsAt ? resetWords(full.resetsAt, now) : 'later'
-  const name = windowName(full.minutes)
-  return `Codex stopped: your ${name} ChatGPT limit is used up (${full.usedPercent}%). It resets ${when}.`
-}
-
-/** "at 3:10 PM" today, "on Tue at 9:05 AM" otherwise, in this Mac's own way of saying times. */
-function resetWords(resetsAt, now) {
-  const at = new Date(resetsAt * 1000)
-  const time = at.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })
-  if (at.toDateString() === new Date(now).toDateString()) return `at ${time}`
-  return `on ${at.toLocaleDateString([], { weekday: 'short', month: 'short', day: 'numeric' })} at ${time}`
+  if (!LIMIT_ERRORS.has(turnError?.codexErrorInfo)) return { error: said, hit: null }
+  const full = fullestOf(limits)
+  const reached = `Codex stopped: you've reached your ChatGPT usage limit. ${turnError.message ?? ''}`
+  if (!full) return { error: reached.trim(), hit: null }
+  return { error: `Codex stopped: ${usedUpWords(full, 'ChatGPT', now)}`, hit: full }
 }
 
-const pctOf = c => (c ? Math.round((c.used / c.window) * 100) : null)
-
-/**
- * A run's usage: fed Codex's notifications, it emits a `usage` event with the latest of both, only
- * when what a person sees changes (a whole percent of context, a limit), not on every token count.
- */
+/** A run's usage, fed Codex's notifications (agent-usage.mjs sends it). */
 export function usageFeed(emit) {
-  let context = null
-  let limits = null
-  let sent = ''
-  const send = () => {
-    if (!context && !limits) return
-    const key = JSON.stringify([pctOf(context), limits])
-    if (key === sent) return
-    sent = key
-    emit({ kind: 'usage', context, limits })
-  }
+  const feed = agentUsageFeed(emit)
   return {
-    onTokens(tokenUsage) {
-      context = contextOf(tokenUsage) ?? context
-      send()
-    },
-    onLimits(snapshot) {
-      limits = limitsOf(snapshot, limits)
-      if (limits) send()
-    },
+    onTokens: tokenUsage => feed.context(contextOf(tokenUsage)),
+    onLimits: snapshot => feed.limits(limitsOf(snapshot, feed.known)),
     /** The limits known so far, for the words a run fails with. */
     get limits() {
-      return limits
+      return feed.known
     },
+    stopped: feed.stopped,
     /** What the run ends with, for its stats. */
     get stats() {
-      return { ...(context ? { context } : {}), ...(limits ? { limits } : {}) }
+      return feed.stats
     },
   }
 }

package/src/agents/codex.mjs

@@ -9,6 +9,7 @@ import { codexBin, openCodex } from './codex-rpc.mjs'
 import { codexInput } from './codex-input.mjs'
 import { turnSteering } from './codex-steer.mjs'
 import { codexStream } from './codex-live.mjs'
+import { codexAgentFeed } from './codex-subagents.mjs'
 import { liveEmitter } from './live.mjs'
 import { kiraDecides } from './checks.mjs'
 import { CODEX_ASKS, askPerson, refusedByPolicy, said } from './codex-ask.mjs'
@@ -51,6 +52,8 @@ async function run({ prompt, attachments, sessionId, cwd, persona, settings, abo
   /** What is still being written (live.mjs): sent as it comes, the final form of each kept. */
   const live = liveEmitter(io.emit)
   const stream = codexStream()
+  /** The agents it spawns, and which thread is whose (codex-subagents.mjs). */
+  const agents = codexAgentFeed(e => io.emit(e))
   let finished
   const ended = new Promise(resolve => (finished = resolve))
   // What the person says while a turn runs goes into it (`codex` is the app server, opened below).
@@ -86,16 +89,22 @@ async function run({ prompt, attachments, sessionId, cwd, persona, settings, abo
   }
 
   const onNotify = (method, p) => {
+    // An item from a thread Codex spawned is its agent's: its steps say so, and what it says is for Codex.
+    const whose = p?.threadId ? agents.whose(p.threadId) : null
     const update = stream.update(method, p)
-    if (update) return live.update(update)
+    if (update) return whose ? undefined : live.update(update)
     if (method === 'item/started') {
       if (p.item.type === 'fileChange') changes.set(p.item.id, p.item.changes ?? [])
+      agents.started(p.item)
       const action = itemAction(p.item, cwd)
-      if (action) io.emit({ kind: 'action', id: p.item.id, ...action })
+      if (action) io.emit({ kind: 'action', id: p.item.id, ...action, ...(whose ? { agent: whose } : {}) })
     } else if (method === 'item/completed') {
+      agents.completed(p.item)
       const reviewed = review.completed(p.item)
       if (reviewed) io.emit(reviewed)
-      if (p.item.type === 'agentMessage' && p.item.text?.trim()) {
+      if (whose && p.item.type === 'agentMessage') {
+        // Its agent's answer goes to Codex, not the person.
+      } else if (p.item.type === 'agentMessage' && p.item.text?.trim()) {
         text = p.item.text
         if (!review.repeats(text)) live.final({ kind: 'message', id: p.item.id, text: short(p.item.text, TEXT_CAP) })
       } else if (itemAction(p.item, cwd)) {
@@ -111,12 +120,13 @@ async function run({ prompt, attachments, sessionId, cwd, persona, settings, abo
     } else if (method === 'account/rateLimits/updated') {
       usage.onLimits(p.rateLimits)
     } else if (method === 'error' && !p.willRetry) {
-      error = stoppedBy(p.error, usage.limits)
+      error = usage.stopped(stoppedBy(p.error, usage.limits))
     } else if (method === 'turn/completed' && p.turn?.id === turnId) {
       const t = p.turn
       steering.ended()
-      if (t.status === 'failed') error = stoppedBy(t.error ?? { message: 'failed' }, usage.limits)
+      if (t.status === 'failed') error = usage.stopped(stoppedBy(t.error ?? { message: 'failed' }, usage.limits))
       if (t.status === 'interrupted') error = 'Stopped by the user.'
+      agents.endAll(t.status === 'completed' ? 'done' : 'stopped')
       finished({ durationMs: t.durationMs ?? undefined })
     }
   }

package/src/agents/protocol.mjs

@@ -10,13 +10,21 @@
 //   action           { kind, id, type, tool, label, target, note?, detail? }
 //                      type: read | search | edit | write | run | fetch | delegate | plan | other
 //                      detail: { edit: {old,new,all} | edits: [...] | content | command }
+//                      agent: the id of the agent (below) whose step it is, when an agent the turn started took it
 //   action_result    { kind, id, ok, preview? }
+//   agent            { kind, id, type, description, status, name?, isolated?, background?, summary?,
+//                      worktree?: { path, branch? }, stats?: { tools?, ms?, adds?, dels? }, agent? }
+//                      an agent the turn started (Claude Code's Agent tool, Codex's spawnAgent), sent again whole
+//                      each time it changes; status: running | done | failed | stopped; worktree: its own, when it
+//                      has one (subagents.mjs, codex-subagents.mjs)
 //   request          { kind, request: AgentRequest }        needs a person; the job waits
 //   request_resolved { kind, id, answer, by }              by: voice | lens | phone | portal | timeout | policy
-//   usage            { kind, context: {used,window} | null, limits: CodexLimits | null }   Codex: how full its
-//                      thread is and the person's ChatGPT limits ({primary,secondary: {usedPercent,resetsAt,minutes},
-//                      credits, plan}), the latest of both each time one changes (codex-usage.mjs)
-//   result           { kind, ok, text?, error?, sessionId?, stats? }
+//   usage            { kind, context: {used,window} | null, limits: AgentLimits | null }   how full the thread
+//                      is and the person's plan limits ({account, primary, secondary, models: [...], credits,
+//                      extra, plan}; each window {usedPercent,resetsAt,minutes,model?}), the latest of both each
+//                      time one changes (agent-usage.mjs; Claude Code: claude-usage.mjs, Codex: codex-usage.mjs)
+//   result           { kind, ok, text?, error?, sessionId?, stats? }   stats: the agent's own, and its last
+//                      context and limits, and limitHit (the window, as above) when a usage limit stopped it
 //
 // Any event with an id may come first as `transient: true` (live.mjs): what is still being written,
 // sent live as it changes and never stored. The next event with the same id that isn't transient is

package/src/agents/subagents.mjs

@@ -0,0 +1,121 @@
+// The agents Claude Code starts inside a turn (its Agent tool, once called Task), as protocol `agent`
+// events: what kind each is, what it was asked, how it's going, and where it works: the job's folder,
+// or a worktree of its own (`isolation: "worktree"`, under <repo>/.claude/worktrees/<name>). Its own
+// steps carry its id as `agent` (claude.mjs); the worktree shows up in the first path one of them
+// touches, and the finished call names it too. Each change of an agent is the whole event again, so
+// the last one with an id is where it stands.
+import { display } from '../git.mjs'
+
+/** Claude Code's tool for starting an agent, by its current name and its old one. */
+export const isAgentCall = name => name === 'Agent' || name === 'Task'
+
+const WORKTREE = /^(.*\/\.claude\/worktrees\/[^/]+)(?:\/|$)/
+
+/** The agent worktree a path is inside, if any. */
+export function worktreeOf(path) {
+  const m = WORKTREE.exec(String(path ?? ''))
+  return m ? m[1] : null
+}
+
+/** Every absolute path a tool call names, for finding where an agent works. */
+export function pathsIn(input) {
+  const i = input ?? {}
+  const named = [i.file_path, i.notebook_path, i.path].filter(p => typeof p === 'string')
+  const cd = /(?:^|&&|;)\s*cd\s+("[^"]+"|'[^']+'|\S+)/.exec(String(i.command ?? ''))
+  if (cd) named.push(cd[1].replace(/^["']|["']$/g, ''))
+  return named.filter(p => p.startsWith('/'))
+}
+
+/** An Agent call as the agent it starts. */
+export function agentFrom(id, input, parent) {
+  const i = input ?? {}
+  return {
+    kind: 'agent',
+    id,
+    type: String(i.subagent_type || 'general-purpose'),
+    description: String(i.description || i.prompt || '').slice(0, 200),
+    status: 'running',
+    ...(i.name ? { name: String(i.name) } : {}),
+    ...(i.isolation === 'worktree' ? { isolated: true } : {}),
+    ...(parent ? { agent: parent } : {}),
+  }
+}
+
+/** A finished Agent call's result (the SDK's tool_use_result): how it went, where, and what it did. */
+export function finished(agent, result, failed) {
+  const r = result && typeof result === 'object' ? result : {}
+  if (r.status === 'async_launched') return { ...agent, background: true }
+  const s = r.toolStats
+  const stats = {
+    ...(typeof r.totalToolUseCount === 'number' ? { tools: r.totalToolUseCount } : {}),
+    ...(typeof r.totalDurationMs === 'number' ? { ms: r.totalDurationMs } : {}),
+    ...(s ? { adds: s.linesAdded ?? 0, dels: s.linesRemoved ?? 0 } : {}),
+  }
+  // Claude Code removes an agent's worktree when it changed nothing, and then doesn't name it.
+  const removed = r.status === 'completed' && agent.isolated
+  const worktree = r.worktreePath
+    ? { path: display(r.worktreePath), ...(r.worktreeBranch ? { branch: r.worktreeBranch } : {}) }
+    : removed
+      ? null
+      : agent.worktree
+  const { worktree: _, ...rest } = agent
+  return {
+    ...rest,
+    status: failed ? 'failed' : 'done',
+    ...(worktree ? { worktree } : {}),
+    ...(Object.keys(stats).length ? { stats } : {}),
+  }
+}
+
+const ENDED = { completed: 'done', failed: 'failed', stopped: 'stopped' }
+
+/**
+ * A turn's agents as they go. `emit` sends each change; `branchOf(path)` reads a worktree's branch
+ * (git, or a stand-in in tests).
+ */
+export function subagentFeed(emit, branchOf) {
+  const agents = new Map()
+  const send = (a, more = {}) => {
+    agents.set(a.id, a)
+    emit({ ...a, ...more })
+  }
+  return {
+    has: id => agents.has(id),
+    /** The Agent call: it starts. */
+    called(id, input, parent) {
+      send(agentFrom(id, input, parent))
+    },
+    /** One of its own calls: the first path inside a worktree says which one it works in. */
+    touched(id, input) {
+      const a = agents.get(id)
+      if (!a || a.worktree) return
+      const path = pathsIn(input).map(worktreeOf).find(Boolean)
+      if (!path) return
+      send({ ...a, worktree: { path: display(path) } })
+      void Promise.resolve(branchOf(path)).then(branch => {
+        const now = agents.get(id)
+        if (branch && now?.worktree && !now.worktree.branch) send({ ...now, worktree: { ...now.worktree, branch } })
+      })
+    },
+    /** A one-line summary of where it's at, while it works: shown live, never stored. */
+    progress(id, summary) {
+      const a = agents.get(id)
+      if (a && summary) emit({ ...a, summary: String(summary).slice(0, 200), transient: true })
+    },
+    /** Its call's result: done, or still going in the background. */
+    returned(id, result, failed) {
+      const a = agents.get(id)
+      if (a) send(finished(a, result, failed))
+    },
+    /** A background agent ended (task_notification). */
+    ended(id, status, summary) {
+      const a = agents.get(id)
+      if (a?.status !== 'running') return
+      send({ ...a, status: ENDED[status] ?? 'done', ...(summary ? { summary: String(summary).slice(0, 200) } : {}) })
+    },
+    /** The turn ended: whatever still runs stops with it. */
+    stopAll() {
+      for (const a of agents.values()) if (a.status === 'running') send({ ...a, status: 'stopped' })
+    },
+  }
+}