@enderfga/claw-orchestrator 4.7.0 → 4.8.1

package/skills/references/autoloop.md

@@ -21,12 +21,39 @@ This page is the operator reference.
 
 ## Roles
 
-| Agent | Engine (default) | cwd | Owns |
+| Agent | Default | cwd | Owns |
 |---|---|---|---|
 | **Planner** | claude / opus | workspace | strategy, `plan.md`, `goal.json`, talking to you |
-| **Coder** | claude / sonnet (override per spawn) | workspace | code changes, eval execution |
+| **Coder** | claude / sonnet | workspace | code changes, eval execution |
 | **Reviewer** | claude / sonnet | `<workspace>/tasks/<run_id>/reviewer_sandbox/` | distrust audit; advance / hold / rollback |
 
+Each role can use any built-in engine, or a `custom` engine config supplied by a
+local caller (custom engines name an executable, so the HTTP API does not accept
+them — see [tools.md](./tools.md)). If a non-Claude role omits `model`, that CLI
+uses its own default model rather than receiving the Claude `opus` / `sonnet`
+defaults. Role instructions are included in-band for engines that do not expose a
+native system-prompt flag.
+
+Engines without native multi-turn conversation (Cursor, OpenCode, one-shot custom
+engines) spawn a fresh process per send, so the dispatcher replays that role's
+transcript in-band as a `<conversation_history>` block, oldest turns dropped past a
+character budget. Claude, Codex and Antigravity keep context themselves and get no
+replay.
+
+The Planner runs read-only so strategy cannot turn into source edits, and that is
+enforced by the engine rather than requested politely: Claude uses plan mode,
+Antigravity and Cursor use their plan modes, and OpenCode gets a generated
+`clawo-readonly` agent that denies `edit`/`bash`/`external_directory` (its built-in
+`plan` agent is a user-overridable preset that denies neither, so a "read-only"
+session could otherwise still author files through a shell heredoc). A custom
+Planner receives `permissionMode: 'manual'` and its `CustomEngineConfig` **must**
+map that mode to the CLI's read-only flag — if it cannot, the session refuses to
+start rather than silently running write-enabled.
+
+Coder and Reviewer engine/model choices can be overridden by the first successful
+`spawn_subagents`; later attempts to change an already-started role are rejected
+instead of silently diverging from the running session.
+
 Coder and Reviewer **never speak to you directly**. Anything they observe
 flows through the Planner. The Planner decides what to surface and what to
 absorb.
@@ -78,7 +105,7 @@ curl -X POST http://127.0.0.1:18789/v1/openclaw/tools/autoloop_stop \
 
 | Tool | Args | What |
 |---|---|---|
-| `autoloop_start` | `run_id`, `workspace`, `planner_model?`, `send_timeout_ms?` | Start a run; launches Planner session. |
+| `autoloop_start` | `run_id`, `workspace`, per-role `*_engine?`, `*_model?`, `*_custom_engine?`, `send_timeout_ms?` | Start a run; launches Planner and stores Coder/Reviewer defaults. Each `custom` role requires its matching config. |
 | `autoloop_chat` | `run_id`, `text` | Send a chat message to the Planner; returns the Planner's reply. |
 | `autoloop_status` | `run_id` | Current state (status, iter, push count, subagents_spawned). |
 | `autoloop_list` | — | All active runs in this manager process. |
@@ -94,7 +121,7 @@ never see the JSON — only the Planner's narrative.
 | Tool | Args | What |
 |---|---|---|
 | `notify_user` | `level` ('info' / 'warn' / 'decision' / 'error'), `summary`, `detail?`, `channel?` ('auto' / 'wechat' / 'webchat' / 'both' / 'email') | Push you out-of-band. |
-| `spawn_subagents` | `coder_model?`, `reviewer_model?`, `initial_directive?` | Start Coder + Reviewer. Only after explicit user approval. |
+| `spawn_subagents` | `coder_engine?`, `coder_model?`, `reviewer_engine?`, `reviewer_model?`, `initial_directive?` | Start Coder + Reviewer. Omitted values inherit run defaults. An engine change without a model uses the new engine's default. Once a role session has started, changing its engine/model is rejected. Custom configs cannot be emitted by Planner. Only after explicit user approval. |
 | `send_directive` | `goal`, `constraints?`, `success_criteria?`, `max_attempts?` | Next iter's instruction to Coder. |
 | `pause_loop` | `reason` | Halt subloop at next iter boundary; chat keeps working. |
 | `resume_loop` | — | Resume after pause. |
@@ -103,6 +130,22 @@ never see the JSON — only the Planner's narrative.
 | `write_plan` | `content` (full plan.md body), `commit_message?` | Write `plan.md` to the workspace and git-commit. The **only** way the Planner can author plan.md — Write/Edit are stripped from the Planner session as a hard role boundary. Re-running replaces the whole file. |
 | `write_goal` | `content` (full goal.json body), `commit_message?` | Same, for `goal.json`. Content is JSON-validated before write; malformed content errors back to the Planner. |
 
+### Custom engines and resume
+
+Custom engine configs are accepted only by `autoloop_start` (or the HTTP resume
+body), never through Planner output. This keeps config fields such as `env` and
+static CLI arguments out of the Planner transcript and `decisions.jsonl`.
+The central registry persists only each role's engine and model, including the
+effective Coder/Reviewer selection after a successful spawn. Resume leaves the
+prior append-only row untouched until startup succeeds, so a transient CLI
+failure cannot erase the run. When resuming a run that uses `custom`, provide
+the matching `planner_custom_engine`, `coder_custom_engine`, or
+`reviewer_custom_engine` again; otherwise resume fails with a clear
+configuration error rather than silently switching to Claude. Custom config
+shape is validated at runtime, while its `env` and static CLI arguments remain
+out of registry and audit records. See [`multi-engine.md`](./multi-engine.md)
+for the `CustomEngineConfig` shape.
+
 ## Default push policy
 
 | Event | Default |
@@ -211,13 +254,13 @@ Every JSON artifact in the ledger carries a `schema_version` field (currently
 | Endpoint | Returns |
 |---|---|
 | `GET /autoloop/list` | `{ ok, runs: AutoloopState[] }` |
-| `POST /autoloop/new` | `{ ok, run_id, planner_session }` — body `{ workspace, run_id?, planner_model?, send_timeout_ms? }` |
+| `POST /autoloop/new` | `{ ok, run_id, planner_session }` — body `{ workspace, run_id?, planner_engine?, planner_model?, planner_custom_engine?, coder_engine?, coder_model?, coder_custom_engine?, reviewer_engine?, reviewer_model?, reviewer_custom_engine?, send_timeout_ms? }` |
 | `GET /autoloop/<id>/state` | `{ ok, state: AutoloopState }` — also returns a `terminated`-state stub reconstructed from the registry for runs that aren't in this process's memory, so the dashboard can open historical runs without 404'ing. |
 | `GET /autoloop/<id>/push_log` | `{ ok, entries: PushLogEntry[] }` — served from the ledger via `autoloopStatus`, so historical runs work the same as live ones. |
 | `GET /autoloop/<id>/chat_history` | `{ ok, entries: ChatEntry[] }` — replays `<ledger>/chat.jsonl`. The dashboard fetches this when opening a run so the Planner-pane conversation survives a page refresh / cross-process / re-opening a terminated run. Returns `[]` when the file doesn't exist (e.g. runs that predate the chat-history feature). |
 | `GET /autoloop/<id>/events` | SSE: `snapshot` / `message` / `state` / `push` / `iter_done` / `planner_reply` / `planner_error` / `coder_reply` / `reviewer_reply` / `terminated`. For runs that are NOT in this process's memory (terminated, or live in another process), the endpoint emits a single-shot `snapshot` + `terminated` then closes — the dashboard's existing handlers render history without hanging. |
 | `POST /autoloop/<id>/chat` | **202** `{ ok, queued: true }` — body `{ text }`. Fire-and-forget: the Planner's reply streams back via the `/events` SSE channel as a `planner_reply` event (or `planner_error` on failure); the HTTP response intentionally does NOT wait for it, because first-contact replies routinely exceed reverse-proxy idle limits (e.g. Cloudflare Tunnel cuts at ~100s → 524). 400 on empty text, 404 when the run is not in this process's memory. The MCP `autoloop_chat` tool path keeps the synchronous await-and-return-reply semantics (it runs in-process). |
-| `POST /autoloop/<id>/resume` | `{ ok, state }` — bring a terminated run back into this process. Reads the registry entry, re-creates dispatcher + runner; `ensurePlanner` picks up the persisted `claudeSessionId` (kept on disk because autoloop terminate now passes `keepPersisted: true`) so Claude resumes the original conversation. Runs that pre-date this change get a fresh Planner; the dashboard replays `chat.jsonl` visually anyway. 404 when the registry has no record. |
+| `POST /autoloop/<id>/resume` | `{ ok, state }` — restore the role engine/model choices from the registry and re-create dispatcher + runner. Optional body fields `planner_custom_engine`, `coder_custom_engine`, `reviewer_custom_engine` must be supplied again for roles using `custom` because configs are intentionally not persisted. Existing engine-specific conversation resume behavior is reused where supported; `chat.jsonl` remains the visual history fallback. 404 when the registry has no record. |
 | `POST /autoloop/<id>/delete` | `{ ok }` — stops the runner if still alive, scrubs the row from `~/.claw-orchestrator/autoloop-registry.jsonl`, and purges `persistedSessions` so the run cannot be `/resume`'d back. The ledger directory under `<workspace>/tasks/<run_id>/` is kept on disk. 404 if the run was not present in either memory or the registry. |
 
 The 3-pane UI consumes these endpoints:

package/skills/references/claude-cli-tracking.md

@@ -2,11 +2,12 @@
 
 This document tracks which Claude Code CLI version Claw Orchestrator is currently synced to, and which features have been integrated.
 
-## Currently tracked: **Claude Code CLI 2.1.206** (as of 2026-07-10, plugin v4.7.0)
+## Currently tracked: **Claude Code CLI 2.1.207** (as of 2026-07-12, plugin v4.8.0)
 
 ## Sync history
 
 | Plugin Version | Claude CLI Version | Date | Notable integrations |
+| v4.8.0 | 2.1.207 | 2026-07-12 | **Autoloop role-level multi-engine support.** Planner, Coder, and Reviewer can select independent engines/models while preserving the Claude defaults. Built-in non-Claude Planners use native read-only/plan modes and receive their role protocol in-band. Spawn selections persist across resume; Codex persists its real thread ID. Runtime and invocation checks used Claude Code 2.1.207 and Codex 0.144.1. |
 | v4.7.0 | 2.1.206 | 2026-07-10 | **Antigravity engine ships + permission-mode sync.** Main feature is the community-contributed first-class `engine: 'agy'` (PR #71, reviewed + hardened: layered resume-ID gating, `agy/` prefix routing, shared `sanitize.ts` across all six engines, ENGINE_TYPES single source). Weekly CLI sync: CC 2.1.200 renamed the `default` permission mode to **`manual`** — verified against 2.1.206 that the choices are now `acceptEdits/auto/bypassPermissions/manual/dontAsk/plan`, that `default` is still accepted (hidden compat), and that **`delegate` is hard-rejected at spawn** — so PermissionMode gains `manual`, drops `delegate`, and agy/gemini map `manual` like `default` (→ `--sandbox`). Codex 0.143.0: empirically re-tested `-c model_reasoning_effort=max` — still 400-rejected for gpt-5.5 (the "first-class max" note is Bedrock GPT-5.6-only), so the `max`→`xhigh` map stays. GPT-5.6 Sol/Terra/Luna registered with official pricing ($5/$30, $2.50/$15, $1/$6; 1M/1M/400K ctx) after the user reported using it — it's a limited preview on API/Codex-auth paths (empirically: ChatGPT-account Codex auth gets a 400, which is why the first probe on this box misread it as Bedrock-only; lesson — an auth-path rejection is not model non-existence). Codex default stays gpt-5.5. Free upside: CC 2.1.205 fixed `--json-schema` invalid-schema silent fallback + `format` keyword rejection; CC 2.1.203 fixed background sessions dropping shell-exported `ANTHROPIC_BASE_URL`. Pins → CC 2.1.206 / Codex 0.143.0 (installed; npm has 0.144.1, exec surface unchanged per release notes). |
 | v4.6.0 | 2.1.199 | 2026-07-03 | **Model registry sync — Claude Fable 5.** Registered `claude-fable-5` (first Claude 5-family model, tier above Opus; standard $10/$50 per Mtok, cache read $1, full 1M context at standard rates per the official pricing page) with new `fable` alias; taught the `isClaudeModel`/`resolveProvider` heuristics to recognize `fable`/`mythos` strings (they only matched claude/opus/sonnet/haiku). Mythos 5 not listed (same price, limited availability). CC 2.1.198–199 are subagent/background-agent reliability fixes — no invocation-surface change; free upside for us: subagent partial output on rate-limit/server error is now returned instead of silently dropped, and API errors in subagents are reported to the parent. Codex unchanged (0.142.5 is a log-scrub patch; pin stays 0.142.4 as installed). |
 | v4.5.0 | 2.1.197 | 2026-07-01 | **Model registry sync — Claude Sonnet 5 + gpt-5.5 pricing.** CLI 2.1.197 shipped Sonnet 5 as the new default (native 1M-token context; standard $3/$15 per Mtok, launch promo $2/$10 through 2026-08-31 — we price the standard rate). Registered `claude-sonnet-5` in `models.ts` and moved the `sonnet` alias to it (was pinned to `claude-sonnet-4-6`), so `--model sonnet` tracks the CLI's own default and cost/context accounting stays correct; `claude-sonnet-4-6` stays selectable by full id. Also corrected `gpt-5.5` (the default Codex model) from placeholder pricing to OpenAI's published $5/$30 per Mtok + 1M context, and updated docs/examples off `gpt-5.4`. The CC 2.1.179→2.1.197 and Codex 0.138→0.142.x ranges are otherwise bug-fix / TUI / remote-executor / plugin-marketplace work that doesn't touch our invocation flags or the stream-json / codex-exec event schema — no wrapper change. Free upside (no code change): 2.1.181 fixed prompt-caching on custom `ANTHROPIC_BASE_URL` (helps proxy mode), 2.1.187 fixed `--json-schema` StructuredOutput infinite-recall, 2.1.196 turned the 5-min streaming idle watchdog on by default; Codex 0.139 preserves `oneOf`/`allOf` in `--output-schema`. Bumped tested versions Claude 2.1.197 / Codex 0.142.4. |

package/skills/references/cli.md

@@ -44,7 +44,7 @@ The server exposes an OpenAI-compatible chat completions endpoint, enabling any
 - `gpt-*` → Codex engine
 - `composer-*` → Cursor engine
 - `gemini-3.5-flash`, `gemini-3.1-pro`, `agy-*`, `agy/*` → Antigravity (`agy`) engine
-- other `gemini-*` → Gemini engine
+- other `gemini-*` → the legacy `gemini` engine (Gemini CLI is sunset; prefer `agy`)
 
 **CORS:** `/v1/` paths allow cross-origin requests by default. Set `OPENCLAW_CORS_ORIGINS=*` to allow all origins on all paths.
 
@@ -61,7 +61,7 @@ clawo session-start [name] [options]
 | Flag | Description |
 |------|-------------|
 | `-d, --cwd <dir>` | Working directory |
-| `-e, --engine <engine>` | Engine: `claude` (default), `codex`, `codex-app`, `gemini`, `agy`, `cursor`, `opencode`, or `custom` |
+| `-e, --engine <engine>` | Engine: `claude` (default), `codex`, `codex-app`, `agy`, `cursor`, `opencode`, or `custom` |
 | `-m, --model <model>` | Model name or alias |
 | `--permission-mode <mode>` | `acceptEdits`, `plan`, `auto`, `bypassPermissions`, `manual`, `dontAsk` |
 | `--effort <level>` | `low`, `medium`, `high`, `max`, `auto` |

package/skills/references/council.md

@@ -106,7 +106,7 @@ Agents can use different engines and models:
   "agents": [
     { "name": "Claude", "emoji": "🎭", "engine": "claude", "model": "opus", "persona": "Deep reasoning" },
     { "name": "Codex", "emoji": "🧠", "engine": "codex", "model": "gpt-5.5", "persona": "Fast implementation" },
-    { "name": "Gemini", "emoji": "💎", "engine": "gemini", "model": "gemini-3.1-pro-preview", "persona": "Creative solutions" }
+    { "name": "Antigravity", "emoji": "💎", "engine": "agy", "model": "agy-pro", "persona": "Creative solutions" }
   ]
 }
 ```

package/skills/references/getting-started.md

@@ -23,7 +23,7 @@ openclaw plugins install @enderfga/claw-orchestrator --dangerously-force-unsafe-
 openclaw gateway restart
 ```
 
-> **Why `--dangerously-force-unsafe-install`?** Claw Orchestrator spawns Claude Code / Codex / Gemini / Cursor Agent / OpenCode CLI subprocesses via `child_process`, which OpenClaw's security scanner flags by design. The flag is required — there is no way to drive coding CLIs without process spawning.
+> **Why `--dangerously-force-unsafe-install`?** Claw Orchestrator spawns Claude Code / Codex / Antigravity / Cursor Agent / OpenCode CLI subprocesses via `child_process`, which OpenClaw's security scanner flags by design. The flag is required — there is no way to drive coding CLIs without process spawning.
 
 Agents automatically get access to all session, council, and management tools.
 
@@ -52,7 +52,7 @@ await manager.stopSession('backend-fix');
 - **Claude Code CLI >= 2.1** — `npm install -g @anthropic-ai/claude-code`
 - **OpenClaw >= 2026.3.0** — for plugin mode (optional)
 - **OpenAI Codex CLI >= 0.112** — `npm install -g @openai/codex` (optional, for codex engine)
-- **Gemini CLI >= 0.35** — `npm install -g @google/gemini-cli` (optional, for gemini engine)
+- **Antigravity CLI** — `curl -fsSL https://antigravity.google/cli/install.sh | bash` (optional, for the `agy` engine — Google's successor to the sunset Gemini CLI)
 
 ### Engine Authentication
 
@@ -60,7 +60,7 @@ Each engine requires its own authentication before use:
 
 - **Claude Code** — run `claude /login` or set `ANTHROPIC_API_KEY`
 - **Codex** — run `codex login` or set `OPENAI_API_KEY`
-- **Gemini** — run `gemini login` or set `GEMINI_API_KEY`
+- **Antigravity** — run `agy` once and complete the Google OAuth login
 
 The plugin does not manage authentication — it expects each CLI to be ready to run.
 
@@ -87,7 +87,7 @@ Quick config for any client:
 |---------|-------|
 | API Base URL | `http://127.0.0.1:18796/v1` |
 | API Key | The value of `OPENCLAW_SERVER_TOKEN`, or any string if auth is disabled |
-| Model | `claude-fable-5`, `claude-opus-4-8`, `claude-sonnet-5`, `gpt-5.5`, `gemini-3.1-pro-preview`, etc. |
+| Model | `claude-fable-5`, `claude-opus-4-8`, `claude-sonnet-5`, `gpt-5.5`, `agy-pro`, etc. |
 
 See [openai-compat.md](./openai-compat.md) for the full session-keying rules, `X-Session-Reset` semantics, the legacy-heuristic env var, and the `/v1/sessions` inspection endpoint.
 

package/skills/references/multi-engine.md

@@ -12,8 +12,6 @@ SessionManager
 │   └── Wraps: codex exec --sandbox workspace-write --json (per-message spawning)
 ├── engine: 'codex-app' → PersistentCodexAppServerSession
 │   └── Wraps: codex app-server --listen stdio:// (long-running JSON-RPC; required for /goal)
-├── engine: 'gemini'    → PersistentGeminiSession
-│   └── Wraps: gemini -p --output-format stream-json (per-message spawning)
 ├── engine: 'agy'       → PersistentAgySession
 │   └── Wraps: agy -p (Google Antigravity CLI, per-message spawning, plain-text output)
 ├── engine: 'cursor'    → PersistentCursorSession
@@ -28,7 +26,7 @@ SessionManager
 
 ### Claude Code (`engine: 'claude'`)
 
-Default engine. Long-running subprocess with streaming JSON I/O. Tested with Claude Code CLI **2.1.206**.
+Default engine. Long-running subprocess with streaming JSON I/O. Tested with Claude Code CLI **2.1.207**.
 
 - Persistent multi-turn conversations
 - Real-time streaming (text, tool_use, tool_result, system events)
@@ -54,7 +52,7 @@ await manager.startSession({
 
 ### OpenAI Codex (`engine: 'codex'`)
 
-Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested with `codex` CLI **0.143.0**.
+Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested with `codex` CLI **0.144.1**.
 
 - Non-interactive execution via `codex exec --sandbox workspace-write --json` (replaces the deprecated `--full-auto` flag from earlier Codex versions)
 - Real per-turn `usage` from the `turn.completed` JSON event (input, output, cached, reasoning tokens)
@@ -63,6 +61,7 @@ Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested wi
 - `codexProfile` → `--profile <name>` (named config profile from `~/.codex/config.toml`)
 - Per-session continuity: the `thread_id` from the first turn's `thread.started` event is captured and reused via `codex exec resume <id>` for subsequent sends, so the model sees prior turns
 - One-shot execution per message (no persistent subprocess between sends)
+- Captures the real Codex thread ID and persists it, so later sends and process-level session resume use `codex exec resume <thread_id>`
 - Working directory passed via `-C` flag
 - Default model: `gpt-5.5`
 - Requires `codex` CLI >= 0.119 (for `exec resume`): `npm install -g @openai/codex`
@@ -106,33 +105,11 @@ await manager.startSession({
 //   await tool('codex_goal_set', { name: 'codex-goal-task', objective: 'build a tic-tac-toe app' });
 ```
 
-### Google Gemini (`engine: 'gemini'`)
-
-Wraps the `gemini` CLI with `--output-format stream-json`. Each `send()` spawns a new process.
-
-- One-shot execution per message (no persistent subprocess)
-- Working directory carries accumulated changes across sends
-- Real token counts from stream-json `result` events (not estimated)
-- Permission modes: `bypassPermissions` → `--yolo`, `default` → `--sandbox`
-- Always passes `--skip-trust` to bypass the "trusted folders" gate introduced
-  in Gemini CLI 0.43 (otherwise headless runs in worktrees / arbitrary cwds
-  abort before producing output)
-- Requires `gemini` CLI installed: `npm install -g @google/gemini-cli`
-
-```typescript
-await manager.startSession({
-  name: 'gemini-task',
-  engine: 'gemini',
-  model: 'gemini-3.1-pro-preview',
-  cwd: '/project',
-});
-```
-
 ### Google Antigravity (`engine: 'agy'`)
 
 Wraps Google's **Antigravity CLI** (`agy`) — the successor to Gemini CLI (consumer
 Gemini CLI tiers stopped serving 2026-06-18). Each `send()` spawns a new process
-in print mode. Verified against `agy` **1.0.16**.
+in print mode. Verified against `agy` **1.1.1**.
 
 - One-shot execution per message (no persistent subprocess)
 - **Plain-text output** — agy has no structured/stream-json mode, so stdout is
@@ -143,9 +120,10 @@ in print mode. Verified against `agy` **1.0.16**.
   externally via `resumeSessionId` (bare UUID only); read it back from
   `getStats().agyConversationId`
 - Permission modes: `bypassPermissions` → `--dangerously-skip-permissions`,
-  `default` → `--sandbox` (terminal-restricted). Other modes run agy's own
-  approval flow, which blocks in headless print mode — use `bypassPermissions`
-  for autonomous work
+  `default` → `--sandbox` (terminal-restricted), and
+  `sandboxMode: 'read-only'` → `--mode plan` (takes precedence). Other modes
+  run agy's own approval flow, which blocks in headless print mode — use
+  `bypassPermissions` for autonomous write-enabled work
 - agy enforces its own print timeout (default 5m); the engine derives
   `--print-timeout` from the send timeout so the wrapper timer decides
 - Unknown `--model` slugs do **not** error — agy silently falls back to its
@@ -167,14 +145,22 @@ await manager.startSession({
 });
 ```
 
+> **Legacy: `engine: 'gemini'`.** Google sunset the consumer Gemini CLI (tiers stopped
+> serving 2026-06-18) in favour of Antigravity. The `gemini` engine still exists and
+> still works — existing callers are not broken, and `gemini-*` model strings outside
+> agy's registered slugs still route to it — but it is no longer a documented option,
+> is not version-tracked, and gets no new work. Use `agy` for Google. (Unrelated: the
+> multi-model **proxy** still talks to the Gemini **API**; that is a different
+> subsystem and is unaffected.)
+
 ### Cursor Agent (`engine: 'cursor'`)
 
-Wraps the Cursor Agent CLI (`agent`) with `--print --force --output-format stream-json`. Each `send()` spawns a new process.
+Wraps the Cursor Agent CLI (`agent`) with `--print --output-format stream-json`. Write-enabled sessions use `--force`. Each `send()` spawns a new process.
 
 - One-shot execution per message (no persistent subprocess)
 - Working directory via `--workspace` flag
 - Real token counts from stream-json `result` events (camelCase: `inputTokens`, `outputTokens`, `cacheReadTokens`)
-- `--force` enables auto-approval of all file changes
+- `--force` enables auto-approval of file changes. `sandboxMode: 'read-only'` does **not** use `--force`; it enforces read-only via a binding `.cursor/cli.json` deny config (`Write`/`Edit`/`Shell` denied) written into an isolated temp dir used as the process cwd, with `--workspace` pointing at the real project (the repo tree is never modified). `--mode plan` is passed too as model steering, but the deny config is the actual boundary — plan mode alone is model-cooperative and was verified to let an adversarial prompt write. Do not add `--sandbox` (it does not restrict in-workspace writes and overrides the mode). Read/grep/search remain available
 - `--trust` auto-trusts the workspace without prompting
 - Cursor uses its own model routing (e.g., `sonnet-4`, `gpt-5`, `auto`)
 - Requires Cursor Agent CLI: `curl https://cursor.com/install -fsSL | bash`
@@ -200,6 +186,7 @@ Wraps the [sst/opencode](https://github.com/sst/opencode) CLI with `run --format
 - Real token counts from `step_finish.part.tokens.{input,output,cache.read}`
 - The wrapper closes the subprocess's stdin immediately after spawn (opencode otherwise reads stdin and blocks on EOF, hanging the call)
 - Provider-agnostic: opencode's `--model` expects `provider/model` form (e.g. `anthropic/claude-sonnet-4`). The wrapper passes `--model` through only when the value contains a `/`; otherwise opencode's own default applies
+- `sandboxMode: 'read-only'` spawns a generated `clawo-readonly` agent (`--agent clawo-readonly` plus an `OPENCODE_CONFIG_CONTENT` env var defining it) whose permissions deny `edit` / `bash` / `external_directory`. It deliberately does **not** use OpenCode's built-in `plan` agent: that is a user-overridable preset whose compiled rules start with `{"permission":"*","action":"allow"}` and deny neither `bash` nor `edit`, so a "read-only" session could still author files through a shell heredoc. Verified against opencode 1.17.15 by attempting a real write, which the agent cannot perform (its toolset has no write/bash tools). Note that `opencode agent list` renders compiled permission rules and does not show the tool-level restriction — trust an actual write attempt, not that view
 - Requires opencode installed: `brew install sst/tap/opencode` or `npm install -g opencode-ai`. Auth via `opencode auth login` **or** any provider env var (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, etc.) — opencode picks up either path
 - Binary: `opencode` (set `OPENCODE_BIN` env var to override)
 
@@ -262,7 +249,7 @@ Team tools (`team_list`, `team_send`) operate on the same virtual-team layer for
 |--------|------------|-------------|
 | Claude | Lists other active SessionManager sessions | Routes via cross-session inbox |
 | Codex | Lists other active SessionManager sessions | Routes via cross-session inbox |
-| Gemini | Lists other active SessionManager sessions | Routes via cross-session inbox |
+| Antigravity | Lists other active SessionManager sessions | Routes via cross-session inbox |
 | Cursor | Lists other active SessionManager sessions | Routes via cross-session inbox |
 
 Messages are delivered via the inbox system — idle sessions receive immediately, busy sessions queue for later delivery.
@@ -318,7 +305,7 @@ Integrate **any** coding agent CLI without writing engine-specific code. You pro
 
 Two protocol modes:
 - **Persistent** (`persistent: true`) — long-running subprocess with stream-json I/O over stdin/stdout (like Claude Code)
-- **One-shot** (`persistent: false`, default) — new process spawned per `send()` (like Gemini/Codex)
+- **One-shot** (`persistent: false`, default) — new process spawned per `send()` (like Codex/Antigravity)
 
 ### CustomEngineConfig
 

package/skills/references/openai-compat.md

@@ -2,7 +2,7 @@
 
 > **Cost warning**: This bridge routes requests through the Claude Code CLI, which uses your Claude Max subscription's **extra usage** quota. When OpenClaw's agent loop sends its system prompt (with distinctive tool definitions and agent instructions), Anthropic's backend recognizes this as programmatic/agent traffic and bills it against extra usage — **not** the included allowance. This is by design: the bridge does NOT bypass Anthropic's billing or subscription enforcement. Using it as OpenClaw's primary model backend means every agent turn consumes extra usage credits at standard API rates ($15/M input, $75/M output for Opus). Monitor your usage at [claude.ai/settings/usage](https://claude.ai/settings/usage).
 
-The embedded server exposes a drop-in OpenAI-compatible endpoint so any client that speaks `/v1/chat/completions` can talk to a persistent Claude Code (or Codex / Gemini / Cursor) session. The bridge is designed to serve **two kinds of clients as first-class citizens**:
+The embedded server exposes a drop-in OpenAI-compatible endpoint so any client that speaks `/v1/chat/completions` can talk to a persistent Claude Code (or Codex / Antigravity / Cursor) session. The bridge is designed to serve **two kinds of clients as first-class citizens**:
 
 1. **Upstream agents** that maintain their own conversation state and forward only the latest user turn — OpenClaw's main agent loop, cron jobs, subagents, programmatic clients.
 2. **OpenAI-compatible webchat / labeling tools** that re-send the full transcript on every turn — ChatGPT-Next-Web, Open WebUI, LobeChat, data-labeling pipelines.

package/skills/references/sessions.md

@@ -29,8 +29,8 @@ Key options:
 
 | Option | Description |
 |--------|-------------|
-| `engine` | `'claude'` (default), `'codex'`, `'codex-app'`, `'gemini'`, `'agy'`, `'cursor'`, `'opencode'`, or `'custom'` — see [Multi-Engine](./multi-engine.md) |
-| `model` | Model alias (`opus`, `sonnet`, `haiku`, `gemini-pro`) or full name |
+| `engine` | `'claude'` (default), `'codex'`, `'codex-app'`, `'agy'`, `'cursor'`, `'opencode'`, or `'custom'` — see [Multi-Engine](./multi-engine.md) |
+| `model` | Model alias (`fable`, `opus`, `sonnet`, `haiku`, `agy-pro`) or full name |
 | `permissionMode` | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`) |
 | `effort` | `low`, `medium`, `high`, `max`, `auto` |
 | `bare` | Skip hooks, LSP, auto-memory, CLAUDE.md |
@@ -162,7 +162,7 @@ SessionManager tracks consecutive failures per engine type. After 3 consecutive
 
 ## Orphaned Process Cleanup
 
-If the plugin crashes without calling `stop()`, child CLI processes (claude, codex, gemini, agent) may become orphans. SessionManager tracks PIDs in `~/.openclaw/session-pids.json` and cleans up stale processes on startup:
+If the plugin crashes without calling `stop()`, child CLI processes (claude, codex, agy, agent, opencode) may become orphans. SessionManager tracks PIDs in `~/.openclaw/session-pids.json` and cleans up stale processes on startup:
 
 1. Reads PID file from previous run
 2. For each PID, checks if process is alive (`kill -0`)

package/skills/references/tools.md

@@ -12,9 +12,10 @@ Start a persistent coding session with full CLI flag support.
 |-----------|------|-------------|
 | `name` | string | Session name (auto-generated if omitted) |
 | `cwd` | string | Working directory |
-| `engine` | `'claude'` \| `'codex'` \| `'codex-app'` \| `'gemini'` \| `'agy'` \| `'cursor'` \| `'opencode'` \| `'custom'` | Engine to use (default: `claude`). `agy` wraps Google Antigravity CLI. `opencode` wraps sst/opencode (pass model as `provider/model`). Use `custom` with `customEngine` for any CLI. |
+| `engine` | `'claude'` \| `'codex'` \| `'codex-app'` \| `'agy'` \| `'cursor'` \| `'opencode'` \| `'custom'` | Engine to use (default: `claude`). `agy` wraps Google Antigravity CLI. `opencode` wraps sst/opencode (pass model as `provider/model`). Use `custom` with `customEngine` for any CLI. (`'gemini'` is still accepted for existing callers, but Gemini CLI is sunset — use `agy` for Google.) |
 | `model` | string | Model alias or full name |
 | `permissionMode` | string | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`) |
+| `sandboxMode` | `'read-only'` \| `'workspace-write'` \| `'danger-full-access'` | Sandbox policy. Codex supports all values. `read-only` is enforced on every other built-in engine too: Claude → plan mode; Antigravity / Cursor → their plan modes; OpenCode → a generated `clawo-readonly` agent denying `edit`/`bash`. A `custom` engine must map it via `permissionModes`, or the session refuses to start. Persisted across session resume. |
 | `effort` | string | `low`, `medium`, `high`, `max`, `auto` |
 | `allowedTools` | string[] | Tools to auto-approve |
 | `disallowedTools` | string[] | Tools to deny |
@@ -537,57 +538,75 @@ Three-agent autonomous iteration loop (Planner / Coder / Reviewer) over a git wo
 
 ### `autoloop_start`
 
-Start an autoloop run. Planner is created persistent; Coder + Reviewer are spawned by the Planner once `plan.md` is ready.
+Start a chat-mode autoloop. Planner starts immediately; Coder + Reviewer start only after the Planner receives plan approval and emits `spawn_subagents`.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `cwd` | string | yes | Workspace (must be a git repo) |
-| `goal` | string | yes | High-level user goal in natural language |
-| `model` | string | | Planner model (default Opus) |
-| `coderModel` | string | | Coder subagent model |
-| `reviewerModel` | string | | Reviewer subagent model |
-| `maxIters` | number | | Cap on Coder/Reviewer rounds (default 50) |
-| `pushChannels` | string[] | | Notification channels (`wechat`, `whatsapp`, `email`) |
+| `run_id` | string | yes | Stable run identifier |
+| `workspace` | string | yes | Git workspace path |
+| `planner_engine` | EngineType | | Planner engine (default `claude`) |
+| `planner_model` | string | | Planner model (Claude default `opus`; other engines use their own default when omitted) |
+| `planner_custom_engine` | object | | Trusted `CustomEngineConfig` when Planner engine is `custom`. **Local callers only** — see below |
+| `coder_engine` | EngineType | | Default Coder engine (default `claude`) |
+| `coder_model` | string | | Default Coder model (Claude default `sonnet`) |
+| `coder_custom_engine` | object | | Trusted config when Coder may use `custom`. **Local callers only** |
+| `reviewer_engine` | EngineType | | Default Reviewer engine (default `claude`) |
+| `reviewer_model` | string | | Default Reviewer model (Claude default `sonnet`) |
+| `reviewer_custom_engine` | object | | Trusted config when Reviewer may use `custom`. **Local callers only** |
+| `send_timeout_ms` | number | | Per-message timeout (default 600000) |
+
+> **Custom engines are local-only.** A `CustomEngineConfig` names an executable to
+> spawn plus its argv and env, so it may only be supplied by a caller that already
+> runs on the host (this MCP tool, or the `SessionManager` API). The HTTP API
+> (`POST /autoloop/new`, `POST /autoloop/<id>/resume`) rejects a `*_custom_engine`
+> body field with a 400 — the embedded server is often reverse-tunnelled and its
+> token is a monitoring credential, not permission to choose what binary runs.
+> Built-in engines are fully selectable over HTTP.
+
+Custom configs are not persisted or accepted from Planner output. See [`multi-engine.md`](./multi-engine.md) for their shape.
 
 ### `autoloop_chat`
 
-Send a message into the Planner conversation (e.g. answer a clarifying question, refine the plan, kick off the subloop).
+Send a message into the Planner conversation.
 
 | Parameter | Type | Required |
 |-----------|------|----------|
-| `id` | string | yes |
-| `message` | string | yes |
+| `run_id` | string | yes |
+| `text` | string | yes |
 
 ### `autoloop_status`
 
-Get current state, phase, recent inbox messages, and ledger summary.
+Get the current state and push log.
 
 | Parameter | Type | Required |
 |-----------|------|----------|
-| `id` | string | yes |
+| `run_id` | string | yes |
 
 ### `autoloop_list`
 
-List active and recent autoloop runs (in-memory + on-disk registry, deduped by run_id).
+List active Autoloop runs in this manager process.
 
 (no params)
 
 ### `autoloop_reset_agent`
 
-Reset one of the subagent sessions (Coder or Reviewer) without losing Planner state — useful when a subagent loops on a stale belief.
+Reset one role session while retaining the role's current engine/model selection.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `id` | string | yes | Run id |
-| `agent` | `'coder'` \| `'reviewer'` | yes | Which subagent to reset |
+| `run_id` | string | yes | Run id |
+| `agent` | `'planner'` \| `'coder'` \| `'reviewer'` | yes | Role to reset; Planner requires `force: true` |
+| `force` | boolean | | Allow Planner reset |
+| `eager_restart` | boolean | | Start the replacement session immediately |
 
 ### `autoloop_stop`
 
-Terminate the run. All sessions are stopped and ledger state is finalised.
+Terminate the run and stop all role sessions.
 
 | Parameter | Type | Required |
 |-----------|------|----------|
-| `id` | string | yes |
+| `run_id` | string | yes |
+| `reason` | string | |
 
 ---