Emit compact_started event in stream-json output before compaction begins
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
- User sends a message
- CLI detects context limit and begins compaction
- No output for ~1-3 minutes (silent)
compact_boundaryevent emitted withcompactMetadata(preTokens, postTokens, durationMs)- 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_boundaryevent 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)
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗