[DOCS] Conflicting information regarding "Plan" mode support in Agent SDK

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

The "Permission modes" section in the general permissions guide and the Type definitions in the language-specific SDK references.

Current Documentation

In permissions.md:

<Note> plan mode is not currently supported in the SDK. </Note>

In python.md:

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

In typescript.md:

type PermissionMode = | 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan'

What's Wrong or Missing?

There is a direct contradiction between the SDK conceptual guides and the API reference files.

• The Permissions guide explicitly tells developers that plan mode cannot be used in the SDK.
• However, the Python and TypeScript reference files both list plan as a valid member of the PermissionMode type/literal.

This creates confusion for developers attempting to implement a read-only "planning" phase using the SDK.

Suggested Improvement

• If Plan mode is now supported in the SDK: Remove the <Note> in permissions.md stating it is not supported. Additionally, provide a brief example in the SDK documentation on how plan mode behaves (e.g., does it only return a plan string in the result message?).
• If Plan mode is truly not supported: Remove "plan" from the PermissionMode type definitions in both python.md and typescript.md to prevent developers from attempting to use an unimplemented feature that the type checker says is valid.

Impact

High - Prevents users from using a feature

Additional Context

The Changelog for version 2.0.28 mentions:

"Plan mode: introduced new Plan subagent"

And 2.0.51 mentions:

"Plan Mode now builds more precise plans and executes more thoroughly"

These entries suggest active development on the feature. If these improvements were intended to reach the Agent SDK libraries, permissions.md simply needs an update to reflect the new capability.