Add max-turns feature

[dsyme]

https://github.com/githubnext/gh-aw-internal/pull/768

---

This PR implements the max-turns frontmatter parameter to limit the number of chat iterations within a single agentic run, providing a crucial safety mechanism to prevent runaway chat loops and control API costs.

Overview

The max-turns feature works by passing a turn limit directly to the AI engine (currently Claude Code action), which enforces the restriction at the engine level. This is different from max-runs which limits the number of separate workflow executions.

New in this version: Engine capability validation ensures max-turns can only be used with compatible engines, preventing compilation errors at runtime.

Usage

Add max-turns to any workflow frontmatter with a supported engine:

---
on:
  workflow_dispatch:
permissions:
  contents: read
engine: claude  # Only Claude currently supports max-turns
max-turns: 5
tools:
  github:
    allowed: [get_issue, add_issue_comment]
---

# Example Workflow

This workflow will limit Claude to exactly 5 chat iterations.

When compiled, this generates a GitHub Actions workflow that passes max_turns: 5 to the Claude Code action, ensuring the AI stops after the specified number of iterations.

Engine Compatibility

• ✅ Claude: Fully supports max-turns feature
• ❌ Codex: Does not support max-turns (compilation will fail with clear error message)

The system now validates engine capabilities during compilation:

# This will fail with a clear error message
$ gh aw compile workflow-with-codex-and-max-turns.md
✗ workflow.md:1:1: error: max-turns not supported: max-turns feature is not supported by engine 'codex' (only supported by: claude)

Implementation Details

• Schema Validation: Added max-turns as an integer field to the JSON schema
• Frontmatter Parsing: Extended workflow data extraction to handle the new parameter
• Engine Integration: Modified Claude engine to include max_turns in action inputs
• Engine Capability System: Added SupportsMaxTurns() method to AgenticEngine interface
• Validation Logic: Prevents compilation when max-turns is used with incompatible engines
• Documentation: Updated frontmatter documentation with examples and best practices
• Testing: Added comprehensive unit tests covering validation and compilation scenarios

Benefits

• 🛡️ Safety: Prevents infinite chat loops that could consume excessive API credits
• 💰 Cost Control: Provides predictable bounds on API usage per workflow run
• 🎯 Efficiency: Encourages focused, concise AI responses
• 🔧 Flexibility: Can be configured per-workflow based on complexity needs
• 🚨 Validation: Prevents usage with incompatible engines at compile time

The feature seamlessly integrates with existing workflows and maintains backward compatibility - workflows without max-turns continue to work unchanged.

Fixes #713.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.