From 304aace48b799890cbd2a0e2b27ffb6ab2ffdd21 Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Mon, 14 Jul 2025 02:57:58 -0400
Subject: [PATCH 01/12] first draft of subagent doc

---
 documentation/docs/experimental/subagents.md | 203 +++++++++++++++++++
 1 file changed, 203 insertions(+)
 create mode 100644 documentation/docs/experimental/subagents.md

diff --git a/documentation/docs/experimental/subagents.md b/documentation/docs/experimental/subagents.md
new file mode 100644
index 000000000000..c2af5eb93e39
--- /dev/null
+++ b/documentation/docs/experimental/subagents.md
@@ -0,0 +1,203 @@
+---
+title: Subagents
+sidebar_position: 3
+sidebar_label: Subagents
+---
+
+Subagents are independent instances of Goosse that execute tasks while keeping your main conversation clean and focused. They bring process isolation and context preservation by offloading work to separate instances. Think of them as temporary assistants that handle specific jobs without cluttering your chat with tool execution details.
+
+:::warning
+Subagents are an experimental feature in active development. Behavior and configuration may change in future releases.
+:::
+
+## Types of Subagents
+
+### Internal Subagents
+Internal subagents spawn Goose instances to handle tasks using your current session's context and extensions.
+
+**Example: Creating HTML Files**
+```
+User: "Use 2 subagents to create hello.html with 'Hello World' content and goodbye.html with 'Goodbye World' content in parallel"
+
+Tool Output:
+{
+  "execution_summary": {
+    "total_tasks": 2,
+    "successful_tasks": 2,
+    "failed_tasks": 0,
+    "execution_time_seconds": 16.2
+  },
+  "task_results": [
+    {
+      "task_id": "create_hello_html",
+      "status": "success",
+      "result": "Successfully created hello.html with Hello World content"
+    },
+    {
+      "task_id": "create_goodbye_html", 
+      "status": "success",
+      "result": "Successfully created goodbye.html with Goodbye World content"
+    }
+  ]
+}
+```
+
+### External Subagents
+External subagents let you bring in AI agents from other providers and platforms, like Claude Code and OpenAI Codex, enabling Goose to coordinate and integrate your workflow with the broader AI ecosystem.
+
+**Example: Code Analysis with Codex**
+
+Goose Prompt:
+```
+"Use the codex subagent to analyze my codebase structure and identify the main components"
+```
+
+Goose Output:
+```
+Based on my analysis of your codebase, here are the main components:
+
+1. **Core Agent System** (`crates/goose/src/agents/`)
+   - Agent orchestration and session management
+   - Tool execution framework
+   - Extension system integration
+
+2. **CLI Interface** (`crates/goose-cli/`)
+   - Command-line interface and session handling
+   - Configuration management
+
+3. **Server Components** (`crates/goose-server/`)
+   - HTTP API endpoints
+   - WebSocket communication for real-time interaction
+
+4. **Desktop UI** (`ui/desktop/`)
+   - Electron-based desktop application
+   - TypeScript frontend with React components
+
+The architecture follows a modular design with clear separation between the core agent logic, interfaces, and UI components.
+```
+
+## Configuration
+
+### Internal Subagents
+
+#### Recipe Mode
+Uses YAML recipe files that define specific instructions, extensions, and behavior.
+
+**Example Recipe File** (`create-docs.yaml`):
+```yaml
+name: "Documentation Generator"
+description: "Generate project documentation"
+extensions:
+  - developer
+  - memory
+instructions: |
+  1. Scan the project structure
+  2. Generate README.md with project overview
+  3. Create API documentation from code comments
+  4. Update CHANGELOG.md with recent changes
+```
+
+**Usage**
+
+Goose Prompt:
+```
+"Run the create-docs recipe as a subagent"
+```
+
+#### Ad-hoc Mode
+Direct instructions provided for one-off tasks.
+
+**Example**
+
+Goose Prompt: 
+
+```
+Use subagents to run the following tasks in parallel
+    - "Create a simple landing page HTML file"
+    - "Generate a Python script that processes CSV files"
+    - "Write unit tests for the authentication module"
+```
+
+### External Subagents
+
+**Codex Configuration** (in your Goose config):
+```yaml
+  subagent:
+    args:
+    - mcp
+    bundled: true
+    cmd: codex
+    description: OpenAI Codex CLI Sub-agent
+    enabled: true
+    env_keys:
+    - OPENAI_API_KEY
+    envs: {}
+    name: subagent
+    timeout: 300
+    type: stdio
+```
+
+**Codex CLI Configuration** (`~/.codex/config.toml`):
+```toml
+# Use fast model for quick responses
+# model = "codex-mini-latest"
+disable_response_storage = true
+
+# Never prompt for approval - auto-execute
+approval_policy = "never"
+
+[sandbox]
+mode = "workspace-write"
+```
+
+## Execution Types
+
+### Sequential (Default)
+Tasks execute one after another in order.
+
+**How to trigger:**
+- Default behavior - no special keywords needed
+- Use phrases like "first do X, then do Y"
+- Any request without parallel keywords
+
+**Example:**
+```
+User: "First analyze the code, then generate documentation based on the analysis"
+```
+
+### Parallel
+Tasks execute simultaneously.
+
+**How to trigger:**
+- Use keywords: "parallel", "simultaneously", "at the same time", "concurrently"
+- Explicitly request concurrent execution
+
+**Example:**
+```
+User: "Create three different HTML templates in parallel"
+```
+
+## Suggested Use Cases
+
+**Simple, Independent Operations**
+- Creating multiple files with similar structure
+- Basic data processing tasks
+- File transformations and generations
+
+**Context Preservation**
+- Complex analysis that generates lots of tool output
+- Specialized tasks better handled by dedicated agents
+- Keeping main conversation focused on high-level decisions
+
+**Process Isolation**
+- Tasks that might fail without affecting main workflow
+- Operations requiring different configurations
+- Experimental or exploratory work
+
+## Lifecycle and Cleanup
+
+Subagents are temporary instances that exist only for task execution. After the task is completed, no manual intervention is needed for cleanup.
+
+:::info
+If a subagent fails or times out (5-minute default), you receive no output from that subagent. For parallel execution, if any subagent fails, you get results only from the successful ones.
+:::

From 41192c5368bf8313d0949917c8ae2b7f1c85dbe9 Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Mon, 14 Jul 2025 04:38:39 -0400
Subject: [PATCH 02/12] updates

---
 documentation/docs/experimental/subagents.md | 188 +++++++++----------
 1 file changed, 88 insertions(+), 100 deletions(-)

diff --git a/documentation/docs/experimental/subagents.md b/documentation/docs/experimental/subagents.md
index c2af5eb93e39..4d825df46f69 100644
--- a/documentation/docs/experimental/subagents.md
+++ b/documentation/docs/experimental/subagents.md
@@ -4,22 +4,41 @@ sidebar_position: 3
 sidebar_label: Subagents
 ---
 
-Subagents are independent instances of Goosse that execute tasks while keeping your main conversation clean and focused. They bring process isolation and context preservation by offloading work to separate instances. Think of them as temporary assistants that handle specific jobs without cluttering your chat with tool execution details.
+Subagents are independent instances that execute tasks while keeping your main conversation clean and focused. They bring process isolation and context preservation by offloading work to separate instances. Think of them as temporary assistants that handle specific jobs without cluttering your chat with tool execution details.
 
 :::warning
 Subagents are an experimental feature in active development. Behavior and configuration may change in future releases.
 :::
 
-## Types of Subagents
+To use subagents, enable alpha features by setting the environment variable:
+
+```bash
+export ALPHA_FEATURES=true
+```
+
+## Execution Types
+
+You can run multiple subagents sequentially or in parallel.
+
+| Type | Description | Trigger Keywords | Example |
+|------|-------------|------------------|---------|
+| **Sequential** (Default) | Tasks execute one after another | "first...then", "after" | `"First analyze the code, then generate documentation"` |
+| **Parallel** | Tasks execute simultaneously | "parallel", "simultaneously", "at the same time", "concurrently" | `"Create three HTML templates in parallel"` |
+
+## Internal Subagents
 
-### Internal Subagents
 Internal subagents spawn Goose instances to handle tasks using your current session's context and extensions.
 
-**Example: Creating HTML Files**
+### Direct Instruction
+Direct instructions provided for one-off tasks using natural language prompts.
+
+**Goose Prompt:**
+```
+"Use 2 subagents to create hello.html with 'Hello World' content and goodbye.html with 'Goodbye World' content in parallel"
 ```
-User: "Use 2 subagents to create hello.html with 'Hello World' content and goodbye.html with 'Goodbye World' content in parallel"
 
-Tool Output:
+**Tool Output:**
+```json
 {
   "execution_summary": {
     "total_tasks": 2,
@@ -42,48 +61,10 @@ Tool Output:
 }
 ```
 
-### External Subagents
-External subagents let you bring in AI agents from other providers and platforms, like Claude Code and OpenAI Codex, enabling Goose to coordinate and integrate your workflow with the broader AI ecosystem.
+### Recipe Configuration
+Use recipe files to define specific instructions, extensions, and behavior for the subagent.
 
-**Example: Code Analysis with Codex**
-
-Goose Prompt:
-```
-"Use the codex subagent to analyze my codebase structure and identify the main components"
-```
-
-Goose Output:
-```
-Based on my analysis of your codebase, here are the main components:
-
-1. **Core Agent System** (`crates/goose/src/agents/`)
-   - Agent orchestration and session management
-   - Tool execution framework
-   - Extension system integration
-
-2. **CLI Interface** (`crates/goose-cli/`)
-   - Command-line interface and session handling
-   - Configuration management
-
-3. **Server Components** (`crates/goose-server/`)
-   - HTTP API endpoints
-   - WebSocket communication for real-time interaction
-
-4. **Desktop UI** (`ui/desktop/`)
-   - Electron-based desktop application
-   - TypeScript frontend with React components
-
-The architecture follows a modular design with clear separation between the core agent logic, interfaces, and UI components.
-```
-
-## Configuration
-
-### Internal Subagents
-
-#### Recipe Mode
-Uses YAML recipe files that define specific instructions, extensions, and behavior.
-
-**Example Recipe File** (`create-docs.yaml`):
+**Recipe File**: (`create-docs.yaml`)
 ```yaml
 name: "Documentation Generator"
 description: "Generate project documentation"
@@ -97,47 +78,52 @@ instructions: |
   4. Update CHANGELOG.md with recent changes
 ```
 
-**Usage**
-
-Goose Prompt:
+**Goose Prompt:**
 ```
 "Run the create-docs recipe as a subagent"
 ```
 
-#### Ad-hoc Mode
-Direct instructions provided for one-off tasks.
-
-**Example**
-
-Goose Prompt: 
-
-```
-Use subagents to run the following tasks in parallel
-    - "Create a simple landing page HTML file"
-    - "Generate a Python script that processes CSV files"
-    - "Write unit tests for the authentication module"
+**Tool Output:**
+```json
+{
+  "execution_summary": {
+    "total_tasks": 1,
+    "successful_tasks": 1,
+    "failed_tasks": 0,
+    "execution_time_seconds": 45.8
+  },
+  "task_results": [
+    {
+      "task_id": "create_docs_recipe",
+      "status": "success",
+      "result": "Successfully generated project documentation: README.md updated, API docs created, CHANGELOG.md refreshed"
+    }
+  ]
+}
 ```
 
-### External Subagents
+## External Subagents
 
-**Codex Configuration** (in your Goose config):
-```yaml
-  subagent:
-    args:
-    - mcp
-    bundled: true
-    cmd: codex
-    description: OpenAI Codex CLI Sub-agent
-    enabled: true
-    env_keys:
-    - OPENAI_API_KEY
-    envs: {}
-    name: subagent
-    timeout: 300
-    type: stdio
-```
+External subagents let you bring in AI agents from other providers and platforms, enabling Goose to coordinate and integrate your workflow with the broader ecosystem. In the below example, we use Codex as a subagent by running it as an MCP server:
 
-**Codex CLI Configuration** (`~/.codex/config.toml`):
+**Goose Configuration** (in your Goose config):
+```yaml
+subagent:
+  args:
+  - mcp
+  bundled: true
+  cmd: codex
+  description: OpenAI Codex CLI Sub-agent
+  enabled: true
+  env_keys:
+  - OPENAI_API_KEY
+  envs: {}
+  name: subagent
+  timeout: 300
+  type: stdio
+```
+
+**External Tool Configuration** (`~/.codex/config.toml`):
 ```toml
 # Use fast model for quick responses
 # model = "codex-mini-latest"
@@ -150,36 +136,38 @@ approval_policy = "never"
 mode = "workspace-write"
 ```
 
-## Execution Types
+**Goose Prompt:**
+```
+"Use the codex subagent to analyze my codebase structure and identify the main components"
+```
 
-### Sequential (Default)
-Tasks execute one after another in order.
+**Goose Output:**
+```
+Based on my analysis of your codebase, here are the main components:
 
-**How to trigger:**
-- Default behavior - no special keywords needed
-- Use phrases like "first do X, then do Y"
-- Any request without parallel keywords
+1. **Core Agent System** (`crates/goose/src/agents/`)
+   - Agent orchestration and session management
+   - Tool execution framework
+   - Extension system integration
 
-**Example:**
-```
-User: "First analyze the code, then generate documentation based on the analysis"
-```
+2. **CLI Interface** (`crates/goose-cli/`)
+   - Command-line interface and session handling
+   - Configuration management
 
-### Parallel
-Tasks execute simultaneously.
+3. **Server Components** (`crates/goose-server/`)
+   - HTTP API endpoints
+   - WebSocket communication for real-time interaction
 
-**How to trigger:**
-- Use keywords: "parallel", "simultaneously", "at the same time", "concurrently"
-- Explicitly request concurrent execution
+4. **Desktop UI** (`ui/desktop/`)
+   - Electron-based desktop application
+   - TypeScript frontend with React components
 
-**Example:**
-```
-User: "Create three different HTML templates in parallel"
+The architecture follows a modular design with clear separation between the core agent logic, interfaces, and UI components.
 ```
 
 ## Suggested Use Cases
 
-**Simple, Independent Operations**
+**Independent Operations**
 - Creating multiple files with similar structure
 - Basic data processing tasks
 - File transformations and generations

From 940b738f3a16d58276e68935abb1220feab85667 Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Mon, 14 Jul 2025 04:42:38 -0400
Subject: [PATCH 03/12] adding links

---
 documentation/docs/experimental/subagents.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/documentation/docs/experimental/subagents.md b/documentation/docs/experimental/subagents.md
index 4d825df46f69..88412133ff20 100644
--- a/documentation/docs/experimental/subagents.md
+++ b/documentation/docs/experimental/subagents.md
@@ -62,7 +62,7 @@ Direct instructions provided for one-off tasks using natural language prompts.
 ```
 
 ### Recipe Configuration
-Use recipe files to define specific instructions, extensions, and behavior for the subagent.
+Use [recipe](/docs/guides/recipes/) files to define specific instructions, extensions, and behavior for the subagent.
 
 **Recipe File**: (`create-docs.yaml`)
 ```yaml
@@ -106,7 +106,7 @@ instructions: |
 
 External subagents let you bring in AI agents from other providers and platforms, enabling Goose to coordinate and integrate your workflow with the broader ecosystem. In the below example, we use Codex as a subagent by running it as an MCP server:
 
-**Goose Configuration** (in your Goose config):
+**[Goose Configuration File](/docs/guides/config-file)** (`.~/.config/goose/config.yaml `):
 ```yaml
 subagent:
   args:

From de1021f228cb6749ba0c1db5330776e716fdd228 Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Mon, 14 Jul 2025 04:55:48 -0400
Subject: [PATCH 04/12] adding env var

---
 documentation/docs/experimental/subagents.md    | 10 +++++++++-
 documentation/docs/guides/config-file.md        | 11 +++++++++++
 .../docs/guides/environment-variables.md        | 17 +++++++++++++++++
 3 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/documentation/docs/experimental/subagents.md b/documentation/docs/experimental/subagents.md
index 88412133ff20..fbb79d39cd2a 100644
--- a/documentation/docs/experimental/subagents.md
+++ b/documentation/docs/experimental/subagents.md
@@ -10,12 +10,20 @@ Subagents are independent instances that execute tasks while keeping your main c
 Subagents are an experimental feature in active development. Behavior and configuration may change in future releases.
 :::
 
-To use subagents, enable alpha features by setting the environment variable:
+:::info Prerequisites
+To use subagents, you need to enable alpha features first. You can do this by setting an [environment variable](/docs/guides/environment-variables#experimental-features) or adding it to your [config file](/docs/guides/config-file#experimental-features):
 
+**Environment Variable:**
 ```bash
 export ALPHA_FEATURES=true
 ```
 
+**Config File** (`~/.config/goose/config.yaml`):
+```yaml
+ALPHA_FEATURES: true
+```
+:::
+
 ## Execution Types
 
 You can run multiple subagents sequentially or in parallel.
diff --git a/documentation/docs/guides/config-file.md b/documentation/docs/guides/config-file.md
index 688156a84613..bfb7fe6c3b63 100644
--- a/documentation/docs/guides/config-file.md
+++ b/documentation/docs/guides/config-file.md
@@ -34,6 +34,14 @@ The following settings can be configured at the root level of your config.yaml f
 | `GOOSE_ALLOWLIST` | URL for allowed extensions | Valid URL | None | No |
 | `GOOSE_RECIPE_GITHUB_REPO` | GitHub repository for recipes | Format: "org/repo" | None | No |
 
+## Experimental Features
+
+These settings enable experimental features that are in active development. These may change or be removed in future releases.
+
+| Setting | Purpose | Values | Default | Required |
+|---------|---------|---------|---------|-----------|
+| `ALPHA_FEATURES` | Enables experimental alpha features like [subagents](/docs/experimental/subagents) | true/false | false | No |
+
 Additional [environment variables](/docs/guides/environment-variables) may also be supported in config.yaml.
 
 ## Example Configuration
@@ -58,6 +66,9 @@ GOOSE_CLI_MIN_PRIORITY: 0.2
 # Recipe Configuration
 GOOSE_RECIPE_GITHUB_REPO: "block/goose-recipes"
 
+# Experimental Features
+ALPHA_FEATURES: true
+
 # Extensions Configuration
 extensions:
   developer:
diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md
index 486de5118399..12a51f0c30e7 100644
--- a/documentation/docs/guides/environment-variables.md
+++ b/documentation/docs/guides/environment-variables.md
@@ -269,6 +269,23 @@ These variables configure the [Langfuse integration for observability](/docs/tut
 | `LANGFUSE_INIT_PROJECT_PUBLIC_KEY` | Alternative public key for Langfuse | String | None |
 | `LANGFUSE_INIT_PROJECT_SECRET_KEY` | Alternative secret key for Langfuse | String | None |
 
+## Experimental Features
+
+These variables enable experimental features that are in active development. These may change or be removed in future releases. Use with caution in production environments.
+
+| Variable | Purpose | Values | Default |
+|----------|---------|---------|---------|
+| `ALPHA_FEATURES` | Enables experimental alpha features like [subagents](/docs/experimental/subagents) | "true", "1" (case insensitive) to enable | false |
+
+**Examples**
+
+```bash
+# Enable alpha features
+export ALPHA_FEATURES=true
+
+# Or enable for a single session
+ALPHA_FEATURES=true goose session start
+```
 
 ## Notes
 

From 40d4267a829555ed065b9d45ca86408cbefa14f0 Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Mon, 14 Jul 2025 05:15:57 -0400
Subject: [PATCH 05/12] Docs: Subagents

---
 documentation/docs/experimental/index.md     |  5 ++++
 documentation/docs/experimental/subagents.md | 26 +++++++++++++++++---
 2 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/documentation/docs/experimental/index.md b/documentation/docs/experimental/index.md
index 2dbee27c0797..3792ea522ba8 100644
--- a/documentation/docs/experimental/index.md
+++ b/documentation/docs/experimental/index.md
@@ -29,6 +29,11 @@ The list of experimental features may change as Goose development progresses. So
       description="An experimental Android automation app that acts as an open agent running on your phone, providing maximal automation of everyday tasks."
       link="/docs/experimental/goose-mobile"
     />
+    <Card 
+      title="Subagents"
+      description="Independent instances that execute tasks while keeping your main conversation clean and focused. Run tasks sequentially or in parallel with process isolation and context preservation."
+      link="/docs/experimental/subagents"
+    />
   </div>
 </div>
 
diff --git a/documentation/docs/experimental/subagents.md b/documentation/docs/experimental/subagents.md
index fbb79d39cd2a..28a0f35021b1 100644
--- a/documentation/docs/experimental/subagents.md
+++ b/documentation/docs/experimental/subagents.md
@@ -38,7 +38,7 @@ You can run multiple subagents sequentially or in parallel.
 Internal subagents spawn Goose instances to handle tasks using your current session's context and extensions.
 
 ### Direct Instruction
-Direct instructions provided for one-off tasks using natural language prompts.
+Direct instructions provided for one-off tasks using natural language prompts. The main agent automatically configures the subagent based on your request.
 
 **Goose Prompt:**
 ```
@@ -86,9 +86,9 @@ instructions: |
   4. Update CHANGELOG.md with recent changes
 ```
 
-**Goose Prompt:**
-```
-"Run the create-docs recipe as a subagent"
+**Command:**
+```bash
+goose run --recipe create-docs.yaml
 ```
 
 **Tool Output:**
@@ -197,3 +197,21 @@ Subagents are temporary instances that exist only for task execution. After the
 :::info
 If a subagent fails or times out (5-minute default), you receive no output from that subagent. For parallel execution, if any subagent fails, you get results only from the successful ones.
 :::
+
+## Configuration
+
+| Parameter | Description | Default | Example |
+|-----------|-------------|---------|---------|
+| **Instructions** | Task-specific behavior and context | Auto-generated from user request | `"You are a code reviewer focusing on security"` |
+| **Max Turns** | Conversation limit before auto-completion | 10 | Set higher for complex tasks |
+| **Timeout** | Maximum execution time | 5 minutes | Prevents runaway processes |
+| **Extensions** | Available tools and capabilities | Inherits from main session | Recipe can specify subset |
+
+**How Configuration Works:**
+1. You make requests to the main Goose agent
+2. The main agent decides if a subagent would be helpful
+3. The main agent configures the subagent using either:
+   - **Direct instructions** - Generated from your natural language request
+   - **Recipe files** - Pre-defined configurations (run with `goose run --recipe <recipe_name>`)
+4. The subagent executes the task and reports back
+5. You see the results from the main agent

From bdf9b60cba8226e0f809e3086d85d46d0a985955 Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Mon, 14 Jul 2025 05:25:00 -0400
Subject: [PATCH 06/12] config prams

---
 documentation/docs/experimental/subagents.md | 11 +++--------
 1 file changed, 3 insertions(+), 8 deletions(-)

diff --git a/documentation/docs/experimental/subagents.md b/documentation/docs/experimental/subagents.md
index 28a0f35021b1..0f5732800654 100644
--- a/documentation/docs/experimental/subagents.md
+++ b/documentation/docs/experimental/subagents.md
@@ -200,6 +200,9 @@ If a subagent fails or times out (5-minute default), you receive no output from
 
 ## Configuration
 
+Goose automatically configures subagents by looking at environment variables, user prompts, and recipe files to determine the best settings for each task.
+
+
 | Parameter | Description | Default | Example |
 |-----------|-------------|---------|---------|
 | **Instructions** | Task-specific behavior and context | Auto-generated from user request | `"You are a code reviewer focusing on security"` |
@@ -207,11 +210,3 @@ If a subagent fails or times out (5-minute default), you receive no output from
 | **Timeout** | Maximum execution time | 5 minutes | Prevents runaway processes |
 | **Extensions** | Available tools and capabilities | Inherits from main session | Recipe can specify subset |
 
-**How Configuration Works:**
-1. You make requests to the main Goose agent
-2. The main agent decides if a subagent would be helpful
-3. The main agent configures the subagent using either:
-   - **Direct instructions** - Generated from your natural language request
-   - **Recipe files** - Pre-defined configurations (run with `goose run --recipe <recipe_name>`)
-4. The subagent executes the task and reports back
-5. You see the results from the main agent

From 0abd649f794f64325afd2b7952f72ab526ce781b Mon Sep 17 00:00:00 2001
From: angiejones <jones.angie@gmail.com>
Date: Mon, 14 Jul 2025 08:14:51 -0500
Subject: [PATCH 07/12] rearranging order to flow better

---
 documentation/docs/experimental/ollama.md    |  2 +-
 documentation/docs/experimental/subagents.md | 25 ++++++++++----------
 2 files changed, 13 insertions(+), 14 deletions(-)

diff --git a/documentation/docs/experimental/ollama.md b/documentation/docs/experimental/ollama.md
index 4b23f3618810..4a2c271c81b8 100644
--- a/documentation/docs/experimental/ollama.md
+++ b/documentation/docs/experimental/ollama.md
@@ -1,6 +1,6 @@
 ---
 title: Ollama Tool Shim
-sidebar_position: 1
+sidebar_position: 2
 sidebar_label: Ollama Tool Shim
 ---
 
diff --git a/documentation/docs/experimental/subagents.md b/documentation/docs/experimental/subagents.md
index 0f5732800654..ed8509817904 100644
--- a/documentation/docs/experimental/subagents.md
+++ b/documentation/docs/experimental/subagents.md
@@ -1,6 +1,6 @@
 ---
 title: Subagents
-sidebar_position: 3
+sidebar_position: 1
 sidebar_label: Subagents
 ---
 
@@ -10,7 +10,15 @@ Subagents are independent instances that execute tasks while keeping your main c
 Subagents are an experimental feature in active development. Behavior and configuration may change in future releases.
 :::
 
-:::info Prerequisites
+You can run multiple subagents sequentially or in parallel.
+
+| Type | Description | Trigger Keywords | Example |
+|------|-------------|------------------|---------|
+| **Sequential** (Default) | Tasks execute one after another | "first...then", "after" | `"First analyze the code, then generate documentation"` |
+| **Parallel** | Tasks execute simultaneously | "parallel", "simultaneously", "at the same time", "concurrently" | `"Create three HTML templates in parallel"` |
+
+
+## Prerequisites
 To use subagents, you need to enable alpha features first. You can do this by setting an [environment variable](/docs/guides/environment-variables#experimental-features) or adding it to your [config file](/docs/guides/config-file#experimental-features):
 
 **Environment Variable:**
@@ -22,16 +30,6 @@ export ALPHA_FEATURES=true
 ```yaml
 ALPHA_FEATURES: true
 ```
-:::
-
-## Execution Types
-
-You can run multiple subagents sequentially or in parallel.
-
-| Type | Description | Trigger Keywords | Example |
-|------|-------------|------------------|---------|
-| **Sequential** (Default) | Tasks execute one after another | "first...then", "after" | `"First analyze the code, then generate documentation"` |
-| **Parallel** | Tasks execute simultaneously | "parallel", "simultaneously", "at the same time", "concurrently" | `"Create three HTML templates in parallel"` |
 
 ## Internal Subagents
 
@@ -150,7 +148,8 @@ mode = "workspace-write"
 ```
 
 **Goose Output:**
-```
+
+```md
 Based on my analysis of your codebase, here are the main components:
 
 1. **Core Agent System** (`crates/goose/src/agents/`)

From 089cb363fb188a42861ccedda87e64b3da6156b4 Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Mon, 14 Jul 2025 09:18:43 -0400
Subject: [PATCH 08/12] Update
 documentation/docs/guides/environment-variables.md

Co-authored-by: Angie Jones <jones.angie@gmail.com>
---
 documentation/docs/guides/environment-variables.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md
index 12a51f0c30e7..4e02ac66b180 100644
--- a/documentation/docs/guides/environment-variables.md
+++ b/documentation/docs/guides/environment-variables.md
@@ -284,7 +284,7 @@ These variables enable experimental features that are in active development. The
 export ALPHA_FEATURES=true
 
 # Or enable for a single session
-ALPHA_FEATURES=true goose session start
+ALPHA_FEATURES=true goose session
 ```
 
 ## Notes

From 75cafaf6139b42683273c78f4d9756447b69b653 Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Mon, 14 Jul 2025 11:50:27 -0400
Subject: [PATCH 09/12] some updates based on code review

---
 documentation/docs/experimental/subagents.md | 156 +++++++++++++------
 1 file changed, 112 insertions(+), 44 deletions(-)

diff --git a/documentation/docs/experimental/subagents.md b/documentation/docs/experimental/subagents.md
index ed8509817904..46efdd6f7765 100644
--- a/documentation/docs/experimental/subagents.md
+++ b/documentation/docs/experimental/subagents.md
@@ -10,6 +10,15 @@ Subagents are independent instances that execute tasks while keeping your main c
 Subagents are an experimental feature in active development. Behavior and configuration may change in future releases.
 :::
 
+## How to Use Subagents
+
+To use subagents, simply ask Goose to delegate tasks using natural language. Goose automatically decides when to spawn subagents and handles their lifecycle. You can:
+
+1. **Request specialized help**: "Use a code reviewer to analyze this function for security issues"
+2. **Reference specific recipes**: "Use the 'security-auditor' recipe to scan this endpoint"  
+3. **Run parallel tasks**: "Create three HTML templates simultaneously"
+4. **Delegate complex work**: "Research quantum computing developments and summarize findings"
+
 You can run multiple subagents sequentially or in parallel.
 
 | Type | Description | Trigger Keywords | Example |
@@ -33,10 +42,10 @@ ALPHA_FEATURES: true
 
 ## Internal Subagents
 
-Internal subagents spawn Goose instances to handle tasks using your current session's context and extensions.
+Internal subagents spawn Goose instances to handle tasks using your current session's context and extensions. 
 
-### Direct Instruction
-Direct instructions provided for one-off tasks using natural language prompts. The main agent automatically configures the subagent based on your request.
+### Direct Prompts
+Direct prompts provided for one-off tasks using natural language prompts. The main agent automatically configures the subagent based on your request.
 
 **Goose Prompt:**
 ```
@@ -67,45 +76,73 @@ Direct instructions provided for one-off tasks using natural language prompts. T
 }
 ```
 
-### Recipe Configuration
-Use [recipe](/docs/guides/recipes/) files to define specific instructions, extensions, and behavior for the subagent.
+### Recipes
+Use [recipe](/docs/guides/recipes/) files to define specific instructions, extensions, and behavior for subagents. Recipes provide reusable configurations that can be shared and referenced by name.
+
+**Creating a Recipe File**
+
+`code-reviewer.yaml`
 
-**Recipe File**: (`create-docs.yaml`)
 ```yaml
-name: "Documentation Generator"
-description: "Generate project documentation"
-extensions:
-  - developer
-  - memory
+id: code-reviewer
+version: 1.0.0
+title: "Code Review Assistant"
+description: "Specialized subagent for code quality and security analysis"
 instructions: |
-  1. Scan the project structure
-  2. Generate README.md with project overview
-  3. Create API documentation from code comments
-  4. Update CHANGELOG.md with recent changes
+  You are a code review assistant. Analyze code and provide feedback on:
+  - Code quality and readability
+  - Security vulnerabilities
+  - Performance issues
+  - Best practices adherence
+activities:
+  - Analyze code structure
+  - Check for security issues
+  - Review performance patterns
+extensions:
+  - type: builtin
+    name: developer
+    display_name: Developer
+    timeout: 300
+    bundled: true
+parameters:
+  - key: focus_area
+    input_type: string
+    requirement: optional
+    description: "Specific area to focus on (security, performance, readability, etc.)"
+    default: "general"
+prompt: |
+  Please review the following code focusing on {{focus_area}} aspects.
+  Provide specific, actionable feedback with examples.
 ```
 
-**Command:**
-```bash
-goose run --recipe create-docs.yaml
+**Place your recipe file where Goose can find it**
+- Set [`GOOSE_RECIPE_PATH`](/docs/guides/recipes/recipe-reference#recipe-location) environment variable to your recipe directory
+- Or place it in your current working directory
+
+**Goose Prompt**
+```
+Use the "code-reviewer" recipe to analyze the authentication feature I implemented
 ```
 
-**Tool Output:**
-```json
-{
-  "execution_summary": {
-    "total_tasks": 1,
-    "successful_tasks": 1,
-    "failed_tasks": 0,
-    "execution_time_seconds": 45.8
-  },
-  "task_results": [
-    {
-      "task_id": "create_docs_recipe",
-      "status": "success",
-      "result": "Successfully generated project documentation: README.md updated, API docs created, CHANGELOG.md refreshed"
-    }
-  ]
-}
+**Goose Output**
+```
+I'll use your code-reviewer recipe to create a specialized subagent for this analysis.
+
+🤖 Subagent created using code-reviewer recipe
+💭 Analyzing authentication function for security issues...
+🔧 Scanning code structure and patterns...
+⚠️  Security vulnerabilities detected!
+
+## Code Review Results
+
+### Critical Issues Found:
+1. **SQL Injection Vulnerability**: Direct string interpolation in SQL query
+2. **Missing Password Hashing**: Plain text password comparison
+
+### Recommendations:
+- Use parameterized queries or ORM
+- Implement proper password hashing (bcrypt, scrypt)
+- Add input validation and sanitization
 ```
 
 ## External Subagents
@@ -193,19 +230,50 @@ The architecture follows a modular design with clear separation between the core
 
 Subagents are temporary instances that exist only for task execution. After the task is completed, no manual intervention is needed for cleanup.
 
+## Configuration
+
+Subagents are automatically have the following pre-configured settings, but you can override any defaults using natural language in your prompts.
+
+### Default Settings
+| Parameter | Default | Source |
+|-----------|---------|--------|
+| **Max Turns** | 10 | Built-in default |
+| **Timeout** | 5 minutes | Built-in default |
+
+
 :::info
-If a subagent fails or times out (5-minute default), you receive no output from that subagent. For parallel execution, if any subagent fails, you get results only from the successful ones.
+If a subagent fails or times out (5-minute default), you will receive no output from that subagent. For parallel execution, if any subagent fails, you get results only from the successful ones.
 :::
 
-## Configuration
+### Customizing Settings in Prompts
+
+You can override any default by including the setting in your natural language request:
+
+**Examples:**
+
+```
+"Use subagents to write a test and documentation, but make them timeout after 7 minutes"
+```
+
+```
+""Use subagents to analyze code, limit each to 5 turns""
+```
+
+## Security Constraints
+
+Subagents operate with filtered tool access for security:
+
+**Subagents can:**
+✅ Search for extensions (safe platform tool)
+
+✅ Read resources (safe platform tool)
+
+✅ Use inherited/recipe extensions (filtered for safety)
 
-Goose automatically configures subagents by looking at environment variables, user prompts, and recipe files to determine the best settings for each task.
+**Subagents cannot:**
+❌ Spawn other subagents (prevents infinite recursion)
 
+❌ Manage extensions (prevents interference with parent)
 
-| Parameter | Description | Default | Example |
-|-----------|-------------|---------|---------|
-| **Instructions** | Task-specific behavior and context | Auto-generated from user request | `"You are a code reviewer focusing on security"` |
-| **Max Turns** | Conversation limit before auto-completion | 10 | Set higher for complex tasks |
-| **Timeout** | Maximum execution time | 5 minutes | Prevents runaway processes |
-| **Extensions** | Available tools and capabilities | Inherits from main session | Recipe can specify subset |
+❌ Manage schedules (prevents interference with parent)
 

From 56d0022711d627abc905f8e943a4abdf878fa5b8 Mon Sep 17 00:00:00 2001
From: angiejones <jones.angie@gmail.com>
Date: Mon, 14 Jul 2025 19:32:45 -0500
Subject: [PATCH 10/12] adding new line to fix wrapping

---
 documentation/docs/experimental/subagents.md | 29 ++++++++++++++++----
 1 file changed, 23 insertions(+), 6 deletions(-)

diff --git a/documentation/docs/experimental/subagents.md b/documentation/docs/experimental/subagents.md
index 46efdd6f7765..7759ba896596 100644
--- a/documentation/docs/experimental/subagents.md
+++ b/documentation/docs/experimental/subagents.md
@@ -14,12 +14,27 @@ Subagents are an experimental feature in active development. Behavior and config
 
 To use subagents, simply ask Goose to delegate tasks using natural language. Goose automatically decides when to spawn subagents and handles their lifecycle. You can:
 
-1. **Request specialized help**: "Use a code reviewer to analyze this function for security issues"
-2. **Reference specific recipes**: "Use the 'security-auditor' recipe to scan this endpoint"  
-3. **Run parallel tasks**: "Create three HTML templates simultaneously"
-4. **Delegate complex work**: "Research quantum computing developments and summarize findings"
+**Request specialized help**: 
+```
+Use a code reviewer to analyze this function for security issues
+```
 
-You can run multiple subagents sequentially or in parallel.
+**Reference specific recipes**
+```
+Use the 'security-auditor' recipe to scan this endpoint
+```
+
+**Run parallel tasks**:
+```
+Create three HTML templates simultaneously
+```
+
+**Delegate complex work**:
+```
+Research quantum computing developments and summarize findings
+```
+
+You can run multiple subagents sequentially or in parallel:
 
 | Type | Description | Trigger Keywords | Example |
 |------|-------------|------------------|---------|
@@ -49,7 +64,7 @@ Direct prompts provided for one-off tasks using natural language prompts. The ma
 
 **Goose Prompt:**
 ```
-"Use 2 subagents to create hello.html with 'Hello World' content and goodbye.html with 'Goodbye World' content in parallel"
+Use 2 subagents to create hello.html with 'Hello World' content and goodbye.html with 'Goodbye World' content in parallel
 ```
 
 **Tool Output:**
@@ -264,6 +279,7 @@ You can override any default by including the setting in your natural language r
 Subagents operate with filtered tool access for security:
 
 **Subagents can:**
+
 ✅ Search for extensions (safe platform tool)
 
 ✅ Read resources (safe platform tool)
@@ -271,6 +287,7 @@ Subagents operate with filtered tool access for security:
 ✅ Use inherited/recipe extensions (filtered for safety)
 
 **Subagents cannot:**
+
 ❌ Spawn other subagents (prevents infinite recursion)
 
 ❌ Manage extensions (prevents interference with parent)

From c947fc1132176e904a35aa0da738ed4a837997b5 Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Mon, 14 Jul 2025 22:56:03 -0400
Subject: [PATCH 11/12] adding more info

---
 documentation/docs/experimental/subagents.md | 39 ++++++++++++--------
 1 file changed, 23 insertions(+), 16 deletions(-)

diff --git a/documentation/docs/experimental/subagents.md b/documentation/docs/experimental/subagents.md
index 46efdd6f7765..34982c972c5f 100644
--- a/documentation/docs/experimental/subagents.md
+++ b/documentation/docs/experimental/subagents.md
@@ -12,7 +12,7 @@ Subagents are an experimental feature in active development. Behavior and config
 
 ## How to Use Subagents
 
-To use subagents, simply ask Goose to delegate tasks using natural language. Goose automatically decides when to spawn subagents and handles their lifecycle. You can:
+To use subagents, ask Goose to delegate tasks using natural language. Goose automatically decides when to spawn subagents and handles their lifecycle. You can:
 
 1. **Request specialized help**: "Use a code reviewer to analyze this function for security issues"
 2. **Reference specific recipes**: "Use the 'security-auditor' recipe to scan this endpoint"  
@@ -26,6 +26,10 @@ You can run multiple subagents sequentially or in parallel.
 | **Sequential** (Default) | Tasks execute one after another | "first...then", "after" | `"First analyze the code, then generate documentation"` |
 | **Parallel** | Tasks execute simultaneously | "parallel", "simultaneously", "at the same time", "concurrently" | `"Create three HTML templates in parallel"` |
 
+:::info
+If a subagent fails or times out (5-minute default), you will receive no output from that subagent. For parallel execution, if any subagent fails, you get results only from the successful ones.
+:::
+
 
 ## Prerequisites
 To use subagents, you need to enable alpha features first. You can do this by setting an [environment variable](/docs/guides/environment-variables#experimental-features) or adding it to your [config file](/docs/guides/config-file#experimental-features):
@@ -42,7 +46,10 @@ ALPHA_FEATURES: true
 
 ## Internal Subagents
 
-Internal subagents spawn Goose instances to handle tasks using your current session's context and extensions. 
+Internal subagents spawn Goose instances to handle tasks using your current session's context and extensions. There are two ways to configure and execute internal subagents:
+
+1. **Direct Prompts** - Quick, one-off tasks using natural language instructions
+2. **Recipes** - Reusable, structured configurations for specialized subagent behavior
 
 ### Direct Prompts
 Direct prompts provided for one-off tasks using natural language prompts. The main agent automatically configures the subagent based on your request.
@@ -240,11 +247,6 @@ Subagents are automatically have the following pre-configured settings, but you
 | **Max Turns** | 10 | Built-in default |
 | **Timeout** | 5 minutes | Built-in default |
 
-
-:::info
-If a subagent fails or times out (5-minute default), you will receive no output from that subagent. For parallel execution, if any subagent fails, you get results only from the successful ones.
-:::
-
 ### Customizing Settings in Prompts
 
 You can override any default by including the setting in your natural language request:
@@ -261,19 +263,24 @@ You can override any default by including the setting in your natural language r
 
 ## Security Constraints
 
-Subagents operate with filtered tool access for security:
+Subagents operate with restricted tool access to ensure safe execution and prevent interference with the main session.
 
-**Subagents can:**
-✅ Search for extensions (safe platform tool)
+### Allowed Operations
 
-✅ Read resources (safe platform tool)
+Subagents have access to these safe operations:
 
-✅ Use inherited/recipe extensions (filtered for safety)
+- **Extension discovery**: Search for available extensions to understand what tools are available
+- **Resource access**: Read and list resources from enabled extensions for context
+- **Extension tools**: Use tools from extensions specified in recipes or inherited from the parent session
 
-**Subagents cannot:**
-❌ Spawn other subagents (prevents infinite recursion)
+### Restricted Operations
 
-❌ Manage extensions (prevents interference with parent)
+The following operations are blocked to ensure subagents remain focused on their assigned tasks without affecting the broader system state:
 
-❌ Manage schedules (prevents interference with parent)
+- **Subagent spawning**: Cannot create additional subagents to prevent infinite recursion
+- **Extension management**: Cannot enable, disable, or modify extensions to avoid conflicts with the main session
+- **Schedule management**: Cannot create, modify, or delete scheduled tasks to prevent interference with parent workflows
 
+:::info
+Subagents can browse extensions for suggestions but cannot enable them to avoid modifying the parent session.
+:::

From 4b877088f174c2af326bba1f1d669fb7f7b3fd84 Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Mon, 14 Jul 2025 22:59:26 -0400
Subject: [PATCH 12/12] move card order

---
 documentation/docs/experimental/index.md     | 10 +++---
 documentation/docs/experimental/subagents.md | 35 +++++---------------
 2 files changed, 13 insertions(+), 32 deletions(-)

diff --git a/documentation/docs/experimental/index.md b/documentation/docs/experimental/index.md
index 3792ea522ba8..722f43051c76 100644
--- a/documentation/docs/experimental/index.md
+++ b/documentation/docs/experimental/index.md
@@ -19,6 +19,11 @@ The list of experimental features may change as Goose development progresses. So
 <div className={styles.categorySection}>
   <h2 className={styles.categoryTitle}>🧪 Experimental Features</h2>
   <div className={styles.cardGrid}>
+      <Card 
+      title="Subagents"
+      description="Independent instances that execute tasks while keeping your main conversation clean and focused. Run tasks sequentially or in parallel with process isolation and context preservation."
+      link="/docs/experimental/subagents"
+    />
     <Card 
       title="Ollama Tool Shim"
       description="Enable tool calling capabilities for language models that don't natively support tool calling (like DeepSeek) using an experimental local interpreter model setup."
@@ -29,11 +34,6 @@ The list of experimental features may change as Goose development progresses. So
       description="An experimental Android automation app that acts as an open agent running on your phone, providing maximal automation of everyday tasks."
       link="/docs/experimental/goose-mobile"
     />
-    <Card 
-      title="Subagents"
-      description="Independent instances that execute tasks while keeping your main conversation clean and focused. Run tasks sequentially or in parallel with process isolation and context preservation."
-      link="/docs/experimental/subagents"
-    />
   </div>
 </div>
 
diff --git a/documentation/docs/experimental/subagents.md b/documentation/docs/experimental/subagents.md
index 993737e19765..34982c972c5f 100644
--- a/documentation/docs/experimental/subagents.md
+++ b/documentation/docs/experimental/subagents.md
@@ -14,27 +14,12 @@ Subagents are an experimental feature in active development. Behavior and config
 
 To use subagents, ask Goose to delegate tasks using natural language. Goose automatically decides when to spawn subagents and handles their lifecycle. You can:
 
-**Request specialized help**: 
-```
-Use a code reviewer to analyze this function for security issues
-```
+1. **Request specialized help**: "Use a code reviewer to analyze this function for security issues"
+2. **Reference specific recipes**: "Use the 'security-auditor' recipe to scan this endpoint"  
+3. **Run parallel tasks**: "Create three HTML templates simultaneously"
+4. **Delegate complex work**: "Research quantum computing developments and summarize findings"
 
-**Reference specific recipes**
-```
-Use the 'security-auditor' recipe to scan this endpoint
-```
-
-**Run parallel tasks**:
-```
-Create three HTML templates simultaneously
-```
-
-**Delegate complex work**:
-```
-Research quantum computing developments and summarize findings
-```
-
-You can run multiple subagents sequentially or in parallel:
+You can run multiple subagents sequentially or in parallel.
 
 | Type | Description | Trigger Keywords | Example |
 |------|-------------|------------------|---------|
@@ -71,7 +56,7 @@ Direct prompts provided for one-off tasks using natural language prompts. The ma
 
 **Goose Prompt:**
 ```
-Use 2 subagents to create hello.html with 'Hello World' content and goodbye.html with 'Goodbye World' content in parallel
+"Use 2 subagents to create hello.html with 'Hello World' content and goodbye.html with 'Goodbye World' content in parallel"
 ```
 
 **Tool Output:**
@@ -280,9 +265,7 @@ You can override any default by including the setting in your natural language r
 
 Subagents operate with restricted tool access to ensure safe execution and prevent interference with the main session.
 
-**Subagents can:**
-
-✅ Search for extensions (safe platform tool)
+### Allowed Operations
 
 Subagents have access to these safe operations:
 
@@ -290,9 +273,7 @@ Subagents have access to these safe operations:
 - **Resource access**: Read and list resources from enabled extensions for context
 - **Extension tools**: Use tools from extensions specified in recipes or inherited from the parent session
 
-**Subagents cannot:**
-
-❌ Spawn other subagents (prevents infinite recursion)
+### Restricted Operations
 
 The following operations are blocked to ensure subagents remain focused on their assigned tasks without affecting the broader system state: