One selector can pick a provider and model for several coding agents, as long as it follows each client's own authentication and request rules.

This article is for teams that run more than one coding agent and want one place to choose a route. When a selector ignores a client's rules, a convenient choice can send a request to the wrong endpoint or write a setting the client never reads. By the end we have a design that leaves each agent's API and credential rules unchanged, and a route record that links every selection to what the launched process did. We work from each client's published configuration and credential documentation. In the worked example, a real request checks the endpoint's tool behavior, and the same fixture can serve as an acceptance test for a native client path and a path through protocol translation.

We work through four steps:

  1. Make the decision before any request leaves the machine.
  2. Learn the configuration and credential rules each client owns.
  3. Resolve one example selection from catalog lookup to tool call.
  4. Record the route at every boundary.

A closing example shows why a credential problem can look like a stale catalog.

A decision before a request

Every selection starts as a configuration decision, so we make it before any task content leaves the machine.

A selector reads the request and chooses what the task needs:

We make that decision in the control plane, the configuration work that prepares a request, while the data plane carries the inference request and response. Keeping the two apart lets us inspect a selection first. An agent-specific configuration adapter turns the selection into settings the chosen agent understands, and the agent then resolves those settings and sends the inference request itself.

Three component types can be added:

For each component we add, we document what it changes and where it runs.

Two platforms. On the control plane: a selector, whose rows read Agent: Pi and Model: example/assistant, a catalog and a configuration adapter. On the second platform: a coding agent and a provider endpoint. Five lanes: 1 Look up the choice. 2 Supported choice goes on. 3 Handed over as settings. 4 The agent sends the request. 5 The endpoint answers. At the end two pale cards rest at the coding agent, tagged Settings and Response.
The selector's catalog lookup and adapter choice sit in the control plane, while the agent's own request and the endpoint response sit in the data plane.
Figure text

The control plane looks up the catalog and selects an adapter. It then chooses and adapts a route. The coding agent sends its own request and receives the endpoint response in the data plane.

  • Choosing a route, sending a request
  • Selector's settings (upright card)
  • Request and answer (sideways card)
  • The selector chose the route and handed it over as settings. The agent sent the request itself.
  • 1 Look up the choice
  • 2 Supported choice goes on
  • 3 Handed over as settings
  • 4 The agent sends the request
  • 5 The endpoint answers
  • Response
  • Selector: Reads the selection
  • Catalog: Known provider and model pairs
  • Configuration adapter
  • Coding agent: Sends the request itself
  • Provider endpoint: Answers the request
  • Settings
  • Control plane: Prepares the request
  • Agent: Pi; Model: example/assistant
  • The endpoint answers the agent.

What each client owns

The adapter can only respect a client's rules once we know what each client's documentation says they are, so we start with the four agents.

Claude Code's settings documentation separates five kinds of settings:

It gives environment variables their own precedence apart from that stack. Whether a shell variable beats a settings key depends on the specific pair. We need to check when an exported variable takes precedence and which sessions an edit to one user file affects.

The Codex configuration reference defines provider fields for a base URL, an environment key, and a wire API. For wire_api, responses is the supported value. That field names only the request contract. The Codex authentication reference lists several credential options:

An adapter should choose one supported authentication combination and write only the fields that combination uses.

Pi's model guide uses models.json for an endpoint that already speaks an API pi supports, while provider extensions handle custom protocols or authentication flows and can define their own behavior. Pi checks credentials in this order:

  1. a runtime key
  2. a stored credential
  3. a model-file key
  4. environment or ambient cloud credentials

That order means pi may keep using its stored provider credential when we set an environment credential.

OpenCode's provider guide treats adding credentials through /connect and configuring the provider as separate steps. Credentials live in OpenCode's own store. Its Azure section says OpenCode doesn't query management APIs to discover deployments, so a shared selector must distinguish models in its catalog from deployment names the client can call.

The four agents share no common schema.

For each agent, an adapter must respect the documented configuration interface and credential handling.
Agent Configuration / selection Credentials
Claude Code User, project, local and managed settings. Settings files and precedence - Claude Code Docs Environment-variable precedence is decided per setting pair, outside the settings-file stack. Settings files and precedence - Claude Code Docs
Codex CLI Provider base URL, env_key and wire_api=responses. Configuration Reference | ChatGPT Learn Supported options include environment keys, command helpers and gateway OAuth. Authentication | ChatGPT Learn
Pi Pi has a model picker and uses models.json for an API it already supports. pi ai pi models Pi reads runtime, stored, model-file and environment credential sources, and a stored credential is tied to its provider. pi models
OpenCode Provider setup and separate provider configuration. Providers | OpenCode Separate stored credentials and provider configuration. Providers | OpenCode

Sources: Settings files and precedence - Claude Code Docs Configuration Reference | ChatGPT Learn Authentication | ChatGPT Learn pi ai pi models Providers | OpenCode.

Resolving one example selection

One worked example shows how the selector moves from a catalog lookup to a confirmed tool call.

Say a request names pi, provider example-provider, and model example-assistant, and the task needs a tool request that reads a disposable fixture file. The endpoint, https://inference.example.com, is a documentation placeholder, and the request carries no credential value.

The selector first looks for the exact provider/model pair in its catalog. If the catalog has no match, the selector stops and returns an unknown-selection result. Falling back to a similarly named model would change the task and conceal the failed catalog match.

A short Python script shows that lookup, with a one-entry catalog and two requests at the top:

"""Selector catalog lookup: an exact provider/model pair resolves, a near miss stops."""
CATALOG = {  # (provider, model) -> endpoint; a placeholder, not a real service
    ("example-provider", "example-assistant"): "https://inference.example.com",
}
REQUESTS = [
    ("pi", "example-provider", "example-assistant"),
    ("pi", "example-provider", "example-assistant-mini"),
]


def select(provider, model):
    """Return the endpoint for the exact pair, or None. It never tries a similar name."""
    return CATALOG.get((provider, model))


for agent, provider, model in REQUESTS:
    print(f"request: agent={agent} provider={provider} model={model}")
    endpoint = select(provider, model)
    if endpoint is None:
        print(f"  unknown-selection: the catalog has no {provider}/{model}; stopped, nothing substituted")
    else:
        print(f"  selected: {provider}/{model} at {endpoint}")

It prints one selected request and one unknown-selection result:

$ python3 select_route.py
request: agent=pi provider=example-provider model=example-assistant
  selected: example-provider/example-assistant at https://inference.example.com
request: agent=pi provider=example-provider model=example-assistant-mini
  unknown-selection: the catalog has no example-provider/example-assistant-mini; stopped, nothing substituted

The second request differs from the catalog entry only by the suffix -mini, and the selector stops instead of choosing the similar name. To try a variation, add that pair to CATALOG or change the provider in a request.

Next, the selector checks whether its pi adapter supports the declared endpoint API and the tool behavior the task needs. Pi's AI library documentation says its chat catalog includes tool-calling models. To see whether this endpoint returns tool requests in the expected format, we send a real request.

For an API pi already supports, the adapter can use pi's compatible-endpoint mechanism. For an unsupported protocol the selector stops, unless we explicitly choose a translation component that covers the contract, and then we check how tool requests, results, and streaming events pass through that added component.

After launch, pi resolves its effective configuration and credential source under its own rules and sends the request, and the endpoint answers. If the response asks for the permitted fixture read, the agent's tool runtime performs it and feeds the result back into the loop. To confirm the read, we check the tool runtime's record of the call.

An unreachable endpoint and an unsupported combination are separate failures. When a request fails, the proposed selector records the intended route and keeps the selected model, so we can review a retry or a later configuration change.

Two platforms named 1. Resolve and 2. Adapt: both checks passed. On the first: a selector, whose rows read Agent: Pi and Model: example/assistant, a catalog and two yes-or-no checks, Combination supported and Capability available. Each check has a dashed No exit to a mark named Stop with reason. On the second: a configuration adapter and a coding agent. At the end one pale card, the settings, rests at the coding agent.
Before turning a candidate into launch configuration, we check the agent's documented interface and the capability the task needs.
Figure text

We first check catalog support and the required capability, stopping if either check fails. We then select an adapter and prepare agent-specific configuration.

  • Two checks before launch
  • Selector's settings (adapter band)
  • A no: selector stops, with reason
  • Dashed lane: described, not taken
  • This play follows two yeses. A no at either check stops before any settings are written. After launch, whether the endpoint answered is still to be checked.
  • 1 Find the choice in the catalog
  • 2 Is this pair supported?
  • 3 Supported: next check
  • 4 Available: write the settings
  • 5 Settings, then launch
  • 6 Not supported: stop
  • 7 Not available: stop
  • Settings
  • Selector
  • Catalog
  • Combination supported?
  • Capability available?
  • Stop with reason
  • Configuration adapter
  • Coding agent
  • 1. Resolve
  • 2. Adapt: both checks passed
  • Agent: Pi; Model: example/assistant
  • The agent is launched with those settings. Whether the endpoint answers is checked next.

Sources: [1] Configuration Reference | ChatGPT Learn; [2] pi models; [3] Providers | OpenCode.

What a route record needs

The record links the selector's decision to what the launched process did.

It captures five details side by side:

We record details at each boundary and what each entry tells us. For authentication, we record the credential mechanism or settings scope and exclude the secret itself. When the endpoint is a gateway, its configuration can also send a model name to a different provider through an alias or a fallback, which The gateway as an attack surface covers.

Boundary What to record What it tells you
Catalog resolution Requested pair, catalog revision, selected entry The selector resolved the intended entry
Client configuration Agent/version, adapter, effective endpoint and API The agent received the intended non-secret settings
Authentication Credential mechanism and the response Whether that request authenticated
Inference Endpoint, requested model, response or error The result of that model request
Tool execution Permitted action, executing process, fixture result Whether the tool action happened
Failure handling Original selection and error layer Whether the failure kept the requested route
Two platforms. On the control plane: a selector, whose rows read Agent: Pi and Model: example/assistant, a catalog, a branch named Match in the catalog, and a configuration adapter. A dashed lane leaves the branch for a mark named Unknown selection. On the second platform: a coding agent and a provider endpoint. Beside the route stands a route record with four of its six rows filled, marked 4 entries. At the end two pale cards rest at the coding agent, tagged Settings and Response.
  1. The decision, in the control plane: we make the decision in the control plane, before any task content leaves the machine; the data plane carries the inference request and response.
  2. Catalog lookup: the selector first looks for the exact provider/model pair in its catalog; if the catalog has no match, the selector stops and returns an unknown-selection result.
  3. Adapter: an agent-specific configuration adapter turns the selection into settings the chosen agent understands.
  4. The agent sends the request: the agent resolves those settings and sends the inference request itself, and the endpoint answers.
  5. The record: we record details at each boundary; the route drawn here crosses catalog resolution, client configuration, authentication and inference.
The decision is made before any request. The record table also has rows for tool execution and failure handling, which this route does not draw. Where each mark sits on the route is a drawing choice.

We can run the same harmless fixture as an acceptance test for a native client path and a path through protocol translation. Each path gets its own request and tool records, because protocol translation can change behavior. We record each path's end-to-end result even when a model listing succeeds.

A route: a selector, a catalog and a configuration adapter, then a coding agent, a tool runtime and a provider endpoint. In front stands a panel named Failed layer? with five numbered rows: catalog entry absent, capability unsupported, authentication rejected, endpoint unreachable, tool action failed; the third is lit red. Beside it stands a route record with one entry written, and at the end a card tagged Recorded rests at it.
When a run fails, we identify which of the five layers failed and record the relevant details before we change anything.
Figure text

Identify whether the failure involves the catalog, capability, authentication, network, or a tool action before a targeted retry or changes to routes, credentials, or model selection.

  • Name the failing layer first
  • Failing layer (lamp and rejected)
  • Bright lamp, no colour: it worked
  • Record entry written (lit row)
  • In this example the endpoint rejected the sign-in, and the catalog lookup had worked. Nothing is fixed yet: the layer is recorded, and credentials are checked before the catalog is refreshed.
  • 1 Look up the choice
  • 2 Check what it can do
  • 3 Handed over as settings
  • 4 The agent sends the request
  • 5 A permitted tool action
  • 6 Write down what failed
  • Selector: Agent: Pi; Model: example/assistant
  • Catalog
  • Configuration adapter
  • Coding agent
  • Provider endpoint
  • Tool runtime
  • Failed layer?
  • Route record
  • 1 Catalog entry absent; 2 Capability unsupported; 3 Authentication rejected; 4 Endpoint unreachable; 5 Tool action failed
  • Recorded
  • Write down the failing layer, then change one thing before trying again.

Sources: [1] Settings files and precedence - Claude Code Docs; [2] Configuration Reference | ChatGPT Learn; [3] pi models; [4] Providers | OpenCode.

Why a stored credential can look like a stale catalog

Pi's documented credential order makes this failure worth a closing example.

The selector finds example-assistant, sets an environment credential, and launches pi. Pi already has a stored credential for the same provider. The endpoint rejects authentication. A stored credential persists through a catalog refresh, the selector's catalog lookup worked, and pi's documented order puts a stored credential ahead of environment credentials, so we check credentials before refreshing the catalog.

We look at which credential the launched pi process picked, then at the provider's authentication response.

What to do next

A shared selector earns its place by leaving each client's API and credential rules intact and by recording every decision at the boundary where it took effect. Start with the four client documents linked above and note which of their rules your adapter must honor before you route a request.

What an attacker targets here

A selector turns a model name into a route and a credential, so its configuration and the credentials it stores are what an attacker wants.