claude-code - 💡(How to fix) Fix Emit compact_started event in stream-json output before compaction begins [1 comments, 2 participants]

Problem

When using --output-format stream-json to consume Claude CLI output programmatically (e.g. in a gateway/orchestrator), there is no way to know that context compaction has started. The CLI goes silent for potentially 3+ minutes during compaction, then emits a compact_boundary system event after completion.

This makes it impossible to show real-time progress UI to end users — they see a frozen interface with no explanation.

Current behavior

1. User sends a message
2. CLI detects context limit and begins compaction
3. No output for ~1-3 minutes (silent)
4. compact_boundary event emitted with compactMetadata (preTokens, postTokens, durationMs)
5. Compacted summary appears as a user message

Requested behavior

Emit a compact_started system event in the stream-json output before compaction begins:

{
  "type": "system",
  "subtype": "compact_started",
  "timestamp": "2026-04-15T19:00:00.000Z",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 967872
  }
}

This would allow SDK consumers and gateway applications to:

• Show a "Compacting context, please wait..." indicator immediately
• Display the pre-compaction token count
• Pair it with the existing compact_boundary event to show duration

Context

We run a multi-agent orchestration gateway that spawns Claude CLI processes with --output-format stream-json and streams events to a web UI via WebSocket. When compaction happens, users currently see a frozen chat with no feedback. The existing PreCompact hook doesn't help because hooks execute in the shell environment, not in the stdout JSON stream that SDK consumers read.

Related issues

• #43946 (PreCompact hook event) — similar goal but hooks-based, not stream-json
• #25689 (Context usage threshold hook)
• #46431 (Background compaction)