Claude Code

Claude Code supports lifecycle hooks that fire before and after tool executions, allowing you to intercept, inspect, and block Claude's actions. You can connect VirtueAgent Guard (Prompt Guard and Action Guard) to Claude Code as a hook to enforce guardrail protections directly on every tool call and user prompt. AgentGuard evaluates each request against your configured policies and returns a decision (allow / deny / ask) that Claude Code enforces.

Prerequisites

• Claude Code installed (v2.0.45 or later for full hook support)
• A running VirtueAgent Guard endpoint with policies configured
• An API key created from the VirtueAgent dashboard

Step 1: Create an API key

1. Navigate to the VirtueAgent dashboard
2. Create an API key with the appropriate permissions for your guardrails
3. Copy the API key to a secure place

Step 2: Copy the Guard endpoint URL

1. Navigate to the Guard tab in the VirtueAgent dashboard
2. Copy the URL of your running Guard endpoint (e.g., https://your-guard-url.virtueai.io)

Step 3: Configure Claude Code hooks

Hooks in Claude Code are defined in one of your settings files:

• ~/.claude/settings.json — user-level settings (applies to all projects)
• .claude/settings.json — project-level settings (committed to repo)
• .claude/settings.local.json — local project settings (not committed)

Add the following hook configuration to your chosen settings file:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "http",
            "url": "https://your-guard-url.virtueai.io/hook/pre-tool-use",
            "timeout": 30,
            "headers": {
              "X-API-Key": "your_virtue_api_key"
            }
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "http",
            "url": "https://your-guard-url.virtueai.io/hook/post-tool-use",
            "timeout": 30,
            "headers": {
              "X-API-Key": "your_virtue_api_key"
            }
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://your-guard-url.virtueai.io/hook/user-prompt",
            "timeout": 30,
            "headers": {
              "X-API-Key": "your_virtue_api_key"
            }
          }
        ]
      }
    ]
  }
}

Replace https://your-guard-url.virtueai.io/hook/... with your actual Guard endpoint URL from Step 2, and your_virtue_api_key with the API key from Step 1.

What each hook does

Hook event	When it fires	VirtueGuard action
PreToolUse	Before any tool call (Bash, Edit, Write, MCP tools, etc.)	Action Guard inspects tool input against policies. Can block, modify, or allow the call.
PostToolUse	After a tool completes successfully	Action Guard inspects tool output for sensitive data leaks or policy violations.
UserPromptSubmit	When the user submits a prompt	Prompt Guard scans user input for prompt injection, jailbreaks, or policy violations.

Scoping hooks to specific tools

The matcher field accepts a regex pattern. To only guard specific high-risk tools, narrow the matcher:

"PreToolUse": [
  {
    "matcher": "Bash|Write|Edit|MultiEdit",
    "hooks": [
      {
        "type": "http",
        "url": "https://your-guard-url.virtueai.io/hook/pre-tool-use",
        "headers": { "X-API-Key": "your_virtue_api_key" }
      }
    ]
  }
]

Step 4: Verify the connection

1. Restart Claude Code (or start a new session) to load the updated settings.

2. Run a test command that should be inspected by your guardrail, for example:

   > Run `ls -la` in the project directory

3. Open the VirtueAgent dashboard Monitor tab — you should see the hook request logged with the policy decision.

To debug hook execution, run Claude Code with the --debug flag:

claude --debug

You'll see each hook invocation, the JSON payload sent to the Guard, and the decision returned.

How decisions work

The VirtueAgent Guard endpoint returns a JSON response that Claude Code interprets as a permission decision. Three actions are supported, matching your dashboard configuration:

Block

The Guard returns a deny decision. Claude Code blocks the tool call and feeds the reason back to Claude, which can then explain the block to the user or try an alternative approach.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Blocked by Virtue Action Guard: command matches dangerous-bash policy"
  }
}

Send external notification (email)

The Guard returns allow and asynchronously sends an email alert to designated recipients. Claude Code proceeds with the action while your team is notified out-of-band.

Human approval (human-in-the-loop)

The Guard returns ask, which prompts the user for confirmation before the tool executes. The user sees the action and the policy that flagged it, and can approve or deny.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "ask",
    "permissionDecisionReason": "Virtue policy 'write-to-prod-config' requires human approval"
  }
}