usage

/audit:usage — where the tokens went

Run

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/usage/audit-usage.py" --format md $ARGUMENTS

Print its stdout verbatim in your own reply — a tool result is collapsed behind the tool call, so running the command is not delivering it. Do NOT re-format, summarize, re-tabulate, or "improve" it. Whether it goes in a code fence depends on the format, and only on that: the default md output is printed unfenced, because it is already markdown (pipe tables, bullets) and a fence would disable the table rendering it exists for; ascii output is printed inside a fenced block, because it is fixed-width text that only lines up in one. The script renders its own final output for a reason: a usage tool that spends a pile of tokens laying out its own tables every time you ask what you spent is self-defeating. Reading the numbers back to the user costs roughly as much as the report describes. Just show it. (A user-supplied --format ascii in the arguments wins over the default above — argparse takes the last occurrence; print that verbatim too, fenced as said above.)

The only thing worth adding is a single line of interpretation when something in the output is genuinely notable — a phase that cost several times its peers, a cache hit rate that collapsed, a model routed somewhere it shouldn't be. Otherwise say nothing.

Read-only: this never takes the audit lock and never touches the manifest. The one exception is --backfill, which rewrites the monthly ledger files and takes the shared usage lock for the duration — the same claim, in the same place, that audit-lock.py status and /audit:doctor report. That lock excludes only another backfill. The metering hook runs on every turn and never takes it. What it takes instead is the month's own lock, across each append's open, write and close; the backfill takes that same lock only around each month's last read and replace. So while a month is swapped no appender is mid-write or holding the file open, appending goes on through the rebuild, and the rows appended since the backfill read the month are carried into the new file — those of sessions it did not re-read. A project with no git repository has no lock scheme at all; there the backfill says so in its own output rather than inventing a guard nothing else can see.

What that still leaves open, stated rather than implied closed:

• A session the backfill re-reads, metered while it runs — another session of this project ending a turn in the window. Its rows from the window are dropped with the rest of that session's old rows, and whichever of the hook's cursor and the backfill's is saved last decides whether its next turn re-reads them or skips them, so that session's spend can come out short or doubled. Run --backfill again once no other session of the project is active; it rebuilds every session it reads from the transcripts. The session running the backfill is exposed only through a subagent of its own finishing in the window: its own Stop metering runs when the turn ends, after the backfill has finished.
• A writer that does not take the month's lock — an append that could not have it within its wait and wrote anyway, a filesystem that refuses locks altogether, or a copy of the hook older than the lock. If it opened the month file before the replace and writes after it, the backfill reads that row through a descriptor it held across the replace, until a short settle period passes with no byte added and no half-written line waiting, with a bounded number of re-checks. A row such a writer lands after that is lost. On a platform that refuses to replace an open file there is no descriptor to read after the replace: the backfill reads the old file one last time, closes it and replaces it, so a row such a writer lands between that read and the replace is lost. An append that takes the lock is never lost this way.

A month with no file yet is created empty before its rebuild and held the same way, so a row the hook appends while the backfill writes that month is carried like any other.