Spend attribution 2026-09-29: count-only scan, ccusage-reconciled receipt, run-shape section and decision record

[seathatflowsinourveins]

Scope

• What this PR changes: adds a portable, count-only scan of Claude Code transcripts (evidence/artifacts/claude-spend-scan.py.txt) with a test that pins it to its receipt (tests/test_claude_spend_scan.py), a receipt from one run of it that is reconciled to ccusage 20.0.26 on a shared copy of the transcript tree (claude-spend-attribution-20260929), a "Run shape and accounting (2026-09-29)" section in docs/token-practice.md, and a decision record (docs/decisions/2026-09-29-token-spend-attribution.md) that gives each token-saving lever its owner and overturn condition. It changes no setting, hook, agent definition, carrier text or pin.
• Base commit: bbc34ace
• Lane: lane:foundation. Paths: docs/, evidence/, tests/ and manifests/evidence.json (a receipt index entry and hashes only, which the hot-file protocol in docs/lanes.md does not treat as a change to what the file says).
• Owned paths touched: docs/token-practice.md, docs/decisions/2026-09-29-token-spend-attribution.md (new), evidence/artifacts/claude-spend-scan.py.txt (new), evidence/receipts/claude-spend-attribution-20260929.json (new), tests/test_claude_spend_scan.py (new), manifests/evidence.json.

SOTA sources

• ccusage (https://github.com/ccusage/ccusage, the repository pinned in manifests/stack.json; v20.0.26 installed; v20.0.17 release notes: "claude: Count advisor model usage"): the counting oracle. ccusage claude daily --json --offline and ccusage claude session --json --offline, with CLAUDE_CONFIG_DIR pointing at a copy of the transcript tree, are the upstream commands the receipt is reconciled to.
• Claude API advisor tool, "Usage and billing" (https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#usage-and-billing, read 2026-09-29): "Top-level usage fields reflect executor tokens only." Advisor inference is therefore read from usage.iterations[type=advisor_message].
• Claude Code docs read 2026-09-29: costs (/clear between unrelated tasks: "Stale context wastes tokens on every subsequent message"), model configuration (max "may show diminishing returns and is prone to overthinking, so test before adopting it broadly"), prompt caching and advisor ("The advisor model's own read of the conversation is not cached").
• API context editing (clear_thinking_20251015 keep default: all turns on Opus 4.5+ and Sonnet 4.6+) and pricing (cache read 0.1x the input price, 0.05x on Opus 5.5; 5-minute write 1.25x, 1-hour write 2x).
• How we built our multi-agent research system: multi-agent runs use about 15x the tokens of a chat, the basis for measuring run shape first.
• Repository precedent: evidence/receipts/claude-advisor-usage-scan-20260928.json (a count-only transcript scan stored with a synthetic-fixture control) and examples/claude-native/workflows/child-usage.mjs (transcriptUsage, the per-child counter that reads no usage.iterations).

Evidence-class table

Claim	Evidence class	Command / receipt
The scan's input, output, cache-read and cache-creation (5m + 1h) totals equal ccusage's within 0.001% on one copy of the transcript tree	native_proven (both tools executed on this host; receipt retained)	data.reconciliation and data.commands (all exit 0) in the receipt
The scan's counting rules give the fixture's hand-computed answer, and removing any one rule moves the answer as computed	synthetic	python3 claude_spend_scan.py --control (data.control, passed: true, five mutants); tests/test_claude_spend_scan.py, 4 tests OK, including one that breaks a rule and expects the control to fail
Children are 81.3% of list-price dollars, children over 60 calls 53.2%, default-typed children 41.1%, the advisor 14.0%, effort max 82.2% of calls	native_proven (list-price proxy, one host, one window, no quality comparison)	data.scan
ccusage lists 303 workflow runs that are 68.1% of its dollars	native_proven	data.ccusage_session_view
A 1-hour subagent cache class costs a net +314M input-equivalents and pays only above a rewrite share of 0.39 (observed 0.20)	source_review (arithmetic on data.scan and the documented price ratios)	data.derived.subagent_cache_ttl; docs/token-practice.md "Cache" bullet
Practice statuses in the decision record	source_review (read back from repository files by a seven-agent Workflow with an independent refuter; no committed receipt)	docs/decisions/2026-09-29-token-spend-attribution.md

Local commands run

$ python3 scripts/validate.py
exit 0  {"components": 69, "hashed_files": 8080, "profiles": 4, "receipts": 171, "status": "passed"}
$ python3 -m unittest tests.test_claude_spend_scan tests.test_context_mode_practice_docs tests.test_evidence_manifest tests.test_host_receipts tests.test_adoption_docs_consistency
Ran 235 tests ... OK (skipped=1)
$ python3 -m unittest tests.test_osv_lockfile_coverage.LockfileInventoryTests.test_every_tracked_lockfile_and_manifest_is_listed tests.test_blind_checkout.RepositoryClassificationTests.test_every_blueprint_value_under_a_label_key_is_classified tests.test_workflow_security_coverage.NewWorkflowSecurityCoverageTests.test_all_published_workflows_are_listed_and_covered
Ran 3 tests ... OK
$ python3 evidence/artifacts/claude-spend-scan.py.txt --control
exit 0  "passed": true
$ python3 scripts/component_matrix.py --write && python3 scripts/new_host_grand_list.py --write
no generated file changed

Decision record

docs/decisions/2026-09-29-token-spend-attribution.md records the user's 2026-09-29 answers (effort stays max, the advisor stays on, savings come from architecture) as their choices, not as measured results, and derives one decision (the subagent cache TTL) from the receipt. An independent review of the first draft found eight fix-level defects (cache-class attribution and the TTL arithmetic, a control with no failing run, --since not reaching the tool counters, an unreproducible reconciliation, unattributed decision wording and a few figures); the first repair fixed them, and a delta review of that repair found one more error, a double count of unsplit cache writes in the dollar breakdown, which this head fixes with a per-model dollar reconciliation (data.reconciliation.cost_usd.by_model) plus seven wording notes. Residuals recorded rather than fixed: the miss bins are approximate (see the receipt's limitations), the unsplit cache remainder's class is unknown, and the external documentation quotes were not re-fetched by the reviewer (they were read by the Workflow's research stages on 2026-09-29). Levers owned elsewhere:

• flag (Gate A PR-H: E2E preregistration for the token-save-practice stack (frozen tasks, metrics, gate, procedure) #381, owner native-agent-stack-2d): maxTurns on the six uncapped role agents, omitClaudeMd starting with landscape-sweep-worker, a query limit per ctx_batch_execute, the serena ids in the carrier's mandatory select (694 loads against 28 calls), per-agent experimental.cacheTtl, and any bashOutputMaxChars change. None is touched here; each waits for the owner.
• flag (compaction window, Compaction-window A/B/C preregistration draft (not frozen, not run) #416): left native.
• flag (repository, queued): count advisor iterations in child-usage.mjs (agent-lab first, then re-vendored), --max-budget-usd at headless call sites (one headless probe on 2.1.284, local_integration and not receipted: error_max_budget_usd with terminal_reason: budget_exhausted at $0.000001, success at $1, on a subscription account), a spend-rate rule beside the existing counter alerts.

Host evidence

Not applicable (no evidence/hosts/ files). The receipt is a measurement of one workstation's own transcripts; a new host runs the same scan and collects its own.

Checklist

• New/changed GitHub Actions are pinned to a full commit SHA with a version comment (none changed).
• New/changed workflows declare top-level permissions: contents: read (none changed).
• No secrets are printed, logged or committed; no new required secret was added.
• No new paid hosting, subscription or billing surface was introduced.
• Peer-owned untracked files and worktrees were preserved.

🤖 Generated with Claude Code