[DOCS] Inconsistency in Python SDK callback return keys: `continue` vs `continue_` keyword conflict

Documentation Type

Unclear/confusing documentation

Documentation Location

• docs/en/agent-sdk/hooks.md - docs/en/agent-sdk/user-input.md

Section/Topic

• The "Common JSON Fields" section in the Hooks reference. - The "Handle clarifying questions" section in the User Input guide.

Current Documentation

In the Hooks Reference (Advanced JSON Output), the documentation states:

``json { "continue": true, // Whether Claude should continue after hook execution (default: true) "stopReason": "string", // Message shown when continue is false } ``

In the User Input guide (Python Example), a "workaround" snippet is provided:

``python # Required workaround: dummy hook keeps the stream open for can_use_tool async def dummy_hook(input_data, tool_use_id, context): return {"continue_": True} ``

In the Hook Types definition:

continue: boolean | Whether the agent should continue after this hook (default: true)

What's Wrong or Missing?

There is a conflict between the documented JSON wire format and the required Python dictionary keys. continue is a reserved keyword in Python. While Python allows "continue" as a string key in a dictionary literal, it is a frequent source of syntax confusion and is inconsistent with the SDK's internal mapping.

Crucially, the documentation is inconsistent: the reference sections instruct users to use "continue", but the functional "dummy hook" workaround example uses "continue_" (with an underscore). A developer following the reference section in Python will likely encounter logic errors or unexpected behavior if the SDK is specifically looking for the continue_ key to avoid keyword collisions.

Suggested Improvement

Explicitly document the Python-specific mapping for the continue key.

Suggested Text for the Hooks Reference:

Note for Python users: Because continue is a reserved keyword in Python, the Python Agent SDK uses the key continue_ (with a trailing underscore) in the dictionary returned by your callback functions. ``python # Python SDK usage return { "continue_": True, "hookSpecificOutput": { ... } } ``

Additionally, all Python snippets throughout the SDK documentation should be audited to ensure they consistently use continue_ instead of continue.

Impact

High - Prevents users from using a feature

Additional Context

• Related Documentation: The issue appears across multiple files in the platform.claude.com documentation set.
• Precedent: Many Python libraries use trailing underscores to avoid collisions with reserved keywords (e.g., class_ in BeautifulSoup or id_ in various ORMs). Standardizing this in the documentation prevents developers from having to guess between the wire-format name and the SDK-format name.