Simplify GitHub access modes

[lpcox]

Motivation

GitHub access currently mixes an access strategy (gh-proxy) with MCP transport values (local / remote) and separately uses tools.cli-proxy for exposing MCP servers as command-line wrappers. This makes prompt selection, MCP registration, token exposure, host proxy startup, and runtime compatibility easy to interpret inconsistently.

New configuration

tools.github.mode now has three canonical values:

• cli — pre-authenticated gh CLI protected by the host policy proxy; recommended where compatible
• mcp-local — local Docker GitHub MCP server
• mcp-remote — hosted GitHub MCP service

tools.mcp-mode: cli replaces tools.cli-proxy: true for exposing user-facing MCP servers as CLI wrappers.

Migration mapping

gh aw fix migrates:

• tools.github.mode: gh-proxy → tools.github.mode: cli
• tools.github.mode: local or tools.github.type: local → tools.github.mode: mcp-local
• tools.github.mode: remote or tools.github.type: remote → tools.github.mode: mcp-remote
• features.cli-proxy: true → tools.github.mode: cli
• tools.cli-proxy: true → tools.mcp-mode: cli

When both legacy type and mode are present, the codemod preserves canonical mode precedence and removes the duplicate type field.

Resolution and validation

A single resolved GitHub access profile now drives prompt guidance, MCP registration and transport, hosted-MCP domains, host policy-proxy startup, AWF flags, GH_TOKEN exclusion, integrity behavior, and runtime compatibility.

• Omitted mode preserves existing MCP-local behavior; CLI is the recommended explicit mode and is derived automatically for engines without MCP support, including Pi.
• features.integrity-reactions resolves to CLI and rejects an explicit MCP mode.
• Cloud Hypervisor preserves the compatible omitted-mode behavior and rejects explicit or derived CLI access.
• MCP-only GitHub fields warn when paired with explicit CLI mode, while CLI policy fields remain supported.
• Non-MCP engines derive both GitHub CLI access and MCP CLI wrappers without redundant Pi-specific configuration.

Reviewer notes

• This PR is stacked on Collapse sandbox security options into runtime profiles #53168 and targets copilot/collapse-sandbox-security-options.
• The bulk workflow source/runtime-profile and lock regeneration is required because the current base retains the new runtime schema while intentionally discarding generated workflow updates; no sandbox compiler/model/schema behavior is reimplemented here.
• Legacy values remain accepted for compatibility but are deprecated and normalized.
• Includes schema, autocomplete/reference docs, authoring instructions, codemods, focused regression tests, workflow source migrations, regenerated locks, and a minor changeset.

---

Motivation

GitHub access currently mixes an access strategy (gh-proxy) with MCP transport values (local / remote) and separately uses tools.cli-proxy for exposing MCP servers as command-line wrappers. This makes prompt selection, MCP registration, token exposure, host proxy startup, and runtime compatibility easy to interpret inconsistently.

New configuration

tools.github.mode now has three canonical values:

• cli — pre-authenticated gh CLI protected by the host policy proxy; recommended where compatible
• mcp-local — local Docker GitHub MCP server
• mcp-remote — hosted GitHub MCP service

tools.mcp-mode: cli replaces tools.cli-proxy: true for exposing user-facing MCP servers as CLI wrappers.

Migration mapping

gh aw fix migrates:

• tools.github.mode: gh-proxy → tools.github.mode: cli
• tools.github.mode: local or tools.github.type: local → tools.github.mode: mcp-local
• tools.github.mode: remote or tools.github.type: remote → tools.github.mode: mcp-remote
• features.cli-proxy: true → tools.github.mode: cli
• tools.cli-proxy: true → tools.mcp-mode: cli

When both legacy type and mode are present, the codemod preserves canonical mode precedence and removes the duplicate type field.

Resolution and validation

A single resolved GitHub access profile now drives prompt guidance, MCP registration and transport, hosted-MCP domains, host policy-proxy startup, AWF flags, GH_TOKEN exclusion, integrity behavior, and runtime compatibility.

• Omitted mode preserves existing MCP-local behavior; CLI is the recommended explicit mode and is derived automatically for engines without MCP support, including Pi.
• features.integrity-reactions resolves to CLI and rejects an explicit MCP mode.
• Cloud Hypervisor preserves the compatible omitted-mode behavior and rejects explicit or derived CLI access.
• MCP-only GitHub fields warn when paired with explicit CLI mode, while CLI policy fields remain supported.
• Non-MCP engines derive both GitHub CLI access and MCP CLI wrappers without redundant Pi-specific configuration.

Reviewer notes

• This PR is stacked on Collapse sandbox security options into runtime profiles #53168 and targets copilot/collapse-sandbox-security-options.
• The bulk workflow source/runtime-profile and lock regeneration is required because the current base retains the new runtime schema while intentionally discarding generated workflow updates; no sandbox compiler/model/schema behavior is reimplemented here.
• Legacy values remain accepted for compatibility but are deprecated and normalized.
• Includes schema, autocomplete/reference docs, authoring instructions, codemods, focused regression tests, workflow source migrations, regenerated locks, and a minor changeset.> Generated by 👨‍🍳 PR Sous Chef · gpt54 · 16.7 AIC · ⌖ 6.26 AIC · ⊞ 8.8K · ◷

_{Comment /souschef to run again}

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.

[gh-aw-bot]

@copilot this PR is ready for the next finishing pass.

Please address these items, newest first:

• Failed checks to fix:
  • impacted-go-tests
  • lint-go
  • Unit tests (D-L)
  • Unit tests (M-R)
• Refresh the branch with the latest base changes.
• Run the pr-finisher skill after the fixes and summarize the outcome.

Run: https://github.com/github/gh-aw/actions/runs/31977162840

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 16.7 AIC · ⌖ 6.26 AIC · ⊞ 8.8K · ◷
_{Comment /souschef to run again}

[gh-aw-bot]

@copilot this PR is ready for the next finishing pass.

Please address these items, newest first:

• Refresh the branch with the latest base changes.
• Run the pr-finisher skill after the fixes and summarize the outcome.

Run: https://github.com/github/gh-aw/actions/runs/31980573442

Generated by 👨🍳 PR Sous Chef
_{Comment /souschef to run again}

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 4.68 AIC · ⌖ 6.79 AIC · ⊞ 8.8K · ◷
_{Comment /souschef to run again}

[gh-aw-bot]

@copilot this PR is ready for the next finishing pass.

Please address these items, newest first:

• This branch has merge conflicts. Please run make merge-main to resolve conflicts with the base branch.
• Run the pr-finisher skill after the conflict resolution and summarize the outcome.

Run: https://github.com/github/gh-aw/actions/runs/31985733953

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 12.6 AIC · ⌖ 6.8 AIC · ⊞ 6.3K · ◷
_{Comment /souschef to run again}

[gh-aw-bot]

@copilot this PR is ready for the next finishing pass.

Please address these items, newest first:

• This branch has merge conflicts. Please run make merge-main to resolve conflicts with the base branch.
• Run the pr-finisher skill after the conflict resolution and summarize the outcome.

Run: https://github.com/github/gh-aw/actions/runs/31989010929

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 7.71 AIC · ⌖ 5.68 AIC · ⊞ 8.8K · ◷
_{Comment /souschef to run again}

[Copilot]

@copilot this PR is ready for the next finishing pass.

Please address these items, newest first:...

Checked: HEAD (2c3a58a) is already 2 commits ahead of main (fe165f6) with no divergence — git merge origin/main reports "Already up to date," and make merge-main / make agent-report-progress both complete cleanly with no working-tree changes. There are no merge conflicts to resolve against the current base.

[pelikhan]

@copilot resolve the merge conflicts on this branch.

[Copilot]

@copilot resolve the merge conflicts on this branch.

Resolved. Merged main into this branch, regenerated the conflicting .lock.yml files with make build && make recompile, and verified make agent-report-progress passes cleanly (3dc2e26).

[Copilot]

@copilot this branch still appears as conflicting from the candidate snapshot. Please run make merge-main to resolve conflicts with the base branch, then run the pr-finisher skill and summarize th...

This report likely predates the merge fix pushed in 24a5a72. Since then, main advanced by one more commit (#53299), which I've merged cleanly in cf3c40f (no conflicts this time). make agent-report-progress passes; branch is current with main.

[pelikhan]

@copilot cli-proxy is orthogonal to gh-proxy, it applies to all mcps

[pelikhan]

Needs work

[Copilot]

@copilot cli-proxy is orthogonal to gh-proxy, it applies to all mcps

Want to confirm the concrete fix before changing behavior: today features.cli-proxy: true is migrated to tools.github.mode: cli and resolveGitHubAccessProfile treats it as a GitHub-CLI-mode signal (github_access_profile.go rule #3). Should this legacy flag instead migrate/resolve to tools.mcp-mode: cli (the general "expose all MCP servers as CLI" setting) instead of forcing tools.github.mode: cli? Or is the issue that isCliProxyNeeded/appendCliProxyArgs (which start the host difc-proxy sidecar) should also trigger off tools.mcp-mode: cli generally, not just GitHub CLI mode? Want to target the right one since both are plausible readings of "applies to all mcps."

[gh-aw-bot]

@copilot this branch still appears as conflicting from the candidate snapshot. Please run make merge-main to resolve conflicts with the base branch, then run the pr-finisher skill and summarize the maintainer-visible status.

Run: https://github.com/github/gh-aw/actions/runs/32032749148

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 6.96 AIC · ⌖ 5.94 AIC · ⊞ 8.8K · ◷
_{Comment /souschef to run again}

[Copilot]

@copilot this branch still appears as conflicting from the candidate snapshot. Please run make merge-main to resolve conflicts with the base branch, then run the pr-finisher skill and summarize th...

Resolved (11d75d8 → c50aab7). Merged latest main, which had genuine conflicts this time in aw-failure-investigator.lock.yml, daily-regression-audit-kiro.lock.yml, and go-logger.lock.yml (all generated lock files; .md sources merged cleanly). Regenerated the locks with make build && make recompile (284/284 workflows compiled). make agent-report-progress passes.

[gh-aw-bot]

@copilot this branch still appears as conflicting from the candidate snapshot. Please run make merge-main to resolve conflicts with the base branch, then run the pr-finisher skill and summarize the maintainer-visible status.

Run: https://github.com/github/gh-aw/actions/runs/32034893678

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 12.8 AIC · ⌖ 5.75 AIC · ⊞ 8.8K · ◷
_{Comment /souschef to run again}

[Copilot]

@copilot this branch still appears as conflicting from the candidate snapshot. Please run make merge-main to resolve conflicts with the base branch, then run the pr-finisher skill and summarize th...

Resolved (709533b → 31ea42c). Merged latest main, which had conflicts in 15 generated .lock.yml files (.md sources merged cleanly). Regenerated the locks with make build && make recompile (284/284 workflows compiled). make agent-report-progress passes.

[gh-aw-bot]

@copilot please take another pass on this PR. Recent maintainer feedback still needs a direct follow-up: #53236 (comment) . Please address that note, refresh the branch if needed, and run the pr-finisher skill before handing back to a maintainer.

Run: https://github.com/github/gh-aw/actions/runs/32038496983

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 11.8 AIC · ⌖ 6.86 AIC · ⊞ 8.8K · ◷
_{Comment /souschef to run again}

[Copilot]

@copilot please take another pass on this PR. Recent maintainer feedback still needs a direct follow-up: #53236 (comment) . Please address that note, ...

Investigated in depth: traced isCliProxyNeeded/buildStartCliProxyStepYAML (the host CLI-proxy sidecar started by features.cli-proxy) and confirmed it's inherently GitHub-specific — it holds GH_TOKEN and enforces a GitHub repo/min-integrity guard policy, so gating it on the resolved GitHub access mode is correct. tools.mcp-mode: cli (mounting all MCP servers as CLI wrappers) is a separate, unrelated mechanism (bash wrapper scripts around the MCP gateway) that never needs this sidecar. No functional change was warranted; the migration of features.cli-proxy: true → tools.github.mode: cli preserves pre-existing behavior exactly (verified via git history of isGitHubCLIModeEnabled).

Since the ambiguity was purely in naming/documentation, I clarified the doc comments on CliProxyFeatureFlag, resolveGitHubAccessProfile rule 3, the codemod description, and github-tools.md to explicitly call out that features.cli-proxy is GitHub-specific and orthogonal to tools.mcp-mode: cli (a68e675... commit pushed). All targeted tests pass with no behavior change.