@zhihand/mcp 0.12.3 → 0.16.0

package/README.md

@@ -2,22 +2,30 @@
 
 ZhiHand MCP Server — let AI agents see and control your phone.
 
-Version: `0.12.1`
+Version: `0.16.0`
 
 ## What is this?
 
-`@zhihand/mcp` is the core integration layer for ZhiHand. It provides an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that exposes phone control tools to any compatible AI agent, including:
+`@zhihand/mcp` is the core integration layer for ZhiHand. It runs as a **persistent daemon** that exposes phone control tools to any compatible AI agent via [MCP (Model Context Protocol)](https://modelcontextprotocol.io/), including:
 
 - **Claude Code**
 - **Codex CLI**
 - **Gemini CLI**
 - **OpenClaw**
 
-One npm package, two entry points:
+The daemon is a single persistent process that bundles three subsystems:
+
+| Subsystem | Purpose |
+|---|---|
+| **MCP Server** | HTTP Streamable transport on `localhost:18686/mcp` — serves tool calls to AI agents |
+| **Relay** | Brain heartbeat (30s), prompt listener (phone-initiated tasks), CLI dispatch |
+| **Config API** | IPC endpoint for `zhihand gemini/claude/codex` backend switching |
+
+Legacy entry points (backward compatible):
 
 | Entry | Purpose |
 |---|---|
-| `zhihand serve` | MCP Server (stdio) — used by Claude Code, Codex, Gemini CLI |
+| `zhihand serve` | MCP Server (stdio mode) — legacy, still works for direct CLI integration |
 | `zhihand.openclaw` | OpenClaw Plugin entry — thin wrapper calling the same core |
 
 ## Requirements
@@ -39,7 +47,7 @@ npx @zhihand/mcp serve
 
 ## Quick Start
 
-### 1. Pair your phone
+### 1. Setup and pair
 
 ```bash
 zhihand setup
@@ -52,62 +60,19 @@ This runs the full interactive setup:
 3. Waits for you to scan the QR code with the ZhiHand mobile app
 4. Saves credentials to `~/.zhihand/credentials.json`
 5. Detects installed CLI tools (Claude Code, Codex, Gemini CLI, OpenClaw)
-6. Prints the MCP configuration snippet for your tools
-
-### 2. Configure your AI tool
+6. Auto-selects the best available tool and configures MCP automatically
+7. Starts the daemon (MCP Server + Relay + Config API)
 
-Add the ZhiHand MCP server to your tool's configuration:
+No manual MCP configuration needed — `zhihand setup` handles everything.
 
-**Claude Code** — Add to `.mcp.json` in your project root, or run:
+### 2. Start the daemon
 
 ```bash
-claude mcp add zhihand -- zhihand serve
+zhihand start              # Start daemon in foreground
+zhihand start -d           # Start daemon in background (detached)
 ```
 
-Or manually create/edit `.mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "zhihand": {
-      "command": "zhihand",
-      "args": ["serve"]
-    }
-  }
-}
-```
-
-**Codex CLI** — Add to your MCP config:
-
-```json
-{
-  "mcpServers": {
-    "zhihand": {
-      "command": "zhihand",
-      "args": ["serve"]
-    }
-  }
-}
-```
-
-**Gemini CLI** — Add to `~/.gemini/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "zhihand": {
-      "command": "zhihand",
-      "args": ["serve"]
-    }
-  }
-}
-```
-
-**OpenClaw** — Install the plugin directly:
-
-```bash
-openclaw plugins install @zhihand/mcp
-```
+The daemon runs the MCP Server on `localhost:18686/mcp` (HTTP Streamable transport), maintains a brain heartbeat every 30 seconds (keeps the phone Brain indicator green), and listens for phone-initiated prompts.
 
 ### 3. Start using it
 
@@ -123,14 +88,52 @@ Once configured, your AI agent can use ZhiHand tools directly. For example, in C
 ## CLI Commands
 
 ```
-zhihand serve              Start MCP Server (stdio mode, called by AI tools)
-zhihand setup              Interactive setup: pair + detect tools + print config
+zhihand setup              Interactive setup: pair + detect tools + auto-select + configure MCP + start daemon
+zhihand start              Start daemon (MCP Server + Relay + Config API)
+zhihand start -d           Start daemon in background (detached)
+zhihand stop               Stop the running daemon
+zhihand status             Show daemon status, pairing info, device, and active backend
+
 zhihand pair               Pair with a phone (QR code in terminal)
-zhihand status             Show current pairing status and device info
 zhihand detect             List detected CLI tools and their login status
+zhihand serve              Start MCP Server (stdio mode, backward compatible)
 zhihand --help             Show help
+
+zhihand claude             Switch backend to Claude Code (sends IPC to daemon, auto-configures MCP)
+zhihand codex              Switch backend to Codex CLI (sends IPC to daemon, auto-configures MCP)
+zhihand gemini             Switch backend to Gemini CLI (sends IPC to daemon, auto-configures MCP)
+```
+
+### Daemon Lifecycle
+
+```bash
+zhihand start              # Start daemon in foreground
+zhihand start -d           # Start daemon in background
+zhihand stop               # Stop the daemon
+zhihand status             # Check if daemon is running, show device & backend info
 ```
 
+The daemon is a single persistent process that runs:
+- **MCP Server** on `localhost:18686/mcp` (HTTP Streamable transport)
+- **Relay**: brain heartbeat every 30s (keeps phone Brain indicator green), prompt listener (phone-initiated tasks dispatched to CLI), CLI dispatch
+- **Config API**: IPC endpoint for backend switching
+
+### Switching Backends
+
+Use `zhihand claude`, `zhihand codex`, or `zhihand gemini` to switch the active backend:
+
+```bash
+zhihand gemini             # Switch to Gemini CLI
+zhihand claude             # Switch to Claude Code
+zhihand codex              # Switch to Codex CLI
+```
+
+When you switch:
+- The command sends an **IPC message to the running daemon**
+- MCP config is **automatically added** to the new backend
+- MCP config is **automatically removed** from the previous backend
+- If the tool is not installed, an error is shown
+
 ### Options
 
 | Option | Description |
@@ -188,26 +191,40 @@ Pair with a phone device. Returns a QR code and pairing URL.
 ## How It Works
 
 ```
-AI Agent ←stdio→ zhihand serve (MCP Server)
-                       │
-                       ├── POST /v1/plugins           Register plugin
-                       ├── POST /v1/pairing/sessions   Create pairing
-                       ├── POST /v1/credentials/{id}/commands   Send command
-                       ├── GET  /v1/credentials/{id}/commands/{cid}   Poll ACK
-                       ├── SSE  /v1/credentials/{id}/events?topic=commands   Real-time ACK
-                       └── GET  /v1/credentials/{id}/screen   Fetch screenshot (JPEG)
-                       │
-                  ZhiHand Server
-                       │
-                  ZhiHand Mobile App
+AI Agent ←HTTP Streamable→ Daemon (localhost:18686/mcp)
+                               │
+                               ├── MCP Server ──→ ZhiHand Server ──→ Mobile App
+                               │     (tool calls: control, screenshot, pair)
+                               │
+                               ├── Relay
+                               │     ├── Brain heartbeat (30s) ──→ Server
+                               │     ├── Prompt listener (SSE) ←── Server ←── Phone
+                               │     └── CLI dispatch ──→ spawn claude/codex/gemini
+                               │
+                               └── Config API
+                                     └── IPC from zhihand claude/codex/gemini
 ```
 
+### Agent-initiated flow (tool calls)
+
 1. AI agent calls a tool (e.g. `zhihand_control` with `action: "click"`)
 2. MCP Server translates to a device command and enqueues it via the ZhiHand API
 3. Mobile app picks up the command, executes it, and sends an ACK
 4. MCP Server receives the ACK (via SSE or polling fallback)
 5. MCP Server fetches a fresh screenshot and returns it to the AI agent
 
+### Phone-initiated flow (prompt relay)
+
+1. User speaks or types a prompt on the phone
+2. Phone sends prompt to ZhiHand Server
+3. Daemon receives prompt via SSE
+4. Daemon spawns the active CLI tool (e.g. `claude`, `codex`, `gemini`) with the prompt
+5. CLI tool executes, result is sent back to the phone
+
+### Brain heartbeat
+
+The daemon sends a heartbeat to the ZhiHand Server every 30 seconds. This keeps the **Brain indicator green** on the phone, showing the user that an AI backend is connected and ready.
+
 Screenshots are transferred as raw JPEG binary and only base64-encoded at the LLM API boundary, minimizing bandwidth.
 
 ## Credential Storage
@@ -217,6 +234,8 @@ Pairing credentials are stored at:
 ```
 ~/.zhihand/
 ├── credentials.json    # Device credentials (credentialId, controllerToken, endpoint)
+├── backend.json        # Active backend selection (claudecode/codex/gemini)
+├── daemon.pid          # Daemon PID file (for zhihand stop)
 └── state.json          # Current pairing session state
 ```
 
@@ -242,10 +261,10 @@ You can manage multiple devices. The `credentials.json` file stores a `default`
 ```
 packages/mcp/
 ├── bin/
-│   ├── zhihand              # Main CLI entry (serve/setup/pair/status/detect)
+│   ├── zhihand              # Main CLI entry (start/stop/status/setup/serve/pair/detect)
 │   └── zhihand.openclaw     # OpenClaw plugin entry
 ├── src/
-│   ├── index.ts             # MCP Server (stdio transport)
+│   ├── index.ts             # MCP Server (stdio transport, legacy)
 │   ├── openclaw.adapter.ts  # OpenClaw Plugin adapter (thin wrapper)
 │   ├── core/
 │   │   ├── config.ts        # Credential & config management (~/.zhihand/)
@@ -253,6 +272,11 @@ packages/mcp/
 │   │   ├── screenshot.ts    # Binary screenshot fetch (JPEG)
 │   │   ├── sse.ts           # SSE client + hybrid ACK (SSE push + polling fallback)
 │   │   └── pair.ts          # Plugin registration + device pairing flow
+│   ├── daemon/
+│   │   ├── index.ts         # Daemon entry: HTTP server + MCP + Relay + Config API
+│   │   ├── heartbeat.ts     # Brain heartbeat loop (30s interval, 5s retry)
+│   │   ├── prompt-listener.ts # SSE + polling prompt listener with dedup
+│   │   └── dispatcher.ts    # Async CLI dispatch (spawn + timeout + two-stage kill)
 │   ├── tools/
 │   │   ├── schemas.ts       # Zod parameter schemas
 │   │   ├── control.ts       # zhihand_control handler
@@ -261,6 +285,7 @@ packages/mcp/
 │   └── cli/
 │       ├── detect.ts        # CLI tool detection (Claude Code, Codex, Gemini, OpenClaw)
 │       ├── spawn.ts         # CLI process spawning (for mobile-initiated tasks)
+│       ├── mcp-config.ts    # MCP auto-configuration (add/remove per backend)
 │       └── openclaw.ts      # OpenClaw auto-detect & plugin install
 ├── dist/                    # Compiled JavaScript (shipped in npm package)
 ├── package.json

package/bin/zhihand

@@ -3,19 +3,29 @@
 import os from "node:os";
 import { parseArgs } from "node:util";
 import { startStdioServer } from "../dist/index.js";
+import { startDaemon, stopDaemon, isAlreadyRunning } from "../dist/daemon/index.js";
 import { detectCLITools, formatDetectedTools } from "../dist/cli/detect.js";
 import { detectAndSetupOpenClaw } from "../dist/cli/openclaw.js";
-import { loadDefaultCredential } from "../dist/core/config.js";
+import { loadDefaultCredential, loadBackendConfig, saveBackendConfig } from "../dist/core/config.js";
 import { executePairing } from "../dist/core/pair.js";
+import { configureMCP, displayName } from "../dist/cli/mcp-config.js";
 
 const DEFAULT_ENDPOINT = "https://api.zhihand.com";
 
+const CLI_TOOL_MAP = {
+  claude: "claudecode",
+  codex: "codex",
+  gemini: "gemini",
+};
+
 const { positionals, values } = parseArgs({
   allowPositionals: true,
+  strict: false,
   options: {
     device: { type: "string" },
-    http: { type: "boolean", default: false },
     help: { type: "boolean", short: "h", default: false },
+    detach: { type: "boolean", short: "d", default: false },
+    port: { type: "string" },
   },
 });
 
@@ -23,25 +33,137 @@ const command = positionals[0] ?? "serve";
 
 if (values.help) {
   console.log(`
-zhihand — MCP Server for phone control
+zhihand — MCP Server and Relay for phone control
 
 Usage:
-  zhihand serve              Start MCP Server (stdio mode)
-  zhihand serve --http       Start MCP Server (HTTP mode)
+  zhihand start              Start daemon (MCP Server + Relay, foreground)
+  zhihand start -d           Start daemon in background (detach)
+  zhihand stop               Stop daemon
+  zhihand status             Show status (pairing, backend, brain)
+
+  zhihand gemini             Switch backend to Gemini CLI
+  zhihand claude             Switch backend to Claude Code
+  zhihand codex              Switch backend to Codex CLI
+
+  zhihand setup              Interactive setup: pair + configure + start
   zhihand pair               Pair with a phone device
-  zhihand status             Show pairing status and device info
   zhihand detect             Detect available CLI tools
-  zhihand setup              Interactive setup: pair + configure
+
+  zhihand serve              Start MCP Server (stdio mode, backward compat)
 
 Options:
   --device <name>    Use a specific paired device
+  --port <port>      Override daemon port (default: 18686)
+  -d, --detach       Run daemon in background
   -h, --help         Show this help
 `);
   process.exit(0);
 }
 
+// ── Backend switch commands: claude, codex, gemini ─────────
+
+if (Object.prototype.hasOwnProperty.call(CLI_TOOL_MAP, command)) {
+  const backendName = CLI_TOOL_MAP[command];
+  const tools = await detectCLITools();
+  const tool = tools.find((t) => t.name === backendName);
+
+  if (!tool) {
+    console.error(`Error: ${command} is not installed or not found in PATH.`);
+    console.error(`Install it first, then try again.`);
+    process.exit(1);
+  }
+
+  if (!tool.loggedIn) {
+    console.error(`Warning: ${command} is installed but not logged in.`);
+  }
+
+  // Check if daemon is running — if so, notify it via HTTP
+  const daemonPid = isAlreadyRunning();
+  const config = loadBackendConfig();
+  const previous = config.activeBackend;
+
+  if (previous === backendName) {
+    console.log(`Already using ${displayName(backendName)} as backend.`);
+    process.exit(0);
+  }
+
+  console.log(`Switching backend to ${displayName(backendName)}...`);
+
+  // Configure MCP (HTTP transport)
+  const { configured, removed } = configureMCP(backendName, previous);
+
+  if (configured) {
+    // Notify daemon if running
+    if (daemonPid) {
+      try {
+        const port = parseInt(process.env.ZHIHAND_PORT ?? "", 10) || 18686;
+        const res = await fetch(`http://127.0.0.1:${port}/internal/backend`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ backend: backendName }),
+          signal: AbortSignal.timeout(5000),
+        });
+        if (res.ok) {
+          console.log(`\nDaemon notified. Backend switched to ${displayName(backendName)}.`);
+        }
+      } catch {
+        // Daemon not responding, just save config
+        saveBackendConfig({ activeBackend: backendName });
+        console.log(`\nBackend config saved. Daemon not responding — restart with 'zhihand start'.`);
+      }
+    } else {
+      saveBackendConfig({ activeBackend: backendName });
+      console.log(`\nBackend switched to ${displayName(backendName)}.`);
+      console.log(`Start the daemon to receive prompts: zhihand start`);
+    }
+
+    if (previous && removed) {
+      console.log(`Previous backend: ${displayName(previous)} (MCP config removed).`);
+    }
+  }
+  process.exit(0);
+}
+
+// ── Other commands ─────────────────────────────────────────
+
 switch (command) {
+  case "start":
+  case "relay": {
+    if (values.detach) {
+      const { spawn: spawnChild } = await import("node:child_process");
+      const args = [process.argv[1], "start"];
+      if (values.port) args.push("--port", values.port);
+      if (values.device) args.push("--device", values.device);
+
+      const child = spawnChild(process.execPath, args, {
+        detached: true,
+        stdio: "ignore",
+        env: { ...process.env },
+      });
+      child.unref();
+      console.log(`Daemon starting in background (PID ${child.pid}).`);
+      process.exit(0);
+    }
+    const port = values.port ? parseInt(values.port, 10) : undefined;
+    await startDaemon({
+      port,
+      deviceName: values.device ?? process.env.ZHIHAND_DEVICE,
+    });
+    break;
+  }
+
+  case "stop": {
+    const stopped = stopDaemon();
+    if (stopped) {
+      console.log("Daemon stopped.");
+    } else {
+      console.log("No daemon is running.");
+    }
+    break;
+  }
+
   case "serve": {
+    // Backward compatible: stdio MCP server (for old configs)
     await startStdioServer(values.device ?? process.env.ZHIHAND_DEVICE);
     break;
   }
@@ -55,13 +177,32 @@ switch (command) {
 
   case "status": {
     const cred = loadDefaultCredential();
+    const backend = loadBackendConfig();
+    const daemonPid = isAlreadyRunning();
+
     if (cred) {
       console.log(`Paired device: ${cred.deviceName}`);
       console.log(`Credential ID: ${cred.credentialId}`);
       console.log(`Endpoint: ${cred.endpoint}`);
-      console.log(`Paired at: ${cred.pairedAt}`);
     } else {
-      console.log("No paired device. Run: zhihand pair");
+      console.log("No paired device. Run: zhihand setup");
+    }
+    console.log(`Active backend: ${backend.activeBackend ? displayName(backend.activeBackend) : "(none)"}`);
+    console.log(`Daemon: ${daemonPid ? `running (PID ${daemonPid})` : "not running"}`);
+
+    // If daemon running, get live status
+    if (daemonPid) {
+      try {
+        const port = parseInt(process.env.ZHIHAND_PORT ?? "", 10) || 18686;
+        const res = await fetch(`http://127.0.0.1:${port}/internal/status`, {
+          signal: AbortSignal.timeout(3000),
+        });
+        if (res.ok) {
+          const status = await res.json();
+          console.log(`Processing: ${status.processing ? "yes" : "idle"}`);
+          console.log(`Queue: ${status.queueLength} prompt(s)`);
+        }
+      } catch { /* daemon not responding */ }
     }
     break;
   }
@@ -73,7 +214,7 @@ switch (command) {
   }
 
   case "setup": {
-    // 1. Check/create pairing
+    // 1. Pair
     let cred = loadDefaultCredential();
     if (!cred) {
       console.log("No paired device found. Starting pairing...\n");
@@ -86,15 +227,34 @@ switch (command) {
       console.log(`\nPaired: ${cred.deviceName} (${cred.credentialId})\n`);
     }
 
-    // 2. Detect CLI tools
+    // 2. Detect tools
     const tools = await detectCLITools();
     console.log(formatDetectedTools(tools));
 
-    // 3. Setup OpenClaw if present
-    await detectAndSetupOpenClaw();
+    if (tools.length === 0) {
+      console.log("\nNo CLI tools detected. Install one of: Claude Code, Codex CLI, Gemini CLI.");
+      break;
+    }
+
+    // 3. Auto-select best tool and configure MCP (HTTP transport)
+    const best = tools.find((t) => t.loggedIn) ?? tools[0];
+    const config = loadBackendConfig();
+
+    console.log(`\nAuto-selecting backend: ${displayName(best.name)}...`);
+    // Ensure MCP URL uses correct port
+    if (values.port) {
+      process.env.ZHIHAND_PORT = values.port;
+    }
+    configureMCP(best.name, config.activeBackend);
+    saveBackendConfig({ activeBackend: best.name });
 
-    console.log("\nSetup complete. Add to your CLI tool's MCP config:");
-    console.log('  { "mcpServers": { "zhihand": { "command": "zhihand", "args": ["serve"] } } }');
+    // 4. Start daemon
+    console.log(`\nStarting daemon...\n`);
+    const port = values.port ? parseInt(values.port, 10) : undefined;
+    await startDaemon({
+      port,
+      deviceName: values.device ?? process.env.ZHIHAND_DEVICE,
+    });
     break;
   }
 

package/dist/cli/detect.js

@@ -30,8 +30,10 @@ async function detectGemini() {
     if (!isCommandAvailable("gemini"))
         return null;
     const version = tryExec("gemini --version") ?? "unknown";
-    // Check login: Google Cloud auth
-    const loggedIn = tryExec("gemini auth status") !== null;
+    // Check login: oauth_creds.json or GOOGLE_API_KEY env var
+    const loggedIn = !!process.env.GOOGLE_API_KEY
+        || !!process.env.GEMINI_API_KEY
+        || tryExec("ls ~/.gemini/oauth_creds.json") !== null;
     return { name: "gemini", command: "gemini", version, loggedIn, priority: 3 };
 }
 async function detectOpenClaw() {

package/dist/cli/mcp-config.d.ts

@@ -0,0 +1,9 @@
+import type { BackendName } from "../core/config.ts";
+/**
+ * Configure MCP (HTTP transport) for the selected backend and remove from others.
+ */
+export declare function configureMCP(backend: BackendName, previousBackend: BackendName | null): {
+    configured: boolean;
+    removed: boolean;
+};
+export declare function displayName(backend: BackendName): string;

package/dist/cli/mcp-config.js

@@ -0,0 +1,71 @@
+import { execSync } from "node:child_process";
+const DEFAULT_PORT = 18686;
+function mcpUrl() {
+    const port = parseInt(process.env.ZHIHAND_PORT ?? "", 10) || DEFAULT_PORT;
+    return `http://localhost:${port}/mcp`;
+}
+const MCP_COMMANDS = {
+    claudecode: {
+        add: () => `claude mcp add --transport http zhihand ${mcpUrl()}`,
+        remove: "claude mcp remove zhihand",
+    },
+    codex: {
+        add: () => `codex mcp add zhihand --url ${mcpUrl()}`,
+        remove: "codex mcp remove zhihand",
+    },
+    gemini: {
+        add: () => `gemini mcp add --transport http --scope user zhihand ${mcpUrl()}`,
+        remove: "gemini mcp remove --scope user zhihand",
+    },
+};
+const DISPLAY_NAMES = {
+    claudecode: "Claude Code",
+    codex: "Codex CLI",
+    gemini: "Gemini CLI",
+    openclaw: "OpenClaw",
+};
+function tryRun(cmd) {
+    try {
+        execSync(cmd, { stdio: "pipe", timeout: 10_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Configure MCP (HTTP transport) for the selected backend and remove from others.
+ */
+export function configureMCP(backend, previousBackend) {
+    let removed = false;
+    let configured = false;
+    // Remove from previous backend if different
+    if (previousBackend && previousBackend !== backend && previousBackend !== "openclaw") {
+        const cmds = MCP_COMMANDS[previousBackend];
+        if (cmds) {
+            console.log(`  Removing MCP config from ${DISPLAY_NAMES[previousBackend]}...`);
+            removed = tryRun(cmds.remove);
+        }
+    }
+    // Add to new backend
+    if (backend === "openclaw") {
+        console.log(`  OpenClaw uses plugin system. Run: openclaw plugins install @zhihand/mcp`);
+        configured = true;
+    }
+    else {
+        const cmds = MCP_COMMANDS[backend];
+        const addCmd = cmds.add();
+        console.log(`  Configuring MCP for ${DISPLAY_NAMES[backend]} (HTTP transport)...`);
+        try {
+            execSync(addCmd, { stdio: "inherit", timeout: 10_000 });
+            configured = true;
+        }
+        catch (err) {
+            console.error(`  Failed to configure ${DISPLAY_NAMES[backend]}: ${err.message}`);
+        }
+    }
+    return { configured, removed };
+}
+export function displayName(backend) {
+    return DISPLAY_NAMES[backend];
+}

package/dist/cli/spawn.d.ts

@@ -1,2 +1,23 @@
 import type { CLITool } from "./detect.ts";
-export declare function spawnCLITask(tool: CLITool, prompt: string): Promise<string>;
+export interface SpawnOptions {
+    model?: string;
+    timeout?: number;
+}
+/**
+ * Spawn a CLI tool interactively, inheriting stdio.
+ * Returns the exit code.
+ */
+export declare function spawnInteractive(command: string, args: string[], options?: {
+    timeout?: number;
+    env?: Record<string, string>;
+}): Promise<number>;
+/**
+ * Launch a CLI tool with a prompt. For Gemini, uses interactive mode (-i).
+ * For others, uses their respective prompt flags.
+ */
+export declare function launchCLI(tool: CLITool, prompt: string, options?: SpawnOptions): Promise<number>;
+/**
+ * Non-interactive spawn that captures output (for MCP-initiated tasks).
+ * Uses spawnSync with argument arrays to avoid shell injection.
+ */
+export declare function spawnCLITask(tool: CLITool, prompt: string): string;