[BUG] PreToolUse hook 'ask' decisions on the Read tool don't render permissionDecisionReason or systemMessage

Status Open
Reported on v2.1.218
Maintainer reply None cached
Activity 2 comments · opened Jul 23, 2026

Summary

Two PreToolUse hooks in the same project, both returning permissionDecision: "ask" with a non-empty reason field, render very differently in the interactive terminal permission dialog depending on which tool the hook matches:

  • Hook matching the Bash tool (a git-mutation guard): the dialog correctly displays permissionDecisionReason, e.g. "Rule 5 — git mutation requires explicit approval: \git commit ...\".
  • Hook matching the Read tool (a large-file gate): the dialog shows no reason text at all — just a bare confirmation — despite the hook emitting well-formed JSON with a correct, non-empty permissionDecisionReason. Adding a top-level systemMessage field to the same hook output (in case reason surfacing is field- or tool-specific) also does not render at decision time for the Read tool.

Repro

  1. Add a PreToolUse hook matched to Read that, for some condition, returns:

``json
{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "ask", "permissionDecisionReason": "some explanation"}, "systemMessage": "some explanation"}
``

  1. Verify the hook's raw stdout independently (e.g. pipe a synthetic PreToolUse payload into the hook script directly) — confirms valid JSON, correct field name, non-empty string.
  2. Trigger a Read call that the hook escalates to ask.
  3. Observe: the interactive approval dialog shows no reason/message text, just a generic Read confirmation.
  4. For comparison, add an equivalent PreToolUse hook matched to Bash returning the same shape (permissionDecision: "ask" + permissionDecisionReason). Trigger a matching Bash command. Observe: the dialog does render the reason text.

Expected

permissionDecisionReason (or systemMessage) should render in the Read-tool ask dialog the same way it does for the Bash tool, so hook authors can explain why a Read requires approval before the user decides.

Environment

  • Claude Code CLI: 2.1.218
  • Platform: Linux

Related (not duplicates)

  • #63343 — for the Bash tool, permissionDecisionReason does render, but styled small/grey below the command (a visibility complaint, not absence).
  • #77163 — systemMessage prefix/localization formatting, demonstrated for SessionStart; doesn't address the Read-tool case.

Neither describes this specific asymmetry (reason/message fields rendering for Bash-tool ask but not at all for Read-tool ask), so filing separately.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗