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

  1. 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`
  1. Spawn the agent with claude --agent hook-test and have it use Bash
  2. 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 >> logfile hook → log file never created
  • Testing with both regex matchers ("^(Bash|Write)$") and simple string matchers ("Bash") → neither fires
  • Testing in both dontAsk and 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 Agent tool with subagent_type matching the agent name

🤖 Generated with Claude Code

View original on GitHub ↗

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