Phase 4 — OpenCode + Gemini Adapters

Goal

Add two more backends. With four total adapters (claude-code, codex, opencode, gemini), the abstraction is well stress-tested. Any further redesign of AgentAdapter should happen here if needed — after this phase, the Protocol is locked.

Preconditions

Phases 1–3 shipped. Per-user BYO keys are available, which matters because users will more often supply their own keys for OpenCode and Gemini than have a shared org key.

Deliverables

1. adapters/opencode.py + tools/opencode.py + registry entry.
2. adapters/gemini.py + tools/gemini.py + registry entry.
3. Tests for both, fixture-driven.
4. Plugin docs / codumentor.yaml example covering all four backends.

New files

src/codumentor/plugins/external_agent/adapters/opencode.py
src/codumentor/plugins/external_agent/adapters/gemini.py
src/codumentor/plugins/external_agent/tools/opencode.py
src/codumentor/plugins/external_agent/tools/gemini.py
tests/test_external_agent_adapter_opencode.py
tests/test_external_agent_adapter_gemini.py
tests/fixtures/external_agent/opencode_*.jsonl
tests/fixtures/external_agent/gemini_*.jsonl

Implementation steps

1. OpenCode: open-source agent (opencode CLI). Check its CLI surface (opencode --help). It also has a server mode; for this phase, stick with the CLI subprocess pattern. Auth varies by provider configuration — for phase 4, defer to whatever OpenCode reads from its env or config and pass through the user's API key as the same env var OpenCode expects.

1. Gemini: Google's Gemini CLI. Auth via GEMINI_API_KEY (verify). Session resume support is limited — likely supports_resume = False; document. JSON output flags are less mature than Claude Code's; if no streaming, fall back to parse_oneshot.

1. For both, follow the same shape as phase 2's Codex adapter. Reuse runner and sandbox unchanged.

1. If any backend reveals a Protocol or union shortcoming, this is the right phase to fix it. Changes must remain additive. Surface in handoff.

1. Test parity: every backend has the same three test files structure (adapter unit, runner integration with fake binary, fixtures). Avoid copy-paste — factor shared test helpers into tests/_external_agent_helpers.py if needed.

Acceptance criteria

• make test passes.
• Manual probe for each: a simple query returns a wrapped answer with a transcript card.
• No regressions in Claude Code or Codex (they still work identically).

Out of scope

• Tier 1 sandbox — phase 5.
• OAuth / Google sign-in for Gemini — phase 6 (and may be deferred further; Gemini's API key model is sufficient for most users).
• OpenCode server mode — not in this rollout. Document it as a future option if you find it would simplify integration; do not implement.

Handoff

Fill out the template. Especially important here, since this is the last chance to evolve the abstraction:

• "Contracts established/changed": any final Protocol or union additions, with exact diffs.
• "Open questions": flag if any backend was significantly harder to fit than expected — this informs phase 7's codumentor adapter design.