# Using Agent Hooks for Complex Verification in Claude Code: A Complete Guide

> Master agent hooks in Claude Code for complex verification. Spawn sub-agents for multi-step reasoning and tool execution. Get structured JSON decisions to block or approve workflows.

- Repository: [Luong NGUYEN/claude-howto](https://github.com/luongnv89/claude-howto)
- Tags: how-to-guide
- Published: 2026-03-30

---

**Agent hooks in Claude Code spawn sandboxed sub-agents capable of multi-step reasoning and tool execution to perform complex verification tasks, returning structured JSON decisions that can block or approve workflow steps.**

Claude Code supports four distinct hook types—**command**, **http**, **prompt**, and **agent**—each designed for different automation scenarios. According to the `luongnv89/claude-howto` repository, agent hooks are uniquely powerful because they launch full-featured sub-agents with access to the complete toolset, making them ideal for implementing automated security reviews, architectural compliance gates, and end-to-end functional validation directly within your development workflow.

## How Agent Hooks Work

Agent hooks operate through a five-step lifecycle that integrates seamlessly with Claude Code's event system:

1. **Event Triggering** – Claude emits a hook event such as `PostToolUse` immediately after tools like `Write` or `Edit` complete, as documented in `[/06-hooks/README.md#L150-L156](https://github.com/luongnv89/claude-howto/blob/main/06-hooks/README.md#L150)`.

2. **Sub-agent Spawning** – When the hook configuration contains `"type": "agent"`, Claude spawns an isolated sub-agent using the provided `prompt` parameter. The configuration structure is defined in `[/06-hooks/README.md#L126-L133](https://github.com/luongnv89/claude-howto/blob/main/06-hooks/README.md#L126)`.

3. **Tool Execution** – The sub-agent operates with the same toolset available to the main session, including `Read`, `Grep`, `Bash`, and others. It can fetch files, execute linters, query repositories, and perform complex investigations as shown in `[/04-subagents/code-reviewer.md#L1-L6](https://github.com/luongnv89/claude-howto/blob/main/04-subagents/code-reviewer.md#L1)`.

4. **Structured Response** – The sub-agent must return a JSON payload containing fields such as `continue`, `stopReason`, `systemMessage`, and optional `hookSpecificOutput`. Claude interprets these fields identically to *prompt* hooks, per `[/06-hooks/README.md#L38-L46](https://github.com/luongnv89/claude-howto/blob/main/06-hooks/README.md#L38)`.

5. **Workflow Control** – Based on the returned payload, the agent can **block** the workflow using `"decision": "block"` or allow progression with `"decision": "approve"`, enabling automated quality gates at any pipeline stage `[/06-hooks/README.md#L57-L62](https://github.com/luongnv89/claude-howto/blob/main/06-hooks/README.md#L57)`.

## When to Use Agent Hooks for Complex Verification

Agent hooks excel in scenarios requiring multi-step analysis that single-command hooks cannot handle:

- **Security Reviews** – After any `Write` or `Edit` operation, a sub-agent can run static analysis, secret-scanning, and policy compliance checks before allowing the change to persist.

- **Architectural Compliance** – Verify that new modules follow naming conventions, directory structures, or design patterns by having the sub-agent read files and compare them against canonical documentation.

- **End-to-End Functional Validation** – Execute unit tests, integration tests, or API health checks. The sub-agent can invoke test runners, parse results, and block the session if any verification fails.

- **Cross-Tool Coordination** – After a `Bash` deployment command, verify service health by querying endpoints, parsing responses, and blocking if the deployment is unhealthy.

## Configuring Agent Hooks in Claude Code

Configure agent hooks in your user settings (`~/.claude/settings.json`) or project-level configuration ([`.claude/settings.json`](https://github.com/luongnv89/claude-howto/blob/main/.claude/settings.json)). Each hook requires a `matcher` to specify which events trigger it, a `type` set to `"agent"`, and a `prompt` that defines the sub-agent's behavior.

### Minimal Agent Hook for Code Review

This example fires after every `Write` or `Edit` operation, spawning a security and style reviewer:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "agent",
            "prompt": "You are a code-reviewer sub-agent. Run a thorough security and style review of the file that was just written/edited. Return a JSON decision:\n{ \"decision\": \"approve\"|\"block\", \"reason\": \"…\" }",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

```

The sub-agent leverages the **code-reviewer** definition found in [`04-subagents/code-reviewer.md`](https://github.com/luongnv89/claude-howto/blob/main/04-subagents/code-reviewer.md) to perform comprehensive analysis before returning its verdict.

### Agent Hook for Custom Deployment Verification

For post-deployment health checks, wrap existing scripts in an agent hook that interprets their output:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "agent",
            "prompt": "Run the health-check script and evaluate its JSON output. If the service is unhealthy, return {\"decision\":\"block\",\"reason\":\"Health check failed\"}. Otherwise return {\"decision\":\"approve\"}.",
            "timeout": 90
          }
        ]
      }
    ]
  }
}

```

Inside your verification script (e.g., `~/.claude/hooks/verify-deployment.sh`), emit JSON that the agent can parse. The LLM prompt then transforms that output into the final blocking or approval decision.

### Agent Hook for Full Test Suite Validation

Execute comprehensive test suites and block on any failure:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "agent",
            "prompt": "Execute `pytest -q` in the repository root. If any test fails, return {\"decision\":\"block\",\"reason\":\"Tests failed\"}. Otherwise return {\"decision\":\"approve\"}.",
            "timeout": 300
          }
        ]
      }
    ]
  }
}

```

The sub-agent invokes the `Bash` tool to run `pytest`, captures stdout and stderr, and applies reasoning to determine whether the test results warrant blocking the workflow.

## Key Architectural Considerations

When implementing **agent hooks for complex verification**, understand these critical architectural constraints:

**Isolation** – Each agent hook runs in its own isolated context. Tool usage within the sub-agent does not affect the main session's tool state, ensuring clean separation between verification logic and primary development work.

**Parallelism** – Multiple matching hooks fire in parallel across all types. However, agent hook results are awaited before the workflow proceeds, ensuring verification completes before potentially destructive operations continue.

**Timeout Configuration** – The default timeout is **60 seconds**, configurable per hook via the `timeout` field. Long-running verification tasks, such as full test suites or complex security scans, should explicitly increase this value to prevent premature termination.

**Output Format Requirements** – Sub-agents must emit valid JSON on `stdout` and exit with code **0**. A non-zero exit code (particularly **2**) signals a blocking error to Claude Code, immediately halting the workflow.

Reference the *Hook Events* table in [`06-hooks/README.md`](https://github.com/luongnv89/claude-howto/blob/main/06-hooks/README.md) (lines 146-160) for the complete list of 25 supported events, including which events support blocking behavior.

## Summary

- **Agent hooks** are the only hook type in Claude Code capable of spawning full-featured sub-agents with complete tool access.
- They execute on events like `PostToolUse` or `Stop`, enabling verification gates after specific operations.
- Sub-agents return structured JSON decisions (`approve` or `block`) that control workflow progression.
- Configuration resides in `~/.claude/settings.json` or project-level [`.claude/settings.json`](https://github.com/luongnv89/claude-howto/blob/main/.claude/settings.json) using the `"type": "agent"` specification.
- Critical implementation details include **60-second default timeouts**, strict **JSON output requirements**, and **exit code 0** for successful validation.
- Example implementations include security reviews ([`04-subagents/code-reviewer.md`](https://github.com/luongnv89/claude-howto/blob/main/04-subagents/code-reviewer.md)), deployment health checks, and automated test validation.

## Frequently Asked Questions

### What is the difference between agent hooks and command hooks in Claude Code?

**Command hooks** execute external scripts or binaries directly, receiving input via environment variables and returning decisions through exit codes. **Agent hooks** spawn a sandboxed LLM sub-agent that can use tools like `Read`, `Grep`, and `Bash` to perform multi-step investigation before returning a structured JSON decision. Agent hooks are necessary when verification requires reasoning, file analysis, or complex conditional logic that static scripts cannot handle.

### How do I prevent an agent hook from blocking the workflow indefinitely?

Set an explicit `timeout` value in your hook configuration (specified in seconds). The default is 60 seconds, but you should increase this for long-running verification tasks like full test suites. If the sub-agent exceeds the timeout, Claude Code treats it as a failure. For critical blocking operations, ensure your prompt instructions include clear completion criteria so the agent terminates promptly after reaching a decision.

### Can agent hooks access the same files and tools as the main Claude session?

Yes. According to the `luongnv89/claude-howto` source code, sub-agents run with the same toolset as the main session, including `Read`, `Grep`, `Bash`, and others. However, they operate in an **isolated context**, meaning their tool usage does not interfere with the main session's state. The sub-agent can read files, execute commands, and query the repository to perform comprehensive verification before returning its decision.

### Where can I find reference implementations for agent hook validation logic?

The repository provides two key reference files: [`06-hooks/validate-prompt.py`](https://github.com/luongnv89/claude-howto/blob/main/06-hooks/validate-prompt.py) demonstrates reading JSON from `stdin` and returning structured decisions, serving as a template for custom agent-hook logic. Additionally, [`06-hooks/auto-adapt-mode.py`](https://github.com/luongnv89/claude-howto/blob/main/06-hooks/auto-adapt-mode.py) shows complex post-tool hook implementations that modify user settings, illustrating how hooks can perform side-effects beyond simple pass/fail decisions. The [`04-subagents/code-reviewer.md`](https://github.com/luongnv89/claude-howto/blob/main/04-subagents/code-reviewer.md) file contains a complete sub-agent definition optimized for security and style review tasks.