Accessibility Or Screen Recording Permission Missing

Symptom

a7y-cli doctor fails Phase 2 (macOS Permissions) with macos-accessibility and/or macos-screen-recording marked as not granted. Or, an agent calling accessibility_state / doctor_check_permissions sees "granted": false for Accessibility or ScreenRecording in the response.

Why

Autonomy needs two separate macOS TCC (Transparency, Consent, and Control) grants:

Accessibility — lets the AX backend read the accessibility tree and perform actions (AXIsProcessTrustedWithOptions).
Screen Recording — lets browser and visual-verification workflows capture the screen (CGPreflightScreenCaptureAccess).

Both checks are live probes, not cached state — doctor and the MCP tools ask macOS directly every time, so a stale grant from before a rebuild won’t show as passing.

Critically, the grant is attached to a specific app identity, not to Autonomy in the abstract:

If you’re running from source in a terminal, the grant belongs to your terminal app (Terminal.app, iTerm2, Warp, …) — the process actually calling the AX/screen APIs.
If you’re running the installed app, the grant belongs to autonomy (a7y).app.

Rebuilding an unsigned or re-signed bundle under a different path can silently lose a grant that looks like it “should” still be there, even though a normal reset (scripts/reset-tester-env.sh) never touches macOS permissions.

Screen Recording being denied does not block everything. AX-only form and document review can continue without it — only visual verification and browser capture workflows are blocked.

Fix

Open the relevant Privacy & Security pane


open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"

Or navigate manually: System Settings → Privacy & Security → Accessibility and System Settings → Privacy & Security → Screen Recording — labeled “Screen & System Audio Recording” on macOS 15 (Sequoia) and later.

Toggle the app on

Modern System Settings (macOS 13 Ventura and later) lists each app with a per-app toggle — there’s no ”+” button here. Find the app that needs the grant — your terminal app if you’re running from source, or autonomy (a7y).app if you’re running the installed bundle — and switch its toggle on. If the app isn’t in the list yet, it appears after it first requests the permission, alongside an “Open System Settings” prompt. Keep the same app identity across updates so macOS doesn’t drop trust.

Restart the process that needs the permission

Screen Recording requires quitting and reopening the app — the grant does not take effect until you do, and macOS itself will prompt you with a “Quit & Reopen” button after you toggle it on. Treat that as mandatory, not optional.

Accessibility usually takes effect for a process that’s already running without a restart. If the app still doesn’t detect the grant, relaunch it as a fallback — not because it’s always required.

Verify


a7y-cli doctor

Phase 2 should now show macos-accessibility and macos-screen-recording as granted. If you don’t have a shell handy, or you’re checking on behalf of a screen-off user, ask the agent to call the permission tool directly — it works even before the daemon is running:


a7y-cli tools accessibility-state --prompt

--prompt asks the platform helper to trigger the native permission prompt where supported. Re-run after granting to confirm permissions.accessibility and permissions.screenRecording both read as granted.

See also Grant permissions for the first-time setup this fix assumes, and MCP tools not visible if the agent still can’t act after permissions are granted.