[DOCS] Documentation incorrectly instructs users to manually set `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING` env var despite automatic handling

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

The "Implement checkpointing" section, specifically "Step 1: Set the environment variable" and the associated code examples in Python and TypeScript.

Current Documentation

The documentation explicitly instructs users to manually pass the environment variable into the options object:

Option 2: Set in SDK options Pass the environment variable through the env option when configuring the SDK:

options = ClaudeAgentOptions(
    enable_file_checkpointing=True,
    env={**os.environ, "CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING": "1"}
)

The full example in the "Implement checkpointing" section also includes this redundancy:

options = ClaudeAgentOptions(
    enable_file_checkpointing=True,
    permission_mode="acceptEdits",
    extra_args={"replay-user-messages": None},
    env={**os.environ, "CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING": "1"}
)

What's Wrong or Missing?

The documentation instructions are redundant and potentially confusing because the SDK source code automatically handles this environment variable setting internally.

In src/claude_agent_sdk/_internal/transport/subprocess_cli.py, the SubprocessCLITransport.connect method explicitly checks the enable_file_checkpointing option and sets the environment variable automatically:

# Enable file checkpointing if requested
if self._options.enable_file_checkpointing:
    process_env["CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING"] = "true"

Instructing users to manually set this variable suggests that enable_file_checkpointing=True is insufficient on its own, which contradicts the actual implementation logic.

Suggested Improvement

Remove the instruction to manually set CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING via the env dictionary when enable_file_checkpointing=True is already being used.

Revised Python Example:

options = ClaudeAgentOptions(
    enable_file_checkpointing=True,
    permission_mode="acceptEdits",
    extra_args={"replay-user-messages": None}
    # The SDK automatically handles the necessary environment variables
)

Revised TypeScript Example:

const opts = {
  enableFileCheckpointing: true,
  permissionMode: "acceptEdits" as const,
  extraArgs: { 'replay-user-messages': null }
};

"Step 1" in the documentation should be updated to clarify that setting the boolean flag in the options is sufficient for the SDK to configure the environment.

Impact

High - Prevents users from using a feature

Additional Context

• Source Code Reference: src/claude_agent_sdk/_internal/transport/subprocess_cli.py (Line ~438 in the current version)
• Logic: The internal transport layer merges the CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING key into process_env automatically if the option is true.
• Impact: While setting it twice doesn't break the code, it creates unnecessary boilerplate for the user and obscures what the high-level API options are actually doing.