[Feature request] History Management hook & API for Session Turns

Feature Request: History Management API for Session Turns

Problem

Claude Code currently provides no safe way to modify session history once turns are written to JSONL transcripts. This prevents:

• Context optimization - can't compress or summarize older turns
• History curation - can't remove noise or irrelevant content
• Memory management - can't implement custom context strategies
• Session evolution - can't adapt history based on session progress

Users need programmatic access to perform CRUD operations on session history without risking corruption or breaking internal state.

Current Limitations

No Safe Modification Path:

• Modifying active JSONL transcripts risks session corruption
• No API to replace older context with compressed versions
• PreCompact hook timing is controlled by Claude Code's internal logic
• No way to provide alternate history without breaking session state

Context Management Opacity:

• Users can't determine current context usage
• No visibility into when compaction will occur
• Can't proactively manage context before limits are reached

Proposed Solution

Add a History Management API that allows safe CRUD operations on session turns through hooks.

Core API: Turn CRUD Operations

{
  "action": "modify_history",
  "operations": [
    {
      "type": "replace",
      "turns": ["uuid1", "uuid2", "uuid3"],
      "with": {
        "type": "assistant",
        "content": "Summary: Implemented authentication system, fixed database issues, added tests.",
        "uuid": "summary-uuid-123"
      }
    },
    {
      "type": "delete",
      "turns": ["uuid4"]
    },
    {
      "type": "insert",
      "after": "uuid5",
      "content": {
        "type": "user",
        "content": "Let's focus on the main issue.",
        "uuid": "insert-uuid-456"
      }
    }
  ]
}

Hook Integration

PostTurn Hook - After each turn completes:

{
  "hooks": {
    "PostTurn": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "command": "/path/to/history-manager.sh"
      }]
    }]
  }
}

TurnCount Hook - At specific turn intervals:

{
  "hooks": {
    "TurnCount": [{
      "matcher": "10,25,50",  // At turns 10, 25, 50
      "hooks": [{
        "type": "command",
        "command": "/path/to/batch-compressor.sh"
      }]
    }]
  }
}

Hook Input Format

{
  "event": "PostTurn",
  "session_id": "abc123",
  "turn_count": 15,
  "current_turn_uuid": "uuid-current",
  "recent_turns": ["uuid-13", "uuid-14", "uuid-current"],
  "total_turns": 15
}

Hook Response Format

{
  "action": "modify_history",
  "operations": [
    {
      "type": "replace",
      "turns": ["uuid-1", "uuid-2", "uuid-3"],
      "with": {
        "type": "assistant",
        "content": "Summary of initial setup and configuration.",
        "uuid": "summary-1-3"
      }
    }
  ]
}

Benefits

1. Safe History Modification: No risk of corrupting active sessions or internal state
2. Flexible Context Management: Create, update, delete turns programmatically
3. Custom Memory Strategies: Implement compression, filtering, or reorganization
4. Performance Control: Proactive context management before limits are reached
5. Session Continuity: Modify history while maintaining logical flow

Primary Use Case: Turn Compression

Problem: Long sessions consume context windows, causing expensive reprocessing or session termination.

Solution: Use PostTurn and TurnCount hooks to progressively compress older turns:

#!/bin/bash
# history-compressor.sh - Called every 10 turns

# Compress turns 1-5 into summary if we're at turn 10
if [[ $TURN_COUNT -eq 10 ]]; then
  echo '{
    "action": "modify_history",
    "operations": [{
      "type": "replace",
      "turns": ["'$TURN_1'", "'$TURN_2'", "'$TURN_3'", "'$TURN_4'", "'$TURN_5'"],
      "with": {
        "type": "assistant",
        "content": "Summary: Initial project setup, dependency installation, basic configuration completed.",
        "uuid": "summary-1-5"
      }
    }]
  }'
fi

Result: 10x longer sessions by compressing older context while preserving recent turns.

Additional Use Cases

Once the core CRUD API exists, it enables broader history management scenarios:

Advanced Compression:

• Multi-level compression (summary → super-summary)
• Context-aware compression based on session progress
• Integration with external summarization services

History Curation:

• Remove debugging noise and failed attempts
• Filter out irrelevant tangents
• Reorganize conversation flow for clarity

External Memory Integration:

• Replace old turns with references to vector database
• Inject context from knowledge bases
• Cross-session context sharing

Privacy & Compliance:

• Scrub sensitive information from history
• Implement retention policies
• Create audit-compliant conversation logs

CLI API

Direct command-line access for manual or scripted history management:

# Replace turns with summary
claude history replace --session abc123 --turns uuid1,uuid2,uuid3 --with "Summary: Setup completed"

# Delete specific turns
claude history delete --session abc123 --turns uuid4,uuid5

# Insert new turn
claude history insert --session abc123 --after uuid6 --content "Let's focus on the main issue"

# Query turn information
claude history list --session abc123 --recent 10
claude history show --session abc123 --turn uuid7

Backward Compatibility

This would be a purely additive feature:

• Existing sessions continue unchanged
• History modification is opt-in via hooks
• No changes to default Claude Code behavior
• JSONL format remains unchanged for compatibility