Document max_turns settings for recipes and subagents (#7044)

documentation/docs/guides/environment-variables.md

@@ -220,7 +220,7 @@ These variables control how goose manages conversation sessions and context.
 |----------|---------|---------|---------|
 | `GOOSE_CONTEXT_STRATEGY` | Controls how goose handles context limit exceeded situations | "summarize", "truncate", "clear", "prompt" | "prompt" (interactive), "summarize" (headless) |
 | `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_SUBAGENT_MAX_TURNS` | Sets the maximum turns allowed for a [subagent](/docs/guides/subagents) to complete before timeout | Integer (e.g., 25) | 25 |
+| `GOOSE_SUBAGENT_MAX_TURNS` | Sets the maximum turns allowed for a [subagent](/docs/guides/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 |
 | `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"]` |
 | `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) |
 | `GOOSE_CLI_THEME` | [Theme](/docs/guides/goose-cli-commands#themes) for CLI response  markdown | "light", "dark", "ansi" | "dark" |
@@ -247,7 +247,8 @@ export GOOSE_MAX_TURNS=25
 # Set a reasonable limit for production
 export GOOSE_MAX_TURNS=100
 
-# Customize subagent turn limit
+# Customize the default subagent turn limit
+# Note: This can be overridden per-recipe or per-subagent using the max_turns setting
 export GOOSE_SUBAGENT_MAX_TURNS=50
 
 # Use multiple context files

documentation/docs/guides/recipes/recipe-reference.md

@@ -516,6 +516,19 @@ The `settings` field allows you to configure the AI model and provider settings
 | `goose_provider` | String | - | The AI provider to use (e.g., "anthropic", "openai") |
 | `goose_model` | String | - | The specific model name to use |
 | `temperature` | Number | - | The temperature setting for the model (typically 0.0-1.0) |
+| `max_turns` | Number | - | Maximum number of turns for subagent tasks created by this recipe |
+
+#### 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).
+
+**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)
+
+**Common use cases:** Limit execution time for automated workflows, prevent runaway subagents, control resource usage in scheduled jobs.
 
 #### Example Settings Configuration
 
@@ -524,6 +537,7 @@ settings:
   goose_provider: "anthropic"
   goose_model: "claude-sonnet-4-20250514"
   temperature: 0.7
+  max_turns: 50
 ```
 
 ```yaml
@@ -791,6 +805,7 @@ settings:
   goose_provider: "anthropic"
   goose_model: "claude-sonnet-4-20250514"
   temperature: 0.7
+  max_turns: 100
 
 retry:
   max_retries: 3
@@ -869,7 +884,8 @@ response:
   "settings": {
     "goose_provider": "anthropic",
     "goose_model": "claude-sonnet-4-20250514",
-    "temperature": 0.7
+    "temperature": 0.7,
+    "max_turns": 100
   },
   "retry": {
     "max_retries": 3,
@@ -929,4 +945,4 @@ When these occur, goose will provide helpful error messages indicating what need
 - **Missing required retry fields**: When `max_retries` or `checks` are not specified
 
 ## Learn More
-Check out the [Recipes](/docs/guides/recipes) guide for more docs, tools, and resources to help you master goose recipes.
+Check out the [Recipes](/docs/guides/recipes) guide for more docs, tools, and resources to help you master goose recipes.

documentation/docs/guides/recipes/subrecipes.md

@@ -409,5 +409,19 @@ In this example:
 - **Pre-set fixed values**: Use `values` for parameters that don't change
 - **Test independently**: Verify subrecipes work alone before combining
 
+:::tip Controlling Subrecipe Execution
+Each subrecipe can specify its own `settings.max_turns` value to control execution limits. If not specified, the subrecipe inherits the parent recipe's `max_turns` setting. See [Recipe Settings](/docs/guides/recipes/recipe-reference#settings) for details.
+
+```yaml
+# subrecipes/quick-scan.yaml
+version: "1.0.0"
+title: "Quick Security Scan"
+settings:
+  max_turns: 10  # Limit this subrecipe to 10 turns
+instructions: "Perform a quick security scan"
+prompt: "Scan for common vulnerabilities"
+```
+:::
+
 ## Learn More
 Check out the [Recipes](/docs/guides/recipes) guide for more docs, tools, and resources to help you master goose recipes.

documentation/docs/guides/subagents.mdx

@@ -243,7 +243,7 @@ Subagents use the following pre-configured settings, but you can override any de
 ### Default Settings
 | Parameter | Default | How to Customize |
 |-----------|---------|------------------|
-| **Max Turns** | 25 | Use natural language or set `GOOSE_SUBAGENT_MAX_TURNS` |
+| **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 |
 | **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 |