Host support: OpenCode — native plugins, skills, commands, and MCP projection

[ScriptedAlchemy]

Priority / evidence

P2 feature expansion; not a blocker for the existing hosts. Research date: 2026-09-06. Read the host's documentation below; no OpenCode installation or live-host test was executed during research. Configuration examples describe the host contract and a proposed emitted artifact, not functionality already available in Agent Bundle.

Agent Bundle baseline: 5fc8de37c9695b816d55bdcf18a6bcb1dfee69f5. Its built-in composite targets remain Claude, Codex, Cursor, and portable. Ponytail's OpenCode integration demonstrates a consumer use case, not an authoritative specification.

Primary specifications and implementation references

• Plugin loading, factories, events, load order, dependencies
• Custom tool definition and execution context
• SKILL.md discovery and permissions
• Commands and prompt templates
• MCP local/remote configuration
• Permission semantics
• Configuration and schema / https://opencode.ai/config.json
• Ponytail consumer example, pinned

Verified host model

OpenCode loads JS/TS plugin modules from project .opencode/plugins/, global ~/.config/opencode/plugins/, or npm packages named in the plugin configuration array. A plugin exports factory functions that receive host context and return hooks. npm loading uses Bun and a host-managed cache. Local and npm copies can both load, so installation must not create duplicate activation paths.

This is an in-process JavaScript extension, not a Claude-style shell-hooks manifest. The documented plugin context includes project/worktree paths and an SDK client. Native custom tools and lifecycle callbacks are available; their argument, return, and error semantics need an explicit adapter mapping. Keep runtime helpers out of the discovered entry export surface.

Skills are separately discovered as SKILL.md directories, with name/description metadata and host-controlled access. Commands are prompt templates, not a second implementation of a canonical tool operation. MCP uses an mcp object with local/remote entries; local command is an argv array and the environment field is environment, not a copied Claude env shape.

Proposed generated layout and operator configuration

composite-root/
  .opencode/plugins/example.mjs   # thin factory entry, no helper exports
  .opencode/commands/review.md    # only if this host command is declared
  .opencode/skills/review/SKILL.md
  runtime/                       # shared compiled implementation as needed
  mcp/example.mjs                # only for a declared MCP server

The exact discovery roots and supported package-entry syntax must be validated against the pinned host release. Avoid shipping both locally auto-discovered and npm-enabled copies by default.

Example host configuration for an npm distribution:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@example/agent-plugin"],
  "mcp": {
    "example": {
      "type": "local",
      "command": ["node", "/absolute/installed-plugin/mcp/example.mjs"],
      "enabled": true
    }
  }
}

This illustrates two independent surfaces; do not register the same operation twice through native tools and MCP unintentionally. Existing user configuration, credentials, permissions, and global defaults must not be overwritten. A local-development flow should choose a supported file/auto-discovery mechanism and remove only its owned registration when stopped.

Agent Bundle mapping

1. Reuse the compiled operation/schema/content graph. Generate a small OpenCode factory over that implementation; do not ask authors to maintain an independent .opencode application.
2. Define the minimum capability subset first: content/skills/commands, declared native tools or MCP, and individually supported lifecycle callbacks. Record unsupported or version-gated events explicitly.
3. Translate native callback inputs into canonical events only where semantics match. Distinguish observational events from callbacks that can block or transform behavior. Preserve per-session/worktree context and cancellation.
4. Keep experimental.* host hooks version-gated. Ponytail's use of experimental.chat.system.transform does not make it a permanent cross-host API.
5. Decide how a composite npm package exposes the native factory without breaking existing root exports. Pin and test package subpath support before relying on it; otherwise use a documented thin loader.
6. Preserve permission decisions. Skill allow/ask/deny and tool permissions belong to OpenCode; emitting a plugin must not grant global execution authority.

Composite / installation hazards

OpenCode can discover skills/instructions shared with other tools. Test effective discovery, not only unique output filenames. Additions to the built-in composite allowlist must follow conformance proof; current custom-registry isolation (AB4106) must not simply be disabled.

Keep code immutable and framework state outside the installed artifact. Store installation identity separately from runtime session identity. A plugin factory's startup is executable code, so inspection/manifest validation must not import it merely to learn metadata.

Acceptance

• Pin OpenCode version, SDK version, schema/source revision and document the supported callback subset.
• Static-only plugin loads skills/commands without an MCP server or Flight worker.
• Native factory initializes once; local+npm duplication is detected or explicitly avoided.
• Canonical tool schema, result/error, cancellation and context survive native invocation.
• Local MCP argv, cwd, environment and remote auth remain host-correct and secrets stay out of artifacts.
• Test a supported before/after lifecycle mapping, plus an unsupported event diagnostic.
• Verify no private helper export is treated as another plugin factory.
• Test single-host and composite roots, reversed target ordering, forbidden foreign discovery, relocated directories and actual packed installation.
• Test update/uninstall preserving unrelated configuration and durable data.
• Record both deterministic adapter tests and a real-host successful invocation; never count a factory import alone as full acceptance.

Implementation owners / boundaries

Existing packages/agent-bundle/src/adapters/{types,registry,composite-layout}.ts, src/build/compose.ts, manifest/launch contracts and tests/build-compose.test.ts; retain #651/#652 small/composite proofs and #680 exact executable selection. Add focused English/Chinese authoring and install documentation. No new agent orchestrator, default permission bypass, mandatory browser App, or second operation registry.

[ScriptedAlchemy]

Resolved by #723 (4dc11a4a06).

OpenCode — observed opencode-ai 1.18.29 exercised 2026-09-06; opencode.ai/docs retrieved 2026-09-06. Supported at the skills tier: the emitted skill tree loads; the manifest does not.

Surface	State	Evidence
manifest	unavailable	2026-09-06: opencode plugin <dir> requires a package.json or index file and refused the emitted package on 1.18.29; OpenCode reads no root plugin.json.
skills	degraded	2026-09-06: the skill tree must be copied into one of OpenCode's own roots; the emitted package as a whole is not an OpenCode install unit, and skill names must be unique across all roots ("Ensure skill names are unique across all locations").
mcp	unavailable	2026-09-06: https://opencode.ai/docs/mcp-servers/ configures servers under the mcp key of opencode.json with OpenCode's own type: "local" | "remote" shape and a command array, not a standalone mcp.json with the standard's stdio and streamable-http types.
placeholders	unavailable	2026-09-06: OpenCode substitutes {env:VAR} and {file:path} in its own configuration; it documents no expansion of the reserved ${PLUGIN_ROOT} and ${PLUGIN_DATA} of Agent Plugins 1.0.0 §9.1, and no emitted document carrying them is read.
hooks	unavailable	2026-09-06: OpenCode's event hooks are JavaScript functions returned by a plugin module (https://opencode.ai/docs/plugins/); Agent Plugins 1.0.0 defines no hooks, and this projection emits no plugin module for it to load.

Paths it reads: skills.
Install: cp -R skills/<skill> .agents/skills/<skill>.

Every row above is pinned to that client's own documentation on the date shown, is validated on every build, and renders in INSTALL.md and the generated hosts reference. A surface recorded unavailable or degraded names exactly what the client would need; no unsupported feature is projected silently.