Skip to content

feat: record subagent dispatch and usage from hooks - #538

Closed
juzser wants to merge 4 commits into
mainfrom
feat/subagent-usage-hooks
Closed

juzser wants to merge 4 commits into
mainfrom
feat/subagent-usage-hooks

Conversation

@juzser

@juzser juzser commented Nov 4, 2026

Copy link
Copy Markdown
Owner

Phase 1a, T2 of the lean-mode scope (docs/specs/lean-mode-scope.md §4 and §6a item 2).

Problem

Dispatches and per-role spend are written by hand today, with a dispatch_decision per agent. That bookkeeping is a large part of the orchestrator's 40% share in the 2026-11-03 trial. §4 moves it into hooks.

Change

  • Hooks. SubagentStart and SubagentStop are registered async in .claude/hooks/hooks.json and call subagent-hook.sh, which runs the lean bs-subagent-hook bin. Each hook always exits 0. Async hooks have no enforced timeout, and their systemMessage reaches the model on its next turn; INSTALL.md says so.
  • Events.
    • subagent-started records agent_id and agent_type.
    • subagent-stopped records role, model, input/output/cache tokens, total_tokens (the delta since that agent's previous stop), cumulative_tokens, last_turn_tokens and complete.
    • Both use explicit parents. A start is parented on the latest operator prompt, or on the root. A stop is parented on its start.
  • Which log. Events go to the epic main log, else to <cli>.jsonl. That log is created with the shared auto-root when needed, so the feat: optional --session and --causal-parent with safe defaults #533 guard sees the entry. A stop is written into the log that holds its agent's start.
  • Fold (agents-registry.ts).
    • Starts and stops pair per agent_id by occurrence, in either arrival order.
    • A hook start binds to the oldest unclaimed hand-written dispatch_decision of its role, so /bs run does not double-count.
    • A bound pair stays live until its hook stop. epic-closed ends every entry of the epic.
    • Ids are normalized, so agent- prefixes and transcript basenames both match.
  • Cap warning. It compares the final turn's input + cache creation + cache read + output against the role's budgets.yml task: cap, with the default tier scale applied. Checked against 275 real Agent-tool totals from one session: 82 matched exactly, 225 came within 2%, 1 warning was missed and none were false.
  • Reads and recovery.
  • Not changed. bs budget alarm stays epic- and task-keyed and does not read these events. Feeding it would double-count under /bs run.

Known follow-up

The direct closer can also close a running sibling, the same as hand-appending a stop. That hides the sibling from the #533 guard. It goes into the subagent guard item that is pending with the operator: refuse subagent stop --agent-id and event append of subagent-* when the PreToolUse input carries agent_id.

Review

A fresh-context review ran four rounds, with probes against the branch build:

  • round 1: a resumed agent never closed, one agent was counted twice under /bs run, a sync 5 s timeout lost stops, the stop lookup missed logs, the guard was blind to prompts-<cli>, the cap formula was wrong, and id shapes were unverified;
  • round 2: an async stop arrived before its start, fan-out bound in reverse, and resumes double-counted spend;
  • round 3: a lost-stop bound pair survived epic-closed, a real resume could be dropped, and cross-log resumes double-counted;
  • round 4: mergeable, once the guard item covers the closer.

Verification

  • Full suite under heavy run: 277 files, 10932 passed, 2 skipped.
  • The reviewer's run passed 26 files (674 tests) plus usage.test.ts (301).
  • typecheck, typecheck:test and biome at error level are clean.
  • Not yet exercised: a live Claude Code SubagentStart/SubagentStop payload. That gets verified in a real session after merge.

🤖 Generated with Claude Code

juzser and others added 4 commits November 4, 2026 12:26
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ks async

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@juzser

juzser commented Nov 4, 2026

Copy link
Copy Markdown
Owner Author

Closed without merging: the project is moving to a minimal plugin (operator decision 2026-11-04), which this change no longer serves. The branch is kept for reference.

@juzser juzser closed this Nov 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant