Example: use HOL Guard from PreToolUse for Bash command safety

[kantorcodes]

Request

Would you be open to a maintained Claude Agent SDK example showing how to invoke HOL Guard from the existing PreToolUse hook for Bash command safety?

The current hooks example already demonstrates that PreToolUse can return permissionDecision: "deny" before a tool executes. A focused HOL Guard example could replace the local pattern check with a real external command-safety engine while keeping the SDK API unchanged.

Proposed landing surface

Either a small dedicated example under examples/ or a focused addition next to the existing hooks example/README section.

The example would:

• install the actual runtime with pipx install hol-guard;
• register a PreToolUse HookMatcher for Bash;
• extract the command from the tool input and invoke hol-guard command test <command> --json before execution;
• allow an explicitly safe result exactly once;
• return permissionDecision: "deny" for unsafe/review-required results and fail closed on unavailable, timeout, malformed, or error results so the Bash action does not execute;
• include a small test/example assertion that blocked/error paths result in zero underlying Bash executions.

hol-guard command test is deliberately side-effect free: it classifies the command but does not execute it, create an approval, evaluate the final Guard policy, or record a receipt. So this example would be scoped as command-safety classification at the SDK's existing pre-tool boundary, not as a claim that Claude Agent SDK is already a full HOL Guard harness integration or that Guard Cloud approvals are wired in.

This would put HOL Guard itself in an official SDK example and give users a concrete security integration path without adding a generic guardrail API.

If this placement fits the project, I can follow up with the smallest example/docs PR and tests.