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.

feat(cua-driver): opt-in refusal of ungranted macOS Automation scripting (#5777)

injaneity8d9ec709d2e2
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 c6eb3f864d..8ed4e6a307 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
@@ -270,6 +270,7 @@ cua-driver serve [OPTIONS]
| <span id="cua-driver-serve--approve-capability-manifest"></span>`--approve-capability-manifest` | boolean | `false` | Trusted-launcher confirmation that the exact capability manifest was reviewed. |
| <span id="cua-driver-serve--approve-session-policy"></span>`--approve-session-policy` | boolean | `false` | Deprecated alias for approve-capability-manifest. |
| <span id="cua-driver-serve--no-permissions-gate"></span>`--no-permissions-gate` | boolean | `false` | Skip the macOS first-launch permissions gate. |
+| <span id="cua-driver-serve--no-automation-prompts"></span>`--no-automation-prompts` | boolean | `false` | Refuse scripting actions without granted macOS Automation consent. |
| <span id="cua-driver-serve--embedded"></span>`--embedded` | boolean | `false` | Run embedded inside a host app: inherit the host's TCC grants, never prompt or relaunch. Also CUA_DRIVER_EMBEDDED=1. |
| <span id="cua-driver-serve--no-overlay"></span>`--no-overlay` | boolean | `false` | Disable the agent cursor overlay for this daemon. |
| <span id="cua-driver-serve--experimental-history"></span>`--experimental-history` | boolean | `false` | Admit the encrypted local Computer History early preview for this daemon launch. |
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/click-and-type.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/click-and-type.mdx
index dff564def6..f0b99e6113 100644
--- a/docs/content/docs/cua-driver/reference/mcp-tools/click-and-type.mdx
+++ b/docs/content/docs/cua-driver/reference/mcp-tools/click-and-type.mdx
@@ -499,7 +499,7 @@ Effect: destructive. Platforms: macOS, Linux, Windows.
<Tab value="macOS">
Press a key combination: e.g. `["cmd", "c"]` for Copy, `["cmd", "shift", "4"]` for screenshot selection. Follows the same `delivery_mode` ladder as click/type_text: it does NOT raise the window by default:
-• `background` (default): post the combo to the target pid WITHOUT fronting or raising it; uses the macOS 14+ auth-message envelope so Chromium/Electron accept it as trusted live input. With an AX target, focus that exact element first. No top-level focus steal. `window_id` here only targets the combo; it does not raise. Background key events never reach a native app's menus, so when the combo is a menu item's key equivalent (cmd+s, cmd+w, ...) and the app is not in front, that menu item runs through accessibility instead (a disabled Save is saved through the app's scripting interface and verified on disk); a menu item macOS keeps disabled in the background is refused with `background_unavailable`, and no keys are sent.
+• `background` (default): post the combo to the target pid WITHOUT fronting or raising it; uses the macOS 14+ auth-message envelope so Chromium/Electron accept it as trusted live input. With an AX target, focus that exact element first. No top-level focus steal. `window_id` here only targets the combo; it does not raise. Background key events never reach a native app's menus, so when the combo is a menu item's key equivalent (cmd+s, cmd+w, ...) and the app is not in front, that menu item runs through accessibility instead (a disabled Save is saved through the app's scripting interface and verified on disk); a menu item macOS keeps disabled in the background is refused with `background_unavailable`. With serve --no-automation-prompts, scripting without granted consent refuses with `automation_consent_required`, without keyboard fallback.
• `foreground`: briefly front the window (NSMenu path, &lt; 1 ms via SLPSSetFrontProcessWithOptions) so native menu key-equivalents (Cmd+Z, Cmd+W) dispatch, then restore the prior frontmost; the explicit escalation for menu-bar shortcuts on non-Chromium apps that ignore a background combo. With an AX target or x,y, the focused field receives the chord through the foreground HID queue (needed by native Chromium fields such as the omnibox). Requires window_id.
A combo is never driver-verifiable (no read-back) → effect:"unverifiable"; confirm via screenshot. NOTE: a keyboard combo does NOT focus a text field; to type into a backgrounded Electron input, establish real renderer focus with a PIXEL click first, then `type_text`. If an app only accepts paste, call `clipboard_write`, then `clipboard_read` and verify its types (and text when applicable) before selecting or replacing editor content; only then send Cmd+V.
@@ -599,7 +599,7 @@ Effect: destructive, idempotent. Platforms: macOS, Linux, Windows.
Set an element's value by `element_token`. A popup button / select dropdown: selects the menu item whose title or value matches `value` (case-insensitive). Safari `<select>` is set through the DOM; AppKit and Chromium popups list items only while open, so the menu is opened, the item pressed and the menu closed again (in the background the user's front window keeps key focus). An unknown value lists the options. Any other element: writes AXValue (sliders, steppers, date pickers, native text fields).
-A Finder file name cell (list or icon view, not being edited) is renamed through Finder's scripting interface with Finder left in the background, and the new name is read back from disk; the value is the full new name with its extension. macOS asks the user once to allow Cua Driver to control Finder. Finder's Get Info `Name` field is refused with `file_name_needs_rename`. For free-form text in web inputs use `type_text_chars`: WebKit ignores AXValue writes.
+A Finder file name cell (list or icon view, not being edited) is renamed through Finder's scripting interface with Finder left in the background, and the new name is read back from disk; the value is the full new name with its extension. macOS may prompt for Automation consent; with serve --no-automation-prompts, ungranted consent refuses with automation_consent_required. Finder's Get Info `Name` field is refused with `file_name_needs_rename`. For free-form text in web inputs use `type_text_chars`: WebKit ignores AXValue writes.
**macOS parameters**
diff --git a/libs/cua-driver/rust/Skills/cua-driver/MACOS.md b/libs/cua-driver/rust/Skills/cua-driver/MACOS.md
index b502b6f557..dd15da43eb 100644
--- a/libs/cua-driver/rust/Skills/cua-driver/MACOS.md
+++ b/libs/cua-driver/rust/Skills/cua-driver/MACOS.md
@@ -96,10 +96,21 @@ through the app's scripting interface instead, still in the background, and the
result says so; TextEdit disables Save whenever it is behind the user's window.
A Save is verified on disk. A background `hotkey` whose combo is a menu item's
key equivalent (⌘S, ⌘W, ⌘C, ...) in a native app takes the same route, because
-background key events never reach an app's menus; no keys are sent. macOS asks
-the user once to allow Cua Driver to control the app (Automation) the first
-time a scripting route runs; when that is off, the call refuses and nothing is
-saved.
+background key events never reach an app's menus; no keys are sent. By default,
+macOS may prompt for Automation consent on first use; unanswered prompts can
+recur. Denied consent refuses the scripting action.
+
+For unattended use, start `cua-driver serve --no-automation-prompts` before
+connecting `cua-driver mcp --socket <path>`. MCP's auto-started daemon does not
+enable this protection, and the flag is serve-only. Only explicitly granted
+Automation targets may receive scripting actions: background Save (including
+hotkeys), Finder rename, browser Apple Events JavaScript and browser quit for
+JavaScript setup, and Safari select updates. Ungranted or unknown consent
+refuses immediately with `automation_consent_required`, naming the app and
+System Settings > Privacy & Security > Automation; no scripting action or
+keyboard fallback is sent. Grant consent with the user's authorization before
+retrying. This does not suppress Accessibility/Screen Recording onboarding or
+other unrelated OS prompts. Omit the flag to preserve prompt-on-first-use behavior.
With the app already in front it resolves every AX level live. Prefer an in-window
element action when the same command has an ordinary control, and prefer
`set_window_frame` for exact geometry. Full rationale is in “Navigating native
@@ -959,6 +970,7 @@ starting point for new browser workflows.
| `Accessibility permission not granted` | TCC not granted | Stop. Follow [Install and approve permissions](#install-and-approve-permissions): approve it yourself only when the owner authorized that for this task, otherwise tell the user to grant it in System Settings |
| `Screen Recording permission not granted` | TCC not granted for capture | Screenshots and pixel actions are unavailable. If the task is AX-completable, use `get_window_state({include_screenshot:false})` and `element_token` actions; otherwise stop and ask the user to run `cua-driver permissions grant` (see [Install and approve permissions](#install-and-approve-permissions)) |
| `AX action failed: ... returned -25200` (or -25205, -25206) | The app may have acted anyway: some AppKit controls return these after a press they performed | Re-read with `get_window_state` before retrying; a second press on a checkbox toggles it back. A radio button or checkbox whose AXValue settles on the pressed state is reported as performed, naming the error |
+| `automation_consent_required` | With `serve --no-automation-prompts`, Automation consent is not explicitly granted for the named app; no scripting action was sent | With the user's authorization, grant access in System Settings > Privacy & Security > Automation |
| `set_value refused (file_name_needs_rename)` | A file's name in Finder's Get Info window (AXIdentifier `Name`): an AXValue write changes only the field | `set_value` the full new name on the file's name cell in a Finder window that lists it (renamed through Finder in the background and read back from disk) |
| `Background input refused (no_focused_text_input)` | Untargeted background `type_text` while the window's focused element is not a text input or an editing surface (spreadsheet grid, document canvas: `AXLayoutArea`, `AXScrollArea`, `AXTable`, `AXCell`, `AXGroup`; not in Finder/Dock); keys would drive the view (Finder type-to-select) | pass the field's `element_token`, or `x,y` to pixel-focus it first; to rename a Finder file, `set_value` its name cell |
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 084ddcee47..1a9f474c37 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/cli.rs
@@ -69,6 +69,7 @@ pub enum Command {
/// (checked inside the gate itself), so the flag is only one of
/// two opt-out signals.
no_permissions_gate: bool,
+ 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
@@ -273,6 +274,7 @@ const SERVE_ONLY_AUTHORIZATION_FLAGS: &[&str] = &[
"--approve-session-policy",
"--dangerously-bypass-approvals",
"--no-permissions-gate",
+ "--no-automation-prompts",
];
fn serve_only_authorization_flag(args: &[String]) -> Option<&'static str> {
@@ -621,6 +623,7 @@ pub fn parse_command() -> Command {
println!(" The capture file supplies source metadata only; the image is never registered as a reusable capture.");
println!();
println!("agent authorization (serve only):");
+ println!(" --no-automation-prompts Refuse scripting actions without granted macOS Automation consent.");
println!(" --permission-mode <mode> standard (default), bounded, or unrestricted.");
println!(
" --grant existing-profile Pre-authorize existing logged-in Chromium attachment"
@@ -799,7 +802,10 @@ pub fn parse_command() -> Command {
if matches!(positionals.first().copied(), None | Some("mcp")) {
if let Some(flag) = serve_only_authorization_flag(&args) {
eprintln!("cua-driver mcp does not accept {flag}; authorization flags belong to `cua-driver serve`.");
- eprintln!("For direct MCP, use CUA_DRIVER_PERMISSION_MODE and the related CUA_DRIVER_* environment variables.");
+ if flag == "--no-automation-prompts" {
+ eprintln!("Start `cua-driver serve --no-automation-prompts` before connecting MCP; an auto-started daemon does not enable this protection.");
+ }
+ eprintln!("For direct MCP authorization, use CUA_DRIVER_PERMISSION_MODE and the related CUA_DRIVER_* environment variables.");
eprintln!("Otherwise start a configured daemon and connect with `cua-driver mcp --socket <path>`." );
process::exit(64);
}
@@ -868,6 +874,7 @@ pub fn parse_command() -> Command {
.any(|a| a == "--approve-capability-manifest" || a == "--approve-session-policy"),
// Bare flag — present anywhere on argv counts as "skip the gate".
no_permissions_gate: args.iter().any(|a| a == "--no-permissions-gate"),
+ no_automation_prompts: args.iter().any(|a| a == "--no-automation-prompts"),
claude_code_compat,
grants,
experimental_history: args.iter().any(|a| a == "--experimental-history"),
@@ -1771,6 +1778,9 @@ fn append_daemon_launch_state(
if state.no_permissions_gate {
args.push("--no-permissions-gate".to_owned());
}
+ if state.no_automation_prompts {
+ args.push("--no-automation-prompts".to_owned());
+ }
if state.claude_code_compat {
args.push("--claude-code-computer-use-compat".to_owned());
}
@@ -2015,6 +2025,7 @@ pub fn build_manifest() -> serde_json::Value {
{ "name": "--session-policy", "type": "string", "description": "Deprecated alias for --capability-manifest." },
{ "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": "--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." }
@@ -4445,6 +4456,7 @@ fn cli_docs_literal() -> serde_json::Value {
{"name":"approve-capability-manifest","short_name":null,"help":"Trusted-launcher confirmation that the exact capability manifest was reviewed.","default_value":false},
{"name":"approve-session-policy","short_name":null,"help":"Deprecated alias for approve-capability-manifest.","default_value":false},
{"name":"no-permissions-gate","short_name":null,"help":"Skip the macOS first-launch permissions gate.","default_value":false},
+ {"name":"no-automation-prompts","short_name":null,"help":"Refuse scripting actions without granted macOS Automation consent.","default_value":false},
{"name":"embedded","short_name":null,"help":"Run embedded inside a host app: inherit the host's TCC grants, never prompt or relaunch. Also CUA_DRIVER_EMBEDDED=1.","default_value":false},
{"name":"no-overlay","short_name":null,"help":"Disable the agent cursor overlay for this daemon.","default_value":false},
{"name":"experimental-history","short_name":null,"help":"Admit the encrypted local Computer History early preview for this daemon launch.","default_value":false}
@@ -5799,6 +5811,7 @@ mod tests {
capability_manifest: Some("/tmp/capabilities.yaml".to_owned()),
approve_capability_manifest: true,
no_permissions_gate: true,
+ no_automation_prompts: true,
claude_code_compat: true,
grants,
};
@@ -5819,6 +5832,19 @@ mod tests {
.any(|pair| { pair == ["--capability-manifest", "/tmp/capabilities.yaml"] }));
assert!(launch.contains(&"--approve-capability-manifest".to_owned()));
assert!(launch.contains(&"--no-permissions-gate".to_owned()));
+ assert!(launch.contains(&"--no-automation-prompts".to_owned()));
+ let encoded = serde_json::to_value(&state).unwrap();
+ let restored: crate::history_runtime::DaemonLaunchState =
+ serde_json::from_value(encoded.clone()).unwrap();
+ assert!(restored.no_automation_prompts);
+ let mut legacy = encoded;
+ legacy
+ .as_object_mut()
+ .unwrap()
+ .remove("no_automation_prompts");
+ let restored: crate::history_runtime::DaemonLaunchState =
+ serde_json::from_value(legacy).unwrap();
+ assert!(!restored.no_automation_prompts);
assert!(launch.contains(&"--claude-code-computer-use-compat".to_owned()));
assert!(launch.contains(&"--experimental-history".to_owned()));
assert!(launch
@@ -5854,6 +5880,14 @@ mod tests {
assert!(!launch.contains(&"CuaDriver".to_owned()));
}
+ #[test]
+ fn automation_prompt_flag_is_serve_only() {
+ assert_eq!(
+ serve_only_authorization_flag(&args(&["mcp", "--no-automation-prompts"])),
+ Some("--no-automation-prompts")
+ );
+ }
+
#[test]
fn history_relaunch_preserves_explicit_unrestricted_approval() {
let state = crate::history_runtime::DaemonLaunchState {
@@ -5867,6 +5901,8 @@ mod tests {
.windows(2)
.any(|pair| { pair == ["--permission-mode", "unrestricted"] }));
assert!(launch.contains(&"--dangerously-bypass-approvals".to_owned()));
+ assert!(!state.no_automation_prompts);
+ assert!(!launch.contains(&"--no-automation-prompts".to_owned()));
}
#[test]
diff --git a/libs/cua-driver/rust/crates/cua-driver/src/history_runtime.rs b/libs/cua-driver/rust/crates/cua-driver/src/history_runtime.rs
index 709546823f..967c30da1c 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/history_runtime.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/history_runtime.rs
@@ -28,6 +28,8 @@ pub struct DaemonLaunchState {
pub capability_manifest: Option<String>,
pub approve_capability_manifest: bool,
pub no_permissions_gate: bool,
+ #[serde(default)]
+ pub no_automation_prompts: bool,
pub claude_code_compat: bool,
pub grants: Vec<String>,
}
@@ -47,6 +49,7 @@ pub fn configure_daemon_launch_state(
capability_manifest: Option<&str>,
approve_capability_manifest: bool,
no_permissions_gate: bool,
+ no_automation_prompts: bool,
claude_code_compat: bool,
grants: &[String],
) {
@@ -57,6 +60,7 @@ pub fn configure_daemon_launch_state(
capability_manifest: capability_manifest.map(str::to_owned),
approve_capability_manifest,
no_permissions_gate,
+ no_automation_prompts,
claude_code_compat,
grants: grants.to_vec(),
};
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 a7abdcbc45..891da82b38 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/main.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/main.rs
@@ -582,6 +582,7 @@ fn main() {
capability_manifest,
approve_capability_manifest,
no_permissions_gate,
+ no_automation_prompts,
claude_code_compat,
grants,
experimental_history,
@@ -611,9 +612,11 @@ fn main() {
capability_manifest.as_deref(),
approve_capability_manifest,
no_permissions_gate,
+ no_automation_prompts,
claude_code_compat,
&grants,
);
+ platform_macos::apple_events::refuse_ungranted_automation(no_automation_prompts);
let gate_opts =
platform_macos::permissions::GateOpts::from_env_and_flag(no_permissions_gate);
if let Some((progress, context)) =
@@ -1006,6 +1009,7 @@ fn main() -> anyhow::Result<()> {
capability_manifest,
approve_capability_manifest,
no_permissions_gate,
+ no_automation_prompts,
claude_code_compat,
grants,
experimental_history,
@@ -1029,6 +1033,7 @@ fn main() -> anyhow::Result<()> {
capability_manifest.as_deref(),
approve_capability_manifest,
no_permissions_gate,
+ no_automation_prompts,
claude_code_compat,
&grants,
);
@@ -1043,7 +1048,7 @@ fn main() -> anyhow::Result<()> {
// 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.
- let _ = no_permissions_gate;
+ 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();
let driver = build_driver(
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/apple_events.rs b/libs/cua-driver/rust/crates/platform-macos/src/apple_events.rs
index b4ee2a43fb..34642dad23 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/apple_events.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/apple_events.rs
@@ -10,21 +10,28 @@
//! touching the pointer, so these routes keep the user's front app untouched.
//!
//! Apple Events need the user's Automation consent for each target app. The
-//! permission is read first without asking. When macOS has never asked, it
-//! shows its consent prompt once, on the first route that needs that app.
-//! When the user has turned it off, the caller gets an honest refusal.
+//! permission is read first without asking. By default, ungranted permission
+//! may trigger a consent prompt. With `serve --no-automation-prompts`, only
+//! explicitly granted targets may receive scripting actions.
use std::ffi::c_void;
use std::io::Write;
use std::path::Path;
use std::process::{Command, Stdio};
+use std::sync::atomic::{AtomicBool, Ordering};
use std::time::{Duration, Instant};
+static REFUSE_UNGRANTED_AUTOMATION: AtomicBool = AtomicBool::new(false);
+
+pub fn refuse_ungranted_automation(refuse: bool) {
+ REFUSE_UNGRANTED_AUTOMATION.store(refuse, Ordering::Release);
+}
+
/// Whether this process may send Apple Events to an app.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AutomationPermission {
Granted,
- /// macOS has not asked the user yet; the first event shows its prompt.
+ /// macOS has not asked the user yet; sending an event may show its prompt.
NeedsConsent,
/// The user turned it off in System Settings > Privacy & Security >
/// Automation.
@@ -177,10 +184,22 @@ fn script_error_refusal(stderr: &str) -> ScriptRefusal {
}
}
-/// Check the permission before a route runs: refuse when the user turned it
-/// off, so no event is sent.
-fn ensure_permitted(bundle_id: &str, app_name: &str) -> Result<(), ScriptRefusal> {
- match automation_permission(bundle_id) {
+pub(crate) fn ensure_permitted(bundle_id: &str, app_name: &str) -> Result<(), ScriptRefusal> {
+ check_permission(
+ automation_permission(bundle_id),
+ REFUSE_UNGRANTED_AUTOMATION.load(Ordering::Acquire),
+ bundle_id,
+ app_name,
+ )
+}
+
+fn check_permission(
+ permission: AutomationPermission,
+ refuse_ungranted: bool,
+ bundle_id: &str,
+ app_name: &str,
+) -> Result<(), ScriptRefusal> {
+ match permission {
AutomationPermission::Denied => Err(ScriptRefusal {
code: "automation_denied",
reason: format!(
@@ -192,7 +211,23 @@ fn ensure_permitted(bundle_id: &str, app_name: &str) -> Result<(), ScriptRefusal
code: "automation_failed",
reason: format!("{app_name} is not running"),
}),
- // NeedsConsent: macOS shows its prompt once, on this event.
+ AutomationPermission::NeedsConsent | AutomationPermission::Unknown(_)
+ if refuse_ungranted =>
+ {
+ let detail = match permission {
+ AutomationPermission::Unknown(status) => {
+ format!(" (permission status {status}; consent has not been established)")
+ }
+ _ => String::new(),
+ };
+ Err(ScriptRefusal {
+ code: "automation_consent_required",
+ reason: format!(
+ "Automation permission for {app_name} ({bundle_id}) is not granted{detail}. \
+ No scripting action was sent. Grant access in System Settings > Privacy & Security > Automation."
+ ),
+ })
+ }
_ => Ok(()),
}
}
@@ -473,6 +508,41 @@ mod tests {
);
}
+ #[test]
+ fn unattended_actions_require_explicit_automation_consent() {
+ for refuse in [false, true] {
+ for (permission, expected) in [
+ (AutomationPermission::Granted, None),
+ (AutomationPermission::Denied, Some("automation_denied")),
+ (AutomationPermission::NotRunning, Some("automation_failed")),
+ (
+ AutomationPermission::NeedsConsent,
+ refuse.then_some("automation_consent_required"),
+ ),
+ (
+ AutomationPermission::Unknown(-50),
+ refuse.then_some("automation_consent_required"),
+ ),
+ ] {
+ let result = check_permission(permission, refuse, "com.apple.TextEdit", "TextEdit");
+ assert_eq!(result.as_ref().err().map(|r| r.code), expected);
+ if expected == Some("automation_consent_required") {
+ let reason = result.unwrap_err().reason;
+ for text in [
+ "TextEdit",
+ "com.apple.TextEdit",
+ "System Settings > Privacy & Security > Automation",
+ ] {
+ assert!(reason.contains(text), "{reason}");
+ }
+ if let AutomationPermission::Unknown(status) = permission {
+ assert!(reason.contains(&status.to_string()));
+ }
+ }
+ }
+ }
+ }
+
#[test]
fn script_errors_name_a_denied_permission() {
let denied = script_error_refusal(
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/browser/browser_js.rs b/libs/cua-driver/rust/crates/platform-macos/src/browser/browser_js.rs
index 5d1e2c2adf..459926774d 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/browser/browser_js.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/browser/browser_js.rs
@@ -28,6 +28,17 @@ fn app_name_for_bundle(bundle_id: &str) -> Option<&'static str> {
}
}
+fn should_quit_before_enabling(
+ permission: crate::apple_events::AutomationPermission,
+ ensure_permitted: impl FnOnce() -> Result<(), crate::apple_events::ScriptRefusal>,
+) -> Result<bool, crate::apple_events::ScriptRefusal> {
+ if permission == crate::apple_events::AutomationPermission::NotRunning {
+ return Ok(false);
+ }
+ ensure_permitted()?;
+ Ok(true)
+}
+
impl BrowserJs {
/// Returns true if this bundle ID is a supported browser.
pub fn supports(bundle_id: &str) -> bool {
@@ -44,6 +55,9 @@ impl BrowserJs {
let app_name = app_name_for_bundle(bundle_id)
.ok_or_else(|| anyhow::anyhow!("Unsupported browser bundle: {bundle_id}"))?;
+ crate::apple_events::ensure_permitted(bundle_id, app_name)
+ .map_err(|r| anyhow::anyhow!("{}: {}", r.code, r.reason))?;
+
// Resolve the WindowServer CGWindowID to stable properties that can be
// matched against the browser's AppleScript window model.
let target = {
@@ -91,15 +105,23 @@ end tell"#
let app_name = app_name_for_bundle(bundle_id)
.ok_or_else(|| anyhow::anyhow!("Unsupported browser bundle: {bundle_id}"))?;
- // Quit the browser.
- let quit_script = format!("tell application \"{app_name}\" to quit");
- let _ = tokio::process::Command::new("/usr/bin/osascript")
- .arg("-e")
- .arg(&quit_script)
- .output()
- .await;
+ let should_quit = should_quit_before_enabling(
+ crate::apple_events::automation_permission(bundle_id),
+ || crate::apple_events::ensure_permitted(bundle_id, app_name),
+ )
+ .map_err(|r| anyhow::anyhow!("{}: {}", r.code, r.reason))?;
- tokio::time::sleep(Duration::from_secs(1)).await;
+ // Quit the browser.
+ if should_quit {
+ let quit_script = format!("tell application \"{app_name}\" to quit");
+ let _ = tokio::process::Command::new("/usr/bin/osascript")
+ .arg("-e")
+ .arg(&quit_script)
+ .output()
+ .await;
+
+ tokio::time::sleep(Duration::from_secs(1)).await;
+ }
// Find profile directory.
let home = std::env::var("HOME").unwrap_or_default();
@@ -417,6 +439,36 @@ mod tests {
}
}
+ #[test]
+ fn closed_browser_skips_quit_without_checking_consent() {
+ for refuse_ungranted in [false, true] {
+ let should_quit = should_quit_before_enabling(
+ crate::apple_events::AutomationPermission::NotRunning,
+ || panic!("closed browser checked consent with refuse={refuse_ungranted}"),
+ )
+ .unwrap();
+ assert!(!should_quit);
+ }
+ }
+
+ #[test]
+ fn running_browser_requires_permission_before_quitting() {
+ use crate::apple_events::{AutomationPermission, ScriptRefusal};
+
+ assert!(should_quit_before_enabling(AutomationPermission::Granted, || Ok(())).unwrap());
+ let refusal = ScriptRefusal {
+ code: "automation_consent_required",
+ reason: "Grant access in System Settings > Privacy & Security > Automation".into(),
+ };
+ assert_eq!(
+ should_quit_before_enabling(
+ AutomationPermission::NeedsConsent,
+ || Err(refusal.clone())
+ ),
+ Err(refusal)
+ );
+ }
+
#[test]
fn applescript_process_identity_accepts_only_the_requested_single_instance() {
assert!(ensure_applescript_process_identity_in("com.google.Chrome", 4242, &[4242]).is_ok());
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/hotkey.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/hotkey.rs
index 2bf28e0582..0614effb78 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/hotkey.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/hotkey.rs
@@ -45,7 +45,9 @@ fn def() -> &'static ToolDef {
front, that menu item runs through accessibility instead (a disabled \
Save is saved through the app's scripting interface and verified on \
disk); a menu item macOS keeps disabled in the background is refused \
- with `background_unavailable`, and no keys are sent.\n\
+ with `background_unavailable`. With serve --no-automation-prompts, \
+ scripting without granted consent refuses with `automation_consent_required`, \
+ without keyboard fallback.\n\
• `foreground`: briefly front the window (NSMenu path, < 1 ms via \
SLPSSetFrontProcessWithOptions) so native menu key-equivalents \
(Cmd+Z, Cmd+W) dispatch, then restore the prior frontmost — the \
@@ -639,7 +641,11 @@ mod tests {
#[test]
fn menu_safety_refusals_do_not_fall_back_to_keys() {
- for code in ["window_not_key", "background_unavailable"] {
+ for code in [
+ "window_not_key",
+ "background_unavailable",
+ "automation_consent_required",
+ ] {
let result =
ToolResult::error("refused").with_structured(serde_json::json!({ "code": code }));
assert_eq!(
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/invoke_menu.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/invoke_menu.rs
index 841d8d000d..fff2ebd1e7 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/invoke_menu.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/invoke_menu.rs
@@ -545,10 +545,15 @@ fn background_unavailable(reason: String) -> ToolResult {
help: the disabled item ignores its shortcut too. Otherwise use the control in the \
window."
);
+ structured_refusal("background_unavailable", message)
+}
+
+fn structured_refusal(code: &str, message: String) -> ToolResult {
ToolResult::error(message.clone()).with_structured(serde_json::json!({
"status": "refused",
- "code": "background_unavailable",
- "refusal": { "code": "background_unavailable", "message": message }
+ "code": code,
+ "effect": "refused",
+ "refusal": { "code": code, "message": message }
}))
}
@@ -873,6 +878,9 @@ pub(super) async fn run_in_background(
ActionTransport::MacosAppleEvent,
"The app's scripting interface reported the document saved",
),
+ Ok(Err(refusal)) if refusal.code == "automation_consent_required" => {
+ structured_refusal(refusal.code, format!("{preface}{}", refusal.reason))
+ }
Ok(Err(refusal)) => background_unavailable(format!(
"{preface}{message}, and saving through {app_name}'s scripting interface did not \
complete ({}: {}). Nothing was saved",
@@ -1074,6 +1082,14 @@ mod tests {
assert!(message.contains("bring_to_front"));
assert!(message.contains("delivery_mode:\"foreground\""));
assert!(message.contains("A background hotkey does not help"));
+ let reason = "hotkey cmd+s: Grant TextEdit access in System Settings > Privacy & Security > Automation";
+ let result = structured_refusal("automation_consent_required", reason.into());
+ assert_eq!(result.is_error, Some(true));
+ let data = result.structured_content.unwrap();
+ assert_eq!(data["code"], "automation_consent_required");
+ assert_eq!(data["effect"], "refused");
+ assert_eq!(data["refusal"]["code"], "automation_consent_required");
+ assert_eq!(data["refusal"]["message"], reason);
}
#[test]
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/set_value.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/set_value.rs
index 3b786748c2..f9b905fc61 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/set_value.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/set_value.rs
@@ -48,7 +48,7 @@ fn def() -> &'static ToolDef {
name: "set_value".into(),
description: "Set an element's value by `element_token`. A popup button / select dropdown: selects the menu item whose title or value matches `value` (case-insensitive). Safari `<select>` is set through the DOM; AppKit and Chromium popups list items only while open, so the menu is opened, the item pressed and the menu closed again (in the background the user's front window keeps key focus). An unknown value lists the options. Any other element: writes AXValue (sliders, steppers, date pickers, native text fields).\n\
\n\
- A Finder file name cell (list or icon view, not being edited) is renamed through Finder's scripting interface with Finder left in the background, and the new name is read back from disk; the value is the full new name with its extension. macOS asks the user once to allow Cua Driver to control Finder. Finder's Get Info `Name` field is refused with `file_name_needs_rename`. For free-form text in web inputs use `type_text_chars`: WebKit ignores AXValue writes.".into(),
+ A Finder file name cell (list or icon view, not being edited) is renamed through Finder's scripting interface with Finder left in the background, and the new name is read back from disk; the value is the full new name with its extension. macOS may prompt for Automation consent; with serve --no-automation-prompts, ungranted consent refuses with automation_consent_required. Finder's Get Info `Name` field is refused with `file_name_needs_rename`. For free-form text in web inputs use `type_text_chars`: WebKit ignores AXValue writes.".into(),
input_schema: serde_json::json!({
"type": "object",
"required": ["value"],
@@ -377,20 +377,27 @@ fn finder_rename_result(
"renamed_to": new_path.display().to_string(),
}))
.with_action_record(rename_record()),
- Ok(Err(refusal)) => ToolResult::error(format!(
- "set_value refused ({FILE_NAME_NEEDS_RENAME}): renaming \"{old_name}\" through \
+ Ok(Err(refusal)) => {
+ let code = if refusal.code == "automation_consent_required" {
+ refusal.code
+ } else {
+ FILE_NAME_NEEDS_RENAME
+ };
+ ToolResult::error(format!(
+ "set_value refused ({code}): renaming \"{old_name}\" through \
Finder did not complete ({}: {}). The file keeps its name; nothing else was sent.",
- refusal.code, refusal.reason
- ))
- .with_structured(serde_json::json!({
- "code": FILE_NAME_NEEDS_RENAME,
- "effect": "refused",
- "path": "apple_events",
- "pid": pid,
- "window_id": window_id,
- "reason": refusal.reason,
- "cause": refusal.code,
- })),
+ refusal.code, refusal.reason
+ ))
+ .with_structured(serde_json::json!({
+ "code": code,
+ "effect": "refused",
+ "path": "apple_events",
+ "pid": pid,
+ "window_id": window_id,
+ "reason": refusal.reason,
+ "cause": refusal.code,
+ }))
+ }
Err(error) => ToolResult::error(format!("set_value rename task failed: {error}")),
}
}
@@ -1183,6 +1190,8 @@ fn set_select_via_js(
element_title: &str,
value: &str,
) -> anyhow::Result<String> {
+ crate::apple_events::ensure_permitted("com.apple.Safari", "Safari")
+ .map_err(|r| anyhow::anyhow!("{}: {}", r.code, r.reason))?;
// Percent-encode the lowercased value using only unreserved URL characters
// as the allowed set, matching the Swift reference's percent-encoding approach.
// This makes the string safe to embed in both a JS single-quoted string
@@ -1326,6 +1335,26 @@ mod tests {
let data = refused.structured_content.unwrap();
assert_eq!(data["code"], "file_name_needs_rename");
assert_eq!(data["cause"], "automation_denied");
+ let refused = super::finder_rename_result(
+ 7,
+ 42,
+ path,
+ "b.txt",
+ Ok(Err(crate::apple_events::ScriptRefusal {
+ code: "automation_consent_required",
+ reason: "Grant Finder access in System Settings > Privacy & Security > Automation"
+ .into(),
+ })),
+ );
+ assert_eq!(refused.is_error, Some(true));
+ let data = refused.structured_content.unwrap();
+ assert_eq!(data["code"], "automation_consent_required");
+ assert_eq!(data["cause"], "automation_consent_required");
+ assert_eq!(data["effect"], "refused");
+ assert_eq!(
+ data["reason"],
+ "Grant Finder access in System Settings > Privacy & Security > Automation"
+ );
}
#[test]
diff --git a/libs/cua/skills/cua-driver/MACOS.md b/libs/cua/skills/cua-driver/MACOS.md
index fdb117c17f..aa252636cb 100644
--- a/libs/cua/skills/cua-driver/MACOS.md
+++ b/libs/cua/skills/cua-driver/MACOS.md
@@ -89,6 +89,19 @@ element action when the same command has an ordinary control, and prefer
`set_window_frame` for exact geometry. Full rationale is in “Navigating native
menu bars” below.
+For unattended use, start `cua-driver serve --no-automation-prompts` before
+connecting `cua-driver mcp --socket <path>`. MCP's auto-started daemon does not
+enable this protection, and the flag is serve-only. Only explicitly granted
+Automation targets may receive scripting actions: background Save (including
+hotkeys), Finder rename, browser Apple Events JavaScript and browser quit for
+JavaScript setup, and Safari select updates. Ungranted or unknown consent
+refuses immediately with `automation_consent_required`, naming the app and
+System Settings > Privacy & Security > Automation; no scripting action or
+keyboard fallback is sent. Grant consent with the user's authorization before
+retrying. This does not suppress Accessibility/Screen Recording onboarding or
+other unrelated OS prompts. By default, macOS may prompt for Automation
+consent on first use; unanswered prompts can recur.
+
**"Open \<app\>" in user speech means launch, not activate.**
`cua-driver launch_app` is the one correct path for process
startup: it's idempotent (no-op on a running app), returns the
@@ -514,6 +527,7 @@ starting point for new browser workflows.
| `AX action failed: ... returned -25200` (or -25205, -25206) | The app may have acted anyway: some AppKit controls return these after a press they performed | Re-read with `get_window_state` before retrying; a second press on a checkbox toggles it back. A radio button or checkbox whose AXValue settles on the pressed state is reported as performed, naming the error |
| `set_value refused (file_name_needs_rename)` | A file's name as Finder lists it: an AXValue write changes only the list, never the file | `click` the item, then with Finder frontmost send `press_key` return, `hotkey` cmd+a, `type_text` the full new name, `press_key` return, each with `scope:"desktop"`; re-read to confirm |
| `set_value refused (file_name_needs_rename)` | A file's name in Finder's Get Info window (AXIdentifier `Name`): an AXValue write changes only the field | foreground `click` at the field's centre in screenshot pixels (with its `capture_id`), then `hotkey` cmd+a, `type_text` the full new name with its extension, `press_key` return, each with `delivery_mode:"foreground"`; a changed extension asks for confirmation first; check the folder listing |
+| `automation_consent_required` | With `serve --no-automation-prompts`, Automation consent is not explicitly granted for the named app; no scripting action was sent | With the user's authorization, grant access in System Settings > Privacy & Security > Automation |
## Example end-to-end task (macOS)
diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json
index a8aadb7ce8..791732b6a5 100644
--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json
+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json
@@ -1101,7 +1101,7 @@
"read_only": false
},
{
- "description": "Press a key combination — e.g. `[\"cmd\", \"c\"]` for Copy, `[\"cmd\", \"shift\", \"4\"]` for screenshot selection. Follows the same `delivery_mode` ladder as click/type_text — it does NOT raise the window by default:\n• `background` (default): post the combo to the target pid WITHOUT fronting or raising it — uses the macOS 14+ auth-message envelope so Chromium/Electron accept it as trusted live input. With an AX target, focus that exact element first. No top-level focus steal. `window_id` here only targets the combo; it does not raise. Background key events never reach a native app's menus, so when the combo is a menu item's key equivalent (cmd+s, cmd+w, ...) and the app is not in front, that menu item runs through accessibility instead (a disabled Save is saved through the app's scripting interface and verified on disk); a menu item macOS keeps disabled in the background is refused with `background_unavailable`, and no keys are sent.\n• `foreground`: briefly front the window (NSMenu path, < 1 ms via SLPSSetFrontProcessWithOptions) so native menu key-equivalents (Cmd+Z, Cmd+W) dispatch, then restore the prior frontmost — the explicit escalation for menu-bar shortcuts on non-Chromium apps that ignore a background combo. With an AX target or x,y, the focused field receives the chord through the foreground HID queue (needed by native Chromium fields such as the omnibox). Requires window_id.\n\nA combo is never driver-verifiable (no read-back) → effect:\"unverifiable\"; confirm via screenshot. NOTE: a keyboard combo does NOT focus a text field — to type into a backgrounded Electron input, establish real renderer focus with a PIXEL click first, then `type_text`. If an app only accepts paste, call `clipboard_write`, then `clipboard_read` and verify its types (and text when applicable) before selecting or replacing editor content; only then send Cmd+V.\n\nRecognized modifiers: cmd/command, shift, option/alt, ctrl/control, fn. Non-modifier keys use the same vocabulary as `press_key`. Order: modifiers first, one non-modifier last.",
+ "description": "Press a key combination — e.g. `[\"cmd\", \"c\"]` for Copy, `[\"cmd\", \"shift\", \"4\"]` for screenshot selection. Follows the same `delivery_mode` ladder as click/type_text — it does NOT raise the window by default:\n• `background` (default): post the combo to the target pid WITHOUT fronting or raising it — uses the macOS 14+ auth-message envelope so Chromium/Electron accept it as trusted live input. With an AX target, focus that exact element first. No top-level focus steal. `window_id` here only targets the combo; it does not raise. Background key events never reach a native app's menus, so when the combo is a menu item's key equivalent (cmd+s, cmd+w, ...) and the app is not in front, that menu item runs through accessibility instead (a disabled Save is saved through the app's scripting interface and verified on disk); a menu item macOS keeps disabled in the background is refused with `background_unavailable`. With serve --no-automation-prompts, scripting without granted consent refuses with `automation_consent_required`, without keyboard fallback.\n• `foreground`: briefly front the window (NSMenu path, < 1 ms via SLPSSetFrontProcessWithOptions) so native menu key-equivalents (Cmd+Z, Cmd+W) dispatch, then restore the prior frontmost — the explicit escalation for menu-bar shortcuts on non-Chromium apps that ignore a background combo. With an AX target or x,y, the focused field receives the chord through the foreground HID queue (needed by native Chromium fields such as the omnibox). Requires window_id.\n\nA combo is never driver-verifiable (no read-back) → effect:\"unverifiable\"; confirm via screenshot. NOTE: a keyboard combo does NOT focus a text field — to type into a backgrounded Electron input, establish real renderer focus with a PIXEL click first, then `type_text`. If an app only accepts paste, call `clipboard_write`, then `clipboard_read` and verify its types (and text when applicable) before selecting or replacing editor content; only then send Cmd+V.\n\nRecognized modifiers: cmd/command, shift, option/alt, ctrl/control, fn. Non-modifier keys use the same vocabulary as `press_key`. Order: modifiers first, one non-modifier last.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -1207,7 +1207,7 @@
"read_only": false
},
{
- "description": "Set an element's value by `element_token`. A popup button / select dropdown: selects the menu item whose title or value matches `value` (case-insensitive). Safari `<select>` is set through the DOM; AppKit and Chromium popups list items only while open, so the menu is opened, the item pressed and the menu closed again (in the background the user's front window keeps key focus). An unknown value lists the options. Any other element: writes AXValue (sliders, steppers, date pickers, native text fields).\n\nA Finder file name cell (list or icon view, not being edited) is renamed through Finder's scripting interface with Finder left in the background, and the new name is read back from disk; the value is the full new name with its extension. macOS asks the user once to allow Cua Driver to control Finder. Finder's Get Info `Name` field is refused with `file_name_needs_rename`. For free-form text in web inputs use `type_text_chars`: WebKit ignores AXValue writes.",
+ "description": "Set an element's value by `element_token`. A popup button / select dropdown: selects the menu item whose title or value matches `value` (case-insensitive). Safari `<select>` is set through the DOM; AppKit and Chromium popups list items only while open, so the menu is opened, the item pressed and the menu closed again (in the background the user's front window keeps key focus). An unknown value lists the options. Any other element: writes AXValue (sliders, steppers, date pickers, native text fields).\n\nA Finder file name cell (list or icon view, not being edited) is renamed through Finder's scripting interface with Finder left in the background, and the new name is read back from disk; the value is the full new name with its extension. macOS may prompt for Automation consent; with serve --no-automation-prompts, ungranted consent refuses with automation_consent_required. Finder's Get Info `Name` field is refused with `file_name_needs_rename`. For free-form text in web inputs use `type_text_chars`: WebKit ignores AXValue writes.",
"destructive": true,
"idempotent": true,
"input_schema": {
diff --git a/scripts/docs-generators/cli-specs/cua-driver.json b/scripts/docs-generators/cli-specs/cua-driver.json
index ee9fafb46c..8a10196722 100644
--- a/scripts/docs-generators/cli-specs/cua-driver.json
+++ b/scripts/docs-generators/cli-specs/cua-driver.json
@@ -234,6 +234,12 @@
"name": "no-permissions-gate",
"short_name": null
},
+ {
+ "default_value": false,
+ "help": "Refuse scripting actions without granted macOS Automation consent.",
+ "name": "no-automation-prompts",
+ "short_name": null
+ },
{
"default_value": false,
"help": "Run embedded inside a host app: inherit the host's TCC grants, never prompt or relaunch. Also CUA_DRIVER_EMBEDDED=1.",