[DOCS] Functional Contradiction: Hook support for query() function in Python Agent SDK

Documentation Type

Unclear/confusing documentation

Documentation Location

• docs/en/agent-sdk/python.md - docs/en/agent-sdk/overview.md

Section/Topic

The "Choosing Between query() and ClaudeSDKClient" comparison table within the Python Agent SDK reference.

Current Documentation

In docs/en/agent-sdk/python.md, the comparison table states:
| Feature | query() | ClaudeSDKClient |
| :--- | :--- | :--- |
| Hooks | ❌ Not supported | ✅ Supported |

However, later in the same file, the ClaudeAgentOptions dataclass (which is passed to query()) is defined as:

@dataclass
class ClaudeAgentOptions:
    # ... other fields
    hooks: dict[HookEvent, list[HookMatcher]] | None = None

Additionally, docs/en/agent-sdk/overview.md provides an explicit example of query() using hooks:

async for message in query(
    prompt="Refactor utils.py to improve readability",
    options=ClaudeAgentOptions(
        permission_mode="acceptEdits",
        hooks={
            "PostToolUse": [HookMatcher(matcher="Edit|Write", hooks=[log_file_change])]
        }
    )
):

What's Wrong or Missing?

There is a logical contradiction between the "Quick Comparison" table and the actual API capabilities.

• The table explicitly discourages users from using query() if they need hooks.
• The ClaudeAgentOptions definition and the overview.md examples prove that query() does support hooks when they are passed as part of the initial configuration.

This likely stems from a distinction between "configured hooks" (supported by both) and "dynamic/lifecycle hook management" (exclusive to the stateful ClaudeSDKClient), but the current table simplifies this to the point of being factually incorrect for the user.

Suggested Improvement

Update the comparison table in docs/en/agent-sdk/python.md to accurately reflect that query() supports hooks via the options parameter.

Suggested Table Row:
| Feature | query() | ClaudeSDKClient |
| :--- | :--- | :--- |
| Hooks | ✅ Supported (via options) | ✅ Supported |

Suggested Clarification Note (below the table):

Note: While query() supports hooks defined in ClaudeAgentOptions at the start of a session, the ClaudeSDKClient provides more granular control for complex applications requiring stateful interaction.

Impact

High - Prevents users from using a feature

Additional Context

• Related Documentation: The overview.md file (Hooks tab) correctly demonstrates the Python query() function utilizing a PostToolUse hook to log file changes.
• Impact: Developers looking for a simple "one-off" script with logging (via hooks) might incorrectly assume they are forced to implement the more verbose ClaudeSDKClient workflow because of this table.