squishling 0.3.0 → 0.5.0

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,16 +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_harness` | `nil` (`:escalation`) | How every squishling class that doesn't declare its own uses its escalation: `:escalation`, `:squishsum`, `:judged_squishsum`, `:ensemble`, `:judged_ensemble`, or a Hash with `type:` and options. See [Harnesses](harnesses.md). |
+| `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`) 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). 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
@@ -62,21 +69,71 @@ Each step is a model name, or a Hash with:
 |---|---|---|
 | `model:` | required | The model id. |
 | `attempts:` | `1` | How many attempts this step gets before escalating to the next one. |
-| `order:` | position | An Integer; steps run lowest first. Give every step an `order:` or none (duplicates are rejected). Gaps are fine. |
+| `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. |
 
-Without `order:`, steps run in the order written. With it, the order is explicit and doesn't depend on position:
+Without `priority:`, steps run in the order written. With it, the order is explicit and doesn't depend on position:
 
 ```ruby
 squishling escalation: [
-  { model: "claude-opus-5-5",   order: 20, params: { thinking: { effort: :high } } },
-  { model: "claude-haiku-4-5",  order: 0, attempts: 2 },
-  { model: "claude-sonnet-5-5", order: 10 }
+  { model: "claude-opus-5-5",   priority: 30, params: { thinking: { effort: :high } } },
+  { model: "claude-haiku-4-5",  priority: 10, attempts: 2 },
+  { model: "gemma-4b",          priority: 10 },
+  { model: "claude-sonnet-5-5", priority: 20 }
 ]
 ```
 
+**Best practice:** number priorities 10, 20, 30, and so on, so a model can be slotted in between later (a `15`)
+without renumbering the rest. Haiku and Gemma share the lowest priority here, so they take turns going first (see below).
+
+### Rotating models within a priority
+
+Give several models the same `priority:` and they share a tier. Each call rotates which of them goes first, so
+every model gets an even share of the real work over many calls, a fair test of how well each handles it:
+
+```ruby
+squishling escalation: [
+  { model: "claude-haiku-4-5",  priority: 10 },
+  { model: "gemma-4b",          priority: 10 },
+  { model: "claude-sonnet-5-5", priority: 20 }
+]
+# call 1: haiku, gemma-4b, sonnet    call 2: gemma-4b, haiku, sonnet    call 3: haiku, gemma-4b, sonnet
+```
+
+- If the model that goes first fails (invalid output or a provider failure, after its own `attempts:`), the other
+  models in the tier are tried, in rotated order, before the call escalates to the next priority.
+- Each class and method counts its own calls (`AClass#a`, `AClass#b` and `BClass#a` rotate independently), shared across
+  threads, but not across processes: each process (a Puma worker, say) starts its own count at the first model, and it
+  restarts with the process. A `squish!` whose own escalation has a rotating tier counts against its method too.
+- A tier rotates by its declared order, so ties keep the order they were written in. A tier with a single model
+  never rotates, and neither does an escalation without `priority:`. `rotate: false` on any step of a tier keeps the
+  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
@@ -93,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
@@ -109,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:
 
@@ -159,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.
@@ -176,8 +240,8 @@ 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
+- 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`, `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
@@ -195,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.
 
@@ -205,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/coolhand.md

@@ -0,0 +1,66 @@
+# Coolhand Labs
+
+Squishling ships an [observer](observers.md) for [Coolhand Labs](https://coolhandlabs.com/). With it, every LLM call a
+squished method makes is filed under a named **workload** and **template** in Coolhand. Squishling knows exactly
+where each call sits (which method, which escalation level, which sample, which judge), so it declares that for you.
+
+## Setup
+
+Add and configure the [`coolhand`](https://github.com/Coolhand-Labs/coolhand-ruby) gem as described in
+[Measuring token spend](measuring-tokens.md#coolhand-labs). **That's all.** Squishling defaults to the Coolhand
+observer whenever Coolhand is already available in your codebase: loaded, with an `api_key`, and not disabled
+(`config.enabled = false`). Nothing is added to Squishling's dependencies, and nothing happens when the gem isn't
+there. It needs a version of the `coolhand` gem that has `Coolhand.with_context` (declared workloads); with an older
+one, the observer stays off.
+
+To turn it off, set `observer` to `false`:
+
+```ruby
+Squishling.configure do |config|
+  config.observer = false # never declare, even though Coolhand is configured
+end
+```
+
+The other settings:
+
+```ruby
+Squishling.configure do |config|
+  config.observer = :coolhand # always declare; raises ConfigurationError now if the gem is missing or too old
+  config.observer = nil       # the default: declare when Coolhand is loaded and configured
+end
+```
+
+To report somewhere else, or as well, use any [other observer](observers.md). `config.observer` holds one.
+
+## What is declared
+
+Each request runs inside `Coolhand.with_context(reporter: "squishling", workload: ..., template: ...)`, so Coolhand's
+Net::HTTP interception tags it with the declaration.
+
+| | Key | Name |
+|---|---|---|
+| Workload | `Class#method` | `Class#method` (its `description` is `Class#method`, or `Class#method (rescue)` when a [`squish!`](routing.md#handing-off-to-the-llm-with-squish) call handed it to the LLM) |
+| Template | `Class#method/<role>` | `Class#method · <role>` |
+
+`<role>` is where the request sits:
+
+| Role | Request |
+|---|---|
+| `squish:L<n>` | Attempt *n* (1-based) of the [escalation](configuration.md#models-and-escalation), counting each attempt of each step (a [custom harness](harnesses.md#custom-harnesses) that escalates stage by stage restarts at L1 for each) |
+| `sample:a`, `sample:b`, ... | A [squishsum](harnesses.md) sample (which runs on a worker thread; the declaration is made on that thread) |
+| `judge` | A harness's judge, chat or System One (all of a judge's attempts share this one template) |
+
+So `Parser#call/squish:L2` is the second attempt of `Parser#call`, e.g. `Parser#call · squish L2` in Coolhand.
+
+- The model is deliberately not in the key. It is on the log, and the position is the stable identity.
+- Repeated attempts on the same step count as separate levels, because the level is the attempt's position in the
+  expanded escalation.
+- A class name long enough to push a key past Coolhand's 255-character limit is left undeclared rather than
+  breaking the call.
+- Squishling's declaration is made inside any `Coolhand.with_context` you wrapped around the call, so for the fields it
+  sets, Squishling's wins.
+- The description never contains the purpose text, which can be a proc that differs per call. The workload's key
+  and name stay `Class#method` either way, so calls that went through `squish!` and calls that didn't share one
+  workload.
+- `observer = :coolhand` loads the gem when it is assigned, so assign it after `coolhand` is available (the default
+  needs no ordering).

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`. |
+| 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 the original exception as its `cause` (when the adapter has one: the RubyLLM adapter always does; the OpenAI-compatible adapter for transport errors, not for HTTP statuses). |
 | 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` with the provider's message and the params in use. 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` |
+| Provider rejects the request (400 Bad Request), 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 on `cause` when the adapter has one (RubyLLM's does; with the OpenAI-compatible adapter `cause` carries only the status). It is never retried, so if you know a given code means "this input was bad", rescue it and decide for yourself. 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` |
-| With a [squishsum or ensemble 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` |
+| 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,25 +59,92 @@ 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, plus a 400'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, so it stays on `cause` (`error.cause.message`) for you to read or log deliberately.
 - 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).
 
+## 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 does nothing unless you
+set it:
 
 ```ruby
 Squishling.configure do |config|
@@ -69,17 +158,36 @@ end
 |---|---|
 | `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) |
+| `metadata` | `label` (`"Class#method"`), `attempt`, `attempts` (the escalation's length; `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`) |
 
 - 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
   code, so rescue inside the hook if an outage in your tracing tool shouldn't.
 - `output` is the same object the result is built from, so treat it as read-only.
-- Under a [harness](harnesses.md), it runs for every sample and judge attempt too, each with its own `input`.
+- Under a [harness](harnesses.md), it runs for every sample and judge attempt too, each with its own `input`, and
+  `role`/`sample` say which one it was. A [custom harness](harnesses.md#reporting-to-squawk) reports the same way.
 - 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).
 
@@ -116,17 +224,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 (400, 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 or ensemble 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::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::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 the original, 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