Expand background control capabilities toward Codex parity

[TheGuyWithoutH]

Summary

Push more actions into true background-first behavior while keeping the current frontmost app unchanged whenever macOS allows it.

Why

One of the biggest UX differences versus bundled Codex Computer Use is how much work appears to happen in the background without visibly stealing focus.

Scope

• Audit all tools and classify them as background-safe, activation-fallback, or activation-required.
• Expand AX-first behavior beyond the current set_value and some perform_secondary_action cases.
• Investigate whether more pointer or menu actions can target background apps safely.
• Keep explicit focus restore for actions that still require activation.
• Document which tools are truly background-safe and which are best-effort only.

Acceptance Criteria

• More actions succeed while leaving the original frontmost app unchanged.
• Behavior categories are documented for contributors and users.
• Remaining activation-required paths are explicit in the code and docs.

[TheGuyWithoutH]

Progress update: Stage Manager thumbnail handling is now implemented for state capture. The helper detects likely side thumbnails, uses WindowManager AX actions (AXAddToStage with AXPress fallback), restores the previous frontmost app, and captures the materialized window via ScreenCaptureKit without moving the hardware cursor. Keeping this issue open because broader background-control parity still remains for pointer/keyboard/menu actions, and the Stage Manager path should be hardened across macOS versions.

[m13v]

went down this exact classification on a macOS agent last year. AXPress and AXShowMenu work 100% background on native Cocoa, but Chromium filters AXAction when the window isn't key so every Electron app silently fails. CGEventPostToPid sidesteps activation on native but drops on SwiftUI List and WKWebView. pointer synthesis always steals focus since CGEventPost walks the HID tap. we settled on AXSetAttribute for text and fell back to CGEvent only when both AX paths returned nil. documented each tool by which failure mode it hits.

[TheGuyWithoutH]

thanks that's really helpful @m13v!! do you have a repo where you have this documentation?