Guard Hooks

Preview — Guard Hooks are available for Claude Code, Gemini CLI, and Codex CLI. The hook protocol and setup CLI may change during the preview period.

Guard Hooks integrate VeriSwarm's PII protection and activity logging into AI coding agents. Hooks log every tool call and scan MCP tool arguments for personal data before it reaches external services.

Plan requirement: PII scanning on MCP tools requires the Max plan. Activity logging works on all plans.

What Hooks Do

Hook Event	Trigger	Action
`SessionStart`	Agent session begins	Logs session metadata to VeriSwarm (Python, once per session)
`PreToolUse` (all tools)	Agent calls any tool	Logs tool name and input size to local buffer (shell, ~25ms)
`PreToolUse` (MCP only)	Agent calls an MCP tool	Tokenizes PII in MCP tool arguments (Python, ~200ms)
`PostToolUse` (all tools)	Any tool returns	Logs tool name and output size to local buffer (shell, ~25ms)
`PostToolUse` (MCP only)	MCP tool returns	Flags PII in MCP tool responses with a context warning (Python, ~200ms)

Two-path architecture

Hooks use two separate scripts to balance coverage and performance:

Fast path (activity_logger.sh): Shell script that appends a JSONL line for every tool call. Sub-25ms with jq. Logs tool name and byte sizes only — never content.
Slow path (guard_hook.py): Python script that calls the VeriSwarm PII API. Only fires on MCP tool calls (tools prefixed with mcp__), which are rare.

User prompts are not scanned. Code contains capitalized identifiers that PII detection models misclassify as person names, producing false positives.

Installation

Automated setup

pip install veriswarm-mcp
veriswarm-setup --platform claude --api-key YOUR_API_KEY

The setup CLI installs:

VeriSwarm MCP Server — 65+ tools for trust scoring, Guard, Passport, Vault
Guard Hooks — activity logging on all tools, PII scanning on MCP tools
Guard Proxy config — instructions for wrapping other MCP servers

Supported platforms

Platform	Setup flag
Claude Code	`--platform claude`
Gemini CLI	`--platform gemini`
Codex CLI	`--platform codex`

Uninstall

veriswarm-setup --platform claude --uninstall

Configuration

Hooks read credentials from ~/.veriswarm/env:

VERISWARM_API_KEY=your-platform-api-key
VERISWARM_API_URL=https://api.veriswarm.ai
GUARD_AGENT_ID=agt_your_agent_id
VERISWARM_AGENT_KEY=agta_your_agent_key

The env file is created automatically by the setup CLI with chmod 600 permissions.

PII Detection

Guard Hooks use the same PII detection engine as the Guard API:

ML-based detection for names, addresses, and locations
Pattern matching for emails, phone numbers, SSNs, credit cards, IP addresses, and credentials
Confidence thresholds tuned to minimize false positives

URLs, code identifiers, and date strings are not flagged.

Activity Reporting

Every tool call is logged to ~/.veriswarm/activity.jsonl with tool name, event type, input/output byte sizes, and timestamp. No content is ever logged.

Events are flushed to the VeriSwarm event ingestion API periodically using the agent key for authentication. The flush happens on session start and when the buffer reaches 50 entries.

For the VeriSwarm MCP server setup and full tool list, see MCP Server docs.