[DOCS] Inconsistent JSON path for `updatedInput` between `PreToolUse` and `PermissionRequest` hook events

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://code.claude.com/docs/en/hooks#pretooluse-decision-control - https://code.claude.com/docs/en/hooks#permissionrequest-decision-control

Section/Topic

The "Advanced: JSON Output" sections for both PreToolUse and PermissionRequest hook events.

Current Documentation

Under PreToolUse Decision Control, the documentation provides the following schema:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "My reason here",
    "updatedInput": {
      "field_to_modify": "new value"
    },
    "additionalContext": "Current environment: production. Proceed with caution."
  }
}

However, under PermissionRequest Decision Control, the documentation provides this schema:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

What's Wrong or Missing?

There is a major structural inconsistency regarding where updatedInput should live within the hookSpecificOutput object.

• In PreToolUse, updatedInput is a direct child of hookSpecificOutput.
• In PermissionRequest, updatedInput is nested inside a decision object.

This inconsistency makes it difficult for developers to write reusable validation logic or middleware. It is unclear if this is a documentation error (where one schema is simply wrong) or an actual API implementation difference that requires branching logic.

Suggested Improvement

Standardize the JSON path for updatedInput across all hook events if possible. If the underlying API truly requires different structures, the documentation should explicitly highlight this "Branching Requirement" to warn developers.

Ideally, the PermissionRequest event should be updated to match the flatter structure of PreToolUse, or both should adopt a consistent nested decision object.

Impact

High - Prevents users from using a feature

Additional Context

• This issue was identified while comparing the two event types in the official hooks reference at https://code.claude.com/docs/en/hooks.
• Related documentation on PreToolUse hooks in the Agent SDK (https://platform.claude.com/docs/en/agent-sdk/hooks) also lists updatedInput as a field, but does not explicitly clarify this discrepancy for the CLI-based hook system.
• Standardizing these paths would follow the "Principal of Least Astonishment," common in other developer tools like GitHub Actions or VS Code extension APIs.