feat(governance): add SidClaw governance service integration

[VladUZH]

Summary

Add a governance service for Google ADK agents using SidClaw — policy evaluation, human-in-the-loop approval, and tamper-proof audit trails for tool calls.

Closes #113

Background

This submission was invited by @rohityan in google/adk-python#5081:

"Hi @VladUZH, 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/"

CLA: Already signed for google/adk-python#5081.

What It Does

The SidClawGovernanceService integrates with ADK's before_tool_callback and after_tool_callback hooks:

from sidclaw import AsyncSidClaw
from google.adk_community.governance import SidClawGovernanceService

client = AsyncSidClaw(api_key="ai_...", agent_id="my-agent")
governance = SidClawGovernanceService(client=client)

agent = Agent(
    name="governed-agent",
    model="gemini-2.5-flash",
    tools=[search_docs, query_database],
    before_tool_callback=governance.before_tool_callback,
    after_tool_callback=governance.after_tool_callback,
)

Before tool execution:

• Evaluates the action against SidClaw policies
• Allow → tool proceeds (~50ms overhead)
• Deny → returns error dict, blocking execution
• Approval required → waits for human reviewer via dashboard, Slack, Teams, or Telegram

After tool execution:

• Records the outcome in SidClaw's hash-chain audit trail

Files Changed

File	Description
src/google/adk_community/governance/__init__.py	Package exports
src/google/adk_community/governance/sidclaw_governance.py	Governance service (~300 LOC)
tests/unittests/governance/__init__.py	Test package
tests/unittests/governance/test_sidclaw_governance.py	20 unit tests
pyproject.toml	Added sidclaw>=0.1.2 dependency

Configuration

Field	Default	Description
default_classification	"internal"	Default data classification for all tools
tool_classifications	{}	Per-tool overrides (e.g., {"delete_db": "restricted"})
resource_scope	"google_adk"	Resource scope for policy matching
wait_for_approval	True	Wait for human approval or reject immediately
fail_open	False	Block tools when SidClaw is unreachable (fail-closed by default)

Testing Plan

Unit Tests

All 20 unit tests pass:

pytest tests/unittests/governance/test_sidclaw_governance.py -v

Coverage includes:

• ✅ Config defaults and custom values
• ✅ Allow decision path (returns None, stores trace ID)
• ✅ Deny decision path (returns error dict)
• ✅ Approval workflow: wait + approved, wait + denied, no-wait mode
• ✅ Per-tool data classification overrides
• ✅ Fail-closed by default, fail-open when configured
• ✅ Null approval_request_id handling
• ✅ Tool with no name attribute (fallback to "unknown_tool")
• ✅ Exception during wait_for_approval
• ✅ After-tool callback: success/error outcome recording
• ✅ No trace ID → no-op in after callback
• ✅ record_outcome failure does not propagate
• ✅ Argument serialization for complex types

Manual E2E Testing

Verified with SidClaw platform (https://api.sidclaw.com):

• Tool allowed by policy → executes normally
• Tool denied by policy → returns error, blocks execution
• Tool requiring approval → waits for human decision via Slack
• Audit trail recorded with correct trace IDs and outcomes

Links

• SidClaw Documentation
• SidClaw Python SDK on PyPI (Apache 2.0)
• Google ADK Integration Guide

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[VladUZH]

@google-cla I've signed the CLA — can you re-check?

[VladUZH]

CLA check is green now. This adds a SidClaw governance middleware sample — wraps ADK tool calls with policy evaluation and human approval. Happy to adjust anything to match the repo's conventions.

[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]

Thanks for the contribution! The integration looks solid and well-tested. I've left a few comments regarding type safety and edge-case handling. Specifically:

• Consider more specific type annotations for tool_context if possible.
• Ensure robust handling of tool_context and its state to avoid potential AttributeError or KeyError.
• _safe_serialize could be made more robust for deeply nested or complex non-dict structures.

Otherwise, the implementation follows the expected patterns and the tests are comprehensive.

[github-actions]

This is a good practice to ensure AsyncSidClaw is available when the service is initialized.

[github-actions]

Is it possible for tool_context to be None here? If so, we should add a check to avoid an AttributeError. Also, the type annotation for tool_context is Any. If there is a more specific type available in ADK, it would be better to use it.

[github-actions]

Should we also log the trace ID when fail_open is triggered? It might be useful for debugging why the evaluation failed.

[github-actions]

Is it possible for tool_context.state to be missing? We should ensure that this doesn't raise a KeyError or AttributeError if tool_context is not as expected.

[github-actions]

The _safe_serialize function handles dict by stringifying non-primitive values. However, if obj is not a dict, it just returns {"raw": str(obj)}. This might be too simplistic for some complex arguments. Have you considered using something like pydantic.json.pydantic_encoder or a similar robust serializer if available? For example, if an argument is a list of complex objects.