[DOCS] Python SDK `UserPromptSubmit` hook example uses undocumented `updatedPrompt` field

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

"Using Hooks for Behavior Modification" section, specifically the user_prompt_modifier example function.

Current Documentation

The Python SDK example demonstrates returning updatedPrompt in the hook output:

async def user_prompt_modifier(
input_data: dict[str, Any],
tool_use_id: str | None,
context: HookContext
) -> dict[str, Any]:
"""Add context to user prompts."""
original_prompt = input_data.get('prompt', '')

# Add timestamp to all prompts
from datetime import datetime
timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")

return {
'hookSpecificOutput': {
'hookEventName': 'UserPromptSubmit',
'updatedPrompt': f"[{timestamp}] {original_prompt}"
}
}

What's Wrong or Missing?

The updatedPrompt field used in the example is not documented in the Hooks Reference. The hooks documentation for UserPromptSubmit only documents:

• decision: "block" or undefined
• reason: explanation when blocking
• additionalContext: string added to the conversation

From the Agent SDK Hooks reference (https://platform.claude.com/docs/en/agent-sdk/hooks), the hookSpecificOutput fields table lists additionalContext for UserPromptSubmit, but no updatedPrompt field.

From the Claude Code Hooks reference (https://code.claude.com/docs/en/hooks), the UserPromptSubmit Decision Control section shows the JSON structure with only decision, reason, and additionalContext fields.

If updatedPrompt is a valid field, users copying this example have no documentation explaining what it does or how it differs from additionalContext. If it's not valid, the example will silently fail to modify the prompt.

Suggested Improvement

Option A: If updatedPrompt is a valid feature

Add it to the Hook-specific output fields table in both hooks references:

| Field | Type | Hooks | Description |
|-------|------|-------|-------------|
| updatedPrompt | string | UserPromptSubmit | Replaces the user's original prompt text |

And document it in the UserPromptSubmit Decision Control section.

Option B: If updatedPrompt is not supported

Update the Python SDK example to use additionalContext instead:

return {
'hookSpecificOutput': {
'hookEventName': 'UserPromptSubmit',
'additionalContext': f"[Timestamp: {timestamp}] Original prompt follows."
}
}

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages

| Page | Line(s) | Context |
|------|---------|---------|
| https://platform.claude.com/docs/en/agent-sdk/python | 2003 | user_prompt_modifier example function |

Cross-reference

The hooks documentation that should (but doesn't) document this field:

• https://platform.claude.com/docs/en/agent-sdk/hooks (Hook-specific output fields table)
• https://code.claude.com/docs/en/hooks (UserPromptSubmit Decision Control section)