Track real-host promotion gate for experimental OpenCode 2 adapter

[ByBrawe]

Why this stays experimental

OpenCode 2 support remains evidence-gated. Stable npm compatibility stays @opencode-ai/plugin >=1.4.0 <2; no stable OpenCode 2 claim is made until exact current-beta lifecycle behavior is proven end to end.

Current evidence — 2026-08-18

1. Project-plugin readiness race is handled

Current @opencode-ai/cli@next resolves to opencode2 v0.0.0-beta-17498 in the real-host gate. Diagnostic #87 proved the first correctly scoped project /api/plugin read can be empty before plugin initialization finishes; a fresh read on the same service exposes the registry and sentinel setup marker. Main has bounded same-service readiness without weakening wrong/rejected/global Location failures.

2. Exact-beta adapter activation is now green

The earlier setup crash TypeError: undefined is not an object (evaluating '_.name.replace') was isolated to the V2 tool registration signature. Beta-17498 exposes tools.add as a one-argument function and expects one complete Tool definition object. The previous adapter used the older three-argument form, so beta treated the string name as the Tool value and later failed while reading name.

PR #162 fixed only that contract mismatch: when the host exposes one-argument tools.add, the adapter registers { name, ...definition, codemode: false }; legacy/prototype test hosts retain the existing three-argument path. Exact-head Experimental OpenCode 2 Host passed on beta-17498, and #162 merged as ba5738b....

Activation is therefore no longer the promotion blocker.

3. Real /goal behavior is blocked by the current beta host surface

Test-only PR #163 exercised the unchanged post-#162 production adapter on exact beta-17498 with a real declared goal command and a deterministic local provider. It was intentionally closed without merge after collecting the runtime shape.

Observed behavior:

• command.transform runs and can mutate the existing goal command, but the later built-in opencode.config.command transform overwrites that mutation with the declared command template before model dispatch.
• session.hook("request", ...) registers successfully but does not fire on the real command/provider path.
• session.hook("context", ...) does fire on each provider turn and exposes { sessionID, agent, model, system, messages, tools }.
• tool.transform registration succeeds, but plugin-added Goals tools are not materialized into the effective request tool set. Diagnostic tools with codemode omitted, false, and true were all absent from both the context hook's tools map and the provider request.
• The managed /goal bridge reaches the model path as ordinary user text. The corresponding context message has an empty metadata object.
• ctx.event.subscribe() exposes the global beta event stream. A real /goal invocation becomes session.inbox.enqueued with an ordinary { type: "user", payload: { text }, delivery: "steer" } item, then session.inbox.delivered. No command name, command-origin marker, capability ID, or other unforgeable invocation identity is present in the observed public event/message shape.

4. Security consequence

The managed bridge text cannot be used as the authorization signal for lifecycle mutation because normal user input can reproduce the same text. Without an unforgeable host-origin signal, the adapter cannot safely distinguish a real /goal invocation from forged ordinary chat.

Separately, even correctly registered plugin tools do not currently reach the effective request tool set on beta-17498. Therefore there is no evidence-backed path on this beta to grant request-scoped opencode_goals_v2_control, execute the lifecycle mutation, and then prove replay is closed.

Do not replace this with a guessed text-marker/nonce scheme derived only from model-visible content.

5. Upstream watch target

anomalyco/opencode#35408 ([FEATURE]: Add V2 model-context plugin hook) tracks the missing provider-turn seam for mutating the final model-facing context/tools before inference. It directly matches the observed tool-materialization gap.

No matching open upstream issue was found for exposing an unforgeable custom-command origin/capability identity to V2 plugins. That remains a separate requirement unless the host adds an equivalent direct command interception API.

Remaining promotion gate

• bounded same-service readiness without weakening Location requirements
• Goals adapter activation on the exact current beta
• host surface can materialize plugin tools into the effective request tool set
• host surface exposes an unforgeable /goal invocation identity or equivalent direct command interception capability
• predeclared-command / direct-command path → control tool → exact persisted Goal behavior
• mismatched lifecycle arguments fail closed before persistence
• ordinary/post-tool requests cannot reuse mutating lifecycle control and retain read-only Goal inspection
• any anti-replay contract is derived from real-host evidence and guarded adversarially
• Plan safety and fail-closed Location behavior have real-host coverage
• completion/recovery parity scope is explicitly resolved before any stable support claim
• opencode2-experimental adversarial category remains 100%
• stable V1 CI, host progress, restart recovery, release readiness, and Actions Security Gate remain green on the promotion head

Resume rule

Resume V2 behavior implementation only when the exact beta/public V2 plugin surface provides both required capabilities above (or one equivalent host API that directly and safely handles custom command invocation plus request-scoped tool exposure). Until then, stable V1 remains the supported path and OpenCode 2 remains experimental/unsupported for lifecycle behavior.

Historical experiments and exact-beta logs remain in the issue comments.

[ByBrawe]

Real-host recheck — 2026-08-13

Retested the promotion gate against current @opencode-ai/cli@next, resolving to opencode2 v0.0.0-next-17403.

The canary now proves the request is scoped to the real committed project Location rather than the global/home Location:

• /api/health succeeds;
• /api/plugin?location[directory]=<temp-project> returns the exact temp project directory;
• the project receives a non-global project ID (73b07c3d... in this run);
• the canary supplies a minimal V2 { id, setup } sentinel and the Goals V2 adapter through project .opencode/plugins/, project opencode.json, and inline config;
• the project-scoped /api/plugin response still returns data: [].

So the current beta still does not activate even the minimal V2 sentinel in this real-host path. This is not evidence of a Goals-adapter-specific failure, and the stable V1 export must remain unchanged.

Separately, the current V2 plugin documentation uses ctx.session.hook("request", ...); the experimental adapter has been aligned to prefer that documented hook while retaining the earlier prototype hook only as best-effort compatibility. That adapter change remains unpromoted until the sentinel gate passes.

Promotion gate remains blocked: do not expose the V2 adapter from the stable npm surface until a future @next host activates the sentinel and then the Goals V2 plugin at the same project Location.

[ByBrawe]

Fresh OpenCode 2 loader probe on 2026-08-14 against @opencode-ai/cli@next = opencode2 v0.0.0-next-17430.

I isolated plugin loading from the Goals adapter completely. The canary creates a minimal V2 plugin:

export default { id: "bybrawe.open-code-goals.v2-loader-sentinel", setup: async () => {} }

and places it only at the project-local .opencode/plugins/ path. No file:// plugin entries and no local-path plugins config are used. The project is a committed git workspace and /api/plugin is queried with the exact project Location.

Result: the host resolves the correct non-global project Location, but /api/plugin returns data: []; the sentinel is not discovered or activated. Server DEBUG log shows the project-scoped /api/plugin request but no local-plugin activation/import attempt.

So the current blocker remains upstream of the Goals adapter: project-local V2 plugin discovery is not active in this next host build. Separately, the current upstream V2 Promise PluginContext now exposes agent, aisdk, catalog, command, integration, plugin, reference, and skill domains, but no session or tool domains, so our old experimental adapter contract is stale and must be rewritten once the host exposes the lifecycle/tool capabilities Goals needs.

Stable V1 remains untouched; no V2 export should be promoted until a minimal sentinel is actually visible in /api/plugin on a real V2 host.

[ByBrawe]

Real-host recheck — 2026-08-17

Retested the promotion gate from main commit 9eff5d425462a11f7d9695ac678ef1aaa74869d4 against current @opencode-ai/cli@next, resolving to opencode2 v0.0.0-beta-17498.

This run strengthens the loader probe by separating project-local discovery from the V2 { id, setup } contract:

1. the canary creates a V1-compatible project-local plugin function in .opencode/plugins/ whose only side effect is writing an isolated marker file when OpenCode executes it;
2. it also creates the minimal V2 { id, setup } sentinel and the Goals V2 adapter bridge in the same directory;
3. project opencode.json contains no plugin injection, and OPENCODE_CONFIG_CONTENT is no longer used, so the test relies only on project-local plugin discovery;
4. /api/health succeeds and /api/plugin?location[directory]=<temp-project> resolves the exact committed, non-global project Location.

Result: /api/plugin still returns data: [], and the V1-compatible marker is never written.

Therefore this run cannot even reach the V2 activation question: on this beta service/API path, project-local .opencode/plugins/ discovery/execution itself is not observed for the exact project Location. This is stronger evidence that the current blocker is upstream of the Goals V2 adapter and upstream of the { id, setup } sentinel contract.

Stable V1 remains unchanged. The promotion gate stays blocked until a real OpenCode 2 host first proves project-local plugin discovery for the project Location, then activates a minimal V2 sentinel, and finally activates the Goals V2 adapter.

[ByBrawe]

OpenCode 2 promotion gate update (2026-08-18): current @opencode-ai/cli@next resolved to opencode2 v0.0.0-beta-17498 and failed the project-plugin activation gate on three separate attempts of the real-host PR canary before any new command-transform assertion could run. In every observed failure, the requested Location resolved to the correct non-global project directory/project ID, but project-scoped GET /api/plugin returned data: [], the minimal V2 sentinel ID was absent, and its setup() marker was not written. This is therefore treated as a current-beta activation blocker/regression, not evidence that command/request/control behavior works. PRs that depend on real V2 activation must remain unmerged/fail-closed until a same-host readiness probe or a newer beta proves activation reliably again. Stable V1 support and the <2 peer range remain unchanged.

[ByBrawe]

2026-08-18 — beta-17498 activation diagnosis refined: startup readiness race, not persistent regression

PR #87's same-service readiness probe changes the interpretation of the earlier data: [] failures. On the same opencode2 v0.0.0-beta-17498 server and same project Location:

• readiness attempt 1 returned an empty plugin registry and the sentinel marker was absent;
• after a bounded 500 ms delay, attempt 2 returned the normal plugin registry including bybrawe.opencode2-readiness-probe and the sentinel setup() marker was present.

So the earlier one-shot host canaries were observing the plugin registry before project-plugin initialization completed. This is not evidence that beta-17498 permanently lost project-local V2 activation.

Promotion should still fail closed, but the activation gate should be hardened to bounded same-service readiness polling before declaring activation failure. Historical one-shot data: [] results should be treated as early-readiness observations, not a persistent activation regression. Real Goals-adapter command/control behavior still needs its own end-to-end host proof after readiness is established.