feat(accounting): report deduplicated SDK result token usage

[ran411285752]

Purpose

Preserve provider token accounting for failed, cancelled-result, autonomous, background, and subagent work without changing existing ACP turn-usage semantics.

Closes #953.

Related to #927 and #914.

Protocol impact

• Adds a negotiated _claude/accountingUsage version 1 extension notification.
• Advertises support through agentCapabilities._meta.claudeCode.accountingUsage.
• Requires the Host to opt in with clientCapabilities._meta.claudeCode.accountingUsage.version = 1.
• Does not change standard usage_update.
• Does not change PromptResponse.usage.

Accounting semantics

• resultId is the stable deduplication key.
• Only params.usage is additive.
• modelUsage is a cumulative SDK audit snapshot and must not be summed directly.
• resultUsage is diagnostic top-level result usage and must not be added to params.usage.
• PromptResponse.usage and accounting events must not be summed together.
• Consecutive aggregate model snapshots are differenced after aggregating all model keys.
• Invalid snapshots use an explicit fallback source.
• Fallback usage is reconciled when cumulative snapshots resume, avoiding double counting.
• Snapshot resets start a new accounting epoch.

Lifecycle coverage

Accounting is attempted before:

• failed result rejection;
• cancellation exits;
• autonomous result exits;
• normal result settlement.

Optional extension delivery failures are logged without changing the standard result lifecycle.

Evidence

Built-Adapter ACP subprocess scenarios covered:

• ordinary multi-turn usage;
• same-model and cross-model subagents;
• background and autonomous results;
• error results;
• cancellation after non-zero assistant usage;
• resume;
• compaction;
• model switching.

A-H and J:

ACP accounting:             304,617
Unique public model ledger: 304,617
Difference:                       0

Compaction scenario I:

Final cumulative modelUsage: 194,914
ACP accounting sum:          194,914
Difference:                        0

The /compact result had zero resultUsage and a 32,903-token accounting delta. Public transcript APIs and JSONL omit that compact-call usage, so they cannot be used as a complete post-compaction accounting ledger.

Verification

• npm run build
• npm run lint
• Prettier check for all five changed files
• 78 focused accounting/lifecycle tests
• Full suite: 711 passed, 20 skipped
• Six pre-existing Windows path-separator assertions remain failing, matching clean origin/main
• Mandatory review: no Critical, High, or Medium findings

Related context

• Expose monotonic provider token counters during active ACP turns #927
• Surface the advisor tool over ACP: result dropped, no config option, advisor tokens missing from usage #914
• Expose accumulated token usage on cancelled PromptResponse #844 / fix: Report usage for cancelled active turns #846
• fix: hold a turn open while its background subagents are still live #870
• PromptResponse.usage sends per-turn token counts, RFD says cumulative #390
• Discrepancies between usage and modelUsage in result messages anthropics/claude-agent-sdk-typescript#112
• Feature request: per-subagent breakdown in modelUsage for cost/token attribution anthropics/claude-agent-sdk-typescript#293