@enderfga/claw-orchestrator 7.14.0 → 7.16.0

package/dist/src/index.js

@@ -22,12 +22,14 @@ export { SessionManager } from './session-manager.js';
 export { PersistentClaudeSession } from './persistent-session.js';
 export { BaseOneShotSession } from './base-oneshot-session.js';
 export { PersistentCodexSession } from './persistent-codex-session.js';
+export { PersistentCodexAppServerSession } from './persistent-codex-app-session.js';
 export { PersistentGeminiSession } from './persistent-gemini-session.js';
 export { PersistentAgySession } from './persistent-agy-session.js';
 export { PersistentCursorSession } from './persistent-cursor-session.js';
 export { PersistentGrokSession } from './persistent-grok-session.js';
 export { PersistentOpencodeSession } from './persistent-opencode-session.js';
 export { PersistentCustomSession } from './persistent-custom-session.js';
+export { PersistentAcpSession } from './persistent-acp-session.js';
 export { Council, getDefaultCouncilConfig } from './council.js';
 export { AutoloopRunner } from './autoloop/runner.js';
 export { ClaudeAgentDispatcher } from './autoloop/dispatcher.js';
@@ -71,6 +73,16 @@ const ACP_AGENT_SCHEMA = {
         },
     ],
 };
+/**
+ * `acpAgent` on the surfaces that write their agents into a stored run spec
+ * (fan-out, council, workflow templates): a preset id only. An inline config can
+ * carry an environment, and the spec is written to disk.
+ */
+const AUTOLOOP_ENGINES = ENGINE_TYPES.filter((e) => e !== 'acp');
+const ACP_AGENT_ID_SCHEMA = {
+    type: 'string',
+    description: 'With engine "acp": the id of a bundled ACP agent preset (`clawo engines`), such as kimi-code or dsh.',
+};
 const CUSTOM_ENGINE_SCHEMA = {
     type: 'object',
     description: 'Custom engine config (required when the corresponding engine is "custom").',
@@ -118,13 +130,23 @@ const CUSTOM_ENGINE_SCHEMA = {
     },
     required: ['name', 'bin', 'args'],
 };
+/**
+ * `customEngine` on the surfaces that also take a preset id: session_start,
+ * session_handoff and council agents all reach `_createSession`, which expands a
+ * string through resolveCustomEngine. Autoloop roles validate an inline config
+ * and take CUSTOM_ENGINE_SCHEMA itself.
+ */
+const CUSTOM_ENGINE_OR_PRESET_SCHEMA = {
+    description: 'Custom engine (required when engine is "custom"): the id of a bundled preset (`clawo engines`), or, from a local caller only, an inline config.',
+    oneOf: [{ type: 'string', description: 'Preset id, e.g. "zcode"' }, CUSTOM_ENGINE_SCHEMA],
+};
 /**
  * OpenClaw plugin object — standard format
  */
 const plugin = {
     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-agent council, worktree isolation, multi-model proxy',
+    description: 'Run Claude Code, Codex, Antigravity, Grok Build, OpenCode, any ACP agent and custom coding CLIs as one unified runtime — persistent sessions, multi-agent council, worktree isolation, multi-model proxy',
     register(api) {
         const rawConfig = (api.pluginConfig || {});
         const registerTool = (definition) => {
@@ -216,7 +238,7 @@ const plugin = {
                     engine: {
                         type: 'string',
                         enum: ENGINE_TYPES,
-                        description: 'Engine to use (default: claude). codex = `codex exec` per send (no /goal). codex-app = long-running `codex app-server` with /goal support. agy = Google Antigravity CLI (Gemini CLI successor; plain-text output, tokens estimated, conversation resume handled automatically). opencode = sst/opencode CLI (provider-agnostic; pass model as `provider/model`). acp = any Agent Client Protocol agent, chosen with acpAgent. Use "custom" with customEngine config for any CLI.',
+                        description: 'Engine to use (default: claude). codex = `codex exec` per send (no /goal). codex-app = long-running `codex app-server` with /goal support. agy = Google Antigravity CLI (stream-json output with reported token usage; the conversation is resumed by its id on each send). grok = xAI Grok Build CLI (reports its own per-turn cost). opencode = sst/opencode CLI (provider-agnostic; pass model as `provider/model`). acp = any Agent Client Protocol agent, chosen with acpAgent. Use "custom" with customEngine config for any CLI. gemini and cursor are legacy, kept for existing callers: use agy and grok instead.',
                     },
                     model: { type: 'string', description: 'Model to use (opus, sonnet, haiku, gpt-5.5, agy-pro, etc.)' },
                     permissionMode: {
@@ -231,6 +253,16 @@ const plugin = {
                         description: 'Tools to auto-approve',
                     },
                     disallowedTools: { type: 'array', maxItems: 200, items: { type: 'string' }, description: 'Tools to deny' },
+                    tools: {
+                        type: ['string', 'array'],
+                        items: { type: 'string' },
+                        description: 'Claude engine only. The built-in tool set (`--tools`): names such as ["Bash", "Edit", "Read"], "" for none, or "default".',
+                    },
+                    addDir: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Directories the session may use besides cwd (`--add-dir`). Claude and Codex; a resumed Codex thread keeps the directories its first turn opened.',
+                    },
                     maxTurns: { type: 'number', description: 'Max agent loop turns' },
                     maxBudgetUsd: { type: 'number', description: 'Max API spend (USD)' },
                     autoCompactPercent: {
@@ -260,14 +292,24 @@ const plugin = {
                         description: 'MCP server config file(s)',
                     },
                     settings: { type: 'string', description: 'Settings.json path or inline JSON' },
+                    pluginUrl: {
+                        type: ['string', 'array'],
+                        items: { type: 'string' },
+                        description: 'Claude engine only. Plugin .zip URL(s) fetched for this session only (`--plugin-url`).',
+                    },
                     ultracode: {
                         type: 'boolean',
-                        description: 'Claude engine only. Enable "ultracode" / dynamic workflows: Claude plans a JS orchestration script per substantive task and fans out to subagents. Injected as the ultracode:true settings key (not a --effort value).',
+                        description: 'Claude engine only. Enable "ultracode" / dynamic workflows: Claude plans a JS orchestration script per substantive task and fans out to subagents. Injected as the ultracode:true settings key (not a --effort value). A workflow runs in the background: session_send returns the launch reply, and the completion arrives later in a turn that no send returns.',
                     },
                     sandboxMode: {
                         type: 'string',
                         enum: ['read-only', 'workspace-write', 'danger-full-access'],
-                        description: 'Sandbox policy. Codex supports all values; other built-in engines map read-only to their native plan/read-only mode.',
+                        description: 'Sandbox policy. Codex supports all values (default workspace-write). read-only is enforced on claude, agy, grok and opencode through their own plan/read-only modes; a custom engine must map it via permissionModes or the session refuses to start. The acp engine refuses read-only, because the agent runs its own tools; its permission answers follow permissionMode.',
+                    },
+                    launcher: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Argv prefix every engine process of this session runs under, e.g. a sandbox wrapper: ["/opt/sandbox.sh", "task"]. Any engine. It runs with your authority, like a contract command check.',
                     },
                     codexProfile: {
                         type: 'string',
@@ -356,11 +398,11 @@ const plugin = {
                         enum: ['default', 'flex', 'priority'],
                         description: 'AWS Bedrock service tier (sets ANTHROPIC_BEDROCK_SERVICE_TIER). Only effective when routing through Bedrock.',
                     },
-                    customEngine: CUSTOM_ENGINE_SCHEMA,
+                    customEngine: CUSTOM_ENGINE_OR_PRESET_SCHEMA,
                     acpAgent: ACP_AGENT_SCHEMA,
                     resumeSessionId: {
                         type: 'string',
-                        description: 'Resume an existing Claude Code session by its ID (e.g. from ~/.claude/sessions/). Replays conversation history via session/load instead of starting fresh.',
+                        description: "Resume an earlier conversation by the engine's own id instead of starting fresh: a Claude Code session id (`--resume`), a Codex or codex-app thread id, an Antigravity conversation id, a Grok or OpenCode session id, an ACP agent's session id, or a custom engine's id when its config maps a resume flag.",
                     },
                 },
             },
@@ -384,9 +426,12 @@ const plugin = {
                     effort: {
                         type: 'string',
                         enum: ['low', 'medium', 'high', 'xhigh', 'max', 'ultra'],
-                        description: 'Effort for this message',
+                        description: 'Effort for this message. agy, grok and opencode pass it to the engine for this turn; on claude, high and above prefix the message with `ultrathink` (a persistent custom engine does the same for high and max). Other engines ignore it.',
+                    },
+                    plan: {
+                        type: 'boolean',
+                        description: 'Ask for a plan only: claude and persistent custom engines prefix the message with a plan-only instruction. The permission mode is unchanged (start with sandboxMode read-only to enforce it); other engines ignore this flag.',
                     },
-                    plan: { type: 'boolean', description: 'Enable plan mode' },
                     timeout: { type: 'number', description: 'Timeout in ms (default 300000)' },
                     stream: {
                         type: 'boolean',
@@ -440,7 +485,8 @@ const plugin = {
                         type: 'number',
                         description: 'Upper bound on the carried history, in characters (default 240000, minimum 4000). When the conversation is longer, the opening request and the newest turns are kept and the turns between them are left out.',
                     },
-                    customEngine: CUSTOM_ENGINE_SCHEMA,
+                    customEngine: CUSTOM_ENGINE_OR_PRESET_SCHEMA,
+                    acpAgent: ACP_AGENT_SCHEMA,
                 },
                 required: ['name', 'engine'],
             },
@@ -452,6 +498,7 @@ const plugin = {
                     message: args.message,
                     maxChars: args.maxChars,
                     customEngine: args.customEngine,
+                    acpAgent: args.acpAgent,
                 });
                 return { ok: true, ...result };
             },
@@ -459,7 +506,7 @@ const plugin = {
         // ─── Tool: session_stop ───────────────────────────────────────────────
         registerTool({
             name: 'session_stop',
-            description: 'Stop a persistent coding session',
+            description: 'Stop a persistent coding session and remove it from the resume registry, so a later session_start under the same name begins a new conversation',
             parameters: {
                 type: 'object',
                 properties: { name: { type: 'string', description: 'Session name' } },
@@ -473,12 +520,11 @@ const plugin = {
         // ─── Tool: session_list ───────────────────────────────────────────────
         registerTool({
             name: 'session_list',
-            description: 'List all active coding sessions',
+            description: 'List the active coding sessions, and the persisted ones that a session_start under the same name resumes',
             parameters: { type: 'object', properties: {} },
             execute: async (_id) => {
-                if (!manager)
-                    return { ok: true, sessions: [], persisted: [] };
-                return { ok: true, sessions: manager.listSessions(), persisted: manager.listPersistedSessions() };
+                const m = getManager();
+                return { ok: true, sessions: m.listSessions(), persisted: m.listPersistedSessions() };
             },
         });
         // ─── Tool: sessions_overview ──────────────────────────────────────────
@@ -502,7 +548,7 @@ const plugin = {
         // ─── Tool: coding_session_status ──────────────────────────────────────
         registerTool({
             name: 'coding_session_status',
-            description: 'Get detailed status of a coding session (context %, tokens, cost, uptime)',
+            description: 'Get detailed status of a coding session: context %, tokens, cost and spend cap, turns, tool calls, retries, start time and last activity',
             parameters: {
                 type: 'object',
                 properties: { name: { type: 'string', description: 'Session name' } },
@@ -516,7 +562,7 @@ const plugin = {
         // ─── Tool: session_grep ───────────────────────────────────────────────
         registerTool({
             name: 'session_grep',
-            description: 'Search session history for events matching a regex pattern',
+            description: "Search the session's in-memory event history (its 100 most recent events) for a regex pattern, case-insensitive",
             parameters: {
                 type: 'object',
                 properties: {
@@ -565,7 +611,7 @@ const plugin = {
         // ─── Tool: team_list ──────────────────────────────────────────────────
         registerTool({
             name: 'team_list',
-            description: 'List teammates in an agent team session (requires enableAgentTeams)',
+            description: "List the other active sessions as this session's teammates, with engine, idle/busy/paused state and turn count. Works on every engine; enableAgentTeams is not required.",
             parameters: {
                 type: 'object',
                 properties: { name: { type: 'string', description: 'Session name' } },
@@ -579,7 +625,7 @@ const plugin = {
         // ─── Tool: team_send ──────────────────────────────────────────────────
         registerTool({
             name: 'team_send',
-            description: 'Send a message to a specific teammate in an agent team session',
+            description: 'Send a message to another active session through the cross-session inbox: delivered now if it is idle, queued if it is busy.',
             parameters: {
                 type: 'object',
                 properties: {
@@ -597,7 +643,7 @@ const plugin = {
         // ─── Tool: session_update_tools ───────────────────────────────────────
         registerTool({
             name: 'session_update_tools',
-            description: 'Update allowedTools or disallowedTools for a running session. Restarts the session process with --resume to apply the new tool constraints while preserving conversation history. Rejects if the session is currently busy.',
+            description: 'Update allowedTools or disallowedTools for a running session. Restarts the session process with --resume to apply the new tool constraints while preserving conversation history. Rejects if the session is currently busy. Without merge:true both lists are replaced, so a list you omit is cleared.',
             parameters: {
                 type: 'object',
                 properties: {
@@ -657,7 +703,7 @@ const plugin = {
                 properties: {
                     path: {
                         type: 'string',
-                        description: 'Project path to purge (resolved to absolute). Ignored when all=true. Defaults to current cwd.',
+                        description: "Project path to purge (resolved to absolute). Ignored when all=true. Defaults to the orchestrator process's working directory.",
                     },
                     all: {
                         type: 'boolean',
@@ -784,7 +830,7 @@ const plugin = {
         // ─── Tool: codex_review ─────────────────────────────────────────────
         registerTool({
             name: 'codex_review',
-            description: 'Run a non-interactive Codex code review (`codex review`). Pick exactly one diff scope: uncommitted (working-tree changes), base (vs branch), or commit (vs SHA). Output is plain text — Codex `review` does not emit JSON.',
+            description: 'Run a non-interactive Codex code review (`codex review`). Pick at most one diff scope — uncommitted (working-tree changes), base (vs branch), or commit (vs SHA); passing two is an error. Output is plain text — Codex `review` does not emit JSON.',
             parameters: {
                 type: 'object',
                 properties: {
@@ -979,7 +1025,7 @@ const plugin = {
                     agents: {
                         type: 'array',
                         maxItems: 16,
-                        description: 'Agent specs: { name, engine?, model?, effort?, prompt?, persona?, baseUrl?, permissionMode?, customEngine? }.',
+                        description: "Agent specs: { name, engine?, model?, effort?, prompt?, persona?, baseUrl?, permissionMode?, sandboxMode?, customEngine?, acpAgent? }. permissionMode uses each engine's own permission handling as in session_start; workers that must not write should set sandboxMode to read-only. sandboxMode uses the same values and per-engine behavior as session_start.",
                         items: {
                             type: 'object',
                             properties: {
@@ -999,6 +1045,17 @@ const plugin = {
                                     description: 'Per-agent role instructions prepended to the shared task when no non-empty prompt is supplied.',
                                 },
                                 baseUrl: { type: 'string' },
+                                permissionMode: {
+                                    type: 'string',
+                                    enum: ['acceptEdits', 'bypassPermissions', 'default', 'manual', 'dontAsk', 'plan', 'auto'],
+                                    description: "Per-agent permission mode (same values as session_start). Passed through to that engine's own permission handling; see session_start for per-engine mapping.",
+                                },
+                                sandboxMode: {
+                                    type: 'string',
+                                    enum: ['read-only', 'workspace-write', 'danger-full-access'],
+                                    description: 'Same values and per-engine behavior as session_start. Use read-only for workers that must not write.',
+                                },
+                                acpAgent: ACP_AGENT_ID_SCHEMA,
                             },
                             required: ['name'],
                         },
@@ -1013,6 +1070,10 @@ const plugin = {
                         enum: ENGINE_TYPES,
                         description: 'Engine for the synthesis pass (default claude).',
                     },
+                    synthesisAcpAgent: {
+                        ...ACP_AGENT_ID_SCHEMA,
+                        description: 'With synthesisEngine "acp": the ACP agent preset the synthesis pass starts.',
+                    },
                     agentTimeoutMs: { type: 'number', description: 'Per-agent timeout in ms (default 600000).' },
                     maxTurnsPerAgent: { type: 'number', description: 'Max agent loop turns (default 30).' },
                     maxBudgetUsd: { type: 'number', description: 'Per-agent spend cap (USD).' },
@@ -1027,6 +1088,7 @@ const plugin = {
                     synthesize: args.synthesize,
                     synthesisModel: args.synthesisModel,
                     synthesisEngine: args.synthesisEngine,
+                    synthesisAcpAgent: args.synthesisAcpAgent,
                     agentTimeoutMs: args.agentTimeoutMs,
                     maxTurnsPerAgent: args.maxTurnsPerAgent,
                     maxBudgetUsd: args.maxBudgetUsd,
@@ -1071,13 +1133,13 @@ const plugin = {
                     template: {
                         type: 'string',
                         enum: ['solve', 'council', 'fanout', 'goal'],
-                        description: 'Build a built-in workflow instead of supplying `spec`. `solve` = triage → implement → verify → repair-until-green → review. `goal` = a Codex /goal on one codex-app thread (`task` is the objective) → verify → repair on the same thread.',
+                        description: 'Build a built-in workflow instead of supplying `spec`. `solve` = triage → implement → review → verify → repair-until-green. `goal` = a /goal on one Codex thread or Claude Code session (`task` is the objective) → verify → repair on the same thread.',
                     },
                     task: { type: 'string', description: 'Task text, when using `template`.' },
                     agents: {
                         type: 'array',
                         maxItems: 16,
-                        description: 'Agents for the template: { name, engine?, model?, effort?, persona? }.',
+                        description: 'Agents for the template: { name, engine?, model?, effort?, persona?, acpAgent? }.',
                         items: {
                             type: 'object',
                             properties: {
@@ -1086,6 +1148,7 @@ const plugin = {
                                 model: { type: 'string' },
                                 effort: { type: 'string', enum: EFFORT_LEVELS },
                                 persona: { type: 'string' },
+                                acpAgent: ACP_AGENT_ID_SCHEMA,
                             },
                             required: ['name'],
                         },
@@ -1102,6 +1165,7 @@ const plugin = {
                                 model: { type: 'string' },
                                 effort: { type: 'string', enum: EFFORT_LEVELS },
                                 persona: { type: 'string' },
+                                acpAgent: ACP_AGENT_ID_SCHEMA,
                             },
                             required: ['name'],
                         },
@@ -1112,19 +1176,26 @@ const plugin = {
                         properties: {
                             engine: { type: 'string', enum: ENGINE_TYPES },
                             model: { type: 'string' },
+                            acpAgent: ACP_AGENT_ID_SCHEMA,
                         },
                     },
                     humanGate: { type: 'boolean', description: '`solve` only: park for approval before writing anything.' },
+                    maxRounds: { type: 'number', description: '`council` only: max collaboration rounds (default 15).' },
                     maxRepairs: {
                         type: 'number',
                         description: '`solve` / `goal`: repair attempts allowed (default 3 for solve, 1 for goal).',
                     },
-                    model: { type: 'string', description: "`goal` only: Codex model (default: codex's own)." },
+                    engine: {
+                        type: 'string',
+                        enum: ['codex', 'claude'],
+                        description: '`goal` only: who runs the goal (default codex).',
+                    },
+                    model: { type: 'string', description: "`goal` only: model (default: the engine's own)." },
                     tokenBudget: { type: 'number', description: '`goal` only: tokens the goal may spend.' },
                     launcher: {
                         type: 'array',
                         items: { type: 'string' },
-                        description: '`goal` only: argv prefix codex runs under, e.g. a sandbox wrapper. It runs with your authority, like a contract command check.',
+                        description: '`goal` only: argv prefix the engine runs under, e.g. a sandbox wrapper. It runs with your authority, like a contract command check.',
                     },
                     cwd: { type: 'string', description: 'Working directory for the run.' },
                     runId: { type: 'string', description: 'Explicit run id (defaults to a generated one).' },
@@ -1207,7 +1278,7 @@ const plugin = {
                         throw new Error('workflow_start needs `spec`, or `template` with `task`');
                     const agents = args.agents ?? [{ name: 'agent' }];
                     if (template === 'council') {
-                        spec = councilWorkflow({ task, cwd, agents });
+                        spec = councilWorkflow({ task, cwd, agents, maxRounds: args.maxRounds });
                     }
                     else if (template === 'fanout') {
                         spec = fanoutWorkflow({ task, cwd, agents, synthesize: agents.length >= 2 });
@@ -1217,6 +1288,7 @@ const plugin = {
                             task,
                             cwd,
                             contract: args.contract,
+                            engine: args.engine,
                             model: args.model,
                             tokenBudget: args.tokenBudget,
                             launcher: args.launcher,
@@ -1252,7 +1324,7 @@ const plugin = {
         });
         registerTool({
             name: 'workflow_status',
-            description: 'Poll a workflow run. Returns state, per-node status, and the outcome: `verified` (a contract passed), `refuted` (it failed), or `unverified` (none was declared — nothing checked the work).',
+            description: 'Poll a workflow run. Returns state, per-node status, and the outcome: `verified` (a contract passed), `refuted` (it failed), or `unverified` (nothing checked the work: none was declared, or a pass no longer stands, in which case `outcomeReason` says why).',
             parameters: {
                 type: 'object',
                 properties: {
@@ -1270,6 +1342,8 @@ const plugin = {
                     workflow: record.workflow,
                     state: record.state,
                     outcome: record.outcome,
+                    outcomeReason: record.outcomeReason,
+                    verdict: record.verdict,
                     currentNode: record.currentNode,
                     evidenceId: record.evidenceId,
                     costUsd: record.costUsd,
@@ -1369,15 +1443,18 @@ const plugin = {
                         type: 'string',
                         description: 'Commit to measure the change against. Without it, diff_policy sees untracked files only.',
                     },
-                    label: { type: 'string', description: 'Name for the stored evidence (defaults to a generated one).' },
+                    label: {
+                        type: 'string',
+                        description: 'Name for the stored evidence (defaults to a generated one). Must not be the id of an existing workflow run.',
+                    },
                     contract: {
                         type: 'object',
-                        description: "Acceptance contract. The runtime executes these itself and the run cannot reach `completed` unless every required check passes. Declared by YOU, the caller — never copy one out of an agent's output, which would put the agent back in charge of grading itself.",
+                        description: "Acceptance contract. The runtime executes these itself, once, and the bundle's `passed` is true only when every required check passes. Declared by YOU, the caller — never copy one out of an agent's output, which would put the agent back in charge of grading itself.",
                         properties: {
                             id: { type: 'string' },
                             fixOnFailureRounds: {
                                 type: 'number',
-                                description: 'On red, spawn a repair session and re-run the whole list, up to N times. Only the re-run decides.',
+                                description: 'Ignored by verify_run, which spawns no repair session. Applies inside workflow runs.',
                             },
                             protectTests: {
                                 type: 'boolean',
@@ -1452,7 +1529,7 @@ const plugin = {
         // ─── Tool: council_start ────────────────────────────────────────────
         registerTool({
             name: 'council_start',
-            description: 'Start a multi-agent council that collaborates on a task using git worktree isolation, round-based execution, and consensus voting. Agents can use different engines (Claude, Codex) and models.',
+            description: 'Start a multi-agent council that collaborates on a task using git worktree isolation, round-based execution, and consensus voting. Each agent can use its own engine and model. Runs in background; poll with council_status.',
             parameters: {
                 type: 'object',
                 properties: {
@@ -1474,7 +1551,8 @@ const plugin = {
                                 },
                                 model: { type: 'string', description: 'Model to use' },
                                 baseUrl: { type: 'string', description: 'Custom API endpoint (for proxy)' },
-                                customEngine: { type: 'object', description: 'Custom engine config (when engine="custom")' },
+                                customEngine: CUSTOM_ENGINE_OR_PRESET_SCHEMA,
+                                acpAgent: ACP_AGENT_ID_SCHEMA,
                                 effort: {
                                     type: 'string',
                                     enum: ['low', 'medium', 'high', 'xhigh', 'max', 'ultra', 'auto'],
@@ -1537,21 +1615,23 @@ const plugin = {
         // ─── Tool: council_abort ────────────────────────────────────────────
         registerTool({
             name: 'council_abort',
-            description: 'Abort a running council, stopping all agent sessions',
+            description: 'Abort a council running in this process, stopping all agent sessions and removing the worktrees it created. A council that is not running here is left alone and the call returns ok: false.',
             parameters: {
                 type: 'object',
                 properties: { id: { type: 'string', description: 'Council session ID' } },
                 required: ['id'],
             },
             execute: async (_id, args) => {
-                getManager().councilAbort(args.id);
-                return { ok: true };
+                const result = getManager().councilAbort(args.id);
+                if (!result.aborted)
+                    return { ok: false, aborted: false, state: result.state, error: result.reason };
+                return { ok: true, aborted: true };
             },
         });
         // ─── Tool: council_inject ───────────────────────────────────────────
         registerTool({
             name: 'council_inject',
-            description: 'Inject a user message into the next round of a running council. The message will be appended to all agent prompts in the next round.',
+            description: 'Inject a user message into the next round of a running council. The message will be appended to all agent prompts in the next round; a second inject before that round replaces the first. The council must be running in this process.',
             parameters: {
                 type: 'object',
                 properties: {
@@ -1717,9 +1797,10 @@ const plugin = {
                     engines: {
                         type: 'array',
                         // Excluded: 'custom', because ultrareview spawns reviewers without a
-                        // customEngine config.
-                        items: { type: 'string', enum: ENGINE_TYPES.filter((e) => e !== 'custom') },
-                        description: 'Engines to round-robin reviewers across (default ["claude"]). Every reviewer runs read-only (sandboxMode read-only), so custom is not accepted. Reviewers fan out in parallel; per-agent failures are isolated.',
+                        // customEngine config, and 'acp', because an ACP agent cannot be held
+                        // to the read-only sandbox every reviewer runs in.
+                        items: { type: 'string', enum: ENGINE_TYPES.filter((e) => e !== 'custom' && e !== 'acp') },
+                        description: 'Engines to round-robin reviewers across (default ["claude"]). Every reviewer runs read-only (sandboxMode read-only), so custom and acp are not accepted. Reviewers fan out in parallel; per-agent failures are isolated.',
                     },
                 },
                 required: ['cwd'],
@@ -1767,14 +1848,19 @@ const plugin = {
                         description: 'Stable run identifier (used to address subsequent chat / status calls)',
                     },
                     workspace: { type: 'string', description: 'Path to the git workspace where the run lives' },
-                    planner_engine: { type: 'string', enum: ENGINE_TYPES, description: 'Planner engine (default: claude)' },
+                    // No 'acp': a role is configured by engine name alone and cannot name the ACP agent.
+                    planner_engine: { type: 'string', enum: AUTOLOOP_ENGINES, description: 'Planner engine (default: claude)' },
                     planner_model: {
                         type: 'string',
                         description: 'Planner model (default: opus for Claude; engine default otherwise)',
                     },
                     planner_effort: { type: 'string', enum: EFFORT_LEVELS, description: 'Fixed Planner reasoning effort' },
                     planner_custom_engine: CUSTOM_ENGINE_SCHEMA,
-                    coder_engine: { type: 'string', enum: ENGINE_TYPES, description: 'Default Coder engine (default: claude)' },
+                    coder_engine: {
+                        type: 'string',
+                        enum: AUTOLOOP_ENGINES,
+                        description: 'Default Coder engine (default: claude)',
+                    },
                     coder_model: {
                         type: 'string',
                         description: 'Default Coder model (default: sonnet for Claude; engine default otherwise)',
@@ -1783,7 +1869,7 @@ const plugin = {
                     coder_custom_engine: CUSTOM_ENGINE_SCHEMA,
                     reviewer_engine: {
                         type: 'string',
-                        enum: ENGINE_TYPES,
+                        enum: AUTOLOOP_ENGINES,
                         description: 'Default Reviewer engine (default: claude)',
                     },
                     reviewer_model: {
@@ -1874,13 +1960,9 @@ const plugin = {
         // ─── Tool: autoloop_list ─────────────────────────────────────
         registerTool({
             name: 'autoloop_list',
-            description: 'List all v2 autoloop runs in this manager process.',
+            description: 'List the v2 autoloop runs recorded on this machine, running and finished, newest first.',
             parameters: { type: 'object', properties: {} },
-            execute: async () => {
-                if (!manager)
-                    return { ok: true, runs: [] };
-                return { ok: true, runs: getManager().autoloopList() };
-            },
+            execute: async () => ({ ok: true, runs: getManager().autoloopList() }),
         });
         // ─── Tool: autoloop_reset_agent ──────────────────────────────
         registerTool({
@@ -1931,7 +2013,7 @@ const plugin = {
         // ─── ultraapp (read-only) ─────────────────────────────────────────────
         registerTool({
             name: 'ultraapp_list',
-            description: 'List all ultraapp runs (interview/build/done) with title, mode, and timestamps. Read-only — to start a new run, open the Forge dashboard tab.',
+            description: 'List all ultraapp runs with title, mode (interview, queued, building, build-complete, deploying, done, failed, cancelled), and timestamps. Read-only — to start a new run, call ultraapp_new or open the Forge dashboard tab.',
             parameters: { type: 'object', properties: {} },
             execute: async () => {
                 const ua = getManager().getUltraappManager();
@@ -2061,7 +2143,7 @@ const plugin = {
         });
         registerTool({
             name: 'ultraapp_build_cancel',
-            description: 'Cancel a queued or in-flight build. Best-effort for in-flight; the worker is expected to honour its own cancellation signal (v0.2 only emits the event).',
+            description: "Cancel a queued or in-flight build. A queued build leaves the queue; an in-flight build's workflow run is cancelled, and the build stops at its next cancellation check.",
             parameters: {
                 type: 'object',
                 properties: { runId: { type: 'string' } },
@@ -2075,7 +2157,7 @@ const plugin = {
         });
         registerTool({
             name: 'ultraapp_feedback',
-            description: 'Submit a done-mode feedback message (after the run reaches `done`). The text is classified by Haiku into cosmetic / spec-delta / structural and routed: cosmetic runs the patcher (Opus diff + validate + auto-revert + version snapshot); spec-delta flips the run back to `interview` with a focused bootstrap; structural posts a "start fresh" suggestion.',
+            description: 'Submit a done-mode feedback message (after the run reaches `done`). The text is classified by Haiku into cosmetic / spec-delta / structural and routed: cosmetic runs the patcher (Opus diff + validate + auto-revert + version snapshot); spec-delta flips the run back to `interview` with a focused bootstrap; structural posts a "start fresh" suggestion. Before the run reaches `done`, the text is sent to the interview as a free-form answer instead.',
             parameters: {
                 type: 'object',
                 properties: {
@@ -2092,7 +2174,7 @@ const plugin = {
         });
         registerTool({
             name: 'ultraapp_promote_version',
-            description: "Atomically swap which previously-built version is currently deployed. Stops the old container, starts the target version's container, updates the router map. Requires a router to be wired (see clawo serve).",
+            description: 'Make a version the one serving the app. A version deployed before is swapped in (the live one is stopped, the target restarted, the router map updated); one never deployed, such as a patched version, is built and deployed first. Requires a router to be wired (see clawo serve).',
             parameters: {
                 type: 'object',
                 properties: {