feat(opencode): add ZERO-294 OpenCode adapter

[spencercharest]

Summary

Subtask: ZERO-298 (OpenCode adapter — JS plugin + skills)

Adds an OpenCode adapter package at plugins/zero-opencode plus consumer install docs:

• OpenCode JS plugin package @zeroxyz/opencode-zero
• session-start runner preparation for ~/.zero/runtime/bin/zero
• copied-profile repair for Docker/containers where a host Zero shim points at a host-only Node path
• OpenCode config hook registering the Zero remote MCP server
• system-context injection for Zero availability
• shell environment hook exporting ZERO_RUNNER and prepending ~/.zero/runtime/bin
• OpenCode skill install via zero init --skills-dir ~/.config/opencode/skills
• /zero command written to ~/.config/opencode/commands/zero.md
• permission.ask auto-approval only for safe Zero commands (search, get, review, runs, init, read-only config)
• OpenCode standalone guide plus README link
• version bump 1.3.3 -> 1.4.0 across versioned manifests via make minor

This PR intentionally does not modify guides/agent-install.md. Proposed runbook notes are documented below for the later agent-install rework.

Official sources used

• OpenCode plugins: https://opencode.ai/docs/plugins/
• OpenCode skills: https://opencode.ai/docs/skills/
• OpenCode MCP servers: https://opencode.ai/docs/mcp-servers/
• OpenCode commands: https://opencode.ai/docs/commands/
• OpenCode CLI/plugin command: https://opencode.ai/docs/cli/
• Published plugin types inspected from @opencode-ai/plugin@1.17.7

Install and update surfaces

Human in-harness path:

/plugin @zeroxyz/opencode-zero

Terminal path:

opencode plugin @zeroxyz/opencode-zero

Update path:

opencode plugin @zeroxyz/opencode-zero --force

Proposed guides/agent-install.md notes

Do not apply in this PR. Suggested section for the later runbook rework:

### OpenCode

1. **Install the Zero plugin package:**

   ```bash
   opencode plugin @zeroxyz/opencode-zero

2. Start a new OpenCode session. The OpenCode plugin runs from OpenCode's
   npm plugin cache and prepares the Zero runner, skill, MCP server, and /zero
   command on session start. Continue with Step 3 below.

## Docker verification

Environment:

- Docker image: `node:22-bookworm`
- OpenCode CLI package: `opencode-ai@1.17.7`
- OpenCode plugin types: `@opencode-ai/plugin@1.17.7`
- OpenAI BYOK loaded with `--env-file ~/zeroclick/env`
- Mounted branch worktree at `/workspace:ro`
- Copied host `~/.zero` into the container as `/root/.zero` before E2E testing
- Installed the OpenCode plugin from the branch-local package path: `/workspace/plugins/zero-opencode`

Plugin install/load command:

```bash
opencode plugin /workspace/plugins/zero-opencode

Result:

• Plugin package ready
• Detected server target
• Plugin config updated
• Installed /workspace/plugins/zero-opencode

OpenCode-driven Zero E2E command shape:

opencode run --model openai/gpt-4.1-mini --format json --dangerously-skip-permissions "$prompt"

The prompt instructed OpenCode to use the Zero skill and bash tool, not run zero review, and execute the required search/get/fetch/curl verification script.

Result:

• Session ID: ses_137f6ef98ffeOJg8BeNzm7nPmx
• Run ID: run_7E1AK3PSHkO0rXBaNf3if
• Returned URL: https://cdn.withzero.xyz/LolkTqxW/agent-harness-e2e-opencode-20260614212716.txt
• Payment amount: 0 USDC
• Verification: true — CDN body matched opencode zero e2e 20260614212716
• Generated assets present:
  • /root/.zero/runtime/bin/zero
  • /root/.config/opencode/skills/zero/SKILL.md
  • /root/.config/opencode/commands/zero.md

Local checks

find . -name '*.json' -print0 | xargs -0 -n1 jq empty
node -e "import('./plugins/zero-opencode/index.js').then(async ({ZeroPlugin}) => { /* permission/env smoke */ })"
cd plugins/zero-opencode && npm pack --dry-run
git diff --check
# CI-style version lockstep over JSON files with top-level "version"

Results:

• JSON parse passed
• OpenCode plugin import passed
• permission.ask smoke allowed zero search and did not allow zero fetch
• shell.env smoke exported ZERO_RUNNER and prepended the Zero runtime bin dir
• npm pack dry-run passed with index.js, README.md, and package.json
• whitespace check passed
• versioned manifests all at 1.4.0

Claude-style plugin compatibility and simpler install option

Full Claude Code plugin package support: No. OpenCode has its own npm/JS plugin system. It does read Claude-compatible skill locations, including .claude/skills/, so the Zero skill body can be reused, but OpenCode does not install Claude Code .claude-plugin packages as a first-class plugin artifact.

What this means for users:

• End users should not run scripts/build-*. The full-integration consumer path should be a published npm package:

  /plugin @zeroxyz/opencode-zero
  

  or:

  opencode plugin @zeroxyz/opencode-zero
  opencode plugin @zeroxyz/opencode-zero --force

• If the npm plugin is not worth maintaining, a simpler alternative is to document an OpenCode setup that copies/uses the existing Zero SKILL.md under .claude/skills/zero or .config/opencode/skills/zero plus a remote MCP entry for https://mcp.zero.xyz. That gives skill + MCP only and drops session/context/permission hooks.

GitHub Releases / no-build install check

Result: No native Gemini-style GitHub Release install path found. OpenCode loads plugins either from local plugin files or from npm packages declared in config. Source: OpenCode plugin docs document local .opencode/plugins/ / ~/.config/opencode/plugins/ loading and npm package loading; they do not document installing plugin release archives directly from GitHub Releases.

Best no-build consumer path:

{
  "plugin": ["@zeroxyz/opencode-zero"]
}

or the in-harness/plugin command once the npm package exists:

opencode plugin @zeroxyz/opencode-zero

A GitHub Release asset could still be useful as a manual fallback containing a ready-to-copy .opencode/plugins/zero file plus skill/command files, but it would be download/extract guidance, not a native OpenCode installer like Gemini.

PR status

Draft. The OpenCode local-package install/load and full OpenCode-driven Zero E2E passed in Docker, but the documented consumer command uses @zeroxyz/opencode-zero, which is not published to npm yet (npm view @zeroxyz/opencode-zero returns 404). Move to ready after the npm package name is published or the consumer install path is changed to a verified distributable source.

[spencercharest]

Folded into #63 as a matrix entry (opencode in plugins/zero/agents.json) — standalone skills + MCP. No install block: @zeroxyz/opencode-zero is still unpublished (npm E404 re-verified 2026-07-02), and OpenCode hooks remain JS-plugin-only (no JSON target). #63 tracks the revisit once the npm plugin ships. The adapter-template work here stays available on this branch if we later ship per-host templates.