feat(plugins): Add GovernancePlugin for runtime agent governance

[sunilp]

Summary

Ref #4764

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.

This directly addresses the three asks from #4764:

1. Before/after callbacks on tool execution — policy checks run before tool invocation; audit receipts emitted after
2. Sub-agent delegation governance — delegation scope constraints with monotonic narrowing
3. Structured audit events — AuditEvent schema with pluggable AuditHandler

What's included

Schemas:

• PolicyDecision — structured ALLOW/DENY with reason, evaluator, timestamp
• AuditEvent — structured audit record (action type, agent, tool, args/result hashes, policy decision, session/invocation IDs)
• ToolPolicy — per-tool config (allowed, call limits, audit toggle)
• DelegationScope — authority constraints for sub-agents (allowed tools, allowed sub-agents, max depth)

Protocols:

• PolicyEvaluator — standard integration point for custom policy engines. Two methods: evaluate_tool_call() and evaluate_agent_delegation()
• AuditHandler — pluggable audit event sink (default: LoggingAuditHandler)

Plugin behavior:

• before_tool_callback: Evaluates tool calls against blocked list → per-tool policy → call limits → delegation scope → custom PolicyEvaluator. Denied calls return error response and emit audit event.
• after_tool_callback: Emits audit receipt with args/result hashes
• on_tool_error_callback: Records tool errors in audit trail
• before_agent_callback: Enforces delegation scope via PolicyEvaluator
• before_run_callback / after_run_callback: Lifecycle tracking and counter management

Usage

from google.adk.plugins import GovernancePlugin, ToolPolicy, DelegationScope

# Simple: block specific tools
plugin = GovernancePlugin(blocked_tools={"dangerous_tool"})

# Advanced: custom policy engine + delegation scopes
plugin = GovernancePlugin(
    policy_evaluator=my_evaluator,
    tool_policies={
        "sql_tool": ToolPolicy(max_calls_per_invocation=5),
        "internal_api": ToolPolicy(allowed=False),
    },
    delegation_scopes={
        "sub_agent": DelegationScope(allowed_tools={"safe_read"}),
    },
)

runner = Runner(agent=root_agent, plugins=[plugin])

# Access audit trail
for event in plugin.audit_log:
    print(event.action, event.tool_name, event.policy_decision)

Design decisions

• Extends BasePlugin — works within the existing plugin system rather than requiring framework changes. This is pragmatic for immediate adoption while the "mandatory callback tier" discussion evolves.
• Protocol-based extensibility — PolicyEvaluator and AuditHandler are typing.Protocol interfaces, not abstract classes. Users implement what they need without inheritance.
• Hashes, not values — audit events store SHA-256 hashes of tool args/results, not the values themselves. This supports compliance auditing without leaking sensitive data.
• Layered evaluation — checks run in order (blocked list → policy → limits → scope → evaluator) with early exit on deny. Each layer is independently useful.

Test plan

Unit tests

• 25 new tests in test_governance_plugin.py covering:
  • PolicyDecision factories and timestamps
  • Plugin initialization (default and custom)
  • Blocked tools denial
  • Tool policy disabled
  • Call count limit enforcement (2 allowed, 3rd denied)
  • Custom PolicyEvaluator deny/allow
  • Delegation scope restricting/allowing tools
  • Audit receipt emission and skip-when-not-required
  • Tool error auditing
  • Agent delegation denied/allowed/unconstrained
  • Invocation lifecycle start/end
  • Counter cleanup after run
  • Audit log accumulation
  • Hash utility correctness

Checklist

• Read CONTRIBUTING.md
• Self-reviewed code
• Added tests for new functionality
• All tests pass locally (25 passed)
• Code formatted with pyink and isort

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a robust GovernancePlugin to the ADK framework, significantly enhancing the security and compliance capabilities of agents. The plugin enables runtime enforcement of policies for tool usage and agent delegation, ensuring that agents operate within defined boundaries. It also provides a structured audit trail for all governance-related decisions, offering transparency and accountability. This addition allows for greater control over agent behavior and interactions within complex systems.

Highlights

• Runtime Governance for ADK Agents: Introduced a new GovernancePlugin to provide policy-based tool filtering, delegation scope enforcement, and structured audit trails for ADK agents without altering their core logic.
• Policy-Based Tool Filtering: Implemented mechanisms to evaluate tool calls against a configurable policy engine before execution, allowing for blocking specific tools, enforcing per-tool policies (e.g., call limits), and restricting tools based on delegation scope.
• Sub-Agent Delegation Governance: Added functionality to validate sub-agent delegations against defined authority scopes, ensuring monotonic narrowing of permissions and preventing unauthorized actions.
• Structured Audit Trails: Designed and implemented a structured AuditEvent schema and a pluggable AuditHandler protocol to emit detailed audit events at every governance decision point, supporting compliance and traceability.
• Extensibility and Integration: Utilized typing.Protocol for PolicyEvaluator and AuditHandler to enable flexible, protocol-based extensibility, allowing users to implement custom policy engines and audit sinks without strict inheritance, and integrated within the existing BasePlugin system.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a robust GovernancePlugin for ADK agents, addressing key aspects of runtime governance including policy-based tool filtering, delegation scope enforcement, and structured audit trails. The design leverages existing plugin mechanisms and protocol-based extensibility, which is commendable. The inclusion of comprehensive unit tests demonstrates a thorough approach to ensuring the reliability of the new functionality. Overall, this is a well-designed and implemented feature that significantly enhances the governance capabilities of ADK agents.

[gemini-code-assist]

The AuditAction.MODEL_REQUEST enum member is defined but does not appear to be used anywhere within the governance_plugin.py file. If this action is not currently utilized, consider removing it to avoid dead code and potential confusion, or add a comment explaining its intended future use.

[gemini-code-assist]

Accessing callback_context._invocation_context.session.id directly uses a private attribute. While it works, relying on private attributes can lead to brittle code that breaks if internal implementations change. It would be more robust to expose session_id via a public property or method on CallbackContext if it's intended for external use by plugins.

Suggested change

	session_id=callback_context._invocation_context.session.id,
	)
	session_id=callback_context.invocation_context.session.id,

[gemini-code-assist]

Accessing tool_context._invocation_context.session.id directly uses a private attribute. Similar to the before_agent_callback, it's generally better to expose necessary data through public interfaces rather than relying on private attributes to maintain encapsulation and reduce coupling. Consider adding a public property for session_id to ToolContext.

Suggested change

	invocation_id=inv_id,
	session_id=tool_context._invocation_context.session.id,
	session_id=tool_context.invocation_context.session.id,

[gemini-code-assist]

The _hash_dict function truncates the SHA-256 hash to 16 characters (64 bits). While sort_keys=True ensures determinism, truncating a cryptographic hash significantly reduces its collision resistance. For "audit purposes" where the integrity and uniqueness of records are important, a 64-bit hash might be insufficient to prevent collisions, especially over a large number of events. Consider using the full SHA-256 hash (64 hex characters) or at least a longer truncation (e.g., 128 bits / 32 hex characters) to provide a stronger guarantee against accidental hash collisions, or clarify in the docstring that this truncation is acceptable for the specific collision probability tolerance of the audit system.

Suggested change

	"""Produce a stable SHA-256 hash of a dictionary for audit purposes."""
	try:
	serialized = json.dumps(d, sort_keys=True, default=str)
	return hashlib.sha256(serialized.encode()).hexdigest()[:16]
	except (TypeError, ValueError):
	return hashlib.sha256(serialized.encode()).hexdigest()

[gemini-code-assist]

Accessing tool_context._invocation_context.session.id directly uses a private attribute. It's recommended to expose session_id through a public property or method on ToolContext to avoid relying on internal implementation details.

Suggested change

	session_id=tool_context._invocation_context.session.id,
	args_hash=_hash_dict(tool_args),
	session_id=tool_context.invocation_context.session.id,

[rohityan]

Hi @sunilp , Thank you for your contribution! We appreciate you taking the time to submit this pull request.
Closing this PR here as it belongs to adk-python-community repo.
We highly recommend releasing the feature as a standalone package that we will then share through: https://google.github.io/adk-docs/integrations/