Feature request: add a PreCompact hook event

Resolved 💬 3 comments Opened Feb 19, 2026 by jaseemts Closed Feb 19, 2026
💡 Likely answer: A maintainer (etraut-openai, contributor) responded on this thread — see the highlighted reply below.

What feature would you like to see?

Add a dedicated PreCompact hook event that runs immediately before conversation compaction (manual or auto).

Why this matters

Today, compaction can happen automatically when token usage crosses model_auto_compact_token_limit. There are hook events for AfterAgent and AfterToolUse, but no hook for the compaction boundary itself.

For users who maintain external memory/state, this means there is no deterministic point to capture full pre-compaction context.

Proposed behavior

Add a new hook event, for example:

  • PreCompact

Triggered when compaction is about to run (both manual and auto).

Suggested payload fields:

  • session_id
  • thread_id
  • turn_id (if applicable)
  • reason (manual or auto)
  • total_usage_tokens_before_compaction
  • auto_compact_limit
  • triggered_at
  • cwd

Failure behavior

Please make failure policy explicit and configurable (same style as existing hook outcomes):

  • continue on error
  • abort compaction on error

Example use cases

  • extract important memory facts before summary compaction
  • persist custom checkpoints to external systems
  • emit telemetry about compaction quality and timing
  • run a user-defined “last chance” context snapshot

Additional context

This request is specifically for Codex hooks (not Claude-specific behavior).

If helpful, I can propose a concrete schema and tests aligned with the existing hook event design.

View original on GitHub ↗

3 Comments

etraut-openai contributor · 6 months ago

We are tracking this feature request in #2109. Please upvote that issue.

YSAA1 · 4 months ago

补一个更明确的 PreCompact 实现建议:

1) 事件触发时机:

  • 自动 compaction 前
  • 手动 compact 命令触发前

2) 事件名建议:PreCompact(或 BeforeCompact)

3) Payload 建议(最小且实用):

  • session_id
  • thread_id
  • turn_id
  • reason (auto | manual)
  • cwd
  • model
  • total_usage_tokens_before_compaction
  • auto_compact_limit
  • provider/model_family(可选)
  • estimated_cost_tokens(可选)
  • recent_rollup_summary(压缩前最近摘要)

4) 决策语义:

  • 支持 on_error: continue|abort(与现有 hook 失败策略一致)
  • 允许 hook 返回 `{
YSAA1 · 4 months ago

补充第 4 点:允许 hook 告知 compact 行为。

  • 输出 decision:{"action":"continue"} | {"action":"abort"}(建议默认 continue)。
  • 可返回 metadata/context_blob 用于在紧接着的 summary prompt 中拼接到补充上下文(可选)。
  • 建议先按 JSON schema 只读参数,未来再做 command_output 注入。

如果可采纳,我可以再补一版极简最小 PR 草案(仅文档+schema)供参考。