Agent-based hooks

Agent hooks are experimental. Behavior and configuration may change in future releases. For production workflows, prefer command hooks.

When verification requires inspecting files or running commands, use type: "agent" hooks. Unlike prompt hooks, which make a single LLM call, agent hooks spawn a subagent that can read files, search code, and use other tools to verify conditions before returning a decision.

Agent hooks use the "ok" / "reason" response format with a longer default timeout of 60 seconds and up to 50 tool-use turns. They don't support the prompt-hook impossible field. On ok: false, Claude Code handles an agent hook the way it handles a prompt hook with continueOnBlock: true on the same event, so on PreToolUse and PostToolUse the turn continues; agent hooks have no continueOnBlock field. See agent hook configuration for the fields, including the $ARGUMENTS placeholder that Claude Code replaces with the hook's JSON input.

This example verifies that tests pass before allowing Claude to stop:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Use prompt hooks when the hook input data alone is enough to make a decision. Use agent hooks when you need to verify something against the actual state of the codebase.

For full configuration options, see Agent-based hooks in the reference.