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__.*.

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.

FieldWhat it does
behavior"allow" or "deny"
messageWith deny: tells Claude why. Claude reads it and adapts
interruptWith deny: true stops Claude
updatedInputWith allow: replaces the tool’s input. Checked again against your deny and ask rules
updatedPermissionsWith 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

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

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.

Download on the App Store