[FEATURE] Hook Exit Code for Conversation Reload from Transcript

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Currently, modifying and reloading conversation state requires exiting Claude Code and resuming with CLI flags—a lossy and inconvenient workflow. This blocks several important use cases:

1. Conversation validation and cleaning: Hooks cannot programmatically validate or clean conversation state
2. Security-based content replacement: No way to replace sensitive message content with semantic placeholders while preserving LLM context
3. Deterministic conversation compacting: Cannot compress conversations on-the-fly by replacing verbose message segments with summaries, then reloading

All of these require external process management rather than in-session handling.

Proposed Solution

Add a hook exit code that enables hooks to programmatically reload the in-memory conversation from the saved transcript. This allows deterministic conversation cleaning, security-based content replacement, and on-the-fly conversation compacting without external process management.

Minimal Approach (Hook Exit Code)

Add a new exit code (suggest exit code 4) that reloads the in-memory conversation from the current transcript file. Behavior matches --resume/--continue CLI flags. Available on all hook events except SessionEnd and SessionStart (specifically: PreToolUse, PermissionRequest, PostToolUse, UserPromptSubmit, Stop, SubagentStop, PreCompact, Notification).

Enhanced Approach (Optional CLI Commands)

Provide two CLI commands for programmatic transcript manipulation:

# Get current conversation as JSON array of message objects
claude conversation:export-messages

# Update conversation from modified JSON array, then reload
claude conversation:import-messages < modified-messages.json

Important: The transcript file contains extensive structural metadata (checksums, timestamps, session IDs, tool invocation details, etc.) not sent to the LLM. These CLI commands expose only the message content actually provided to the LLM context which is the only relevant part for modification. Benefit hooks scripts do not need to parse or manage transcript structure.

Benefits

• Deterministic conversation management: Hooks can validate, clean, and modify conversation state programmatically
• Security enforcement: Replace sensitive content with semantic placeholders that preserve LLM context
• On-the-fly compacting: Compress conversations intelligently without external process management
• No external tooling: Eliminates lossy exit/resume workflow
• Extensible: CLI commands enable custom transcript processing without parsing internals

Alternative Solutions

_No response_

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

Security-Based Content Replacement

# PostToolUse hook: Replace sensitive output with explanation
if [[ $TOOL_NAME == "Bash" ]] && grep -q "password\|token\|secret" "$TOOL_OUTPUT"; then
  # Read current messages
  claude conversation:export-messages | jq '.[] |=
    if .content | contains("password") or contains("token") then
      .content = "[REDACTED: Sensitive credential output removed for security]"
    else . end' | claude conversation:import-messages
  exit 4  # Reload conversation
fi

Conversation Compacting

# PreCompact hook: Compress verbose early messages with semantic placeholders
claude conversation:export-messages | jq '.[:5] |=
  map(.content = "[SUMMARY: Initial discussion about <topic>. Key decision: <X>. Outcome: <Y>]")' | \
  claude conversation:import-messages
exit 4  # Reload compacted conversation

Deterministic Conversation Cleaning

# PostToolUse hook: Validate and clean conversation state
# Remove formatting artifacts, normalize content, validate structure
claude conversation:export-messages | clean-and-validate.py | \
  claude conversation:import-messages
exit 4

Additional Context

_No response_