Migrate agent enclaves from gh CLI proxy to GitHub MCP

[lpcox]

Summary

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

The implementation has landed across AWF, gh-aw, and gh-aw-mcpg. Agent enclaves now use the compiler-owned shared mcpg process directly: the enclave receives a distinct policy-limited identity, connects only to /mcp/github, and has no gh executable or local GitHub proxy.

The migration is functionally complete and has passed end-to-end scheduled smoke runs. Closure is pending a green smoke run from current main after the gh-aw v0.88.2 workflow recompile introduced a workflow-definition failure.

Landed work

• Isolate runtime access for multiple gateway agent IDs gh-aw-mcpg#12186 added concurrent multi-agent identities, fail-closed per-agent server/tool/repository policies, isolated session and DIFC state, redacted attribution, and shared-gateway close isolation. Released in gh-aw-mcpg v0.4.15.
• Connect agent enclaves directly to shared GitHub MCP #7991 removed the enclave GitHub CLI wrapper, REST capability path, local GitHub bridge, dedicated control network, certificate handoff, and bridge audit lifecycle. AWF now attaches compiler-owned mcpg directly to the isolated enclave-agent network.
• Compile enclave GitHub access through shared multi-agent mcpg gh-aw#57973 compiles independent primary/enclave gateway identities and complete gateway.agentPolicies, passes the private AWF handoff, and removes the dedicated enclave GitHub proxy lifecycle.
• test: validate shared-gateway enclave smoke #8026 recompiled the Issues-read smoke workflow for the shared-gateway topology and added regression assertions for topology, policy, identity masking, and primary-agent exclusion.
• Scheduled end-to-end smoke runs 33702518393 and 33757331745 passed.

Current runtime contract

For enclaves[].agent.github.cli: issues-read-v1, the compiler provides AWF with:

• AWF_ENCLAVE_MCP_GATEWAY_CONTAINER: the existing shared mcpg container name;
• AWF_ENCLAVE_MCP_GATEWAY_ENDPOINT: its host-loopback readiness endpoint;
• AWF_ENCLAVE_MCP_GATEWAY_IDENTITY: the run identity used to verify container ownership; and
• AWF_ENCLAVE_GITHUB_MCP_AGENT_ID: a distinct mcpg identity reserved for the agent enclave.

The compiler configures the enclave identity in gateway.agentIds and gateway.agentPolicies, allowing only:

• the github MCP server;
• list_issues and issue_read; and
• the union of repositories declared for the trusted enclave agent, enforced through an allow-only policy.

AWF then:

• verifies the compiler-owned gateway container and run label;
• stages the enclave identity in a mode-0600 private file and removes it from the host environment;
• attaches mcpg to the internal awf-enclave-agent network at its fixed address;
• verifies exact steady-state network membership;
• performs an MCP initialize handshake and requires the advertised tools to be exactly list_issues and issue_read;
• gives each single-use enclave only a read-only private copy of the enclave identity; and
• disconnects, but never stops or removes, the compiler-owned gateway during cleanup.

Security requirements

• The primary agent must never receive the enclave identity, GitHub PAT, gateway API key, or full gateway configuration.
• The enclave must never receive the GitHub PAT, primary identity, compiler root material, or undeclared MCP servers.
• The enclave identity must expose only github, list_issues, and issue_read.
• Repository access must be allow-only and limited to the trusted repository union declared for the enclave agent.
• Search, GraphQL, writes, unknown tools, and unrelated repositories must fail closed.
• Primary and enclave identities must have independent MCP sessions and DIFC state.
• Agent identities and credentials must remain masked or absent from plaintext logs and agent-readable artifacts.
• Existing script enclaves and agent enclaves without GitHub access must retain their current behavior.
• Missing or malformed handoff fields must fail before primary-agent startup.

Accepted identity-scope decision

The enclave gateway identity is job-lifetime rather than per-invocation. Its mcpg repository policy covers the union of trusted repositories configured for the enclave agent; it is not independently expired, revoked, or narrowed to the repository assigned to one invocation.

This is the accepted replacement for the former per-invocation awf-egh1 capability. Do not restore the local proxy or REST capability path solely to regain per-invocation identity binding. AWF continues to enforce per-invocation process isolation, immutable repository seed assignment, admission serialization, the shared disclosure ledger, finite output schemas, invocation limits, timeout, output budget, and timing controls.

Remaining work

• Fix the workflow-definition failure introduced when Upgrade gh-aw workflows to v0.88.2 #8061 recompiled workflows with gh-aw v0.88.2. The current failing run is 33777543534.
• Obtain a green smoke-enclave-issues-read run from current main.
• Close this issue after the current-head smoke confirms the already-landed shared-gateway topology.

Non-blocking cleanup: ENCLAVE_GITHUB_PROXY_ALIAS and ENCLAVE_GITHUB_PROXY_PORT appear to be obsolete enclave-specific constants and can be removed separately if confirmed unused.

Acceptance status

• Agent enclaves read assigned-repository issues through GitHub MCP and the shared mcpg process.
• The enclave profile requires no gh binary or local GitHub CLI proxy.
• The GitHub PAT remains outside the enclave.
• The enclave identity exposes exactly list_issues and issue_read.
• Enclave repository access is constrained by an allow-only repository policy.
• Primary and enclave identities have independent policy, session, and DIFC state.
• The accepted job-lifetime identity model is documented.
• Existing enclave behavior without GitHub access remains covered.
• Integration uses gh-aw-mcpg v0.4.15.
• The migrated topology has passed scheduled end-to-end smoke runs.
• The smoke workflow passes on current main after the gh-aw v0.88.2 recompile.

Related work

• Compile enclaves through one multi-agent MCP gateway gh-aw#57787
• Compile enclave GitHub access through shared multi-agent mcpg gh-aw#57973
• Isolate runtime access for multiple gateway agent IDs gh-aw-mcpg#12186
• Connect agent enclaves directly to shared GitHub MCP #7991
• test: validate shared-gateway enclave smoke #8026
• Upgrade gh-aw workflows to v0.88.2 #8061