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

[Copilot]

Overview

This PR adds support for an optional args field in the engine configuration that allows users to inject custom command-line arguments into the AI engine CLI command. The arguments are inserted after all default and tool-specific arguments but before the prompt/instruction for all supported engines (Copilot, Claude, and Codex).

Motivation

Users need fine-grained control over AI engine command-line arguments for advanced use cases such as:

• Adding additional directories to the context with --add-dir
• Enabling verbose logging with --verbose or --debug
• Passing engine-specific flags without modifying workflow compilation logic

Changes

1. Schema Update

Updated pkg/parser/schemas/main_workflow_schema.json to include the args field in the engine_config definition:

"args": {
  "type": "array",
  "items": {
    "type": "string"
  },
  "description": "Optional array of command-line arguments to pass to the AI engine CLI..."
}

2. Engine Configuration

Modified pkg/workflow/engine.go:

• Added Args []string field to the EngineConfig struct
• Updated ExtractEngineConfig to parse the args field from both []any and []string formats

3. Engine Implementations

Updated all three AI engines to support custom args:

Copilot Engine (pkg/workflow/copilot_engine.go):

• Modified GetExecutionSteps to inject custom args before the --prompt flag
• Args are appended after tool permission args and cache-memory args

Claude Engine (pkg/workflow/claude_engine.go):

• Modified GetExecutionSteps to inject custom args before the prompt argument
• Args are appended to the claudeArgs slice before the command is built

Codex Engine (pkg/workflow/codex_engine.go):

• Modified GetExecutionSteps to inject custom args before the "$INSTRUCTION"
• Args are inserted into the command string after all default flags

4. Documentation

Added comprehensive documentation in docs/src/content/docs/reference/engines.md:

• New "Engine Command-Line Arguments" section with examples
• Updated all engine sections (Copilot, Claude, Codex) to include args field examples
• Documented common use cases and important notes

Usage Examples

Copilot:

engine:
  id: copilot
  args: ["--add-dir", "/workspace", "--verbose"]

Claude:

engine:
  id: claude
  args: ["--custom-flag", "value"]

Codex:

engine:
  id: codex
  args: ["--custom-flag", "value"]

Generated CLI Commands

Copilot:

copilot --add-dir /tmp/gh-aw/ --log-level all --log-dir /tmp/gh-aw/.copilot/logs/ \
  [tool-args...] \
  --add-dir /workspace --verbose \
  --prompt "$COPILOT_CLI_INSTRUCTION"

Claude:

claude --print [default-args] --custom-flag value "$(cat /tmp/gh-aw/aw-prompts/prompt.txt)"

Codex:

codex exec [default-args] --custom-flag value "$INSTRUCTION"

Testing

Added comprehensive test coverage for all engines:

• Unit tests (pkg/workflow/engine_args_test.go): Test cases covering args field extraction and injection for Copilot, Claude, and Codex
• Integration tests (pkg/workflow/engine_args_integration_test.go): End-to-end workflow compilation tests for all three engines
• All existing tests continue to pass
• make agent-finish completed successfully with 0 errors

Validation

✅ All unit tests pass (9.833s)
✅ All integration tests pass for all engines
✅ Schema validation works correctly
✅ Manual testing confirms proper arg injection for Copilot, Claude, and Codex
✅ Documentation complete and accurate for all engines

Original prompt

Add an optional "args" field on the "engine" configuration that takes a string array. The args are injected in the cli after all other args before the prompt.

engine:
   id: copilot
   args: ["--add-dir", "/"]

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[pelikhan]

@copilot add support for claude and codex

[pelikhan]

@copilot add support for custom agentic engine

[Copilot]

@copilot add support for claude and codex

Added support for claude and codex engines in commit 9e12adc. The args field now works for all three engines (copilot, claude, and codex), with args injected before the prompt/instruction in each engine's CLI command.

[github-actions]

Agentic Changeset Generator triggered by this pull request