Add optional "args" field to engine configuration for all engines

docs/src/content/docs/reference/engines.md

@@ -21,11 +21,13 @@ engine:
   id: copilot
   version: latest
   model: gpt-5                          # Optional: uses claude-sonnet-4 by default
+  args: ["--add-dir", "/workspace"]     # Optional: custom CLI arguments
 ```
 
 **Copilot-specific fields:**
 - **`model`** (optional): AI model to use (`gpt-5` or defaults to `claude-sonnet-4`)
 - **`version`** (optional): Version of the GitHub Copilot CLI to install (defaults to `latest`)
+- **`args`** (optional): Array of custom command-line arguments to pass to the Copilot CLI (supported by all engines)
 
 **Environment Variables:**
 - **`COPILOT_MODEL`**: Alternative way to set the model (e.g., `gpt-5`)
@@ -69,6 +71,7 @@ engine:
   version: beta
   model: claude-3-5-sonnet-20241022
   max-turns: 5
+  args: ["--custom-flag", "value"]      # Optional: custom CLI arguments
   env:
     AWS_REGION: us-west-2
     DEBUG_MODE: "true"
@@ -107,6 +110,7 @@ engine: codex
 engine:
   id: codex
   model: gpt-4
+  args: ["--custom-flag", "value"]      # Optional: custom CLI arguments
   user-agent: custom-workflow-name
   env:
     CODEX_API_KEY: ${{ secrets.CODEX_API_KEY_CI }}
@@ -123,6 +127,7 @@ engine:
 **Codex-specific fields:**
 - **`user-agent`** (optional): Custom user agent string for GitHub MCP server configuration
 - **`config`** (optional): Additional TOML configuration text appended to generated config.toml
+- **`args`** (optional): Array of custom command-line arguments to pass to the Codex CLI (supported by all engines)
 
 **Secrets:**
 
@@ -171,6 +176,39 @@ engine:
     CUSTOM_API_ENDPOINT: https://api.example.com
 ```
 
+## Engine Command-Line Arguments
+
+All engines support custom command-line arguments through the `args` field. These arguments are injected into the AI engine CLI command after all other arguments but before the prompt:
+
+```yaml
+engine:
+  id: copilot
+  args: ["--add-dir", "/workspace"]
+```
+
+**Common use cases:**
+- Adding additional directories to the context with `--add-dir`
+- Enabling verbose logging with `--verbose` or `--debug`
+- Passing engine-specific flags for advanced configuration
+
+**Example with multiple arguments:**
+```yaml
+engine:
+  id: copilot
+  args: ["--add-dir", "/workspace", "--verbose"]
+```
+
+This generates the following CLI command structure:
+```bash
+copilot [default-args] [tool-args] --add-dir /workspace --verbose --prompt "$INSTRUCTION"
+```
+
+**Important notes:**
+- Arguments are added in the order specified in the array
+- Arguments are always placed before the `--prompt` flag
+- Different engines may support different command-line arguments
+- Consult the specific engine's CLI documentation for available flags
+
 ## Engine Error Patterns
 
 All engines support custom error pattern recognition for enhanced log validation:

pkg/parser/schemas/main_workflow_schema.json

@@ -2969,6 +2969,13 @@
             "config": {
               "type": "string",
               "description": "Additional TOML configuration text that will be appended to the generated config.toml in the action (codex engine only)"
+            },
+            "args": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Optional array of command-line arguments to pass to the AI engine CLI. These arguments are injected after all other args but before the prompt."
             }
           },
           "required": [

pkg/workflow/claude_engine.go

@@ -144,6 +144,11 @@ func (e *ClaudeEngine) GetExecutionSteps(workflowData *WorkflowData, logFile str
 		claudeArgs = append(claudeArgs, "--settings", "/tmp/gh-aw/.claude/settings.json")
 	}
 
+	// Add custom args from engine configuration before the prompt
+	if workflowData.EngineConfig != nil && len(workflowData.EngineConfig.Args) > 0 {
+		claudeArgs = append(claudeArgs, workflowData.EngineConfig.Args...)
+	}
+
 	var stepLines []string
 
 	stepName := "Execute Claude Code CLI"

pkg/workflow/codex_engine.go

@@ -124,10 +124,18 @@ func (e *CodexEngine) GetExecutionSteps(workflowData *WorkflowData, logFile stri
 	// See https://github.com/githubnext/gh-aw/issues/892
 	fullAutoParam := " --full-auto --skip-git-repo-check " //"--dangerously-bypass-approvals-and-sandbox "
 
+	// Build custom args parameter if specified in engineConfig
+	var customArgsParam string
+	if workflowData.EngineConfig != nil && len(workflowData.EngineConfig.Args) > 0 {
+		for _, arg := range workflowData.EngineConfig.Args {
+			customArgsParam += arg + " "
+		}
+	}
+
 	command := fmt.Sprintf(`set -o pipefail
 INSTRUCTION=$(cat $GITHUB_AW_PROMPT)
 mkdir -p $CODEX_HOME/logs
-codex %sexec%s%s"$INSTRUCTION" 2>&1 | tee %s`, modelParam, webSearchParam, fullAutoParam, logFile)
+codex %sexec%s%s%s"$INSTRUCTION" 2>&1 | tee %s`, modelParam, webSearchParam, fullAutoParam, customArgsParam, logFile)
 
 	env := map[string]string{
 		"CODEX_API_KEY":        "${{ secrets.CODEX_API_KEY || secrets.OPENAI_API_KEY }}",

pkg/workflow/copilot_engine.go

@@ -96,6 +96,11 @@ func (e *CopilotEngine) GetExecutionSteps(workflowData *WorkflowData, logFile st
 		copilotArgs = append(copilotArgs, "--add-dir", "/tmp/gh-aw/cache-memory/")
 	}
 
+	// Add custom args from engine configuration before the prompt
+	if workflowData.EngineConfig != nil && len(workflowData.EngineConfig.Args) > 0 {
+		copilotArgs = append(copilotArgs, workflowData.EngineConfig.Args...)
+	}
+
 	copilotArgs = append(copilotArgs, "--prompt", "\"$COPILOT_CLI_INSTRUCTION\"")
 	command := fmt.Sprintf(`set -o pipefail
 COPILOT_CLI_INSTRUCTION=$(cat /tmp/gh-aw/aw-prompts/prompt.txt)

pkg/workflow/custom_engine.go

@@ -63,6 +63,12 @@ func (e *CustomEngine) GetExecutionSteps(workflowData *WorkflowData, logFile str
 				envVars["GITHUB_AW_MAX_TURNS"] = workflowData.EngineConfig.MaxTurns
 			}
 
+			// Add GITHUB_AW_ARGS if args are configured
+			if workflowData.EngineConfig != nil && len(workflowData.EngineConfig.Args) > 0 {
+				// Join args with space separator for environment variable
+				envVars["GITHUB_AW_ARGS"] = strings.Join(workflowData.EngineConfig.Args, " ")
+			}
+
 			// Add custom environment variables from engine config
 			if workflowData.EngineConfig != nil && len(workflowData.EngineConfig.Env) > 0 {
 				for key, value := range workflowData.EngineConfig.Env {

pkg/workflow/engine.go

@@ -17,6 +17,7 @@ type EngineConfig struct {
 	Steps         []map[string]any
 	ErrorPatterns []ErrorPattern
 	Config        string
+	Args          []string
 }
 
 // NetworkPermissions represents network access permissions
@@ -183,6 +184,20 @@ func (c *Compiler) ExtractEngineConfig(frontmatter map[string]any) (string, *Eng
 				}
 			}
 
+			// Extract optional 'args' field (array of strings)
+			if args, hasArgs := engineObj["args"]; hasArgs {
+				if argsArray, ok := args.([]any); ok {
+					config.Args = make([]string, 0, len(argsArray))
+					for _, arg := range argsArray {
+						if argStr, ok := arg.(string); ok {
+							config.Args = append(config.Args, argStr)
+						}
+					}
+				} else if argsStrArray, ok := args.([]string); ok {
+					config.Args = argsStrArray
+				}
+			}
+
 			// Return the ID as the engineSetting for backwards compatibility
 			return config.ID, config
 		}