codex - 💡(How to fix) Fix Proposal: Expose a Plugin Extension Point for Custom Compaction

Summary

While looking into Codex's compaction flow, I noticed that Codex already has internal support for replacing model-visible history during compaction.

From my understanding, ContextManager owns the ordered conversation history and exposes prompt-facing history through for_prompt(). The existing compact flow can also build a replacement_history and apply it through Codex's internal compact replacement path.

However, this capability currently appears to be internal to Codex's built-in compaction flow. Plugins and hooks can observe lifecycle events and add additional model-visible context, but they cannot provide their own compacted replacement.

I think exposing a small, constrained extension point here could make Codex's plugin system more powerful and unlock interesting community experimentation around compaction behavior.

Motivation

Codex already has a plugin and hook system that allows external code to extend parts of the agent lifecycle. This is useful for adding context, enforcing policies, reacting to tool usage, and integrating project-specific workflows.

Compaction seems like another place where extensibility could be valuable.

Different users, projects, and organizations may want different compaction behavior. Some may want compact summaries optimized for debugging continuity. Others may want summaries that preserve architectural decisions, active TODOs, file-level changes, test results, or project-specific constraints. Some plugins may want to experiment with cheaper local models, rule-based summarizers, domain-specific compactors, or other strategies that Codex itself does not need to own directly.

Today, a plugin can append additional context, but it cannot participate in the actual replacement of model-visible history during compaction. That limits what plugin authors can do. A plugin can say "please also consider this summary", but it cannot provide a real compacted replacement through the same mechanism Codex already uses internally.

If Codex exposed a safe plugin extension point for custom compaction, the core system could keep control over validation and history integrity while allowing the community to explore more specialized compaction strategies.

Proposal

Would the Codex team consider exposing a plugin extension point for custom compaction?

The high-level idea is:

• keep the existing built-in compact behavior as the default;
• allow a trusted plugin or hook to optionally provide a compacted replacement during a compact operation;
• have Codex core validate and apply the replacement through the existing compaction replacement path;
• keep normal hooks additive-only, so history replacement remains limited to explicit compaction semantics.

This could be implemented either by extending PreCompact or by introducing a dedicated custom compaction hook/provider.

The important part is that plugins would not directly mutate ContextManager. Instead, they would return a constrained request or compact result, and Codex core would remain responsible for applying it safely.

A possible high-level shape could be:

{
  "operation": "replace_range",
  "startItemId": "...",
  "endItemId": "...",
  "summary": "Compact representation for the replaced span."
}

Codex core would still be responsible for:

• validating the selected range;
• preserving tool call / tool result invariants;
• constructing valid model-visible history items;
• normalizing the resulting history;
• deciding whether the custom replacement is safe to apply;
• falling back to the current compact path if the plugin output is invalid or absent.

Why this might be useful

This would allow plugins to experiment with new compaction strategies without requiring Codex itself to own every strategy.

Possible examples include:

• project-specific compaction policies;
• different summary formats for different workflows;
• compactors optimized for debugging sessions;
• compactors optimized for code review sessions;
• compactors that preserve test status and file-change summaries;
• compactors that use small local or cheaper background models;
• compactors that integrate with external project memory or issue-tracking systems.

The main benefit is extensibility: Codex keeps the safe core history machinery, while plugins can provide custom compaction policy.

This could allow the ecosystem to discover useful patterns organically. Some of those patterns may eventually inform future built-in Codex behavior, while others can remain as specialized plugins.

Compatibility

This should not change default behavior.

If no plugin provides a custom replacement, Codex would continue using the existing compaction implementation.

If a plugin does provide one, it should be treated as an optional experimental extension, ideally behind the existing plugin/hook trust model or a feature flag.

Possible API Shape

This is only a sketch, not a final API proposal.

A PreCompact hook or dedicated custom compaction hook could return something like:

{
  "hookSpecificOutput": {
    "hookEventName": "PreCompact",
    "decision": "replace",
    "operations": [
      {
        "type": "replace_range",
        "startItemId": "item-start",
        "endItemId": "item-end",
        "summary": "Summary to insert for the replaced span."
      }
    ]
  }
}

Codex core would then:

1. Validate that startItemId and endItemId exist.
2. Validate that the selected range can be safely replaced.
3. Ensure tool call / tool output pairs are not broken.
4. Construct a valid replacement history item.
5. Apply the result through the same internal history replacement path used by compact.
6. Record the compaction result for debugging and auditability.

Non-goals

This proposal is not asking for a general beforeModelCall(messages) -> messages hook.

A fully general prompt-rewrite hook would be powerful, but it would also make prompt construction harder to reason about and harder to debug.

The suggested scope is intentionally narrower: allow custom replacement only during explicit compaction semantics, where history rewriting is already expected.

This proposal is also not asking plugins to directly mutate ContextManager. Codex core should remain responsible for validating and applying all history changes.

Willingness to contribute

If this direction fits Codex's design goals, I would be happy to work on a focused PR for the extension point and tests.

I wanted to open the discussion first because this touches compaction behavior and plugin boundaries, and I understand that the team may have specific design constraints here.