feat: per-request pass-through headers on ModelConfig

[TarasLykhenko]

Motivation

kagent supports static defaultHeaders on outbound LLM calls, and apiKeyPassthrough for forwarding the caller's Bearer credential. There is no way to forward an arbitrary caller-supplied header per request — e.g. a guardrail token, tenant token, or request id that a proxy in front of the LLM provider needs. Organizations running LLM traffic through policy gateways need the caller's own token on each outbound call, which static configuration cannot express.

What this adds

apiVersion: kagent.dev/v1alpha3
kind: ModelConfig
spec:
  defaultHeaders:            # unchanged: static values
    x-tenant: acme
  passthroughHeaders:        # NEW: names resolved from each incoming A2A request
    - x-guardrail-token

Header names are case-insensitive; values are read per request from the incoming A2A call context. A pass-through value overrides a defaultHeaders entry of the same name; headers absent from the request are omitted. Authorization is rejected at admission (CEL) — credential forwarding stays on apiKeyPassthrough — and both runtimes additionally drop credential carriers (Proxy-Authorization, Cookie) and RFC 9110 hop-by-hop names at runtime.

Changes by layer

• CRD (v1alpha3): passthroughHeaders []string with bounds and CEL validation; envtest CEL test; manifests + Helm CRDs regenerated.
• Wire: passthrough_headers on adk.BaseModel; populateHeaderFields helper (mirrors populateTLSFields) in the adkconfig translator, covering all 10 provider branches.
• Go runtime: allowedRequestHeaders lifted from pkg/mcp into a shared pkg/headers package (a2a-go v2); headerTransport overlays per-request headers from the call context after static ones. 8/10 providers get this via BuildHTTPClient; GeminiVertexAI and SAPAICore log a warning — they build clients without the shared transport and already drop defaultHeaders/TLS today (pre-existing gap, left as-is here).
• A2A gateway: a callerHeadersInterceptor on the runtime dialer relays caller-supplied custom headers from the public request onto the private runtime call, excluding credential, hop-by-hop, gRPC pseudo/system, and interceptor-owned (traceparent, x-a2a-extensions) metadata. Without this hop, neither passthroughHeaders nor the existing MCP allowedHeaders can see caller headers through the gateway; the runtime-side allowlists remain the actual gate.
• Python runtime: LLMHeaderPassthroughPlugin resolves session-state headers (case-insensitive, restricted names filtered, empty values omitted) onto llm_request.config.http_options for OpenAI/Azure (per-call extra_headers) and Gemini (honoured natively); Anthropic uses a cache-invalidating set_passthrough_headers, the same mechanism as set_passthrough_key (same shared-client concurrency caveat, documented). Bedrock, Ollama, VertexAI, and SAP AI Core log a warning and ignore the field.

Design points for reviewers

1. Gateway forwarding scope — the interceptor forwards all non-restricted custom caller headers rather than resolving the instance's configured allowlist at the gateway (the dialer has no ModelConfig access, and the runtime filters by allowlist anyway). If you'd rather plumb the configured names into the resolved bundle instead, happy to rework.
2. Anthropic delivery — per-call headers can't reach messages.create inside the ADK Claude base class, hence the cache-invalidation setter. A per-request carrier in google-adk would allow removing it.

Testing

Unit tests at every layer (transport overlay + credential protection, restricted-name filter, wire round-trip, gateway interceptor, CEL admission via envtest, Python plugin + provider behavior), plus a regression asserting a defaultHeaders-only config produces byte-identical requests.