@enderfga/claw-orchestrator 4.7.0 → 4.8.0

package/skills/references/multi-engine.md

@@ -28,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.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 +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.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 +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`
@@ -113,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)
@@ -132,7 +133,7 @@ await manager.startSession({
 
 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 +144,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
@@ -169,12 +171,12 @@ await manager.startSession({
 
 ### 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`
@@ -200,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)
 

package/skills/references/tools.md

@@ -15,6 +15,7 @@ Start a persistent coding session with full CLI flag support.
 | `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`, `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 | |
 
 ---