[FEATURE]: allow user to inject custom instruction when compacting a session

[danry446]

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Problem

When a session is compacted, the LLM generates a structured summary of the conversation. However, the user has no way to provide per-compaction guidance — e.g., what to prioritize in the summary, what information is no longer relevant, or what the next work focus should be.

The existing experimental.session.compacting plugin hook can inject context into the compaction prompt, but:

• It only receives { sessionID } — no per-invocation dynamic input
• The injected content is static (determined by plugin code), not changeable per compaction

Additionally, the recent conversation that the user might use to convey such guidance is often excluded from the compaction scope (it falls into the "recent" portion that is preserved verbatim), so the compaction LLM never sees it.

Proposal

Allow the user to pass an optional instruction string when triggering a compaction, which gets appended to the compaction LLM prompt.

Suggested changes

1. API layer — Add instruction?: string to SummarizePayload (packages/opencode/src/server/routes/instance/httpapi/groups/session.ts)

2. Handler — Pass instruction through compactSvc.create() → compaction.process() (packages/opencode/src/session/compaction.ts)

3. Compaction prompt — Append the user instruction to the summary prompt in processCompaction:

   if (input.instruction) {
     nextPrompt += `\n\nAdditional user instruction for this compaction:\n${input.instruction}`
   }

4. TUI — When the user triggers /compact (or c), show a DialogPrompt input box (already available at packages/tui/src/ui/dialog-prompt.tsx) with a placeholder like "Optional: guide the compaction (what to prioritize, what to drop)…". The user can type a one-liner or leave it empty and press Enter to proceed.
   Why

• Per-compaction guidance is a common pattern in agent frameworks (e.g., Claude Code's /compact with optional instructions)
• The change is minimal — one field threaded through 4 layers, each just passing it along
• No breaking changes — instruction is optional; existing behavior is preserved when it's absent
  Context
• Current compaction implementation: packages/opencode/src/session/compaction.ts (V1 path, actively used)
• V2 core compaction (packages/core/src/session/compaction.ts) does not yet support plugin hooks; this proposal should be considered for both paths
• DialogPrompt component already exists and is used by other commands (e.g., session rename, provider config)

[sghng]

Adding a concrete use case that makes per-compaction instructions more than a nice-to-have: task-transition compaction.

Use case

A common workflow: I've finished work on one aspect of a project and want to move on to a different one. Before switching, I compact to free up context window. The problem is that the summarizer doesn't know the first task is done — it preserves a blend of everything, spending summary budget on details of the finished work while dropping the state that matters for what comes next.

If I could simply steer the compaction at invocation time, e.g.:

/compact retain info related to the implementation of X

—or the inverse for transitions: "aspect A is complete and won't be revisited; keep only its outcome, and prioritize decisions and open threads relevant to aspect B"—compaction quality would improve significantly. This is exactly the instruction field proposed above, but it's the difference between a summary that serves the next task and one that just recency-weights the last few turns. Without it, each compaction during a long session drifts toward whatever was discussed most recently rather than what's needed next.

Note that this guidance has to reach the compaction invocation itself: by the time the user would type it as a normal message, it falls into the verbatim-preserved "recent" portion and never reaches the summarizer (as the description already points out).

Related work not yet linked here

• [FEATURE]: Compaction: deterministic retention of user messages and a configurable compaction prompt #49463 — deterministic retention of user messages plus a configurable compaction prompt. Documents the same gap in the experimental.session.compacting hook (it only receives { sessionID }, no per-invocation input), and is complementary: config-level defaults + per-invocation instructions would cover both "always keep X" and "this time keep Y".
• PR fix(session): restore compact slash arguments #28630 (closed, unmerged) — actually implemented /compact <instructions> and /summarize <instructions> (TUI prompt box, instructions persisted and appended to the compaction prompt, with tests). Good prior art for the TUI and plumbing parts of this proposal.
• PR feat(core): enhanced compaction with ratios and combined context-restoration advancement #45125 (open) — improves summary fidelity via a context-restoration document and a <newest_context> relevance signal, but it's still summarizer-mediated: there's no way to tell the summarizer what the next task is. User-supplied instructions would slot in naturally alongside its prompt sections.
• [FEATURE]: Implement V2 manual compaction #40614 — worth noting for the V2 path mentioned above: SessionV2.compact is still a stub, so on V2 there is no manual compaction to attach instructions to yet. If both are implemented together, the instruction field should be part of the V2 compact API from the start rather than retrofitted.