@enderfga/claw-orchestrator 7.2.0 → 7.4.0

package/skills/references/multi-engine.md

@@ -133,7 +133,7 @@ await manager.startSession({
 
 Wraps Google's **Antigravity CLI** (`agy`) — the successor to Gemini CLI (consumer
 Gemini CLI tiers stopped serving 2026-06-18). Each `send()` spawns a new process
-in print mode. Verified against `agy` **1.1.13**.
+in print mode. Adapter behavior is covered through `agy` **1.2.2**.
 
 - One-shot execution per message (no persistent subprocess)
 - **Structured output and real usage** — `--output-format stream-json` emits an
@@ -145,6 +145,18 @@ in print mode. Verified against `agy` **1.1.13**.
   scrape remains as a fallback for turns that die before emitting `init`. Seed it
   externally via `resumeSessionId` (bare UUID only); read it back from
   `getStats().agyConversationId`.
+- **Empty responses fail adapter-wide and remain recoverable**: an exit-0 result
+  with a missing, blank, or whitespace-only response rejects instead of becoming
+  a successful empty reply, whether the caller is Autoloop, MCP, HTTP, or the
+  library API. agy 1.1.26 may do this after plan mode soft-denies a tool
+  confirmation. The adapter clears the per-session log before each spawn and
+  recognizes only the narrow current-turn `tool_confirmation_manager` marker,
+  returning a fixed sanitized diagnosis without exposing native log content. A
+  conversation id already emitted by `init` is retained for the caller's next
+  send; the failed turn is not retried automatically. On agy 1.2.2 the same
+  denial can accompany `status: SUCCESS` and a non-empty reply; the refused tool
+  names are emitted as `permission_denials`, which SessionManager exposes as
+  `SendResult.permissionDenials` without discarding the reply.
 - **Reasoning effort**: session `effort` and per-turn `session_send` overrides map
   to `--effort`. agy accepts `low`, `medium`, and `high`; everything above that
   (`xhigh`, `max`, `ultra`) clamps to `high`. agy 1.1.25 requires an effort with unsuffixed base
@@ -163,15 +175,21 @@ in print mode. Verified against `agy` **1.1.13**.
 - Permission modes: `bypassPermissions` → `--dangerously-skip-permissions`,
   `default` → `--sandbox` (terminal-restricted), and
   `sandboxMode: 'read-only'` → `--mode plan` (takes precedence). Other modes
-  run agy's own approval flow, which blocks in headless print mode — use
-  `bypassPermissions` for autonomous write-enabled work
+  run agy's own approval flow, which can block in headless print mode. A caller
+  must explicitly choose `bypassPermissions` for a write-enabled session; it is
+  not a recovery mechanism. In particular, an Autoloop Planner stays on
+  `--mode plan` when its preserved conversation is resumed.
 - agy enforces its own print timeout (default 5m); the engine derives
   `--print-timeout` from the send timeout so the wrapper timer decides
-- Unknown `--model` slugs do **not** error — agy silently falls back to its
-  default model. Registered slugs: `gemini-3.5-flash` (alias `agy-flash`),
-  `gemini-3.1-pro` (alias `agy-pro`); agy also proxies Claude and GPT-OSS
-  models (`agy models` lists them) which pass through unregistered. The
-  `agy/` prefix forces Antigravity routing for provider-like model strings
+- Do not rely on an unknown `--model` falling back: current agy versions can
+  report `status: ERROR` with no usable response. The adapter rejects result
+  errors, non-success statuses, and empty responses. `agy-flash` and the engine
+  default resolve to `gemini-3.8-flash`; `agy-pro` resolves to
+  `gemini-3.1-pro`. The registry also describes the 3.5/3.6/3.7 Flash API
+  families for pricing and routing, but agy's own `agy models` output decides
+  which slugs are executable. agy also proxies Claude and GPT-OSS models, which
+  pass through unregistered. The `agy/` prefix forces Antigravity routing for
+  provider-like model strings.
 - Consumer auth is a one-time `agy` Google OAuth login (subscription quotas, no
   per-token billing — registry pricing mirrors Gemini API rates as a value proxy)
 - Requires `agy` installed: `curl -fsSL https://antigravity.google/cli/install.sh | bash`
@@ -181,7 +199,7 @@ in print mode. Verified against `agy` **1.1.13**.
 await manager.startSession({
   name: 'antigravity-task',
   engine: 'agy',
-  model: 'gemini-3.5-flash',
+  model: 'gemini-3.8-flash',
   effort: 'high',
   cwd: '/project',
 });

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).