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): make macOS permission consent explicit and durable (#2407)

Francesco Bonacci7ac41be61e6b
diff --git a/.github/scripts/tests/test_cua_driver_release_wiring.py b/.github/scripts/tests/test_cua_driver_release_wiring.py
index 0a45efb436..037fc52a82 100644
--- a/.github/scripts/tests/test_cua_driver_release_wiring.py
+++ b/.github/scripts/tests/test_cua_driver_release_wiring.py
@@ -34,6 +34,22 @@ class TestCuaDriverReleaseWiring(unittest.TestCase):
self.assertIn("os: ubuntu-24.04-arm", workflow)
self.assertIn("arch: arm64", workflow)
+ def test_macos_bundle_explains_screen_capture_and_automation_prompts(self) -> None:
+ plist = self.read(
+ "libs/cua-driver/rust/scripts/CuaDriverBundle/Contents/Info.plist"
+ )
+
+ self.assertIn("NSScreenCaptureUsageDescription", plist)
+ self.assertIn("NSAppleEventsUsageDescription", plist)
+ self.assertNotIn("NSMicrophoneUsageDescription", plist)
+
+ cli = self.read("libs/cua-driver/rust/crates/cua-driver/src/cli.rs")
+ self.assertIn("missing from Screen & System Audio Recording", cli)
+ self.assertIn("add {app_path}", cli)
+
+ limits = self.read("docs/content/docs/reference/cua-driver/limits.mdx")
+ self.assertIn("without this grant it returns the tree only (no PNG)", limits)
+
def test_release_please_owns_driver_and_lume(self) -> None:
config = self.read("release-please-config.json")
workflow = self.read(".github/workflows/release-please.yml")
@@ -202,6 +218,15 @@ class TestCuaDriverReleaseWiring(unittest.TestCase):
self.assertNotIn(".cua-driver-rs", installer)
self.assertNotIn('rm -rf "$HOME/.cua-driver"', installer)
+ def test_local_install_hints_name_the_local_permission_identity(self) -> None:
+ installer = self.read("libs/cua-driver/scripts/_install-local-rust.sh")
+ shared_hints = self.read("libs/cua-driver/scripts/post-install-hints.txt")
+
+ self.assertIn('permission prompts say \\"Cua Driver Local\\"', installer)
+ self.assertNotIn('permission prompts say \\"Cua Driver\\"', installer)
+ self.assertIn("launches the installed", shared_hints)
+ self.assertNotIn("launches CuaDriver", shared_hints)
+
def test_local_macos_signing_uses_an_unambiguous_identity_hash(self) -> None:
installer = self.read("libs/cua-driver/scripts/_install-local-rust.sh")
diff --git a/docs/content/docs/how-to-guides/driver/run-in-macos-lume-vm.mdx b/docs/content/docs/how-to-guides/driver/run-in-macos-lume-vm.mdx
index 5e7c549aaa..d24faabafb 100644
--- a/docs/content/docs/how-to-guides/driver/run-in-macos-lume-vm.mdx
+++ b/docs/content/docs/how-to-guides/driver/run-in-macos-lume-vm.mdx
@@ -144,14 +144,27 @@ with open('/tmp/cua-driver-permissions.json') as source:
assert status['accessibility'] is True
assert status['screen_recording'] is True
-assert status['screen_recording_capturable'] is True
+assert status['screen_recording_capturable'] is None
+assert status['direct_capture_status'] == 'not_checked'
assert status['source']['attribution'] == 'driver-daemon'
PY
```
-Exercise both the accessibility and capture paths:
+Run the prompt-capable live probe explicitly, then exercise both the
+accessibility and capture paths:
```bash
+/Users/lume/.local/bin/cua-driver call check_permissions '{"prompt":true}' \
+ > /tmp/cua-driver-permissions-live.json
+/usr/bin/python3 - <<'PY'
+import json
+
+with open('/tmp/cua-driver-permissions-live.json') as source:
+ status = json.load(source)['structuredContent']
+
+assert status['screen_recording_capturable'] is True
+assert status['direct_capture_status'] == 'ready'
+PY
/Users/lume/.local/bin/cua-driver call get_accessibility_tree '{}'
/Users/lume/.local/bin/cua-driver call set_config '{"capture_scope":"desktop"}'
/Users/lume/.local/bin/cua-driver call get_desktop_state '{}' \
diff --git a/docs/content/docs/how-to-guides/driver/run-tests-in-macos-lume-vm.mdx b/docs/content/docs/how-to-guides/driver/run-tests-in-macos-lume-vm.mdx
index 31b68e9431..dc3e0558df 100644
--- a/docs/content/docs/how-to-guides/driver/run-tests-in-macos-lume-vm.mdx
+++ b/docs/content/docs/how-to-guides/driver/run-tests-in-macos-lume-vm.mdx
@@ -207,8 +207,7 @@ DRIVER=/Users/lume/.local/bin/cua-driver
Choose **Allow** for:
- Terminal controlling System Events;
-- CuaDriver controlling System Events; and
-- CuaDriver capturing screen and audio without the system picker.
+- CuaDriver direct screen capture without the system picker.
These are normal macOS consent flows. Do not edit `TCC.db`. Rerun all three
probes and require them to finish without another prompt.
@@ -219,10 +218,16 @@ Verify the app-owned grants, signature, capture result, and SIP state:
"$DRIVER" permissions status --json | jq -e '
.accessibility == true
and .screen_recording == true
- and .screen_recording_capturable == true
+ and .screen_recording_capturable == null
+ and .direct_capture_status == "not_checked"
and .source.attribution == "driver-daemon"
'
+"$DRIVER" call check_permissions '{"prompt":true}' | jq -e '
+ .structuredContent.screen_recording_capturable == true
+ and .structuredContent.direct_capture_status == "ready"
+'
+
jq -e '
.screenshot_mime_type == "image/png"
and .screenshot_width > 0
diff --git a/docs/content/docs/how-to-guides/driver/troubleshoot-stale-macos-permissions.mdx b/docs/content/docs/how-to-guides/driver/troubleshoot-stale-macos-permissions.mdx
index aacf256f33..9a691424fd 100644
--- a/docs/content/docs/how-to-guides/driver/troubleshoot-stale-macos-permissions.mdx
+++ b/docs/content/docs/how-to-guides/driver/troubleshoot-stale-macos-permissions.mdx
@@ -105,8 +105,9 @@ cua-driver permissions grant
In **System Settings → Privacy & Security**, enable CuaDriver under both
**Accessibility** and **Screen Recording**. If macOS asks you to quit and reopen
the app after granting Screen Recording, do so, then run the command above
-again. Automation consent is requested later when a driver action needs to
-control another app.
+again. If CuaDriver is missing from **Screen & System Audio Recording**, click
+**+** and add `/Applications/CuaDriver.app` before enabling it. Automation
+consent is requested later when a driver action needs to control another app.
## Verify the repaired grants
@@ -117,8 +118,11 @@ cua-driver permissions status --json
```
The result should report `accessibility: true`, `screen_recording: true`, and
-`source.attribution: "driver-daemon"`. The permissions status should also
-report `screen_recording_capturable: true`.
+`source.attribution: "driver-daemon"`. Because status is read-only, it should
+report `screen_recording_capturable: null` and
+`direct_capture_status: "not_checked"`. Run `cua-driver permissions grant` to
+request and verify direct ScreenCaptureKit access explicitly; do not use a
+read-only diagnostic as a prompt-capable probe.
If either permission remains false, run `cua-driver diagnose` again and confirm
that the reported executable and bundle are the installed
diff --git a/docs/content/docs/reference/cua-driver/embedding.mdx b/docs/content/docs/reference/cua-driver/embedding.mdx
index f32e51804d..9424eb658b 100644
--- a/docs/content/docs/reference/cua-driver/embedding.mdx
+++ b/docs/content/docs/reference/cua-driver/embedding.mdx
@@ -68,7 +68,8 @@ Call the `check_permissions` MCP tool after the proxy connects to the embedded d
{
"accessibility": true,
"screen_recording": true,
- "screen_recording_capturable": true,
+ "screen_recording_capturable": null,
+ "direct_capture_status": "not_checked",
"source": {
"attribution": "host",
"host_bundle_id": "com.yourco.yourapp",
@@ -77,6 +78,11 @@ Call the `check_permissions` MCP tool after the proxy connects to the embedded d
}
```
+Embedded mode never lets the driver raise consent dialogs, so this read-only
+call deliberately does not run the prompt-capable ScreenCaptureKit probe. The
+host should present its own consent context and verify pixels with an explicit
+screenshot/capture operation.
+
If `source.attribution` is not `host` on macOS, embedded mode is not active in the daemon handling your MCP calls. Check that `CUA_DRIVER_EMBEDDED=1` is passed to the `serve` child, that the daemon was spawned directly, and that the proxy uses the intended private socket.
`source.attribution: "host"` means the daemon is running in embedded mode; it does not prove that your GUI app is the responsible process. If a gateway or Node process spawned the daemon, the reported grant state still belongs to that spawner.
diff --git a/docs/content/docs/reference/cua-driver/macos-permissions.mdx b/docs/content/docs/reference/cua-driver/macos-permissions.mdx
index ca4c320017..f1303b5f37 100644
--- a/docs/content/docs/reference/cua-driver/macos-permissions.mdx
+++ b/docs/content/docs/reference/cua-driver/macos-permissions.mdx
@@ -20,11 +20,30 @@ cua-driver permissions grant # launch CuaDriver via LaunchServices so the pro
| -------- | ------------------------------- |
| `--json` | Machine-readable status output. |
-The JSON status also includes `screen_recording_capturable`, a live capture
-probe attributed to the CuaDriver daemon. macOS Tahoe can present separate
-consent dialogs when CuaDriver controls System Events or requests direct screen
-and audio capture without the system picker. The Automation grant is outside
-the `permissions status` payload.
+The JSON status distinguishes the ordinary Screen Recording preflight from
+direct ScreenCaptureKit readiness. Because macOS Tahoe can show a separate
+private-window-picker bypass dialog when ScreenCaptureKit is queried,
+`permissions status` never runs that probe: it returns
+`screen_recording_capturable: null` and
+`direct_capture_status: "not_checked"`. This preserves the command's read-only,
+no-prompt contract.
+
+`permissions grant` explains the additional dialog before deliberately
+triggering it, then requires a successful live capture probe. macOS describes
+the combined privacy category as screen and system-audio recording even though
+Cua Driver's current ScreenCaptureKit recorder captures screen video only and
+does not enable audio capture. The consent is limited to macOS capture; it does
+not authorize browser-profile access, browser data, or CDP attachment.
+
+If the installed app is not listed under **Screen & System Audio Recording**
+after the prompt, click **+**, add `/Applications/CuaDriver.app` (or
+`/Applications/CuaDriverLocal.app` for a local build), enable it, and run
+`permissions grant` again. This recovers a stale or missing macOS registration
+without granting the terminal or another build identity.
+
+Automation prompts can also appear when an explicitly requested browser or app
+operation uses Apple Events. Those grants are target-specific and remain
+outside the core `permissions status` payload.
For the complete prompt sequence in a Lume guest, see [Run Cua Driver in a
macOS Lume VM](/how-to-guides/driver/run-in-macos-lume-vm). Source-built test
diff --git a/docs/content/docs/reference/cua-driver/mcp-tools.mdx b/docs/content/docs/reference/cua-driver/mcp-tools.mdx
index 5fd340059f..5bc2e5ded3 100644
--- a/docs/content/docs/reference/cua-driver/mcp-tools.mdx
+++ b/docs/content/docs/reference/cua-driver/mcp-tools.mdx
@@ -678,7 +678,7 @@ All parameters are optional; omit any you do not want to change.
Report TCC permission status for Accessibility and Screen Recording. By default also raises the system permission dialogs for any missing grants — Apple's request APIs are no-ops when the grant is already active, so this is safe to call repeatedly. Pass &#123;"prompt": false&#125; for a purely read-only status check.
-Returns: `accessibility` + `screen_recording` (booleans from the TCC preflight APIs), `screen_recording_capturable` (a live ScreenCaptureKit probe — if it disagrees with `screen_recording`, the preflight grant belongs to a different process), and `source` (which TCC identity the booleans reflect: the CuaDriver daemon vs the launching terminal/IDE). macOS attributes grants to the responsible process, so a standalone call from a terminal reports the terminal's grants, not the driver's.
+Returns: `accessibility` + `screen_recording` (booleans from the TCC preflight APIs), `screen_recording_capturable` (a live ScreenCaptureKit probe when `prompt` is true; null on read-only calls), `direct_capture_status` (`ready`, `unavailable`, `blocked_by_screen_recording`, or `not_checked`), and `source` (which TCC identity the booleans reflect: the CuaDriver daemon vs the launching terminal/IDE). macOS attributes grants to the responsible process, so a standalone call from a terminal reports the terminal's grants, not the driver's. The prompt-capable ScreenCaptureKit probe never runs when `prompt` is false.
**Arguments:**
@@ -686,7 +686,7 @@ Returns: `accessibility` + `screen_recording` (booleans from the TCC preflight A
### `health_report`
-Single-call end-to-end driver diagnostics. Designed to let downstream consumers ship one stable call instead of stitching together check_permissions, doctor, version, bundle attribution, and a screenshot probe. cua-driver owns the health model; consumers stay thin.
+Single-call end-to-end driver diagnostics. Designed to let downstream consumers ship one stable call instead of stitching together check_permissions, doctor, version, bundle attribution, and platform capability status. On macOS, prompt-capable direct capture is deliberately skipped; use `cua-driver permissions grant` to verify it explicitly. cua-driver owns the health model; consumers stay thin.
Input — all optional:
&#123;
diff --git a/libs/cua-driver/rust/Skills/cua-driver/EMBEDDING.md b/libs/cua-driver/rust/Skills/cua-driver/EMBEDDING.md
index d884fcffb3..589a598a47 100644
--- a/libs/cua-driver/rust/Skills/cua-driver/EMBEDDING.md
+++ b/libs/cua-driver/rust/Skills/cua-driver/EMBEDDING.md
@@ -164,7 +164,8 @@ a dialog (the `prompt` argument is ignored) and returns:
{
"accessibility": true,
"screen_recording": true,
- "screen_recording_capturable": true,
+ "screen_recording_capturable": null,
+ "direct_capture_status": "not_checked",
"source": {
"attribution": "host",
"host_bundle_id": "com.yourco.yourapp",
@@ -181,10 +182,11 @@ a dialog (the `prompt` argument is ignored) and returns:
- `accessibility` / `screen_recording` — the live TCC state *of your app's
grant*, answered from inside the driver process (which shares your
identity). If both are true, it is safe to drive the desktop.
-- `screen_recording_capturable` — a live ScreenCaptureKit probe
- (`SCShareableContent`), the authoritative signal. If it disagrees with
- `screen_recording`, the preflight boolean is stale or belongs to a
- different identity — see troubleshooting.
+- `screen_recording_capturable` / `direct_capture_status` — embedded
+ `check_permissions` is read-only and never runs Tahoe's prompt-capable
+ ScreenCaptureKit probe, so these are `null` / `not_checked`. The host owns
+ the consent UX and should verify pixels with an explicit screenshot or
+ capture operation after explaining the prompt.
- `source.attribution` values:
- `host` — embedded mode; booleans reflect the host's grant. What you
should always see when embedding.
@@ -414,15 +416,13 @@ that the proxy uses the host's private socket. To see exactly which identity mac
run: `log stream --debug --predicate 'subsystem == "com.apple.TCC" AND
eventMessage BEGINSWITH "AttributionChain"'` and trigger the action again.
-**"Screenshots come back black (or `screen_recording: true` but
-`screen_recording_capturable: false`)."**
-The preflight boolean and the live probe disagree, which means the Screen
-Recording grant TCC found does not belong to the driver's current
-responsible identity. Either the host never actually got the grant (check
-System Settings), the grant was reset (`tccutil reset ScreenCapture`) after
-the app cached a `true`, or the driver escaped the host's chain (see the
-previous item). Restart the driver child after any grant change — TCC
-answers are cached per process.
+**"Screenshots come back black even though `screen_recording: true`."**
+The read-only permission check cannot verify direct ScreenCaptureKit access
+without risking a system dialog. Exercise an explicit screenshot only after
+the host has explained and requested consent. If that fails, the grant may not
+belong to the driver's current responsible identity, may have been reset, or
+the driver may have escaped the host's chain (see the previous item). Restart
+the driver child after any grant change — TCC answers are cached per process.
**"The AX tree comes back empty / clicks do nothing."**
`AXIsProcessTrusted()` is false for the effective identity. The host hasn't
diff --git a/libs/cua-driver/rust/Skills/cua-driver/MACOS.md b/libs/cua-driver/rust/Skills/cua-driver/MACOS.md
index 06ed894644..0806245d51 100644
--- a/libs/cua-driver/rust/Skills/cua-driver/MACOS.md
+++ b/libs/cua-driver/rust/Skills/cua-driver/MACOS.md
@@ -222,20 +222,31 @@ editor state.
1. `cua-driver` is on `$PATH` (`which cua-driver`). If not, point the
user at `scripts/install-local.sh` and stop.
-2. Run `cua-driver check_permissions` (with the daemon up — see step 3).
- The default behavior also raises the system permission dialogs for
- any missing grants, so the user can grant on the spot. If either
- grant still reads `false` after that (user dismissed the dialog),
- tell them to open System Settings → Privacy & Security and grant
- Accessibility and Screen Recording to `CuaDriver.app`, then stop.
- Pass `'{"prompt":false}'` for a purely read-only status check that
- won't steal focus.
-3. Start the daemon with `open -n -g -a CuaDriver --args serve` (the
+2. Start the daemon with `open -n -g -a CuaDriver --args serve` (the
recommended form — goes through LaunchServices so TCC attributes
the process to CuaDriver.app). `cua-driver serve &` also works;
the CLI auto-relaunches through `open -n -g -a CuaDriver` when it
detects a wrong-TCC context (any IDE-spawned shell: Claude Code,
Cursor, VS Code, Conductor). Verify with `cua-driver status`.
+3. Run `cua-driver permissions status --json`. This
+ path is read-only: it checks Accessibility and Screen Recording but
+ deliberately does not run Tahoe's prompt-capable direct-capture probe.
+ Therefore `screen_recording_capturable` is `null` and
+ `direct_capture_status` is `"not_checked"` until the explicit grant flow.
+ - If Accessibility is `false`, stop. AX reads and actions cannot work;
+ tell the user to run `cua-driver permissions grant` and approve it.
+ - If Screen Recording is `false`, continue only when the task can be
+ completed and verified from the AX tree. Call `get_window_state` with
+ `include_screenshot:false` and use element-indexed AX actions. Do not use
+ screenshots, pixel coordinates, or pixel-based verification.
+ - If the task materially needs pixels, stop and ask the user to run
+ `cua-driver permissions grant`. That command explains and deliberately
+ triggers the additional private-window-picker bypass dialog before
+ verifying live capture. macOS mentions screen and audio in the combined
+ consent, although Cua Driver's current recorder does not enable audio.
+ If the installed app is absent from **Screen & System Audio Recording**,
+ the user should click **+**, add `/Applications/CuaDriver.app` (or
+ `/Applications/CuaDriverLocal.app`), enable it, and rerun the command.
## Resolve target pid — always via `launch_app`
@@ -299,9 +310,10 @@ macOS-specific residuals worth knowing (the rest of the capture/dispatch/
addressing params are a shared cross-platform contract — see `SKILL.md` →
*Cross-platform parameter contract*):
-- **`check_permissions.prompt` is macOS-only.** It raises the TCC
- Accessibility / Screen-Recording dialogs; pass `{"prompt":false}` for a
- read-only status check. There is no Windows/Linux equivalent — TCC is a
+- **`check_permissions.prompt` is macOS-only.** `true` raises the TCC
+ Accessibility / Screen-Recording dialogs and runs the prompt-capable direct
+ ScreenCaptureKit probe. `false` is read-only and returns direct-capture
+ readiness as not checked. There is no Windows/Linux equivalent — TCC is a
macOS construct, so the param is intentionally absent from the shared
contract.
- **`session` always worked on macOS;** the cross-platform change is that
@@ -514,7 +526,7 @@ starting point for new browser workflows.
|---|---|---|
| macOS system-alert beep on `press_key` with no visible change | Target window is minimized; Return / Space / Tab commits don't establish real renderer focus on minimized windows | AX-click a clickable equivalent (Go button, Submit button, checkbox) instead of pressing the key; see "Keyboard commits on minimized windows" under the Browser section |
| `Accessibility permission not granted` | TCC not granted | Stop; tell user to grant in System Settings |
-| `Screen Recording permission not granted` | TCC not granted for capture | Affects `screenshot` and `get_window_state` (which always captures). Grant in System Settings — the driver can't operate without it |
+| `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-indexed actions; otherwise stop and ask the user to run `cua-driver permissions grant` |
## Example end-to-end task (macOS)
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/health_report.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/health_report.rs
index 761bc1ad1d..96ff3b054e 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/health_report.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/health_report.rs
@@ -343,7 +343,7 @@ fn def() -> &'static ToolDef {
// The description is part of the public contract — downstream
// consumers depend on it spelling out `schema_version="1"` and the per-
// platform check matrix. A test pins this commitment.
- description: r#"Single-call end-to-end driver diagnostics. Designed to let downstream consumers ship one stable call instead of stitching together check_permissions, doctor, version, bundle attribution, and a screenshot probe. cua-driver owns the health model; consumers stay thin.
+ description: r#"Single-call end-to-end driver diagnostics. Designed to let downstream consumers ship one stable call instead of stitching together check_permissions, doctor, version, bundle attribution, and platform capability status. On macOS, prompt-capable direct capture is deliberately skipped; use `cua-driver permissions grant` to verify it explicitly. cua-driver owns the health model; consumers stay thin.
Input — all optional:
{
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 8b9605de55..1704cda078 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/cli.rs
@@ -424,9 +424,10 @@ pub fn parse_command() -> Command {
println!(" Answers via a running daemon, so the result carries the CuaDriver");
println!(" identity (com.trycua.driver). If no daemon is running it reports");
println!(" `unknown` rather than your terminal's grants. Add --json for the payload.");
- println!(" cua-driver permissions grant Launch CuaDriver via LaunchServices so the permission dialog attributes");
- println!(" to com.trycua.driver (not your terminal), wait for the grant, then");
- println!(" confirm the driver's own status. This is the correct way to grant.");
+ println!(" cua-driver permissions grant Launch CuaDriver via LaunchServices so dialogs attribute to the app,");
+ println!(" explain and request Accessibility, Screen Recording, and Tahoe's");
+ println!(" direct-capture consent, then verify live capture. This is the correct");
+ println!(" way to grant; the read-only status command never triggers that probe.");
println!();
println!("Updating cua-driver:");
println!(" cua-driver check-update Ask GitHub whether a newer release is available. Read-only.");
@@ -2389,7 +2390,9 @@ fn run_permissions_status(json: bool) {
let b = |k: &str| structured.get(k).and_then(|v| v.as_bool()).unwrap_or(false);
let ax = b("accessibility");
let sr = b("screen_recording");
- let cap = b("screen_recording_capturable");
+ let cap = structured
+ .get("screen_recording_capturable")
+ .and_then(|v| v.as_bool());
let attribution = structured
.get("source")
.and_then(|s| s.get("attribution"))
@@ -2404,11 +2407,19 @@ fn run_permissions_status(json: bool) {
"Screen Recording: {}",
if sr { "✅ granted" } else { "❌ not granted" }
);
- if sr && !cap {
- println!(
- " ⚠️ preflight reports granted, but a live capture probe failed — the grant \
- likely belongs to another process, not this one."
- );
+ match cap {
+ Some(true) => println!("Direct Capture: ✅ ready"),
+ Some(false) => {
+ println!("Direct Capture: ❌ unavailable");
+ if sr {
+ println!(
+ " ⚠️ preflight reports granted, but the explicit live capture probe failed."
+ );
+ }
+ }
+ None => println!(
+ "Direct Capture: ❓ not checked (status is read-only; run `{cli_name} permissions grant`)"
+ ),
}
println!("Source: {attribution}");
if !(ax && sr) {
@@ -2416,6 +2427,24 @@ fn run_permissions_status(json: bool) {
}
}
+fn permission_flag(structured: &serde_json::Value, key: &str) -> bool {
+ structured
+ .get(key)
+ .and_then(|value| value.as_bool())
+ .unwrap_or(false)
+}
+
+fn permission_grant_is_ready(structured: &serde_json::Value) -> bool {
+ permission_flag(structured, "accessibility")
+ && permission_flag(structured, "screen_recording")
+ && permission_flag(structured, "screen_recording_capturable")
+}
+
+fn permission_grant_needs_direct_capture(structured: &serde_json::Value) -> bool {
+ permission_flag(structured, "screen_recording")
+ && !permission_flag(structured, "screen_recording_capturable")
+}
+
/// Launch CuaDriver via LaunchServices so the permission prompt attributes to
/// com.trycua.driver, wait (user-paced) for the daemon to come up — its socket
/// only appears once the permissions gate passes, i.e. the grant was given —
@@ -2425,6 +2454,8 @@ fn run_permissions_grant() {
{
let cli_name = crate::bundle::cli_name();
let app_name = crate::bundle::app_name();
+ let app_path = crate::bundle::app_bundle_path();
+ let bundle_id = crate::bundle::bundle_id();
let socket = crate::serve::default_socket_path();
if crate::serve::is_daemon_listening(&socket) {
println!("{app_name} daemon already running — checking its permissions…");
@@ -2446,8 +2477,10 @@ fn run_permissions_grant() {
}
// Since #1761 the daemon binds its socket IMMEDIATELY — before the
// permissions gate completes — so the first `check_permissions`
- // query returns "pending" while the grant is still missing. Poll
- // the daemon until both grants flip true (success) or we time out.
+ // query returns "pending" while the grant is still missing. First poll
+ // only the non-prompting TCC preflight booleans. Direct
+ // ScreenCaptureKit access has its own Tahoe consent and is requested
+ // explicitly below, after we explain the system dialog.
//
// The gate re-execs the daemon (~every 25s) to pick up an
// Accessibility grant — `AXIsProcessTrusted` is cached per process
@@ -2471,14 +2504,8 @@ fn run_permissions_grant() {
.and_then(|r| r.result)
.and_then(|res| res.get("structuredContent").cloned())
{
- ax = structured
- .get("accessibility")
- .and_then(|v| v.as_bool())
- .unwrap_or(false);
- sr = structured
- .get("screen_recording")
- .and_then(|v| v.as_bool())
- .unwrap_or(false);
+ ax = permission_flag(&structured, "accessibility");
+ sr = permission_flag(&structured, "screen_recording");
if ax && sr {
break;
}
@@ -2490,9 +2517,7 @@ fn run_permissions_grant() {
}
std::thread::sleep(std::time::Duration::from_secs(2));
}
- if ax && sr {
- println!("\n✅ CuaDriver has Accessibility + Screen Recording. You're set.");
- } else {
+ if !(ax && sr) {
let missing = match (ax, sr) {
(false, false) => "Accessibility + Screen Recording",
(false, true) => "Accessibility",
@@ -2501,10 +2526,81 @@ fn run_permissions_grant() {
};
println!("\n⚠️ Timed out waiting on: {missing}.");
println!(
- "Approve CuaDriver for \u{201c}Cua Driver\u{201d} in System Settings \u{2192} \
- Privacy & Security, then re-run `cua-driver permissions grant`."
+ "Approve {app_name} in System Settings \u{2192} Privacy & Security, then \
+ re-run `{cli_name} permissions grant`."
+ );
+ if !sr {
+ println!(
+ "If {app_name} is missing from Screen & System Audio Recording, click +, \
+ add {app_path}, enable it, then re-run the command."
+ );
+ }
+ process::exit(1);
+ }
+
+ println!("\nAccessibility and Screen Recording are granted.");
+ println!(
+ "macOS may now ask {app_name} to bypass the system private window picker and \
+ directly access your screen and audio. This is the expected consent for exact \
+ screenshots and recordings without a picker. Cua Driver's current recorder \
+ captures screen video only; it does not enable system-audio capture. This \
+ consent does not authorize browser profiles, browser data, or CDP attachment."
+ );
+ println!("Choose Allow to request and verify direct capture now…");
+
+ let direct_req = crate::serve::DaemonRequest {
+ method: "call".into(),
+ name: Some("check_permissions".into()),
+ args: Some(serde_json::json!({ "prompt": true })),
+ session_id: None,
+ observation_origin: Some(crate::serve::ToolObservationOrigin::Direct),
+ };
+ let direct_deadline = std::time::Instant::now() + std::time::Duration::from_secs(180);
+ let mut direct_status = None;
+ loop {
+ if let Some(structured) = crate::serve::send_request(&socket, &direct_req)
+ .ok()
+ .filter(|r| r.ok)
+ .and_then(|r| r.result)
+ .and_then(|res| res.get("structuredContent").cloned())
+ {
+ direct_status = Some(structured.clone());
+ if permission_grant_is_ready(&structured) {
+ println!(
+ "\n✅ {app_name} has Accessibility, Screen Recording, and direct capture access. You're set."
+ );
+ return;
+ }
+ // The explicit probe returned a real negative result (the
+ // user denied the consent or ScreenCaptureKit failed). Do not
+ // hammer the user with the same system dialog in a poll loop.
+ break;
+ }
+ if std::time::Instant::now() >= direct_deadline {
+ break;
+ }
+ std::thread::sleep(std::time::Duration::from_secs(2));
+ }
+
+ eprintln!("\n❌ {app_name} still cannot use direct ScreenCaptureKit capture.");
+ if direct_status
+ .as_ref()
+ .is_some_and(permission_grant_needs_direct_capture)
+ {
+ eprintln!(
+ "Screen Recording is granted, but the private-window-picker bypass consent \
+ was denied or the live probe failed."
);
}
+ eprintln!(
+ "In System Settings \u{2192} Privacy & Security \u{2192} Screen & System Audio Recording, \
+ allow {app_name} ({bundle_id}), then re-run `{cli_name} permissions grant`."
+ );
+ eprintln!("If it is already allowed, reset the stale decision and retry:");
+ eprintln!(" tccutil reset ScreenCapture {bundle_id}");
+ eprintln!(" {cli_name} stop");
+ eprintln!(" {cli_name} permissions grant");
+ process::exit(1);
}
#[cfg(not(target_os = "macos"))]
{
@@ -2999,13 +3095,19 @@ fn diagnose_tcc_section() -> String {
};
let ax = display("accessibility");
let sr = display("screen_recording");
+ let direct = status
+ .as_ref()
+ .and_then(|value| value.get("direct_capture_status"))
+ .and_then(serde_json::Value::as_str)
+ .unwrap_or("unknown (daemon unavailable)");
format!(
"## tcc probes (daemon)\n\
accessibility (AXIsProcessTrusted): {ax}\n\
- screen recording (SCShareableContent): {sr}\n\n\
- if the UI disagrees with these booleans the daemon is fine —\n\
- the issue is elsewhere (wrong bundle granted, stale cdhash, etc)."
+ screen recording (CGPreflightScreenCaptureAccess): {sr}\n\
+ direct capture (prompt-capable probe): {direct}\n\n\
+ diagnose is read-only and never runs the direct ScreenCaptureKit probe;\n\
+ use `cua-driver permissions grant` to request and verify it explicitly."
)
}
@@ -3515,6 +3617,40 @@ mod tests {
);
}
+ #[test]
+ fn permission_grant_requires_live_capture_probe() {
+ let stale = serde_json::json!({
+ "accessibility": true,
+ "screen_recording": true,
+ "screen_recording_capturable": false
+ });
+
+ assert!(!permission_grant_is_ready(&stale));
+ assert!(permission_grant_needs_direct_capture(&stale));
+ }
+
+ #[test]
+ fn permission_grant_accepts_all_live_checks() {
+ let ready = serde_json::json!({
+ "accessibility": true,
+ "screen_recording": true,
+ "screen_recording_capturable": true
+ });
+
+ assert!(permission_grant_is_ready(&ready));
+ assert!(!permission_grant_needs_direct_capture(&ready));
+ }
+
+ #[test]
+ fn permission_grant_missing_live_probe_is_not_ready() {
+ let incomplete = serde_json::json!({
+ "accessibility": true,
+ "screen_recording": true
+ });
+
+ assert!(!permission_grant_is_ready(&incomplete));
+ }
+
#[test]
fn sanitize_tool_name_passes_through_canonical_names() {
assert_eq!(sanitize_tool_name("click"), "click");
diff --git a/libs/cua-driver/rust/crates/cua-driver/src/skills.rs b/libs/cua-driver/rust/crates/cua-driver/src/skills.rs
index 3f58ff9936..d1a1e23227 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/skills.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/skills.rs
@@ -821,6 +821,25 @@ mod tests {
);
}
+ #[test]
+ fn macos_skill_keeps_ax_only_and_non_prompting_permission_guidance() {
+ let crate_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+ let macos = std::fs::read_to_string(crate_dir.join("../../Skills/cua-driver/MACOS.md"))
+ .expect("canonical macOS skill must be readable");
+
+ for required in [
+ "screen_recording_capturable` is `null",
+ "direct_capture_status` is `\"not_checked\"",
+ "include_screenshot:false",
+ "element-indexed AX actions",
+ ] {
+ assert!(
+ macos.contains(required),
+ "macOS skill lost required permission guidance: {required}"
+ );
+ }
+ }
+
#[test]
fn extract_flat_tarball_v_0_2_20_plus() {
// Post-fix shape: one wrapper dir, files directly under it.
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/check_permissions.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/check_permissions.rs
index 7820e2a3c2..031c4b48c4 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/check_permissions.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/check_permissions.rs
@@ -12,6 +12,16 @@ use crate::permissions::status::{
pub struct CheckPermissionsTool;
+fn driver_bundle_id_for_executable(executable: &str) -> Option<&'static str> {
+ if executable.contains("/CuaDriverLocal.app/Contents/MacOS/") {
+ Some("com.trycua.driver.local")
+ } else if executable.contains("/CuaDriver.app/Contents/MacOS/") {
+ Some("com.trycua.driver")
+ } else {
+ None
+ }
+}
+
/// (A) Real ScreenCaptureKit capability probe — what THIS process can
/// actually capture right now, independent of the CGPreflight cache.
///
@@ -28,6 +38,10 @@ fn screen_recording_capturable() -> bool {
.unwrap_or(false)
}
+fn should_probe_direct_capture(should_prompt: bool, screen_recording: bool) -> bool {
+ should_prompt && screen_recording
+}
+
/// (B) Which TCC identity the booleans in this response reflect.
///
/// macOS attributes Accessibility / Screen-Recording to the *responsible
@@ -77,24 +91,27 @@ fn permission_source() -> serde_json::Value {
// — outside the bundle — the env var must NOT grant daemon attribution, or
// a caller could pre-set it and spoof the TCC source. Fail closed to
// "caller" whenever the bundle signal is absent.
- let inside_bundle = exe.contains("/CuaDriver.app/Contents/MacOS/");
- let is_driver_daemon = inside_bundle && (ppid == 1 || disclaimed);
+ let driver_bundle_id = driver_bundle_id_for_executable(&exe);
+ let is_driver_daemon = driver_bundle_id.is_some() && (ppid == 1 || disclaimed);
let (attribution, note) = if is_driver_daemon {
(
"driver-daemon",
- "These booleans reflect the CuaDriver daemon's own TCC identity \
- (com.trycua.driver) because this process is its own responsible \
- process.",
+ format!(
+ "These booleans reflect the CuaDriver daemon's own TCC identity \
+ ({}) because this process is its own responsible process.",
+ driver_bundle_id.expect("driver daemon must have a bundle id")
+ ),
)
} else {
(
"caller",
"These booleans reflect the TCC identity of the app that launched \
- this process (e.g. your terminal/IDE), NOT the CuaDriver daemon \
- (com.trycua.driver). A standalone check can read `true` here while \
- `tccutil … com.trycua.driver` reports no record. To grant for the \
- driver, run `cua-driver permissions grant`.",
+ this process (e.g. your terminal/IDE), NOT an installed CuaDriver \
+ app bundle. A standalone check can read `true` here while the \
+ driver's bundle has no grant. To grant for the driver, run \
+ `cua-driver permissions grant`."
+ .to_owned(),
)
};
@@ -104,6 +121,7 @@ fn permission_source() -> serde_json::Value {
"responsible_ppid": ppid,
"executable": exe,
"disclaim_env": disclaimed,
+ "bundle_id": driver_bundle_id,
"note": note,
})
}
@@ -121,11 +139,13 @@ fn def() -> &'static ToolDef {
status check.\n\n\
Returns: `accessibility` + `screen_recording` (booleans from the TCC \
preflight APIs), `screen_recording_capturable` (a live ScreenCaptureKit \
- probe — if it disagrees with `screen_recording`, the preflight grant \
- belongs to a different process), and `source` (which TCC identity the \
+ probe when `prompt` is true; null on read-only calls), \
+ `direct_capture_status` (`ready`, `unavailable`, \
+ `blocked_by_screen_recording`, or `not_checked`), and `source` (which TCC identity the \
booleans reflect: the CuaDriver daemon vs the launching terminal/IDE). \
macOS attributes grants to the responsible process, so a standalone call \
- from a terminal reports the terminal's grants, not the driver's.".into(),
+ from a terminal reports the terminal's grants, not the driver's. The \
+ prompt-capable ScreenCaptureKit probe never runs when `prompt` is false.".into(),
input_schema: serde_json::json!({
"type": "object",
"properties": {
@@ -166,7 +186,23 @@ impl Tool for CheckPermissionsTool {
let accessibility = accessibility_granted();
let screen_recording = screen_recording_granted();
// (A) Authoritative live probe — see `screen_recording_capturable`.
- let screen_recording_capturable = screen_recording_capturable();
+ // SCShareableContent::get() can itself raise Tahoe's separate
+ // private-window-picker bypass consent. A status/read-only call must
+ // therefore never execute it. The explicit grant path opts in with
+ // `prompt:true`, explains the dialog first, and verifies the result.
+ let (screen_recording_capturable, direct_capture_status) = if !should_prompt {
+ (None, "not_checked")
+ } else if !screen_recording {
+ (None, "blocked_by_screen_recording")
+ } else if should_probe_direct_capture(should_prompt, screen_recording) {
+ let capturable = screen_recording_capturable();
+ (
+ Some(capturable),
+ if capturable { "ready" } else { "unavailable" },
+ )
+ } else {
+ unreachable!("all non-probing direct-capture states were handled")
+ };
// (B) Which identity the booleans above belong to.
let source = permission_source();
let is_caller = source.get("attribution").and_then(|v| v.as_str()) == Some("caller");
@@ -189,11 +225,17 @@ impl Tool for CheckPermissionsTool {
"{ax_prefix} Accessibility: {ax_state}.\n{sr_prefix} Screen Recording: {sr_state}."
);
// Flag a preflight/probe disagreement (the false-positive tell).
- if screen_recording && !screen_recording_capturable {
+ if screen_recording_capturable == Some(false) {
summary.push_str(
"\n⚠️ Screen Recording reads granted but a live capture probe failed — \
the grant likely belongs to a different process, not this one.",
);
+ } else if screen_recording_capturable.is_none() && !should_prompt {
+ summary.push_str(
+ "\nℹ️ Direct ScreenCaptureKit readiness was not probed because this is a \
+ read-only check. Run `cua-driver permissions grant` to request and \
+ verify direct capture explicitly.",
+ );
}
// Make the attribution explicit when answering for a host or caller
// (not the daemon).
@@ -215,6 +257,7 @@ impl Tool for CheckPermissionsTool {
"accessibility": accessibility,
"screen_recording": screen_recording,
"screen_recording_capturable": screen_recording_capturable,
+ "direct_capture_status": direct_capture_status,
"source": source,
}))
}
@@ -246,6 +289,34 @@ mod tests {
}
}
+ #[test]
+ fn recognizes_release_and_local_driver_bundles() {
+ assert_eq!(
+ driver_bundle_id_for_executable(
+ "/Applications/CuaDriver.app/Contents/MacOS/cua-driver"
+ ),
+ Some("com.trycua.driver")
+ );
+ assert_eq!(
+ driver_bundle_id_for_executable(
+ "/Applications/CuaDriverLocal.app/Contents/MacOS/cua-driver-local"
+ ),
+ Some("com.trycua.driver.local")
+ );
+ assert_eq!(
+ driver_bundle_id_for_executable("/Users/test/.local/bin/cua-driver-local"),
+ None
+ );
+ }
+
+ #[test]
+ fn read_only_checks_never_run_the_prompt_capable_direct_capture_probe() {
+ assert!(!should_probe_direct_capture(false, false));
+ assert!(!should_probe_direct_capture(false, true));
+ assert!(!should_probe_direct_capture(true, false));
+ assert!(should_probe_direct_capture(true, true));
+ }
+
#[test]
fn disclaim_env_var_alone_does_not_grant_daemon_attribution() {
// The disclaim env var is caller-controlled, so on its own it must not
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/health_report.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/health_report.rs
index a1dd789d0d..02a9208096 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/health_report.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/health_report.rs
@@ -57,7 +57,7 @@ impl HealthCheckProvider for MacosHealthProvider {
NAME_TCC_ACCESSIBILITY => check_tcc_accessibility(),
NAME_TCC_SCREEN_RECORDING => check_tcc_screen_recording(),
NAME_AX_CAPABILITY => check_ax_capability(),
- NAME_SCREEN_CAPTURE_CAPABILITY => check_screen_capture_capability().await,
+ NAME_SCREEN_CAPTURE_CAPABILITY => check_screen_capture_capability(),
// Defensive: the dispatcher only forwards names in
// `check_names()`, so this branch should be unreachable.
other => CheckEntry::skip(
@@ -203,51 +203,20 @@ fn check_ax_capability() -> CheckEntry {
)
}
-async fn check_screen_capture_capability() -> CheckEntry {
- // Live ScreenCaptureKit probe — same shape as `check_permissions`'s
- // `screen_recording_capturable`, but answer the consumer-facing
- // capability question and surface the display count.
- //
- // `SCShareableContent::get()` is a synchronous C call; wrap it in
- // spawn_blocking so the async runtime isn't held by a system call
- // that can take 10-100ms on first invocation.
- let result = tokio::task::spawn_blocking(probe_shareable_displays)
- .await
- .unwrap_or(Err("probe task panicked".to_owned()));
- match result {
- Ok(count) => CheckEntry::pass(
- NAME_SCREEN_CAPTURE_CAPABILITY,
- format!("ScreenCaptureKit reachable; {count} display(s) shareable."),
- )
- .with_data(CheckData {
- display_count: Some(count),
- ..Default::default()
- }),
- Err(detail) => CheckEntry::fail(
- NAME_SCREEN_CAPTURE_CAPABILITY,
- "ScreenCaptureKit probe failed.",
- "Confirm tcc_screen_recording is granted. If it is, this is an SCK regression — \
- set capture_mode to `ax` to skip screen capture entirely.",
- )
- .with_data(CheckData {
- error_detail: Some(detail),
- ..Default::default()
- }),
- }
+fn check_screen_capture_capability() -> CheckEntry {
+ // SCShareableContent::get() is not a read-only probe on recent macOS:
+ // Tahoe may display the separate private-window-picker bypass consent.
+ // `health_report` is declared read-only, so fail closed to an explicit
+ // unknown/skip state. `permissions grant` is the sole flow allowed to
+ // explain, request, and verify direct capture.
+ CheckEntry::skip(
+ NAME_SCREEN_CAPTURE_CAPABILITY,
+ "Direct ScreenCaptureKit readiness was not probed because health_report is read-only; run `cua-driver permissions grant` to request and verify it explicitly.",
+ )
}
// ── Helpers ──────────────────────────────────────────────────────────────────
-/// Live ScreenCaptureKit probe — enumerates shareable displays. Writes
-/// nothing to disk; we never start a stream. Returns display count on
-/// success, error string on failure.
-fn probe_shareable_displays() -> Result<u32, String> {
- use screencapturekit::prelude::SCShareableContent;
- let content =
- SCShareableContent::get().map_err(|e| format!("SCShareableContent::get: {e:?}"))?;
- Ok(content.displays().len() as u32)
-}
-
/// Read the running process's `CFBundleIdentifier` via CoreFoundation.
/// Returns `None` when the process has no associated bundle (e.g.
/// running the bare binary outside `CuaDriver.app`).
@@ -339,6 +308,13 @@ mod tests {
assert_eq!(entry.status, CheckStatus::Pass);
}
+ #[test]
+ fn screen_capture_capability_is_not_probed_by_read_only_health_report() {
+ let entry = check_screen_capture_capability();
+ assert_eq!(entry.status, CheckStatus::Skip);
+ assert!(entry.message.contains("permissions grant"));
+ }
+
#[test]
fn bundle_identity_in_test_host_fails_with_full_shape() {
// The Rust test binary runs outside CuaDriver.app, so its
diff --git a/libs/cua-driver/rust/scripts/CuaDriverBundle/Contents/Info.plist b/libs/cua-driver/rust/scripts/CuaDriverBundle/Contents/Info.plist
index 4536709215..a6f2cb05ad 100644
--- a/libs/cua-driver/rust/scripts/CuaDriverBundle/Contents/Info.plist
+++ b/libs/cua-driver/rust/scripts/CuaDriverBundle/Contents/Info.plist
@@ -71,6 +71,10 @@
<true/>
<key>NSHighResolutionCapable</key>
<true/>
+ <key>NSScreenCaptureUsageDescription</key>
+ <string>Cua Driver captures the screen so agents can see and interact with the interface you ask them to control.</string>
+ <key>NSAppleEventsUsageDescription</key>
+ <string>Cua Driver uses Automation only when a requested action needs to communicate with another app.</string>
<key>NSSupportsAutomaticTermination</key>
<true/>
</dict>
diff --git a/libs/cua-driver/scripts/_install-local-rust.sh b/libs/cua-driver/scripts/_install-local-rust.sh
index ea86198141..3cec6f105a 100755
--- a/libs/cua-driver/scripts/_install-local-rust.sh
+++ b/libs/cua-driver/scripts/_install-local-rust.sh
@@ -570,7 +570,7 @@ if [ "$INSTALL_AUTOSTART" != true ]; then
if [ "$OS" = "Darwin" ]; then
echo "Auto-start (recommended on macOS): re-run with --autostart to register a LaunchAgent."
echo " A launchd-started daemon is attributed to com.trycua.driver.local (not your terminal),"
- echo " so permission prompts say \"Cua Driver\" and grants stick — grant Accessibility +"
+ echo " so permission prompts say \"Cua Driver Local\" and grants stick — grant Accessibility +"
echo " Screen Recording once and every cua-driver-local call/mcp routes through it correctly."
echo " (Without it, a prompt raised from a terminal attributes to the terminal instead.)"
else
diff --git a/libs/cua-driver/scripts/post-install-hints.txt b/libs/cua-driver/scripts/post-install-hints.txt
index 1b4ad44ffa..b7e579d372 100644
--- a/libs/cua-driver/scripts/post-install-hints.txt
+++ b/libs/cua-driver/scripts/post-install-hints.txt
@@ -8,9 +8,9 @@ Next steps:
2. Grant permissions (macOS — Accessibility + Screen Recording):
{{BINARY}} permissions status # report status (read-only; tells you which
# identity the grants belong to)
- {{BINARY}} permissions grant # the correct way to grant — launches CuaDriver
- # so the dialog says "Cua Driver" and the grant
- # sticks to the driver, not your terminal.
+ {{BINARY}} permissions grant # the correct way to grant — launches the installed
+ # app so every dialog and Settings entry matches
+ # this driver identity, not your terminal.
# Tip: `--autostart` (above) keeps a launchd daemon
# running so you grant once and it persists.
diff --git a/libs/cua-driver/scripts/tests/test_uninstall_local.py b/libs/cua-driver/scripts/tests/test_uninstall_local.py
index d42282f4cf..296c179911 100644
--- a/libs/cua-driver/scripts/tests/test_uninstall_local.py
+++ b/libs/cua-driver/scripts/tests/test_uninstall_local.py
@@ -31,6 +31,12 @@ def test_unix_local_uninstall_removes_owned_links_and_preserves_release(tmp_path
local_marker = local_home / "packages/current/cua-driver-local"
local_marker.parent.mkdir(parents=True)
local_marker.write_text("local\n", encoding="utf-8")
+ for runtime_file in (
+ ".telemetry_identity.lock",
+ ".telemetry_lifecycle.lock",
+ ".telemetry_retry_after",
+ ):
+ (local_home / runtime_file).write_text("local runtime state\n", encoding="utf-8")
_executable(fake_bin / "uname", "printf 'Linux\\n'")
_executable(fake_bin / "pkill", "exit 0")
@@ -150,6 +156,13 @@ def test_local_uninstall_contract_is_explicit_on_both_platforms() -> None:
assert 'rm -rf "$HOME_DIR"' not in unix
assert "--validate-only" in unix
assert "$ValidateOnly" in windows
+ for token in (
+ ".telemetry_identity.lock",
+ ".telemetry_lifecycle.lock",
+ ".telemetry_retry_after",
+ ):
+ assert token in unix
+ assert token in windows
def test_unix_local_uninstall_rejects_release_home_override(tmp_path: Path) -> None:
diff --git a/libs/cua-driver/scripts/uninstall-local.ps1 b/libs/cua-driver/scripts/uninstall-local.ps1
index bb4b3ed042..c91a0b604b 100644
--- a/libs/cua-driver/scripts/uninstall-local.ps1
+++ b/libs/cua-driver/scripts/uninstall-local.ps1
@@ -156,7 +156,9 @@ if (Test-Path -LiteralPath $LocalHomeMarker) {
}
foreach ($file in @(
".installation_recorded", ".telemetry_enabled", ".telemetry_id",
- ".telemetry_install_channel", ".tcc-signing-identity", "config.json",
+ ".telemetry_identity.lock", ".telemetry_install_channel",
+ ".telemetry_lifecycle.lock", ".telemetry_retry_after",
+ ".tcc-signing-identity", "config.json",
"serve.err.log", "serve.out.log", "version_check.json"
)) {
$path = Join-Path $HomeDir $file
diff --git a/libs/cua-driver/scripts/uninstall-local.sh b/libs/cua-driver/scripts/uninstall-local.sh
index 410b49b363..c152ce9279 100755
--- a/libs/cua-driver/scripts/uninstall-local.sh
+++ b/libs/cua-driver/scripts/uninstall-local.sh
@@ -202,7 +202,10 @@ if [[ -e "$LOCAL_HOME_MARKER" || -L "$LOCAL_HOME_MARKER" ]]; then
"$HOME_DIR/.installation_recorded" \
"$HOME_DIR/.telemetry_enabled" \
"$HOME_DIR/.telemetry_id" \
+ "$HOME_DIR/.telemetry_identity.lock" \
"$HOME_DIR/.telemetry_install_channel" \
+ "$HOME_DIR/.telemetry_lifecycle.lock" \
+ "$HOME_DIR/.telemetry_retry_after" \
"$HOME_DIR/.tcc-signing-identity" \
"$HOME_DIR/config.json" \
"$HOME_DIR/serve.err.log" \
diff --git a/libs/cua-driver/tests/runners/macos-lume/README.md b/libs/cua-driver/tests/runners/macos-lume/README.md
index 37ce3304b3..7cae580b4b 100644
--- a/libs/cua-driver/tests/runners/macos-lume/README.md
+++ b/libs/cua-driver/tests/runners/macos-lume/README.md
@@ -171,7 +171,8 @@ remaining consent paths before freezing the seed:
osascript -e \
'tell application "System Events" to get name of first application process whose frontmost is true'
-# The installed app owns driver-side app enumeration.
+# The installed app owns driver-side app enumeration. This uses NSWorkspace and
+# must not require Automation access to System Events.
~/.local/bin/cua-driver-local list_apps '{}'
# A desktop screenshot triggers Tahoe's direct-capture/private-window prompt.
@@ -189,24 +190,34 @@ jq -e '
' /tmp/cua-driver-seed-desktop-state.json >/dev/null
```
-Choose Allow for both `Terminal` -> `System Events` and `CuaDriverLocal` ->
-`System Events`, and choose Allow on the CuaDriverLocal direct-capture prompt. These
-are normal macOS consent flows; do not edit `TCC.db`. Rerun the commands and
-require them to finish without another prompt. Then verify the daemon's own
-identity, live capture permission, stable signature, and SIP state:
+Choose Allow for `Terminal` -> `System Events` and on the CuaDriverLocal
+direct-capture prompt. CuaDriverLocal app enumeration must not ask for System
+Events. Target-specific Automation prompts may still appear later when a user
+explicitly requests an Apple Events-backed browser or app operation; do not
+pre-grant those in the seed. These are normal macOS consent flows; do not edit
+`TCC.db`. Rerun the commands and require them to finish without another prompt.
+Then verify the daemon's own
+identity and the read-only status contract before running the explicit live
+capture probe. The first command must not raise a dialog; the second is
+intentionally prompt-capable:
```bash
~/.local/bin/cua-driver-local permissions status --json | jq -e '
.accessibility == true
and .screen_recording == true
- and .screen_recording_capturable == true
+ and .screen_recording_capturable == null
+ and .direct_capture_status == "not_checked"
and .source.attribution == "driver-daemon"
'
+~/.local/bin/cua-driver-local call check_permissions '{"prompt":true}' | jq -e '
+ .structuredContent.screen_recording_capturable == true
+ and .structuredContent.direct_capture_status == "ready"
+'
codesign -d -r- /Applications/CuaDriverLocal.app 2>&1 | grep 'certificate leaf'
csrutil status
```
-All three commands must succeed, and `csrutil status` must report disabled.
+All four commands must succeed, and `csrutil status` must report disabled.
Stop the builder and clone it to a date/version-named private seed plus two
stopped backups:
@@ -229,8 +240,9 @@ granted and then rerun without prompts:
- `CuaDriverLocal.app`: Accessibility and Screen Recording
- Terminal controlling System Events
-- CuaDriverLocal controlling System Events
-- CuaDriverLocal direct screen and audio capture without the system picker
+- CuaDriverLocal direct screen capture without the system picker. macOS labels
+ this combined consent as screen and system-audio access even though Cua
+ Driver's current ScreenCaptureKit recorder does not enable audio capture.
Build a new seed instead of updating one in place.
diff --git a/libs/cua-driver/tests/runners/macos-lume/run-all.sh b/libs/cua-driver/tests/runners/macos-lume/run-all.sh
index 2aad4cfb8c..733524705e 100755
--- a/libs/cua-driver/tests/runners/macos-lume/run-all.sh
+++ b/libs/cua-driver/tests/runners/macos-lume/run-all.sh
@@ -154,7 +154,8 @@ for _ in 1 2 3 4 5 6 7 8 9 10; do
&& jq -e '
.accessibility == true
and .screen_recording == true
- and .screen_recording_capturable == true
+ and .screen_recording_capturable == null
+ and .direct_capture_status == "not_checked"
and .source.attribution == "driver-daemon"
' "${PERMISSIONS_FILE}" >/dev/null; then
PERMISSIONS_READY=1
@@ -168,9 +169,21 @@ if [[ "${PERMISSIONS_READY}" != 1 ]]; then
exit 1
fi
-echo "[AUTOMATION] Verifying the installed CuaDriver can query System Events"
+LIVE_PERMISSIONS_FILE="${ARTIFACT_DIR}/permissions-live-capture.json"
+if ! "${INSTALLED_BIN}" call check_permissions '{"prompt":true}' \
+ > "${LIVE_PERMISSIONS_FILE}" \
+ || ! jq -e '
+ .structuredContent.screen_recording_capturable == true
+ and .structuredContent.direct_capture_status == "ready"
+ ' "${LIVE_PERMISSIONS_FILE}" >/dev/null; then
+ cat "${LIVE_PERMISSIONS_FILE}" >&2 || true
+ echo "The cloned golden image does not have usable direct ScreenCaptureKit consent" >&2
+ exit 1
+fi
+
+echo "[APP DISCOVERY] Verifying the installed CuaDriver can enumerate apps"
if ! "${INSTALLED_BIN}" list_apps '{}' > "${ARTIFACT_DIR}/driver-list-apps.json"; then
- echo "CuaDriver cannot control System Events; rebuild the seed and grant the Automation prompt" >&2
+ echo "CuaDriver cannot enumerate applications" >&2
exit 2
fi