anthropics / anthropics/claude-agent-sdk-python

[Feature Request] Support truncating conversation history when resuming sessions

Open
#444 2 comments 5 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
8.1k
Forks
1.3k
Avg merge
2d 31m
Merged PRs (30d)
1

Description

## 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:

```python
@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

```python
# 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.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with ClaudeAgentOptions and the existing resume and fork_session handling; inspect how session transcript JSONL messages are loaded before reaching the Claude API. Clarify whether resume_from_turn or resume_drop_turns is the supported interface, including turn indexing and max_turns interactions. Done means resuming keeps only the requested turns and has coverage for the stated examples.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
ai, backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.