claude-code - 💡(How to fix) Fix [BUG] `type: "agent"` hooks broken on PreToolUse— "Messages are required for agent hooks" [1 comments, 2 participants]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

type: "agent" hooks on PreToolUse immediately throw "Failed to run: Messages are required for agent hooks. This is a bug." and never execute. The sub-agent is never spawned, so no review happens. The edit/write proceeds as if the hook didn't exist.

The root cause is that the PreToolUse call sites in the hook executor do not pass the messages (conversation history) parameter, which agent hooks require to spawn a sub-agent. The assertion fails and the hook is skipped.

What Should Happen?

type: "agent" hooks on PreToolUse should spawn a sub-agent that reviews the tool call and returns a JSON decision ({"ok": true} or {"ok": false, "reason": "..."}), as documented at https://code.claude.com/docs/en/hooks. The edit/write should only proceed after the agent hook completes successfully.

Error Messages/Logs

PreToolUse:Edit hook error
Failed to run: Messages are required for agent hooks. This is a bug.



PreToolUse:Write hook error
Failed to run: Messages are required for agent hooks. This is a bug.


The error fires on every `Edit` and `Write` tool call. The edit/write still goes through — the agent hook silently never executes.

Steps to Reproduce

1. Add this to any project's .claude/settings.json:

   {
     "hooks": {
       "PreToolUse": [
         {
           "matcher": "Edit|Write",
           "hooks": [
             {
               "type": "agent",
               "prompt": "Review this edit. The hook input JSON is in $ARGUMENTS.",
               "timeout": 300
             }
           ]
         }
       ]
     }
   }

2. Start a Claude Code session in that project
3. Ask Claude to edit or create any file (e.g. "add a docstring to main.py")
4. The hook fires and immediately fails with: Failed to run: Messages are required for agent hooks. This is a bug.
5. The edit proceeds anyway — the agent hook never ran

Reproduces on every Edit and Write, regardless of file type (.py, .csv, .md, etc.).

type: "agent" hooks may have never worked on PreToolUse/PostToolUse. The internal hook development skill guide (plugins/plugin-dev/skills/hook-development/SKILL.md) only documents prompt and command types, suggesting agent was added later and may not have been fully wired up.

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

No response

Claude Code Version

2.1.104

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

No response