Docs · Internals
Which provider runs this session?
When a chat session opens, the backend has to pick a provider. The rule is a short ordered list, and it is strict about when it may change its mind.
What it does
A session that already exists keeps its provider for life. Otherwise the first level that names a provider wins: request, task, persona, run, project rule, global rule, then the configured default.
An explicit choice is never substituted. An unknown, forbidden or unhealthy provider is an error, not a quiet fallback.
Only the executor role may fall back to the next level, and never to an instance that is not allowed.
The diagram
Drag to move. Pinch, Ctrl + wheel or the + and - keys to zoom; arrow keys to move; 0 to fit; double-click to fit. Select a node to light up its links.
Text description of the diagram
Flow diagram. Opening a session first asks whether the session exists. If it does, its provider is frozen and a request naming another provider is refused with provider_conflict. If not, the levels are walked in order: request, task, persona, run, project rule, global rule, configured default. An explicit choice that is not usable is refused with provider_unknown, endpoint_not_allowed or provider_unavailable. Otherwise the role decides: a pilot never falls back, an executor may fall back to the next level. With nothing configured, claude-code is used if it exists, is healthy and is allowed, else no_provider. Every path ends by opening the session, which can fail with a typed error.
Guided reading
Step 1. Does the session already exist?
If so, its provider is frozen (routed_by is session) and is never resolved again. A request that names another provider is answered with 409 provider_conflict.
Step 2. Walk the levels
Otherwise the levels are tried in order: request, task, persona, run, project rule, global rule, configured default. The first level that has a provider wins.
Step 3. Explicit choices are final
A choice made in the request, the task or the persona is never replaced. Unknown gives 404 provider_unknown, forbidden gives 403 endpoint_not_allowed, unhealthy gives 503 provider_unavailable.
Step 4. The optional auto level
When a cognitive decider is installed and the mode and stage allow it, the chosen provider and model fill the project rule slot, below the run and above the global rule, and the session records routed_by auto with a readable reason. A request, task, persona or run that names a provider is never replaced. Without a decider nothing changes.
Step 5. Roles
The pilot role never falls back, at any level. For an executor, a level that is not explicit and is unhealthy or forbidden hands over to the next level, and the session records that it was routed by fallback. A forbidden instance is never chosen.
Step 6. The built-in default
If nothing is configured, or the executor chain is exhausted, claude-code is used when it exists, is healthy and is allowed for the project. Otherwise the answer is 409 no_provider.
Step 7. Opening can still fail, with a code
Each failure has a code and an HTTP status: cli_not_found 424, credentials_locked 423, unauthorized 502 (never 401), model_no_tools 422, rate_limited 429 and so on. A missing CLI answers 424 with a code instead of a mute 500.
Step 8. Moving a conversation to another provider
A session never changes provider: moving a conversation (POST /api/chat/sessions/{id}/switch-provider) opens a new session on the target and closes the old one only after the new one has opened. The stored history is rendered as text, a tool call becoming one line with a bounded result, and placed in front of your message. Past 40% of the target window the oldest entries are dropped and the relay says so; no model summarises anything. A conversation_relayed event tells both threads. Consent, the endpoint guard and the security gate apply as for any explicit choice, and a refusal leaves the old session open. A tool still running at the moment of the switch is not carried over.
Why it is built this way
Pinned per session
Resolving again on a running conversation could move it to another vendor in the middle. A frozen provider keeps history, cost and resume tokens consistent.
Explicit means explicit
If you chose a provider, substituting another would change cost and where your data goes without telling you.
The pilot does not fall back
The pilot is the one you talk to, and a silent switch would change who is answering. Executors doing delegated work may take the next configured level, and the switch is recorded.
A locked vault is an error
Credentials are references resolved from the vault when needed. A locked vault answers credentials_locked; it never falls back to a provider that happens to need no credential.
What is not established
- Not established: a provider switch has never been replayed against a real Claude Code or a real Codex, only against fakes.
Public sources
Where to check each statement, in the public repositories.