permissionRequest hook: the input payload is not documented #46334

What is missing

hooks-reference.md has a "Hook event input payloads" section that documents the stdin payload for sessionStart, sessionEnd, userPromptSubmitted, userPromptTransformed, preToolUse, postToolUse, postToolUseFailure and agentStop. permissionRequest is not among them, and it has no payload subsection anywhere else on the page.

Why it matters

permissionRequest is the only hook that can pre-approve a tool call — returning {"behavior":"allow"} short-circuits the permission service. Its decision-control section tells you to return behavior / message / interrupt, but to write a useful hook you need the tool name and the tool input, and neither field is documented. You have to discover them by writing a hook that dumps stdin to a file, which is how I obtained the payload below.

Payload actually received (CLI 1.0.98, Windows; toolName is powershell on Windows and bash on Unix):

{
  "hookName": "permissionRequest",
  "sessionId": "…",
  "timestamp": 1792065216069,
  "cwd": "C:\\src\\my-repo",
  "toolName": "powershell",
  "toolInput": { "command": "git status" },
  "permissionSuggestions": []
}

Suggested addition — a subsection alongside the other events:

permissionRequest

{
  "hookName": "permissionRequest",
  "sessionId": "...",
  "timestamp": 0,
  "cwd": "/path/to/repo",
  "toolName": "bash",
  "toolInput": { "command": "git status" },
  "permissionSuggestions": []
}

• toolName — the tool being requested (bash on Unix, powershell on Windows).
• toolInput — the arguments for that tool; for shell tools the command is toolInput.command.
• permissionSuggestions — the permission rules the CLI would otherwise offer to save.

Two behaviours worth documenting on the same page, if they are not already:

• permissionRequest does not fire for the read and hook permission kinds.
• Exit code 2 denies; any other non-zero exit is logged and falls through (fail-open), unlike preToolUse, which is fail-closed. Timeouts are fail-open for every event.

Repro to capture the payload

{
  "hooks": {
    "permissionRequest": [
      { "type": "command", "bash": "cat > /tmp/perm-payload.json" }
    ]
  }
}

Then run any shell tool and read /tmp/perm-payload.json.