Skip to content

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

How the provider of a session is resolvedFlow 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.yesyes + other providernodecider installedyes, not usablenono level setchain exhaustedyes, usableopen a chat sessionsession already exists?provider frozen on the sessionrouted_by = sessionnever resolved again409 provider_conflictrequest names another providerlevels, in order: request, task, persona, run,project rule, global rule, configured defaultthe first level that names a provider winsauto level, routed_by = autoonly when a decider is installed and mode and stage applymixed: executors · full: everyone · advisory: executors ·shadow/primary: neverfills the project rule slot: below run, above the global rulethe ticked models (routing_pool) are the only candidates atopennever replaces request, task, persona or runexplicit choice?request, task, personanever substitutedprovider_unknown 404endpoint_not_allowed 403provider_unavailable 503rolepilotno fallback at any levelexecutorunhealthy or forbidden level: next levelrouted_by = fallbacknever to a forbidden instancenothing configuredclaude-code if it exists, is healthy, allowed and its CLI is on theserverelse 409 no_provideropen the session on the chosen providertyped failures: cli_not_found 424, credentials_locked 423,unauthorized 502, model_no_tools 422, rate_limited 429, ...switch provider on the same sessionrefusals typed: empty_message 400, same_provider 400,invalid id 400, unknown session 404, else the new session’sopening refusal

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.

Zoom outZoom inFull screen
Redrawn from the verified diagram po-chat-provider (verified 878281ca). Labels are the names used in the code.
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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

  8. 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.