@enderfga/claw-orchestrator 7.12.1 → 7.14.0

package/dist/src/types.d.ts

@@ -8,7 +8,7 @@ export declare const MODEL_ALIASES: Record<string, string>;
 export type PermissionMode = 'acceptEdits' | 'bypassPermissions' | 'default' | 'manual' | 'dontAsk' | 'plan' | 'auto';
 export declare const EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max", "ultra", "auto"];
 export type EffortLevel = (typeof EFFORT_LEVELS)[number];
-export declare const ENGINE_TYPES: readonly ["claude", "codex", "codex-app", "gemini", "agy", "cursor", "grok", "opencode", "custom"];
+export declare const ENGINE_TYPES: readonly ["claude", "codex", "codex-app", "gemini", "agy", "cursor", "grok", "opencode", "custom", "acp"];
 export type EngineType = (typeof ENGINE_TYPES)[number];
 /** Common execution binding shared by every directly configured agent. */
 export interface AgentBinding {
@@ -159,6 +159,26 @@ export interface CustomEngineConfig {
      */
     sanitizePatterns?: string[];
 }
+export interface AcpAgentConfig {
+    /** Display name (logs, session ids). */
+    name: string;
+    /** Command name or path that serves ACP on stdio, e.g. 'kimi'. */
+    command: string;
+    /** Environment variable that overrides `command` at runtime, e.g. 'KIMI_BIN'. */
+    commandEnv?: string;
+    /** Arguments after the command, e.g. ['acp']. */
+    args?: string[];
+    /** Extra environment for the process. */
+    env?: Record<string, string>;
+    /** Context window in tokens, when the agent does not report one. */
+    contextWindow?: number;
+    /** Price per million tokens, used only when the agent reports no cost. */
+    pricing?: {
+        input: number;
+        output: number;
+        cached?: number;
+    };
+}
 /**
  * One entry of Claude Code's `--agents` JSON, passed to the CLI verbatim.
  *
@@ -319,6 +339,12 @@ export interface SessionConfig {
      * Defaults to 'workspace-write' for Codex.
      */
     sandboxMode?: 'read-only' | 'workspace-write' | 'danger-full-access';
+    /**
+     * Argv prefix the engine binary runs under, e.g. a sandbox wrapper:
+     * `['/opt/task/sandbox.sh', 'task', '0 1']`. Set by the caller that owns the
+     * session; never taken from an agent.
+     */
+    launcher?: string[];
     /**
      * Codex only. Named config profile from `~/.codex/config.toml`, passed as
      * `codex exec --profile <name>`. Bundles model + reasoning effort + approval +
@@ -358,6 +384,12 @@ export interface SessionConfig {
      * `src/engine-presets.ts` for what a preset promises and what it does not.
      */
     customEngine?: CustomEngineConfig | string;
+    /**
+     * The agent to run — required when engine is 'acp'. An inline config, or the
+     * id of a bundled preset from `configs/engines/` (the only form accepted over
+     * HTTP, as for `customEngine`).
+     */
+    acpAgent?: AcpAgentConfig | string;
 }
 export interface SessionStats {
     /**
@@ -437,6 +469,8 @@ export interface SessionStats {
     opencodeSessionId?: string;
     /** Grok Build session ID captured from the turn's JSON result. Reused via `--resume` for multi-turn context. */
     grokSessionId?: string;
+    /** ACP session id from `session/new`; a later session loads it with `session/load` or `session/resume`. */
+    acpSessionId?: string;
     /**
      * True when the most recent turn's token counts came from estimateTokens()
      * because the engine reported no usage. Cost derived from those counts is an

package/dist/src/types.js

@@ -22,6 +22,7 @@ export const ENGINE_TYPES = [
     'grok',
     'opencode',
     'custom',
+    'acp',
 ];
 /**
  * The executables the built-in engines actually spawn — the defaults in each
@@ -70,6 +71,7 @@ export function engineHasNativeConversation(engine, customEngine) {
         case 'opencode':
         case 'cursor':
         case 'grok':
+        case 'acp':
             return true;
         case 'custom':
             // A persistent custom engine is a long-running stdin/stdout process, so it

package/dist/src/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,YAAY,EACZ,YAAY,EACZ,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,oDAAoD;AACpD,MAAM,CAAC,MAAM,aAAa,GAA2B,UAAU,EAAE,CAAC;AAUlE,+EAA+E;AAC/E,8EAA8E;AAC9E,gFAAgF;AAChF,8EAA8E;AAC9E,0EAA0E;AAC1E,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,CAAU,CAAC;AAGjG,+EAA+E;AAE/E,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ;IACR,OAAO;IACP,WAAW;IACX,QAAQ;IACR,KAAK;IACL,QAAQ;IACR,MAAM;IACN,UAAU;IACV,QAAQ;CACA,CAAC;AAUX;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,UAAU,CAAU,CAAC;AAErH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,2BAA2B,CACzC,MAA8B,EAC9B,YAAiC;IAEjC,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,QAAQ,CAAC;QACd,KAAK,OAAO,CAAC;QACb,KAAK,WAAW,CAAC;QACjB,KAAK,KAAK,CAAC;QACX,KAAK,UAAU,CAAC;QAChB,KAAK,QAAQ,CAAC;QACd,KAAK,MAAM;YACT,OAAO,IAAI,CAAC;QACd,KAAK,QAAQ;YACX,2EAA2E;YAC3E,gEAAgE;YAChE,OAAO,YAAY,EAAE,UAAU,KAAK,IAAI,CAAC;QAC3C;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,YAAY,EACZ,YAAY,EACZ,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,oDAAoD;AACpD,MAAM,CAAC,MAAM,aAAa,GAA2B,UAAU,EAAE,CAAC;AAUlE,+EAA+E;AAC/E,8EAA8E;AAC9E,gFAAgF;AAChF,8EAA8E;AAC9E,0EAA0E;AAC1E,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,CAAU,CAAC;AAGjG,+EAA+E;AAE/E,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ;IACR,OAAO;IACP,WAAW;IACX,QAAQ;IACR,KAAK;IACL,QAAQ;IACR,MAAM;IACN,UAAU;IACV,QAAQ;IACR,KAAK;CACG,CAAC;AAUX;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,UAAU,CAAU,CAAC;AAErH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,2BAA2B,CACzC,MAA8B,EAC9B,YAAiC;IAEjC,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,QAAQ,CAAC;QACd,KAAK,OAAO,CAAC;QACb,KAAK,WAAW,CAAC;QACjB,KAAK,KAAK,CAAC;QACX,KAAK,UAAU,CAAC;QAChB,KAAK,QAAQ,CAAC;QACd,KAAK,MAAM,CAAC;QACZ,KAAK,KAAK;YACR,OAAO,IAAI,CAAC;QACd,KAAK,QAAQ;YACX,2EAA2E;YAC3E,gEAAgE;YAChE,OAAO,YAAY,EAAE,UAAU,KAAK,IAAI,CAAC;QAC3C;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC"}

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "claw-orchestrator",
   "name": "Claw Orchestrator",
-  "description": "Run Claude Code, Codex, Antigravity, Grok Build, OpenCode and custom coding CLIs as one unified runtime. Persistent sessions, multi-engine orchestration, multi-agent council, worktree isolation, multi-model proxy, structured output, plan mode workflows.",
+  "description": "Run Claude Code, Codex, Antigravity, Grok Build, OpenCode, any ACP agent and custom coding CLIs as one unified runtime. Persistent sessions, multi-engine orchestration, multi-agent council, worktree isolation, multi-model proxy, structured output, plan mode workflows.",
   "enabledByDefault": false,
   "configSchema": {
     "type": "object",

package/package.json

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

package/skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: claw-orchestrator
-description: Manage persistent coding sessions across Claude Code, Codex, Antigravity (agy), Grok Build, and OpenCode engines. Use when orchestrating multi-engine coding agents, starting/sending/stopping sessions, running multi-agent council collaborations, cross-session messaging, ultraplan deep planning, ultrareview parallel code review, autoloop autonomous workspace iteration, ultraapp building deployable web apps from a structured Q&A interview, switching models/tools at runtime, exposing the orchestrator's 78 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose, or running as an Agent Client Protocol (ACP) agent that Zed / JetBrains / Neovim / Emacs / VS Code / dsh can drive directly. Triggers on "start a session", "send to session", "run council", "ultraplan", "ultrareview", "autoloop", "ultraapp", "Forge tab", "build a web app", "one-click app", "AppSpec", "autonomous iteration", "iterate until goal", "auto research", "switch model", "hand off a session", "session handoff", "switch engine", "continue on codex", "continue on claude", "move this session to another engine", "multi-agent coding", "coding session", "session inbox", "grok session", "grok build", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol", "ultracode", "dynamic workflow", "fanout", "fan-out", "best-of-N", "steer turn", "interrupt turn", "fork thread", "rollback turns", "acp", "agent client protocol", "clawo acp", "zed agent", "jetbrains agent", "external agent", "dsh subagent", "deepseek harness", "clawo runs", "run ledger", "session cost", "coding-agent token usage", "spend cap", "budget limit", "maxBudgetUsd", "durable workflow", "resume a run", "verify a coding run", "acceptance contract", "evidence bundle", "did the agent's tests actually pass", "protected tests", "agent edited the tests", "human gate", "repair loop", "clawo workflow", "clawo verify", "clawo solve", "clawo fanout", "fix and verify", "solve from the terminal".
+description: Manage persistent coding sessions across Claude Code, Codex, Antigravity (agy), Grok Build, and OpenCode engines. Use when orchestrating multi-engine coding agents, starting/sending/stopping sessions, running multi-agent council collaborations, cross-session messaging, ultraplan deep planning, ultrareview parallel code review, autoloop autonomous workspace iteration, ultraapp building deployable web apps from a structured Q&A interview, switching models/tools at runtime, exposing the orchestrator's 78 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose, or running as an Agent Client Protocol (ACP) agent that Zed / JetBrains / Neovim / Emacs / VS Code / dsh can drive directly. Triggers on "start a session", "send to session", "run council", "ultraplan", "ultrareview", "autoloop", "ultraapp", "Forge tab", "build a web app", "one-click app", "AppSpec", "autonomous iteration", "iterate until goal", "auto research", "switch model", "hand off a session", "session handoff", "switch engine", "continue on codex", "continue on claude", "move this session to another engine", "multi-agent coding", "coding session", "session inbox", "grok session", "grok build", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol", "ultracode", "dynamic workflow", "fanout", "fan-out", "best-of-N", "steer turn", "interrupt turn", "fork thread", "rollback turns", "acp", "agent client protocol", "clawo acp", "zed agent", "jetbrains agent", "external agent", "dsh subagent", "deepseek harness", "acp engine", "acp agent", "kimi code", "kimi acp", "dsh acp", "any acp agent", "clawo runs", "run ledger", "session cost", "coding-agent token usage", "spend cap", "budget limit", "maxBudgetUsd", "durable workflow", "resume a run", "verify a coding run", "acceptance contract", "evidence bundle", "did the agent's tests actually pass", "protected tests", "agent edited the tests", "human gate", "repair loop", "clawo workflow", "clawo verify", "clawo solve", "clawo fanout", "fix and verify", "solve from the terminal", "codex goal", "/goal", "clawo goal", "long-horizon goal", "unattended codex run", "goal node", "run codex in a sandbox", "launcher".
 metadata:
   {
     'openclaw':
@@ -213,15 +213,18 @@ For setup, the dsh YAML block, and the cancellation/permission limits: see [refe
 
 ## Durable workflows
 
-`workflow_start` runs a declarative graph of `agent` / `fanout` / `council` / `verifier` /
-`human_gate` / `router` / `subflow` / `autoloop` / `ultraapp_synth` /
+`workflow_start` runs a declarative graph of `agent` / `fanout` / `council` / `goal` /
+`verifier` / `human_gate` / `router` / `subflow` / `autoloop` / `ultraapp_synth` /
 `ultraapp_deploy` nodes. Every state transition is checkpointed to
 `~/.claw-orchestrator/wf/<runId>/`, so a run survives a process restart and `workflow_resume`
 picks it up at the node boundary — nodes already succeeded are not re-run, and the one that
 was in flight is retried because a half-finished node left no result to trust.
 
-Three built-in templates: `solve` (triage → implement → verify → repair-until-green →
-review), `council`, and `fanout`. Retry, per-node timeout, cancel, steer, human gates, and
+Four built-in templates: `solve` (triage → implement → verify → repair-until-green →
+review), `council`, `fanout`, and `goal` (a Codex `/goal` on one `codex-app` thread, run
+unattended for as long as it takes — reattached on resume, resumed after usage limits and
+stalls within a bound, optionally under a sandbox `launcher` — then verify → repair on the
+same thread; `clawo goal` from the terminal). Retry, per-node timeout, cancel, steer, human gates, and
 bounded loops come from the kernel rather than from each mode's own state machine.
 
 For node shapes, routing conditions, and the control surfaces:

package/skills/references/acp.md

@@ -8,6 +8,10 @@ spawns an arbitrary command as a subagent.
 The model selector spans several engines, and session modes select the
 orchestration shape: a single agent, a council, a planning pass, or a review.
 
+The other direction, the orchestrator as an ACP **client** driving an agent such
+as `kimi acp` or `dsh --profile acp`, is the `acp` engine: see
+[multi-engine.md](./multi-engine.md#acp-agents-engine-acp).
+
 ```bash
 clawo acp          # or the dedicated binary:
 clawo-acp

package/skills/references/autoloop.md

@@ -138,6 +138,19 @@ A successful increase appends exactly one `timeout_migration` record to
 pending dispatch identity when available. It does not rewrite the original
 stored spec, chat or iteration evidence, or any earlier audit bytes.
 
+A live run paused by `pause_loop` or an expired activity lease, with
+`pending_dispatch` null, continues on `autoloopResume()` / `POST /autoloop/<id>/resume`
+with no timeout fields. That resume clears the lease expiry, sets status back
+to `planning` (or `running` once subagents have been spawned), re-arms the
+activity lease from the resume, and leaves the original hard deadline where it
+was. That call returns once the run is active again; Planner chat accepted
+during the pause was parked, not delivered, and is then delivered once, in
+order, by the background drain. If the hard deadline has already passed, the
+same resume terminates the run with `hard_timeout_exceeded` and delivers
+nothing. A no-option resume of an `awaiting_resume` send-timeout pause is still
+a no-op: the pending dispatch, its reason, and the lease suspension stay as
+they are until an explicit timeout increase names that dispatch.
+
 ## Quick start
 
 Over HTTP, against `clawo serve` (default `127.0.0.1:18796`):
@@ -212,7 +225,7 @@ removes partial files, and suppresses both spawn and directives.
 | `notify_user`        | `level` ('info' / 'warn' / 'decision' / 'error'), `summary`, `detail?`, `channel?` ('auto' / 'wechat' / 'webchat' / 'both' / 'email') | Push you out-of-band.                                                                                                                                                                                                                                                                |
 | `spawn_subagents`    | `coder_engine?`, `coder_model?`, `reviewer_engine?`, `reviewer_model?`, `initial_directive?`                                          | Start Coder + Reviewer. Omitted values inherit run defaults. An engine change without a model uses the new engine's default. Once a role session has started, changing its engine/model is rejected. Custom configs cannot be emitted by Planner. Only after explicit user approval. |
 | `send_directive`     | `goal`, `constraints?`, `success_criteria?`, `max_attempts?`                                                                          | Next iter's instruction to Coder.                                                                                                                                                                                                                                                    |
-| `pause_loop`         | `reason`                                                                                                                              | Halt subloop at next iter boundary; chat keeps working.                                                                                                                                                                                                                              |
+| `pause_loop`         | `reason`                                                                                                                              | Pause the live run. Planner chat is parked during a pause and is delivered once, in order, on resume.                                                                                                                                                                                |
 | `resume_loop`        | —                                                                                                                                     | Resume after pause.                                                                                                                                                                                                                                                                  |
 | `terminate`          | `reason`                                                                                                                              | End run.                                                                                                                                                                                                                                                                             |
 | `update_push_policy` | partial PushPolicy                                                                                                                    | Mutate notification rules (e.g. when you say "tell me every iter").                                                                                                                                                                                                                  |
@@ -390,7 +403,7 @@ Every JSON artifact in the ledger carries a `schema_version` field (currently
 | `GET /autoloop/<id>/events`              | SSE: `snapshot` / `message` / `state` / `push` / `iter_done` / `planner_reply` / `planner_error` / `coder_reply` / `reviewer_reply` / `terminated`. For runs that are NOT in this process's memory (terminated, or live in another process), the endpoint emits a single-shot `snapshot` + `terminated` then closes — the dashboard's existing handlers render history without hanging. A run still in memory that has already reached `terminated` or `crashed` gets the same single-shot pair instead of an open stream that would never receive another event. Every such stream sets `retry: 864000000`, so an `EventSource` does not keep reconnecting to a stream that can only end again.                                                                                                                                                                                                                                                                                            |
 | `POST /autoloop/<id>/chat`               | **202** `{ ok, queued: true }` — body `{ text }`. Fire-and-forget: the Planner's reply streams back via the `/events` SSE channel as a `planner_reply` event (or `planner_error` on failure); the HTTP response intentionally does NOT wait for it, because first-contact replies routinely exceed reverse-proxy idle limits (e.g. Cloudflare Tunnel cuts at ~100s → 524). 400 on empty text. 404 when the run is not in this process's memory: if the store still holds it, the error says so and names `POST /autoloop/<id>/resume`; an unknown or malformed id is plain `not found`. The MCP `autoloop_chat` tool path keeps the synchronous await-and-return-reply semantics (it runs in-process).                                                                                                                                                                                                                                                                                      |
 | `GET /autoloop/<id>/resume-requirements` | `{ ok, runId, rolesNeedingCustomEngine }` — the roles whose engine was `custom`, so a caller knows which secret references a resume needs. Role names only; nothing sensitive. 404 when there is no such run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `POST /autoloop/<id>/resume`             | `{ ok, state }` — restore the role engine/model choices from the run's spec and re-create dispatcher + runner. For recoverable send timeouts, body fields `send_timeout_ms` and `pending_dispatch_id` apply the increase-only migration described above; `allow_decrease`, lease overrides, and hard-cap overrides are rejected. A custom-engine config is never persisted and is never accepted over HTTP, so a role using `custom` is re-supplied by **reference**: `plannerCustomEngineRef` / `coderCustomEngineRef` / `reviewerCustomEngineRef` name an environment variable `CLAWO_CUSTOM_ENGINE_<NAME>` on the orchestrator host, which the server reads and resolves. The name is not sensitive, the value never crosses the wire, and an unknown name is an error rather than a silent start without credentials. Existing engine-specific conversation resume behavior is reused where supported; `chat.jsonl` remains the visual history fallback. 404 when there is no such run. |
+| `POST /autoloop/<id>/resume`             | `{ ok, state }` — for a live ordinary or activity-lease pause (`pending_dispatch` null), an empty timeout body continues that run: the response returns once status is `planning` or `running` again, the lease re-arms, the hard deadline stays put, and parked Planner input is then delivered once, in order. A live `awaiting_resume` pause is unchanged unless the body increases the send timeout. Otherwise restore the role engine/model choices from the run's spec and re-create dispatcher + runner. For recoverable send timeouts, body fields `send_timeout_ms` and `pending_dispatch_id` apply the increase-only migration described above; `allow_decrease`, lease overrides, and hard-cap overrides are rejected. A custom-engine config is never persisted and is never accepted over HTTP, so a role using `custom` is re-supplied by **reference**: `plannerCustomEngineRef` / `coderCustomEngineRef` / `reviewerCustomEngineRef` name an environment variable `CLAWO_CUSTOM_ENGINE_<NAME>` on the orchestrator host, which the server reads and resolves. The name is not sensitive, the value never crosses the wire, and an unknown name is an error rather than a silent start without credentials. Existing engine-specific conversation resume behavior is reused where supported; `chat.jsonl` remains the visual history fallback. 404 when there is no such run. |
 | `POST /autoloop/<id>/delete`             | `{ ok }` — stops the loop if still live, deletes the run record from the run store, and purges the role sessions' persisted resume ids so the run cannot be resumed. The ledger directory under `<workspace>/tasks/<run_id>/` is kept on disk. 404 when there is no such run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
 The dashboard's 3-pane autoloop view (`/dashboard`) consumes these endpoints:
@@ -486,6 +499,18 @@ retried, and there is no message outbox. A gap or malformed closed tail after a
 valid prefix refuses the resume with a fixed generic error before any new
 session or effect; ledger text is never echoed into the error.
 
+**Accepted chat survives stop and owner loss.** `autoloop_chat` and `POST
+/autoloop/:id/chat` accept a message only once it is in the run's checkpoint;
+otherwise they fail (`autoloop chat could not be persisted`, or a stopping,
+restoring or limit error) and nothing is sent. Up to 1,000 entries and 8 MiB
+can be pending. Chat that was not yet handed to the Planner is delivered once,
+in order, after a resume. Chat that was being delivered when the run stopped is
+not resent: the status gains `unconfirmed_chat` (`count`, `last_at`,
+`history_pending`) and chat history gets one system notice asking to re-send it
+if needed. No further chat is handed over until that notice is recorded; if it
+cannot be written the run pauses with `chat_notice_pending`, and a plain resume
+retries it.
+
 ## Known limitations
 
 - **`webchat` channel is a no-op.** No webchat session id is carried at the run

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.307** (as of 2026-10-22, plugin v7.12.1)
+## Currently tracked: **Claude Code CLI 2.1.310** (as of 2026-10-25, plugin v7.14.0)
 
 ## Sync history
 
 | Plugin Version      | Claude CLI Version | Date       | Notable integrations                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | ------------------- | ------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | v7.12.0             | 2.1.302            | 2026-10-17 | CC 2.1.296→2.1.302, Codex 0.162.1→0.163.0, agy 1.3.2→1.4.0, grok 1.0.50→1.0.62, OpenCode 1.19.0→1.19.3. No flag the wrappers pass changed. grok read-only re-measured on 1.0.62 (direct, shell and subagent writes blocked; the failed-sandbox warning unchanged). OpenCode 2 still beta-only, still refused. Codex 0.163.0 turns Daybreak (security programme, not a model) on for eligible accounts; billing follows the model codex reports.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | v7.11.0             | 2.1.296            | 2026-10-11 | CC 2.1.295→2.1.296, Codex 0.162.0→0.162.1, OpenCode 1.18.35→1.19.0; agy 1.3.2 and grok 1.0.50 unchanged. No flag the wrappers pass changed. OpenCode 1.19.0 offers `opencode upgrade --major` to OpenCode 2 (beta builds `0.0.0-beta-N`, replaces V1): measured on 0.0.0-beta-17823 it drops `step_finish` and `--variant`, and its free tier answers 403 to a custom agent, so the read-only agent is unverifiable — the OpenCode session now refuses a V2 binary at start.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

package/skills/references/cli.md

@@ -72,35 +72,36 @@ 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`, 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)) |
+| 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).
 
@@ -108,14 +109,19 @@ The remaining `session_start` options (hook events, permission-prompt tool, debu
 
 ```bash
 clawo session-send <name> <message> [options]
+clawo session-send <name> --message-file <file> [options]
 ```
 
-| Flag                 | Description                      |
-| -------------------- | -------------------------------- |
-| `--effort <level>`   | Override effort for this message |
-| `--plan`             | Enable plan mode                 |
-| `-s, --stream`       | Collect streaming chunks         |
-| `-t, --timeout <ms>` | Timeout (default 300000)         |
+| 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 |
+
+Every command that fails prints `Failed: …` and exits 1.
 
 ### session-stop
 
@@ -132,9 +138,11 @@ clawo session-list
 ### session-status
 
 ```bash
-clawo session-status <name>
+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.
+
 ### session-grep
 
 ```bash
@@ -238,6 +246,37 @@ 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`.
 
+## `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).
+
+```bash
+clawo goal "<objective>" | --objective-file <file>
+           [--check "<command>"]... [--contract <file>] [--check-timeout <minutes>]
+           [--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                                                                       |
+
+`clawo workflow show <runId>` prints the goal's status, tokens, time, resume
+attempts and thread id while it runs; `clawo workflow steer <runId> "<text>"`
+goes into the running turn.
+
 ## `clawo workflow`
 
 ```bash
@@ -245,7 +284,7 @@ clawo workflow list [--state <s>] [--workflow <name>] [--limit N] [--json]
 clawo workflow show <runId> [--json]
 clawo workflow resume <runId>          # re-attach to a run whose process died
 clawo workflow cancel <runId>
-clawo workflow steer <runId> "<text>"  # queue a correction for the next agent node
+clawo workflow steer <runId> "<text>"  # a correction for the next agent node, or into a running goal
 clawo workflow approve <runId> [reject]
 ```
 
@@ -269,7 +308,7 @@ files included).
 
 ## `clawo engines`
 
-Lists the community engine presets bundled with the installed package, with each
+Lists the community engine presets bundled with the installed package (custom engines and ACP agents), with each
 one's provenance — who attested it, against which engine version, on what date.
 Read locally rather than over HTTP, since it is a property of the package and has
 to work with no server running.
@@ -278,9 +317,10 @@ to work with no server running.
 clawo engines
 clawo engines --json
 clawo session-start my-session -e custom --custom-engine <id>
+clawo session-start my-session -e acp --acp-agent <id>     # an ACP agent preset
 ```
 
-A preset id is the only form of custom engine the CLI can pass: it reaches the
+A preset id is the only form of custom engine or ACP agent the CLI can pass: it reaches the
 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.

package/skills/references/dashboard.md

@@ -120,7 +120,11 @@ that both read the file always agree.
 Opening a run whose `status` is `terminated` (because its process has
 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`;
+and shows a green **Resume run** button in the topbar. The same button is shown
+for any live paused run, and it follows later SSE state: a pause adds it, and
+returning to an active status removes it. Timeout fields are included only when
+`pending_dispatch` exists; an ordinary or activity-lease pause resumes with
+an empty timeout body. 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.

package/skills/references/multi-engine.md

@@ -62,7 +62,7 @@ await manager.startSession({
 
 ### OpenAI Codex (`engine: 'codex'`)
 
-Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested with `codex` CLI **0.163.0**.
+Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested with `codex` CLI **0.164.0**.
 
 - Non-interactive execution via `codex exec --sandbox workspace-write --skip-git-repo-check --json`
 - Real `usage` from the `turn.completed` JSON event (input, output, cached, reasoning tokens). **These are cumulative over the thread, not per turn**, so they replace the session totals rather than being added to them; subtracting consecutive values gives one turn's prompt
@@ -102,19 +102,18 @@ await manager.startSession({
 
 ### OpenAI Codex App-Server (`engine: 'codex-app'`)
 
-Wraps `codex app-server --listen stdio:// --enable goals` as a long-running JSON-RPC subprocess. **Required for `/goal` long-horizon objective support** — Codex's exec subcommand has no slash-command surface.
+Wraps `codex app-server --listen stdio:// --enable goals` as a long-running JSON-RPC subprocess. **Required for `/goal` long-horizon objective support** — Codex's exec subcommand has no goal surface. Tested with `codex` CLI **0.164.0**.
 
 - Long-running subprocess; one `codex app-server` per session
 - JSON-RPC 2.0 over stdio with v2 protocol method names (`initialize`, `thread/start`, `turn/start`, ...)
 - Real-time streaming via `item/agentMessage/delta` notifications
 - Cumulative token tracking from `thread/tokenUsage/updated` notifications. The same notification's `last` breakdown and `modelContextWindow` drive `contextPercent`, so it reports live occupancy against the window the server enforces rather than a running total over the model's published window
 - `appendSystemPrompt` is placed at the top of the first message of a new thread (app-server has no system-prompt flag); a resumed thread already carries it
-- Goal lifecycle observation via `thread/goal/updated` and `thread/goal/cleared` notifications
-- Goal control via the `codex_goal_*` tools (which internally send the `/goal` slash command as user text — see [tools.md](./tools.md#codex-13))
-- v2 RPC tools (Codex 0.137): `codex_interrupt` (`turn/interrupt`), `codex_steer` (`turn/steer`), `codex_fork` (`thread/fork`), `codex_rollback` (`thread/rollback`), `codex_models` (`model/list`), `codex_thread_list` (`thread/list`). A `turn/completed` with `status: 'failed'` rejects the turn and increments `toolErrors`.
-- Thread resume: starting with `resumeSessionId` loads the existing thread via `thread/resume` instead of `thread/start`.
-
-> **Feature flag.** `goals` is an experimental Codex feature. The session always passes `--enable goals`; some goal commands may still fail or be ignored by the server.
+- Goals through the typed RPCs `thread/goal/set` / `get` / `clear`: setting an objective starts the server's own turn loop, which runs until the goal is `complete`, `budgetLimited`, `blocked`, `usageLimited` or `paused`. Each change arrives as `thread/goal/updated`. The `codex_goal_*` tools wrap these; the kernel's `goal` node drives them for unattended runs ([workflow.md](./workflow.md#goal))
+- `error` notifications are read as `{ error: { message, codexErrorInfo }, willRetry }`. The session keeps the last one (`lastError`, with `codexErrorInfo` as a name such as `serverOverloaded`) and emits it as `codex:error`; an error notification never throws when nothing listens for errors
+- v2 RPC tools (Codex 0.137): `codex_interrupt` (`turn/interrupt`), `codex_steer` (`turn/steer`, including into a turn the goal loop started), `codex_fork` (`thread/fork`), `codex_rollback` (`thread/rollback`), `codex_models` (`model/list`), `codex_thread_list` (`thread/list`). A `turn/completed` with `status: 'failed'` rejects the turn and increments `toolErrors`.
+- Threads are opened and resumed with `approvalPolicy: "never"`, and a server request the session cannot handle (an approval, a request for user input) gets an error reply at once: nothing here can answer one, and an unanswered request blocks its turn. The sandbox mode is the boundary.
+- Thread resume: starting with `resumeSessionId` loads the existing thread via `thread/resume` instead of `thread/start`. The id the session manager stores and replays (model switch, restart) is the app-server's own thread id. A thread resumed with an active goal continues it on its own.
 
 ```typescript
 await manager.startSession({
@@ -123,12 +122,22 @@ await manager.startSession({
   model: 'gpt-5.5',
   cwd: '/project',
 });
-// Then either:
-//   await manager.codexGoalCommand('codex-goal-task', 'build a tic-tac-toe app');
+await manager.codexGoal('codex-goal-task', { action: 'set', objective: 'build a tic-tac-toe app' });
 // or via the codex_goal_set tool:
 //   await tool('codex_goal_set', { name: 'codex-goal-task', objective: 'build a tic-tac-toe app' });
 ```
 
+### Running an engine under a launcher
+
+`SessionConfig.launcher` is an argv prefix the engine binary runs under, for every
+engine: `launcher: ['/opt/task/sandbox.sh', 'task', '0 1']` spawns
+`/opt/task/sandbox.sh task '0 1' codex app-server …`. This is how a caller puts
+the agent inside its own sandbox (bubblewrap, a container entry point, `taskset`)
+without a custom engine. The launcher is the caller's own command, at the same
+trust level as a contract's command check, which the HTTP API also accepts: set
+it through the SessionManager API, `/session/start` or a workflow spec (the `goal`
+node's `launcher`). It is not a parameter of the `session_start` tool.
+
 ### Google Antigravity (`engine: 'agy'`)
 
 Wraps Google's **Antigravity CLI** (`agy`) — the successor to Gemini CLI (consumer
@@ -307,6 +316,26 @@ await manager.startSession({
 });
 ```
 
+### ACP agents (`engine: 'acp'`)
+
+Drives any agent that serves the [Agent Client Protocol](https://agentclientprotocol.com) on stdio, with no per-agent code. Run through it so far: Kimi Code 2.3.1 (`kimi acp`), DeepSeek's dsh 0.2.1-rc.2 (`dsh --profile acp`) and OpenCode 1.19.4 (`opencode acp`). This is the client side of the protocol; [acp.md](./acp.md) is the other side, where the orchestrator is the agent.
+
+- `acpAgent` names the agent: a bundled preset id (`kimi-code`, `dsh`; `clawo engines` lists them), or, from a local caller only, an inline `{ name, command, commandEnv?, args?, env?, contextWindow?, pricing? }`. Over HTTP, which includes the `clawo` CLI, only a preset id is accepted, as for `customEngine`.
+- One agent process per session; each send is one `session/prompt` on one ACP session, so the conversation carries over between sends. `initialize` advertises no `fs` or `terminal` capability: the agent reads, writes and runs commands with its own tools.
+- A turn succeeds when the agent ends it with `stopReason: "end_turn"`; any other stop reason (`refusal`, `max_tokens`, `cancelled`, …) fails it. A turn that runs past its timeout is cancelled with `session/cancel`. An agent that exits mid-turn fails the turn and the session.
+- `session/request_permission` is answered at once from `permissionMode`: `bypassPermissions`, `acceptEdits`, `auto` and `dontAsk` pick an allow option, the others a reject option. Nothing waits on a person.
+- Resume: the agent's session id is the resume id (`stats.acpSessionId`). A resumed session reattaches it with `session/resume`, or `session/load` when that is all the agent offers; an agent with neither fails the start rather than opening a new conversation.
+- Usage and cost are whatever the agent reports (`PromptResponse.usage`, `usage_update`). With `pricing` set and no reported cost, the cost is estimated from the reported tokens. Kimi Code 2.3.1 and dsh 0.2.1-rc.2 report neither, so their sessions show 0 tokens and $0. OpenCode reports tokens.
+- The model and credentials are the agent's own configuration, set in its environment:
+  - Kimi Code: `KIMI_MODEL_NAME`, `KIMI_MODEL_API_KEY`, `KIMI_MODEL_BASE_URL`, `KIMI_MODEL_MAX_CONTEXT_SIZE`, `KIMI_MODEL_CAPABILITIES`, or a `kimi` login. `KIMI_BIN` overrides the command.
+  - dsh: `DEEPSEEK_API_KEY` (and `DEEPSEEK_BASE_URL`); its profile chooses the model. `DSH_BIN` overrides the command.
+- `launcher` applies as for every engine.
+
+```bash
+clawo session-start kimi -e acp --acp-agent kimi-code --permission-mode bypassPermissions -d ./project
+clawo session-send kimi "Fix the failing test in tests/test_io.py"
+```
+
 ### Community engine presets
 
 `customEngine` accepts either an inline `CustomEngineConfig` or the id of a preset