feat(runtime): add Gemini CLI as third execution runtime

[tgmerritt]

Summary

• Add Google Gemini CLI as a third AgentRuntime alongside Claude Code and Codex CLI
• Change the default execution runtime from claude to codex
• Hardcode Claude as the interview backend regardless of configured runtime (create_llm_adapter(use_case="interview") always returns ClaudeCodeAdapter)
• Support user selection via config.yaml, CLI flag (--runtime gemini), and env var (OUROBOROS_AGENT_RUNTIME=gemini)

New modules

• gemini_permissions.py — permission mode to CLI flag mapping (--sandbox, --approval-mode, --yolo)
• providers/gemini_cli_adapter.py — LLM adapter (thin subclass of CodexCliLLMAdapter)
• orchestrator/gemini_cli_runtime.py — agent runtime (thin subclass of CodexCliRuntime)

Config changes

• OrchestratorConfig.runtime_backend default: "claude" → "codex"
• New fields: gemini_cli_path, gemini_permission_mode
• New env vars: OUROBOROS_GEMINI_CLI_PATH, OUROBOROS_GEMINI_PERMISSION_MODE

Factory changes

• create_llm_adapter(use_case="interview") always returns ClaudeCodeAdapter
• Both runtime and provider factories resolve "gemini" / "gemini_cli" aliases

Documentation

• New runtime guide: docs/runtime-guides/gemini.md
• Updated capability matrix with Gemini column
• Updated config reference with new keys and env vars

Test plan

• 35 new unit tests for Gemini permissions, adapter, runtime, and factory wiring
• Updated existing factory and config model tests for new defaults
• 192 feature-related tests pass (0 failures)
• ruff check and ruff format pass on all changed files
• Interview hardcoding verified: create_llm_adapter(backend="gemini", use_case="interview") returns ClaudeCodeAdapter
• Default change verified: OrchestratorConfig().runtime_backend == "codex"
• Factory resolution verified: resolve_agent_runtime_backend("gemini_cli") == "gemini"

🤖 Generated with Claude Code

[ouroboros-agent]

Review — ouroboros-agent[bot]

Verdict: REQUEST_CHANGES

Reviewing commit 431e72b | Triggered by: PR opened

Branch: feat/gemini-runtime | 19 files, +1117/-59 | CI: unknown

Issue #N/A Requirements

Requirement	Status
No linked issue detected in PR body	N/A — No issue requirements to map.

Previous Review Follow-up

Previous Finding	Status
First review — no previous findings.	N/A — First bot review on this PR.

Code Findings

#	File:Line	Severity	Confidence	Finding
1	src/ouroboros/providers/gemini_cli_adapter.py:41	High	High	GeminiCliLLMAdapter._build_command() ignores output_schema_path, so every response_format={"type":"json_schema",...} request is silently downgraded to an unconstrained text completion. That breaks existing QA / semantic / consensus callers which parse the reply as JSON and currently depend on schema-constrained output.
2	src/ouroboros/orchestrator/gemini_cli_runtime.py:103	High	Medium	The Gemini runtime only overrides session-id extraction, but inherits Codex-only event normalization. The parent runtime converts thread.started, item.completed, and turn.failed; Gemini -o stream-json events are unlikely to match that shape, so assistant/tool streaming and explicit failure events will be dropped instead of surfaced to the orchestrator.
3	src/ouroboros/config/loader.py:564	Medium	High	_default_model_for_backend() treats Gemini as a “Codex-like” backend and rewrites default model names to "default". For consensus this collapses the default 3-model roster into ("default","default","default"), which defeats min_models/diversity_required semantics and turns stage-3 consensus into repeated votes from the same local default model.
4	src/ouroboros/providers/gemini_cli_adapter.py:68	Medium	Medium	The LLM adapter only recognizes session_id, while the runtime already had to support both session_id and sessionId. If Gemini emits camelCase here as well, one-shot completions will lose session tracking in raw_response, making resume/debug metadata inconsistent across the two Gemini code paths.
5	docs/runtime-guides/gemini.md:73	Medium	High	The Gemini guide documents gemini_permission_mode: sandbox / auto_edit and matching env/CLI examples, but the actual accepted values are default, acceptEdits, and bypassPermissions (OrchestratorConfig and resolve_gemini_permission_mode). Following the guide produces validation/runtime errors on first use.
6	docs/config-reference.md:79	Low	High	The config reference says runtime_backend: opencode raises NotImplementedError, but the factory currently rejects it with ValueError during backend resolution. The docs are advertising a behavior and support level that the implementation does not provide.

Test Coverage

Missing tests for env/config precedence and backend-specific branches in src/ouroboros/config/loader.py, especially Gemini-specific permission selection and the "default" model normalization path.
Missing Gemini structured-output tests in src/ouroboros/providers/gemini_cli_adapter.py that exercise CompletionConfig.response_format the same way src/ouroboros/evaluation/consensus.py and src/ouroboros/mcp/tools/qa.py use it.
Missing event-shape normalization tests in src/ouroboros/orchestrator/gemini_cli_runtime.py using representative Gemini stream-json payloads; current tests only validate command construction and session-id extraction.
Missing regression coverage for consensus model defaults under llm.backend=gemini across src/ouroboros/config/loader.py and src/ouroboros/evaluation/consensus.py.
I could not run the Python test suite here because pytest is not installed in this environment.

Design

The general direction is sound: adding Gemini through the existing runtime/provider factories keeps the public surface relatively clean. The problem is that the implementation reuses Codex base classes almost verbatim while only adapting flags and path lookup. That is not enough when the transport protocol differs. The current design assumes Gemini emits Codex-compatible runtime and completion events, plus equivalent schema/output features, but the code does not prove or enforce that.

The config/docs layer is also ahead of the implementation. New options are exposed broadly, including unsupported opencode values and Gemini permission examples that do not match the actual validators. No previous review findings were supplied, so there was nothing to verify as fixed or still open from an earlier round.

Files Reviewed

• docs/config-reference.md
• docs/runtime-capability-matrix.md
• docs/runtime-guides/gemini.md
• src/ouroboros/config/__init__.py
• src/ouroboros/config/loader.py
• src/ouroboros/config/models.py
• src/ouroboros/gemini_permissions.py
• src/ouroboros/orchestrator/__init__.py
• src/ouroboros/orchestrator/gemini_cli_runtime.py
• src/ouroboros/orchestrator/runtime_factory.py
• src/ouroboros/providers/__init__.py
• src/ouroboros/providers/factory.py
• src/ouroboros/providers/gemini_cli_adapter.py
• tests/unit/config/test_models.py
• tests/unit/orchestrator/test_gemini_cli_runtime.py

---

Reviewed by ouroboros-agent[bot] via Codex deep analysis

[ouroboros-agent]

Review — ouroboros-agent[bot]

Verdict: REQUEST_CHANGES

Reviewing commit 431e72b | Triggered by: PR opened

Branch: feat/gemini-runtime | 19 files, +1117/-59 | CI: no checks reported on the 'feat/gemini-runtime' branch

Issue #N/A Requirements

Requirement	Status
No linked issue detected in PR body	N/A — No issue requirements to map.

Previous Review Follow-up

Previous Finding	Status
First review — no previous findings.	N/A — First bot review on this PR.

Code Findings

#	File:Line	Severity	Confidence	Finding
1	src/ouroboros/providers/gemini_cli_adapter.py:41	high	high	GeminiCliLLMAdapter._build_command() accepts output_schema_path but never uses it. The parent completion flow still builds a schema file and expects the backend command to enforce it, so any response_format={"type": "json_schema", ...} request sent through the Gemini adapter silently degrades to unconstrained free-form output. That is a behavioral regression relative to the existing Codex adapter contract.
2	docs/runtime-guides/gemini.md:73	medium	high	The new guide tells users to set gemini_permission_mode: sandbox / auto_edit, but the implementation only accepts default, acceptEdits, and bypassPermissions (src/ouroboros/gemini_permissions.py:14). Copy-pasting the documented config will fail validation before the runtime even starts.
3	docs/runtime-guides/gemini.md:220	medium	high	The CLI examples repeat the same invalid permission values (--permission-mode sandbox and --permission-mode auto_edit). The runtime validators and config model only recognize default, acceptEdits, and bypassPermissions, so the documented commands are not runnable as written.
4	src/ouroboros/providers/gemini_cli_adapter.py:78	medium	medium	The provider-side session-id extraction only recognizes session_id, while the runtime-side Gemini parser was already extended to accept both session_id and sessionId (src/ouroboros/orchestrator/gemini_cli_runtime.py:103). If the Gemini CLI emits camelCase on the one-shot path too, completion metadata/session tracking will be lost there even though the runtime path handles it.
5	src/ouroboros/config/loader.py:531	medium	medium	create_llm_adapter(backend="gemini") resolves its permission mode through get_llm_permission_mode() (src/ouroboros/providers/factory.py:98), but that loader only has backend-specific branches for OpenCode. The new Gemini backend therefore has no Gemini-specific permission override path on the LLM-only side, which makes the runtime and provider surfaces inconsistent and prevents a dedicated Gemini override from ever being honored there.

Test Coverage

The current test suite covers constructor wiring and flag mapping, but it does not exercise the two places most likely to break in real use:

• No provider test requests a structured response format through GeminiCliLLMAdapter, so the missing output_schema_path handling is not caught (tests/unit/providers/test_gemini_cli_adapter.py).
• No test asserts that the documentation examples use validator-accepted permission strings, so the sandbox / auto_edit drift shipped unchecked (tests/unit/test_gemini_permissions.py, docs only).
• No provider test covers sessionId (camelCase) on the one-shot Gemini path, even though the runtime path explicitly anticipates that variant (tests/unit/providers/test_gemini_cli_adapter.py, tests/unit/orchestrator/test_gemini_cli_runtime.py).

Design

The overall shape is sensible: keep Gemini as a thin Codex-derived runtime/provider pair, centralize permission translation in gemini_permissions.py, and wire backend selection through the existing factories. That preserves the handler/runtime layering rather than forking new orchestration logic.

The problems are mostly contract mismatches at the edges:

• the provider adapter does not yet preserve the parent structured-output contract,
• the docs/examples are out of sync with the actual validator surface,
• and the runtime/provider config surfaces are not aligned on Gemini-specific permission handling.

I would fix those boundary mismatches before merging; otherwise the first user-facing Gemini paths are likely to fail in ways that look like product instability rather than normal beta roughness.

Files Reviewed

• docs/config-reference.md
• docs/runtime-capability-matrix.md
• docs/runtime-guides/gemini.md
• src/ouroboros/config/__init__.py
• src/ouroboros/config/loader.py
• src/ouroboros/config/models.py
• src/ouroboros/gemini_permissions.py
• src/ouroboros/orchestrator/__init__.py
• src/ouroboros/orchestrator/gemini_cli_runtime.py
• src/ouroboros/orchestrator/runtime_factory.py
• src/ouroboros/providers/__init__.py
• src/ouroboros/providers/factory.py
• src/ouroboros/providers/gemini_cli_adapter.py
• tests/unit/config/test_models.py
• tests/unit/orchestrator/test_gemini_cli_runtime.py

---

Reviewed by ouroboros-agent[bot] via Codex deep analysis

[Q00]

Thanks for the contribution, @tgmerritt! The overall shape is solid — thin Codex-derived subclasses with centralized permission translation is exactly the right pattern. A few things to address before merge, and some that can wait.

---

Must fix before merge

1. output_schema_path silently dropped (High)
GeminiCliLLMAdapter._build_command() accepts output_schema_path but never passes it to the CLI. The parent _complete_once() builds a schema temp file and expects the backend to enforce it, so any response_format={"type": "json_schema", ...} request (used by QA, consensus, semantic callers) silently degrades to unconstrained text output. This will cause JSON parse failures downstream.

Either wire --output-schema through (if Gemini CLI supports it) or explicitly raise/warn when structured output is requested but unsupported.

2. Docs use invalid permission values (Medium-High)
docs/runtime-guides/gemini.md documents sandbox and auto_edit as config values (lines 73, 220+), but the actual validator (resolve_gemini_permission_mode) only accepts default, acceptEdits, bypassPermissions. Users following the guide will hit a validation error on first use. The permission table and CLI examples both need updating.

---

Can defer to next iteration

3. Event normalization assumes Codex event shape — The Gemini runtime inherits Codex event parsing (thread.started, item.completed, turn.failed). Gemini's stream-json output is unlikely to match. This is fine for beta since the actual Gemini CLI event format needs empirical validation first. Suggest opening a follow-up issue to test with real Gemini output and adapt the normalizer.

4. sessionId camelCase inconsistency — Runtime handles both session_id and sessionId, but the provider-side adapter only checks session_id. Low priority until we confirm what Gemini actually emits.

5. Consensus model defaults — Gemini is grouped with Codex in _CODEX_LLM_BACKENDS, so _default_model_for_backend() rewrites consensus models to ("default", "default", "default"), defeating diversity. Only matters when OpenRouter isn't configured. Low priority for beta.

---

Needs discussion

6. Breaking change: default runtime claude → codex
OrchestratorConfig.runtime_backend default changed from "claude" to "codex". This silently changes behavior for every user without an explicit config. This should either:

• Be reverted and handled in a separate PR with proper changelog/migration note, or
• At minimum be called out as a breaking change in the PR description and release notes

7. Interview hardcoded to Claude
create_llm_adapter(use_case="interview") now always returns ClaudeCodeAdapter. Reasonable for quality, but Gemini-only users (no Anthropic API key / no Max Plan) won't be able to run interviews at all. Worth documenting this requirement explicitly.

---

Bot review assessment

The ouroboros-agent bot flagged largely the same issues. Findings #1 and #2 are real blockers. The rest are valid observations but appropriate to defer for a beta release. The bot was thorough — not unfair, just not triaging by release phase.

Nice work on the 35 tests and thorough docs. Looking forward to the next iteration! 🚀

[ouroboros-agent]

Review — ouroboros-agent[bot]

Verdict: REQUEST_CHANGES

Reviewing commit 431e72b | Triggered by: backlog review sweep

Branch: feat/gemini-runtime | 19 files, +1117/-59 | CI: No checks reported

Issue #N/A Requirements

Requirement	Status
No linked issue detected in PR body.	See code findings below for file:line evidence.

Previous Review Follow-up

Previous Finding	Status
Prior bot review exists	Follow-up checked in current analysis.

Code Findings

#	File:Line	Severity	Confidence	Finding
1	src/ouroboros/providers/gemini_cli_adapter.py:41	High	High	GeminiCliLLMAdapter._build_command() ignores output_schema_path, so every response_format={"type":"json_schema",...} request is silently downgraded to an unconstrained text completion. That breaks existing QA / semantic / consensus callers which parse the reply as JSON and currently depend on schema-constrained output.
2	src/ouroboros/orchestrator/gemini_cli_runtime.py:103	High	Medium	The Gemini runtime only overrides session-id extraction, but inherits Codex-only event normalization. The parent runtime converts thread.started, item.completed, and turn.failed; Gemini -o stream-json events are unlikely to match that shape, so assistant/tool streaming and explicit failure events will be dropped instead of surfaced to the orchestrator.
3	src/ouroboros/config/loader.py:564	Medium	High	_default_model_for_backend() treats Gemini as a “Codex-like” backend and rewrites default model names to "default". For consensus this collapses the default 3-model roster into ("default","default","default"), which defeats min_models/diversity_required semantics and turns stage-3 consensus into repeated votes from the same local default model.
4	src/ouroboros/providers/gemini_cli_adapter.py:68	Medium	Medium	The LLM adapter only recognizes session_id, while the runtime already had to support both session_id and sessionId. If Gemini emits camelCase here as well, one-shot completions will lose session tracking in raw_response, making resume/debug metadata inconsistent across the two Gemini code paths.
5	docs/runtime-guides/gemini.md:73	Medium	High	The Gemini guide documents gemini_permission_mode: sandbox / auto_edit and matching env/CLI examples, but the actual accepted values are default, acceptEdits, and bypassPermissions (OrchestratorConfig and resolve_gemini_permission_mode). Following the guide produces validation/runtime errors on first use.
6	docs/config-reference.md:79	Low	High	The config reference says runtime_backend: opencode raises NotImplementedError, but the factory currently rejects it with ValueError during backend resolution. The docs are advertising a behavior and support level that the implementation does not provide.

Test Coverage

Missing tests for env/config precedence and backend-specific branches in src/ouroboros/config/loader.py, especially Gemini-specific permission selection and the "default" model normalization path.
Missing Gemini structured-output tests in src/ouroboros/providers/gemini_cli_adapter.py that exercise CompletionConfig.response_format the same way src/ouroboros/evaluation/consensus.py and src/ouroboros/mcp/tools/qa.py use it.
Missing event-shape normalization tests in src/ouroboros/orchestrator/gemini_cli_runtime.py using representative Gemini stream-json payloads; current tests only validate command construction and session-id extraction.
Missing regression coverage for consensus model defaults under llm.backend=gemini across src/ouroboros/config/loader.py and src/ouroboros/evaluation/consensus.py.
I could not run the Python test suite here because pytest is not installed in this environment.

Design

The general direction is sound: adding Gemini through the existing runtime/provider factories keeps the public surface relatively clean. The problem is that the implementation reuses Codex base classes almost verbatim while only adapting flags and path lookup. That is not enough when the transport protocol differs. The current design assumes Gemini emits Codex-compatible runtime and completion events, plus equivalent schema/output features, but the code does not prove or enforce that.

The config/docs layer is also ahead of the implementation. New options are exposed broadly, including unsupported opencode values and Gemini permission examples that do not match the actual validators. No previous review findings were supplied, so there was nothing to verify as fixed or still open from an earlier round.

Files Reviewed

• docs/config-reference.md
• docs/runtime-capability-matrix.md
• docs/runtime-guides/gemini.md
• src/ouroboros/config/__init__.py
• src/ouroboros/config/loader.py
• src/ouroboros/config/models.py
• src/ouroboros/gemini_permissions.py
• src/ouroboros/orchestrator/__init__.py
• src/ouroboros/orchestrator/gemini_cli_runtime.py
• src/ouroboros/orchestrator/runtime_factory.py
• src/ouroboros/providers/__init__.py
• src/ouroboros/providers/factory.py
• src/ouroboros/providers/gemini_cli_adapter.py
• tests/unit/config/test_models.py
• tests/unit/orchestrator/test_gemini_cli_runtime.py

---

Reviewed by ouroboros-agent[bot] via Codex deep analysis

[Q00]

⚠️ Base branch rebased onto main

release/0.26.0-beta has been rebased onto the latest main (ef54b9b). This brings in recent main fixes including PR #180 (delegated MCP tool context) and build improvements.

Your branch will need a rebase:

git fetch origin
git rebase origin/release/0.26.0-beta

Key structural changes to be aware of:

• AgentRuntime protocol now has runtime_backend, working_directory, permission_mode properties
• RuntimeHandle.backend is now normalized via __post_init__
• Handler files split from definitions.py into separate modules

Let me know if you need help with the rebase.