@enderfga/claw-orchestrator 4.6.0 → 4.8.0

package/skills/references/autoloop.md

@@ -21,12 +21,40 @@ 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 (Gemini, 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,
+Gemini gets `--approval-mode plan` **plus an admin policy denying `exit_plan_mode`**
+(plan mode on its own is model-cooperative — the agent can call that tool and walk
+out of it), 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), and Antigravity/Cursor use their plan modes. 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 +106,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 +122,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 +131,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 +255,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,13 @@
 
 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.199** (as of 2026-07-03, plugin v4.6.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. |
 | v4.3.0 | 2.1.178 | 2026-06-16 | **Parity batch 2 + legacy-subsystem upgrades (local-only, no cloud).** Claude `--fallback-model` array form (CSV, verified via `claude --help`). Codex-app `codex_threads` (`thread/list`) and `thread/resume` on start when `resumeSessionId` is set (param shapes from `generate-json-schema`). Council agents gain per-agent `effort`/`ultracode`. `ultrareview` re-implemented on the new cross-engine `fanout` primitive (opt-in `engines`, default claude-only). Consensus parsing exposes match source for observability. Dropped on purpose: `codex cloud exec`/best-of-N (cloud/managed — loses local control), `--bg` (we own the subprocess), `--output-last-message` (we already capture final text), ultraplan `ultracode` (violates its plan-only contract). Autoloop mid-turn steer deferred — the loop is strictly sequential (Coder fully completes before the Reviewer runs), so steer would always fall back to a fresh turn; a real version needs concurrent review. |

package/skills/references/cli.md

@@ -43,7 +43,8 @@ The server exposes an OpenAI-compatible chat completions endpoint, enabling any
 - `claude-*`, `opus`, `sonnet`, `haiku` → Claude engine
 - `gpt-*` → Codex engine
 - `composer-*` → Cursor engine
-- `gemini-*` → Gemini engine
+- `gemini-3.5-flash`, `gemini-3.1-pro`, `agy-*`, `agy/*` → Antigravity (`agy`) engine
+- other `gemini-*` → Gemini engine
 
 **CORS:** `/v1/` paths allow cross-origin requests by default. Set `OPENCLAW_CORS_ORIGINS=*` to allow all origins on all paths.
 
@@ -60,9 +61,9 @@ clawo session-start [name] [options]
 | Flag | Description |
 |------|-------------|
 | `-d, --cwd <dir>` | Working directory |
-| `-e, --engine <engine>` | Engine: `claude` (default), `codex`, or `gemini` |
+| `-e, --engine <engine>` | Engine: `claude` (default), `codex`, `codex-app`, `gemini`, `agy`, `cursor`, `opencode`, or `custom` |
 | `-m, --model <model>` | Model name or alias |
-| `--permission-mode <mode>` | `acceptEdits`, `plan`, `auto`, `bypassPermissions` |
+| `--permission-mode <mode>` | `acceptEdits`, `plan`, `auto`, `bypassPermissions`, `manual`, `dontAsk` |
 | `--effort <level>` | `low`, `medium`, `high`, `max`, `auto` |
 | `--allowed-tools <tools>` | Comma-separated tool whitelist |
 | `--max-turns <n>` | Max agent loop turns |

package/skills/references/mcp.md

@@ -223,7 +223,7 @@ Hosts deliberately do not forward your full shell environment to MCP subprocesse
 | `CLAWO_MCP_TOOLS` | Comma-separated allowlist of tool names; unlisted tools are not advertised |
 | `CLAWO_NO_EMBEDDED_SERVER` | Suppresses port 18796 binding. `clawo-mcp` sets this automatically |
 
-The engines themselves (`claude`, `codex`, `gemini`, `agent`, `opencode`) must also be installed and authenticated on the host machine — `clawo-mcp` spawns them as subprocesses, it does not bundle them.
+The engines themselves (`claude`, `codex`, `gemini`, `agy`, `agent`, `opencode`) must also be installed and authenticated on the host machine — `clawo-mcp` spawns them as subprocesses, it does not bundle them.
 
 ---
 

package/skills/references/multi-engine.md

@@ -14,6 +14,8 @@ SessionManager
 │   └── 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
 │   └── Wraps: agent -p --force --trust --output-format stream-json (per-message spawning)
 ├── engine: 'opencode'  → PersistentOpencodeSession
@@ -26,7 +28,7 @@ SessionManager
 
 ### Claude Code (`engine: 'claude'`)
 
-Default engine. Long-running subprocess with streaming JSON I/O. Tested with Claude Code CLI **2.1.199**.
+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)
@@ -52,7 +54,7 @@ await manager.startSession({
 
 ### OpenAI Codex (`engine: 'codex'`)
 
-Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested with `codex` CLI **0.142.4**.
+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)
@@ -61,6 +63,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`
@@ -111,7 +114,7 @@ Wraps the `gemini` CLI with `--output-format stream-json`. Each `send()` spawns
 - 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`
+- Permission modes: `bypassPermissions` → `--yolo`, `default` → `--sandbox`; `sandboxMode: 'read-only'` → `--approval-mode plan` (takes precedence)
 - 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)
@@ -126,14 +129,54 @@ await manager.startSession({
 });
 ```
 
+### 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.1.1**.
+
+- One-shot execution per message (no persistent subprocess)
+- **Plain-text output** — agy has no structured/stream-json mode, so stdout is
+  forwarded as streaming text and **token counts are estimated** (~4 chars/token)
+- **Real conversation continuity**: agy logs `Created conversation <uuid>` to its
+  log file; the engine passes a private `--log-file`, harvests the ID after the
+  first turn, and resumes with `--conversation <id>` on subsequent sends. Seed it
+  externally via `resumeSessionId` (bare UUID only); read it back from
+  `getStats().agyConversationId`
+- Permission modes: `bypassPermissions` → `--dangerously-skip-permissions`,
+  `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
+  default model. Registered slugs: `gemini-3.5-flash` (alias `agy-flash`),
+  `gemini-3.1-pro` (alias `agy-pro`); agy also proxies Claude and GPT-OSS
+  models (`agy models` lists them) which pass through unregistered. The
+  `agy/` prefix forces Antigravity routing for provider-like model strings
+- Consumer auth is a one-time `agy` Google OAuth login (subscription quotas, no
+  per-token billing — registry pricing mirrors Gemini API rates as a value proxy)
+- Requires `agy` installed: `curl -fsSL https://antigravity.google/cli/install.sh | bash`
+- Binary: `agy` (set `AGY_BIN` env var to override)
+
+```typescript
+await manager.startSession({
+  name: 'antigravity-task',
+  engine: 'agy',
+  model: 'gemini-3.5-flash',
+  cwd: '/project',
+});
+```
+
 ### 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`; `sandboxMode: 'read-only'` uses `--mode plan`. 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'` replaces it with `--mode plan`
 - `--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`
@@ -159,6 +202,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'` selects OpenCode's built-in `plan` agent via `--agent plan`
 - 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)
 
@@ -384,9 +428,10 @@ await manager.startSession({
 
 ### Example: Google Antigravity CLI (`agy`)
 
-Google is sunsetting Gemini CLI (consumer tiers stop serving **2026-06-18**) in
-favour of the Go-based **Antigravity CLI** (`agy`). Until `agy` ships first-class
-support here, you can drive it today via a custom engine:
+> **Note:** `agy` now has first-class support — use [`engine: 'agy'`](#google-antigravity-engine-agy)
+> instead, which adds conversation resume and timeout coherence the recipe below
+> lacks. This recipe remains as a reference for driving older agy builds or
+> forks with a diverged flag surface:
 
 ```typescript
 await manager.startSession({

package/skills/references/sessions.md

@@ -29,9 +29,9 @@ Key options:
 
 | Option | Description |
 |--------|-------------|
-| `engine` | `'claude'` (default), `'codex'`, or `'gemini'` — see [Multi-Engine](./multi-engine.md) |
+| `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 |
-| `permissionMode` | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `default` |
+| `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 |
 | `worktree` | Run in isolated git worktree |

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'` \| `'gemini'` \| `'cursor'` \| `'opencode'` \| `'custom'` | Engine to use (default: `claude`). `opencode` wraps sst/opencode (pass model as `provider/model`). Use `custom` with `customEngine` for any CLI. |
+| `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. |
 | `model` | string | Model alias or full name |
-| `permissionMode` | string | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `default` |
+| `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; Gemini → `--approval-mode plan` + an admin policy denying `exit_plan_mode`; OpenCode → a generated `clawo-readonly` agent denying `edit`/`bash`; Antigravity/Cursor → plan mode. 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 | |
 
 ---