[DOCS] Platform SDK Hooks documentation missing deprecation notice for `decision` and `reason` fields

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://platform.claude.com/docs/en/agent-sdk/hooks

Section/Topic

The "Hook-specific output fields" table and "Permission decision flow" section for PreToolUse hooks.

Current Documentation

The Platform SDK hooks documentation shows only the current field names without any migration guidance:

| `permissionDecision` | `'allow'` \| `'deny'` \| `'ask'` | PreToolUse | Controls whether the tool executes |
| `permissionDecisionReason` | `string` | PreToolUse | Explanation shown to Claude for the decision |

Code examples use only the new fields:

'permissionDecision': 'deny',
'permissionDecisionReason': 'Writing to /etc is not allowed'

What's Wrong or Missing?

The Claude Code hooks documentation (code.claude.com/docs/en/hooks) includes an explicit deprecation notice that is completely absent from the Platform SDK documentation:

From code.claude.com/docs/en/hooks (lines 928-932):

<Note>
  The `decision` and `reason` fields are deprecated for PreToolUse hooks.
  Use `hookSpecificOutput.permissionDecision` and
  `hookSpecificOutput.permissionDecisionReason` instead. The deprecated fields
  `"approve"` and `"block"` map to `"allow"` and `"deny"` respectively.
</Note>

Impact:

• Developers reading only Platform docs won't know deprecated fields exist
• Existing code using decision/reason fields has no migration path documented
• The value mapping ("approve" → "allow", "block" → "deny") is only documented in Claude Code docs
• Users migrating from older implementations may be confused when their code stops working

Suggested Improvement

Add a deprecation/migration note to the Platform SDK hooks documentation in the "Hook-specific output fields" section:

> **Migration Note:** If you're upgrading from older hook implementations:
> - `decision` → `hookSpecificOutput.permissionDecision`
> - `reason` → `hookSpecificOutput.permissionDecisionReason`
> - `"approve"` → `"allow"`
> - `"block"` → `"deny"`
>
> The deprecated fields still work but will be removed in a future version.

Impact

High - Prevents users from using a feature

Additional Context

• Claude Code docs with deprecation notice: https://code.claude.com/docs/en/hooks (lines 928-932)
• Platform docs missing notice: https://platform.claude.com/docs/en/agent-sdk/hooks
• Mirror location: platform.claude.com/docs/en/agent-sdk/hooks.md
• Related: This creates documentation drift between the two official sources