Skip to content

OpenCode plugin: support OpenCode 2.x plugin API while keeping 1.x #271

Closed

Description

@lukemaj

What: The OpenCode Project Direction plugin loads and works on OpenCode 2.x as well as 1.x.
Why: OpenCode 2.x only loads plugins whose default export is {id, setup}, so the current 1.x-shaped plugin is skipped and sessions run silently without Project Direction or the Elon gate.
So what: An agent ports the plugin in one PR with deterministic tests and an isolated real-CLI check; the user merges, then the release and install follow under repository policy.

Outcome

opencode/agentsmd-project-direction.js delivers the loader context and operations pointer to the system prompt, and blocks gh create calls that fail the Elon check, on OpenCode 2.x and on the 1.x versions already supported (1.18.32 pin, 1.19.6 installed on rocky). The user is moving machines to OpenCode 2 (decision 2026-11-18).

Evidence (measured 2026-11-18)

  • OpenCode 2.3.2 (@opencode/cli) rejects the current plugin: Plugin must export a default definition with an id and an effect or setup function. (cause: SchemaError(Expected object at ["default"])). A function default is rejected even when it carries id and setup properties.
  • 2.x hook API (@opencode/plugin 2.3.2 types): ctx.session.hook("context", cb) exposes mutable system: SystemPart[] and messages; ctx.tool.hook("execute.before", cb) runs before a tool executes, and the host maps a thrown error to a Tool.Error.
  • Isolated probe (scratch HOME/XDG, --standalone, local oMLX model): on 2.3.2 a default object {id, server, setup} loaded; setup's context hook text reached the model, and a throw in execute.before stopped echo ... > marker.txt (no file written; model saw the error). On 1.18.32 and 1.19.6 the same object loaded through the v1 module form: server hooks injected the system text and blocked the bash call. 1.x also calls setup with a reduced context that has no session or tool, so setup must no-op there.

Acceptance criteria

  • One module, default export {id, server, setup}, no other exports.
  • 1.x path (server) keeps today's behavior and tests.
  • 2.x path (setup) appends the loader payload and the routing pointer to system on every context hook, and forwards gh create/api shell calls to the loader's PreToolUse gate from tool.hook("execute.before"), throwing on block and failing closed when the loader cannot run.
  • setup without session/tool hooks (1.x host) registers nothing and logs nothing.
  • Node seam tests cover both paths; docs state supported versions.
  • Isolated real-CLI check on 2.3.2 and 1.19.6 recorded on the PR.

Non-goals

  • Changing the bounded run adapter (bin/agentsmd-opencode run), which stays pinned to the 1.x CLI.
  • Changing plugin install or the loader.
  • Installing anything into ~/.config/opencode or a global OpenCode.

Blockers

None.

Required proof

python3 -m unittest tests.test_opencode_plugin tests.test_elon_gate tests.test_opencode, the full suite, versionctl release-check, plus the isolated real-CLI runs above.

Elon record

  • Requirements and who asked: User: plugin works on OpenCode 2.x and keeps 1.x working; map every hook, report anything unportable.
  • Deleted: A second 2.x-only plugin file and a version switch: one object serves both hosts, since each ignores the other's key.
  • Bottleneck: 2.x default-export schema; settled by the probe.
  • Checked myself: Read @opencode/plugin 2.3.2 types and the 2.3.2/1.19.6 loader code; ran the probe plugin on 2.3.2, 1.19.6 and 1.18.32 in scratch dirs with the local model.

Activity

  1. added a commit that references this issue on Nov 18, 2026
  2. lukemaj commented on Nov 18, 2026

    @lukemaj
    ContributorAuthor

    Delivered. Merged: PR #272 as cbe8032 (head d6c4514, CI validate pass, review/independent success). Released: v17.5.0 (release workflow 44290722329 success). Marketplace: toolboxmd/marketplace#212 merged, v1.5.145. Installed on rocky, cavallo, bestia: clone at v17.5.0; Claude Code, Codex, Grok, Muse at 17.5.0; inspect healthy valid-stable-link for all five harnesses; Muse hooks trusted_enabled. The installed OpenCode plugin link on each machine delivered ready direction and blocked gh issue create through both server (1.x) and setup (2.x) in a Node driver. All three machines run OpenCode CLI 1.19.6; no OpenCode 2 is installed yet. Behavioral Live Verification on OpenCode 2 is pending, user-owned. Runbook: lukemaj/runbook b0803cc.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions