@enderfga/claw-orchestrator 7.1.1 → 7.3.0

package/dist/src/types.d.ts

@@ -467,11 +467,31 @@ export interface SessionInfo {
     /** True once `costUsd` reached `budgetUsd` — further turns are refused. */
     budgetExhausted?: boolean;
 }
+/** A tool call the engine refused to run during a turn. */
+export interface PermissionDenial {
+    toolName: string;
+    toolUseId?: string;
+    /** The arguments the model passed, as the engine reported them. */
+    input?: unknown;
+}
 export interface SendResult {
     output: string;
     sessionId?: string;
     error?: string;
     events: StreamEvent[];
+    /**
+     * Tool calls the engine blocked during this turn. Present only when there was
+     * at least one.
+     *
+     * Read this alongside `error`, not instead of it: a turn whose every tool call
+     * was denied still ends `subtype: 'success'` with `is_error: false`, so it
+     * counts in `turnsSucceeded` and sets no `error`. Measured against Claude Code
+     * 2.1.269 with `--permission-prompts none` (what a session gets when no prompt
+     * tool is configured): asked to write a file, the turn "succeeded", the Bash
+     * call appeared here, and no file was written. A caller that treats a
+     * successful turn as work done needs this field to know otherwise.
+     */
+    permissionDenials?: PermissionDenial[];
 }
 export interface GrepMatch {
     time: string;

package/openclaw.plugin.json

@@ -111,6 +111,7 @@
     "tools": [
       "session_start",
       "session_send",
+      "session_handoff",
       "session_stop",
       "session_list",
       "sessions_overview",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enderfga/claw-orchestrator",
-  "version": "7.1.1",
+  "version": "7.3.0",
   "description": "Claw Orchestrator \u2014 run Claude Code, Codex, Gemini, Cursor Agent, OpenCode and custom coding CLIs as one unified runtime. Drop into Hermes Agent, Claude Desktop, Cursor, Cline, Continue, Zed, Windsurf, Goose or any Model Context Protocol (MCP) host, install as an OpenClaw plugin, or run standalone. Persistent sessions, multi-agent council, ultraplan, ultrareview, autoloop, tool orchestration.",
   "type": "module",
   "main": "./dist/src/index.js",

package/skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: claw-orchestrator
-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 77 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", "deep paper review", "auto research", "switch model", "multi-agent", "coding session", "session inbox", "grok", "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", "how much did it cost", "token usage", "spend cap", "budget limit", "maxBudgetUsd", "workflow", "durable workflow", "resume a run", "verify", "verification", "acceptance contract", "evidence", "evidence bundle", "did the tests actually pass", "prove it works", "human gate", "repair loop", "clawo workflow", "clawo verify".
+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", "deep paper review", "auto research", "switch model", "hand off", "handoff", "switch engine", "continue on codex", "continue on claude", "move this session to another engine", "multi-agent", "coding session", "session inbox", "grok", "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", "how much did it cost", "token usage", "spend cap", "budget limit", "maxBudgetUsd", "workflow", "durable workflow", "resume a run", "verify", "verification", "acceptance contract", "evidence", "evidence bundle", "did the tests actually pass", "prove it works", "human gate", "repair loop", "clawo workflow", "clawo verify".
 metadata:
   {
     'openclaw':
@@ -36,7 +36,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, Antigravity, Grok Build, OpenCode, and custom CLIs into headless agentic engines with 77 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, Antigravity, Grok Build, OpenCode, and custom CLIs into headless agentic engines with 78 tools.
 
 ## Engine Quick Reference
 
@@ -188,7 +188,7 @@ For the full control protocol, registry/resume behavior, and ledger layout, see
 
 | Category          | Tools                                                                                                                                             |
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Session Lifecycle | `session_start`, `session_send`, `session_stop`, `session_list`, `sessions_overview`                                                              |
+| Session Lifecycle | `session_start`, `session_send`, `session_handoff`, `session_stop`, `session_list`, `sessions_overview`                                         |
 | 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`                                                                                                    |

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

@@ -2,11 +2,12 @@
 
 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.260** (as of 2026-09-04, plugin v7.1.0)
+## Currently tracked: **Claude Code CLI 2.1.269** (as of 2026-09-13, plugin v7.2.0)
 
 ## Sync history
 
 | Plugin Version | Claude CLI Version | Date | Notable integrations |
+| v7.2.0 | 2.1.269 | 2026-09-13 | **Nine Claude Code releases with no new flag in `--help` — the change that mattered was in the result event.** CC 2.1.260→2.1.269, Codex 0.153.2→0.154.0, agy 1.1.25→1.2.2, grok 1.0.13→1.0.30, OpenCode 1.18.27→1.18.30; every live turn passed through the real wrapper, registry 25 models / 0 drift. The flag diff was empty for every engine but Codex, so the Claude changelog was read for what help cannot show. 2.1.269 made stream-json report *all* refused tool calls in the result event's `permission_denials`; measured with `--permission-prompts none`, a turn asked to write a file ended `subtype: success`, `is_error: false`, the Bash call listed as denied and no file on disk. `sendMessage` dropped that event, so every caller saw a clean success — it is now surfaced as `SendResult.permissionDenials`. agy 1.2.2 has the same shape: in `--mode plan` a refused `RunCommand` still produced `status: SUCCESS` and a non-empty reply, the refusal visible only as a `soft-denying tool confirmation` line in its log. Codex 0.154.0's `--worktree` (behind `--enable worktrees`) measured and deliberately not wired: edits land in `~/.codex/worktrees/<hash>/<repo>` on a detached HEAD, never in the session cwd, so contracts and evidence would verify an untouched tree. Also in 2.1.261–2.1.269 and needing nothing here: `-p --resume` no longer inserts a spurious "Continue" turn, non-interactive sessions no longer reset cwd per message, a mid-turn model switch no longer loses the reply; `--append-subagent-system-prompt-file` exists but is hidden from help and has no counterpart option in this wrapper. |
 | v7.1.0 | 2.1.260 | 2026-09-04 | **Weekly sweep: five engines, zero regressions — the finding was in our own registry, not in a wrapper.** CC 2.1.259→2.1.260, Codex 0.153.0→0.153.2; agy 1.1.25, grok 1.0.13, OpenCode 1.18.27 unchanged. Grok's live turn passed for the first time since its free tier ran out — last week's pin was carried unverified, because an exhausted quota hangs silently rather than erroring. Two registry corrections: all three GPT-5.6 tiers had been repriced by OpenAI after launch while this repo kept the launch rates (Luna over-reported 5x), and `gpt-6-astra` needed registering (1,050,000 window, 10/1/50) or it would have fallen back to Sonnet pricing and a 200K window. Astra is absent from Codex 0.153.0 and present in 0.153.2 — baselining on the installed binary instead of upstream would have hidden it another week, which is the concrete case for that rule. The guard test for bare `gpt-5.6` had pinned launch literals and so failed to notice the repricing; it now asserts equality with `gpt-5.6-sol`, the invariant that actually holds. Still unregistered on purpose: `gpt-5.6-pro` (in the binary, no docs/pricing) and `gpt-5.6-cyber` (documented, not selectable by any engine here). |
 | v6.5.0 | 2.1.259 | 2026-09-03 | **First sweep run by script, not by hand — and it caught what by-hand missed.** CC 2.1.258→2.1.259, Codex 0.152.1→0.153.0, agy 1.1.22→1.1.25, OpenCode 1.18.26→1.18.27, grok unverifiable (silent hang on a spent free tier; pin stays 1.0.13). `scripts/sweep.ts` measures versions/pins/upstream, the wrapper's flags against each binary's `--help`, one live turn per engine *through the real wrapper class*, and the ACP/MCP handshakes; `scripts/sweep-workflow.json` wraps it as verifier→router→draft-agent→human-gate. CC delta: `--permission-prompts none` (2.1.259) now passed whenever no prompt tool is configured — a prompt nobody can answer is denied instead of hanging to the turn timeout. agy delta: 1.1.25 dropped `gemini-3.5-flash` (status: ERROR), which was this wrapper's default — every model-less Antigravity session was failing; default and `agy-flash` alias moved to 3.8 (registered, $0.75/$3.75 current rate), verified live. The by-hand sweep and the script's first version both exercised agy with a minimal argv and no `--model`, so both passed on agy's own default and never saw it; the live turn now goes through the wrapper. Two script lessons: help-text diffing flagged four still-accepted Claude flags as removed (advisory now, not a verdict), and `execFile` left a dangling stdin that timed out every one-shot engine (stdin is closed now, as the opencode wrapper always did). |
 | v6.2.1 | 2.1.258 | 2026-09-02 | **Fable 5.1 registry sync.** CC 2.1.251→2.1.258 in two days, Codex 0.151.0→0.152.1, OpenCode 1.18.25→1.18.26 (both surface-identical, both re-exercised); exactly one item in the delta is AI-facing. `claude-fable-5-1` is the new default Fable model, and the CLI's own `fable` alias resolves to it — read back from `modelUsage.canonicalModel` on a real turn against 2.1.258, not taken from the release note. Registered with `claude-mythos-5-1`, and the `fable` alias moved off 5, the same alias drift that hit Opus 5 and Sonnet 5 in earlier generations. The subtle part is the cache-read rate: 5.1 reads cache at **0.025x base input** ($0.25/Mtok against $10), where every other Claude model is 0.1x — copying Fable 5's $1 or deriving from the input rate over-reports it 4x. Cache *writes* keep the usual 1.25x/2x, so only the read is special. Everything else in the range is TUI/settings/auto-mode/gateway and was dropped: `timeFormat`/`timeZone`, `/effort s`, `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`, `permissions.blockReadsOutsideWorkingDirectories`, gateway model discovery, the auto-mode Containment Escape rule. |

package/skills/references/multi-engine.md

@@ -76,6 +76,12 @@ Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested wi
 - Reasoning effort: the engine-agnostic `effort` maps to `-c model_reasoning_effort=<level>` and passes straight through. Codex 0.149's ladder runs `low|medium|high|xhigh|max|ultra` — it is the only engine here that reaches `ultra`, and all three top levels were exercised against 0.149.1. `auto` and `ultracode` are omitted. Note `-c` values are not validated at spawn: codex prints `reasoning effort: <whatever>` and sends it, so an unknown level fails at the API rather than at the command line
 - `noSessionPersistence` → `--ephemeral` (accepted by `exec` and `exec resume`); `ignoreUserConfig` → `--ignore-user-config`, which stops `$CODEX_HOME/config.toml` from deciding an orchestrated run's model behind the caller's back (auth still resolves from `CODEX_HOME`); `addDir` → `--add-dir` on the first turn only, since `exec resume` rejects it and the resumed thread keeps the roots it opened with
 - `codexProfile` → `--profile <name>` (named config profile from `~/.codex/config.toml`)
+- `--worktree` (0.154.0, behind `--enable worktrees`) is deliberately not wired. Measured: the turn's
+  edits land in `~/.codex/worktrees/<hash>/<repo>` on a detached HEAD, not in the session's `cwd`, and
+  the JSON stream never reports that path except inside individual `file_change` items. Everything
+  here that checks work — acceptance contracts, evidence diffs, the baseline change set — reads the
+  session's `cwd`, so passing the flag would have them verify an untouched tree and report on it.
+  Council's own per-agent git worktrees cover the isolation use case with paths the orchestrator owns
 - 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
 - `sandboxMode` maps to `--sandbox <mode>` on the first turn. **A resumed thread does not inherit it**, and `codex exec resume` rejects `--sandbox`, so the policy is restated as `-c sandbox_mode="<mode>"` on every resume. Without that, a `read-only` session goes writable from its second turn onward — verified against 0.146.0, where such a session wrote to disk on turn 2 on every attempt. Re-probed on 0.147.0 (direct write, shell redirect and delegate-to-subagent, each on a resumed turn): no writes
 - One-shot execution per message (no persistent subprocess between sends)

package/skills/references/sessions.md

@@ -77,6 +77,53 @@ 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.
 
+### Handing off to another engine
+
+`resumeSessionId` and `forkSession` continue a conversation on the engine that holds it. To continue
+it somewhere else — a stuck Claude session into Codex, an expensive model into a cheaper one —
+use `handoffSession` (tool: `session_handoff`):
+
+```typescript
+await manager.handoffSession('refactor', {
+  engine: 'codex',
+  message: 'Carry on from where we stopped.', // optional: send now and return the reply
+});
+// → new session 'refactor-codex', same cwd; 'refactor' keeps running untouched
+```
+
+**How the conversation travels.** No engine can resume another's session, and each keeps its
+history in its own undocumented on-disk format. So the conversation is replayed as text: a
+`<conversation_history>` block in front of the new session's first message, after which the new
+engine holds it itself. Every turn in it is fenced, so a reply that contains the block's own tags
+cannot close it early and speak as another role. Nothing is written into either engine's session
+store.
+
+**What carries across.** What was said: every message sent through `sendMessage` and every reply,
+recorded per session as it happens. The session's own history buffer is not used for this — it is
+capped by event count, and on a long session the opening request is the first thing it loses. The
+new session inherits the source's working directory and its engine-neutral settings (permission and
+sandbox mode, effort, spend cap, system prompts, extra directories). It does not inherit anything
+written for the source engine — its model, tool allowlists in that engine's tool names, resume ids,
+profiles.
+
+**What does not.** The source engine's hidden reasoning, which no engine exposes, and the detail of
+tool calls — the new agent sees the replies that described the work, and the workspace itself, which
+the framing tells it to check before relying on anything the history describes.
+
+**When it is too long.** Up to `maxChars` (default 240,000 characters, ~60k tokens) the whole
+conversation is sent. Past that, the opening request is kept, the newest turns fill what is left,
+and one line records how many turns in between were left out: the request says what the work is
+for, the newest turns say where it stands, and the middle is what the workspace can answer.
+
+**A fork, not a move.** The two sessions go their separate ways. The new one starts from the
+source's record, so handing it off again carries the whole conversation rather than only its own
+part. The history is cleared only after a first send succeeds, so a first turn that fails on the
+new engine does not strand the conversation it was carrying.
+
+Verified end to end over MCP against the installed engines: a fact planted in a Claude session was
+recalled by Codex 0.154.0 after a handoff, and again by Claude after a second handoff back, which
+also named Codex as the engine it had taken over from.
+
 ### 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`):
@@ -158,6 +205,15 @@ in cleanup), `gemini` succeeds on exit 53 because its turn limit resolves,
 `interrupt()` does not count, and `opencode` refuses a turn on purpose when
 read-only enforcement did not load.
 
+**A succeeded turn is not a turn that did the work.** When the engine refuses a
+tool call it usually does not fail the turn. Measured on Claude Code 2.1.269 with
+`--permission-prompts none` — which a session gets whenever no prompt tool is
+configured — a turn asked to write a file came back `subtype: 'success'`,
+`is_error: false`, with the refused Bash call listed in the result event and no
+file on disk. It counts in `turnsSucceeded` and sets no `error`. The refused calls
+reach the caller as `permissionDenials` on the send result; read that before
+treating a successful turn as work done.
+
 The run ledger's `ok` reads this same counter, so a turn cannot be a failure on
 `/v1/sessions` and a success in `clawo runs`.
 

package/skills/references/tools.md

@@ -2,7 +2,7 @@
 
 All tools are registered as Claw Orchestrator plugin tools. In standalone mode, they're accessible via the embedded HTTP server.
 
-## Session Lifecycle (5)
+## Session Lifecycle (6)
 
 ### `session_start`
 
@@ -71,6 +71,32 @@ Send a message and get the response.
 | `timeout` | number  |          | Timeout in ms (default 300000)     |
 | `stream`  | boolean |          | Collect streaming chunks in result |
 
+Returns `{ ok, output, sessionId, error?, permissionDenials? }`. `permissionDenials` lists the tool
+calls the engine refused during the turn — `[{ toolName, toolUseId?, input? }]` — and is present only
+when there was at least one. Check it even when `error` is absent: a turn whose tool calls were all
+denied still ends as a success. See [sessions.md](./sessions.md) on what "succeeded" does and does
+not mean.
+
+### `session_handoff`
+
+Continue a session's conversation on another engine — or the same engine with another model. Starts
+a new session in the source's working directory and carries the conversation into it; the source
+keeps running untouched.
+
+| Parameter      | Type   | Required | Description                                                                 |
+| -------------- | ------ | -------- | --------------------------------------------------------------------------- |
+| `name`         | string | yes      | The session to hand off from                                                |
+| `engine`       | string | yes      | Engine for the new session                                                  |
+| `model`        | string |          | Model for the new session (default: the engine's default)                   |
+| `newName`      | string |          | Name for the new session (default `<name>-<engine>`)                        |
+| `message`      | string |          | Send this now and return the reply; otherwise the history waits for `session_send` |
+| `maxChars`     | number |          | Cap on the carried history, in characters (default 240000, minimum 4000)   |
+| `customEngine` | object |          | As in `session_start`, when `engine` is `custom`                            |
+
+Returns `{ ok, name, engine, from: { name, engine }, carried: { turns, omitted, chars }, result? }`.
+`result` is the send result of `message`, when one was given. See [sessions.md](./sessions.md) for
+what carries across, what does not, and what is kept when the conversation is too long to send whole.
+
 ### `session_stop`
 
 Graceful shutdown (SIGTERM, then SIGKILL after 3s).