cost-report

name	cost-report
description	Report actual token spend and dollar cost of dispatched work — per agent and total — and flag cost regressions. Use when the user asks "how much did that cost", "token spend", "cost of this run", "cost report", or wants to check for a cost regression after /code-review or an orchestration run.
argument-hint	[--transcript <path>] [--tolerance <n>]
user-invocable	true
allowed-tools	Bash(python3 *, jq *, tail *, cat *, ls *, test *)

Cost Report (#102)

Role: worker. Reports runtime cost/token spend captured by the cost meter.

Token usage is not available to hooks, so the Stop/SubagentStop hook (hooks/cost_meter.py) records a per-session summary to metrics/cost-metering.jsonl by parsing the session transcript, converting tokens to dollars via knowledge/model-pricing.json. This skill reports that data.

Steps

1. Per-session breakdown. If the user passes --transcript <path> (or you know the current transcript path), run an exact per-agent report:

   python3 "${CLAUDE_PLUGIN_ROOT}/hooks/lib/cost_meter.py" report --transcript <path>
   

   Otherwise show the most recently recorded session from the metrics log (prefer the migrated .claude/metrics/ location, falling back to the legacy bare metrics/ path for a project mid-transition):

   log=".claude/metrics/cost-metering.jsonl"; [ -f "$log" ] || log="metrics/cost-metering.jsonl"
   tail -n 1 "$log" | python3 -m json.tool
   

2. Regression check. Compare the latest session's total cost against the rolling mean of prior sessions (default tolerance +50%):

   log=".claude/metrics/cost-metering.jsonl"; [ -f "$log" ] || log="metrics/cost-metering.jsonl"
   python3 "${CLAUDE_PLUGIN_ROOT}/hooks/lib/cost_meter.py" regression \
     --log "$log" --tolerance 0.5
   

3. Report the per-model, per-thread (main/subagent), and per-agent-type tokens

   • cost, the session total, and whether a cost regression was detected. Do not invent numbers — print exactly what the meter emits. If .claude/metrics/cost-metering.jsonl (or the legacy metrics/cost-metering.jsonl) is absent, tell the user the meter hasn't recorded a session yet (the hook records on turn end).

   For a windowed cost-regression baseline (mean of only the N most recent prior sessions instead of all-time), pass --window N:

   log=".claude/metrics/cost-metering.jsonl"; [ -f "$log" ] || log="metrics/cost-metering.jsonl"
   python3 "${CLAUDE_PLUGIN_ROOT}/hooks/lib/cost_meter.py" regression \
     --log "$log" --tolerance 0.5 --window 10
   

Attribution dimensions (#102, #170, #1094)

report breaks spend down by model, by thread (main-loop vs subagent), and by agent type (#1094), plus the session total.

The agent-type dimension answers "which agent type drives spend" (e.g. security-review vs test-review vs general-purpose): main-loop turns land in main; sidechain turns are attributed via the native attributionAgent field the harness stamps on subagent records, falling back to the Task/Agent dispatch join (tool_use input.subagent_type paired with toolUseResult.agentId). Sidechain spend carrying neither signal lands in an honest unattributed bucket — the meter never guesses. The meter also folds in the sibling per-subagent transcript files (<dir>/<session-id>/subagents/agent-*.jsonl) that newer harness versions write instead of inline sidechain turns, so subagent spend stays visible.

Attribution is limited to what the Claude Code harness actually records on transcript turns. Per-command, per-phase, and per-fix-loop-iteration buckets were removed (#170): they relied on attributionSkill / orchestrationPhase / fixLoopIteration fields the harness never writes (verified 0/312 in a real transcript), and a plugin has no write-path into the transcript — so those dimensions were always empty. The main/subagent split uses the native isSidechain flag, which the harness does provide; the agent-type dimension likewise reads only harness-recorded fields (verified against a real transcript, #1094).

Review value (#348)

/build records, per inline review checkpoint, whether review actually changed anything (metrics/review-value.jsonl, schema in performance-metrics). When that file exists, surface a compact "review value" summary so the user can see whether the pipeline's review overhead paid off on this work — the count of checkpoints that found+fixed a defect vs. those that passed no-op, with the fix-loop iterations spent:

log=".claude/metrics/review-value.jsonl"; [ -f "$log" ] || log="metrics/review-value.jsonl"
[ -f "$log" ] && jq -s '
  {checkpoints: length,
   no_op:    (map(select(.outcome=="no-op"))    | length),
   fixed:    (map(select(.outcome=="fixed"))     | length),
   escalated:(map(select(.outcome=="escalated")) | length),
   issues_found: (map(.issues_found) | add // 0),
   issues_fixed: (map(.issues_fixed) | add // 0),
   fix_iterations: (map(.fix_iterations) | add // 0)}' \
  "$log"

A run that is mostly no_op is evidence the review ceremony is over-provisioned for that class of work — feed it back into the /plan plan-tier and /build per-step complexity routing. Counts only; no code or file content is stored.

Context pollution — per-phase resident vs one-time spend (#1520)

A one-time token bill and context that lingers and "charges rent" on every subsequent turn are economically different costs (Martin Fowler, "The Orchestrator's Tax"). The session totals above cannot tell them apart. The phase_marker.py PostToolUse hook records a marker at every /handoff (a phase boundary) capturing, for the main-loop context, the resident occupancy and the cumulative output spend at that boundary. phase-report turns the marker sequence into a per-phase ratio:

log=".claude/metrics/phase-markers.jsonl"; [ -f "$log" ] || log="metrics/phase-markers.jsonl"
python3 "${CLAUDE_PLUGIN_ROOT}/hooks/lib/cost_meter.py" phase-report --log "$log"

Report the per-phase resident_tokens, spent_tokens (output generated during the phase), and resident_to_spent_ratio. A high ratio flags a phase whose context stayed resident (pollution — a candidate for earlier mid-phase compaction or narrower subagent scoping) rather than being one-time cost; a low ratio means most of the phase's spend was transient. If the log is absent, tell the user no phase boundary has been recorded yet (the hook records on each /handoff).

Honesty caveat — this is a session-scoped proxy, not exact per-phase accounting. resident is sampled at the /handoff marker because that is the closest phase boundary the harness exposes; the harness records no explicit phase marker of its own (the same reason per-command/per-phase cost attribution was removed in #170 — see Attribution dimensions above). The metric lives in its own phase-markers.jsonl log and is never folded into the cost-metering.jsonl incremental state.

Privacy boundary

The meter persists only token counts, dollar amounts, model identifiers, the main/subagent thread flag, agent-type identifiers, and — for phase markers — a phase label and the resident/spent token counts. It never records prompt text, code, file paths, or tool payloads. metrics/cost-metering.jsonl and metrics/phase-markers.jsonl are metrics-only artifacts by construction.

1. Account pace (optional, #142). When the user asks "am I on track for my budget", "how much have I burned this week", or "which model should I use for the rest of the period", report account-level pace: cumulative spend over a rolling window, the implied daily rate, and the projected spend for a billing period — flagging when pace would exhaust a stated budget:

   log=".claude/metrics/cost-metering.jsonl"; [ -f "$log" ] || log="metrics/cost-metering.jsonl"
   python3 "${CLAUDE_PLUGIN_ROOT}/hooks/lib/cost_meter.py" pace \
     --log "$log" --budget 100 --period-days 30 --window-days 7
   

   Without --budget it reports pace only (no flag). When it flags an over-budget pace it suggests dropping a model tier (Opus→Sonnet) for the rest of the window.

Notes

• Disable the meter with DEV_TEAM_COST_METER=off.
• Pricing lives in knowledge/model-pricing.json — update it when rates change (it is the named instrument for every cost number this skill prints).