Models and harnesses

When a codon's model field is set in hank.json, that one spelling decides several things at once: which model actually runs, which in-process runner (the harness) sends the work, which credential pays for it, and what it costs. This page is the lookup surface for those decisions. It lists the 30 spellings verified for this release with their routes, prices, and capabilities, explains the two harnesses and the dispatch rule that picks between them, walks through each spelling form, and shows how to check a model locally before a run spends money. The resolution grammar and failure formats live on the linked reference pages; this page stays with the verified data and the practical consequences.

Model spellings and verification#

A codon is one sealed agent task, and its model spelling determines the route shown in the table below. The 30 spellings come from the shipped registry and the Pi catalog, and they cover seven tiers: Frontier reasoning (6), Workhorse (5), Fast and cheap (6), Open-weight via Baseten (3), Open-weight via OpenRouter (5), Subscription-backed (3), and Amazon Bedrock (2).

Two catalogs sit behind these rows. Hankweave's shipped registry contains 7,436 models across 213 providers; the embedded Pi coding agent's catalog covers 39 providers (pi-ai@0.85.1 inside the artifact). The registry supplies model and price data when it has the resolved provider/id; Pi's catalog supplies fallback data and the startup gate for Pi-routed models. A model in neither source cannot be selected. The curated table selects the spellings, prices, context limits, and harness routes checked for this release rather than listing every model in either catalog. Its selection was audit-screened: the final audit passed with no P0, P1, or P2 issue across the 30 rows.

The registry behind the table was refreshed for this release. [changed 0.11.0] models-dev-data.json grew from 188 to 213 providers and from 6,472 to 7,436 models, adding anthropic/claude-fable-5-1, google/gemini-3.8-flash and openai/gpt-6-astra, dropping google/gemini-robotics-er-1.6-preview, and making gemini-flash-style fuzzy queries resolve to gemini-3.8-flash instead of gemini-flash-latest.

Every row was exercised by the validation campaign, and the summary line records the outcome:

30 slugs · VALID 6 · VALID-UNAUTHENTICATED-HERE 24 · SELF-TEST-FAILED 0 · INVALID 0 · numbers from registry 27 / pi-catalog 3 / none 0

The report covers 30 spellings: 6 VALID, 24 VALID-UNAUTHENTICATED-HERE, 0 SELF-TEST-FAILED, and 0 INVALID. VALID-UNAUTHENTICATED-HERE is the selection rig's verdict for a spelling the runtime accepted but whose build environment lacked that provider's credential; the table renders it ✓ spelling (no key in the build env), a spelling check rather than a full pass. Plain ✓ means VALID, a full self-test pass. A user's own run with a missing key hard-fails the harness self-test at startup (Self-test completed: FAILED … Server startup failed!); it never produces that table label.

These verdicts establish local spelling, catalog, and harness checks, not a successful generation against every provider. Credential presence does not prove key validity, current model access, quota, or live availability, and GOOD TO RUN! is not evidence that a model has answered a request. Assurance that a model answers requires an explicitly authorized live check, which can be billable.

The validation record also includes resolved identities such as haiku → anthropic/claude-haiku-4-5 "Claude Haiku 4.5 (latest)" and gpt-5.6-xhigh → openai/gpt-5.6-sol with the xhigh effort suffix, matching each row's provider and harness columns. The table's Kimi row is the routed openrouter/moonshotai/kimi-k3; the registry's bare kimi-k3 is a first-party twin that this route does not select. The dictionary-only shortcut gpt-5.6 has no generated table row of its own; it is accepted and expands to gpt-5.6-sol.

Record both the requested spelling and the resolved provider/model identity. Registry resolution can accept a fuzzy match, so a successful lookup need not name the exact model intended; inspect the resolved identity before freezing the hank. A matching Hankweave version string alone does not prove that a development checkout, npm artifact, and this documentation bundle contain identical catalogs.

The full table follows. Read harness for the resolved runner and verified for the runtime verdict; the remaining columns are prices, capacities, and capabilities per route.

Pricing provenance: this table was generated on 2026-10-05 from the artifact's shipped models-dev-data.json snapshot dated 2026-09-10, with a Pi-catalog fallback for the display numbers of the 3 rows only Pi's catalog knows (the captured totals are 27 registry rows and 3 Pi-catalog rows). The fallback concerns the generated table's columns only: at runtime a pi/ route takes capabilities and cost from the Hankweave registry when it knows the model, else fixed 200,000-token context / 64,000-output / no-cost defaults. Prices are catalog estimates for the named routes, not provider invoices or live price quotes, and a $0 catalog entry does not establish free service; see Prices and your budget, including the separate xhigh multiplier.

Model resolution owns the resolution grammar; authentication and models owns authentication; environment variables owns the complete key catalog.

Two harnesses, one dispatch rule#

The harness column above names the runner each row resolves to. A harness is the in-process runner that sends a codon to its model, and hankweave has exactly two: the Claude Agent SDK harness (claude-agent-sdk) and the embedded Pi harness (pi). Both are fully described in model resolution §4 and authentication and models §2; this page shows which harness each table row resolves to.

selectHarness computes the route at dispatch time from the model's real identity; the choice is late-bound and is not persisted. A model routes to claude-agent-sdk when providerId === "anthropic", or when providerId === "amazon-bedrock" and its model id is an Anthropic-family id (anthropic.claude-… or <geo>.anthropic.claude-…). Everything else uses pi. In the table, the six Anthropic rows (opus, claude-fable-5-1, sonnet, haiku, and the bare dotted Bedrock ids anthropic.claude-opus-5 and anthropic.claude-sonnet-5) run claude-agent-sdk; the other 24 run pi.

The single routing rule and harnessOverride semantics belong to model resolution and authentication and models. An explicit pi/... spelling forces harnessOverride: "pi", so an explicit pi/amazon-bedrock/... spelling stays on Pi even when its target id is Anthropic-family. Bedrock mode for the SDK route is derived from that provider/model identity, not from an environment variable: the runtime sets CLAUDE_CODE_USE_BEDROCK=1 plus its enumerated AWS variables for the SDK child itself; ambient CLAUDE_CODE_* variables still pass through, but a codon env block cannot set that Bedrock variable or the AWS list. SUPPORTED_CODON_PROVIDER_IDS and the unsupported-model error belong to model resolution §6.

Here, Pi means the embedded coding agent, not a separate harness installation: it runs in-process inside hankweave. Its catalog is the static vendored snapshot bundled in the artifact plus the user's ~/.pi/agent/models.json; per-user Pi state lives under ~/.pi/agent/, including the OAuth auth.json that pi login writes. Both harnesses emit Claude-compatible line-delimited JSON (JSONL), so one log format covers both. Log paths, names, and translation details belong to observing and debugging, the execution directory, and runtime architecture.

The table's inputs column describes catalog model capabilities (the model's modality list recorded in the registry or the Pi catalog), not a promise that either harness exposes every modality as a tool; a working input still depends on the model, harness, and host combination.

The diagram below traces one spelling through the whole path: shortcut expansion, registry resolution, the harness split, the key plane, and the startup catalog gate.

Harness dispatch from a spelling to a runner, key plane, and startup gate.

↗ Enlarge

harness dispatch:
  model: "<spelling>" in hank.json
    |
    v
  shortcut expansion
    |
    v
  registry resolution
    exact -> inferred provider -> fuzzy
                 |
                 v
            selectHarness
             /         \
  providerId=anthropic     everything else
  or amazon-bedrock +      -> embedded Pi harness
  Anthropic-family model id
  -> Claude Agent SDK
     (runtime sets CLAUDE_CODE_USE_BEDROCK=1 for Bedrock)

  explicit pi/<provider>/<model>
    (harnessOverride: "pi")
      -> embedded Pi harness
      -> pi target <provider>/<model>
                      aliases zhipuai/z-ai -> zai;
                      moonshot/moonshot-ai -> moonshotai;
                      moonshotai -> openrouter/moonshotai/<model>
                              |
                              +--> model_catalog gate
                                   (same lookupPiModel at startup)

  prefix rewrites before resolution:
    opencode/<provider>/<model> -> pi/<provider>/<model>
    openrouter/<org>/<model> -> pi/openrouter/<org>/<model>

  key plane:
    ANTHROPIC_API_KEY · GEMINI_API_KEY · OPENAI_API_KEY ·
    OPENROUTER_API_KEY · ZAI_API_KEY -> hankweave runtime keys
    every other provider -> Pi's own config (env / ~/.pi/agent,
    e.g. BASETEN_API_KEY, pi login)

  effort suffix:
    -high/-xhigh stripped before dispatch -> thinkingLevel

A table row's claude-agent-sdk or pi value is the resolved dispatch harness; the opus row and the pi/zai/glm-5.3 row show the two values.

Model resolution owns routing and harnessOverride; authentication and models explains the route decision.

How to spell a model#

The model field accepts six table-exercised forms, plus two dictionary-only forms, and the choice between them is a choice about behavior. Choose a shortcut when the latest family member should follow automatically; a bare id when preferred-provider inference is wanted; pi/... to force Pi; openrouter/... for an organization/model route; or an effort suffix to change reasoning effort. Each form below states its rule, points to a table row that exercises it, and links the owning reference. The resolution mechanics of every form are owned by model resolution.

Shortcut form

A shortcut resolves to the latest non-dated model selected for its family. The table exercises opus, sonnet, and haiku; their expansions are opus → claude-opus, sonnet → claude-sonnet, and haiku → claude-haiku, and registry resolution then selects the current identity, such as anthropic/claude-haiku-4-5 for the table's haiku row. gpt-5.6 is a dictionary-only shortcut with no generated table row; it expands to gpt-5.6-sol.

Qualification does not bypass shortcut expansion, and an effort suffix is preserved while the base is expanded: anthropic/sonnet → anthropic/claude-sonnet, openai/gpt-5.6 → openai/gpt-5.6-sol, and openai/gpt-5.6-xhigh → openai/gpt-5.6-sol-xhigh. After that application, the expanded result is not recursively expanded again.

Shortcuts track the latest non-dated model. Dated or snapshot ids are the pinning choice; a pinned spelling should be re-checked after an upgrade. Shortcut expansion is defined by model resolution; the re-check path belongs to upgrading.

Bare registry id

A bare id resolves through the shipped registry when its provider can be inferred: claude → anthropic, gemini → google, deepseek → deepseek, glm- → zhipuai, kimi → moonshotai, and gpt-, o1-, or o3- → openai. The table exercises bare ids such as deepseek-v4-pro, gemini-3.8-flash, and gpt-6-astra. Resolution order and fuzzy behavior belong to model resolution §3.

Provider-qualified form

A provider-qualified id names the provider before the model id (provider/model) and is a dictionary-only spelling form on this page: provider-qualified Anthropic forms such as anthropic/claude-… do not appear as generated table rows. Qualification does not bypass shortcut expansion; applyModelShortcuts applies the shortcut to the segment after the first slash. The grammar is defined in model resolution.

pi/<provider>/<model> passthrough

An explicit pi/<provider>/<model> spelling selects the embedded Pi harness and passes the written provider/model split verbatim as the dispatched identity. Validation sets harnessOverride: "pi" and takes capabilities and cost from the Hankweave registry when it knows the underlying model; for a model the registry does not know, validation uses fixed defaults of 200,000-token context, 64,000 output tokens, and no cost, so a dollar cap has nothing to price against. Pi's own model data is not read for this. The pi/zai/glm-5.3, pi/xai/grok-4.6, pi/baseten/…, and pi/openai-codex/… rows exercise this form.

Provider aliases resolve zhipuai and z-ai to zai; moonshot and moonshot-ai resolve to moonshotai, and the Moonshot first-party route is sent through openrouter/moonshotai/<model> because hankweave carries no Moonshot first-party API key. That routed twin is distinct from a Baseten-hosted spelling such as pi/baseten/moonshotai/Kimi-K3, which names Baseten as its provider and follows Pi's credential lookup. Passthrough and aliases are defined by model resolution.

openrouter/<org>/<model> form

An openrouter/<org>/<model> spelling names an OpenRouter route and is rewritten to pi/openrouter/<org>/<model>, so the resulting route uses the embedded Pi harness and the OpenRouter key plane (below). The legacy opencode/<provider>/<model> rewrite to pi/<provider>/<model> belongs to model resolution §5. The table's openrouter/moonshotai/kimi-k3 row supplies an organization/model spelling.

Effort-suffixed form

An effort suffix changes the reasoning effort sent to the target while preserving the underlying model identity. -high and -xhigh are stripped before dispatch and become thinkingLevel; an unsuffixed OpenAI model defaults to high. Effort variants are registered for reasoning-capable OpenAI models. The pricing multipliers (high ×1, xhigh ×2) and the suffix grammar belong to model resolution §5.

gpt-5.6-xhigh resolves to openai/gpt-5.6-sol with xhigh. The generated table's -xhigh row renders the base price; the registry accounts the auto-generated variant at 2× – see Prices and your budget. Budget behavior belongs to budgets.

Which key your route needs#

Once a spelling resolves to a route, the route determines where the credential comes from. A route uses either a hankweave runtime key or Pi's own credential lookup, depending on the provider.

Credential planes

Hankweave enforces five provider keys and injects them at runtime: ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, and ZAI_API_KEY. Every other provider uses Pi's own configuration, including environment variables and ~/.pi/agent. Runtime-key injection and the full key catalog belong to authentication and models and environment variables.

Baseten is not key-enforced: Pi resolves its credentials itself and reads BASETEN_API_KEY from the environment. The deepseek rows likewise use Pi's own configuration. The bare dotted Bedrock ids are Anthropic-on-Bedrock: identity-based dispatch selects the Claude Agent SDK harness and the runtime sets CLAUDE_CODE_USE_BEDROCK=1, while an explicit pi/amazon-bedrock/* spelling remains the Pi override on Pi's AWS credential route. Credential behavior is owned by AWS Bedrock. Full prefixes and masking rules stay on the linked pages.

openrouter/moonshotai/kimi-k3 is routed through OpenRouter because hankweave hands Pi no Moonshot first-party key, so it uses OPENROUTER_API_KEY; a Baseten-hosted Kimi spelling instead follows Pi's credential lookup, as other Baseten rows do.

Google key spelling. Hankweave's own key resolution reads Google's key from GEMINI_API_KEY only; the legacy GOOGLE_API_KEY alias was removed there, so setting it alone leaves Google unconfigured in hankweave. The environment-variable reference and authentication guide own the full key contract; the generated table's Google rows show where this spelling applies.

Codex subscription door

The pi/openai-codex/<model> route uses Pi's subscription authentication door: it is opened with pi login, and its OAuth credential is stored at ~/.pi/agent/auth.json. The table's three subscription-backed rows exercise this route. The metered-versus-subscription catalog difference belongs to authentication and models §6. The shipped scaffold includes the route's instructions:

- The `pi/openai-codex/gpt-5.6-terra` codon runs on a **ChatGPT subscription** (no `OPENAI_API_KEY`): the OAuth credential is read from Pi's store at `~/.pi/agent/auth.json`. Put it there with `pi login` (choose "OpenAI (ChatGPT Plus/Pro)"). No subscription? Delete that codon, or switch its model to a keyed spelling like `gpt-5.5` with `OPENAI_API_KEY` set.

Authentication and models §6 and first run §2 own the door and the scaffold.

Same model, multiple routes. A family has separate rows when its route changes the displayed route data. The deliberate same-model families are the API↔Codex twins gpt-5.6-luna/gpt-5.6-terra/gpt-5.6-sol ↔ pi/openai-codex/…, the first-party↔Baseten DeepSeek twins, the first-party Anthropic↔bare-dotted-Bedrock twins, and gpt-5.6-sol ↔ gpt-5.6-xhigh. The DeepSeek twins differ in price and context. The API and Codex rows differ in the generated table's displayed source columns (the registry rows show 1050k context, text+image+pdf inputs, and a knowledge date; the Codex display rows show the Pi-catalog fallback 272k context, text+image inputs, and no knowledge date) and, for Sol, in displayed price; Luna and Terra match their API prices. Those displayed values are source columns, not a claim about verified capability differences: at runtime the pi/openai-codex/* route takes capabilities and cost from the registry when it knows the model, else the fixed 200k/64k/no-cost defaults. The Anthropic↔Bedrock twins share the first-party numbers but differ in provider and key plane (AWS credentials vs ANTHROPIC_API_KEY); both resolve to the claude-agent-sdk harness. -xhigh is the same base id, registry-accounted at 2×. Choose the row whose spelling matches the route that will run, and use that row's context and price columns for planning. See model resolution and budgets for the owning contracts.

Checking a model before you spend#

Two checks stand between a spelling and a paid run: the per-model startup self-test with its Pi catalog preflight, which runs at every normal (non-replay) startup and during --validate, and the --validate command, which can be run at any time. This section covers both, then shows what a failure looks like on the console.

Startup catalog check

The model_catalog preflight is the self-test check that confirms a Pi-routed model can be found in Pi's catalog, using the same lookup a Pi session uses at launch. It runs at every normal (non-replay) startup – fresh or resumed – and during --validate; replay passes skipSelfTests and runs none of the self-tests. The check runs against the fixed snapshot shipped with the artifact plus ~/.pi/agent/models.json, so a miss at self-test time is deterministically a miss at launch, and it fails at config load before any codon runs.

The table's VALID / VALID-UNAUTHENTICATED-HERE column is the per-model self-test's consumer-visible result. Failure formats and the unsupported-model error belong to model resolution §6 and authentication and models §4, including the deepseek-flash drift case: a model the registry resolves but Pi's catalog cannot serve fails the preflight with a named list of available models.

Local validation command

--validate checks configuration without running the hank – the workflow file.

bunx hankweave@0.11.0 hank.json data/ --validate

--validate hashes its inputs, resolves and validates configuration, and runs the same per-model harness self-test as startup: SDK import, credential presence, and, for Pi models, the catalog preflight. It does not execute codons and makes no model-generation self-test; the registry is initialized with provider health checks disabled. A missing ANTHROPIC_API_KEY therefore fails --validate with exit 1. What validation leaves unproven is key validity and provider health: the credential check tests presence only. Validation can add $schema to the hank and writes a temporary log, and it is not universally offline – Bedrock credential discovery can probe instance metadata. Runtime startup separately performs provider health checks, which can call generateText("Hi", maxOutputTokens:16) for available registry providers; those can be billable and sit outside any tracked-codon capture total. A successful validation ends with the configuration summary, codon summary, and GOOD TO RUN! box shown here:

╭──────────────────────────────────────────────────────────────────────────────╮
│  Minimal single provider v1.0.0                                              │
│  1 codon • 0 loops                                                           │
╰──────────────────────────────────────────────────────────────────────────────╯

└─ [1] summarize-notes (Summarize the notes)
      model: haiku │ mode: fresh │ prompts: 1 (13 lines)
      checkpointedGlobs: 1

╭─ GOOD TO RUN! ─────────────────────────────────────────────────────╮
│  1 codons • 1 prompts • 0 system prompts • 0 rigs • 1 checkpoints  │
╰────────────────────────────────────────────────────────────────────╯

The capture's mode, checkpointedGlobs, loops, rigs, checkpoints, and system prompts are defined by hank.json, loops, rigs, and checkpoints; this page shows them in the capture without defining them.

Runbook §2, first run §4, and CLI own the command's full behavior.

Startup failure readings

A failed model self-test stops startup and exposes the failing model and reason on the console. The failure observable is the self-test aggregate followed by Server startup failed; the execution directory is created as part of the failed startup path. The capture below shows that sequence for a missing ANTHROPIC_API_KEY:

[<ts>] [ERROR] Self-test completed: FAILED
[<ts>] [ERROR] Self-test FAILED: Some checks failed
[<ts>] [ERROR]   - authentication: ✗ No authentication found (set ANTHROPIC_API_KEY)
[ERROR] Server startup failed!
Error message: Self-test failed for 1 model(s):
  - Claude Haiku 4.5 (latest) (anthropic/claude-haiku-4-5): Some checks failed
      • authentication: No authentication found (set ANTHROPIC_API_KEY)

Failure formats belong to the linked runbook, first-run, authentication, and model-resolution pages. There is no models list or hankweave run subcommand: use the curated table for discovery and --validate for checking. For execution selection, see --execution; this page carries no resume flag.

Runbook §2, first run §4, and model resolution §6.

Prices and your budget#

Price and capacity columns

The generated table reports dated price and capacity data for estimating a model route, not an undated promise about future provider prices. in, out, and cache-read are USD per 1M tokens; context and max out are token counts. The table also records reasoning support, accepted inputs, knowledge date, harness, provider, and verification status. Cost and price claims stay dated and generated with the table; no "~10–20× cheaper" multipliers substitute for them.

maxDollars is the total cost budget in USD and maxTimeSeconds is the wall-clock limit; both are set in hank.json's budget block. For shares, caps, onExceeded, and their operational behavior, see Budgets and hank.json; this page states only what the table's columns mean for estimation.

One row needs care here. The generated table renders gpt-5.6-xhigh at base prices, while the registry's auto-generated -xhigh variant carries an effortCostMultiplier of 2×. The table is the published display; the registry accounting is the 2× signal. For an xhigh codon's budget, price it at the registry accounting, not the displayed base column.

Zai pricing is per model

Zai pricing is per model, and the runtime's two price tables agree. Pi's vendored catalog prices five zai models – glm-4.7 $0.6/$2.2/$0.11, glm-5-turbo $1.2/$4/$0.24, glm-5.2 $1.4/$4.4/$0.26, glm-5.3 $1.4/$4.4/$0.26, and glm-5.3-flash $0.075/$0.25/$0.015 per million input/output/cache-read tokens – and the registry carries the same five prices. A pi/zai/<model> codon on one of the five priced models reports its real cost, and maxDollars can stop it mid-codon.

Two ids are the exception: glm-5.2-highspeed and glm-5.3-highspeed list every cost field 0 in the Pi catalog and have no registry price. A codon on either reports cost: 0 on every message, and no dollar cap can trip for it. Guard those two with maxTimeSeconds, maxOutputTokens, or maxContextTokens instead. A $0 display in any generated-table row is catalog display provenance, not evidence of free service; the runtime route prices from the registry per the rules above.

The embedded table supplies the route-specific price and capacity examples. Budgets and hank.json own shares, caps, onExceeded, and the two-party budget contract; authentication and models §7 and runbook §7 own the operational consequences.