@enderfga/claw-orchestrator 4.1.2 → 4.4.0

package/skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: claw-orchestrator
-description: Manage persistent coding sessions across Claude Code, Codex, Gemini, Cursor, 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, or exposing the orchestrator's 55 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose. 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", "deep paper review", "auto research", "switch model", "multi-agent", "coding session", "session inbox", "cursor agent", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol".
+description: Manage persistent coding sessions across Claude Code, Codex, Gemini, Cursor, 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, or exposing the orchestrator's 65 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose. 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", "deep paper review", "auto research", "switch model", "multi-agent", "coding session", "session inbox", "cursor agent", "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".
 metadata:
   {
     "openclaw":
@@ -43,7 +43,7 @@ metadata:
 
 # Claw Orchestrator Skill
 
-Claw Orchestrator — persistent multi-engine coding session manager for claw-style agent systems. Runs as a standalone CLI/server, with first-class OpenClaw plugin support. Wraps Claude Code, Codex, Gemini, Cursor Agent, OpenCode, and custom CLIs into headless agentic engines with 55 tools.
+Claw Orchestrator — persistent multi-engine coding session manager for claw-style agent systems. Runs as a standalone CLI/server, with first-class OpenClaw plugin support. Wraps Claude Code, Codex, Gemini, Cursor Agent, OpenCode, and custom CLIs into headless agentic engines with 65 tools.
 
 ## Engine Quick Reference
 
@@ -184,7 +184,7 @@ Asymmetric ratchet reviewer runs in a sandbox tmpdir (no source access), only wr
 
 For details and worked examples (Karpathy-style scalar improvement + paper-review style gates): see [references/autoloop.md](references/autoloop.md).
 
-## 27 Tools Overview
+## Tools Overview
 
 | Category | Tools |
 |----------|-------|
@@ -192,9 +192,15 @@ For details and worked examples (Karpathy-style scalar improvement + paper-revie
 | Session Ops | `coding_session_status`, `session_grep`, `session_compact`, `session_update_tools`, `session_switch_model` |
 | Inbox | `session_send_to`, `session_inbox`, `session_deliver_inbox` |
 | Teams | `coding_agents_list`, `team_list`, `team_send` |
+| Codex | `codex_resume`, `codex_review`, `codex_goal_*`, `codex_interrupt`, `codex_steer`, `codex_fork`, `codex_rollback`, `codex_models`, `codex_threads` |
+| Claude CLI | `claude_goal_*`, `claude_agents_list`, `plugin_details` |
+| Fan-out | `fanout_start`, `fanout_status`, `fanout_abort` |
 | Council | `council_start`, `council_status`, `council_abort`, `council_inject`, `council_review`, `council_accept`, `council_reject` |
 | Ultra | `ultraplan_start`, `ultraplan_status`, `ultrareview_start`, `ultrareview_status` |
 
+`ultracode` (Claude dynamic workflows) is a `session_start` option, not a separate tool: set
+`ultracode: true` to have Claude orchestrate a JS workflow and fan out to subagents per task.
+
 For full parameter reference: see [references/tools.md](references/tools.md)
 
 ## Authentication Prerequisites

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

@@ -2,11 +2,13 @@
 
 This document tracks which Claude Code CLI version Claw Orchestrator is currently synced to, and which features have been integrated.
 
-## Currently tracked: **Claude Code CLI 2.1.161** (as of 2026-06-03, plugin v4.1.2)
+## Currently tracked: **Claude Code CLI 2.1.178** (as of 2026-06-16, plugin v4.3.0)
 
 ## Sync history
 
 | Plugin Version | Claude CLI Version | Date | Notable integrations |
+| v4.3.0 | 2.1.178 | 2026-06-16 | **Parity batch 2 + legacy-subsystem upgrades (local-only, no cloud).** Claude `--fallback-model` array form (CSV, verified via `claude --help`). Codex-app `codex_threads` (`thread/list`) and `thread/resume` on start when `resumeSessionId` is set (param shapes from `generate-json-schema`). Council agents gain per-agent `effort`/`ultracode`. `ultrareview` re-implemented on the new cross-engine `fanout` primitive (opt-in `engines`, default claude-only). Consensus parsing exposes match source for observability. Dropped on purpose: `codex cloud exec`/best-of-N (cloud/managed — loses local control), `--bg` (we own the subprocess), `--output-last-message` (we already capture final text), ultraplan `ultracode` (violates its plan-only contract). Autoloop mid-turn steer deferred — the loop is strictly sequential (Coder fully completes before the Reviewer runs), so steer would always fall back to a fresh turn; a real version needs concurrent review. |
+| v4.2.0 | 2.1.178 | 2026-06-16 | **`ultracode` integration + binary-verified parity pass.** Added the `ultracode` option on `session_start` — Claude Code's dynamic-workflow mode, wired as the `ultracode: true` settings key merged into `--settings` (confirmed by spawning: it activates `workflow_agent` events in headless stream-json; `--effort ultracode` is rejected by the CLI). Added `claude_agents_list` (wraps `claude agents --json`). Verified against the binary that `claude continue/respawn/stop/logs` do **not** exist as headless subcommands (session continuation stays on `--resume`). Codex 0.137 side: app-server RPC tools `codex_interrupt`/`codex_steer`/`codex_fork`/`codex_rollback`/`codex_models`, `codex exec` reasoning-effort (`-c model_reasoning_effort`) + `--profile` passthrough, and a cross-engine `fanout_*` primitive. Bumped tested versions Claude 2.1.178 / Codex 0.137.0. |
 | v4.1.2 | 2.1.161 | 2026-06-03 | **Model registry sync, not a CLI-flag integration.** Registered Opus 4.8 (`claude-opus-4-8`, now the `opus` alias) and 4.7 in `models.ts` — 2.1.154 shipped Opus 4.8 as the new default and our `opus` alias was still pinned to 4.6, mis-attributing cost. Effort ladder `low/medium/high/xhigh/max` was already supported (`index.ts`/`types.ts`). The 2.1.151–2.1.161 range (note: .151/.155 skipped) is otherwise TUI/reliability/telemetry; two fixes silently benefit our spawn path with no code change — 2.1.153 (stream-json stdin-close hang) and 2.1.161 (`-p` stdout corruption from background subagents). **Watch-out documented, not fixed:** 2.1.160 adds permission prompts under `acceptEdits` (our default) for build-tool config files (`.npmrc`/`.bazelrc`/`.pre-commit-config.yaml`/`.devcontainer/` etc.) and shell-startup files — headless flows touching these should set `dangerouslySkipPermissions` or a bypass permission mode. Codex unchanged (0.133.0); separately fixed Codex `turn.failed`/`error` events being swallowed. |
 | v4.1.1 | 2.1.150 | 2026-05-24 | **No Claude wrapper change** — 2.1.141–2.1.150 are almost entirely TUI / agent-view / security / visual; 2.1.150 itself is "internal infrastructure only". The one scripting-adjacent addition, `claude agents --json` (2.1.145), lists *CLI-managed* sessions and is not used by our own session manager. This release's real engine work was on Codex/Gemini: Codex `--output-schema` wired into `jsonSchema` (Codex 0.132+), Gemini `--skip-trust` for the 0.43 trusted-folders gate. Bumped tested versions Claude 2.1.150 / Codex 0.133.0 / Gemini 0.43.0. |
 |---|---|---|---|

package/skills/references/multi-engine.md

@@ -15,9 +15,9 @@ SessionManager
 ├── engine: 'gemini'    → PersistentGeminiSession
 │   └── Wraps: gemini -p --output-format stream-json (per-message spawning)
 ├── engine: 'cursor'    → PersistentCursorSession
-│   └── Wraps: agent -p --force --output-format stream-json (per-message spawning)
+│   └── Wraps: agent -p --force --trust --output-format stream-json (per-message spawning)
 ├── engine: 'opencode'  → PersistentOpencodeSession
-│   └── Wraps: opencode run --format json --dangerously-skip-permissions (per-message spawning)
+│   └── Wraps: opencode run --format json (per-message spawning)
 └── engine: 'custom'    → PersistentCustomSession
     └── Wraps: any CLI via user-provided CustomEngineConfig
 ```
@@ -26,7 +26,7 @@ SessionManager
 
 ### Claude Code (`engine: 'claude'`)
 
-Default engine. Long-running subprocess with streaming JSON I/O. Tested with Claude Code CLI **2.1.140**.
+Default engine. Long-running subprocess with streaming JSON I/O. Tested with Claude Code CLI **2.1.178**.
 
 - Persistent multi-turn conversations
 - Real-time streaming (text, tool_use, tool_result, system events)
@@ -52,10 +52,13 @@ await manager.startSession({
 
 ### OpenAI Codex (`engine: 'codex'`)
 
-Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested with `codex` CLI **0.128.0**.
+Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested with `codex` CLI **0.137.0**.
 
 - 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)
+- `item.completed` parsing distinguishes `reasoning` / `todo_list` (logged, not counted) from real tool items (`command_execution`, `file_change`, `mcp_tool_call`, `web_search`, which increment `toolCalls`; a non-zero `command_execution.exit_code` increments `toolErrors`)
+- Reasoning effort: the engine-agnostic `effort` maps to `-c model_reasoning_effort=<level>` (`max`→`xhigh`; `auto`/`ultracode` omitted)
+- `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)
 - Working directory passed via `-C` flag
@@ -82,7 +85,9 @@ Wraps `codex app-server --listen stdio:// --enable goals` as a long-running JSON
 - Real-time streaming via `item/agentMessage/delta` notifications
 - Cumulative token tracking from `thread/tokenUsage/updated` notifications
 - Goal lifecycle observation via `thread/goal/updated` and `thread/goal/cleared` notifications
-- Goal control via the `codex_goal_*` tools (which internally send the `/goal` slash command as user text — see [tools.md](./tools.md#codex-7))
+- Goal control via the `codex_goal_*` tools (which internally send the `/goal` slash command as user text — see [tools.md](./tools.md#codex-13))
+- v2 RPC tools (Codex 0.137): `codex_interrupt` (`turn/interrupt`), `codex_steer` (`turn/steer`), `codex_fork` (`thread/fork`), `codex_rollback` (`thread/rollback`), `codex_models` (`model/list`), `codex_threads` (`thread/list`). A `turn/completed` with `status: 'failed'` rejects the turn and increments `toolErrors`.
+- Thread resume: starting with `resumeSessionId` loads the existing thread via `thread/resume` instead of `thread/start`.
 
 > **Feature-flag risk.** The `goals` feature is marked "under development" in Codex 0.128.0 and has known bugs (e.g. issue #20591). The session class always passes `--enable goals` so it works the moment upstream stabilizes the feature, but during the transition period some goal commands may fail or be silently dropped on the server side. The wrapper layer is unaffected.
 

package/skills/references/sessions.md

@@ -75,6 +75,24 @@ await manager.startSession({
 });
 ```
 
+> `claude continue/respawn/stop/logs` are not headless subcommands — session continuation is via `resumeSessionId`/`forkSession`. Use the `claude_agents_list` tool (`claude agents --json`) to enumerate Claude Code background agent sessions.
+
+### ultracode (Claude dynamic workflows)
+
+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` (not a `--effort` value — the CLI rejects `--effort ultracode`):
+
+```typescript
+await manager.startSession({ name: 'big-task', engine: 'claude', ultracode: true });
+```
+
+### Codex app-server turn control (`engine: 'codex-app'`)
+
+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).
+
+### Fan-out (cross-engine parallel)
+
+`fanout_start` runs one task across N engine/model agents in parallel and collects their answers (optional synthesis) — the best-of-N / diverse-perspective primitive. Unlike Council, no rounds/votes/worktrees; use Council for isolated parallel edits. See [tools.md](./tools.md#fan-out-3).
+
 ## Runtime Operations
 
 ### Model Switching

package/skills/references/tools.md

@@ -31,6 +31,7 @@ Start a persistent coding session with full CLI flag support.
 | `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. |
 | `mcpConfig` | string \| string[] | MCP server config file(s) |
 | `settings` | string | Settings.json path or inline JSON |
+| `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`), **not** a `--effort` value (the CLI rejects `--effort ultracode`). |
 | `noSessionPersistence` | boolean | Do not save session to disk |
 | `betas` | string \| string[] | Custom beta headers |
 | `enableAgentTeams` | boolean | Enable experimental agent teams |
@@ -210,7 +211,7 @@ Returns the regular turn result; goal info is in the assistant's reply text.
 
 ---
 
-## Codex (7)
+## Codex (13)
 
 Tools targeting OpenAI's `codex` CLI. The `codex_resume` and `codex_review` tools are one-shot wrappers and work without a managed session. The `codex_goal_*` tools require a session started with `engine: "codex-app"` (see [multi-engine.md](./multi-engine.md)) — the legacy `engine: "codex"` (which uses `codex exec`) has no slash-command surface.
 
@@ -283,6 +284,67 @@ Returns `{ ok, text, goal }`.
 
 > **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.
 
+### `codex_interrupt` / `codex_steer` / `codex_fork` / `codex_rollback` / `codex_models`
+
+Codex app-server v2 RPCs (require `engine: "codex-app"`). Method names + param shapes verified against `codex app-server generate-json-schema` (Codex 0.137).
+
+| Tool | RPC | Params | Returns |
+|------|-----|--------|---------|
+| `codex_interrupt` | `turn/interrupt` | `name` | `{ ok, interrupted }` — cancels the in-flight turn (no-op if idle) |
+| `codex_steer` | `turn/steer` | `name`, `message` | `{ ok, steered, turnId? , text? }` — adds input to the in-flight turn; falls back to a normal turn when idle |
+| `codex_fork` | `thread/fork` | `name` | `{ ok, threadId }` — branches the thread; returns the forked id |
+| `codex_rollback` | `thread/rollback` | `name`, `numTurns` | `{ ok, numTurns }` — drops the last N turns |
+| `codex_models` | `model/list` | `name` | `{ ok, models }` — incl. each model's `supportedReasoningEfforts` |
+| `codex_threads` | `thread/list` | `name`, `searchTerm?`, `cwd?`, `archived?`, `cursor?`, `limit?` | `{ ok, data, nextCursor }` — list threads with filters + pagination |
+
+To **resume** a codex-app thread, start a session with `engine: "codex-app"` and
+`resumeSessionId: "<threadId>"` — it loads the existing thread via `thread/resume` instead of
+opening a fresh one.
+
+---
+
+## Claude CLI (1)
+
+### `claude_agents_list`
+
+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.)
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `all` | boolean | Include completed sessions (`--all`). |
+| `cwd` | string | Scope to sessions started under this directory (`--cwd`). |
+
+Returns `{ ok, agents }`.
+
+---
+
+## Fan-out (3)
+
+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.
+
+### `fanout_start`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task` | string | yes | Shared prompt sent to every agent (unless an agent overrides via its own `prompt`). |
+| `projectDir` | string | yes | Working directory all agents run in. |
+| `agents` | array | yes | Specs: `{ name, engine?, model?, prompt?, baseUrl?, permissionMode?, customEngine? }`. |
+| `synthesize` | boolean | | Run a final synthesis pass over the successful results (needs ≥2). |
+| `synthesisModel` / `synthesisEngine` | string | | Model/engine for the synthesis pass (default engine `claude`). |
+| `agentTimeoutMs` | number | | Per-agent timeout (default 600000). |
+| `maxTurnsPerAgent` | number | | Max agent loop turns (default 30). |
+| `maxBudgetUsd` | number | | Per-agent spend cap. |
+
+Runs in the background; returns `{ ok, id, status, ... }`. Poll with `fanout_status`.
+
+### `fanout_status`
+
+Poll a fan-out by `id`. Returns `{ ok, id, status, results: [{ agent, engine, model, ok, output, error?, durationMs }], synthesis? }`.
+
+### `fanout_abort`
+
+Abort a running fan-out by `id` (already-started agents finish; synthesis is skipped).
+
 ---
 
 ## Agent Teams (3)