[DOCS] [Python SDK] `system_prompt` documentation incorrectly suggests string literal for "claude_code" preset

Documentation Type

Unclear/confusing documentation

Documentation Location

docs/en/agent-sdk/migration-guide.md docs/en/agent-sdk/python.md

Section/Topic

• System prompt configuration and presets for the Python SDK.

Current Documentation

In python.md, under the SettingSource section, it states:

"The claude_code system prompt preset does NOT automatically load CLAUDE.md - you must also specify setting sources... system_prompt="claude_code" in Python."

In the ClaudeAgentOptions property table in python.md:

"Pass a string for custom prompt, or use {"type": "preset", "preset": "claude_code"} for Claude Code's system prompt."

What's Wrong or Missing?

There is a logic conflict between the documentation and the actual SDK implementation in src/claude_agent_sdk/_internal/transport/subprocess_cli.py.

The documentation suggests that system_prompt="claude_code" is a valid way to invoke the preset. However, the SubprocessCLITransport._build_command method (Line 160) prioritizes string type checking:

if self._options.system_prompt is None:
    cmd.extend(["--system-prompt", ""])
elif isinstance(self._options.system_prompt, str):
    # This block triggers for "claude_code", passing it as a literal string
    cmd.extend(["--system-prompt", self._options.system_prompt])
else: 
    # Preset logic only reached if system_prompt is a dict
    if self._options.system_prompt.get("type") == "preset"...

If a user follows the shorthand system_prompt="claude_code", the SDK executes the CLI with the flag --system-prompt "claude_code". This results in the model receiving the literal text "claude_code" as its system instruction, rather than the intended rich instructions associated with the preset.

Suggested Improvement

The documentation should be updated to remove the suggestion that the preset can be enabled via a string literal. It should explicitly state that presets require the dictionary format.

Suggested Text for python.md:
Change:

"...or use system_prompt="claude_code" in Python."

To:

"...or use system_prompt={"type": "preset", "preset": "claude_code"} in Python."

The ClaudeAgentOptions table should also be clarified to show that a string input is strictly for custom text and will not trigger presets.

Impact

High - Prevents users from using a feature

Additional Context

• See src/claude_agent_sdk/_internal/transport/subprocess_cli.py in the Python SDK source.
• Contrast this with the TypeScript implementation where the SystemPrompt type correctly distinguishes between the preset type and raw strings.

---