[BUG] Hooks in agent frontmatter are not executed for subagents

Resolved 💬 3 comments Opened Jan 15, 2026 by paddo Closed Jan 19, 2026

Preflight Checklist

  • [x] I have searched existing issues and this hasn't been reported yet
  • [x] This is a single bug report
  • [x] I am using the latest version of Claude Code

What's Wrong?

Hooks defined in custom agent frontmatter are not being executed when the agent runs as a subagent via the Task tool.

Steps To Reproduce

  1. Create a custom agent with a PreToolUse hook in frontmatter:
---
name: test-browser
description: Test agent
model: haiku
tools: Bash, Read
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: |
            echo "Hook fired" >> /tmp/hook-test.log
            exit 0
---
  1. Spawn the agent via Task tool
  2. Have the agent run a Bash command
  3. Check /tmp/hook-test.log - file does not exist

Expected Behavior

The hook should execute before Bash tool calls, writing to the log file.

Actual Behavior

The hook never executes. Tested with:

  • PreToolUse matcher on "Bash"
  • PreToolUse matcher on "mcp__" (to block MCP tools)
  • Various command formats (single line, multiline)

None of the hooks fire.

Environment

  • Claude Code version: 2.1.x
  • OS: macOS

Additional Context

The 2.1.0 changelog states: "Added hooks support to agent frontmatter, allowing agents to define PreToolUse, PostToolUse, and Stop hooks scoped to the agent's lifecycle"

The tools: allowlist in frontmatter is also not enforced (known issue), so hooks were the proposed workaround.

View original on GitHub ↗

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