@kodelyth/acpx 2026.5.39

package/error-format.mjs

@@ -0,0 +1,6 @@
+export function formatErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message || error.name || "Error";
+  }
+  return String(error);
+}

package/index.js

@@ -0,0 +1,7 @@
+export * from "../../../dist/extensions/acpx/index.js";
+import defaultModule from "../../../dist/extensions/acpx/index.js";
+let defaultExport = defaultModule;
+for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
+  defaultExport = defaultExport.default;
+}
+export { defaultExport as default };

package/klaw.plugin.json

@@ -0,0 +1,189 @@
+{
+  "id": "acpx",
+  "activation": {
+    "onStartup": true
+  },
+  "enabledByDefault": true,
+  "name": "ACPX Runtime",
+  "description": "Embedded ACP runtime backend with plugin-owned session and transport management.",
+  "skills": [
+    "./skills"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "cwd": {
+        "type": "string",
+        "minLength": 1
+      },
+      "stateDir": {
+        "type": "string",
+        "minLength": 1
+      },
+      "probeAgent": {
+        "type": "string",
+        "minLength": 1
+      },
+      "permissionMode": {
+        "type": "string",
+        "enum": [
+          "approve-all",
+          "approve-reads",
+          "deny-all"
+        ]
+      },
+      "nonInteractivePermissions": {
+        "type": "string",
+        "enum": [
+          "deny",
+          "fail"
+        ]
+      },
+      "pluginToolsMcpBridge": {
+        "type": "boolean"
+      },
+      "openClawToolsMcpBridge": {
+        "type": "boolean"
+      },
+      "strictWindowsCmdWrapper": {
+        "type": "boolean"
+      },
+      "timeoutSeconds": {
+        "type": "number",
+        "minimum": 0.001,
+        "default": 120
+      },
+      "queueOwnerTtlSeconds": {
+        "type": "number",
+        "minimum": 0
+      },
+      "mcpServers": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "object",
+          "properties": {
+            "command": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Command to run the MCP server"
+            },
+            "args": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Arguments to pass to the command"
+            },
+            "env": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              },
+              "description": "Environment variables for the MCP server"
+            }
+          },
+          "required": [
+            "command"
+          ]
+        }
+      },
+      "agents": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "object",
+          "properties": {
+            "command": {
+              "type": "string",
+              "minLength": 1
+            },
+            "args": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "required": [
+            "command"
+          ]
+        }
+      }
+    }
+  },
+  "uiHints": {
+    "cwd": {
+      "label": "Default Working Directory",
+      "help": "Default working directory for embedded ACP session operations when not set per session."
+    },
+    "stateDir": {
+      "label": "State Directory",
+      "help": "Directory used for embedded ACP session state and persistence."
+    },
+    "permissionMode": {
+      "label": "Permission Mode",
+      "help": "Default permission policy for embedded ACP runtime prompts."
+    },
+    "nonInteractivePermissions": {
+      "label": "Non-Interactive Permission Policy",
+      "help": "Policy when interactive permission prompts are unavailable."
+    },
+    "pluginToolsMcpBridge": {
+      "label": "Plugin Tools MCP Bridge",
+      "help": "Default off. When enabled, inject the built-in Klaw plugin-tools MCP server into embedded ACP sessions so ACP agents can call plugin-registered tools.",
+      "advanced": true
+    },
+    "openClawToolsMcpBridge": {
+      "label": "Klaw Tools MCP Bridge",
+      "help": "Default off. When enabled, inject the built-in Klaw core-tools MCP server into embedded ACP sessions so ACP agents can call selected built-in tools such as cron.",
+      "advanced": true
+    },
+    "strictWindowsCmdWrapper": {
+      "label": "Strict Windows cmd Wrapper",
+      "help": "Legacy compatibility field. The current embedded acpx/runtime package uses its own Windows command resolution behavior. Setting this to false is accepted for compatibility and logged as ignored.",
+      "advanced": true
+    },
+    "timeoutSeconds": {
+      "label": "Runtime Operation Timeout Seconds",
+      "help": "Timeout for embedded ACP runtime startup and control operations. ACP turns use Klaw agent/run timeouts.",
+      "advanced": true
+    },
+    "queueOwnerTtlSeconds": {
+      "label": "Queue Owner TTL Seconds",
+      "help": "Reserved compatibility field for the older embedded ACPX queue-owner path. Accepted for compatibility and logged as ignored.",
+      "advanced": true
+    },
+    "probeAgent": {
+      "label": "Health Probe Agent",
+      "help": "Agent id used for the embedded ACP runtime health probe. Defaults to the first `acp.allowedAgents` entry when that allowlist is set, otherwise to the runtime built-in probe agent (codex). Set this explicitly (for example `opencode` or `claude`) when the default probe agent is not installed or not authenticated, so the whole embedded ACP backend does not get marked unavailable.",
+      "advanced": true
+    },
+    "mcpServers": {
+      "label": "MCP Servers",
+      "help": "Named MCP server definitions to inject into embedded ACP session bootstrap. Each entry needs a command and can include args and env.",
+      "advanced": true
+    },
+    "agents": {
+      "label": "Agent Commands",
+      "help": "Optional per-agent command overrides for the embedded ACP runtime.",
+      "advanced": true
+    }
+  },
+  "configContracts": {
+    "dangerousFlags": [
+      {
+        "path": "permissionMode",
+        "equals": "approve-all"
+      }
+    ],
+    "secretInputs": {
+      "bundledDefaultEnabled": false,
+      "paths": [
+        {
+          "path": "mcpServers.*.env.*",
+          "expected": "string"
+        }
+      ]
+    }
+  }
+}

package/mcp-command-line.mjs

@@ -0,0 +1,123 @@
+const WINDOWS_DIRECT_EXECUTABLE_PATH_RE =
+  /^(?<command>(?:[A-Za-z]:[\\/]|\\\\[^\\/]+[\\/][^\\/]+[\\/]).*?\.(?:exe|com))(?=\s|$)(?:\s+(?<rest>.*))?$/i;
+
+// Windows wrapper scripts need their host shell or interpreter (`cmd.exe`,
+// `powershell.exe`, or `node`) instead of direct spawning.
+const WINDOWS_WRAPPER_PATH_RE =
+  /^(?:[A-Za-z]:[\\/]|\\\\[^\\/]+[\\/][^\\/]+[\\/]).*?\.(?:bat|cmd|cjs|js|mjs|ps1)$/i;
+
+function splitCommandParts(value, platform = process.platform) {
+  const parts = [];
+  let current = "";
+  let quote = null;
+  let escaping = false;
+
+  for (let index = 0; index < value.length; index += 1) {
+    const ch = value[index];
+    const next = value[index + 1];
+    if (escaping) {
+      current += ch;
+      escaping = false;
+      continue;
+    }
+    if (ch === "\\") {
+      if (quote === "'") {
+        current += ch;
+        continue;
+      }
+      if (platform === "win32") {
+        if (quote === '"') {
+          if (next === '"' || next === "\\") {
+            escaping = true;
+            continue;
+          }
+          current += ch;
+          continue;
+        }
+        if (!quote) {
+          current += ch;
+          continue;
+        }
+      }
+      escaping = true;
+      continue;
+    }
+    if (quote) {
+      if (ch === quote) {
+        quote = null;
+      } else {
+        current += ch;
+      }
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      if (current.length > 0) {
+        parts.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += ch;
+  }
+
+  if (escaping) {
+    current += "\\";
+  }
+  if (quote) {
+    throw new Error("Invalid agent command: unterminated quote");
+  }
+  if (current.length > 0) {
+    parts.push(current);
+  }
+  return parts;
+}
+
+function splitWindowsExecutableCommand(value, platform = process.platform) {
+  if (platform !== "win32") {
+    return null;
+  }
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.startsWith('"') || trimmed.startsWith("'")) {
+    return null;
+  }
+  const match = trimmed.match(WINDOWS_DIRECT_EXECUTABLE_PATH_RE);
+  if (!match?.groups?.command) {
+    return null;
+  }
+  const rest = match.groups.rest?.trim() ?? "";
+  return {
+    command: match.groups.command,
+    args: rest ? splitCommandParts(rest, platform) : [],
+  };
+}
+
+function assertSupportedWindowsCommand(command, platform = process.platform) {
+  if (platform !== "win32" || !WINDOWS_WRAPPER_PATH_RE.test(command)) {
+    return;
+  }
+  throw new Error(
+    `Unsupported Windows agent command wrapper: ${command}. ` +
+      "Invoke wrapper scripts through their shell or interpreter instead " +
+      "(for example `cmd.exe /c`, `powershell.exe -File`, or `node <script>`).",
+  );
+}
+
+export function splitCommandLine(value, platform = process.platform) {
+  const windowsCommand = splitWindowsExecutableCommand(value, platform);
+  const parts = windowsCommand ?? splitCommandParts(value, platform);
+  if (parts.length === 0) {
+    throw new Error("Invalid agent command: empty command");
+  }
+  const parsed = Array.isArray(parts)
+    ? {
+        command: parts[0],
+        args: parts.slice(1),
+      }
+    : parts;
+  assertSupportedWindowsCommand(parsed.command, platform);
+  return parsed;
+}

package/mcp-proxy.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import { pathToFileURL } from "node:url";
+import { formatErrorMessage } from "./error-format.mjs";
+import { splitCommandLine } from "./mcp-command-line.mjs";
+
+function decodePayload(argv) {
+  const payloadIndex = argv.indexOf("--payload");
+  if (payloadIndex < 0) {
+    throw new Error("Missing --payload");
+  }
+  const encoded = argv[payloadIndex + 1];
+  if (!encoded) {
+    throw new Error("Missing MCP proxy payload value");
+  }
+  const parsed = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Invalid MCP proxy payload");
+  }
+  if (typeof parsed.targetCommand !== "string" || parsed.targetCommand.trim() === "") {
+    throw new Error("MCP proxy payload missing targetCommand");
+  }
+  const mcpServers = Array.isArray(parsed.mcpServers) ? parsed.mcpServers : [];
+  return {
+    targetCommand: parsed.targetCommand,
+    mcpServers,
+  };
+}
+
+function shouldInject(method) {
+  return method === "session/new" || method === "session/load" || method === "session/fork";
+}
+
+function rewriteLine(line, mcpServers) {
+  if (!line.trim()) {
+    return line;
+  }
+  try {
+    const parsed = JSON.parse(line);
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      Array.isArray(parsed) ||
+      !shouldInject(parsed.method) ||
+      !parsed.params ||
+      typeof parsed.params !== "object" ||
+      Array.isArray(parsed.params)
+    ) {
+      return line;
+    }
+    const next = {
+      ...parsed,
+      params: {
+        ...parsed.params,
+        mcpServers,
+      },
+    };
+    return JSON.stringify(next);
+  } catch {
+    return line;
+  }
+}
+
+export function createTargetSpawnOptions(platform = process.platform) {
+  const options = {
+    stdio: ["pipe", "pipe", "inherit"],
+    env: process.env,
+  };
+  if (platform === "win32") {
+    options.windowsHide = true;
+  }
+  return options;
+}
+
+function isMainModule() {
+  const mainPath = process.argv[1];
+  if (!mainPath) {
+    return false;
+  }
+  return import.meta.url === pathToFileURL(path.resolve(mainPath)).href;
+}
+
+function main() {
+  const { targetCommand, mcpServers } = decodePayload(process.argv.slice(2));
+  const target = splitCommandLine(targetCommand);
+  const child = spawn(target.command, target.args, createTargetSpawnOptions());
+
+  if (!child.stdin || !child.stdout) {
+    throw new Error("Failed to create MCP proxy stdio pipes");
+  }
+
+  const input = createInterface({ input: process.stdin });
+  input.on("line", (line) => {
+    child.stdin.write(`${rewriteLine(line, mcpServers)}\n`);
+  });
+  input.on("close", () => {
+    child.stdin.end();
+  });
+
+  child.stdout.pipe(process.stdout);
+
+  child.on("error", (error) => {
+    process.stderr.write(`${formatErrorMessage(error)}\n`);
+    process.exit(1);
+  });
+
+  child.on("close", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 0);
+  });
+}
+
+if (isMainModule()) {
+  main();
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@kodelyth/acpx",
+  "version": "2026.5.39",
+  "description": "Klaw ACP runtime backend",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kodelyth/klaw"
+  },
+  "type": "module",
+  "dependencies": {
+    "@agentclientprotocol/claude-agent-acp": "0.33.1",
+    "@zed-industries/codex-acp": "0.14.0",
+    "acpx": "0.7.0",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@kodelyth/plugin-sdk": "1.0.1"
+  },
+  "klaw": {
+    "extensions": [
+      "./index.js"
+    ],
+    "install": {
+      "npmSpec": "@kodelyth/acpx",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.25"
+    },
+    "compat": {
+      "pluginApi": ">=2026.5.39"
+    },
+    "build": {
+      "klawVersion": "2026.5.39",
+      "staticAssets": [
+        {
+          "source": "./src/runtime-internals/mcp-proxy.mjs",
+          "output": "mcp-proxy.mjs"
+        },
+        {
+          "source": "./src/runtime-internals/error-format.mjs",
+          "output": "error-format.mjs"
+        },
+        {
+          "source": "./src/runtime-internals/mcp-command-line.mjs",
+          "output": "mcp-command-line.mjs"
+        }
+      ]
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
+  }
+}

package/register.runtime.js

@@ -0,0 +1,7 @@
+export * from "../../../dist/extensions/acpx/register.runtime.js";
+import * as module from "../../../dist/extensions/acpx/register.runtime.js";
+let defaultExport = "default" in module ? module.default : module;
+for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
+  defaultExport = defaultExport.default;
+}
+export { defaultExport as default };

package/runtime-api.js

@@ -0,0 +1,7 @@
+export * from "../../../dist/extensions/acpx/runtime-api.js";
+import * as module from "../../../dist/extensions/acpx/runtime-api.js";
+let defaultExport = "default" in module ? module.default : module;
+for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
+  defaultExport = defaultExport.default;
+}
+export { defaultExport as default };

package/setup-api.js

@@ -0,0 +1,7 @@
+export * from "../../../dist/extensions/acpx/setup-api.js";
+import defaultModule from "../../../dist/extensions/acpx/setup-api.js";
+let defaultExport = defaultModule;
+for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
+  defaultExport = defaultExport.default;
+}
+export { defaultExport as default };

package/skills/acp-router/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: acp-router
+description: Route plain-language requests for Pi, Claude Code, Cursor, Copilot, Klaw ACP, OpenCode, Gemini CLI, Qwen, Kiro, Kimi, iFlow, Factory Droid, Kilocode, or explicit ACP harness work into either Klaw ACP runtime sessions or direct acpx-driven sessions ("telephone game" flow). For coding-agent thread requests, read this skill first, then use only `sessions_spawn` for thread creation. Codex chat binding defaults to the native Codex app-server plugin unless ACP is explicit or background spawn needs ACP.
+user-invocable: false
+---
+
+# ACP Harness Router
+
+When user intent is "run this in Pi/Claude Code/Cursor/Copilot/Klaw/OpenCode/Gemini/Qwen/Kiro/Kimi/iFlow/Droid/Kilocode (ACP harness)", do not use subagent runtime or PTY scraping. Route through ACP-aware flows.
+
+Codex is special: plain chat/conversation binding and control should use the native Codex app-server plugin (`/codex bind`, `/codex threads`, `/codex resume`) instead of the default ACP path. Use ACP for Codex only when the user explicitly names ACP/`/acp`/acpx, or when spawning background child sessions through `sessions_spawn` where a native Codex runtime spawn is not available yet.
+
+## Intent detection
+
+Trigger this skill when the user asks Klaw to:
+
+- run something in Pi / Claude Code / Cursor / Copilot / Klaw / OpenCode / Gemini / Qwen / Kiro / Kimi / iFlow / Droid / Kilocode
+- run Codex explicitly through ACP, `/acp`, or acpx
+- continue existing harness work
+- relay instructions to an external coding harness
+- keep an external harness conversation in a thread-like conversation
+
+Mandatory preflight for coding-agent thread requests:
+
+- Before creating any thread for ACP harness work, read this skill first in the same turn.
+- After reading, follow `Klaw ACP runtime path` below; do not use `message(action="thread-create")` for ACP harness thread spawn.
+
+## Mode selection
+
+Choose one of these paths:
+
+1. Klaw ACP runtime path (default): use `sessions_spawn` / ACP runtime tools.
+2. Direct `acpx` path (telephone game): use `acpx` CLI through `exec` to drive the harness session directly.
+
+Use direct `acpx` when one of these is true:
+
+- user explicitly asks for direct `acpx` driving
+- ACP runtime/plugin path is unavailable or unhealthy
+- the task is "just relay prompts to harness" and no Klaw ACP lifecycle features are needed
+
+Do not use:
+
+- `subagents` runtime for harness control
+- `/acp` command delegation as a requirement for the user
+- PTY scraping of supported ACP harness CLIs when `acpx` is available
+
+## AgentId mapping
+
+Use these defaults when user names a harness directly:
+
+- "pi" -> `agentId: "pi"`
+- "klaw" -> `agentId: "klaw"`
+- "claude" or "claude code" -> `agentId: "claude"`
+- "codex" -> `agentId: "codex"` only for explicit ACP/acpx requests or background ACP runtime spawn
+- "copilot" or "github copilot" -> `agentId: "copilot"`
+- "cursor" or "cursor cli" -> `agentId: "cursor"`
+- "droid" or "factory droid" -> `agentId: "droid"`
+- "opencode" -> `agentId: "opencode"`
+- "gemini" or "gemini cli" -> `agentId: "gemini"`
+- "iflow" -> `agentId: "iflow"`
+- "kilocode" -> `agentId: "kilocode"`
+- "kimi" or "kimi cli" -> `agentId: "kimi"`
+- "kiro" or "kiro cli" -> `agentId: "kiro"`
+- "qwen" or "qwen code" -> `agentId: "qwen"`
+
+These defaults match current acpx built-in aliases.
+
+If policy rejects the chosen id, report the policy error clearly and ask for the allowed ACP agent id.
+
+## Klaw ACP runtime path
+
+Required behavior:
+
+1. For ACP harness thread spawn requests, read this skill first in the same turn before calling tools.
+2. Use `sessions_spawn` with:
+   - `runtime: "acp"`
+   - `thread: true`
+   - `mode: "session"` (unless user explicitly wants one-shot)
+3. For ACP harness thread creation, do not use `message` with `action=thread-create`; `sessions_spawn` is the only thread-create path.
+4. Put requested work in `task` so the ACP session gets it immediately.
+5. Set `agentId` explicitly unless ACP default agent is known.
+6. Do not ask user to run slash commands or CLI when this path works directly.
+
+Example:
+
+User: "spawn a test codex ACP session in thread and tell it to say hi"
+
+Call:
+
+```json
+{
+  "task": "Say hi.",
+  "runtime": "acp",
+  "agentId": "codex",
+  "thread": true,
+  "mode": "session"
+}
+```
+
+## Thread spawn recovery policy
+
+When the user asks to start a coding harness in a thread, treat that as an ACP runtime request and try to satisfy it end-to-end.
+
+Required behavior when ACP backend is unavailable:
+
+1. Do not immediately ask the user to pick an alternate path.
+2. First attempt automatic local repair:
+   - ensure plugin-local pinned acpx is installed in the ACPX plugin package
+   - verify `${ACPX_CMD} --version`
+3. After reinstall/repair, restart the gateway and explicitly offer to run that restart for the user.
+4. Retry ACP thread spawn once after repair.
+5. Only if repair+retry fails, report the concrete error and then offer fallback options.
+
+When offering fallback, keep ACP first:
+
+- Option 1: retry ACP spawn after showing exact failing step
+- Option 2: direct acpx telephone-game flow
+
+Do not default to subagent runtime for these requests.
+
+## ACPX install and version policy (direct acpx path)
+
+For this repo, direct `acpx` calls must follow the same pinned policy as the `@klaw/acpx` extension package.
+
+1. Prefer plugin-local binary, not global PATH:
+   - `${ACPX_PLUGIN_ROOT}/node_modules/.bin/acpx`
+2. Resolve pinned version from extension dependency:
+   - `node -e "console.log(require(process.env.ACPX_PLUGIN_ROOT + '/package.json').dependencies.acpx)"`
+3. If binary is missing or version mismatched, install plugin-local pinned version:
+   - `cd "$ACPX_PLUGIN_ROOT" && npm install --omit=dev --no-save acpx@<pinnedVersion>`
+4. Verify before use:
+   - `${ACPX_PLUGIN_ROOT}/node_modules/.bin/acpx --version`
+5. If install/repair changed ACPX artifacts, restart the gateway and offer to run the restart.
+6. Do not run `npm install -g acpx` unless the user explicitly asks for global install.
+
+Set and reuse:
+
+```bash
+ACPX_PLUGIN_ROOT="<bundled-acpx-plugin-root>"
+ACPX_CMD="$ACPX_PLUGIN_ROOT/node_modules/.bin/acpx"
+```
+
+## Direct acpx path ("telephone game")
+
+Use this path to drive harness sessions without `/acp` or subagent runtime.
+
+### Rules
+
+1. Use `exec` commands that call `${ACPX_CMD}`.
+2. Reuse a stable session name per conversation so follow-up prompts stay in the same harness context.
+3. Prefer `--format quiet` for clean assistant text to relay back to user.
+4. Use `exec` (one-shot) only when the user wants one-shot behavior.
+5. Keep working directory explicit (`--cwd`) when task scope depends on repo context.
+
+### Session naming
+
+Use a deterministic name, for example:
+
+- `oc-<harness>-<conversationId>`
+
+Where `conversationId` is thread id when available, otherwise channel/conversation id.
+
+### Command templates
+
+Persistent session (create if missing, then prompt):
+
+```bash
+${ACPX_CMD} codex sessions show oc-codex-<conversationId> \
+  || ${ACPX_CMD} codex sessions new --name oc-codex-<conversationId>
+
+${ACPX_CMD} codex -s oc-codex-<conversationId> --cwd <workspacePath> --format quiet "<prompt>"
+```
+
+One-shot:
+
+```bash
+${ACPX_CMD} codex exec --cwd <workspacePath> --format quiet "<prompt>"
+```
+
+Cancel in-flight turn:
+
+```bash
+${ACPX_CMD} codex cancel -s oc-codex-<conversationId>
+```
+
+Close session:
+
+```bash
+${ACPX_CMD} codex sessions close oc-codex-<conversationId>
+```
+
+### Harness aliases in acpx
+
+- `claude`
+- `codex`
+- `copilot`
+- `cursor`
+- `droid`
+- `gemini`
+- `iflow`
+- `kilocode`
+- `kimi`
+- `kiro`
+- `klaw`
+- `opencode`
+- `pi`
+- `qwen`
+
+### Built-in adapter commands in acpx
+
+Defaults are:
+
+- `klaw -> klaw acp`
+- `claude -> bundled @agentclientprotocol/claude-agent-acp@0.32.0`
+- `codex -> bundled @zed-industries/codex-acp@0.13.0 through Klaw's isolated CODEX_HOME wrapper`
+- `copilot -> copilot --acp --stdio`
+- `cursor -> cursor-agent acp`
+- `droid -> droid exec --output-format acp`
+- `gemini -> gemini --acp`
+- `iflow -> iflow --experimental-acp`
+- `kilocode -> npx -y @kilocode/cli acp`
+- `kimi -> kimi acp`
+- `kiro -> kiro-cli acp`
+- `opencode -> npx -y opencode-ai acp`
+- `pi -> npx pi-acp@^0.0.22`
+- `qwen -> qwen --acp`
+
+If `~/.acpx/config.json` overrides `agents`, those overrides replace defaults.
+If your local Cursor install still exposes ACP as `agent acp`, set that as the `cursor` agent override explicitly.
+
+### Failure handling
+
+- `acpx: command not found`:
+  - for thread-spawn ACP requests, install plugin-local pinned acpx in the ACPX plugin package immediately
+  - restart gateway after install and offer to run the restart automatically
+  - then retry once
+  - do not ask for install permission first unless policy explicitly requires it
+  - do not install global `acpx` unless explicitly requested
+- adapter command missing (for example `claude-agent-acp` not found):
+  - for thread-spawn ACP requests, first restore built-in defaults by removing broken `~/.acpx/config.json` agent overrides
+  - then retry once before offering fallback
+  - if user wants binary-based overrides, install exactly the configured adapter binary
+- `NO_SESSION`: run `${ACPX_CMD} <agent> sessions new --name <sessionName>` then retry prompt.
+- queue busy: either wait for completion (default) or use `--no-wait` when async behavior is explicitly desired.
+
+### Output relay
+
+When relaying to user, return the final assistant text output from `acpx` command result. Avoid relaying raw local tool noise unless user asked for verbose logs.