[DOCS] CLI flag `--replay-user-messages` required for file checkpointing but not in CLI reference

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The file checkpointing guide references replay-user-messages as a required flag, but the CLI Reference page does not document this flag.

Current Documentation

The file checkpointing guide states (multiple times):

extra_args={"replay-user-messages": None}  # Required to receive checkpoint UUIDs

And in the options table:

| Receive checkpoint UUIDs | extra_args={"replay-user-messages": None} | extraArgs: { 'replay-user-messages': null } | Required to get user message UUIDs in the stream |

What's Wrong or Missing?

The --replay-user-messages flag is documented as required for file checkpointing functionality, but:

1. It does not appear in the CLI Reference (https://code.claude.com/docs/en/cli-reference)
2. Users must pass an undocumented flag through extra_args to use a documented feature
3. There's no explanation of what this flag does or why it's needed

This creates a confusing situation where users must use an undocumented internal flag to implement a documented SDK feature.

Suggested Improvement

Option A: Document the flag (minimum fix)

Add --replay-user-messages to the CLI Reference with description:

Include user messages with UUIDs in the response stream. Required for file checkpointing to identify rewind points.

Option B: Improve SDK abstraction (preferred)

Modify enable_file_checkpointing=True to automatically set replay-user-messages internally, so users don't need to pass undocumented flags:

# Current (confusing)
options = ClaudeAgentOptions(
enable_file_checkpointing=True,
extra_args={"replay-user-messages": None}  # Why is this needed?
)

# Improved (clear)
options = ClaudeAgentOptions(
enable_file_checkpointing=True  # Handles everything
)

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://platform.claude.com/docs/en/agent-sdk/file-checkpointing | 61, 102, 189, 197, 210, 221, 322, 356, 411, 461, 582, 638, 764, 766 | 13+ occurrences requiring this undocumented flag |
| https://code.claude.com/docs/en/cli-reference | N/A | Flag is NOT documented here |

Total scope: 1 page uses undocumented flag; 1 page missing documentation