feat(samples): add SidClaw governance middleware sample

contributing/samples/sidclaw_governance_agent/README.md

@@ -0,0 +1,81 @@
+# SidClaw Governance Agent
+
+This sample shows how to add policy evaluation, human approval, and a
+tamper-proof audit trail to ADK tool calls using
+[SidClaw](https://sidclaw.com) — an open-source governance layer for AI agents.
+
+The sample builds a customer support agent with three tools: `send_email`,
+`get_customer_record`, and `lookup_order`. Before any tool executes, SidClaw
+evaluates it against your org's policies. Operations flagged as high-risk
+(based on `data_classification`) are held for human review in the SidClaw
+dashboard before proceeding.
+
+## Setup
+
+Install dependencies:
+
+```bash
+uv pip install sidclaw google-adk
+```
+
+Get a free API key and agent ID from [app.sidclaw.com](https://app.sidclaw.com)
+(no credit card required for the free tier — covers 5 agents).
+
+Set environment variables:
+
+```bash
+export SIDCLAW_API_KEY=your_api_key
+export SIDCLAW_AGENT_ID=customer-support-agent
+```
+
+## Running the agent
+
+```bash
+adk run contributing/samples/sidclaw_governance_agent
+```
+
+When the agent calls `send_email` or `get_customer_record`, SidClaw intercepts
+the call, evaluates the configured policy, and — if the policy marks it as
+`approval_required` — holds the action until a reviewer approves or denies it
+from the dashboard or a connected Slack/Teams channel.
+
+## What SidClaw adds
+
+- **Policy evaluation** — named policies with priority ordering evaluate every
+  tool call before execution. Allow, deny, or require human approval per
+  operation type, data classification, or resource scope.
+- **Human approval workflow** — reviewers see the agent's identity, what it
+  wants to do, the full action payload, and the agent's reasoning before
+  deciding.
+- **Hash-chain audit trail** — every evaluation, approval, and execution is
+  recorded in a cryptographically chained log. The trace is tamper-evident and
+  exportable for compliance reviews (FINRA, EU AI Act, NIST AI RMF).
+
+## Governance configuration
+
+```python
+from sidclaw.middleware.google_adk import GoogleADKGovernanceConfig
+
+config = GoogleADKGovernanceConfig(
+    data_classification={
+        "send_email": "confidential",
+        "get_customer_record": "confidential",
+    },
+    default_classification="internal",
+    resource_scope="customer_support",
+    wait_for_approval=True,
+    approval_timeout_seconds=300.0,
+)
+```
+
+`data_classification` maps tool names to sensitivity levels. Tools classified as
+`confidential` are evaluated against stricter policies by default. Override this
+in the SidClaw policy editor without changing agent code.
+
+## SDK reference
+
+- `govern_google_adk_tool(client, tool, config)` — wrap a single tool
+- `govern_google_adk_tools(client, tools, config)` — wrap a list of tools
+- `govern_google_adk_tool_async(client, tool, config)` — async variant
+
+Source: [github.com/sidclawhq/python-sdk](https://github.com/sidclawhq/python-sdk)

contributing/samples/sidclaw_governance_agent/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

contributing/samples/sidclaw_governance_agent/agent.py

@@ -0,0 +1,149 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Sample demonstrating SidClaw governance middleware with Google ADK tools.
+
+SidClaw adds a policy evaluation, human approval, and tamper-proof audit trail
+to individual tool calls before they execute. This sample shows a customer
+support agent that can send emails and access customer records. High-risk
+operations — like sending an email or accessing PII — are intercepted by
+SidClaw before execution. A human reviewer approves or denies each flagged
+action from the SidClaw dashboard (app.sidclaw.com).
+
+Requirements:
+    pip install sidclaw google-adk
+
+Environment variables:
+    SIDCLAW_API_KEY: API key from app.sidclaw.com
+    SIDCLAW_AGENT_ID: Agent ID created via `npx create-sidclaw-app` or the dashboard
+"""
+
+import os
+
+from google.adk import Agent
+from sidclaw import SidClaw
+from sidclaw.middleware.google_adk import (
+    GoogleADKGovernanceConfig,
+    govern_google_adk_tools,
+)
+
+
+# ---------------------------------------------------------------------------
+# Initialize SidClaw client
+# ---------------------------------------------------------------------------
+
+sidclaw_client = SidClaw(
+    api_key=os.environ["SIDCLAW_API_KEY"],
+    agent_id=os.environ.get("SIDCLAW_AGENT_ID", "customer-support-agent"),
+)
+
+governance_config = GoogleADKGovernanceConfig(
+    data_classification={
+        "send_email": "confidential",
+        "get_customer_record": "confidential",
+    },
+    default_classification="internal",
+    resource_scope="customer_support",
+    wait_for_approval=True,
+    approval_timeout_seconds=300.0,
+)
+
+
+# ---------------------------------------------------------------------------
+# Tool definitions
+# ---------------------------------------------------------------------------
+
+
+def send_email(to: str, subject: str, body: str) -> str:
+    """Send an email to a customer.
+
+    Args:
+        to: Recipient email address.
+        subject: Email subject line.
+        body: Plain text email body.
+
+    Returns:
+        Confirmation message with message ID.
+    """
+    # In production: integrate with your email provider (SendGrid, SES, etc.)
+    return f"Email sent to {to} — subject: '{subject}'"
+
+
+def get_customer_record(customer_id: str) -> dict:
+    """Retrieve a customer record including contact information and account status.
+
+    Args:
+        customer_id: The unique customer identifier.
+
+    Returns:
+        Dictionary with customer name, email, account status, and plan.
+    """
+    # In production: query your CRM or database
+    return {
+        "customer_id": customer_id,
+        "name": "Alex Johnson",
+        "email": "alex@example.com",
+        "status": "active",
+        "plan": "business",
+    }
+
+
+def lookup_order(order_id: str) -> dict:
+    """Look up an order by ID.
+
+    Args:
+        order_id: The order identifier.
+
+    Returns:
+        Dictionary with order details and current status.
+    """
+    # In production: query your order management system
+    return {
+        "order_id": order_id,
+        "status": "shipped",
+        "tracking": "1Z999AA10123456784",
+        "estimated_delivery": "2026-04-05",
+    }
+
+
+# ---------------------------------------------------------------------------
+# Wrap tools with SidClaw governance
+# ---------------------------------------------------------------------------
+
+raw_tools = [send_email, get_customer_record, lookup_order]
+governed_tools = govern_google_adk_tools(
+    sidclaw_client, raw_tools, governance_config
+)
+
+
+# ---------------------------------------------------------------------------
+# ADK Agent
+# ---------------------------------------------------------------------------
+
+root_agent = Agent(
+    model="gemini-2.0-flash",
+    name="customer_support_agent",
+    description="A customer support agent with SidClaw governance on all tools.",
+    instruction="""
+You are a customer support agent. Help customers with order status, account
+questions, and general inquiries.
+
+When a customer asks you to look up their order, use lookup_order.
+When a customer asks about their account, use get_customer_record.
+When you need to send a confirmation or follow-up email, use send_email.
+
+Be concise and helpful. Always confirm before sending emails.
+""",
+    tools=governed_tools,
+)

contributing/samples/sidclaw_governance_agent/requirements.txt

@@ -0,0 +1 @@
+sidclaw>=0.1.2