github · pelikhan · Jul 30, 2026 · Jul 30, 2026
diff --git a/.github/aw/github-agentic-workflows.md b/.github/aw/github-agentic-workflows.md
diff --git a/.github/aw/github-mcp-server-pagination.md b/.github/aw/github-mcp-server-pagination.md
@@ -0,0 +1,54 @@
+# GitHub MCP Server — Pagination
+
+See [github-mcp-server.md](github-mcp-server.md) for toolset and tool reference.
+
+MCP tool responses have a **25,000 token limit**. Fetching large result sets without pagination causes the response to be truncated or rejected, forcing costly retry turns.
+
+## `perPage` Defaults by Item Type
+
+| Item type | Recommended `perPage` |
+|-----------|----------------------|
+| PRs with diffs / issues with comments (detailed) | 10–20 |
+| Simple list operations (commits, branches, labels) | 50–100 |
+| Exploratory / schema-discovery queries | 1–5 |
+
+Always pass an explicit `perPage` value. Do **not** rely on server defaults.
+
+## Tool-Specific Guidance
+
+**Pull Requests**
+- `list_pull_requests` — use `perPage: 10`, `sort: updated`, `direction: desc`
+- `pull_request_read` with `method: get_files` — use `perPage: 30`
+- Fetch diff and comments **separately** when full detail is needed
+
+**Issues**
+- `list_issues` — `perPage: 20`
+- `issue_read` with `method: get_comments` — `perPage: 20`
+
+**Search**
+- `search_issues`, `search_pull_requests`, `search_code` — `perPage: 10`
+- `search_repositories` exploratory calls — `perPage: 3–5`; increase only after narrowing the query
+
+## Pagination Loop (when all pages are needed)
+
+```
+page 1 → check total_count or has_next_page → fetch page 2, 3, … until done
+```
+
+Process results incrementally rather than accumulating all pages in memory.
+
+## Known Tool Quirks
+
+Two built-in GitHub MCP tools ignore standard pagination parameters:
+
+- **`list_label`** — uses a hardcoded GraphQL `labels(first: 100)` query; `perPage` is silently ignored. Use the `shared/github-mcp-pagination-wrappers.md` wrapper instead.
+- **`list_workflows`** — uses snake_case `per_page` (inconsistent with every other list tool). Use the `shared/github-mcp-pagination-wrappers.md` wrapper for consistent camelCase `perPage` support.
+
+## Oversized-Response Errors
+
+If you encounter errors like:
+
+- `MCP tool "list_pull_requests" response (75897 tokens) exceeds maximum allowed tokens (25000)`
+- `Response too large for tool [tool_name]`
+
+add `perPage: 10` (or smaller) and retry.
diff --git a/.github/aw/github-mcp-server.md b/.github/aw/github-mcp-server.md
@@ -359,56 +359,7 @@ When calling `list_code_scanning_alerts` in workflow prompts/templates, always b
 
 ## Pagination
 
-MCP tool responses have a **25,000 token limit**. Fetching large result sets without pagination causes the response to be truncated or rejected, forcing costly retry turns.
-
-### `perPage` Defaults by Item Type
-
-| Item type | Recommended `perPage` |
-|-----------|----------------------|
-| PRs with diffs / issues with comments (detailed) | 10–20 |
-| Simple list operations (commits, branches, labels) | 50–100 |
-| Exploratory / schema-discovery queries | 1–5 |
-
-Always pass an explicit `perPage` value. Do **not** rely on server defaults.
-
-### Tool-Specific Guidance
-
-**Pull Requests**
-- `list_pull_requests` — use `perPage: 10`, `sort: updated`, `direction: desc`
-- `pull_request_read` with `method: get_files` — use `perPage: 30`
-- Fetch diff and comments **separately** when full detail is needed
-
-**Issues**
-- `list_issues` — `perPage: 20`
-- `issue_read` with `method: get_comments` — `perPage: 20`
-
-**Search**
-- `search_issues`, `search_pull_requests`, `search_code` — `perPage: 10`
-- `search_repositories` exploratory calls — `perPage: 3–5`; increase only after narrowing the query
-
-### Pagination Loop (when all pages are needed)
-
-```
-page 1 → check total_count or has_next_page → fetch page 2, 3, … until done
-```
-
-Process results incrementally rather than accumulating all pages in memory.
-
-### Known Tool Quirks
-
-Two built-in GitHub MCP tools ignore standard pagination parameters:
-
-- **`list_label`** — uses a hardcoded GraphQL `labels(first: 100)` query; `perPage` is silently ignored. Use the `shared/github-mcp-pagination-wrappers.md` wrapper instead.
-- **`list_workflows`** — uses snake_case `per_page` (inconsistent with every other list tool). Use the `shared/github-mcp-pagination-wrappers.md` wrapper for consistent camelCase `perPage` support.
-
-### Oversized-Response Errors
-
-If you encounter errors like:
-
-- `MCP tool "list_pull_requests" response (75897 tokens) exceeds maximum allowed tokens (25000)`
-- `Response too large for tool [tool_name]`
-
-add `perPage: 10` (or smaller) and retry.
+MCP tool responses have a **25,000 token limit**; always pass an explicit `perPage`. See [github-mcp-server-pagination.md](github-mcp-server-pagination.md) for per-tool `perPage` defaults, the pagination loop pattern, known tool quirks (`list_label`, `list_workflows`), and oversized-response recovery.
 
 ---
 

diff --git a/.github/aw/safe-outputs-runtime.md b/.github/aw/safe-outputs-runtime.md
@@ -91,6 +91,21 @@ The `report-incomplete` safe-output is enabled by default and is distinct from `
 - `allowed-domains:` - Allowed domains for URLs in safe output content (array)
   - URLs from unlisted domains are replaced with `(redacted)`
   - GitHub domains are always included by default
+- `data:` - Structured data configuration for body-based safe outputs (boolean, object, or GitHub Actions expression)
+  - Applies to `create-issue`, `add-comment`, `create-pull-request`, `create-pull-request-review-comment`, `submit-pull-request-review`, and `reply-to-pull-request-review-comment`
+  - `false` or omitted (default) - no structured `data` field accepted
+  - `true` - accept any object as the `data` field alongside `body`
+  - Inline schema object - enforce shape; supports full JSON Schema keywords (`type`, `properties`, `required`, `items`, `enum`, etc.) or shorthand (`{ verdict: string, score: number }`)
+  - `${{ ... }}` expression - resolves to one of the above at runtime
+  - Example:
+
+    ```yaml
+    safe-outputs:
+      data:
+        verdict: string
+        score: number
+      add-comment:
+    ```
 - `allowed-github-references:` - Allowed repositories for GitHub-style references (array)
   - Controls which GitHub references (`#123`, `owner/repo#456`) are allowed in workflow output
   - References to unlisted repositories are escaped with backticks to prevent timeline items

diff --git a/.github/aw/syntax-agentic.md b/.github/aw/syntax-agentic.md
@@ -270,86 +270,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
 
   - `setup-steps`/`pre-steps` also apply to built-in jobs (e.g. `activation`): use `setup-steps` for OIDC/secret bootstrap that must run before framework token minting, then verify the result in `pre-steps`.
 
-- **`engine:`** - AI processor configuration
-  - String format: `"copilot"` (default, recommended), `"claude"`, `"codex"`, `"gemini"`, or the experimental `"antigravity"`, `"opencode"`, `"pi"`
-  - Object format for extended configuration:
-
-    ```yaml
-    engine:
-      id: copilot                       # Required: coding agent identifier (copilot, claude, codex, gemini; experimental: antigravity, opencode, pi)
-      version: beta                     # Optional: version of the action (has sensible default); also accepts GitHub Actions expressions: ${{ inputs.engine-version }}
-      model: gpt-5                      # Deprecated alias for the top-level `model`; prefer the top-level field
-      permission-mode: acceptEdits      # Optional (claude only): auto | acceptEdits | plan | bypassPermissions. Default: acceptEdits (auto when tools.edit is false)
-      agent: technical-doc-writer       # Optional: custom agent file (Copilot only, references .github/agents/{agent}.agent.md)
-      max-turns: 5                      # Deprecated alias for the top-level `max-turns`; prefer the top-level field
-      max-continuations: 3              # Optional: max autopilot continuations (copilot only; >1 enables --autopilot mode, default: 1)
-      concurrency: "gh-aw-${{ github.workflow }}"  # Optional: agent job concurrency group (string or GitHub Actions concurrency object)
-      env:                              # Optional: custom environment variables (object)
-        DEBUG_MODE: "true"
-      args: ["--verbose"]               # Optional: custom CLI arguments injected before prompt (array)
-      api-target: api.acme.ghe.com      # Optional: custom API endpoint hostname for GHEC/GHES (hostname only, no protocol/path)
-      command: /usr/local/bin/copilot   # Optional: override default engine executable (skips installation)
-      bare: true                        # Optional: disable automatic context loading (copilot: --no-custom-instructions; claude: --bare; codex: --no-system-prompt; gemini: GEMINI_SYSTEM_MD=/dev/null). Default: false
-      user-agent: "myapp/1.0"           # Optional: custom user agent string (codex engine only)
-      config: |                         # Optional: additional TOML config appended to config.toml (codex engine only)
-        [extra]
-        key = "value"
-    ```
-
-  - **`gemini` engine**: Google Gemini CLI. Requires `GEMINI_API_KEY` secret. Does not support `max-turns`, `web-fetch`, or `web-search`. Supports AWF firewall and LLM gateway.
-  - **`antigravity` engine** (experimental): Google Antigravity CLI in headless mode. Requires `ANTIGRAVITY_API_KEY` secret; model via `model:` (maps to `ANTIGRAVITY_MODEL`). Supports `max-turns`, tools allow-list, AWF firewall, and LLM gateway. Does not support `web-search`, `max-continuations`, or native agent files (agent content is prepended to the prompt).
-  - **`opencode` engine** (experimental): Provider-agnostic, open-source AI coding agent (BYOK). Defaults to Copilot routing via `COPILOT_GITHUB_TOKEN` (or `${{ github.token }}` with `copilot-requests` feature). Supports 75+ models via `provider/model` format. Supports AWF firewall and LLM gateway.
-  - **`engine.driver:`** — canonical field to run a custom inner driver script instead of the engine's built-in CLI. For the `pi` engine it launches the driver directly with Node.js (e.g. built-in `pi_agent_core_driver.cjs`, or a workspace-relative path like `.github/drivers/pi_agent_core_driver_sample_node.cjs`); the driver must emit JSONL compatible with `parse_pi_log.cjs` so step summaries and token tracking keep working. Accepts a bare basename (resolved from the setup-action directory) or a workspace-relative path; no absolute paths, no `..`, only `.js`/`.cjs`/`.mjs` (pi).
-  - **`copilot-sdk`** (copilot only): set `copilot-sdk: true` to start a headless Copilot CLI SDK sidecar. **`engine.driver`** (experimental, copilot only): set `driver: <path-or-command>` to supply a custom SDK driver (`.js`/`.cjs`/`.mjs`/`.py`/`.ts`/`.mts`/`.rb`, or a bare PATH command); this also enables `copilot-sdk: true` automatically. Tune the repeated-tool-denial safeguard with the top-level `max-tool-denials:` field (default `5`).
-
-    **Inline driver source** (copilot engine only): instead of pointing to a checked-in file, you can embed the driver source directly in the frontmatter using an object with exactly one runtime key (`node`, `python`, `go`, or `java`). The compiler materializes the source under `.gh-aw/copilot-sdk/` at runtime and generates a launcher wrapper. The required SDK package is installed automatically.
-
-    ```yaml
-    # Node.js / TypeScript inline driver (SDK installed via npm)
-    engine:
-      id: copilot
-      driver:
-        node: |
-          const sdk = require("@github/copilot-sdk");
-          // ... driver implementation
-    ```
-
-    ```yaml
-    # Python inline driver (SDK installed via pip into workspace target dir)
-    engine:
-      id: copilot
-      driver:
-        python: |
-          import sys
-          from github_copilot_sdk import CopilotAgent
-          # ... driver implementation
-    ```
-
-    ```yaml
-    # Go inline driver (SDK installed via go get; go.mod generated automatically)
-    engine:
-      id: copilot
-      driver:
-        go: |
-          package main
-          import "github.com/github/copilot-sdk/go"
-          func main() { /* driver implementation */ }
-    ```
-
-    ```yaml
-    # Java inline driver (SDK resolved via Maven pom.xml generated automatically)
-    engine:
-      id: copilot
-      driver:
-        java: |
-          public class Main {
-              public static void main(String[] args) { /* driver implementation */ }
-          }
-    ```
-
-    Constraints: exactly one runtime key per `driver` object; source must be non-empty; only supported on the `copilot` engine. Use `runtimes.<id>.version` to pin the runtime version used for the generated module files (e.g. `runtimes.go.version: "1.22"`).
-  - **`engine.auth:`** — keyless Workload Identity Federation via the AWF API proxy instead of a static API key; requires `id-token: write`. Set `type: github-oidc` (only supported type) plus `provider: azure` (`azure-tenant-id`, `azure-client-id`, optional `azure-scope`/`azure-cloud`) for Azure OpenAI, or `provider: anthropic` (`federation-rule-id`, `organization-id`, `service-account-id`, `workspace-id`) for Claude. Optional `audience:`. Maps to `AWF_AUTH_*` env vars.
-  - **Advanced engine sub-fields** (see the `engine_config` definition in `pkg/parser/schemas/main_workflow_schema.json`): `model-provider` (`github` | `anthropic` | `openai`), `harness` (retry policy), engine-level `mcp` (`session-timeout`/`tool-timeout`), `extensions`, and `cwd`.
+- **`engine:`** - AI processor configuration (string or object: `id`, `model`, `permission-mode`, `agent`, `max-continuations`, `driver`, `copilot-sdk`, `auth`, and more). See [syntax-engine.md](syntax-engine.md) for the full field reference, per-engine support notes, and inline driver examples.
 
 - **`network:`** - Network access control for AI engines (top-level field)
   - String format: `"defaults"` (curated allow-list of development domains)