diff --git a/crates/goose/src/agents/agent.rs b/crates/goose/src/agents/agent.rs index e4e1113c5..16ae009ac 100644 --- a/crates/goose/src/agents/agent.rs +++ b/crates/goose/src/agents/agent.rs @@ -49,7 +49,6 @@ use tokio::sync::{mpsc, Mutex}; use tokio_util::sync::CancellationToken; use tracing::{error, instrument, warn}; -const DEFAULT_MAX_TURNS: u32 = 1000; const DEFAULT_STOP_HOOK_BLOCK_CAP: u32 = 8; fn provider_creation_error(error: anyhow::Error, context: impl fmt::Display) -> anyhow::Error { @@ -562,11 +561,9 @@ impl Agent { cancel: CancellationToken, steer_queue: SteerQueue, ) -> StateMachine<'_, Session, GooseEffect> { - let max_turns = session_config.max_turns.unwrap_or_else(|| { - Config::global() - .get_param::("GOOSE_MAX_TURNS") - .unwrap_or(DEFAULT_MAX_TURNS) - }); + let max_turns = session_config + .max_turns + .unwrap_or_else(|| Config::global().default_max_turns()); let extension_lease = self .tool_confirmation_coordinator .session(&session_config.id) diff --git a/crates/goose/src/agents/platform_extensions/summon.rs b/crates/goose/src/agents/platform_extensions/summon.rs index aa96c524e..0dc09dab7 100644 --- a/crates/goose/src/agents/platform_extensions/summon.rs +++ b/crates/goose/src/agents/platform_extensions/summon.rs @@ -2,7 +2,6 @@ use crate::agents::extension::PlatformExtensionContext; use crate::agents::final_output_tool::FinalOutputTool; use crate::agents::mcp_client::{Error, McpClientTrait}; use crate::agents::state_machine::DELEGATED_META_KEY; -use crate::agents::subagent_task_config::DEFAULT_SUBAGENT_MAX_TURNS; use crate::agents::tool_execution::ToolCallContext; use crate::config::paths::Paths; use crate::config::{resolve_extensions_for_new_session, Config, GooseMode}; @@ -1127,9 +1126,6 @@ impl SummonClient { .and_then(serde_json::Value::as_str) .map(str::to_string); - // max_turns is set later in resolve_subagent_config so it can incorporate params.max_turns - // with the correct priority ordering; setting it here would cause it to be overridden - // by the parent session's recipe instead. let settings = model.map(|m| Settings { goose_model: Some(m), goose_provider: params.provider.clone(), @@ -1195,10 +1191,7 @@ impl SummonClient { .resolve_provider_config(params, recipe, session) .await?; - let max_turns = params - .max_turns - .or_else(|| recipe.settings.as_ref().and_then(|s| s.max_turns)) - .unwrap_or_else(|| self.resolve_max_turns(session)); + let max_turns = Self::resolve_max_turns(params, recipe, Config::global()); if max_turns == 0 || max_turns > u32::MAX as usize { anyhow::bail!( @@ -1352,23 +1345,12 @@ impl SummonClient { Ok((provider_name, model_config)) } - fn resolve_max_turns(&self, session: &crate::session::Session) -> usize { - session - .recipe - .as_ref() - .and_then(|r| r.settings.as_ref()) - .and_then(|s| s.max_turns) - .or_else(|| { - std::env::var("GOOSE_SUBAGENT_MAX_TURNS") - .ok() - .and_then(|v| v.parse().ok()) - }) - .or_else(|| { - Config::global() - .get_param::("GOOSE_SUBAGENT_MAX_TURNS") - .ok() - }) - .unwrap_or(DEFAULT_SUBAGENT_MAX_TURNS) + fn resolve_max_turns(params: &DelegateParams, recipe: &Recipe, config: &Config) -> usize { + params + .max_turns + .or_else(|| recipe.settings.as_ref().and_then(|s| s.max_turns)) + .or_else(|| config.get_param::("GOOSE_SUBAGENT_MAX_TURNS").ok()) + .unwrap_or_else(|| config.default_max_turns() as usize) } } @@ -1485,7 +1467,7 @@ mod tests { use std::collections::{HashMap, HashSet}; use std::fs; use std::sync::Arc; - use tempfile::TempDir; + use tempfile::{NamedTempFile, TempDir}; fn create_test_context() -> PlatformExtensionContext { create_test_context_with_session_manager(Arc::new( @@ -2256,77 +2238,69 @@ You review code."#; #[test] #[serial] - fn test_resolve_max_turns_recipe_overrides_env_var() { - let context = create_test_context(); - let client = SummonClient::new(context).unwrap(); + fn test_resolve_max_turns_precedence() { + let config_file = NamedTempFile::new().unwrap(); + let secrets_file = NamedTempFile::new().unwrap(); + let config = + Config::new_with_file_secrets(config_file.path(), secrets_file.path()).unwrap(); + fs::write( + config_file.path(), + "GOOSE_SUBAGENT_MAX_TURNS: 7\nGOOSE_MAX_TURNS: 8\n", + ) + .unwrap(); + let _env = env_lock::lock_env([ + ("GOOSE_SUBAGENT_MAX_TURNS", Some("99")), + ("GOOSE_MAX_TURNS", Some("42")), + ]); - let session = crate::session::Session { - recipe: Some(crate::recipe::Recipe { - version: "1.0.0".to_string(), - title: String::new(), - description: String::new(), - instructions: None, - prompt: None, - extensions: None, - settings: Some(crate::recipe::Settings { - goose_provider: None, - goose_model: None, - temperature: None, - max_turns: Some(10), - }), - activities: None, - author: None, - parameters: None, - response: None, - sub_recipes: None, - retry: None, - }), - ..Default::default() - }; - - // Set env var to a different value — recipe should still win - let _env = env_lock::lock_env([("GOOSE_SUBAGENT_MAX_TURNS", Some("99"))]); - let result = client.resolve_max_turns(&session); - - assert_eq!( - result, 10, - "recipe settings.max_turns should take priority over env var" - ); + for (delegate_limit, recipe_limit, expected) in + [(Some(3), Some(5), 3), (None, Some(5), 5), (None, None, 99)] + { + let params = DelegateParams { + max_turns: delegate_limit, + ..Default::default() + }; + let mut recipe = empty_recipe(); + recipe.settings = Some(Settings { + goose_provider: None, + goose_model: None, + temperature: None, + max_turns: recipe_limit, + }); + assert_eq!( + SummonClient::resolve_max_turns(¶ms, &recipe, &config), + expected + ); + } } #[test] #[serial] - fn test_resolve_max_turns_falls_back_to_env_var() { - let context = create_test_context(); - let client = SummonClient::new(context).unwrap(); + fn test_resolve_max_turns_from_config_file_or_default() { + let config_file = NamedTempFile::new().unwrap(); + let secrets_file = NamedTempFile::new().unwrap(); + let config = + Config::new_with_file_secrets(config_file.path(), secrets_file.path()).unwrap(); + let _env = env_lock::lock_env([ + ("GOOSE_SUBAGENT_MAX_TURNS", None::<&str>), + ("GOOSE_MAX_TURNS", None), + ]); - let session = crate::session::Session::default(); // no recipe - - let _env = env_lock::lock_env([("GOOSE_SUBAGENT_MAX_TURNS", Some("7"))]); - let result = client.resolve_max_turns(&session); - - assert_eq!( - result, 7, - "should fall back to GOOSE_SUBAGENT_MAX_TURNS env var" - ); - } - - #[test] - #[serial] - fn test_resolve_max_turns_falls_back_to_default() { - let context = create_test_context(); - let client = SummonClient::new(context).unwrap(); - - let session = crate::session::Session::default(); // no recipe - - std::env::remove_var("GOOSE_SUBAGENT_MAX_TURNS"); - let result = client.resolve_max_turns(&session); - - assert_eq!( - result, - crate::agents::subagent_task_config::DEFAULT_SUBAGENT_MAX_TURNS, - "should fall back to DEFAULT_SUBAGENT_MAX_TURNS" - ); + for (contents, expected) in [ + ("", 1000), + ("GOOSE_MAX_TURNS: 42\n", 42), + ("GOOSE_SUBAGENT_MAX_TURNS: 7\nGOOSE_MAX_TURNS: 42\n", 7), + ] { + fs::write(config_file.path(), contents).unwrap(); + assert_eq!( + SummonClient::resolve_max_turns( + &DelegateParams::default(), + &empty_recipe(), + &config + ), + expected + ); + } } fn empty_recipe() -> crate::recipe::Recipe { diff --git a/crates/goose/src/agents/subagent_task_config.rs b/crates/goose/src/agents/subagent_task_config.rs index e64137c2c..663b9c4eb 100644 --- a/crates/goose/src/agents/subagent_task_config.rs +++ b/crates/goose/src/agents/subagent_task_config.rs @@ -4,9 +4,6 @@ use std::fmt; use std::path::PathBuf; use std::sync::Arc; -/// Default maximum number of turns for task execution -pub const DEFAULT_SUBAGENT_MAX_TURNS: usize = 25; - /// Configuration for task execution with all necessary dependencies #[derive(Clone)] pub struct TaskConfig { diff --git a/crates/goose/src/checks/mod.rs b/crates/goose/src/checks/mod.rs index 3d8e96513..d93b84ba8 100644 --- a/crates/goose/src/checks/mod.rs +++ b/crates/goose/src/checks/mod.rs @@ -14,9 +14,6 @@ use std::fs; use std::path::{Path, PathBuf}; /// Default maximum number of turns a check subagent may take. -/// -/// Mirrors `goose::agents::subagent_task_config::DEFAULT_SUBAGENT_MAX_TURNS`, -/// duplicated here to keep the checks module self-contained for parsing. pub const DEFAULT_CHECK_TURN_LIMIT: usize = 25; /// Virtual check name prefix for `REVIEW.md`-derived checks. Findings emitted diff --git a/crates/goose/src/config/base.rs b/crates/goose/src/config/base.rs index 5f1603dfe..2dce94744 100644 --- a/crates/goose/src/config/base.rs +++ b/crates/goose/src/config/base.rs @@ -1336,6 +1336,10 @@ config_value!(GOOSE_MAX_ACTIVE_AGENTS, usize); config_value!(GOOSE_DISABLE_SESSION_NAMING, bool); impl Config { + pub(crate) fn default_max_turns(&self) -> u32 { + self.get_param::("GOOSE_MAX_TURNS").unwrap_or(1000) + } + pub fn get_goose_context_limit(&self) -> Result, ConfigError> { match self.get_param::("GOOSE_CONTEXT_LIMIT") { Ok(0) => Err(ConfigError::DeserializeError( diff --git a/documentation/docs/guides/context-engineering/subagents.mdx b/documentation/docs/guides/context-engineering/subagents.mdx index d3775753a..189fca079 100644 --- a/documentation/docs/guides/context-engineering/subagents.mdx +++ b/documentation/docs/guides/context-engineering/subagents.mdx @@ -272,7 +272,7 @@ Subagents use the following pre-configured settings, but you can override any de | Parameter | Default | How to Customize | |-----------|---------|------------------| | **Maximum Concurrent Subagents** | 5 | Set `GOOSE_MAX_CONCURRENT_SUBAGENTS` to a positive integer. Additional tasks wait until a running subagent finishes. The limit applies per parent session. | -| **Max Turns** | 25 | Use natural language, set `GOOSE_SUBAGENT_MAX_TURNS`, or configure `settings.max_turns` in [recipes](/docs/guides/recipes/recipe-reference#settings) or subagent tool calls | +| **Max Turns** | `GOOSE_MAX_TURNS`, otherwise 1000 | Use natural language, set `GOOSE_SUBAGENT_MAX_TURNS`, or configure `settings.max_turns` in [recipes](/docs/guides/recipes/recipe-reference#settings) or subagent tool calls | | **Timeout** | 5 minutes | Request longer timeout in your prompt | | **Extensions** | Inherited from parent | Specify which extensions to use in your prompt | | **Return Mode** | All subagent information provided in main session | Specify how much detail you want in your prompt | @@ -294,7 +294,15 @@ You can override any default by including the setting in your natural language r "Use a research subagent with 30 turns and 20-minute timeout to investigate quantum computing trends" ``` -**Environment variable:** Set `GOOSE_SUBAGENT_MAX_TURNS` to change the default max turns for all subagents. Similarly, `GOOSE_SUBAGENT_MODEL` and `GOOSE_SUBAGENT_PROVIDER` set defaults for the subagent model and provider; recipe [`settings`](/docs/guides/recipes/recipe-reference#settings) take precedence over both. +Subagent turn limits use the first configured value below: + +1. The `delegate` tool's `max_turns` argument. +2. The child recipe's `settings.max_turns`. +3. `GOOSE_SUBAGENT_MAX_TURNS` in the environment or configuration file. +4. `GOOSE_MAX_TURNS` in the environment or configuration file. +5. The default of 1000. + +`GOOSE_SUBAGENT_MODEL` and `GOOSE_SUBAGENT_PROVIDER` set defaults for the subagent model and provider; recipe [`settings`](/docs/guides/recipes/recipe-reference#settings) take precedence over both. ### Extension Control diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md index b0b6eb0cc..8909686d1 100644 --- a/documentation/docs/guides/environment-variables.md +++ b/documentation/docs/guides/environment-variables.md @@ -137,7 +137,7 @@ These variables control how goose manages conversation sessions and context. | `GOOSE_MAX_TURNS` | [Maximum number of turns](/docs/guides/sessions/smart-context-management#maximum-turns) allowed without user input | Integer (e.g., 10, 50, 100) | 1000 | | `GOOSE_GATEWAY_MAX_TURNS` | Maximum number of turns for gateway sessions (e.g., Telegram). Overrides `GOOSE_MAX_TURNS` for gateway traffic only, so chat platforms can keep a stricter cap than CLI/desktop sessions. | Integer (e.g., 5, 10, 25) | Falls back to `GOOSE_MAX_TURNS`, then 5 | | `GOOSE_MAX_CONCURRENT_SUBAGENTS` | Maximum number of subagents running at once per parent session. Additional tasks wait for a slot. Unset or invalid values use the default. | Positive integer (e.g., 2, 5, 10) | 5 | -| `GOOSE_SUBAGENT_MAX_TURNS` | Sets the maximum turns allowed for a [subagent](/docs/guides/context-engineering/subagents) to complete before timeout. Can be overridden by [`settings.max_turns`](/docs/guides/recipes/recipe-reference#settings) in recipes or subagent tool calls. | Integer (e.g., 25) | 25 | +| `GOOSE_SUBAGENT_MAX_TURNS` | Overrides the turn budget for [subagents](/docs/guides/context-engineering/subagents). An explicit delegate `max_turns` or child recipe [`settings.max_turns`](/docs/guides/recipes/recipe-reference#settings) takes precedence. | Positive integer (e.g., 25) | Falls back to `GOOSE_MAX_TURNS`, then 1000 | | `CONTEXT_FILE_NAMES` | Specifies custom filenames for [hint/context files](/docs/guides/context-engineering/using-goosehints#custom-context-files) | JSON array of strings (e.g., `["CLAUDE.md", ".goosehints"]`) | `[".goosehints", "AGENTS.md"]` | | `GOOSE_DISABLE_SESSION_NAMING` | Disables automatic AI-generated session naming; avoids the background model call and keeps the default "CLI Session" (goose CLI) or "New Chat" (goose Desktop) | "1", "true" (case-insensitive) to enable | false | | `GOOSE_PROMPT_EDITOR` | [External editor](/docs/guides/goose-cli-commands#external-editor-mode) to use for composing prompts instead of CLI input | Editor command (e.g., "vim", "code --wait") | Unset (uses CLI input) | diff --git a/documentation/docs/guides/recipes/recipe-reference.md b/documentation/docs/guides/recipes/recipe-reference.md index 1e93205d5..257b25600 100644 --- a/documentation/docs/guides/recipes/recipe-reference.md +++ b/documentation/docs/guides/recipes/recipe-reference.md @@ -504,13 +504,15 @@ The `settings` field allows you to configure the AI model and provider settings #### Understanding max_turns -The `max_turns` setting controls how many iterations an agent can perform before stopping. When set in a recipe's settings, it applies to that recipe's execution and any subagents or subrecipes it creates (unless they specify their own value). +The `max_turns` setting controls how many iterations an agent can perform before stopping. When set in a recipe's settings, it applies to that recipe's execution. -**Configuration precedence (highest to lowest):** -1. Subagent tool call override -2. Recipe `settings.max_turns` -3. `GOOSE_SUBAGENT_MAX_TURNS` environment variable -4. Default value (1000 for main recipes, 25 for subagents) +**Subagent configuration precedence (highest to lowest):** + +1. The `delegate` tool's `max_turns` argument. +2. The child recipe's `settings.max_turns`. +3. `GOOSE_SUBAGENT_MAX_TURNS` in the environment or configuration file. +4. `GOOSE_MAX_TURNS` in the environment or configuration file. +5. The default of 1000. **Common use cases:** Limit execution time for automated workflows, prevent runaway subagents, control resource usage in scheduled jobs.