[FEATURE]: experimental.session.pre-compact hook #24993

[FEATURE]: experimental.session.pre-compact hook

Feature hasn't been suggested before.

• I have verified this feature hasn't been suggested before.

Describe the enhancement you want to request

During compaction, OpenCode enforces tools: {} and summary: true, blocking all tool calls. This prevents plugins from performing critical write operations before context is compressed — specifically, archiving important understandings from the conversation into scratchpad files and/or persistent memory (e.g., Memory.md).

The existing experimental.session.compacting hook only allows injecting text into the summary prompt. It cannot execute tools, so structured data migration is impossible.

Use case: AI memory systems

In long sessions, AI accumulates critical understandings that should persist beyond the current conversation window. Before compaction destroys the detailed context, plugins need to:

• Extract key insights from the conversation
• Write them to scratchpad or structured memory files (Memory.md)
• Go through normal permission/approval flows for file modifications

Without this hook, these operations must happen during normal conversation (unreliable) or are lost entirely.

Proposed solution

Add an experimental.session.pre-compact hook that fires before compaction, giving plugins an autonomous cycle with tool access:

"experimental.session.pre-compact"?: (
  input: { sessionID: string; auto: boolean; parentID: string },
  output: { shouldRun: boolean; prompt?: string },
) => Promise<void>

Key design points:

• Opt-in: shouldRun: false by default — zero impact on existing users
• Tool access: Pre-compact round uses the complete tool registry (unlike compact's tools: {})
• Resilient: Pre-compact failure never blocks compaction
• Security: Tool executions should go through normal permission/approval flows (not silently bypassed)

Two-phase architecture:

[Pre-Compact]              [Compact]
  plugin-controlled          OpenCode-controlled
  structured operations      lossy compression
  archive to files           summary generation

Open design questions (for maintainer input)

• Should pre-compact assistant messages be retained in session history?
• Should pre-compact respect auto-compact vs manual /compact differently?
• How should permission approvals work during pre-compact? (Normal flow vs special handling?)

Related issues

• [FEATURE]:Add pre-compaction hook for session save/export #14164 — pre-compaction hook for session save/export
• [FEATURE]: Add expanded hook events to the plugin system to enable more powerful plugin capabilities. #21075 — expanded plugin hook events (includes preCompact)

Implementation status

We have a minimal working(unsecured, non-productive) prototype on branch pre-compact-minimal (2 commits, ~95 lines across 3 files). It implements the basic hook mechanism and integrates with ToolRegistry. The permission/approval flow and message retention behavior are left as open design decisions for upstream.