Do Claude Code hooks fire inside subagents? On my machine they fired and blocked — but one open report says otherwise

Claude Code is Anthropic's terminal coding agent: it runs shell commands and edits files on your
machine while it works. It lets you install hooks — small scripts it calls before a tool runs,
which can rewrite the command or refuse it. That is a common way to stop it from deleting things.

There is a claim that keeps circulating about that mechanism: a PreToolUse hook in your user
settings does not fire for Bash calls made inside a subagent (a child agent the main one
spawns to do a piece of the work). If that were true, every safety hook you install would have a
hole in it — you block rm -rf on the main thread, the model hands the work to a child, and the
child runs it unguarded. The threads are #34692 (closed 2026-05-30), #21460 before it (closed,
and now locked), and #88441, which is still open.

In March I added a "Can confirm" to #34692. No steps, no output, no version. Thirteen days
later I posted the opposite on #21460 — that user-level hooks do inherit to subagents,
because they load at the process level — also without measuring. Two confident comments in
opposite directions, zero runs between them.

Three people had already measured it before me:

Who	When	What they measured	Result
rwilk002	2026-04, #34692	invocation; 2.1.119 / Win 11 / Git Bash, via --settings	did not reproduce
dicksontsai (Anthropic)	2026-05-29, #21460	invocation and blocking; Write + exit 2, v2.1.22 and main	did not reproduce
bcherny (Anthropic)	2026-08-15, #86405	invocation; 2.1.233 / macOS, project-scope settings	did not reproduce

So blocking had already been measured three months before I got to it, and my March mechanism
claim was answered directly: dicksontsai noted that project-scope and user-scope settings merge
into the same startup snapshot, so there is no project-versus-user difference for subagent
inheritance. That is precisely the mechanism I had asserted on #21460 without testing it.

What is actually new below is the updatedInput rewrite path, which none of the three covered.
The rest is a fourth data point on a fourth platform.

I am not an engineer. Claude Code does the implementation and the investigation here; my job is
to direct it, and to check what comes back. This is one of the checks.

The setup

Do not use your real config for this. The safe way is --settings <file>: it swaps only the
settings and leaves your real auth alone, so no long-lived credential ever gets copied anywhere.
That is how rwilk002 ran it, and it is what I would recommend you start with.

I used the heavier CLAUDE_CONFIG_DIR route because I wanted the user-scope path specifically,
and a fresh config directory has no credentials — the run stops at Not logged in before it
measures anything. If you want to reproduce that exact path, use a private temporary directory
rather than a fixed one, and delete it afterwards:

D=$(mktemp -d) && mkdir -p "$D/cfg" "$D/proj" && chmod 700 "$D/cfg"
cp ~/.claude/.credentials.json "$D/cfg/"
# ... run the harness below, then:
# rm -rf "$D"

A fixed path like /tmp/h is a bad idea on a shared machine: if it already exists and belongs to
someone else, your chmod 700 will not save you. mktemp -d avoids that. Do not leave your
credentials sitting in /tmp when you are done.

The hook logs the fields that matter and reacts to two markers. MARKER_DENY refuses the call.
MARKER_REWRITE rewrites it. I wanted both, because "did the hook get called" and "did the hook
actually stop anything" are different questions, and the second one is what a safety hook is for.

cat > "$D/hook.py" <<EOF
import sys, json
d = json.load(sys.stdin)
cmd = (d.get("tool_input") or {}).get("command", "")
open("$D/hook.jsonl", "a").write(json.dumps(
    {"agent": d.get("agent_type") or "TOPLEVEL",
     "agent_id": d.get("agent_id"), "cmd": cmd}) + "\n")
if "MARKER_DENY" in cmd:
    print(json.dumps({"hookSpecificOutput": {
        "hookEventName": "PreToolUse", "permissionDecision": "deny",
        "permissionDecisionReason": "test guard: this command is blocked"}}))
elif "MARKER_REWRITE" in cmd:
    print(json.dumps({"hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "updatedInput": {"command": cmd.replace("MARKER_REWRITE", "REWRITTEN")}}}))
EOF

The settings file goes in the isolated config directory. The permissions block matters: claude
-p is non-interactive, so without it the run stalls on approval and fails before any hook fires,
which looks exactly like "the hook did not run".

cat > "$D/cfg/settings.json" <<EOF
{"permissions": {"allow": ["Bash", "Task"], "defaultMode": "acceptEdits"},
 "hooks": {"PreToolUse": [{"matcher": "Bash", "hooks": [
   {"type": "command", "command": "python3 $D/hook.py"}]}]}}
EOF

Then four cases in one run: the parent runs each marker itself, and the parent spawns a subagent
that runs each marker.

cd "$D/proj" && CLAUDE_CONFIG_DIR="$D/cfg" claude -p \
  "1. Run 'echo MARKER_REWRITE_TOP' with Bash yourself. \
   2. Run 'echo MARKER_DENY_TOP' with Bash yourself. \
   3. Spawn a general-purpose Task subagent that runs 'echo MARKER_REWRITE_SUB'. \
   4. Spawn one that runs 'echo MARKER_DENY_SUB'. \
   Report the exact output or error of each." \
  --output-format stream-json --verbose

Results

Where	Command	Hook fired	Outcome
Parent	MARKER_REWRITE_TOP	yes	ran as REWRITTEN_TOP
Parent	MARKER_DENY_TOP	yes	blocked
Subagent	MARKER_REWRITE_SUB	yes	ran as REWRITTEN_SUB
Subagent	MARKER_DENY_SUB	yes	blocked

Four out of four. The hook did not merely get invoked inside the subagent — deny stopped the
call and updatedInput rewrote it, exactly as on the main thread.

Measured on 2.1.233, then re-run on 2.1.246 with the same four results.

Confirming the documented subagent markers

This part is documented behaviour — the hooks reference says agent_id and agent_type are
populated when the hook fires inside a subagent — and it matched here (two lines from the
2.1.233 run, with the columns padded for alignment):

{"agent":"TOPLEVEL",        "agent_id":null,                "cmd":"echo MARKER_REWRITE_TOP"}
{"agent":"general-purpose", "agent_id":"aa23eb22fd31c7276", "cmd":"echo MARKER_REWRITE_SUB"}

agent_type (logged as agent above) and agent_id are present only for the child. The id
changes on every run, so match on presence, not value. session_id and cwd were identical to
the parent's, so those two cannot separate them. If you want a hook that behaves differently
inside subagents — a stricter rule for unattended work, say — those are the keys.

What I can and cannot say

I measured my own machine — Linux (WSL2), CLI via claude -p, a user-scope hook from an isolated
CLAUDE_CONFIG_DIR — on those two versions, with a general-purpose Task subagent. It did not
reproduce. That is the whole claim.

And one report points the other way and is still open. #84701 (2026-08-07) had a Task
subagent run find -delete and chmod -R 777 against a hard-deny hook, and verified
independently — by looking at the filesystem, not by asking the subagent — that both went
through. The same hook denied the same commands when fed to it directly. That is not an old
version, not a plugin hook, and not a different tool: it is Bash, deny, and a Task subagent,
in August. It is the one case my disclaimers below do not cover.

I posted a candidate cause there, and it matters that the reporter has not confirmed it: their
hook identified subagents by transcript_path containing /subagents/, and on 2.1.246 the
parent and subagent payloads carry an identical transcript_path, byte for byte. If that is what
happened, their detection never fired and their deny branch was never taken — indistinguishable
from an enforcement failure when seen from outside. That is a hypothesis about someone else's
code, so I am not counting it as resolved. Treat #84701 as open.

So the honest summary is not "hooks block in subagents". It is: enforcement held in my
environment and did not in theirs, and nobody has isolated the difference. What follows is one
data point on one side of a split.

Beyond that: older versions, plugin-supplied hooks, a different matcher, and other subagent
types are all different setups from this one, and I did not test them. Project-scope settings are
not on that list any more — dicksontsai reported that project and user settings merge into
the same startup snapshot, so there is no separate project-scope path to test.

Worth noting that one of the existing reports, #21460, blocks with exit code 1, while the docs
say exit code 2 is the blocking signal. I do not think that fully explains their result — they
report the parent blocking and only the child getting through — but it is the first thing I would
re-check.

What I would actually ask: do not believe this and do not dispute it. Run the harness above once
in your own environment. If it reproduces for you, the log file is the fastest way to show it,
because it records what arrived rather than what any of us believed arrived. Post it on #88441
— it is the only one of these threads still open; #34692 is closed and #21460 is locked.

The part I got wrong

Writing "Can confirm" costs nothing, and it still gets counted as evidence. "I see the same
symptom" and "the same cause is happening" are different claims, and in a public thread they pile
up as the same number.

The worse half is the one I nearly left out of this piece. Thirteen days after "Can confirm", I
posted a confident mechanism on #21460 — project hooks bind only to the agent that loads
them, user hooks inherit — in the opposite direction from what I had just agreed with, and again
without running anything. dicksontsai answered it directly two months later: both scopes merge
into the same snapshot. Being wrong twice in opposite directions is not bad luck. It is what
writing without measuring looks like from the outside.

Five months later that came back at me, because I ship a set of free safety hooks and their whole
premise is that they cover everything the model runs — which is exactly why I wanted this measured
rather than left to my own optimism. I had helped put a stone in the road and then tripped over it.

Three rules I now hold myself to:

• Only add agreement when I can write the steps.
• Never use "confirmed" for a symptom match; only when the cause matches.
• Re-measure safety assumptions when the version changes. Received wisdom has a shelf life.

I retracted the March comment on #34692 in August, with the measurement attached.

The hook collection is free and MIT: https://github.com/yurukusa/cc-safe-setup