feat: add cli-proxy feature flag for AWF gh CLI proxy sidecar (firewall v0.25.14)

[lpcox]

Summary

AWF firewall v0.25.14 adds a gh CLI proxy sidecar (--enable-cli-proxy) that gives agents secure gh CLI access without exposing GITHUB_TOKEN in the agent container. The token is held in an mcpg DIFC proxy inside the sidecar, enforcing guard policies and audit logging — the same integrity guarantees as the existing DIFC proxy for pre-agent steps.

This issue tracks the gh-aw compiler changes needed to take advantage of this new firewall capability.

Background

• Firewall PRs: github/gh-aw-firewall#1730 (implementation), github/gh-aw-firewall#1734 (integration tests)
• Design doc: github/gh-aw-firewall#1726

AWF flags available in v0.25.14

Flag	Type	Description
--enable-cli-proxy	bool	Start the cli-proxy sidecar at 172.30.0.50:11000
--cli-proxy-writable	bool	Allow write operations (default: read-only)
--cli-proxy-policy <json>	string	Guard policy JSON for the mcpg DIFC proxy
--cli-proxy-mcpg-image <image>	string	Override mcpg image (only used with --build-local)

How the sidecar works

Agent runs `gh pr list`
  → gh wrapper (shell script at /tmp/awf-lib/gh, prepended to PATH)
  → HTTP POST to cli-proxy sidecar at 172.30.0.50:11000/exec
  → server.js validates subcommand allowlist (read-only by default)
  → execFile("gh", args) with GH_HOST=localhost:18443
  → mcpg proxy injects GH_TOKEN, enforces guard policy, logs to JSONL
  → Squid enforces domain allowlist on outbound traffic
  → response returned to agent

Implementation Plan

1. Bump firewall version

In pkg/constants/version_constants.go:

const DefaultFirewallVersion Version = "v0.25.14"  // was "v0.25.13"

2. Add cli-proxy feature flag

In pkg/constants/feature_constants.go:

// CliProxyFeatureFlag enables the AWF CLI proxy sidecar.
// When enabled, the compiler injects --enable-cli-proxy into the AWF command,
// giving the agent secure gh CLI access without exposing GITHUB_TOKEN.
CliProxyFeatureFlag FeatureFlag = "cli-proxy"

Workflow frontmatter usage:

features:
  cli-proxy: true

3. Inject --enable-cli-proxy in AWF command builder

In pkg/workflow/awf_helpers.go, inside BuildAWFCommand(), after the existing --enable-api-proxy injection:

// Enable CLI proxy sidecar when feature flag is set
if isFeatureEnabled(config.WorkflowData, constants.CliProxyFeatureFlag) {
    awfArgs = append(awfArgs, "--enable-cli-proxy")
    awfHelpersLog.Print("Added --enable-cli-proxy for gh CLI proxy sidecar")
}

4. Generate and pass guard policy

Reuse getDIFCProxyPolicyJSON() from compiler_difc_proxy.go to generate the guard policy, then pass it as --cli-proxy-policy:

if isFeatureEnabled(config.WorkflowData, constants.CliProxyFeatureFlag) {
    githubTool := config.WorkflowData.Tools["github"]
    policyJSON := getDIFCProxyPolicyJSON(githubTool)
    if policyJSON != "" {
        awfArgs = append(awfArgs, "--cli-proxy-policy", policyJSON)
        awfHelpersLog.Printf("Added --cli-proxy-policy with guard policy")
    }
}

5. Support cli-proxy-writable feature flag (optional)

For workflows that need write access (e.g., creating issues, merging PRs):

features:
  cli-proxy: true
  cli-proxy-writable: true

CliProxyWritableFeatureFlag FeatureFlag = "cli-proxy-writable"

When set, inject --cli-proxy-writable into the AWF command.

6. (Future) Reduce GitHub MCP toolsets

When cli-proxy is enabled, the agent can use gh directly for read operations, so the GitHub MCP server's read-only toolsets become redundant. A future optimization could:

• Remove read-only MCP toolsets (issue_read, list_commits, search_code, get_file_contents, etc.)
• Keep only write-sink toolsets (create_issue, add_issue_comment, create_pull_request, etc.)
• This reduces context by ~8-12k tokens/turn

This is not required for the initial implementation — both MCP tools and gh CLI can coexist (Phase 1 coexistence).

7. Documentation

Update the gh-aw instructions file to document:

• The cli-proxy feature flag
• When to use it (agents that benefit from gh CLI access)
• The cli-proxy-writable option for write operations
• That gh api is blocked in read-only mode (use typed subcommands)

Key Files to Modify

File	Change
pkg/constants/version_constants.go	Bump DefaultFirewallVersion to v0.25.14
pkg/constants/feature_constants.go	Add CliProxyFeatureFlag and CliProxyWritableFeatureFlag
pkg/workflow/awf_helpers.go	Inject --enable-cli-proxy, --cli-proxy-writable, --cli-proxy-policy in BuildAWFCommand()
pkg/workflow/awf_helpers_test.go	Tests for the new flag injection
.github/aw/github-agentic-workflows.md	Document the feature flags

Testing

• Unit test: BuildAWFCommand() includes --enable-cli-proxy when feature flag is set
• Unit test: BuildAWFCommand() includes --cli-proxy-policy with correct JSON when guard policies configured
• Unit test: BuildAWFCommand() includes --cli-proxy-writable when writable feature flag is set
• Unit test: BuildAWFCommand() does NOT include cli-proxy flags when feature flag is absent
• Integration: compile a test workflow with features: cli-proxy: true and verify the lock file contains the flags

Reference

• Existing pattern: --enable-api-proxy is always injected in BuildAWFCommand() (line ~242 of awf_helpers.go). The cli-proxy follows the same pattern but is gated behind a feature flag.
• Guard policy reuse: getDIFCProxyPolicyJSON() in compiler_difc_proxy.go already generates the correct static policy JSON from tools.github config (min-integrity, repos). The same function can be called for the cli-proxy policy.
• DIFC proxy feature flag: difc-proxy was deprecated in favor of tools.github.integrity-proxy. The cli-proxy flag is a separate concern (agent-side gh CLI access vs. pre-agent step filtering).