@enderfga/claw-orchestrator 7.14.0 → 7.16.0

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

@@ -2,12 +2,14 @@
 
 This document tracks which Claude Code CLI version Claw Orchestrator is currently synced to, and which features have been integrated. Recent rows also record the other engines' versions checked in the same sync.
 
-## Currently tracked: **Claude Code CLI 2.1.310** (as of 2026-10-25, plugin v7.14.0)
+## Currently tracked: **Claude Code CLI 2.1.310** (as of 2026-10-28, plugin v7.16.0)
 
 ## Sync history
 
 | Plugin Version      | Claude CLI Version | Date       | Notable integrations                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | ------------------- | ------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| v7.16.0             | 2.1.310            | 2026-10-28 | Pins as tracked in v7.15.0; not re-run live this release (installed: CC 2.1.312, Codex 0.165.0, agy 1.4.9). Integrated: `/goal` on Claude Code behind the `goal` node — measured on CC 2.1.312 in stream-json mode (bare `/goal` probe, Stop-hook turns, `interrupt` control request). |
+| v7.15.0             | 2.1.310            | 2026-10-26 | Engine versions as tracked in v7.14.0 (agy 1.4.7 is installed but not yet run live; the pin stays 1.4.6). Integrated: `codex-app` passes reasoning effort — `turn/start` `effort` and `model_reasoning_effort` in the thread `config` on `thread/start` / `thread/resume` (Codex 0.164.0). |
 | v7.14.0             | 2.1.310            | 2026-10-25 | CC 2.1.307→2.1.310, agy 1.4.4→1.4.6, grok 1.0.67→1.0.70, OpenCode 1.19.3→1.19.4; Codex 0.164.0 unchanged. No flag the wrappers pass changed; one live turn per engine ok. Integrated: the `acp` engine (an ACP client over `@agentclientprotocol/sdk` 1.3.0), run against Kimi Code 2.3.1 (`kimi acp`, model from `KIMI_MODEL_*`), dsh 0.2.1-rc.2 (`dsh --profile acp`, `--patch` honoured) and OpenCode 1.19.4 (`opencode acp`, recall across a resumed session). Kimi Code and dsh report no usage over ACP.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | v7.13.0             | 2.1.307            | 2026-10-24 | Codex 0.163.0→0.164.0; the other engines as tracked in v7.12.1. Integrated: Codex 0.164 app-server goal RPCs (`thread/goal/set` / `get` / `clear`, six goal states, `tokenBudget`, `thread/goal/updated`), structured `error` notifications (`codexErrorInfo`, `willRetry`), `turn/steer` during goal turns, and `approvalPolicy` on `thread/start` / `thread/resume`; the `goal` workflow node is built on them. Measured: a goal objective is capped at 4,000 characters, and a thread can be resumed only after its first turn.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | v7.12.1             | 2.1.307            | 2026-10-22 | CC 2.1.302→2.1.307, agy 1.4.0→1.4.4, grok 1.0.62→1.0.67; Codex 0.163.0 and OpenCode 1.19.3 unchanged. No flag the wrappers pass changed. grok 1.0.67 makes `grok-4.7` its default and only model: registered (same prices and 500K window as `grok-4.6`), the `grok` alias moved to it, and a session with no `model` is labelled with the model grok reports. grok read-only re-measured on 1.0.67 (direct and shell writes blocked; the subagent probe hit the free-tier limit). OpenCode 2 still beta-only, still refused.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
@@ -49,8 +51,9 @@ This document tracks which Claude Code CLI version Claw Orchestrator is currentl
 When syncing to a new Claude Code CLI version:
 
 1. Run `claude --version` to confirm target version
-2. Check Claude Code changelog / release notes for new flags, events, env vars since the last tracked version
-3. Decide which features are valuable for programmatic/agent use (vs human-interactive only)
-4. Implement worthwhile features (add to `SessionConfig` → wire into `persistent-session.ts` → expose in tool schema → document)
-5. Update this file with the new version + notable integrations
-6. Update the engine tables in `AGENTS.md` and `README.md`
+2. Run `npx tsx scripts/sweep.ts` (or `--no-live` for versions and flags only) to see installed, pinned and upstream versions of every core engine, the flags each wrapper passes against the binary's `--help`, and one live turn per engine
+3. Check Claude Code changelog / release notes for new flags, events, env vars since the last tracked version
+4. Decide which features are valuable for programmatic/agent use (vs human-interactive only)
+5. Implement worthwhile features (add to `SessionConfig` → wire into `persistent-session.ts` → expose in tool schema → document)
+6. Update this file: the "Currently tracked" line and a new row with the version + notable integrations
+7. Update the tested versions: the engine table in `AGENTS.md` (the pins the sweep reads), the engine compatibility table in `README.md`, and the "Tested with" line of each engine in [multi-engine.md](./multi-engine.md)

package/skills/references/cli.md

@@ -1,6 +1,12 @@
 # CLI Reference
 
-The CLI is an HTTP client that talks to the Claw Orchestrator embedded server. In plugin mode, the server auto-starts. In standalone mode, run `clawo serve` first.
+The CLI is an HTTP client that talks to the Claw Orchestrator embedded server. Under OpenClaw, the plugin starts the server on its first tool call (unless `CLAWO_NO_EMBEDDED_SERVER=1`). In standalone mode, run `clawo serve` first. `clawo acp` and `clawo engines` run locally and do not need the server.
+
+## Connecting to the server
+
+- **Address**: commands reach the server at `CLAWO_API_URL` (default `http://127.0.0.1:18796`).
+- **Token**: every request carries the server's token, when the CLI finds one, as `Authorization: Bearer <token>`. The CLI reads it from `CLAWO_AUTH_TOKEN`, then `OPENCLAW_SERVER_TOKEN`, then `~/.openclaw/server-token`, which the server writes when it starts. See [Getting Started](./getting-started.md) for how the server chooses the token.
+- **Errors**: when the server reports an error or cannot be reached, a command prints `Failed: <error>` to stderr and exits 1. With `--json`, `session-send` and `session-status` print the JSON result instead and still exit 1.
 
 ## Server
 
@@ -8,7 +14,9 @@ The CLI is an HTTP client that talks to the Claw Orchestrator embedded server. I
 clawo serve [-p, --port <port>] [-H, --host <host>] [--ultraapp-runtime host|docker]
 ```
 
-Start standalone embedded server (default port 18796, bound to `127.0.0.1`; pass `-H 0.0.0.0` for remote access). `--ultraapp-runtime` selects how ultraapp builds run: `host` (default, spawns Node directly) or `docker`. CLI commands reach the server at `CLAWO_API_URL` (default `http://127.0.0.1:18796`).
+Start the standalone embedded server (default port 18796, bound to `127.0.0.1`, or `OPENCLAW_SERVER_HOST` when set; pass `-H 0.0.0.0` for remote access). `--ultraapp-runtime` selects how ultraapp builds run: `host` (default, spawns Node directly) or `docker`. The server also starts the ultraapp reverse-proxy router on port 19000 (or the next free port); if the router cannot start, ultraapp deploys are skipped and the server runs without it. If the server's port is already in use, `clawo serve` prints an error and exits 1.
+
+Under `clawo serve` the session manager allows 32 concurrent sessions and unloads a session after 60 idle minutes (the plugin defaults are 5 and 120). Override with `OPENCLAW_SERVE_MAX_SESSIONS` and `OPENCLAW_SERVE_TTL_MINUTES`.
 
 ### Rate Limiting
 
@@ -16,14 +24,15 @@ The embedded server limits each IP address to 300 requests per minute (sliding w
 
 ### OpenAI-Compatible API
 
-The server exposes an OpenAI-compatible chat completions endpoint, enabling any webchat frontend to use it as a backend.
+The server exposes an OpenAI-compatible chat completions endpoint, enabling any webchat frontend to use it as a backend. The full rules — session keying, `X-Session-Reset`, tool calls and environment variables — are in [openai-compat.md](./openai-compat.md).
 
 **Endpoints:**
 
-| Endpoint               | Method | Description                                  |
-| ---------------------- | ------ | -------------------------------------------- |
-| `/v1/chat/completions` | POST   | Chat completions (streaming + non-streaming) |
-| `/v1/models`           | GET    | List available models                        |
+| Endpoint               | Method | Description                                                                                            |
+| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------ |
+| `/v1/chat/completions` | POST   | Chat completions (streaming + non-streaming)                                                           |
+| `/v1/models`           | GET    | List available models                                                                                  |
+| `/v1/sessions`         | GET    | List the live OpenAI-compatible sessions, each with turns, tokens, cached tokens, context use and cost |
 
 **Request format** (same as OpenAI):
 
@@ -42,17 +51,17 @@ The server exposes an OpenAI-compatible chat completions endpoint, enabling any
 3. A hash of the model, system prompt and tool definitions (`sys-<hash>`)
 4. `default`, when all of those are empty
 
-**Model routing:** The `model` field auto-routes to the correct engine:
+An `X-Session-Reset: 1` (or `true`) header answers the request from a fresh session: the session under that key is stopped first, and the fresh one is stopped once the reply is sent.
+
+**Model routing:** The `model` field picks the engine. A model id or alias in the model registry routes to the engine it is registered under (`opus` → Claude, `gemini-3.8-flash` / `agy-pro` → Antigravity), and an `agy/` prefix always selects Antigravity (`agy`). Other names route by prefix:
 
-- `claude-*`, `opus`, `sonnet`, `haiku` → Claude engine
-- `gpt-*`, `o3*`, `o4*`, `codex*` → Codex engine
+- `gpt*`, `o3*`, `o4*`, `codex*` → Codex engine
 - `grok*` → Grok engine
-- `composer*`, `cursor*`, `auto` → Cursor engine (legacy)
-- `agy/*`, the `agy-flash` / `agy-pro` aliases, and the registered Antigravity models (e.g. `gemini-3.8-flash`, `gemini-3.1-pro`) → Antigravity (`agy`) engine
-- other `gemini*` → the legacy `gemini` engine (Gemini CLI is sunset; prefer `agy`)
+- any other name containing `gemini` → the legacy `gemini` engine (Gemini CLI is sunset; prefer `agy/<model>` or a registered Antigravity model)
+- `composer*`, `cursor*`, `auto` → the legacy `cursor` engine
 - anything else → Claude engine
 
-**CORS:** `/v1/` paths allow cross-origin requests by default. Set `OPENCLAW_CORS_ORIGINS=*` to allow all origins on all paths.
+**CORS:** `/v1/` paths allow cross-origin requests by default, and `localhost` origins are allowed on every path. Set `OPENCLAW_CORS_ORIGINS=*` to allow all origins on all paths.
 
 **Auto-compact:** When a session's context utilization exceeds 80%, the endpoint automatically compacts the session before sending the next message.
 
@@ -72,38 +81,40 @@ Run as an Agent Client Protocol agent over stdio (same as the `clawo-acp` binary
 clawo session-start [name] [options]
 ```
 
-| Flag                            | Description                                                                                     |
-| ------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `-d, --cwd <dir>`               | Working directory                                                                               |
-| `-e, --engine <engine>`         | Engine: `claude` (default), `codex`, `codex-app`, `agy`, `grok`, `opencode`, `acp`, or `custom` |
-| `-m, --model <model>`           | Model name or alias                                                                             |
-| `--permission-mode <mode>`      | `acceptEdits` (default), `plan`, `auto`, `bypassPermissions`, `manual`, `dontAsk`               |
-| `--effort <level>`              | `low`, `medium`, `high`, `xhigh`, `max`, `ultra`, `auto`                                        |
-| `--allowed-tools <tools>`       | Comma-separated tool whitelist                                                                  |
-| `--disallowed-tools <tools>`    | Comma-separated tools to deny                                                                   |
-| `--max-turns <n>`               | Max agent loop turns                                                                            |
-| `--max-budget <usd>`            | API cost ceiling                                                                                |
-| `--system-prompt <text>`        | Replace system prompt                                                                           |
-| `--append-system-prompt <text>` | Append to system prompt                                                                         |
-| `--agents <json>`               | Custom sub-agents JSON                                                                          |
-| `--agent <name>`                | Default agent                                                                                   |
-| `--bare`                        | No CLAUDE.md, no git context                                                                    |
-| `-w, --worktree [name]`         | Git worktree                                                                                    |
-| `--fallback-model <model>`      | Fallback model                                                                                  |
-| `--json-schema <schema>`        | JSON Schema for structured output                                                               |
-| `--mcp-config <paths>`          | MCP config files (comma-separated)                                                              |
-| `--settings <pathOrJson>`       | Settings.json path or inline JSON                                                               |
-| `--skip-persistence`            | Do not save the session — neither the engine's transcript nor the resume registry               |
-| `--betas <headers>`             | Beta headers (comma-separated)                                                                  |
-| `--enable-agent-teams`          | Enable agent teams                                                                              |
-| `--enable-auto-mode`            | Enable auto permission mode                                                                     |
-| `--resume-session-id <id>`      | Resume an existing session by ID                                                                |
-| `--base-url <url>`              | Custom API endpoint (for proxy)                                                                 |
-| `--add-dir <dirs>`              | Comma-separated additional working directories                                                  |
-| `--custom-engine <preset>`      | With `-e custom`: the id of a bundled engine preset (see [`clawo engines`](#clawo-engines))     |
-| `--acp-agent <preset>`          | With `-e acp`: the id of a bundled ACP agent preset, e.g. `kimi-code`, `dsh`                    |
-
-The remaining `session_start` options (hook events, permission-prompt tool, debug output, `fromPr`, MCP channels, prompt-cache settings and others) are tool parameters only and have no CLI flag. See [Tools Reference](./tools.md#session_start).
+`name` defaults to `session-<timestamp>`. Starting a name that is already live returns that session unchanged; a name in the resume registry resumes its conversation (see [sessions.md](./sessions.md#session-persistence)).
+
+| Flag                            | Description                                                                                                 |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `-d, --cwd <dir>`               | Working directory                                                                                           |
+| `-e, --engine <engine>`         | Engine: `claude` (default), `codex`, `codex-app`, `agy`, `grok`, `opencode`, `acp`, or `custom`             |
+| `-m, --model <model>`           | Model name or alias                                                                                         |
+| `--permission-mode <mode>`      | `acceptEdits` (default), `plan`, `auto`, `bypassPermissions`, `manual`, `dontAsk`                           |
+| `--effort <level>`              | `low`, `medium`, `high`, `xhigh`, `max`, `ultra`, `auto` (default); each engine clamps it to its own ladder |
+| `--allowed-tools <tools>`       | Comma-separated tools to auto-approve                                                                       |
+| `--disallowed-tools <tools>`    | Comma-separated tools to deny                                                                               |
+| `--max-turns <n>`               | Max agent loop turns                                                                                        |
+| `--max-budget <usd>`            | Spend cap in USD, checked before every send on every engine                                                 |
+| `--system-prompt <text>`        | Replace system prompt                                                                                       |
+| `--append-system-prompt <text>` | Append to system prompt                                                                                     |
+| `--agents <json>`               | Custom sub-agents JSON                                                                                      |
+| `--agent <name>`                | Default agent                                                                                               |
+| `--bare`                        | Claude Code minimal mode: skips hooks, LSP, auto-memory and CLAUDE.md discovery                             |
+| `-w, --worktree [name]`         | Git worktree                                                                                                |
+| `--fallback-model <model>`      | Fallback model                                                                                              |
+| `--json-schema <schema>`        | JSON Schema for structured output                                                                           |
+| `--mcp-config <paths>`          | MCP config files (comma-separated)                                                                          |
+| `--settings <pathOrJson>`       | Settings.json path or inline JSON                                                                           |
+| `--skip-persistence`            | Keep the session out of the resume registry; Claude Code and Codex also skip writing their own transcript   |
+| `--betas <headers>`             | Beta headers (comma-separated)                                                                              |
+| `--enable-agent-teams`          | Enable agent teams                                                                                          |
+| `--enable-auto-mode`            | Enable auto permission mode                                                                                 |
+| `--resume-session-id <id>`      | Resume an earlier conversation by the engine's own id (Claude session id, Codex thread id, …)               |
+| `--base-url <url>`              | Custom API endpoint (for proxy)                                                                             |
+| `--add-dir <dirs>`              | Comma-separated additional working directories                                                              |
+| `--custom-engine <preset>`      | With `-e custom`: the id of a bundled engine preset (see [`clawo engines`](#clawo-engines))                 |
+| `--acp-agent <preset>`          | With `-e acp`: the id of a bundled ACP agent preset, e.g. `kimi-code`, `dsh`                                |
+
+Most of these flags map to Claude Code options; [multi-engine.md](./multi-engine.md) lists which ones each other engine honours. The remaining `session_start` options (`sandboxMode`, `autoCompactPercent`, `ultracode`, hook events, permission-prompt tool, debug output, `fromPr`, MCP channels, prompt-cache settings and others) are tool parameters only and have no CLI flag. See [Tools Reference](./tools.md#session_start).
 
 ### session-send
 
@@ -112,16 +123,16 @@ clawo session-send <name> <message> [options]
 clawo session-send <name> --message-file <file> [options]
 ```
 
-| Flag                    | Description                                                                  |
-| ----------------------- | ---------------------------------------------------------------------------- |
-| `--message-file <file>` | Read the message from a file (long text, or text starting with `-`)          |
-| `--effort <level>`      | Override effort for this message                                             |
-| `--plan`                | Enable plan mode                                                             |
-| `-s, --stream`          | Collect streaming chunks                                                     |
-| `-t, --timeout <ms>`    | Timeout (default 300000)                                                     |
-| `--json`                | Print the whole result (`ok`, `output`, `sessionId`, `error`, …) as one line |
+| Flag                    | Description                                                                                                                                  |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--message-file <file>` | Read the message from a file (long text, or text starting with `-`)                                                                          |
+| `--effort <level>`      | Override effort for this message                                                                                                             |
+| `--plan`                | Ask for a plan only: Claude Code and persistent custom engines get a plan-only instruction in front of the message; other engines ignore it  |
+| `-s, --stream`          | Accepted, but has no effect: the server returns the reply when the turn ends, with no streamed chunks                                        |
+| `-t, --timeout <ms>`    | Turn timeout (default 300000)                                                                                                                |
+| `--json`                | Print the whole result as one line, including `ok`, `output`, `sessionId`, `error`, and `permissionDenials` / `images` when the turn had any |
 
-Every command that fails prints `Failed: …` and exits 1.
+`--plan` does not change the permission mode. For a session that cannot write, start it with `--permission-mode plan` (Claude Code, Grok) or the `sandboxMode: 'read-only'` tool parameter.
 
 ### session-stop
 
@@ -129,19 +140,23 @@ Every command that fails prints `Failed: …` and exits 1.
 clawo session-stop <name>
 ```
 
+Stops the session and removes it from the resume registry, so a later `session-start` with the same name begins a new conversation.
+
 ### session-list
 
 ```bash
 clawo session-list
 ```
 
+Lists the server's live sessions as `name — model (cwd)`. Sessions held only in the resume registry are not listed.
+
 ### session-status
 
 ```bash
 clawo session-status <name> [--json]
 ```
 
-`--json` prints the whole status (`stats` with turns, tool calls, tokens, cost and the engine's resume id) as one line.
+Prints turns, tool calls, cost, tokens and uptime. `--json` prints the whole status as one line: `name`, `cwd`, `model`, `created`, `claudeSessionId` (the engine's resume id), `costUsd` (and `budgetUsd` / `budgetExhausted` when a spend cap is set), and `stats` with turns, `turnsSucceeded`, tool calls, tokens, `contextPercent`, uptime and the engine's own conversation id.
 
 ### session-grep
 
@@ -149,12 +164,16 @@ clawo session-status <name> [--json]
 clawo session-grep <name> <pattern> [-n, --limit <n>]
 ```
 
+Case-insensitive regular-expression search over the session's recent event history (`--limit` default 50). Prints the time and event type of each match.
+
 ### session-compact
 
 ```bash
 clawo session-compact <name> [--summary <text>]
 ```
 
+Compacts the conversation; `--summary` is passed to the engine's compaction (`/compact <summary>` on Claude Code). Engines without compaction do nothing — see [sessions.md](./sessions.md#context-management).
+
 ## Run Ledger
 
 ```bash
@@ -164,33 +183,28 @@ clawo runs [-s, --since <window>] [-n, --limit <n>] [--session <name>] [--engine
 Show the durable per-turn record kept at `~/.claw-orchestrator/runs/`. Unlike
 `session-status`, this survives restarts and covers sessions this process never
 owned. `--since` takes `30m` / `24h` / `7d` / `2w` or an ISO timestamp (default
-`24h`); `--parent` filters to one council / fanout / autoloop / workflow run;
-`--verified` / `--refuted` keep only turns whose acceptance contract passed /
-failed. Costs marked with a trailing `~` came from estimated token counts. The
-`VERIFIED` column reads `yes`, `NO`, or `—` ("no contract was declared, so
-nothing checked it"). See [observability.md](observability.md).
+`24h`); `--limit` caps the rows (default 50); `--parent` filters to one council /
+fanout / autoloop / workflow run; `--verified` / `--refuted` keep only turns whose
+acceptance contract passed / failed. Costs marked with a trailing `~` came from
+estimated token counts. The `VERIFIED` column reads `yes`, `NO`, or `—` ("no
+contract was declared, so nothing checked it"). `--json` prints `{ rows, summary }`.
+See [observability.md](observability.md).
 
-## Agent Management
+## Agents, Skills and Rules
 
 ```bash
 clawo agents-list [-d, --cwd <dir>]
-clawo agents-create <name> [--description <desc>] [--prompt <prompt>]
-```
+clawo agents-create <name> [-d, --cwd <dir>] [--description <desc>] [--prompt <prompt>]
 
-## Skills Management
-
-```bash
 clawo skills-list [-d, --cwd <dir>]
-clawo skills-create <name> [--description <desc>] [--prompt <prompt>] [--trigger <t>]
-```
-
-## Rules Management
+clawo skills-create <name> [-d, --cwd <dir>] [--description <desc>] [--prompt <prompt>] [--trigger <t>]
 
-```bash
 clawo rules-list [-d, --cwd <dir>]
-clawo rules-create <name> [--description <desc>] [--content <text>] [--paths <glob>] [--condition <expr>]
+clawo rules-create <name> [-d, --cwd <dir>] [--description <desc>] [--content <text>] [--paths <glob>] [--condition <expr>]
 ```
 
+These manage Claude Code's `.claude/agents/`, `.claude/skills/` and `.claude/rules/` directories. With `-d`, the create commands write under `<dir>/.claude/`; without it, under the user-level `~/.claude/`. The list commands show the entries under `<dir>/.claude/` first, then the user-level entries whose name the project does not define. A rule's `--paths` and `--condition` become its `paths:` and `if:` frontmatter.
+
 ## Agent Teams
 
 ```bash
@@ -198,11 +212,7 @@ clawo session-team-list <name>
 clawo session-team-send <name> <teammate> <message>
 ```
 
-## Tools Without a CLI Command
-
-Tools without a CLI command are reachable through the OpenClaw plugin, the MCP
-server (`clawo-mcp`, see [mcp.md](./mcp.md)), or the `SessionManager` API. See
-[Tools Reference](./tools.md) for full parameter documentation.
+`session-team-list` lists the server's other live sessions as virtual teammates, with each one's engine, state and turn count. `session-team-send` delivers a message to one of them through the session inbox — at once if it is idle, queued otherwise. See [inbox.md](./inbox.md).
 
 ## `clawo solve`
 
@@ -217,16 +227,16 @@ clawo solve "<task>" [--engine <engine[:model]>] [--check "<command>"]... [--con
 
 | Option          | Default           | Notes                                                                                                                                        |
 | --------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `-e, --engine`  | `claude`          | The implementer, `engine` or `engine:model` (`codex:gpt-6.1-sol`)                                                                            |
+| `-e, --engine`  | `claude`          | The implementer, `engine` or `engine:model` (`codex:gpt-6.1-sol`), or `acp:<preset>` for an ACP agent (`acp:kimi-code`)                      |
 | `-c, --check`   | —                 | A command check, repeatable. Split on whitespace and run as argv, never through a shell; anything that needs quoting belongs in `--contract` |
 | `--contract`    | —                 | A contract JSON file ([verification.md](./verification.md)); `--check` entries are appended to it                                            |
-| `--scouts`      | the implementer   | Comma-separated triage agents, `engine[:model]` each                                                                                         |
+| `--scouts`      | the implementer   | Comma-separated triage agents, `engine[:model]` each (`acp:<preset>` for an ACP agent)                                                       |
 | `--reviewers`   | —                 | Comma-separated reviewers of the finished change                                                                                             |
 | `--max-repairs` | `3`               | Attempts the router allows while the checks are red; `0` keeps only the first attempt                                                        |
 | `--human-gate`  | off               | Park before anything is written until `clawo workflow approve`                                                                               |
 | `--cwd`         | current directory | Project directory                                                                                                                            |
 | `-w, --wait`    | off               | Follow the run, printing each node transition, then the verdict                                                                              |
-| `--json`        | off               | Print `{ runId }`, or with `--wait` the final run record                                                                                     |
+| `--json`        | off               | Print `{ runId, state }`, or with `--wait` the final run record                                                                              |
 
 With `--wait` the exit code is the verdict: `0` when the run completed (verified,
 or unverified because no check was given), `1` when it was refuted, failed or
@@ -241,37 +251,48 @@ clawo fanout "<task>" [--engines <list>] [--synthesize] [--check "<command>"]...
              [--contract <file>] [--cwd <dir>] [--wait] [--json]
 ```
 
-`--engines` (default `claude,codex`) takes `engine[:model]` items; the same
-engine may appear more than once. With `--wait` the run is followed to the end
-and every answer is printed, followed by the synthesis when `--synthesize` was
-given. Checks run after the fan-out, as for `solve`.
+| Option             | Default           | Notes                                                                                                          |
+| ------------------ | ----------------- | -------------------------------------------------------------------------------------------------------------- |
+| `-e, --engines`    | `claude,codex`    | Comma-separated agents, `engine[:model]` each, or `acp:<preset>` for an ACP agent; an engine may repeat        |
+| `-s, --synthesize` | off               | Merge the answers in a final pass. It runs only when at least two agents answered                              |
+| `-c, --check`      | —                 | A command check, repeatable, run after the fan-out, as for `solve`                                             |
+| `--contract`       | —                 | A contract JSON file; `--check` entries are appended to it                                                     |
+| `--cwd`            | current directory | Project directory                                                                                              |
+| `-w, --wait`       | off               | Follow the run to the end, then print every answer under a `## <agent>` heading — or the synthesis, if one ran |
+| `--json`           | off               | Print `{ runId, state }`, or with `--wait` the final run record                                                |
 
 ## `clawo goal`
 
-Run a Codex `/goal` on one `codex-app` thread, then have the runtime check the
-result: goal → verify → repair on the same thread. See [workflow.md](./workflow.md#goal).
+Run a `/goal` on one thread — a Codex `codex-app` thread, or a Claude Code
+session with `--engine claude` — then have the runtime check the result: goal →
+verify → repair on the same thread. See [workflow.md](./workflow.md#goal).
 
 ```bash
 clawo goal "<objective>" | --objective-file <file>
            [--check "<command>"]... [--contract <file>] [--check-timeout <minutes>]
-           [--launcher <arg>]... [--model <model>] [--effort <level>] [--sandbox <mode>] [--thread <id>]
+           [--engine codex|claude] [--launcher <arg>]... [--model <model>] [--effort <level>] [--sandbox <mode>] [--thread <id>]
            [--token-budget N] [--goal-timeout <minutes>] [--max-repairs N]
            [--cwd <dir>] [--wait] [--json]
 ```
 
-| Option             | Default           | Notes                                                                                                               |
-| ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `--objective-file` | —                 | Read the objective from a file instead of the argument. Codex accepts at most 4,000 characters                      |
-| `-c, --check`      | —                 | A command check, repeatable, run after the goal. Split on whitespace; quote-needing commands go in `--contract`     |
-| `--check-timeout`  | 10                | Minutes for each `--check`. The verifier's node timeout is sized from the checks                                    |
-| `--launcher`       | —                 | Run codex under this command, one argv element per flag: `--launcher ./sandbox.sh --launcher task --launcher "0 1"` |
-| `-m, --model`      | codex's own       | Codex model                                                                                                         |
-| `--sandbox`        | `workspace-write` | Codex's own sandbox mode. With an outer sandbox as the boundary, `danger-full-access`                               |
-| `--thread`         | —                 | Start on this existing codex thread: its goal is replaced, its history kept                                         |
-| `--token-budget`   | —                 | The goal stops as `budgetLimited` past this                                                                         |
-| `--goal-timeout`   | none              | Wall-clock minutes for one goal pass                                                                                |
-| `--max-repairs`    | `1`               | Times a red verdict sends the goal back to the same thread                                                          |
-| `-w, --wait`       | off               | Follow the run; exit `0` only if it completes                                                                       |
+| Option             | Default           | Notes                                                                                                                    |
+| ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `--objective-file` | —                 | Read the objective from a file instead of the argument. A goal accepts at most 4,000 characters                          |
+| `-e, --engine`     | `codex`           | Who runs the goal: `codex` (a `codex-app` thread) or `claude` (a Claude Code session)                                    |
+| `-c, --check`      | —                 | A command check, repeatable, run after the goal. Split on whitespace; quote-needing commands go in `--contract`          |
+| `--contract`       | —                 | A contract JSON file; `--check` entries are appended to it                                                               |
+| `--check-timeout`  | 10                | Minutes for each `--check` (at least 1). The verifier's node timeout is sized from the checks                            |
+| `--launcher`       | —                 | Run the engine under this command, one argv element per flag: `--launcher ./sandbox.sh --launcher task --launcher "0 1"` |
+| `-m, --model`      | the engine's own  | Model                                                                                                                    |
+| `--effort`         | the engine's own  | Reasoning effort                                                                                                         |
+| `--sandbox`        | `workspace-write` | Codex's own sandbox mode (claude has none). With an outer sandbox as the boundary, `danger-full-access`                  |
+| `--thread`         | —                 | Start on this existing codex thread or claude session: its goal is replaced, its history kept                            |
+| `--token-budget`   | —                 | The goal stops as `budgetLimited` past this                                                                              |
+| `--goal-timeout`   | none              | Wall-clock minutes for one goal pass                                                                                     |
+| `--max-repairs`    | `1`               | Times a red verdict sends the goal back to the same thread                                                               |
+| `--cwd`            | current directory | Project directory                                                                                                        |
+| `-w, --wait`       | off               | Follow the run; exit `0` only if it completes                                                                            |
+| `--json`           | off               | Print `{ runId, state }`, or with `--wait` the final run record                                                          |
 
 `clawo workflow show <runId>` prints the goal's status, tokens, time, resume
 attempts and thread id while it runs; `clawo workflow steer <runId> "<text>"`
@@ -288,9 +309,12 @@ clawo workflow steer <runId> "<text>"  # a correction for the next agent node, o
 clawo workflow approve <runId> [reject]
 ```
 
-`list` prints one row per run with its outcome as `verified` / `REFUTED` /
-`unchecked`. `unchecked` means no acceptance contract was declared — it is not a
-failure.
+`list` prints one row per run (default limit 25) with its outcome as `verified` /
+`REFUTED` / `unchecked`. `unchecked` means no acceptance contract was declared — it
+is not a failure.
+
+`approve` answers the gate a run is parked on: it approves unless the last
+argument is `reject`, `false` or `no`.
 
 Runs survive restarts, so `list` sees runs started by other processes and by
 earlier sessions.
@@ -301,10 +325,11 @@ earlier sessions.
 clawo verify <runId> [--evidence <id>] [--json]
 ```
 
-Prints the evidence bundle: per-check pass/fail with the failing command and the
-lines of its output that say why (an assertion message, an error line — the last
-few lines when nothing stands out), the base and head commits, and the files the run changed (created
-files included).
+Prints the evidence bundle (the run's latest unless `--evidence` names one):
+per-check pass/fail with the failing command and the lines of its output that say
+why (an assertion message, an error line — the last few lines when nothing stands
+out), the base and head commits, and the files the run changed (created files
+included).
 
 ## `clawo engines`
 
@@ -324,3 +349,9 @@ A preset id is the only form of custom engine or ACP agent the CLI can pass: it
 session through the HTTP surface, which refuses inline configs because those name
 a binary and its arguments. See [multi-engine.md](./multi-engine.md) for the tiers
 and what a community preset does and does not claim.
+
+## Tools Without a CLI Command
+
+Tools without a CLI command are reachable through the OpenClaw plugin, the MCP
+server (`clawo-mcp`, see [mcp.md](./mcp.md)), or the `SessionManager` API. See
+[Tools Reference](./tools.md) for full parameter documentation.

package/skills/references/council.md

@@ -48,13 +48,23 @@ project/
 
 Agents cannot interfere with each other's files. All integration happens via `git merge` to `main`.
 
+If `projectDir` does not exist it is created; if it is not a git repository the council runs `git init`, and if
+the repository has no commit yet it commits whatever the directory holds. Commits need a git identity: when the
+repository has none at any level, the council sets a local `Council <council@openclaw>` in `.git/config`; an
+identity you configured is left untouched. Agent names become branch names, so they must match
+`^[a-zA-Z0-9_-]+$`. A council refuses to start with a `projectDir` inside the orchestrator's own package
+directory.
+
 ### Consensus Voting
 
 Every agent must include `[CONSENSUS: YES]` or `[CONSENSUS: NO]` at the end of each round's response. The council continues until:
 
-- **All agents vote YES** — consensus reached
-- **Max rounds reached** — timeout
-- **Aborted** — user intervention
+- **All agents vote YES** — consensus reached; status becomes `awaiting_user` (ready for review / accept / reject)
+- **Max rounds reached** — status `max_rounds`
+- **Aborted** — user intervention; status `error`
+
+An agent that fails or errors in a round counts as a NO for that round. A loosely formatted vote (for example
+`CONSENSUS=YES`) is still read, and a missing vote counts as NO.
 
 ## Quick Start
 
@@ -99,9 +109,12 @@ console.log(`Council started: ${session.id}`);
 const status = manager.councilStatus(session.id);
 ```
 
+`councilStart`, `fanoutStart`, `ultraplanStart` and `ultrareviewStart` are async (each creates a durable run before
+returning); direct TypeScript callers need `await`.
+
 ### Mixed Engines
 
-Agents can use different engines and models:
+Agents can use different engines and models. Each agent also accepts `effort` and, on Claude, `ultracode`:
 
 ```json
 {
@@ -115,15 +128,15 @@ Agents can use different engines and models:
 
 ## Council Tools
 
-| Tool             | Description                                                                             |
-| ---------------- | --------------------------------------------------------------------------------------- |
-| `council_start`  | Start a council. Runs in background, returns session ID immediately.                    |
-| `council_status` | Get current status (running/consensus/max_rounds/error), responses, votes.              |
-| `council_abort`  | Stop all agent sessions and terminate the council.                                      |
-| `council_inject` | Inject a user message into all agents' prompts in the next round.                       |
-| `council_review` | Review completed council output: changed files, branches, plan status, agent summaries. |
-| `council_accept` | Accept work and clean up: remove worktrees, branches, plan.md, reviews/.                |
-| `council_reject` | Reject work: rewrite plan.md with feedback for the council to retry.                    |
+| Tool             | Description                                                                                                             |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `council_start`  | Start a council. Runs in background, returns session ID immediately.                                                    |
+| `council_status` | Status (`running`, `awaiting_user`, `max_rounds`, `error`, `accepted`, `rejected`) and each response with its vote.     |
+| `council_abort`  | Stop all agent sessions, terminate a council running in this process, and remove the worktrees it created.              |
+| `council_inject` | Inject a user message into all agents' prompts in the next round. A second inject before that round replaces the first. |
+| `council_review` | Review completed council output: changed files, branches, plan status, agent summaries.                                 |
+| `council_accept` | Accept work and clean up: remove worktrees, branches, plan.md, reviews/.                                                |
+| `council_reject` | Reject work: rewrite plan.md with feedback for the council to retry.                                                    |
 
 ## Post-Processing Lifecycle
 
@@ -143,6 +156,7 @@ Returns a structured report:
 - **planContent**: full plan.md text (check for unchecked tasks)
 - **reviews**: review files in `reviews/` directory
 - **agentSummaries**: final-round output preview from each agent
+- **reviewerGuidance**: the checklist from `configs/council-reviewer-prompt.md`, for whoever reviews the output
 
 ### 2. Accept
 
@@ -150,14 +164,14 @@ Returns a structured report:
 { "tool": "council_accept", "args": { "id": "<council-id>" } }
 ```
 
-Cleans up all council scaffolding:
+Checks out `main` (or `master`), then cleans up all council scaffolding:
 
 - Removes the worktrees under `{projectDir}/.worktrees/`, and that directory —
   selection is by containment, so a worktree of yours that merely has `council`
   somewhere in its path is never touched
 - Deletes all `council/*` branches
 - Removes `plan.md` and `reviews/` directory
-- Sets council status to `accepted`
+- Sets council status to `accepted`, recorded on the run so `council_status` reports it
 
 ### 3. Reject
 
@@ -165,7 +179,7 @@ Cleans up all council scaffolding:
 { "tool": "council_reject", "args": { "id": "<council-id>", "feedback": "..." } }
 ```
 
-Rewrites `plan.md` with rejection feedback and commits it. All worktrees and branches are preserved so the council can be restarted to address the feedback.
+Rewrites `plan.md` with rejection feedback and commits it, and sets council status to `rejected`, recorded on the run. All worktrees and branches are preserved so the council can be restarted to address the feedback: a new `council_start` on the same `projectDir` with the same agent names reuses those worktrees (resetting each to its branch head, which discards uncommitted changes in them).
 
 ## Configuration
 
@@ -176,6 +190,8 @@ Rewrites `plan.md` with rejection feedback and commits it. All worktrees and bra
 | `maxTurnsPerAgent` | 50                 | Max tool turns per agent per round |
 | `maxBudgetUsd`     | —                  | API spend limit per agent          |
 
+These are the `council_start` defaults. The `council` workflow template (`workflow_start`) runs up to 8 rounds.
+
 ### defaultPermissionMode
 
 Optional. Sets the default permission mode for council agents when individual agents don't specify one. Defaults to `bypassPermissions`.
@@ -238,18 +254,24 @@ workflow_start({
 
 Without a contract the run completes `unverified` — nothing checked it.
 
-`councilStart`, `fanoutStart`, `ultraplanStart` and `ultrareviewStart` are
-async (each creates a durable run before returning); direct TypeScript callers
-need `await`.
-
 ## Durable runs
 
 A council is a durable kernel run. `GET /council/list` (and the dashboard)
 returns real records from disk, across processes.
 
+| Route                      | Purpose                                                                                                                                                                |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET /council/list`        | Every council run, newest first.                                                                                                                                       |
+| `POST /council/new`        | Body `{ task, projectDir, maxRounds? }`. Starts the dashboard preset: three Claude agents, 15 rounds by default.                                                       |
+| `GET /council/<id>/state`  | The council session (status, config, responses).                                                                                                                       |
+| `GET /council/<id>/events` | SSE: a `snapshot`, then a `council-event` for each session, round and agent event (output chunks included). Only for a council running in this process; 404 otherwise. |
+
 `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.
+they act on the git state the council left behind, not on live agents, and the
+accept / reject decision is written to the run record.
+`council_inject` and `council_abort` need the live run and say so plainly when
+there is none: `council_abort` then returns `ok: false` with the run's state and
+leaves the run and its worktrees as they are.
 
 ## Changed-file reporting