Agent-level hooks defined in .claude/agents/*.md frontmatter don't fire when run from CLI
Resolved 💬 3 comments Opened Mar 3, 2026 by Butanium Closed Apr 25, 2026
Bug Description
PreToolUse hooks defined in the YAML frontmatter of .claude/agents/*.md files are documented but never execute. The hook scripts are never invoked — confirmed by debug logging that shows no file writes from the hook.
Steps to Reproduce
- Create a minimal agent definition at
.claude/agents/hook-test.md:
---
name: hook-test
description: Minimal test agent
tools: Bash, Read
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: 'echo "HOOK FIRED $(date)" >> /tmp/agent_hook_test.log'
---
You are a test agent. Run: `echo hello`
- Spawn the agent with
claude --agent hook-testand have it useBash - Check
/tmp/agent_hook_test.log— file does not exist
Expected Behavior
Per the Sub-agents documentation ("Define hooks for subagents" section), hooks defined in agent frontmatter should fire when the subagent uses the matching tool. The docs explicitly show a PreToolUse example with matcher: "Bash".
Actual Behavior
The hook command is never invoked. Confirmed by:
- Adding file-based debug logging to the hook script → log file never created
- Using a trivial
echo >> logfilehook → log file never created - Testing with both regex matchers (
"^(Bash|Write)$") and simple string matchers ("Bash") → neither fires - Testing in both
dontAskand default permission modes → neither fires
Global hooks defined in settings.json / settings.local.json continue to work as expected. Only agent-level hooks from frontmatter are affected.
Environment
- Claude Code CLI (latest as of 2025-03-03)
- Linux
- Agent spawned via the
Agenttool withsubagent_typematching the agent name
🤖 Generated with Claude Code
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗