anthropics / anthropics/claude-code

[BUG] Subagent frontmatter hooks: PreToolUse never fires on 2.1.258 (same hook in settings.json fires for the subagent)

Open
#95,650 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area:agents area:hooks bug has repro platform:windows
Dominant language
TypeScript
Stars
147k
Forks
24k
PR merge metrics
PR metrics pending

Description

Summary

A hooks: block in a custom agent's frontmatter (documented under "Lifecycle Hooks" on the sub-agents page) never fires on Claude Code 2.1.258 (Windows 11, Git Bash present). The identical hook placed in the project's .claude/settings.json fires for the same subagent's tool calls and denies as expected.

Repro

.claude/agents/probe-hook.md:

---
name: probe-hook
description: probe
disallowedTools: Write, Edit, Bash
hooks:
  PreToolUse:
    - matcher: "mcp__.*__get_top_folders"
      hooks:
        - type: command
          command: 'python C:/tmp/deny.py frontmatter'
---
Call get_user_info_whoami, then get_top_folders, and report ok/denied for each.

deny.py writes its stdin to a file and exits 2 with a message on stderr.

  1. claude -p "Launch the probe-hook subagent and relay its report" (any MCP server with those two tools; I used a local stdio server).
  2. Result: both calls succeed; no file written by the frontmatter hook; the agent's report contains no denial.
  3. Move the same hook into .claude/settings.json (PreToolUse, same matcher/command): the call is denied, stderr reaches the model, and the recorded stdin contains agent_type: "probe-hook", agent_id, tool_name, cwd, permission_mode.

Expected

Per the docs, frontmatter hooks are "scoped to this subagent's lifecycle" and should fire on the subagent's PreToolUse events.

Notes

  • Exec form vs shell form does not matter here; neither fires from frontmatter.
  • The settings-level hook works and carries agent_type, so scoping a plugin hook by agent is possible as a workaround, but it is session-wide.
  • Environment: Claude Code 2.1.258, Windows 11 Enterprise 10.0.26200, hooks run under Git Bash 5.3.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the issue with .claude/agents/probe-hook.md and the claude -p command, then compare it with the identical hook in .claude/settings.json. Use deny.py and the recorded stdin to verify whether the frontmatter hook reaches the subagent's PreToolUse event. Done means the frontmatter hook fires for get_top_folders and denies it with the expected stderr and input.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, typescript
Domain
cli, devtools
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.