Skip to content

OpenCode plugin: support the OpenCode 2.x plugin API, keep 1.x (#271) - #272

Merged
lukemaj merged 1 commit into
mainfrom
opencode-2-plugin-support
Nov 18, 2026
Merged

lukemaj merged 1 commit into
mainfrom
opencode-2-plugin-support

Conversation

@lukemaj

@lukemaj lukemaj commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

What changed: The OpenCode Project Direction plugin now loads on OpenCode 2.x and still works on 1.x, delivering Project Direction and enforcing the Elon gate on both.
Why: OpenCode 2.x only loads a default object with id and setup, so the 1.x-shaped plugin was skipped and 2.x sessions ran silently without it.
So what: Needs independent review, then the user's merge; after merge the release and local install follow under repository policy.

Closes #271.

Change

opencode/agentsmd-project-direction.js default-exports {id, server, setup} and nothing else.

Purpose OpenCode 1.x (unchanged) OpenCode 2.x (new)
Load {id, server}; server(ctx) returns hooks {id, setup}; setup(ctx) registers hooks; server ignored
Directory ctx.directory / ctx.worktree ctx.location.directory
System prompt experimental.chat.system.transform, push strings to output.system ctx.session.hook("context"), push {type:"text", text} to input.system
Elon gate tool.execute.before (input.tool, output.args), throw to block ctx.tool.hook("execute.before") (input.tool, input.input), throw to block

Nothing was left unported: 2.x has a real pre-execution hook, and a throw there fails the tool call before it runs. 1.18.32 and 1.19.6 also call setup, with a reduced context lacking session/tool; setup returns without registering in that case so 1.x is not double-injected.

Proof

  • Profile complete proof on d6c4514: python3 -m unittest discover -s tests -p 'test_*.py' 515 OK; versionctl suite OK; versionctl release-check --sha d6c4514… OK (v17.5.0).
  • Node seam tests now drive both server (1.x) and setup (2.x): payload byte-equality, routing pointer, outside-repo verdict, installed link, unreachable/failing loader, export shape, reduced-context no-op; Elon gate blocks/allows/fails closed through both paths.
  • Isolated real CLI, scratch HOME/XDG, OpenCode 2.x with --standalone, local oMLX gemma-4-26B-A4B-it-heretic-5bit, zero paid spend, fixture repo with Objective "Grow heliotrope in the fixture garden.":
    • 2.3.2: model quoted the Objective from the injected block; shell call gh issue create --title t --body hi failed with AgentsMD blocked \gh issue create`: every Issue needs an Elon record…`.
    • 1.19.6: same two results through bash.
    • 1.18.32: the {id, server, setup} shape probe loaded, injected system text and blocked a bash call (probe plugin, not this file).
    • Before: 2.3.2 rejected a function default: Plugin must export a default definition with an id and an effect or setup function. (cause: SchemaError(Expected object at ["default"])).
  • Website impact: none; toolboxmd/toolbox.md code search finds no OpenCode mention.

Limits

  • 2.x Code Mode routes inner tool calls through the same execute.before trigger per the 2.3.2 binary; no live run exercised a gh call made inside execute.
  • Some 1.19.6 runs stalled past my time cap; it happened with main's plugin too, and one sampled stall was idle waiting on the shared local model. Not reproduced as a plugin defect.
  • bin/agentsmd-opencode run stays pinned to 1.18.32 (non-goal).
  • User Live Verification on real 2.x work is pending.

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 runtime version switch; the old supportedOpenCodeVersion function property became a list on the default object.
  • Bottleneck: 2.x default-export schema; settled by a probe before coding.
  • Checked myself: Read @opencode/plugin 2.3.2 types and the 2.3.2/1.19.6 loaders; ran this plugin on 2.3.2 and 1.19.6 in scratch dirs with the local model; ran the full suite.

🤖 Generated with Claude Code

OpenCode 2.x loads only a default object with `id` and `setup`, so the
1.x-shaped plugin was skipped and sessions ran without Project Direction
or the Elon gate. The default export is now `{id, server, setup}`:
1.x calls `server` with the existing hooks; 2.x calls `setup`, which
appends the loader context through `session.hook("context")` and runs
the Elon gate from `tool.hook("execute.before")`. `setup` does nothing
in the reduced context 1.x also passes it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@lukemaj

lukemaj commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

What: Independent review found no blocking defects at d6c4514.
Why: Both plugin paths preserve the required context delivery and pre-execution gate wiring, and the focused suite passes.
So what: Review passes with the non-blocking notes below; final merge remains with the user.

Reviewed against main 23e0674. Read Issue #271 in full, the complete PR diff, surrounding plugin/tests/docs, and the base plugin. No repository edits, OpenCode/model runs, or paid calls.

Findings

  • Non-blocking, test coverage: tests/test_opencode_plugin.py:45 slices off the host system prefix without asserting its preservation, and successful context cases (:163, :183, :214) invoke the hook once. A faulty callback that overwrites the existing prefix, or stops appending after the first successful request, could escape. Add an explicit unchanged-prefix assertion and two successful requests. Current code uses push on every callback (opencode/agentsmd-project-direction.js:216), so this is a proof gap, not an observed implementation defect.
  • Non-blocking, test coverage: tests/test_elon_gate.py:1264 exercises blocked/allowed issue creation, harmless commands, and blocked REST issue creation through both plugin APIs, but not gh pr create or REST pulls. A plugin-specific PR-only bypass could escape these seam tests even though direct loader tests cover PRs. Current forwarding is generic and the loader is unchanged, so this does not block the port.
  • Non-blocking, wording: docs/opencode.md:155 describes the default export as {id, server, setup}; opencode/agentsmd-project-direction.js:238 also includes supportedOpenCodeVersions. Clarifying “with version metadata” would make the description literal. This remains one default object with no other module exports, and no host incompatibility is established.

Blocking findings: none. Verdict: PASS.

Correctness and scope

The 1.x server hooks retain the previous directory/session selection, string payload ordering and gate argument mapping (opencode/agentsmd-project-direction.js:171). The extracted helper preserves loader-then-routing behavior. On 2.x, setup checks both hook interfaces before doing anything (:200), silently returns on the reduced 1.x context, selects location.directory, registers session.hook("context"), and appends {type:"text", text} parts (:216). tool.hook("execute.before") forwards input.tool and input.input (:224); a denial throws. Missing-loader candidate calls fail closed through the shared spawn error path (:131). Published @opencode/plugin@2.3.2 declarations were also checked during delegated review for these registration/input shapes; this was a declaration inspection, not a compiler or live-host check.

README.md and docs/opencode.md describe the two paths and tested versions consistently, apart from the metadata shorthand above. VERSION, all five declared mirrors, and CHANGELOG consistently use 17.5.0. A minor bump fits a backward-compatible capability addition. bin/agentsmd-opencode, plugin installation, and bin/project-direction are unchanged, matching the Issue non-goals.

Falsifiability of the changed tests

These are concrete faulty implementations each test would reject, by assertion inspection; mutation runs were not performed:

  • test_triad_repository_payload_reaches_the_system_prompt (tests/test_opencode_plugin.py:163): missing/truncated loader context, wrong directory, omitted routing/reminder, or malformed 2.x text parts.
  • test_directory_outside_a_repository_carries_the_loader_verdict (:183): using the plugin/repository directory instead of the supplied outside directory.
  • test_default_export_serves_both_plugin_apis (:199): function default, additional named module export, incorrect ID, or missing server/setup function.
  • test_installed_link_resolves_the_canonical_loader (:214): resolving loader paths relative to the installed link instead of canonical source.
  • test_setup_without_session_and_tool_hooks_registers_nothing (:228): dereferencing absent hooks, logging, or returning a value on the reduced context.
  • test_unreachable_loader_leaves_the_system_prompt_unchanged (:247): injecting fabricated payload on loader absence or omitting the diagnostic.
  • test_failing_loader_leaves_the_system_prompt_unchanged_and_logs_once (:257): accepting failed context-loader output or repeating diagnostics over two callbacks.
  • test_opencode_plugin_fails_closed_without_loader (tests/test_elon_gate.py:1254): silently allowing candidate creates when the loader is missing.
  • test_opencode_plugin_throws_on_blocked_call (:1264): ignoring gate denials, reading the wrong API argument field, rejecting a valid record/harmless command, or dropping REST issue creation.

Observed proof and limits

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest tests.test_opencode_plugin tests.test_elon_gate ran in the supplied worktree on the exact head: 95 tests in 148.025s, OK, no skips reported. I inspected the delegated command output. git diff --check 23e0674 d6c4514 passed; worktree status remained clean. Review scratch was removed.

GitHub validate passed, but its log is version validation on the PR merge candidate, not the full behavioral suite on this exact head. The PR records the requested isolated CLI evidence and full-suite result; those are author-reported and were not rerun in this review under the explicit no-OpenCode limit. User behavioral Live Verification remains pending.

@lukemaj

lukemaj commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Agent cost: agent-observer publish --task toolboxmd/agentsmd#272 --pr 272 reported "nothing to publish: no sessions in scope", so no cost comment is posted. Review notes (prefix preservation, gh pr create through the plugin seam, export wording) are left as non-blocking.

@lukemaj
lukemaj merged commit cbe8032 into main Nov 18, 2026
2 checks passed
@lukemaj
lukemaj deleted the opencode-2-plugin-support branch November 18, 2026 11:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

1 participant