You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Can the currently supported OpenCode v1.x plugin API observe successful Read, Write, Apply Patch, and LSP events and make newly matched durable rule content available before the immediately following provider dispatch in the same logical turn? Identify the exact hook and message APIs, mutability and persistence constraints, ordering and concurrency behavior, and any version-specific limitations. Contrast the result with the assumptions in feat: deliver rules at the earliest OpenCode v2 hook.
Yes, for successful built-in Read, Write, Apply Patch, and LSP calls, the supported OpenCode v1.x API can make newly matched durable content visible to the immediately following provider dispatch in the same logical turn. It requires a composition of existing v1 APIs rather than one purpose-built hook:
Observe the successful call in tool.execute.after and update a per-session, concurrency-safe pending set.
Before returning from that awaited hook, persist newly admitted durable content with client.session.prompt({ noReply: true, parts: [{ type: "text", synthetic: true, ... }] }).
Use experimental.chat.messages.transform as the next-dispatch guard: merge any still-pending content into its mutable messages output, then let OpenCode build the provider request.
This is viable throughout the repository's declared v1 range beginning at @opencode-ai/plugin 1.3.7. The exact current package/runtime combination was also checked: the repository declares peer compatibility from ^1.3.7 and development ranges from ^1.18.23; the local lock resolves plugin and SDK 1.18.23; and the installed OpenCode runtime reports 1.18.25. Relevant hook and prompt-loop source is unchanged between OpenCode 1.18.23 and 1.18.25.
Evidence
Successful tool input and output are visible
The v1 plugin contract gives tool.execute.after the tool name, session ID, call ID, and original args, plus mutable title, output, and metadata fields. It gives experimental.chat.messages.transform the mutable message/part array (plugin 1.18.23 hook types). The same required hooks already exist at the repository's minimum supported plugin version (plugin 1.3.7 hook types).
For registry-backed built-in tools, OpenCode awaits the tool implementation, constructs its model-visible result, and only then awaits tool.execute.after; a thrown/failed execution does not reach that after-hook (1.18.23 tool wrapper, 1.3.7 tool wrapper). Therefore:
Read matching can inspect the successful returned output text and path arguments.
Write matching can inspect the submitted content/path in args; the output confirms success.
Apply Patch matching can inspect successful args.patchText and the returned result.
LSP matching can inspect its operation/path arguments and successful returned output text.
This observes the result exposed to the model, including any truncation already performed by the tool. It does not reconstruct omitted file content or treat a failed tool attempt as an observation.
Ordering reaches the next dispatch
OpenCode awaits each plugin's hook sequentially in plugin load order and passes the same mutable output through the chain (1.18.23 trigger implementation; the 1.3.7 implementation is equivalent at lines 285-298). Event subscriptions are not suitable for this guarantee because event callbacks are not awaited in the same way.
After a tool step, the session loop starts its next iteration by reloading persisted messages. It then awaits experimental.chat.messages.transform, converts those mutated messages to model messages, and only afterward calls the processor/provider (1.18.23 loop, transform-to-dispatch sequence). Version 1.3.7 has the same ordering (transform-to-dispatch sequence). Because the tool wrapper awaits tool.execute.after, state mutation and awaited persistence complete before that tool result settles and before the continuation dispatch can be assembled.
experimental.chat.messages.transform is dispatch-local: OpenCode uses the mutated in-memory array to build provider messages but does not write those mutations back to session storage. It is therefore the correct immediate-visibility guard, not durable storage.
Durable synthetic persistence is available without another model turn
The official v1 SDK/server API accepts noReply on session.prompt; official documentation describes it as injecting context without an AI response (SDK session API, server message endpoint). In version-matched source, prompt creation persists the user message and parts, while noReply: true returns before entering the model loop (1.18.23 prompt flow, 1.3.7 prompt flow). Text-part input explicitly supports synthetic: true and metadata (1.18.23 schema).
Consequently, an awaited session.prompt call from tool.execute.after can persist a synthetic user text part without independently resuming the assistant. The running loop then reloads that message for its next dispatch. The plugin must mark and ignore its own synthetic message in chat.message, because synthetic admission itself invokes that hook before storage. A delivery ledger must only acknowledge the rule after persistence succeeds; on failure, the pending rule remains available for the transform/retry path.
Concurrency requires plugin-side coordination
OpenCode 1.18.23/1.18.25 uses AI SDK 6.0.168. That SDK intentionally starts tool executions without awaiting each one, tracks outstanding results, and closes the tool-result stream only after all have settled (AI SDK 6.0.168 execution scheduling, stream completion barrier). Thus multiple tool.execute.after callbacks for one provider response may overlap, but the next OpenCode dispatch waits for all tool-result executions to settle.
The plugin must serialize admission/persistence per session and deduplicate by durable rule identity. There is no v1 "all tools in this provider response completed" plugin hook, so the safe design is to admit each newly matched identity atomically as successful calls finish. All admitted messages are present before the next dispatch, but distinct concurrent matches are not guaranteed to be persisted as one synthetic message. In-memory state that is only eventually flushed, an unawaited SDK call, or an event handler cannot provide the timing guarantee.
Version and compatibility constraints
Repository contract: package.json declares @opencode-ai/plugin and @opencode-ai/sdk peers as ^1.3.7, and development ranges as ^1.18.23.
Minimum supported v1: 1.3.7 contains all three required APIs (tool.execute.after, experimental.chat.messages.transform, and prompt noReply) and the required ordering, so this finding does not inherently require raising the peer floor.
Current environment: the local dependency lock resolves plugin/SDK 1.18.23, while opencode --version reports 1.18.25. The relevant files have identical content in both tags; the official comparison contains no change to these seams.
experimental.chat.messages.transform remains explicitly experimental. Any OpenCode upgrade must re-verify its signature and ordering.
A later plugin in load order can mutate the same messages after this plugin. The guarantee assumes ordinary cooperative plugins, not a later hook deliberately removing the injected content.
The future ticket assumes a v2 session-context hook and a v2 synthetic-session operation as first-class seams. Those APIs are not present in the v2 Promise plugin surface shipped with OpenCode 1.18.23/1.18.25: its PluginContext exposes agent, AI SDK, catalog, command, integration, plugin, reference, and skill domains, but no session-context domain (v2 Promise PluginContext).
The v1 answer therefore does not validate those future v2 API names or semantics. It establishes that file-content matching need not wait for v2: v1 can meet the temporal and durability requirement by composing an after-hook, an awaited no-reply synthetic prompt, and the pre-dispatch message transform. The v2 ticket remains the place to replace that composition with a single authoritative context/persistence seam once OpenCode actually ships and versions those APIs.
Specification consequence
The file-content rule specification may require successful Read, Write, Apply Patch, and path-associated LSP observations to become durably available on the immediately following provider dispatch under OpenCode v1.x. It must also require per-session serialization, identity deduplication, retry-on-persistence-failure, self-synthetic-message suppression, and dispatch-local transform fallback. It must not require one persisted message per concurrent tool batch, because v1 exposes no batch-completion hook.
Activity
frap129 commentedon Aug 28, 2026
OpenCode v1.x next-dispatch durable delivery
Decision
Yes, for successful built-in Read, Write, Apply Patch, and LSP calls, the supported OpenCode v1.x API can make newly matched durable content visible to the immediately following provider dispatch in the same logical turn. It requires a composition of existing v1 APIs rather than one purpose-built hook:
tool.execute.afterand update a per-session, concurrency-safe pending set.client.session.prompt({ noReply: true, parts: [{ type: "text", synthetic: true, ... }] }).experimental.chat.messages.transformas the next-dispatch guard: merge any still-pending content into its mutablemessagesoutput, then let OpenCode build the provider request.This is viable throughout the repository's declared v1 range beginning at
@opencode-ai/plugin1.3.7. The exact current package/runtime combination was also checked: the repository declares peer compatibility from^1.3.7and development ranges from^1.18.23; the local lock resolves plugin and SDK 1.18.23; and the installed OpenCode runtime reports 1.18.25. Relevant hook and prompt-loop source is unchanged between OpenCode 1.18.23 and 1.18.25.Evidence
Successful tool input and output are visible
The v1 plugin contract gives
tool.execute.afterthe tool name, session ID, call ID, and originalargs, plus mutabletitle,output, andmetadatafields. It givesexperimental.chat.messages.transformthe mutable message/part array (plugin 1.18.23 hook types). The same required hooks already exist at the repository's minimum supported plugin version (plugin 1.3.7 hook types).For registry-backed built-in tools, OpenCode awaits the tool implementation, constructs its model-visible result, and only then awaits
tool.execute.after; a thrown/failed execution does not reach that after-hook (1.18.23 tool wrapper, 1.3.7 tool wrapper). Therefore:outputtext and path arguments.args; the output confirms success.args.patchTextand the returned result.outputtext.This observes the result exposed to the model, including any truncation already performed by the tool. It does not reconstruct omitted file content or treat a failed tool attempt as an observation.
Ordering reaches the next dispatch
OpenCode awaits each plugin's hook sequentially in plugin load order and passes the same mutable output through the chain (1.18.23 trigger implementation; the 1.3.7 implementation is equivalent at lines 285-298). Event subscriptions are not suitable for this guarantee because event callbacks are not awaited in the same way.
After a tool step, the session loop starts its next iteration by reloading persisted messages. It then awaits
experimental.chat.messages.transform, converts those mutated messages to model messages, and only afterward calls the processor/provider (1.18.23 loop, transform-to-dispatch sequence). Version 1.3.7 has the same ordering (transform-to-dispatch sequence). Because the tool wrapper awaitstool.execute.after, state mutation and awaited persistence complete before that tool result settles and before the continuation dispatch can be assembled.experimental.chat.messages.transformis dispatch-local: OpenCode uses the mutated in-memory array to build provider messages but does not write those mutations back to session storage. It is therefore the correct immediate-visibility guard, not durable storage.Durable synthetic persistence is available without another model turn
The official v1 SDK/server API accepts
noReplyonsession.prompt; official documentation describes it as injecting context without an AI response (SDK session API, server message endpoint). In version-matched source, prompt creation persists the user message and parts, whilenoReply: truereturns before entering the model loop (1.18.23 prompt flow, 1.3.7 prompt flow). Text-part input explicitly supportssynthetic: trueand metadata (1.18.23 schema).Consequently, an awaited
session.promptcall fromtool.execute.aftercan persist a synthetic user text part without independently resuming the assistant. The running loop then reloads that message for its next dispatch. The plugin must mark and ignore its own synthetic message inchat.message, because synthetic admission itself invokes that hook before storage. A delivery ledger must only acknowledge the rule after persistence succeeds; on failure, the pending rule remains available for the transform/retry path.Concurrency requires plugin-side coordination
OpenCode 1.18.23/1.18.25 uses AI SDK 6.0.168. That SDK intentionally starts tool executions without awaiting each one, tracks outstanding results, and closes the tool-result stream only after all have settled (AI SDK 6.0.168 execution scheduling, stream completion barrier). Thus multiple
tool.execute.aftercallbacks for one provider response may overlap, but the next OpenCode dispatch waits for all tool-result executions to settle.The plugin must serialize admission/persistence per session and deduplicate by durable rule identity. There is no v1 "all tools in this provider response completed" plugin hook, so the safe design is to admit each newly matched identity atomically as successful calls finish. All admitted messages are present before the next dispatch, but distinct concurrent matches are not guaranteed to be persisted as one synthetic message. In-memory state that is only eventually flushed, an unawaited SDK call, or an event handler cannot provide the timing guarantee.
Version and compatibility constraints
package.jsondeclares@opencode-ai/pluginand@opencode-ai/sdkpeers as^1.3.7, and development ranges as^1.18.23.tool.execute.after,experimental.chat.messages.transform, and promptnoReply) and the required ordering, so this finding does not inherently require raising the peer floor.opencode --versionreports 1.18.25. The relevant files have identical content in both tags; the official comparison contains no change to these seams.experimental.chat.messages.transformremains explicitly experimental. Any OpenCode upgrade must re-verify its signature and ordering.Contrast with feat: deliver rules at the earliest OpenCode v2 hook
The future ticket assumes a v2 session-context hook and a v2 synthetic-session operation as first-class seams. Those APIs are not present in the v2 Promise plugin surface shipped with OpenCode 1.18.23/1.18.25: its
PluginContextexposes agent, AI SDK, catalog, command, integration, plugin, reference, and skill domains, but no session-context domain (v2 PromisePluginContext).The v1 answer therefore does not validate those future v2 API names or semantics. It establishes that file-content matching need not wait for v2: v1 can meet the temporal and durability requirement by composing an after-hook, an awaited no-reply synthetic prompt, and the pre-dispatch message transform. The v2 ticket remains the place to replace that composition with a single authoritative context/persistence seam once OpenCode actually ships and versions those APIs.
Specification consequence
The file-content rule specification may require successful Read, Write, Apply Patch, and path-associated LSP observations to become durably available on the immediately following provider dispatch under OpenCode v1.x. It must also require per-session serialization, identity deduplication, retry-on-persistence-failure, self-synthetic-message suppression, and dispatch-local transform fallback. It must not require one persisted message per concurrent tool batch, because v1 exposes no batch-completion hook.