docs: add max turns (#3372)

documentation/docs/guides/config-file.md

@@ -23,6 +23,7 @@ The following settings can be configured at the root level of your config.yaml f
 | `GOOSE_MODEL` | Default model to use | Model name (e.g., "claude-3.5-sonnet", "gpt-4") | None | Yes |
 | `GOOSE_TEMPERATURE` | Model response randomness | Float between 0.0 and 1.0 | Model-specific | No |
 | `GOOSE_MODE` | Tool execution behavior | "auto", "approve", "chat", "smart_approve" | "smart_approve" | No |
+| `GOOSE_MAX_TURNS` | [Maximum number of turns](/docs/guides/smart-context-management#maximum-turns) allowed without user input | Integer (e.g., 10, 50, 100) | 1000 | No |
 | `GOOSE_LEAD_PROVIDER` | Provider for lead model in [lead/worker mode](/docs/guides/environment-variables#leadworker-model-configuration) | Same as `GOOSE_PROVIDER` options | Falls back to `GOOSE_PROVIDER` | No |
 | `GOOSE_LEAD_MODEL` | Lead model for lead/worker mode | Model name | None | No |
 | `GOOSE_PLANNER_PROVIDER` | Provider for [planning mode](/docs/guides/creating-plans) | Same as `GOOSE_PROVIDER` options | Falls back to `GOOSE_PROVIDER` | No |

documentation/docs/guides/environment-variables.md

@@ -106,6 +106,7 @@ These variables control how Goose manages conversation sessions and context.
 | Variable | Purpose | Values | Default |
 |----------|---------|---------|---------|
 | `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/smart-context-management#maximum-turns) allowed without user input | Integer (e.g., 10, 50, 100) | 1000 |
 
 **Examples**
 
@@ -115,6 +116,15 @@ export GOOSE_CONTEXT_STRATEGY=summarize
 
 # Always prompt user to choose (default for interactive mode)
 export GOOSE_CONTEXT_STRATEGY=prompt
+
+# Set a low limit for step-by-step control
+export GOOSE_MAX_TURNS=5
+
+# Set a moderate limit for controlled automation
+export GOOSE_MAX_TURNS=25
+
+# Set a reasonable limit for production
+export GOOSE_MAX_TURNS=100
 ```
 
 ### Context Limit Configuration

documentation/docs/guides/goose-cli-commands.md

@@ -144,6 +144,31 @@ goose configure
     goose session --max-turns 50
     ```
 
+- Set the [maximum number of turns](/docs/guides/smart-context-management#maximum-turns) allowed without user input (default: 1000)
+
+    **Options:**
+
+    **`--max-turns <NUMBER>`**
+
+    **Usage:**
+
+    ```bash
+    goose session --max-turns 10
+    ```
+
+    **Examples:**
+
+    ```bash
+    # Low limit for step-by-step control
+    goose session --max-turns 3
+    
+    # Moderate limit for controlled automation
+    goose session --max-turns 25
+    
+    # Combined with other options
+    goose session --name my-project --max-turns 10 --debug
+    ```
+
 ---
 ### session list [options]
 
@@ -303,6 +328,7 @@ Execute commands from an instruction file or stdin. Check out the [full guide](/
 - **`--with-extension <COMMAND>`**: Add stdio extensions (can be used multiple times in the same command)
 - **`--with-builtin <n>`**: Add builtin extensions by name (e.g., 'developer' or multiple: 'developer,github')
 - **`--debug`**: Output complete tool responses, detailed parameter values, and full file paths
+- **`--max-turns <NUMBER>`**: [Maximum number of turns](/docs/guides/smart-context-management#maximum-turns) allowed without user input (default: 1000)
 - **`--explain`**: Show a recipe's title, description, and parameters
 - **`--no-session`**: Run goose commands without creating or storing a session file
 - **`--max-turns <NUMBER>`**: Limit the maximum number of turns the agent can take before asking for user input to continue (default: 1000)
@@ -335,6 +361,9 @@ goose run --no-session -i instructions.txt
 
 #Run with a limit of 25 turns before asking for user input
 goose run --max-turns 25 -i plan.md
+
+#Run with limited turns before prompting user
+goose run --recipe recipe.yaml --max-turns 10
 ```
 
 ---

documentation/docs/guides/smart-context-management.md

@@ -8,13 +8,14 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import { ScrollText } from 'lucide-react';
 
-When working with [Large Language Models (LLMs)](/docs/getting-started/providers), there are limits to how much conversation history they can process at once. Goose provides smart context management features to help you maintain productive sessions even when reaching these limits. Here are the key concepts:
+When working with [Large Language Models (LLMs)](/docs/getting-started/providers), there are limits to how much conversation history they can process at once. Goose provides smart context management features to help handle context and conversation limits so you can maintain productive sessions. Here are some key concepts:
 
 - **Context Length**: The amount of conversation history the LLM can consider
 - **Context Limit**: The maximum number of tokens the model can process
 - **Context Management**: How Goose handles conversations approaching these limits
+- **Turn**: One complete prompt-response interaction between Goose and the LLM
 
-## Smart Context Management Features
+## Context Limit Strategy
 
 When a conversation reaches the context limit, Goose offers different ways to handle it:
 
@@ -23,8 +24,9 @@ When a conversation reaches the context limit, Goose offers different ways to ha
 | **Summarization** | Condenses conversation while preserving key points | Long, complex conversations | Maintains most context |
 | **Truncation** | Removes oldest messages to make room | Simple, linear conversations | Loses old context |
 | **Clear** | Starts fresh while keeping session active | New direction in conversation | Loses all context |
+| **Prompt** | Asks user to choose from the above options | Control over each decision in interactive sessions | Depends on choice made |
 
-## Using Smart Context Management
+Your available options depend on whether you're using the Desktop app or CLI.
 
 <Tabs groupId="interface">
   <TabItem value="ui" label="Goose Desktop" default>
@@ -56,23 +58,23 @@ You can proactively summarize your conversation before reaching context limits:
   </TabItem>
   <TabItem value="cli" label="Goose CLI">
 
-The CLI offers three context management options: summarize, truncate, or clear your session.
+The CLI supports all context limit strategies: `summarize`, `truncate`, `clear`, and `prompt`. 
 
-#### Default Context Strategy
+The default behavior depends on the mode you're running in:
+- **Interactive mode**: Prompts user to choose (equivalent to `prompt`)
+- **Headless mode** (`goose run`): Automatically summarizes (equivalent to `summarize`)
 
-You can configure Goose to automatically handle context limits without prompting by setting the `GOOSE_CONTEXT_STRATEGY` environment variable:
+You can configure how Goose handles context limits by setting the `GOOSE_CONTEXT_STRATEGY` environment variable:
 
 ```bash
-# Set default strategy (choose one)
+# Set automatic strategy (choose one)
 export GOOSE_CONTEXT_STRATEGY=summarize  # Automatically summarize (recommended)
 export GOOSE_CONTEXT_STRATEGY=truncate   # Automatically remove oldest messages
 export GOOSE_CONTEXT_STRATEGY=clear      # Automatically clear session
-export GOOSE_CONTEXT_STRATEGY=prompt     # Always prompt user (default)
-```
 
-**Default behavior:**
+# Set to prompt the user
-- **Interactive mode**: Prompts user to choose (equivalent to `prompt`)
+export GOOSE_CONTEXT_STRATEGY=prompt
-- **Headless mode** (`goose run`): Automatically summarizes (equivalent to `summarize`)
+```
 
 <Tabs>
   <TabItem value="automatic" label="Automatic" default>
@@ -135,6 +137,104 @@ Key information has been preserved while reducing context length.
   </TabItem>
 </Tabs>
 
+## Maximum Turns
+The `Max Turns` limit is the maximum number of consecutive turns that Goose can take without user input (default: 1000). When the limit is reached, Goose stops and prompts: "I've reached the maximum number of actions I can do without user input. Would you like me to continue?" If the user answers in the affirmative, Goose continues until the limit is reached and then prompts again.
+
+This feature gives you control over agent autonomy and prevents infinite loops and runaway behavior, which could have significant cost consequences or damaging impact in production environments. Use it for:
+
+- Preventing infinite loops and excessive API calls or resource consumption in automated tasks
+- Enabling human supervision or interaction during autonomous operations
+- Controlling loops while testing and debugging agent behavior
+
+This setting is stored as the `GOOSE_MAX_TURNS` environment variable in your [config.yaml file](/docs/guides/config-file). You can configure it using the Desktop app or CLI.
+
+<Tabs groupId="interface">
+    <TabItem value="ui" label="Goose Desktop" default>
+
+      1. Click the gear icon `⚙️` on the top toolbar
+      2. Click `Advanced settings`
+      3. Scroll to `Conversation Limits` and enter a value for `Max Turns`
+        
+    </TabItem>
+    <TabItem value="cli" label="Goose CLI">
+
+      1. Run the `configuration` command:
+      ```sh
+      goose configure
+      ```
+
+      2. Select `Goose Settings`:
+      ```sh
+      ┌   goose-configure
+      │
+      ◆  What would you like to configure?
+      │  ○ Configure Providers
+      │  ○ Add Extension
+      │  ○ Toggle Extensions
+      │  ○ Remove Extension
+      // highlight-start
+      │  ● Goose Settings (Set the Goose Mode, Tool Output, Tool Permissions, Experiment, Goose recipe github repo and more)
+      // highlight-end
+      └ 
+      ```
+
+      3. Select `Max Turns`:
+      ```sh
+      ┌   goose-configure
+      │
+      ◇  What would you like to configure?
+      │  Goose Settings
+      │
+      ◆  What setting would you like to configure?
+      │  ○ Goose Mode 
+      │  ○ Router Tool Selection Strategy 
+      │  ○ Tool Permission 
+      │  ○ Tool Output 
+      // highlight-start
+      │  ● Max Turns (Set maximum number of turns without user input)
+      // highlight-end
+      │  ○ Toggle Experiment 
+      │  ○ Goose recipe github repo 
+      │  ○ Scheduler Type 
+      └ 
+      ```
+
+      4. Enter the maximum number of turns:
+      ```sh
+      ┌   goose-configure 
+      │
+      ◇  What would you like to configure?
+      │  Goose Settings 
+      │
+      ◇  What setting would you like to configure?
+      │  Max Turns 
+      │
+        // highlight-start
+      ◆  Set maximum number of agent turns without user input:
+      │  10
+        // highlight-end
+      │
+      └  Set maximum turns to 10 - Goose will ask for input after 10 consecutive actions
+      ```
+
+      :::tip
+      In addition to the persistent `Max Turns` setting, you can provide a runtime override for a specific session or task via the `goose session --max-turns` and `goose run --max-turns` [CLI commands](/docs/guides/goose-cli-commands).
+      :::
+
+    </TabItem>
+    
+</Tabs>
+
+**Choosing the Right Value**
+
+The appropriate max turns value depends on your use case and comfort level with automation:
+
+- **5-10 turns**: Good for exploratory tasks, debugging, or when you want frequent check-ins. For example, "analyze this codebase and suggest improvements" where you want to review each step
+- **25-50 turns**: Effective for well-defined tasks with moderate complexity, such as "refactor this module to use the new API" or "set up a basic CI/CD pipeline"
+- **100+ turns**: More suitable for complex, multi-step automation where you trust Goose to work independently, like "migrate this entire project from React 16 to React 18" or "implement comprehensive test coverage for this service"
+
+Remember that even simple-seeming tasks often require multiple turns. For example, asking Goose to "fix the failing tests" might involve analyzing test output (1 turn), identifying the root cause (1 turn), making code changes (1 turn), and verifying the fix (1 turn).
+
 ## Token Usage
 After sending your first message, Goose Desktop and Goose CLI display token usage.
 
@@ -165,18 +265,18 @@ After sending your first message, Goose Desktop and Goose CLI display token usag
 </Tabs>
 
 ## Cost Tracking
-Display real-time costs of your session at the bottom of the Goose Desktop window.
+Display estimated real-time costs of your session at the bottom of the Goose Desktop window.
 
 <Tabs groupId="interface">
     <TabItem value="ui" label="Goose Desktop" default>
 To manage live cost tracking:
-  1. Click `⚙️` in the upper right corner 
+  1. Click the gear icon `⚙️` on the top toolbar
-  2. Click `Advanced Settings`
+  2. Click `Advanced settings`
-  3. Scroll to `App Settings` and toggle `Cost Tracking` on or off.
+  3. Scroll to `App Settings` and toggle `Cost Tracking` on or off
 
 The session cost updates dynamically as tokens are consumed. Hover over the cost to see a detailed breakdown of token usage. If multiple models are used in the session, this includes a cost breakdown by model. Ollama and local deployments always show a cost of $0.00.
 
-Pricing data is regularly fetched from the OpenRouter API and cached locally. The `Advanced Settings` tab shows when the data was last updated and allows you to refresh. 
+Pricing data is regularly fetched from the OpenRouter API and cached locally. The `Advanced settings` tab shows when the data was last updated and allows you to refresh. 
 
 These costs are estimates only, and not connected to your actual provider bill. The cost shown is an approximation based on token counts and public pricing data.
 </TabItem>