[P4.2] OpenCode adapter — build + parse + capabilities + tests + docs

[frankbria]

Phase 4 — Provider onboarding.

Scope

• lib/agents/opencode.sh:
  • Build: opencode run, --format json (raw events), -s/--session <id> /
    -c/--continue / --fork, -m provider/model, --dangerously-skip-permissions.
  • Parse: OpenCode JSON events -> internal struct.
  • Capabilities: structured=yes, session=resume-id (-s), token usage=verify,
    permission_denials=no (auto-approve model), api_limit=off.
• Tests via [P2.2]; docs/providers/OPENCODE.md; README row.

Acceptance

• ralph --provider opencode drives the loop against a mock. Full suite green.

Depends on: [P3.1].

[github-actions]

🏷️ Triage: Enhancement

This issue has been categorized as an enhancement / feature request and labeled enhancement.

Why: It's an implementation task that adds new capability — a provider adapter (lib/agents/opencode.sh) so ralph --provider opencode can drive the loop, with build/parse/capabilities/tests/docs. It is not a defect in existing behavior, so bug does not apply.

Not a duplicate: This is a unique task within the structured multi-provider epic (it already carries the multi-provider label) and is distinct from the other phase issues such as #310 (P0.1, capability matrix + ADR). Its stated dependency on [P3.1] is a sequencing relationship, not a duplicate.

Recommended next steps:

• Resolve the [P3.1] dependency before starting, since this adapter builds on it.
• Verify the OpenCode CLI capability assumptions against the installed opencode --help (notably token usage=verify).
• Land tests via the [P2.2] harness, add docs/providers/OPENCODE.md, and update the provider README row, per the acceptance criteria.

The enhancement label complements the existing multi-provider epic label.

Generated by Issue Triage Assistant for issue #319 · opus48 397.8K · ◷

[coderabbitai]

Coding Plan

Summary

• Establish a minimal adapter infrastructure (lib/agents/) with interface contract and dispatcher, following the existing sandbox adapter pattern
• Implement OpenCode adapter that normalizes JSONL events to the standard response analysis schema expected by the rest of ralph_loop.sh
• Create disk-based mock executable tests following test_sandbox_*.bats patterns
• Add provider documentation in new docs/providers/ directory and integrate via --provider flag for backward-compatible provider selection

Design Choices

Design Choice 1: Adapter Infrastructure Approach

Options Considered:

1. Create a formal interface template file (lib/agents/_interface.sh) documenting required functions
2. Inline-document expected functions within each adapter file only

Chosen Option: 1

Rationale: A central interface template provides clear contract documentation and enables validation, following the pattern where sandbox adapters share a common interface.

Design Choice 2: Integration Strategy with ralph_loop.sh

Options Considered:

1. Create a dispatcher that sources the appropriate adapter and delegates to adapter-specific functions
2. Refactor build_claude_command() inline to switch on provider type

Chosen Option: 1

Rationale: A separate dispatcher (lib/agents/dispatch.sh) is less invasive, mirrors the sandbox provider pattern, and keeps provider-specific logic isolated.

Design Choice 3: Parse Function Output Format

Options Considered:

1. Adapter parse function produces the same .json_parse_result schema that response_analyzer.sh expects
2. Each adapter defines its own output schema

Chosen Option: 1

Rationale: The rest of ralph_loop.sh depends on the standardized analysis schema; adapters must normalize their output to this common format.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Agent Adapter Infrastructure

Establish the foundational directory structure and interface contract that the OpenCode adapter (and future adapters) will implement.

Task 1: Create Agent Adapter Directory and Interface Contract

Define the adapter interface that all agent providers must implement, providing a clear contract for build, parse, and capabilities functions.

• Create lib/agents/ directory
• Create lib/agents/_interface.sh as a documented template specifying the three required functions:
  • build_<provider>_command() — populates AGENT_CMD_ARGS array with CLI invocation
  • parse_<provider>_response() — transforms provider JSON to standard .json_parse_result schema
  • get_<provider>_capabilities() — returns JSON object with capability flags
• Document expected global variables: AGENT_CMD_ARGS, AGENT_SESSION_ID, AGENT_PROVIDER
• Document the capabilities schema: { structured, session_mode, token_usage, permission_denials, api_limit }

Task 2: Create Agent Dispatcher

Implement a dispatcher that sources the appropriate adapter based on the selected provider and exposes unified function names.

• Create lib/agents/dispatch.sh with functions:
  • load_agent_adapter() — sources lib/agents/<provider>.sh based on AGENT_PROVIDER
  • build_agent_command() — delegates to provider-specific build function
  • parse_agent_response() — delegates to provider-specific parse function
  • get_agent_capabilities() — delegates to provider-specific capabilities function
• Validate that required functions exist after sourcing adapter
• Export dispatcher functions for use by ralph_loop.sh

🤖 Prompt for AI agents

Establish the foundational agent adapter infrastructure by creating the
`lib/agents/` directory with an interface contract and dispatcher.

**Task 1: Create `lib/agents/_interface.sh`**
- Create the `lib/agents/` directory
- Create `lib/agents/_interface.sh` as a documented template (not meant to be
sourced directly) that specifies the three required functions every adapter must
implement:
- `build_<provider>_command()` — populates the `AGENT_CMD_ARGS` global array
with the CLI invocation arguments
- `parse_<provider>_response()` — transforms provider-specific JSON output to
the standard `.json_parse_result` schema
- `get_<provider>_capabilities()` — returns a JSON object with capability flags
- Document expected global variables used across adapters: `AGENT_CMD_ARGS`,
`AGENT_SESSION_ID`, `AGENT_PROVIDER`
- Document the capabilities schema: `{ structured, session_mode, token_usage,
permission_denials, api_limit }`

**Task 2: Create `lib/agents/dispatch.sh`**
- Implement `load_agent_adapter()` that sources `lib/agents/<provider>.sh` based
on the value of `AGENT_PROVIDER`
- Implement `build_agent_command()` that delegates to the provider-specific
`build_<provider>_command()` function
- Implement `parse_agent_response()` that delegates to the provider-specific
`parse_<provider>_response()` function
- Implement `get_agent_capabilities()` that delegates to the provider-specific
`get_<provider>_capabilities()` function
- After sourcing the adapter in `load_agent_adapter()`, validate that the
required provider-specific functions exist; error if they do not
- Export all dispatcher functions for use by `ralph_loop.sh`

Phase 2: OpenCode Adapter Implementation

Implement the OpenCode-specific adapter following the interface contract, handling OpenCode CLI flags and JSON event parsing.

Task 1: Implement OpenCode Build Function

Create the command construction logic for invoking OpenCode CLI with appropriate flags.

• Create lib/agents/opencode.sh
• Implement build_opencode_command() that populates AGENT_CMD_ARGS array with:
  • Base command: opencode run
  • Output format: --format json (JSONL event stream)
  • Session handling: -s <session_id> for resume, -c for continue previous, --fork for branch
  • Model selection: -m <provider/model> from OPENCODE_MODEL env var
  • Permission bypass: --dangerously-skip-permissions when OPENCODE_AUTO_APPROVE=true
  • Prompt: passed as final positional argument
• Read session ID from .ralph/.agent_session_id when resuming
• Support configuration via env vars: OPENCODE_MODEL, OPENCODE_AUTO_APPROVE, OPENCODE_SESSION_MODE

Task 2: Implement OpenCode Parse Function

Transform OpenCode's JSONL event stream into the standard response analysis schema.

• Implement parse_opencode_response() in lib/agents/opencode.sh
• Parse JSONL events line-by-line, handling event types:
  • step_start — extract sessionID, initialize tracking
  • tool_use — count tool invocations, track file modifications from tool outputs
  • text — accumulate model output text, scan for RALPH_STATUS markers
  • step_finish — extract token usage from part.tokens, mark completion
  • error — capture error details, set is_error flag
• Handle known issue: step_finish may be missing; derive completion from event stream end
• Write standardized JSON to .ralph/.json_parse_result matching the schema:
  • status, exit_signal, session_id, files_modified, confidence, summary
  • has_permission_denials: false (auto-approve mode)
• Extract and persist session ID to .ralph/.agent_session_id

Task 3: Implement OpenCode Capabilities Function

Return the capability descriptor for OpenCode's feature set.

• Implement get_opencode_capabilities() in lib/agents/opencode.sh
• Return JSON object:

  { "structured": true, "session_mode": "resume-id", "token_usage": true, 
    "permission_denials": false, "api_limit": false }
  

• structured: true — OpenCode emits structured JSON events
• session_mode: "resume-id" — supports -s <id> for explicit session resume
• token_usage: true — verify availability from step_finish events
• permission_denials: false — auto-approve model bypasses permission tracking
• api_limit: false — no built-in rate limit detection in OpenCode events

🤖 Prompt for AI agents

Implement the OpenCode-specific adapter in `lib/agents/opencode.sh` following
the interface contract established in Phase 1.

**Task 1: `build_opencode_command()`**
- Create `lib/agents/opencode.sh`
- Implement `build_opencode_command()` that populates the `AGENT_CMD_ARGS`
global array with:
  - Base command: `opencode run`
  - Output format flag: `--format json` (JSONL event stream)
- Session handling: `-s <session_id>` for resume (read session ID from
`.ralph/.agent_session_id`), `-c` for continue previous, `--fork` for branch —
controlled by `OPENCODE_SESSION_MODE` env var
  - Model selection: `-m <provider/model>` sourced from `OPENCODE_MODEL` env var
- Permission bypass: `--dangerously-skip-permissions` when
`OPENCODE_AUTO_APPROVE=true`
  - Prompt as final positional argument

**Task 2: `parse_opencode_response()`**
- Implement `parse_opencode_response()` in the same file
- Parse JSONL events line-by-line, handling the following event types:
  - `step_start` — extract `sessionID`, initialize tracking
- `tool_use` — count tool invocations, track file modifications from tool
outputs
  - `text` — accumulate model output text, scan for RALPH_STATUS markers
  - `step_finish` — extract token usage from `part.tokens`, mark completion
  - `error` — capture error details, set `is_error` flag
- Handle the known issue where `step_finish` may be missing by deriving
completion from event stream end
- Write standardized JSON to `.ralph/.json_parse_result` with fields: `status`,
`exit_signal`, `session_id`, `files_modified`, `confidence`, `summary`, and
`has_permission_denials: false`
- Extract and persist session ID to `.ralph/.agent_session_id`

**Task 3: `get_opencode_capabilities()`**
- Implement `get_opencode_capabilities()` in the same file
- Return the following JSON object:
  ```
{ "structured": true, "session_mode": "resume-id", "token_usage": true,
"permission_denials": false, "api_limit": false }
  ```

Phase 3: Testing

Create comprehensive tests for the OpenCode adapter using the established BATS testing patterns.

Task 1: Create OpenCode Mock Executable

Build a disk-based mock that simulates OpenCode CLI responses for deterministic testing.

• Create tests/helpers/mock_opencode.bash with helper functions
• Implement _mock_opencode() that writes executable to $TEST_DIR/mock_bin/opencode:
  • Records invocation arguments to $TEST_DIR/opencode_args
  • Emits scripted JSONL event sequences based on mode parameter
  • Supports modes: ok, session-resume, error, missing-step-finish, tool-use-heavy
• Create fixture functions for common JSONL event sequences:
  • create_opencode_success_events() — step_start, text, step_finish with tokens
  • create_opencode_error_events() — step_start, error event
  • create_opencode_session_events() — events with specific session ID

Task 2: Create OpenCode Adapter Unit Tests

Test each adapter function in isolation with mocked CLI responses.

• Create tests/unit/test_agent_opencode.bats
• Test build_opencode_command():
  • Verify AGENT_CMD_ARGS contains correct base command and flags
  • Test session resume flag inclusion when session ID exists
  • Test model flag from OPENCODE_MODEL env var
  • Test --dangerously-skip-permissions when OPENCODE_AUTO_APPROVE=true
• Test parse_opencode_response():
  • Verify .json_parse_result schema compliance
  • Test session ID extraction from step_start events
  • Test token usage extraction from step_finish
  • Test handling of missing step_finish event
  • Test RALPH_STATUS marker detection in text events
  • Test error event handling sets appropriate flags
• Test get_opencode_capabilities():
  • Verify returned JSON matches expected capability set

Task 3: Create Adapter Dispatcher Tests

Test the dispatcher routing and function delegation.

• Create tests/unit/test_agent_dispatch.bats
• Test load_agent_adapter():
  • Verify correct adapter file is sourced for AGENT_PROVIDER=opencode
  • Verify error handling for unknown provider
  • Verify validation of required functions after load
• Test unified function delegation:
  • build_agent_command() calls through to provider-specific function
  • parse_agent_response() calls through to provider-specific function

🤖 Prompt for AI agents

Create BATS-based tests for the OpenCode adapter and dispatcher using disk-based
mock executables, following the existing `test_sandbox_*.bats` patterns.

**Task 1: Create `tests/helpers/mock_opencode.bash`**
- Implement `_mock_opencode()` that writes an executable mock to
`$TEST_DIR/mock_bin/opencode`
  - The mock records invocation arguments to `$TEST_DIR/opencode_args`
  - Emits scripted JSONL event sequences based on a mode parameter
- Supports modes: `ok`, `session-resume`, `error`, `missing-step-finish`,
`tool-use-heavy`
- Add fixture helper functions for common JSONL event sequences:
- `create_opencode_success_events()` — emits step_start, text, and step_finish
with tokens
  - `create_opencode_error_events()` — emits step_start and an error event
  - `create_opencode_session_events()` — emits events with a specific session ID

**Task 2: Create `tests/unit/test_agent_opencode.bats`**
- Test `build_opencode_command()`:
  - Verify `AGENT_CMD_ARGS` contains the correct base command and flags
  - Test session resume flag inclusion when a session ID file exists
  - Test model flag population from `OPENCODE_MODEL` env var
- Test `--dangerously-skip-permissions` is included when
`OPENCODE_AUTO_APPROVE=true`
- Test `parse_opencode_response()`:
  - Verify `.json_parse_result` schema compliance
  - Test session ID extraction from `step_start` events
  - Test token usage extraction from `step_finish`
  - Test handling of a missing `step_finish` event
  - Test RALPH_STATUS marker detection in `text` events
  - Test that error events set the appropriate flags
- Test `get_opencode_capabilities()`:
  - Verify the returned JSON matches the expected capability set

**Task 3: Create `tests/unit/test_agent_dispatch.bats`**
- Test `load_agent_adapter()`:
  - Verify the correct adapter file is sourced when `AGENT_PROVIDER=opencode`
  - Verify error handling for an unknown provider
  - Verify that required provider-specific functions are validated after loading
- Test unified function delegation:
  - `build_agent_command()` calls through to the provider-specific function
  - `parse_agent_response()` calls through to the provider-specific function

Phase 4: Documentation and Integration

Add provider documentation and wire the adapter into the main Ralph loop.

Task 1: Create OpenCode Provider Documentation

Document OpenCode adapter configuration and usage.

• Create docs/providers/ directory (new documentation pattern for agent providers)
• Create docs/providers/OPENCODE.md covering:
  • Prerequisites: OpenCode CLI installation
  • Configuration: env vars (OPENCODE_MODEL, OPENCODE_AUTO_APPROVE, OPENCODE_SESSION_MODE)
  • Session management: resume vs continue vs fork behavior
  • JSON event format reference
  • Capability limitations vs Claude adapter
  • Troubleshooting: missing step_finish handling, session ID persistence

Task 2: Update README with Provider Table

Add provider documentation and OpenCode row to README.

• Add new "Agent Providers" section to README.md (after existing configuration sections)
• Create provider comparison table with columns: Provider, Structured Output, Session Support, Token Tracking, Permission Tracking
• Add OpenCode row with capability values
• Add placeholder Claude row (for future Claude adapter ticket)
• Link to docs/providers/OPENCODE.md for detailed configuration

Task 3: Integrate --provider Flag into ralph_loop.sh

Wire the adapter dispatcher into the main loop to enable provider selection.

• Add --provider <name> CLI flag parsing in ralph_loop.sh argument handling section
• Add AGENT_PROVIDER env var support with default value claude for backward compatibility
• Source lib/agents/dispatch.sh during initialization (alongside other lib files)
• Call load_agent_adapter() after configuration loading
• Replace build_claude_command() call site with build_agent_command() in execute_claude_code() (or rename function)
• Update .ralphrc.template with AGENT_PROVIDER option and documentation comment

🤖 Prompt for AI agents

Add provider documentation and wire the OpenCode adapter dispatcher into
`ralph_loop.sh` for backward-compatible provider selection.

**Task 1: Create `docs/providers/OPENCODE.md`**
- Create the `docs/providers/` directory
- Create `docs/providers/OPENCODE.md` covering:
  - Prerequisites (OpenCode CLI installation)
- Configuration via env vars: `OPENCODE_MODEL`, `OPENCODE_AUTO_APPROVE`,
`OPENCODE_SESSION_MODE`
  - Session management: resume vs continue vs fork behavior
  - JSON event format reference
  - Capability limitations vs Claude adapter
  - Troubleshooting: missing `step_finish` handling and session ID persistence

**Task 2: Update `README.md`**
- Add a new "Agent Providers" section after existing configuration sections
- Add a provider comparison table with columns: Provider, Structured Output,
Session Support, Token Tracking, Permission Tracking
- Add an OpenCode row with its capability values
- Add a placeholder Claude row (for a future Claude adapter ticket)
- Link to `docs/providers/OPENCODE.md` for detailed configuration

**Task 3: Update `ralph_loop.sh` and `.ralphrc.template`**
- Add `--provider <name>` CLI flag parsing in the argument handling section of
`ralph_loop.sh`
- Add `AGENT_PROVIDER` env var support with default value `claude` for backward
compatibility
- Source `lib/agents/dispatch.sh` during initialization alongside other lib
files
- Call `load_agent_adapter()` after configuration loading
- Replace the `build_claude_command()` call site with `build_agent_command()`
inside `execute_claude_code()` (or rename the function)
- Update `.ralphrc.template` with the `AGENT_PROVIDER` option and a
documentation comment

Research

Ralph is a bash-based automation loop for AI coding agents, currently hardcoded to the Anthropic Claude Code CLI. The lib/ directory contains flat utility files with no existing agents/ subdirectory. The closest adapter pattern exists in lib/sandbox_docker.sh and lib/sandbox_e2b.sh, which use global array population (e.g., build_sandbox_exec_args()) and are dispatched by provider type. Response parsing is centralized in lib/response_analyzer.sh, which produces standardized JSON structs (.json_parse_result and .response_analysis). Tests follow the BATS framework with disk-based executable mocks for external CLI tools.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Establish the foundational agent adapter infrastructure by creating the
`lib/agents/` directory with an interface contract and dispatcher.

**Task 1: Create `lib/agents/_interface.sh`**
- Create the `lib/agents/` directory
- Create `lib/agents/_interface.sh` as a documented template (not meant to be
sourced directly) that specifies the three required functions every adapter must
implement:
- `build_<provider>_command()` — populates the `AGENT_CMD_ARGS` global array
with the CLI invocation arguments
- `parse_<provider>_response()` — transforms provider-specific JSON output to
the standard `.json_parse_result` schema
- `get_<provider>_capabilities()` — returns a JSON object with capability flags
- Document expected global variables used across adapters: `AGENT_CMD_ARGS`,
`AGENT_SESSION_ID`, `AGENT_PROVIDER`
- Document the capabilities schema: `{ structured, session_mode, token_usage,
permission_denials, api_limit }`

**Task 2: Create `lib/agents/dispatch.sh`**
- Implement `load_agent_adapter()` that sources `lib/agents/<provider>.sh` based
on the value of `AGENT_PROVIDER`
- Implement `build_agent_command()` that delegates to the provider-specific
`build_<provider>_command()` function
- Implement `parse_agent_response()` that delegates to the provider-specific
`parse_<provider>_response()` function
- Implement `get_agent_capabilities()` that delegates to the provider-specific
`get_<provider>_capabilities()` function
- After sourcing the adapter in `load_agent_adapter()`, validate that the
required provider-specific functions exist; error if they do not
- Export all dispatcher functions for use by `ralph_loop.sh`
===============================================================================

Task: 2

Implement the OpenCode-specific adapter in `lib/agents/opencode.sh` following
the interface contract established in Phase 1.

**Task 1: `build_opencode_command()`**
- Create `lib/agents/opencode.sh`
- Implement `build_opencode_command()` that populates the `AGENT_CMD_ARGS`
global array with:
  - Base command: `opencode run`
  - Output format flag: `--format json` (JSONL event stream)
- Session handling: `-s <session_id>` for resume (read session ID from
`.ralph/.agent_session_id`), `-c` for continue previous, `--fork` for branch —
controlled by `OPENCODE_SESSION_MODE` env var
  - Model selection: `-m <provider/model>` sourced from `OPENCODE_MODEL` env var
- Permission bypass: `--dangerously-skip-permissions` when
`OPENCODE_AUTO_APPROVE=true`
  - Prompt as final positional argument

**Task 2: `parse_opencode_response()`**
- Implement `parse_opencode_response()` in the same file
- Parse JSONL events line-by-line, handling the following event types:
  - `step_start` — extract `sessionID`, initialize tracking
- `tool_use` — count tool invocations, track file modifications from tool
outputs
  - `text` — accumulate model output text, scan for RALPH_STATUS markers
  - `step_finish` — extract token usage from `part.tokens`, mark completion
  - `error` — capture error details, set `is_error` flag
- Handle the known issue where `step_finish` may be missing by deriving
completion from event stream end
- Write standardized JSON to `.ralph/.json_parse_result` with fields: `status`,
`exit_signal`, `session_id`, `files_modified`, `confidence`, `summary`, and
`has_permission_denials: false`
- Extract and persist session ID to `.ralph/.agent_session_id`

**Task 3: `get_opencode_capabilities()`**
- Implement `get_opencode_capabilities()` in the same file
- Return the following JSON object:
  ```
{ "structured": true, "session_mode": "resume-id", "token_usage": true,
"permission_denials": false, "api_limit": false }
  ```
===============================================================================

Task: 3

Create BATS-based tests for the OpenCode adapter and dispatcher using disk-based
mock executables, following the existing `test_sandbox_*.bats` patterns.

**Task 1: Create `tests/helpers/mock_opencode.bash`**
- Implement `_mock_opencode()` that writes an executable mock to
`$TEST_DIR/mock_bin/opencode`
  - The mock records invocation arguments to `$TEST_DIR/opencode_args`
  - Emits scripted JSONL event sequences based on a mode parameter
- Supports modes: `ok`, `session-resume`, `error`, `missing-step-finish`,
`tool-use-heavy`
- Add fixture helper functions for common JSONL event sequences:
- `create_opencode_success_events()` — emits step_start, text, and step_finish
with tokens
  - `create_opencode_error_events()` — emits step_start and an error event
  - `create_opencode_session_events()` — emits events with a specific session ID

**Task 2: Create `tests/unit/test_agent_opencode.bats`**
- Test `build_opencode_command()`:
  - Verify `AGENT_CMD_ARGS` contains the correct base command and flags
  - Test session resume flag inclusion when a session ID file exists
  - Test model flag population from `OPENCODE_MODEL` env var
- Test `--dangerously-skip-permissions` is included when
`OPENCODE_AUTO_APPROVE=true`
- Test `parse_opencode_response()`:
  - Verify `.json_parse_result` schema compliance
  - Test session ID extraction from `step_start` events
  - Test token usage extraction from `step_finish`
  - Test handling of a missing `step_finish` event
  - Test RALPH_STATUS marker detection in `text` events
  - Test that error events set the appropriate flags
- Test `get_opencode_capabilities()`:
  - Verify the returned JSON matches the expected capability set

**Task 3: Create `tests/unit/test_agent_dispatch.bats`**
- Test `load_agent_adapter()`:
  - Verify the correct adapter file is sourced when `AGENT_PROVIDER=opencode`
  - Verify error handling for an unknown provider
  - Verify that required provider-specific functions are validated after loading
- Test unified function delegation:
  - `build_agent_command()` calls through to the provider-specific function
  - `parse_agent_response()` calls through to the provider-specific function
===============================================================================

Task: 4

Add provider documentation and wire the OpenCode adapter dispatcher into
`ralph_loop.sh` for backward-compatible provider selection.

**Task 1: Create `docs/providers/OPENCODE.md`**
- Create the `docs/providers/` directory
- Create `docs/providers/OPENCODE.md` covering:
  - Prerequisites (OpenCode CLI installation)
- Configuration via env vars: `OPENCODE_MODEL`, `OPENCODE_AUTO_APPROVE`,
`OPENCODE_SESSION_MODE`
  - Session management: resume vs continue vs fork behavior
  - JSON event format reference
  - Capability limitations vs Claude adapter
  - Troubleshooting: missing `step_finish` handling and session ID persistence

**Task 2: Update `README.md`**
- Add a new "Agent Providers" section after existing configuration sections
- Add a provider comparison table with columns: Provider, Structured Output,
Session Support, Token Tracking, Permission Tracking
- Add an OpenCode row with its capability values
- Add a placeholder Claude row (for a future Claude adapter ticket)
- Link to `docs/providers/OPENCODE.md` for detailed configuration

**Task 3: Update `ralph_loop.sh` and `.ralphrc.template`**
- Add `--provider <name>` CLI flag parsing in the argument handling section of
`ralph_loop.sh`
- Add `AGENT_PROVIDER` env var support with default value `claude` for backward
compatibility
- Source `lib/agents/dispatch.sh` during initialization alongside other lib
files
- Call `load_agent_adapter()` after configuration loading
- Replace the `build_claude_command()` call site with `build_agent_command()`
inside `execute_claude_code()` (or rename the function)
- Update `.ralphrc.template` with the `AGENT_PROVIDER` option and a
documentation comment

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!