Model Profiles and Routing

A model choice is part of a work plan. It affects cost, latency, and the quality of the reasoning available to a particular job. The useful question is not “which model is best?” It is “what capability does this role need, and what is the least costly route that still supplies it?” Gentle Shell makes that question explicit through profiles and per-agent routing instead of silently letting every helper inherit an accidental default.

Model identifiers use the format provider/model. The provider is not cosmetic: it identifies the route used to obtain the model. When using OpenAI models in these examples, use the openai-codex provider rather than bare openai. For example, a valid-shaped identifier is:

openai-codex/<model>

<model> is a placeholder, not a recommendation or a value copied from someone else's setup. What models you can actually select depends on the providers and credentials available in your installation. Do not infer that a model named in a configuration example is available to you.

Two related routing controls

Gentle Shell describes named profiles as a way to route the orchestrator atomically: a profile can choose the orchestrator's model and effort together. It does so independently from packaged and review roles. The active profile is bound to the parent session, and routing applies per session. A repository may pin a profile so its subagents stop following the globally active profile. The profiles interface shows the effective routing the runtime is using, which is more useful than guessing from an old settings file.

Per-agent routing is complementary. The subagent configuration has a model_profiles map whose keys are agent names and whose values can contain a model identifier. Its shape can be represented without exposing anybody's personal choices:

{
  "model_profiles": {
    "gentle-ai-explore": { "model": "provider/reading-model" },
    "gentle-ai-worker": { "model": "provider/writing-model" },
    "gentle-ai-verify": { "model": "provider/review-model" }
  }
}

This is a generic example, not a catalog of installed models. It teaches the mechanism: the named role is the stable routing target, while the model string is the provider-qualified choice. Keep configuration and credentials separate; a model profile is not a place to publish tokens or private account details.

Route by role, not by prestige

The explorer, worker, and verifier do different work. An explorer compresses read-only investigation into evidence and uncertainty. A worker reads a bounded specification, edits authorized surfaces, and checks the result. A verifier is an independent read-only check. Giving all three the same expensive route can waste budget when the exploration is routine; giving all three the cheapest route can undermine a difficult implementation or review.

A cost-aware plan therefore starts with the role's failure mode. Heavy reading and routine mapping can often use a cheaper or subscription-backed model when it can reliably produce an evidence-backed map. Heavy writing needs enough capacity to follow detailed requirements, preserve local conventions, and self-verify. Independent verification needs enough care to challenge a writer's assumptions; it should not be selected merely because it is the same model that wrote the change.

That is a tradeoff, not a universal hierarchy. A narrow familiar change may need no delegation and no extra route at all. A high-risk change may justify a stronger independent verifier. The parent still chooses topology first: model cost never creates permission to delegate, and an inexpensive model never makes a vague task safe.

Configure without losing the thread

The generic configuration pattern above is intentionally small. First choose roles. Then decide whether a session profile or repository pin should govern the parent session. Then map each configured helper role to a provider/model value you have confirmed is available. Finally, use the runtime's effective-routing display to verify what will actually happen.

Session profile records support explicit model selections and thinking choices. A saved binding is a snapshot: it can contain role model entries such as {"worker":{"model":"provider/model"}}. Valid thinking takes precedence over the older effort field where both appear. The record format is a persistence contract, not an invitation to hand-edit session history; let the supported controls make selections.

A packaged agent can also declare a default model in its definition. Routing configuration lets the user's selected profile override the accidental nature of that default. The result is predictable: the role stays recognizable while the model choice remains yours.

Common mistakes

The first mistake is omitting the provider prefix. model-name alone does not say which provider route should serve it. The second is using bare openai when the intended route is openai-codex/<model>. The third is copying another person's subagents.json verbatim. It may encode unavailable models or private preferences and does not teach the decision behind the choices.

The fourth is equating “cheaper” with “safe.” Savings come from matching the model to bounded work, avoiding unneeded delegation, and keeping handoffs precise. They do not come from weakening independent review or silently changing a repository's routing policy.

Try it

Open your profile or model controls and note the effective route shown for the parent session. Next, make a paper plan for a hypothetical feature: identify one read-heavy exploration task, one write task, and one verification task. For each, write a generic provider/model route and one sentence explaining why its cost and capability fit the role. Replace placeholders only after you have confirmed what your own installation makes available.