[DOCS] Python Agent SDK: Invalid method call `set_permission_mode` on `query()` iterator in permissions guide

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

In the Set permission mode section, under the During streaming tab for the Python code example.

Current Documentation

The documentation provides the following Python example for changing permission modes dynamically:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    q = query(
        prompt="Help me refactor this code",
        options=ClaudeAgentOptions(
            permission_mode="default",  # Start in default mode
        ),
    )

    # Change mode dynamically mid-session
    await q.set_permission_mode("acceptEdits")

    # Process messages with the new permission mode
    async for message in q:
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

What's Wrong or Missing?

The example code provided throws an AttributeError and cannot function as written.

1. The query() function in the Python SDK returns an AsyncIterator (a generator that yields messages), not a client object.
2. The AsyncIterator type does not have a set_permission_mode() method.
3. Dynamic session controls like set_permission_mode are only available on the ClaudeSDKClient class, not on the lightweight query() helper function.

Trying to run this code results in: AttributeError: 'async_generator' object has no attribute 'set_permission_mode'.

Suggested Improvement

Update the example to use the ClaudeSDKClient class, which supports dynamic session management and methods like set_permission_mode.

Suggested corrected code:

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        permission_mode="default",  # Start in default mode
    )

    async with ClaudeSDKClient(options=options) as client:
        # Start the query
        await client.query("Help me refactor this code")

        # Change mode dynamically mid-session
        await client.set_permission_mode("acceptEdits")

        # Process messages with the new permission mode
        async for message in client.receive_response():
            if hasattr(message, "result"):
                print(message.result)

asyncio.run(main())

Impact

High - Prevents users from using a feature

Additional Context

• The ClaudeSDKClient class definition in the SDK source (client.py) confirms that set_permission_mode is a method of that class.
• The query function definition in the SDK source (query.py) confirms it returns AsyncIterator[Message].
• This mirrors the pattern used in other sections of the docs (like "Sessions"), where ClaudeSDKClient is used for stateful interactions.