@enderfga/claw-orchestrator 4.7.0 → 4.8.1

package/README.md

@@ -4,7 +4,7 @@
 
 # Claw Orchestrator
 
-> A runtime for coding agents. Wrap Claude Code, Codex, Gemini, Cursor Agent, OpenCode, or any custom CLI as persistent programmable sessions; coordinate them in multi-agent councils; run autonomous Planner / Coder / Reviewer loops; or hand a five-question interview to an Opus council that ships a deployed web app at `localhost:19000/forge/<slug>/`.
+> A runtime for coding agents. Wrap Claude Code, Codex, Antigravity, Cursor Agent, OpenCode, or any custom CLI as persistent programmable sessions; coordinate them in multi-agent councils; run autonomous Planner / Coder / Reviewer loops; or hand a five-question interview to an Opus council that ships a deployed web app at `localhost:19000/forge/<slug>/`.
 
 [![npm version](https://img.shields.io/npm/v/@enderfga/claw-orchestrator.svg)](https://www.npmjs.com/package/@enderfga/claw-orchestrator)
 [![CI](https://github.com/Enderfga/claw-orchestrator/actions/workflows/ci.yml/badge.svg)](https://github.com/Enderfga/claw-orchestrator/actions/workflows/ci.yml)
@@ -27,11 +27,11 @@ https://github.com/user-attachments/assets/fbd2b0ea-28d8-4387-9894-c29cf15ba030
 | Capability                  | What it does                                                                                                                                                                                                                    | Reference                                                  |
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
 | **Persistent Sessions**     | Long-lived coding agents kept alive across requests, with full context, tool, model, and worktree control.                                                                                                                      | [`sessions.md`](./skills/references/sessions.md)           |
-| **Multi-Engine Runtime**    | One interface over Claude Code, Codex, Gemini, Antigravity (agy), Cursor Agent, OpenCode, and arbitrary custom CLIs.                                                                                                                               | [`multi-engine.md`](./skills/references/multi-engine.md)   |
+| **Multi-Engine Runtime**    | One interface over Claude Code, Codex, Antigravity (agy), Cursor Agent, OpenCode, and arbitrary custom CLIs.                                                                                                                               | [`multi-engine.md`](./skills/references/multi-engine.md)   |
 | **Multi-Agent Council**     | Parallel agents in isolated git worktrees, voting on consensus until they agree.                                                                                                                                                | [`council.md`](./skills/references/council.md)             |
 | **Fan-out**                 | Run one task across N engine/model agents in parallel and collect their answers, with an optional synthesis pass — the cross-engine best-of-N / diverse-perspective primitive (no rounds or worktrees).                          | [`tools.md`](./skills/references/tools.md)                 |
 | **ultracode**               | `session_start({ ultracode: true })` lets Claude orchestrate a dynamic JS workflow and fan out to subagents per task (Claude engine).                                                                                            | [`tools.md`](./skills/references/tools.md)                 |
-| **Autoloop**                | Three-agent autonomous workspace iteration. Chat with the Planner; it spawns Coder + Reviewer into a self-iterating subloop and pushes you on regression, target-hit, or decision points.                                       | [`autoloop.md`](./skills/references/autoloop.md)           |
+| **Autoloop**                | Three-agent autonomous workspace iteration with independent engine/model selection for Planner, Coder, and Reviewer. Chat with the Planner; it spawns Coder + Reviewer into a self-iterating subloop and pushes you on regression, target-hit, or decision points. | [`autoloop.md`](./skills/references/autoloop.md)           |
 | **Ultraapp**                | A three-agent Opus council turns a five-question interview into a deployed web app — Tailwind UI, BYOK, file-queue runtime, smoke test, all live at `localhost:19000/forge/<slug>/`.                                            | [`ultraapp.md`](./skills/references/ultraapp.md)           |
 | **Embedded Dashboard**      | Three-tab UI for Autoloop, Council, and Forge with sidebar lifecycle controls, per-run live event streaming, and cookie-based auth via a `/login` redirect.                                                                     | [`dashboard.md`](./skills/references/dashboard.md)         |
 | **OpenAI-Compatible Proxy** | `POST /v1/chat/completions` translates OpenAI requests into native Anthropic, OpenAI, and Google calls and streams responses back in OpenAI shape. Point any OpenAI-SDK client at the orchestrator without changing call sites. | [`openai-compat.md`](./skills/references/openai-compat.md) |
@@ -91,12 +91,11 @@ Register `clawo-mcp` with any MCP-compatible host: Hermes Agent, Claude Desktop,
 
 | Engine       | CLI        | Tested Version |
 | ------------ | ---------- | -------------- |
-| Claude Code  | `claude`   | 2.1.206        |
-| Codex        | `codex`    | 0.143.0        |
-| Gemini       | `gemini`   | 0.43.0         |
-| Antigravity  | `agy`      | 1.0.16         |
-| Cursor Agent | `agent`    | 2026.03.30     |
-| OpenCode     | `opencode` | 1.1.40         |
+| Claude Code  | `claude`   | 2.1.207        |
+| Codex        | `codex`    | 0.144.1        |
+| Antigravity  | `agy`      | 1.1.1          |
+| Cursor Agent | `agent`    | 2026.07.09-a3815c0 |
+| OpenCode     | `opencode` | 1.17.15        |
 | Custom CLI   | any        | —              |
 
 Any coding CLI that runs as a subprocess can be wired up as a custom engine — see [`multi-engine.md`](./skills/references/multi-engine.md#custom-engine-enginecustom).

package/configs/autoloop-coder-prompt.md

@@ -46,10 +46,10 @@ make Reviewer audits unreliable.
 
 ## Your tools
 
-You are a Claude Code session with the workspace as cwd. You have the full
-file-editing palette: Read, Write, Edit, Glob, Grep, Bash. Use them freely
-on workspace code — that's your job. The role boundary is Rule 1: do not
-touch `plan.md`, `goal.json`, or `tasks/`.
+You are a coding-agent session with the workspace as cwd. Use the selected
+engine's file-reading, editing, search, and shell tools freely on workspace
+code — that's your job. The role boundary is Rule 1: do not touch `plan.md`,
+`goal.json`, or `tasks/`.
 
 You also have **autoloop control tools** via fenced JSON blocks:
 

package/configs/autoloop-planner-prompt.md

@@ -41,15 +41,14 @@ a one-paragraph email is a Coder task.
 > 5. Ask: "Plan ready, spawn the Coder?"
 > 6. On approval, `spawn_subagents` with an initial directive.
 
-### Rule 2 — You CANNOT use Write / Edit / MultiEdit / NotebookEdit
+### Rule 2 — You CANNOT edit workspace source files
 
-These tools have been stripped from your session. Trying to call them will
-error. This is by design: it physically prevents Rule 1 from being violated.
-
-The only way you can author files is the `write_plan` and `write_goal`
-autoloop tools, and those only write to `plan.md` and `goal.json`. There is
-no escape hatch. Bash heredocs that try to write content files are also
-out-of-bounds — they violate Rule 1 even though they're technically possible.
+The orchestrator starts Planner sessions in the engine's native read-only /
+plan mode. Claude additionally has Write / Edit / MultiEdit / NotebookEdit
+removed. The only supported authoring path is the `write_plan` and
+`write_goal` autoloop tools, which write only `plan.md` and `goal.json`.
+Bash heredocs, `tee`, or output redirection that author content files violate
+Rule 1 and must not be used.
 
 ### Rule 3 — Never `spawn_subagents` without explicit user approval
 
@@ -61,7 +60,8 @@ and wait for go / ok / 开干 / 干 / yes / similar. The only exception:
 
 ## Your tools
 
-You are a Claude Code session with the workspace as cwd. You have:
+You are a read-only coding-agent session with the workspace as cwd. Depending
+on the selected engine, equivalent tool names may differ. You have:
 
 | Tool | Purpose |
 |---|---|
@@ -91,7 +91,7 @@ turn. Anything outside the blocks is shown to the user as your chat reply.
 | `write_plan` | `content` (full plan.md body as string), `commit_message?` | Writes `plan.md` to the workspace and git-commits. Re-running replaces the whole file (no patches). |
 | `write_goal` | `content` (full goal.json body as string), `commit_message?` | Same, for `goal.json`. The orchestrator parses the content as JSON before writing; malformed JSON errors back to you. |
 | `notify_user` | `level` ('info'/'warn'/'decision'/'error'), `summary` (one line), `detail?`, `channel?` ('auto'/'wechat'/'webchat'/'both'/'email') | Push the user out-of-band via wechat → whatsapp → email fallback chain. Use sparingly: 5-min dedup applies. |
-| `spawn_subagents` | `coder_model?`, `reviewer_model?`, `initial_directive?: { goal, constraints?, success_criteria?, max_attempts? }` | Start the Coder + Reviewer subloop. Call this **only when the user has explicitly approved the plan** (Rule 3). Optionally include the first directive. |
+| `spawn_subagents` | `coder_engine?`, `coder_model?`, `reviewer_engine?`, `reviewer_model?`, `initial_directive?: { goal, constraints?, success_criteria?, max_attempts? }` | Start the Coder + Reviewer subloop. Omitted fields inherit the run defaults; changing engine/model after that role's session has started is rejected. `custom` may only select a config preloaded by `autoloop_start` or resume; never include custom config, `env`, or `extra` in this block. Call this **only when the user has explicitly approved the plan** (Rule 3). |
 | `send_directive` | `goal`, `constraints?`, `success_criteria?`, `max_attempts?` | Send a fresh directive to Coder for the next iter. |
 | `pause_loop` | `reason` | Halt the Coder/Reviewer subloop at the next iter boundary (you can keep chatting). |
 | `resume_loop` | `{}` | Resume after a pause. |

package/configs/autoloop-reviewer-prompt.md

@@ -35,10 +35,9 @@ orchestrator stalls if you skip it.
 
 ## Your tools
 
-Standard Claude Code palette in the sandbox cwd: Read, Glob, Grep, Bash.
-You technically have Write/Edit too, but Rule 3 confines you to the
-sandbox cwd. The orchestrator does not enforce this at the tool level —
-it enforces it by trusting you.
+Use the selected engine's read, search, and shell tools inside the sandbox
+cwd. You may edit only sandbox memory, scratch, and audit files. Rule 3
+forbids writes outside that cwd; engine-specific tool names may differ.
 
 The current contents of `reviewer_memory.md` are **injected as a frozen
 snapshot in your system prompt** at session start. You do not need to

package/dist/src/autoloop/dispatcher.d.ts

@@ -1,9 +1,7 @@
 /**
- * ClaudeAgentDispatcher — wires the v2 runner to real persistent Claude
- * sessions managed by SessionManager.
- *
- * S2 scope: Planner only (chat-mode, no subagents yet). Coder/Reviewer
- * delivery throws — S4 wires them in.
+ * ClaudeAgentDispatcher — wires the v2 runner to real persistent coding
+ * sessions managed by SessionManager. The historical class name is retained
+ * for compatibility; each Autoloop role may use a different engine.
  *
  * Naming convention:
  *   autoloop-<run_id>-planner
@@ -21,6 +19,7 @@
 import { EventEmitter } from 'node:events';
 import type { SessionManager } from '../session-manager.js';
 import type { Logger } from '../logger.js';
+import { type CustomEngineConfig, type EngineType } from '../types.js';
 import { type AnyAutoloopMessage } from './messages.js';
 import { type AgentDispatcher, type AutoloopState, type PushPolicy } from './types.js';
 import { type SpawnSubagentsArgs } from './planner-tools.js';
@@ -33,12 +32,18 @@ export interface ClaudeAgentDispatcherConfig {
     /** Override Coder/Reviewer prompt paths (defaults walk-up to configs/autoloop-{coder,reviewer}-prompt.md). */
     coderPromptPath?: string;
     reviewerPromptPath?: string;
-    /** Model alias for Planner (default: 'opus'). */
+    /** Planner engine/model (default: claude/opus). */
+    plannerEngine?: EngineType;
     plannerModel?: string;
-    /** Default Coder model (default: 'sonnet'). Can be overridden per spawn_subagents call. */
+    plannerCustomEngine?: CustomEngineConfig;
+    /** Coder defaults. Engine/model can be overridden per spawn_subagents call. */
+    coderEngine?: EngineType;
     coderModel?: string;
-    /** Default Reviewer model (default: 'sonnet'). */
+    coderCustomEngine?: CustomEngineConfig;
+    /** Reviewer defaults. Engine/model can be overridden per spawn_subagents call. */
+    reviewerEngine?: EngineType;
     reviewerModel?: string;
+    reviewerCustomEngine?: CustomEngineConfig;
     /** Per-message wall-clock cap. Default 10 min. */
     sendTimeoutMs?: number;
     logger?: Logger;
@@ -63,6 +68,17 @@ export interface ClaudeAgentDispatcherConfig {
     pushPolicyRef?: PushPolicy;
     /** Called when Planner emits spawn_subagents. S4 implements; S3 records the intent. */
     onSpawnSubagents?: (args: SpawnSubagentsArgs) => Promise<void>;
+    /** Persist the effective non-secret role selection after a successful spawn. */
+    onRoleSelectionChanged?: (selection: {
+        coder: {
+            engine: EngineType;
+            model?: string;
+        };
+        reviewer: {
+            engine: EngineType;
+            model?: string;
+        };
+    }) => Promise<void> | void;
 }
 export declare class ClaudeAgentDispatcher extends EventEmitter implements AgentDispatcher {
     readonly config: ClaudeAgentDispatcherConfig;
@@ -76,8 +92,10 @@ export declare class ClaudeAgentDispatcher extends EventEmitter implements Agent
     private plannerSystemPrompt;
     private coderSystemPrompt;
     private reviewerSystemPrompt;
-    private coderModel;
-    private reviewerModel;
+    private reviewerSessionPrompt;
+    private plannerSelection;
+    private coderSelection;
+    private reviewerSelection;
     /** Where Reviewer reads from. Created lazily by stageReviewSandbox(). */
     private reviewerSandboxDir;
     private ledgerDir;
@@ -92,6 +110,37 @@ export declare class ClaudeAgentDispatcher extends EventEmitter implements Agent
         purge?: boolean;
     }): Promise<void>;
     deliver(env: AnyAutoloopMessage): Promise<AnyAutoloopMessage[]>;
+    private roleModel;
+    private validateSelection;
+    /**
+     * Stop a session we started during a failed spawn. Returns true only when the
+     * session is genuinely gone — the caller uses that to decide whether it may
+     * clear the role's `started` flag. Returning false keeps the role marked as
+     * started, which is the safe lie: a later engine change is then rejected
+     * instead of silently binding the run to a process that never went away.
+     */
+    private stopRolledBackSession;
+    /**
+     * Does this engine carry conversation across sends on its own?
+     *
+     * claude keeps one subprocess alive; codex / codex-app resume a thread; agy
+     * resumes a harvested `--conversation <uuid>`. Everything else (gemini,
+     * cursor, opencode, and non-persistent custom engines) spawns a FRESH process
+     * per send with zero memory of the last turn — for those the dispatcher must
+     * replay the transcript in-band, or the role is amnesiac and a chat-driven
+     * Planner can never remember the plan it just proposed (let alone whether the
+     * user approved it).
+     */
+    private hasNativeConversation;
+    /**
+     * Replayed transcript for engines without native conversation. Capped so a
+     * long run can't grow the prompt without bound: we keep the most recent
+     * turns within REPLAY_CHAR_BUDGET, oldest dropped first.
+     */
+    private transcripts;
+    private recordTurn;
+    private renderHistory;
+    private withRoleInstructions;
     /**
      * Start Coder + Reviewer sessions. Idempotent. Called in response to a
      * Planner spawn_subagents tool (the SessionManager wires this via

package/dist/src/autoloop/dispatcher.js

@@ -1,9 +1,7 @@
 /**
- * ClaudeAgentDispatcher — wires the v2 runner to real persistent Claude
- * sessions managed by SessionManager.
- *
- * S2 scope: Planner only (chat-mode, no subagents yet). Coder/Reviewer
- * delivery throws — S4 wires them in.
+ * ClaudeAgentDispatcher — wires the v2 runner to real persistent coding
+ * sessions managed by SessionManager. The historical class name is retained
+ * for compatibility; each Autoloop role may use a different engine.
  *
  * Naming convention:
  *   autoloop-<run_id>-planner
@@ -22,12 +20,19 @@ import { EventEmitter } from 'node:events';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { ENGINE_TYPES } from '../types.js';
 import { nullLogger } from '../logger.js';
 import { spawn } from 'node:child_process';
 import { Msg } from './messages.js';
-import { LEDGER_SCHEMA_VERSION } from './types.js';
+import { LEDGER_SCHEMA_VERSION, } from './types.js';
 import { applyPlannerToolCalls, parsePlannerReply, } from './planner-tools.js';
 import { extractIterComplete, extractReviewComplete, parseAgentReply } from './agent-tools.js';
+/**
+ * Character budget for the replayed transcript handed to engines without native
+ * conversation (see hasNativeConversation). Oldest turns are dropped first, so a
+ * long run keeps the recent context instead of growing the prompt forever.
+ */
+const REPLAY_CHAR_BUDGET = 24_000;
 /**
  * Files inside <ledger>/reviewer_sandbox/ that survive `stageReviewSandbox`.
  * Anything not listed is wiped between iters. `reviewer_memory.md` is also
@@ -70,8 +75,10 @@ export class ClaudeAgentDispatcher extends EventEmitter {
     plannerSystemPrompt;
     coderSystemPrompt;
     reviewerSystemPrompt;
-    coderModel;
-    reviewerModel;
+    reviewerSessionPrompt = null;
+    plannerSelection;
+    coderSelection;
+    reviewerSelection;
     /** Where Reviewer reads from. Created lazily by stageReviewSandbox(). */
     reviewerSandboxDir;
     ledgerDir;
@@ -86,8 +93,21 @@ export class ClaudeAgentDispatcher extends EventEmitter {
         this.plannerSystemPrompt = fs.readFileSync(promptPath, 'utf-8');
         this.coderSystemPrompt = fs.readFileSync(config.coderPromptPath ?? resolveDefaultCoderPrompt(), 'utf-8');
         this.reviewerSystemPrompt = fs.readFileSync(config.reviewerPromptPath ?? resolveDefaultReviewerPrompt(), 'utf-8');
-        this.coderModel = config.coderModel ?? 'sonnet';
-        this.reviewerModel = config.reviewerModel ?? 'sonnet';
+        this.plannerSelection = {
+            engine: config.plannerEngine ?? 'claude',
+            model: config.plannerModel,
+            customEngine: config.plannerCustomEngine,
+        };
+        this.coderSelection = {
+            engine: config.coderEngine ?? 'claude',
+            model: config.coderModel,
+            customEngine: config.coderCustomEngine,
+        };
+        this.reviewerSelection = {
+            engine: config.reviewerEngine ?? 'claude',
+            model: config.reviewerModel,
+            customEngine: config.reviewerCustomEngine,
+        };
         this.ledgerDir = path.join(config.workspace, 'tasks', config.runId);
         this.reviewerSandboxDir = path.join(this.ledgerDir, 'reviewer_sandbox');
     }
@@ -129,18 +149,198 @@ export class ClaudeAgentDispatcher extends EventEmitter {
                 throw new Error(`[autoloop] unexpected dispatcher target: ${env.to}`);
         }
     }
+    roleModel(role, selection) {
+        if (selection.model !== undefined)
+            return selection.model;
+        if (selection.engine !== 'claude')
+            return undefined;
+        return role === 'planner' ? 'opus' : 'sonnet';
+    }
+    validateSelection(role, selection) {
+        const label = role[0].toUpperCase() + role.slice(1);
+        if (!ENGINE_TYPES.includes(selection.engine)) {
+            throw new Error(`${label} engine '${String(selection.engine)}' is not supported`);
+        }
+        if (selection.engine === 'custom' && !selection.customEngine) {
+            throw new Error(`${label} custom engine config is required`);
+        }
+    }
+    /**
+     * Stop a session we started during a failed spawn. Returns true only when the
+     * session is genuinely gone — the caller uses that to decide whether it may
+     * clear the role's `started` flag. Returning false keeps the role marked as
+     * started, which is the safe lie: a later engine change is then rejected
+     * instead of silently binding the run to a process that never went away.
+     */
+    async stopRolledBackSession(name) {
+        try {
+            await this.config.manager.stopSession(name);
+            return true;
+        }
+        catch (stopErr) {
+            this.logger.error?.(`[autoloop] rollback could not stop ${name}: ${stopErr.message} — ` +
+                `leaving it marked started so a later engine change is rejected rather than silently ignored`);
+            this.appendDecisionLog({
+                kind: 'phase_error',
+                actor: 'dispatcher',
+                payload: { agent: name, phase: 'rollback_stop', error: stopErr.message },
+            });
+            return false;
+        }
+    }
+    /**
+     * Does this engine carry conversation across sends on its own?
+     *
+     * claude keeps one subprocess alive; codex / codex-app resume a thread; agy
+     * resumes a harvested `--conversation <uuid>`. Everything else (gemini,
+     * cursor, opencode, and non-persistent custom engines) spawns a FRESH process
+     * per send with zero memory of the last turn — for those the dispatcher must
+     * replay the transcript in-band, or the role is amnesiac and a chat-driven
+     * Planner can never remember the plan it just proposed (let alone whether the
+     * user approved it).
+     */
+    hasNativeConversation(selection) {
+        switch (selection.engine) {
+            case 'claude':
+            case 'codex':
+            case 'codex-app':
+            case 'agy':
+                return true;
+            case 'custom':
+                // A persistent custom engine is a long-running stdin/stdout process, so
+                // it keeps context the same way claude does. One-shot ones do not.
+                return selection.customEngine?.persistent === true;
+            default:
+                return false;
+        }
+    }
+    /**
+     * Replayed transcript for engines without native conversation. Capped so a
+     * long run can't grow the prompt without bound: we keep the most recent
+     * turns within REPLAY_CHAR_BUDGET, oldest dropped first.
+     */
+    transcripts = {
+        planner: [],
+        coder: [],
+        reviewer: [],
+    };
+    recordTurn(role, who, text) {
+        if (!text)
+            return;
+        const log = this.transcripts[role];
+        log.push({ who, text });
+        let budget = REPLAY_CHAR_BUDGET;
+        let keepFrom = log.length;
+        for (let i = log.length - 1; i >= 0; i--) {
+            budget -= log[i].text.length;
+            if (budget < 0)
+                break;
+            keepFrom = i;
+        }
+        if (keepFrom > 0)
+            log.splice(0, keepFrom);
+    }
+    renderHistory(role, selection) {
+        if (this.hasNativeConversation(selection))
+            return null;
+        const log = this.transcripts[role];
+        if (log.length === 0)
+            return null;
+        const lines = log.map((entry) => `<${entry.who}>\n${entry.text}\n</${entry.who}>`);
+        return ['<conversation_history>', ...lines, '</conversation_history>'].join('\n');
+    }
+    withRoleInstructions(role, selection, systemPrompt, message) {
+        if (selection.engine === 'claude')
+            return message;
+        const parts = ['<autoloop_role_instructions>', systemPrompt.trim(), '</autoloop_role_instructions>', ''];
+        const history = this.renderHistory(role, selection);
+        if (history)
+            parts.push(history, '');
+        parts.push('<autoloop_message>', message, '</autoloop_message>');
+        return parts.join('\n');
+    }
     /**
      * Start Coder + Reviewer sessions. Idempotent. Called in response to a
      * Planner spawn_subagents tool (the SessionManager wires this via
      * onSpawnSubagents).
      */
     async spawnSubagents(args = {}) {
-        if (args.coder_model)
-            this.coderModel = args.coder_model;
-        if (args.reviewer_model)
-            this.reviewerModel = args.reviewer_model;
-        await this.ensureCoder();
-        await this.ensureReviewer();
+        const nextCoderEngine = args.coder_engine ?? this.coderSelection.engine;
+        const nextReviewerEngine = args.reviewer_engine ?? this.reviewerSelection.engine;
+        const nextCoder = {
+            ...this.coderSelection,
+            engine: nextCoderEngine,
+            model: args.coder_model !== undefined
+                ? args.coder_model
+                : nextCoderEngine !== this.coderSelection.engine
+                    ? undefined
+                    : this.coderSelection.model,
+        };
+        const nextReviewer = {
+            ...this.reviewerSelection,
+            engine: nextReviewerEngine,
+            model: args.reviewer_model !== undefined
+                ? args.reviewer_model
+                : nextReviewerEngine !== this.reviewerSelection.engine
+                    ? undefined
+                    : this.reviewerSelection.model,
+        };
+        this.validateSelection('coder', nextCoder);
+        this.validateSelection('reviewer', nextReviewer);
+        const coderChanged = nextCoder.engine !== this.coderSelection.engine ||
+            this.roleModel('coder', nextCoder) !== this.roleModel('coder', this.coderSelection);
+        const reviewerChanged = nextReviewer.engine !== this.reviewerSelection.engine ||
+            this.roleModel('reviewer', nextReviewer) !== this.roleModel('reviewer', this.reviewerSelection);
+        if (this.coderStarted && coderChanged) {
+            throw new Error('Cannot change Coder engine or model after its session has started');
+        }
+        if (this.reviewerStarted && reviewerChanged) {
+            throw new Error('Cannot change Reviewer engine or model after its session has started');
+        }
+        const previousCoder = this.coderSelection;
+        const previousReviewer = this.reviewerSelection;
+        const coderWasStarted = this.coderStarted;
+        const reviewerWasStarted = this.reviewerStarted;
+        this.coderSelection = nextCoder;
+        this.reviewerSelection = nextReviewer;
+        try {
+            await this.ensureCoder();
+            await this.ensureReviewer();
+        }
+        catch (err) {
+            // Roll back only what THIS call started. Crucially, `<role>Started` may be
+            // cleared only when the stop actually succeeded: SessionManager.startSession
+            // returns the EXISTING session for a name that is still live and ignores the
+            // new engine/model. So if we lied about the session being gone, the next
+            // spawn_subagents would sail past the "engine cannot change after start"
+            // guard, silently reuse the old engine's process, and still record the new
+            // engine in decisions.jsonl and the registry — the exact divergence that
+            // guard exists to prevent.
+            if (!coderWasStarted && this.coderStarted) {
+                this.coderStarted = !(await this.stopRolledBackSession(this.coderName));
+            }
+            if (!reviewerWasStarted && this.reviewerStarted) {
+                this.reviewerStarted = !(await this.stopRolledBackSession(this.reviewerName));
+            }
+            this.coderSelection = previousCoder;
+            this.reviewerSelection = previousReviewer;
+            throw err;
+        }
+        const effectiveSelection = {
+            coder: { engine: nextCoder.engine, model: nextCoder.model },
+            reviewer: { engine: nextReviewer.engine, model: nextReviewer.model },
+        };
+        this.appendDecisionLog({
+            kind: 'spawn_subagents',
+            actor: 'planner',
+            payload: {
+                coder_engine: nextCoder.engine,
+                coder_model: this.roleModel('coder', nextCoder),
+                reviewer_engine: nextReviewer.engine,
+                reviewer_model: this.roleModel('reviewer', nextReviewer),
+            },
+        });
+        await this.config.onRoleSelectionChanged?.(effectiveSelection);
     }
     /**
      * Reset a single subagent — stop its session, clear the started flag, and
@@ -171,8 +371,10 @@ export class ClaudeAgentDispatcher extends EventEmitter {
             this.plannerStarted = false;
         if (agent === 'coder')
             this.coderStarted = false;
-        if (agent === 'reviewer')
+        if (agent === 'reviewer') {
             this.reviewerStarted = false;
+            this.reviewerSessionPrompt = null;
+        }
         if (opts.eagerRestart) {
             if (agent === 'planner')
                 await this.ensurePlanner();
@@ -314,12 +516,15 @@ export class ClaudeAgentDispatcher extends EventEmitter {
     async ensurePlanner() {
         if (this.plannerStarted)
             return;
+        this.validateSelection('planner', this.plannerSelection);
         await this.config.manager.startSession({
             name: this.plannerName,
             cwd: this.config.workspace,
-            engine: 'claude',
-            model: this.config.plannerModel ?? 'opus',
-            permissionMode: 'bypassPermissions',
+            engine: this.plannerSelection.engine,
+            model: this.roleModel('planner', this.plannerSelection),
+            customEngine: this.plannerSelection.engine === 'custom' ? this.plannerSelection.customEngine : undefined,
+            permissionMode: this.plannerSelection.engine === 'claude' ? 'bypassPermissions' : 'manual',
+            sandboxMode: this.plannerSelection.engine === 'claude' ? undefined : 'read-only',
             systemPrompt: this.plannerSystemPrompt,
             // Hard role boundary: Planner must NEVER author content files itself.
             // Its only writes are plan.md / goal.json via the write_plan /
@@ -355,7 +560,7 @@ export class ClaudeAgentDispatcher extends EventEmitter {
             // iter_done
             promptText = `[system] iter ${env.iter} done. verdict=${env.payload.verdict} metric=${env.payload.metric}`;
         }
-        const result = (await this.config.manager.sendMessage(this.plannerName, promptText, {
+        const result = (await this.config.manager.sendMessage(this.plannerName, this.withRoleInstructions('planner', this.plannerSelection, this.plannerSystemPrompt, promptText), {
             timeout: this.config.sendTimeoutMs ?? 10 * 60_000,
         }));
         if (result.error) {
@@ -363,6 +568,11 @@ export class ClaudeAgentDispatcher extends EventEmitter {
             this.emit('planner_error', new Error(result.error));
         }
         const replyText = (result.output ?? '').trim();
+        // Feed the transcript that engines without native conversation replay next
+        // turn. Recorded AFTER the send so the current message isn't duplicated in
+        // its own history block.
+        this.recordTurn('planner', 'user', promptText);
+        this.recordTurn('planner', 'agent', replyText);
         // S3: parse autoloop-fenced tool calls out of the reply, apply effects,
         // and bubble emitted messages back into the runner queue.
         const parsed = parsePlannerReply(replyText);
@@ -371,16 +581,11 @@ export class ClaudeAgentDispatcher extends EventEmitter {
         }
         const effects = {
             spawnSubagents: async (args) => {
-                this.appendDecisionLog({
-                    kind: 'spawn_subagents',
-                    actor: 'planner',
-                    payload: { args },
-                });
                 if (this.config.onSpawnSubagents) {
                     await this.config.onSpawnSubagents(args);
                 }
                 else {
-                    this.logger.warn?.('[autoloop] spawn_subagents called but no handler installed (S4 not wired yet)');
+                    this.logger.warn?.('[autoloop] spawn_subagents called but no handler is installed');
                 }
             },
             updatePushPolicy: (delta) => {
@@ -470,11 +675,13 @@ export class ClaudeAgentDispatcher extends EventEmitter {
     async ensureCoder() {
         if (this.coderStarted)
             return;
+        this.validateSelection('coder', this.coderSelection);
         await this.config.manager.startSession({
             name: this.coderName,
             cwd: this.config.workspace,
-            engine: 'claude',
-            model: this.coderModel,
+            engine: this.coderSelection.engine,
+            model: this.roleModel('coder', this.coderSelection),
+            customEngine: this.coderSelection.engine === 'custom' ? this.coderSelection.customEngine : undefined,
             permissionMode: 'bypassPermissions',
             systemPrompt: this.coderSystemPrompt,
         });
@@ -526,7 +733,9 @@ export class ClaudeAgentDispatcher extends EventEmitter {
             text: `🔨 Coder iter ${env.iter} working…`,
             ts: new Date().toISOString(),
         });
-        const result = await this.sendWithRecovery('coder', this.coderName, promptText);
+        const result = await this.sendWithRecovery('coder', this.coderName, this.withRoleInstructions('coder', this.coderSelection, this.coderSystemPrompt, promptText));
+        this.recordTurn('coder', 'user', promptText);
+        this.recordTurn('coder', 'agent', (result.output ?? '').trim());
         // A3: subprocess died (recovery retry exhausted). Surface as phase_error
         // rather than silently masquerading as a "clarification request"; the
         // runner's circuit breaker can then trip after enough consecutive failures.
@@ -645,16 +854,26 @@ export class ClaudeAgentDispatcher extends EventEmitter {
     async ensureReviewer() {
         if (this.reviewerStarted)
             return;
+        this.validateSelection('reviewer', this.reviewerSelection);
         fs.mkdirSync(this.reviewerSandboxDir, { recursive: true });
-        await this.config.manager.startSession({
-            name: this.reviewerName,
-            cwd: this.reviewerSandboxDir,
-            engine: 'claude',
-            model: this.reviewerModel,
-            permissionMode: 'bypassPermissions',
-            systemPrompt: this.buildReviewerSystemPrompt(),
-        });
-        this.reviewerStarted = true;
+        const sessionPrompt = this.buildReviewerSystemPrompt();
+        this.reviewerSessionPrompt = sessionPrompt;
+        try {
+            await this.config.manager.startSession({
+                name: this.reviewerName,
+                cwd: this.reviewerSandboxDir,
+                engine: this.reviewerSelection.engine,
+                model: this.roleModel('reviewer', this.reviewerSelection),
+                customEngine: this.reviewerSelection.engine === 'custom' ? this.reviewerSelection.customEngine : undefined,
+                permissionMode: 'bypassPermissions',
+                systemPrompt: sessionPrompt,
+            });
+            this.reviewerStarted = true;
+        }
+        catch (err) {
+            this.reviewerSessionPrompt = null;
+            throw err;
+        }
     }
     /**
      * Stage the iter's artifacts into the Reviewer sandbox cwd. Reviewer is a
@@ -724,7 +943,9 @@ export class ClaudeAgentDispatcher extends EventEmitter {
             text: `🔍 Reviewer iter ${env.payload.iter} auditing…`,
             ts: new Date().toISOString(),
         });
-        const result = await this.sendWithRecovery('reviewer', this.reviewerName, promptText);
+        const result = await this.sendWithRecovery('reviewer', this.reviewerName, this.withRoleInstructions('reviewer', this.reviewerSelection, this.reviewerSessionPrompt ?? this.reviewerSystemPrompt, promptText));
+        this.recordTurn('reviewer', 'user', promptText);
+        this.recordTurn('reviewer', 'agent', (result.output ?? '').trim());
         if (result.fatal) {
             this.appendDecisionLog({
                 kind: 'phase_error',