[DOCS] "Required workaround" for Python `can_use_tool` indicates SDK race condition or design flaw

Documentation Type

Unclear/confusing documentation

Documentation Location

URL: https://platform.claude.com/docs/en/agent-sdk/user-input

Section/Topic

Section: "Handle tool approval requests" -> Python implementation example.

Current Documentation

The Python implementation for tool approvals includes the following note and code block:

"Note: In Python, can_use_tool requires streaming mode and a PreToolUse hook that returns {"continue_": True} to keep the stream open. Without this hook, the stream closes before the permission callback can be invoked."

# 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}

What's Wrong or Missing?

The documentation presents a significant functional hurdle as a standard "required workaround." This is highly confusing for developers for several reasons:

1. Implied Race Condition: It suggests that the SDK/CLI bridge is not designed to wait for a can_use_tool response before closing the connection, which is the primary purpose of that callback.
2. Implementation Bloat: Requiring a "dummy hook" that performs no logic other than returning True adds unnecessary boilerplate to what should be a straightforward implementation.
3. Discrepancy with TypeScript: The TypeScript example does not require this workaround, creating an inconsistent developer experience between the two supported languages.
4. Placement: Presenting a major architectural limitation in the middle of a "Quickstart" or "How-to" guide without explaining the root cause or a plan for a fix makes the SDK feel unstable.

Suggested Improvement

• Immediate Term: Move this "workaround" to a dedicated "Known Issues" or "Troubleshooting" section. Label it clearly as a technical limitation of the current Python SDK bridge.
• Clarity: Explain why the Python stream behaves differently than the TypeScript one.
• Guidance: If the workaround is strictly required, provide a cleaner way to register it, perhaps via an option in ClaudeAgentOptions (e.g., keep_stream_open_for_permissions=True) rather than forcing the user to define a manual dummy function.
• Long-term: The SDK should be updated to handle stream persistence internally when a can_use_tool callback is present. Once resolved, the documentation should be updated to remove the workaround entirely.

Impact

High - Prevents users from using a feature

Additional Context

• This was found in the provided platform_claude_com_docs-part2.md file under the "Handle tool approval requests" header.
• Similar "Required workaround" logic appears again in the "Complete example" at the end of the same document.
• In multi-tenant or serverless environments, requiring an extra hook just to maintain a connection state is an anti-pattern that increases the risk of hanging sessions and ghost costs.