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.

[DeanChensj]

@gemini-cli /review

[github-actions]

🤖 Hi @DeanChensj, I've received your request, and I'm working on it now! You can track my progress in the logs for more details.

[github-actions]

Great start on the GovernancePlugin! It provides a solid foundation for runtime governance in ADK.

I've identified a few issues that should be addressed before merging:

1. Missing Regex Argument Validation: The allowed_arg_patterns in ToolPolicy is defined but not enforced in before_tool_callback. This was mentioned as a key feature in the PR description.
2. Memory Growth in _audit_log: The internal audit log list grows indefinitely, which could lead to memory leaks in long-running applications.
3. Interleaved Audit Events: Since _audit_log is shared across invocations, events from different sessions will be mixed.

Please address these implementation details. Otherwise, the architecture looks sound and well-integrated with the ADK plugin system.

[github-actions]

The allowed_arg_patterns attribute is defined here but doesn't seem to be used in before_tool_callback. Was the implementation missed?

[github-actions]

Since _audit_log is shared across all invocations using this plugin instance, events from different sessions will be interleaved. If this is intended for a global audit trail, it's fine, but be aware of memory growth.

[github-actions]

Missing implementation for ToolPolicy.allowed_arg_patterns regex validation. The PR description and docstrings mention this feature, but the code doesn't enforce it here. It should probably be checked before or after the custom policy evaluator.

[github-actions]

The _audit_log list grows indefinitely as it's never cleared. This could lead to a memory leak in long-running processes. Consider adding a way to clear it or using a bounded buffer if internal logging is desired.