stacktrace-cli 0.8.0__tar.gz → 0.9.0__tar.gz

{stacktrace_cli-0.8.0 → stacktrace_cli-0.9.0}/CLAUDE.md

@@ -108,6 +108,10 @@ nothing about detection.
 - **OpenACA carries nothing AIDR** (ADR-0006). No finding family, no output row
   type, no scan flag, no rule namespace upstream. Detection rule identifiers are
   `stacktrace-*`, never `openaca-*`, and the combined report is assembled here.
+- **Cost is tokens, never dollars** (ADR-0099). Every cost figure, threshold,
+  severity, budget, label and doc line is in tokens or a ratio to the usual
+  ("3× the usual", "40M tokens more"). No price table, no dollar amount, no
+  currency, here or in Fleet. The family is still called `cost`.
 - **Session collection is not ours** (ADR-0002). It lives in `openaidr`, open
   source. Its types stop at our adapter; parsing an agent format here would
   duplicate the thing the split exists to prevent.
@@ -122,6 +126,12 @@ nothing about detection.
   `test_bom_shape.py`, `test_fingerprint_covers_what_the_analyzer_reads.py`. When
   a review names a site, fix the invariant and extend the exhaustive test — a
   second finding of the same class means the first fix was at the wrong level.
+  Cost has its own: `tests/cost/test_cost_findings_carry_no_session_text.py`,
+  `tests/cost/test_cost_is_tokens.py`, `test_cost_findings_are_dated_by_their_citations.py`,
+  and the range and usual checks in
+  `tests/monitor/test_render_cost.py`. When reviews keep re-arguing scope (a
+  time boundary, which sessions a rule reads), write the answer into the spec,
+  as `docs/specs/cost-phase-1.md` §1 "What a rule reads, and when" does.
 
 ## Adding a command
 

{stacktrace_cli-0.8.0 → stacktrace_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stacktrace-cli
-Version: 0.8.0
+Version: 0.9.0
 Summary: CLI for Stacktrace — Detection and Response platform for AI Agents.
 Project-URL: Homepage, https://stacktrace.ai
 Author-email: "Stacktrace AI, Inc" <founders@stacktrace.ai>
@@ -51,7 +51,7 @@ Requires Python 3.11 or newer.
 
 ```console
 $ stacktrace --version
-stacktrace 0.8.0 (openaca 0.8.0)
+stacktrace 0.9.0 (openaca 0.8.0)
 ```
 
 ## Quick start

{stacktrace_cli-0.8.0 → stacktrace_cli-0.9.0}/README.md

@@ -24,7 +24,7 @@ Requires Python 3.11 or newer.
 
 ```console
 $ stacktrace --version
-stacktrace 0.8.0 (openaca 0.8.0)
+stacktrace 0.9.0 (openaca 0.8.0)
 ```
 
 ## Quick start

{stacktrace_cli-0.8.0 → stacktrace_cli-0.9.0}/docs/adrs/0006-trust-boundary-and-detection-upload.md

@@ -5,7 +5,7 @@ status: accepted
 date: 2026-08-28
 supersedes: null
 superseded-by: null
-amended-by: 0011, 0027, 0031, 0039, 0064, 0084, 0086
+amended-by: 0011, 0027, 0031, 0039, 0064, 0084, 0086, 0096
 ---
 
 ## Context

{stacktrace_cli-0.8.0 → stacktrace_cli-0.9.0}/docs/adrs/0026-the-console-becomes-a-product-surface.md

@@ -6,7 +6,7 @@ date: 2026-09-06
 supersedes: 0008
 superseded-by: null
 amends: null
-amended-by: null
+amended-by: 0097
 ---
 
 ## Context

stacktrace_cli-0.9.0/docs/adrs/0092-cost-is-its-own-rule-family.md

@@ -0,0 +1,49 @@
+---
+id: 0092
+title: Cost is its own rule family
+status: proposed
+date: 2026-10-05
+supersedes: null
+superseded-by: null
+amends: null
+amended-by: null
+---
+
+## Context
+
+Cost Phase 1 adds cost rules (`docs/specs/cost-phase-1.md`). The catalogue has
+two families, security and reliability, and Fleet's `detection_rules` check
+constraint allows only those two (migration 0016). ADR-0013 created reliability
+because stuck sessions needed their own heading and handling. Cost now needs the
+same, as one of the product's main use cases.
+
+## Decision
+
+Cost rules form a third family, **`cost`**, named `stacktrace-cost-*`, with a
+`COST_RULES` set in the catalogue. `rules.family_of` derives it, never stored on
+a finding (ADR-0013). `stacktrace-blocked-quota` stays reliability, because the
+agent got stuck, and cost findings may cite it as evidence.
+
+## Alternatives considered
+
+- **Reliability, separated by name prefix.** This was the first proposal. It is
+  rejected for three reasons:
+  - Fleet users count, filter and route by family, and a prefix is invisible to
+    them.
+  - Cost goes to the people who own the budget, not to whoever runs the agent.
+  - Reliability asks whether the session worked; a runaway can work perfectly
+    and still use far more tokens than it needs.
+- **Security.** Rejected: costly behaviour is not an attack.
+
+## Consequences
+
+- One Fleet migration adds `cost` to the family check constraint, done in Phase
+  1 before any cost finding exists, so no stored data moves.
+- The CLI catalogue, the monitor's `by_family` summary, the Fleet console and
+  Slack each gain a third family.
+- Phase 2 can route notifications per family.
+
+## When to revisit
+
+If a cost rule turns out to be mainly about a session failing rather than
+using too many tokens, move that rule to reliability.

stacktrace_cli-0.9.0/docs/adrs/0093-environment-cost-baselines-count-tokens-keyed-by-model.md

@@ -0,0 +1,78 @@
+---
+id: 0093
+title: Environment cost baselines count tokens and are keyed by model
+status: proposed
+date: 2026-10-05
+supersedes: null
+superseded-by: null
+amends: null
+amended-by: 0099
+---
+
+## Context
+
+`stacktrace-cost-runaway-session` must catch a session running away, while it
+runs, against this developer's normal. Three things move "normal" without
+anything going wrong: a price change, a new default model, and idle time.
+
+## Decision
+
+- The daemon keeps p50, p95 and p99 of **cumulative tokens by active minute**,
+  and of 5-minute burn, from this environment's finished sessions over 30 days.
+- It also keeps a **day curve**: cumulative tokens by local time of day per
+  working day, per model. That curve gives the personal-anomaly rule "your usual
+  by now", and needs 10 working days of history.
+  The rule's score is log(today ÷ usual) divided by the spread: 1.48 × the
+  median absolute deviation of that log, at least 0.25. The spec's "beyond the
+  normal range" is a score of 3 or more; "far beyond" is 6 or more.
+- It also keeps **behaviour curves** per run: sub-agents started in 10 minutes,
+  repeats with an unchanged result, input per response, cache reads and cache
+  writes, as p5 and p99, and fresh input at p95. A waste rule fires only when
+  the behaviour and the cost are both unusual for this developer, so no waste
+  rule rests on a fixed limit alone.
+- The summaries are keyed by cohort, `(repo, entrypoint, model)`, falling back
+  to `(entrypoint, model)`, then `(model)`. Each level needs at least 20
+  sessions; with none, the rule is silent.
+- **Tokens, not dollars**, throughout: floors and severity too (ADR-0099).
+- **Recorded tokens on both sides.** Baselines and rules count only what the
+  transcripts record.
+  - The client's own totals are not read at all (ADR-0099): they arrive after
+    the work, with no time of their own, and add about half a percent.
+  - A comparison then undercounts alike on both sides.
+  - On a run with many sub-agents, whose output is often a lower bound, a rule
+    fires later, never falsely sooner.
+- The baseline is backfilled from transcripts at start, excludes sessions with
+  an open cost finding, and is written only by the daemon (ADR-0046).
+- Rules get a frozen snapshot as an input.
+- **The table holds one numeric summary per finished session**, not the
+  percentiles: the summary's curves and behaviour measures, its cohort, run,
+  day and login type. The snapshot computes the percentiles from these rows,
+  which is what lets it drop a flagged run or a row older than 30 days.
+  - Numbers only, never content, so it is an exception to ADR-0006 constraint 1
+    on the same terms as the verdict cache (ADR-0011). It is not the sessions
+    table ADR-0046 rejected, which would have held session models.
+  - It is additive, so `SCHEMA_VERSION` does not move (ADR-0057).
+  - The monitor reads the same snapshot, read-only, for "your usual" (ADR-0097).
+
+## Alternatives considered
+
+- **Dollar baselines.** Rejected: a price change would fire everywhere.
+- **One baseline across models.** Rejected: a model launch would fire everywhere.
+- **Thresholds on finished-session totals.** Rejected: they fire after the
+  tokens are used.
+- **Recompute from transcripts every scan.** Rejected: it repeats the cold pass
+  ADR-0011 and ADR-0037 avoid.
+- **Rules querying the store directly.** Rejected: it breaks the single writer,
+  and output would depend on when it was read.
+
+## Consequences
+
+- Price changes and model launches can't trigger the rule on their own.
+- It costs a new store table and a backfill.
+- A developer with too few sessions gets no runaway findings until Phase 2
+  sends peer numbers.
+
+## When to revisit
+
+If the cohorts prove too thin in measurement, or Phase 2's fleet-wide numbers
+make the narrow levels unnecessary.

stacktrace_cli-0.9.0/docs/adrs/0094-estimate-cost-from-tokens-the-agent-figure-is-a-cross-check.md

@@ -0,0 +1,63 @@
+---
+id: 0094
+title: Cost is tokens × price at the time of use; the agent's own figure is a cross-check
+status: superseded
+date: 2026-10-05
+supersedes: null
+superseded-by: 0099
+amends: null
+amended-by: null
+---
+
+## Context
+
+Phase 1 shows dollars and uses them as floors. Claude Code already
+writes a running `totalCostUSD` in `cost-state` records, in 109 of 181 measured
+sessions. Using it is the obvious shortcut.
+
+## Decision
+
+- The CLI prices each response's token buckets from a **versioned,
+  effective-dated price table**, at the price **in effect when the response
+  happened**.
+- A model with no price is **unpriced**: shown in tokens, never priced at zero.
+- Every dollar says which rate produced it: at list price, or at the org's own
+  rates once entered (Phase 2). The arithmetic is exact for what it prices —
+  tokens by model, type and date — but that excludes two billing dimensions
+  the agent's own figure does include: the 10% multiplier Anthropic applies to
+  a response on US data residency, and per-request fees such as web search,
+  which aren't token charges at all ([cost.md §4.3](../specs/cost.md#43-what-cost-is)).
+- Claude Code's own figure is compared per session as a **cross-check only**.
+- Tokens the transcripts miss, such as some sub-agent work, are taken from
+  Claude Code's per-model token totals and priced the same way, as one
+  "unrecorded" line — reconciled once per **run**, against the run's own
+  latest cumulative figure, never once per session: a resumed session's figure
+  already includes its earlier spend, and a parent's already includes its
+  sub-agents', so summing each session's own remainder would double-count
+  both. Its dollars are never used.
+
+## Alternatives considered
+
+- **Use Claude Code's `cost-state` as the cost.** Rejected, for four reasons:
+  - it is a per-session running total, so it can't price a window, a run or a
+    response;
+  - it is missing in 72 of 181 sessions;
+  - it is Claude Code's alone, and Codex records none;
+  - it can't take org rates or be re-priced.
+- **Price in OpenAIDR.** Rejected by OpenAIDR ADR-0015: a price is
+  interpretation.
+- **The provider's usage API.** Not available in the environment: it needs an
+  admin key, lags, and has no per-session detail. It is Phase 2's reconciliation
+  source.
+
+## Consequences
+
+- One method prices every agent, window and run.
+- The price table must be maintained, and every price change noted in a release.
+- A persistent gap against the cross-check, beyond the data-residency and
+  per-request gaps above, points to a missing price or a counting error.
+
+## When to revisit
+
+If a provider records per-response cost in the transcript: carry it as recorded,
+and make the estimate the cross-check.

stacktrace_cli-0.9.0/docs/adrs/0095-cost-findings-reach-fleet-each-rule-can-be-muted.md

@@ -0,0 +1,53 @@
+---
+id: 0095
+title: Every cost finding shows in Fleet; each cost rule's Slack notifications can be switched off
+status: proposed
+date: 2026-10-05
+supersedes: null
+superseded-by: null
+amends: null
+amended-by: null
+---
+
+## Context
+
+Fleet posts every newly stored finding to Slack (`detections.py`, first
+insert), with no filter by rule or severity. Phase 1 accepts that: its few
+environment rules are checked on recorded sessions before they ship. Phase 2
+adds Fleet's own rules, which compare people with the org and cannot be fully
+tested before real org data exists. A rule that turns out noisy would keep
+paging Fleet users until the next release.
+
+## Decision
+
+- Cost findings drain to Fleet over the existing upload, with **no wire change**,
+  and show in its console per environment and run from day one.
+- In Phase 1, Fleet posts every cost finding to Slack, like any other finding.
+- From Phase 2, Fleet's catalogue gives each cost rule a **`notify` switch**,
+  on by default, and the Slack outbox skips rules with it off.
+- The Stacktrace team turns a rule's `notify` off when it proves noisy, and back
+  on once it is fixed. Its findings still show in Fleet.
+- Reviewing findings as right or wrong is available to the team but optional,
+  and never a gate before a rule notifies.
+- Developers get every cost finding locally either way.
+
+## Alternatives considered
+
+- **Keep findings local until Phase 2.** Rejected: Phase 1 would not be end to
+  end, and Fleet would have no evidence to evaluate.
+- **Hold every new rule off until its findings are reviewed.** Rejected: manual
+  review does not scale, and every new rule would wait on reviewers.
+- **No switch.** Rejected: a noisy rule would page until a release removed it,
+  and teach Fleet users to skip cost alerts.
+- **Send them as low severity.** Rejected: severity says how bad a finding is,
+  not whether a rule is trustworthy, and Slack V1 has no severity filter.
+
+## Consequences
+
+- A small Fleet change: a per-rule setting and one outbox condition.
+- Other rules keep today's behaviour, with `notify` on.
+
+## When to revisit
+
+When Fleet's Slack delivery gains severity or routing filters, which would make
+this flag redundant.

stacktrace_cli-0.9.0/docs/adrs/0096-cost-usage-may-leave-as-token-totals-and-work-identifiers.md

@@ -0,0 +1,86 @@
+---
+id: 0096
+title: Cost usage may leave as token totals and work identifiers
+status: accepted
+date: 2026-10-06
+supersedes: null
+superseded-by: null
+amends: 0006
+amended-by: null
+---
+
+## Context
+
+Cost Phase 2 (`docs/specs/cost-phase-2.md`) needs Fleet to judge an environment
+owner's spend against their own past and against the org. Phase 1 already sends
+findings and nothing else (ADR-0061, ADR-0095), and Fleet still has no usage.
+The phase 2 upload, a new endpoint beside `detect-runs`, would send token totals
+per run, session, model and minute, and per run the repo, branch, title and the
+Anthropic account the agent is signed into.
+
+That document is not a finding. [ADR-0006](0006-trust-boundary-and-detection-upload.md)
+constraint 1 says detection findings are the one thing that may travel — amended
+only by ADR-0039, for a different channel — and constraint 2 says the uploaded
+document carries no user. The account is sent because, on a shared dev box or CI
+runner, it names the person and the Fleet enrollment key does not. None of
+ADR-0092 through ADR-0095 amends constraint 1 or 2, so an implementer who followed
+the spec alone would cross the boundary those constraints still state.
+
+## Decision
+
+This amends ADR-0006 constraints 1 and 2 for one document: the cost usage upload,
+and the cost findings Fleet draws from it. The rest of ADR-0006 stays in force,
+including for every other finding family and for ADR-0039's telemetry.
+
+1. **Token totals may travel. The session may not.** Counts per run, session,
+   model, minute and token type (input, output, cache read, cache write — the
+   rates differ by type), plus a local reduction of the last 30 days to those
+   same counts. The session id is the key already allowed on a finding's session
+   reference, not the session. Transcripts, correlation records and session
+   models stay on the machine. There is still no upload path for them.
+2. **A closed set of work identifiers, and the provider account.** Per run: repo
+   name, branch name, title, and the Anthropic account the agent is signed into.
+   Per component: the tokens its definitions add to every call, whether it was
+   used, and how many calls carried it per model. Repo, branch and title are
+   names of the work, not a path, a working directory or a machine name. The
+   account may appear on a cost finding because that finding is about who spent;
+   it is how a shared environment names the person. No other finding family
+   gains a user.
+3. **Nothing else.** Prompts, tool arguments, tool results and paths do not
+   travel. A title that reproduces the prompt is a prompt and does not travel.
+   Absolute paths and secret-shaped strings are still refused (ADR-0006
+   constraint 4). ADR-0039 is unchanged: its events still exclude repository
+   names.
+
+The findings drain stays findings-only (ADR-0061). This is a separate endpoint.
+
+## Alternatives considered
+
+- **Cut the upload back to what ADR-0006 already allows.** Rejected. Findings
+  carry no usage, so Fleet cannot price an owner's past, separate a shared rise
+  from one person's, or say which work cost the money. That is the gap Phase 2
+  exists to close; Phase 1 already sends findings alone.
+- **Upload the transcripts and price them in Fleet.** Rejected. ADR-0006 already
+  rejected central analysis of session content. The 30-day backfill is computed
+  locally and only the aggregates leave.
+- **Put the rows on the findings drain.** Rejected. ADR-0061 keeps that drain
+  findings-only so the detection document does not grow a second shape.
+- **Drop repo, branch, title and the account, and send token totals under the
+  Fleet key alone.** Rejected. A shared box enrolls as one Fleet member, so the
+  key is not the person who signed the agent in, and a finding that cannot name
+  the work cannot be acted on.
+
+## Consequences
+
+- The cost spec may name these fields because this decision does. A field that
+  is not in the list above is still a breach.
+- Cost findings and their Slack text may repeat the account, the repo, the
+  branch and the title. Other families may not.
+- A title is the easiest way for conversation to leak through a field this
+  decision allows. Watch for one that is the prompt.
+
+## When to revisit
+
+If Phase 2 ships without this upload, supersede this amendment. If the account
+or the title is found to carry a credential or conversation in practice, narrow
+clause 2 rather than widening what else may travel.

stacktrace_cli-0.9.0/docs/adrs/0097-the-daemon-makes-cost-findings-and-the-monitor-reads-them.md

@@ -0,0 +1,69 @@
+---
+id: 0097
+title: The daemon makes cost findings once, and the monitor reads them from the store
+status: proposed
+date: 2026-10-06
+supersedes: null
+superseded-by: null
+amends: 0026
+amended-by: null
+---
+
+## Context
+
+ADR-0026 clause 2 says the console does no analysis of its own: it calls
+`collect_sessions`, `acquire_correlated_view` and `run_detector`, and "a
+finding on the page is a finding `detect` would print".
+
+Cost findings don't fit that shape.
+
+- `budget-breach` and `personal-anomaly` judge today's usage across the
+  whole environment, whatever range the page shows.
+- Every rule but budget breach judges against the 30-day baseline the daemon
+  keeps (ADR-0093).
+- The waste rules judge a run, whose sub-agents the daemon collects.
+
+The monitor sees only the sessions in its range. `detect` sees only its
+window.
+
+## Decision
+
+- **The daemon is the only host that turns cost rules into findings.** It
+  stores them like any other finding, and they reach the session, the webhook
+  and Fleet from there.
+- **The monitor reads cost findings from the store, read-only,** and shows
+  them in `alerts` in `detection_json`'s shape. The baseline snapshot behind
+  "your usual" is read the same way.
+- **`detect` runs no cost rules in Phase 1.** `stacktrace findings` prints the
+  stored ones.
+- The cost numbers themselves (tokens and runs) are pure functions of the
+  sessions, and every surface computes them the same way.
+- This amends ADR-0026 clause 2 for the cost family only: **a cost finding on
+  the page is one the daemon stored.** For security and reliability the
+  clause stands.
+
+## Alternatives considered
+
+- **Every surface runs the cost rules.** Rejected:
+  - A page showing five minutes would judge "today" from five minutes of
+    sessions.
+  - Three hosts would give three answers, and the one Slack received is the
+    daemon's.
+- **The monitor computes its own baseline.** Rejected: it repeats a 30-day
+  cold pass per monitor start (ADR-0011, ADR-0037), and still differs from
+  what Fleet was sent.
+
+## Consequences
+
+- Without a running daemon, the Cost tab shows numbers but no cost findings,
+  and says why.
+- The monitor gains a second input, the store, opened read-only (ADR-0046).
+  The store's newest `seq` joins the watcher's fingerprint, so a new finding
+  shows without waiting for a transcript to change.
+- `detect` users in CI see cost numbers nowhere until a later phase decides
+  otherwise.
+
+## When to revisit
+
+If `detect` gains a reason to report cost findings, such as CI budget checks,
+or the monitor gains a cheaper way to hold a baseline of its own.

stacktrace_cli-0.9.0/docs/adrs/0098-a-run-is-its-main-session.md

@@ -0,0 +1,53 @@
+---
+id: 0098
+title: A run is its main session, and a finding about a run is filed under it
+status: proposed
+date: 2026-10-06
+supersedes: null
+superseded-by: null
+amends: null
+amended-by: null
+---
+
+## Context
+
+Cost judges a piece of work: a main session together with its sub-agents and
+workflow agents (cost-phase-1, "Measure"). Fleet must show cost findings "per
+environment and run" with no wire change (ADR-0095). But neither side's
+detection document has a run field, and Fleet reads a span's session from the
+span itself, so a finding can cite only its own session's spans.
+
+## Decision
+
+- **A run's id is its main session's id.** The parent of a sub-agent is read
+  from OpenAIDR's identity, `<kind>:<parent>:<file stem>` (OpenAIDR ADR-0001),
+  in one place: `sessions/lineage.py`.
+- **A run is keyed by the pair `(agent_kind, run id)`**, like every session.
+- **A finding about a run is filed under its main session.** Fleet then shows
+  it under that session, which is the run, with no new field.
+- The run's other sessions are counted in an evidence line, not listed.
+- A sub-agent's own spans are never cited, because Fleet would refuse them.
+  Evidence cites the main session's turns.
+
+## Alternatives considered
+
+- **A `run_id` field on the detection wire.** Rejected for Phase 1 by ADR-0095.
+  Phase 2's usage upload is where run identity, and the list of a run's
+  sessions, reach Fleet.
+- **File each finding under the sub-agent where the waste happened.** Rejected:
+  a fan-out of small sub-agents is the waste, and each looks normal alone.
+- **Group resumes into a run by transcript file.** Not needed: no transcript
+  on the measuring machine held more than one session id. A resume that keeps
+  its id is already inside its session.
+
+## Consequences
+
+- Fleet shows a run as its main session, plus a count of its sessions and
+  sub-agents.
+- A sub-agent never gets a cost finding of its own.
+- If a client writes a resume as a new session, it is a run of its own.
+
+## When to revisit
+
+When Phase 2's usage upload carries run identity, or a client is found writing
+resumes as new sessions.

stacktrace_cli-0.9.0/docs/adrs/0099-cost-is-measured-in-tokens-and-relative-increases.md

@@ -0,0 +1,85 @@
+---
+id: 0099
+title: Cost is measured in tokens and relative increases, never in dollars
+status: proposed
+date: 2026-10-06
+supersedes: 0094
+superseded-by: null
+amends: 0093
+amended-by: null
+---
+
+## Context
+
+ADR-0094 priced every response at list price and stated cost, floors, budgets
+and severity in dollars. That needs a price table kept current for every model,
+and a dollar figure invites a comparison with an invoice it never matches:
+subscriptions, discounts and committed spend all differ from list price. On a
+subscription, a "spend" figure is not money anyone pays.
+
+Tokens are what the agent actually uses, and what cost follows. Measured on one
+environment's 30 days (193 sessions, 3.1B tokens), 98.1% of all tokens were
+cache reads, and what a token cost varied 3.6-fold from hour to hour (p10 to
+p90) as the mix of token kinds moved. A raw count across people or models
+tracks cost loosely. A count relative to the same developer's similar runs
+(ADR-0093's cohorts) tracks it closely, because the mix of token kinds is
+similar.
+
+## Decision
+
+**Every cost figure is tokens, or a relative increase.** That covers evidence,
+thresholds, severity, budgets, the monitor, notifications, Fleet, specs and
+release notes. Nothing carries a price, a dollar amount or a currency, and
+there is no price table.
+
+- **Relative to the usual.** A finding says how far above this developer's
+  usual it is ("3× the usual"), and how many tokens that is ("40M more").
+- **The tokens a rule is about.** A rule counts the kind of token its
+  behaviour wastes. `cache-collapse` counts uncached input, fresh input and
+  cache writes, for both its triggers: a cache that stops being reused re-sends
+  the same tokens uncached, and one re-written again and again writes them
+  afresh, while the total barely moves. The other rules count all recorded
+  tokens.
+- **Thresholds are token amounts or ratios.** Materiality floors and budget
+  limits are token amounts; severity is how many times the usual a finding is
+  (low under 3×, medium from 3×, high from 10×). The defaults are starting
+  points in tokens, to be tuned against recorded sessions. No exchange rate between
+  tokens and money is recorded or used anywhere.
+- **The family is still `cost`.** Cost is what the rules protect; tokens are
+  how it is measured. Rule ids stay `stacktrace-cost-*`.
+- **Claude Code's own running totals** (`cost-state`) are not read at all,
+  neither their dollars nor their tokens. Measured on 111 sessions, their
+  tokens add 0.54% to what the transcripts record, and they carry no time and
+  arrive only after the work. Every figure comes from the transcripts' own
+  per-response counts.
+
+## Alternatives considered
+
+- **Tokens × list price (ADR-0094).** Rejected: a table to maintain, a figure
+  that differs from every invoice, and a "spend" that subscription users never
+  pay.
+- **Dollars at the org's own rates (Phase 2).** Rejected for the same reasons,
+  and because no org has entered rates.
+- **Total tokens for every rule.** Rejected: cache reads dominate, so a cache
+  that stops being reused is invisible in the total.
+- **Tokens weighted by kind**, such as a cache read counting a tenth. Rejected:
+  that is a price table by another name.
+
+## Consequences
+
+- A new model works on day one: there is nothing to price and no "unpriced"
+  response.
+- Token counts are large and less intuitive than dollars, so every figure is
+  paired with a ratio to the usual.
+- A budget limit is a guard against runaway volume, not a spend cap: the same
+  token limit is different money on different models and plans.
+- There is no check against the client's own figures, in dollars or tokens.
+  The transcripts miss about half a percent of tokens, mostly side calls on a
+  small model and unfinished sub-agent output; rules and baselines count the
+  same recorded tokens on both sides, so a comparison stays fair.
+
+## When to revisit
+
+If customers ask for spend in their own currency, at their own rates, and
+supply those rates, a Phase 2 view could price tokens for display only. Rules,
+thresholds and evidence would stay in tokens.