claude.print/codex usage: record token & cost in State and reports

[qinhaihong-red]

Parent

#1

What to build

Carved out of #9 (claude.print adapter) — see the scope decision recorded on that
issue. #9 ships the adapter and normalizes exit_status, stdout, stderr,
structured_output, and artifacts, but deliberately does not plumb the Agent
CLI's reported token/cost usage, because doing so extends the vendor-neutral Adapter
contract (ADR 0006) and the persisted node output shape — a cross-cutting change worth
its own issue.

This issue adds usage as a first-class, vendor-neutral concept:

• Add a neutral usage representation to AgentResult (e.g. input/output tokens and
  a cost figure), populated by each real Adapter from the CLI's own usage report
  (claude -p --output-format json exposes token counts and total_cost_usd;
  codex exec exposes its equivalent).
• Thread usage through NodeResult into State, persisted inside the node's existing
  normalized_output JSON payload (no new State column — avoids a schema migration of
  the kind Resume across schema versions: node.cause column has no migration #76 had to repair).
• Surface usage where run results are shown. The dedicated Reporter is Reporters and caw report in four formats #12; until it
  lands, the existing caw run / caw resume run summary is the surfacing point.
• Update ADR 0006 to record the contract extension (the AgentResult.usage field and the
  rule that usage rides inside the persisted output, not a new column).

Acceptance criteria

• AgentResult carries a vendor-neutral usage value; the claude.print adapter
  populates it from the CLI's JSON usage report
• Usage is persisted in State within the node's normalized output (no new State column)
• Usage is surfaced in the run summary today, and renders in caw report once Reporters and caw report in four formats #12 lands
• ADR 0006 is updated to document the usage contract extension
• codex.exec (codex.exec adapter with symmetric capabilities #11) populates the same usage field symmetrically (or this is tracked
  as codex.exec adapter with symmetric capabilities #11's own symmetry criterion)
• Fixture-based offline tests cover usage normalization; real-CLI tests auto-skip when
  the CLI is absent

Blocked by

• claude.print adapter for claude -p #9

Related

• codex.exec adapter with symmetric capabilities #11 (codex.exec records usage symmetrically)
• Reporters and caw report in four formats #12 (Reporters render usage)
• ADR 0006 (Adapter interface contract)

[qinhaihong-red]

Two scope items folded in from the #9 / PR #80 review

The claude.print review (PR #80) surfaced two concerns that belong here rather than
in #9, because both require parsing the CLI's JSON result wrapper — the same parse this
issue already needs to extract usage/cost:

• Freeform-path is_error detection. claude.print adapter for claude -p #9 normalizes is_error: true to a failed
  node ONLY on the structured path (where the wrapper is parsed). A freeform claude -p
  node (no output_schema) that exits 0 but reports is_error: true (e.g.
  subtype: error_max_turns) is silently reported as SUCCEEDED, while the identical
  node with a schema FAILS. Parsing the wrapper unconditionally (the CLI supports
  --output-format json regardless of schema) closes this asymmetry AND is the same
  parse needed for usage/cost — so it should land together here.
• capability_check version surfacing. claude.print adapter for claude -p #9 added ClaudePrintAdapter.capability_check()
  which probes claude --version, but nothing in the kernel calls it and the version is
  not persisted (deliberately deferred). Recording/surfacing the CLI version belongs with
  this issue's usage/cost surfacing work.

[qinhaihong-red]

Note (from #101): codex.exec shipped without usage plumbing, symmetric with claude.print —
both leave usage and durable version surfacing for this issue. Seams ready to populate both:

• claude -p --output-format json exposes token counts + total_cost_usd; codex exec --json
  emits a turn.completed event carrying usage (input / cached / output / reasoning tokens).
• Both adapters' capability_check() already returns the CLI version string (kept adapter-local
  per their docstrings, which carve version/usage surfacing here).