Opencode v2 compatibility (compaction within context-mode)

[nathanpride]

What / Why / How

What: OpenCode v2 support via Dual Support — one published package serves both OpenCode 1.x and 2.x hosts. Adds a v2 adapter (setup() entrypoint, tool registration, hooks, usage capture, readiness sentinel, destructive-tool policy) and — the headline — non-LLM compaction: context-mode supplies its own database-derived table-of-contents summary via SessionCompaction.result, so the compaction step completes with zero LLM calls (configurable own | passthrough).

Why: OpenCode 2's plugin loader ignores the V1 { id, server } shape — per OpenCode's migration guide, "V1 plugin implementations do not run in V2." Today context-mode silently fails to load on OpenCode 2: no ctx_* tools, no hooks, no indication anything is wrong.

Acknowledgements: This builds on the direction established by @Scratchydisk in #1171, which got this effort started. Credit where due — several pieces converge in both branches independently: the v2 dual-export shape, the full V1→V2 hook mapping, routing enforcement (deny/modify/context), per-turn usage capture via ctx.event.subscribe, and the pid-based readiness sentinel. The genuine deltas here:

• Non-LLM compaction (own mode, the default): fix(opencode): support OpenCode 2 plugin API (V1/V2 dual export) #1171's compaction hook appends the TOC snapshot to event.system — the host's LLM still runs to narrate the summary. Here ctx.session.hook("compaction") sets SessionCompaction.result = { summary }, so the summarization model call never happens — compaction completes with zero LLM calls. Configurable via plugin options.compaction (own | passthrough), surfaced in ctx_doctor.
• A fix for the failure mode fix(opencode): support OpenCode 2 plugin API (V1/V2 dual export) #1171 is vulnerable to: that branch builds the v2 shape via await import("@opencode/plugin") with a catch fallback that drops setup — if the import fails to resolve on a host (e.g. opencode plugin add skipping full dependency resolution), OpenCode 2 rejects the whole plugin ("Plugin must export a default definition with an id and an effect or setup function"). Here the merged default export is a plain object literal ({ id, setup, server }) that never depends on that import at runtime, and a regression test locks the invariant by simulating the import failure.
• Destructive-tool policy (v2-only): ctx_purge/ctx_upgrade refuse by default; opt in via CONTEXT_MODE_ALLOW_DESTRUCTIVE=1. (v2 hosts create no per-call permission prompt for plugin tools, so the policy is enforced in the tool itself.)
• v2-native usage capture: fix(opencode): support OpenCode 2 plugin API (V1/V2 dual export) #1171 listens on message.updated (the v1 event name) with the existing parseOpencodeUsage; this targets session.step.ended with session.step.started model correlation, native USD cost passthrough, and reasoning tokens folded into output per the gemini thoughtsTokenCount precedent.
• Adapter target axis (v1/v2): CLI --v2 flag, config-as-ground-truth target detection, stale opposite-key migration (plugin → plugins) to prevent double registration — plus ctx_doctor reporting the effective target and compaction mode.

How:

• Shared ContextModeCore (src/adapters/opencode/core.ts): SessionDB, capture/claim, routing islands, ctx tool handlers — memoized per platform::loadScopeDir. V1 and V2 are thin delivery shells over the same core.
• Merged default export in plugin.ts: { id: "context-mode", setup: setupV2, server: createContextModePlugin } — V1 calls server(), V2 calls setup(), each ignores the other's key.
• @opencode/plugin / @opencode/schema are type-only devDependencies (import type → erased); the runtime tree contains no @opencode/* import, so nothing new can fail to resolve on a host.
• v2 tool input built with the existing zod3ShapeToV4 conversion ([Feature]: Plugin-only tool registration for ts-plugin adapters (OpenCode, KiloCode, OpenClaw) #574); CoreTool.run re-parses with the v3 schema for authoritative coercion and byte-identical "Invalid arguments for <name>: …" errors.
• Tools register bare names + options.namespace: "ctx" → effective ctx_*; hooks receive the effective name.
• Compaction: ctx.session.hook("compaction") sets ev.result = { summary } only in own mode (guard: non-empty snapshot). Routing block + resume pointer are pushed into ev.system for kind="primary" requests with a quorum guard.

Affected platforms

• Claude Code
• Cursor
• VS Code Copilot (GitHub Copilot)
• JetBrains Copilot
• Gemini CLI
• Qwen Code
• OpenCode
• KiloCode
• Codex CLI
• OpenClaw (Pi Agent)
• Pi
• Kiro
• Antigravity
• Zed
• All platforms

Scope is the OpenCode adapter only. The V1 / KiloCode path is byte-identical — all 57 pre-existing v1 plugin tests pass unchanged.

Test plan

• New v2 tests (merged into tests/adapters/opencode.test.ts per the guide's one-file-per-domain rule — 122 tests: 65 v1 + 57 v2): dual-export shape, tool registration under the ctx namespace, compaction own/passthrough/host-alias modes, routing-block quorum, usage capture (session.step.ended cost/token mapping + model correlation), destructive-policy refusal, doctor compaction-mode surfacing, and a regression guard that setup survives a simulated @opencode/plugin resolution failure (negative-verified: swapping in the buggy await-import+fallback pattern makes the test fail).
• Full suite (rebased onto next): npx vitest run → 213 files, 4845 passed / 31 skipped / 0 failed.
• npm run typecheck: EXIT 0.
• Live verification against a real OpenCode 2 install (isolated OPENCODE_CONFIG_DIR + --standalone): plugin loads clean, ctx_execute runs sandboxed code end-to-end (4), ctx_stats reports from the real session DB, ctx_purge refused by default per the destructive policy.
• Contribution-guide compliance pass (Three main rules): the one regex in shipped code (systemHasRoutingInstructions word-boundary check) was replaced with a structural delimiter walk (containsAsWord), and the two regex assertions added in tests were replaced with startsWith / indexOf containment checks. Shipped-code diff verified regex-free; rebuilt artifacts confirmed clean.
• Untested paths, named explicitly (per "never a plausible sentence where the evidence is missing"): compaction ownership (own/passthrough) and routing-block-on-primary are exercised in the mock harness but not yet in a live long session — they require a session long enough to trigger a real compaction cycle. Tool execution, usage capture, destructive-policy refusal, and plugin load are live-verified.

Checklist

• Tests added/updated (TDD: red → green)
• npm test passes
• npm run typecheck passes
• Docs updated if needed (README, platform-support.md) — docs/platform-support.md gains an "OpenCode v2 (Dual Support)" section with the compaction-mode table; configs/opencode/opencode-v2.json template added
• No Windows path regressions (forward slashes only)
• Targets next branch — rebased onto next tip (e31360d); diff vs next is exactly this feature (17 files, +3461/−894 incl. rebuilt bundles)