Session tools
Start, escalate, inspect and end lifecycle sessions.
Start, escalate, inspect and end lifecycle sessions.
| Tool | Description | Platforms |
|---|---|---|
start_session | Optionally create or return a lifecycle session before acting. | macOS, Linux, Windows |
escalate_session | Deprecated compatibility tool for legacy capture-scope sessions. | macOS, Linux, Windows |
get_session | Read content-free lifecycle, cursor, recording, and idle status for one session visible to this authenticated transport. | macOS, Linux, Windows |
list_sessions | List content-free lifecycle summaries attached to this authenticated transport lease. | macOS, Linux, Windows |
get_session_state | Deprecated compatibility alias that reads a live legacy session's capture policy. | macOS, Linux, Windows |
end_session | End one visible lifecycle session and run its cursor, recording, configuration, and other cleanup hooks exactly once. | macOS, Linux, Windows |
Served by cua-driver mcp; see MCP tools for every tool.
start_session#Optionally create or return a lifecycle session before acting. For multi-call work, prefer a short public session label and repeat it on every call that accepts it; an omitted value uses the authenticated transport lease's implicit session instead. This tool is optional because an ordinary action can create or reuse a named run directly. Use it to set the initial cursor theme before acting or to revive a public name after it has ended; ordinary actions never revive ended names. capture_scope is deprecated compatibility input; new callers select window or desktop modality per action. Idempotent.
Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
| Parameter | Type | Default | Description |
|---|---|---|---|
capture_scope | "auto" | "window" | "desktop" | Deprecated compatibility policy. New callers select window or desktop modality on each action instead of storing it on the session. | |
cursor_theme | object | Optional initial cursor theme. The host applies it before the cursor is first made visible, avoiding a flash of the default theme. | |
cursor_theme.reduced_motion | "auto" | "on" | "off" | "auto" | |
cursor_theme.theme_id | string | ||
session | string | Optional stable public label for this run (e.g. "research-run-1"). When omitted, the authenticated transport lease's implicit session is created or returned. |
escalate_session#Deprecated compatibility tool for legacy capture-scope sessions. New callers select window or desktop modality on each action. No deescalate_session tool exists.
Effect: mutating. Platforms: macOS, Linux, Windows.
| Parameter | Type | Default | Description |
|---|---|---|---|
detail | string | Optional bounded diagnostic detail. Never use secrets or page content. | |
reason | "ax_tree_pixel_mismatch" | "background_delivery_failed" | "foreground_ineffective" | "no_window_target" | "other" | required | Why the window-scoped attempt failed and desktop capture is needed. |
session | string | required | Public label of the legacy capture-scope session to escalate. |
Example arguments
{"session":"<session>","reason":"ax_tree_pixel_mismatch"}get_session#Read content-free lifecycle, cursor, recording, and idle status for one session visible to this authenticated transport. Omit session to inspect its implicit session.
Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
| Parameter | Type | Default | Description |
|---|---|---|---|
session | string | Optional public label. When omitted, inspect the caller's attached implicit session. |
list_sessions#List content-free lifecycle summaries attached to this authenticated transport lease. It does not enumerate other callers' sessions.
Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
| Parameter | Type | Default | Description |
|---|---|---|---|
cursor | string | Opaque continuation cursor returned by a previous call. | |
limit | integer | Maximum number of content-free summaries to return (default 50, max 100). Ordinary agent transports are scoped to their own lease. Minimum: 0. |
get_session_state#Deprecated compatibility alias that reads a live legacy session's capture policy. Use get_session for lifecycle state.
Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
| Parameter | Type | Default | Description |
|---|---|---|---|
session | string | Optional public label. When omitted, inspect the caller's attached implicit session. |
end_session#End one visible lifecycle session and run its cursor, recording, configuration, and other cleanup hooks exactly once. Omit session to end the authenticated transport's implicit session. Idempotent.
Effect: destructive, idempotent. Platforms: macOS, Linux, Windows.
| Parameter | Type | Default | Description |
|---|---|---|---|
session | string | Optional public label to end. When omitted, end the caller's attached implicit session. |