[DOCS] Inconsistency between Python SDK `PermissionMode` type definitions and documentation

Documentation Type

Missing documentation (feature not documented)

Documentation Location

• https://platform.claude.com/docs/en/agent-sdk/python#permissionmode - https://platform.claude.com/docs/en/agent-sdk/permissions

Section/Topic

The PermissionMode type definition in the Python SDK reference and the "Available modes" comparison table in the general permissions guide.

Current Documentation

The documentation at https://platform.claude.com/docs/en/agent-sdk/permissions lists the following "Available modes":

• default
• acceptEdits
• dontAsk
• bypassPermissions

It also includes a Note stating:

"plan mode is not currently supported in the SDK."

However, the Python SDK reference at https://platform.claude.com/docs/en/agent-sdk/python#permissionmode lists:

PermissionMode = Literal[
    "default",           # Standard permission behavior
    "acceptEdits",       # Auto-accept file edits
    "plan",              # Planning mode - no execution
    "bypassPermissions"  # Bypass all permission checks (use with caution)
]

What's Wrong or Missing?

There is a significant mismatch between the documented feature set and the actual Python source code implementation in src/claude_agent_sdk/types.py:

1. Missing dontAsk mode: The documentation highlights dontAsk as a primary mode (useful for CI/CD environments), but this value is missing from the PermissionMode Literal in the Python SDK source.
2. Unsupported plan mode: The documentation explicitly states that plan mode is not supported, yet it remains present in the Python type hints and source code.
3. Impact: Developers attempting to use dontAsk in Python will encounter type-checking errors (mypy/pyright), while the presence of plan in the IDE autocomplete suggests a feature exists that the documentation claims is unimplemented.

Suggested Improvement

The Python SDK source code types should be synchronized with the intended feature set described in the documentation.

Update src/claude_agent_sdk/types.py as follows:

PermissionMode = Literal[
    "default",
    "acceptEdits",
    "dontAsk",
    "bypassPermissions"
]

If plan is truly unsupported, it should be removed from the Literal to prevent developer confusion. If it is supported, the "Note" in the permissions guide should be removed.

Impact

High - Prevents users from using a feature

Additional Context

Source Code Evidence:
In the current Python SDK src/claude_agent_sdk/types.py:

# Permission modes
PermissionMode = Literal["default", "acceptEdits", "plan", "bypassPermissions"]

Documentation Evidence:
From https://platform.claude.com/docs/en/agent-sdk/permissions:
| Mode | Description |
| :--- | :--- |
| dontAsk | Skip approval prompts |
| ... | ... |

Note: plan mode is not currently supported in the SDK.