OpenCode 2: validate .opencode config against the v2 schema and port the v1 plugins

Part of the fleet-wide OpenCode 2 migration tracked at developing-today-forks/opencode#374 (origin issue for the whole set).

Upstream migration guide: https://dev.opencode.ai/v2/docs/migrate-v1/

Two workstreams in this repo:

1. Config validation — `.opencode/opencode.jsonc` against OpenCode v2

Load the repo config with OpenCode v2 (@opencode/cli@2.1.4) and record what it accepts and rejects.
Config files, agents, commands, and skills under .opencode/ are intended to be compatible; some v1 fields are accepted but ignored by v2. Hard rejections get fixed (PR); accepted-but-ignored fields get listed here so we can decide whether to keep them while runtimes are still migrating or drop them.
Note: .opencode/cli.json already targets the v2 CLI schema (https://opencode.ai/v2/cli.json), while .opencode/tui.jsonc still exists alongside it (v2 auto-migrates tui.json → cli.json).

2. Plugin ports — v1 plugin API → v2 plugin API

v1 plugins do not run in v2 (new plugin API). Ours, in order of how much we depend on them:

mcpx bridge + mcpx-session — .opencode/plugin/mcpx-session.ts is the plugin entry (imports tool and Plugin from @opencode-ai/plugin; default export is async ({ directory, worktree, project, client }, options) => …), backed by the .opencode/plugin/mcpx/ modules (daemon client, ops). First step: inventory the v1 hooks/lifecycle points and SDK calls these use, and diff them against the v2 plugin API in the migration guide; list anything with no v2 equivalent.
subtask2 — third-party npm plugin @openspoon/subtask2@latest in the config plugin array, configured by .opencode/subtask2.jsonc. First step: check whether subtask2 ships a v2-compatible release; if not, decide between a fork, vendoring, or replacing it.
The rest of the plugin array is also v1-era npm plugins (opencode-working-memory, opencode-scheduler, opencode-pty, opencode-devcontainers, @openchamber/opencode-claude, @pieliesdie/opencode-antigravity-auth, and more). Each needs the same v2-compatibility check; the two items above are the ones we own or depend on most.
.opencode/package.json pins @opencode-ai/plugin 1.18.19 — the plugin SDK bump belongs to this workstream.

Status: config validation is being run first; plugin ports are scoped here but not started.

Acceptance criteria

Workstream 1 (config validation) is recorded as done: .opencode/opencode.jsonc loads clean under OpenCode v2 (validation comment, 2026-10-24); any accepted-but-ignored v1 fields are listed on this issue with a keep/drop decision each.
The mcpx bridge + mcpx-session plugin has a v2 port, or a written gap list naming every v1 hook/SDK call with no v2 equivalent and the chosen workaround.
subtask2 has a recorded decision: v2-compatible release adopted, fork/vendor chosen, or replacement named.
Every remaining plugin in the config plugin array has a v2-compatibility verdict recorded on this issue.
.opencode/package.json pins a v2-era @opencode-ai/plugin SDK and the repo's agents/commands/skills still load under the v2 CLI.

Config validation result — ran 2026-10-24

Verdict: .opencode/opencode.jsonc loads clean under OpenCode v2. No PR opened — there are no hard incompatibilities in the config itself to fix. Details below; the plugin half of this issue is where the real breakage is (also below).

Method

Installed @opencode/cli@2.1.4 in an isolated prefix with a scratch HOME (the live v1.18.31 server and its config were not touched).
Copied this repo's .opencode/ tree into a scratch project and ran:
- opencode debug config → exit 0, zero WARN/ERROR lines.
- opencode debug agents → exit 0; all agents resolve (config-defined build, classifier, classifier-complex, coder, reasoner, compaction, plus the agents/*.md agents Explore/General/Plan and built-ins).
- A full project load by a fresh v2 server (for plugin behavior, below) → no config/schema errors in the server log.

What v2 does with the v1-shaped config

The v2 loader normalizes v1 fields itself — these renames happen automatically, no edit needed:

v1 field	v2 result
`agent`	`agents` (all 6 keys preserved)
`provider`	`providers` (all 14 provider IDs preserved exactly)
`plugin`	`plugins` (all 14 specs preserved)
`autoupdate: true`	`update: "auto"`
`disabled_providers`	`policies` (`provider.use` deny entries)
`compaction`	accepted, reshaped to v2 form

Accepted but dropped (v2 ignores these — decision needed, not a fix)

default ("claude-code/claude-haiku-5-5") — does not appear in v2's resolved config, and v2 does not turn it into a model either. On upstream v2 this field is a no-op. Keeping it costs nothing while runtimes are still on v1; flagging it here so the set remembers it once the fork rebase decides whether our v2 line keeps a default-model concept.
experimental.model_routes — the model-pool routing table (cheap-pool targets etc.). Upstream v2 drops the whole experimental block. If pool routing is load-bearing for the fleet, it has to be carried by the fork rebase (origin issue, item (a)) or reimplemented — v2 upstream will not honor it.

Neither field is rejected by v2, and removing them from the repo config now would change behavior for the still-on-v1 runtimes, so both stay until the runtime migration lands.

Plugin load evidence (workstream 2 preview — ports NOT started)

On the fresh v2 server load of the full tree (with .opencode/package.json deps installed, @opencode-ai/plugin 1.18.19), 8 plugins were attempted in the capture window and 6 failed with the same v2 module-contract error:

PluginModule.LoadError: Plugin must export a default definition with an id and an effect or setup function.

Failed:

plugin/mcpx-session.ts (ours — its v1-style async-function default export does not satisfy the v2 contract)
plugins/autoresearch-context.ts (ours)
@openspoon/subtask2@latest (subtask2's current release is not v2-compatible)
opencode-scheduler@latest, opencode-pty@latest, opencode-devcontainers@latest

Attempted with no failure recorded in the window: opencode-working-memory@latest, @mohak34/opencode-notifier@latest. The remaining specs in the plugin array weren't reached in the window; assume v1-shaped until checked. This confirms the scoping in the issue body: the port's first step is the v2 plugin contract (id + effect/setup default export) vs the v1 hooks our plugins use.

Intake review — fleet monitor, 2026-10-26T08:26:24Z.

Still live — partially advanced: workstream 1 is already done (the 2026-10-24 comment on this issue records .opencode/opencode.jsonc loading clean under OpenCode v2, no PR needed). Workstream 2 (plugin ports) is not started, per the issue body, and nothing since has changed that: the mcpx bridge inventory/diff against the v2 plugin API is still the first step. Acceptance criteria were missing and have been appended to the body (original text preserved verbatim above them).

Related: this is one leg of a cross-repo set — origin issue developing-today-forks/opencode#374 (still open), sibling leg developing-today-forks/openchamber#384. Per the fleet cross-repo rule, the set is tracked from the origin issue; do not file per-repo duplicates.

Suggested approach: sequence after the opencode#374 fork rebase lands a stable v2 plugin API surface; start with the mcpx-session hook inventory since the fleet depends on it most.

Risks: porting against a moving v2 API wastes the effort; effort class l reflects the whole plugin array, not the mcpx bridge alone.

🤖 Agent note · cross-reference from #1858 triage (queue task 2746, 2026-10-29)

The shipped-plugin v2 port (mcpx: port the opencode plugin to opencode v2 (a rewrite, and several things get better) #1858, pkgs/mcpx/plugin/opencode/) was triaged today: scope confirmed, core rewrite enqueued as queue task 3068. This issue's workstream 2 (the deployed copy at .opencode/plugin/mcpx-session.ts) is a different artifact and stays owned here — noted on mcpx: port the opencode plugin to opencode v2 (a rewrite, and several things get better) #1858 so the two ports follow one shape and do not diverge silently.

🤖 Agent note · picked up

Agent: queue worker (repo-worker-code), lane F
Session / ID: queue task 2194
Found via: queue claim
Task: Triage OpenCode 2: validate .opencode config against the v2 schema and port the v1 plugins #730 — verify workstream 1/2 state against current main (config validation, plugin array, SDK pin, deployed mcpx-session copy, and the mcpx: port the opencode plugin to opencode v2 (a rewrite, and several things get better) #1858/mcpx opencode v2 plugin: implement the #1858 SET-REMAINDER items (1)-(5) #2841 shipped-port set), then route the remainders.
Expectation: effort l overall; triage done = verdict posted with HEAD citations, each remainder routed or explicitly linked to the set that owns it, labels synced.
Links: issue OpenCode 2: validate .opencode config against the v2 schema and port the v1 plugins #730

🤖 Agent note · done

Agent: queue worker (repo-worker-code), lane F
Session / ID: queue task 2194 (triage)
Found via: queue claim
Task: Triage verdict for OpenCode 2: validate .opencode config against the v2 schema and port the v1 plugins #730 — WS1 DONE; WS2 CONFIRMED still owed, on current main 558cc1d23e1d2d90df2a0d36189b5e585f12f99b.
Verified at HEAD:
- Workstream 1: done — the 2026-10-24 comment on this issue records .opencode/opencode.jsonc loading clean under OpenCode v2; nothing since contradicts it. Acceptance item 1's validation half is satisfied; the accepted-but-ignored field list was recorded in that same comment.
- .opencode/package.json still pins @opencode-ai/plugin 1.18.19 — acceptance item 5 (v2-era SDK pin) not done.
- .opencode/opencode.jsonc:6463-6478 — the plugin array now has 13 active entries (antigravity-auth commented out 2026-10-24); no comment on this issue records a v2 verdict for any of them, and subtask2 (@openspoon/subtask2@latest, :6467) has no recorded decision — acceptance items 3 and 4 not done.
- .opencode/plugin/mcpx-session.ts:1 still imports { tool, type Plugin } from @opencode-ai/plugin (the v1 SDK) — the deployed copy is unported. Per the 2026-10-29 cross-reference, its port rides the shipped-plugin set: mcpx: port the opencode plugin to opencode v2 (a rewrite, and several things get better) #1858 / mcpx opencode v2 plugin: implement the #1858 SET-REMAINDER items (1)-(5) #2841, queue task 3997 (parked, items (1)(3)(4)(5) remain). Acceptance item 2 is owned there, not duplicated here.
Route: the unowned remainder (plugin-array verdicts + subtask2 decision, with the SDK bump gated on them) is split to linked issue OpenCode 2 (#730 WS2 remainder): plugin-array v2 verdict pass + subtask2 decision #3286 — filed because this issue's queue triage dedupe key is consumed by task 2194 itself (the enqueue returned 2194) — and enqueued as queue task 4850 (kind triage). This issue stays open as the parent tracker; labels synced to queue/queued for the routed remainder.

Plugin-array V2 compatibility verdicts — checked 2026-11-01

The V2 migration guide says V1 plugin implementations do not run in V2. The V2 loader requires the module's default export to be a definition with a stable id and setup or effect. Verdicts below are based on current upstream package/source evidence, not version recency alone. Config entries are from main dee3cb93d, .opencode/opencode.jsonc:6533-6547; the SDK pin remains @opencode-ai/plugin 1.18.19 (.opencode/package.json:4).

Active plugin entry	Verdict	Upstream evidence checked
`opencode-working-memory@latest`	V2-ready — 1.7.0	npm latest; entrypoint default-exports `{ id, server, setup }`; compatibility notes record verification with CLI/plugin 2.1.4.
`opencode-scheduler@latest`	V2-incompatible — 1.3.0	npm latest; manifest and source depend on/import the V1 `@opencode-ai/plugin` interface; no V2 entrypoint is declared.
`@openspoon/subtask2@latest`	V2-incompatible — 0.3.9	npm latest; published source default-exports a V1 hook function, not a V2 definition. Details/options below.
`@mohak34/opencode-notifier@latest`	V2-ready — 1.1.2	npm latest; entrypoint exports `{ id, setup }`; changelog records V2 support since 0.4.0 and subsequent V2 fixes.
`opencode-pty@latest`	V2-incompatible as configured — 0.4.0	published root entrypoint has no compliant default export. A compliant V2 subpath exists, but upstream issue #85 reports OpenCode 2.0.32 cannot load it as an npm plugin.
`opencode-devcontainers@latest`	V2-incompatible — 0.5.1	published manifest points to entrypoint, which default-exports an async V1 hook function, not `{ id, setup/effect }`.
`@franlol/opencode-md-table-formatter@latest`	V2-incompatible — 0.0.6	published entrypoint has a named async export and no compliant default export; README describes the V1 `experimental.text.complete` hook.
`opencode-cmd-provider@latest`	V2-ready — 2.3.2	published entrypoint default-exports `{ id: "commandcode", server, setup }`; V2 test validates the definition against the V2 loader schema.
`opencode-cockpit@latest`	V2-ready — 0.11.2	server entry default-exports `dualServer(...)`; its helper returns a definition with `id` and `setup`.
`@openchamber/opencode-claude@1.3.8`	V2-ready — configured pin 1.3.8	The pinned entrypoint default-exports a plugin definition with `id` and async `setup`; its manifest uses `@opencode/plugin`. npm latest observed was 1.7.0, but the configured 1.3.8 pin itself has the V2 shape.
`opencode-models-discovery@latest`	V2-ready — 2.1.0	Published entrypoint default-exports `combinedPlugin`; its definition has an `id` and `setupV2`.
`opencode-mem@latest`	V2-ready — 2.39.0	Published plugin entry exports the V2 plugin definition; its V2 implementation defines `id` and async `setup`.
`opencode-auto-continue@…/tags/latest.tar.gz`	V2-incompatible — tag `latest` (package 1.0.0)	The configured tarball tag resolves to commit `aceb217`; its entrypoint is a V1 async plugin function returning legacy hooks, not a V2 definition.

subtask2 options — decision requested from Drew

No V2-compatible @openspoon/subtask2 release was found: npm dist-tags show only latest: 0.3.9, its published source is V1-only, and the repository's current @spoons-and-mirrors/subtask2@0.3.5 manifest is also V1-only. Its GitHub releases endpoint is empty.

Options: (1) use native V2 commands with subagent: true (the subtask alias is deprecated) if simple background delegation is enough; this is not feature parity for subtask2's chaining, loops, parallel expansion, and turn references; or (2) fork/port or vendor-and-port if those behaviors are required (vendoring alone does not fix the API). I found no evidenced drop-in replacement; Pocket Universe is marked WIP and still declares only the V1 SDK (repo).

Recommendation: first confirm which subtask2-specific behaviors are actually used. Prefer native V2 commands if basic child delegation suffices; if chaining/loops/parallel expansion/turn references are required, a maintained V2 fork/port is the clearest route. Drew's decision is needed on that feature trade-off; no replacement or port is being chosen silently. The SDK-pin bump and plugin ports remain separate scoped follow-ups after this verdict pass.

🤖 Agent note · escalated

Agent: queue worker (repo-worker-code), OpenChamber scheduled lane
Session / ID: queue task 4850
Found via: queue claim for linked remainder OpenCode 2 (#730 WS2 remainder): plugin-array v2 verdict pass + subtask2 decision #3286
Read: the source-linked verdict table above shows @openspoon/subtask2@0.3.9 remains V1-only and no V2-compatible release/replacement was evidenced. Native V2 subagent: true commands cover basic background delegation but not subtask2 chaining, loops, parallel expansion, or turn references.
Decision requested from Drew: confirm which of those behaviors must be preserved; if required, authorize a maintained V2 fork/port, otherwise route the migration to native V2 commands. This choice was not made silently.
Links: OpenCode 2 (#730 WS2 remainder): plugin-array v2 verdict pass + subtask2 decision #3286 · queue task 4850

agent-note:v1
task: 5175 (triage, OpenChamber scheduled lane)
state: picked-up
checked_at: 2026-11-02T00:42:47Z

Agent: repo-worker-code
Session / ID: ses_e5e664d196effeXtKu9JvRgg6W
Found via: queue claim
Task: Revalidate safety-net triage for OpenCode 2: validate .opencode config against the v2 schema and port the v1 plugins #730 against current GitHub state; no implementation.
Expectation: identify existing ownership and route without duplicating the completed triage or overriding any Drew decision.

agent-note:v1
task: 5175 (triage, OpenChamber scheduled lane)
state: superseded
checked_at: 2026-11-02T00:43:31Z

Fresh GitHub state confirms OpenCode 2: validate .opencode config against the v2 schema and port the v1 plugins #730 remains open, but its previous monitor queue label is absent. Task 5560 already re-triaged the parent; the remaining plugin verdicts and subtask2 decision are recorded on OpenCode 2: validate .opencode config against the v2 schema and port the v1 plugins #730 and routed to OpenCode 2 (#730 WS2 remainder): plugin-array v2 verdict pass + subtask2 decision #3286.
OpenCode 2 (#730 WS2 remainder): plugin-array v2 verdict pass + subtask2 decision #3286 is already blocked and user-escalated for Drew's feature choice; mcpx opencode v2 plugin: implement the #1858 SET-REMAINDER items (1)-(5) #2841 remains separately blocked on its named API/host limitation. PRs feat(mcpx): opencode v2 plugin core — {id, setup}, namespaced tools, ctx.storage (#1858) #2489 and mcpx v2 plugin: permission gate for daemon_select (#1858 item (2)) #3018 are merged.
No duplicate follow-up was created and no existing escalation or ownership was changed. Queue task 5175 completed as superseded.

RULING (Muse, acting for Drew, 2026-11-03): do not adopt subtask2-specific chaining/loops/parallel expansion — no V2-compatible @openspoon/subtask2 release exists and current use cases do not require it (verdicts in comment 6560539252). Revisit only when a V2-compatible release ships. Task 4850 closed.

Navigation Menu

Repository navigation

OpenCode 2: validate .opencode config against the v2 schema and port the v1 plugins #730

1. Config validation — `.opencode/opencode.jsonc` against OpenCode v2

2. Plugin ports — v1 plugin API → v2 plugin API

Acceptance criteria

Config validation result — ran 2026-10-24

Method

What v2 does with the v1-shaped config

Accepted but dropped (v2 ignores these — decision needed, not a fix)

Plugin load evidence (workstream 2 preview — ports NOT started)

Intake review — fleet monitor, 2026-10-26T08:26:24Z.

10 remaining items

Plugin-array V2 compatibility verdicts — checked 2026-11-01

subtask2 options — decision requested from Drew

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

OpenCode 2: validate .opencode config against the v2 schema and port the v1 plugins #730

Description

1. Config validation — .opencode/opencode.jsonc against OpenCode v2

2. Plugin ports — v1 plugin API → v2 plugin API

Acceptance criteria

Activity

dezren39 commented on Oct 24, 2026

Config validation result — ran 2026-10-24

Method

What v2 does with the v1-shaped config

Accepted but dropped (v2 ignores these — decision needed, not a fix)

Plugin load evidence (workstream 2 preview — ports NOT started)

dezren39 commented on Oct 26, 2026

Intake review — fleet monitor, 2026-10-26T08:26:24Z.

dezren39 commented on Oct 29, 2026

dezren39 commented on Nov 1, 2026

dezren39 commented on Nov 1, 2026

10 remaining items

dezren39 commented on Nov 1, 2026

Plugin-array V2 compatibility verdicts — checked 2026-11-01

subtask2 options — decision requested from Drew

dezren39 commented on Nov 1, 2026

dezren39 commented on Nov 2, 2026

dezren39 commented on Nov 2, 2026

dezren39 commented on Nov 3, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

1. Config validation — `.opencode/opencode.jsonc` against OpenCode v2