[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
- 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
---
- Spawn the agent via Task tool
- Have the agent run a Bash command
- 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.
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗