[FEATURE] Add OnCompactFailed hook for graceful failure handling

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

When auto-compact or /compact fails (e.g., "Conversation too long" error), the entire Claude Code session becomes unrecoverable. The user is forced to restore from a previous checkpoint, losing all work since that checkpoint.

This creates a critical failure mode where:

• In-progress work is lost without warning
• The user has no opportunity to save critical state before the session dies
• There's no graceful degradation or recovery path
• Users must manually remember to checkpoint frequently, interrupting flow

The current behavior treats compact failure as a catastrophic, unrecoverable error with no escape hatch.

Proposed Solution

Add an OnCompactFailed hook event that fires when compact fails, allowing users to define custom failure handling logic in their configuration.

The hook would receive:

• The error details (reason for failure, conversation size, etc.)
• Access to the current session state
• Time to execute before session termination

Example use cases:

// In .claude/config.json or equivalent
{
  "hooks": {
    "onCompactFailed": {
      "script": "./recovery-script.js",
      "actions": [
        "save-conversation-to-file",
        "notify-user",
        "trigger-emergency-checkpoint"
      ]
    }
  }
}

Users could implement:

• Auto-save critical state to files (decision logs, in-progress work)
• Alert the user via system notifications or /say command
• Trigger custom recovery logic (create emergency checkpoint, send to backup location)
• Log the failure for post-mortem analysis

Alternative Solutions

Current workaround: Manually checkpoint frequently (every N messages)

• Interrupts flow
• Requires constant vigilance
• Still loses work between last checkpoint and failure

Alternative 1: Increase compact size limits

• Doesn't solve the fundamental problem, just delays it
• May not be technically feasible

Alternative 2: Auto-checkpoint before compact

• Helps, but doesn't address the core issue of no graceful failure handling
• Doesn't give users control over recovery logic

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

Scenario:

1. User is in a 3-hour deep debugging session with director-agent orchestrating multiple subagents
2. Decision log contains critical findings about a production bug
3. Auto-compact triggers but fails due to conversation size
4. Current behavior: Session crashes, all decision logs since last checkpoint are lost
5. With OnCompactFailed hook:

• Hook detects failure
• Saves decision log to /.claude/logs/session-emergency-2026-01-02.md
• Sends notification: "Compact failed! Emergency save completed."
• User can review saved state and resume work with minimal loss

This would save hours of lost work and enable users to build more robust recovery workflows.

Additional Context

This feature would complement the existing checkpoint system by adding a safety net for the "unrecoverable failure" case. It follows the principle of "graceful degradation" - when things go wrong, give users a chance to save their work before crashing.

Related patterns from other tools:

• Git pre-commit hooks (allow custom logic before critical operations)
• Browser beforeunload event (chance to save before closing)
• Database transaction rollback hooks (custom cleanup on failure)

The hook could also enable telemetry/analytics on compact failures to help Anthropic understand and improve the compaction system.