@mindfullabai/onda-mcp 0.3.2 → 0.5.1

package/dist/index.js

@@ -577,6 +577,195 @@ const TOOLS = [
             required: ['workspace', 'bin'],
         },
     },
+    // --- Agent delegation (preferred over onda_launch_session) ---
+    // These three tools (`spawn` / `wait` / `close`) are the canonical
+    // entry points for "Claude session A delegates work to Claude session
+    // B via Onda mosaic". They expose the same composer pipeline as the
+    // legacy onda_launch_session but with three improvements:
+    //   1. Three placement modes (workspace / pane-split / same-workspace)
+    //      so the caller can decide whether to splice a new tile, split a
+    //      pane in the current workspace, or just add a terminal to an
+    //      already-mounted workspace.
+    //   2. The mount path goes through the post-fix `mountWorkspaceInTile`
+    //      flow, so the tile actually appears in the UI (the legacy
+    //      launchSession path only set the active workspace, which after
+    //      the B1 fix in Onda 1.9.1 was no longer enough on its own).
+    //   3. Optional `subscribe + sessionId` so the caller can immediately
+    //      hand the sessionId to `onda_agent_wait` without a separate
+    //      `terminal_subscribe` round-trip.
+    //
+    // The legacy `onda_launch_session` tool still works (it maps to the
+    // same backend handler) but is kept only for backward compatibility.
+    // New code should prefer `onda_agent_spawn`.
+    {
+        name: 'onda_agent_spawn',
+        description: 'Boot an agent in a workspace+pane and return once the TUI is ready to accept a prompt. Does NOT submit a task — use `onda_agent_prompt` after spawn for that. Splitting bootstrap and prompt delivery makes the flow resilient: you can retry the prompt without re-paying the agent cold-start (5-10s for Claude), and you can intercept unexpected TUI states (trust dialog, model picker) between the two steps. Placement modes: "workspace" (default — full create+mount+add), "pane-split" (split active pane of current workspace), "same-workspace" (add a terminal to an already-mounted workspace). For non-TUI binaries (bash, scripts), pass the full command in `agentArgs` and use `execMode: "run"`; `onda_agent_prompt` is then unnecessary.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                placement: {
+                    type: 'string',
+                    enum: ['workspace', 'pane-split', 'same-workspace'],
+                    description: 'Where to host the new agent terminal. Default "workspace": create-or-locate workspace + mount + add terminal. "pane-split": split the active pane of the focused workspace. "same-workspace": add a terminal pane to an existing mounted workspace (requires `workspaceId`).',
+                },
+                // --- placement=workspace ---
+                workspaceRootPath: {
+                    type: 'string',
+                    description: 'placement=workspace: filesystem path used to locate (or create) the workspace. If the workspace does not exist and rootPath is set, it will be auto-created (name = basename of rootPath unless `workspaceName` is given).',
+                },
+                workspaceName: {
+                    type: 'string',
+                    description: 'placement=workspace: optional override for the auto-created workspace name. Ignored if a workspace already matches `workspaceRootPath`.',
+                },
+                targetWindowId: {
+                    type: 'string',
+                    description: 'placement=workspace: window to mount the workspace in. Default: focused window.',
+                },
+                mountDirection: {
+                    type: 'string',
+                    enum: ['down', 'right'],
+                    description: 'placement=workspace: where to splice the new tile in the mosaic. Default "down" (matches the Cmd+P picker default).',
+                },
+                // --- placement=pane-split ---
+                splitDirection: {
+                    type: 'string',
+                    enum: ['right', 'down', 'left', 'up', 'horizontal', 'vertical'],
+                    description: 'placement=pane-split: how to split the active pane. Default "down".',
+                },
+                splitCwd: {
+                    type: 'string',
+                    description: 'placement=pane-split: cwd of the new pane (typically the project root the delegated agent should work in).',
+                },
+                // --- placement=same-workspace ---
+                workspaceId: {
+                    type: 'string',
+                    description: 'placement=same-workspace: id of an already-mounted workspace to add a terminal to.',
+                },
+                addDirection: {
+                    type: 'string',
+                    enum: ['right', 'down'],
+                    description: 'placement=same-workspace: split direction for the new pane. Default "down".',
+                },
+                // --- universal ---
+                agentName: {
+                    type: 'string',
+                    description: 'Listener label shown in the pane header (e.g. "kai-2026-05-23"). Recommended: include a date or session identifier so the user can tell concurrent delegations apart.',
+                },
+                agentBin: {
+                    type: 'string',
+                    description: 'Binary to exec inside the pane. Default "claude". Any PATH-resolvable executable works (claude, qwen, codex, bash, etc.).',
+                },
+                agentArgs: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Extra argv entries appended after the binary. For TUI agents (claude/qwen): use flags only (e.g. ["--dangerously-skip-permissions"]) — DO NOT include the task prompt here; submit it separately via onda_agent_prompt once readyPattern has matched. For non-TUI bins (bash/sh): include the full command line, e.g. ["-lc", "build.sh && echo DONE"].',
+                },
+                execMode: {
+                    type: 'string',
+                    enum: ['exec', 'run'],
+                    description: 'How to hand the binary to the pane\'s existing shell. Default "exec": writes `exec bin args` so the binary REPLACES the shell (right for long-lived TUI agents like claude/qwen — they own the pane, no shell prompt visible). Set to "run" for one-shot commands (build, script, quick check): writes `bin args` plainly, the shell runs it as a child and re-prompts when done, so the PTY stays alive and `agent.wait` subscribers survive even for short tasks. Wrong choice for short tasks under "exec" causes the PTY to exit the moment the command completes, wiping any pending wait subscriber.',
+                },
+                readyPattern: {
+                    type: 'string',
+                    description: 'JavaScript regex (string form). When set, agent.spawn blocks until the pattern matches new output before returning. Use it to synchronize on "TUI is ready for a prompt" — for Claude TUI a good default is "❯|Welcome back|Try \\"|bypass permissions"; for qwen "qwen>|Ready"; for bash this is unnecessary. The response includes `ready: true` on match, `ready: false` on timeout (caller decides whether to proceed).',
+                },
+                readyTimeoutMs: {
+                    type: 'number',
+                    description: 'Max wait for readyPattern in ms. Default 15000 (15s — enough for Claude cold-start on a busy machine).',
+                },
+                subscribe: {
+                    type: 'boolean',
+                    description: 'Attach a listener and return a `sessionId` ready for `onda_agent_wait`. Default true. Also lights up the presence badge in the pane header.',
+                },
+                snapshotDelay: {
+                    type: 'number',
+                    description: 'Milliseconds to wait before reading the first chunk of buffer for the `firstChunk` field in the response. Default 500. Set to 0 to skip the snapshot. Ignored if readyPattern matched and provided a sync point already.',
+                },
+            },
+            required: ['agentBin'],
+        },
+    },
+    {
+        name: 'onda_agent_prompt',
+        description: 'Submit a task prompt to an agent that was previously spawned with `onda_agent_spawn`. Use this once `onda_agent_spawn` has returned with `ready: true` (TUI textbox is up and accepting keystrokes). Writes the prompt as raw text into the PTY, then optionally sends Enter to submit. Idempotent in the sense that you can call it multiple times — useful for multi-line drafts (each call with `submitWith: "none"` except the last) or for retry-on-blocker scenarios.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                terminalId: {
+                    type: 'string',
+                    description: 'Terminal id from `onda_agent_spawn` response (paneId === terminalId for terminal-content panes).',
+                },
+                prompt: {
+                    type: 'string',
+                    description: 'The text to write. For TUI agents this populates the textbox. No shell-quoting — the caller talks to a TUI, not a shell. Caller is responsible for any agent-bus preamble (e.g. "# STATUS:", "# DONE" sentinels, "/send kai brief: ..." vocabulary). Onda stays opinion-free about protocol semantics.',
+                },
+                submitWith: {
+                    type: 'string',
+                    enum: ['enter', 'none'],
+                    description: 'How to submit the prompt. "enter" (default) writes a CR after the text — this is what most TUIs need to actually submit. "none" leaves the text in the buffer without submitting; use this when chaining multiple writes (e.g. multi-line draft, each call writing one line with submitWith=none, the final one with submitWith=enter).',
+                },
+                readyPattern: {
+                    type: 'string',
+                    description: 'Optional defensive ready-sync regex. If provided, `agent.prompt` first runs a quick `waitForPattern` (default 5s timeout) before writing. Cheap when the buffer already matches; safety net when the caller is racing TUI cold-start. Generally redundant if `agent.spawn` already synced on the same pattern.',
+                },
+                readyTimeoutMs: {
+                    type: 'number',
+                    description: 'Max wait for `readyPattern` in ms. Default 5000.',
+                },
+                preWriteDelay: {
+                    type: 'number',
+                    description: 'Optional ms delay between ready-sync and the actual write. Some TUIs need a beat to finish layout transitions even after the textbox is technically present.',
+                },
+                postSubmitDelay: {
+                    type: 'number',
+                    description: 'Optional ms delay after sending Enter, before returning. Useful if you want to give the agent a moment to start streaming output that the next caller-side step (terminal_read snapshot, agent_wait) will need.',
+                },
+            },
+            required: ['terminalId', 'prompt'],
+        },
+    },
+    {
+        name: 'onda_agent_wait',
+        description: 'Block on a subscriber session until a regex matches new terminal output, or timeout. Use this after `onda_agent_spawn` to wait for a sentinel pattern that indicates the delegated agent is done (or has hit a blocker). Returns { matched, match?, bufferedChunks, tailContent? } where tailContent is the last ~4KB of accumulated output (useful for surfacing a summary to the user or for debugging mismatched expectations).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sessionId: {
+                    type: 'string',
+                    description: 'Session id returned by `onda_agent_spawn` (or by a manual `onda_terminal_subscribe`).',
+                },
+                doneRegex: {
+                    type: 'string',
+                    description: 'JavaScript regex (string form). Default matches `^# DONE`, `^# BLOCKED`, or `Esc to interrupt`. Pick a sentinel that matches whatever the agent-bus protocol used by your team prescribes.',
+                },
+                timeoutMs: {
+                    type: 'number',
+                    description: 'Max wait in ms. Default 300000 (5 min). Cap to whatever your task complexity warrants.',
+                },
+                flags: {
+                    type: 'string',
+                    description: 'Regex flags. Default "m" (multiline).',
+                },
+            },
+            required: ['sessionId'],
+        },
+    },
+    {
+        name: 'onda_agent_close',
+        description: 'Escalation cleanup after an agent finishes (or to abandon a delegation). Three levels: SOFT — only `sessionId` set → unsubscribe (keeps PTY alive, lets you reattach or let the user inspect). MEDIUM — `+ killPty + terminalId` → terminates the agent process. HARD — `+ unmountWorkspace + workspaceId` (and optionally `+ closeWindow + windowId`) → full teardown of an ephemeral delegation. All fields are optional; the tool does only what you ask.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sessionId: { type: 'string', description: 'Subscriber session to detach. Idempotent.' },
+                terminalId: { type: 'string', description: 'Terminal to kill. Required when `killPty` is true.' },
+                workspaceId: { type: 'string', description: 'Workspace to unmount. Required when `unmountWorkspace` is true.' },
+                killPty: { type: 'boolean', description: 'Default false. When true, the underlying PTY process is terminated (UI shows [Process exited]).' },
+                unmountWorkspace: { type: 'boolean', description: 'Default false. When true, the workspace is dropped from its window\'s mosaic. The workspace itself still exists in the global list.' },
+                closeWindow: { type: 'boolean', description: 'Default false. When true, the host window is closed via `BrowserWindow.close()`. Requires `windowId`. Only use when YOU spawned this window via `onda_window_new`.' },
+                windowId: { type: 'string', description: 'Required when `closeWindow` is true.' },
+            },
+        },
+    },
     // --- System ---
     {
         name: 'onda_context',
@@ -695,6 +884,65 @@ const TOOL_MAP = {
         }),
     },
     onda_launch_session: { method: 'launchSession' },
+    // Agent delegation: forward EVERY declared param to the backend. Do
+    // not silently drop fields (the old `workspace.addTerminal` mapParams
+    // bug was caused exactly by that: schema declared `direction`, mapper
+    // omitted it, calls silently fell back to default placement).
+    onda_agent_spawn: {
+        method: 'agent.spawn',
+        mapParams: (args) => ({
+            placement: args.placement,
+            workspaceRootPath: args.workspaceRootPath,
+            workspaceName: args.workspaceName,
+            targetWindowId: args.targetWindowId,
+            mountDirection: args.mountDirection,
+            splitDirection: args.splitDirection,
+            splitCwd: args.splitCwd,
+            workspaceId: args.workspaceId,
+            addDirection: args.addDirection,
+            agentName: args.agentName,
+            agentBin: args.agentBin,
+            agentArgs: args.agentArgs,
+            execMode: args.execMode,
+            subscribe: args.subscribe,
+            snapshotDelay: args.snapshotDelay,
+            readyPattern: args.readyPattern,
+            readyTimeoutMs: args.readyTimeoutMs,
+        }),
+    },
+    onda_agent_prompt: {
+        method: 'agent.prompt',
+        mapParams: (args) => ({
+            terminalId: args.terminalId,
+            prompt: args.prompt,
+            submitWith: args.submitWith,
+            readyPattern: args.readyPattern,
+            readyTimeoutMs: args.readyTimeoutMs,
+            preWriteDelay: args.preWriteDelay,
+            postSubmitDelay: args.postSubmitDelay,
+        }),
+    },
+    onda_agent_wait: {
+        method: 'agent.wait',
+        mapParams: (args) => ({
+            sessionId: args.sessionId,
+            doneRegex: args.doneRegex,
+            timeoutMs: args.timeoutMs,
+            flags: args.flags,
+        }),
+    },
+    onda_agent_close: {
+        method: 'agent.close',
+        mapParams: (args) => ({
+            sessionId: args.sessionId,
+            terminalId: args.terminalId,
+            workspaceId: args.workspaceId,
+            killPty: args.killPty,
+            unmountWorkspace: args.unmountWorkspace,
+            closeWindow: args.closeWindow,
+            windowId: args.windowId,
+        }),
+    },
     // System (onda_context handled separately - it's local, not RPC)
     onda_status: { method: 'session.current' },
     onda_app_info: { method: 'app.info' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindfullabai/onda-mcp",
-  "version": "0.3.2",
+  "version": "0.5.1",
   "description": "MCP server for Onda terminal - control tabs, panes, terminals from AI agents",
   "type": "module",
   "main": "./dist/index.js",

package/skills/onda-mcp-usage/SKILL.md

@@ -2,22 +2,30 @@
 name: onda-mcp-usage
 description: Best practices for driving Onda (terminal emulator) from Claude Code via the `onda` MCP server (`mcp__onda__*`). Covers workspaces/windows/panes/terminals + buffer reading (read/subscribe/poll/wait_for/send_keys) + spatial awareness (layout/screenshot). Use whenever you call any `mcp__onda__*` tool or the user mentions Onda, pane, workspace, terminal listener, presence badge, inception loop (Claude controlling Onda from inside Onda). Triggers — onda mcp, drive onda, control onda terminal, show pane, workspace layout, onda screenshot, kai watcher, terminal listener.
 metadata:
-  version: 0.3.1
+  version: 0.5.0
   source: '@mindfullabai/onda-mcp'
 ---
 
 # Onda MCP usage skill
 
-This skill tells you **how to correctly use the `mcp__onda__*` tools** exposed by the `onda-mcp` server (~40 tools as of 0.3.1). It is installed alongside the MCP server. Without this guide you miss non-obvious patterns (subscribe vs read, direction semantics, multi-window orchestration, inception loop).
+This skill tells you **how to correctly use the `mcp__onda__*` tools** exposed by the `onda-mcp` server (~42 tools as of 0.4.0). It is installed alongside the MCP server. Without this guide you miss non-obvious patterns (subscribe vs read, direction semantics, multi-window orchestration, agent delegation atomic macro, inception loop).
 
 ## Compatibility note
 
-Some bug fixes shipped in `@mindfullabai/onda-mcp@0.3.1` + Onda 1.9.1+:
+Breaking change in `@mindfullabai/onda-mcp@0.5.0`:
+- `onda_agent_spawn` no longer accepts a `prompt` argument. Prompt delivery is now a separate call, `onda_agent_prompt`, gated on a `readyPattern` sync. See "Pattern: agent delegation" below for the new four-tool flow. The split makes the pipeline resilient against TUI cold-start race conditions (trust dialog, splash screen, model picker) that previously caused the Enter keystroke to land on the wrong control.
+- `submitDelay` is removed from `onda_agent_spawn` (the spawn never auto-submits anymore). Use `agent_prompt` with `preWriteDelay` if you really need a beat between ready-sync and the write.
+- The legacy `onda_launch_session` is unchanged and still accepts the v2 `prompt` argv + auto-submit semantics; use it if you have existing callers you don't want to touch.
+
+New in `@mindfullabai/onda-mcp@0.4.0`:
+- **Agent delegation tools**: `onda_agent_spawn` + `onda_agent_wait` + `onda_agent_close` (0.5.0 added `onda_agent_prompt`). Replaces the 6-step manual dance. Three placement modes (workspace / pane-split / same-workspace).
+
+Bug fixes shipped in `@mindfullabai/onda-mcp@0.3.1` + Onda 1.9.1+:
 - `terminal_read` now returns the full buffer even on first call (eager tap attach at PTY spawn). Pre-0.3.1 a fresh terminal returned an empty buffer until `subscribe` was active.
 - `workspace_add_terminal` now respects `direction='down'` (was silently rewritten to `'row'` whenever the anchor was already in a row split).
 - `window_mount_workspace` now actually splices the workspace into the tiled mosaic (pre-fix the registry was updated but the UI tab/tile never appeared). Accepts `direction` ('down'|'right', default 'down') and `anchorWorkspaceId` mirroring the Cmd+P picker.
 
-If you are talking to an older host, fall back to the legacy patterns: subscribe before run, avoid direction='down' on add_terminal, click-mount via the user.
+If you are talking to an older host (Onda < 1.9.1), fall back to the legacy patterns: subscribe before run, avoid direction='down' on add_terminal, click-mount via the user. The `agent_spawn` tool will respond with `{error: "Unknown method"}` if the host pre-dates 0.4.0 — fall back to `onda_launch_session` in that case.
 
 ## Mental model
 
@@ -43,6 +51,10 @@ Internal workspace layout = mosaic-component tree. Read it via `onda_workspace_l
 | "Move workspace W from one window to another" | `onda_window_mount_workspace` with target `windowId` (atomic transfer, returns `transferred: true`) |
 | "Drop workspace from its window without deleting it" | `onda_workspace_unmount` (registry slot released, PTYs survive) |
 | "Bring a window to front" | `onda_window_focus` (omit `windowId` to focus primary) |
+| "Boot an agent in a workspace" | `onda_agent_spawn` (mount + add terminal + exec bin + readyPattern sync) |
+| "Submit a task prompt to a TUI agent" | `onda_agent_prompt` (after spawn returned ready:true) |
+| "Wait until the delegated agent reports done" | `onda_agent_wait` with `doneRegex` |
+| "Clean up after a delegation" | `onda_agent_close` (escalation: soft → kill → unmount → close window) |
 | "Read what the terminal has printed so far" | `onda_terminal_read` (no subscribe needed) |
 | "I want to receive every new output chunk" | `subscribe` + `poll` loop |
 | "Wait until the build finishes" | `onda_terminal_wait_for` with regex |
@@ -162,7 +174,121 @@ screenshot = window_screenshot(windowId, format="jpeg", quality=72, dataUrl=fals
 
 Default `dataUrl=true` returns inline base64 (~1-2 MB), `dataUrl=false` writes a tempfile that `Read` mounts as multimodal image — preferred to avoid wasting context.
 
-## Pattern: launching Claude Code in a pane (inception)
+## Pattern: agent delegation (PREFERRED, two-call for TUIs)
+
+When you need to delegate work to another Claude session (or any TUI agent) — e.g. Alita @ work-hub asks Kai to refactor something in Orbit — use the four-tool flow: `onda_agent_spawn` → `onda_agent_prompt` → `onda_agent_wait` → `onda_agent_close`. The first two are the meat; `wait` and `close` are observation + cleanup.
+
+The flow is **split into spawn + prompt** intentionally. Booting a TUI like Claude costs 5-10s and runs through several transient states (trust dialog → splash → welcome → textbox). Submitting the prompt while the TUI is still in trust dialog state means the Enter goes to the dialog, not your prompt. Splitting the two phases gives you a sync point (`readyPattern`) and lets you retry just the prompt if delivery fails, without re-paying the cold start.
+
+```
+# 1. Spawn (boot only — no prompt yet)
+spawn = agent_spawn(
+  placement="workspace",                       # create-or-locate workspace + mount + add terminal
+  workspaceRootPath="~/Projects/04-Production/Orbit",
+  mountDirection="right",                      # splice the new tile to the right
+  agentName="kai-2026-05-23",                  # listener label in pane header
+  agentBin="claude",
+  agentArgs=["--dangerously-skip-permissions"], # flags only, NOT the task prompt
+  readyPattern="❯|Welcome back|Try \"",        # block until Claude TUI textbox is up
+  readyTimeoutMs=20000,                        # generous: Claude cold-start
+  subscribe=True,                              # default; returns sessionId for agent_wait
+)
+# → {sessionId, terminalId, paneId, workspaceId, windowId, ready: True, firstChunk, completedSteps:[...,'ready_sync']}
+
+if not spawn.ready:
+    # readyPattern didn't match — TUI is in an unexpected state.
+    # Inspect spawn.firstChunk to see where it got stuck (trust dialog?
+    # model picker? bin not found?). Decide whether to retry, send keystrokes
+    # to navigate the dialog, or give up and call agent_close.
+    ...
+
+# 2. Submit the task prompt
+agent_prompt(
+  terminalId=spawn.terminalId,
+  prompt="/send kai brief: refactor Authenticator.swift; target test file Tests/AuthTests.swift; report '# DONE' on its own line when green",
+  submitWith="enter",                          # default; press Enter to submit
+)
+# → {success: True, bytesWritten, completedSteps:['write','submit']}
+
+# 3. Wait for the agent to signal completion
+result = agent_wait(
+  sessionId=spawn.sessionId,
+  doneRegex="DONE|BLOCKED",                    # see "doneRegex pattern" below
+  timeoutMs=15000,                              # short window, loop if needed
+  timeoutMs=600000,                            # 10 min budget
+)
+# → {matched: True, match: "# DONE", tailContent: "...last 4KB..."}
+
+# 4. Clean up. SOFT (default): unsubscribe only, leave the PTY alive so the
+#    user can inspect. MEDIUM (+killPty + terminalId): terminate the agent.
+#    HARD (+unmountWorkspace + workspaceId): drop the workspace tile.
+agent_close(sessionId=spawn.sessionId)
+```
+
+### doneRegex pattern: match across renderers
+
+Don't be too literal with `# DONE`. TUI agents re-render markdown: Claude turns `# DONE` into a styled bullet `⏺ DONE` (with bold + italic + underline ANSI), qwen prefixes timestamps, codex may emit `[DONE]`. Pick a pattern that survives the visual layer.
+
+Recommended generic patterns for delegated agents:
+
+```
+# Most resilient — matches DONE/BLOCKED regardless of bullet, prefix, or styling
+doneRegex = "(DONE|BLOCKED|FAILED|ERROR)\\b"
+
+# Conservative — matches the literal sentinel words preceded by whitespace, bullet, or markdown header
+doneRegex = "(^|\\s|[#⏺\\-\\*•])\\s*(DONE|BLOCKED|FAILED)\\b"
+
+# Strict — your team enforces "# DONE" / "# BLOCKED" exactly (works when the agent runs in a non-TUI shell, e.g. bash one-shot)
+doneRegex = "^# (DONE|BLOCKED)"
+```
+
+For Claude TUI specifically, the markdown `# DONE` in the agent's reply becomes `⏺ DONE` on screen. The bullet glyph `⏺` (U+23FA) is the most reliable marker because Claude always renders it before H1 sentinels. Combined patterns work well: `"(⏺|^|^#)\\s*DONE"`.
+
+### Long-running tasks: chunked polling
+
+`agent_wait` blocks server-side until the regex matches or `timeoutMs` elapses. **But the MCP JSON-RPC client has its own timeout (~60s)**: a single `agent_wait(timeoutMs=300000)` call will fail client-side with "Connection timeout" long before the backend would have returned, even if the agent eventually completes in time.
+
+For any task likely to take >30s, do **chunked polling**: loop with a short timeout, check `matched`, repeat until done or your budget is spent.
+
+```
+budget = 600  # 10 minutes
+elapsed = 0
+while elapsed < budget:
+    r = agent_wait(sessionId, doneRegex=..., timeoutMs=15000)
+    if r.matched:
+        break
+    elapsed += 15
+else:
+    # timed out
+    ...
+```
+
+The session cursor advances on each poll, so you don't re-scan bytes from the previous loop iteration; only new emissions are evaluated.
+
+### Why split spawn + prompt?
+
+Concretely: the alternative (single `agent_spawn` call that also submits the prompt) was tried — `claude --prompt` as argv mostly works for short prompts, but a multi-line / long prompt can land in the textbox while the trust dialog is still active, and the Enter goes to the dialog instead of submitting. The split flow has two side benefits:
+
+1. **Retry-on-failure is cheap**: if `agent_prompt` reports `errorCode: "not_ready"`, you re-call `agent_prompt` (potentially after `terminal_read` to see what's blocking) without ever touching the PTY-spawn cost.
+2. **TUI navigation between phases**: occasionally claude shows a model picker or "select profile" screen before the textbox. Between `agent_spawn` (which can target `readyPattern="select profile"`) and `agent_prompt`, the caller can send `send_keys(["Enter"])` to dismiss it, then proceed.
+
+### Placement modes
+
+| Mode | When to use |
+|------|-------------|
+| `workspace` (default) | Long isolated delegation. New tile alongside yours in the same window. Survives across delegations. |
+| `pane-split` | Quick parallel work in the SAME workspace you're already in. The agent's cwd is `splitCwd`. Nothing to clean up at the workspace level. |
+| `same-workspace` | The target workspace is already mounted (`workspaceId`). Just add another terminal pane to it — useful when several agents share one repo. |
+
+### What `agent.spawn` does NOT do
+
+- **Protocol preamble**: the `prompt` field is sent verbatim (modulo shell-quote). If your team has agent-bus conventions like `# STATUS:`, `/send`, `# DONE` markers — compose them into the prompt yourself before calling. This is intentional: Onda stays opinion-free about agent communication semantics, the agent-bus skill is the source of truth for that vocabulary.
+- **Result aggregation**: `agent_wait` returns raw `tailContent`. Parsing structured output (extracting commit hashes, PR URLs, etc.) lives in the caller.
+- **Workspace limit handling**: in free/dev builds Onda caps at 2 workspaces. When the cap is reached `agent_spawn` returns `{success: false, errorCode: "workspace_limit_reached", needsUserAction: true, hint: "..."}` — surface that to the user, do not retry blindly.
+
+## Pattern: launching Claude Code in a pane (legacy, manual)
+
+Pre-`agent_spawn` (0.3.x and earlier) pattern. Still works, but verbose. New code should prefer the section above.
 
 ```
 pane = workspace_add_terminal(workspaceId="...", direction="right")
@@ -303,6 +429,7 @@ Con: prompt cache miss every 15 min (cache threshold 5 min), non-zero token cost
 3. **`workspace_add_terminal` without prior `workspace_layout`**: blind placement. Append-right quickly becomes unreadable.
 4. **Listener without unsubscribe**: leak for 30 min TTL. UI badge stays. Clean up.
 5. **`window_new`** when the user just wants "one more workspace on the right": NO. Use `window_mount_workspace(workspaceId, windowId=current, direction='right')` to splice it into the existing window as a side-by-side tile. Open a new window only when the user actually wants two separate windows.
+9. **Manual 6-step delegation dance** (`workspace_locate` → `workspace_create` → `window_mount_workspace` → `workspace_add_terminal` → `terminal_spawn` → `send_keys Enter` → `terminal_subscribe`): NO. Use `onda_agent_spawn` — it composes all of these atomically and avoids the race conditions where a fail mid-sequence leaves orphaned state.
 6. **Assuming `app_info.name === "Onda-dev"`** distinguishes dev vs prod: NO. Use `app_info.path` or an explicit flag.
 7. **`terminal_run` alone to submit a prompt to Claude TUI**: NO. The TUI treats `\n` as newline buffer. You must always follow with `send_keys(["Enter"])` to actually submit. (Validated 21 May 2026 spawning a dedicated Kai.)
 8. **Spawning Kai and then waiting for Mario to click and type**: anti-pattern. If you spawned the session, you drive it to "Kai is working" (pattern "drive a remote Claude Code session"). Mario shouldn't be a human postman in your agent team.
@@ -314,7 +441,7 @@ Con: prompt cache miss every 15 min (cache threshold 5 min), non-zero token cost
 - Onda uses a **single UDS socket**, `~/.config/onda/onda.sock`. Only one Onda instance answers MCP at a time (the first to bind). If `app_info` shows odd data, you may be talking to a different instance.
 - The MCP server holds the socket binding until the master Onda app exits — restarting Onda via Cmd+Q + relaunch is how you "promote" another instance to master.
 
-## Tool reference (38 total)
+## Tool reference (~42 total)
 
 Application:
 - `onda_app_info` — version, pid, paths
@@ -364,7 +491,13 @@ Terminal (read/listen plane, M+1 2026-05-21):
 
 Session:
 - `onda_session_current` — current CLI consumer session
-- `onda_launchSession` — atomic macro "open workspace + add terminal + spawn bin"
+- `onda_launch_session` — atomic macro "open workspace + add terminal + spawn bin" (DEPRECATED, use `onda_agent_spawn`)
+
+Agent delegation (preferred since 0.4.0, split into spawn+prompt in 0.5.0):
+- `onda_agent_spawn` — boot an agent in a workspace+pane and return when `readyPattern` matches (or timeout). Returns `sessionId` + `firstChunk`. Does NOT submit a prompt.
+- `onda_agent_prompt` — write a prompt into the spawned agent's TUI textbox and submit it. Has its own optional `readyPattern` defensive sync.
+- `onda_agent_wait` — block on the spawned agent's sessionId until `doneRegex` matches; returns matched chunk + tail content.
+- `onda_agent_close` — escalation cleanup: unsubscribe → kill PTY → unmount workspace → close window. Each step opt-in via boolean flags.
 
 ## Versioning