fix(cua-driver): background refusals recommend unavailable foreground on Hyprland
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 56/100
- Issue type
- Bug
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- rust
- Domain
- backend-api-design, desktop
Research direction
Read libs/cua-driver/rust/crates/platform-linux/src/tools/press_key.rs and trace the refusal paths into platform-linux/src/input/delivery.rs, cua-driver-core/src/delivery.rs, and cua-driver-core/src/recovery_hint.rs. Check how Hyprland plugin availability is determined in platform-linux/src/wayland/hyprland_input.rs; then compare background refusal guidance when the plugin is absent with foreground guidance when a supported route exists. Done means the unavailable case no longer recommends foreground retry while valid consent conditioned recovery guidance remains.
Written by the indexing model from the issue text.
Description
Summary
On a native Hyprland session without the optional input plugin, a window-targeted background key refusal recommends foreground delivery even though that retry immediately refuses because the plugin is unavailable. This sends agents through a recovery step that cannot work in the current configuration, and can prompt unnecessary requests for permission to bring the window forward.
Primary area
Cua Driver
Steps to reproduce
These are the supplied runtime case, corroborated by tracing the same branches in the current source; the current release binary was not rerun.
- Use a Hyprland Wayland session without the Cua input plugin, with
CUA_DRIVER_RS_ENABLE_WAYLAND=1. LeaveCUA_DRIVER_EXPERIMENTAL_HYPRLAND_INPUTandCUA_INJECT_SOCKETunset so neither the experimental input protocol nor a nested compositor substitutes another route. - Open a small native PyGObject GTK 3 window with an entry containing
abc, leaving the window on a hidden workspace. Launch it withenv -u NO_AT_BRIDGEif necessary so its accessibility tree is available. Through an authorized Driver session, uselist_windowsandget_window_stateto obtain and read its actualpidandwindow_id. - Call
press_keywith thatsession,pid,window_id, andkey:"x", omittingdelivery_mode, element tokens, and coordinates. Observe the background refusal and foreground recommendation. The supplied MCP run also observed this withhotkeyandkeys:["ctrl","a"]. - Repeat the same
press_keycall withdelivery_mode:"foreground". Observe the plugin-unavailable refusal instead of the promised recovery.
Expected behavior
Recovery advice should name only routes supported in the current situation. When foreground input is unavailable because the Hyprland plugin is absent, the background refusal should explain that limitation rather than recommend an immediate foreground retry. Keep the action refused and preserve the user's focus; this report does not ask to add a new input backend or bypass authorization.
Actual behavior
The supplied CLI run exited 1 on each call. Selected fields from the background result:
{
"code": "background_unavailable",
"detail": "the requested target has no focus-free input backend; the remaining input route can only deliver to the globally focused widget",
"escalation": {
"reason": "background input is unavailable on this surface; retry this action with delivery_mode:\"foreground\".",
"recommended": "foreground"
},
"suggestion": "Retry this action with delivery_mode:\"foreground\"."
}
The MCP result was isError:true; its final recovery hint also advised Retry with delivery_mode:"foreground" only if the user allows the window to come forward. The foreground CLI result contained:
{
"code": "foreground_unavailable",
"reason": "unsupported_operation",
"detail": "production Hyprland input plugin is unavailable",
"effect": "refused"
}
The MCP retry likewise returned isError:true with foreground_unavailable (unsupported_operation): production Hyprland input plugin is unavailable. The supplied verification recorded no focus or workspace change and the entry still contained abc.
Runtime or environment
- Supplied executed baseline: checksum-verified Linux x86_64 Cua Driver 0.49.11, Omarchy/Arch Linux, kernel 7.2.15, Hyprland 0.56.2 on Wayland, native PyGObject GTK 3 fixture;
hyprctl plugin listreturnedno plugins loaded. - Current default branch inspected in a fresh clone:
mainat3f1661d00f382145720dea568ccde58b993fc0f0. - Latest published non-nightly Driver release inspected:
cua-driver-rs-v0.52.3, release targete7d713b28f7a8f7102cf7b15f567efb46f300beb. The relevant Linux key routing, refusal builder, shared escalation builder, and recovery-hint files have no differences from the inspected default branch. Current-source verification was static; no current binary runtime reproduction is claimed.
Evidence
- Expected source: The Recovery hints contract states that every hint names only routes supported in that situation and explains when nothing will work.
- Failure source: Supplied saved CLI/MCP transcripts, excerpted above, plus the current-source reachability trace below.
- Evidence provenance: supplied
- Local verification: static-proof
- Reproduction completeness: complete
The executed background/foreground refusal pair came from the supplied saved verification run; the current branch and release-tag comparison were independently inspected. Runtime reproduction was not run for either current artifact. The concrete static trigger is a previously read native GTK window on opted-in Hyprland, no input-plugin socket, no experimental protocol, no nested injection, and a window-targeted press_key with a valid single key.
For that trigger, platform-linux/src/tools/press_key.rs:212-299 skips isolated input because hyprland_input::enabled() is false, then returns a background refusal through the GTK guard or unavailable_wayland_focused_input_background. Both paths use platform-linux/src/input/delivery.rs:149-168, which unconditionally promises a foreground retry. cua-driver-core/src/delivery.rs:118-140 unconditionally sets escalation.recommended:"foreground", and cua-driver-core/src/recovery_hint.rs:872-954 adds the generic foreground advice. All paths are relative to libs/cua-driver/rust/crates/.
On the foreground retry, the background guards are skipped. platform-linux/src/tools/impl_.rs:3066-3070 selects the Hyprland foreground branch based on delivery mode and compositor; focus_hyprland_foreground at :3623-3635 then checks the same plugin availability and returns the observed refusal before activation. platform-linux/src/wayland/hyprland_input.rs:244-260 defines availability from the opted-in session, selected protocol, and owned input sockets. The failure is the recovery recommendation, not the intentional refusal to inject without a supported backend.
Restoration check
Repeat the window-targeted background key call with the plugin unavailable. It must still refuse without changing focus, workspace, or entry contents, but its structured escalation, suggestion, and MCP text/hint must no longer recommend an immediate foreground retry that the same configuration cannot execute. As a control, when a supported foreground route is available, legitimate foreground recovery guidance should remain available under its existing consent condition.
Workaround and additional context
Treat this key step as blocked rather than following the foreground recommendation. Element actions and menu/browser routes may serve other tasks, but were not verified as equivalents for this arbitrary keypress. No new input capability is requested.
References
- https://github.com/trycua/cua/issues/2617 — closed guidance work established direct foreground retries instead of persistent activation; the remaining case here is when foreground itself is unavailable.
- https://github.com/trycua/cua/issues/6711 — related refusal sequence on generic wlroots/labwc, but that report seeks foreground input support there; this report concerns incorrect recovery guidance on plugin-less Hyprland.
Submission checks
- I searched for duplicate issues and active pull requests.
- This issue describes a single problem.
- I removed credentials, private data, sensitive screenshots, and vulnerability details from this public report.
Triage assessment
- Impact level: P2
- Assessment status: provisional
- Impact basis: The saved runtime case and unchanged current routing show unusable recovery advice for affected Hyprland key calls. Wasted retries and unnecessary foreground-consent requests are consequential for agents; aggregate frequency and automation impact have not been measured.
- Workaround status: available
- Workaround basis: An agent can recognize the missing-plugin condition and report the key step as blocked without retrying or disturbing the user. This avoids the misleading recovery step; it does not provide otherwise unavailable key delivery.
- Dominant language
- Rust
- Stars
- 32.3k
- Forks
- 2.4k
- Avg merge
- 4h 47m
- Merged PRs (30d)
- 711
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from trycua/cua
-
Difficulty 1/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 86/100
Maintainers usually reply within 1 day
Similar issues
-
app-request
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
flatpark/flatpark#1423 · 1 comment ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
helix-editor/termina#35 ·
-
Difficulty 1/5 Under an hour Newbie friendliness 75/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 77/100
Maintainers usually reply within 5 days
-
Add coverage reportsOpentype:ci
Difficulty 2/5 1-3 hours Newbie friendliness 68/100