Feature Request: Pre-tool-call governance hook for cross-org agent deployments

[aeoess]

** Please make sure you read the contribution guide and file the issues in the right place. **
Contribution guide.

🔴 Required Information

Is your feature request related to a specific problem?

For cross-org ADK deployments (one organization's ADK agent calling another organization's tools or invoking another agent via A2A), there is no cryptographic record of who is calling, under what delegation, or within what scope. ADK's existing auth/ module handles user-to-agent authentication via OAuth2 and credential managers, which is solid for that layer. The complementary gap is agent-to-agent authorization: once an ADK agent is running on behalf of a user, what it is authorized to do when it calls out to another party is not cryptographically verifiable at the tool-call boundary.

This gap is showing up across agent runtime projects in the last few weeks:

• crewAI (#4875) 5-layer stack including execution proof via Signet bilateral co-signed receipts
• AutoGen (#7525) proposing before_tool_call hook composition with identity, authorization, and behavioral trust
• Goose (#8742) pre-tool-call governance hook proposal at the AAIF/Linux Foundation
• MS agent-governance-toolkit (ADR 0006, merged) formalizing constitutional constraint layer as community extension

Describe the Solution You'd Like

A pre-tool-call hook trait (or callback) at the point in src/google/adk/flows/llm_flows/ where tools are dispatched. The hook receives the tool name, arguments, and agent context, and returns an authorization decision (permit, deny, or modify). Default implementation is a no-op, zero behavior change for existing users. Community extensions can implement the hook with governance primitives.

Conceptual signature:

class PreToolCallHook(Protocol):
    async def check(
        self,
        tool_name: str,
        tool_args: dict,
        context: AgentContext,
    ) -> ToolCallDecision: ...

Where ToolCallDecision is permit / deny / modify, and community implementations can plug in identity verification, delegation-chain checks, scope matching, and policy evaluation. This does not overlap with the existing auth/ module. User-to-agent authentication stays with OAuth2 and credentials. Agent-to-tool authorization lives in the hook.

The natural composition with ADK's existing a2a/ experimental module: when one ADK agent calls another via A2A, the hook provides the cryptographic record that the calling agent's authority to invoke includes the requested scope. ADK's A2A experimental code ships today without that layer, and the proposed hook is where it would land.

Impact on your work

For deployments running ADK in cross-org or regulated settings (EU AI Act, GDPR, SOC 2 audit trails), this layer is the difference between "we allow cross-org tool calls" and "we allow cross-org tool calls with verifiable authorization records per call." Enterprise ADK users we talk to hit this gap before they ship.

Timeline is not urgent for us. We are shipping outside ADK today. The value of a native ADK hook is that deployments do not have to fork ADK to add it, which is where the community-extension lane in ADK's contribution guide is the right fit.

Willingness to contribute

Yes, conditional on maintainer direction. The Large or Complex Changes guidance in CONTRIBUTING.md asks for an issue first. This is that issue. Before writing any code we'd like to hear:

1. Does the direction match ADK's architectural approach, or is there an existing path we haven't found?
2. Is flows/llm_flows/ the right integration point, or would tools/ or another module be preferred?
3. Should the hook live in core with a no-op default, or is this explicitly a community-extension pattern?

Given ADK requires a Contributor License Agreement, we will sign the CLA at the point code contribution is welcomed. Happy to iterate on the hook signature in this issue before any PR is opened.

---

🟡 Recommended Information

Describe Alternatives You've Considered

1. Monkey-patching ADK in user code. Works for prototypes, does not compose when ADK updates, and the patch surface shifts across versions. Not a real path.
2. External wrapper around ADK agent. Possible but loses the fine-grained per-tool-call hook point. Agent-level wrapping means governance evaluates the agent, not the specific tool-call-plus-arguments pair, which is where the scope enforcement actually needs to happen.
3. Implementing entirely in ADK's auth/ module as an extension. Rejected because auth/ is about user-to-agent credentials, not agent-to-tool authorization. Mixing them would make the existing auth API harder to reason about.

Additional Context

Background on where we ship today: agent-passport-system (Apache-2.0, TypeScript reference implementation, byte-parity Python SDK on PyPI). The protocol covers identity, delegation with monotonic narrowing, enforcement, commerce, and coordination. Independent of this feature request, ADK deployments could call our Python SDK directly today without any changes to ADK, just without the ergonomics of a native hook.

Not filing this to push a specific implementation. Filing to start the design discussion per ADK's process for large changes. Happy to iterate or drop the idea if maintainers already have a different direction in mind.

[aeoess]

Cross-reference for the record: @tomjwxf opened #5164 on Apr 5 on a complementary-scope problem, signed receipts for ADK tool execution. The two issues sit at different points in the call path. #5164 is about proving what executed after the fact via Ed25519-signed receipts. This issue is about pre-tool-call authorization, checking whether the call is within the agent's delegation scope before execution.

Both layers have been running in production via aeoess/adk-aps-integration, a joint example repo @tomjwxf and I stood up Apr 19 that composes APS authorization with protect-mcp-adk receipt signing into a single end-to-end flow. That repo is what a deployment would look like today without native ADK hooks. The feature request here is the ADK-native hook that eliminates the need for the authorization adapter layer in user code.

If the ADK team takes up either direction, the native integration points naturally complement rather than conflict with #5164.

[srotzin]

The PreToolCallHook is exactly the right abstraction — it's the natural seam between authentication (who the agent is) and authorization (what capability tier it's operating at for this specific tool call). The delegation-chain-checks you mention in the proposed signature are where smsh stamps integrate cleanly: the hook can verify not just that the agent is authenticated but that its last inference cycle produced a credential meeting the required capability tier, giving you both identity and compute quality provenance in a single check (https://hivecompute-g2g7.onrender.com). Happy to coordinate on the Python SDK if the maintainer wants a reference implementation.

[klateefa]

@aeoess Thanks for the update. The request is currently being reviewed by our team, and I will let you know if anything further is needed. Thank you for understanding.

[adk-bot]

🚨 Automated Spam Detection Alert 🚨
@maintainers, a suspected spam comment was detected in this thread.

Reason:

@srotzin's comment promotes a 3rd-party service via the link 'https://hivecompute-g2g7.onrender.com' related to 'smsh stamps' and offers to coordinate on a reference implementation, which constitutes promotional content.

[srotzin]

The hook is the right abstraction. One addition worth considering: the ToolCallDecision should carry a capital authorization alongside permit/deny — not just “can this agent call this tool” but “how much can this call cost.” We wire this at the PreToolCallHook layer so the governance check and the payment authorization happen atomically. If the agent’s tier doesn’t cover the tool’s price, it’s denied before execution. The capital check IS the governance check.

[srotzin]

The gap aeoess is describing is exactly what HiveTrust covers at the infrastructure layer — but the hook pattern they're proposing is the right ADK-native approach. For anyone who wants a working reference before ADK ships the hook natively: POST https://hivetrust.onrender.com/v1/trust/score/:did returns a trust score, tier, and bond status in ~100ms, $0.01/lookup, no issuer-pays model. Plugs into a before_tool_call wrapper today without waiting for ADK to standardize the hook. The MATRYOSHKA shell model (7 layers of access depth, each unlocked by earned tier) is structurally what the ToolCallDecision permit/deny/modify pattern needs to enforce — Shell 1 is public, and calling depth is determined by what the agent has proven, not claimed.