feat: Add max_turns to recipe and subagent settings

[clouatre]

Please explain the motivation behind the feature request.

Subagents have a default max_turns limit of 25. Complex tasks (e.g., multi-file implementations with build/test verification) can exceed this limit, causing the subagent to stop with "I've reached the maximum number of actions I can do without user input."

Currently, the only way to configure this is via the GOOSE_SUBAGENT_MAX_TURNS environment variable, which:

• Requires external setup before running goose
• Applies globally to all subagents
• Cannot be shared as part of a recipe

Describe the solution you'd like

Add max_turns field to:

1. Settings struct in crates/goose/src/recipe/mod.rs - for top-level recipe configuration
2. SubagentSettings struct in crates/goose/src/agents/subagent_tool.rs - for per-subagent configuration

This would allow recipes to specify:

settings:
  goose_provider: "gcp_vertex_ai"
  goose_model: "claude-sonnet-4-5@20250929"
  max_turns: 50

And subagent tool calls to override:

{
  "settings": {
    "model": "claude-haiku-4-5@20251001",
    "max_turns": 30
  }
}

Describe alternatives you've considered

Setting GOOSE_SUBAGENT_MAX_TURNS=50 in shell config. This works but is not portable across machines or shareable in recipes.

Additional context

Related: #3938 requested max turns for subagents but was closed before implementation. Since then, SubagentSettings was added with provider, model, temperature - adding max_turns would complete this.

Relevant code:

• crates/goose/src/agents/subagent_task_config.rs - defines DEFAULT_SUBAGENT_MAX_TURNS (25) and reads env var

• crates/goose/src/agents/subagent_tool.rs - apply_settings_overrides would need to handle max_turns

• I have verified this does not duplicate an existing feature request

[katzdave]

Nice suggestion. I'm thinking adding an ENV section to recipes (and sub-recipes) might be a good first step. Would at least solve the portability issue.

[clouatre]

Thanks for the feedback!

An ENV section would be more general-purpose, but for max_turns specifically, a direct field seems better UX: discoverable in schema, type-safe, and consistent with existing goose_provider/goose_model/temperature fields.

Happy to implement either approach, or both if you'd like the ENV section for other use cases.

[katzdave]

Sorry took a deeper look. I think your original suggestion makes a lot of sense since we already have most of the relevant configs available

[jhult]

I (with goose's help) made an attempt to implement this in #6687.

[clouatre]

PR #6687 landed the resolution chain (GOOSE_SUBAGENT_MAX_TURNS env -> recipe settings.max_turns -> default of 25) but the per-delegate override was scaffolded without being wired up.

DelegateParams has no max_turns field, the delegate tool schema doesn't expose one, and build_task_config calls resolve_max_turns(session) unconditionally. The with_max_turns() builder on TaskConfig exists but is never called anywhere.

Net effect: all delegates share a single ceiling. A recipe that needs a 175-turn build agent and a 75-turn validator can't differentiate.

Three small changes to close this out:

// 1. DelegateParams: add field
pub max_turns: Option<usize>,

// 2. Tool schema: add to properties
"max_turns": { "description": "Maximum turns for the subagent", "type": "integer" }

// 3. build_task_config: prefer per-delegate, fall back to resolution chain
let max_turns = params.max_turns.unwrap_or_else(|| self.resolve_max_turns(session));
task_config.max_turns = Some(max_turns);

Happy to open a PR if this approach looks right. cc @jhult @katzdave