Sub agent not follow the model setting

[zeerd]

Sub agent chooses model by some self-logical but not the setting from main agent.

[github-actions]

Investigation findings

Thanks for the report! I investigated the relevant code and documentation to understand the model selection behavior for sub-agents.

What I found

Files examined:

• nodejs/src/types.ts — CustomAgentConfig and SessionConfig type definitions
• nodejs/src/client.ts — how session config (including model) is sent to the CLI via JSON-RPC
• docs/features/custom-agents.md — custom agents documentation

How model selection works for sub-agents (by design):

1. Custom agents defined via customAgents in your session config have an optional model field:

   // CustomAgentConfig (nodejs/src/types.ts)
   model?: string; // "When set, the runtime will attempt to use this model for the agent,
                   //  falling back to the parent session model if unavailable."

   When model is not set on a custom agent, the runtime falls back to the parent session's model. When it is set, the agent uses that model.

2. Built-in sub-agents (e.g., explore, task, general-purpose spawned by the runtime's task tool) have their own runtime-determined model preferences (e.g., lighter models for faster exploration tasks). These are determined by the CLI runtime and are not directly controlled by the session-level model setting.

Why this is a documentation issue

The current behavior is intentional and designed — sub-agents can use different models for performance/cost reasons. However, the model field on CustomAgentConfig is not documented at all in docs/features/custom-agents.md. The docs only show the session-level model parameter in examples, with no explanation of:

• The model field available per-agent in CustomAgentConfig (to explicitly set a per-agent model)
• That custom agents fall back to the parent session's model when model is not set
• That built-in sub-agents (explore, task, etc.) may use runtime-selected model defaults independent of the session model

What you can do today

For custom agents, you can explicitly set the model per-agent:

const session = await client.createSession({
    model: "gpt-4.1",             // parent session model
    customAgents: [
        {
            name: "researcher",
            prompt: "...",
            model: "gpt-4.1",     // explicitly inherit/pin the model for this agent
        }
    ],
});

If model is omitted from a CustomAgentConfig, the runtime falls back to the parent session's model.

For built-in sub-agents spawned by the task tool, model selection is managed by the CLI runtime and is not currently exposed as a configurable option at the SDK level.

Relabeling as documentation — the specific documentation gap is in docs/features/custom-agents.md, which should document the model field in CustomAgentConfig, explain model inheritance/fallback behavior, and clarify how built-in sub-agent model selection works.

Generated by Bug Handler for issue #1640 · sonnet46 1.6M · ◷