feat: add OpenCode integration with plugin, MCP, and skills

[omergk28]

Summary

• Add and harden the OpenCode integration setup so managed plugin, skills, AGENTS content, and MCP config install correctly and refresh when stale.
• Align help/docs/spec language with actual runtime behavior, especially around background bootstrap and recall-driven context access.
• Reuse shared AGENTS deployment behavior instead of maintaining OpenCode-specific duplication.

Key changes

• refresh stale managed OpenCode assets on rerun instead of only skipping existing files
• harden MCP config generation and refresh behavior
• quote MCP launcher arguments safely and handle non-ENOENT config read failures correctly
• validate managed targets before refresh to avoid unsafe/non-regular replacements
• improve ctx-remember guidance and keep OpenCode docs/spec/help consistent with implemented behavior
• cover the new refresh and validation behavior with targeted tests

Wire-format change (cross-cutting)

internal/mcp/proto/schema.go: ToolContent.Text drops omitempty. Every tools/call response now emits "text": "" for empty content instead of omitting the key. The MCP spec
defines text as required on type:"text" content, so this is the spec-compliant form; OpenCode's Zod validator enforces it strictly, while Claude Code and Copilot CLI tolerate
either shape.

Verified live: ctx mcp serve (this branch) registered against both Claude Code and Copilot CLI v1.0.40 — tools/call ctx_status succeeded end-to-end on both. Locked down by
TestToolContentTextFieldAlwaysPresent in internal/mcp/proto/schema_test.go so a future revert to omitempty fails CI.

Validation

Automated validation

• go test ./internal/cli/setup/core/opencode
• go test ./internal/cli/setup/core/agents
• go test ./internal/mcp/proto
• make build
• go test ./...

Manual smoke test

Validated the OpenCode + ctx integration end to end in a fresh dummy project using an isolated OpenCode home.
Confirmed:

• ctx setup opencode --write installed the plugin, skills, AGENTS integration, and global MCP config
• slash skills worked: /ctx-status, /ctx-agent, /ctx-remember, /ctx-wrap-up
• shell.env injected the correct CTX_DIR
• edit/write flow worked and captured session diffs
• OpenCode shell-driven git commit flow worked
• idle hook fired successfully
• compaction fired successfully
• recall still worked after compaction, including seeded task and decision context
• MCP wire-format compatibility verified live against Claude Code and Copilot CLI v1.0.40

[josealekhine]

Hi @omergk28

Thanks for the careful work on this.

Tthe commit history makes it clear you smoke-tested end-to-end and dug into the actual OpenCode plugin SDK contracts
(signature shape, plugin discovery rule, MCP schema, CTX_DIR resolution)
rather than guessing. The shape mirrors the Copilot CLI integration cleanly,
and the persisted DECISIONS/LEARNINGS entries make the rationale recoverable for future maintainers.

Below is what I found. One blocker, the rest are non-blocking concerns
and follow-ups.

---

Blocker

Lint failure breaks make test

internal/cli/setup/core/agents/agents_test.go:82 shadows the outer err
declared at line 76:

template, err := agent.AgentsMd()
if err != nil {
    t.Fatalf("read embedded AGENTS.md: %v", err)
}

var buf bytes.Buffer
if err := Deploy(testCmd(&buf)); err != nil {   // <- shadows
    t.Fatalf("Deploy() error = %v", err)
}

govet flags this and internal/compliance/TestGolangciLint fails as a
result, so a full make test is red even though
go test ./internal/cli/setup/core/opencode ./internal/cli/setup/core/agents
passes. One-line fix — rename to deployErr, or hoist the Deploy call
above the template, err := line.

---

Other Concerns

1. Cross-cutting MCP schema change is buried in an OpenCode PR

internal/mcp/proto/schema.go:

-Text string `json:"text,omitempty"`
+Text string `json:"text"`

Justified by commit afcb1297 (OpenCode's Zod schema requires text
present), but it now changes the wire format for every MCP client — not
just OpenCode. Two requests:

• Confirm Claude Code and Copilot CLI MCP clients are still happy with
  always-present empty text fields. The MCP spec allows it, so this is
  almost certainly fine, but worth one round of explicit verification.
• Call this out in the merge commit / release notes so it isn't
  rediscovered as a regression by a non-OpenCode user.

2. MCPConfigPathOpenCode warning string ignores $OPENCODE_HOME

internal/config/setup/setup.go:

MCPConfigPathOpenCode = "~/.config/opencode/opencode.json"

This literal is passed to writeErr.WarnFile when ensureMCPConfig fails,
but the actual writer (globalConfigPath) honors $OPENCODE_HOME. If a
user has $OPENCODE_HOME set and the write fails, the warning will name
the wrong path. Cosmetic but misleading — easy follow-up: have the warning
report the path that globalConfigPath() actually computed.

3. Global config write deserves a caveat in user-facing docs

ctx setup opencode --write is the only ctx integration that mutates a file
outside the project root (~/.config/opencode/opencode.json). It's
intentional (non-interactive shells need the global path — see commit
afcb1297), but it surprises a user who expects setup commands to be
project-local. A one-line note in docs/home/opencode.md ("This also
registers the ctx MCP server in OpenCode's global config at
~/.config/opencode/opencode.json so non-interactive shells can find it.")
would prevent confusion.

4. Plugin refresh semantics aren't surfaced to users

When deployPlugin finds a stale .opencode/plugins/ctx.ts, it rewrites
in place — but OpenCode only picks it up on next launch, not mid-session.
This is the right behavior (and is documented in commit messages) but
isn't mentioned in the quickstart. Worth a sentence: "If you re-run
ctx setup opencode --write, restart OpenCode to pick up the refreshed
plugin."

---

Documentation gaps

Recipes

• No docs/recipes/ entry references OpenCode at all. Copilot CLI is
  mentioned in multi-tool-setup.md, guide-your-agent.md, and
  index.md. OpenCode should appear in the same places, at minimum:
  • multi-tool-setup.md — add OpenCode to the # ## Cursor / Aider / Copilot / Windsurf ## block (line 34) and the per-tool sections
    further down.
  • guide-your-agent.md — list OpenCode as an AGENTS.md-aware tool.
  • recipes/index.md — add OpenCode to whatever tool index lives there.

Other missing docs

• No dedicated troubleshooting section in docs/home/opencode.md. The
  PR commit history surfaces three real failure modes that users will hit:

  • opencode mcp list shows ctx ✗ failed MCP error -32000: Connection closed → CTX_DIR not resolving (covered by the sh-wrapper, but a
    user with a stale install needs to know to re-run ctx setup opencode --write).
  • Plugin appears installed but no hooks fire → flat-vs-subdirectory
    discovery rule (the v0.7.x layout). Worth telling users how to verify
    the plugin loaded (opencode --print-logs --log-level DEBUG).
  • ctx agent markdown leaking into the TUI → was the
    .nothrow().quiet() fix; if users ever see it again on an SDK bump,
    they should know what to look for.

• The hooks.yaml (internal/assets/commands/text/hooks.yaml) gained
  20 lines but docs/operations/integrations.md is the only place this
  surfaces. If there's a generated hook reference page (the way Copilot
  CLI has one), OpenCode needs an entry there too.

• Block-dangerous-commands omission is permanent (DECISIONS entry
  2026-04-26-231517) but not mentioned in user-facing docs. A user
  coming from Claude Code may notice the missing protection. One sentence
  in docs/home/opencode.md under "What Happens Automatically" would
  cover it: "Note: dangerous-command blocking is Claude Code-specific and
  is not part of the OpenCode integration."

• Compaction behavior is mentioned in the quickstart but not explained
  for users who don't know what experimental.session.compacting is. The
  current text ("your memory survives compaction") is great for marketing
  but doesn't tell a user what to expect when their context window fills
  up. A short paragraph would help.

---

What's good

• Spec is current. specs/opencode-integration.md matches the landed
  code, including the deliberate tool.execute.before skip.
• Docstrings are not lazy. Each func has Parameters/Returns blocks;
  tricky bits (sh-wrapper rationale, plugin discovery, BunShell
  .nothrow().quiet(), additive output.context) get real prose.
• The index.ts header comment is genuinely instructive for the next
  maintainer — it spells out the SDK contract gotchas you discovered the
  hard way. Future plugin work for any editor benefits from this.
• Magic-string discipline preserved — new constants (KeyEnabled,
  DirXDGConfig, FileOpenCodePluginDeploy, CmdFlag,
  FormatPOSIXSpawnRelativeCtxDir, MissingEmbeddedAsset) keep call
  sites clean and audit-friendly.
• Refactoring AGENTS deployment into shared coreAgents.Deploy is a
  net win — opencode.Deploy() stays small, and Copilot CLI / future
  integrations get the same symlink/non-regular-file rejection for free.

---

TL;DR

It would be awesome if you can address all these.

The blocker one I stated is a must, but the others are also equally important.

Nice work overall.