feat(a2a): GuardrailPlugin for org argument binding (PR #73 follow-up)

[dmartinol]

Summary

Adds an ADK GuardrailPlugin that enforces organization / tenant consistency on MCP tool arguments before tools run. This is the first tranche of hard enforcement called for after PR #73.

Why this is needed (security)

PR #73 moved the agent toward an orchestrator model (planning, pagination HITL, prompt-level guardrails). That PR’s “What’s covered vs. what needs follow-up” table called out org-id parameter tampering as not covered by prompts alone and requiring a before_tool_callback-style enforcement layer.

Relying only on the system prompt does not stop a motivated caller or a model that mis-follows instructions from passing a different organization id in tool parameters than the one bound to the validated JWT. Downstream MCP and Insights APIs still authenticate with the forwarded token, but argument-level cross-tenant targeting is an unnecessary risk and complicates auditing. This plugin short-circuits incompatible tool calls (code: guardrail_org_mismatch) so they never hit MCP when org-style parameters disagree with org_id from Red Hat SSO (or when those parameters appear but the request has no org context to verify).

This complements (does not replace) JWT validation, MCP-side auth, and rate limiting.

What changed

• New GuardrailPlugin (before_tool_callback), registered before logging and usage plugins.
• Setting: guardrail_org_args_enabled / GUARDRAIL_ORG_ARGS_ENABLED (default true).
• Recursive collection of org-style keys (including list/tuple of scalars under an org key); tests for key shapes and structures.
• Docs (api.md, configuration.md, troubleshooting.md) and deploy env wiring (Containerfile, cloudbuild.yaml, Cloud Run service.yaml, Podman configmap, .env.example, CLAUDE.md).

Follow-up (out of scope here)

As in PR #73: tool-call limits (metering plugin), broader guardrail policy (writes / arg size), message sanitization (A2A chain), multi-agent split.

Test plan

• make lint && make test

[yuvalk]

I'm ok with the concept, but disagree on calling it "first tranche"

our first line of defense is the JWT token - the agent session can only see what that token allows it to, regardless of whatever tampering it can do to API parameters

the LLMs cannot change or control it, it is totally controlled by deterministic code.

so tampering with parameters should only lead to "unauthorized" (403) responses

[dmartinol]

I'm ok with the concept, but disagree on calling it "first tranche"

Let me explain the wording: this is called "first tranche" because I'm planning to push all the 4 tranches mentioned in #73 in these days. Second one is already there as #79

our first line of defense is the JWT token - the agent session can only see what that token allows it to, regardless of whatever tampering it can do to API parameters
the LLMs cannot change or control it, it is totally controlled by deterministic code.

Agree, but not clear what you are proposing.

so tampering with parameters should only lead to "unauthorized" (403) responses

This is exactly what happens when the tampering is in the token.
Instead, blocking at the plugin returns a tool short-circuit, not an HTTP 403 to the end user, even if the semantic outcome aligns with “not authorized for that scope.”