docs: document GitHub Actions expression support in timeout-minutes, engine.version, and tools.timeout (#23947)

Author: github-actions[bot]

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

@@ -83,6 +83,23 @@ engine:
 
 Pinning is useful when you need reproducible builds or want to avoid breakage from a new CLI release while testing. Remember to update the pinned version periodically to pick up bug fixes and new features.
 
+`version` also accepts a GitHub Actions expression string, enabling `workflow_call` reusable workflows to parameterize the engine version via caller inputs. Expressions are passed injection-safely through an environment variable rather than direct shell interpolation:
+
+```yaml wrap
+on:
+  workflow_call:
+    inputs:
+      engine-version:
+        type: string
+        default: latest
+
+---
+
+engine:
+  id: copilot
+  version: ${{ inputs.engine-version }}
+```
+
 ### Copilot Custom Configuration
 
 For the Copilot engine, you can specify a specialized prompt to be used whenever the coding agent is invoked. This is called a "custom agent" in Copilot vocabulary. You specify this using the `agent` field. This references a file located in the `.github/agents/` directory:

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

@@ -475,6 +475,16 @@ timeout-minutes: 30                  # Defaults to 20 minutes
 
 `runs-on` applies to the main agent job only. `runs-on-slim` applies to all framework/generated jobs (activation, safe-outputs, unlock, etc.) and defaults to `ubuntu-slim`. `safe-outputs.runs-on` takes precedence over `runs-on-slim` for safe-output jobs specifically.
 
+`timeout-minutes` accepts either an integer or a GitHub Actions expression string. This allows `workflow_call` reusable workflows to parameterize the timeout via caller inputs:
+
+```yaml wrap
+# Literal integer
+timeout-minutes: 30
+
+# Expression — useful in reusable (workflow_call) workflows
+timeout-minutes: ${{ inputs.timeout }}
+```
+
 **Supported runners for `runs-on:`**
 
 | Runner | Status |

docs/src/content/docs/reference/tools.md

@@ -126,6 +126,37 @@ tools:
 
 See [GH-AW as an MCP Server](/gh-aw/reference/gh-aw-as-mcp-server/) for available operations.
 
+## Tool Timeout Configuration
+
+### Tool Operation Timeout (`tools.timeout`)
+
+Sets the per-operation timeout in seconds for tool and MCP server calls. Applies to all tools and MCP servers when supported by the engine. Defaults vary by engine (Claude: 60 s, Codex: 120 s).
+
+```yaml wrap
+tools:
+  timeout: 120   # seconds
+```
+
+### MCP Server Startup Timeout (`tools.startup-timeout`)
+
+Sets the timeout in seconds for MCP server initialization. Default is 120 seconds.
+
+```yaml wrap
+tools:
+  startup-timeout: 60   # seconds
+```
+
+Both fields accept either an integer or a GitHub Actions expression string, enabling `workflow_call` reusable workflows to parameterize these values:
+
+```yaml wrap
+tools:
+  timeout: ${{ inputs.tool-timeout }}
+  startup-timeout: ${{ inputs.startup-timeout }}
+```
+
+> [!NOTE]
+> Expression values are passed through environment variables in the compiled workflow. TOML-based engine configs (Codex MCP gateway) fall back to engine defaults when an expression is used, since TOML has no expression syntax.
+
 ## Custom MCP Servers (`mcp-servers:`)
 
 Integrate custom Model Context Protocol servers for third-party services: