Follow up OpenCode upstream updates: notification/permissionDenied hook mappings, references key, V2 beta tracking

[dyoshikawa]

Summary

Three OpenCode drifts as of v1.18.14: two canonical hook events (notification, permissionDenied) have faithful upstream plugin counterparts but are unmapped, and the stable references config key — a genuine context-provisioning surface — has no rulesync coverage. Additionally, the OpenCode V2 beta restructures nearly every key rulesync emits and deserves a tracking note.

Canonical repo note: sst/opencode 301-redirects to anomalyco/opencode (same repository id). Latest stable at research time: v1.18.14 (2026-08-05).

Recent Releases

• v1.18.14 (2026-08-05) — latest stable — https://github.com/anomalyco/opencode/releases
• v1.17.4 (2026-06-12) — MCP cwd for local servers (already followed).
• v1.17.1 (2026-06-10) — reference renamed to references (gap 3 below).
• V2 beta — separate opencode2 binary via @opencode-ai/cli@next — https://opencode.ai/v2/docs (gap 4).

Gaps

1. hooks — canonical notification unmapped despite tui.toast.show

• Upstream: the plugin API exposes tui.toast.show (payload: message, variant info/success/warning/error, optional title, duration) — https://opencode.ai/docs/plugins/
• rulesync (project, global): notification is mapped for many other tools but absent from OPENCode_HOOK_EVENTS (src/types/hooks.ts:323) and CANONICAL_TO_OPENCODE_EVENT_NAMES (:1115), so OpenCode users get no plugin stub for it.
• Follow-up: add notification to the event set and map it to tui.toast.show.

2. hooks — canonical permissionDenied unmapped despite permission.replied

• Upstream: permission.replied carries sessionID, requestID, and reply ("once" | "always" | "reject"), so denial is distinguishable — https://opencode.ai/docs/plugins/
• rulesync: maps permissionRequest → permission.asked but nothing to permission.replied.
• Follow-up: gate on reply === "reject" using the same mechanism as SHELL_EVENT_TOOL_GATES in src/features/hooks/opencode-style-generator.ts. Because KILO_HOOK_EVENTS aliases the OpenCode set (src/types/hooks.ts:345), this lands for Kilo too.

3. rules — the references config key has no coverage

• Upstream: references (stable V1; renamed from deprecated reference in v1.17.1) maps an alias to a local path or a git repository (+ branch), with description and hidden; entries carrying a description are injected into the agent's system context automatically — a context-provisioning surface alongside instructions, not just autocomplete. https://opencode.ai/docs/references/
• rulesync: writes instructions into opencode.json but never touches references.
• Follow-up: discretionary — decide whether rulesync should author references (most likely via a tool-scoped opencode section). This is a new capability rather than a fix.

4. Forward-looking — V2 beta restructures nearly every emitted key

Per https://opencode.ai/v2/docs/migrate-v1: permission/tools → ordered permissions array, agent → agents, command → commands, plugin → plugins, reference → references, agent prompt → system, disable → disabled, permission actions bash → shell / task → subagent, MCP enabled → inverted disabled, timeout split into timeout.catalog/timeout.execution. V1 config is not auto-migrated and the binary is separate (opencode2), so this would be a new target id, not a change to the existing adapters. Track; do not implement while the APIs are marked unstable.

Proposed Follow-up

1. Map notification → tui.toast.show and permissionDenied → gated permission.replied (fixes Kilo simultaneously).
2. Decide on references authoring.
3. Keep a watch on V2 GA for an opencode2 target.

References

• https://opencode.ai/docs/plugins/ — TUI events + permission events (gaps 1–2)
• https://opencode.ai/docs/references/ — references key (gap 3)
• https://opencode.ai/v2/docs/migrate-v1 — V2 rename table (gap 4)
• https://opencode.ai/config.json — published JSON schema used to verify the non-gaps
• https://github.com/anomalyco/opencode/releases — release dating

[dyoshikawa]

Gaps 1 and 2 are resolved in #2617 (merged).

• notification -> tui.toast.show and permissionDenied -> permission.replied, both verified against anomalyco/opencode v1.18.14 (packages/schema/src/tui-event.ts and packages/schema/src/v1/permission.ts) and listed as subscribable plugin events in the plugins docs. permission.replied fires for every reply, so the generated handler is gated on event.properties.reply === "reject".
• One deliberate asymmetry: notification landed for OpenCode only. Kilo's plugin docs enumerate the same events except that they document no TUI section at all, so emitting tui.toast.show into a Kilo plugin risked a hook that never fires - the same failure mode as the old command.executed mapping. KILO_HOOK_EVENTS now filters it out. Happy to add it if Kilo documents TUI events later.

Not addressed, and why:

• Gap 3 (references authoring) is discretionary and needs a design decision on the authoring shape first.
• Gap 4 (the V2 GA gate) has not fired - the latest release is still 1.18.14, so there is nothing to follow yet.

[dyoshikawa]

Upstream update (re-check on 2026-08-13)

Window: v1.15.0 (2026-05-15) → v1.18.18 (2026-08-13). Gaps 1 and 2 confirmed fixed by #2617; gap 3 (references) and gap 4 (the V2 GA gate, still unfired) unchanged. One gap not recorded here:

Additional gap

permissions — experimental.policies (provider-access control) cannot be authored.

opencode.json accepts experimental.policies[], each statement { effect: "allow" | "deny", action: "provider.use", resource: <wildcard> }. Last match wins, the default is allow, and the global config takes precedence over project, so a repo cannot re-enable a provider its user config denies. Docs: https://opencode.ai/docs/policies/ — page added 2026-05-30 alongside "feat(core): add location-scoped config loading" (#29625, shipped around v1.15.13). Typed in https://opencode.ai/config.json as ConfigV2.Experimental.Policy.

rulesync is project + global for permission only. OpencodePermissions.fromRulesyncPermissions builds patch: { permission }, and the OpenCode override block is OpencodePermissionsOverrideSchema = looseObject({ permission }) (src/types/permissions.ts:99), so nothing else reaches opencode.json.

Worth being precise about the severity: this is an authoring gap, not a clobbering one. applySharedConfigPatch merges onto the parsed existing document and replaces only declared owned keys, so a hand-written experimental.policies survives generate untouched. What a user cannot do is express it from .rulesync/permissions.jsonc.

Proposed follow-up: let the opencode permissions override carry experimental.policies — model the three fields and keep action open for future actions — and emit it into opencode.json at both scopes, which also means adding experimental to the file's ownedKeys in shared-config-gateway.ts. Caveat for the maintainer: the surface is explicitly experimental upstream, so following it now is a judgement call rather than a straight parity fix — it sits in the same discretionary bucket as gap 3.

One refinement to gap 3

The singular reference key is now marked @deprecated in the published schema. rulesync emits neither spelling, so there is no deprecated-surface exposure to clean up — the decision on gap 3 is purely "should rulesync author this at all", with no migration pressure attached. If the answer is no, recording that explicitly would stop it resurfacing every research pass.

Verified unchanged

Re-checked against the published schema and the docs with no drift: MCP (local/remote, environment, cwd, enabled, headers, oauth, timeout, tool filters), commands (variant reaches the file via passthrough), subagents (the loose schema round-trips steps / hidden / color), skills (all five frontmatter fields; the skills.paths / skills.urls config keys add extra folders and remote catalogs but do not affect the default .opencode/skills discovery rulesync writes into), and hooks — the v1 flat plugin shape is unchanged, and the v1.17.10 "namespaced / V2 plugin API" additions are additive (chat.message and experimental.session.compacting are both still exported from packages/plugin/src/index.ts).

One item checked specifically because the docs and the schema disagree: the action-only permission keys (webfetch, websearch, todowrite, question, doom_loop). The permissions prose says webfetch "matches the URL" and websearch "matches the query", which reads like object-rule support, but config.json still types both as PermissionActionConfig — scalar only. OPENCODE_ACTION_ONLY_PERMISSION_KEYS collapsing a map with a warning matches the schema, which is the right authority here. Not a gap; recording it so the docs wording does not get re-filed as one.

References

• https://opencode.ai/docs/policies/ — the experimental.policies statement shape and the global-over-project precedence (the new gap)
• https://opencode.ai/config.json — ConfigV2.Experimental.Policy, and the @deprecated marking on singular reference
• https://opencode.ai/docs/plugins/ — re-verified that the v1 flat hooks shape is unchanged

[dyoshikawa]

Upstream update (re-check on 2026-08-23)

Newly found releases / changes

Canonical repo note: sst/opencode 301-redirects to anomalyco/opencode (same repo id 975734319); the releases feed is identical.

Version	Date	URL
v1.18.21 (latest stable)	2026-08-21	https://github.com/sst/opencode/releases/tag/v1.18.21
v1.18.20	2026-08-21	https://github.com/sst/opencode/releases
v1.18.19	2026-08-20	https://github.com/sst/opencode/releases
v1.18.18	2026-08-13	https://github.com/sst/opencode/releases
v1.18.17	2026-08-12	https://github.com/sst/opencode/releases
v1.18.16	2026-08-10	https://github.com/sst/opencode/releases
v1.18.15	2026-08-07	https://github.com/sst/opencode/releases

The whole v1.18.15 → v1.18.21 window is provider/model/desktop/retry bugfixes — no config-key, file-location, or feature-surface change. Cross-checked against the doc sources: rules.mdx, skills.mdx, agents.mdx, plugins.mdx, commands.mdx, permissions.mdx, mcp-servers.mdx, and references.mdx have had no commits since 2026-08-06 (the latest relevant is config.mdx, 2026-08-07, a TUI cursor key). One release-note item worth knowing: v1.18.16's "Ignore unknown top-level config fields instead of failing config parsing" makes rulesync's config writes strictly safer, not a gap.

V2 is still beta with no GA — @opencode-ai/cli dist-tags show beta: 0.0.0-beta-18027, and the migration guide still says "OpenCode 2.0 is in beta… the server and plugin APIs may continue to change." Gap 4's "track only" stance stands unchanged.

The four gaps below therefore came from grounding the feature dimensions against the released type/schema artifacts rather than from the changelog diff. None appear on this issue, #2501, #2400, or #2230.

Additional or changed gaps

New: hooks — session.deleted is unmapped even though canonical sessionDelete already exists

session.deleted (payload { sessionID, info }) is a documented plugin event (Session Events), and it is live in the released artifacts, not just dev: @opencode-ai/sdk@1.18.21 dist/gen/types.gen.d.ts:506 declares type: "session.deleted", the schema source is packages/schema/src/v1/session.ts:589, and a bundled first-party plugin consumes it (packages/opencode/src/plugin/openai/codex.ts:285).

rulesync has the canonical event already: sessionDelete (src/types/hooks.ts:210), mapped for Qwen Code as "SessionDelete" (src/types/hooks.ts:1681). It is absent from both OPENCODE_HOOK_EVENTS (src/types/hooks.ts:325-341) and CANONICAL_TO_OPENCODE_EVENT_NAMES (:1257-1280), so the same sessionDelete hook emits fine for qwencode and is silently dropped for OpenCode.

Proposed follow-up: add "sessionDelete" to OPENCODE_HOOK_EVENTS and sessionDelete: "session.deleted" to the name map. This is a plain event.type dispatch needing no generator change — exactly like the session.compacted / session.error / file.watcher.updated entries added from #2400.

New: hooks — command.execute.before is unmapped even though canonical userPromptExpansion already exists

"command.execute.before"?: (input: { command, sessionID, arguments }, output: { parts }) => Promise<void> is a mutable named hook that runs on the expanded slash-command parts immediately before submission. It is in the released @opencode-ai/plugin@1.18.21 (dist/index.d.ts:228) and actually fired at packages/opencode/src/session/prompt.ts:1461 — plugin.trigger("command.execute.before", { command, sessionID, arguments }, { parts }) — right before prompt(...) and before command.executed is published.

rulesync's userPromptExpansion (src/types/hooks.ts:198) is documented as "a mutation-only hook that runs on the transformed prompt" (:505-510) and is mapped for Qwen Code (UserPromptExpansion) and Copilot CLI (userPromptTransformed, :1370). OpenCode has no entry.

Worth being precise about the relationship to #2501: that issue removed the afterShellExecution → command.executed mis-mapping, i.e. the after-the-fact slash-command event. command.execute.before is the distinct pre-submission named hook, and #2501 explicitly deferred it ("If observing slash commands is wanted, that needs its own canonical event") — the canonical event turns out to already exist.

Proposed follow-up: add "userPromptExpansion" to OPENCODE_HOOK_EVENTS, userPromptExpansion: "command.execute.before" to the name map, and "command.execute.before": "input.command" to NAMED_HOOK_MATCHER_SUBJECTS (src/features/hooks/opencode-style-generator.ts:17-22) — unlike chat.message / experimental.session.compacting, this hook does expose a matchable subject (the command name), so matchers can be honored rather than dropped. Document the scope difference from beforeSubmitPrompt → chat.message: this one fires only for slash commands.

New: hooks — chat.params is unmapped even though canonical preModelInvocation already exists

"chat.params"?: (input: { sessionID, agent, model, provider, message }, output: { temperature, topP, topK, maxOutputTokens, options }) ships in the released @opencode-ai/plugin@1.18.21 (dist/index.d.ts:203) and is triggered on every LLM request — main agent and subagents alike — at packages/opencode/src/session/llm/request.ts:114-131, immediately before the provider call. It is stable, outside the experimental. namespace.

rulesync's preModelInvocation (src/types/hooks.ts:163) is mapped for Goose (pre_llm_call, :1003), Kiro (PreInvocation, :1185) and Pi (context, :1312), but not OpenCode, so such a hook produces nothing for opencode.

Proposed follow-up: add "preModelInvocation" plus preModelInvocation: "chat.params", with "chat.params": "input.agent" as the matcher subject (the agent name is the only stable string in the input). The postModelInvocation sibling has no good counterpart — the closest is experimental.text.complete, which fires per completed text part and is explicitly experimental — so it is better left unmapped than mapped inaccurately.

Shared-constant caution for all three: KILO_HOOK_EVENTS is derived from OPENCODE_HOOK_EVENTS (src/types/hooks.ts:353) and CANONICAL_TO_KILO_EVENT_NAMES is CANONICAL_TO_OPENCODE_EVENT_NAMES (:1289-1290), so each addition lands in Kilo too. Kilo's plugin docs need checking per event before widening the shared constant; the notification precedent shows the filter mechanism already exists.

New: config — .opencode/opencode.json(c) is a real project config location rulesync neither reads nor writes, and it overrides the root file

Any directory ending in .opencode is scanned for opencode.json and opencode.jsonc (packages/opencode/src/config/config.ts:424-433), and that loop runs after the root project-config merge (:405-409) — so .opencode/opencode.json takes precedence over ./opencode.json. This matches the documented precedence order (4. Project config → 5. .opencode directories) and the bundled customize-opencode skill, which lists "Project config | ./opencode.json, ./opencode.jsonc, or .opencode/opencode.json" (packages/core/src/plugin/skill/customize-opencode.md, updated 2026-08-13 by PR #42337).

rulesync probes neither: readOpencodeConfig (src/features/opencode-config.ts:34-51) resolves only join(outputRoot, ".") + opencode.jsonc → opencode.json (or ~/.config/opencode/ in global mode) via getOpencodeConfigDir (:24-32), with no .opencode/ candidate. The dry runs confirm the write side: project writes opencode.json at the repo root, global writes ~/.config/opencode/opencode.jsonc, never .opencode/opencode.json.

Effect for a project that keeps its config in .opencode/opencode.json: rulesync import silently sees no MCP servers, permissions, inline commands, or agents; and rulesync generate writes mcp, permission, and instructions into a root opencode.json that the existing .opencode/opencode.json then overrides — a silent no-op for conflicting keys, with no warning.

Proposed follow-up: extend getOpencodeConfigDir / readOpencodeConfig to also probe .opencode/opencode.jsonc and .opencode/opencode.json on read (project scope only — the global tree has no .opencode sub-directory), and at minimum warn on generate when a .opencode/opencode.json(c) exists alongside the root file rulesync is about to write, since it wins.

Status of the gaps already tracked here

• Gaps 1 and 2 are already implemented on main. notification: "tui.toast.show" and permissionDenied: "permission.replied" (gated on event.properties.reply === "reject") are live at src/types/hooks.ts:1272 / :1271 and src/features/hooks/opencode-style-generator.ts:41-43.
• Gap 3 (references) is still uncovered — grep references src/features/opencode-config.ts src/features/rules/opencode-rule.ts returns no hits.
• Gap 4 (V2) is correctly still "track only"; see the beta status above.

Verified non-gaps this cycle (recorded so they are not re-filed)

• permission.ask is declared in @opencode-ai/plugin@1.18.21 (dist/index.d.ts:225) as a decision hook with a mutable output.status, which would look like a higher-fidelity permissionRequest target than the read-only permission.asked event. It is dead code: a full grep of the dev tree finds exactly one occurrence — the type declaration itself — and the live plugin.trigger names are experimental.chat.messages.transform, experimental.chat.system.transform, experimental.session.compacting, experimental.compaction.autocontinue, experimental.text.complete, chat.params, chat.headers, chat.message, command.execute.before, tool.execute.before/after, shell.env, tool.definition. The current permissionRequest → permission.asked mapping is correct.
• todo.updated carries the whole todo array (packages/schema/src/session-todo.ts:17-23), so created-vs-completed cannot be distinguished without diffing prior state. Not a faithful target for canonical todoCreated/todoCompleted; deliberately left unmapped.
• MCP — McpLocalConfig (type/command/cwd/environment/enabled/timeout) and McpRemoteConfig (type/url/headers/oauth/enabled/timeout), both additionalProperties: false, plus McpOAuthConfig (clientId/clientSecret/scope/callbackPort/redirectUri) — unchanged since Follow up OpenCode upstream updates: {enabled}-only MCP entries abort import, 4 unmapped plugin hook events, skills.paths on import #2400 and fully covered by OpencodeMcpLocalServerSchema / OpencodeMcpRemoteServerSchema plus OPENCODE_PASSTHROUGH_SERVER_FIELDS = ["timeout","oauth"] (src/features/mcp/opencode-mcp.ts:78). The { enabled: false } toggle arm from Follow up OpenCode upstream updates: {enabled}-only MCP entries abort import, 4 unmapped plugin hook events, skills.paths on import #2400 is implemented (:86-97).
• Permissions — the published PermissionConfig key set is exactly read/edit/glob/grep/list/bash/task/external_directory/todowrite/question/webfetch/websearch/lsp/doom_loop/skill with open additionalProperties for MCP tool names; unchanged since Follow up OpenCode upstream updates: permission agent category must map to task; deprecated tools gating; subagent color/steps/hidden #2230/Follow up OpenCode upstream updates: {enabled}-only MCP entries abort import, 4 unmapped plugin hook events, skills.paths on import #2400.
• Subagents — AgentConfig still exposes model/variant/temperature/top_p/prompt/tools(deprecated)/disable/description/mode/hidden/options/color/steps/maxSteps(deprecated)/permission; nothing new.
• Skills — the five recognized frontmatter fields (name, description, license, compatibility, metadata) match OpenCodeSkillFrontmatterSchema (src/features/skills/opencode-skill.ts:25-42) exactly, and Follow up OpenCode upstream updates: {enabled}-only MCP entries abort import, 4 unmapped plugin hook events, skills.paths on import #2400's skills.paths import gap is implemented (:116-148).
• Directory naming — config.mdx explicitly states the plural forms (agents/, commands/, plugins/, skills/, …) are canonical with singular kept for back-compat; rulesync's plural choices are correct and it keeps singular as an alternative import root.
• Rules — instructions (including remote URLs with a 5s timeout) and the global ~/.config/opencode/opencode.json instructions are unchanged; Follow up OpenCode upstream updates: afterShellExecution mapped to slash-command event (also kilo), global non-root rules dropped #2501's global non-root gap is fixed (the global dry run writes .config/opencode/memories/*.md plus .config/opencode/opencode.jsonc).
• ignore / checks — still correctly unsupported; watcher.ignore remains a file-watcher key, not an AI-context ignore surface.

References

• https://github.com/sst/opencode/releases — release feed; v1.18.21 (2026-08-21) is latest stable and v1.18.15–21 contain no config-surface change.
• https://opencode.ai/docs/plugins/ — the documented plugin event list; source for session.deleted and confirmation that named hooks are documented only through the plugin package types.
• @opencode-ai/plugin@1.18.21 dist/index.d.ts (npm) — the released type surface: command.execute.before (:228), chat.params (:203), permission.ask (:225, dead).
• @opencode-ai/sdk@1.18.21 dist/gen/types.gen.d.ts:506 — session.deleted in the released event union.
• sst/opencode@dev packages/opencode/src/session/prompt.ts:1461 — the live command.execute.before trigger.
• sst/opencode@dev packages/opencode/src/session/llm/request.ts:114-131 — the live chat.params trigger on every LLM call.
• sst/opencode@dev packages/opencode/src/config/config.ts:405-433 — .opencode/opencode.json(c) discovery and its post-root merge order.
• https://opencode.ai/docs/config/ — the documented precedence order corroborating the .opencode/ gap, and the plural-directory note.
• https://opencode.ai/config.json — the published schema used to re-verify MCP, permissions, agent, command, skills, and references key shapes.
• https://opencode.ai/v2/docs/migrate-v1 — V2 still beta with no GA; gap 4's tracking note stands unchanged.
• fix(skills): Update global config path in documentation anomalyco/opencode#42337 — the v1.18.19 skills-config-path doc fix that confirms .opencode/opencode.json as a project config location.

[dyoshikawa]

Upstream update (re-check on 2026-08-25)

Latest release: v1.18.23 (2026-08-25). Repository note for future passes: sst/opencode now redirects to anomalyco/opencode; rulesync carries no sst/opencode string anywhere, so there is nothing to re-point.

Sources fetched cleanly this run: https://opencode.ai/config.json (the published schema), the rules, agents, commands, skills, plugins, permissions, policies, references and tools doc pages, the GitHub releases API for anomalyco/opencode, and npm @opencode-ai/plugin and @opencode-ai/sdk at both 1.14.25 and 1.18.23 — the version diff between those two packages is what dates several findings below.

Additional or changed gaps

1. permissions — canonical write and notebookedit are written into opencode.json where OpenCode ignores them (silent no-op).

Permissions docs: "edit — file modifications including edit, write, patch". The schema's PermissionConfig names exactly read, edit, glob, grep, list, bash, task, external_directory, todowrite, question, webfetch, websearch, lsp, doom_loop, skill — there is no write and no notebookedit. Source-confirmed: packages/opencode/src/tool/write.ts declares permission: "edit".

rulesync: project + global, but src/features/permissions/opencode-permissions.ts translates only agent → task via CANONICAL_TO_OPENCODE_PERMISSION_KEYS, and isSharedPermissionCategory keeps write and notebookedit in the shared block. Reproduced: a .rulesync/permissions.jsonc with {"bash":{"*":"ask"}, "write":{"*":"deny"}, "notebookedit":{"*":"deny"}, "agent":{"*":"deny"}} generated "write": {"*":"deny"} and "notebookedit": {"*":"deny"} verbatim (agent correctly became task). Because additionalProperties is permitted, OpenCode validates the file and then never consults those keys — so a user's write: deny does not block writes. Follow-up: add write → edit to the translation table, merging with any existing canonical edit entry using the existing deny > ask > allow precedence and mirroring it on import so edit does not round-trip into two canonical keys; warn-and-drop notebookedit the way other unmappable categories are handled.

2. permissions — experimental.policies (provider access control) is unsupported.

Policies, doc page added 2026-05-30: experimental.policies: [{effect: "allow"|"deny", action: "provider.use", resource: <providerID|glob>}]. Last matching statement wins, global policies take precedence over project policies (a repo cannot re-enable a globally denied provider), and the default is allow. rulesync: unsupported — not modeled anywhere; it survives an existing opencode.json only because the config schemas are loose objects. Follow-up: decide explicitly whether provider-resource policy belongs under rulesync's permissions feature (it is access control, but over providers rather than tools) or stays out of scope. It is experimental.* and OpenCode-only, so an opencode: override block under permissions is the low-risk shape if adopted. Low priority.

3. hooks — the dispose plugin hook has no canonical mapping.

v1.15.11 (2026-05-27) — "Added a dispose hook for plugins." Confirmed present in @opencode-ai/plugin@1.18.23 dist/index.d.ts (dispose?: () => Promise<void>) and absent from @opencode-ai/plugin@1.14.25, so it is genuinely new in this window. rulesync: OPENCODE_HOOK_EVENTS (src/types/hooks.ts:325) has 15 entries and omits sessionEnd, the nearest canonical counterpart. Follow-up: map canonical sessionEnd → dispose and add it to OPENCODE_HOOK_EVENTS — and to KILO_HOOK_EVENTS, which is derived from it, only if Kilo documents the same hook.

4. hooks — four canonical events have OpenCode counterparts rulesync does not emit (standing rather than new, included for the diff): sessionDelete → session.deleted; userPromptExpansion → command.execute.before (named hook, (input:{command,sessionID,arguments}, output:{parts}), present in both 1.14.25 and 1.18.23); preModelInvocation → chat.params (and chat.headers), the mutable pre-LLM-call hooks; and todoCreated / todoCompleted → todo.updated, which is a single upstream event and therefore lossy — that one may be a deliberate omission. Follow-up: add the first three; treat todo.updated as a separate decision.

While verifying that list, the existing notification → tui.toast.show and permissionDenied → permission.replied mappings were confirmed correct against current upstream. permission.asked and permission.replied are both defined in packages/schema/src/v1/permission.ts; their absence from the published @opencode-ai/sdk v1 types.gen.d.ts is generator lag, not a removal. The reply payload is {sessionID, requestID, reply: "once"|"always"|"reject"}, matching rulesync's generated gate event.properties.reply === "reject" in src/features/hooks/opencode-style-generator.ts:42.

5. hooks — concrete V2 surfaces behind this issue's "V2 beta tracking" item.

v1.17.10 (2026-06-24) — "Added namespaced plugin hook APIs" and "Added the V2 plugin API for Effect and Promise plugins." @opencode-ai/plugin@1.18.23 ships dist/v2/promise/* and dist/v2/effect/* with registration modules for agent, command, skill, reference, catalog, integration and context. Separately, @opencode-ai/sdk@1.18.23 adds a ~40-event session.next.* family (session.next.tool.called/success/failed, .shell.started/ended, .compaction.started/ended, .step.started/ended/failed, .prompted, .prompt.admitted, .retried, .agent.switched, .model.switched, .revert.staged/committed/cleared, …) that is absent from 1.14.25 and lives only in dist/v2/gen/types.gen.d.ts, not the v1 Event union — so it is not reachable from a v1 plugin today.

rulesync emits a v1-shape plugin (generateOpencodeStylePluginCode), which remains correct. Two concrete follow-ups this surface would unlock once V2 stabilizes, worth recording now: beforeShellExecution / afterShellExecution could map to real session.next.shell.started/ended instead of the current tool.execute.before/after gated on input.tool === "bash", and postToolUseFailure — canonical, currently unmapped for OpenCode — gets a real counterpart in session.next.tool.failed.

6. subagents — subagent_depth is unmodeled, and its default silently disables subagent nesting.

v1.18.2 (2026-07-15) — "Stopped subagents from launching nested subagents by default, with a configurable subagent_depth limit when needed." Schema: top-level subagent_depth: integer, "Maximum subagent nesting depth. Defaults to 1, which prevents subagents from launching subagents." rulesync: unsupported — no way to express it, so rulesync-generated subagents that assume nesting now behave differently on OpenCode ≥ 1.18.2 than on Claude Code. Follow-up: at minimum treat it as an opencode: override key under subagents; a canonical cross-tool concept is probably not warranted. Related and already fine: permission.task with per-subagent-name globs works today because rulesync passes task object maps through unchanged.

7. skills — skills.paths and skills.urls config keys are unsupported.

https://opencode.ai/config.json carries a top-level skills: {paths: string[] ("Additional paths to skill folders"), urls: string[] ("URLs to fetch skills from, e.g. https://example.com/.well-known/skills/")}; source at packages/core/src/v1/config/skills.ts. Remote skill caching shipped around v1.17.12 (2026-06-30) ("Refresh cached remote skills", "Preserve skill resource paths"). These keys are not documented on the skills page — they are schema-only. rulesync: unsupported; skills are written only to the canonical roots. Low priority since rulesync authors into the default roots anyway; worth an opencode: override key only if users ask for extra roots.

8. rules — the references sub-surfaces are newer than this issue's one-word mention, and reference is now formally deprecated.

References, doc page added 2026-06-10. Keys per entry: path (local, relative/absolute/~), repository (git URL, host/path, or owner/repo), branch, description, hidden. Referenced roots and their descriptions are injected into agent system context, so this is a rules-adjacent surface rather than only a TUI convenience. What is new: description and hidden landed in v1.17.1 (2026-06-10) ("References can include usage descriptions for agents… and be hidden from @ autocomplete when needed"), and the same release deprecated reference in favor of references — the published schema now annotates reference as @deprecated Use 'references' field instead. rulesync: unsupported for both spellings. Follow-up if adopted: emit only the references spelling, read both on import, and carry description / hidden through since they change what the agent sees.

9. subagents / commands — new documented frontmatter fields are not in rulesync's declared schemas (minor). Upstream AgentConfig adds hidden, color (hex or theme token), steps (with maxSteps now @deprecated) and variant; upstream command config adds variant; and tools is now @deprecated Use 'permission' field instead. rulesync's OpenCodeSubagentFrontmatterSchema declares description, mode, name, model, temperature, top_p, prompt, disable, tools, permission and OpenCodeCommandFrontmatterSchema declares description, agent, subtask, model. Both are loose objects, so the new fields round-trip without data loss — this is a stale declared-surface gap, not a correctness bug. Follow-up: add the four fields to the subagent schema and variant to the command schema, and note tools's deprecation in the existing comment.

Verified unchanged this run

• mcp — cwd (v1.17.4, 2026-06-12) is already in OpencodeMcpLocalServerSchema; timeout and oauth (including the newer callbackPort / redirectUri / scope from the v1.16.x line) are preserved by OPENCODE_PASSTHROUGH_SERVER_FIELDS; the bare {enabled: false} toggle arm matches the schema's third union member. No gap.
• ignore — OpenCode still ships no ignore-file surface for agent access. Ignore patterns documents a .ignore file, but it is ripgrep's un-ignore mechanism (re-including gitignored paths in grep/glob) — the opposite of what rulesync's ignore feature expresses. The real restriction surface is permission.read deny patterns plus external_directory, which rulesync already emits. unsupported stays correct.
• checks — no upstream code-review-check file convention. unsupported stays correct.
• paths — docs confirm the plural .opencode/agents/, .opencode/commands/, .opencode/skills/ and the ~/.config/opencode/ global root, matching src/constants/opencode-paths.ts. Global opencode.jsonc auto-creation is handled by rulesync's JSON/JSONC fallback, which the global dry run exercised.

Dry runs: project emits AGENTS.md and opencode.json (permissions), with ignore and checks skipped by the processor gate; global emits 6 rules, 1 MCP, 5 subagents, 41 skills, 1 hooks plugin and 1 permissions file.

References

• https://opencode.ai/config.json — the published schema; the authority for PermissionConfig's key list (gap 1), experimental.policies (gap 2), subagent_depth (gap 6), skills.paths/skills.urls (gap 7), and the deprecation annotations in gaps 8–9.
• https://opencode.ai/docs/permissions/ — "edit — file modifications including edit, write, patch" (gap 1).
• https://opencode.ai/docs/policies/ — provider policy semantics and precedence (gap 2).
• https://opencode.ai/docs/references/ — the references entry keys, including description and hidden (gap 8).
• https://opencode.ai/docs/tools/#ignore-patterns — the .ignore un-ignore mechanism, cited for why ignore stays unsupported.
• https://www.npmjs.com/package/@opencode-ai/plugin — 1.14.25 vs 1.18.23 diff dating dispose (gap 3) and the V2 API (gap 5).
• https://www.npmjs.com/package/@opencode-ai/sdk — 1.14.25 vs 1.18.23 diff establishing the session.next.* family (gap 5).
• https://github.com/anomalyco/opencode — the current repository, after the sst/opencode redirect.

[dyoshikawa]

Upstream update (re-check on 2026-09-08)

Window: v1.18.24 (2026-08-28) → v1.18.29 (2026-09-04), i.e. everything after the 2026-08-25 pass (v1.18.23).
Latest stable is v1.18.29, 2026-09-04.

Newly found releases / changes

Version	Date	Content
v1.18.29	2026-09-04	Codex OAuth model filtering — no config surface
v1.18.28	2026-09-04	Copilot interaction header, desktop — no config surface
v1.18.27	2026-09-02	provider header/chunk timeout defaults, Anthropic thinking.blockBinding opt-out
v1.18.26	2026-09-01	provider/desktop bugfixes
v1.18.25	2026-08-28	Azure auth bugfix
v1.18.24	2026-08-28	"V1 now reads supported V2 config fields so newer config files keep working in more mixed setups."

Only v1.18.24 touches a surface rulesync owns. It ships PR #45421
(merged 2026-08-27), adding packages/opencode/src/config/v2-compat.ts — present at tag v1.18.24, absent at
v1.18.23 — wired into every config source load (packages/opencode/src/config/config.ts:189) and the config
update path (:665). ConfigV2Compat.lower() now accepts these V2 spellings inside a plain V1 opencode.json(c):

V2 field in a V1 file	Lowered to
mcp.servers envelope (what opencode2 mcp add writes)	flat mcp.<name>
global mcp.timeout {startup, catalog, execution}	per-server timeouts
per-server timeout object, disabled, codemode, snake_case oauth.client_id/client_secret/callback_port/redirect_uri	V1 server fields
agents (plural)	agent
commands (plural, entries keyed template)	command
skills: string[]	skills.paths / skills.urls
experimental.subagent_depth	subagent_depth
snapshots, media, compaction.keep.tokens, compaction.buffer, object model	V1 equivalents
top-level permissions, or any agent permissions	throws — the whole config fails to load

Corroboration that nothing else moved in the window: @opencode-ai/plugin 1.18.23 vs 1.18.29 has a byte-identical
dist/ (only package.json differs), so no hook additions; @opencode-ai/sdk differs only in
dist/v2/gen/types.gen.d.ts; rules.mdx, skills.mdx, agents.mdx, plugins.mdx, commands.mdx,
permissions.mdx, mcp-servers.mdx, references.mdx and policies.mdx have no commits since 2026-08-20; and
packages/core/src/v1 carries only the two provider-timeout commits. V2 is still beta
(npm view @opencode-ai/cli dist-tags → latest: 0.0.0-beta-17823), so gap 4 stays "track only".

Additional or changed gaps

All five below follow from v1.18.24 and are reproduced against main @ ec15feb with this fixture opencode.json:

{ "mcp": { "servers": { "github": { "type": "local", "command": ["gh-mcp"], "disabled": false } },
           "timeout": { "startup": 30000, "execution": 60000 } },
  "agents": { "reviewer": { "description": "rev", "mode": "subagent", "system": "You review." } },
  "commands": { "ship": { "template": "ship it", "description": "Ship" } } }

1. mcp — a V2 mcp.servers envelope or a global mcp.timeout aborts the whole MCP import.
OpencodeConfigSchema types mcp as z.record(z.string(), OpencodeMcpServerSchema)
(src/features/mcp/opencode-mcp.ts:132-137), whose union has no arm for either shape, and the OpencodeMcp
constructor uses .parse() (:458). rulesync import --targets opencode --features mcp prints
Failed to load MCP files for tool target: opencode: Zod raw error: […"path":["mcp","servers"]…"path":["mcp","timeout"]…]
and imports nothing — the same failure class as the {enabled}-only entry from #2400.

2. mcp — a per-server object timeout fails the run outright. With
{"type":"remote","url":"…","timeout":{"startup":5000,"execution":30000}}, import exits 1 with
"path": ["mcpServers","api","timeout"], "message": "Invalid input: expected number, received object" —
rulesync's canonical MCP schema types timeout as a number.

3. mcp — generate silently deletes a V2 mcp.servers envelope and global mcp.timeout. This is the one
worth prioritising: it is data loss, not just a missed read. The generate path uses safeParse
(src/features/mcp/opencode-mcp.ts:554); when it fails, the existing mcp block is discarded and
applySharedConfigPatch rewrites the whole owned mcp key. Running
rulesync generate --targets opencode --features mcp over the fixture with one rulesync server produced:

{ "mcp": { "local-fs": { "type": "local", "command": ["npx","-y","fs-mcp"], "enabled": true } },
  "agents": { … }, "commands": { … } }

The github server and the timeout block are gone, with no warning. (agents/commands survive only
because rulesync does not own those keys.) Minimum fix: teach the mcp union about the envelope and the two
timeout shapes; failing that, refuse to rewrite mcp when the existing block did not parse.

4. subagents / commands — the V2 agents and commands keys are not read on import. The same fixture yields
No command files found for opencode. Skipping import. and No subagent files found for opencode. Skipping import.
asOpencodeEntries(config.agent) (src/features/subagents/opencode-subagent.ts:210) and
asOpencodeEntries(config.command) (src/features/commands/opencode-command.ts:196) read the singular keys only,
while OpenCode V1 now loads both spellings (agents entries use system/disabled; commands entries key the
body as template).

5. skills — a V2 flat skills: ["./path", "https://…"] array yields no import roots.
getConfiguredImportRoots calls asOpencodeEntries(config.skills) (src/features/skills/opencode-skill.ts:132-134),
and asOpencodeEntries returns null for arrays (src/features/opencode-config.ts:59-64), so the array form —
which V1 now lowers into skills.paths/skills.urls — is skipped where the object form is honoured. Minor next
to 1–3.

Non-gap checked while here: a flat {type:"local", command:[…], disabled:true} imports as canonical
disabled: true and regenerates as "enabled": false. Correct. Also note the hard-throw row above — a top-level
permissions array kills the whole config on V1 — but rulesync emits only permission, and its OpenCode
permissions patch is { permission } (src/features/permissions/opencode-permissions.ts:294), so there is no
exposure.

Status of the gaps already tracked here

Verified against main @ ec15feb; nothing has moved since 2026-08-25. Gaps 1–2 remain implemented
(src/types/hooks.ts:1315-1316). Still open: gap 3 (references — grep of opencode-config.ts /
opencode-rule.ts returns nothing); gap 4 (V2 GA, unfired); experimental.policies; subagent_depth;
skills.paths/skills.urls authoring; write→edit and notebookedit translation
(CANONICAL_TO_OPENCODE_PERMISSION_KEYS is still { agent: "task" }); hook events sessionDelete,
userPromptExpansion, preModelInvocation, sessionEnd(dispose) — OPENCODE_HOOK_EVENTS still has the same
15 entries; .opencode/opencode.json(c) discovery (readOpencodeConfig, src/features/opencode-config.ts:34-51);
and the declared subagent (hidden/color/steps/variant) and command (variant) frontmatter fields.

Dry runs this pass: project emits AGENTS.md + opencode.json (permissions), ignore/checks gated off; global
emits 56 files (6 rules, 1 MCP, 5 subagents, 42 skills, 1 hooks plugin, 1 permissions file).

References

• https://github.com/anomalyco/opencode/releases/tag/v1.18.24 — "V1 now reads supported V2 config fields…" (2026-08-28)
• feat(opencode): load supported v2 config in v1 anomalyco/opencode#45421 — the V2-compat adapter, merged 2026-08-27
• packages/opencode/src/config/v2-compat.ts @ v1.18.29 — lowering rules and the permissions hard-throw; absent at v1.18.23
• packages/opencode/src/config/config.ts:189,665 @ v1.18.29 — where lower() runs
• https://github.com/anomalyco/opencode/releases — v1.18.25–29 dating (provider/desktop only)
• https://www.npmjs.com/package/@opencode-ai/plugin — 1.18.23 vs 1.18.29 dist/ identical, so no hook changes
• https://www.npmjs.com/package/@opencode-ai/cli — latest: 0.0.0-beta-17823; V2 still beta
• https://opencode.ai/v2/docs/migrate-v1 — the V1→V2 rename table these V2 spellings come from

[dyoshikawa]

Triaged in an autonomous backlog run (2026-09-12); leaving this open as inconclusive rather than acting on it.

Re-checked against current main: OpencodeConfigSchema still types mcp as a flat record<name, server> (src/features/mcp/opencode-mcp.ts), so the V2 spellings v1.18.24 started lowering (mcp.servers envelope, global mcp.timeout, per-server object timeout, plural agents / commands, flat skills array) are still unread on import and not preserved on generate. Note that the generate-side drop is the existing ownership rule — rulesync rewrites the whole mcp key, so a hand-written V1 server is replaced the same way — rather than something specific to the V2 envelope.

What a maintainer needs to decide before any of this is implemented:

1. Whether rulesync should read (and preserve) V2 config spellings inside a V1 opencode.json(c) at all while V2 is still beta, or keep targeting the V1 shape only and wait for GA.
2. If yes, how a global mcp.timeout object and a per-server timeout object map onto the canonical number-typed timeout, and how mcp.servers is disambiguated from a server literally named servers.
3. Whether the stable references key gets rulesync coverage, and under which feature.

No PR was opened and nothing was closed.

[dyoshikawa]

Upstream update (re-check on 2026-09-12)

Newly found releases / changes

• OpenCode V2 is GA and now owns the opencode command — the "V2 GA gate" (gap 4) has fired. Tags v2.0.0 (2026-09-11), v2.0.1 and v2.0.2 (2026-09-12) exist at https://github.com/anomalyco/opencode/tree/v2.0.2 (tags only; no GitHub Release objects yet), and npm @opencode/cli / @opencode/plugin / @opencode/sdk / @opencode/server all have latest = 2.0.2 (2.0.0 published 2026-09-11T23:44Z, 2.0.2 at 2026-09-12T07:54Z). V2 renamed its binary from opencode2 to opencode on the beta branch (bb564f96, alias kept by 0f26ad87), and the V2 curl installer (opencode.ai/v2/install) replaces the V1 binary. Docs: https://opencode.ai/v2/docs/ and https://opencode.ai/v2/docs/migrate-v1/.
• V2 reads the same config locations as V1 (~/.config/opencode/opencode.json(c), <project>/opencode.json(c), <project>/.opencode/opencode.json(c)) and normalizes V1 field shapes in memory (permission → permissions, flat mcp → mcp.servers, subtask → subagent, legacy agent fields), so most rulesync output keeps working. The three intentional breaks are the plugin API, the server API and the TUI config. Two documented non-compat behaviours hit rulesync output directly (see below).
• v1.18.30 (2026-09-09) — https://github.com/anomalyco/opencode/releases/tag/v1.18.30 — V1 maintenance, provider/model only; @opencode-ai/plugin dist byte-identical to 1.18.29, config.json schema unchanged. Nothing new beyond what the 2026-09-08 comment records for v1.18.24–1.18.29.

Additional or changed gaps

1. rules — V2 does not load instructions, so rulesync's non-root rules are silently dropped (project + global). https://opencode.ai/v2/docs/instructions/ and https://opencode.ai/v2/docs/config/: the instructions array is accepted for V1 compatibility "but V2 does not currently resolve its files, glob patterns, or URLs"; V2 discovers only ~/.config/opencode/AGENTS.md, AGENTS.md from the cwd upward, and nested AGENTS.md lazily when the agent works in a subdirectory (the CLAUDE.md fallback is gone). rulesync writes non-root rules to .opencode/memories/*.md / ~/.config/opencode/memories/*.md and registers them only through opencode.json instructions (rules-processor.ts:757-770, mcpInstructionsRegistrar: OpencodeMcp + mcpInstructionsRegistrarGlobal: true), with ruleDiscoveryMode: "toon" leaving the root AGENTS.md without any reference to them — verified in this repo's own opencode.json / AGENTS.md. Under a default V2 install every non-root rule is unreachable. Proposed: for opencode, emit the TOON reference block into the root AGENTS.md even when the registrar runs (or fold non-root rules into the root, as codexcli/crush do), and keep the instructions registration for V1 users; optionally honour agentsmd.subprojectPath to emit nested AGENTS.md files that V2 discovers lazily. The docs say "does not currently resolve", so this may be temporary upstream, but V2 is the default install today.
2. hooks — the generated V1 plugin does not run in OpenCode V2 (project + global). https://opencode.ai/v2/docs/migrate-v1/ ("Plugins"): "V1 plugin implementations do not run in V2. Moving a file or renaming its config entry is not enough." V2 plugins are Plugin.define({ id, setup(ctx) }) from @opencode/plugin, with ctx.tool.hook("execute.before" | "execute.after"), ctx.shell.hook("create.before"), ctx.permission.hook("evaluate"), ctx.session.hook("prompt" | "context" | "compaction" | …) and ctx.event.subscribe(...) (https://opencode.ai/v2/docs/build/plugins/). Local plugins are still discovered from .opencode/plugin/ and .opencode/plugins/. rulesync's opencode-style-generator.ts (exportStyle: "named", wrapInExportShape) emits export const RulesyncHooksPlugin = async ({ $ }) => ({ event, "tool.execute.before", … }) into .opencode/plugins/rulesync-hooks.js; V2 loads the file but no hook fires. The V2 plugin doc explicitly describes a dual-mode export — export default { ...Plugin.define({ id, setup }), async server(input) { /* V1 */ } } — noting the V1 object form is accepted from 1.18.29 (readV1Plugin, verified at v1.18.30) and that "sharing an export does not translate V1 hooks into V2 hooks". Proposed: switch the OpenCode output to that dual-mode default export, with a V2 setup(ctx) branch mapping preToolUse/postToolUse → ctx.tool.hook("execute.before"/"execute.after"), beforeShellExecution → ctx.shell.hook("create.before"), permissionRequest → ctx.permission.hook("evaluate"), beforeSubmitPrompt → ctx.session.hook("prompt"), preCompact → ctx.session.hook("compaction"), and the remaining events (sessionStart, stop, afterFileEdit, afterError, fileChanged, notification, permissionDenied, postCompact) → ctx.event.subscribe(...). Open questions before implementing: whether V2's setup(ctx) exposes a $-style shell runner for the await $\…`hook bodies, whether a plain object withoutPlugin.define/ the@opencode/plugindependency is accepted by the V2 loader (rulesync emits dependency-free.js), and the exact V2 event type names for ctx.event.subscribe— none of these were confirmed against@opencode/plugin@2.0.2` typings in this pass.
3. meta — gap 4's "separate binary → likely a new target id" premise no longer holds. V2 shares the command name, the config paths and (via normalization) the V1 field shapes, while V1 ≤ 1.18.30 throws on an unknown top-level permissions key, so native V2 spellings cannot be emitted unconditionally while V1 users remain. Suggested re-plan: treat V2 as a compatibility mode of the existing opencode target — fix items 1–2 now (they break today's default install), make import accept native V2 spellings (already tracked here: mcp.servers, plural agents/commands, flat skills, timeout objects, .opencode/opencode.json(c) discovery — all now higher priority since V2 users following the migrate guide hit them immediately), and defer native V2 output until the V1 floor can be dropped or add an opt-in (e.g. targets.opencode.configFormat: "v2"). Native V2 spellings for reference: permissions as an ordered {action, resource, effect} array with bash→shell, task→subagent, write/patch→edit (doom_loop, lsp, list, todowrite are not V2 actions); agents system / disabled / permissions / model#variant / request.body / steps; commands subagent (subtask deprecated alias); mcp.servers + disabled + timeout: { startup, catalog, execution }; flat skills: []; plugins: [{ package, options }]; nested command/agent IDs (commands/team/review.md → /team/review).
4. skills — V2 slash / metadata.opencode/slash / metadata.opencode/autoinvoke frontmatter not carried (project + global). https://opencode.ai/v2/docs/skills/: a skill may set top-level slash: true|false or metadata.opencode/slash to control exposure as a /skill command and metadata.opencode/autoinvoke to opt out of auto-invocation; a single-file skills/<name>.md form is also accepted, and .claude/skills / .agents/skills are still scanned. OpencodeSkill.fromRulesyncSkill copies only license / compatibility / metadata / allowed-tools, so a top-level slash is dropped (metadata.opencode/* passes through via metadata). Proposed: add slash?: boolean to the OpenCode skill frontmatter schema with passthrough, and document the metadata.opencode/* keys. No need to emit the flat .md form.
5. commands — accept subagent on import as an alias of subtask now; emit subagent only once the V1 floor accepts it (not re-checked against the 1.18.30 schema in this pass). The rest of the V2 command/agent frontmatter (hidden / color / steps / variant, already tracked 2026-09-08; system / disabled / permissions) folds into item 3.

Rulesync-side observation outside this issue's scope: in global mode tool-rule.ts (buildToolRuleParamsAgentsmd) still honours agentsmd.subprojectPath, so --global for opencode (and codexcli/kilo) writes ~/.github/workflows/AGENTS.md from .rulesync/rules/github-actions-security.md.

References

• V2 tags — https://github.com/anomalyco/opencode/tree/v2.0.2 — v2.0.0–v2.0.2 (no release notes yet).
• npm @opencode/cli — https://www.npmjs.com/package/@opencode/cli — latest = 2.0.2, 2.0.0 published 2026-09-11.
• Migrate guide — https://opencode.ai/v2/docs/migrate-v1/ — shared config paths, "V1 plugin implementations do not run in V2", "V2 currently only discovers AGENTS.md".
• Instructions — https://opencode.ai/v2/docs/instructions/ — instructions accepted but not resolved.
• Config — https://opencode.ai/v2/docs/config/ — V2 spellings and V1 normalization.
• Plugins — https://opencode.ai/v2/docs/build/plugins/ — Plugin.define / setup(ctx) API, dual-mode export, .opencode/plugins/ discovery.
• Skills — https://opencode.ai/v2/docs/skills/ — slash, metadata.opencode/*, flat .md form.
• Commands / Agents — https://opencode.ai/v2/docs/commands/, https://opencode.ai/v2/docs/agents/ — subagent, nested IDs, native agent fields.
• v1.18.30 — https://github.com/anomalyco/opencode/releases/tag/v1.18.30 — V1 maintenance only.