[Feature Request] Support truncating conversation history when resuming sessions

[pxguan]

Summary

Add support for resuming a conversation from a specific turn number, discarding earlier turns from the context. This would allow "truncated resume" - e.g., resuming from turn 6 of a 10-turn conversation, ignoring turns 1-5.

Motivation

When working with long conversations, sometimes we want to:

• Skip irrelevant early context and focus on later discussion points
• Reduce token usage by dropping earlier turns that are no longer needed
• Restart a conversation from an intermediate state
• Create "branches" from specific points in a conversation

Currently, the resume parameter only supports resuming the full conversation with all historical turns included.

Proposed Solution

Add new parameters to ClaudeAgentOptions to support truncated resumption:

@dataclass
class ClaudeAgentOptions:
    # ... existing fields ...
    
    resume: str | None = None
    resume_from_turn: int | None = None  # New: Resume from specific turn number (1-indexed)
    resume_drop_turns: int | None = None  # New: Drop first N turns when resuming

Usage Examples

# Example 1: Resume from turn 6 onwards (drops turns 1-5)
options = ClaudeAgentOptions(
    resume="session-id",
    resume_from_turn=6  # Keep turns 6-10, discard 1-5
)

# Example 2: Drop first 5 turns, keep the rest
options = ClaudeAgentOptions(
    resume="session-id",
    resume_drop_turns=5  # Alternative syntax
)

# Example 3: Combine with max_turns for new conversation
options = ClaudeAgentOptions(
    resume="session-id",
    resume_from_turn=6,
    max_turns=5  # Continue for 5 more turns after resuming
)

Use Cases

• Long conversation cleanup - Remove irrelevant early discussions
• Token optimization - Reduce context window usage by dropping old context
• Conversation branching - Create alternative paths from specific points
• Debugging - Restart from a specific turn to test different outcomes
• Multi-session workflows - Hand off conversations while dropping setup context

Alternative Approaches Considered

1. Manual context extraction - Parse transcript JSONL and reconstruct messages

   • ❌ Fragile: depends on internal file format
   • ❌ Complex: requires re-parsing and re-formatting messages
   • ❌ Error-prone: might miss important metadata

2. Using system_prompt to summarize - Summarize early turns and include as context

   • ❌ Loses actual message content
   • ❌ Still wastes tokens on summary
   • ❌ Not the same as actual truncation

Implementation Notes

This could be implemented by:

1. Loading the session transcript
2. Filtering messages to only include those after resume_from_turn
3. Reconstructing the conversation context with filtered messages
4. Passing the truncated context to the Claude API

The existing fork_session parameter creates a new session ID but doesn't truncate history - this feature would complement it by actually removing earlier turns from the context.

Related Features

• fork_session: Creates new session ID (currently exists)
• enable_file_checkpointing: Allows rewinding files (currently exists)
• resume_from_turn: Would allow rewinding conversation context (this proposal)

---

Would love to hear thoughts on this feature! Happy to provide more examples or clarification.