feat(cua-driver): embedded mode — inherit host TCC grants, never prompt

Adds explicit embedded mode (CUA_DRIVER_EMBEDDED=1 / --embedded
[--host-bundle-id <id>]) so a host app (e.g. OpenClaw) can embed the
driver as a direct child and have macOS attribute Accessibility +
Screen Recording to the host it already trusted — one grant, one
Settings entry, no com.trycua.driver prompts.

In embedded mode the driver:
- skips the responsibility-disclaim re-exec (stays in the host's chain)
- skips the daemon auto-relaunch via the CuaDriver.app bundle
- opts out of the startup permissions gate and never calls
  request_accessibility / request_screen_recording (check_permissions
  ignores prompt=true)
- reports check_permissions source.attribution = "host" with the
  advisory host bundle id, keeping the live SCShareableContent probe

Fail-closed property preserved: the caller-controlled env var only ever
downgrades attribution (host, never driver-daemon); daemon attribution
stays keyed on the non-spoofable bundle-path signal. Standalone
behavior is unchanged when the flag is off.

Ships Skills/cua-driver/EMBEDDING.md (integration guide +
troubleshooting) and examples/embedded-host-macos/ (signed AppKit
reference host + one-grant demo script).

Author: injaneity

docs/content/docs/reference/cua-driver/cli-reference.mdx

@@ -71,13 +71,15 @@ On macOS, shell-spawned MCP processes can auto-launch and proxy through a CuaDri
 | Name | Type | Default | Description |
 | ---- | ---- | ------- | ----------- |
 | `--socket` | String | — | Override the daemon socket or named-pipe path used by the proxy fallback. |
+| `--host-bundle-id` | String | — | Advisory host bundle id label echoed in check_permissions output (embedded mode). |
 
 **Flags:**
 
 | Name | Description |
 | ---- | ----------- |
 | `--no-daemon-relaunch` | Stay in-process instead of proxying through a daemon. |
 | `--claude-code-computer-use-compat` | Expose the Claude Code computer-use compatibility screenshot surface. |
+| `--embedded` | Run embedded inside a host app: inherit the host's TCC grants, never prompt or relaunch. Also CUA_DRIVER_EMBEDDED=1. |
 
 ### `cua-driver serve`
 
@@ -91,12 +93,14 @@ The daemon owns per-process state such as element-index caches, recording state,
 | ---- | ---- | ------- | ----------- |
 | `--socket` | String | — | Override the daemon socket or named-pipe path. |
 | `--pid-file` | String | — | Override the pid-file path on Unix targets. |
+| `--host-bundle-id` | String | — | Advisory host bundle id label echoed in check_permissions output (embedded mode). |
 
 **Flags:**
 
 | Name | Description |
 | ---- | ----------- |
 | `--no-permissions-gate` | Skip the macOS first-launch permissions gate. |
+| `--embedded` | Run embedded inside a host app: inherit the host's TCC grants, never prompt or relaunch. Also CUA_DRIVER_EMBEDDED=1. |
 
 ### `cua-driver stop`
 

libs/cua-driver/rust/Skills/cua-driver/EMBEDDING.md

@@ -19,6 +19,11 @@ platform: no focus steal, no cursor warp.
 - `LINUX.md` — Linux carve-out (X11 background input via AT-SPI +
   XSendEvent, recording, Wayland opt-in/preview). Read this when
   driving on Linux.
+- `EMBEDDING.md` — embedding cua-driver inside another macOS app
+  (agent harness) so the driver inherits the host's Accessibility +
+  Screen Recording grants with zero extra prompts. Read this when
+  integrating the driver into your own app rather than running it
+  standalone.
 
 ## What the skill covers
 

libs/cua-driver/rust/Skills/cua-driver/README.md

@@ -12,6 +12,26 @@
 
 pub const RESPONSIBILITY_DISCLAIMED_ENV: &str = "CUA_DRIVER_RS_RESPONSIBILITY_DISCLAIMED";
 
+/// Embedded mode (`CUA_DRIVER_EMBEDDED=1` / `--embedded`): the driver runs
+/// as a direct child of a host app and stays in its TCC responsibility
+/// chain — no disclaim re-exec, no daemon relaunch, no permission prompts.
+/// See `Skills/cua-driver/EMBEDDING.md`.
+///
+/// Caller-controlled, which is safe only because embedded mode strictly
+/// REMOVES capability claims; it must never feed into the `driver-daemon`
+/// attribution decision (`permission_source` in platform-macos).
+pub const EMBEDDED_ENV: &str = "CUA_DRIVER_EMBEDDED";
+
+/// Advisory label for the embedding host's bundle id, echoed in
+/// `check_permissions` output. NOT a trust signal — trust comes from the
+/// OS responsibility chain.
+pub const HOST_BUNDLE_ID_ENV: &str = "CUA_DRIVER_HOST_BUNDLE_ID";
+
+/// Only the exact value `1` counts — fail-safe for anything else.
+pub fn embedded_mode() -> bool {
+    std::env::var_os(EMBEDDED_ENV).is_some_and(|v| v == "1")
+}
+
 pub mod capture_mode;
 pub mod cdp;
 pub mod element_cache;

libs/cua-driver/rust/crates/cua-driver-core/src/lib.rs

@@ -140,6 +140,7 @@ const VALUE_FLAGS: &[&str] = &[
     "--cursor-icon", "--cursor-id", "--cursor-palette", "--cursor-shape",
     "--glide-ms", "--dwell-ms", "--idle-hide-ms",
     "--screenshot-out-file", "--client", "--socket", "--pid-file", "--type",
+    "--host-bundle-id",
     // Experimental PiP preview — value flag for the optional geometry
     // override (--experimental-pip itself is a bare flag and doesn't
     // need to be listed here).
@@ -201,6 +202,10 @@ pub fn parse_command() -> Command {
         println!("mcp options (macOS):");
         println!("  --no-daemon-relaunch    Stay in-process; skip auto-launching the CuaDriver daemon.");
         println!("                          Also: CUA_DRIVER_RS_MCP_NO_RELAUNCH=1");
+        println!("  --embedded              Run embedded inside a host app (also: CUA_DRIVER_EMBEDDED=1).");
+        println!("                          Inherits the host's TCC grants; never prompts or relaunches.");
+        println!("                          See Skills/cua-driver/EMBEDDING.md.");
+        println!("  --host-bundle-id <id>   Advisory host bundle id label for check_permissions output.");
         println!("  --socket <path>         Override the daemon UDS path used by the proxy fallback.");
         println!("  --claude-code-computer-use-compat");
         println!("                          Select the Claude Code computer-use compat surface.");
@@ -254,6 +259,16 @@ pub fn parse_command() -> Command {
     let mcp_client = flag_value(&args, "--client");
     let socket = flag_value(&args, "--socket");
 
+    // `--embedded` / `--host-bundle-id` export to the environment rather
+    // than threading through `Command`: all consumers read
+    // `cua_driver_core::embedded_mode()` and children inherit the mode.
+    if args.iter().any(|a| a == "--embedded") {
+        std::env::set_var(cua_driver_core::EMBEDDED_ENV, "1");
+    }
+    if let Some(id) = flag_value(&args, "--host-bundle-id") {
+        std::env::set_var(cua_driver_core::HOST_BUNDLE_ID_ENV, id);
+    }
+
     // Strip cursor-overlay flags (and their values) to expose the subcommand.
     let mut positionals: Vec<&str> = Vec::new();
     let mut i = 0;
@@ -540,6 +555,12 @@ pub fn run_describe(registry: &ToolRegistry, name: &str) {
 #[cfg(target_os = "macos")]
 pub fn should_use_daemon_proxy(no_daemon_relaunch: bool) -> bool {
     use crate::bundle::{is_env_truthy, is_executable_inside_cuadriver_app, parent_is_not_launchd};
+    // Embedded mode stays in-process: relaunching via `open -a CuaDriver`
+    // would leave the host's TCC responsibility chain and could prompt
+    // for com.trycua.driver.
+    if cua_driver_core::embedded_mode() {
+        return false;
+    }
     if no_daemon_relaunch {
         return false;
     }
@@ -590,6 +611,10 @@ pub fn should_use_daemon_proxy(no_daemon_relaunch: bool) -> bool {
 #[cfg(not(target_os = "macos"))]
 pub fn should_use_daemon_proxy(no_daemon_relaunch: bool) -> bool {
     use crate::bundle::is_env_truthy;
+    // Same rule as macOS: an embedded driver answers in-process.
+    if cua_driver_core::embedded_mode() {
+        return false;
+    }
     if no_daemon_relaunch {
         return false;
     }
@@ -846,14 +871,18 @@ pub fn build_manifest() -> serde_json::Value {
               "args": [
                   { "name": "--no-daemon-relaunch", "type": "flag", "description": "Skip the bundle-based TCC auto-relaunch and stay in-process." },
                   { "name": "--socket", "type": "string", "description": "Override the daemon proxy UDS path." },
-                  { "name": "--claude-code-computer-use-compat", "type": "flag", "description": "Select the Claude Code computer-use compat tool surface." }
+                  { "name": "--claude-code-computer-use-compat", "type": "flag", "description": "Select the Claude Code computer-use compat tool 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." }
               ] },
             { "name": "serve",
               "description": "Run the long-lived daemon — backs the proxy/auto-relaunch path on macOS and the autostart Session 1+ daemon on Windows.",
               "args": [
                   { "name": "--socket", "type": "string", "description": "Override the listen socket path." },
                   { "name": "--no-permissions-gate", "type": "flag", "description": "Skip the macOS TCC first-launch gate." },
-                  { "name": "--claude-code-computer-use-compat", "type": "flag", "description": "Forwarded by the MCP proxy when the client asked for the compat surface." }
+                  { "name": "--claude-code-computer-use-compat", "type": "flag", "description": "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." }
               ] },
             { "name": "stop",
               "description": "Stop a running daemon by sending it a shutdown request.",
@@ -2019,11 +2048,13 @@ fn cli_docs_json() -> serde_json::Value {
                 "discussion": "On macOS, shell-spawned MCP processes can auto-launch and proxy through a CuaDriver.app daemon so TCC grants attach to the bundle. On Windows and Linux, MCP proxies through an already-running daemon when one is listening.",
                 "arguments": no_args,
                 "options": [
-                    {"name":"socket","short_name":null,"help":"Override the daemon socket or named-pipe path used by the proxy fallback.","type":"String","default_value":null,"is_optional":true}
+                    {"name":"socket","short_name":null,"help":"Override the daemon socket or named-pipe path used by the proxy fallback.","type":"String","default_value":null,"is_optional":true},
+                    {"name":"host-bundle-id","short_name":null,"help":"Advisory host bundle id label echoed in check_permissions output (embedded mode).","type":"String","default_value":null,"is_optional":true}
                 ],
                 "flags": [
                     {"name":"no-daemon-relaunch","short_name":null,"help":"Stay in-process instead of proxying through a daemon.","default_value":false},
-                    {"name":"claude-code-computer-use-compat","short_name":null,"help":"Expose the Claude Code computer-use compatibility screenshot surface.","default_value":false}
+                    {"name":"claude-code-computer-use-compat","short_name":null,"help":"Expose the Claude Code computer-use compatibility screenshot surface.","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}
                 ],
                 "subcommands": no_subcommands
             },
@@ -2067,10 +2098,12 @@ fn cli_docs_json() -> serde_json::Value {
                 "arguments": no_args,
                 "options": [
                     {"name":"socket","short_name":null,"help":"Override the daemon socket or named-pipe path.","type":"String","default_value":null,"is_optional":true},
-                    {"name":"pid-file","short_name":null,"help":"Override the pid-file path on Unix targets.","type":"String","default_value":null,"is_optional":true}
+                    {"name":"pid-file","short_name":null,"help":"Override the pid-file path on Unix targets.","type":"String","default_value":null,"is_optional":true},
+                    {"name":"host-bundle-id","short_name":null,"help":"Advisory host bundle id label echoed in check_permissions output (embedded mode).","type":"String","default_value":null,"is_optional":true}
                 ],
                 "flags": [
-                    {"name":"no-permissions-gate","short_name":null,"help":"Skip the macOS first-launch permissions gate.","default_value":false}
+                    {"name":"no-permissions-gate","short_name":null,"help":"Skip the macOS first-launch permissions gate.","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}
                 ],
                 "subcommands": no_subcommands
             },

libs/cua-driver/rust/crates/cua-driver/src/cli.rs

@@ -17,12 +17,22 @@ pub fn already_disclaimed() -> bool {
     std::env::var_os(cua_driver_core::RESPONSIBILITY_DISCLAIMED_ENV).is_some()
 }
 
+/// Split out from [`reexec_disclaimed_if_needed`] so the decision is
+/// testable without spawning. Embedded mode must skip the disclaim:
+/// disclaiming would make the driver its own responsible process and
+/// break TCC inheritance from the host.
+#[cfg(target_os = "macos")]
+fn should_skip_disclaim(embedded: bool, already_disclaimed: bool, inside_bundle: bool) -> bool {
+    embedded || already_disclaimed || inside_bundle
+}
+
 #[cfg(target_os = "macos")]
 pub fn reexec_disclaimed_if_needed() {
-    if already_disclaimed() {
-        return;
-    }
-    if crate::bundle::is_executable_inside_cuadriver_app() {
+    if should_skip_disclaim(
+        cua_driver_core::embedded_mode(),
+        already_disclaimed(),
+        crate::bundle::is_executable_inside_cuadriver_app(),
+    ) {
         return;
     }
 
@@ -164,6 +174,15 @@ pub fn reexec_disclaimed_if_needed() {}
 mod tests {
     use super::*;
 
+    #[test]
+    fn embedded_mode_skips_disclaim_reexec() {
+        assert!(should_skip_disclaim(true, false, false));
+        // A bare standalone binary must still disclaim.
+        assert!(!should_skip_disclaim(false, false, false));
+        assert!(should_skip_disclaim(false, true, false));
+        assert!(should_skip_disclaim(false, false, true));
+    }
+
     #[test]
     fn already_disclaimed_reflects_env_var() {
         let name = cua_driver_core::RESPONSIBILITY_DISCLAIMED_ENV;

libs/cua-driver/rust/crates/cua-driver/src/responsibility.rs

@@ -165,9 +165,11 @@ impl Default for GateOpts {
 impl GateOpts {
     /// Construct from the standard env-var
     /// (`CUA_DRIVER_RS_PERMISSIONS_GATE` set to `0` / `false` / `no` /
-    /// `off`, case-insensitive, disables the gate) and an explicit
-    /// `--no-permissions-gate` flag.  Either signal is sufficient to opt
-    /// out.
+    /// `off`, case-insensitive, disables the gate), an explicit
+    /// `--no-permissions-gate` flag, and embedded mode
+    /// (`CUA_DRIVER_EMBEDDED=1`).  Any signal is sufficient to opt out.
+    /// Embedded mode opts out because the host app owns the grant flow;
+    /// the driver must never raise its own prompts.
     pub fn from_env_and_flag(no_gate_flag: bool) -> Self {
         // Match the standard list of "off" sentinels case-insensitively so
         // CI scripts can use any of `0`, `false`, `no`, `off`, `FALSE`,
@@ -181,7 +183,7 @@ impl GateOpts {
             })
             .unwrap_or(false);
         Self {
-            opt_out: no_gate_flag || env_disabled,
+            opt_out: no_gate_flag || env_disabled || cua_driver_core::embedded_mode(),
             ..Self::default()
         }
     }
@@ -595,22 +597,11 @@ fn fmt_missing(missing: &[MissingPermission]) -> String {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use std::sync::{Mutex, OnceLock};
-
-    /// Serializes every test that mutates `CUA_DRIVER_RS_PERMISSIONS_GATE`.
-    /// `cargo test` runs tests in parallel by default and `std::env::set_var`
-    /// / `remove_var` touch a process-global table — without this lock the
-    /// env-var tests race and produce flaky failures.
-    static TEST_ENV_MUTEX: OnceLock<Mutex<()>> = OnceLock::new();
 
+    /// Crate-wide env-var test lock — `from_env_and_flag` reads
+    /// `CUA_DRIVER_EMBEDDED`, which the `check_permissions` tests mutate.
     fn env_lock() -> std::sync::MutexGuard<'static, ()> {
-        // `lock()` can only fail if a previous holder panicked.  Recover the
-        // guard and keep going — the env var will be re-set/cleared by this
-        // test anyway, so a poisoned mutex carries no stale invariant.
-        TEST_ENV_MUTEX
-            .get_or_init(|| Mutex::new(()))
-            .lock()
-            .unwrap_or_else(|e| e.into_inner())
+        crate::permissions::test_env_lock()
     }
 
     #[test]
@@ -652,10 +643,23 @@ mod tests {
     fn neither_flag_nor_env_does_not_opt_out() {
         let _guard = env_lock();
         std::env::remove_var("CUA_DRIVER_RS_PERMISSIONS_GATE");
+        std::env::remove_var(cua_driver_core::EMBEDDED_ENV);
         let opts = GateOpts::from_env_and_flag(false);
         assert!(!opts.opt_out);
     }
 
+    #[test]
+    fn embedded_mode_opts_out_of_gate() {
+        let _guard = env_lock();
+        std::env::remove_var("CUA_DRIVER_RS_PERMISSIONS_GATE");
+        std::env::set_var(cua_driver_core::EMBEDDED_ENV, "1");
+        assert!(GateOpts::from_env_and_flag(false).opt_out);
+        // Only the exact value "1" enables embedded mode.
+        std::env::set_var(cua_driver_core::EMBEDDED_ENV, "true");
+        assert!(!GateOpts::from_env_and_flag(false).opt_out);
+        std::env::remove_var(cua_driver_core::EMBEDDED_ENV);
+    }
+
     #[test]
     fn env_var_truthy_values_do_not_opt_out() {
         let _guard = env_lock();

libs/cua-driver/rust/crates/platform-macos/src/permissions/gate.rs

@@ -24,3 +24,15 @@ pub mod panel;
 
 pub use status::{PermissionsStatus, current_status};
 pub use gate::{GateOpts, MissingPermission, run_if_needed};
+
+/// Crate-wide lock serializing tests that mutate process-global env vars.
+/// Per-module locks are not enough: `gate` and `check_permissions` tests
+/// share `CUA_DRIVER_EMBEDDED`.
+#[cfg(test)]
+pub(crate) fn test_env_lock() -> std::sync::MutexGuard<'static, ()> {
+    static LOCK: std::sync::OnceLock<std::sync::Mutex<()>> = std::sync::OnceLock::new();
+    // Poison carries no stale invariant (tests restore the vars they touch).
+    LOCK.get_or_init(|| std::sync::Mutex::new(()))
+        .lock()
+        .unwrap_or_else(|e| e.into_inner())
+}