Skip to content

feat(XCOD-82): configurable subagent model selection (part 1) - #27

Merged
pminev1 merged 1 commit into
devfrom
xcod-82-subagent-models
Sep 24, 2026
Merged

pminev1 merged 1 commit into
devfrom
xcod-82-subagent-models

Conversation

@pminev1

@pminev1 pminev1 commented Sep 24, 2026

Copy link
Copy Markdown
Collaborator

Part 1 of XCOD-82: configurable subagent model selection. The ticket stays open. Graduating the background flag, the monitoring surface and the lifecycle semantics come in part 2.

Resolution

The first rule that matches wins:

  1. Per call: the model the main agent passes to the task tool. This only applies when subagent.dynamic.enabled is true and the model is on subagent.dynamic.allow. Anything else is refused with a tool error the model can see; it is never silently replaced.
  2. Per type: agent.<type>.model.
  3. Global: subagent.model.
  4. Inherit: the main agent's current model. This stays the default.

Each setting accepts three values: "inherit", "small" (uses small_model, or inherits if that isn't set), or "provider/model".

Rules the ticket required

  • Variant: an inherited model keeps the main agent's reasoning variant. An overridden model uses the configured variant, or the model's default. This removes the silent variant drop at task.ts:209.
  • Residency first: the resolved model is checked against the residency policy before the subagent session starts.
    • A denial names the rule that chose the model, e.g. agent.qa.model → anthropic/claude-haiku-4-5 denied by residency policy.
    • The denial is written to the audit log.
    • Entries on dynamic.allow that the policy denies are never offered to the main agent.
  • Constrained schema: the task tool's model parameter exists only when dynamic selection is enabled, and then as an enum of the allowed models. It is added per request in the tool registry.
  • Resume: continuing a task with task_id keeps the original run's model unless the call explicitly picks another allowed one.
  • Explainable: the task metadata carries model, modelRule and modelSource.
  • Live config path: subagent is declared in both ConfigV1.Info and the v2 schema, and agent.<type>.model keeps its raw spec. A config test decodes every new key from a real file.

Verification: test/cli/run/subagent-model.test.ts, real lunos run

The scripted LLM records the model field of every request, so each case checks which model was actually called, not just what the resolver returned.

Case Subagent actually called Rule
no subagent config test-model (main) inherit
agent.explore.model: "small" small-model per-type, agent.explore.model
subagent.model small-model global
dynamic, allowed model small-model per-call
dynamic, model not on the list not started; tool error not on subagent.dynamic.allow —
residency allow: ["eu"], agent.explore.model: anthropic/… not started, never called; audit line anthropic allowed:false error names agent.explore.model
  • Negative control: removing checkResidency makes the residency case fail.
  • Unit tests: 9 resolver and schema tests.
  • Snapshot: the parameters snapshot gains the optional model field. The validator must accept it; the wire schema strips it unless dynamic selection is on.
  • Typecheck: the full turbo typecheck passes after ./script/generate.ts.
  • Full suite: no new failures against the dev baseline. httpapi: 208/208.

🤖 Generated with Claude Code

Resolution, first match wins: per-call (only if subagent.dynamic.enabled
and on subagent.dynamic.allow; anything else is refused, never replaced) →
per-type agent.<type>.model → global subagent.model → inherit.
Values: "inherit", "small" (small_model, else inherit), "provider/model".

- agent/subagent-model.ts: pure resolver returning the model, variant,
  rule and source. checkResidency() runs before the subagent session
  starts; a denial names the rule ("agent.qa.model → anthropic/... denied
  by residency policy") and is written to the residency audit log.
- Reasoning variant: inherited models keep the main agent's variant;
  overridden models use the configured variant or the model default. This
  removes the silent variant drop at task.ts:209.
- Resume keeps the original run's model unless the call explicitly picks
  another allowed model.
- Task tool: `model` is only in the JSON schema when dynamic selection is
  enabled, as an enum of allowed models minus residency-denied ones. It is
  added per request in the tool registry.
- Metadata: model, modelRule and modelSource on every task call.
- Config: `subagent` declared in ConfigV1.Info and the v2 schema;
  agent.<type>.model keeps its raw spec so "small"/"inherit" survive.
- Docs: agents.mdx "Choosing models for subagents", deployment guide note,
  CHANGELOG.

Real runs (test/cli/run/subagent-model.test.ts; the scripted LLM records
the model each request actually used): no config → subagent on the main
model; agent.explore.model "small" → explore called small-model;
subagent.model → global; dynamic allowed → per-call, off-list → tool
error; residency-denied per-type model → refused before start, never
called, audit line written. Removing checkResidency fails the last case.

Not in this part: graduating the background flag, the monitoring surface,
and lifecycle semantics. Those are the rest of XCOD-82.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@pminev1
pminev1 merged commit 4b381d5 into dev Sep 24, 2026
3 of 6 checks passed
@pminev1
pminev1 deleted the xcod-82-subagent-models branch September 26, 2026 15:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant