hmbown--codewhale/docs/PREVIEW_REQUEST.md

# `/preview-request` — see the outbound request without sending it

`/preview-request` renders a **request manifest**: a typed, redacted
description of the request the next **primary agent turn** would send. It never
sends that request, never appends to the conversation, and never writes engine,
session, or Work state. `/dryrun` and `/preview_request` are compatibility
aliases.

It is a human command. There is deliberately no model-visible tool for it.

```
/preview-request                      # session facts; route/body reported unavailable
/preview-request json                 # same manifest as JSON
/preview-request --prompt <text>      # the next turn for that prompt
/preview-request json --prompt <text> # both
/preview-request base-prompt          # exact base layer only; no runtime additions
```

### Argument grammar

```
args   := flag* [ "--prompt" <whitespace> prompt ]
flag   := json | --json | manifest | --manifest | prompt | base-prompt | --base-prompt
prompt := every remaining byte, verbatim
```

**Flags come before `--prompt`, which is terminal.** Everything after it is
prompt text — including a trailing `json`. `/preview-request --prompt fix it
json` previews the prompt *"fix it json"* as a human table; the JSON spelling
is `/preview-request json --prompt fix it`. There is exactly one reading of any
input, and an unknown argument before `--prompt` is rejected rather than
guessed at.

**The prompt keeps your bytes.** Repeated whitespace and newlines inside it
survive; exactly one whitespace codepoint separates `--prompt` from its text
and is consumed as syntax. Any additional leading whitespace, plus all
trailing whitespace and newlines, remains prompt data. The prompt is hashed
into the previewed body, so normalizing it would describe a request that
differs from the real one in the one field you typed.

`prompt` remains a compatibility alias for the ordinary protected manifest.
`base-prompt` / `--base-prompt` are an explicit, human-only disclosure mode:
they print exactly the effective base-prompt bytes and nothing else. They
cannot be combined with JSON or `--prompt`. Effective system text is never
printed because it can contain project instructions, skills, and memory.

## `--prompt` is necessary for an exact manifest, and not always sufficient

The next user message is **part of the request**. Without it there is no
next-turn body to describe, and under auto model routing there is not even a
route: the route is decided by the text you have not typed yet.

So the manifest is sectioned, and each section is either exact or typed-absent:

| Section | Exact when |
| --- | --- |
| `session` | always — posture, gates, base-prompt provenance, requested model/reasoning |
| `route` | `--prompt` was supplied, an active goal has not exhausted its token budget, a fixed route is selected, no `message_submit` hooks are configured, and the shared planner resolved that route |
| `tools` | the route is exact **and** the MCP tool state can be snapshotted without connecting |
| `body` | the tool surface and authoritative Work snapshot are exact **and** no runtime transform would rewrite the request first |

### Why a section stops being exact

| Typed reason | What a real turn would do that an inspection may not |
| --- | --- |
| `auto-route-unresolved-until-next-prompt` | decide the route from text you have not typed |
| `auto-route-classification-not-executed` | call the provider-backed Auto classifier; preview is strictly offline, so production must resolve it |
| `no-hypothetical-prompt-supplied` | send a message the manifest does not have |
| `message-submit-hooks-not-executed` | run mutable hooks that can rewrite or block the text — and therefore the route, tool policy, and body derived from it |
| `prompt-resolution-failed` | fail the same way on skill authority or file mentions |
| `route-plan-failed` | fail route resolution or preflight |
| `mcp-state-not-snapshottable` | connect MCP servers and discover tools this catalog does not contain |
| `runtime-transforms-before-send` | auto-compact, run context-overflow recovery, inject a background-shell completion, allow a running or terminal-undelivered child to complete, or flush pending LSP diagnostics before the first request |
| `work-state-not-snapshottable` | read the current graph-backed Work projection; preview never substitutes an asynchronously published, potentially stale To-do view |
| `goal-token-budget-exhausted` | stop the active goal before dispatch because durable token usage has reached the configured budget |
| `goal-state-not-snapshottable` | decide whether the active goal's terminal budget gate permits another request |
| `request-preparation-failed` | build no body at all |

**`mcp-state-not-snapshottable` takes the body with it.** A catalog missing its
MCP contribution is not "the same request with no MCP tools" — a real turn
connects, and may send a different tool list, a different tool region, and
therefore a different body and hashes. The body inherits the tool
section's reason rather than publishing an exact hash of a request that would
never be sent. The `route` section survives: the endpoint, dialect, and wire
model do not depend on which tools are on the request.

**Detection is read-only.** Nothing is drained, received, flushed, or
compacted to find out: eligible running and terminal-undelivered children are checked, LSP blocks
are checked for emptiness, the shell manager is checked without polling or
marking completions reported, and the compaction decision is evaluated against
the borrowed hypothetical message list with its active slop gate pinned.
Inspecting the pending state does not consume it.

Without `--prompt` the route section is unavailable even on a fixed model.
That is deliberate: a route is only reported when it was resolved by the same
planner that would send the turn, for the same next message. A route that was
"probably still the current one" is exactly the kind of almost-true fact this
command exists to avoid.

An unavailable section publishes a typed reason and **no fields**. When auto
routing is unresolved there is no `provider_id`, `route_id`, `dialect`,
`endpoint_host_class`, `endpoint_fingerprint`, `wire_model`, `billing`,
`tool_surface_budget`, or `body_sha256` anywhere in the JSON — not a `null`,
not the previous turn's value. `requested_model` reads `auto`, because that is
what you actually selected.

## What runs, and what does not

With `--prompt`, the preview executes the **deterministic part of the
production path** up to (but not including) the send:

1. The prompt is resolved into model-facing content exactly as a real submit
   does — the pending active skill it would be wrapped with (**cloned**, not
   consumed), file mentions, git mentions, and the paused-command note — with
   the same error propagation. What a submit does that an inspection may not is
   run `message_submit` hooks; when any are configured the manifest says so and
   claims nothing downstream of the text.
2. For a fixed route, that content goes through the **same shared route
   planner** (`plan_turn_route`) that `spawned_dispatch_inner` uses for a real
   turn: effective provider and model, route identity resolution, preflight,
   route limits, compaction policy, and reasoning-effort normalization. Auto
   stops before this step because the planner would call a model classifier.
3. The engine projects the planned route into a throw-away client — the same
   client construction a turn installs, without installing it.
4. It rebuilds the tool catalog and narrows it with the same planner the turn
   loop uses, composes the system prompt **for that route's model and context
   window**, and appends the hypothetical user message through the same
   constructor production uses (turn metadata, route stamp, and provenance),
   then resolves an `auto` reasoning tier against
   those messages the way the turn loop does. Production sends stored history
   and nothing else — Codewhale does not re-state the To-do list on model
   steps — so the previewed outbound message list is exactly that list, and
   one estimate over stored messages plus system covers both the manifest
   number and the overflow decision.
5. It prepares the request through `DeepSeekClient::prepare_outbound_request`
   and describes the result — unless a runtime transform would rewrite it
   first, in which case the body is typed unavailable instead.

**Nothing is installed, not even briefly.** Everything a turn installs before
building its request — the command-scoped tool gate, the effective mode and
approval posture, the policy-narrowing event, the working set with the new
message observed — is passed as a value or snapshotted onto a clone. There is
no write-then-restore: a restore is not atomic across an `await`, and it does
not survive a cancellation or a panic. Terminal continuation state is read
without mutating its counters. A regression test
asserts that config, caches, session messages, model, system prompt, working
set, provider, mode, and the MCP pool are all byte-identical afterwards.

**No outbound call can happen.** With a fixed model, planning and request
preparation are local. With Auto selected, the command reports
`auto-route-classification-not-executed` and stops before the shared planner,
because resolving the route would call a model classifier. Preview never
reads or populates the classifier response cache and never changes provider
retry or rate-limit state.

**Nothing else has a side effect.** The tool-catalog build runs in a passive
mode: it never creates the MCP pool, calls `connect_all`, reloads an MCP config
source, starts a server, spawns a sub-agent runtime task, captures a fork
snapshot, or emits a UI status event. When the connected MCP state is not
already exactly what a turn would use — no pool yet, a config source changed,
or an enabled server is not connected — the `tools` section reports
`mcp-state-not-snapshottable` instead of connecting to find out.

## Scope: primary agent turns only

This manifest describes `LlmClient::create_message` /
`create_message_stream` — the model turns the agent loop runs. It does **not**
describe Codewhale's auxiliary provider calls, which have their own shapes:

| Auxiliary call | Status |
| --- | --- |
| Chat-dialect translation (`translate`) | **Not** on the prepared seam: it builds a small fixed body (no tools, temperature 0.1) directly. Out of scope. |
| Anthropic/Responses-dialect translation | Routed through `prepare_outbound_request` to avoid a second builder, but still an auxiliary call and still out of scope for this manifest. |
| FIM completion, speech, provider-native search, `/models` listing | Separate endpoints and bodies. Out of scope. |
| Auto-router classifier | A separate small turn on the router route. Out of scope and never executed by preview. |

Any claim that "every outbound request" goes through the previewed seam would
be false, and this document does not make one.

## Where the numbers come from

**The prepared outbound request.** Every primary model turn reaches the wire
through `DeepSeekClient::prepare_outbound_request`, which returns a
`PreparedOutboundRequest`: dialect, endpoint identity, canonical wire model,
the final body, and a reasoning receipt. Production dispatch sends that value;
the preview describes it. There is no second body builder.

Parity tests do not feed a captured logical request back through that builder.
They run a real production turn against an HTTP mock, parse the first body the
server actually received, canonicalize those captured bytes independently,
and compare that hash with preview. The coverage includes translated prompt
context, paused-command detach, and native Anthropic Messages shaping.

Preparation runs the full production sequence: tool-history repair and
model-bound secret redaction, protocol binding and route model re-resolution,
the dialect's own body builder with every provider-specific sanitizer and
reasoning shaper, and exact endpoint resolution.

Every production dialect is preserved end to end — nothing is projected
through Chat Completions:

| Dialect | Routes |
| --- | --- |
| `chat-completions` | DeepSeek, Moonshot/Kimi (including the Kimi Code K3 nested `thinking.effort` shape and the direct K3 fixed-sampling shape), Z.ai, xAI, OpenRouter, vLLM/Ollama/SGLang, OpenCode Zen chat routes, custom compatible endpoints |
| `anthropic-messages` | Anthropic, DeepSeek Messages, MiniMax Messages, OpenModel |
| `openai-responses` | OpenAI Codex (ChatGPT backend path), OpenCode Zen responses routes |

The manifest reports the dialect *and* the route shape
(`standard`, `deepseek-beta-strict-tools`, `kimi-code-k3`,
`direct-moonshot-k3`, `codex-responses`, `opencode-zen`,
`custom-compatible`), so you can see which builder branch actually ran.

**The engine.** The manifest is built by the engine, not the command layer,
because only the engine can rebuild the exact next-turn tool catalog, active
subset, gates, permission posture, and tool choice. The session's last tool
catalog is never consulted — it is one turn stale and stores the
pre-activation catalog.

## Streaming is reported as a wire fact

`caller_entrypoint` says which transport entry point was described
(`streaming` / `blocking`). `body_stream_field` says what the **body** says,
read off the finished JSON:

- Chat Completions streaming → `true`; Chat blocking → the field is absent
  (`null`), because the blocking body never carries it.
- Anthropic Messages → mirrors the caller.
- OpenAI Responses → **always `true`, including on the blocking entry point**,
  which opens an SSE stream and folds it into one response.

The manifest describes the body field exactly rather than inferring it from the
caller, so the Responses blocking case cannot be misreported as a non-streaming
request.

`tool_choice` is likewise read from the finished provider body, not the
logical request: Anthropic may carry an object, Responses carries its mapped
string, and DeepSeek thinking requests omit the field entirely.

## What the manifest tells you

| Section | Fields |
| --- | --- |
| `session` | exact primary-agent role/lane/Fleet non-assignment, requested model (`auto` when auto), routing mode, requested reasoning, whether a hypothetical prompt was supplied, mode, approval posture, allow/deny gate sizes, base-prompt origin + bytes + SHA-256 |
| `route` | provider id + display name, named route id, typed routing source, dialect, route shape, safe endpoint host class/digest, endpoint fingerprint, **wire model**, caller entrypoint, body `stream` field, context ceiling + source (`configured`, `provider-reported`, static floor, catalog, or fallback), route input/output limits or `unknown`, typed billing |
| `tools` | active count, catalog / deferred counts, logical catalog SHA-256, surface budget, Standard-vs-Full collapse, MCP servers and MCP tools |
| `body` | reasoning resolution + wire control keys + wire effort **and the key path it came from**, `tool_choice`, system-prompt assembly + effective canonical JSON bytes/SHA-256, body/system/tool-schema/message/tool-result/attachment/framing canonical JSON sizes, per-class estimates, exact input-budget ceiling and headroom, literal wire output cap or `unknown`, provider-reported usage explicitly unavailable because no request ran, **whole-body SHA-256**, wire tool-schema SHA-256, local system/tools component SHA-256 |

Counts and estimates are extracted **dialect-aware**: a Responses body's
`instructions`/`input`, an Anthropic body's `system`/`messages`, and a Chat
body's inline `system`-role message are each read from where that dialect
actually keeps them.

### The byte classes are an exact accounting, not byte slices

`system + tool_schemas + messages + framing == body_canonical_json_bytes`, exactly, in
every dialect and on both entry points. The first three are the canonical
serializations of selected JSON values; they are not four disjoint ranges
borrowed from the body buffer. **`framing` is the algebraic remainder** after
those selected values. It includes every other top-level field and whatever
JSON structure was not already counted inside a selected array value. An
invariant test asserts the sum identity, and mutation tests check the intended
attribution. Do not use these counts to reconstruct the request bytes.

`tool_result` and `attachment` bytes are *subsets* of the message bytes,
reported for attribution and never added again.

### Headroom is measured against the input budget

`estimated_input_headroom_tokens` subtracts production's conservative
messages-plus-system estimate from this route's
**input budget ceiling** — `context_input_budget_for_route`, the same seam the
turn loop checks before it sends, which is the context window minus the output
reservation and the safety headroom. It is not the raw `context_limit_tokens`:
subtracting input from a window the route also has to fit its response into
reports headroom the turn does not have. The value goes negative when the
request would not fit, rather than clamping to zero and reading as "it fits" —
and when it does, the body is reported unavailable, because the turn loop would
run context-overflow recovery and send something else.

This production gate is distinct from the manifest's independent conservative
estimate over canonical JSON body bytes. The latter remains useful for
provider-body attribution, but it does not decide overflow or headroom.

The manifest publishes that exact ceiling as `input_budget_ceiling_tokens`.
It also keeps three different limit facts separate: the context ceiling and
its resolver source, optional route/offering input and output limits, and the
output cap literally serialized on the wire. If a route or dialect supplies
no such fact, the value is `unknown`; preview never fabricates one from a
neighboring model or an installed route.

### Reasoning controls are read wherever the dialect puts them

`reasoning_wire_effort` reads the flat `reasoning_effort`, Kimi Code's nested
`thinking.effort`, the Responses `reasoning.effort`, and the Anthropic
`output_config.effort`, and `reasoning_wire_effort_source` names which one it
came from (a compile-time constant, never a key lifted out of the body).
Reporting only the flat key made the routes that think hardest read as "no
effort sent".

`reasoning_resolution` distinguishes an `explicit` user selection from a
`route-default` control the user never asked for, and reports
`not-applicable` when the body asks for no reasoning at all. A Responses
`include` field *discloses* reasoning output rather than requesting a tier, so
`include` alone is never reported as a reasoning request.

## The whole-body hash

`body_sha256` covers the complete canonicalized wire body, not a prefix. It
changes when any of these change: max-token fields, `tool_choice`, nested
reasoning controls, provider-transformed tool schemas, attachments, stream
options, sampling parameters, or any message — including the appended
hypothetical prompt. Canonicalization sorts object keys, so builder insertion
order alone does not move the hash. Any real input change does, including
date/working-set/git metadata, runtime injections, tool discovery, prompt
settings, or routing.

`tools.active_tool_catalog_sha256` is a separate, stable hash over the current
active tool catalog **before dialect shaping** (name, description, canonical
logical schema, in order). It moves on membership, ordering, and logical schema
changes. It is a catalog identity, not a wire fact: two routes can agree here
and still send different bytes, because each dialect transforms schemas its own
way and strict mode sanitizes them further.

`body.tool_schema_wire_sha256` is the hash of the `tools` region **as the
provider receives it**. `body.local_system_tools_component_sha256` combines
that digest with the final wire system-region digest as a local comparison
fingerprint. It is not a provider cache key, does not claim those regions are
adjacent, and carries no route-specific cache-semantics guarantee. It is
omitted when the tool surface is not exactly known.

## Disclosure boundary

The manifest is a fixed set of counts, hashes, enums, and short provenance
labels. It has no field that can hold free-form request text. It cannot
contain:

- the system prompt, project instructions, memory, or skill content;
- message content, tool-result bodies, or attachment payloads;
- credentials, `Authorization` headers, or query strings;
- URL paths (which can themselves carry a deployment secret);
- absolute workspace or home paths.

**Identifiers are not trusted either.** A custom route id and a model id are
user-authored text that can be an absolute path, a URL, a URL path, or a
deployment id that is itself a credential. Every such value crosses an
allowlist boundary (`crate::safe_label`) before it is printed: an
generic identifier is published verbatim only when it contains no slash. A
slash-bearing model id additionally has to match an exact entry in the active
local model catalog; a vendor-looking prefix is not sufficient. Anything else
is replaced by a stable `sha256:<12 hex>` fingerprint. Two previews of the same
hostile id still compare equal; the id itself is never shown.

**Error text is not trusted either, and is not scrubbed — it is
allowlisted.** Preflight, MCP, prompt-resolution, and request-preparation
failures all interpolate host text, and that text routinely carries a route id,
a server name in quotes, an endpoint whose *path* is the secret, or a raw
credential. Every whitespace-separated token has to earn its place:

- a token containing a control character is dropped;
- a URL keeps only `scheme://host[:port]`, and only when both are themselves
  ordinary — path, query, fragment, and userinfo are never published, and a
  token-shaped "host" makes the whole token opaque rather than half-published;
- anything path-shaped (POSIX absolute, `~/`, Windows drive, or containing a
  backslash) collapses to `<path-redacted>`;
- a token carrying `"`, `'`, or a backtick is replaced wholesale — quoted spans
  are where hostile identifiers hide;
- everything else must be a short ordinary word (ASCII alphanumerics plus
  `-`, `_`, `.`, bounded in length, rejected if it looks token- or key-shaped),
  with only sentence punctuation allowed at its edges.

Anything else becomes `<redacted>`, runs of redactions collapse, and the result
is truncated. Ordinary diagnostic sentences survive intact; hostile ones become
a generic shape.

Endpoints are published two ways only: a bounded host class (`http loopback`
or `https remote sha256:<12 hex>`) and a SHA-256 fingerprint of the full URL
for "same endpoint?" comparisons. A remote authority is always digested — it
may be a credential-shaped tenant subdomain — and paths, IDNs, userinfo,
queries, and fragments are never shown.

**This is an inspectability slice, not a request-body export.** A regression
test asserts that no manifest field carries a serialized message array or tool
schema.

## Estimates are estimates

Every token number is an **offline estimate** (~4 bytes/token plus a 5%
conservative margin), never a provider-authoritative count. Use them to
compare requests to each other, not to predict a bill. Byte counts, hashes,
and counts are exact.

Tool-result and attachment estimates are *subsets* of the message estimate and
are reported for attribution; they are not added again into the total.

## Base-prompt provenance (#3928)

The protected manifest distinguishes three things without printing effective
system text. The explicit `/preview-request base-prompt` mode separately prints
only the exact effective base-prompt bytes:

- **Origin** — where the base-prompt bytes came from:
  - `bundled in this codewhale-tui build (BASE_PROMPT, compiled in)`
  - `config-directory override installed at startup (prompts/constitution.md,
    opt-in enabled)`
- **Assembly** — how the effective prompt was built on top of that base:
  `base prompt only`, `base prompt + configured static layers`, or
  `base prompt + configured layers + runtime/session additions`.
- **Effective hash** — the SHA-256 of the system region of the *prepared
  request*: the prompt in its final wire form, not an independently
  recomposed string.

In a live session the assembly is normally
`base prompt + configured layers + runtime/session additions`, because the
environment block, project context, skills, and memory are appended after the
constitution. Codewhale does not claim the configured constitution is the
effective base prompt, and no diagnostic cites a source-tree path that does not
exist on an installed binary.

## Tool-surface labels

`standard_and_full_surfaces_collapsed` is **derived, not asserted**: the
surface shaper is run over the actual current catalog under both the Standard
and the Full budget and the results are compared. Today it reports `true`
— the two budgets produce the same catalog — and the manifest says so in
plain words rather than implying a difference. The day the shaper narrows
Standard differently from Full, the field flips on its own with no copy edit.

Any benchmark claim about one surface offering "more tools" has to show a
different `active_tool_catalog_sha256` first.

## Comparing routes before you spend anything

`/preview-request` makes a provider-free fixed-route A/B possible: switch route,
preview with the same prompt, compare.

1. Select the route (`/model`, `/provider`, or your profile) — do not send a
   turn.
2. Run `/preview-request json --prompt "<the same text each time>"` and save
   the output, e.g. `glm-5.2.json`.
3. Repeat for each route.
4. Diff the manifests.

What to read in the diff:

- **`route.dialect` / `route.route_shape`** — two routes on different dialects
  are sending structurally different requests, not the same request to a
  different host.
- **`route.wire_model`** — the id that actually goes on the wire. Router
  entries frequently differ from the label you selected.
- **`tools.active_tool_count` / `body.tool_schema_wire_sha256`** — identical
  wire hashes mean identical tool bytes, whatever the surface label says. Use
  `tools.active_tool_catalog_sha256` only to compare *logical* catalogs; two
  dialects can agree there and still send different schemas.
- **`body.estimates.tool_schemas` vs `route.context_limit_tokens`** — the fixed
  overhead each route pays before the conversation starts, against the window
  it has.
- **`body.reasoning_wire_control_keys` / `body.reasoning_wire_effort` /
  `body.reasoning_resolution`** — whether the route is actually being asked to
  think, in which dialect, and whether that came from you or from auto
  routing. Two routes with different effective effort are not comparable.
- **`body.body_sha256`** — the whole request. If it is unchanged, nothing about
  the outbound bytes changed.
- **`body.local_system_tools_component_sha256`** — whether the two locally
  measured wire components changed. It does not prove provider cache reuse or
  invalidation.
- **`route.billing`** — subscription quota and metered API routes are not
  cost-comparable, and `unknown` means cost reporting fails closed.

Each manifest is exact for the snapshot it describes. Repeated previews are
identical only when every contributing input is identical: route, current
date, git and working-set metadata, prompt settings, tool/MCP
state, session history, and pending runtime transforms. Previewing does not
mutate session history or the response cache, but no cross-call byte-stability
claim is made. Auto is intentionally unavailable and cannot be used for this
comparison until production resolves a concrete route.

`schema_version` is bumped whenever a field is renamed or removed, so scripted
consumers can detect an incompatible manifest instead of silently reading
`null`. The current shape is `9`: v8's `work-state-not-snapshottable`
unavailable reason is gone, because no request carries a To-do block for a
snapshot to fail on. The active goal token-budget terminal gate remains an
explicit fail-closed dependency of an exact outbound request.

## What is still approximate

Auto routing is not approximated: its provider-backed classifier is never run
by preview, and the route-dependent sections are typed unavailable instead.

Working-set drift used to be listed here. It no longer applies: a real submit
calls `working_set.observe_user_message` before it builds `<turn_meta>`, and
the preview now performs that same observation on a **clone** of the working
set and builds the block from that snapshot. Same bytes, no session write.

Everything else that used to be "approximate" is now typed. If a runtime
transform would change the request, the body section says so and publishes no
bytes at all, rather than publishing numbers that are nearly right.

## Credit

The `dryrun` concept — preview the next request from the real request-building
seam rather than a hand-rolled summary — was harvested from PR #1099 by
[@GTC2080](https://github.com/GTC2080) (TaoMu). No code from that PR is
reused; the implementation here is written against Codewhale's current
multi-dialect client.