squishling 0.4.0 → 0.5.1

data/docs/configuration.md

@@ -1,7 +1,9 @@
 # Configuration
 
-Squishling sends requests through [RubyLLM](https://rubyllm.com), so configure provider API keys there first
-(OpenAI, Anthropic Claude, Google Gemini, AWS Bedrock, OpenRouter, and any other provider RubyLLM supports):
+Squishling sends requests through an [adapter](adapters.md): [RubyLLM](https://rubyllm.com) (OpenAI, Anthropic
+Claude, Google Gemini, AWS Bedrock, OpenRouter, and any other provider RubyLLM supports), any OpenAI-compatible
+endpoint, or your own. With none configured it uses RubyLLM when the `ruby_llm` gem is in your bundle. For RubyLLM,
+configure provider API keys there first (`require "ruby_llm"` first if your app doesn't use `Bundler.require`):
 
 ```ruby
 RubyLLM.configure do |config|
@@ -14,6 +16,7 @@ Then configure Squishling:
 
 ```ruby
 Squishling.configure do |config|
+  config.adapter = :ruby_llm                   # or :openai_compatible, or your own: see Adapters
   config.default_model = "claude-sonnet-5-5"   # or default_escalation, below
   config.default_provider = nil
   config.default_params = { temperature: 0 }
@@ -24,17 +27,20 @@ end
 
 | Option | Default | Description |
 |---|---|---|
-| `default_model` | `nil` | The universal model (a single attempt) for every squishling class that doesn't declare one. `nil` uses RubyLLM's `default_model`. |
+| `adapter` | `nil` (RubyLLM, when its gem is available) | How requests reach a model: `:ruby_llm`, `:openai_compatible`, a [registered](adapters.md#writing-your-own) name, a Hash with `type:` and that adapter's options, or an adapter instance. See [Adapters](adapters.md). |
+| `default_model` | `nil` | The universal model (a single attempt) for every squishling class that doesn't declare one. `nil` uses the adapter's own default (RubyLLM's `default_model`; the OpenAI-compatible adapter's `default_model:` option). |
 | `default_escalation` | `nil` | The universal [escalation](#models-and-escalation): models tried in order. Assigning it clears `default_model`, and vice versa. |
-| `default_provider` | `nil` | The provider for `default_model`/`default_escalation` steps that don't name one. Only needed for models missing from RubyLLM's registry (see below). |
+| `default_provider` | `nil` | The provider for `default_model`/`default_escalation` steps that don't name one. What it means depends on the adapter: RubyLLM needs it only for models missing from its registry (see below); the OpenAI-compatible adapter ignores it. |
 | `default_params` | `{}` | Generation params for every call (temperature, reasoning effort, top_p, …), overridable per class, per method, and per escalation step. See [Generation params](#generation-params). |
-| `squawk` | `nil` | A callable run after every LLM attempt with the raw output, for sending it to an error tracker or tracing tool. Also settable per class and per method. See [Observing every attempt](failures.md#observing-every-attempt-squawk). |
+| `default_max_total_output_tokens`, `default_max_total_input_tokens` | `nil` (no limit) | The most output (or input) tokens one call may use across all its requests; once reached, the call raises `BudgetExhaustedError` instead of making another attempt. Overridable per class (`squishling max_total_output_tokens: ...`), per method, and per `squish!` call. See [Capping a call's cost](failures.md#capping-a-calls-cost-token-budgets). |
+| `squawk` | `nil` | A callable run after every LLM attempt (see `squawk_on`), and once more when a token budget or a disagreement stops the call, with the raw output, for sending it to an error tracker or tracing tool. Also settable per class and per method. See [Observing every attempt](failures.md#observing-every-attempt-squawk). |
+| `squawk_on` | `:all` | Which attempts reach the `squawk` hook: `:all`, `:rejections` (errors only), `:retries` (errors plus any accepted attempt after the first), `:final` (the last attempt the escalation allows), or a list of them (any one holding runs the hook). A call [stopped](failures.md#a-call-that-is-stopped) by a token budget or a disagreement is always reported. Also settable per class and per method. |
 | `observer` | `nil` | An around-style hook for every provider request: `:coolhand`, any object responding to `around(call)`, or `false` for none. `nil` uses the [Coolhand observer](coolhand.md) when the `coolhand` gem is configured. See [Observers](observers.md). |
 | `default_harness` | `nil` (`:escalation`) | How every squishling class that doesn't declare its own uses its escalation: `:escalation`, `:squishsum`, `:judged_squishsum`, a [registered custom harness](harnesses.md#custom-harnesses), or a Hash with `type:` and options. See [Harnesses](harnesses.md). |
 | `logger` | `nil` | Any `Logger`. Debug lines when a call routes to the LLM, warnings on each escalation and when a fallback is used. Never includes the raw model response; see [what ends up in errors and logs](failures.md#what-ends-up-in-errors-and-logs). |
 
-Transport-level retries (rate limits, 5xx, timeouts) are configured on RubyLLM itself
-(`RubyLLM.config.max_retries`, `request_timeout`).
+Transport-level retries (rate limits, 5xx, timeouts) belong to the adapter: RubyLLM's own
+(`RubyLLM.config.max_retries`, `request_timeout`), or the OpenAI-compatible adapter's `max_retries:` option.
 
 > **`max_retries` was removed.** The escalation now decides how many attempts run, and setting
 > `config.max_retries` raises `ConfigurationError`. The old default (`max_retries = 1`, two attempts on one model) is
@@ -65,7 +71,9 @@ Each step is a model name, or a Hash with:
 | `attempts:` | `1` | How many attempts this step gets before escalating to the next one. |
 | `priority:` | position | An Integer; steps run lowest first. Give every step a `priority:` or none. Steps with the same priority are one tier (see [Rotating models](#rotating-models-within-a-priority)). Gaps are fine. `order:` is the deprecated name for it. |
 | `rotate:` | `true` | Set `false` on a step to keep its tier in the order written instead of rotating it. |
+| `include_when:` | always | A Proc that leaves this step out of any call where it returns falsy (see [Excluding a model per call](#excluding-a-model-per-call)). |
 | `provider:` | the level's `provider:` | See [Providers](#providers-and-newly-released-models). |
+| `retry_temperature:` | none | A Numeric `temperature` for this step's retries in the same chat (not its first attempt), to nudge a model that keeps sending the same rejected reply. Don't use it on a step that sets `thinking`, since reasoning models reject `temperature`. |
 | `forward_rejected:` | `true` | Set `false` to start this step from the original input alone, without the previous step's rejected output and its errors (see below). |
 | `params:` | `{}` | [Generation params](#generation-params) for this step, merged over the class and method params key by key. |
 
@@ -107,6 +115,25 @@ squishling escalation: [
   whole tier in the order written, whatever its other steps say.
 - Rotation also moves which stages the [`:squishsum` and `:judged_squishsum`](harnesses.md) harnesses sample first.
 
+### Excluding a model per call
+
+`include_when:` takes a Proc, called like a `squish_when` predicate: against the instance, with the method's inputs as
+keywords. A step whose Proc returns falsy is left out of that call's escalation, for example a model without a BAA:
+
+```ruby
+squishling escalation: [
+  { model: "gpt-5", include_when: ->(client:, **) { !client.needs_a_baa_model? } },
+  "claude-sonnet-5-5"
+]
+```
+
+- Steps are filtered before rotation, so a tier rotates only between the models still eligible for the call. A step
+  that is excluded takes no part in its tier, so an excluded `rotate: false` step no longer pins it.
+- A call whose steps are all excluded raises `ConfigurationError`. It is never retried or passed to `squish_fallback`.
+- It applies wherever an escalation is declared (class, method, `default_escalation`, or `squish!`), but not to a judge
+  or harness step, which are single steps.
+- The Proc runs on the calling thread. An exception it raises propagates unwrapped.
+
 `params:` on a step let one step switch to a reasoning model that rejects sampling params:
 
 ```ruby
@@ -123,7 +150,7 @@ The first level that declares a `model:` or an `escalation:` supplies the whole
 2. per method: `squish :name, model: ...` or `escalation: ...`
 3. per class: `squishling model: ...` or `escalation: ...` (inherited by subclasses)
 4. universal: `Squishling.config.default_model` or `default_escalation`
-5. RubyLLM's `default_model` (a single attempt)
+5. the adapter's default model (RubyLLM's `default_model`, or the OpenAI-compatible adapter's `default_model:`; a single attempt)
 
 ```ruby
 class InvoiceParser
@@ -139,16 +166,20 @@ end
 Passing both `model:` and `escalation:` in one declaration raises `ConfigurationError`, and so does a list passed as
 `model:`. Across separate declarations (a reopened class, or two config assignments), the latest one wins.
 
-Consecutive attempts of the same step (same model, provider, params, and `forward_rejected:`, e.g. `attempts: 2`)
+Consecutive attempts of the same step (same model, provider, params, `forward_rejected:`, and `retry_temperature:`, e.g. `attempts: 2`)
 continue one conversation. Moving to a different step starts a fresh chat with the original input plus the previous
 output and why it was rejected, so no provider-specific history crosses providers. That rejected output is
 model-generated and is sent to the next step's provider, even when it is a different one, truncated to 4,000
 characters. If you don't want a step to see it (say, because the next step is a different provider), set
 `forward_rejected: false` on that step and it starts from the original input only. Configuration errors (bad
-credentials, an unknown model, a request the provider rejects) never move to the next attempt. See [Failure handling](failures.md).
+credentials, an unknown model, a request the provider rejects) never move to the next attempt. A retry that returns
+exactly the reply the step was just told was invalid skips the step's remaining attempts and moves to the next step. See [Failure handling](failures.md).
 
 ## Providers and newly released models
 
+This section is about the RubyLLM adapter; the OpenAI-compatible adapter takes model names as given and ignores
+`provider:`.
+
 RubyLLM looks models up in its bundled registry. To use a model that isn't there yet, such as a newly released
 OpenAI or Anthropic model, name its provider next to it. Squishling then tells RubyLLM to assume the model exists:
 
@@ -189,14 +220,17 @@ end
 
 | Key | Sent as |
 |---|---|
-| `temperature` | RubyLLM's `with_temperature` |
-| `max_output_tokens` | RubyLLM's `with_max_output_tokens` (translated to each provider's own field) |
-| `thinking` | RubyLLM's `with_thinking`: `true` (the model's default), `false` (off), or options such as `{ effort: :low }`, `{ budget: 1024 }`, `{ display: :omitted }` |
-| anything else (`top_p`, `seed`, `service_tier`, Gemini's `generationConfig`, …) | merged into the provider request as-is via `with_provider_options`, in that provider's own field names |
+| `temperature` | RubyLLM's `with_temperature`; `temperature` in the request body for OpenAI-compatible endpoints |
+| `max_output_tokens` | RubyLLM's `with_max_output_tokens` (translated to each provider's own field); `max_completion_tokens` (or `max_tokens`) for OpenAI-compatible endpoints |
+| `thinking` | RubyLLM's `with_thinking`: `true` (the model's default), `false` (off), or options such as `{ effort: :low }`, `{ budget: 1024 }`, `{ display: :omitted }`. OpenAI-compatible endpoints take only `{ effort: }`, as `reasoning_effort`. |
+| anything else (`top_p`, `seed`, `service_tier`, Gemini's `generationConfig`, …) | merged into the provider request as-is (via `with_provider_options` in RubyLLM), in that provider's own field names |
 
 - **No params means provider defaults.** Squishling sends nothing unless you set it. For structured
   extraction on non-reasoning models (e.g. Anthropic Claude Haiku), a low temperature reduces run-to-run
   variance.
+- **Thinking counts against `max_output_tokens`** on providers that bill it as output: leave room for the thinking
+  budget plus the answer. With `thinking: { budget: 8192 }` and `max_output_tokens: 8192`, a reply that uses its full
+  budget is cut off before any JSON, which shows as [`InvalidOutputError#truncated?`](failures.md#a-cutoff-or-a-wrong-answer).
 - **Reasoning models** (e.g. OpenAI GPT-6 Luna) usually reject sampling params like `temperature` and `top_p`;
   tune `thinking: { effort: }` instead. Anthropic requires `temperature` to be 1 (or unset) when `thinking` is on.
 - **Unsetting an inherited key:** set it to `nil` to send nothing for that key, so the provider default applies.
@@ -206,9 +240,9 @@ end
   squish :triage, model: "gpt-6-luna", provider: :openai, params: { temperature: nil, thinking: { effort: :low } }
   ```
 
-- Keys that Squishling or RubyLLM control (`model`, `messages`, `input`, `instructions`, `system`, `stream`,
-  `response_format`, `text`, `output_config`, `tools`, `tool_choice`, `schema`, and the camelCase and plural
-  spellings other providers use, such as `systemInstruction`, `toolConfig`/`tool_config`, `outputConfig`, `inputs`, …)
+- Keys that Squishling or the adapter control (`model`, `messages`, `input`, `instructions`, `system`, `stream`,
+  `response_format`, `text`, `output_config`, `tools`, `tool_choice`, `functions`, `function_call`, `schema`, and the camelCase and plural
+  spellings other providers use, such as `systemInstruction`, `cachedContent`/`cached_content`, `toolConfig`/`tool_config`, `outputConfig`, `inputs`, …)
   raise `ConfigurationError`, because they would override the model, the conversation, or the strict output format.
 - **Nested containers** such as Gemini's `generationConfig` (and `generation_config` for Gemini Interactions) and
   Mistral Conversations' `completion_args` accept ordinary settings, but reject the keys inside them that carry the
@@ -225,7 +259,7 @@ end
 
 ## Inheritance
 
-Subclasses inherit the model or escalation and its provider (as a pair), harness, generation params (merged key by key), purpose, output schema,
+Subclasses inherit the model or escalation and its provider (as a pair), harness, generation params (merged key by key), token budgets (limit by limit), purpose, output schema,
 `squish_when` predicate, `squish_context` names, `squish_validate`, `squish_fallback`, and every `squish` declaration. Overrides in a subclass, including
 overridden methods, are routed the same way.
 
@@ -235,5 +269,6 @@ overridden methods, are routed the same way.
 ## Per-call overrides
 
 Inside a squished method, `squish!` sends the call to the LLM with its own `purpose:`,
-`append_to_purpose:`, `context:`, `model:` or `escalation:` (with `provider:`), `params:`, and `harness:`. Each layers over the method and class
+`append_to_purpose:`, `context:`, `model:` or `escalation:` (with `provider:`), `params:`, `harness:`, and
+`max_total_output_tokens:`/`max_total_input_tokens:`. Each layers over the method and class
 settings the same way they layer over each other. See [Handing off to the LLM](routing.md#handing-off-to-the-llm-with-squish).

data/docs/failures.md

@@ -8,26 +8,48 @@ A failed attempt moves on to the next one; once the last fails, the error is rai
 
 | Failure | What Squishling does |
 |---|---|
-| Rate limit, 5xx, overload, timeout, connection error | RubyLLM retries at the HTTP level first (`RubyLLM.config.max_retries`, default 3). If it still fails, moves to the next attempt in a fresh chat; on the last attempt, raises `Squishling::LLMError` with the original exception as its `cause`. |
-| Bad API key, unknown model, missing provider config | Raises `Squishling::ConfigurationError`. Never escalated, never sent to the fallback. |
-| Provider rejects the request (400 Bad Request), e.g. an unsupported `temperature` or a schema it won't accept | Raises `ConfigurationError` naming the error class and HTTP status, and the params in use; the provider's own message is on `cause`. Never escalated, never sent to the fallback, so a setup mistake can't be silently covered up on every call. |
-| Empty or `nil` response (e.g. a refusal or a max-tokens cutoff) | Moves to the next attempt, then raises `Squishling::InvalidOutputError` |
+| Rate limit, 5xx, overload, timeout, connection error | The [adapter](adapters.md) retries at the HTTP level first (RubyLLM: `RubyLLM.config.max_retries`, default 3; OpenAI-compatible: `max_retries:`, default 2). If it still fails, moves to the next attempt in a fresh chat; on the last attempt, raises `Squishling::LLMError` with a `cause` when the adapter has one: the RubyLLM adapter always does, a [sanitized stand-in](#the-cause-of-a-provider-failure); the OpenAI-compatible adapter only for transport errors (the error itself, which carries no response body), not for HTTP statuses. |
+| Bad API key, billing or quota problem (402), unknown model or endpoint (404), missing provider config | Raises `Squishling::ConfigurationError`. Never escalated, never sent to the fallback. |
+| Provider rejects the request (400 Bad Request, or another 4xx such as 409 or 422), e.g. an unsupported `temperature` or a schema it won't accept | Raises `Squishling::RequestRejectedError` (a `ConfigurationError`) naming the error class, the HTTP status, and the provider's error status/code when its body carries one (`INVALID_ARGUMENT`, `invalid_request_error`). They are also on `error.provider_status` and `error.provider_code` (nil when absent); only plain tokens are kept, never the provider's message. The message points at a param only when the provider named it, and otherwise says the params, output schema, or input may be invalid. The provider's own message is not on `cause` either unless you opt in (see [the cause of a provider failure](#the-cause-of-a-provider-failure)). It is never retried, so if you know a given code means "this input was bad", rescue it and decide for yourself. A 400 that reports an overlong input is the exception: the adapter raises an `LLMError` for it (the built-in adapters recognize the structured `context_length_exceeded` code; RubyLLM's own `ContextLengthExceededError` is honored too, and the OpenAI-compatible adapter also recognizes the usual wording of servers that send none), since a bigger model may take it. Which of the two a failure is, is the adapter's call (see [the error contract](adapters.md#the-error-contract)); a wording it doesn't recognize stays a rejected request. Never escalated, never sent to the fallback, so a setup mistake can't be silently covered up on every call. |
+| Empty or `nil` response (e.g. a refusal or a max-tokens cutoff) | Moves to the next attempt, then raises `Squishling::InvalidOutputError`. When the provider reported a max-tokens cutoff, the error says so and [`truncated?`](#a-cutoff-or-a-wrong-answer) is true. |
 | Malformed or truncated JSON | Moves to the next attempt, then raises `InvalidOutputError`. JSON wrapped in a markdown code fence is accepted. |
 | JSON that doesn't match the schema (wrong types, missing or extra keys, `null` in a non-`optional` field, a broken [conditional rule](schemas.md#contracts-beyond-the-schema), root not an object) | Moves to the next attempt with the validation errors, then raises `InvalidOutputError` |
 | Schema-valid output that [`squish_validate`](#output-checks-squish_validate) rejects | Moves to the next attempt with your messages, then raises `InvalidOutputError` |
+| The call has used its [token budget](#capping-a-calls-cost-token-budgets) | Stops before the next attempt and raises `Squishling::BudgetExhaustedError` (an `InvalidOutputError`) |
 | With a [squishsum harness](harnesses.md): two valid samples that differ, with no judge or a judge that rejects both | Raises `Squishling::DisagreementError` (an `InvalidOutputError`), carrying both typed `candidates` |
 
 Squishling validates output itself with [json_schemer](https://github.com/davishmcclurg/json_schemer), because
-RubyLLM doesn't, and some providers don't enforce strict mode. When the next attempt is on the same step (same
-model, provider, params, and `forward_rejected:`), the re-ask happens in the same conversation, so the model sees
-what it got wrong. A different step gets a fresh chat with the original input plus the rejected output (truncated to
-4,000 characters) and its errors, so that output is sent to the next step's provider, which may not be the one that
-produced it. Set `forward_rejected: false` on a step to leave both out. `InvalidOutputError` exposes `errors`, `raw`
-(the last response), `attempts`, and `models` (the model tried on each attempt); for a
-[`DisagreementError`](harnesses.md#when-the-harness-fails), `raw` holds both candidates, `attempts` is `nil`, and
-`models` has one entry per role (sample a, sample b, then the judge). With a `logger` configured, every
+adapters don't, and some providers don't enforce strict mode. When the next attempt is on the same step (same
+model, provider, params, `forward_rejected:`, and `retry_temperature:`), the re-ask happens in the same conversation, so the model sees
+what it got wrong. If that re-ask returns the same reply it was just told was invalid, Squishling doesn't spend the
+step's remaining attempts: it moves straight to the next step (or raises `InvalidOutputError`, when this was the
+last), so size `attempts:` for replies that can differ. Set `retry_temperature:` on a step to vary the temperature
+of its same-chat retries. A different step gets a fresh chat with the original input plus the rejected output
+(truncated to 4,000 characters) and its errors, so that output is sent to the next step's provider, which may not be the one that
+produced it. Set `forward_rejected: false` on a step to leave both out. `InvalidOutputError` exposes `errors`,
+`error_details` (the same messages, each tagged with where it came from; see below), `raw`
+(the last response), `attempts`, `models` (the model tried on each attempt), and `finish_reason` (why the provider
+stopped on the last one). For a [`DisagreementError`](harnesses.md#when-the-harness-fails), `raw` holds both
+candidates, `attempts` and `finish_reason` are `nil`, and `models` has one entry per role (sample a, sample b, then
+the judge). With a `logger` configured, every
 escalation is logged as a warning.
 
+### A cutoff or a wrong answer
+
+An empty or half-written reply can mean the model was cut off at the output cap, not that it answered wrongly. The
+provider's stop reason tells them apart: `InvalidOutputError#finish_reason` and `squawk`'s `metadata[:finish_reason]`
+hold it as a Symbol (`:stop`, `:max_tokens`, `:content_filter`, or the provider's own spelling; `nil` when it reported
+none), and `truncated?` is true for `:max_tokens`. A truncated error's message and the log line say so.
+
+```ruby
+rescue Squishling::InvalidOutputError => e
+  e.truncated? # => true: raise max_output_tokens, rather than tuning the prompt or validator
+```
+
+Providers that count thinking against the cap need `max_output_tokens` to leave room for the thinking budget plus the
+answer: `thinking: { budget: 8192 }` with `max_output_tokens: 8192` leaves none, so every reply that uses its full
+budget is cut off before any JSON is written.
+
 ### What ends up in errors and logs
 
 Model output can echo sensitive input, so the raw response is kept in one place: `InvalidOutputError#raw` (plus the opt-in `squawk` hook below).
@@ -37,28 +59,113 @@ Model output can echo sensitive input, so the raw response is kept in one place:
   snippet of the response.
 - JSON Schema errors, which name the schema path and the rule that failed. They never contain the rejected value, but
   they do name an extra key the model added (`object property at /foo is a disallowed additional property`), and
-  that key name is chosen by the model.
+  that key name is chosen by the model. These are the only entries Squishling itself fills with model-chosen text; see
+  [telling the entries apart](#telling-the-entries-apart).
 - Your own `squish_validate` messages, verbatim. If you interpolate result values into them, those values reach
   the message, the logger, and the next attempt's prompt.
 - A fixed message when a response contains a value JSON can't represent (`1e400` parses to `Infinity`, or a string
   with invalid UTF-8).
-- For a failed provider request (`LLMError`, and the `ConfigurationError` for a 400, bad credentials, or a forbidden
-  key), only the error class and HTTP status. The provider's own message can echo request content or part of an API
-  key, so it stays on `cause` (`error.cause.message`) for you to read or log deliberately.
+- For a failed provider request (`LLMError`, and the `ConfigurationError` for a rejected request, bad credentials, or a forbidden
+  key), only the error class and HTTP status, plus a rejection's provider status and code when they are plain tokens. The provider's own message can echo request content or part of an API
+  key, and error trackers report the whole `cause` chain, so it is not on `cause` either unless you
+  [opt in](#the-cause-of-a-provider-failure).
 - At most the first 20 of these errors, plus a count of the rest, so a very large malformed response can't flood
   the retry message or the log.
 - For a [`DisagreementError`](harnesses.md#when-the-harness-fails), only what Squishling wrote: a `:judgment` judge's
   choice and probability. A chat judge's `reason` is model-written, so it is available as `#reason` but never in the
   message or logs.
 
+#### Telling the entries apart
+
+`InvalidOutputError#errors` is an Array of Strings. `#error_details` is the same list as
+`Squishling::InvalidOutputError::Detail` values (`message`, `source`), so a sink with its own control syntax (a chat
+webhook, HTML, a markdown renderer) can escape only what needs it:
+
+| `source` | Where the message came from | `model_derived?` |
+|---|---|---|
+| `:schema` | A JSON Schema error. It can name a key the model chose. | `true` |
+| `:validator` | Your own [`squish_validate`](#output-checks-squish_validate) message, verbatim. Never flagged, so escape it too if you interpolate result values into it. | `false` |
+| `:parse` | A message about a response or return value that didn't parse (not valid JSON, empty, a value JSON can't represent). | `false` |
+| `:squishling` | Other text Squishling or a [custom harness](harnesses.md#when-the-harness-fails) wrote, such as the "... and N more errors" notice. | `false` |
+
+```ruby
+squish_fallback do |error, **|
+  trusted = error.error_details.reject(&:model_derived?).map(&:message)
+  notify_channel("squishling rejected output: #{trusted.first(2).join('; ')}")
+  # ...
+end
+```
+
 The same applies to anything you log yourself, such as `error.message` in a [fallback](#fallbacks). Use `error.raw`
 only where you are willing to store model output. To send the output of every attempt somewhere on purpose, use
 [`squawk`](#observing-every-attempt-squawk).
 
+### The cause of a provider failure
+
+A provider's own exception (RubyLLM's, say) carries the provider's response body in its message and `response`, and the
+body can echo your request. Error trackers such as Sentry report the whole `cause` chain, so an `LLMError`,
+`ConfigurationError`, or `RequestRejectedError` raised for a failed request does not carry that exception as its
+`cause`. The [RubyLLM adapter](adapters.md#ruby_llm) puts a `Squishling::Adapter::ProviderFailure` there instead: its
+message is the original's class and HTTP status (`RubyLLM::RateLimitError, HTTP 429`), and it has the original's
+backtrace, but none of its message, response, or other state. Transport errors that carry no body (the OpenAI-compatible
+adapter's timeouts and connection failures) are passed through as they are.
+
+To get the original back for debugging, accept that it reaches your tracker and set `keep_cause: true`:
+
+```ruby
+Squishling.configure do |config|
+  config.adapter = { type: :ruby_llm, keep_cause: true }
+end
+```
+
+Then `error.cause` is the `RubyLLM::Error` itself, with its message and `response`.
+
+## Capping a call's cost (token budgets)
+
+`attempts:` limits retries per step, but a call that fails every attempt still pays for all of them, and with
+reasoning models the failed attempts are often the longest. A token budget caps what one call may use across every
+request it makes, whichever [harness](harnesses.md) it runs:
+
+```ruby
+class TicketTriager
+  include Squishling
+
+  squishling escalation: [{ model: "claude-haiku-4-5", attempts: 2 }, { model: "claude-sonnet-5-5", attempts: 2 }],
+    max_total_output_tokens: 25_000,
+    max_total_input_tokens: 200_000
+end
+```
+
+Before each request, Squishling checks the tokens used so far by the call's earlier requests (the escalation's
+attempts, a squishsum harness's samples, and a judge's). Once either total has reached its limit, it makes no more
+requests and raises `Squishling::BudgetExhaustedError`. It is an `InvalidOutputError` (so
+[`squish_fallback`](#fallbacks) receives it, and existing `rescue InvalidOutputError` code keeps working), and
+`rescue Squishling::BudgetExhaustedError` tells it apart from a plain validation failure:
+
+- `limit` is `:max_total_output_tokens` or `:max_total_input_tokens`, `max` its value, and `used` the tokens spent
+  so far (`{ input_tokens:, output_tokens: }`).
+- `errors` starts with the budget line, followed by the validation errors of the last rejected output, which is in
+  `raw` (`nil` when no output was rejected, e.g. the samples were valid but there was no budget left for the judge);
+  `attempts` and `models` are the requests made.
+- Like any other error message, it carries no model output.
+
+Things to know:
+
+- The first request always runs, and a request already in flight is never cut short, so a call can end above the
+  limit by one request (for the squishsum harnesses, one round of samples).
+- Tokens are the counts the [adapter](adapters.md) reports (`output_tokens` includes a reasoning model's thinking
+  tokens for providers that count them that way). A request that failed reports none, and a provider that reports no
+  usage never exhausts a budget.
+- The limits are positive Integers. Set them with `Squishling.configure` (`default_max_total_output_tokens`,
+  `default_max_total_input_tokens`), `squishling`, `squish :method, ...`, or a [`squish!`](routing.md#handing-off-to-the-llm-with-squish) call.
+  The more specific level wins, limit by limit, and `false` lifts a limit set at a wider level.
+- To limit a single response instead, use the `max_output_tokens` [generation param](configuration.md#generation-params).
+
 ## Observing every attempt (`squawk`)
 
 `squawk` is an opt-in hook for sending what the model returned to an error tracker or tracing tool. It runs after
-every LLM attempt, accepted or rejected, and does nothing unless you set it:
+every LLM attempt, accepted or rejected (unless you narrow it with `squawk_on:`, below), and once more when a token
+budget or a disagreement stops the call. It does nothing unless you set it:
 
 ```ruby
 Squishling.configure do |config|
@@ -71,12 +178,30 @@ end
 | Keyword | Value |
 |---|---|
 | `output` | The raw response: a Hash or String, or `nil` when the provider call itself failed |
-| `error` | `nil` for an accepted attempt. Otherwise the `InvalidOutputError` (with `errors` and `raw`) or `LLMError` that ended the attempt |
-| `metadata` | `label` (`"Class#method"`), `attempt`, `attempts` (the escalation's length; under a harness, the sample's or judge's own attempts), `final` (the last attempt), `model`, `provider`, `params`, `input` (the JSON sent: arguments and named context only), `usage` (token counts, when RubyLLM reports them), `role` (`nil` for an escalation attempt, `:sample`, or `:judge`), `sample` (`"a"`, `"b"`, ... for a sample's attempt, else `nil`) |
+| `error` | `nil` for an accepted attempt. Otherwise the `InvalidOutputError` (with `errors` and `raw`) or `LLMError` that ended the attempt, or the `BudgetExhaustedError` or `DisagreementError` that stopped the call |
+| `metadata` | `label` (`"Class#method"`), `attempt`, `attempts` (the escalation's length, or for a [stopped call](#a-call-that-is-stopped) the attempts made; `attempt` jumps past the attempts a repeated reply skips; under a harness, the sample's or judge's own attempts), `final` (the last attempt, or a rejection after which none follows), `repeated` (`true` when the attempt returned the same reply as the one before it, in the same chat, which skips the step's remaining attempts), `model`, `provider`, `params`, `input` (the JSON sent: arguments and named context only), `usage` (token counts, when the adapter reports them), `finish_reason` (why the provider stopped, e.g. `:stop` or `:max_tokens`; `nil` when unknown or the call failed), `role` (`nil` for an escalation attempt, `:sample`, or `:judge`), `sample` (`"a"`, `"b"`, ... for a sample's attempt, else `nil`), `stopped` (`nil` for an attempt; `:budget` or `:disagreement` for the [stopped call's report](#a-call-that-is-stopped)) |
 
 - Set it globally with `config.squawk`, per class with `squishling squawk: ...`, or per method with
   `squish :triage, squawk: ...`. The method's hook wins over the class's, which wins over the configured one;
   `squawk: false` silences an inherited hook. Subclasses and `squish!` calls inherit it.
+- Limit which attempts reach the hook with `squawk_on:`: `:all` (the default), `:rejections` (only attempts that
+  errored), `:retries` (those plus any accepted attempt after the first), or `:final` (the last attempt the escalation
+  allows, accepted or not; `metadata[:final]`). A classifier that passes on the first try nearly every time can post
+  only when something went wrong:
+
+  ```ruby
+  squishling squawk: ->(error:, **) { Tracer.record(error) if error }, squawk_on: :retries
+  ```
+
+  Pass a list to combine conditions; the hook runs when any one holds. `squawk_on: %i[rejections final]` reports
+  every error, plus the last attempt when it is reached and succeeds. A call accepted on an earlier attempt never
+  reaches `:final`. A level's value replaces the one above it; lists are never merged across levels.
+
+  Set it globally with `config.squawk_on`, per class with `squishling squawk_on: ...`, or per method with
+  `squish :triage, squawk_on: ...`. It resolves on its own, method then class then configured, so
+  `config.squawk_on = :retries` filters every hook, including a class's own, unless that class or method overrides it.
+  Under a [harness](harnesses.md), `attempt`, `attempts` and `final` count per sample or judge, so a sample's
+  first-attempt success is skipped even while another sample retries, and `:final` fires once per sample and judge.
 - Any object that responds to `call` works. The hook receives only the keywords it declares, unless it takes `**`,
   so a lambda that wants just `error:` is fine and new metadata fields won't break it.
 - It runs inline, so keep it quick. Exceptions it raises propagate unchanged and fail the call, like any of your own
@@ -87,6 +212,28 @@ end
 - It isn't called for a `ConfigurationError`, for deterministic and fallback returns, or for an attempt where your own
   `squish_validate` raises (that exception propagates first).
 
+### A call that is stopped
+
+A call that a [token budget](#capping-a-calls-cost-token-budgets) or a
+[disagreement](harnesses.md#when-the-harness-fails) stops has no attempt of its own to report: the attempt before a
+budget stop was reported as not final, and a disagreement's samples were both accepted. So the call gets one more
+report, whatever `squawk_on:` is set to:
+
+- `error` is the `BudgetExhaustedError` or `DisagreementError`, `output` is `nil` (nothing was sent), `metadata[:final]`
+  is `true`, and `metadata[:stopped]` is `:budget` or `:disagreement` (it is `nil` for every attempt's report).
+- `attempt` and `attempts` are `error.attempts`, or `0` when that is `nil` (a disagreement, or a budget that ran out
+  before a sample or judge made its first attempt); a stop before a retry counts the attempts already made. `model` is
+  the last of `error.models`, and `provider`, `params`, `usage`, `role`, and `sample` are `nil`.
+- It is sent once, after the attempts that led to it and before `squish_fallback` runs, for the built-in harnesses and
+  for a [custom one](harnesses.md#reporting-to-squawk) that raises either error. A call to another squished method
+  from your own code (a `squish_validate`, say) reports its own stop, and the outer call does not report that error
+  again. The attempts before it keep `final: false`, so `squawk_on: :final` sees a budget or disagreement ending only
+  through this report.
+- Like any attempt's report, it runs your hook inline: an exception the hook raises propagates in place of the
+  `BudgetExhaustedError` or `DisagreementError` (which stays on `cause`), so `squish_fallback` does not run.
+- `squawk: false`, or no hook, sends nothing. Ending on the last invalid attempt is not a stop: that attempt already
+  carried `final: true`.
+
 ## Output checks (`squish_validate`)
 
 The schema covers shape and types. For rules it can't express, such as cross-field arithmetic or a lookup against
@@ -120,17 +267,18 @@ end
 | Error | Raised when |
 |---|---|
 | `Squishling::Error` | Base class for everything below. Raised directly for misuse at call time, e.g. `result` or `squish!` called outside a squished method |
-| `Squishling::ConfigurationError` | Missing purpose or schema, a non-strict schema, invalid or reserved params, an invalid `model:`/`escalation:` declaration, an invalid `append_to_purpose` item or unavailable source, bad credentials, an unknown model, a request the provider rejects (400) |
+| `Squishling::ConfigurationError` | Missing purpose or schema, a non-strict schema, invalid or reserved params, an invalid `model:`/`escalation:` declaration, an invalid `append_to_purpose` item or unavailable source, bad credentials, an unknown model, a request the provider rejects (a 400 or other rejected 4xx, as `RequestRejectedError`, with `provider_status` and `provider_code`) |
 | `Squishling::InvalidOutputError` | LLM output still invalid (schema or `squish_validate`) after every attempt in the escalation, or a deterministic/fallback return that doesn't match the schema |
 | `Squishling::DisagreementError` | A subclass of `InvalidOutputError`: a [squishsum harness](harnesses.md#when-the-harness-fails)'s samples disagreed and no judge accepted either. `candidates`, `verdict`, and `reason` describe what happened |
-| `Squishling::LLMError` | The provider call failed on the last attempt in the escalation, after RubyLLM's own retries, including context-length errors (`cause` holds the original) |
+| `Squishling::BudgetExhaustedError` | A subclass of `InvalidOutputError`: the call used up its [token budget](#capping-a-calls-cost-token-budgets) before an attempt was accepted. `limit`, `max`, and `used` describe the budget |
+| `Squishling::LLMError` | The provider call failed on the last attempt in the escalation, after the adapter's own retries, including context-length errors (`cause` holds a [sanitized stand-in](#the-cause-of-a-provider-failure), when the adapter has one) |
 
 Errors raised by your own Ruby code are not wrapped.
 
 ## Fallbacks
 
 Use `squish_fallback` to decide what happens when the LLM path fails with `InvalidOutputError` (including a
-`DisagreementError`) or `LLMError`. It's the one fallback for every [harness](harnesses.md).
+`DisagreementError` or `BudgetExhaustedError`) or `LLMError`. It's the one fallback for every [harness](harnesses.md).
 It receives the error plus the method's inputs as keywords, and runs against the instance:
 
 ```ruby

data/docs/harnesses.md

@@ -58,8 +58,8 @@ Both samples run on the escalation's first step, with its model, provider, and p
 - **They're independent.** Each sample has its own chat, and the two requests are sent concurrently on separate
   threads. Only the provider requests run on those threads. Parsing, schema validation, `squish_validate`,
   `compare:`, and the judge all run on the calling thread, so your Squishling callbacks never run concurrently.
-  RubyLLM instrumentation subscribers (e.g. `ActiveSupport::Notifications` listeners for `chat.ruby_llm`) do see
-  each sample's request on its worker thread, outside the Rails executor, so keep them thread-safe.
+  With the RubyLLM adapter, instrumentation subscribers (e.g. `ActiveSupport::Notifications` listeners for
+  `chat.ruby_llm`) do see each sample's request on its worker thread, outside the Rails executor, so keep them thread-safe.
 - **Each one is retried like an escalation step.** A sample with invalid output is re-asked in its own chat, up to
   the first step's `attempts:`, while a sample that already passed keeps its result. A failed request gets a fresh
   chat. A sample still failing after its attempts fails the call with `InvalidOutputError` or `LLMError`, as
@@ -83,7 +83,7 @@ whose typed result is returned (`squished?` is `true`), or it picks `neither`, w
 The judge is:
 
 1. the `judge:` step, if declared: a model name, or a Hash with `model:`, `provider:`, `params:`, and `attempts:`
-   (as in an escalation step, without `priority:` or `rotate:`), plus `type:`; or
+   (as in an escalation step, without `priority:`, `rotate:`, or `include_when:`), plus `type:`; or
 2. the escalation's next step after the sampled one, with its attempts. Steps tied on `priority:` rotate between calls
    (see [Rotating models](configuration.md#rotating-models-within-a-priority)), so which model that is can vary.
 
@@ -91,6 +91,13 @@ A judged harness with neither raises `ConfigurationError` before any sample is r
 step uses only its own `provider:`; it doesn't inherit the class or method `provider:`, which belongs to their models
 (a chat judge's params, though, do merge over the method's).
 
+**What the judge is sent.** The judge's provider receives the operation's purpose, the call's full input (the same
+method arguments and named context the samples saw), and **both candidate outputs**, whatever they hold. None of it is
+capped or filtered, and there is no opt-out short of not using a judged harness. When the judge is a different
+provider than the sampled model (a `judge:` step with its own `provider:`, or an escalation's next step on another
+provider), the input and both outputs go to that provider as well, so only name a judge you would trust with the
+input itself.
+
 ### Chat judges
 
 By default the judge is a chat model, asked for a strict `{ "verdict": "a" | "b" | "neither", "reason": "..." }`.
@@ -108,8 +115,10 @@ valid verdict raises `InvalidOutputError`. A chat judge's params are the method'
 ### System One judgment models (Jev)
 
 A judge can also be a System One decision model, such as TypeSafe's Jev, via
-[RubyLLM judgments](https://rubyllm.com/judgments/) (RubyLLM 2.1+). Decision models return calibrated
-probabilities rather than text, so they are much faster and cheaper than a chat judge.
+[RubyLLM judgments](https://rubyllm.com/judgments/) (RubyLLM 2.1+). This needs an [adapter](adapters.md) that
+supports judgments, which today means the `:ruby_llm` adapter; on any other, a `type: :judgment` judge raises
+`ConfigurationError` before a request is made (a `type: :chat` judge works with every adapter). Decision models return
+calibrated probabilities rather than text, so they are much faster and cheaper than a chat judge.
 
 ```ruby
 squishling harness: {
@@ -122,8 +131,8 @@ Squishling asks one `choice` question (`a`, `b`, or `neither`), with the judge p
 operation's purpose, input, output schema, and candidates as the judgment input. A pick of `a` or `b` is
 accepted only when its probability is at least `min_confidence:` (default `0.8`). Otherwise, as with `neither`,
 `DisagreementError` is raised with the choice and its probability in its `reason`. A judgment judge sends only its own
-`params:` (as RubyLLM `provider_options:`). `attempts:` retries a failed request. Configure the provider's
-credentials in RubyLLM as usual.
+`params:` (as RubyLLM `provider_options:`). `attempts:` retries a failed request. Judgments are a RubyLLM feature, so
+they need the `:ruby_llm` adapter, with the provider's credentials configured in RubyLLM as usual.
 
 ### The default judge prompt
 
@@ -166,6 +175,10 @@ end
 | `attempts` | `nil` |
 | `models` | The model behind each role: sample `a`, sample `b`, then the judge if one ran (one entry each, not one per attempt) |
 
+A [token budget](failures.md#capping-a-calls-cost-token-budgets) covers every request of the call, the samples
+and the judge's included. When it is spent before the next round of retries or before the judge can run, the call raises
+`BudgetExhaustedError` (also an `InvalidOutputError`, and also sent to the fallback) instead of a `DisagreementError`.
+
 Other failures are unchanged. A sample or judge that never produces valid output raises `InvalidOutputError`, a
 failed request on the last attempt raises `LLMError`, and setup mistakes (including a provider 400 on either
 sample) raise `ConfigurationError`, which is never sent to the fallback.
@@ -256,7 +269,7 @@ the harness is declared, before any request is made, and an unknown, missing, or
 
 | Type | Accepts | `call` receives |
 |---|---|---|
-| `:step` | A model name, or a Hash with `model:`, `provider:`, `params:`, `attempts:`, `forward_rejected:` | A normalized, frozen step; pass it to `run.escalate`, or in the Array given to `run.samples` |
+| `:step` | A model name, or a Hash with `model:`, `provider:`, `params:`, `attempts:`, `forward_rejected:`, `retry_temperature:` | A normalized, frozen step; pass it to `run.escalate`, or in the Array given to `run.samples` |
 | `:proc` | A Proc | The Proc |
 | `:string`, `:symbol`, `:integer`, `:boolean` | A String, a Symbol (or String, converted), an Integer, `true` or `false` | The value |
 
@@ -288,12 +301,15 @@ results, the same type the deterministic path returns.
 | `run.stage(declaration)` | A stage from a model name or a step Hash (a single step is a stage of one attempt). It keeps its own provider, and its `params:` merge over the method's, as a [judge](#the-judge) step does |
 | `run.escalate(*stages)` | Makes each attempt in order until an output passes the schema and `squish_validate`, in the same chat after invalid output and in a fresh one (told about the rejected output) on a new step. With no argument, it runs the escalation: exactly what `:escalation` does |
 | `run.samples(stages)` | Takes an Array of stages (so `run.samples([stage, stage])`, not `run.samples(stage)`; a bare step counts as a stage of one attempt): one sample per stage, each in its own chat and retried like an escalation step, with the requests of every round sent concurrently. Returns the outputs in order. Each stage must be one model's attempts: mixed steps raise `ConfigurationError`. Samples are named `"a"`, `"b"`, ... (up to 26) |
-| `run.judge(judge: nil, instructions: nil)` | Resolves a [judge](#the-judge) now (so a missing one raises `ConfigurationError` before any request) and returns it. `judge:` is a model name, or a [judge Hash](#the-judge) (`model:`, `provider:`, `params:`, `attempts:`, `type:`, `min_confidence:`; no `priority:` or `rotate:`), and `instructions:` a non-blank String or a Proc. `judge.verdict(first, second)` returns a `Squishling::Judge::Verdict` with `choice` (`:a`, `:b`, or `:neither`), `reason`, and `detail`, and `judge.step` is its first attempt. A chat judge's `reason` is model-written, so use `detail` (Squishling's own text, `nil` for a chat judge), not `reason`, in messages and logs. Without `judge:`, the judge is the escalation's second stage |
+| `run.judge(judge: nil, instructions: nil)` | Resolves a [judge](#the-judge) now (so a missing one raises `ConfigurationError` before any request) and returns it. `judge:` is a model name, or a [judge Hash](#the-judge) (`model:`, `provider:`, `params:`, `attempts:`, `type:`, `min_confidence:`; no `priority:`, `rotate:`, or `include_when:`), and `instructions:` a non-blank String or a Proc. `judge.verdict(first, second)` returns a `Squishling::Judge::Verdict` with `choice` (`:a`, `:b`, or `:neither`), `reason`, and `detail`, and `judge.step` is its first attempt. A chat judge's `reason` is model-written, so use `detail` (Squishling's own text, `nil` for a chat judge), not `reason`, in messages and logs. Without `judge:`, the judge is the escalation's second stage |
 | `run.agree?(first, second, compare = nil)` | `compare` (evaluated against the instance with both results and the method's inputs) or, without one, exact equality |
 | `run.log(message)` | A warning to `config.logger`, prefixed with `"[Squishling] Class#method"` |
 
 `call` returns the accepted result: one a primitive of this run returned. Returning anything else (a Hash, `nil`, a
-result you built or copied with `with`) raises `ConfigurationError`, so a harness can't skip validation.
+result you built or copied with `with`) raises `ConfigurationError`, so a harness can't skip validation. The check is
+by object identity, which suits the typed results of an object schema. When the schema isn't an object, a result is a
+bare JSON value, and an immediate such as `1` or `true` counts as produced whatever its source, so there the check can't
+catch a hand-built value.
 
 ### When a custom harness fails
 
@@ -302,8 +318,10 @@ A harness fails the way the built-ins do, so `squish_fallback` and the error cla
 - **Attempts run out.** `run.escalate` and `run.samples` raise `InvalidOutputError` (invalid output after the last
   attempt) or `LLMError` (a failed request on the last attempt) themselves, with the same attributes as always.
 - **Your rule rejects.** Raise one of those errors yourself. `Squishling::DisagreementError.new(candidates:,
-  models:)` is the one for samples that don't agree, and `Squishling::InvalidOutputError.new(errors: [...], source: "Harness")` for
-  anything else. Both go to [`squish_fallback`](failures.md#fallbacks).
+  models:)` is the one for samples that don't agree, and `Squishling::InvalidOutputError.new(errors: [...],
+  source: "Harness")` for anything else. Both go to [`squish_fallback`](failures.md#fallbacks). A String error is
+  tagged `:squishling` in [`error_details`](failures.md#telling-the-entries-apart); pass a
+  `Squishling::InvalidOutputError::Detail` to tag it yourself.
 - **Setup mistakes** raise `ConfigurationError`, which is never retried and never sent to the fallback.
 - **Your own exceptions** (from `call`, `compare:`, or `squish_validate`) propagate unchanged. Squishling doesn't wrap or
   swallow them.
@@ -313,10 +331,16 @@ available to your code as the results and in `InvalidOutputError#raw`, and to `s
 
 ### Reporting to `squawk`
 
-Every attempt a primitive makes is reported to the [`squawk`](failures.md#observing-every-attempt-squawk) hook, with
-usage, so [token measuring](measuring-tokens.md) works unchanged. `metadata[:role]` says what the attempt was for:
+Every attempt a primitive makes is reported to the [`squawk`](failures.md#observing-every-attempt-squawk) hook
+(unless narrowed with `squawk_on:`), with usage, so [token measuring](measuring-tokens.md) works unchanged. `metadata[:role]` says what the attempt was for:
 `nil` for an escalation attempt, `:sample` (with `metadata[:sample]` set to `"a"`, `"b"`, ...), or `:judge`. `attempt`
-and `attempts` count within that sample, judge, or escalation.
+and `attempts` count within that sample, judge, or escalation. `metadata[:repeated]` is `true` for an attempt that
+sent back the reply it was just rejected for; the primitive then skips the rest of that step's attempts (the next
+step's `attempt` jumps past them, and a sample ends with its `InvalidOutputError`).
+
+A call that ends on the token budget or on a `DisagreementError` (the built-in squishsum harnesses', or one your
+`call` raises) is reported once more, as [a stopped call](failures.md#a-call-that-is-stopped), with `metadata[:stopped]`
+set and no output. Squishling does it around your `call`, so a custom harness needs no code for it.
 
 ### Threads
 

data/docs/measuring-tokens.md

@@ -6,11 +6,13 @@ first tells you when the second is worth paying.
 ## What Squishling gives you
 
 - `result.squished?` says which path served a call, so you can count LLM calls per class.
-- The [`squawk` hook](failures.md#observing-every-attempt-squawk) runs after every LLM attempt and receives the
+- The [`squawk` hook](failures.md#observing-every-attempt-squawk) runs after every LLM attempt (by default; see `squawk_on` below) and receives the
   method (`label`, e.g. `"ShipmentUpdate#call"`), the model and provider, which attempt it was, and the token usage
-  RubyLLM reported. That is enough to attribute spend to a squishling method without any other tooling.
-- Cost in dollars comes from RubyLLM's model pricing. Multiply the reported tokens by your model's price, or read it
-  from RubyLLM directly (see [OpenTelemetry](#opentelemetry), or RubyLLM's `config.instrumenter`).
+  the adapter reported. That is enough to attribute spend to a squishling method without any other tooling.
+- A [token budget](failures.md#capping-a-calls-cost-token-budgets) (`max_total_output_tokens:`, `max_total_input_tokens:`)
+  caps what a single call may use across all its attempts, so a call that keeps failing can't spend without limit.
+- Cost in dollars isn't reported by Squishling's adapters. Multiply the reported tokens by your model's price, or, with
+  the RubyLLM adapter, read it from RubyLLM directly (see [OpenTelemetry](#opentelemetry), or RubyLLM's `config.instrumenter`).
 
 ## Deciding when to write the code
 
@@ -56,8 +58,8 @@ template each call belongs to; see [Coolhand Labs](coolhand.md).
 
 ### Custom: the `squawk` hook
 
-`config.squawk` runs after every LLM attempt, accepted or rejected, and is handed the method's label, the model,
-and the token usage RubyLLM reported. A lambda can take just the keywords it needs:
+`config.squawk` runs after every LLM attempt, accepted or rejected (unless you narrow it with `squawk_on:`, which makes token totals undercount, so keep `:all` for measuring), and is handed the method's label, the model,
+and the token usage the adapter reported. A lambda can take just the keywords it needs:
 
 ```ruby
 Squishling.configure do |config|
@@ -70,6 +72,10 @@ Squishling.configure do |config|
 end
 ```
 
+A call that stops on its [token budget](failures.md#capping-a-calls-cost-token-budgets) or a disagreement is also
+reported once, with `metadata[:stopped]` set (`:budget` or `:disagreement`) and no `usage`, so the hook above logs
+it with empty counts; check `metadata[:stopped]` to count it apart from an attempt.
+
 Each line carries the `"Class#method"` that made the call, so grouping by label gives you tokens per squishling. A call
 that stays in Ruby makes no LLM request and never reaches the hook, so a label that stops appearing is a path that has
 been hardened. You can also set the hook per class (`squishling squawk: ...`) or per method. See