Skip to content

Add verification hook example using VeroQ Shield#799

Open
JohnnyTarrr wants to merge 1 commit intoanthropics:mainfrom
JohnnyTarrr:add-verification-hook-example
Open

Add verification hook example using VeroQ Shield#799
JohnnyTarrr wants to merge 1 commit intoanthropics:mainfrom
JohnnyTarrr:add-verification-hook-example

Conversation

@JohnnyTarrr
Copy link
Copy Markdown

Summary

Adds examples/verification_hook.py -- a self-contained example that demonstrates how to use SDK hooks for post-response fact-checking with VeroQ Shield.

Two hook patterns are shown:

  • Stop hook -- reads the session transcript when Claude finishes, extracts the last assistant message, and verifies all factual claims via veroq.verify_output. If any claim is contradicted, it injects a warning into the conversation (or optionally halts the session).
  • PostToolUse hook -- verifies non-trivial Bash tool output before Claude incorporates it into its reasoning. Scoped to Bash via HookMatcher(matcher="Bash", ...).

Both hooks follow the existing conventions in examples/hooks.py:

  • Async HookCallback signature (input_data, tool_use_id, context)
  • Return HookJSONOutput with hookSpecificOutput, reason, and systemMessage
  • Use HookMatcher with ClaudeAgentOptions.hooks
  • CLI-style runner with sys.argv dispatch

The example degrades gracefully when the veroq package is not installed -- it logs a warning and returns simulated results so the hook wiring itself can still be studied.

Why this is useful

The hooks system is powerful but the current examples focus on permission gating and context injection. This example shows a real-world pattern: calling an external verification API inside a hook to audit Claude's outputs before they reach the user. That pattern generalizes to any trust/safety/compliance layer.

Test plan

  • python examples/verification_hook.py prints usage help
  • python examples/verification_hook.py stop runs the Stop hook demo (requires claude-agent-sdk installed)
  • python examples/verification_hook.py post_tool_use runs the PostToolUse hook demo
  • python examples/verification_hook.py all runs both demos
  • With veroq not installed, the example still runs and logs a fallback warning
  • No existing tests or examples are modified

Demonstrates two hook patterns for fact-checking Claude's responses:
- Stop hook: verifies the final assistant message after the agent finishes
- PostToolUse hook: verifies Bash tool output before Claude uses it

Includes graceful fallback when veroq package is not installed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant