Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

docs(catalog): document the wire reader, model-spec markers and custom wire

Jack Rudenko9bde383b1e92
diff --git a/CLAUDE.md b/CLAUDE.md
index e9b88623..63560378 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10,6 +10,7 @@ lives in `ROADMAP.md`.
## Where the rationale lives — all files below are in `ai-docs/architecture/`
- `routing.md` — `provider@model` syntax, every provider prefix, catalog-gathered route candidates and their tier order, `defaultProvider` as the fallback position, the derived picker provider list, `SUBSCRIPTION_PROVIDERS`, local models
+- `wire.md` — every request built from the connection's catalog `wire` + route registry (no model-name rules anywhere); clamp / borrow-and-drop / try-in-turn; the first-run refusal trap; `+pro` vs the `+` chain separator; custom endpoints' declared wire; read before touching `connection-*.ts`, `wire-*.ts`, step 5w, or any limit/reasoning field
- `adapters.md` — Layers 1–3, stream parsers, error classification and retry, the 400 remap, why Gemini tool schemas need `items` on every array
- `network-recovery.md` — the two-tier connection hold: the DERIVED deadline (`API_TIMEOUT_MS`, not a
watchdog), why tier 2 answers 503 and never 429, why the banner is magmux's `overlay` and never a
diff --git a/ai-docs/architecture/README.md b/ai-docs/architecture/README.md
index 85e1ba1e..0da7a4d2 100644
--- a/ai-docs/architecture/README.md
+++ b/ai-docs/architecture/README.md
@@ -26,6 +26,7 @@ three earlier write-ups this material cites were lost.
| [`predefined-endpoints.md`](predefined-endpoints.md) | The 25-vendor bundled catalog: credential-gated activation, the single registration seam, evidence tiers (all `probe`, none `live`), and the no-model-data rule | add a vendor to `providers/predefined-catalog.ts`, or change endpoint registration |
| [`onepassword.md`](onepassword.md) | SDK-only secret resolution, the FOUR causes of an identical denial error, the cross-process handshake lock, parent-side route pinning, and the config TUI tab | touch `providers/onepassword*.ts`, credential pre-hydration, or the 1Password TUI tab |
| [`keychain.md`](keychain.md) | The macOS Keychain backend: the 17ms-vs-28ms measurement that split presence from values, the two `security` behaviours that are traps (hex reads, a "secure" write that stores nothing and exits 0), and why no new `CredentialSource` member | touch `providers/keychain.ts`, `keychain-source.ts`, or the Providers tab's key write/delete |
+| [`wire.md`](wire.md) | Every request from the connection's catalog `wire` and the route registry: the four-step pipeline, Jack's decisions where they diverge from the backend spec (clamp, borrow-and-drop, try in turn), the first-run refusal that stuck for a session, `+` doubling as the chain separator, name gates one layer down, custom endpoints' declared wire, the advisor and discovery on registry hosts | touch `connection-*.ts`, `wire-*.ts`, `declared-wire.ts`, `ComposedHandler` step 5w, an adapter's limit or reasoning fields, the advisor's request, or `+`/`#` model-spec markers |
| [`adapters.md`](adapters.md) | Layers 1–3 (FormatConverter / ModelTranslator / ProviderTransport), stream-parser selection, errors that ride an HTTP 200, and the `upstream_status` remap with its downstream readers | add a provider, model translator, or stream parser; or change error classification and retry |
| [`network-recovery.md`](network-recovery.md) | The two-tier connection hold: why the deadline is DERIVED from `API_TIMEOUT_MS` (measured 359.607 s, a default and not a watchdog), why the tier-2 status is 503 and never 429, why the banner is magmux's `overlay` and never a pane of ours (closing a pane wedged Claude Code), why its lease is renewed on its own tick and not by ladder events, the five sites where a network failure wore an auth status code, and why a pane child gets no watchdog | touch the retry ladder, `recovery/`, the tier-2 status, the recovery banner, or any `x-claudish-recovery` reader |
| [`behavior-layer.md`](behavior-layer.md) | Layer 4, the harness-convention SUPERVISOR: the rule engine, the four hooks, the 115-call plan-mode measurement it was built on, and opt-in telemetry | write a `behavior/` rule, or change harness-conformance handling |
diff --git a/ai-docs/architecture/adapters.md b/ai-docs/architecture/adapters.md
index b25249f9..eeedecba 100644
--- a/ai-docs/architecture/adapters.md
+++ b/ai-docs/architecture/adapters.md
@@ -438,6 +438,11 @@ The exclusion rested on "a 503 cannot silently switch the user off a pinned mode
## The catalog's endpoint contract has two halves (v9.0.7)
+> **Superseded (10.5.0).** The gate, the name rule and the model-level `tokenParam` read
+> described here are deleted. Every request is now built from its connection's `wire`
+> ([`wire.md`](wire.md)). Kept for the history of why reading half a contract is worse
+> than reading none.
+
`gpt-6-astra` was in the catalog and could not run. The child exited 1 on
```
diff --git a/ai-docs/architecture/custom-endpoints.md b/ai-docs/architecture/custom-endpoints.md
index acbd978a..3797241a 100644
--- a/ai-docs/architecture/custom-endpoints.md
+++ b/ai-docs/architecture/custom-endpoints.md
@@ -110,3 +110,19 @@ edit rather than a hunt for ternaries.
Verified live against a header-inspecting mock — `authorization: null`, `x-api-key` **absent
from the request entirely** (not empty), and a declared `headers: {"X-Team":"platform"}` still
delivered, since for some gateways a custom header IS the credential.
+
+## The declared wire (v10.5.0)
+
+A custom endpoint has no catalog connection, so until v10.5.0 its request shape came from the
+model NAME: a name-picked dialect (`enable_thinking` for anything matching `qwen`, a `thinking`
+toggle for `glm-N.M ≥ 4.5`) and `OpenAIAPIFormat`'s `gpt-5`/`o1`/`o3`/`o4` token-field rule. That
+is the guessing the catalog wire reader removed everywhere else ([`wire.md`](wire.md)).
+
+An endpoint now declares a `wire` block (`CustomEndpointWireSchema`) in the catalog's own
+vocabulary, and `declared-wire.ts` turns it into a connection that goes through the same step 5w
+as a catalog connection. With no block the documented defaults apply: the transport's API,
+`max_tokens` (`max_output_tokens` on Responses), and no reasoning field. The schema refuses a
+`wire.api` the transport cannot speak (Messages on `openai`, Chat on `anthropic`).
+
+Bundled vendors with a catalog route (`together`, `fireworks`) are built from the catalog wire
+first; the other bundled rows take the declared defaults.
diff --git a/ai-docs/architecture/wire.md b/ai-docs/architecture/wire.md
new file mode 100644
index 00000000..17c52c69
--- /dev/null
+++ b/ai-docs/architecture/wire.md
@@ -0,0 +1,119 @@
+# The wire reader: every request from the connection's `wire`
+
+> How claudish decides the API, URL, output-limit field, reasoning encoding, mode and speed of
+> a request: from the catalog's per-connection `wire` and the route registry, never from a
+> model name. Read before touching `providers/connection-*.ts`, `providers/wire-*.ts`,
+> `providers/declared-wire.ts`, `ComposedHandler` step 5w, an adapter's token or reasoning
+> fields, or the advisor's request building.
+
+Spec: Models Index `ai-docs/claudish-wire-requirements.md` (R1–R13) and
+`ai-docs/claudish-catalog-3.7.0.md`. Plan and gap counts: `ai-docs/reports/wire-reader-plan-20261012.md`.
+
+## Why it exists
+
+Catalog 3.7.0 (live 2026-10-08) changed what the model-level `tokenParam` and `endpoints` mean:
+they now describe the model OWNER's direct connection only. claudish 10.4.1 applied the
+model-level field to every chat body on every host, so GPT and Grok chat requests to gateways
+carried `max_output_tokens` (a Responses-only field): about 150 chat connections on generation
+`g-20261012101007285-7770c36e`; `[email protected]` answered 400. Before that, months of
+regressions came from name rules (`requiresResponsesApi`, `includes("codex")`, OpenCode family
+lists, effort ladders by `gpt-5.x`) being falsified by each new model release.
+
+## The pipeline
+
+1. **Data** (`all-models-cache.ts`, `catalog-client.ts`). The refresh reads the slim model pages,
+ the plans, and `queryModels?catalog=routes&generationId=<same>`; a different generationId
+ restarts the whole refresh once. A 3.7.0 cache is rejected whole if any mapped connection lacks
+ a wire, names a missing route profile, or has a known API without a base URL — a partial wire
+ table would send some requests from data and the rest from nothing. Reads are memoized by mtime
+ and size: the request path reads the 2.7 MB file per request.
+2. **Connection** (`connection-resolver.ts`). The provider's exact route binding plus the exact
+ wire id; never a family or sibling. It carries the wire, the registry profile, the model's
+ VENDOR (catalog `provider`) and the owner's direct-connection wire.
+3. **Handler** (`wire-handler.ts`, from `createHandlerForProvider` before any profile). Adapter by
+ `wire.api`, URL from the registry (a user base-URL override is kept and logged), the provider's
+ own transport only for auth and identity headers (Codex keeps its credential-decided host:
+ OAuth → chatgpt.com, API key → api.openai.com).
+4. **Request** (`ComposedHandler` step 5w → `wire-request.ts`). After every adapter has run, every
+ field any of them may have emitted for the limit, reasoning, mode or speed is removed, then the
+ wire's values are written at their RFC 6901 pointers.
+
+## Decisions (Jack, 2026-10-12) and where they diverge from the backend spec
+
+| Topic | Backend spec | claudish |
+|---|---|---|
+| Effort not in `effort.values` | refuse | clamp to the nearest published value, ties up |
+| `tokenParam` / `reasoning` `unknown` | send nothing | try the owner's direct-connection value when it is on the SAME API; drop exactly those borrowed fields on the 400 that names them (`recoverBorrowedWireFields`) |
+| `wire.status: unknown`, or model not published for the provider | APIs in fixed order | same (`TryInTurnHandler`): advance only on 404/405/protocol-400, remember the winner per generation |
+| No catalog | wait or fail | local providers only; catalog providers wait, then refuse per request (below) |
+| Pro / speed | `--mode`, `--speed` suggested | `model+pro`, `model#fast` |
+
+`not_applicable` is an ANSWER, never borrowed over (Codex found the shaper treating it like
+`unknown`). Mode and speed are never borrowed: they carry entitlement and price.
+
+## Traps
+
+- **Older claudish erases the registry.** Releases before 10.5.0 rewrite
+ `cloud-models-catalog-v3.json` on every refresh without `routeRegistry` (measured 2026-10-14:
+ an installed 10.4.1 in another session replaced the cache with a newer generation). The
+ registry therefore also lives in a sidecar, `cloud-models-catalog-v3.routes.json`, attached on
+ read when its generation matches; when it does not, `ensureRouteRegistryReady` fetches only
+ `catalog=routes` for the cache's generation (1.4 s live, against 9.3 s for a full refresh).
+- **The first run after an upgrade.** The old cache has no registry; the refresh that writes it
+ measured 9.3 s, and the request path first waited 5 s and refused. The proxy caches handlers
+ per model, so the refusal stuck for the whole session (`--probe gpt-6-sol` refused cx@, oai@ and
+ zen@ while grok-4.7, built after the refresh, answered). Now: 30 s wait, then
+ `CatalogPendingHandler`, which rebuilds per request and refuses only while the catalog is still
+ missing. Never return a cached refusal for a transient state.
+- **`+` is ALSO the route-chain separator** (`team` spawns `zgo@x+mm@y+or@z`). `parseModelChain`
+ attaches a segment that is only a mode word to the spec before it; real chain elements always
+ contain `@`. `-pro` (102 ids) and `-fast` (22) are real model ids; `>>` and `|` are shell
+ operators (an unquoted `>>fast` silently redirects to a file). `#` is literal mid-word in bash
+ and default zsh; with zsh `extendedglob` it fails loudly ("no matches found").
+- **Markers travel per request** (`wireMarkerContext`, AsyncLocalStorage), never in a cached
+ handler or a body: the native passthrough forwards the body verbatim.
+- **A name gate one layer down.** Removing the dialect choice left two: the shared message
+ converter added the Grok tool prompt for any id containing "grok", and the Gemini
+ thought-signature middleware re-filtered itself by name after being selected from data. Both
+ now read the connection's vendor (`setUpstreamVendor`, `alwaysHandle`). Search for the NAME
+ check at every layer, not just the selector.
+- **Codex's reasoning summary.** The wire does not publish `reasoning.summary`; the shaper drops
+ the whole `reasoning` object. Claude Code's visible thinking needs it, so the Codex transport
+ restores `summary: "auto"` where reasoning was sent.
+- **Kimi Code `k3`.** Its `disable` is served by K2.8 Preview (`served_model_changes`). Reasoning
+ stays on and the log says why, unless `--accept-served-model` (env
+ `CLAUDISH_ACCEPT_SERVED_MODEL=1`) names the swap.
+
+## Off-catalog requests
+
+- **Custom endpoints** declare their wire (`config-schema.ts` `CustomEndpointWireSchema`); the
+ documented default is the transport's API, `max_tokens` (`max_output_tokens` on Responses), no
+ reasoning. They go through step 5w like a catalog connection (`declared-wire.ts`). LiteLLM and
+ OpenRouter/Poe models the catalog does not publish get the same default.
+- **Dynamic subscriptions** (`gk@`, `ag@`, `dv@`) publish no wire; the account decides what they
+ serve. Only `gk@` names a dialect, explicitly in its profile (Grok effort with learn-on-400).
+ Nothing picks a dialect by model name any more; `dialect-manager.ts` serves local models only.
+ One model quirk no wire field describes stays, keyed on the catalog VENDOR: a `minimax` model
+ on any connection gets the MiniMax dialect for its temperature clamp (its reasoning fields are
+ overwritten by step 5w). Dropping it with the name dialects was caught in test review.
+- **The advisor** resolves the same connection, follows `wire.api` (Chat, Responses, Messages or
+ Gemini, non-streamed), takes its URL from the registry and shapes the body with the same step.
+ The provider docs' endpoints remain only as the cold-catalog fallback, logged when used.
+- **Discovery** (`model-discovery.ts`) lists models from the registry base + `/models` for a
+ catalog-routed provider (OpenCode moved Zen to `opencode.ai/inference/v1` on 2026-10-12);
+ a user base-URL override keeps the definition's path.
+- **Vision** with a connection reads the catalog's `inputModalities` / `supportsVision`; unknown
+ sends the image the user attached.
+
+## Verification on record
+
+- 1770 mapped connections on generation `g-20261012101007285-7770c36e`: every one carries a wire,
+ every known API has a base URL, the registry covers every claudish route binding.
+- Intercepted end-to-end capture of 19 connections, each body exactly the wire's
+ (`ai-docs/sessions/…/p3-capture.ts`, gitignored).
+- Live `--probe` (2026-10-12): every funded hop answered — `oai@gpt-6-sol` on `/v1/responses`,
+ `[email protected]` on Responses, `kc@` on `api.kimi.ai`, `oc@` on `ollama.com/v1` with plain ids,
+ `qtoken@` on the qwencloud host, `[email protected]` with `max_tokens`. Zen and Together
+ answered 402 (account funds).
+- `providers/no-name-rules.test.ts` scans every non-test source file (NUL-safe: `devin.ts` and
+ `grok-effort-support.ts` contain NUL bytes) for the removed identifiers.
diff --git a/docs/settings-reference.md b/docs/settings-reference.md
index bedc7aa1..f6f54338 100644
--- a/docs/settings-reference.md
+++ b/docs/settings-reference.md
@@ -22,6 +22,7 @@ All flags recognized by `parseArgs()` in `packages/cli/src/cli.ts`.
| `--model` | `-m` | string | none (prompts interactively) | Model to use. Accepts `provider@model` syntax, legacy `prefix/model`, or bare model name for auto-detection |
| `--default-provider` | | string | none | Default provider for auto-routing (v7.0.0+). Overrides env var and config file. Valid: built-in provider names or custom endpoint names |
| `--config` | | path | none | Use this file as the run's ONLY config, replacing both the global and project config. Consumed before `parseArgs()` — see [Config File Override](#44-config-file-override---config) |
+| `--accept-served-model` | | boolean | false | Allow a reasoning-off that the connection serves with a DIFFERENT model (catalog `served_model_changes`; e.g. Kimi Code `k3`: thinking off is served by K2.8 Preview). Without it reasoning stays on and the log says why. Env: `CLAUDISH_ACCEPT_SERVED_MODEL=1` (v10.5.0+) |
| `--model-opus` | | string | none | Model for Opus role (planning, complex tasks) |
| `--model-sonnet` | | string | none | Model for Sonnet role (default coding) |
| `--model-haiku` | | string | none | Model for Haiku role (fast tasks, background) |
@@ -425,6 +426,21 @@ ll@my-model # LiteLLM proxy with auto catalog resolution
Provider part is **case-insensitive**. Shortcuts are resolved to canonical provider names.
+**Request mode and speed markers (v10.5.0+).** A model spec may end in `+pro` and/or
+`#<speed>` (`fast`, `priority`, `flex`, `ultrafast`, `standard`):
+
+```
+cx@gpt-6-sol+pro # reasoning mode pro
+oai@gpt-6-sol#fast # fast speed tier (sent as the connection's native value, e.g. service_tier=priority)
+oai@gpt-6-sol+pro#flex # both, in either order
+```
+
+A marker is only a REQUEST. Each catalog connection publishes which modes and speeds it offers
+(`claudish --probe <model>` prints them); a value the connection does not offer is refused with
+the list it does offer, never silently dropped or guessed. A faster tier can bill at a higher
+rate. The markers need a catalog connection (or a custom endpoint); they are refused elsewhere.
+`-pro`/`-fast` are NOT markers: `gpt-6-sol-pro` and `kimi-k3-fast` are separate models.
+
### 5.2 Provider Shortcuts
#### Remote Providers
@@ -669,6 +685,7 @@ For OpenAI- or Anthropic-compatible servers:
| `authScheme` | `"bearer"`, `"x-api-key"` or `"none"` | no | Auth header scheme (default: `bearer`) |
| `modelPrefix` | string | no | Prepended to model name before sending to API |
| `models` | string[] | no | Restrict to listed models; omit to allow any |
+| `wire` | object | no | How requests are built — see **Declaring the wire** below |
Usage: `claudish --model [email protected] "task"`
@@ -729,6 +746,38 @@ Full control over transport, auth, headers, and stream format:
| `streamFormat` | string | no | Stream parser override (e.g., `"openai-sse"`, `"anthropic-sse"`) |
| `modelPrefix` | string | no | Prepended to model name |
| `models` | string[] | no | Restrict to listed models |
+| `wire` | object | no | How requests are built — see **Declaring the wire** below |
+
+### Declaring the wire (v10.5.0+)
+
+claudish never chooses a request's output-limit field or reasoning parameters from the model
+name. A catalog provider gets them from the cloud models catalog; a custom endpoint gets them
+from its `wire` block, or from these documented defaults:
+
+| Field | Default | Meaning |
+|-------|---------|---------|
+| `api` | the transport's API | `"chat-completions"`, `"responses"` (openai transport only) or `"anthropic-messages"` |
+| `tokenParam` | `max_tokens` (`max_output_tokens` on Responses) | The output-limit field; `"none"` sends no limit |
+| `reasoning` | nothing sent | `effort: { path, values?, default? }`, `enable: [{path, value}]`, `disable: [{path, value}]` |
+
+Paths are RFC 6901 pointers into the request body. `effort.values` maps claudish's effort
+names (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`) to the endpoint's own values;
+when omitted, the names are sent as they are. A requested effort the endpoint does not list is
+clamped to the nearest one it does. Example for a vLLM server running a Qwen thinking model:
+
+```json
+"wire": {
+ "tokenParam": "max_tokens",
+ "reasoning": {
+ "enable": [{ "path": "/chat_template_kwargs/enable_thinking", "value": true }],
+ "disable": [{ "path": "/chat_template_kwargs/enable_thinking", "value": false }]
+ }
+}
+```
+
+Before v10.5.0 claudish picked these from the model name (a Qwen name got `enable_thinking`,
+a `gpt-5` name got `max_completion_tokens`); such an endpoint now needs the block above, or
+`--model-params`, to keep that behaviour.
### Environment variable expansion