Document max_turns settings for recipes and subagents (#7044)

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.