Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

fix(cua-driver): remove stale screenshot tool references (#2317)

injaneity5fbd90a3a9cc
diff --git a/docs/content/docs/cua-driver/guides/local-models.mdx b/docs/content/docs/cua-driver/guides/local-models.mdx
index 1d101db922..ae7609fa21 100644
--- a/docs/content/docs/cua-driver/guides/local-models.mdx
+++ b/docs/content/docs/cua-driver/guides/local-models.mdx
@@ -74,7 +74,7 @@ Astron Token Plan, add `--text-only` to the filter's `args`. The filter then
requests `get_window_state` without a screenshot and replaces any remaining
image content with a short text note, so the model works through the
accessibility tree and its `element_token` values. Leave pixel-only tools such
-as `screenshot` and `zoom` out of the allowlist. Without `--text-only`, a
+as `zoom` out of the allowlist. Without `--text-only`, a
provider that rejects images fails every request once a screenshot reaches
the conversation. Apps that expose no usable accessibility elements (canvas,
video, custom-drawn surfaces) need a vision model instead.
diff --git a/docs/content/docs/cua-driver/guides/permissions.mdx b/docs/content/docs/cua-driver/guides/permissions.mdx
index b0528ac1cb..aca80ab24c 100644
--- a/docs/content/docs/cua-driver/guides/permissions.mdx
+++ b/docs/content/docs/cua-driver/guides/permissions.mdx
@@ -253,7 +253,7 @@ package cua.policy
import rego.v1
-safe_tools := {"screenshot", "get_window_state", "list_apps", "list_windows", "click", "press_key", "wait"}
+safe_tools := {"get_window_state", "list_apps", "list_windows", "click", "press_key", "wait"}
allow if {
input.tool in safe_tools
diff --git a/docs/content/docs/cua-driver/reference/cli/serve-and-configure.mdx b/docs/content/docs/cua-driver/reference/cli/serve-and-configure.mdx
index 8ed4e6a307..92141ab7b4 100644
--- a/docs/content/docs/cua-driver/reference/cli/serve-and-configure.mdx
+++ b/docs/content/docs/cua-driver/reference/cli/serve-and-configure.mdx
@@ -264,7 +264,7 @@ cua-driver serve [OPTIONS]
| <span id="cua-driver-serve--dwell-ms"></span>`--dwell-ms` | number | | Override how long the agent cursor dwells after a click, in milliseconds. |
| <span id="cua-driver-serve--idle-hide-ms"></span>`--idle-hide-ms` | number | | Override how long an idle agent cursor stays visible, in milliseconds. |
| <span id="cua-driver-serve--experimental-pip-geometry"></span>`--experimental-pip-geometry` | string | | Size and optional top-left origin of the experimental preview window: WxH or WxH+X+Y (default 480x360, top-right of the main display). |
-| <span id="cua-driver-serve--claude-code-computer-use-compat"></span>`--claude-code-computer-use-compat` | boolean | `false` | Select the Claude Code computer-use compatibility surface (forwarded by `mcp` when it launches the daemon). |
+| <span id="cua-driver-serve--claude-code-computer-use-compat"></span>`--claude-code-computer-use-compat` | boolean | `false` | Legacy compatibility flag forwarded by `mcp` when it launches the daemon; no current tool-surface effect. |
| <span id="cua-driver-serve--experimental-pip"></span>`--experimental-pip` | boolean | `false` | Show a small always-on-top window with the latest post-action screenshot and a one-line label (macOS only). |
| <span id="cua-driver-serve--dangerously-bypass-approvals"></span>`--dangerously-bypass-approvals` | boolean | `false` | Select unrestricted mode and acknowledge its risk. |
| <span id="cua-driver-serve--approve-capability-manifest"></span>`--approve-capability-manifest` | boolean | `false` | Trusted-launcher confirmation that the exact capability manifest was reviewed. |
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/apps-windows-and-screen.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/apps-windows-and-screen.mdx
index d3d2c1fc9c..fa7288b83c 100644
--- a/docs/content/docs/cua-driver/reference/mcp-tools/apps-windows-and-screen.mdx
+++ b/docs/content/docs/cua-driver/reference/mcp-tools/apps-windows-and-screen.mdx
@@ -238,7 +238,7 @@ Windows-only field: `path` (Swift uses `bundle_id` since macOS apps resolve via
| <span id="launch_app--windows--launch_path"></span>`launch_path` | `string` | | Round-trip the `launch_path` returned by `list_apps`. Highest precedence: when set, this exact string is handed to ShellExecuteEx unchanged. For Windows desktop apps it's the full `.exe` commandline (path + arguments preserved from the source shortcut); for UWP apps it's `shell:appsFolder\{PackageFamilyName}!{AppId}`. For precise UWP pid capture, prefer `aumid` over `launch_path`. |
| <span id="launch_app--windows--name"></span>`name` | `string` | | App display name. Tried against the `shell:AppsFolder` index first for packaged-app lookup; on a miss, passed to ShellExecuteEx's PATH search. |
| <span id="launch_app--windows--path"></span>`path` | `string` | | Full path to executable. Windows-only; takes precedence over name/bundle_id/aumid (but not over `launch_path`). |
-| <span id="launch_app--windows--start_minimized"></span>`start_minimized` | `boolean` | | When true, launch the app's window minimized to the taskbar instead of restored-but-not-activated. Use this when the agent wants to drive the app entirely in the background: the user's previously-frontmost window (e.g. terminal) stays visually on top. Desktop launches hold the foreground lock through startup and use SW_SHOWMINNOACTIVE; packaged-app activation remains broker-controlled and receives a best-effort SW_SHOWMINNOACTIVE post-pass. UIA / background dispatch still work on a minimized window; only `screenshot` and `delivery_mode:"foreground"` need it restored. |
+| <span id="launch_app--windows--start_minimized"></span>`start_minimized` | `boolean` | | When true, launch the app's window minimized to the taskbar instead of restored-but-not-activated. Use this when the agent wants to drive the app entirely in the background: the user's previously-frontmost window (e.g. terminal) stays visually on top. Desktop launches hold the foreground lock through startup and use SW_SHOWMINNOACTIVE; packaged-app activation remains broker-controlled and receives a best-effort SW_SHOWMINNOACTIVE post-pass. UIA / background dispatch still work on a minimized window; only window screenshots and `delivery_mode:"foreground"` need it restored. |
| <span id="launch_app--windows--urls"></span>`urls` | `string[]` | | URLs to open in the default browser via ShellExecuteEx (no activation). |
| <span id="launch_app--windows--webkit_inspector_port"></span>`webkit_inspector_port` | `integer` | | Accepted for cross-platform parity; no-op on Windows. |
diff --git a/libs/cua-driver/README.md b/libs/cua-driver/README.md
index af9865102c..f65263c23f 100644
--- a/libs/cua-driver/README.md
+++ b/libs/cua-driver/README.md
@@ -196,23 +196,19 @@ Contributor documentation:
- `docs/linux-desktop-validation.md` covers representative Linux sessions.
- `docs/linux-support-completion-plan.md` preserves the historical Linux plan.
-## Claude Code computer-use compatibility
+## Claude Code registration
-Standard Claude Code MCP registration:
+Register the standard MCP server:
```bash
claude mcp add --transport stdio cua-driver -- cua-driver mcp
```
-If you want Claude Code's vision/computer-use-style flow to ground on CuaDriver window screenshots, register the compatibility mode:
-
-```bash
-claude mcp add --transport stdio cua-computer-use -- cua-driver mcp --claude-code-computer-use-compat
-```
-
-This keeps CuaDriver's normal MCP tools and changes only `screenshot`, which requires `pid` and `window_id` and captures that window only.
-
-Use MCP for this Claude Code vision/computer-use-style path. CLI screenshots still work as CuaDriver calls, but they do not expose the `mcp__cua-computer-use__screenshot` tool name that Claude Code appears to use as the image-grounding cue.
+The legacy `--claude-code-computer-use-compat` flag is still accepted so old
+configurations keep starting, but it currently has no tool-surface effect and
+does not register a standalone `screenshot` tool. Use `get_window_state` for a
+window tree plus screenshot, `get_desktop_state` for a full-display screenshot,
+and `zoom` for a cropped region.
## macOS process identity and permissions
diff --git a/libs/cua-driver/rust/README.md b/libs/cua-driver/rust/README.md
index 71828ca8ce..fa9f4cdc76 100644
--- a/libs/cua-driver/rust/README.md
+++ b/libs/cua-driver/rust/README.md
@@ -104,7 +104,7 @@ calls through `allow.rules`, and explicit overrides through `deny.tools`:
```yaml
allow:
- tools: [screenshot, scroll, wait]
+ tools: [get_window_state, get_desktop_state, scroll, wait]
rules:
- tool: click
constraints:
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/image_utils.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/image_utils.rs
index 3d11c3c32d..7c3b0244fd 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/image_utils.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/image_utils.rs
@@ -54,7 +54,7 @@ pub fn png_bytes_to_jpeg(png_bytes: &[u8], quality: u8) -> Result<Vec<u8>> {
/// Default JPEG quality for a screenshot requested as `jpeg`.
pub const DEFAULT_JPEG_QUALITY: u8 = 85;
-/// Highest accepted JPEG quality, matching the `screenshot` tool's `quality`.
+/// Highest accepted JPEG quality.
pub const MAX_JPEG_QUALITY: u8 = 95;
/// How a screenshot is encoded for the caller.
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/policy.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/policy.rs
index 20a3bce2d9..c14f4f049d 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/policy.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/policy.rs
@@ -779,13 +779,13 @@ mod tests {
let policy = yaml_policy(
r#"
allow:
- tools: [screenshot, wait]
+ tools: [get_window_state, wait]
deny:
tools: [shell_execute]
"#,
);
assert_eq!(
- policy.evaluate("screenshot", &serde_json::json!({})),
+ policy.evaluate("get_window_state", &serde_json::json!({})),
PolicyDecision::Allow
);
assert!(matches!(
@@ -797,7 +797,7 @@ deny:
#[cfg(feature = "yaml")]
#[test]
fn yaml_is_deny_by_default() {
- let policy = yaml_policy("allow:\n tools: [screenshot]\n");
+ let policy = yaml_policy("allow:\n tools: [get_window_state]\n");
assert!(matches!(
policy.evaluate("click", &serde_json::json!({"x": 10, "y": 10})),
PolicyDecision::Deny(_)
@@ -899,9 +899,11 @@ allow:
#[cfg(feature = "yaml")]
#[test]
fn explicit_deny_overrides_allow() {
- let policy = yaml_policy("allow:\n tools: [screenshot]\ndeny:\n tools: [screenshot]\n");
+ let policy = yaml_policy(
+ "allow:\n tools: [get_window_state]\ndeny:\n tools: [get_window_state]\n",
+ );
assert!(matches!(
- policy.evaluate("screenshot", &serde_json::json!({})),
+ policy.evaluate("get_window_state", &serde_json::json!({})),
PolicyDecision::Deny(_)
));
}
@@ -937,7 +939,7 @@ default allow = false
allow if {
input.server == "cua-driver"
- input.tool == "screenshot"
+ input.tool == "get_window_state"
}
allow if {
@@ -952,7 +954,7 @@ allow if {
.unwrap();
let policy = PolicyEngine::load(&path).unwrap().unwrap();
assert_eq!(
- policy.evaluate("screenshot", &serde_json::json!({})),
+ policy.evaluate("get_window_state", &serde_json::json!({})),
PolicyDecision::Allow
);
assert_eq!(
@@ -979,13 +981,13 @@ allow if {
)
.unwrap();
fs::write(
- dir.path().join("screenshot.rego"),
- "package cua.policy\nallow if input.tool == \"screenshot\"\n",
+ dir.path().join("window-state.rego"),
+ "package cua.policy\nallow if input.tool == \"get_window_state\"\n",
)
.unwrap();
let policy = PolicyEngine::load(dir.path()).unwrap().unwrap();
assert_eq!(
- policy.evaluate("screenshot", &serde_json::json!({})),
+ policy.evaluate("get_window_state", &serde_json::json!({})),
PolicyDecision::Allow
);
}
diff --git a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs b/libs/cua-driver/rust/crates/cua-driver/src/cli.rs
index 1a9f474c37..ec94c55e91 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/cli.rs
@@ -25,11 +25,9 @@ pub enum Command {
/// Own the runtime in this MCP process. On macOS this is an explicit
/// TCC-attribution choice; it is mutually exclusive with `--socket`.
direct: bool,
- /// `--claude-code-computer-use-compat`: register the compat
- /// `screenshot` tool (window-scoped, JPEG @ 85%, pid + window_id
- /// both required) instead of the full-featured one. Used when
- /// the MCP server is wired up as `cua-computer-use` in Claude
- /// Code, where this is the documented best-practice install.
+ /// `--claude-code-computer-use-compat`: legacy compatibility flag.
+ /// It currently has no tool-surface effect and remains accepted so
+ /// existing Claude Code launch configurations keep working.
claude_code_compat: bool,
/// Repeatable trusted launch grants for residual standard-mode
/// boundaries, for example `--grant existing-profile`.
@@ -72,8 +70,8 @@ pub enum Command {
no_automation_prompts: bool,
/// True when `--claude-code-computer-use-compat` is on argv. The MCP
/// proxy forwards this flag to a daemon it auto-launches (see
- /// `launch_daemon_and_wait`) so that daemon registers the requested
- /// compatibility surface.
+ /// `launch_daemon_and_wait`) so existing launch configurations stay
+ /// stable. It currently has no tool-surface effect.
claude_code_compat: bool,
/// Repeatable trusted launch grants.
grants: Vec<String>,
@@ -667,21 +665,11 @@ pub fn parse_command() -> Command {
);
println!(" --socket <path> Select an explicit daemon socket/pipe endpoint.");
println!(" --claude-code-computer-use-compat");
- println!(" Select the Claude Code computer-use compat surface.");
+ println!(" Legacy compatibility flag retained for existing launch configs.");
println!(
- " Now forwarded to the proxy-launched daemon (was a no-op"
+ " It currently has no tool-surface effect and does not add a"
);
- println!(
- " on the proxy path — the path you actually run — because"
- );
- println!(" the daemon hardcoded compat=false). Note: the compat");
- println!(
- " screenshot tool itself was removed in #1692, so the flag"
- );
- println!(
- " has no tool-surface effect today; the wiring is in place"
- );
- println!(" for any future compat-gated tool.");
+ println!(" standalone screenshot tool.");
println!();
println!("agent cursor overlay (serve only — needs the daemon UI runloop):");
println!(" The overlay is ON by default: every MCP session automatically gets its own");
@@ -1477,17 +1465,9 @@ fn launch_daemon_with_state_and_wait(
// `~/Applications`), LaunchServices may otherwise pick a different copy
// than the one this CLI belongs to, with different TCC grants.
let open_args = daemon_launch_arguments(&app_path, socket_path, state, experimental_history);
- // Thread the Claude-Code compat flag through to the daemon. Without this
- // the proxy-spawned daemon always called build_macos_registry() (compat
- // hardcoded false), so `cua-driver mcp --claude-code-computer-use-compat`
- // SILENTLY DROPPED the flag on the proxy path — the path users actually
- // run on an installed bundle. Today this is latent: the compat screenshot
- // tool was removed in #1692, so `register_all(compat)` ignores the flag and
- // the served surface is identical either way. But the flag was being lost
- // before reaching the daemon at all, so the moment any compat-gated tool is
- // re-introduced the proxy path would not honour it. This makes the flag
- // travel end-to-end. Only honoured on a freshly-launched daemon — a
- // pre-existing daemon keeps whatever surface it launched with.
+ // `daemon_launch_arguments` keeps forwarding the legacy compatibility flag
+ // so existing launch configurations behave the same across proxy and
+ // in-process paths. It currently has no tool-surface effect.
let status = Cmd::new("/usr/bin/open")
// `-n` forces a new instance: CuaDriver.app might already be
// running from a previous MCP session, and without `-n`, `open
@@ -2008,7 +1988,7 @@ pub fn build_manifest() -> serde_json::Value {
"args": [
{ "name": "--socket", "type": "string", "description": "Select an explicit daemon socket or named-pipe endpoint." },
{ "name": "--direct", "type": "flag", "description": "Own the runtime in the MCP process; on macOS this explicitly accepts host TCC attribution. Mutually exclusive with --socket." },
- { "name": "--claude-code-computer-use-compat", "type": "flag", "description": "Select the Claude Code computer-use compat tool surface." },
+ { "name": "--claude-code-computer-use-compat", "type": "flag", "description": "Legacy compatibility flag with no current tool-surface effect." },
{ "name": "--embedded", "type": "flag", "description": "Declare embedding-host mode. Without --direct, requires the host's private service through --socket instead of auto-launching the standalone app." },
{ "name": "--host-bundle-id", "type": "string", "description": "Advisory host bundle id label echoed in check_permissions output." },
{ "name": "--grant", "type": "repeatable-string", "description": "Pre-authorize a residual standard-mode boundary for a newly launched runtime. Supported value: existing-profile." }
@@ -2026,7 +2006,7 @@ pub fn build_manifest() -> serde_json::Value {
{ "name": "--approve-session-policy", "type": "flag", "description": "Deprecated alias for --approve-capability-manifest." },
{ "name": "--no-permissions-gate", "type": "flag", "description": "Skip the macOS TCC first-launch gate." },
{ "name": "--no-automation-prompts", "type": "flag", "description": "Refuse scripting actions without granted macOS Automation consent." },
- { "name": "--claude-code-computer-use-compat", "type": "flag", "description": "Forwarded by the MCP proxy when the client asked for the compat surface." },
+ { "name": "--claude-code-computer-use-compat", "type": "flag", "description": "Legacy compatibility flag forwarded by the MCP proxy; no current tool-surface effect." },
{ "name": "--embedded", "type": "flag", "description": "Run embedded inside a host app: inherit the host's TCC grants, never prompt or relaunch. Also CUA_DRIVER_EMBEDDED=1." },
{ "name": "--host-bundle-id", "type": "string", "description": "Advisory host bundle id label echoed in check_permissions output." }
,{ "name": "--experimental-history", "type": "flag", "description": "Admit the encrypted local Computer History early preview for this daemon launch." }
@@ -2678,8 +2658,7 @@ pub fn run_call(
}
if let Some(sc) = result.get("structuredContent") {
// Merge image data into the structured payload so
- // `cua-driver call screenshot` over
- // the daemon socket still emits
+ // a daemon-routed image response still emits
// `screenshot_png_b64`. Previously this path
// dropped the image entirely when no
// --screenshot-out-file was given.
@@ -4450,7 +4429,7 @@ fn cli_docs_literal() -> serde_json::Value {
{"name":"experimental-pip-geometry","short_name":null,"help":"Size and optional top-left origin of the experimental preview window: WxH or WxH+X+Y (default 480x360, top-right of the main display).","type":"String","default_value":null,"is_optional":true}
],
"flags": [
- {"name":"claude-code-computer-use-compat","short_name":null,"help":"Select the Claude Code computer-use compatibility surface (forwarded by `mcp` when it launches the daemon).","default_value":false},
+ {"name":"claude-code-computer-use-compat","short_name":null,"help":"Legacy compatibility flag forwarded by `mcp` when it launches the daemon; no current tool-surface effect.","default_value":false},
{"name":"experimental-pip","short_name":null,"help":"Show a small always-on-top window with the latest post-action screenshot and a one-line label (macOS only).","default_value":false},
{"name":"dangerously-bypass-approvals","short_name":null,"help":"Select unrestricted mode and acknowledge its risk.","default_value":false},
{"name":"approve-capability-manifest","short_name":null,"help":"Trusted-launcher confirmation that the exact capability manifest was reviewed.","default_value":false},
diff --git a/libs/cua-driver/rust/crates/cua-driver/src/doctor.rs b/libs/cua-driver/rust/crates/cua-driver/src/doctor.rs
index 092168d75f..9bfef6b9e0 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/doctor.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/doctor.rs
@@ -295,7 +295,7 @@ fn append_platform_probes(report: &mut Report) {
report.push(
Probe::warn(
"interactive session",
- "running in Session 0 (services); window-driving tools (list_windows, click, type_text, screenshot, get_window_state) will return empty results — these APIs need an attached interactive desktop.",
+ "running in Session 0 (services); window-driving tools (list_windows, click, type_text, get_window_state, get_desktop_state) will return empty results — these APIs need an attached interactive desktop.",
)
.with_detail(
"re-run cua-driver from an interactive logon (RDP, console, or a scheduled task in the user's session) for the GUI tools to function.",
@@ -488,7 +488,7 @@ fn append_platform_probes(report: &mut Report) {
format!("Wayland only (WAYLAND_DISPLAY={w}, DISPLAY unset)"),
)
.with_detail(
- "X11 tools (list_windows, screenshot) need XWayland — start your session with XWayland enabled.",
+ "X11 window discovery and capture (list_windows, get_window_state) need XWayland — start your session with XWayland enabled.",
),
),
(Some(d), Some(w)) => report.push(Probe::ok(
diff --git a/libs/cua-driver/rust/crates/cua-driver/src/main.rs b/libs/cua-driver/rust/crates/cua-driver/src/main.rs
index 3593ca408b..1d08e869f1 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/main.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/main.rs
@@ -658,8 +658,8 @@ fn main() {
// Honour the compat flag forwarded by the MCP proxy
// (launch_daemon_and_wait passes `serve
// --claude-code-computer-use-compat`). The Serve arm is the daemon
- // the proxy talks to, so without this the proxy path always served
- // the full screenshot tool regardless of the client's request.
+ // the proxy talks to. The flag is currently surface-neutral but
+ // remains forwarded for compatibility with existing launch configs.
let driver = match build_driver(
cursor_cfg.clone(),
claude_code_compat,
@@ -1046,9 +1046,9 @@ fn main() -> anyhow::Result<()> {
// before any blocking work so the banner can land on stderr.
version_check::maybe_announce_update();
// The Rust permissions gate is macOS-only (TCC concept).
- // On Windows / Linux the flag is silently accepted for
- // CLI uniformity and ignored. The Claude-Code compat screenshot
- // surface is accepted on every platform for CLI uniformity.
+ // On Windows / Linux the flag is accepted for CLI uniformity and
+ // ignored. The legacy Claude Code compatibility flag is accepted on
+ // every platform and has no current tool-surface effect.
let _ = (no_permissions_gate, no_automation_prompts);
// Serve mode needs the cursor overlay just like MCP mode.
let cursor_cfg = cursor_overlay::CursorConfig::from_args();
diff --git a/libs/cua-driver/rust/crates/cua-driver/src/proxy.rs b/libs/cua-driver/rust/crates/cua-driver/src/proxy.rs
index 02b4498be7..40d46c6f73 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/proxy.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/proxy.rs
@@ -935,7 +935,7 @@ async fn forward_tool_call(
// The daemon client is sync, so jump to a blocking thread to keep
// the tokio reactor responsive while the AX-heavy call (e.g.
- // `screenshot`, `get_window_state`) does its thing on the daemon
+ // `get_window_state`) does its thing on the daemon
// side.
let socket = socket_path.to_owned();
let blocking = tokio::task::spawn_blocking(move || send_request(&socket, &req)).await;
diff --git a/libs/cua-driver/rust/crates/cua-driver/src/serve.rs b/libs/cua-driver/rust/crates/cua-driver/src/serve.rs
index 518df3518e..f7ec8d0b89 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/serve.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/serve.rs
@@ -2244,7 +2244,7 @@ pub fn run_serve_cmd(
// Session-0 warning banner (Windows). The daemon runs fine in services
// / SSH contexts for tools that don't touch the desktop, but every
- // window-driving tool (click, type_text, screenshot, get_window_state,
+ // window-driving tool (click, type_text, get_window_state, get_desktop_state,
// list_windows, launch_app for UWP) will fail or return empty when
// invoked from this daemon. Surfacing this at startup saves users
// hours of debugging tools that are working as designed.
@@ -2253,8 +2253,8 @@ pub fn run_serve_cmd(
if matches!(platform_windows::diagnostics::current_session_id(), Some(0),) {
eprintln!(
"WARNING: cua-driver serve is starting in Session 0 (services). \
- Window-driving tools — click, type_text, screenshot, \
- get_window_state, list_windows, and UWP launches — need an \
+ Window-driving tools — click, type_text, get_window_state, \
+ get_desktop_state, list_windows, and UWP launches — need an \
attached interactive desktop and will fail or return empty \
here. Re-run from an interactive logon (RDP, console, or a \
scheduled task in the user's session) for the GUI tools to \
diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/policy_tools_list_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/policy_tools_list_test.rs
index 68e85e1cd4..bd2bd79cde 100644
--- a/libs/cua-driver/rust/crates/cua-driver/tests/policy_tools_list_test.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/tests/policy_tools_list_test.rs
@@ -12,13 +12,13 @@ fn tools_list_hides_policy_denied_tools_and_calls_stay_denied() {
let directory = tempfile::tempdir().expect("temporary policy directory");
let policy_path = directory.path().join("policy.yaml");
// `get_config` is unconditionally allowed via `allow.tools`.
- // `screenshot` is conditionally allowed via `allow.rules` with a
+ // `zoom` is conditionally allowed via `allow.rules` with a
// constraint. Both must appear in `tools/list` because `tools/list`
// should not hide tools that are *potentially* allowed.
// `list_apps` is explicitly denied and must be absent.
std::fs::write(
&policy_path,
- "allow:\n tools: [get_config]\n rules:\n - tool: screenshot\n constraints:\n display_id: {\"const\": 0}\ndeny:\n tools: [list_apps]\n",
+ "allow:\n tools: [get_config]\n rules:\n - tool: zoom\n constraints:\n window_id: {\"allowed\": [0]}\ndeny:\n tools: [list_apps]\n",
)
.expect("write permission policy");
let policy = policy_path.display().to_string();
@@ -43,7 +43,7 @@ fn tools_list_hides_policy_denied_tools_and_calls_stay_denied() {
"unconditionally allowed tool must remain listed"
);
assert!(
- names.contains("screenshot"),
+ names.contains("zoom"),
"rule-conditionally allowed tool must remain listed even though empty-arg evaluation would deny it"
);
assert!(
diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/protocol_media_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/protocol_media_test.rs
index 6dc6e2a85b..071b3d605b 100644
--- a/libs/cua-driver/rust/crates/cua-driver/tests/protocol_media_test.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/tests/protocol_media_test.rs
@@ -579,8 +579,8 @@ fn click_debug_image_out() {
#[test]
#[cfg(any(target_os = "macos", target_os = "windows"))]
fn set_config_screenshot_resize() {
- //! set_config(max_image_dimension=200) then screenshot — returned image must
- //! have both dimensions ≤ 200. Verifies the ResizeRegistry pipeline end-to-end.
+ //! set_config(max_image_dimension=200) then get_window_state — the returned
+ //! window image must have both dimensions ≤ 200.
let Some(mut d) = spawn_unrestricted() else {
return;
};
@@ -588,7 +588,7 @@ fn set_config_screenshot_resize() {
d.send(&serde_json::json!({"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}));
d.recv();
- // Set a tiny max_image_dimension so the full display screenshot will be resized.
+ // Set a tiny max_image_dimension so the window screenshot will be resized.
d.send(&serde_json::json!({
"jsonrpc":"2.0","id":2,"method":"tools/call",
"params":{"name":"set_config","arguments":{"max_image_dimension":200}}
@@ -600,40 +600,104 @@ fn set_config_screenshot_resize() {
"set_config returned error: {resp:?}"
);
- // Capture full display; must be ≤ 200 px in both dimensions.
+ // Find a visible window to capture through the canonical state tool.
d.send(&serde_json::json!({
"jsonrpc":"2.0","id":3,"method":"tools/call",
- "params":{"name":"screenshot","arguments":{}}
+ "params":{"name":"list_windows","arguments":{}}
}));
- let resp = d.recv();
- assert!(resp["error"].is_null(), "screenshot failed: {resp:?}");
- // A screenshot can be unavailable in a non-interactive session (Session 0 on
- // Windows, no display) — there's nothing to resize, so skip rather than fail.
- // (The old Windows mirror lacked this skip and asserted unconditionally; it
- // had never been run in such an environment.)
- if resp["result"]["isError"].as_bool().unwrap_or(false) {
- eprintln!("screenshot unavailable — skipping resize assertion: {resp:?}");
- return;
+ let listed = d.recv();
+ let windows = listed["result"]["structuredContent"]["windows"]
+ .as_array()
+ .cloned()
+ .unwrap_or_default();
+ let mut tried = 0usize;
+ let mut capture_errors = Vec::new();
+ let mut captured = false;
+ for target in windows
+ .iter()
+ .filter(|window| window["is_on_screen"].as_bool() == Some(true))
+ .take(5)
+ {
+ let (Some(pid), Some(window_id)) = (target["pid"].as_u64(), target["window_id"].as_u64())
+ else {
+ continue;
+ };
+ tried += 1;
+ d.send(&serde_json::json!({
+ "jsonrpc":"2.0","id":3 + tried as u64,"method":"tools/call",
+ "params":{"name":"get_window_state","arguments":{
+ "pid":pid,"window_id":window_id,"max_elements":10,"max_depth":2
+ }}
+ }));
+ let state = d.recv();
+ let structured = &state["result"]["structuredContent"];
+ match (
+ structured["screenshot_width"].as_u64(),
+ structured["screenshot_height"].as_u64(),
+ ) {
+ (Some(w), Some(h)) => {
+ assert!(
+ !state["result"]["isError"].as_bool().unwrap_or(false),
+ "get_window_state returned image dimensions with an error: {state:?}"
+ );
+ assert!(
+ w > 0 && w <= 200,
+ "screenshot width {w} should be in 1..=200"
+ );
+ assert!(
+ h > 0 && h <= 200,
+ "screenshot height {h} should be in 1..=200"
+ );
+ captured = true;
+ break;
+ }
+ _ => {
+ // macOS reports an object, Windows a string; either means the
+ // window was not capturable from this session.
+ let error = match &structured["screenshot_error"] {
+ serde_json::Value::Null => None,
+ serde_json::Value::String(text) => Some(text.clone()),
+ other => Some(other.to_string()),
+ };
+ capture_errors.push((window_id, error));
+ }
+ }
}
- let (Some(w), Some(h)) = (
- resp["result"]["structuredContent"]["width"].as_u64(),
- resp["result"]["structuredContent"]["height"].as_u64(),
- ) else {
- eprintln!("screenshot returned no dimensions — skipping resize assertion: {resp:?}");
- return;
+
+ let describe = |errors: &[(u64, Option<String>)]| {
+ errors
+ .iter()
+ .map(|(id, error)| {
+ format!(
+ "window_id={id}: {}",
+ error
+ .as_deref()
+ .unwrap_or("no dimensions and no screenshot_error")
+ )
+ })
+ .collect::<Vec<_>>()
+ .join(" | ")
};
- assert!(
- w <= 200,
- "screenshot width {w} should be ≤ 200 after max_image_dimension=200"
- );
- assert!(
- h <= 200,
- "screenshot height {h} should be ≤ 200 after max_image_dimension=200"
- );
+ if tried == 0 {
+ eprintln!("No on-screen windows found — skipping resize assertion");
+ } else if !captured && capture_errors.iter().all(|(_, error)| error.is_some()) {
+ // Capture is unavailable in this session (no Screen Recording grant,
+ // Windows Session 0): there is nothing to resize.
+ eprintln!(
+ "No visible window was capturable — skipping resize assertion. Errors: {}",
+ describe(&capture_errors)
+ );
+ } else {
+ assert!(
+ captured,
+ "Expected a capturable window with resized image dimensions. Errors: {}",
+ describe(&capture_errors)
+ );
+ }
- // get_config should reflect the updated value.
+ // get_config should reflect the updated value even in a headless session.
d.send(&serde_json::json!({
- "jsonrpc":"2.0","id":4,"method":"tools/call",
+ "jsonrpc":"2.0","id":100,"method":"tools/call",
"params":{"name":"get_config","arguments":{}}
}));
let resp = d.recv();
diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/removed_tool_docs_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/removed_tool_docs_test.rs
new file mode 100644
index 0000000000..cd81f83b27
--- /dev/null
+++ b/libs/cua-driver/rust/crates/cua-driver/tests/removed_tool_docs_test.rs
@@ -0,0 +1,172 @@
+//! Keep removed tools out of the live registry and maintained user guidance.
+
+use std::collections::HashSet;
+use std::path::{Path, PathBuf};
+
+const REMOVED_TOOLS: &[&str] = &["screenshot"];
+
+#[cfg(target_os = "macos")]
+fn live_tool_names() -> HashSet<String> {
+ platform_macos::register_tools()
+ .tool_names()
+ .map(str::to_owned)
+ .collect()
+}
+
+#[cfg(target_os = "windows")]
+fn live_tool_names() -> HashSet<String> {
+ platform_windows::register_tools()
+ .tool_names()
+ .map(str::to_owned)
+ .collect()
+}
+
+#[cfg(target_os = "linux")]
+fn live_tool_names() -> HashSet<String> {
+ platform_linux::register_tools()
+ .tool_names()
+ .map(str::to_owned)
+ .collect()
+}
+
+fn collect_docs(dir: &Path, files: &mut Vec<PathBuf>) {
+ // Nix tests the filtered Rust source, which intentionally excludes the
+ // repository-level docs tree. Scan every maintained-doc root available in
+ // the current source distribution instead of requiring the full checkout.
+ if !dir.is_dir() {
+ return;
+ }
+
+ let mut entries = std::fs::read_dir(dir)
+ .unwrap_or_else(|error| panic!("failed to read docs directory {}: {error}", dir.display()))
+ .map(|entry| entry.expect("failed to read docs directory entry").path())
+ .collect::<Vec<_>>();
+ entries.sort();
+
+ for path in entries {
+ if path.is_dir() {
+ collect_docs(&path, files);
+ } else if matches!(
+ path.extension().and_then(|ext| ext.to_str()),
+ Some("md" | "mdx")
+ ) {
+ files.push(path);
+ }
+ }
+}
+
+fn advertises_removed_tool(line: &str, tool: &str) -> bool {
+ let line = line.to_ascii_lowercase();
+ let invocation = [
+ format!("cua-driver call {tool}"),
+ format!("cua-driver {tool}"),
+ format!("{tool}("),
+ ]
+ .iter()
+ .any(|pattern| line.contains(pattern));
+
+ let tool_reference = [
+ format!("`{tool}` tool"),
+ format!("{tool} tool"),
+ format!("tool `{tool}`"),
+ format!("tool named `{tool}`"),
+ ]
+ .iter()
+ .any(|pattern| line.contains(pattern));
+ let explicitly_absent = [
+ "no standalone",
+ "does not register",
+ "does not add",
+ "removed",
+ "obsolete",
+ ]
+ .iter()
+ .any(|marker| line.contains(marker));
+
+ invocation || (tool_reference && !explicitly_absent)
+}
+
+#[test]
+fn maintained_guidance_does_not_advertise_removed_tools() {
+ let registered = live_tool_names();
+ for tool in REMOVED_TOOLS {
+ assert!(
+ !registered.contains(*tool),
+ "removed tool {tool:?} is still present in the live registry"
+ );
+ }
+
+ let rust_root = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+ .parent()
+ .and_then(Path::parent)
+ .expect("rust workspace root")
+ .to_path_buf();
+ let driver_root = rust_root.parent().expect("cua-driver root");
+ let repo_root = driver_root
+ .parent()
+ .and_then(Path::parent)
+ .expect("repository root");
+
+ // Keep this list limited to current user guidance. Historical plans may
+ // accurately discuss old tools and are not instructions to users.
+ let mut files = vec![
+ driver_root.join("README.md"),
+ driver_root.join("docs/tool-output-format.md"),
+ rust_root.join("README.md"),
+ driver_root.join("scripts/post-install-hints.txt"),
+ driver_root.join("scripts/install.ps1"),
+ ];
+ collect_docs(&rust_root.join("Skills/cua-driver"), &mut files);
+ collect_docs(&repo_root.join("docs/content/docs/cua-driver"), &mut files);
+
+ let mut failures = Vec::new();
+ for path in files.into_iter().filter(|path| path.is_file()) {
+ let contents = std::fs::read_to_string(&path).unwrap_or_else(|error| {
+ panic!("failed to read guidance file {}: {error}", path.display())
+ });
+ let mut line_number = 1;
+ for paragraph in contents.split_inclusive("\n\n") {
+ for tool in REMOVED_TOOLS {
+ if advertises_removed_tool(paragraph, tool) {
+ failures.push(format!(
+ "{}:{} advertises removed tool {tool:?}: {}",
+ path.display(),
+ line_number,
+ paragraph.split_whitespace().collect::<Vec<_>>().join(" ")
+ ));
+ }
+ }
+ line_number += paragraph.lines().count();
+ }
+ }
+
+ assert!(
+ failures.is_empty(),
+ "removed tools appear in maintained guidance:\n{}",
+ failures.join("\n")
+ );
+}
+
+#[test]
+fn removed_tool_reference_detection_covers_invocations_and_prose() {
+ for reference in [
+ "cua-driver call screenshot '{}'",
+ "screenshot({ window_id: 42 })",
+ "use the `screenshot` tool",
+ "use the screenshot tool",
+ ] {
+ assert!(
+ advertises_removed_tool(reference, "screenshot"),
+ "{reference:?}"
+ );
+ }
+
+ for notice in [
+ "there is no standalone screenshot tool",
+ "the `screenshot` tool was removed",
+ "this does not register a standalone `screenshot` tool",
+ "the old compatibility flag does not add a screenshot tool",
+ ] {
+ assert!(!advertises_removed_tool(notice, "screenshot"), "{notice:?}");
+ }
+}
diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/removed_tool_protocol_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/removed_tool_protocol_test.rs
new file mode 100644
index 0000000000..32c5bb0c72
--- /dev/null
+++ b/libs/cua-driver/rust/crates/cua-driver/tests/removed_tool_protocol_test.rs
@@ -0,0 +1,33 @@
+//! Cross-platform protocol coverage for tools removed from the registry.
+
+#![cfg(any(target_os = "macos", target_os = "windows", target_os = "linux"))]
+
+use cua_driver_testkit::RawDriver;
+
+#[test]
+fn standalone_screenshot_tool_is_removed() {
+ let Some(mut driver) = RawDriver::spawn() else {
+ return;
+ };
+
+ driver.send(&serde_json::json!({
+ "jsonrpc":"2.0","id":1,"method":"initialize","params":{}
+ }));
+ driver.recv();
+
+ driver.send(&serde_json::json!({
+ "jsonrpc":"2.0","id":2,"method":"tools/call",
+ "params":{"name":"screenshot","arguments":{}}
+ }));
+ let response = driver.recv();
+ assert_eq!(
+ response["result"]["isError"],
+ serde_json::json!(true),
+ "{response:?}"
+ );
+ let text = response["result"]["content"]
+ .as_array()
+ .and_then(|items| items.iter().find_map(|item| item["text"].as_str()))
+ .unwrap_or_default();
+ assert_eq!(text, "Unknown tool: screenshot");
+}
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/atspi/mod.rs b/libs/cua-driver/rust/crates/platform-linux/src/atspi/mod.rs
index 5ca9ca7a8c..08e5f94727 100644
--- a/libs/cua-driver/rust/crates/platform-linux/src/atspi/mod.rs
+++ b/libs/cua-driver/rust/crates/platform-linux/src/atspi/mod.rs
@@ -156,7 +156,7 @@ pub(crate) fn walk_tree_for_recording(
/// Walk the AT-SPI tree with caller-supplied caps. `None` for either cap
/// means "use the walker's built-in default" (5 000 nodes; unlimited depth).
-/// Issue #22865: caps protect against Electron / large web apps that
+/// These caps protect against Electron / large web apps that
/// produce 10k+ element trees and blow context windows.
pub fn walk_tree_bounded(
pid: u32,
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/atspi/native.rs b/libs/cua-driver/rust/crates/platform-linux/src/atspi/native.rs
index a176e547e8..19f78d038f 100644
--- a/libs/cua-driver/rust/crates/platform-linux/src/atspi/native.rs
+++ b/libs/cua-driver/rust/crates/platform-linux/src/atspi/native.rs
@@ -1427,7 +1427,7 @@ async fn resolve_window_frame(
/// - `max_depth = None` keeps depth uncapped (the historical behaviour);
/// `Some(d)` skips enqueueing children whose depth would exceed `d`.
///
-/// Issue #22865: caps protect against Electron / large web apps that produce
+/// These caps protect against Electron / large web apps that produce
/// 10k+ element trees and blow context windows.
async fn collect_visited_bounded<'a>(
conn: &'a AccessibilityConnection,
@@ -1868,7 +1868,7 @@ async fn collect_visited_bounded_opts<'a>(
let child_in_web_doc = in_web_doc || is_document_role(&role);
// Enqueue children (fetched above) before moving `acc` into `visited`.
- // Honor max_depth (#22865): skip enqueueing descendants whose depth
+ // Honor max_depth: skip enqueueing descendants whose depth
// would exceed the cap.
let descend = max_depth.map(|d| depth < d).unwrap_or(true);
// A menu that is not open (a menubar entry that is not expanded, or
@@ -2510,7 +2510,7 @@ pub struct WalkedTree {
/// Walk the AT-SPI tree with caller-supplied node + depth caps.
/// `max_elements = None` keeps the historical 5 000-node default; `max_depth
-/// = None` keeps the historical unbounded depth. Issue #22865.
+/// = None` keeps the historical unbounded depth.
pub fn walk_tree_bounded(
pid: u32,
xid: u64,
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/lib.rs b/libs/cua-driver/rust/crates/platform-linux/src/lib.rs
index 0a84635850..999c51396e 100644
--- a/libs/cua-driver/rust/crates/platform-linux/src/lib.rs
+++ b/libs/cua-driver/rust/crates/platform-linux/src/lib.rs
@@ -230,10 +230,8 @@ pub fn register_tools() -> ToolRegistry {
tools::build_registry(false)
}
-/// `compat=true` enables Claude Code computer-use compatibility mode:
-/// the regular `screenshot` tool is replaced by a window-scoped variant
-/// (pid + window_id required, JPEG @ 85%, text note pointing at pixel
-/// tools). See `tools::impl_::ScreenshotCompatTool`.
+/// `compat` is a legacy Claude Code compatibility flag with no current
+/// tool-surface effect. It remains accepted for launch compatibility.
pub fn register_tools_with_cursor(cfg: cursor_overlay::CursorConfig, compat: bool) -> ToolRegistry {
register_tools_with_cursor_and_provider(None, cfg, compat)
}
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/tools/double_click.rs b/libs/cua-driver/rust/crates/platform-linux/src/tools/double_click.rs
index 471c2e7a60..ca2f15819a 100644
--- a/libs/cua-driver/rust/crates/platform-linux/src/tools/double_click.rs
+++ b/libs/cua-driver/rust/crates/platform-linux/src/tools/double_click.rs
@@ -22,9 +22,9 @@ use super::{
},
};
-// `ScreenshotTool` and `ScreenshotCompatTool` removed in PR #1692 — see the
-// matching note in platform-windows/src/tools/impl_.rs. `get_window_state` is
-// the canonical screenshot path (it always returns a screenshot now); the
+// The standalone screenshot tools were removed in PR #1692. `get_window_state`
+// is the canonical window-capture path and `get_desktop_state` handles
+// full-display capture; the
// underlying capture machinery (XGetImage / `import` shell-out / etc.)
// stays reachable through GetWindowStateTool.
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs b/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs
index d9dbcc070a..bc1cd4249d 100644
--- a/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs
+++ b/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs
@@ -4655,10 +4655,9 @@ pub fn build_registry_with_provider(
&mut r,
Arc::new(crate::clipboard::LinuxClipboard::new()),
);
- // `screenshot` removed - see the matching comment in
- // platform-windows/src/tools/impl_.rs::build_registry. Canonical
- // screenshot path is `get_window_state` (it always returns a screenshot now).
- let _ = compat;
+ // Standalone screenshot capture is intentionally absent. Use
+ // `get_window_state` for a window or `get_desktop_state` for the display.
+ let _ = compat; // legacy flag; no current tool-surface effect
r.register(Box::new(GetScreenSizeTool));
r.register(Box::new(GetDesktopStateTool {
state: state.clone(),
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/ax/tree.rs b/libs/cua-driver/rust/crates/platform-macos/src/ax/tree.rs
index 9af61dc2ac..2fcc6c599a 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/ax/tree.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/ax/tree.rs
@@ -24,7 +24,7 @@ use std::time::Instant;
///
/// Callers can override per-call via `walk_tree`'s `max_depth` parameter to
/// trade fidelity for context-window budget on AX-heavy apps (Electron,
-/// Obsidian, large web apps — issue #22865).
+/// Obsidian and other large web apps).
pub const DEFAULT_MAX_DEPTH: usize = 25;
/// Default maximum total nodes visited during a single AX walk. Chromium-family
@@ -34,7 +34,7 @@ pub const DEFAULT_MAX_DEPTH: usize = 25;
/// with a warning line appended (mirrors Swift reference implementation).
///
/// Callers can override per-call via `walk_tree`'s `max_elements` parameter
-/// (issue #22865).
+/// for large accessibility trees.
pub const DEFAULT_MAX_ELEMENTS: usize = 2_000;
/// Bound each native AX request. Tokio cannot cancel a blocked
@@ -185,7 +185,7 @@ pub fn walk_tree(pid: i32, window_id: Option<u32>, query: Option<&str>) -> TreeW
/// the cap) and depth-wise (nodes whose markdown indent would exceed the cap
/// are omitted). Markdown and the `nodes` vec are truncated identically.
///
-/// Issue #22865: caps protect against Electron / Obsidian / large web apps
+/// These caps protect against Electron / Obsidian / large web apps
/// that produce 10k+ element trees and blow context windows.
pub fn walk_tree_bounded(
pid: i32,
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/lib.rs b/libs/cua-driver/rust/crates/platform-macos/src/lib.rs
index 48187b4836..f7a5c48d0b 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/lib.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/lib.rs
@@ -92,10 +92,9 @@ pub fn register_tools() -> ToolRegistry {
register_tools_with_compat(false)
}
-/// Same as `register_tools` but lets the caller pick the Claude Code
-/// computer-use compat mode. `compat=true` swaps the regular `screenshot`
-/// tool for the window-scoped variant (pid + window_id required,
-/// JPEG @ 85%, text note pointing at pixel tools).
+/// Same as `register_tools` but accepts the legacy Claude Code
+/// computer-use compatibility flag. The flag currently has no tool-surface
+/// effect; it remains accepted so existing launch configurations keep working.
pub fn register_tools_with_compat(compat: bool) -> ToolRegistry {
#[cfg(target_os = "macos")]
{
@@ -116,10 +115,8 @@ pub fn register_tools_with_compat(compat: bool) -> ToolRegistry {
/// `platform_macos::cursor::overlay::run_on_main_thread()` on the OS
/// main thread to actually display the overlay.
///
-/// `compat=true` enables Claude Code computer-use compatibility mode:
-/// the regular `screenshot` tool is replaced by a window-scoped variant
-/// (pid + window_id required, JPEG @ 85%, text note pointing at pixel
-/// tools). See `tools::screenshot_compat`.
+/// `compat` is a legacy Claude Code compatibility flag with no current
+/// tool-surface effect. It remains accepted for launch compatibility.
pub fn register_tools_with_cursor(
cfg: cursor_overlay::CursorConfig,
compat: bool,
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/get_window_state.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/get_window_state.rs
index 19517bda52..0ffee17fd5 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/get_window_state.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/get_window_state.rs
@@ -331,7 +331,7 @@ impl Tool for GetWindowStateTool {
.and_then(|value| value.as_bool())
== Some(true);
// Optional caps — when omitted, fall back to the defaults baked into
- // the AX walker (#22865). minimum:1 keyed in the schema, but defend
+ // the AX walker. minimum:1 is keyed in the schema, but defend
// against 0 here as well so a misbehaving client can't disable the
// walk entirely.
let max_elements = view.max_elements(
@@ -708,7 +708,7 @@ impl Tool for GetWindowStateTool {
"elements": elements_json,
"_note": "Prefer `elements` — `tree_markdown` will continue to work \
but new fields will only be added to the structured side. \
- Issue #22865: use `max_elements` / `max_depth` to bound the \
+ Use `max_elements` / `max_depth` to bound the \
AX walk on apps with very large trees."
});
if query.is_some() {
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rs
index bc6a36c05b..b0b5e5ad0b 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rs
@@ -990,10 +990,8 @@ pub(crate) fn cursor_overlay_unavailable() -> cua_driver_core::protocol::ToolRes
}))
}
-/// Register all macOS tools into the registry. `compat=true` swaps the
-/// regular `screenshot` tool for the Claude Code computer-use compat
-/// variant — same name, stricter args, window-scoped JPEG @ 85% + a text
-/// note telling the caller to use pixel-addressed tools.
+/// Register all macOS tools into the registry. `compat` is retained for
+/// launch compatibility but currently has no effect on the tool surface.
pub fn register_all(
registry: &mut ToolRegistry,
compat: bool,
@@ -1155,14 +1153,10 @@ pub fn register_all(
registry,
Arc::new(clipboard::MacosClipboard::new()),
);
- // The standalone `screenshot` tool was removed (#1692). The pixel-grounding
- // screenshot the Claude Code computer-use compat loop relies on now comes
- // from `get_window_state` (which always returns BOTH the tree AND a
- // screenshot — perception is mode-agnostic; `capture_mode` is deprecated/
- // ignored) for a window, or `get_desktop_state` for the whole screen.
- // `compat` no longer gates a tool swap here — the flag's live purpose is to
- // register the MCP server under the `cua-computer-use` name, which is what
- // triggers Claude Code's computer-use beta-tool injection (see cli.rs).
+ // The standalone `screenshot` tool was removed in #1692. Window capture
+ // now comes from `get_window_state` (tree plus screenshot by default), while
+ // `get_desktop_state` handles explicit full-display capture. `capture_mode`
+ // is deprecated and ignored. `compat` no longer gates a tool swap here.
let _ = compat;
registry.register(Box::new(get_screen_size::GetScreenSizeTool));
registry.register(Box::new(get_desktop_state::GetDesktopStateTool::new(
@@ -1229,6 +1223,29 @@ pub fn register_all(
registry.register_session_tools();
}
+#[cfg(test)]
+mod registry_surface_tests {
+ use super::*;
+
+ fn names(compat: bool) -> Vec<String> {
+ let mut registry = ToolRegistry::new();
+ register_all(&mut registry, compat, false, false, None);
+ registry.tool_names().map(str::to_owned).collect()
+ }
+
+ #[test]
+ fn default_and_legacy_compat_surfaces_have_no_screenshot_tool() {
+ let default = names(false);
+ let compat = names(true);
+ assert!(!default.iter().any(|name| name == "screenshot"));
+ assert!(!compat.iter().any(|name| name == "screenshot"));
+ assert_eq!(
+ default, compat,
+ "legacy compat flag must remain surface-neutral"
+ );
+ }
+}
+
#[cfg(test)]
mod session_config_guard_tests {
use super::*;
diff --git a/libs/cua-driver/rust/crates/platform-windows/examples/list_tools_parity.rs b/libs/cua-driver/rust/crates/platform-windows/examples/list_tools_parity.rs
index 3487418238..ba88a2d7e7 100644
--- a/libs/cua-driver/rust/crates/platform-windows/examples/list_tools_parity.rs
+++ b/libs/cua-driver/rust/crates/platform-windows/examples/list_tools_parity.rs
@@ -43,7 +43,6 @@ fn main() {
"press_key",
"hotkey",
"scroll",
- "screenshot",
"list_apps",
"list_windows",
"get_cursor_position",
diff --git a/libs/cua-driver/rust/crates/platform-windows/examples/screenshot_parity.rs b/libs/cua-driver/rust/crates/platform-windows/examples/screenshot_parity.rs
deleted file mode 100644
index 48af29d92a..0000000000
--- a/libs/cua-driver/rust/crates/platform-windows/examples/screenshot_parity.rs
+++ /dev/null
@@ -1,132 +0,0 @@
-//! Parity check for `screenshot`.
-
-#[cfg(target_os = "windows")]
-use std::io::{Read, Write};
-#[cfg(target_os = "windows")]
-use std::time::{Duration, Instant};
-
-#[cfg(target_os = "windows")]
-fn main() {
- let mut pipe = std::fs::OpenOptions::new()
- .read(true)
- .write(true)
- .open(r"\\.\pipe\cua-driver")
- .expect("open pipe");
-
- fn req(p: &mut std::fs::File, json: &str) -> String {
- p.write_all(format!("{json}\n").as_bytes()).unwrap();
- p.flush().ok();
- let mut out = Vec::new();
- // Heap-allocate the 64 KiB read buffer — a stack array of this size
- // overflows the default thread stack on Windows debug builds.
- let mut buf: Vec<u8> = vec![0u8; 64 * 1024];
- let deadline = Instant::now() + Duration::from_secs(4);
- loop {
- if Instant::now() > deadline {
- panic!("timeout");
- }
- let n = p.read(&mut buf).unwrap_or(0);
- if n == 0 {
- break;
- }
- out.extend_from_slice(&buf[..n]);
- if out.contains(&b'\n') {
- break;
- }
- }
- String::from_utf8_lossy(&out).into_owned()
- }
-
- // Window screenshot: find Chrome.
- let lw = req(
- &mut pipe,
- r#"{"method":"call","name":"list_windows","args":{}}"#,
- );
- let lwv: serde_json::Value = serde_json::from_str(lw.trim()).unwrap();
- let wins = lwv
- .pointer("/result/structuredContent/windows")
- .and_then(|w| w.as_array())
- .unwrap();
- let target = wins
- .iter()
- .find(|w| {
- let n = w
- .pointer("/app_name")
- .and_then(|s| s.as_str())
- .unwrap_or("")
- .to_lowercase();
- n.contains("chrome")
- })
- .expect("no chrome");
- let wid = target
- .pointer("/window_id")
- .and_then(|n| n.as_u64())
- .unwrap();
-
- // 1. Window screenshot.
- let ss = format!(r#"{{"method":"call","name":"screenshot","args":{{"window_id":{wid}}}}}"#);
- let r1 = req(&mut pipe, &ss);
- let v1: serde_json::Value = serde_json::from_str(r1.trim()).unwrap();
- // Last content entry is text; first should be image.
- let content = v1
- .pointer("/result/content")
- .and_then(|c| c.as_array())
- .unwrap();
- assert!(
- content
- .iter()
- .any(|c| c.get("type").and_then(|t| t.as_str()) == Some("image")),
- "Response should contain an image content block"
- );
- let text = content
- .iter()
- .find_map(|c| {
- if c.get("type").and_then(|t| t.as_str()) == Some("text") {
- c.get("text").and_then(|t| t.as_str())
- } else {
- None
- }
- })
- .unwrap_or("");
- println!("Window resp: {text:?}");
- assert!(
- text.starts_with("✅ Window screenshot — ")
- && text.contains(&format!("[window_id: {wid}]")),
- "Window text doesn't match Swift format: {text:?}"
- );
- let sc = v1.pointer("/result/structuredContent").unwrap();
- assert!(
- sc.get("width").is_some() && sc.get("height").is_some() && sc.get("format").is_some(),
- "structuredContent missing width/height/format"
- );
-
- // 2. JPEG format.
- let ss2 = format!(
- r#"{{"method":"call","name":"screenshot","args":{{"window_id":{wid},"format":"jpeg","quality":50}}}}"#
- );
- let r2 = req(&mut pipe, &ss2);
- let v2: serde_json::Value = serde_json::from_str(r2.trim()).unwrap();
- let c2 = v2
- .pointer("/result/content")
- .and_then(|c| c.as_array())
- .unwrap();
- let img = c2
- .iter()
- .find(|c| c.get("type").and_then(|t| t.as_str()) == Some("image"))
- .unwrap();
- let mime = img.get("mimeType").and_then(|m| m.as_str()).unwrap_or("");
- assert_eq!(
- mime, "image/jpeg",
- "jpeg format should set mimeType image/jpeg, got: {mime:?}"
- );
- let fmt = v2
- .pointer("/result/structuredContent/format")
- .and_then(|f| f.as_str())
- .unwrap_or("");
- assert_eq!(fmt, "jpeg", "structuredContent.format should be jpeg");
-
- println!("\n✅ PASS: screenshot text format + image + structuredContent + jpeg path verified");
-}
-
-#[cfg(not(target_os = "windows"))]
-fn main() {}
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/diagnostics.rs b/libs/cua-driver/rust/crates/platform-windows/src/diagnostics.rs
index dd80c66ac8..fb9be4e06c 100644
--- a/libs/cua-driver/rust/crates/platform-windows/src/diagnostics.rs
+++ b/libs/cua-driver/rust/crates/platform-windows/src/diagnostics.rs
@@ -7,8 +7,8 @@
//!
//! ## Why the session-id probe matters
//!
-//! Window-driving tools (`list_windows`, `click`, `type_text`, `screenshot`,
-//! `get_window_state`) all bottom out in Win32 APIs that are scoped to the
+//! Window-driving tools (`list_windows`, `click`, `type_text`, `get_window_state`,
+//! `get_desktop_state`) all bottom out in Win32 APIs that are scoped to the
//! calling process's WindowStation + Desktop. A process that lives in
//! Session 0 (services) — which is where Windows lands all SSH-launched
//! processes by default — has no attached interactive desktop, so
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/lib.rs b/libs/cua-driver/rust/crates/platform-windows/src/lib.rs
index 215270bd9c..61197fad98 100644
--- a/libs/cua-driver/rust/crates/platform-windows/src/lib.rs
+++ b/libs/cua-driver/rust/crates/platform-windows/src/lib.rs
@@ -135,10 +135,8 @@ pub fn register_tools() -> ToolRegistry {
tools::build_registry(false)
}
-/// `compat=true` enables Claude Code computer-use compatibility mode:
-/// the regular `screenshot` tool is replaced by a window-scoped variant
-/// (pid + window_id required, JPEG @ 85%, text note pointing at pixel
-/// tools). See `tools::impl_::ScreenshotCompatTool`.
+/// `compat` is a legacy Claude Code compatibility flag with no current
+/// tool-surface effect. It remains accepted for launch compatibility.
pub fn register_tools_with_cursor(cfg: cursor_overlay::CursorConfig, compat: bool) -> ToolRegistry {
register_tools_with_cursor_and_provider(None, cfg, compat)
}
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs b/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs
index c5d198335a..68375a2978 100644
--- a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs
+++ b/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs
@@ -1047,9 +1047,9 @@ pub(crate) fn focus_cached_element_for_foreground(
)
}
-// `ScreenshotTool` and `ScreenshotCompatTool` were removed in PR #1692 —
-// `get_window_state` (which now always returns a screenshot) is the single
-// canonical screenshot path. The underlying capture functions
+// The standalone screenshot tools were removed in PR #1692.
+// `get_window_state` is the canonical window-capture path and
+// `get_desktop_state` handles full-display capture. The underlying functions
// (`crate::capture::screenshot_window_bytes_with_occlusion`,
// `screenshot_display_bytes`, etc.) and the WGC backend
// (`crate::wgc::screenshot_window_via_wgc`) are still in use by
@@ -1409,9 +1409,9 @@ pub fn build_registry_with_provider(
&mut r,
Arc::new(crate::clipboard::WindowsClipboard::new()),
);
- // `screenshot` / `ScreenshotCompatTool` removed from the tool surface
- // — `get_window_state` (which now always returns a screenshot) is the
- // single canonical path for getting a window screenshot. Reasons:
+ // The standalone screenshot tools were removed from the tool surface.
+ // `get_window_state` is the canonical path for a window screenshot and
+ // `get_desktop_state` handles explicit full-display capture. Reasons:
// 1. One entry point means callers always have a window_id context,
// which `screenshot` made ambiguous (whole-display fallback
// always picked the wrong thing for headless agent workflows).
@@ -1421,12 +1421,8 @@ pub fn build_registry_with_provider(
// 3. Claude Code's vision pipeline can be retargeted at
// `get_window_state` via its tool-anchor config — no need for
// a dedicated "screenshot" name.
- // The `ScreenshotTool` and `ScreenshotCompatTool` structs are kept in
- // this file for now as private impl helpers — the `capture::*`
- // functions they wrap are still the actual screenshot machinery.
- // Delete the structs in a follow-up after confirming no callers
- // depend on them via `Tool` trait reflection.
- let _ = compat; // formerly drove the ScreenshotCompatTool branch
+ // The `capture::*` functions remain the underlying screenshot machinery.
+ let _ = compat; // legacy flag; no current tool-surface effect
r.register(Box::new(GetScreenSizeTool));
r.register(Box::new(GetDesktopStateTool {
state: state.clone(),
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/tools/launch_app.rs b/libs/cua-driver/rust/crates/platform-windows/src/tools/launch_app.rs
index b908e618d9..e6698ef0e4 100644
--- a/libs/cua-driver/rust/crates/platform-windows/src/tools/launch_app.rs
+++ b/libs/cua-driver/rust/crates/platform-windows/src/tools/launch_app.rs
@@ -174,7 +174,7 @@ impl Tool for LaunchAppTool {
"additional_arguments":{"type":"array","items":{"type":"string"},"description":"Extra command-line arguments passed to the launched process (or activation arguments for packaged apps)."},
"webkit_inspector_port":{"type":"integer","description":"Accepted for cross-platform parity; no-op on Windows."},
"creates_new_application_instance":{"type":"boolean","description":"Accepted for parity; no-op on Windows (ShellExecuteEx always creates a new process)."},
- "start_minimized":{"type":"boolean","description":"When true, launch the app's window minimized to the taskbar instead of restored-but-not-activated. Use this when the agent wants to drive the app entirely in the background — the user's previously-frontmost window (e.g. terminal) stays visually on top. Desktop launches hold the foreground lock through startup and use SW_SHOWMINNOACTIVE; packaged-app activation remains broker-controlled and receives a best-effort SW_SHOWMINNOACTIVE post-pass. UIA / background dispatch still work on a minimized window; only `screenshot` and `delivery_mode:\"foreground\"` need it restored."}
+ "start_minimized":{"type":"boolean","description":"When true, launch the app's window minimized to the taskbar instead of restored-but-not-activated. Use this when the agent wants to drive the app entirely in the background — the user's previously-frontmost window (e.g. terminal) stays visually on top. Desktop launches hold the foreground lock through startup and use SW_SHOWMINNOACTIVE; packaged-app activation remains broker-controlled and receives a best-effort SW_SHOWMINNOACTIVE post-pass. UIA / background dispatch still work on a minimized window; only window screenshots and `delivery_mode:\"foreground\"` need it restored."}
},"additionalProperties":false}),
read_only: false, destructive: false, idempotent: true, open_world: true,
})
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/tools/stubs.rs b/libs/cua-driver/rust/crates/platform-windows/src/tools/stubs.rs
index 6e1e6524d8..f9747c79b0 100644
--- a/libs/cua-driver/rust/crates/platform-windows/src/tools/stubs.rs
+++ b/libs/cua-driver/rust/crates/platform-windows/src/tools/stubs.rs
@@ -172,10 +172,6 @@ stub_tool!(scroll_m, ScrollTool, "scroll",
"Scroll the target pid's focused region. direction required; by defaults to line, amount defaults to 3.",
serde_json::json!({"type":"object","required":["direction"],"properties":{"session": cua_driver_core::tool_schema::session_schema(),"pid":{"type":"integer"},"direction":{"type":"string","enum":["up","down","left","right"]},"by":{"type":"string","enum":["line","page"]},"amount":{"type":"integer","minimum":1,"maximum":50},"window_id":{"type":"integer"},"element_token": cua_driver_core::tool_schema::element_token_schema()},"additionalProperties":false}));
-stub_tool!(screenshot_m, ScreenshotTool, "screenshot",
- "Capture a screenshot. Without window_id captures the full display. Supports png and jpeg formats.",
- serde_json::json!({"type":"object","properties":{"window_id":{"type":"integer"},"format":{"type":"string","enum":["png","jpeg"]},"quality":{"type":"integer","minimum":1,"maximum":95}},"additionalProperties":false}));
-
stub_tool!(
get_screen_size_m,
GetScreenSizeTool,
@@ -320,7 +316,6 @@ pub fn build_registry() -> cua_driver_core::tool::ToolRegistry {
r.register(Box::new(SetValueTool));
r.register(Box::new(InvokeMenuTool));
r.register(Box::new(ScrollTool));
- r.register(Box::new(ScreenshotTool));
r.register(Box::new(GetScreenSizeTool));
r.register(Box::new(GetCursorPositionTool));
r.register(Box::new(MoveCursorTool));
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/uia/mod.rs b/libs/cua-driver/rust/crates/platform-windows/src/uia/mod.rs
index 11c6b16ad9..1228a8769d 100644
--- a/libs/cua-driver/rust/crates/platform-windows/src/uia/mod.rs
+++ b/libs/cua-driver/rust/crates/platform-windows/src/uia/mod.rs
@@ -262,8 +262,8 @@ pub fn invoke_menu_path(hwnd: u64, path: &[String]) -> Result<(), String> {
}
/// Walk the UIA tree with caller-supplied caps. `max_elements`/`max_depth`
-/// truncate the walk and the rendered markdown identically. Issue #22865:
-/// caps protect against Electron / large web apps that produce 10k+
+/// truncate the walk and the rendered markdown identically. These caps
+/// protect against Electron / large web apps that produce 10k+
/// element trees and blow context windows.
pub fn walk_tree_bounded(
hwnd: u64,
diff --git a/libs/cua-driver/scripts/install.ps1 b/libs/cua-driver/scripts/install.ps1
index 34db8aac48..fc4b5ae506 100644
--- a/libs/cua-driver/scripts/install.ps1
+++ b/libs/cua-driver/scripts/install.ps1
@@ -62,7 +62,7 @@
# every logon (Windows-native equivalent of macOS LaunchAgent).
# The task runs with LogonType=Interactive so it lands in
# Session 1+ with an attached desktop — required for the
-# GUI tools (click, type_text, screenshot, get_window_state)
+# GUI tools (click, type_text, get_window_state, get_desktop_state)
# to function. Default off; the post-install message prints
# the registration command so you can opt in later. Safe to
# re-run: existing task is replaced.
diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json
index ccce45451a..2664ebe866 100644
--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json
+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json
@@ -332,7 +332,7 @@
"type": "string"
},
"start_minimized": {
- "description": "When true, launch the app's window minimized to the taskbar instead of restored-but-not-activated. Use this when the agent wants to drive the app entirely in the background — the user's previously-frontmost window (e.g. terminal) stays visually on top. Desktop launches hold the foreground lock through startup and use SW_SHOWMINNOACTIVE; packaged-app activation remains broker-controlled and receives a best-effort SW_SHOWMINNOACTIVE post-pass. UIA / background dispatch still work on a minimized window; only `screenshot` and `delivery_mode:\"foreground\"` need it restored.",
+ "description": "When true, launch the app's window minimized to the taskbar instead of restored-but-not-activated. Use this when the agent wants to drive the app entirely in the background — the user's previously-frontmost window (e.g. terminal) stays visually on top. Desktop launches hold the foreground lock through startup and use SW_SHOWMINNOACTIVE; packaged-app activation remains broker-controlled and receives a best-effort SW_SHOWMINNOACTIVE post-pass. UIA / background dispatch still work on a minimized window; only window screenshots and `delivery_mode:\"foreground\"` need it restored.",
"type": "boolean"
},
"urls": {
diff --git a/scripts/docs-generators/cli-specs/cua-driver.json b/scripts/docs-generators/cli-specs/cua-driver.json
index 8a10196722..cb928f90e2 100644
--- a/scripts/docs-generators/cli-specs/cua-driver.json
+++ b/scripts/docs-generators/cli-specs/cua-driver.json
@@ -200,7 +200,7 @@
"flags": [
{
"default_value": false,
- "help": "Select the Claude Code computer-use compatibility surface (forwarded by `mcp` when it launches the daemon).",
+ "help": "Legacy compatibility flag forwarded by `mcp` when it launches the daemon; no current tool-surface effect.",
"name": "claude-code-computer-use-compat",
"short_name": null
},