@enderfga/claw-orchestrator 7.8.0 → 7.10.0

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 (38) hide show
  1. package/README.md +84 -29
  2. package/dist/bin/cli.js +263 -0
  3. package/dist/bin/cli.js.map +1 -1
  4. package/dist/src/autoloop/dispatcher.d.ts +6 -0
  5. package/dist/src/autoloop/dispatcher.js +20 -0
  6. package/dist/src/autoloop/dispatcher.js.map +1 -1
  7. package/dist/src/embedded-server.js +12 -2
  8. package/dist/src/embedded-server.js.map +1 -1
  9. package/dist/src/engine-spawn.js +8 -5
  10. package/dist/src/engine-spawn.js.map +1 -1
  11. package/dist/src/index.js +12 -4
  12. package/dist/src/index.js.map +1 -1
  13. package/dist/src/kernel/exec.js +4 -1
  14. package/dist/src/kernel/exec.js.map +1 -1
  15. package/dist/src/kernel/nodes/agent.d.ts +9 -0
  16. package/dist/src/kernel/nodes/agent.js +35 -1
  17. package/dist/src/kernel/nodes/agent.js.map +1 -1
  18. package/dist/src/models.js +17 -4
  19. package/dist/src/models.js.map +1 -1
  20. package/dist/src/persistent-grok-session.js +63 -20
  21. package/dist/src/persistent-grok-session.js.map +1 -1
  22. package/dist/src/persistent-opencode-session.d.ts +8 -0
  23. package/dist/src/persistent-opencode-session.js +16 -0
  24. package/dist/src/persistent-opencode-session.js.map +1 -1
  25. package/dist/src/session-manager.js +7 -7
  26. package/dist/src/session-manager.js.map +1 -1
  27. package/dist/src/verify/evidence.d.ts +6 -0
  28. package/dist/src/verify/evidence.js +19 -0
  29. package/dist/src/verify/evidence.js.map +1 -1
  30. package/package.json +1 -1
  31. package/skills/SKILL.md +1 -1
  32. package/skills/references/autoloop.md +5 -3
  33. package/skills/references/claude-cli-tracking.md +2 -1
  34. package/skills/references/cli.md +45 -2
  35. package/skills/references/multi-engine.md +19 -11
  36. package/skills/references/tools.md +72 -71
  37. package/skills/references/ultra.md +1 -1
  38. package/skills/references/workflow.md +5 -0
package/skills/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: claw-orchestrator
3
- description: Manage persistent coding sessions across Claude Code, Codex, Antigravity (agy), Grok Build, and OpenCode engines. Use when orchestrating multi-engine coding agents, starting/sending/stopping sessions, running multi-agent council collaborations, cross-session messaging, ultraplan deep planning, ultrareview parallel code review, autoloop autonomous workspace iteration, ultraapp building deployable web apps from a structured Q&A interview, switching models/tools at runtime, exposing the orchestrator's 78 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose, or running as an Agent Client Protocol (ACP) agent that Zed / JetBrains / Neovim / Emacs / VS Code / dsh can drive directly. Triggers on "start a session", "send to session", "run council", "ultraplan", "ultrareview", "autoloop", "ultraapp", "Forge tab", "build a web app", "one-click app", "AppSpec", "autonomous iteration", "iterate until goal", "auto research", "switch model", "hand off a session", "session handoff", "switch engine", "continue on codex", "continue on claude", "move this session to another engine", "multi-agent coding", "coding session", "session inbox", "grok session", "grok build", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol", "ultracode", "dynamic workflow", "fanout", "fan-out", "best-of-N", "steer turn", "interrupt turn", "fork thread", "rollback turns", "acp", "agent client protocol", "clawo acp", "zed agent", "jetbrains agent", "external agent", "dsh subagent", "deepseek harness", "clawo runs", "run ledger", "session cost", "coding-agent token usage", "spend cap", "budget limit", "maxBudgetUsd", "durable workflow", "resume a run", "verify a coding run", "acceptance contract", "evidence bundle", "did the agent's tests actually pass", "protected tests", "agent edited the tests", "human gate", "repair loop", "clawo workflow", "clawo verify".
3
+ description: Manage persistent coding sessions across Claude Code, Codex, Antigravity (agy), Grok Build, and OpenCode engines. Use when orchestrating multi-engine coding agents, starting/sending/stopping sessions, running multi-agent council collaborations, cross-session messaging, ultraplan deep planning, ultrareview parallel code review, autoloop autonomous workspace iteration, ultraapp building deployable web apps from a structured Q&A interview, switching models/tools at runtime, exposing the orchestrator's 78 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose, or running as an Agent Client Protocol (ACP) agent that Zed / JetBrains / Neovim / Emacs / VS Code / dsh can drive directly. Triggers on "start a session", "send to session", "run council", "ultraplan", "ultrareview", "autoloop", "ultraapp", "Forge tab", "build a web app", "one-click app", "AppSpec", "autonomous iteration", "iterate until goal", "auto research", "switch model", "hand off a session", "session handoff", "switch engine", "continue on codex", "continue on claude", "move this session to another engine", "multi-agent coding", "coding session", "session inbox", "grok session", "grok build", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol", "ultracode", "dynamic workflow", "fanout", "fan-out", "best-of-N", "steer turn", "interrupt turn", "fork thread", "rollback turns", "acp", "agent client protocol", "clawo acp", "zed agent", "jetbrains agent", "external agent", "dsh subagent", "deepseek harness", "clawo runs", "run ledger", "session cost", "coding-agent token usage", "spend cap", "budget limit", "maxBudgetUsd", "durable workflow", "resume a run", "verify a coding run", "acceptance contract", "evidence bundle", "did the agent's tests actually pass", "protected tests", "agent edited the tests", "human gate", "repair loop", "clawo workflow", "clawo verify", "clawo solve", "clawo fanout", "fix and verify", "solve from the terminal".
4
4
  metadata:
5
5
  {
6
6
  'openclaw':
package/skills/references/autoloop.md CHANGED
@@ -460,9 +460,11 @@ Custom-engine configs are the one thing the spec does not carry (they can hold
460
460
  secrets), so a resume must be given them again. Cancelling a run stops all three
461
461
  agents, the same as `autoloop_stop`. If the highest committed Coder iteration
462
462
  has ledger artifacts and no `verdict.json`, and `HEAD` still names that iter,
463
- resume delivers one `review_request` for it and the dispatcher persists the
464
- Reviewer verdict; it does not send a new Coder directive. An in-flight send is
465
- still not retried, and there is no message outbox.
463
+ resume starts and sends only the Reviewer: one `review_request` for that
464
+ checkpoint, and the dispatcher persists `verdict.json`. It does not create or
465
+ resume a Coder session, and a historical persisted Coder registry row is left
466
+ unchanged. An in-flight send is still not retried, and there is no message
467
+ outbox.
466
468
 
467
469
  ## Known limitations
468
470
 
package/skills/references/claude-cli-tracking.md CHANGED
@@ -2,12 +2,13 @@
2
2
 
3
3
  This document tracks which Claude Code CLI version Claw Orchestrator is currently synced to, and which features have been integrated. Recent rows also record the other engines' versions checked in the same sync.
4
4
 
5
- ## Currently tracked: **Claude Code CLI 2.1.292** (as of 2026-10-07, plugin v7.8.0)
5
+ ## Currently tracked: **Claude Code CLI 2.1.295** (as of 2026-10-09, plugin v7.10.0)
6
6
 
7
7
  ## Sync history
8
8
 
9
9
  | Plugin Version | Claude CLI Version | Date | Notable integrations |
10
10
  | ------------------- | ------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11
+ | v7.10.0 | 2.1.295 | 2026-10-09 | CC 2.1.292→2.1.295, Codex 0.160.1→0.162.0, agy 1.3.1→1.3.2, grok 1.0.46→1.0.50; OpenCode 1.18.35 unchanged. No flag the wrappers pass changed. Integrated: Claude Haiku 5.5 registered and the `haiku` alias moved to it (`--model haiku` resolves to `claude-haiku-5-5` in 2.1.295); Sonnet 5.5's cache-hit price corrected to 0.05× input. Integrated: grok 1.0.50's `--sandbox read-only` backs Grok's `sandboxMode: 'read-only'`, measured against direct, shell, subagent, resumed-turn and out-of-project writes; a profile grok cannot apply only warns, so the session kills the process on that warning. |
11
12
  | v7.8.0 | 2.1.292 | 2026-10-07 | CC 2.1.291→2.1.292, agy 1.3.0→1.3.1, OpenCode 1.18.34→1.18.35; Codex 0.160.1 and grok 1.0.46 unchanged. No flag surface changed. Integrated: Codex image generation surfaced as `images` on the send result (`codex exec` from `$CODEX_HOME/generated_images/<thread>/`, `codex-app` from the `imageGeneration` item). Read, no change needed: CC 2.1.292 negotiates MCP protocol 2026-07-28 with local stdio servers by default — `clawo-mcp` answers with 2025-11-25 and connects with no delay (measured against `MCP_PROTOCOL_NEGOTIATION=legacy`). |
12
13
  | v7.7.0 | 2.1.291 | 2026-10-07 | CC 2.1.289→2.1.291, Codex 0.160.0→0.160.1, agy 1.2.17→1.3.0; grok 1.0.46 and OpenCode 1.18.34 unchanged. No flag surface changed. Integrated: `--chrome` behind a `chrome` session option (2.1.290 stopped project settings from turning Claude in Chrome on, so the flag is the way in); `system/model_refusal_fallback` recorded per turn in the ledger. Read, no change needed: Codex's `computer_use` feature is the ChatGPT desktop app's Computer Use plugin, not a tool in `codex exec`, which reports none; agy 1.3.0 is interactive-view changes. |
13
14
  | v7.6.2 | 2.1.289 | 2026-10-05 | CC 2.1.286→2.1.289, Codex 0.159.3→0.160.0, agy 1.2.14→1.2.17, grok 1.0.44→1.0.46; OpenCode 1.18.34 unchanged. No flag surface changed, no wrapper change. Read, no change needed: CC 2.1.288 limits background-command time only in unattended (`-p`) sessions, which these already are; agy 1.2.16 fixes `-p` runs exiting before the agent answers a finished background command, consistent with the 7.5.6 deadline handling. |
package/skills/references/cli.md CHANGED
@@ -196,6 +196,48 @@ Tools without a CLI command are reachable through the OpenClaw plugin, the MCP
196
196
  server (`clawo-mcp`, see [mcp.md](./mcp.md)), or the `SessionManager` API. See
197
197
  [Tools Reference](./tools.md) for full parameter documentation.
198
198
 
199
+ ## `clawo solve`
200
+
201
+ Start the built-in `solve` workflow — triage → implement → verify → repair until
202
+ green — and let the runtime decide whether it worked.
203
+
204
+ ```bash
205
+ clawo solve "<task>" [--engine <engine[:model]>] [--check "<command>"]... [--contract <file>]
206
+ [--scouts <list>] [--reviewers <list>] [--max-repairs N] [--human-gate]
207
+ [--cwd <dir>] [--wait] [--json]
208
+ ```
209
+
210
+ | Option | Default | Notes |
211
+ | --------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
212
+ | `-e, --engine` | `claude` | The implementer, `engine` or `engine:model` (`codex:gpt-6.1-sol`) |
213
+ | `-c, --check` | — | A command check, repeatable. Split on whitespace and run as argv, never through a shell; anything that needs quoting belongs in `--contract` |
214
+ | `--contract` | — | A contract JSON file ([verification.md](./verification.md)); `--check` entries are appended to it |
215
+ | `--scouts` | the implementer | Comma-separated triage agents, `engine[:model]` each |
216
+ | `--reviewers` | — | Comma-separated reviewers of the finished change |
217
+ | `--max-repairs` | `3` | Attempts the router allows while the checks are red; `0` keeps only the first attempt |
218
+ | `--human-gate` | off | Park before anything is written until `clawo workflow approve` |
219
+ | `--cwd` | current directory | Project directory |
220
+ | `-w, --wait` | off | Follow the run, printing each node transition, then the verdict |
221
+ | `--json` | off | Print `{ runId }`, or with `--wait` the final run record |
222
+
223
+ With `--wait` the exit code is the verdict: `0` when the run completed (verified,
224
+ or unverified because no check was given), `1` when it was refuted, failed or
225
+ cancelled. Unknown engine names are refused before anything starts.
226
+
227
+ ## `clawo fanout`
228
+
229
+ Ask several engines the same thing in parallel, optionally merging the answers.
230
+
231
+ ```bash
232
+ clawo fanout "<task>" [--engines <list>] [--synthesize] [--check "<command>"]...
233
+ [--contract <file>] [--cwd <dir>] [--wait] [--json]
234
+ ```
235
+
236
+ `--engines` (default `claude,codex`) takes `engine[:model]` items; the same
237
+ engine may appear more than once. With `--wait` the run is followed to the end
238
+ and every answer is printed, followed by the synthesis when `--synthesize` was
239
+ given. Checks run after the fan-out, as for `solve`.
240
+
199
241
  ## `clawo workflow`
200
242
 
201
243
  ```bash
@@ -220,8 +262,9 @@ earlier sessions.
220
262
  clawo verify <runId> [--evidence <id>] [--json]
221
263
  ```
222
264
 
223
- Prints the evidence bundle: per-check pass/fail with the failing command and its
224
- output tail, the base and head commits, and the files the run changed (created
265
+ Prints the evidence bundle: per-check pass/fail with the failing command and the
266
+ lines of its output that say why (an assertion message, an error line — the last
267
+ few lines when nothing stands out), the base and head commits, and the files the run changed (created
225
268
  files included).
226
269
 
227
270
  ## `clawo engines`
package/skills/references/multi-engine.md CHANGED
@@ -28,7 +28,7 @@ SessionManager
28
28
 
29
29
  ### Claude Code (`engine: 'claude'`)
30
30
 
31
- Default engine. Long-running subprocess with streaming JSON I/O. Tested with Claude Code CLI **2.1.292**.
31
+ Default engine. Long-running subprocess with streaming JSON I/O. Tested with Claude Code CLI **2.1.295**.
32
32
 
33
33
  - Persistent multi-turn conversations
34
34
  - Real-time streaming (text, tool_use, tool_result, system events)
@@ -62,7 +62,7 @@ await manager.startSession({
62
62
 
63
63
  ### OpenAI Codex (`engine: 'codex'`)
64
64
 
65
- Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested with `codex` CLI **0.160.1**.
65
+ Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested with `codex` CLI **0.162.0**.
66
66
 
67
67
  - Non-interactive execution via `codex exec --sandbox workspace-write --skip-git-repo-check --json`
68
68
  - Real `usage` from the `turn.completed` JSON event (input, output, cached, reasoning tokens). **These are cumulative over the thread, not per turn**, so they replace the session totals rather than being added to them; subtracting consecutive values gives one turn's prompt
@@ -133,7 +133,7 @@ await manager.startSession({
133
133
 
134
134
  Wraps Google's **Antigravity CLI** (`agy`) — the successor to Gemini CLI (consumer
135
135
  Gemini CLI tiers stopped serving 2026-06-18). Each `send()` spawns a new process
136
- in print mode. Tested with `agy` **1.3.1**.
136
+ in print mode. Tested with `agy` **1.3.2**.
137
137
 
138
138
  - One-shot execution per message (no persistent subprocess)
139
139
  - **Structured output and real usage** — `--output-format stream-json` emits an
@@ -218,7 +218,7 @@ await manager.startSession({
218
218
  ### Grok Build (`engine: 'grok'`)
219
219
 
220
220
  Wraps xAI's **Grok Build** CLI. Each `send()` spawns `grok -p <msg> --output-format json`, which
221
- prints a single JSON object and exits. Tested with `grok` **1.0.46**.
221
+ prints a single JSON object and exits. Tested with `grok` **1.0.50**.
222
222
 
223
223
  - **Cost comes from the engine, not from the price table.** The result object carries
224
224
  `total_cost_usd`, and the wrapper writes it straight into the session's spend, so the run ledger
@@ -240,13 +240,21 @@ prints a single JSON object and exits. Tested with `grok` **1.0.46**.
240
240
  `dangerouslySkipPermissions` → `--always-approve`, `customSessionId` → `--session-id`, `forkSession`
241
241
  → `--fork-session`. **grok validates neither tool list**: a name that does not exist is ignored
242
242
  rather than rejected, so a typo in a denylist leaves the tool enabled. Prefer an allowlist.
243
- - **`sandboxMode: 'read-only'` is refused.** A read-only `--tools` allowlist plus
244
- `--permission-mode plan` does not stop a delegated subagent from writing, because the subagent
245
- does not inherit the parent's tool restriction. A read-only grok session therefore throws at start instead of running
246
- writable.
247
- - **On an exhausted free tier, `grok -p` may hang with no output instead of exiting with an error.**
248
- The session's turn timeout is then the only thing that ends the turn. If a grok turn times out with
249
- no output, run `grok -p` by hand to check your quota.
243
+ - **`sandboxMode: 'read-only'` runs inside grok's `--sandbox read-only` profile**, which the OS
244
+ enforces (Seatbelt on macOS, Landlock on Linux) for the whole process tree: the session reads
245
+ anywhere and can write only to `~/.grok/` and the temp directory. Measured on 1.0.50 with
246
+ `bypassPermissions`: a direct write, a shell write, a delegated subagent, a write on a resumed turn
247
+ and a write outside the project all fail with `Operation not permitted`. A tool allowlist was not
248
+ enough — a delegated subagent does not inherit it. Three cases are refused rather than claimed:
249
+ - a project under the temp directory, which the profile leaves writable;
250
+ - a platform other than macOS or Linux;
251
+ - a sandbox grok reports it could not apply. grok itself would carry on unsandboxed; the session
252
+ kills the process on that warning, which grok prints at startup before any model call.
253
+
254
+ Child-process network access is not blocked on macOS (grok enforces that part on Linux only).
255
+
256
+ - **On an exhausted free tier grok answers with an error object** (`{"type":"error","message":...}`),
257
+ and the session reports that message as the turn's error.
250
258
  - Binary: `grok` (set `GROK_BIN` to override). Not `agent`: xAI's installer claims that name too,
251
259
  and so did Cursor's.
252
260
  - Requires Grok Build: see `x.ai/cli`.
package/skills/references/tools.md CHANGED
@@ -8,57 +8,57 @@ All 78 tools are registered as OpenClaw plugin tools and exposed over MCP by `cl
8
8
 
9
9
  Start a persistent coding session with full CLI flag support.
10
10
 
11
- | Parameter | Type | Description |
12
- | ------------------------------------ | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13
- | `name` | string | Session name (auto-generated if omitted) |
14
- | `cwd` | string | Working directory |
15
- | `engine` | `'claude'` \| `'codex'` \| `'codex-app'` \| `'agy'` \| `'grok'` \| `'opencode'` \| `'custom'` | Engine to use (default: `claude`). `agy` wraps Google Antigravity CLI. `grok` wraps xAI Grok Build and reports its own per-turn cost. `opencode` wraps sst/opencode (pass model as `provider/model`). Use `custom` with `customEngine` for any CLI. (`'gemini'` and `'cursor'` are still accepted for existing callers but are legacy — not version-tracked; use `agy` for Google and `grok` in place of Cursor.) |
16
- | `model` | string | Model alias or full name |
17
- | `permissionMode` | string | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`) |
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
- | `allowedTools` | string[] | Tools to auto-approve |
20
- | `disallowedTools` | string[] | Tools to deny |
21
- | `maxTurns` | number | Max agent loop turns |
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. |
23
- | `autoCompactPercent` | number | Compact the conversation before a send once `contextPercent` reaches this value (1–99). Off by default. For long-lived sessions, where cost grows with context size; survives a server restart. A failed compaction does not block the send. |
24
- | `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 |
26
- | `agents` | object | Custom sub-agents JSON |
27
- | `agent` | string | Default agent to use |
28
- | `bare` | boolean | Skip hooks, LSP, auto-memory, CLAUDE.md |
29
- | `worktree` | string \| boolean | Run in git worktree |
30
- | `fallbackModel` | string \| string[] | Fallback model(s) when the primary is overloaded; an array is tried in order |
31
- | `resumeSessionId` | string | Resume existing session by ID |
32
- | `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
- | `mcpConfig` | string \| string[] | MCP server config file(s) |
34
- | `settings` | string | Settings.json path or inline JSON |
35
- | `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
- | `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
- | `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`. |
38
- | `codexProfile` | string | Codex only. Named profile from `~/.codex/config.toml`, passed as `codex exec --profile` |
39
- | `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. |
40
- | `betas` | string \| string[] | Custom beta headers |
41
- | `enableAgentTeams` | boolean | Enable experimental agent teams |
42
- | `enableAutoMode` | boolean | Enable auto permission mode |
43
- | `customEngine` | object | Custom engine config (required when `engine='custom'`). See [Multi-Engine: Custom Engine](./multi-engine.md#custom-engine-engine-custom). |
44
- | `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 |
45
- | `includeHookEvents` | boolean | Stream hook lifecycle events (PreToolUse/PostToolUse) as `system` events |
46
- | `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 |
47
- | `chrome` | boolean | Let the session use the user's Chrome through the Claude in Chrome extension, acting with that browser's sign-ins (Claude engine, `--chrome`). Off by default. Needs Chrome running with the extension and a claude.ai login; survives a server restart |
48
- | `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. |
49
- | `excludeDynamicSystemPromptSections` | boolean | Move cwd/env/git context from system prompt to user message for better prompt cache hits; auto-enabled with `bare: true` |
50
- | `enablePromptCaching1H` | boolean | Enable 1-hour prompt cache TTL (vs default 5-min); auto-enabled with `bare: true` |
51
- | `debug` | string \| string[] | Debug categories to enable (e.g. `"api,mcp"` or `["api", "mcp"]`) |
52
- | `debugFile` | string | File path to write debug output to |
53
- | `fromPr` | string | Resume a session linked to a GitHub PR number or URL |
54
- | `channels` | string \| string[] | MCP channel subscription spec (research preview) |
55
- | `dangerouslyLoadDevelopmentChannels` | string \| string[] | Development MCP channel subscriptions (research preview) |
56
- | `forkSubagent` | boolean | Fork subagent for non-interactive sessions (sets `CLAUDE_CODE_FORK_SUBAGENT=1`) |
57
- | `enableToolSearch` | boolean | Enable Vertex AI tool search (sets `ENABLE_TOOL_SEARCH=1`) |
58
- | `otelLogUserPrompts` | boolean | OpenTelemetry: log user prompts (sets `OTEL_LOG_USER_PROMPTS=1`) |
59
- | `otelLogRawApiBodies` | boolean | OpenTelemetry: log raw API request/response bodies (sets `OTEL_LOG_RAW_API_BODIES=1`); debug only |
60
- | `bedrockServiceTier` | `'default'` \| `'flex'` \| `'priority'` | AWS Bedrock service tier (sets `ANTHROPIC_BEDROCK_SERVICE_TIER`); only effective when routing through Bedrock |
61
- | `effort` | `'low'` \| `'medium'` \| `'high'` \| `'xhigh'` \| `'max'` \| `'ultra'` \| `'auto'` | Reasoning effort level. Engines do not share one ladder: Claude Code takes up to `max`, Codex adds `ultra`, Grok stops at `xhigh`, Antigravity at `high`, and OpenCode forwards the level to its provider unvalidated. A level above an engine's ceiling clamps rather than being dropped. `high` and above trigger the `ultrathink` prefix on Claude user messages. |
11
+ | Parameter | Type | Description |
12
+ | ------------------------------------ | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
13
+ | `name` | string | Session name (auto-generated if omitted) |
14
+ | `cwd` | string | Working directory |
15
+ | `engine` | `'claude'` \| `'codex'` \| `'codex-app'` \| `'agy'` \| `'grok'` \| `'opencode'` \| `'custom'` | Engine to use (default: `claude`). `agy` wraps Google Antigravity CLI. `grok` wraps xAI Grok Build and reports its own per-turn cost. `opencode` wraps sst/opencode (pass model as `provider/model`). Use `custom` with `customEngine` for any CLI. (`'gemini'` and `'cursor'` are still accepted for existing callers but are legacy — not version-tracked; use `agy` for Google and `grok` in place of Cursor.) |
16
+ | `model` | string | Model alias or full name |
17
+ | `permissionMode` | string | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`) |
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 → its OS-enforced `--sandbox read-only` profile (refused for a project under the temp directory, on platforms without Seatbelt or Landlock, and when grok cannot apply it). A `custom` engine must map it via `permissionModes`, or the session refuses to start. Persisted across session resume. |
19
+ | `allowedTools` | string[] | Tools to auto-approve |
20
+ | `disallowedTools` | string[] | Tools to deny |
21
+ | `maxTurns` | number | Max agent loop turns |
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. |
23
+ | `autoCompactPercent` | number | Compact the conversation before a send once `contextPercent` reaches this value (1–99). Off by default. For long-lived sessions, where cost grows with context size; survives a server restart. A failed compaction does not block the send. |
24
+ | `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 |
26
+ | `agents` | object | Custom sub-agents JSON |
27
+ | `agent` | string | Default agent to use |
28
+ | `bare` | boolean | Skip hooks, LSP, auto-memory, CLAUDE.md |
29
+ | `worktree` | string \| boolean | Run in git worktree |
30
+ | `fallbackModel` | string \| string[] | Fallback model(s) when the primary is overloaded; an array is tried in order |
31
+ | `resumeSessionId` | string | Resume existing session by ID |
32
+ | `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
+ | `mcpConfig` | string \| string[] | MCP server config file(s) |
34
+ | `settings` | string | Settings.json path or inline JSON |
35
+ | `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
+ | `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
+ | `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`. |
38
+ | `codexProfile` | string | Codex only. Named profile from `~/.codex/config.toml`, passed as `codex exec --profile` |
39
+ | `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. |
40
+ | `betas` | string \| string[] | Custom beta headers |
41
+ | `enableAgentTeams` | boolean | Enable experimental agent teams |
42
+ | `enableAutoMode` | boolean | Enable auto permission mode |
43
+ | `customEngine` | object | Custom engine config (required when `engine='custom'`). See [Multi-Engine: Custom Engine](./multi-engine.md#custom-engine-engine-custom). |
44
+ | `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 |
45
+ | `includeHookEvents` | boolean | Stream hook lifecycle events (PreToolUse/PostToolUse) as `system` events |
46
+ | `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 |
47
+ | `chrome` | boolean | Let the session use the user's Chrome through the Claude in Chrome extension, acting with that browser's sign-ins (Claude engine, `--chrome`). Off by default. Needs Chrome running with the extension and a claude.ai login; survives a server restart |
48
+ | `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. |
49
+ | `excludeDynamicSystemPromptSections` | boolean | Move cwd/env/git context from system prompt to user message for better prompt cache hits; auto-enabled with `bare: true` |
50
+ | `enablePromptCaching1H` | boolean | Enable 1-hour prompt cache TTL (vs default 5-min); auto-enabled with `bare: true` |
51
+ | `debug` | string \| string[] | Debug categories to enable (e.g. `"api,mcp"` or `["api", "mcp"]`) |
52
+ | `debugFile` | string | File path to write debug output to |
53
+ | `fromPr` | string | Resume a session linked to a GitHub PR number or URL |
54
+ | `channels` | string \| string[] | MCP channel subscription spec (research preview) |
55
+ | `dangerouslyLoadDevelopmentChannels` | string \| string[] | Development MCP channel subscriptions (research preview) |
56
+ | `forkSubagent` | boolean | Fork subagent for non-interactive sessions (sets `CLAUDE_CODE_FORK_SUBAGENT=1`) |
57
+ | `enableToolSearch` | boolean | Enable Vertex AI tool search (sets `ENABLE_TOOL_SEARCH=1`) |
58
+ | `otelLogUserPrompts` | boolean | OpenTelemetry: log user prompts (sets `OTEL_LOG_USER_PROMPTS=1`) |
59
+ | `otelLogRawApiBodies` | boolean | OpenTelemetry: log raw API request/response bodies (sets `OTEL_LOG_RAW_API_BODIES=1`); debug only |
60
+ | `bedrockServiceTier` | `'default'` \| `'flex'` \| `'priority'` | AWS Bedrock service tier (sets `ANTHROPIC_BEDROCK_SERVICE_TIER`); only effective when routing through Bedrock |
61
+ | `effort` | `'low'` \| `'medium'` \| `'high'` \| `'xhigh'` \| `'max'` \| `'ultra'` \| `'auto'` | Reasoning effort level. Engines do not share one ladder: Claude Code takes up to `max`, Codex adds `ultra`, Grok stops at `xhigh`, Antigravity at `high`, and OpenCode forwards the level to its provider unvalidated. A level above an engine's ceiling clamps rather than being dropped. `high` and above trigger the `ultrathink` prefix on Claude user messages. |
62
62
 
63
63
  ### `session_send`
64
64
 
@@ -555,14 +555,14 @@ Get status and plan text when completed.
555
555
 
556
556
  Start 1–20 reviewer agents that review the code in parallel, each from a different angle. Runs in background.
557
557
 
558
- | Parameter | Type | Required | Description |
559
- | -------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
560
- | `cwd` | string | yes | Project directory |
561
- | `agentCount` | number | | Agents (1-20, default 5) |
562
- | `maxDurationMinutes` | number | | Duration (5-25 min, default 10) |
563
- | `model` | string | | Model for reviewers |
564
- | `focus` | string | | Review focus area |
565
- | `engines` | string[] | | Engines to spread reviewers across (default `["claude"]`). Every reviewer runs read-only, so `grok` and `custom` are not allowed |
558
+ | Parameter | Type | Required | Description |
559
+ | -------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
560
+ | `cwd` | string | yes | Project directory |
561
+ | `agentCount` | number | | Agents (1-20, default 5) |
562
+ | `maxDurationMinutes` | number | | Duration (5-25 min, default 10) |
563
+ | `model` | string | | Model for reviewers |
564
+ | `focus` | string | | Review focus area |
565
+ | `engines` | string[] | | Engines to spread reviewers across (default `["claude"]`). Every reviewer runs read-only, so `custom` is not allowed |
566
566
 
567
567
  ### `ultrareview_status`
568
568
 
@@ -822,18 +822,19 @@ Full semantics in [`workflow.md`](./workflow.md) and
822
822
  Start a durable run. Every state transition is checkpointed to disk, so a run
823
823
  survives a process restart and can be resumed.
824
824
 
825
- | Param | Type | Notes |
826
- | ------------ | -------------------------------- | -------------------------------------------------------------------- |
827
- | `spec` | object | `WorkflowSpec`: `{ name, nodes[], cwd?, contract?, maxNodeVisits? }` |
828
- | `template` | `solve` \| `council` \| `fanout` | Build a built-in instead of supplying `spec` |
829
- | `task` | string | Required with `template` |
830
- | `agents` | array | `{ name, engine?, model?, effort?, persona? }` |
831
- | `reviewers` | array | `solve` only — same agent binding for final reviewers |
832
- | `humanGate` | boolean | `solve` only — park for approval before anything is written |
833
- | `maxRepairs` | number | `solve` only, default 3 |
834
- | `cwd` | string | Working directory |
835
- | `runId` | string | Explicit id |
836
- | `contract` | object | Acceptance contract — see below |
825
+ | Param | Type | Notes |
826
+ | ------------- | -------------------------------- | ------------------------------------------------------------------------- |
827
+ | `spec` | object | `WorkflowSpec`: `{ name, nodes[], cwd?, contract?, maxNodeVisits? }` |
828
+ | `template` | `solve` \| `council` \| `fanout` | Build a built-in instead of supplying `spec` |
829
+ | `task` | string | Required with `template` |
830
+ | `agents` | array | `{ name, engine?, model?, effort?, persona? }` |
831
+ | `reviewers` | array | `solve` only — same agent binding for final reviewers |
832
+ | `implementer` | object | `solve` only — `{ engine?, model? }` for the agent that writes the change |
833
+ | `humanGate` | boolean | `solve` only — park for approval before anything is written |
834
+ | `maxRepairs` | number | `solve` only, default 3 |
835
+ | `cwd` | string | Working directory |
836
+ | `runId` | string | Explicit id |
837
+ | `contract` | object | Acceptance contract — see below |
837
838
 
838
839
  Returns `{ runId, workflow, state, nodes }` and runs in the background.
839
840
 
package/skills/references/ultra.md CHANGED
@@ -122,6 +122,6 @@ if (status?.status === 'completed') {
122
122
  | `maxDurationMinutes` | 10 | 5-25 | Per-agent timeout |
123
123
  | `model` | session default | — | Model for all reviewers |
124
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
+ | `engines` | `['claude']` | — | Engines assigned to reviewers round-robin. Not `custom`, which has no config to start a reviewer from |
126
126
 
127
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.
package/skills/references/workflow.md CHANGED
@@ -240,6 +240,11 @@ with `visits_lt`.
240
240
  }
241
241
  ```
242
242
 
243
+ When the router sends control back to `implement`, the agent is told what the
244
+ last verification found: each failing required check and the lines of its output
245
+ that say why, framed as data, ahead of the node's own prompt. This applies to any
246
+ `agent` node re-entered after a failed verifier, not only to `solve`.
247
+
243
248
  The run leaves `completed` only if the last `verify` was green. There is no
244
249
  second verifier at the end on purpose: re-running a contract that shells out to a
245
250
  test suite would double the most expensive part of the run to learn nothing new.