The end-of-turn token figure, normalised from a session/prompt response
(#827).
Two places a runtime puts it, tried in order:
usage— the (unstable, as of protocol v1)Usageobject:inputTokens,outputTokens,cachedReadTokens,cachedWriteTokens,totalTokens,thoughtTokens. claude-agent-acp ≥ 0.6x fills it with the turn's accumulated API usage (reset when the turn starts) and codex-acp with the thread's last token count;_meta.inputTokens/_meta.outputTokens— where an adapter put it before the field had a name.
The result is one flat, string-keyed map (so it can go straight into a
JSON column): %{"input" => n, "output" => n} plus "cache_read" /
"cache_write" when reported. nil when the response carries neither — a turn without a
usage, not a zero one.
Deliberately not derived from the usage_update notifications that
stream during a turn: those are context-window occupancy (used / size)
and a cumulative session cost, and what they mean per update differs by
runtime. The one figure recorded per turn is the one the runtime reports
when the turn ends.
Summary
Functions
The turn's usage from a session/prompt result, or nil.
Types
@type t() :: %{required(String.t()) => non_neg_integer()}