PR #58003: Agents: fix subagent model precedence

• Repository: openclaw/openclaw
• Author: neeravmakwana
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/58003

Description (problem / solution / changelog)

Summary

• Problem: sessions_spawn and related subagent model resolution preferred agents.defaults.subagents.model over a named agent's own model.primary, so per-agent model defaults were ignored.
• Why it matters: named agents could not reliably keep their configured primary model for spawned subagents unless every spawn call repeated an explicit model override.
• What changed: reordered subagent model precedence to prefer agents.list[].subagents.model, then agents.list[].model.primary, then agents.defaults.subagents.model, and mirrored that precedence in isolated cron model resolution.
• What did NOT change (scope boundary): explicit spawn/job model overrides still win, and no broader agent/default model resolution behavior was changed.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #57993
• Related #57993
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: resolveSubagentConfiguredModelSelection in src/agents/model-selection.ts placed agents.defaults.subagents.model ahead of the target agent's own model, so the global subagent default masked the per-agent primary model.
• Missing detection / guardrail: there was no regression test asserting that a named agent's model.primary beats the global subagent default when subagents.model is unset.
• Prior context (git blame, prior PR, issue, or refactor if known): issue #57993 reported the precedence mismatch with a direct repro.
• Why this regressed now: the precedence chain encoded the wrong specificity order.
• If unknown, what was ruled out: N/A.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/model-selection.test.ts, src/cron/isolated-agent.subagent-model.test.ts, and src/gateway/sessions-patch.test.ts
• Scenario the test should lock in: named agent model.primary is used for subagents unless a more specific agents.list[].subagents.model or explicit runtime override is present.
• Why this is the smallest reliable guardrail: it locks the precedence helper directly and covers the two mirrored runtime consumers that depended on the old order.
• Existing test that already covers this (if any): src/gateway/sessions-patch.test.ts already covered adjacent allowlist behavior and was updated to stay aligned with the corrected precedence.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

• Named agents now keep their own model.primary for spawned subagents when agents.list[].subagents.model is unset, even if agents.defaults.subagents.model is configured.
• Isolated cron runs now apply the same precedence when targeting a named agent.

Diagram (if applicable)

Before:
subagent spawn -> global defaults.subagents.model -> agent model.primary ignored

After:
subagent spawn -> agent subagents.model (if set) -> else agent model.primary -> else global defaults.subagents.model

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS 15 / Darwin 25.x
• Runtime/container: local Node 22+ / pnpm workspace
• Model/provider: config-driven subagent model selection
• Integration/channel (if any): N/A
• Relevant config (redacted): agents.defaults.subagents.model, agents.list[].model.primary, optional agents.list[].subagents.model

Steps

1. Configure agents.defaults.subagents.model and a named agent with a different model.primary.
2. Spawn a subagent for that named agent without an explicit model override.
3. Inspect the resolved subagent model.

Expected

• The named agent's model.primary is used unless agents.list[].subagents.model is configured.

Actual

• Before this fix, agents.defaults.subagents.model won and masked the named agent's model.primary.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios: reproduced the precedence issue in code inspection, updated the precedence helper, ran targeted regression tests for model selection, cron isolated-agent subagent resolution, and gateway sessions patch behavior; also ran pnpm check and pnpm build.
• Edge cases checked: agent subagents.model still outranks agent model.primary; explicit runtime/job model overrides still outrank config defaults; global defaults.subagents.model still applies when the agent has no explicit model.
• What you did not verify: I did not change or validate unrelated CLI help output; repo-wide pnpm test still reports the existing unrelated failure in src/cli/config-cli.test.ts about --container examples in help text.

AI Assistance

• AI-assisted: yes

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: another runtime path could still encode a different subagent model precedence order.
  • Mitigation: the helper and isolated cron path now match, and regression tests cover both direct helper precedence and mirrored runtime usage.

Made with Cursor

Changed files

• src/agents/model-selection.test.ts (modified, +46/-0)
• src/agents/model-selection.ts (modified, +2/-2)
• src/cron/isolated-agent.subagent-model.test.ts (modified, +25/-0)
• src/cron/isolated-agent/model-selection.ts (modified, +2/-0)
• src/gateway/sessions-patch.test.ts (modified, +2/-3)