@enderfga/claw-orchestrator 7.2.0 → 7.3.0

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/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`):

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`
 
@@ -77,6 +77,26 @@ when there was at least one. Check it even when `error` is absent: a turn whose
 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).