A .nika workflow has always named its model. The model: line says which model answers, written as a provider and a name. What it did not say was how the run gets there.
The same model can often be reached in more than one way. You can call a provider's API with your own key. You can go through an agent application you are already signed into, over an agent session. Each path has its own account and its own billing. Before this change, the file did not make that choice. The 0.118.0 changelog section, first shipped publicly in v0.118.6, says that nika run "resolves the access plan once per attempt" from "this machine's provider and seat rows, the --access pin". Since v0.119.0, nika check and the run's announce list the ready paths the plan outranked, instead of a bare count. A reviewer reading the file could see the model. They could not see the route.
On 8 October 2026 the language specification added a place to write it down. The v0.123.0-preview.1 prerelease of 9 October pins that spec revision, and ordinary installs received the declaration with v0.123.0 on 23 October.
Two declarations under run: #
The new keys live in the optional top-level run: block, beside two older declarations about randomness and time. This is the block as the spec showed it on the day it was added. It is a fragment of a workflow, not a complete file:
run:
entropy: ambient # none | ambient | { seeded: <u64> }
clock: system # system | virtual
access: # how the run reaches its model · optional
via: codex # the route · an agent application or an API provider id
protocol: acp # api | acp
fallback: none # none · also what an omitted fallback means
reasoning: # optional
effort: high # the EXACT native value the route offersThe spec puts the split in one sentence:
model:says WHICH model answers.run.accesssays HOW the run reaches it, andrun.reasoning.effortsays which native effort it is asked to spend.
Each key is small:
access.vianames the route: an agent application or an API provider. The spec gives examples (codex,claude-code,openai) and says it "freezes no catalog of routes or models".access.protocolisapi, the route's inference API, oracp, an Agent Client Protocol session with an agent application. The spec adds: "there is no third value".access.fallbackhas one value,none: "the declared selection is exact". Leaving it out means the same thing onceaccess:is declared.reasoning.effortis "the EXACT native value the selected route advertises for the selected model". Reasoning effort is how much thinking a model is asked to spend before it answers. Each route names its own levels.
One more sentence keeps secrets out: "The credentials, account and billing a route uses stay in that route's own configuration, never in the file."
No silent substitution #
The core of the rule is what happens when the declared route cannot be honoured. The spec answers without exceptions:
An explicit selection (route · protocol · model · effort) is honored exactly or refused.
A route the engine cannot reach is refused before inference. A route that fails during the run fails its task, and a declared retry stays on that same route. The spec names the tempting shortcut and closes it: neither case is handed to another route, "not even by an API key or a direct CLI that happens to be configured on the same machine."
Three more rules follow from the same idea:
- Literal, from the file alone. Values are plain text, never
${{ }}templates, so the route is known before the first task. A launch option that contradicts the file is refused, "never silently preferred". - ACP is the protocol, not the program. A direct command-line call to an agent application does not count as
protocol: acp, and the record keeps naming the connection actually used. - Native effort, never translated. "There is no universal effort scale". An engine must not map, round or substitute the value.
Judged before any prompt #
In the spec, the static contract (the schema and nika check) "is the shape only": closed key sets, the two enums, a kebab-case via, no templates. Whether a route exists, speaks the protocol, serves the model or offers the effort "is a runtime fact". The spec's rule is that the engine discovers it first, and refuses a selection it cannot honour "before any inference request is sent", which it spells out as "no prompt, no API inference call".
The spec also requires a run to keep four facts apart: the selection the file requested, the selection sent to the route, the configuration the route confirmed, and the model that responded, the last one only when "the route attests it". An unattested fact "stays absent, never guessed".
Tested against scripted peers #
The first spec commit was honest about its runtime fixtures: "No adapter executes them yet: they are contracts, not agreement." A conformance fixture is a small test case any engine can be run against. Later the same day, a second spec commit added the adapter. Its message says it stages "fixture-declared ACP agents and API peers", runs "the unchanged engine", and judges its receipts "against independently observed requests and configuration". The fixture guide states the boundary: the adapter "never discovers a host binary, reads an account store or calls a real provider."
How it reached users #
On 9 October an engine commit added the block to the engine's schema test fixtures (crates/nika-schema/tests/document_fixtures/run-access.nika, absent at v0.122.0). The prerelease published that evening pins the 8 October spec revision in its SPEC_PIN file, described there as the commit "this repo's conformance fixtures, embedded pack and runtime trace witness are proven at". The prerelease's own notes do not list the declaration among what it brings.
A prerelease is a published build that ordinary installs do not pick up. The notes of v0.123.0-preview.1 say it "is not the Latest release, it is not in the Homebrew formula, and npm carries it only under the next dist-tag", and that "Homebrew and the default install script stay on 0.122.0." Most people got the declaration with v0.123.0 on 23 October, whose notes say: "The workflow file names its model, and Nika never substitutes another one silently."
The 0.123.0 changelog is also where a runtime refusal is recorded. A workflow that declared run.reasoning.effort: low for a model whose catalog lists no effort level passed « check · clean ✔ », and the changelog goes on: "Every run of it was then refused before its first task (NIKA-1800)." The fix made the Session's check report it as a finding, so "such bytes are neither shown as ready nor saved as clean."
Why it matters #
Choosing your model is half of the freedom. Choosing how you reach it (your key, your agent application, a local model) is the other half, and it was the half nobody could review. Now it is a line in the file, read in code review like permits:, and the spec makes it a promise rather than a preference.
The rule does not pick a side between local and remote. In the spec's words: "Where a route runs is deployment, not syntax", and "nothing in this declaration makes local execution mandatory or forbidden."
The earlier post The access layer is an operating contract described how the engine separated the model from the path that reaches it. This change hands the path to the author of the file.
What it does not do #
- It is optional. Without the declaration, "the engine resolves the route as it always has."
- The check proves shape, not routes. The spec freezes no list of routes or models. The conformance guide says of the shape fixtures: "A workflow that passes them proves nothing about any route."
- No alternatives.
fallbackhas a single value, and "Declared alternatives are not specified". - One route per run. There is no task-level
access:. A task whose model the declared route cannot serve is refused, "never re-routed". - Efforts are route-specific. A file that names an effort names it in its route's own words, and is tied to that route.
- A prerelease is not a release. Under "What it does not claim", the preview's notes list "no general reliability or speed qualification", and ordinary installs had none of this until 23 October.
- Later additions are another story. A service tier joined the same block in 0.124.2.
Read the prerelease notes, the v0.123.0 release and the envelope chapter of the spec.