Problem
ADK already has a global plugin boundary for tool execution: BasePlugin.before_tool_callback(...) receives the tool, validated arguments, and tool context before the tool runs, and returning a dictionary short-circuits tool execution. That makes it a good fit for a small, provider-specific security example without changing ADK's execution model.
I'd like to contribute an official sample showing how to use HOL Guard at that boundary for command-executing tools.
Proposed scope
Add a focused sample under contributing/samples/plugins/ that:
- installs HOL Guard separately and keeps it optional to ADK core;
- implements a
BasePlugin with before_tool_callback;
- applies only to a clearly identified shell/command tool shape, rather than pretending arbitrary structured tool calls are shell commands;
- calls HOL Guard's side-effect-free
hol-guard command test '<command>' --json inspection surface before execution;
- proceeds only when the result is explicitly benign (
classification.explicitly_benign == true) and no Guard command rule raises the minimum action;
- returns a structured blocked/tool response for review, risky, unknown, malformed, timeout, or Guard-unavailable outcomes so the command tool executes zero times;
- includes an execution-counter test demonstrating that the blocked path never invokes the wrapped command tool;
- documents that
command test is command inspection (policy_evaluation: "not_run"), not a claim that ADK is receiving HOL Guard's full final policy decision;
- keeps Guard Cloud out of the required path.
This would be an ADK example/integration only. It would not add a new generic guardrail API or special-case HOL Guard in ADK core.
Why this fits the current ADK API
BasePlugin.before_tool_callback is documented as running before a tool call and as short-circuiting the tool when it returns a dictionary. Plugins also apply globally to agents registered with a Runner, which is useful for a cross-cutting command-security control.
HOL Guard's current command-inspection contract is intentionally side-effect-free and exposes classification.explicitly_benign, minimum_action, structured rule matches, and policy_evaluation: "not_run". The sample would preserve that boundary rather than overstate it as full policy enforcement.
Contribution plan
Per CONTRIBUTING.md, I'm opening the issue first rather than sending code. If maintainers agree that an official sample is useful, I can submit the smallest sample + tests and provide the requested test plan/E2E evidence. I maintain HOL Guard / Hashgraph Online and am disclosing that affiliation. AI assistance was used to prepare this proposal.
HOL Guard: https://github.com/hashgraph-online/hol-guard
Product: https://hol.org/guard
Problem
ADK already has a global plugin boundary for tool execution:
BasePlugin.before_tool_callback(...)receives the tool, validated arguments, and tool context before the tool runs, and returning a dictionary short-circuits tool execution. That makes it a good fit for a small, provider-specific security example without changing ADK's execution model.I'd like to contribute an official sample showing how to use HOL Guard at that boundary for command-executing tools.
Proposed scope
Add a focused sample under
contributing/samples/plugins/that:BasePluginwithbefore_tool_callback;hol-guard command test '<command>' --jsoninspection surface before execution;classification.explicitly_benign == true) and no Guard command rule raises the minimum action;command testis command inspection (policy_evaluation: "not_run"), not a claim that ADK is receiving HOL Guard's full final policy decision;This would be an ADK example/integration only. It would not add a new generic guardrail API or special-case HOL Guard in ADK core.
Why this fits the current ADK API
BasePlugin.before_tool_callbackis documented as running before a tool call and as short-circuiting the tool when it returns a dictionary. Plugins also apply globally to agents registered with a Runner, which is useful for a cross-cutting command-security control.HOL Guard's current command-inspection contract is intentionally side-effect-free and exposes
classification.explicitly_benign,minimum_action, structured rule matches, andpolicy_evaluation: "not_run". The sample would preserve that boundary rather than overstate it as full policy enforcement.Contribution plan
Per
CONTRIBUTING.md, I'm opening the issue first rather than sending code. If maintainers agree that an official sample is useful, I can submit the smallest sample + tests and provide the requested test plan/E2E evidence. I maintain HOL Guard / Hashgraph Online and am disclosing that affiliation. AI assistance was used to prepare this proposal.HOL Guard: https://github.com/hashgraph-online/hol-guard
Product: https://hol.org/guard