ouroboros-ai 0.40.2.dev18__tar.gz → 0.40.2.dev20__tar.gz

{ouroboros_ai-0.40.2.dev18 → ouroboros_ai-0.40.2.dev20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.40.2.dev18
+Version: 0.40.2.dev20
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE
@@ -73,7 +73,7 @@ Description-Content-Type: text/markdown
   <a href="#from-wonder-to-ontology">Philosophy</a>
 </p>
 
-**Turn a vague idea into a verified, working codebase -- across Claude Code, Codex CLI, OpenCode, and Hermes.**
+**Turn a vague idea into a verified, working codebase -- across Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Kiro, Copilot, and Pi.**
 
 Ouroboros is an **Agent OS** for AI coding: a local-first runtime layer that
 turns non-deterministic agent work into a replayable, observable, policy-bound
@@ -149,7 +149,7 @@ curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.
 > ooo interview "I want to build a task management CLI"
 ```
 
-> Works with Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode, Hermes, Gemini, and Kiro CLI. The installer detects Claude Code, Codex CLI, and Hermes CLI automatically and registers the MCP server. For OpenCode, Kiro, or GitHub Copilot CLI, run `ouroboros setup --runtime <opencode|kiro|copilot>` after installation. The Copilot CLI runtime live-discovers its model catalog via the GitHub Copilot models API and lets you pick a default during setup.
+> Works with Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode, Hermes, Gemini, Kiro CLI, and Pi CLI. The installer detects Claude Code, Codex CLI, and Hermes CLI automatically and registers the MCP server where the host supports it. For OpenCode, Kiro, GitHub Copilot CLI, Gemini CLI, or Pi CLI, run `ouroboros setup --runtime <opencode|kiro|copilot|gemini|pi>` after installation. The Copilot CLI runtime live-discovers its model catalog via the GitHub Copilot models API and lets you pick a default during setup.
 
 <details>
 <summary><strong>Kiro CLI quick start</strong></summary>
@@ -206,7 +206,7 @@ ouroboros setup                         # configure runtime
 
 Legacy compatibility: `ouroboros-ai[dashboard]` is still accepted as a compatibility alias/no-op; it does not install dashboard runtime payload. `ouroboros-ai[all]` includes that no-op alias only for compatibility.
 
-See runtime guides: [Claude Code](./docs/runtime-guides/claude-code.md) · [Codex CLI](./docs/runtime-guides/codex.md) · [Hermes](./docs/runtime-guides/hermes.md) · [OpenCode](./docs/runtime-guides/opencode.md) · [Kiro CLI](./docs/runtime-guides/kiro.md) · [Gemini CLI](./docs/runtime-guides/gemini.md) · [GitHub Copilot CLI](./docs/runtime-guides/copilot.md)
+See runtime guides: [Claude Code](./docs/runtime-guides/claude-code.md) · [Codex CLI](./docs/runtime-guides/codex.md) · [Hermes](./docs/runtime-guides/hermes.md) · [OpenCode](./docs/runtime-guides/opencode.md) · [Kiro CLI](./docs/runtime-guides/kiro.md) · [Gemini CLI](./docs/runtime-guides/gemini.md) · [GitHub Copilot CLI](./docs/runtime-guides/copilot.md) · [Pi JSON mode](https://pi.dev/docs/latest/json)
 
 </details>
 
@@ -372,7 +372,7 @@ src/ouroboros/
 +-- resilience/     4-pattern stagnation detection, 5 lateral personas
 +-- observability/  3-component drift measurement, auto-retrospective
 +-- persistence/    Event sourcing (SQLAlchemy + aiosqlite), checkpoints
-+-- orchestrator/   Runtime abstraction layer (Claude Code, Codex CLI, OpenCode, Hermes)
++-- orchestrator/   Runtime abstraction layer (Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Kiro, Copilot, Pi)
 +-- core/           Types, errors, seed, ontology, security
 +-- providers/      LiteLLM adapter (100+ models)
 +-- mcp/            MCP client/server integration
@@ -388,7 +388,7 @@ src/ouroboros/
 - **Evolution** -- Up to 30 generations, convergence at ontology similarity >= 0.95
 - **Stagnation** -- Detects spinning, oscillation, no-drift, and diminishing returns patterns
 - **Agent OS runtime** -- Replayable execution contract across capability discovery, policy, directives, event journal, and agent processes
-- **Runtime backends** -- Pluggable abstraction layer (`orchestrator.runtime_backend` config) with first-class support for Claude Code, Codex CLI, OpenCode, and Hermes; same workflow spec, different execution engines
+- **Runtime backends** -- Pluggable abstraction layer (`orchestrator.runtime_backend` config) with first-class support for Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Goose, Kiro, Copilot, and Pi; same workflow spec, different execution engines
 
 See [Architecture](./docs/architecture.md) for the full design document.
 

{ouroboros_ai-0.40.2.dev18 → ouroboros_ai-0.40.2.dev20}/README.md

@@ -36,7 +36,7 @@
   <a href="#from-wonder-to-ontology">Philosophy</a>
 </p>
 
-**Turn a vague idea into a verified, working codebase -- across Claude Code, Codex CLI, OpenCode, and Hermes.**
+**Turn a vague idea into a verified, working codebase -- across Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Kiro, Copilot, and Pi.**
 
 Ouroboros is an **Agent OS** for AI coding: a local-first runtime layer that
 turns non-deterministic agent work into a replayable, observable, policy-bound
@@ -112,7 +112,7 @@ curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.
 > ooo interview "I want to build a task management CLI"
 ```
 
-> Works with Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode, Hermes, Gemini, and Kiro CLI. The installer detects Claude Code, Codex CLI, and Hermes CLI automatically and registers the MCP server. For OpenCode, Kiro, or GitHub Copilot CLI, run `ouroboros setup --runtime <opencode|kiro|copilot>` after installation. The Copilot CLI runtime live-discovers its model catalog via the GitHub Copilot models API and lets you pick a default during setup.
+> Works with Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode, Hermes, Gemini, Kiro CLI, and Pi CLI. The installer detects Claude Code, Codex CLI, and Hermes CLI automatically and registers the MCP server where the host supports it. For OpenCode, Kiro, GitHub Copilot CLI, Gemini CLI, or Pi CLI, run `ouroboros setup --runtime <opencode|kiro|copilot|gemini|pi>` after installation. The Copilot CLI runtime live-discovers its model catalog via the GitHub Copilot models API and lets you pick a default during setup.
 
 <details>
 <summary><strong>Kiro CLI quick start</strong></summary>
@@ -169,7 +169,7 @@ ouroboros setup                         # configure runtime
 
 Legacy compatibility: `ouroboros-ai[dashboard]` is still accepted as a compatibility alias/no-op; it does not install dashboard runtime payload. `ouroboros-ai[all]` includes that no-op alias only for compatibility.
 
-See runtime guides: [Claude Code](./docs/runtime-guides/claude-code.md) · [Codex CLI](./docs/runtime-guides/codex.md) · [Hermes](./docs/runtime-guides/hermes.md) · [OpenCode](./docs/runtime-guides/opencode.md) · [Kiro CLI](./docs/runtime-guides/kiro.md) · [Gemini CLI](./docs/runtime-guides/gemini.md) · [GitHub Copilot CLI](./docs/runtime-guides/copilot.md)
+See runtime guides: [Claude Code](./docs/runtime-guides/claude-code.md) · [Codex CLI](./docs/runtime-guides/codex.md) · [Hermes](./docs/runtime-guides/hermes.md) · [OpenCode](./docs/runtime-guides/opencode.md) · [Kiro CLI](./docs/runtime-guides/kiro.md) · [Gemini CLI](./docs/runtime-guides/gemini.md) · [GitHub Copilot CLI](./docs/runtime-guides/copilot.md) · [Pi JSON mode](https://pi.dev/docs/latest/json)
 
 </details>
 
@@ -335,7 +335,7 @@ src/ouroboros/
 +-- resilience/     4-pattern stagnation detection, 5 lateral personas
 +-- observability/  3-component drift measurement, auto-retrospective
 +-- persistence/    Event sourcing (SQLAlchemy + aiosqlite), checkpoints
-+-- orchestrator/   Runtime abstraction layer (Claude Code, Codex CLI, OpenCode, Hermes)
++-- orchestrator/   Runtime abstraction layer (Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Kiro, Copilot, Pi)
 +-- core/           Types, errors, seed, ontology, security
 +-- providers/      LiteLLM adapter (100+ models)
 +-- mcp/            MCP client/server integration
@@ -351,7 +351,7 @@ src/ouroboros/
 - **Evolution** -- Up to 30 generations, convergence at ontology similarity >= 0.95
 - **Stagnation** -- Detects spinning, oscillation, no-drift, and diminishing returns patterns
 - **Agent OS runtime** -- Replayable execution contract across capability discovery, policy, directives, event journal, and agent processes
-- **Runtime backends** -- Pluggable abstraction layer (`orchestrator.runtime_backend` config) with first-class support for Claude Code, Codex CLI, OpenCode, and Hermes; same workflow spec, different execution engines
+- **Runtime backends** -- Pluggable abstraction layer (`orchestrator.runtime_backend` config) with first-class support for Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Goose, Kiro, Copilot, and Pi; same workflow spec, different execution engines
 
 See [Architecture](./docs/architecture.md) for the full design document.
 

{ouroboros_ai-0.40.2.dev18 → ouroboros_ai-0.40.2.dev20}/docs/architecture.md

@@ -550,7 +550,7 @@ The orchestrator never inspects backend-specific internals — each adapter maps
 - **`KiroAdapter`** (`backend="kiro"`) — Drives the Kiro CLI in headless mode. Module: `src/ouroboros/orchestrator/kiro_adapter.py`
 - **`CopilotCliLLMAdapter`** (`backend="copilot"`) — Drives the GitHub Copilot CLI via `copilot -p`, with live model discovery (queries `https://api.githubcopilot.com/models` at setup) and automatic hyphen-to-dotted model name mapping for cross-runtime config compatibility. Module: `src/ouroboros/providers/copilot_cli_adapter.py`
 - **`PiRuntime`** (`backend="pi"`) — Drives the Pi CLI in documented JSON mode with skill dispatch, session resumption, and JSONL event normalization. Module: `src/ouroboros/orchestrator/pi_runtime.py`
-- **`PiLLMAdapter`** (`backend="pi"`) — Exposes the Pi CLI for unstructured LLM-only flows such as interview and seed generation. Module: `src/ouroboros/providers/pi_llm_adapter.py`
+- **`PiLLMAdapter`** (`backend="pi"`) — Exposes the Pi CLI for LLM-only flows such as interview, ambiguity scoring, seed extraction, and structured JSON responses. Structured `response_format` calls are soft-enforced with prompt instructions plus adapter-side extraction/validation because Pi has no native `--output-schema` flag. Module: `src/ouroboros/providers/pi_llm_adapter.py`
 
 > Each runtime has different tool sets, permission models, and streaming semantics. Ouroboros normalizes these differences at the adapter boundary, but feature parity is not guaranteed across runtimes.
 
@@ -607,4 +607,4 @@ For environment variables, `config.yaml` schema, and all configuration options,
 ---
 
 > For install instructions and first-run onboarding, see **[Getting Started](getting-started.md)**.
-> For backend-specific configuration, see the [Claude Code](runtime-guides/claude-code.md), [Codex CLI](runtime-guides/codex.md), [OpenCode](runtime-guides/opencode.md), [Hermes](runtime-guides/hermes.md), [Gemini](runtime-guides/gemini.md), [Kiro CLI](runtime-guides/kiro.md), and [GitHub Copilot CLI](runtime-guides/copilot.md) runtime guides. For Pi's JSON-mode contract, see the [Pi JSON mode documentation](https://pi.dev/docs/latest/json).
+> For backend-specific configuration, see the [Claude Code](runtime-guides/claude-code.md), [Codex CLI](runtime-guides/codex.md), [OpenCode](runtime-guides/opencode.md), [Hermes](runtime-guides/hermes.md), [Gemini](runtime-guides/gemini.md), [Kiro CLI](runtime-guides/kiro.md), [GitHub Copilot CLI](runtime-guides/copilot.md), and [Pi CLI](runtime-guides/pi.md) references.

{ouroboros_ai-0.40.2.dev18 → ouroboros_ai-0.40.2.dev20}/docs/cli-reference.md

@@ -67,7 +67,7 @@ ouroboros auto "Build a local-first habit tracker CLI"
 | Option | Description |
 |--------|-------------|
 | `--resume TEXT` | Resume an existing auto session id |
-| `--runtime TEXT` | Runtime backend for the **run-handoff** phase. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `kiro`, `copilot`. Authoring phases (interview, seed generation, seed repair) **always run in-process** inside the Ouroboros MCP server in `ooo auto` flow — see [What `--runtime` controls in `ooo auto`](#what---runtime-controls-in-ooo-auto) below. |
+| `--runtime TEXT` | Runtime backend for the **run-handoff** phase. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`. Authoring phases (interview, seed generation, seed repair) **always run in-process** inside the Ouroboros MCP server in `ooo auto` flow — see [What `--runtime` controls in `ooo auto`](#what---runtime-controls-in-ooo-auto) below. |
 | `--max-interview-rounds INTEGER` | Maximum automatic interview rounds; prevents unbounded interview loops |
 | `--max-repair-rounds INTEGER` | Maximum Seed repair rounds; prevents unbounded repair loops |
 | `--skip-run` | Stop after creating an A-grade Seed |
@@ -226,7 +226,7 @@ truth table describes the gate function alone, not the auto flow:
 Detect available runtime backends and configure Ouroboros for your environment.
 
 Ouroboros supports multiple runtime backends via a pluggable `AgentRuntime` protocol. The `setup` command auto-detects
-which runtimes are available in your PATH (currently: Claude Code, Codex CLI, OpenCode) and
+which runtimes are available in your PATH (including Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Kiro, Copilot, Goose, and Pi) and
 configures `orchestrator.runtime_backend` accordingly. Additional runtimes can be registered
 by implementing the protocol — see [Architecture](architecture.md#how-to-add-a-new-runtime-adapter).
 
@@ -238,11 +238,15 @@ ouroboros setup [OPTIONS]
 
 | Option | Description |
 |--------|-------------|
-| `-r, --runtime TEXT` | Runtime backend to configure. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `kiro`. Auto-detected if omitted |
+| `-r, --runtime TEXT` | Runtime backend to configure. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`. Auto-detected if omitted |
 | `--opencode-mode TEXT` | OpenCode integration mode: `plugin` (default, recommended — bridge plugin for interactive sessions) or `subprocess` (headless/CI). Mutually exclusive — see [OpenCode runtime guide](runtime-guides/opencode.md#configuration) |
 | `--non-interactive` | Skip interactive prompts (for scripted installs) |
 | `--mcp-mode TEXT` | Codex MCP config mode: `auto` (default), `preserve`, or `stdio` |
 
+For Pi, setup also installs `~/.pi/agent/extensions/ouroboros-ooo-bridge.ts`.
+Restart Pi or run `/reload` and interactive Pi/roach-pi sessions can dispatch
+`ooo ...` commands into Ouroboros through the shared skill router.
+
 **Examples:**
 
 ```bash
@@ -323,8 +327,8 @@ ouroboros init [start] [OPTIONS] [CONTEXT]
 | `-r, --resume TEXT` | Resume an existing interview by ID |
 | `--state-dir DIRECTORY` | Custom directory for interview state files |
 | `-o, --orchestrator` | Use Claude Code for the interview/seed flow; combine with `--runtime` to choose the workflow handoff backend |
-| `--runtime TEXT` | Agent runtime backend for the workflow execution step after seed generation. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `kiro`. Custom adapters registered in `runtime_factory.py` are also accepted. |
-| `--llm-backend TEXT` | LLM backend for interview, ambiguity scoring, and seed generation (`claude_code`, `litellm`, `codex`, `opencode`, `kiro`) |
+| `--runtime TEXT` | Agent runtime backend for the workflow execution step after seed generation. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`. Custom adapters registered in `runtime_factory.py` are also accepted. |
+| `--llm-backend TEXT` | LLM backend for interview, ambiguity scoring, and seed generation (`claude_code`, `litellm`, `codex`, `copilot`, `opencode`, `gemini`, `goose`, `kiro`, `pi`) |
 | `-d, --debug` | Show verbose logs including debug messages |
 
 **Examples:**
@@ -396,7 +400,7 @@ ouroboros run [workflow] [OPTIONS] SEED_FILE
 | Option | Description |
 |--------|-------------|
 | `-o/-O, --orchestrator/--no-orchestrator` | Use the agent-runtime orchestrator for execution (default: enabled) |
-| `--runtime TEXT` | Agent runtime backend override (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `kiro`). Uses configured default if omitted |
+| `--runtime TEXT` | Agent runtime backend override (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `copilot`, `goose`, `kiro`, `pi`). Uses configured default if omitted |
 | `-r, --resume TEXT` | Resume a previous orchestrator session by ID |
 | `--mcp-config PATH` | Path to MCP client configuration YAML file |
 | `--mcp-tool-prefix TEXT` | Prefix to add to all MCP tool names (e.g., `mcp_`) |
@@ -925,8 +929,8 @@ ouroboros mcp serve [OPTIONS]
 | `-p, --port INTEGER` | Port to bind to (default: 8080) |
 | `-t, --transport TEXT` | Transport type: `stdio`, `sse`, or `streamable-http` (default: stdio). Note: `http` is only a client config alias for outbound MCP connections and is NOT a valid serve transport. |
 | `--db TEXT` | Path to the EventStore database file |
-| `--runtime TEXT` | Agent runtime backend for orchestrator-driven tools (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `kiro`). Affects which tool variants are instantiated |
-| `--llm-backend TEXT` | LLM backend for interview/seed/evaluation tools (`claude_code`, `litellm`, `codex`, `opencode`, `gemini`, `kiro`). Affects which tool variants are instantiated |
+| `--runtime TEXT` | Agent runtime backend for orchestrator-driven tools (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `copilot`, `goose`, `kiro`, `pi`). Affects which tool variants are instantiated |
+| `--llm-backend TEXT` | LLM backend for interview/seed/evaluation tools (`claude_code`, `litellm`, `codex`, `copilot`, `opencode`, `gemini`, `goose`, `kiro`, `pi`). Affects which tool variants are instantiated |
 
 **Examples:**
 
@@ -990,7 +994,7 @@ If Ouroboros is installed directly (not via `uvx`), use:
 
 ```yaml
 orchestrator:
-  runtime_backend: claude   # or "codex", "opencode", "hermes", "gemini", or "kiro"
+  runtime_backend: claude   # or "codex", "opencode", "hermes", "gemini", "copilot", "goose", "kiro", or "pi"
 ```
 
 Override per-session with the `OUROBOROS_AGENT_RUNTIME` environment variable if needed.
@@ -1007,8 +1011,8 @@ ouroboros mcp info [OPTIONS]
 
 | Option | Description |
 |--------|-------------|
-| `--runtime TEXT` | Agent runtime backend for orchestrator-driven tools (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `kiro`). Affects which tool variants are instantiated |
-| `--llm-backend TEXT` | LLM backend for interview/seed/evaluation tools (`claude_code`, `litellm`, `codex`, `opencode`, `gemini`, `kiro`). Affects which tool variants are instantiated |
+| `--runtime TEXT` | Agent runtime backend for orchestrator-driven tools (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `copilot`, `goose`, `kiro`, `pi`). Affects which tool variants are instantiated |
+| `--llm-backend TEXT` | LLM backend for interview/seed/evaluation tools (`claude_code`, `litellm`, `codex`, `copilot`, `opencode`, `gemini`, `goose`, `kiro`, `pi`). Affects which tool variants are instantiated |
 
 **Available Tools:**
 
@@ -1023,7 +1027,7 @@ ouroboros mcp info [OPTIONS]
 ## Typical Workflows
 
 > For first-time setup and the complete onboarding flow, see **[Getting Started](getting-started.md)**.
-> For runtime-specific configuration, see the [Claude Code](runtime-guides/claude-code.md), [Codex CLI](runtime-guides/codex.md), and [OpenCode](runtime-guides/opencode.md) runtime guides.
+> For runtime-specific configuration, see the [Claude Code](runtime-guides/claude-code.md), [Codex CLI](runtime-guides/codex.md), [OpenCode](runtime-guides/opencode.md), [Hermes](runtime-guides/hermes.md), [Gemini](runtime-guides/gemini.md), [Kiro CLI](runtime-guides/kiro.md), [GitHub Copilot CLI](runtime-guides/copilot.md), and [Pi CLI](runtime-guides/pi.md) references.
 
 ### Cancelling Stuck Executions
 
@@ -1046,7 +1050,7 @@ The table below covers the most commonly used variables. For the full list — i
 | `ANTHROPIC_API_KEY` | — | Anthropic API key for Claude models |
 | `OPENAI_API_KEY` | — | OpenAI API key for LiteLLM / Codex CLI |
 | `OPENROUTER_API_KEY` | — | OpenRouter API key for consensus and LiteLLM |
-| `OUROBOROS_AGENT_RUNTIME` | `orchestrator.runtime_backend` | Override the runtime backend (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `kiro`) |
+| `OUROBOROS_AGENT_RUNTIME` | `orchestrator.runtime_backend` | Override the runtime backend (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`) |
 | `OUROBOROS_RUNTIME` | `orchestrator.runtime_backend` (fallback) | Shortcut env var honored by both `orchestrator.runtime_backend` and `llm.backend` resolution when their dedicated env vars are unset |
 | `OUROBOROS_KIRO_CLI_PATH` | `orchestrator.kiro_cli_path` | Explicit path to `kiro-cli` binary when it is not on `PATH` |
 | `OUROBOROS_AGENT_PERMISSION_MODE` | `orchestrator.permission_mode` | Permission mode for Claude Code / Codex runtimes (no-op for OpenCode) |

{ouroboros_ai-0.40.2.dev18 → ouroboros_ai-0.40.2.dev20}/docs/config-reference.md

@@ -766,7 +766,7 @@ llm:
   backend: pi
 ```
 
-Pi is available as an agent runtime backend and, when the Pi LLM adapter is installed, an LLM-only backend for unstructured interview and seed-generation flows. The Pi LLM adapter rejects structured `response_format` requests, so schema-dependent flows such as QA should continue to use a backend with structured output support. The runtime uses documented JSON mode (`pi --mode json <prompt>`) and preserves Pi native session IDs for targeted resume.
+Pi is available as an agent runtime backend and, when the Pi LLM adapter is installed, an LLM-only backend for interview, ambiguity scoring, seed-extraction, and structured JSON flows. `ouroboros setup --runtime pi` records the Pi executable and installs a managed Pi extension at `~/.pi/agent/extensions/ouroboros-ooo-bridge.ts`, so interactive Pi/roach-pi sessions can route exact-prefix `ooo ...` input back into Ouroboros after Pi restart or `/reload`. The Pi LLM adapter supports structured `response_format` requests through prompt-level JSON/schema instructions plus adapter-side extraction and validation; Pi does not expose a Codex-style native `--output-schema` hard-enforcement flag. The runtime uses documented JSON mode (`pi --mode json <prompt>`) and preserves Pi native session IDs for targeted resume.
 
 ### Full Config Skeleton
 

{ouroboros_ai-0.40.2.dev18 → ouroboros_ai-0.40.2.dev20}/docs/getting-started.md

@@ -163,7 +163,7 @@ Use WSL 2 for the supported Windows path, then run the Linux install commands fr
 | OpenCode backend | Python >= 3.12, `opencode` on PATH, provider configured in OpenCode |
 | Kiro CLI backend | Python >= 3.12, `kiro-cli` on PATH (signed in to Kiro), `pip install ouroboros-ai[claude]` (shares the Claude extras for the Agent SDK types). Then `ouroboros setup --runtime kiro` to register the Ouroboros MCP server in `~/.kiro/settings/mcp.json` |
 | GitHub Copilot CLI backend | Python >= 3.12, `copilot` on PATH, `gh` on PATH (`gh auth login`), `pip install 'ouroboros-ai[mcp]'` (or `pipx`/`uv tool` install). Then `ouroboros setup --runtime copilot` to live-discover available models, pick a default, and register the Ouroboros MCP server in `~/.copilot/mcp-config.json` |
-| Pi CLI backend | Python >= 3.12, `pi` on PATH or `orchestrator.pi_cli_path` configured. Use `runtime_backend: pi` for workflow execution and `llm.backend: pi` only for unstructured LLM flows such as interview and seed generation |
+| Pi CLI backend | Python >= 3.12, `pi` on PATH or `orchestrator.pi_cli_path` configured. Use `runtime_backend: pi` for workflow execution. Use `llm.backend: pi` only when authoring/evaluation flows can accept Pi's adapter-level JSON extraction and schema validation rather than native `--output-schema` enforcement |
 
 ---
 
@@ -187,10 +187,10 @@ export OPENAI_API_KEY="your-openai-key"
 
 ```yaml
 orchestrator:
-  runtime_backend: claude   # claude | codex | opencode | hermes | gemini | kiro | copilot | pi
+  runtime_backend: claude   # claude | codex | opencode | hermes | gemini | copilot | goose | kiro | pi
 
 llm:
-  backend: claude_code      # claude_code | codex | litellm | kiro | copilot | pi
+  backend: claude_code      # claude_code | codex | litellm | copilot | opencode | gemini | goose | kiro | pi
 
 logging:
   level: info
@@ -365,6 +365,8 @@ For backend-specific configuration:
 - [OpenCode runtime guide](runtime-guides/opencode.md)
 - [Kiro CLI runtime guide](runtime-guides/kiro.md)
 - [GitHub Copilot CLI runtime guide](runtime-guides/copilot.md)
+- [Pi CLI runtime guide](runtime-guides/pi.md)
+- [Pi JSON mode documentation](https://pi.dev/docs/latest/json)
 
 ---
 

{ouroboros_ai-0.40.2.dev18 → ouroboros_ai-0.40.2.dev20}/docs/runtime-capability-matrix.md

@@ -13,7 +13,7 @@ The runtime backend is selected via the `orchestrator.runtime_backend` config ke
 
 ```yaml
 orchestrator:
-  runtime_backend: claude   # Supported values: claude | codex | opencode | hermes | kiro | copilot | pi
+  runtime_backend: claude   # Supported values: claude | codex | opencode | hermes | gemini | kiro | copilot | pi
                             # The runtime abstraction layer also accepts custom
                             # adapters registered in runtime_factory.py
 ```
@@ -26,7 +26,7 @@ ouroboros run workflow --runtime codex seed.yaml
 
 You can also override the configured backend with the `OUROBOROS_AGENT_RUNTIME` environment variable.
 
-> **Extensibility:** Ouroboros uses a pluggable `AgentRuntime` protocol. Claude Code, Codex CLI, OpenCode, Hermes, Kiro CLI, GitHub Copilot CLI, and Pi CLI are the natively shipped backends; additional runtimes can be registered by implementing the protocol and extending `runtime_factory.py`. See [Architecture — How to add a new runtime adapter](architecture.md#how-to-add-a-new-runtime-adapter).
+> **Extensibility:** Ouroboros uses a pluggable `AgentRuntime` protocol. Claude Code, Codex CLI, OpenCode, Hermes, Gemini CLI, Kiro CLI, GitHub Copilot CLI, and Pi CLI are the natively shipped backends; additional runtimes can be registered by implementing the protocol and extending `runtime_factory.py`. See [Architecture — How to add a new runtime adapter](architecture.md#how-to-add-a-new-runtime-adapter).
 
 ## Capability Matrix
 
@@ -34,41 +34,41 @@ You can also override the configured backend with the `OUROBOROS_AGENT_RUNTIME`
 
 These capabilities are part of the Ouroboros core engine and work the same way regardless of runtime backend.
 
-| Capability                         | Claude Code | Codex CLI | OpenCode | Hermes | Kiro CLI | Copilot CLI | Pi CLI | Notes                                                       |
-| ---------------------------------- | :---------: | :-------: | :------: | :----: | :------: | :---------: | :----: | ----------------------------------------------------------- |
-| Seed file parsing                  |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     |  Yes   | Same YAML schema, same validation                           |
-| Acceptance criteria tree           |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     |  Yes   | Structured AC decomposition                                 |
-| Evaluation principles              |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     |  Yes   | Weighted scoring against principles                         |
-| Exit conditions                    |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     |  Yes   | Deterministic termination logic                             |
-| Event sourcing (SQLite)            |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     |  Yes   | Full event log, replay support                              |
-| Checkpoint / resume                |     Yes     |    Yes    |   Yes    |  Yes   | Partial  |     No      |  Yes   | `--resume <session_id>` everywhere; Kiro forwards to `--resume-id` **when the caller supplies the id** — headless does not surface session ids, so automatic checkpoint/resume is future work; Copilot CLI does not expose a resume API; Pi resumes with its native `--session` flag |
-| TUI dashboard                      |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     |  Yes   | Textual-based progress view                                 |
-| Interview (Socratic seed creation) |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     |  Yes   | `ouroboros init start ...` with the appropriate LLM backend |
-| Dry-run validation                 |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     |  Yes   | `--dry-run` validates without executing                     |
-| Live model discovery               |     No      |    No     |    No    |   No   |    No    |     Yes     |   No   | Only Copilot queries its provider's models API at setup time and lets you pick a default from the live list |
+| Capability                         | Claude Code | Codex CLI | OpenCode | Hermes | Gemini CLI | Kiro CLI | Copilot CLI | Pi CLI | Notes                                                       |
+| ---------------------------------- | :---------: | :-------: | :------: | :----: | :--------: | :------: | :---------: | :----: | ----------------------------------------------------------- |
+| Seed file parsing                  |     Yes     |    Yes    |   Yes    |  Yes   |    Yes     |   Yes    |     Yes     |  Yes   | Same YAML schema, same validation                           |
+| Acceptance criteria tree           |     Yes     |    Yes    |   Yes    |  Yes   |    Yes     |   Yes    |     Yes     |  Yes   | Structured AC decomposition                                 |
+| Evaluation principles              |     Yes     |    Yes    |   Yes    |  Yes   |    Yes     |   Yes    |     Yes     |  Yes   | Weighted scoring against principles                         |
+| Exit conditions                    |     Yes     |    Yes    |   Yes    |  Yes   |    Yes     |   Yes    |     Yes     |  Yes   | Deterministic termination logic                             |
+| Event sourcing (SQLite)            |     Yes     |    Yes    |   Yes    |  Yes   |    Yes     |   Yes    |     Yes     |  Yes   | Full event log, replay support                              |
+| Checkpoint / resume                |     Yes     |    Yes    |   Yes    |  Yes   |     No     | Partial  |     No      |  Yes   | Native resume varies by backend: Claude/Codex/OpenCode/Hermes use `--resume <session_id>`; Gemini and Copilot CLI do not expose native session-resume APIs; Kiro forwards to `--resume-id` **when the caller supplies the id** — headless does not surface session ids, so automatic checkpoint/resume is future work; Pi resumes with its native `--session` flag |
+| TUI dashboard                      |     Yes     |    Yes    |   Yes    |  Yes   |    Yes     |   Yes    |     Yes     |  Yes   | Textual-based progress view                                 |
+| Interview (Socratic seed creation) |     Yes     |    Yes    |   Yes    |  Yes   |    Yes     |   Yes    |     Yes     |  Yes   | `ouroboros init start ...` with the appropriate LLM backend |
+| Dry-run validation                 |     Yes     |    Yes    |   Yes    |  Yes   |    Yes     |   Yes    |     Yes     |  Yes   | `--dry-run` validates without executing                     |
+| Live model discovery               |     No      |    No     |    No    |   No   |     No     |    No    |     Yes     |   No   | Only Copilot queries its provider's models API at setup time and lets you pick a default from the live list |
 
 ### Runtime Layer (differs by backend)
 
 These capabilities depend on the runtime backend's native features and execution model.
 
-| Capability                |             Claude Code             |       Codex CLI       |                         OpenCode                          |                                   Hermes                                   |           Kiro CLI           |                                Copilot CLI                                |             Pi CLI              | Notes                                                            |
-| ------------------------- | :---------------------------------: | :-------------------: | :-------------------------------------------------------: | :------------------------------------------------------------------------: | :--------------------------: | :-----------------------------------------------------------------------: | :-----------------------------: | ---------------------------------------------------------------- |
-| **Authentication**        |        Max Plan subscription        |    OpenAI API key     |        Provider API keys (configured in OpenCode)         |        NousResearch (or compatible provider) API key or local model        |      Kiro AWS sign-in        | GitHub Copilot subscription via `gh auth login`                           | Pi CLI account/session          | No API key needed for Claude Code, Kiro, Copilot, or Pi CLI      |
-| **Underlying model**      |         Claude (Anthropic)          |   GPT-5.4+ (OpenAI)   | Provider-dependent (OpenCode supports multiple providers) | Provider-dependent (Hermes supports multiple providers) or Any local model | Claude (via AWS) + others    | Live-discovered (Claude, GPT-5, etc.; whatever your subscription grants)  | Pi-selected or `--model` value  | Copilot is the only runtime with a live model picker             |
-| **Tool surface**          | Read, Write, Edit, Bash, Glob, Grep | Codex-native tool set |            Read, Write, Edit, Bash, Glob, Grep            |                      Custom skills via MCP + run cmd                       |   Kiro-native tool set       | Read, Write, Edit, Bash, Glob, Grep (via `--available-tools` allowlist)   | Pi-native tool set              | Different tool implementations; same task outcomes               |
-| **Sandbox / permissions** |    Claude Code permission system    |  Codex sandbox model  |                OpenCode permission system                 |                          Hermes permission system                          | `--trust-tools` / `--trust-all-tools` | `--add-dir <CWD>` boundary + `--allow-tool` envelope             | Pi CLI permission model         | Each runtime manages its own safety boundaries                   |
-| **Cost model**            |        Included in Max Plan         | Per-token API charges |              Depends on configured provider               |                            Depends on API/Local                            |    Included in Kiro plan     | Included in Copilot subscription                                          | Depends on Pi account/provider  | See [OpenAI pricing](https://openai.com/pricing) for Codex costs |
-| **Declared capabilities** | skill_dispatch, targeted_resume, structured_output | all three | all three | all three | skill_dispatch only; `targeted_resume=False` (headless does not surface session ids), `structured_output=False` (plain-text stdio) | skill_dispatch only; `targeted_resume=False` (no resume API); `structured_output=False` (no `--output-schema`, JSON via prompt directive) | all three | See `RuntimeCapabilities` on the adapter |
+| Capability                |             Claude Code             |       Codex CLI       |                         OpenCode                          |                                   Hermes                                   |                  Gemini CLI                  |           Kiro CLI           |                                Copilot CLI                                |             Pi CLI              | Notes                                                            |
+| ------------------------- | :---------------------------------: | :-------------------: | :-------------------------------------------------------: | :------------------------------------------------------------------------: | :------------------------------------------: | :--------------------------: | :-----------------------------------------------------------------------: | :-----------------------------: | ---------------------------------------------------------------- |
+| **Authentication**        |        Max Plan subscription        |    OpenAI API key     |        Provider API keys (configured in OpenCode)         |        NousResearch (or compatible provider) API key or local model        | Google auth (`gemini auth` or `GOOGLE_API_KEY`) |      Kiro AWS sign-in        | GitHub Copilot subscription via `gh auth login`                           | Pi provider auth via `/login` or provider API key | No separate Ouroboros API key is needed for Claude Code, Kiro, Copilot, or Pi CLI; Pi still needs its own provider credentials |
+| **Underlying model**      |         Claude (Anthropic)          |   GPT-5.4+ (OpenAI)   | Provider-dependent (OpenCode supports multiple providers) | Provider-dependent (Hermes supports multiple providers) or Any local model | Gemini-selected or `--model` value           | Claude (via AWS) + others    | Live-discovered (Claude, GPT-5, etc.; whatever your subscription grants)  | Pi-selected or `--model` value  | Copilot is the only runtime with a live model picker             |
+| **Tool surface**          | Read, Write, Edit, Bash, Glob, Grep | Codex-native tool set |            Read, Write, Edit, Bash, Glob, Grep            |                      Custom skills via MCP + run cmd                       | Gemini-managed tool set                      |   Kiro-native tool set       | Read, Write, Edit, Bash, Glob, Grep (via `--available-tools` allowlist)   | Pi-native tool set              | Different tool implementations; same task outcomes               |
+| **Sandbox / permissions** |    Claude Code permission system    |  Codex sandbox model  |                OpenCode permission system                 |                          Hermes permission system                          | `--approval-mode auto_edit` / `yolo`         | `--trust-tools` / `--trust-all-tools` | `--add-dir <CWD>` boundary + `--allow-tool` envelope             | Pi CLI permission model         | Each runtime manages its own safety boundaries                   |
+| **Cost model**            |        Included in Max Plan         | Per-token API charges |              Depends on configured provider               |                            Depends on API/Local                            | Depends on Google account/API usage          |    Included in Kiro plan     | Included in Copilot subscription                                          | Depends on Pi account/provider  | See [OpenAI pricing](https://openai.com/pricing) for Codex costs |
+| **Declared capabilities** | skill_dispatch, targeted_resume, structured_output | all three | all three | all three | skill_dispatch and structured_output; `targeted_resume=False` (no native resume API) | skill_dispatch only; `targeted_resume=False` (headless does not surface session ids), `structured_output=False` (plain-text stdio) | skill_dispatch only; `targeted_resume=False` (no resume API); `structured_output=False` (no `--output-schema`, JSON via prompt directive) | all three | See `RuntimeCapabilities` on the adapter |
 
 ### Integration Surface (UX differences)
 
-| Aspect                      | Claude Code                                   | Codex CLI                                                                                                                                                                                                                                                    | OpenCode                                           | Hermes                                           | Kiro CLI                                                                                      | Copilot CLI                                                                                                                                                  | Pi CLI                                      |
-| --------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
-| **Primary UX**              | In-session skills and MCP server              | Session-oriented Ouroboros runtime over Codex CLI transport                                                                                                                                                                                                  | MCP server integration                             | In-session skills and MCP server                 | In-session skills and MCP server (Kiro headless mode)                                         | In-session skills and MCP server (Copilot CLI session)                                                                                                       | Pi CLI JSON-mode runtime                    |
-| **Skill shortcuts (`ooo`)** | Yes -- skills loaded into Claude Code session | Yes -- after `ouroboros setup --runtime codex` installs managed skills into `~/.codex/skills/`, rules into `~/.codex/rules/`, and the MCP/env hookup into `~/.codex/config.toml`. Keep role-specific Ouroboros model overrides in `~/.ouroboros/config.yaml` | Yes -- after `ouroboros setup --runtime opencode`  | Yes -- after `ouroboros setup --runtime hermes`  | Yes -- after `ouroboros setup --runtime kiro` the Ouroboros MCP server is registered in `~/.kiro/settings/mcp.json` with `OUROBOROS_RUNTIME=kiro` / `OUROBOROS_LLM_BACKEND=kiro` baked in | Yes -- after `ouroboros setup --runtime copilot` the MCP server is registered in `~/.copilot/mcp-config.json` with `OUROBOROS_AGENT_RUNTIME=copilot` / `OUROBOROS_LLM_BACKEND=copilot` baked in | Yes -- `SkillInterceptor` routes `ooo <skill>` prefixes before spawning Pi |
-| **MCP integration**         | Native MCP server support                     | Deterministic skill/MCP dispatch through the Ouroboros Codex adapter                                                                                                                                                                                         | Native MCP server support                          | Native MCP server support                        | Native MCP server support; `SkillInterceptor` routes `ooo <skill>` prefixes before spawning Kiro subprocess | Native MCP server support; restart required after first registration so Copilot binds the new child         | Deterministic skill/MCP dispatch through the Ouroboros Pi adapter |
-| **Session context**         | Shares Claude Code session context            | Preserved via runtime handles, native session IDs, and resume support                                                                                                                                                                                        | Session IDs + resume via `--session`               | Preserved via session IDs and internal parser    | Headless runs do not surface session IDs; callers may pass an externally sourced `--resume-id`, but automatic targeted resume is not declared yet | Copilot CLI does not expose a session resume API; checkpointing happens at the Ouroboros lineage layer                                                       | Native Pi session IDs preserved through runtime handles |
-| **Install extras**          | `ouroboros-ai[claude]`                        | `ouroboros-ai` (base package) + `codex` on PATH                                                                                                                                                                                                              | `ouroboros-ai` (base package) + `opencode` on PATH | `ouroboros-ai` (base package) + `hermes` on PATH | `ouroboros-ai[claude]` + `kiro-cli` on PATH                                                   | `ouroboros-ai[mcp]` + `copilot` on PATH + `gh` on PATH (for live model discovery)                                                                            | `ouroboros-ai` (base package) + `pi` on PATH |
+| Aspect                      | Claude Code                                   | Codex CLI                                                                                                                                                                                                                                                    | OpenCode                                           | Hermes                                           | Gemini CLI                                      | Kiro CLI                                                                                      | Copilot CLI                                                                                                                                                  | Pi CLI                                      |
+| --------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
+| **Primary UX**              | In-session skills and MCP server              | Session-oriented Ouroboros runtime over Codex CLI transport                                                                                                                                                                                                  | MCP server integration                             | In-session skills and MCP server                 | Gemini CLI `stream-json` runtime                | In-session skills and MCP server (Kiro headless mode)                                         | In-session skills and MCP server (Copilot CLI session)                                                                                                       | Pi CLI JSON-mode runtime                    |
+| **Skill shortcuts (`ooo`)** | Yes -- skills loaded into Claude Code session | Yes -- after `ouroboros setup --runtime codex` installs managed skills into `~/.codex/skills/`, rules into `~/.codex/rules/`, and the MCP/env hookup into `~/.codex/config.toml`. Keep role-specific Ouroboros model overrides in `~/.ouroboros/config.yaml` | Yes -- after `ouroboros setup --runtime opencode`  | Yes -- after `ouroboros setup --runtime hermes`  | Yes -- adapter-level `ooo <skill>` dispatch after `ouroboros setup --runtime gemini` writes config | Yes -- after `ouroboros setup --runtime kiro` the Ouroboros MCP server is registered in `~/.kiro/settings/mcp.json` with `OUROBOROS_RUNTIME=kiro` / `OUROBOROS_LLM_BACKEND=kiro` baked in | Yes -- after `ouroboros setup --runtime copilot` the MCP server is registered in `~/.copilot/mcp-config.json` with `OUROBOROS_AGENT_RUNTIME=copilot` / `OUROBOROS_LLM_BACKEND=copilot` baked in | Yes -- `SkillInterceptor` routes `ooo <skill>` prefixes before spawning Pi |
+| **MCP integration**         | Native MCP server support                     | Deterministic skill/MCP dispatch through the Ouroboros Codex adapter                                                                                                                                                                                         | Native MCP server support                          | Native MCP server support                        | Deterministic skill/MCP dispatch through the Ouroboros Gemini adapter | Native MCP server support; `SkillInterceptor` routes `ooo <skill>` prefixes before spawning Kiro subprocess | Native MCP server support; restart required after first registration so Copilot binds the new child         | Deterministic skill/MCP dispatch through the Ouroboros Pi adapter |
+| **Session context**         | Shares Claude Code session context            | Preserved via runtime handles, native session IDs, and resume support                                                                                                                                                                                        | Session IDs + resume via `--session`               | Preserved via session IDs and internal parser    | Stateless native CLI; checkpointing happens at the Ouroboros lineage layer | Headless runs do not surface session IDs; callers may pass an externally sourced `--resume-id`, but automatic targeted resume is not declared yet | Copilot CLI does not expose a session resume API; checkpointing happens at the Ouroboros lineage layer                                                       | Native Pi session IDs preserved through runtime handles |
+| **Install extras**          | `ouroboros-ai[claude]`                        | `ouroboros-ai` (base package) + `codex` on PATH                                                                                                                                                                                                              | `ouroboros-ai` (base package) + `opencode` on PATH | `ouroboros-ai` (base package) + `hermes` on PATH | `ouroboros-ai` (base package) + `gemini` on PATH | `ouroboros-ai[claude]` + `kiro-cli` on PATH                                                   | `ouroboros-ai[mcp]` + `copilot` on PATH + `gh` on PATH (for live model discovery)                                                                            | `ouroboros-ai` (base package) + `pi` on PATH |
 
 ## What Stays the Same
 
@@ -150,7 +150,7 @@ hand `opencode_mode="subprocess"` to the authoring handlers.
 
 ## Choosing a Runtime
 
-The table below covers the three currently shipped backends. Because Ouroboros uses a pluggable `AgentRuntime` protocol, teams can register additional backends without modifying the core engine.
+The table below covers the currently shipped backends. Because Ouroboros uses a pluggable `AgentRuntime` protocol, teams can register additional backends without modifying the core engine.
 
 | If you...                                                              | Consider                                                                      |
 | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
@@ -158,13 +158,16 @@ The table below covers the three currently shipped backends. Because Ouroboros u
 | Want a Codex-backed Ouroboros session instead of a Claude Code session | Codex CLI (`runtime_backend: codex`)                                          |
 | Want to use OpenCode with multiple model providers                     | OpenCode (`runtime_backend: opencode`)                                        |
 | Want to use the Hermes Agent (open source local & API agent)           | Hermes (`runtime_backend: hermes`)                                            |
+| Want to use Google's Gemini CLI in headless `stream-json` mode         | Gemini CLI (`runtime_backend: gemini`)                                        |
 | Want to use Kiro CLI (AWS-provided coding agent, browser-free headless) | Kiro (`runtime_backend: kiro`)                                                |
 | Have a GitHub Copilot subscription and want the live model picker       | Copilot CLI (`runtime_backend: copilot`)                                      |
 | Want to use the Pi coding agent through JSON mode                       | Pi CLI (`runtime_backend: pi`)                                                |
 | Want to use Anthropic's Claude models                                  | Claude Code or Copilot CLI (Claude models exposed via Copilot subscription)   |
+| Want to use Google's Gemini models                                     | Gemini CLI                                                                   |
 | Want to use OpenAI's GPT models                                        | Codex CLI or Copilot CLI                                                      |
 | Want to use multiple providers via a single runtime                    | OpenCode or Copilot CLI (Copilot multiplexes Anthropic + OpenAI under one auth) |
-| Need MCP server integration                                            | Claude Code, OpenCode, Hermes, Kiro, or Copilot CLI                           |
+| Need native MCP host integration                                       | Claude Code, OpenCode, Hermes, Kiro, or Copilot CLI                           |
+| Want deterministic adapter-level skill/MCP dispatch                    | Codex CLI, Gemini CLI, or Pi CLI                                              |
 | Want minimal Python dependencies                                       | Codex CLI, OpenCode, or Hermes                                                |
 | Want to integrate a custom or third-party AI coding agent              | Implement the `AgentRuntime` protocol and register it in `runtime_factory.py` |
 
@@ -172,10 +175,12 @@ The table below covers the three currently shipped backends. Because Ouroboros u
 
 - [Claude Code runtime guide](runtime-guides/claude-code.md)
 - [Codex CLI runtime guide](runtime-guides/codex.md)
+- [Gemini CLI runtime guide](runtime-guides/gemini.md)
 - [Hermes Agent runtime guide](runtime-guides/hermes.md)
 - [OpenCode runtime guide](runtime-guides/opencode.md)
 - [Kiro CLI runtime guide](runtime-guides/kiro.md)
 - [GitHub Copilot CLI runtime guide](runtime-guides/copilot.md)
+- [Pi CLI runtime guide](runtime-guides/pi.md)
 - [Pi JSON mode documentation](https://pi.dev/docs/latest/json)
 - [Platform support matrix](platform-support.md) (OS and Python version compatibility)
 - [Architecture overview](architecture.md) — including [How to add a new runtime adapter](architecture.md#how-to-add-a-new-runtime-adapter)

{ouroboros_ai-0.40.2.dev18 → ouroboros_ai-0.40.2.dev20}/docs/runtime-guides/gemini.md

@@ -77,7 +77,7 @@ Each task spawns:
 gemini --prompt <PROMPT> \
        --non-interactive \
        --output-format stream-json \
-       --approval-mode yolo \
+       --approval-mode auto_edit \
        [--model gemini-2.5-pro]
 ```
 
@@ -86,9 +86,21 @@ gemini --prompt <PROMPT> \
 | `--prompt`          | Carries the request (Gemini's documented headless API)  |
 | `--non-interactive` | Disables TTY prompts so the subprocess never blocks     |
 | `--output-format`   | NDJSON event stream parsed by `GeminiEventNormalizer`   |
-| `--approval-mode`   | `yolo` — required for headless approvals                |
+| `--approval-mode`   | `auto_edit` by default (`acceptEdits`); `yolo` only when `bypassPermissions` is explicitly configured |
 | `--model`           | Optional model override (`gemini-2.5-pro`, `flash`)     |
 
+Ouroboros maps its permission modes onto Gemini's non-blocking headless
+approval modes:
+
+| Ouroboros permission mode | Gemini flag value | When used                                      |
+|---------------------------|-------------------|------------------------------------------------|
+| `acceptEdits`             | `auto_edit`       | Default; applies edits without TTY prompts     |
+| `bypassPermissions`       | `yolo`            | Explicit full bypass requested by the operator |
+
+The interactive Ouroboros `default` permission mode is normalized to
+`acceptEdits` for Gemini because `--non-interactive` cannot service TTY
+approval prompts.
+
 ## Event mapping
 
 The runtime parses Gemini's `stream-json` events through