Emit compact_started event in stream-json output before compaction begins

Resolved 💬 2 comments Opened Apr 15, 2026 by gellyfish-ai Closed May 25, 2026

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)

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗