glossary//agent-hook
agent hook
An agent hook is harness code that fires on a lifecycle event, such as a subagent finishing or a session ending, and runs below the agents where no model can see it or call it.
The model requests a tool and the result returns to its context; nobody requests a hook, an event does, and what it produces usually goes to disk. It is not a webhook either, though the word invites the confusion: the Flask webhook in memory is easy, retrieval is hard receives Telegram messages over an inbound HTTP endpoint, a different mechanism with four letters in common.
The key distinction is against run accounting. Run accounting records what each stage cost, in which model, and with what confidence. A hook writes the lines into that record. Read the accounting page to inspect the file; read this entry to see what produced it.
The hooks that write the ledger
Agent run cost attribution describes two hooks. When a specialist finishes, the harness fires a SubagentStop hook that receives the finished transcript as a file path, deduplicates by message ID, sums usage, and appends one line to the run log keyed by attempt_id. The Conductor's own tokens come from a Stop hook that fires when the main session ends a turn. Neither count is available from above. By the time the total exists, the agent that produced it has exited, and the transcript holding it sits outside what anything in the run can read. The hook runs one layer down, after the fact, on the file.
The same essay shows the failure mode. The hook shipped, passed its whole test suite, and did nothing in production. Nothing above a hook waits for its output, so when it stops working, nothing complains.
Hook code gets audited like any other code
A clean audit run proves nothing treats ownership gaps in hooks as a defect class. One round of fixes gated a single branch of the session-stop handler. A second branch, added later for subagent-spawned work, re-implemented the same concern by hand and never got gated.
What closed it was structure rather than another patch. The run's nonce enters the specialist agent's spawn prompt, so the session-stop hook can verify identity before attributing tokens. No nonce means reject, not accept. All four known token-event emit sites now carry an OWNERSHIP-GATE: marker comment, a CI count-parity lint keeps the markers aligned with the emit sites, and a meta-test drives all three hook emitters with a foreign session and asserts zero attribution.