Preflight Checklist
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.
Preflight Checklist
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
Expected Behavior
The hook should execute before Bash tool calls, writing to the log file.
Actual Behavior
The hook never executes. Tested with:
None of the hooks fire.
Environment
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.