feat(subagents): propose Model parameter for invoke_subagent / define_subagent

[MattBetancourt]

Summary

Add an optional Model string parameter to invoke_subagent and define_subagent, enabling callers to specify which model a subagent should run on — rather than always inheriting the session-level model.

Full proposal: docs/proposals/subagent-model-selection.md

---

Motivation

Since v1.0.5, --model and /model let users pick a model at the session level. But subagents have no equivalent — they always inherit the parent session's model with no way to override it.

This blocks three practical architectures:

1. Cost-optimised orchestration — an orchestrator reasonably runs on a capable model (e.g. Gemini 3.1 Pro (High)), but file-scanning and research subagents only need something fast and cheap (e.g. Gemini 3.5 Flash (Low)). There is currently no way to express this split.

2. Capability-differentiated pipelines — some subtasks genuinely benefit from extended thinking (adversarial security review, complex planning). Spawning one subagent on Claude Sonnet 4.6 (Thinking) while keeping others on a standard model requires either a separate session or awkward workarounds.

3. Model benchmarking — running the same prompt against two subagents using different models for comparison is impossible today in a single session.

---

Proposed API Changes

invoke_subagent

 {
   "TypeName": "string (required)",
   "Role": "string (required)",
   "Prompt": "string (required)",
-  "Workspace": "inherit | branch | share  (optional, default: inherit)"
+  "Workspace": "inherit | branch | share  (optional, default: inherit)",
+  "Model": "string (optional) — e.g. \"Gemini 3.5 Flash (Low)\""
 }

define_subagent

 {
   "name": "string (required)",
   "description": "string (required)",
   "system_prompt": "string (required)",
   "enable_mcp_tools": "bool (optional)",
   "enable_subagent_tools": "bool (optional)",
-  "enable_write_tools": "bool (optional)"
+  "enable_write_tools": "bool (optional)",
+  "Model": "string (optional) — default model for this subagent type"
 }

Override chain (lowest → highest precedence)

session default  →  define_subagent.Model  →  invoke_subagent.Model

---

Behaviour Spec

Scenario	Expected result
Model omitted	Inherits session model — no regression
Model set in define_subagent only	All invocations of that type use the specified model
Model set in invoke_subagent only	That specific invocation uses the specified model
Both set	invoke_subagent.Model takes precedence
Invalid model identifier	Fail-fast with a clear error before the subagent starts
self-type subagent with Model	Spawns with the override, not the parent's model

---

Example

// Orchestrator (Gemini 3.1 Pro) spawns two concurrent subagents
// with different models suited to their tasks.
{
  "Subagents": [
    {
      "TypeName": "research",
      "Role": "Quick File Scanner",
      "Prompt": "List all Python files that import the requests library",
      "Workspace": "inherit",
      "Model": "Gemini 3.5 Flash (Low)"
    },
    {
      "TypeName": "self",
      "Role": "Security Reviewer",
      "Prompt": "Perform an adversarial OWASP-style review of the auth module",
      "Workspace": "branch",
      "Model": "Claude Sonnet 4.6 (Thinking)"
    }
  ]
}

Currently available models (as of v1.0.6, via agy models):

• Gemini 3.5 Flash (Low) / (Medium) / (High)
• Gemini 3.1 Pro (Low) / (High)
• Claude Sonnet 4.6 (Thinking)
• Claude Opus 4.6 (Thinking)
• GPT-OSS 120B (Medium)

---

Backwards Compatibility

Model is entirely optional. All existing invoke_subagent and define_subagent calls without it behave exactly as today — no regressions.

Out of Scope (follow-up candidates)

• Model capability validation (e.g. checking tool-calling support before assigning a model to a subagent with enable_write_tools: true)
• TUI surface for subagent model selection
• Pre-launch cost estimation hints

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[MattBetancourt]

The CLA check is resolved. This PR currently introduces the design proposal document so we can align on the API behavior. Let me know if you are happy to review the design here, or if you'd prefer I move this discussion to an Issue!