{"record":{"id":"c6c38024e0e557a7","repo":"Hmbown/CodeWhale","slug":"shared-pointer-required","errorCode":"shared_pointer_required","errorMessage":"This action needs the shared macOS pointer and was not sent in background mode. Use an accessibility action or a separate computer; foreground control requires exclusive desktop use authorized by the user.","messagePattern":"This action needs the shared macOS pointer and was not sent in background mode\\. Use an accessibility action or a separate computer; foreground control requires exclusive desktop use authorized by the user\\.","errorType":"error_code","errorClass":"ExecError","httpStatus":null,"severity":"error","filePath":"crates/tui/plugins/computer-use/src/backends/darwin.mjs","lineNumber":367,"sourceCode":"  // ---------- pointer input ----------\n  // Our qualified raw pointer path uses the shared event tap, which moves\n  // the user's real cursor. Process/window-directed mouse delivery has not\n  // passed the independent fixture. So the pointer path is:\n  //   1. accessibility action on the element under the point (quiet, exact),\n  //   2. otherwise refuse in background mode. Explicit foreground control\n  //      permits a global gesture only when the bound application owns the\n  //      window under the point. Restoring the cursor is not isolation.\n  // Every receipt says which of the two happened.\n  function mouseName(button) { return { left: \"left\", right: \"right\", middle: \"middle\" }[button] ?? \"left\"; }\n\n  function assertInScreen(x, y) {\n    if (!Number.isFinite(x) || !Number.isFinite(y)) throw new ExecError(\"coordinates must be finite numbers\");\n  }\n\n  function buttonCode(button) { return button === \"middle\" ? 2 : button === \"right\" ? 1 : 0; }\n\n  function requireSharedPointer() {\n    if (!state.foregroundInput) throw Object.assign(new ExecError(\"This action needs the shared macOS pointer and was not sent in background mode. Use an accessibility action or a separate computer; foreground control requires exclusive desktop use authorized by the user.\"), { code: \"shared_pointer_required\" });\n  }\n\n  /** Refuse a global gesture whose landing point belongs to another application. */\n  async function assertOwnsPoint(x, y) {\n    if (!state.inputApp) throw new ExecError(\"open_application first to choose which application receives input\");\n    const w = await native(\"window_at_point\", { x, y });\n    if (!w?.found) throw new ExecError(`no window at (${x}, ${y}) — take a fresh screenshot and choose a point inside the target window`);\n    if (w.owner_pid !== state.inputApp.pid) {\n      throw new ExecError(`(${x}, ${y}) is covered by a window owned by ${w.owner_name || \"another application\"} (pid ${w.owner_pid}) — use an accessibility element target or a separate computer; no pointer input was sent`);\n    }\n    return w;\n  }\n\n  /** What a global gesture cost the user: their cursor, and briefly their foreground. */\n  function pointerCost(r) {\n    return {\n      pointer_moved: true,\n      pointer_restored: !!r?.restored,","sourceCodeStart":349,"sourceCodeEnd":385,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/73e0f67d83c59909b571efdfc88c4bc28c309cb1/crates/tui/plugins/computer-use/src/backends/darwin.mjs#L349-L385","documentation":"Some macOS pointer actions (global gestures like drags) need the shared hardware pointer, and requireSharedPointer only permits them when the session runs in background/shared mode (state.foregroundInput set). In foreground mode the backend has been authorized for exclusive desktop use; refusing here prevents the agent from hijacking the user's only pointer without that authorization.","triggerScenarios":"Invoking a shared-pointer tool (e.g. pointer_sequence — nativeLease calls requireSharedPointer for it) while the session was opened with foreground/exclusive input instead of background mode, i.e. state.foregroundInput is false.","commonSituations":"Running the agent directly on the user's desktop (foreground session) and then attempting a drag; misconfigured session options that left background mode off; scripts written for a remote/separate-computer setup run locally in foreground mode.","solutions":["Re-open the session in background/shared mode (set the background_input/foreground option appropriately when calling open_application) so shared-pointer actions are allowed.","Replace the gesture with an accessibility element action (AXPress etc.) which doesn't need the shared pointer.","Run the target on a separate computer/virtual display so the shared pointer is genuinely free.","If foreground control is truly intended, obtain explicit user authorization for exclusive desktop use and start the session in foreground mode."],"exampleFix":"// before\nawait open_application(app, { foreground: true });\nawait pointer_sequence({ actions: [drag...] }); // shared_pointer_required\n\n// after\nawait open_application(app, { background: true });\nawait pointer_sequence({ actions: [drag...] });","handlingStrategy":"validation","validationCode":"// before shared-pointer gestures, confirm the session allows them\nif (!sessionState.foregroundInput && wantsSharedPointer) {\n  throw new Error('open the session in background/shared mode first');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await pointer_sequence(drag);\n} catch (e) {\n  if (e?.code === 'shared_pointer_required') {\n    // switch to accessibility action instead of hijacking the pointer\n    await a11yAction(target, 'AXPress');\n  } else throw e;\n}","preventionTips":["Open sessions in background/shared mode when the script needs drags or global gestures.","Never request foreground (exclusive) mode unless the user explicitly authorized it.","Prefer accessibility element actions, which work in background mode without the shared pointer.","Document per-session mode and gate shared-pointer tools on it."],"tags":["macos","pointer","permissions","background-mode"],"backgroundTag":"permission-denied","analyzedSha":"73e0f67d83c59909b571efdfc88c4bc28c309cb1","analyzedAt":"2026-09-22T01:30:00.501Z","contentChangedAt":"2026-09-22T01:30:00.501Z","schemaVersion":2},"datasetVersion":"2026-09-22T16:17:23.217Z"}