git:20260504.a1c2a99 to git:20260629.fe782dc

+ ---

+ name: acp-router

+ description: Route plain-language requests for Claude Code, Cursor, Codex, Gemini, Qwen, Pi, Kiro, Kimi, iFlow, Factory Droid, Kilocode, OpenCode, Copilot into ACPX child sessions via acp_spawn. Pick the right agentId for the user's intent.

+ metadata:

+ openclaw:

+ emoji: "🧭"

+ tlamatini:

+ runtime: in-process

+ requires_tools: ["acp_spawn", "acp_send", "acp_kill", "list_acp_agents", "acp_doctor"]

+ requires_mcps: []

+ budget:

+ max_iterations: 4

+ max_seconds: 30

+ max_tokens: 6000

+ permissions:

+ filesystem: { read: [], write: [] }

+ shell: []

+ network: deny

+ db: deny

+ inputs:

+ - { name: harness, type: enum, required: true,

+ values: ["claude","cursor","codex","copilot","gemini","qwen","pi","droid","iflow","kilocode","kimi","kiro","opencode","tlamatini"] }

+ - { name: task, type: string, required: true }

+ - { name: cwd, type: string, required: false }

+ - { name: mode, type: enum, required: false,

+ values: ["session","one-shot"], default: "session" }

+ outputs:

+ - { name: session_id, type: string, required: true }

+ - { name: agent_id, type: string, required: true }

+ - { name: transcript_path, type: string, required: true }

+ triggers:

+ keywords: ["claude code","cursor","codex","copilot","gemini","qwen","kiro","kimi","iflow","droid","kilocode","opencode","run in","spawn","acp"]

+ ---

+ <!--

+ ═══════════════════════════════════════════════════════════════════

+ ✦ T L A M A T I N I ✦ — "one who knows"

+ Created by Angela López Mendoza · @angelahack1

+ Developer · Architect · Creator of Tlamatini

+ Tlamatini Author Banner — do not remove (Angela's name is kept in every build)

+ ═══════════════════════════════════════════════════════════════════

+ -->

+

+ # ACP Router

+

+ Route a plain-language request to the right ACPX harness.

+

+ ## Decision rules

+

+ 1. If the user's wording names a harness explicitly ("run this in Claude

+ Code", "ask Cursor to..."), use that as `harness` directly.

+ 2. If the user wants Codex chat conversation, prefer the native Codex

+ binding (a separate skill); use ACPX Codex only when ACP/`/acp`/acpx

+ is named explicitly or when background spawn is needed.

+ 3. Default `mode` to `session` so follow-up turns can be added with

+ `acp_send`. Use `one-shot` only when the user asked for a single

+ non-interactive task. (Note: `mode` is ignored by `oneshot-prompt`

+ transport agents — claude / cursor / gemini / qwen / codex — because

+ each turn is its own fresh process. Continuity inside the child is

+ not preserved between `acp_send` calls on those harnesses.)

+

+ ## Transport awareness

+

+ The runtime now uses three transports. `acp_doctor` returns each agent's

+ transport in `details[].transport` (when populated by the host) or you

+ can infer from the `agent_id`:

+

+ - `oneshot-prompt` (**claude, cursor, gemini, qwen, codex**) — re-spawns

+ the CLI fresh per turn with the prompt as a CLI argument

+ (`claude -p "<task>"`, `codex exec "<task>"`, ...) and captures stdout

+ to EOF. `acp_spawn` runs the first turn synchronously and returns the

+ answer in the `events` array; the `assistant_message` event holds the

+ captured stdout.

+ - `json-acp` (**tlamatini** self-host) — strict JSON envelope on stdin.

+ - `tui-repl` (**kiro, kimi, iflow, kilocode, opencode, pi, droid,

+ copilot**) — long-lived REPL over stdin. `acp_spawn` returns the

+ session_id sub-second; harvest answers via `acp_send_and_wait` /

+ `acp_transcript`.

+

+ ## Procedure

+

+ 1. Call `list_acp_agents` to confirm the chosen agentId is `resolvable`.

+ If not, call `acp_doctor` and surface the doctor message to the user.

+ 2. Call `acp_spawn(agent_id=harness, task=<task>, cwd=<cwd>, mode=<mode>)`.

+ 3. Return `{session_id, agent_id, transcript_path}` from the spawn result.

+

+ ## Failure handling

+

+ - If `acp_spawn` returns `code: AGENT_NOT_FOUND`, do NOT silently fall

+ back to a different harness. Report the missing CLI to the user, name

+ the install instruction (e.g. "install the Claude Code CLI"), and ask

+ whether they want to retry with a different harness.

+ - If `acp_spawn` returns `code: PERMISSION_DENIED`, the runtime is in

+ `deny-all` mode. Report this to the user; do not try to bypass.

+ - If a `oneshot-prompt` spawn returns events with empty

+ `assistant_message.text` and a `done._synthetic == "timeout"`, the CLI

+ exceeded the default 180 s hard cap. Retry with explicit

+ `timeout_seconds=300` if the task warrants it; otherwise report the

+ timeout to the user.