@enderfga/claw-orchestrator 7.5.3 → 7.5.5

package/skills/references/council.md

@@ -80,7 +80,7 @@ import { SessionManager } from '@enderfga/claw-orchestrator';
 
 const manager = new SessionManager();
 
-const session = manager.councilStart('Build a REST API with authentication', {
+const session = await manager.councilStart('Build a REST API with authentication', {
   agents: [
     {
       name: 'Planner',
@@ -173,7 +173,7 @@ Rewrites `plan.md` with rejection feedback and commits it. All worktrees and bra
 | ------------------ | ------------------ | ---------------------------------- |
 | `maxRounds`        | 15                 | Maximum collaboration rounds       |
 | `agentTimeoutMs`   | 1,800,000 (30 min) | Per-agent timeout per round        |
-| `maxTurnsPerAgent` | 30                 | Max tool turns per agent per round |
+| `maxTurnsPerAgent` | 50                 | Max tool turns per agent per round |
 | `maxBudgetUsd`     | —                  | API spend limit per agent          |
 
 ### defaultPermissionMode
@@ -181,7 +181,7 @@ Rewrites `plan.md` with rejection feedback and commits it. All worktrees and bra
 Optional. Sets the default permission mode for council agents when individual agents don't specify one. Defaults to `bypassPermissions`.
 
 ```typescript
-manager.councilStart('task', {
+await manager.councilStart('task', {
   agents: [...],
   maxRounds: 10,
   projectDir: '/project',
@@ -191,52 +191,41 @@ manager.councilStart('task', {
 
 Permission priority: agent-level `permissionMode` > `defaultPermissionMode` > `'bypassPermissions'`
 
-> **Note (Claude CLI 2.1.121+):** When agent personas are persisted as Claude agent files with frontmatter, the `permissionMode`, `tools`, and `disallowedTools` fields are now **enforced** by `--agent` and `--print` modes (previously advisory). If you write agent files with restrictive `tools` lists, expect those agents to refuse calls to other tools at runtime.
-
 ## System Prompt
 
-The council system prompt is loaded from `configs/council-system-prompt.md` and supports hot-editing. It includes 9 charter sections tuned through extensive multi-agent collaboration testing:
+The council system prompt is loaded from `configs/council-system-prompt.md` and supports hot-editing. It has 9 charter sections:
 
-| Section                     | Purpose                                        |
-| --------------------------- | ---------------------------------------------- |
-| §0 No Hallucination         | Agents must use tools, never fabricate results |
-| §1 Plan First               | Two-phase protocol with plan.md                |
-| §2 Parallel Coordination    | Claim/done protocol for concurrent work        |
-| §3 Truth in Git             | Git state over conversation memory             |
-| §4 Merge to Main            | Local only, never push                         |
-| §5 Cross-Review             | Structured APPROVE/REQUEST_CHANGES             |
-| §6 Auto-Conflict Resolution | Never stop on merge conflicts                  |
-| §7 Action Over Words        | Never ask permission, just work                |
-| §8 Efficient Tool Use       | Minimum necessary principle                    |
+| Section                           | Purpose                                        |
+| --------------------------------- | ---------------------------------------------- |
+| §0 Must Use Tools to Execute      | Agents must use tools, never fabricate results |
+| §1 Blueprint First                | Two-phase protocol with plan.md                |
+| §2 Parallel Coordination          | Claim/done protocol for concurrent work        |
+| §3 Truth in Git                   | Git state over conversation memory             |
+| §4 Integration Is Completion      | Local only, never push                         |
+| §5 Cross-Review                   | Structured APPROVE/REQUEST_CHANGES             |
+| §6 Autonomous Conflict Resolution | Never stop on merge conflicts                  |
+| §7 Action Over Words              | Never ask permission, just work                |
+| §8 Efficient Tool Use             | Minimum necessary principle                    |
 
 Placeholders: `{{emoji}}`, `{{name}}`, `{{persona}}`, `{{workDir}}`, `{{projectDir}}`, `{{otherBranches}}`
 
 The charter is each seat's only instruction channel, and it reaches every engine through `appendSystemPrompt`:
 natively on Claude Code and Grok, as the top of the seat's first message on Codex, Antigravity and OpenCode.
-Nothing is written into the worktrees. Seats used to get their identity and workspace boundary from a
-generated `<worktree>/.claude/CLAUDE.md`, which only Claude Code reads and which an agent could commit
-into the project.
+Nothing is written into the worktrees.
 
 ## Transcript Logging
 
-All council sessions save transcripts to `~/.openclaw/council-logs/council-<timestamp>.md`. Completed councils remain queryable via `council_status` for 30 minutes after completion.
-
-## Consensus is advisory (6.0.0)
+All council sessions save transcripts to `~/.openclaw/council-logs/council-<timestamp>.md`. Transcripts are for humans to read; nothing parses them. Completed councils stay queryable via `council_status` indefinitely — the run record is on disk.
 
-Through 5.1.0 a council ended when `parseConsensus` found `[CONSENSUS: YES]` in
-every agent's reply — that is, the termination condition was a regex over agent
-prose. Two things made that weaker than it looked: the fallback patterns match a
-bare `consensus: yes` anywhere in the text, and when a reply came back short and
-unmarked the orchestrator re-prompted twice _asking for the token_, which is
-demanding a vote rather than checking anything.
+## Votes end the rounds; contracts decide the verdict
 
-Votes are still collected and still recorded — they are what the agents were
-asked for, and they are useful. They are recorded on the run as
-`consensusVotes`, each with the parse `source` (`strict` / `variant` / `none`) so
-a loosely-detected vote is visible as such.
+A council stops early when every agent votes YES, but the votes do not decide
+whether the work is acceptable. They are recorded on the run as
+`consensusVotes`, each with the parse `source` (`strict` / `variant` / `none`),
+so a loosely detected vote is visible as such.
 
-What changed is that they no longer decide whether the work is acceptable. Give
-the run an acceptance contract and the runtime checks the result itself:
+To have the result checked, give the run an acceptance contract and the runtime
+runs the checks itself:
 
 ```jsonc
 workflow_start({
@@ -247,42 +236,30 @@ workflow_start({
 })
 ```
 
-Without a contract the council behaves exactly as before and the run completes
-`unverified` — nothing checked it.
-
-`council_start` and the rest of the `council_*` tools keep their signatures, with
-one change forced by the cutover: **`councilStart` is now async** (it creates a
-durable run before returning). The same applies to `fanoutStart`,
-`ultraplanStart` and `ultrareviewStart`. Tool callers are unaffected; direct
-TypeScript callers need an `await`.
+Without a contract the run completes `unverified` — nothing checked it.
 
-## Lifecycle moved to the kernel
+`councilStart`, `fanoutStart`, `ultraplanStart` and `ultrareviewStart` are
+async (each creates a durable run before returning); direct TypeScript callers
+need `await`.
 
-A council is a kernel run. `councils`, its 30-minute eviction timer, and
-`listCouncilsFromDisk` — which read `~/.openclaw/council-logs/*.md` with a regex
-and fabricated a stub session with no responses and an empty config — are gone.
-`council_list` returns real records, from disk, across processes.
+## Durable runs
 
-`council_review` / `accept` / `reject` work after a restart now. They act on the
-git state a finished council left behind, not on live agents, so they run against
-a `Council` rebuilt from the record. Only `council_inject` still needs the live
-engine, and it says so plainly when there isn't one.
+A council is a durable kernel run. `GET /council/list` (and the dashboard)
+returns real records from disk, across processes.
 
-Transcripts are still written to `~/.openclaw/council-logs/` for humans. Nothing
-parses them.
+`council_review` / `council_accept` / `council_reject` work after a restart:
+they act on the git state the council left behind, not on live agents.
+`council_inject` needs the live run and says so plainly when there is none.
 
 ## Changed-file reporting
 
-`council_review` used to diff `HEAD~20..HEAD` with a `HEAD~10` fallback: a magic
-window unrelated to when the council started, which returned nothing at all on a
-shallow or young history. It now diffs against the **merge-base** of `HEAD` and
-the first `council/*` branch — the actual fork point — and includes files the
-agents created, which a tracked-file diff cannot see.
+`council_review` diffs against the **merge-base** of `HEAD` and the first
+`council/*` branch — the point where the council's work started — and includes
+files the agents created, which a tracked-file diff cannot see.
 
-`CouncilChangedFile.status` was previously hardcoded to `'clean'` for every
-entry, which read as "reviewed and found fine" when nothing had looked at it. It
-is now optional and left undefined until a reviewer assesses the file; the new
-`change` field carries git's own account (`added` / `modified` / `deleted`).
+Each `CouncilChangedFile` carries `change` — git's own account (`added` /
+`modified` / `deleted`). `status` is optional and stays undefined until a
+reviewer assesses the file.
 
 ## Related
 

package/skills/references/dashboard.md

@@ -2,8 +2,8 @@
 
 The dashboard is a single-page HTML app served by the orchestrator's embedded
 HTTP server. It lets you **launch and observe** Council sessions, Autoloop
-runs, and Forge (Ultraapp) builds from a browser — no CLI, no webchat, no
-plugin tool calls needed.
+runs and Forge (Ultraapp) builds, and browse durable workflow runs, from a
+browser — no CLI, no webchat, no plugin tool calls needed.
 
 URL: `http://127.0.0.1:18796/dash` (local) or whatever public hostname you
 front the embedded server with (the recommended setup uses a path-based
@@ -16,8 +16,10 @@ reverse proxy, e.g. `https://<your-host>/dash`).
 | Autoloop | `SessionManager.autoloopStart()` | `POST /autoloop/new` |
 | Council  | `SessionManager.councilStart()`  | `POST /council/new`  |
 | Forge    | `UltraappManager.createRun()`    | `POST /ultraapp/new` |
+| Runs     | `GET /workflow/list`             | — (view only)        |
 
-Each tab has a `+ New` button in the sidebar. Council and Autoloop open a
+Autoloop, Council and Forge each have a `+ New` button in the sidebar; Runs is
+view-only (start runs with `workflow_start`). Council and Autoloop open a
 modal form (because they need workspace/task input); Forge POSTs an empty
 body and drops you into an interview (the spec is built conversationally).
 
@@ -65,10 +67,14 @@ launchctl print "gui/$(id -u)/com.clawo.serve" | grep state
 
 ## Auth
 
-The embedded server self-generates a 32-byte token at startup and writes it
-to `~/.openclaw/server-token` (mode 0600). Same-user processes on the box
-read it and present it as `Authorization: Bearer <token>` (or
-`?token=<v>` query / `clawo_auth` cookie).
+On first start the embedded server generates a 32-byte token and writes it
+to `~/.openclaw/server-token` (mode 0600); later starts reuse it. Same-user
+processes on the box read it and present it as `Authorization: Bearer <token>`
+(or `?token=<v>` query / `clawo_auth` cookie).
+
+`OPENCLAW_SERVER_TOKEN=<v>` sets an explicit token instead.
+`OPENCLAW_SERVER_TOKEN=disabled` turns authentication off entirely — only safe
+on a trusted single-user host.
 
 ### Local access
 
@@ -76,24 +82,25 @@ read it and present it as `Authorization: Bearer <token>` (or
 http://127.0.0.1:18796/dash?token=$(cat ~/.openclaw/server-token)
 ```
 
-The server sets a `clawo_auth` cookie on the first query-token request, so
-the bookmark `/dash` works on subsequent visits.
+The server sets a `clawo_auth` cookie on the first query-token request, so a
+bookmarked `/dash` works for the next 24 hours (the cookie's lifetime).
 
 ### Hosted access via reverse proxy (recommended)
 
 Don't expose the token to the public internet. Instead, gate the public
-hostname with whatever auth layer you already trust (CF Access passkey,
+hostname with whatever auth layer you already trust (Cloudflare Access,
 Tailscale, mTLS, etc.) and have the reverse proxy **inject the Bearer
 token on behalf of the user** when forwarding to port 18796. The browser
 authenticates only against your edge auth; the dashboard's own token stays
 inside the box.
 
-Example sasha-doctor pattern (matches the user-side setup):
+Example reverse-proxy pattern (Node):
 
 ```js
 // after the edge auth check passes:
 if (!req.headers.authorization) {
-  req.headers.authorization = 'Bearer ' + fs.readFileSync('~/.openclaw/server-token', 'utf-8').trim();
+  const tokenFile = path.join(os.homedir(), '.openclaw', 'server-token');
+  req.headers.authorization = 'Bearer ' + fs.readFileSync(tokenFile, 'utf-8').trim();
 }
 proxyHTTP(req, res, 18796);
 ```
@@ -103,20 +110,17 @@ quick one-shot setups (works locally and through proxies that DON'T inject
 the Bearer for you), but the proxy-injects-Bearer pattern is preferred
 because users never see or paste the token.
 
-Token-file write is deferred to the `listen()`-success callback so a second
-process that loses the EADDRINUSE race does NOT clobber the winner's token.
-The token is also re-read from disk on every request so that if a different
-clawo instance (test runner, nohup launch, etc.) writes a new value mid-life,
-the proxy and the server stay in agreement on the next request — no restart
-required.
+The token file is written only after the server has bound its port, so a
+second process that fails to bind does not overwrite the running server's
+token. The token is read from disk on every request, so a server and a proxy
+that both read the file always agree.
 
 ## Resuming a terminated autoloop run
 
 Opening a run whose `status` is `terminated` (because its process has
-exited, or because you're viewing it cross-process) no longer hangs on
-"Waiting…". The dashboard fetches `/autoloop/<id>/chat_history`, replays
-the conversation into the Planner pane, and surfaces a green **Resume
-run** button in the topbar. Clicking it POSTs `/autoloop/<id>/resume`;
+exited, or because you're viewing it cross-process) fetches
+`/autoloop/<id>/chat_history`, replays the conversation into the Planner pane,
+and shows a green **Resume run** button in the topbar. Clicking it POSTs `/autoloop/<id>/resume`;
 the orchestrator re-attaches the Planner (reusing the persisted Claude
 session ID when available, so Claude's context picks up where it left
 off) and the dashboard reconnects to `/events` for live updates.
@@ -124,42 +128,27 @@ off) and the dashboard reconnects to `/events` for live updates.
 If the run used a **custom engine** for any role, the button first asks
 `/autoloop/<id>/resume-requirements` and prompts for one reference name per
 role — the name of a `CLAWO_CUSTOM_ENGINE_<NAME>` variable on the orchestrator
-host. The config itself is never stored and never sent; only the name is. Until
-this existed the button sent an empty body unconditionally, so a custom-engine
-run was resumable from the library and the HTTP API but not from the UI that
-offers the button.
+host. The config itself is never stored and never sent; only the name is.
 
-Runs that pre-date this feature have no `chat.jsonl` and no persisted
-session — they still resume cleanly, but with a blank Planner pane and a
-fresh Claude context. New runs going forward retain both.
+A run without a `chat.jsonl` or a persisted session still resumes, with a blank
+Planner pane and a fresh Claude context.
 
 ## Cross-process visibility
 
-When the dashboard runs in a different process from where you spawn runs
-(e.g. you started a council via the OpenClaw plugin tool from webchat, but
-the dashboard is in `clawo serve`), the run state is invisible across
-in-memory boundaries. The dashboard fixes this by unioning in-memory state
-with on-disk records on every list call:
-
-- **Councils**: `~/.openclaw/council-logs/council-*.md` — parsed for
-  `- **ID**:`, `- **Time**:`, `- **Task**:`, `- **Status**:` headers.
-  Legacy transcripts (pre-v4.0) fall back to a filename-derived id.
-- **Autoloops**: `~/.claw-orchestrator/autoloop-registry.jsonl` — an
-  append-only JSONL index written by `autoloopStart()`. Stale entries
-  whose ledger directory no longer exists are filtered out at read time.
-- **Forge**: `UltraappStore.listRuns()` already reads from disk
-  (`~/.claw-orchestrator/ultraapps/`).
-
-Result: any run you've ever started — from any process — shows up in the
-sidebar, sorted newest-first, until the underlying files are deleted.
+Every council, autoloop and workflow run is a durable kernel run stored under
+`~/.claw-orchestrator/wf/`, so the dashboard lists runs started by any process —
+the OpenClaw plugin, `clawo serve`, or the CLI — sorted newest-first, until the
+run records are deleted. Forge runs are read from
+`~/.claw-orchestrator/ultraapps/`.
 
 ## Reverse-proxy integration
 
-If you front the embedded server with sasha-doctor (or another reverse
-proxy), route these paths to `127.0.0.1:18796`:
+If you front the embedded server with a reverse proxy, route these paths to
+`127.0.0.1:18796`:
 
 - `/dashboard`, `/dash`, `/login`
 - `/autoloop/*`, `/council/*`, `/ultraapp/*`
+- `/workflow/*`, `/runs`
 
 The dashboard's relative `fetch()` calls expect the proxy to preserve the
 path verbatim — no prefix stripping. `/v1/openclaw/*` should keep routing
@@ -167,21 +156,19 @@ to the OpenClaw gateway, not the embedded server.
 
 ## Reset
 
-To wipe dashboard state without touching real run data:
+To rotate the auth token, delete the token file and restart the server — a
+restart alone reuses the existing token:
 
 ```sh
-# Forget all known autoloops (council/forge unchanged).
-rm ~/.claw-orchestrator/autoloop-registry.jsonl
-
-# Force the standalone server to mint a fresh auth token.
+rm ~/.openclaw/server-token
 launchctl kickstart -k "gui/$(id -u)/com.clawo.serve"
 # Then visit /login?token=$(cat ~/.openclaw/server-token)&redirect=/dash once
 # to refresh the cookie.
 ```
 
-## Runs tab (6.0.0)
+## Runs tab
 
-A fourth tab listing durable workflow runs. Because runs are checkpointed to
+Lists durable workflow runs. Because runs are checkpointed to
 disk, this sees runs started by other processes and by earlier sessions, not just
 what the current server started.
 

package/skills/references/getting-started.md

@@ -7,7 +7,7 @@
 ```bash
 npm install -g @enderfga/claw-orchestrator
 
-# Start the embedded server
+# Start the embedded server (keeps running; use a second terminal for the commands below)
 clawo serve
 
 # Drive sessions from the command line
@@ -32,7 +32,7 @@ Agents automatically get access to all session, council, and management tools.
 ```typescript
 import { SessionManager } from '@enderfga/claw-orchestrator';
 
-const manager = new SessionManager({ defaultModel: 'claude-sonnet-4-6' });
+const manager = new SessionManager({ defaultModel: 'claude-sonnet-5' });
 
 const session = await manager.startSession({
   name: 'backend-fix',
@@ -53,6 +53,8 @@ await manager.stopSession('backend-fix');
 - **OpenClaw >= 2026.3.0** — for plugin mode (optional)
 - **OpenAI Codex CLI >= 0.112** — `npm install -g @openai/codex` (optional, for codex engine)
 - **Antigravity CLI** — `curl -fsSL https://antigravity.google/cli/install.sh | bash` (optional, for the `agy` engine — Google's successor to the sunset Gemini CLI)
+- **Grok Build CLI** — optional, for the `grok` engine
+- **OpenCode CLI** — `npm install -g opencode-ai` (optional, for the `opencode` engine)
 
 ### Engine Authentication
 
@@ -61,18 +63,20 @@ Each engine requires its own authentication before use:
 - **Claude Code** — run `claude /login` or set `ANTHROPIC_API_KEY`
 - **Codex** — run `codex login` or set `OPENAI_API_KEY`
 - **Antigravity** — run `agy` once and complete the Google OAuth login
+- **Grok** — run `grok` once and sign in (grok.com account or `XAI_API_KEY`)
+- **OpenCode** — run `opencode auth login`, or set a provider key such as `ANTHROPIC_API_KEY`
 
 The plugin does not manage authentication — it expects each CLI to be ready to run.
 
 ### Embedded Server Authentication
 
-The embedded HTTP server (used by CLI and standalone mode) optionally supports bearer token authentication:
+Authentication on the embedded HTTP server (used by the CLI and standalone mode) is on by default:
 
-| Variable                | Purpose                                                                                                       |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `OPENCLAW_SERVER_TOKEN` | Set to enable bearer token auth. All requests (except `/health`) must include `Authorization: Bearer <token>` |
+| Variable                | Purpose                                                                                                                       |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `OPENCLAW_SERVER_TOKEN` | Unset: a random token is generated. Set to a value: use that token. Set to `disabled`: turn auth off (single-user hosts only) |
 
-When set, the token is also written to `~/.openclaw/server-token` for the CLI to read automatically. Default: no auth (localhost binding is the primary security boundary).
+On start the server writes the token to `~/.openclaw/server-token` (mode 0600) and reuses it across restarts; the CLI reads it automatically. Every request except `/health` must carry it as `Authorization: Bearer <token>` or the `clawo_auth` cookie. Browsers sign in once via `/login?token=<token>&redirect=/dashboard`, which sets the cookie.
 
 ### OpenAI-Compatible Endpoint
 
@@ -83,11 +87,11 @@ The server exposes an OpenAI-compatible API at `/v1/chat/completions`. It serves
 
 Quick config for any client:
 
-| Setting      | Value                                                                            |
-| ------------ | -------------------------------------------------------------------------------- |
-| API Base URL | `http://127.0.0.1:18796/v1`                                                      |
-| API Key      | The value of `OPENCLAW_SERVER_TOKEN`, or any string if auth is disabled          |
-| Model        | `claude-fable-5`, `claude-opus-5`, `claude-sonnet-5`, `gpt-5.5`, `agy-pro`, etc. |
+| Setting      | Value                                                                                 |
+| ------------ | ------------------------------------------------------------------------------------- |
+| API Base URL | `http://127.0.0.1:18796/v1`                                                           |
+| API Key      | The server token (from `~/.openclaw/server-token`), or any string if auth is disabled |
+| Model        | `claude-fable-5-1`, `claude-opus-5-5`, `claude-sonnet-5`, `gpt-5.5`, `agy-pro`, etc.  |
 
 See [openai-compat.md](./openai-compat.md) for the full session-keying rules, `X-Session-Reset` semantics, the legacy-heuristic env var, and the `/v1/sessions` inspection endpoint.
 
@@ -124,8 +128,10 @@ In `~/.openclaw/openclaw.json`:
 
 - [Sessions](./sessions.md) — persistent session lifecycle and management
 - [Session Inbox](./inbox.md) — cross-session messaging
-- [Multi-Engine](./multi-engine.md) — using Claude Code and Codex side by side
+- [Multi-Engine](./multi-engine.md) — one interface over Claude Code, Codex, Antigravity, Grok Build, OpenCode and custom CLIs
 - [Council](./council.md) — multi-agent collaboration with consensus voting
 - [Ultraplan & Ultrareview](./ultra.md) — deep planning and fleet code review
-- [Tools Reference](./tools.md) — complete tool API reference (27 tools)
+- [Tools Reference](./tools.md) — complete tool API reference (78 tools)
 - [CLI Reference](./cli.md) — command-line interface
+- [MCP Server](./mcp.md) — expose the tools to any MCP host
+- [ACP Agent](./acp.md) — run the orchestrator as an Agent Client Protocol agent

package/skills/references/inbox.md

@@ -1,6 +1,6 @@
 # Session Inbox
 
-Cross-session messaging allows different sessions to communicate with each other. Inspired by Claude Code's UDS Inbox feature.
+Cross-session messaging allows different sessions to communicate with each other.
 
 ## How It Works
 
@@ -21,7 +21,9 @@ Session A (planner)          SessionManager           Session B (coder)
 - **Idle sessions** receive messages immediately as a new user turn
 - **Busy sessions** have messages queued in an inbox (max 200 messages)
 - Messages are wrapped in `<cross-session-message>` XML tags
-- Supports broadcast to all sessions via `to: "*"`
+- Supports broadcast to all sessions via `to: "*"`; a broadcast skips the sender
+- Sender and target must be existing sessions, otherwise the call fails
+- Returns `{ delivered, queued }`
 
 ## Usage
 
@@ -72,10 +74,10 @@ The auth module needs rate limiting. Please add a token bucket...
 </cross-session-message>
 ```
 
-Attributes are properly escaped to prevent XML injection.
+Attribute values are XML-escaped, and any `cross-session-message` tag inside the body is escaped, so a sender cannot forge a second envelope.
 
 ## Inbox Limits
 
 - **Max size**: 200 messages per session
 - **Eviction**: oldest read messages dropped first, then oldest unread
-- **No TTL**: messages persist until read or evicted (in-memory only, not persisted to disk)
+- **No TTL**: messages, read or unread, stay in memory until evicted or the process exits. They are not persisted to disk.

package/skills/references/mcp.md

@@ -1,6 +1,6 @@
 # MCP integration
 
-Claw Orchestrator ships a Model Context Protocol (MCP) server (`clawo-mcp`) so any MCP-compatible host can drive its 55 tools.
+Claw Orchestrator ships a Model Context Protocol (MCP) server (`clawo-mcp`) so any MCP-compatible host can drive its 78 tools.
 
 This document covers:
 
@@ -29,17 +29,22 @@ This document covers:
 
 Tools fall into a few groups:
 
-| Group                   | Examples                                                                                                                                           |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Session lifecycle       | `session_start`, `session_send`, `session_stop`, `session_list`, `session_grep`, `session_compact`, `session_update_tools`, `session_switch_model` |
-| Cross-session messaging | `session_send_to`, `session_inbox`, `session_deliver_inbox`                                                                                        |
-| Status / introspection  | `sessions_overview`, `coding_session_status`, `coding_agents_list`                                                                                 |
-| Multi-agent council     | `council_start`, `council_status`, `council_abort`, `council_inject`, `council_review`, `council_accept`, `council_reject`                         |
-| Ultraplan / ultrareview | `ultraplan_start`, `ultraplan_status`, `ultrareview_start`, `ultrareview_status`                                                                   |
-| Autoloop                | `autoloop_start`, `autoloop_chat`, `autoloop_status`, `autoloop_list`, `autoloop_reset_agent`, `autoloop_stop`                                     |
-| Codex specifics         | `codex_resume`, `codex_review`, `codex_goal_set`, `codex_goal_get`, `codex_goal_pause`, `codex_goal_resume`, `codex_goal_clear`                    |
-| Agent teams             | `team_list`, `team_send`                                                                                                                           |
-| Maintenance             | `project_purge`                                                                                                                                    |
+| Group                   | Examples                                                                                                                                                              |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Session lifecycle       | `session_start`, `session_send`, `session_handoff`, `session_stop`, `session_list`, `session_grep`, `session_compact`, `session_update_tools`, `session_switch_model` |
+| Cross-session messaging | `session_send_to`, `session_inbox`, `session_deliver_inbox`                                                                                                           |
+| Status / introspection  | `sessions_overview`, `coding_session_status`, `coding_agents_list`                                                                                                    |
+| Multi-agent council     | `council_start`, `council_status`, `council_abort`, `council_inject`, `council_review`, `council_accept`, `council_reject`                                            |
+| Ultraplan / ultrareview | `ultraplan_start`, `ultraplan_status`, `ultrareview_start`, `ultrareview_status`                                                                                      |
+| Autoloop                | `autoloop_start`, `autoloop_chat`, `autoloop_status`, `autoloop_list`, `autoloop_reset_agent`, `autoloop_stop`                                                        |
+| Codex specifics         | `codex_resume`, `codex_review`, `codex_goal_set`, `codex_goal_get`, `codex_goal_pause`, `codex_goal_resume`, `codex_goal_clear`                                       |
+| Codex app-server        | `codex_interrupt`, `codex_steer`, `codex_fork`, `codex_rollback`, `codex_models`, `codex_thread_list`                                                                 |
+| Claude specifics        | `claude_goal_set`, `claude_goal_status`, `claude_goal_clear`, `claude_agents_list`, `plugin_details`                                                                  |
+| Fan-out                 | `fanout_start`, `fanout_status`, `fanout_abort`                                                                                                                       |
+| Workflow & verification | `workflow_start`, `workflow_status`, `workflow_list`, `workflow_resume`, `workflow_cancel`, `workflow_steer`, `workflow_approve`, `verify_run`                        |
+| Ultraapp                | `ultraapp_*` (14 tools) — see [`ultraapp.md`](./ultraapp.md)                                                                                                          |
+| Agent teams             | `team_list`, `team_send`                                                                                                                                              |
+| Maintenance             | `project_purge`                                                                                                                                                       |
 
 Full per-tool parameter documentation lives in [`tools.md`](./tools.md).
 
@@ -47,7 +52,7 @@ Install once:
 
 ```bash
 npm install -g @enderfga/claw-orchestrator
-# `clawo-mcp` is on PATH; the OpenClaw `clawo` CLI is also installed
+# `clawo-mcp` is on PATH; the `clawo` CLI is also installed
 ```
 
 When invoked, `clawo-mcp`:
@@ -214,22 +219,22 @@ Check your host's MCP docs for the exact key names (`command`/`cmd`, `env`/`envs
 
 Hosts deliberately do not forward your full shell environment to MCP subprocesses. Pass every variable your engines need explicitly under the host's `env` block.
 
-| Variable                               | Used by                                                                    |
-| -------------------------------------- | -------------------------------------------------------------------------- |
-| `ANTHROPIC_API_KEY`                    | Claude Code engine                                                         |
-| `OPENAI_API_KEY`                       | Codex engine                                                               |
-| `GEMINI_API_KEY` (or `GOOGLE_API_KEY`) | Gemini engine                                                              |
-| `GATEWAY_URL`, `GATEWAY_KEY`           | Routing through an OpenClaw / Anthropic-style gateway                      |
-| `CLAWO_MCP_TOOLS`                      | Comma-separated allowlist of tool names; unlisted tools are not advertised |
-| `CLAWO_NO_EMBEDDED_SERVER`             | Suppresses port 18796 binding. `clawo-mcp` sets this automatically         |
+| Variable                     | Used by                                                                    |
+| ---------------------------- | -------------------------------------------------------------------------- |
+| `ANTHROPIC_API_KEY`          | Claude Code engine                                                         |
+| `OPENAI_API_KEY`             | Codex engine                                                               |
+| `GEMINI_API_KEY`             | Multi-model proxy (Gemini models)                                          |
+| `GATEWAY_URL`, `GATEWAY_KEY` | Routing through an OpenClaw / Anthropic-style gateway                      |
+| `CLAWO_MCP_TOOLS`            | Comma-separated allowlist of tool names; unlisted tools are not advertised |
+| `CLAWO_NO_EMBEDDED_SERVER`   | Suppresses port 18796 binding. `clawo-mcp` sets this automatically         |
 
-The engines themselves (`claude`, `codex`, `gemini`, `agy`, `agent`, `opencode`) must also be installed and authenticated on the host machine — `clawo-mcp` spawns them as subprocesses, it does not bundle them.
+The engines themselves (`claude`, `codex`, `agy`, `grok`, `opencode`) must also be installed and authenticated on the host machine — `clawo-mcp` spawns them as subprocesses, it does not bundle them.
 
 ---
 
 ## Tool filtering
 
-55 tools is a lot for a small context window. Reduce noise either at the host level (most hosts have an `include` / `exclude` filter — see Hermes example above) or at the server level via `CLAWO_MCP_TOOLS`:
+78 tools is a lot for a small context window. Reduce noise either at the host level (most hosts have an `include` / `exclude` filter — see Hermes example above) or at the server level via `CLAWO_MCP_TOOLS`:
 
 ```bash
 CLAWO_MCP_TOOLS="session_start,session_send,session_stop,council_start,council_status" clawo-mcp
@@ -272,7 +277,7 @@ For "let the model commission an ultrareview before merging":
 
 **Engine starts but fails with `command not found`**
 
-- The underlying coding CLI (`claude`, `codex`, `gemini`, etc.) is not on PATH in the host's subprocess environment. Either install globally or set `claudeBin` / `codexBin` etc. via `customEngine.bin` per session, or pass an explicit `PATH` in the host's `env` block.
+- The underlying coding CLI (`claude`, `codex`, `agy`, etc.) is not on PATH in the host's subprocess environment. Either install globally, pass an explicit `PATH` in the host's `env` block, or point at the binary with `CLAUDE_BIN` / `CODEX_BIN` / `AGY_BIN` / `GROK_BIN` / `OPENCODE_BIN`.
 
 **`401` / `auth` errors from a session**