PermissionRequest hooks: subagent prompts don't invoke the hook; when it did fire, a returned allow was ignored

Data points on your two questions, from 2.1.220 (Linux x86_64, interactive TTY), in case they help triage. My hook is a PermissionRequest command hook registered from a plugin's hooks.json with matcher: "*", and I have daemon-side logs that timestamp every dispatch.

Q1 — does PermissionRequest fire for subagent tool-call prompts?

Yes on this build, for backgrounded subagents (the default for the Agent tool since 2.1.198). The payload carries agent_id and tool_name; I have ~10 such dispatches logged today, e.g. agent_id: a3a3a4f8fd49bb54a, tool_name: Read.

Q2 — is a returned allow honored?

Yes, when the decision uses the documented hookSpecificOutput envelope. Measured on one subagent Read:

T+0.000s   PermissionRequest hook invoked   (agent_id present, tool_name Read)
T+26.000s  hook returns
           {"hookSpecificOutput":{"hookEventName":"PermissionRequest",
                                  "decision":{"behavior":"allow"}}}
T+26.080s  PostToolUse for the same agent_id + tool_name → the tool executed
           zero permission_prompt notifications at any point → no prompt was shown

So your Mode A may well have been the top-level-decision shape you already suspected — I could not reproduce it with the enveloped form. If you can re-test the envelope fix, that would settle it.

One diagnostic note that cost me some time and may be relevant to how Mode B was observed: when a hook holds a subagent's request, the hold is invisible from inside the session. No dialog appears and the tool simply takes longer and then succeeds, which reads exactly like "the call was never gated". I misread it that way myself before checking the hook-side log. So "no prompt appeared" is not by itself evidence that the hook did not fire.

Separately, I filed #82150 for an adjacent asymmetry I did reproduce: while the hook is holding, no local dialog is constructed for a backgrounded subagent (measured: zero permission_prompt for a 120s hold, then the dialog appearing 6.079s after the hook returned {}), whereas the main session constructs it in parallel and lets the first answer win.

Thanks for the detailed report. I tried to reproduce this on 2.1.233 on Linux, and also on your exact version 2.1.191, using your suggested repro: a PermissionRequest hook (matcher Read) in settings.json that logs stdin and prints {"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"}}}, plus the same hooks registered via a plugin's hooks.json, reading /etc/hostname in a default-mode session in tmux.

In all four combinations (both versions × settings.json/plugin), both modes behaved as documented: the hook fired and the prompt was skipped ("Allowed by PermissionRequest hook"), and a subagent's Read also fired the hook — with agent_id/agent_type in the payload — and the allow was honored. So I can't reproduce either mode as described.

Two things that can look exactly like what you saw:

1. The permission dialog is drawn while the hook command runs and auto-dismisses when it returns allow. If the hook script is slow or doesn't exit (e.g. a background child keeps stdout open), the prompt stays on screen even though the hook "fired".
2. If the hook's stdout doesn't match the documented schema exactly (see https://code.claude.com/docs/en/hooks), the decision is silently ignored and the real prompt shows. Also, the hook only runs when a permission request is actually generated — a subagent call that's already allowed by rules or a prior approval won't fire it.

Could you share your exact hook script, its raw stdout, and a claude --debug-file /tmp/cc-debug.txt log from a failing run (grep for PermissionRequest)? Happy to dig back in with that.

🤖 Generated with Claude Code

We weren't able to reproduce this. Could you provide steps to trigger the issue — what you ran, what happened, and what you expected? This issue will be closed automatically if there's no activity within 7 days.