@enderfga/claw-orchestrator 7.5.2 → 7.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/README.md +26 -27
  2. package/configs/engines/README.md +7 -6
  3. package/dist/bin/cli.js +1 -1
  4. package/dist/bin/cli.js.map +1 -1
  5. package/dist/src/acp-server.d.ts +1 -1
  6. package/dist/src/acp-server.js +7 -5
  7. package/dist/src/acp-server.js.map +1 -1
  8. package/dist/src/autoloop/dispatcher.js +3 -3
  9. package/dist/src/autoloop/dispatcher.js.map +1 -1
  10. package/dist/src/autoloop/notify.d.ts +5 -7
  11. package/dist/src/autoloop/notify.js +21 -20
  12. package/dist/src/autoloop/notify.js.map +1 -1
  13. package/dist/src/base-oneshot-session.js +20 -1
  14. package/dist/src/base-oneshot-session.js.map +1 -1
  15. package/dist/src/dashboard/index.html +94 -15
  16. package/dist/src/embedded-server.js +40 -7
  17. package/dist/src/embedded-server.js.map +1 -1
  18. package/dist/src/fanout.d.ts +6 -0
  19. package/dist/src/fanout.js +1 -0
  20. package/dist/src/fanout.js.map +1 -1
  21. package/dist/src/index.js +19 -11
  22. package/dist/src/index.js.map +1 -1
  23. package/dist/src/kernel/nodes/fanout.js +1 -0
  24. package/dist/src/kernel/nodes/fanout.js.map +1 -1
  25. package/dist/src/kernel/types.d.ts +2 -0
  26. package/dist/src/kernel/types.js.map +1 -1
  27. package/dist/src/models.js +36 -7
  28. package/dist/src/models.js.map +1 -1
  29. package/dist/src/openai-compat.d.ts +2 -2
  30. package/dist/src/openai-compat.js +5 -2
  31. package/dist/src/openai-compat.js.map +1 -1
  32. package/dist/src/persistent-agy-session.js +6 -1
  33. package/dist/src/persistent-agy-session.js.map +1 -1
  34. package/dist/src/session-manager.d.ts +1 -0
  35. package/dist/src/session-manager.js +17 -5
  36. package/dist/src/session-manager.js.map +1 -1
  37. package/dist/src/types.d.ts +2 -0
  38. package/openclaw.plugin.json +1 -1
  39. package/package.json +2 -2
  40. package/skills/SKILL.md +31 -32
  41. package/skills/references/acp.md +19 -36
  42. package/skills/references/autoloop.md +163 -180
  43. package/skills/references/claude-cli-tracking.md +28 -27
  44. package/skills/references/cli.md +62 -79
  45. package/skills/references/council.md +40 -63
  46. package/skills/references/dashboard.md +42 -55
  47. package/skills/references/getting-started.md +21 -15
  48. package/skills/references/inbox.md +6 -4
  49. package/skills/references/mcp.md +29 -24
  50. package/skills/references/multi-engine.md +105 -153
  51. package/skills/references/observability.md +42 -32
  52. package/skills/references/openai-compat.md +169 -303
  53. package/skills/references/sessions.md +20 -29
  54. package/skills/references/tools.md +62 -76
  55. package/skills/references/ultra.md +17 -16
  56. package/skills/references/ultraapp.md +59 -64
  57. package/skills/references/verification.md +29 -52
  58. package/skills/references/workflow.md +37 -104
  59. package/skills/ultraapp/SKILL.md +9 -10
package/skills/references/sessions.md CHANGED
@@ -27,14 +27,14 @@ const info = await manager.startSession({
27
27
 
28
28
  Key options:
29
29
 
30
- | Option | Description |
31
- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
32
- | `engine` | `'claude'` (default), `'codex'`, `'codex-app'`, `'agy'`, `'grok'`, `'opencode'`, or `'custom'` — see [Multi-Engine](./multi-engine.md) |
33
- | `model` | Model alias (`fable`, `opus`, `sonnet`, `haiku`, `agy-pro`) or full name |
34
- | `permissionMode` | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`) |
35
- | `effort` | `low`, `medium`, `high`, `max`, `auto` |
36
- | `bare` | Skip hooks, LSP, auto-memory, CLAUDE.md |
37
- | `worktree` | Run in isolated git worktree |
30
+ | Option | Description |
31
+ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
32
+ | `engine` | `'claude'` (default), `'codex'`, `'codex-app'`, `'agy'`, `'grok'`, `'opencode'`, or `'custom'` — see [Multi-Engine](./multi-engine.md) |
33
+ | `model` | Model alias (`fable`, `opus`, `sonnet`, `haiku`, `agy-pro`) or full name |
34
+ | `permissionMode` | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`) |
35
+ | `effort` | `low`, `medium`, `high`, `xhigh`, `max`, `ultra`, `auto` — each engine clamps to its own ladder (see [Multi-Engine](./multi-engine.md)) |
36
+ | `bare` | Skip hooks, LSP, auto-memory, CLAUDE.md |
37
+ | `worktree` | Run in isolated git worktree |
38
38
  | `appendSystemPrompt` | Append custom instructions to the system prompt. Claude Code and Grok take it natively; Codex, Antigravity and OpenCode have no such flag and receive it at the top of the first message of a conversation |
39
39
 
40
40
  ### Sending Messages
@@ -120,10 +120,6 @@ source's record, so handing it off again carries the whole conversation rather t
120
120
  part. The history is cleared only after a first send succeeds, so a first turn that fails on the
121
121
  new engine does not strand the conversation it was carrying.
122
122
 
123
- Verified end to end over MCP against the installed engines: a fact planted in a Claude session was
124
- recalled by Codex 0.154.0 after a handoff, and again by Claude after a second handoff back, which
125
- also named Codex as the engine it had taken over from.
126
-
127
123
  ### ultracode (Claude dynamic workflows)
128
124
 
129
125
  Set `ultracode: true` on a Claude `session_start` to have Claude orchestrate a JS workflow per substantive task and fan out to subagents. It is injected as the `ultracode: true` settings key merged into `--settings`:
@@ -141,7 +137,7 @@ Code session. Read the outcome by sending a follow-up once the workflow has had
141
137
 
142
138
  ### Codex app-server turn control (`engine: 'codex-app'`)
143
139
 
144
- Mid-turn and thread control via Codex 0.137 v2 RPCs, surfaced as tools: `codex_interrupt` (cancel the in-flight turn), `codex_steer` (add input without restarting), `codex_fork` (branch the thread), `codex_rollback` (drop the last N turns), `codex_models` (list models + supported reasoning efforts).
140
+ Mid-turn and thread control via the Codex app-server v2 RPCs, surfaced as tools: `codex_interrupt` (cancel the in-flight turn), `codex_steer` (add input without restarting), `codex_fork` (branch the thread), `codex_rollback` (drop the last N turns), `codex_models` (list models + supported reasoning efforts), `codex_thread_list` (list the threads the session can see).
145
141
 
146
142
  ### Fan-out (cross-engine parallel)
147
143
 
@@ -215,7 +211,7 @@ in cleanup), `gemini` succeeds on exit 53 because its turn limit resolves,
215
211
  read-only enforcement did not load.
216
212
 
217
213
  **A succeeded turn is not a turn that did the work.** When the engine refuses a
218
- tool call it usually does not fail the turn. Measured on Claude Code 2.1.269 with
214
+ tool call it usually does not fail the turn. On Claude Code with
219
215
  `--permission-prompts none` — which a session gets whenever no prompt tool is
220
216
  configured — a turn asked to write a file came back `subtype: 'success'`,
221
217
  `is_error: false`, with the refused Bash call listed in the result event and no
@@ -246,7 +242,7 @@ Built-in format translation lets Claude Code CLI talk to non-Anthropic models:
246
242
  - **Gemini** thought signature caching (round-trip thinking)
247
243
  - Auto-detect provider from model name patterns
248
244
 
249
- See `src/proxy/` for implementation details.
245
+ See [`src/proxy/`](https://github.com/Enderfga/claw-orchestrator/tree/main/src/proxy) for implementation details.
250
246
 
251
247
  ## Circuit Breaker
252
248
 
@@ -258,7 +254,7 @@ SessionManager tracks consecutive failures per engine type. After 3 consecutive
258
254
 
259
255
  ## Orphaned Process Cleanup
260
256
 
261
- 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:
257
+ If the plugin crashes without calling `stop()`, child CLI processes (claude, codex, agy, grok, opencode, and legacy engines) may become orphans. SessionManager tracks PIDs in `~/.openclaw/session-pids.json` and cleans up stale processes on startup:
262
258
 
263
259
  1. Reads PID file from previous run
264
260
  2. For each PID, checks if process is alive (`kill -0`)
@@ -270,18 +266,13 @@ If the plugin crashes without calling `stop()`, child CLI processes (claude, cod
270
266
 
271
267
  Session stats are returned by `getStats()` and surfaced through `coding_session_status`.
272
268
 
273
- Fields added in plugin v2.13.0 (Claude CLI 2.1.111):
274
-
275
- | Field | Type | Description |
276
- | ---------------- | ------------------- | -------------------------------------------------- |
277
- | `retries` | number | Total API retries that occurred during the session |
278
- | `lastRetryError` | string \| undefined | Error message from the most recent retry (if any) |
279
-
280
- Fields added in plugin v2.14.0 (Claude CLI 2.1.121):
269
+ Claude Code–specific stats:
281
270
 
282
- | Field | Type | Description |
283
- | -------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
284
- | `pluginErrors` | `Array<{plugin, reason}>` \| undefined | Plugins that failed to load due to unmet dependencies, captured from the `system/init` event. `undefined` when no plugin errors occurred. |
271
+ | Field | Type | Description |
272
+ | ---------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
273
+ | `retries` | number | Total API retries that occurred during the session |
274
+ | `lastRetryError` | string \| undefined | Error message from the most recent retry (if any) |
275
+ | `pluginErrors` | `Array<{plugin, reason}>` \| undefined | Plugins that failed to load due to unmet dependencies, captured from the `system/init` event. `undefined` when no plugin errors occurred. |
285
276
 
286
277
  ### `system/api_retry` events
287
278
 
@@ -304,7 +295,7 @@ const session = manager.getSession('my-session');
304
295
  console.log(session.pid); // e.g., 12345 or undefined
305
296
  ```
306
297
 
307
- ## Verifying what a session did (6.0.0)
298
+ ## Verifying what a session did
308
299
 
309
300
  A plain session leaves no verdict — it ran, and nothing checked the result. To
310
301
  check it, hand `verify_run` a contract and the directory:
@@ -319,5 +310,5 @@ verify_run({
319
310
  For work that should be checked as part of running it, use a workflow instead —
320
311
  see [`workflow.md`](./workflow.md).
321
312
 
322
- `SendOptions` also gained `nodeKind` and `taskKind`, both stamped onto the run
313
+ `SendOptions` also accepts `nodeKind` and `taskKind`, both stamped onto the run
323
314
  ledger row. `taskKind` is caller-declared and never inferred from the prompt.
package/skills/references/tools.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Tools Reference
2
2
 
3
- All tools are registered as Claw Orchestrator plugin tools. In standalone mode, they're accessible via the embedded HTTP server.
3
+ All 78 tools are registered as OpenClaw plugin tools and exposed over MCP by `clawo-mcp` (see [mcp.md](./mcp.md)). The embedded HTTP server covers a subset of them.
4
4
 
5
5
  ## Session Lifecycle (6)
6
6
 
@@ -16,18 +16,17 @@ Start a persistent coding session with full CLI flag support.
16
16
  | `model` | string | Model alias or full name |
17
17
  | `permissionMode` | string | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`) |
18
18
  | `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 → its plan mode; OpenCode → a generated `clawo-readonly` agent denying `edit`/`bash`. **`grok` refuses a read-only session** rather than approximate one — its enforcement has not been adversarially verified. A `custom` engine must map it via `permissionModes`, or the session refuses to start. Persisted across session resume. |
19
- | `effort` | string | `low`, `medium`, `high`, `max`, `auto` |
20
19
  | `allowedTools` | string[] | Tools to auto-approve |
21
20
  | `disallowedTools` | string[] | Tools to deny |
22
21
  | `maxTurns` | number | Max agent loop turns |
23
22
  | `maxBudgetUsd` | number | Max API spend (USD). Enforced by the runtime on every engine: once the session's cumulative cost reaches the cap, further sends are refused before the engine is spawned. See [observability.md](observability.md) for the accuracy caveat on engines that estimate token counts. |
24
23
  | `systemPrompt` | string | Replace system prompt |
25
- | `appendSystemPrompt` | string | Append custom instructions to the system prompt. Claude Code and Grok take it natively; Codex, Antigravity and OpenCode have no such flag and receive it at the top of the first message of a conversation |
24
+ | `appendSystemPrompt` | string | Append custom instructions to the system prompt. Claude Code and Grok take it natively; Codex, Antigravity and OpenCode have no such flag and receive it at the top of the first message of a conversation |
26
25
  | `agents` | object | Custom sub-agents JSON |
27
26
  | `agent` | string | Default agent to use |
28
27
  | `bare` | boolean | Skip hooks, LSP, auto-memory, CLAUDE.md |
29
28
  | `worktree` | string \| boolean | Run in git worktree |
30
- | `fallbackModel` | string | Fallback when primary overloaded |
29
+ | `fallbackModel` | string \| string[] | Fallback model(s) when the primary is overloaded; an array is tried in order |
31
30
  | `resumeSessionId` | string | Resume existing session by ID |
32
31
  | `jsonSchema` | string | JSON Schema for structured output. Claude: `--json-schema` (inline). Codex: `--output-schema` (written to a temp file, requires Codex 0.132+). Other engines ignore it. |
33
32
  | `mcpConfig` | string \| string[] | MCP server config file(s) |
@@ -35,20 +34,21 @@ Start a persistent coding session with full CLI flag support.
35
34
  | `ultracode` | boolean | Claude only. Enable "ultracode" / dynamic workflows — Claude plans a JS orchestration script per substantive task and fans out to subagents. Injected as the `ultracode:true` settings key (merged into `settings`). The workflow runs in the background: `session_send` returns at launch, and the completion turn is not returned by a later send (see sessions.md). |
36
35
  | `noSessionPersistence` | boolean | Do not save session to disk — both the engine's own transcript and this orchestrator's resume registry, so a later start under the same name does not reattach |
37
36
  | `ignoreUserConfig` | boolean | Codex only. Run without loading `$CODEX_HOME/config.toml`, so an orchestrated run is decided by what the caller passed rather than by the machine's own Codex config — notably a `model = …` line in that file, which otherwise picks the model while the ledger records this engine's default. Auth still resolves from `CODEX_HOME`. |
37
+ | `codexProfile` | string | Codex only. Named profile from `~/.codex/config.toml`, passed as `codex exec --profile` |
38
38
  | `restricted` | boolean | Claude Code only. Restricted mode (`--restricted`): the CLI removes the built-in tools that run commands or code — Bash, PowerShell, the REPL — plus `WebFetch` unless `tools` names them, and ignores user, project and local settings files. Separate from `sandboxMode: 'read-only'`: that maps to plan mode, which holds on its own, while this makes the shell absent rather than refused. It also drops the caller's CLAUDE.md and hooks, so it is never switched on implicitly. |
39
39
  | `betas` | string \| string[] | Custom beta headers |
40
40
  | `enableAgentTeams` | boolean | Enable experimental agent teams |
41
41
  | `enableAutoMode` | boolean | Enable auto permission mode |
42
- | `customEngine` | object | Custom engine config (required when `engine='custom'`). See [Multi-Engine: Custom Engine](./multi-engine.md#custom-engine-enginecustom). |
42
+ | `customEngine` | object | Custom engine config (required when `engine='custom'`). See [Multi-Engine: Custom Engine](./multi-engine.md#custom-engine-engine-custom). |
43
43
  | `crossSessionInbound` | string | `accept` / `hold` / `refuse` — policy for peer messages from other Claude Code sessions on this machine (Claude engine). Delivered as a settings key; there is no CLI flag. Without it the CLI holds messages whose two sides run different permission modes, which is the usual orchestrated-session-to-human-terminal case |
44
44
  | `includeHookEvents` | boolean | Stream hook lifecycle events (PreToolUse/PostToolUse) as `system` events |
45
45
  | `forwardSubagentText` | boolean | Forward subagent text and thinking into the output stream (Claude engine, CLI 2.1.211+). Without it the parent stream stays quiet while a subagent works |
46
- | `permissionPromptTool` | string | MCP tool name to delegate permission prompts to (non-interactive use) When omitted, the session runs with `--permission-prompts none`: a prompt nobody could answer is denied rather than left waiting until the turn timeout. |
46
+ | `permissionPromptTool` | string | MCP tool name to delegate permission prompts to (non-interactive use). When omitted, the session runs with `--permission-prompts none`: a prompt nobody could answer is denied rather than left waiting until the turn timeout. |
47
47
  | `excludeDynamicSystemPromptSections` | boolean | Move cwd/env/git context from system prompt to user message for better prompt cache hits; auto-enabled with `bare: true` |
48
48
  | `enablePromptCaching1H` | boolean | Enable 1-hour prompt cache TTL (vs default 5-min); auto-enabled with `bare: true` |
49
- | `debug` | string | Debug categories to enable (comma-separated, e.g. `"api,mcp"`) |
49
+ | `debug` | string \| string[] | Debug categories to enable (e.g. `"api,mcp"` or `["api", "mcp"]`) |
50
50
  | `debugFile` | string | File path to write debug output to |
51
- | `fromPr` | string \| number | Resume a session linked to a GitHub PR number or URL |
51
+ | `fromPr` | string | Resume a session linked to a GitHub PR number or URL |
52
52
  | `channels` | string \| string[] | MCP channel subscription spec (research preview) |
53
53
  | `dangerouslyLoadDevelopmentChannels` | string \| string[] | Development MCP channel subscriptions (research preview) |
54
54
  | `forkSubagent` | boolean | Fork subagent for non-interactive sessions (sets `CLAUDE_CODE_FORK_SUBAGENT=1`) |
@@ -119,7 +119,7 @@ Dashboard view: all sessions with ready/busy/paused state, cost, context %, last
119
119
 
120
120
  ### `coding_session_status`
121
121
 
122
- Detailed status: tokens, cost, context %, tool calls, uptime. (Renamed from `session_status` in v3.2 to avoid collision with OpenClaw's built-in `session_status` tool.)
122
+ Detailed status: tokens, cost, context %, tool calls, uptime. (Prefixed to avoid clashing with OpenClaw's built-in `session_status`.)
123
123
 
124
124
  | Parameter | Type | Required |
125
125
  | --------- | ------ | -------- |
@@ -190,9 +190,9 @@ Returns `{ ok, stdout, stderr, dryRun }`.
190
190
 
191
191
  ---
192
192
 
193
- ## Claude (4)
193
+ ## Claude (5)
194
194
 
195
- Tools targeting Claude Code's CLI. `plugin_details` is a one-shot wrapper. The `claude_goal_*` tools require a session started with `engine: "claude"` (the default) and pre-format the `/goal` slash command introduced in CLI 2.1.139.
195
+ Tools targeting Claude Code's CLI. `plugin_details` and `claude_agents_list` are one-shot wrappers. The `claude_goal_*` tools require a session started with `engine: "claude"` (the default) and pre-format the `/goal` slash command introduced in CLI 2.1.139.
196
196
 
197
197
  ### `plugin_details`
198
198
 
@@ -240,6 +240,17 @@ Returns the regular turn result; goal info is in the assistant's reply text.
240
240
 
241
241
  > Note: Claude's `/goal` is interactive-only in the upstream TUI sense — it has no dedicated CLI flag or JSON event. These wrappers work because Claude Code interprets slash-prefixed user messages in non-interactive (`-p` / stream-json) mode the same way. The wrappers exist for engine-guard and discoverability, not protocol translation.
242
242
 
243
+ ### `claude_agents_list`
244
+
245
+ Wraps `claude agents --json` — lists Claude Code background agent sessions (state/model/title/progress). One-shot spawn, not tied to a managed session. (`claude continue/respawn/stop/logs` do not exist as headless subcommands; use `resumeSessionId` on `session_start` to resume.)
246
+
247
+ | Parameter | Type | Description |
248
+ | --------- | ------- | --------------------------------------------------------- |
249
+ | `all` | boolean | Include completed sessions (`--all`). |
250
+ | `cwd` | string | Scope to sessions started under this directory (`--cwd`). |
251
+
252
+ Returns `{ ok, agents }`.
253
+
243
254
  ---
244
255
 
245
256
  ## Codex (13)
@@ -313,11 +324,11 @@ Send `/goal pause`, `/goal resume`, or `/goal clear` respectively. Requires `eng
313
324
 
314
325
  Returns `{ ok, text, goal }`.
315
326
 
316
- > **Stability note:** Codex's `goals` feature is flagged "under development" in 0.128.0 and has known bugs (issue #20591). The slash-command parsing on the server side may also evolve. The wrapper is intentionally a thin sugar layer so upstream changes only affect the slash-text we send, not the protocol structure.
327
+ > **Stability note:** Codex's `goals` feature is experimental upstream. The wrapper only formats the `/goal` slash text, so upstream changes affect that text, not the protocol.
317
328
 
318
- ### `codex_interrupt` / `codex_steer` / `codex_fork` / `codex_rollback` / `codex_models`
329
+ ### Codex app-server RPCs
319
330
 
320
- Codex app-server v2 RPCs (require `engine: "codex-app"`). Method names + param shapes verified against `codex app-server generate-json-schema` (Codex 0.137).
331
+ `codex_interrupt`, `codex_steer`, `codex_fork`, `codex_rollback`, `codex_models` and `codex_thread_list` call Codex app-server v2 methods and require `engine: "codex-app"`. Method names and parameter shapes follow `codex app-server generate-json-schema`.
321
332
 
322
333
  | Tool | RPC | Params | Returns |
323
334
  | ------------------- | ----------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
@@ -334,21 +345,6 @@ opening a fresh one.
334
345
 
335
346
  ---
336
347
 
337
- ## Claude CLI (1)
338
-
339
- ### `claude_agents_list`
340
-
341
- Wraps `claude agents --json` — lists Claude Code background agent sessions (state/model/title/progress). One-shot spawn, not tied to a managed session. (`claude continue/respawn/stop/logs` do not exist as headless subcommands; use `resumeSessionId` on `session_start` to resume.)
342
-
343
- | Parameter | Type | Description |
344
- | --------- | ------- | --------------------------------------------------------- |
345
- | `all` | boolean | Include completed sessions (`--all`). |
346
- | `cwd` | string | Scope to sessions started under this directory (`--cwd`). |
347
-
348
- Returns `{ ok, agents }`.
349
-
350
- ---
351
-
352
348
  ## Fan-out (3)
353
349
 
354
350
  Run one task across N engine/model agents **in parallel** and collect their answers, with an optional synthesis pass. Cross-engine best-of-N / diverse-perspective primitive — no rounds, votes, or git worktrees. For isolated parallel _editing_, use Council.
@@ -382,7 +378,7 @@ Abort a running fan-out by `id` (already-started agents finish; synthesis is ski
382
378
 
383
379
  ### `coding_agents_list`
384
380
 
385
- List agent definitions from `.claude/agents/` (project + global). (Renamed from `agents_list` in v3.2 to avoid collision with OpenClaw's built-in `agents_list` tool.)
381
+ List agent definitions from `.claude/agents/` (project + global). (Prefixed to avoid clashing with OpenClaw's built-in `agents_list`.)
386
382
 
387
383
  | Parameter | Type |
388
384
  | --------- | ------ |
@@ -542,15 +538,16 @@ Get status and plan text when completed.
542
538
 
543
539
  ### `ultrareview_start`
544
540
 
545
- Launch a fleet of bug-hunting agents (1-20) reviewing code from different angles.
541
+ Start 1–20 reviewer agents that review the code in parallel, each from a different angle. Runs in background.
546
542
 
547
- | Parameter | Type | Required | Description |
548
- | -------------------- | ------ | -------- | ------------------------------- |
549
- | `cwd` | string | yes | Project directory |
550
- | `agentCount` | number | | Agents (1-20, default 5) |
551
- | `maxDurationMinutes` | number | | Duration (5-25 min, default 10) |
552
- | `model` | string | | Model for reviewers |
553
- | `focus` | string | | Review focus area |
543
+ | Parameter | Type | Required | Description |
544
+ | -------------------- | -------- | -------- | ---------------------------------------------------------------------------------- |
545
+ | `cwd` | string | yes | Project directory |
546
+ | `agentCount` | number | | Agents (1-20, default 5) |
547
+ | `maxDurationMinutes` | number | | Duration (5-25 min, default 10) |
548
+ | `model` | string | | Model for reviewers |
549
+ | `focus` | string | | Review focus area |
550
+ | `engines` | string[] | | Engines to spread reviewers across (default `["claude"]`). Every reviewer runs read-only, so `grok` and `custom` are not allowed |
554
551
 
555
552
  ### `ultrareview_status`
556
553
 
@@ -597,21 +594,13 @@ Start a chat-mode autoloop. Planner starts immediately; Coder + Reviewer start o
597
594
  > permission to choose what binary runs. Built-in engines stay fully selectable
598
595
  > over HTTP.
599
596
  >
600
- > The check used to be wired into two autoloop routes and to match three
601
- > snake_case names; `POST /session/start` had no guard and `session_start` spells
602
- > the field `customEngine`, so it went straight through. Matching by shape at the
603
- > one place every body passes is what stops the next route from inheriting the
604
- > same gap.
605
- >
606
- > **Resuming one is done by reference.** Refusing the config over HTTP left a real
607
- > gap: a custom-engine run that crashed could not be brought back by any remote
608
- > caller, because the material it needed had nowhere to come from. So a remote
609
- > resume names the secret instead of carrying it — `plannerCustomEngineRef` and
610
- > friends on `POST /autoloop/<id>/resume`, `agentCustomEngineRefs` on
611
- > `workflow_resume` — and the orchestrator resolves the name against its own
612
- > `CLAWO_CUSTOM_ENGINE_<NAME>` environment. `GET /autoloop/<id>/resume-requirements`
613
- > says which roles need one. The name is not sensitive, the value never leaves the
614
- > host, and an unknown name fails loudly rather than starting without credentials.
597
+ > **Resuming by reference.** A remote resume names the credential instead of
598
+ > carrying it — `plannerCustomEngineRef` and friends on `POST /autoloop/<id>/resume`,
599
+ > `agentCustomEngineRefs` on `workflow_resume` — and the orchestrator resolves the
600
+ > name against its own `CLAWO_CUSTOM_ENGINE_<NAME>` environment.
601
+ > `GET /autoloop/<id>/resume-requirements` lists which roles need one. The name is
602
+ > not sensitive, the value never leaves the host, and an unknown name fails rather
603
+ > than starting without credentials.
615
604
 
616
605
  Custom configs are not persisted or accepted from Planner output. See [`multi-engine.md`](./multi-engine.md) for their shape.
617
606
 
@@ -626,7 +615,7 @@ when it coincides with lease expiry.
626
615
  Recovery is exposed by `POST /autoloop/<id>/resume`, not by an MCP resume tool.
627
616
  Its timeout body is limited to `send_timeout_ms` plus
628
617
  `pending_dispatch_id`. The send timeout must be finite, in range, and strictly
629
- larger than the run's latest effective value (legacy baseline: 600000). Equal
618
+ larger than the run's latest effective value (600000 for runs that predate this setting). Equal
630
619
  or smaller values are rejected, and there is deliberately no
631
620
  `allow_decrease`. Lease and hard-cap overrides are not accepted on resume.
632
621
  Each successful increase appends one migration row to `decisions.jsonl`; the
@@ -695,7 +684,7 @@ Full snapshot of a run: spec + chat + state.
695
684
 
696
685
  | Parameter | Type | Required |
697
686
  | --------- | ------ | -------- |
698
- | `id` | string | yes |
687
+ | `runId` | string | yes |
699
688
 
700
689
  ### `ultraapp_status`
701
690
 
@@ -703,15 +692,13 @@ Lightweight status (mode + timestamps).
703
692
 
704
693
  | Parameter | Type | Required |
705
694
  | --------- | ------ | -------- |
706
- | `id` | string | yes |
695
+ | `runId` | string | yes |
707
696
 
708
697
  ### `ultraapp_new`
709
698
 
710
- Create a fresh run. Optionally seeds the interview with the user's first message.
699
+ Create a fresh run and start the interview session. Returns `{ ok, runId }`. The first question arrives via `ultraapp_get`.
711
700
 
712
- | Parameter | Type | Required | Description |
713
- | -------------- | ------ | -------- | ----------------------------------------------------------------------------- |
714
- | `firstMessage` | string | | Free-form opening line; the interview Opus reads it before its first question |
701
+ (no params)
715
702
 
716
703
  ### `ultraapp_answer`
717
704
 
@@ -719,19 +706,18 @@ Submit an answer to the current interview question.
719
706
 
720
707
  | Parameter | Type | Required | Description |
721
708
  | ---------- | ------ | -------- | -------------------------------------------------------------------- |
722
- | `id` | string | yes | Run id |
709
+ | `runId` | string | yes | Run id |
723
710
  | `value` | string | yes | One of the question's `options[].value`, or `''` when using freeform |
724
711
  | `freeform` | string | | Free-form text when none of the options fit |
725
712
 
726
713
  ### `ultraapp_add_file`
727
714
 
728
- Upload a sample file to `examples/` (the interview engine will `extract_metadata` it).
715
+ Reference a local example file by absolute path (under `$HOME` or `/tmp`; symlinks and dotfiles are rejected). The interview extracts metadata from it. To upload a file from a browser, use the dashboard.
729
716
 
730
- | Parameter | Type | Required |
731
- | --------- | ---------------- | -------- |
732
- | `id` | string | yes |
733
- | `path` | string | yes |
734
- | `content` | string \| Buffer | yes |
717
+ | Parameter | Type | Required |
718
+ | -------------- | ------ | -------- |
719
+ | `runId` | string | yes |
720
+ | `absolutePath` | string | yes |
735
721
 
736
722
  ### `ultraapp_spec_edit`
737
723
 
@@ -739,7 +725,7 @@ Apply RFC 6902 JSON Patch ops to the AppSpec mid-interview.
739
725
 
740
726
  | Parameter | Type | Required |
741
727
  | --------- | -------- | -------- |
742
- | `id` | string | yes |
728
+ | `runId` | string | yes |
743
729
  | `patch` | object[] | yes |
744
730
 
745
731
  ### `ultraapp_build_start`
@@ -748,7 +734,7 @@ Validate the spec strictly (shape + cross-refs + DAG) and enqueue the build. Cou
748
734
 
749
735
  | Parameter | Type | Required |
750
736
  | --------- | ------ | -------- |
751
- | `id` | string | yes |
737
+ | `runId` | string | yes |
752
738
 
753
739
  ### `ultraapp_build_cancel`
754
740
 
@@ -756,7 +742,7 @@ Abort an active build. Council sessions are stopped and the worktrees are left a
756
742
 
757
743
  | Parameter | Type | Required |
758
744
  | --------- | ------ | -------- |
759
- | `id` | string | yes |
745
+ | `runId` | string | yes |
760
746
 
761
747
  ### `ultraapp_feedback`
762
748
 
@@ -764,7 +750,7 @@ Done-mode feedback. Haiku classifier routes into `cosmetic` (Opus patcher), `spe
764
750
 
765
751
  | Parameter | Type | Required | Description |
766
752
  | --------- | ------ | -------- | ----------------------- |
767
- | `id` | string | yes | Run id |
753
+ | `runId` | string | yes | Run id |
768
754
  | `text` | string | yes | The feedback (1+ chars) |
769
755
 
770
756
  ### `ultraapp_promote_version`
@@ -773,7 +759,7 @@ Atomically swap the deployed version. Stops the current container/process, start
773
759
 
774
760
  | Parameter | Type | Required | Description |
775
761
  | --------- | ------ | -------- | ------------------------------------ |
776
- | `id` | string | yes | Run id |
762
+ | `runId` | string | yes | Run id |
777
763
  | `version` | string | yes | Target version label (`v1`, `v2`, …) |
778
764
 
779
765
  ### `ultraapp_start_container`
@@ -782,7 +768,7 @@ Start the container/process for the active version (no-op if already running).
782
768
 
783
769
  | Parameter | Type | Required |
784
770
  | --------- | ------ | -------- |
785
- | `id` | string | yes |
771
+ | `runId` | string | yes |
786
772
 
787
773
  ### `ultraapp_stop_container`
788
774
 
@@ -790,7 +776,7 @@ Stop the container/process without deleting any state.
790
776
 
791
777
  | Parameter | Type | Required |
792
778
  | --------- | ------ | -------- |
793
- | `id` | string | yes |
779
+ | `runId` | string | yes |
794
780
 
795
781
  ### `ultraapp_delete`
796
782
 
@@ -798,11 +784,11 @@ Stop + remove the run completely (sessions, container, on-disk state, router ent
798
784
 
799
785
  | Parameter | Type | Required |
800
786
  | --------- | ------ | -------- |
801
- | `id` | string | yes |
787
+ | `runId` | string | yes |
802
788
 
803
789
  ---
804
790
 
805
- ## Workflow kernel & verification (6.0.0)
791
+ ## Workflow & Verification (8)
806
792
 
807
793
  Full semantics in [`workflow.md`](./workflow.md) and
808
794
  [`verification.md`](./verification.md).
package/skills/references/ultra.md CHANGED
@@ -18,7 +18,7 @@ Runs in background — poll with `ultraplan_status`.
18
18
  ### Usage
19
19
 
20
20
  ```typescript
21
- const plan = manager.ultraplanStart('Add OAuth2 support with Google and GitHub providers', {
21
+ const plan = await manager.ultraplanStart('Add OAuth2 support with Google and GitHub providers', {
22
22
  cwd: '/path/to/project',
23
23
  model: 'opus', // default
24
24
  timeout: 1800000, // 30 min default
@@ -48,20 +48,20 @@ if (status?.status === 'completed') {
48
48
  | `cwd` | `process.cwd()` | Project directory to explore |
49
49
  | `timeout` | 1,800,000 ms (30 min) | Maximum planning time |
50
50
 
51
- Results remain queryable for 30 minutes after completion.
51
+ Results are stored as a durable run and remain queryable after a restart.
52
52
 
53
53
  ---
54
54
 
55
55
  ## Ultrareview
56
56
 
57
- A fleet of specialized bug-hunting agents that review your codebase in parallel, each from a different angle. Built on top of the [Council](./council.md) system.
57
+ A set of specialized reviewer agents that review your codebase in parallel, each from a different angle. Built on the fan-out primitive (see `fanout_start` in [tools.md](./tools.md)).
58
58
 
59
59
  ### How It Works
60
60
 
61
- 1. Creates a council with N reviewer agents (5-20)
62
- 2. Each agent specializes in a different review angle
63
- 3. Agents run in parallel via git worktree isolation
64
- 4. Findings from all agents are synthesized into a single report
61
+ 1. Starts a fan-out of N reviewer agents (1-20, default 5)
62
+ 2. Each agent reviews from a different angle in the project directory, read-only on every engine (`sandboxMode: 'read-only'`, and plan mode on Claude), so no reviewer can change the code it is reviewing
63
+ 3. Agents run in parallel; one failing reviewer does not stop the others
64
+ 4. A read-only synthesis pass merges all findings into one report
65
65
 
66
66
  ### Available Review Angles (20)
67
67
 
@@ -91,14 +91,14 @@ A fleet of specialized bug-hunting agents that review your codebase in parallel,
91
91
  ### Usage
92
92
 
93
93
  ```typescript
94
- const review = manager.ultrareviewStart('/path/to/project', {
94
+ const review = await manager.ultrareviewStart('/path/to/project', {
95
95
  agentCount: 10, // use 10 of the 20 angles
96
96
  maxDurationMinutes: 15, // 15 min timeout per agent
97
97
  model: 'sonnet', // model for all reviewers
98
98
  focus: 'Find security and performance bugs',
99
99
  });
100
100
 
101
- console.log(`Review ID: ${review.id}, Council: ${review.councilId}`);
101
+ console.log(`Review ID: ${review.id}`);
102
102
 
103
103
  // Poll for completion
104
104
  const status = manager.ultrareviewStatus(review.id);
@@ -116,11 +116,12 @@ if (status?.status === 'completed') {
116
116
 
117
117
  ### Configuration
118
118
 
119
- | Parameter | Default | Range | Description |
120
- | -------------------- | ------------------------- | ----- | ------------------------- |
121
- | `agentCount` | 5 | 1-20 | Number of reviewer agents |
122
- | `maxDurationMinutes` | 10 | 5-25 | Per-agent timeout |
123
- | `model` | session default | — | Model for all reviewers |
124
- | `focus` | bugs + security + quality | — | Review focus description |
119
+ | Parameter | Default | Range | Description |
120
+ | -------------------- | ------------------------- | ----- | ------------------------------------------------------------------------------- |
121
+ | `agentCount` | 5 | 1-20 | Number of reviewer agents |
122
+ | `maxDurationMinutes` | 10 | 5-25 | Per-agent timeout |
123
+ | `model` | session default | — | Model for all reviewers |
124
+ | `focus` | bugs + security + quality | — | Review focus description |
125
+ | `engines` | `['claude']` | — | Engines assigned to reviewers round-robin. Not `grok`, which refuses a read-only session, or `custom` |
125
126
 
126
- The council runs with `maxRounds: 2` — one round to find bugs, one to cross-review. Results remain queryable for 30 minutes.
127
+ Reviewers run once each (up to 20 turns); there is no cross-review round. Results are stored as a durable run and remain queryable after a restart.