[Phase 4] Agent Adapter Architecture: Delegate to Frontier Coding Agents

[frankbria]

Summary

Refactor CodeFrame's execution layer so that frontier coding agents (Claude Code, Codex, OpenCode, Kilocode, etc.) are first-class execution engines, with CodeFrame's built-in ReactAgent as a fallback. CodeFrame becomes the orchestrator (PRD → tasks → dependencies → verification → PR) while delegating the actual code writing to whatever tool does it best.

Problem Statement

CodeFrame currently implements its own ReAct agent with 7 custom tools, a 4-level fuzzy editor, 3-tier token compaction, and adaptive iteration budgets. This is fundamentally trying to compete with Claude Code, Codex, OpenCode, and Kilocode — tools backed by entire engineering teams dedicated to making the best coding agent.

CodeFrame's actual value is everything around the coding agent:

• PRD generation and task decomposition
• Dependency graph analysis and batch scheduling
• Verification gates (ruff, pytest) with self-correction loops
• Human-in-the-loop blocker resolution
• State machine and lifecycle management
• PR workflow and Git integration
• Workspace hooks and configuration

None of this exists in Claude Code, Codex, or OpenCode. They write code for a single task. CodeFrame manages the full development lifecycle.

Architectural Vision

Current (CodeFrame IS the agent)

CLI → Runtime → ReactAgent → Anthropic API → custom tools → files
                    ↑
         CodeFrame owns ALL of this

Proposed (CodeFrame ORCHESTRATES agents)

CLI → Runtime → AgentAdapter → ┌─ claude-code (subprocess)
                    │          ├─ codex (app-server protocol)
                    │          ├─ opencode (subprocess)
                    │          ├─ kilocode (extension protocol)
                    │          ├─ custom (configurable)
                    │          └─ built-in (ReactAgent fallback)
                    │
         CodeFrame still owns:
         ✅ Task context assembly
         ✅ Verification gates + self-correction
         ✅ Stall detection & blocker escalation
         ✅ State machine & lifecycle
         ✅ Batch orchestration
         ✅ Workspace hooks
         ✅ PR workflow

Key Design Principle

The AgentAdapter protocol defines what CodeFrame needs from any coding agent:

1. Input: Task description + context (files, PRD, constraints)
2. Output: Modified files + status (success/failure/blocked)
3. Streaming: Progress events for observability

CodeFrame doesn't care how the agent writes code. It cares what happened (files changed, tests pass, blockers hit).

Sub-Issues

Implementation is broken into atomic sub-issues:

• [Phase 4] Agent Adapter Protocol Definition #409 — Agent Adapter Protocol (interface definition)
• [Phase 4] Task Context Packager for External Agents #410 — Task Context Packager (rich context → agent-consumable prompt)
• [Phase 4] Claude Code Engine Adapter #411 — Claude Code engine adapter (subprocess)
• [Phase 4] Codex/OpenAI Engine Adapter (App-Server Protocol) #412 — Codex/OpenAI engine adapter (app-server protocol)
• [Phase 4] OpenCode Engine Adapter #416 — OpenCode engine adapter (subprocess)
• [Phase 4] Kilocode Engine Adapter (VS Code Extension Protocol) #417 — Kilocode engine adapter (extension protocol)
• [Phase 4] Engine Registry and Runtime Selection #414 — Runtime engine registry and selection
• [Phase 4] Verification Gate Wrapper for External Agents #415 — Verification gate wrapper for external agents

#413 — Aider adapter (closed, replaced by #416 OpenCode and #417 Kilocode)

Dependency Graph

#409 (protocol) ──┬──> #411 (Claude Code adapter)
                  ├──> #412 (Codex adapter)
                  ├──> #416 (OpenCode adapter)
                  ├──> #417 (Kilocode adapter)
                  ├──> #414 (engine registry) ──> needs ≥1 adapter
                  └──> #415 (verification wrapper)
                  
#410 (context packager) ──> feeds into #411, #412, #416, #417

#409 and #410 are independent foundations.
#411, #412, #416, #417 are independent adapters (can be done in parallel).
#414 ties everything together.
#415 can be done in parallel with adapters.

What Stays the Same

• core/react_agent.py — remains as the --engine built-in fallback
• core/context.py — context loading (feeds into the new packager)
• core/gates.py — verification gates
• core/runtime.py — run lifecycle (extended with new engine types)
• core/conductor.py — batch orchestration
• All CLI commands — just the --engine flag gets new values

What This Means for the Roadmap

This should be early Phase 4 work because:

1. It unblocks multi-agent by making agents interchangeable
2. It dramatically reduces CodeFrame's maintenance burden
3. It makes CodeFrame immediately useful today with Claude Code or OpenCode
4. The built-in ReactAgent becomes the "no internet / no subscription" fallback

Acceptance Criteria

• cf work start <id> --execute --engine claude-code delegates to Claude Code CLI
• cf work start <id> --execute --engine opencode delegates to OpenCode
• cf work start <id> --execute --engine built-in uses existing ReactAgent
• All engines receive the same rich task context from CodeFrame
• Verification gates run after ANY engine completes (not just built-in)
• Self-correction loop works: gate failure → re-invoke engine with error context
• Batch execution works with any engine
• Engine is configurable per-workspace (CODEFRAME.md/AGENTS.md)

[traycerai]

Plan

Observations

The codebase has a clean separation: codeframe/core/ is headless domain logic; codeframe/cli/app.py is the entry point; and codeframe/core/runtime.py's execute_agent() is the single choke-point that decides which engine runs. Today execute_agent() validates only "plan" and "react" engines and hard-codes ReactAgent/Agent instantiation. conductor.py already threads an engine field through BatchRun and _execute_task_subprocess(). context.py's ContextLoader and TaskContext.to_prompt_context() already produce a rich, serialisable context string — perfect for feeding external agents. The adapters/llm/base.py pattern (Protocol via ABC + data-class results) is the right model to replicate for the new AgentAdapter.

Approach

Introduce an AgentAdapter Protocol in codeframe/core/adapters/ that mirrors the existing LLMProvider pattern. Implement three concrete adapters (Claude Code, Codex, Aider) as subprocess wrappers, a TaskContextPackager that converts TaskContext into an agent-readable prompt, a VerificationWrapper that applies gates.run() after any adapter completes, and an EngineRegistry for lookup and workspace-config-driven selection. Plug everything into the existing execute_agent() call site — the CLI and conductor need no structural changes, only --engine value expansion.

---

Implementation Steps

Step 1 — AgentAdapter Protocol (#409)

Create file:codeframe/core/adapters/__init__.py and file:codeframe/core/adapters/agent_adapter.py.

Define the following using Python typing.Protocol (consistent with LLMProvider as ABC, but Protocol is more flexible here since external adapters won't subclass):

AgentResult  (dataclass)
  status: Literal["completed", "failed", "blocked"]
  output: str            # human-readable summary / stdout
  modified_files: list[str]
  error: str | None
  blocker_question: str | None

AgentEvent  (dataclass)
  type: str              # "progress", "tool_call", "output", etc.
  data: dict

AgentAdapter  (Protocol)
  name: str
  def run(
      self,
      task_id: str,
      prompt: str,           # assembled by TaskContextPackager
      workspace_path: Path,
      on_event: Callable[[AgentEvent], None] | None = None,
  ) -> AgentResult: ...

Keep AgentResult.status values aligned with the existing AgentStatus enum in codeframe/core/agent.py so the bridge in execute_agent() stays trivial.

---

Step 2 — TaskContextPackager (#410)

Create file:codeframe/core/context_packager.py.

This thin wrapper over ContextLoader and TaskContext.to_prompt_context():

• Instantiates ContextLoader(workspace) and calls loader.load(task_id) to get a TaskContext.
• Calls context.to_prompt_context() to produce the base markdown prompt.
• Appends a "Constraints" section drawn from workspace's AGENTS.md/CLAUDE.md preferences (already in context.preferences.to_prompt_section()).
• Appends a "Gate requirements" section listing which gates will run post-execution (ruff, pytest, etc.) so the external agent knows the success criteria.
• Returns (prompt: str, context: TaskContext) — the packager exposes both so the verification wrapper can later diff modified files.

The TaskContextPackager.build(workspace, task_id) -> tuple[str, TaskContext] method is the sole public interface.

---

Step 3 — Claude Code adapter (#411)

Create file:codeframe/core/adapters/claude_code.py.

ClaudeCodeAdapter implements AgentAdapter:

• Checks that claude CLI is available via shutil.which("claude") on construction; raises EnvironmentError with a clear install message if missing.
• Assembles the subprocess command: ["claude", "--print", "--dangerously-skip-permissions"] with the prompt piped via stdin or a temp-file flag, running cwd=workspace.repo_path.
• Streams stdout line-by-line, calling on_event(AgentEvent(type="output", data={"line": ...})) per line using subprocess.Popen with stdout=PIPE.
• On exit code 0 → AgentResult(status="completed", ...).
• On exit code != 0 → inspect stderr/stdout for blocker keywords (classify_error_for_blocker from codeframe/core/blocker_detection.py) and set status="blocked" or status="failed" accordingly.
• Does not run verification gates — that is the VerificationWrapper's job.

No new library dependencies: subprocess from stdlib.

---

Step 4 — Codex adapter (#412)

Create file:codeframe/core/adapters/codex.py.

CodexAdapter implements AgentAdapter:

• Checks for codex binary via shutil.which("codex").
• Builds the invocation: ["codex", "--approval-mode", "full-auto", "--quiet"] with the prompt written to a temp file and passed via --context flag (or stdin if the CLI supports it — verify from codex --help at runtime).
• Streams output and maps exit codes to AgentResult the same way as ClaudeCodeAdapter.

---

Step 5 — OpenCode adapter (#416)

Create file:codeframe/core/adapters/opencode.py.

OpenCodeAdapter implements AgentAdapter:

• Checks for opencode binary via shutil.which("opencode").
• Builds invocation: ["opencode", "--auto-approve", "--silent"] with the prompt piped via stdin or passed as a temp file, running cwd=workspace.repo_path.
• Streams stdout line-by-line via subprocess.Popen, calling on_event(AgentEvent(...)) per line.
• Maps exit code 0 → AgentResult(status="completed").
• Maps non-zero exit codes: inspect stderr/stdout for blocker keywords using classify_error_for_blocker() from codeframe/core/blocker_detection.py, set status="blocked" or status="failed" accordingly.

---

Step 6 — Kilocode adapter (#417)

Create file:codeframe/core/adapters/kilocode.py.

KilocodeAdapter implements AgentAdapter:

• Checks for kilocode binary via shutil.which("kilocode").
• Builds invocation using the Kilocode extension protocol: ["kilocode", "--mode", "auto", "--workspace", "<workspace_path>"] with the prompt written to a temp file and passed via --context flag.
• Streams output and maps exit codes to AgentResult following the same pattern as OpenCodeAdapter.

---

Step 7 — Engine registry and selection (#414)

Create file:codeframe/core/engine_registry.py.

BUILTIN_ENGINES = {
    "react":        <lazy factory for ReactAgent wrapper>,
    "plan":         <lazy factory for Agent wrapper>,
    "claude-code":  ClaudeCodeAdapter,
    "codex":        CodexAdapter,
    "opencode":     OpenCodeAdapter,
    "kilocode":     KilocodeAdapter,
}

def get_adapter(engine: str, workspace: Workspace, **kwargs) -> AgentAdapter: ...
def resolve_engine(workspace: Workspace, cli_engine: str | None) -> str: ...

resolve_engine priority order:

1. CLI --engine flag (explicit wins)
2. workspace.config field default_engine (if stored in .codeframe/config.json)
3. CODEFRAME_ENGINE environment variable
4. Falls back to "react"

To wrap ReactAgent and Agent (which don't implement AgentAdapter) without modifying them, add file:codeframe/core/adapters/builtin.py with two thin shim adapters (BuiltinReactAdapter, BuiltinPlanAdapter) that delegate to the existing constructors and map AgentStatus → AgentResult.status.

---

Step 8 — Verification gate wrapper (#415)

Create file:codeframe/core/adapters/verification_wrapper.py.

VerificationWrapper wraps any AgentAdapter:

class VerificationWrapper:
    def __init__(self, inner: AgentAdapter, max_correction_rounds: int = 3): ...
    def run(self, task_id, prompt, workspace_path, on_event=None) -> AgentResult: ...

Internal loop:

1. Call inner.run(...) → AgentResult.
2. If status != "completed" → return as-is (no point running gates).
3. Run gates.run(workspace) → GateResult.
4. If gates pass → return AgentResult(status="completed").
5. If gates fail → append failure output to prompt as a "Fix the following gate failures" section and re-invoke inner.run(...) (up to max_correction_rounds).
6. If still failing after all rounds → return AgentResult(status="failed", error=<gate output>).

This is the exact same self-correction loop that ReactAgent._run_final_verification() uses, but decoupled from the ReAct engine so it wraps any adapter.

---

Step 9 — Wire into execute_agent() in runtime.py

Modify file:codeframe/core/runtime.py → execute_agent():

1. Expand valid_engines to include "claude-code", "codex", "opencode", "kilocode".
2. For external engines (not "plan" / "react"):
   • Call TaskContextPackager(workspace).build(task_id) → (prompt, context).
   • Call get_adapter(engine, workspace) from engine_registry.
   • Wrap with VerificationWrapper(adapter).
   • Call wrapper.run(task_id, prompt, workspace.repo_path, on_event=on_agent_event).
   • Map AgentResult.status → AgentStatus → complete_run / fail_run / block_run (same logic as today).
3. Remove the hard-coded API key check for external engines (those tools manage their own auth).
4. Keep the plan/react branches exactly as they are.

This is the only change needed in runtime.py.

sequenceDiagram
    participant CLI as cli/app.py
    participant RT as runtime.execute_agent()
    participant REG as EngineRegistry
    participant PKG as TaskContextPackager
    participant ADP as ConcreteAdapter
    participant VW as VerificationWrapper
    participant GT as gates.run()

    CLI->>RT: execute_agent(workspace, run, engine="claude-code")
    RT->>PKG: build(workspace, task_id)
    PKG-->>RT: (prompt, context)
    RT->>REG: get_adapter("claude-code", workspace)
    REG-->>RT: ClaudeCodeAdapter
    RT->>VW: VerificationWrapper(adapter)
    RT->>VW: wrapper.run(task_id, prompt, workspace_path)
    VW->>ADP: inner.run(task_id, prompt, workspace_path)
    ADP-->>VW: AgentResult(status="completed")
    VW->>GT: gates.run(workspace)
    GT-->>VW: GateResult(passed=True)
    VW-->>RT: AgentResult(status="completed")
    RT->>RT: complete_run(workspace, run.id)

Loading

---

Step 10 — Extend --engine validation in CLI

Modify file:codeframe/cli/app.py → work_start():

• Update the help string for --engine to list all valid values: react | plan | claude-code | codex | opencode | kilocode.
• Remove the require_anthropic_api_key() check when engine is an external adapter (those adapters do their own environment validation at instantiation time).
• The engine_mode display string already reads from the flag, no other changes needed.

Modify file:codeframe/cli/app.py → work batch run command:

• The --engine flag already flows through start_batch() → BatchRun.engine → _execute_task_subprocess() → subprocess --engine flag. No structural changes needed; the subprocess picks up the new engine value automatically.

---

Step 11 — Workspace-level engine configuration

Modify file:codeframe/core/workspace.py (or file:codeframe/core/config.py) to read a default_engine field from the workspace config file (.codeframe/config.json). This allows AGENTS.md/CODEFRAME.md to specify default_engine: claude-code and have it respected without a CLI flag.

In resolve_engine() (Step 6), read this field via workspace.config.get("default_engine").

---

Module Summary

New file	Purpose
codeframe/core/adapters/__init__.py	Package init, re-exports
codeframe/core/adapters/agent_adapter.py	AgentAdapter Protocol, AgentResult, AgentEvent
codeframe/core/adapters/builtin.py	Shim wrappers for ReactAgent and Agent
codeframe/core/adapters/claude_code.py	Claude Code subprocess adapter
codeframe/core/adapters/codex.py	Codex subprocess adapter
codeframe/core/adapters/opencode.py	OpenCode subprocess adapter
codeframe/core/adapters/kilocode.py	Kilocode extension protocol adapter
codeframe/core/adapters/verification_wrapper.py	Gate-wrapping decorator for any adapter
codeframe/core/context_packager.py	TaskContextPackager — rich prompt assembly
codeframe/core/engine_registry.py	Adapter lookup + engine resolution

Modified file	Change
codeframe/core/runtime.py	execute_agent() — route to adapters for external engines
codeframe/cli/app.py	Expand --engine help text; conditional API key check
codeframe/core/workspace.py	Read default_engine from config

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a clean separation: `codeframe/core/` is headless domain logic; `codeframe/cli/app.py` is the entry point; and `codeframe/core/runtime.py`'s `execute_agent()` is the single choke-point that decides which engine runs. Today `execute_agent()` validates only `"plan"` and `"react"` engines and hard-codes `ReactAgent`/`Agent` instantiation. `conductor.py` already threads an `engine` field through `BatchRun` and `_execute_task_subprocess()`. `context.py`'s `ContextLoader` and `TaskContext.to_prompt_context()` already produce a rich, serialisable context string — perfect for feeding external agents. The `adapters/llm/base.py` pattern (Protocol via ABC + data-class results) is the right model to replicate for the new `AgentAdapter`.

## Approach

Introduce an `AgentAdapter` Protocol in `codeframe/core/adapters/` that mirrors the existing `LLMProvider` pattern. Implement three concrete adapters (Claude Code, Codex, Aider) as subprocess wrappers, a `TaskContextPackager` that converts `TaskContext` into an agent-readable prompt, a `VerificationWrapper` that applies `gates.run()` after any adapter completes, and an `EngineRegistry` for lookup and workspace-config-driven selection. Plug everything into the existing `execute_agent()` call site — the CLI and conductor need no structural changes, only `--engine` value expansion.

---

## Implementation Steps

### Step 1 — `AgentAdapter` Protocol (`#409`)

Create `file:codeframe/core/adapters/__init__.py` and `file:codeframe/core/adapters/agent_adapter.py`.

Define the following using Python `typing.Protocol` (consistent with `LLMProvider` as ABC, but Protocol is more flexible here since external adapters won't subclass):

```
AgentResult  (dataclass)
  status: Literal["completed", "failed", "blocked"]
  output: str            # human-readable summary / stdout
  modified_files: list[str]
  error: str | None
  blocker_question: str | None

AgentEvent  (dataclass)
  type: str              # "progress", "tool_call", "output", etc.
  data: dict

AgentAdapter  (Protocol)
  name: str
  def run(
      self,
      task_id: str,
      prompt: str,           # assembled by TaskContextPackager
      workspace_path: Path,
      on_event: Callable[[AgentEvent], None] | None = None,
  ) -> AgentResult: ...
```

Keep `AgentResult.status` values aligned with the existing `AgentStatus` enum in `codeframe/core/agent.py` so the bridge in `execute_agent()` stays trivial.

---

### Step 2 — `TaskContextPackager` (`#410`)

Create `file:codeframe/core/context_packager.py`.

This thin wrapper over `ContextLoader` and `TaskContext.to_prompt_context()`:

- Instantiates `ContextLoader(workspace)` and calls `loader.load(task_id)` to get a `TaskContext`.
- Calls `context.to_prompt_context()` to produce the base markdown prompt.
- Appends a **"Constraints" section** drawn from workspace's `AGENTS.md`/`CLAUDE.md` preferences (already in `context.preferences.to_prompt_section()`).
- Appends a **"Gate requirements" section** listing which gates will run post-execution (ruff, pytest, etc.) so the external agent knows the success criteria.
- Returns `(prompt: str, context: TaskContext)` — the packager exposes both so the verification wrapper can later diff modified files.

The `TaskContextPackager.build(workspace, task_id) -> tuple[str, TaskContext]` method is the sole public interface.

---

### Step 3 — Claude Code adapter (`#411`)

Create `file:codeframe/core/adapters/claude_code.py`.

`ClaudeCodeAdapter` implements `AgentAdapter`:

- Checks that `claude` CLI is available via `shutil.which("claude")` on construction; raises `EnvironmentError` with a clear install message if missing.
- Assembles the subprocess command: `["claude", "--print", "--dangerously-skip-permissions"]` with the prompt piped via `stdin` or a temp-file flag, running `cwd=workspace.repo_path`.
- Streams stdout line-by-line, calling `on_event(AgentEvent(type="output", data={"line": ...}))` per line using `subprocess.Popen` with `stdout=PIPE`.
- On exit code 0 → `AgentResult(status="completed", ...)`.
- On exit code != 0 → inspect stderr/stdout for blocker keywords (`classify_error_for_blocker` from `codeframe/core/blocker_detection.py`) and set `status="blocked"` or `status="failed"` accordingly.
- Does **not** run verification gates — that is the `VerificationWrapper`'s job.

No new library dependencies: `subprocess` from stdlib.

---

### Step 4 — Codex adapter (`#412`)

Create `file:codeframe/core/adapters/codex.py`.

`CodexAdapter` implements `AgentAdapter`:

- Checks for `codex` binary via `shutil.which("codex")`.
- Builds the invocation: `["codex", "--approval-mode", "full-auto", "--quiet"]` with the prompt written to a temp file and passed via `--context` flag (or `stdin` if the CLI supports it — verify from `codex --help` at runtime).
- Streams output and maps exit codes to `AgentResult` the same way as `ClaudeCodeAdapter`.

---

### Step 5 — OpenCode adapter (`#416`)

Create `file:codeframe/core/adapters/opencode.py`.

`OpenCodeAdapter` implements `AgentAdapter`:

- Checks for `opencode` binary via `shutil.which("opencode")`.
- Builds invocation: `["opencode", "--auto-approve", "--silent"]` with the prompt piped via `stdin` or passed as a temp file, running `cwd=workspace.repo_path`.
- Streams stdout line-by-line via `subprocess.Popen`, calling `on_event(AgentEvent(...))` per line.
- Maps exit code 0 → `AgentResult(status="completed")`.
- Maps non-zero exit codes: inspect stderr/stdout for blocker keywords using `classify_error_for_blocker()` from `codeframe/core/blocker_detection.py`, set `status="blocked"` or `status="failed"` accordingly.

---

### Step 6 — Kilocode adapter (`#417`)

Create `file:codeframe/core/adapters/kilocode.py`.

`KilocodeAdapter` implements `AgentAdapter`:

- Checks for `kilocode` binary via `shutil.which("kilocode")`.
- Builds invocation using the Kilocode extension protocol: `["kilocode", "--mode", "auto", "--workspace", "<workspace_path>"]` with the prompt written to a temp file and passed via `--context` flag.
- Streams output and maps exit codes to `AgentResult` following the same pattern as `OpenCodeAdapter`.

---

### Step 7 — Engine registry and selection (`#414`)

Create `file:codeframe/core/engine_registry.py`.

```
BUILTIN_ENGINES = {
    "react":        <lazy factory for ReactAgent wrapper>,
    "plan":         <lazy factory for Agent wrapper>,
    "claude-code":  ClaudeCodeAdapter,
    "codex":        CodexAdapter,
    "opencode":     OpenCodeAdapter,
    "kilocode":     KilocodeAdapter,
}

def get_adapter(engine: str, workspace: Workspace, **kwargs) -> AgentAdapter: ...
def resolve_engine(workspace: Workspace, cli_engine: str | None) -> str: ...
```

`resolve_engine` priority order:
1. CLI `--engine` flag (explicit wins)
2. `workspace.config` field `default_engine` (if stored in `.codeframe/config.json`)
3. `CODEFRAME_ENGINE` environment variable
4. Falls back to `"react"`

To wrap `ReactAgent` and `Agent` (which don't implement `AgentAdapter`) without modifying them, add `file:codeframe/core/adapters/builtin.py` with two thin shim adapters (`BuiltinReactAdapter`, `BuiltinPlanAdapter`) that delegate to the existing constructors and map `AgentStatus` → `AgentResult.status`.

---

### Step 8 — Verification gate wrapper (`#415`)

Create `file:codeframe/core/adapters/verification_wrapper.py`.

`VerificationWrapper` wraps any `AgentAdapter`:

```python
class VerificationWrapper:
    def __init__(self, inner: AgentAdapter, max_correction_rounds: int = 3): ...
    def run(self, task_id, prompt, workspace_path, on_event=None) -> AgentResult: ...
```

Internal loop:
1. Call `inner.run(...)` → `AgentResult`.
2. If `status != "completed"` → return as-is (no point running gates).
3. Run `gates.run(workspace)` → `GateResult`.
4. If gates pass → return `AgentResult(status="completed")`.
5. If gates fail → append failure output to `prompt` as a **"Fix the following gate failures"** section and re-invoke `inner.run(...)` (up to `max_correction_rounds`).
6. If still failing after all rounds → return `AgentResult(status="failed", error=<gate output>)`.

This is the exact same self-correction loop that `ReactAgent._run_final_verification()` uses, but decoupled from the ReAct engine so it wraps any adapter.

---

### Step 9 — Wire into `execute_agent()` in `runtime.py`

Modify `file:codeframe/core/runtime.py` → `execute_agent()`:

1. Expand `valid_engines` to include `"claude-code"`, `"codex"`, `"opencode"`, `"kilocode"`.
2. For external engines (not `"plan"` / `"react"`):
   - Call `TaskContextPackager(workspace).build(task_id)` → `(prompt, context)`.
   - Call `get_adapter(engine, workspace)` from `engine_registry`.
   - Wrap with `VerificationWrapper(adapter)`.
   - Call `wrapper.run(task_id, prompt, workspace.repo_path, on_event=on_agent_event)`.
   - Map `AgentResult.status` → `AgentStatus` → `complete_run` / `fail_run` / `block_run` (same logic as today).
3. Remove the hard-coded API key check for external engines (those tools manage their own auth).
4. Keep the plan/react branches exactly as they are.

This is the **only change** needed in `runtime.py`.

```mermaid
sequenceDiagram
    participant CLI as cli/app.py
    participant RT as runtime.execute_agent()
    participant REG as EngineRegistry
    participant PKG as TaskContextPackager
    participant ADP as ConcreteAdapter
    participant VW as VerificationWrapper
    participant GT as gates.run()

    CLI->>RT: execute_agent(workspace, run, engine="claude-code")
    RT->>PKG: build(workspace, task_id)
    PKG-->>RT: (prompt, context)
    RT->>REG: get_adapter("claude-code", workspace)
    REG-->>RT: ClaudeCodeAdapter
    RT->>VW: VerificationWrapper(adapter)
    RT->>VW: wrapper.run(task_id, prompt, workspace_path)
    VW->>ADP: inner.run(task_id, prompt, workspace_path)
    ADP-->>VW: AgentResult(status="completed")
    VW->>GT: gates.run(workspace)
    GT-->>VW: GateResult(passed=True)
    VW-->>RT: AgentResult(status="completed")
    RT->>RT: complete_run(workspace, run.id)
```

---

### Step 10 — Extend `--engine` validation in CLI

Modify `file:codeframe/cli/app.py` → `work_start()`:

- Update the help string for `--engine` to list all valid values: `react | plan | claude-code | codex | opencode | kilocode`.
- Remove the `require_anthropic_api_key()` check when engine is an external adapter (those adapters do their own environment validation at instantiation time).
- The `engine_mode` display string already reads from the flag, no other changes needed.

Modify `file:codeframe/cli/app.py` → `work batch run` command:

- The `--engine` flag already flows through `start_batch()` → `BatchRun.engine` → `_execute_task_subprocess()` → subprocess `--engine` flag. No structural changes needed; the subprocess picks up the new engine value automatically.

---

### Step 11 — Workspace-level engine configuration

Modify `file:codeframe/core/workspace.py` (or `file:codeframe/core/config.py`) to read a `default_engine` field from the workspace config file (`.codeframe/config.json`). This allows `AGENTS.md`/`CODEFRAME.md` to specify `default_engine: claude-code` and have it respected without a CLI flag.

In `resolve_engine()` (Step 6), read this field via `workspace.config.get("default_engine")`.

---

### Module Summary

| New file | Purpose |
|---|---|
| `codeframe/core/adapters/__init__.py` | Package init, re-exports |
| `codeframe/core/adapters/agent_adapter.py` | `AgentAdapter` Protocol, `AgentResult`, `AgentEvent` |
| `codeframe/core/adapters/builtin.py` | Shim wrappers for `ReactAgent` and `Agent` |
| `codeframe/core/adapters/claude_code.py` | Claude Code subprocess adapter |
| `codeframe/core/adapters/codex.py` | Codex subprocess adapter |
| `codeframe/core/adapters/opencode.py` | OpenCode subprocess adapter |
| `codeframe/core/adapters/kilocode.py` | Kilocode extension protocol adapter |
| `codeframe/core/adapters/verification_wrapper.py` | Gate-wrapping decorator for any adapter |
| `codeframe/core/context_packager.py` | `TaskContextPackager` — rich prompt assembly |
| `codeframe/core/engine_registry.py` | Adapter lookup + engine resolution |

| Modified file | Change |
|---|---|
| `codeframe/core/runtime.py` | `execute_agent()` — route to adapters for external engines |
| `codeframe/cli/app.py` | Expand `--engine` help text; conditional API key check |
| `codeframe/core/workspace.py` | Read `default_engine` from config |

---

Execution Information

Branch: main
Commit: 705b160

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

🔗 Related PRs

#9 - Merge Sprint 4 Multi-Agent Coordination work into main [merged]
#246 - feat(agents): trigger multi-agent execution after task approval [merged]
#356 - fix: agent execution resilience + Phase 2.5 architecture research [merged]
#363 - feat: wire ReactAgent into runtime with --engine react CLI flag [merged]
#364 - feat: phase-based event emission for ReactAgent progress reporting [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!