Agent-type PreToolUse hooks fail: 'Messages are required for agent hooks'

Resolved 💬 3 comments Opened Apr 9, 2026 by srizzo Closed Apr 9, 2026

Description

"type": "agent" hooks fail at runtime on PreToolUse events with:

Failed to run: Messages are required for agent hooks. This is a bug.

The hook loads and fires correctly, but the agent executor crashes because the conversation messages parameter is not passed from the PreToolUse code path.

Reproduction

  1. Create a hook in hooks.json or settings.json:
{
  "matcher": "Bash",
  "hooks": [{
    "type": "agent",
    "prompt": "Check if this tool call is safe: $ARGUMENTS",
    "timeout": 30
  }]
}
  1. Trigger a Bash tool call
  2. Debug log shows: Hook PreToolUse:Bash (PreToolUse) error: Failed to run: Messages are required for agent hooks. This is a bug.

Root cause

In the bundled source, the PreToolUse hook caller (d68) calls US() without a messages parameter:

yield* US({hookInput: Y, toolUseID: _, matchQuery: H, signal: $,
           timeoutMs: T, toolUseContext: K, requestPrompt: A, toolInputSummary: z})
// No 'messages' parameter ↑

But the agent hook branch in US requires it:

if (E.type === "agent") {
  if (!A) throw Error("Messages are required for agent hooks. This is a bug.");
}

The "prompt" field is accepted by the hook loader, but the runtime expects messages (conversation history) which is only available in Stop hook contexts.

Environment

  • Claude Code 2.1.97
  • macOS
  • Hook works when "type": "prompt" is used instead, and "type": "command" works fine

Expected behavior

Agent-type hooks should work on PreToolUse events, with the prompt field converted to messages internally, or with an appropriate subset of conversation context provided.

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗