The Claude Code PermissionRequest hook
Updated
Quick answer
PermissionRequest runs when a tool call needs a permission decision, just before Claude Code would show the prompt. The hook receives the tool name and its input, and can return allow or deny. If it returns nothing, the usual prompt appears. Deny rules in your settings still apply, so a hook cannot allow what you have forbidden.
When it fires
PermissionRequest fires only when Claude Code is about to ask you, which makes it different from PreToolUse, which runs before every tool call whether it needs approval or not. It fires at once, without the six-second wait of the Notification hook’s permission_prompt. Its matcher filters on the tool name: Bash, Edit|Write, mcp__github__.*.
- In sessions that can’t show a prompt, such as background subagents in a
claude -prun, it still runs, and a request no hook decides is denied. - When the run also has a
--permission-prompt-toolor an Agent SDK callback, both are asked and whichever decides first applies. - It doesn’t fire for a sandboxed command’s network request; only the
Notificationhook sees that one. - It only fires when there is a prompt. In auto mode that is rare, and in bypassPermissions mode almost never.
What it receives
Standard input
{
"session_id": "abc123",
"cwd": "/Users/you/dev/harbor",
"permission_mode": "default",
"hook_event_name": "PermissionRequest",
"tool_name": "Bash",
"tool_input": { "command": "rm -rf node_modules", "description": "Remove node_modules" },
"permission_suggestions": [
{
"type": "addRules",
"rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }],
"behavior": "allow",
"destination": "localSettings"
}
]
}
There is no tool_use_id. For an MCP tool, an mcp_server object comes too; inside a subagent, agent_id and agent_type. permission_suggestions holds the changes Claude Code would offer, such as an allow rule; it can be missing, and it isn’t an exact copy of the options on screen.
What it can answer
Print one JSON object and exit 0. The decision object takes:
Swipe the table sideways to see both columns.
| Field | What it does |
|---|---|
behavior | "allow" or "deny" |
message | With deny: tells Claude why. Claude reads it and adapts |
interrupt | With deny: true stops Claude |
updatedInput | With allow: replaces the tool’s input. Checked again against your deny and ask rules |
updatedPermissions | With allow: permission changes to apply, such as a suggestion echoed back with "destination": "session" to allow it for the rest of the session |
Two complete answers
{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"}}}
{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"deny","message":"Not on a Friday. Do not retry."}}}
Print nothing and the usual prompt appears. A destination other than session writes the rule to a settings file: localSettings, projectSettings or userSettings.
What it cannot do
- Override your rules. Claude Code evaluates deny and ask rules whatever the hook returns.
- Deny with exit code 2. That code isn’t honored on this event; return a decision instead. With
"onFailure": "block", a hook that fails or times out denies the request. - Answer a question with a plain allow.
AskUserQuestionalso reaches this hook, and needsupdatedInputwith ananswersobject; so doesExitPlanMode. - Take back a keyboard answer. In our tests with Claude Code 2.1.325, an interactive prompt stayed on screen while the hook waited; when we answered at the keyboard first, that answer applied and the hook’s later one was ignored. This behavior isn’t documented and may change.
A minimal script
This hook asks someone elsewhere, through a file, which is how a phone app works underneath. It waits up to 60 seconds for allow or deny in ~/.claude/remote-answer, then answers; with no answer it prints nothing and the prompt decides. The matcher keeps questions out.
~/.claude/settings.json
{
"hooks": {
"PermissionRequest": [
{
"matcher": "Bash|Edit|Write|WebFetch",
"hooks": [{ "type": "command", "command": "~/.claude/hooks/remote.sh", "timeout": 90 }]
}
]
}
}
~/.claude/hooks/remote.sh (needs jq)
#!/bin/sh
input=$(cat)
answer="$HOME/.claude/remote-answer"
rm -f "$answer"
printf '%s\n' "$input" | jq -c '{tool_name, tool_input}' >> "$HOME/.claude/remote-requests.log"
i=0
while [ "$i" -lt 60 ]; do
if [ -f "$answer" ]; then
case "$(cat "$answer")" in
allow) echo '{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"}}}' ;;
deny) echo '{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"deny","message":"Denied remotely."}}}' ;;
esac
rm -f "$answer"
exit 0
fi
sleep 1; i=$((i + 1))
done
exit 0
Try it in Manual mode: when a prompt appears, run echo allow > ~/.claude/remote-answer from another terminal, or over SSH from your phone. Note the timeout of 90 seconds, longer than the script’s own wait, so Claude Code never cancels it mid-answer.
Rules or a hook
For a decision that never changes, a rule is simpler and faster: "allow": ["Bash(npm run test *)"], "deny": ["Bash(git push --force *)"], edited by hand or through /permissions. Reach for PermissionRequest when the answer depends on something a rule can’t see, such as the time, the branch or the content of the command, or when someone who isn’t at the keyboard should decide. Monish is that second case: its hook sends the request to your iPhone with Allow and Deny, and returns your tap to Claude Code.
Questions
- Can a PermissionRequest hook allow a command my deny rules block?
- No. Claude Code evaluates deny and ask rules whatever the hook returns, and re-checks any updatedInput against them.
- What happens when the hook times out?
- Claude Code cancels it and ignores its output. In an interactive session the prompt stays for you to answer; in a session that can’t show a prompt, the request is denied.
- Does it fire for Claude’s questions?
- Yes, AskUserQuestion reaches it. To answer, allow with updatedInput that echoes the questions and adds an answers object; a plain allow isn’t enough.
- PermissionRequest or PreToolUse?
- PreToolUse runs before every tool call and suits checks and blocks. PermissionRequest runs only when a prompt is about to appear, which is what you want for answering prompts.
More guides
- Approve Claude Code permissions from your iPhoneHow a hook hands your Allow or Deny back to Claude Code.
- Claude Code permission modes, and fewer promptsManual, auto, plan and the rest, and rules that cut the prompts you don’t need.
- Claude Code hooks explained, with examplesThe events, where they live, and which ones matter for notifications.
- How safe is approving Claude Code from a phone?Who can answer, what a tap can do, and what leaves your computer.
New to Monish? The home page shows what lands on your iPhone, and all guides are listed here.
Get Monish on your iPhone
Free, no account. Your 6-digit code is waiting in the app.