feat: transparent proxy mode for zero-code interception

[imran-siddique]

Summary

Add a transparent proxy/tunnel mode so AGT's governance sidecar can intercept agent traffic without requiring the agent to make explicit API calls.

Problem

AGT's current sidecar deployment requires the orchestration layer to explicitly call the sidecar HTTP API (e.g., POST /api/v1/check-policy). This means:

• It's not truly "zero-code" integration (Tier 0)
• Agents that don't know about AGT can't be governed
• Retrofitting governance onto existing agent deployments requires code changes

The docs in docs/deployment/openclaw-sidecar.md explicitly note: "The orchestration layer must call the sidecar API." This is the biggest gap in AGT's zero-code story.

Proposed design

Tunnel-based transparent interception

Deploy AGT as a forward proxy that the agent's traffic routes through automatically (via network config, not code changes). The proxy:

1. Intercepts outbound connections (HTTP/HTTPS, MCP over stdio/SSE)
2. Parses the request at the protocol level
3. Evaluates policy rules against the parsed request
4. Forwards allowed requests, blocks denied requests
5. Logs every decision to the audit trail

Deployment options

1. Network namespace proxy (Linux): Run the agent in a network namespace where all outbound traffic routes through AGT's proxy process
2. Docker network proxy: Configure Docker networking so the agent container's traffic routes through an AGT sidecar container
3. Kubernetes sidecar with iptables: Use init container to redirect outbound traffic through AGT sidecar (Istio-style)
4. Environment variable proxy: Set HTTP_PROXY/HTTPS_PROXY for HTTP-only interception (simplest, least coverage)

What changes vs. current sidecar

Current sidecar	Transparent proxy
Agent calls AGT API explicitly	Agent traffic routed through AGT automatically
Agent must know AGT exists	Agent is unaware of AGT
HTTP API only	Protocol-aware (HTTP, MCP, potentially more)
Requires code changes	Requires network config only

Acceptance criteria

• At least one transparent interception mode implemented (Docker network proxy recommended for MVP)
• HTTP/HTTPS traffic intercepted and policy-evaluated
• MCP over SSE traffic intercepted and policy-evaluated
• Audit log captures all intercepted requests and verdicts
• No changes required to agent code
• Documentation with Docker Compose example
• Performance benchmarks (latency overhead of proxy)
• docs/integration-tiers.md updated to reflect true Tier 0 capability

[Ricky-G]

Scope clarification: this issue is Python-only.

To keep the initial PR small and reviewable, this ticket will implement the transparent proxy mode in the Python stack only (agent-governance-python/).

The same capability for the other language SDKs (TypeScript, .NET, Rust, Go) — including per-language examples, docs, and proxy-aware client guidance — is tracked separately in #2573 so each can be sized and reviewed independently.

Follow-up: #2573

[miyannishar]

This is the single biggest scope item on the board right now. The design is solid but there's a sequencing dependency we need to respect.

Why it should wait for wire-protocol parity (#2537): The transparent proxy needs to understand the traffic it's intercepting — not just forward bytes. The wire-protocol facets work adds SQL and K8s parsers that extract structured fields (verb, target, tables, functions) from protocol-level content. Without that, the proxy would be limited to URL-level policy checks, which defeats the purpose.

@Ricky-G thanks for scoping this down to Python-only in the first pass with the follow-up in #2573 for other SDKs. That's the right call — this is going to be complex enough without trying to do all five languages at once.

A few things to think about for the implementation:

1. Docker network proxy is the right MVP target. It's the most practical for the majority of agent deployments today. The Kubernetes iptables approach is important but it's a superset of the Docker version — build the simpler one first.

2. MCP over stdio is going to be tricky. HTTP/HTTPS interception is well-understood (mitmproxy patterns), but stdio-based MCP means you need to sit in the process pipe, not the network stack. That might need a wrapper binary rather than a network proxy. Worth thinking about whether that belongs in MVP or follow-up.

3. Performance benchmarks should be a hard requirement, not a nice-to-have. If the proxy adds >10ms p99 latency to every tool call, operators won't use it. Need numbers before merge.

Keeping this open but it's behind #2537 and #2478 in the queue. Once wire-protocol facets land, we can start prototyping the HTTP proxy layer.

[Ricky-G]

Quick status check on the blocked state for this issue.

The dependency called out earlier in this thread, #2537 (wire-protocol-aware policy evaluation), closed as completed on 2026-05-26 via #2587 and #2588. With that upstream work shipped, this issue may no longer be blocked.

Could a maintainer confirm which of the following applies:

1. Unblocked. Ready to move forward. In that case I will clear the blocked label and add a blocked-by:2537 tag so the historical dependency stays auditable.
2. Still blocked on something else. Please share the new blocker issue number and I will relabel with blocked-by:<num> instead.

No rush, just want to keep the blocked state accurate and auditable.