Add resume_session_at / resume_drops_turn for truncating resume - #1198

@claude please review this PR for correctness, edge cases, and test coverage.

Claude finished @qing-ant's task in 2m 13s —— View job

Code Review: Add resume_session_at / resume_drops_turn for truncating resume

• Gather context and read all changed files
• Review types.py changes
• Review subprocess_cli.py transport changes
• Review _internal/query.py error handling changes
• Review unit tests (test_transport.py, test_query.py)
• Review e2e test (test_truncating_resume.py)
• Run CI checks locally (tests, ruff, mypy — all pass)
• Post review findings

Overall this is a clean, well-structured PR with thorough documentation and good test coverage. The implementation correctly follows the patterns already established for resume / session_id and matches the TypeScript SDK's behavior. A few observations:

types.py — New fields on ClaudeAgentOptions

The two new dataclass fields are well-placed (after fork_session) and have excellent docstrings that explain the relationship between resume_session_at and resume_drops_turn, how to choose the fork point, and what to expect on refusal. No issues here.

subprocess_cli.py — Command building

Correct patterns used:

• Both options use the --flag=value equals form (preventing value-as-flag injection), consistent with resume and session_id.
• Windows cmd metacharacter rejection is applied to both.
• The _reject_windows_cmd_metacharacters docstring is updated to name the new options.

Deliberate asymmetry is well-reasoned: resume_session_at uses truthiness (if self._options.resume_session_at:) while resume_drops_turn uses is not None (if self._options.resume_drops_turn is not None:). The comment explains why: an empty resume_drops_turn must reach the CLI to be rejected as malformed rather than silently disarming the safety guard. This matches the TS transport's behavior and is the correct choice.

_internal/query.py — Error propagation to pending control requests

This is the subtlest change and the one that fixes a real bug. Previously, the error-handling block in _read_messages signaled pending control requests with the raw exception e before the ProcessError replacement logic ran. So initialize() — which is in flight as a pending control request during startup — received the generic "Command failed with exit code 1" even when the CLI reported a specific refusal reason like "Resume rejected by --resume-drops-turn: ...".

The fix reorders the logic:

1. Compute pending_error (either the replaced ProcessError with actionable text, or the original exception)
2. Then signal all pending control requests with pending_error

This is correct and the new test_pending_initialize_gets_result_error_text test covers the exact scenario. The pending_error variable also carries the original exit_code which is good for downstream consumers.

One observation: The pending_error assigned to pending control requests is the ProcessError with the replaced message, but error_text (used for the stream's {"type": "error"} message) is computed separately and is just the string. These two paths could in theory diverge if the logic changes later, but this is a minor concern and the current state is correct.

Test coverage

Unit tests (transport):

• test_build_command_resume_session_at_and_drops_turn — both flags emitted in equals form ✓
• test_build_command_resume_drops_turn_omitted_by_default — None → absent ✓
• test_build_command_empty_resume_drops_turn_is_forwarded — "" → --resume-drops-turn= ✓
• test_bad_truncating_resume_values_raise_on_windows — metacharacter rejection ✓

Unit tests (query):

• test_pending_initialize_gets_result_error_text — the key fix: pending initialize() gets the replaced error text with exit code preserved ✓

E2e tests:

• Matching resume_drops_turn → successful fork with turn 2 discarded, source untouched ✓
• Wrong resume_drops_turn → ProcessError containing refusal text ✓

Minor nit (non-blocking)

The _reject_windows_cmd_metacharacters docstring edit at subprocess_cli.py:450 introduces a line slightly over the project's 88-char ruff limit (109 chars). This is consistent with pre-existing violations in the same file (6 others), and E501 is not enforced, so it's fine — just noting it for completeness. If you want to fix it:

session_id / resume_session_at / resume_drops_turn values,
which applications commonly take from external input, stay
inert even if a cmd.exe hop is ever reintroduced

Verdict

Looks good — clean implementation, correct patterns, thorough tests, and the query.py fix is a real improvement for the error-reporting path. No blocking issues.