# Reasoning Token Usage Recording Plan

## Current Design

- OpenCode reports assistant token usage over ACP with `inputTokens`, `outputTokens`, optional `thoughtTokens`, cache tokens, context usage, and cumulative `cost`.
- Investibook persists only input/output/cache/context/cost in `interaction_token_usage`.
- `cost_amount` for ACP chat comes from OpenCode's cumulative cost snapshot, but `thoughtTokens` is not stored and is not included in `output_tokens`.

## Risks

- Treating reasoning tokens as output tokens would hide provider behavior and make output-token trends inaccurate.
- Adding a DB column must migrate existing dev/prod SQLite files without breaking old rows.
- Auxiliary backend-owned calls may not have reasoning usage; they should default to zero.

## Target Contract

- `reasoning_tokens` is a first-class usage field in `interaction_token_usage`.
- `reasoning_tokens` is parsed from ACP `thoughtTokens` / `reasoningTokens` style payloads and stored separately from `output_tokens`.
- Existing rows and non-reasoning calls use `reasoning_tokens = 0`.
- API summaries and eval reports expose reasoning totals/averages explicitly.

## Implementation Steps

1. Add `reasoning_tokens INTEGER NOT NULL DEFAULT 0` to the token usage schema and migration.
2. Extend ACP usage accumulation and `get_and_reset_usage()` to carry reasoning tokens.
3. Pass `reasoning_tokens` through all `_db_insert_token_usage()` call sites and backend-owned usage helpers.
4. Include reasoning totals in chat/admin/eval/context debug summaries.
5. Add focused tests for ACP parsing, DB migration/insertion, and public summaries.

## Verification Checklist

- Run focused backend tests for token usage, chat stats, context debug, and eval formatting.
- Run `git diff --check`.
- Do not deploy until local contract tests pass.