From 415d80636d8ccb31700326b5cae854c6ba044b58 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 25 Mar 2026 18:14:47 +0000
Subject: [PATCH 1/3] Initial plan


From 9c231ce4ed7d5c7e8bb80dd8edee889574164013 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 25 Mar 2026 18:36:31 +0000
Subject: [PATCH 2/3] feat: enable max-turns support for Copilot engine

Enable the `max-turns` frontmatter option for the Copilot engine,
allowing workflow authors to control the turn limit for complex
build workflows. The execution code already supported setting
GH_AW_MAX_TURNS env var; this change removes the validation gate
that blocked usage with the Copilot engine.

Fixes the largest category of pipeline failures where agents making
good progress get cut off before completing their task.

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
Agent-Logs-Url: https://github.com/github/gh-aw/sessions/ec5f6eda-e028-46d8-a829-eb10a578faf1
---
 docs/src/content/docs/reference/engines.md    |  4 +--
 .../docs/reference/frontmatter-full.md        |  4 +--
 pkg/parser/schemas/main_workflow_schema.json  |  2 +-
 pkg/workflow/copilot_engine.go                |  2 +-
 pkg/workflow/copilot_engine_test.go           |  4 +--
 pkg/workflow/max_turns_validation_test.go     | 25 +++++++++++++++++++
 scratchpad/token-budget-guidelines.md         | 13 +++++++---
 7 files changed, 43 insertions(+), 11 deletions(-)

diff --git a/docs/src/content/docs/reference/engines.md b/docs/src/content/docs/reference/engines.md
index 94f851c4baf..5ef9c5094e6 100644
--- a/docs/src/content/docs/reference/engines.md
+++ b/docs/src/content/docs/reference/engines.md
@@ -26,7 +26,7 @@ Not all features are available across all engines. The table below summarizes pe
 
 | Feature | Copilot | Claude | Codex | Gemini |
 |---------|:-------:|:------:|:-----:|:------:|
-| `max-turns` | ❌ | ✅ | ❌ | ❌ |
+| `max-turns` | ✅ | ✅ | ❌ | ❌ |
 | `max-continuations` | ✅ | ❌ | ❌ | ❌ |
 | `tools.web-fetch` | ✅ | ✅ | ✅ | ✅ |
 | `tools.web-search` | via MCP | via MCP | ✅ (opt-in) | via MCP |
@@ -35,7 +35,7 @@ Not all features are available across all engines. The table below summarizes pe
 | Tools allowlist | ✅ | ✅ | ✅ | ✅ |
 
 **Notes:**
-- `max-turns` limits the number of AI chat iterations per run (Claude only).
+- `max-turns` limits the number of AI chat iterations per run (Copilot and Claude).
 - `max-continuations` enables autopilot mode with multiple consecutive runs (Copilot only).
 - `web-search` for Codex is disabled by default; add `tools: web-search:` to enable it. Other engines use a third-party MCP server — see [Using Web Search](/gh-aw/guides/web-search/).
 - `engine.agent` references a `.github/agents/` file for custom Copilot agent behavior. See [Copilot Custom Configuration](#copilot-custom-configuration).
diff --git a/docs/src/content/docs/reference/frontmatter-full.md b/docs/src/content/docs/reference/frontmatter-full.md
index 54ade376735..b6f0c1befb2 100644
--- a/docs/src/content/docs/reference/frontmatter-full.md
+++ b/docs/src/content/docs/reference/frontmatter-full.md
@@ -1492,8 +1492,8 @@ engine:
   model: "example-value"
 
   # Maximum number of chat iterations per run. Helps prevent runaway loops and
-  # control costs. Has sensible defaults and can typically be omitted. Note: Only
-  # supported by the claude engine.
+  # control costs. Has sensible defaults and can typically be omitted. Note:
+  # Supported by the copilot and claude engines.
   # (optional)
   # This field supports multiple formats (oneOf):
 
diff --git a/pkg/parser/schemas/main_workflow_schema.json b/pkg/parser/schemas/main_workflow_schema.json
index 22ab3f984b4..b1f940672f9 100644
--- a/pkg/parser/schemas/main_workflow_schema.json
+++ b/pkg/parser/schemas/main_workflow_schema.json
@@ -8861,7 +8861,7 @@
                   "description": "Maximum number of chat iterations per run as a string value"
                 }
               ],
-              "description": "Maximum number of chat iterations per run. Helps prevent runaway loops and control costs. Has sensible defaults and can typically be omitted. Note: Only supported by the claude engine."
+              "description": "Maximum number of chat iterations per run. Helps prevent runaway loops and control costs. Has sensible defaults and can typically be omitted. Note: Supported by the copilot and claude engines."
             },
             "max-continuations": {
               "type": "integer",
diff --git a/pkg/workflow/copilot_engine.go b/pkg/workflow/copilot_engine.go
index 26cdb017d07..838e998b144 100644
--- a/pkg/workflow/copilot_engine.go
+++ b/pkg/workflow/copilot_engine.go
@@ -39,7 +39,7 @@ func NewCopilotEngine() *CopilotEngine {
 			description:              "Uses GitHub Copilot CLI with MCP server support",
 			experimental:             false,
 			supportsToolsAllowlist:   true,
-			supportsMaxTurns:         false, // Copilot CLI does not support max-turns feature yet
+			supportsMaxTurns:         true,  // Copilot CLI supports max-turns via GH_AW_MAX_TURNS env var
 			supportsMaxContinuations: true,  // Copilot CLI supports --autopilot with --max-autopilot-continues
 			supportsWebFetch:         true,  // Copilot CLI has built-in web-fetch support
 			supportsWebSearch:        false, // Copilot CLI does not have built-in web-search support
diff --git a/pkg/workflow/copilot_engine_test.go b/pkg/workflow/copilot_engine_test.go
index 91e198995a1..1c00154859e 100644
--- a/pkg/workflow/copilot_engine_test.go
+++ b/pkg/workflow/copilot_engine_test.go
@@ -34,8 +34,8 @@ func TestCopilotEngine(t *testing.T) {
 		t.Error("Expected copilot engine to support tools allowlist")
 	}
 
-	if engine.SupportsMaxTurns() {
-		t.Error("Expected copilot engine to not support max-turns yet")
+	if !engine.SupportsMaxTurns() {
+		t.Error("Expected copilot engine to support max-turns")
 	}
 
 	// Test declared output files (session files are copied to logs folder)
diff --git a/pkg/workflow/max_turns_validation_test.go b/pkg/workflow/max_turns_validation_test.go
index f145aa7fcf7..6e9439c38e8 100644
--- a/pkg/workflow/max_turns_validation_test.go
+++ b/pkg/workflow/max_turns_validation_test.go
@@ -60,6 +60,26 @@ This should succeed because claude supports max-turns.`,
 			engine:      "claude",
 			expectError: false,
 		},
+		{
+			name: "max-turns with copilot engine should succeed",
+			content: `---
+on:
+  workflow_dispatch:
+permissions:
+  contents: read
+  issues: read
+  pull-requests: read
+engine:
+  id: copilot
+  max-turns: 60
+---
+
+# Test Workflow
+
+This should succeed because copilot supports max-turns.`,
+			engine:      "copilot",
+			expectError: false,
+		},
 		{
 			name: "codex engine without max-turns should succeed",
 			content: `---
@@ -148,6 +168,11 @@ func TestEngineSupportsMaxTurns(t *testing.T) {
 			engineID:        "claude",
 			expectedSupport: true,
 		},
+		{
+			name:            "copilot engine supports max-turns",
+			engineID:        "copilot",
+			expectedSupport: true,
+		},
 		{
 			name:            "codex engine does not support max-turns",
 			engineID:        "codex",
diff --git a/scratchpad/token-budget-guidelines.md b/scratchpad/token-budget-guidelines.md
index 982b0f2537e..6b1f673d8cb 100644
--- a/scratchpad/token-budget-guidelines.md
+++ b/scratchpad/token-budget-guidelines.md
@@ -15,11 +15,18 @@ This document establishes token budget targets and optimization strategies for a
 
 ### Available Controls
 
-#### 1. `max-turns` (For Claude/Custom Engines Only)
+#### 1. `max-turns` (For Copilot/Claude/Custom Engines)
 
 Limits the number of conversation rounds between the agent and the AI engine.
 
-**Important:** `max-turns` is **only supported by Claude and Custom engines**, not Copilot. For Copilot workflows, use prompt optimization and timeout controls instead.
+```yaml
+---
+# Copilot engine with max-turns
+engine:
+  id: copilot
+  max-turns: 60  # Recommended for complex build workflows
+---
+```
 
 ```yaml
 ---
@@ -46,9 +53,9 @@ engine:
 - Earlier termination if task completes
 
 **Engine Support:**
+- ✅ **Copilot**: Fully supported
 - ✅ **Claude**: Fully supported
 - ✅ **Custom**: Fully supported
-- ❌ **Copilot**: Not supported - use prompt optimization instead
 - ❌ **Codex**: Not supported
 
 #### 2. `timeout-minutes` (Secondary Control)

From f398dbc3e7891a1c8b668745bf98bd2d65b68fd0 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 25 Mar 2026 19:36:31 +0000
Subject: [PATCH 3/3] revert: Copilot CLI does not natively support max-turns

The Copilot CLI has no --max-turns flag (unlike Claude CLI which does).
While GH_AW_MAX_TURNS env var is set in the execution environment,
the Copilot CLI ignores it entirely. Enabling supportsMaxTurns would
mislead users into thinking they can control the turn limit when
the setting would have no effect.

Reverting all changes until the Copilot CLI adds native max-turns support.

Agent-Logs-Url: https://github.com/github/gh-aw/sessions/f8a1aad5-5e08-48ab-b056-20ec1d4e74c9

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
---
 docs/src/content/docs/reference/engines.md    |  4 +--
 .../docs/reference/frontmatter-full.md        |  4 +--
 pkg/parser/schemas/main_workflow_schema.json  |  2 +-
 pkg/workflow/copilot_engine.go                |  2 +-
 pkg/workflow/copilot_engine_test.go           |  4 +--
 pkg/workflow/max_turns_validation_test.go     | 25 -------------------
 scratchpad/token-budget-guidelines.md         | 13 +++-------
 7 files changed, 11 insertions(+), 43 deletions(-)

diff --git a/docs/src/content/docs/reference/engines.md b/docs/src/content/docs/reference/engines.md
index 5ef9c5094e6..94f851c4baf 100644
--- a/docs/src/content/docs/reference/engines.md
+++ b/docs/src/content/docs/reference/engines.md
@@ -26,7 +26,7 @@ Not all features are available across all engines. The table below summarizes pe
 
 | Feature | Copilot | Claude | Codex | Gemini |
 |---------|:-------:|:------:|:-----:|:------:|
-| `max-turns` | ✅ | ✅ | ❌ | ❌ |
+| `max-turns` | ❌ | ✅ | ❌ | ❌ |
 | `max-continuations` | ✅ | ❌ | ❌ | ❌ |
 | `tools.web-fetch` | ✅ | ✅ | ✅ | ✅ |
 | `tools.web-search` | via MCP | via MCP | ✅ (opt-in) | via MCP |
@@ -35,7 +35,7 @@ Not all features are available across all engines. The table below summarizes pe
 | Tools allowlist | ✅ | ✅ | ✅ | ✅ |
 
 **Notes:**
-- `max-turns` limits the number of AI chat iterations per run (Copilot and Claude).
+- `max-turns` limits the number of AI chat iterations per run (Claude only).
 - `max-continuations` enables autopilot mode with multiple consecutive runs (Copilot only).
 - `web-search` for Codex is disabled by default; add `tools: web-search:` to enable it. Other engines use a third-party MCP server — see [Using Web Search](/gh-aw/guides/web-search/).
 - `engine.agent` references a `.github/agents/` file for custom Copilot agent behavior. See [Copilot Custom Configuration](#copilot-custom-configuration).
diff --git a/docs/src/content/docs/reference/frontmatter-full.md b/docs/src/content/docs/reference/frontmatter-full.md
index b6f0c1befb2..54ade376735 100644
--- a/docs/src/content/docs/reference/frontmatter-full.md
+++ b/docs/src/content/docs/reference/frontmatter-full.md
@@ -1492,8 +1492,8 @@ engine:
   model: "example-value"
 
   # Maximum number of chat iterations per run. Helps prevent runaway loops and
-  # control costs. Has sensible defaults and can typically be omitted. Note:
-  # Supported by the copilot and claude engines.
+  # control costs. Has sensible defaults and can typically be omitted. Note: Only
+  # supported by the claude engine.
   # (optional)
   # This field supports multiple formats (oneOf):
 
diff --git a/pkg/parser/schemas/main_workflow_schema.json b/pkg/parser/schemas/main_workflow_schema.json
index b1f940672f9..22ab3f984b4 100644
--- a/pkg/parser/schemas/main_workflow_schema.json
+++ b/pkg/parser/schemas/main_workflow_schema.json
@@ -8861,7 +8861,7 @@
                   "description": "Maximum number of chat iterations per run as a string value"
                 }
               ],
-              "description": "Maximum number of chat iterations per run. Helps prevent runaway loops and control costs. Has sensible defaults and can typically be omitted. Note: Supported by the copilot and claude engines."
+              "description": "Maximum number of chat iterations per run. Helps prevent runaway loops and control costs. Has sensible defaults and can typically be omitted. Note: Only supported by the claude engine."
             },
             "max-continuations": {
               "type": "integer",
diff --git a/pkg/workflow/copilot_engine.go b/pkg/workflow/copilot_engine.go
index 838e998b144..26cdb017d07 100644
--- a/pkg/workflow/copilot_engine.go
+++ b/pkg/workflow/copilot_engine.go
@@ -39,7 +39,7 @@ func NewCopilotEngine() *CopilotEngine {
 			description:              "Uses GitHub Copilot CLI with MCP server support",
 			experimental:             false,
 			supportsToolsAllowlist:   true,
-			supportsMaxTurns:         true,  // Copilot CLI supports max-turns via GH_AW_MAX_TURNS env var
+			supportsMaxTurns:         false, // Copilot CLI does not support max-turns feature yet
 			supportsMaxContinuations: true,  // Copilot CLI supports --autopilot with --max-autopilot-continues
 			supportsWebFetch:         true,  // Copilot CLI has built-in web-fetch support
 			supportsWebSearch:        false, // Copilot CLI does not have built-in web-search support
diff --git a/pkg/workflow/copilot_engine_test.go b/pkg/workflow/copilot_engine_test.go
index 1c00154859e..91e198995a1 100644
--- a/pkg/workflow/copilot_engine_test.go
+++ b/pkg/workflow/copilot_engine_test.go
@@ -34,8 +34,8 @@ func TestCopilotEngine(t *testing.T) {
 		t.Error("Expected copilot engine to support tools allowlist")
 	}
 
-	if !engine.SupportsMaxTurns() {
-		t.Error("Expected copilot engine to support max-turns")
+	if engine.SupportsMaxTurns() {
+		t.Error("Expected copilot engine to not support max-turns yet")
 	}
 
 	// Test declared output files (session files are copied to logs folder)
diff --git a/pkg/workflow/max_turns_validation_test.go b/pkg/workflow/max_turns_validation_test.go
index 6e9439c38e8..f145aa7fcf7 100644
--- a/pkg/workflow/max_turns_validation_test.go
+++ b/pkg/workflow/max_turns_validation_test.go
@@ -60,26 +60,6 @@ This should succeed because claude supports max-turns.`,
 			engine:      "claude",
 			expectError: false,
 		},
-		{
-			name: "max-turns with copilot engine should succeed",
-			content: `---
-on:
-  workflow_dispatch:
-permissions:
-  contents: read
-  issues: read
-  pull-requests: read
-engine:
-  id: copilot
-  max-turns: 60
----
-
-# Test Workflow
-
-This should succeed because copilot supports max-turns.`,
-			engine:      "copilot",
-			expectError: false,
-		},
 		{
 			name: "codex engine without max-turns should succeed",
 			content: `---
@@ -168,11 +148,6 @@ func TestEngineSupportsMaxTurns(t *testing.T) {
 			engineID:        "claude",
 			expectedSupport: true,
 		},
-		{
-			name:            "copilot engine supports max-turns",
-			engineID:        "copilot",
-			expectedSupport: true,
-		},
 		{
 			name:            "codex engine does not support max-turns",
 			engineID:        "codex",
diff --git a/scratchpad/token-budget-guidelines.md b/scratchpad/token-budget-guidelines.md
index 6b1f673d8cb..982b0f2537e 100644
--- a/scratchpad/token-budget-guidelines.md
+++ b/scratchpad/token-budget-guidelines.md
@@ -15,18 +15,11 @@ This document establishes token budget targets and optimization strategies for a
 
 ### Available Controls
 
-#### 1. `max-turns` (For Copilot/Claude/Custom Engines)
+#### 1. `max-turns` (For Claude/Custom Engines Only)
 
 Limits the number of conversation rounds between the agent and the AI engine.
 
-```yaml
----
-# Copilot engine with max-turns
-engine:
-  id: copilot
-  max-turns: 60  # Recommended for complex build workflows
----
-```
+**Important:** `max-turns` is **only supported by Claude and Custom engines**, not Copilot. For Copilot workflows, use prompt optimization and timeout controls instead.
 
 ```yaml
 ---
@@ -53,9 +46,9 @@ engine:
 - Earlier termination if task completes
 
 **Engine Support:**
-- ✅ **Copilot**: Fully supported
 - ✅ **Claude**: Fully supported
 - ✅ **Custom**: Fully supported
+- ❌ **Copilot**: Not supported - use prompt optimization instead
 - ❌ **Codex**: Not supported
 
 #### 2. `timeout-minutes` (Secondary Control)