Enforce sandbox-disable justification strings and surface new AWF import/safe-output constraints (#38228)

Author: Copilot

.github/aw/create-agentic-workflow.md

@@ -148,6 +148,7 @@ Rules:
 - always restrict `create-pull-request.allowed-files`
 - prefer the dedicated safe output instead of shelling out to `gh` for the same mutation
 - include `noop` guidance in the prompt so successful no-op runs are explicit
+- when using `create-issue`, instruct the agent to provide a meaningful body (20-65000 characters; avoid placeholder-only text)
 
 ### 7. Decide who can trigger the workflow
 

.github/aw/experiments.md

@@ -292,5 +292,5 @@ experiments:
 - ❌ **Interpreting early results** (<~20 runs/variant) — chance variation dominates.
 - ❌ **Experiments as feature flags** — use `features:` for deterministic switches.
 - ❌ **Engine experiments in one file** — `engine:` cannot switch mid-run; use two parallel files.
-- ❌ **Nesting `{{#if experiments.<name> }}` inside `{{#runtime-import? }}`** — evaluation order not guaranteed across import boundaries.
+- ❌ **Nesting `{{#if experiments.<name> }}` inside `{{#runtime-import? }}`** — evaluation order is brittle across import boundaries. Prefer explicit branching in the main workflow prompt or separate workflow files per variant.
 - ❌ **Writing the internal env-var form** `__GH_AW_EXPERIMENTS__*` — implementation detail, may change.

.github/aw/safe-outputs-content.md

@@ -26,6 +26,10 @@ description: Safe-output reference for issue, discussion, comment, and pull requ
       allowed-repos: [owner/other]    # Optional: additional repos agent can target (agent uses `repo` field in output)
   ```
 
+  `create_issue` output validation requires:
+  - `body` minimum length: **20** characters
+  - `body` maximum length: **65000** characters
+
   **Auto-Expiration**: The `expires` field auto-closes issues after a time period. Supports integers (days) or relative formats (2h, 7d, 2w, 1m, 1y). Generates `agentics-maintenance.yml` workflow that runs at minimum required frequency based on shortest expiration time: 1 day or less → every 2 hours, 2 days → every 6 hours, 3-4 days → every 12 hours, 5+ days → daily.
   **Deduplication for Scheduled Workflows**: When a `schedule:` trigger is combined with `create-issue`, use `skip-if-match:` in the `on:` block to prevent opening a duplicate issue on every run. Pair with `expires:` so stale issues are cleaned up automatically:
 

.github/aw/syntax-agentic.md

@@ -62,6 +62,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
     - `cli-proxy: true` - Enable AWF CLI proxy sidecar for secure read-only `gh` CLI access without exposing `GITHUB_TOKEN` (requires AWF v0.26.0+). Prerequisite for `integrity-reactions`; the compiler enables it automatically when `integrity-reactions: true` is set.
     - `integrity-reactions: true` - Enable reaction-based integrity promotion/demotion. Maintainers can use 👍/❤️ reactions to promote content to `approved` and 👎/😕 to demote it to `none`. Compiler automatically enables `cli-proxy`. Requires `tools.github.min-integrity` to be set and MCPG >= v0.2.18. Defaults: endorsement reactions THUMBS_UP/HEART, disapproval reactions THUMBS_DOWN/CONFUSED, endorser-min-integrity: approved, disapproval-integrity: none.
     - `mcp-cli: true` - Deprecated. This flag has been removed; MCP CLI mounting is now always enabled when `tools.cli-proxy: true` is set.
+    - `dangerously-disable-sandbox-agent: "<justification>"` - Required when `sandbox.agent: false` is set. Must be a plain string justification (minimum 20 characters; expressions are not allowed) that explains why disabling the sandbox is safe for this workflow.
 
 - **`experiments:`** - A/B testing experiments for balanced variant selection (object)
   - Maps experiment names to variant lists (bare array) or full config objects
@@ -343,9 +344,11 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
         model-fallback: false       # Optional: disable model fallback (default true); set false for BYOK Azure OpenAI to prevent deployment-name rewriting
     ```
 
-  - To disable the agent firewall while keeping MCP gateway enabled (not allowed in strict mode):
+  - To disable the agent firewall while keeping MCP gateway enabled, you must provide the dangerous-disable justification feature:
 
     ```yaml
+    features:
+      dangerously-disable-sandbox-agent: "controlled environment with no internet access"
     sandbox:
       agent: false
     ```

.github/aw/upgrade-agentic-workflows.md

@@ -102,7 +102,13 @@ Before attempting to compile, apply automatic codemods:
 
    This will automatically update workflow files with changes like:
    - Replacing 'timeout_minutes' with 'timeout-minutes'
-   - Replacing 'network.firewall' with 'sandbox.agent: false'
+   - Replacing `network.firewall: false` with:
+     ```yaml
+     features:
+       dangerously-disable-sandbox-agent: "controlled environment with no internet access"
+     sandbox:
+       agent: false
+     ```
    - Removing deprecated 'mcp-scripts.mode' field
 
 2. **Review the Changes**

docs/src/content/docs/reference/safe-outputs.md

@@ -129,6 +129,8 @@ See [Cross-Repository Operations](/gh-aw/reference/cross-repository/) for compre
 
 #### `create_issue` tool field schema (`fields`)
 
+`create_issue.body` must be between **20** and **65000** characters.
+
 | Parameter | Type | Required | Description | Example |
 |-----------|------|----------|-------------|---------|
 | `fields` | `array<object>` | No | Optional issue field updates to apply immediately after issue creation. | `[{"name":"Priority","value":"P1"}]` |

pkg/cli/codemod_network_firewall.go

@@ -1,6 +1,7 @@
 package cli
 
 import (
+	"fmt"
 	"strconv"
 	"strings"
 
@@ -9,6 +10,8 @@ import (
 
 var networkFirewallCodemodLog = logger.New("cli:codemod_network_firewall")
 
+const migratedSandboxDisableJustification = "migrated from deprecated network.firewall disable setting"
+
 // getNetworkFirewallCodemod creates a codemod for migrating network.firewall to sandbox.agent
 func getNetworkFirewallCodemod() Codemod {
 	return newFieldRemovalCodemod(fieldRemovalCodemodConfig{
@@ -21,26 +24,44 @@ func getNetworkFirewallCodemod() Codemod {
 		LogMsg:       "Applied network.firewall migration (firewall now always enabled via sandbox.agent: awf default)",
 		Log:          networkFirewallCodemodLog,
 		PostTransform: func(lines []string, frontmatter map[string]any, fieldValue any) []string {
+			requiresDisableFlag := requiresSandboxDisableFeatureFlag(fieldValue)
 			_, hasSandbox := frontmatter["sandbox"]
 
 			if !hasSandbox {
 				sandboxLines := sandboxAgentLinesFromFirewall(fieldValue)
 				if len(sandboxLines) > 0 {
 					lines = insertSandboxAfterNetworkBlock(lines, sandboxLines)
+					if requiresDisableFlag {
+						lines = ensureSandboxDisableFeatureFlag(lines)
+					}
 					networkFirewallCodemodLog.Print("Converted deprecated network.firewall to sandbox.agent")
 				}
 				return lines
 			}
 
 			lines, merged := mergeFirewallIntoExistingSandbox(lines, fieldValue)
 			if merged {
+				if requiresDisableFlag {
+					lines = ensureSandboxDisableFeatureFlag(lines)
+				}
 				networkFirewallCodemodLog.Print("Merged deprecated network.firewall into existing sandbox.agent")
 			}
 			return lines
 		},
 	})
 }
 
+func requiresSandboxDisableFeatureFlag(fieldValue any) bool {
+	switch value := fieldValue.(type) {
+	case bool:
+		return !value
+	case string:
+		return strings.EqualFold(strings.TrimSpace(value), "disable")
+	default:
+		return false
+	}
+}
+
 func sandboxAgentLinesFromFirewall(fieldValue any) []string {
 	switch value := fieldValue.(type) {
 	case bool:
@@ -260,3 +281,59 @@ func indentLines(lines []string, indent string) []string {
 	}
 	return indented
 }
+
+func ensureSandboxDisableFeatureFlag(lines []string) []string {
+	featureKey := "dangerously-disable-sandbox-agent:"
+
+	featuresIdx := -1
+	featuresIndent := ""
+	featuresEnd := len(lines)
+	for i, line := range lines {
+		trimmed := strings.TrimSpace(line)
+		if isTopLevelKey(line) && strings.HasPrefix(trimmed, "features:") {
+			featuresIdx = i
+			featuresIndent = getIndentation(line)
+			for j := i + 1; j < len(lines); j++ {
+				if isTopLevelKey(lines[j]) {
+					featuresEnd = j
+					break
+				}
+			}
+			break
+		}
+	}
+
+	if featuresIdx >= 0 {
+		featureIndent := featuresIndent + "  "
+		for i := featuresIdx + 1; i < featuresEnd; i++ {
+			if strings.HasPrefix(strings.TrimSpace(lines[i]), featureKey) {
+				return lines
+			}
+		}
+		featureLine := fmt.Sprintf("%s%s %s", featureIndent, featureKey, strconv.Quote(migratedSandboxDisableJustification))
+		newLines := make([]string, 0, len(lines)+1)
+		newLines = append(newLines, lines[:featuresEnd]...)
+		newLines = append(newLines, featureLine)
+		newLines = append(newLines, lines[featuresEnd:]...)
+		return newLines
+	}
+
+	insertIndex := len(lines)
+	for i, line := range lines {
+		if isTopLevelKey(line) && strings.HasPrefix(strings.TrimSpace(line), "sandbox:") {
+			insertIndex = i
+			break
+		}
+	}
+
+	featureLines := []string{
+		"features:",
+		"  " + featureKey + " " + strconv.Quote(migratedSandboxDisableJustification),
+	}
+
+	newLines := make([]string, 0, len(lines)+len(featureLines))
+	newLines = append(newLines, lines[:insertIndex]...)
+	newLines = append(newLines, featureLines...)
+	newLines = append(newLines, lines[insertIndex:]...)
+	return newLines
+}

pkg/cli/codemod_network_firewall_test.go

@@ -82,6 +82,7 @@ permissions:
 	assert.NotContains(t, result, "firewall:", "Should remove firewall field")
 	assert.Contains(t, result, "sandbox:", "Should add sandbox block")
 	assert.Contains(t, result, "agent: false", "Should convert firewall false to sandbox.agent: false")
+	assert.Contains(t, result, `dangerously-disable-sandbox-agent: "migrated from deprecated network.firewall disable setting"`, "Should add required sandbox-disable justification feature")
 }
 
 func TestNetworkFirewallCodemod_NoNetworkField(t *testing.T) {
@@ -208,6 +209,43 @@ sandbox:
 	assert.Contains(t, result, "sandbox:", "Should preserve existing sandbox block")
 	assert.Contains(t, result, "mcp: true", "Should preserve existing sandbox settings")
 	assert.Contains(t, result, "agent: false", "Should migrate firewall false to sandbox.agent: false")
+	assert.Contains(t, result, `dangerously-disable-sandbox-agent: "migrated from deprecated network.firewall disable setting"`, "Should add required sandbox-disable justification feature")
+}
+
+func TestNetworkFirewallCodemod_PreservesExistingSandboxDisableJustification(t *testing.T) {
+	codemod := getNetworkFirewallCodemod()
+
+	content := `---
+on: workflow_dispatch
+network:
+  firewall: false
+features:
+  dangerously-disable-sandbox-agent: "already documented justification string with enough detail"
+sandbox:
+  mcp: true
+---
+
+# Test Workflow`
+
+	frontmatter := map[string]any{
+		"on": "workflow_dispatch",
+		"network": map[string]any{
+			"firewall": false,
+		},
+		"features": map[string]any{
+			"dangerously-disable-sandbox-agent": "already documented justification string with enough detail",
+		},
+		"sandbox": map[string]any{
+			"mcp": true,
+		},
+	}
+
+	result, applied, err := codemod.Apply(content, frontmatter)
+
+	require.NoError(t, err)
+	assert.True(t, applied)
+	assert.Contains(t, result, `dangerously-disable-sandbox-agent: "already documented justification string with enough detail"`)
+	assert.NotContains(t, result, migratedSandboxDisableJustification, "Should not overwrite existing justification")
 }
 
 func TestNetworkFirewallCodemod_MigratesFirewallVersionIntoExistingSandbox(t *testing.T) {

pkg/constants/feature_constants.go

@@ -84,6 +84,6 @@ const (
 	// Workflow frontmatter usage:
 	//
 	//	features:
-	//	  dangerously-disable-sandbox-agent: true
+	//	  dangerously-disable-sandbox-agent: "controlled environment with no internet access"
 	DangerouslyDisableSandboxAgentFeatureFlag FeatureFlag = "dangerously-disable-sandbox-agent"
 )

pkg/workflow/compiler_validators_test.go

@@ -385,7 +385,7 @@ func TestValidateToolConfiguration_EmitsSandboxWarningBeforeThreatDetectionError
 	workflowData := &WorkflowData{
 		Name: "Test",
 		Features: map[string]any{
-			"dangerously-disable-sandbox-agent": true,
+			"dangerously-disable-sandbox-agent": "controlled environment with no internet access",
 		},
 		SandboxConfig: &SandboxConfig{
 			Agent: &AgentSandboxConfig{Disabled: true},