anthropics / anthropics/claude-agent-sdk-python

[Feature Request] Support truncating conversation history when resuming sessions

未关闭
#444 2 条评论 5 个 reaction 已指派 0 人 在 GitHub 查看
enhancement
主要语言
Python
星标
8.1k
派生
1.3k
平均合并
2 天 31 分钟
30 天内合并 PR
1

描述

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

贡献指南

这个仓库没有索引到贡献指南

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。