feat(governance): Add GovernancePlugin for runtime agent governance

[sunilp]

Summary

Adds a GovernancePlugin that provides runtime governance for ADK agents — policy-based tool filtering, delegation scope enforcement, and structured audit trails — without modifying agent logic.

Moved here from google/adk-python#4897 per maintainer guidance (community plugins belong in this repo).

What it does

• Policy-based tool filtering — evaluate tool calls against custom policies before execution; deny with structured reasons
• Tool argument validation — regex-based argument pattern enforcement (e.g., SQL queries must start with SELECT)
• Delegation scope enforcement — control which agents can delegate to which other agents
• Structured audit trail — every policy decision logged with timestamp, agent, tool, decision, and reason
• Pluggable architecture — custom PolicyEvaluator protocol for organization-specific rules; custom AuditHandler for integration with logging/SIEM systems

Usage

from google.adk_community.governance import (
    GovernancePlugin, PolicyEvaluator, PolicyDecision, ToolPolicy,
)

class MyPolicyEvaluator(PolicyEvaluator):
    async def evaluate_tool_call(self, *, tool_name, tool_args,
                                 agent_name, context):
        if tool_name == "dangerous_tool":
            return PolicyDecision.deny("Tool not allowed by policy")
        return PolicyDecision.allow()

plugin = GovernancePlugin(
    policy_evaluator=MyPolicyEvaluator(),
    tool_policies={"sql_tool": ToolPolicy(allowed_arg_patterns={"query": r"^SELECT"})},
)
# runner = Runner(..., plugins=[plugin])

Files

• src/google/adk_community/governance/governance_plugin.py — plugin implementation (692 lines)
• src/google/adk_community/governance/__init__.py — public API exports
• tests/unittests/governance/test_governance_plugin.py — unit tests (577 lines)

Testing plan

• 577 lines of unit tests covering: policy evaluation, tool filtering, argument validation, delegation scope enforcement, audit trail generation, edge cases
• Tests use mocks for ADK internals (BaseAgent, CallbackContext, InvocationContext)

Related

• Original PR: feat(plugins): Add GovernancePlugin for runtime agent governance adk-python#4897 (closed — directed here by @rohityan)

[sunilp]

Friendly bump — anything needed from my side to move this forward? Happy to address feedback or adjust the scope.