Migrate agent enclaves from gh CLI proxy to GitHub MCP

[lpcox]

Summary

Migrate agent-enclave GitHub access from the current PAT-free gh api proxy path to the GitHub MCP server through gh-aw's shared MCP Gateway.

This enables github/gh-aw#57787 to compile primary and enclave access through one multi-agent mcpg instance instead of starting a dedicated awmg proxy process for issues-read-v1.

Context

The current enclaves[].agent.github.cli: issues-read-v1 implementation:

• exposes a constrained gh api surface inside the enclave;
• routes requests through an AWF-owned local CLI proxy;
• authenticates each invocation with a short-lived signed awf-egh1 capability;
• binds that capability to the workflow run, invocation, assigned repository, allowed operations, and expiry;
• keeps the GitHub PAT, mcpg endpoint, root capability key, and repository catalog outside the enclave.

gh-aw-mcpg v0.4.15 now supports concurrent gateway.agentIds and fail-closed gateway.agentPolicies, including per-agent server/tool allowlists, allow-only repository policies, independent session/DIFC state, redacted attribution, and shared-gateway close isolation.

However, AWF agent enclaves currently run gh rather than acting as MCP clients. The awf-enclave MCP route is used by the primary agent to invoke AWF; it does not configure the nested enclave agent to connect back to the shared gateway.

Proposed direction

Teach the agent-enclave runtime to consume a compiler-provided GitHub MCP connection for its declared GitHub profile:

• Configure the nested enclave agent as an MCP client of the existing shared mcpg instance.
• Provide only the enclave-specific gateway identity through a protected AWF-to-enclave handoff.
• Expose only the GitHub MCP server and exact tools declared by the closed enclave profile.
• Keep the upstream GitHub token solely in mcpg/the GitHub MCP backend.
• Preserve repository assignment, DIFC secrecy labels, integrity floors, audit attribution, invocation limits, and fail-closed behavior.
• Remove the need for the AWF-owned local gh proxy and awf-egh1 REST authorization path once equivalent or stronger guarantees exist.

The user-facing field may remain github.cli: issues-read-v1 temporarily for compatibility, but the runtime implementation should use MCP. A later schema migration can rename the field/profile separately if desired.

Security requirements

• The primary agent must never receive the enclave gateway identity.
• One enclave identity must not access another identity's session, tools, repositories, or policy.
• The enclave must not receive the GitHub PAT, primary agent ID, capability root key, full gateway configuration, or undeclared MCP servers.
• Repository access must remain allow-only and bound to the enclave's declared repository assignment.
• The issues-read-v1 profile must remain read-only and limited to issue listing, issue reads, and issue-comment listing.
• Unknown tools, GraphQL-equivalent capabilities, writes, search, and unrelated repository operations must fail closed.
• Agent IDs and credentials must be absent from plaintext logs, diagnostics, configuration artifacts exposed to the enclave, and primary-agent environment.
• Concurrent enclave/primary requests must maintain independent DIFC state.

Capability-model decision

The current signed capability is per invocation and binds run, invocation, repository, operation subset, and TTL. A static gateway agent ID plus agentPolicies does not automatically provide all of those properties.

Define an explicit replacement before removing awf-egh1. Options include:

1. generating a distinct preconfigured gateway identity per permitted enclave invocation;
2. adding a trusted AWF-to-mcpg mechanism for short-lived delegated identities;
3. retaining an invocation capability as an additional MCP header that mcpg validates; or
4. documenting why the enclave lifecycle, network isolation, gateway policy, and process teardown provide equivalent enforcement.

Prefer a design that preserves per-invocation revocation/expiry and repository binding without exposing compiler-owned root material.

Required work

• Extend AWF enclave configuration/runtime types with the shared gateway endpoint, enclave identity handoff, server name, and allowed tool/profile metadata.
• Configure supported nested agent engines to use the GitHub MCP server through mcpg.
• Establish private-network reachability from the enclave to the shared gateway without exposing other gateway surfaces.
• Map the closed issues-read-v1 profile to exact GitHub MCP tool names and validate their availability at startup.
• Initialize the enclave's DIFC state with its assigned repository secrecy label and configured integrity floor.
• Preserve invocation timeout, maximum invocation, output-budget, and teardown enforcement.
• Remove the local CLI proxy, CA/certificate handoff, and REST capability path after migration.
• Update schemas, runtime documentation, threat model, and cross-repository integration fixtures.

Acceptance criteria

• An agent enclave reads assigned-repository issues using GitHub MCP through the shared mcpg process.
• No gh binary or local GitHub CLI proxy is required for the profile.
• The GitHub PAT remains outside the enclave.
• The primary agent cannot invoke enclave-only GitHub tools or access enclave-only repositories.
• The enclave cannot invoke undeclared GitHub MCP tools or access undeclared private repositories.
• Concurrent primary and enclave requests have independent session/DIFC state and redacted audit attribution.
• The replacement capability model preserves or strengthens per-invocation repository, operation, and lifetime bounds.
• Existing script enclaves and agent enclaves without GitHub access retain current behavior.
• Integration coverage works with gh-aw-mcpg v0.4.15 or a clearly identified later minimum version.

Related work

• Compile enclaves through one multi-agent MCP gateway gh-aw#57787
• Isolate runtime access for multiple gateway agent IDs gh-aw-mcpg#12186
• Add read-only GitHub Issues access to agent enclaves gh-aw#55531
• gh-aw-mcpg v0.4.15