Add AWF token steering frontmatter opt-out

.github/aw/syntax-agentic.md

@@ -302,6 +302,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
         id: awf                     # Required in strict mode
         version: "v0.25.29"         # Optional: pin AWF version
         model-fallback: false       # Optional: disable model fallback (default true); set false for BYOK Azure OpenAI to prevent deployment-name rewriting
+        token-steering: false       # Optional: disable API proxy token steering to preserve the configured provider and model
     ```
 
   - To disable the agent firewall while keeping MCP gateway enabled, you must provide the dangerous-disable justification feature:

docs/public/editor/autocomplete-data.json

@@ -793,6 +793,11 @@
               "desc": "Enable or disable model fallback for unresolved model selections.",
               "leaf": true
             },
+            "token-steering": {
+              "type": "boolean",
+              "desc": "Enable or disable API proxy token steering.",
+              "leaf": true
+            },
             "runtime": {
               "type": "string",
               "desc": "Container runtime for the agent container.",

docs/src/content/docs/reference/frontmatter-full.md

@@ -2110,6 +2110,11 @@ sandbox:
     # Format 2: GitHub Actions expression that resolves to a boolean at runtime
     model-fallback: "example-value"
 
+    # Enable or disable API proxy token steering. Set to false to preserve the
+    # explicitly configured provider and model.
+    # (optional)
+    token-steering: true
+
     # Container runtime for the agent container. Use 'gvisor' to run the agent under
     # gVisor's runsc runtime for additional kernel-level isolation. Use 'docker-sbx'
     # to run the agent inside a Docker sbx microVM with KVM hypervisor-level isolation

docs/src/content/docs/reference/sandbox.md

@@ -162,6 +162,16 @@ When omitted, AWF's own default memory limit applies. Specifying an invalid form
 > [!NOTE]
 > Exit code 137 means the process received `SIGKILL`. A memory limit can be one cause, but verify with logs before changing `memory`. If you increase `memory`, leave headroom for the runner OS and other processes.
 
+#### Token steering (`sandbox.agent.token-steering`)
+
+AWF enables API proxy token steering by default. To keep the explicitly configured provider and model, disable it for a workflow:
+
+```yaml wrap
+sandbox:
+  agent:
+    token-steering: false
+```
+
 #### Copilot BYOK request customization (`sandbox.agent.targets.copilot`)
 
 When routing Copilot through a BYOK-compatible upstream behind the AWF proxy, you can attach custom headers, extra request body fields, and an explicit session identifier on upstream requests:

pkg/parser/schemas/main_workflow_schema.json

@@ -3515,6 +3515,11 @@
                       "description": "Enable or disable model fallback for unresolved model selections. Set to false for BYOK Azure OpenAI deployments to prevent deployment-name rewriting. Supports literal boolean or GitHub Actions expression.",
                       "examples": [false, "${{ inputs.model-fallback }}"]
                     },
+                    "token-steering": {
+                      "type": "boolean",
+                      "description": "Enable or disable API proxy token steering. Set to false to preserve the explicitly configured provider and model.",
+                      "examples": [false]
+                    },
                     "runtime": {
                       "type": "string",
                       "description": "Container runtime for the agent container. Use 'gvisor' to run the agent under gVisor's runsc runtime for additional kernel-level isolation. Use 'docker-sbx' to run the agent inside a Docker sbx microVM with KVM hypervisor-level isolation \u2014 requires sandbox.agent.sudo: true, DOCKER_PAT and DOCKER_USERNAME secrets, and a KVM-capable runner. Incompatible with runner.topology: arc-dind.",

pkg/workflow/awf_config.go

@@ -279,7 +279,7 @@ type AWFAPIProxyConfig struct {
 	Enabled bool `json:"enabled"`
 
 	// EnableTokenSteering enables budget-warning system message injection near ET budget exhaustion.
-	EnableTokenSteering bool `json:"enableTokenSteering,omitempty"`
+	EnableTokenSteering *bool `json:"enableTokenSteering,omitempty"`
 
 	// MaxRuns is the maximum number of LLM invocations allowed for a run.
 	MaxRuns int `json:"maxRuns,omitempty"`
@@ -553,21 +553,28 @@ func BuildAWFConfigJSON(config AWFCommandConfig) (string, error) {
 	// value (-1) omits that budget from the AWF config and disables token steering.
 	// When maxAICredits is 0 (runtime default), token steering stays enabled here.
 	enableTokenSteering := maxAICredits >= 0
+	if config.WorkflowData != nil && config.WorkflowData.SandboxConfig != nil && config.WorkflowData.SandboxConfig.Agent != nil && config.WorkflowData.SandboxConfig.Agent.TokenSteering != nil {
+		enableTokenSteering = *config.WorkflowData.SandboxConfig.Agent.TokenSteering
+	}
 	if maxAICredits < 0 {
 		// Negative signals "disabled" — omit the budget from the AWF config.
 		maxAICredits = 0
 	}
+	var tokenSteeringEnabled *bool
+	if awfSupportsTokenSteering(firewallConfig) && (enableTokenSteering || (config.WorkflowData != nil && config.WorkflowData.SandboxConfig != nil && config.WorkflowData.SandboxConfig.Agent != nil && config.WorkflowData.SandboxConfig.Agent.TokenSteering != nil)) {
+		tokenSteeringEnabled = &enableTokenSteering
+	}
 
 	apiProxy := &AWFAPIProxyConfig{
 		Enabled:             true,
 		MaxRuns:             maxRuns,
 		MaxTurnCacheMisses:  maxTurnCacheMisses,
 		MaxAICredits:        maxAICredits,
-		EnableTokenSteering: enableTokenSteering && awfSupportsTokenSteering(firewallConfig),
+		EnableTokenSteering: tokenSteeringEnabled,
 	}
 
 	if !enableTokenSteering {
-		awfConfigLog.Printf("Skipping apiProxy.enableTokenSteering: max-ai-credits is negative (disabled)")
+		awfConfigLog.Print("Disabling apiProxy.enableTokenSteering")
 	} else if !awfSupportsTokenSteering(firewallConfig) {
 		awfConfigLog.Printf("Skipping apiProxy.enableTokenSteering: AWF version %q requires at least %s", getAWFImageTag(firewallConfig), constants.AWFTokenSteeringMinVersion)
 	}

pkg/workflow/awf_config_test.go

@@ -436,6 +436,27 @@ func TestBuildAWFConfigJSON(t *testing.T) {
 		assert.Contains(t, jsonStr, `"enableTokenSteering":true`, "apiProxy should emit enableTokenSteering by default")
 	})
 
+	t.Run("token steering can be disabled in the sandbox config", func(t *testing.T) {
+		disabled := false
+		config := AWFCommandConfig{
+			EngineName:     "copilot",
+			AllowedDomains: "github.com",
+			WorkflowData: &WorkflowData{
+				EngineConfig: &EngineConfig{ID: "copilot"},
+				NetworkPermissions: &NetworkPermissions{
+					Firewall: &FirewallConfig{Enabled: true},
+				},
+				SandboxConfig: &SandboxConfig{
+					Agent: &AgentSandboxConfig{TokenSteering: &disabled},
+				},
+			},
+		}
+
+		jsonStr, err := BuildAWFConfigJSON(config)
+		require.NoError(t, err)
+		assert.Contains(t, jsonStr, `"enableTokenSteering":false`, "apiProxy should emit the sandbox token-steering override")
+	})
+
 	t.Run("token steering is disabled when max-ai-credits is negative", func(t *testing.T) {
 		config := AWFCommandConfig{
 			EngineName:     "copilot",

pkg/workflow/frontmatter_extraction_security.go

@@ -309,6 +309,14 @@ func (c *Compiler) extractAgentSandboxConfig(agentVal any) *AgentSandboxConfig {
 		}
 	}
 
+	// Extract token-steering (AWF API proxy token steering enable/disable flag).
+	if tsVal, hasTS := agentObj["token-steering"]; hasTS {
+		if value, ok := tsVal.(bool); ok {
+			agentConfig.TokenSteering = &value
+			frontmatterExtractionSecurityLog.Print("Extracted sandbox.agent.token-steering")
+		}
+	}
+
 	// Extract targets (per-provider API proxy target overrides, e.g. authHeader, extraHeaders)
 	if targetsVal, hasTargets := agentObj["targets"]; hasTargets {
 		if targetsObj, ok := targetsVal.(map[string]any); ok {

pkg/workflow/frontmatter_extraction_security_test.go

@@ -190,6 +190,28 @@ func TestExtractAgentSandboxConfigModelFallback(t *testing.T) {
 	})
 }
 
+func TestExtractAgentSandboxConfigTokenSteering(t *testing.T) {
+	compiler := &Compiler{}
+
+	t.Run("extracts sandbox.agent.token-steering false", func(t *testing.T) {
+		config := compiler.extractAgentSandboxConfig(map[string]any{
+			"id":             "awf",
+			"token-steering": false,
+		})
+
+		require.NotNil(t, config)
+		require.NotNil(t, config.TokenSteering)
+		assert.False(t, *config.TokenSteering)
+	})
+
+	t.Run("token-steering is nil when absent", func(t *testing.T) {
+		config := compiler.extractAgentSandboxConfig(map[string]any{"id": "awf"})
+
+		require.NotNil(t, config)
+		assert.Nil(t, config.TokenSteering)
+	})
+}
+
 func TestExtractAgentSandboxConfigMemory(t *testing.T) {
 	compiler := &Compiler{}
 

pkg/workflow/sandbox.go

@@ -79,6 +79,7 @@ type AgentSandboxConfig struct {
 	Mounts                []string                              `yaml:"mounts,omitempty"`         // Container mounts to add for AWF (format: "source:dest:mode")
 	Memory                string                                `yaml:"memory,omitempty"`         // Memory limit for the AWF container (e.g., "4g", "8g")
 	ModelFallback         *TemplatableBool                      `yaml:"model-fallback,omitempty"` // AWF API proxy model fallback enable/disable flag (optional)
+	TokenSteering         *bool                                 `yaml:"token-steering,omitempty"` // AWF API proxy token steering enable/disable flag (optional)
 	Targets               map[string]*AgentAPIProxyTargetConfig `yaml:"targets,omitempty"`        // Per-provider API proxy target overrides keyed by provider name (e.g. "openai", "anthropic")
 }
 

specs/awf-config-sources-spec.md

@@ -111,6 +111,7 @@ The following fields previously existed in schema but were missed in spec CLI ma
 | `apiProxy.models` | config-only (model alias rewriting) | `pkg/workflow/awf_config_test.go` |
 | `apiProxy.modelMultipliers` | config-only (effective-token accounting) | `pkg/workflow/awf_config_test.go` |
 | `apiProxy.modelFallback` | config-only (model fallback policy; set `sandbox.agent.model-fallback: false` to prevent deployment-name rewriting for BYOK Azure) | `pkg/workflow/awf_config_test.go` (`TestAWFConfig_ModelFallback*`) |
+| `apiProxy.enableTokenSteering` | config-only (set `sandbox.agent.token-steering: false` to preserve the explicitly configured provider and model) | `pkg/workflow/awf_config_test.go` |
 | `apiProxy.maxRuns` | config-only (LLM invocation hard cap) | `pkg/workflow/awf_config_test.go` |
 | `apiProxy.auth.*` | config-only (maps to `AWF_AUTH_*` env vars) | `pkg/workflow/awf_config_test.go` |
 | `apiProxy.targets.openai.authHeader` | `--openai-api-auth-header` (frontmatter: `sandbox.agent.targets.openai.authHeader`) | `pkg/workflow/awf_config_test.go` |