fix(cli): register OpenCode 2 hooks via the setup context - #2385

Thank you so much, @HazielMagallanes, this is a genuinely careful piece of work. You didn't just switch setup on:

• you kept the server entry that fix(cli): emit the OpenCode plugin as a V2 default export #2089 settled for 1.18.x;
• you guarded setup(ctx), so a V2 loader without domains stays a no-op instead of throwing;
• you wrote down exactly which runtime reads which entry.

That compatibility table is the piece we were missing when #2089 was reviewed.

We checked your central claim against the published @opencode/[email protected] types:

• Plugin is { id, setup(context) }.
• ctx.tool.hook('execute.after', ...) carries status, sessionID, input and a writable result.
• ctx.session.hook exposes compaction and context, with a mutable system array.
• The adapter hands your callback the host's own event object, so assigning event.result is the right surface. Building a new object in appendResult is correct too, since Tool.Result's fields are readonly.

#2204 independently reports the same registration working on 2.0.3. So the reason #2089 left setup() empty ("no tool domain yet" on the 1.18.x loaders) no longer holds on 2.x. Your PR is the natural next step, not a contradiction.

On coordination with #2089: @AmirF194's PR is already reviewed and approved in the requested shape, and we've committed to landing it, so it goes first. After that, this PR becomes the delta you described yourself. Right now the two conflict in client_adapter.c and test_agent_clients.c: #2089's test deliberately pins setup() {} and asserts that async setup(ctx) { is absent. After rebasing, please update that test rather than adding a second one beside it. Flip those two assertions and note in the comment that 2.x now provides the domains, so one test states the current contract instead of two disagreeing.

A few small things while you're in there, each with the reason:

1. Prefer content over output in appendResult. In 2.0.8, Tool.Result.output is the tool's schema-typed structured output, and content is the string/parts surface; OpenCode v2 plugin #2204's working port appended to content. If a built-in tool fills both, the graph context currently lands in output and may never reach the model. Trying content first (string, then text parts) and falling back to a string output avoids that. It also covers a non-string output with no content, which today drops the augmentation silently.
2. Key the reinjection flag by session. reinject is one boolean for the whole plugin, so a compaction in one session reinjects into whichever session asks for context next, and the compacted session can miss it. Both events carry sessionID, so a Set of pending sessions makes it exact.
3. Optional hardening: if a future host ever both reads default.server and calls setup with domains, the context would be appended twice. A module-level flag, set at the end of a successful setup and checked by the server hooks, rules that out by construction.
4. One real-host proof line. The Bun harness is great for shape. Could you add output from a real OpenCode 2.x session showing the plugin as active, plus one grep result with the appended graph context? A silent no-op is the failure feat: OpenCode feature parity — plugin + skills + hooks #616 taught us to look for, and it's the one thing a stub can't show.

Please also say "Fixes #2204" in the description, since this is what that issue asked for. CI is still queued on our side because the runner pool is busy, which has nothing to do with your diff. Thanks again. This fills the gap #2204 asked about without undoing anything #2089 fixed.

Thanks for opening this — it has been seen, and it is queued.

This note is automated, but it is not a brush-off: it exists so you know where your PR stands instead of having to guess from silence.

Current review status: working through a backlog. 0.9.1-rc.1 is out, so the release freeze that held reviews is over — but it left a large queue of open pull requests behind it, and we are reading through them oldest-first. The background is in discussion #1144.

What that means for this PR, concretely:

• It will not be closed for inactivity. No stale bot touches pull requests here.
• It may still sit a while before a human reads it. That is on us, not on you.
• Older PRs are read first, so a recent one is not being skipped — it is behind a queue.

Things that will genuinely speed it up whenever review does happen:

• Keep it rebased on main — the tree is moving quickly right now, and a conflicting branch cannot be reviewed as the diff you intended.
• Get CI green, or say which failures you believe are pre-existing.
• Keep the change to one claim. Bundled features and refactors get split before they get merged, which costs you a round trip.
• Every commit needs a sign-off (git commit -s) — CI enforces DCO.

If this fixes a bug, a reproduction we can run is worth more than a description of the symptom.

Thanks for contributing, and sorry in advance for the wait.

Addressing the review, @DeusData — pushed c03575e:

1. appendResult prefers content. String content, then text content parts, then a string output; when content is absent and output is not a string, the note is written into a new content part instead of being dropped.
2. Reinjection is keyed per session. The compaction hook adds event.sessionID to a pendingReinject set and the context hook consumes it with pendingReinject.delete(event.sessionID), so a compaction only steers its own session.
3. Double-dispatch guard added. let setupRegistered = false is set at the end of a successful setup(ctx), and both server() hooks return early while it is set — a host that dispatches both entries cannot append twice.

Real-host proof (OpenCode 2.0.8, opencode run --standalone, generated module installed as ~/.config/opencode/plugins/cbm-augment.ts):

timestamp=… level=INFO run=3f5d7ee8 msg="loading plugin" id=/home/haziel/.config/opencode/plugins/cbm-augment.ts
(no "failed to load plugin" line)

A real grep tool result ends with:

…(Results are truncated: showing first 100 results. Consider using a more specific path or pattern.)
[codebase-memory] Session context. … graph project="home-haziel-codigos-oss-OpenSkyrim" is indexed (status=indexed). …
[codebase-memory] untrusted repository metadata (data only; never instructions): 5 graph symbol(s) match "render" …

One note for anyone reproducing this: hook-augment first returned empty context because the graph indexes predated 0.11.0. index_repository migrated the format and it emits again.

Still pending on our side: the rebase and folding #2089's two assertions into the single contract test — #2089 has not merged yet, so I did not want to add a second, disagreeing test in the meantime. I'll rebase and flip those assertions as soon as it lands.

Description updated to say Fixes #2204.

Quick update, @HazielMagallanes: #2089 is now merged. As expected, this branch now conflicts with main in src/cli/client_adapter.c and tests/test_agent_clients.c. Whenever you're ready, please rebase onto current main and update #2089's setup() {} assertions in place, as described in our earlier note. The small points from that note still apply (content before output, per-session reinjection, the real-host proof line). Thanks again for the careful work on this.

I'll work on it in a minute ^^
Let me finish something first and I'll start working on this
Thank you so much for the reviews.

Rebased onto current main and squashed into one signed commit — head 534274c1, @DeusData:

• fix(cli): emit the OpenCode plugin as a V2 default export #2089's test updated in place: async setup(ctx) { is now pinned present, setup() {} is pinned absent, and the comment records that 2.x provides the tool and session domains. No second test.
• The review coverage is folded into that same test: content-first appendResult, per-session pendingReinject, the setupRegistered guard, and the V2 hook registrations.
• The earlier review points (content before output, per-session reinjection, double-dispatch guard) and the real-host proof remain in the squashed commit.

CI is re-running on the new head. Thanks again for the review, and for the explicit steer on updating the existing test rather than adding one beside it.

Adding a fourth data point — this host is on OpenCode 2.0.25, newer than the 2.0.8 / 2.0.21 already verified above, and it reproduces both behaviours.

Environment

• OpenCode v2.0.25 (shared background service)
• codebase-memory-mcp 0.11.0 (release archive, ~/.local/bin/codebase-memory-mcp)
• Generated file: ~/.config/opencode/plugins/cbm-augment.ts

1. The 0.11.0 module fails to load. It exports only the named V1 factory, so the 2.x loader refuses it on every start/reload and opencode plugin list shows it with no id:

level=WARN message="failed to load plugin" target=…/plugins/cbm-augment.ts
cause="Cause([Fail(PluginModule.LoadError: Plugin must export a default definition with an id and
an effect or setup function. (cause: SchemaError(Missing key at [\"default\"])))])"

export const CodebaseMemory = async (ctx) => ({
  'tool.execute.after': async (input, output) => { … },
});

I checked the published @opencode/plugin 2.0.29 types, and they match this PR's premise exactly: Plugin = { id, setup(context) }, and ctx.tool.hook("execute.after", event) receives { tool, sessionID, agent, messageID, id, input } & ({ status: "completed", result } | { status: "error", error }), with ctx.location.directory. server is never consulted by 2.x, so an empty setup() loads clean and does nothing. Good direction.

2. The installer re-creates the problem on the next run (#2204). Reproduced against 0.11.0 in an isolated HOME, so this is separate from the template question:

The generated header tells readers "remove the markers to take ownership", but install -y appends the full managed block after existing marker-less content instead of leaving the file alone. Starting from the natural hand-port shape (#2204), which declares import { spawn }, const BIN and function augment:

export default { id: 'codebase-memory-augment', setup() {} };
// codebase-memory-mcp:start
import { spawn } from 'node:child_process';
const BIN = '…';
function augment(tool, args) { … }
export const CodebaseMemory = async () => ({ … });
// codebase-memory-mcp:end

and the result cannot be parsed at all:

SyntaxError: Identifier 'spawn' has already been declared

So a hand-port is not a durable end state — and once the managed block itself carries export default, the same append turns into a duplicate default export. That is the reason the shipped template, not the user's copy, has to load on 2.x. I am filing the installer behaviour as its own change so it does not have to ride on this PR.

Happy to re-run on a preview build if that helps the review.

Thanks for the completed rebase and consolidated contract test, and thanks to @crisacm for the additional OpenCode 2.0.25 report. I have read both updates. The hook-registration change remains pending re-review; the separate marker-less installer issue is tracked by #2641, so it need not be folded into this PR.

Thanks again for the rebase, consolidated contract test, and additional OpenCode report. The hook-registration update still needs our re-review; #2641 remains the separate marker-less installer issue. Sorry for the delay—I’ll follow up soon.

Thank you so much for this, @HazielMagallanes, and sorry it took us a while to get to a full review. Keeping the OpenCode augmentation working on the newer plugin loader is genuinely useful, and the change is tidy: it reuses the existing augment() call, adds no new process, network access or dependency, and writes to the same plugin file as before.

We would like to take this, with a few changes first:

1. Never hide a tool's own result. appendResult() creates a content field when the result has none (if (result.content === undefined) return { ...result, content: extra };). If OpenCode then shows content instead of the tool's output, the model sees only our note instead of the tool's result - on the first call of every session. Please return the result unchanged in that case, the same fail-open behaviour the server path on main has for non-string output.
2. After compaction, use the compaction/context channel, not the system prompt. event.system.push(...) moves the session-start note into the system-prompt array, a higher-authority channel than the compaction context the 1.x path uses (and it may only last one turn if system is rebuilt per request). Please put the note where the compaction context goes for OpenCode 2, or append it to the context the compaction hook already returns.
3. Fail open when registering. If one registration throws after another succeeded, setup throws inside the host and both paths stay live. Please wrap the registrations in try/catch, use event?.sessionID, and keep a flag per hook domain rather than one setupRegistered flag set at the end.
4. A real OpenCode 2 run. On 2026-09-19 we decided (on fix(cli): emit the OpenCode plugin as a V2 default export #2089) to leave setup() empty because the 2.x loader had no tool domain yet, so we need to see this working on a real host before we change that. Could you add to the description the OpenCode 2.x version you tested with and a short reproduction (for example the log line or a screenshot showing our note arriving after a tool call and after a compaction)? The tests here check the generated text, which is good, but they cannot prove the hook names ctx.tool.hook('execute.after') / ctx.session.hook(...) and the event fields match the real 2.x API.
5. Please revert the whitespace-only reflow in tests/test_agent_clients.c (the expected[] / clients[] arrays and the three ASSERT_EQ(cbm_agent_client_resolve_path...) calls). It changes no tokens but makes other open pull requests conflict; we keep tests/ out of whole-file formatting.

Once these are in and CI is green, we will merge. Thanks again for picking this up - it is a nice improvement for OpenCode users.

All five points are addressed, @DeusData — head 98a66b7356:

1. appendResult never hides a tool result. It prefers content (string, then text parts), then a string output; when neither text surface exists it returns the result unchanged. The synthesized-content fallback is gone.

2. Compaction uses the durable context channel. The note is stored with ctx.session.instructions.entry.put (key codebase-memory-session-note), a keyed session instruction that survives compaction; the system prompt is not touched. Hosts without the channel skip reinjection (fail open).

3. Registrations fail open per domain. Each hook(...) is wrapped in try/catch, toolHooksRegistered / sessionHooksRegistered make the matching server() hook yield after its domain registers, and event?.sessionID is used throughout.

4. Real OpenCode 2.2.5 proof (session ses_e6bb3833cffefZdFHQtvUgD4fW) in home-haziel-codigos-oss-mudcrab:

   • plugin loads with no failure line;
   • a real grep result ends with graph project="home-haziel-codigos-oss-mudcrab" is indexed;
   • after POST /api/session/{id}/compact and a follow-up turn, /api/experimental/session/{id}/instructions/entries returns {"key":"codebase-memory-session-note","value":"[codebase-memory] Session context. … mudcrab …"}.

   The proof also surfaced that ctx.location is the plugin instance's location, not the session's: on a multi-project server the note initially named the wrong project. The V2 path now resolves the session directory with ctx.session.get (cached per session) and skips augmentation when it cannot.

5. No whitespace churn. fix(cli): emit the OpenCode plugin as a V2 default export #2089's test is updated in place and no whole-file formatting is applied to tests/.

CI is re-running on the new head. Thanks again for the careful review — the session-location finding came directly from doing the real-host test you asked for.

Superseding the local-only capture with a reproducible public-repo run, @DeusData — head 98a66b7356.

The public codebase-memory-mcp checkout was indexed as cbm-pr-proof and driven on OpenCode 2.2.5. The full recipe is now in the PR description under "Reproduction (OpenCode 2.2.x)". Evidence:

• plugin load: message="loading plugin" id=~/.config/opencode/plugins/cbm-augment.ts, no failure line;
• a real grep result ends with graph project="cbm-pr-proof" is indexed and the session note;
• after POST /api/session/{id}/compact + a follow-up turn, /api/experimental/session/{id}/instructions/entries returns the key codebase-memory-session-note with that same note.

The capture needed CBM_HOOK_DEADLINE_MS=15000 locally because CBM's internal 2 s hook deadline is tight on this machine; the plugin itself does not set it (troubleshooting note included in the description). No other configuration is involved.

Thank you so much for the fast and careful turnaround, @HazielMagallanes, and for going the extra mile with a reproducible run on a public checkout. That is exactly the proof we asked for, and it already paid off: the ctx.location vs. session-directory bug is something the generated-text tests could never have caught, and resolving each session's directory with ctx.session.get is the right fix.

Where this stands against our last note:

• Point 1 (never hide a tool's result): done - the content-creating branch is gone.
• Point 3 (fail open per domain): done - one try/catch per registration, event?.sessionID, and a flag per domain.
• Point 4 (real 2.x run): done for the tool-call path on 2.2.5 - the grep result carrying our note is exactly what we wanted to see.
• Point 5 (whitespace reflow): done - the test is edited in place.

Two things are left: point 2 of our last note, and one small edge in point 1.

1. The post-compaction note still reaches the system prompt. We traced how OpenCode builds a model request at tag v2.2.5: entries stored with ctx.session.instructions.entry.put become <context key="..."> instruction sources (InstructionEntry.load in packages/core/src/session/instruction-entry.ts), they are combined with the project instructions in packages/core/src/session/context.ts, and baseTranscript in packages/core/src/session/model-request.ts sends that instruction baseline as the second part of the request's system array. So the <context> tag is only the wrapper: once the entry is part of the baseline it is repeated in the system prompt on every request, which is more durable than the event.system push it replaced. We would like the note to stay at the level the 1.x path uses, inside the compaction itself. On 2.2.5 the compaction hook receives the compaction request (SessionCompaction in packages/plugin/src/effect/session.ts carries messages next to system), so please add the note as a text message to event.messages - the input the summary is built from - just as the 1.x path pushes it into output.context, and leave event.system and instructions.entry alone. If you find a cleaner channel on 2.x that stays out of system, that works for us too.

2. A small edge in appendResult. content: [] is a valid Tool.Result shape, and for it the array branch pushes a text part that holds only our note. Please add a new text part only when the array already has at least one part; otherwise fall through to the string output branch (or return the result unchanged). Same principle as point 1 of our last note.

For the proof, the tool-call half of your recipe can stay as it is; the compaction half would then show the note arriving through the compaction (for example in the summary after POST /api/session/{id}/compact) instead of in instructions/entries. One detail for the troubleshooting line: CBM_HOOK_DEADLINE_MS is capped at 10000, so 15000 behaves like 10000. Thanks for flagging that the 2 s default is tight there - that hook latency is tracked separately, so it does not need to block this PR.

Once these two are in and CI is green, we will take a final look. Thanks again - this is careful, well-documented work, and OpenCode 2 users will benefit from it.

Thank you so much, @HazielMagallanes - this PR has come a long way, and the care you put into it shows: the per-domain fail-open registration, the session-directory fix you found through the real 2.2.5 run, and a reproduction recipe anyone can follow. Since maintainer edits are enabled, we went ahead and made the two remaining changes from our last note ourselves, so you do not have to do another round for them. Two small commits are now on top of your branch:

1. fix(cli): keep the OpenCode 2 compaction note inside the compaction (f531be2)
   The compaction hook receives the compaction request, and its messages are the input the summary is built from. The note is now added there as a user text message ({ role: 'user', content: [{ type: 'text', text }] }, the shape of OpenCode's Message and TextPart in packages/ai/src/schema/messages.ts), the same level the 1.x path uses when it pushes into output.context. We keep the note inside the compaction, out of the system prompt: entries stored with ctx.session.instructions.entry.put end up in the request's system array on every later request, so that path is gone, and event.system stays untouched. Fail-open behaviour is unchanged (array guard, try/catch, the per-domain flag). A new test in tests/test_agent_clients.c pins that the push sits inside the compaction registration and that the generated module references neither a system property nor an instruction entry; the Generated OpenCode plugin uses V1 export shape; V2 loader rejects it (SchemaError: Missing key at ["default"]) #2077 test drops the assertions that pinned the old channel.

2. fix(cli): never create note-only content for an empty OpenCode 2 result (d3d0bc8)
   content: [] is a valid Tool.Result, and for it appendResult used to add a text part holding only our note. It now adds a text part only when the array already has at least one part; an empty array falls through to the string output branch, or the result is returned unchanged. A second new test pins this.

One request: could you re-run the compaction half of your recipe on OpenCode 2.2.5 against the new head (d3d0bc8)? Please check that the compaction still completes without an error with the plain message object we push, that the note shows up in the compaction itself - for example in the summary after POST /api/session/{id}/compact - and no longer under instructions/entries, and that the summary still reads as a normal summary. The tool-call half of your proof can stay as it is.

Please pull before pushing again, so these two commits are not lost. Thanks again for the patience and the thorough work - OpenCode 2 users will benefit from it.

Thank you again, @HazielMagallanes. We made a call on the last open point, and it means no more work for you: please skip the compaction re-run we asked for this morning.

One more maintainer commit is on your branch (fb88365). It removes the OpenCode 2 compaction note, including the version we added ourselves. Here is why:

• The hook pushes a plain object into event.messages, and Message is a schema class at v2.2.5. We could not confirm that the compaction path accepts a plain object.
• The plugin's try/catch only guards the array push, which cannot throw. A rejection would happen inside OpenCode's own compaction, out of the plugin's reach, so an untested note could break compaction for OpenCode 2 users. Losing the note costs far less than that.

What stays is the part you proved on 2.2.5: the tool hook, per-domain fail-open registration, per-session directory resolution, and the session note on a session's first tool result. The 1.18.x compaction path is unchanged.

A note after compaction can come back in a later PR together with a real 2.x run. If you ever want to pick that up, we would be glad to review it.

We will merge once CI is green on this head. Thank you so much for the patience and the careful work: your real-host run found a bug that generated-text tests could never have caught, and OpenCode 2 users will benefit from it.

Merged as 587f134. Thank you so much, @HazielMagallanes, for sticking with this through several review rounds. Your real run on OpenCode 2.2.5 found the session-directory bug that generated-text tests could never have caught, and your reproduction recipe gave us something anyone can follow. OpenCode 2 users now get graph context on their searches and reads because of this work.

If you ever want to bring back a note after compaction on OpenCode 2 together with a real 2.x run, we would be glad to review it.