[DOCS] Contradiction in Python SDK `system_prompt` preset documentation

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://platform.claude.com/docs/en/agent-sdk/modifying-system-prompts

Section/Topic

The "Understanding system prompts" section, specifically the Note regarding default behavior and Python implementation.

Current Documentation

The "Understanding system prompts" note currently says:

"Default behavior: The Agent SDK uses a minimal system prompt by default... To include the full Claude Code system prompt, specify systemPrompt: { preset: "claude_code" } in TypeScript or system_prompt="claude_code" in Python."

What's Wrong or Missing?

There is a contradiction between this guide and the actual Python SDK implementation. The guide claims a developer can pass the string "claude_code" to the system_prompt option in Python.

However, the SDK source code (specifically in subprocess_cli.py) treats all strings passed to system_prompt as verbatim custom prompts:

elif isinstance(self._options.system_prompt, str): 
    cmd.extend(["--system-prompt", self._options.system_prompt])

Passing the string "claude_code" results in the CLI being called with --system-prompt "claude_code", which makes the model receive the literal text "claude_code" as its instructions rather than triggering the preset. The SDK actually requires the dictionary structure {"type": "preset", "preset": "claude_code"} to correctly trigger the preset logic for the CLI.

Suggested Improvement

Update the text to state that the dictionary/TypedDict form is required for presets in the Python SDK to match the TypeScript implementation.

Suggested Text:

"Default behavior: The Agent SDK uses a minimal system prompt by default... To include the full Claude Code system prompt, specify systemPrompt: { preset: "claude_code" } in TypeScript or system_prompt={"type": "preset", "preset": "claude_code"} in Python."

Impact

High - Prevents users from using a feature

Additional Context

• Related Documentation: The ClaudeAgentOptions section in the Python reference (https://platform.claude.com/docs/en/agent-sdk/python#claudeagentoptions) correctly identifies SystemPromptPreset as a TypedDict, but the guide at https://platform.claude.com/docs/en/agent-sdk/modifying-system-prompts provides the incorrect string-based example.
• Impact: Developers following the guide will inadvertently strip all useful instructions from their agent and replace them with the words "claude_code", leading to poor agent performance and confusion.