diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 76572703be..ea517de90f 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -1017,14 +1017,23 @@ stage `connection`. If macOS denies Apple Events, REA reports `details.launch_rejection.boundary: "apple_events_authorization"` with -`reason: "not_authorized"`, category `unavailable`, and `retryable: false`. -Allow the application that starts REA under -**System Settings → Privacy & Security → Automation** when that client can be -authorized. A hardened-runtime application requires the +`reason: "not_authorized"`, +`responsibility: "client_or_disclaimed_runtime"`, +`settings_pane: "privacy_security_automation"`, and +`entitlement_id: "com.apple.security.automation.apple-events"`, +category `unavailable`, and `retryable: false`. The helper does not identify +the responsible process, so `responsibility` covers both an authorizable client +and a client that disclaims TCC responsibility. +Allow the application that macOS identifies as responsible for REA under +**System Settings → Privacy & Security → Automation**. Some MCP clients, including +Claude Desktop, disclaim responsibility, so macOS attributes the request to the +REA runtime, such as `node`; changing the client's Automation setting cannot +authorize that runtime. In this case start REA from a client macOS can authorize, +such as Claude Code or Terminal. A hardened-runtime application requires the `com.apple.security.automation.apple-events` entitlement before macOS will -prompt; without it, ask the client developer to add the entitlement or start -REA from a client macOS can authorize, such as Terminal. Retrying from the same -unauthorized client will not succeed until authorization changes. REA releases +prompt; if the responsible client lacks it, ask its developer to add the +entitlement. Retrying from the same unauthorized client will not succeed until +authorization changes. REA releases the target reservation when the native helper reports its complete authorization rejection after literal argument admission. Before application handoff, REA refuses double quotes, backslashes, or line breaks in the final launcher path or arguments, diff --git a/src/hopper/HopperClient.ts b/src/hopper/HopperClient.ts index ea71650dde..ee9a2be821 100644 --- a/src/hopper/HopperClient.ts +++ b/src/hopper/HopperClient.ts @@ -33,6 +33,7 @@ import { type HopperServerInfo, } from "./HopperReplyContracts.js"; import { + hopperAppleEventsAuthorizationRejection, hopperCancelledBySignal, type HopperCancelledError, type HopperError, @@ -1209,10 +1210,7 @@ export class HopperClient< ) { this.#resources.shutdownConfirmed = true; return new HopperStartError({ - launchRejection: { - boundary: "apple_events_authorization", - reason: "not_authorized", - }, + launchRejection: hopperAppleEventsAuthorizationRejection, launcherFailure, }); } diff --git a/src/hopper/HopperErrorProjection.test.ts b/src/hopper/HopperErrorProjection.test.ts index c324ed0c7e..244f2e10f3 100644 --- a/src/hopper/HopperErrorProjection.test.ts +++ b/src/hopper/HopperErrorProjection.test.ts @@ -10,6 +10,7 @@ import { HopperTimeoutError, HopperCancelledError, HopperProtocolError, + hopperAppleEventsAuthorizationRejection, hopperErrorCatalogue, } from "./HopperErrors.js"; import { @@ -74,10 +75,7 @@ describe("analysis error projection: Hopper provider failures", () => { it("projects an Apple Events denial as unavailable and not retryable from the same client", () => { const projected = projectAnalysisError( new HopperStartError({ - launchRejection: { - boundary: "apple_events_authorization", - reason: "not_authorized", - }, + launchRejection: hopperAppleEventsAuthorizationRejection, launcherFailure: { exit_code: 2, signal: null, @@ -103,6 +101,9 @@ describe("analysis error projection: Hopper provider failures", () => { launch_rejection: { boundary: "apple_events_authorization", reason: "not_authorized", + responsibility: "client_or_disclaimed_runtime", + settings_pane: "privacy_security_automation", + entitlement_id: "com.apple.security.automation.apple-events", }, launcher: { exit_code: 2, signal: null }, }, @@ -540,10 +541,7 @@ describe("Hopper error catalogue", () => { [ "Apple Events authorization denied", new HopperStartError({ - launchRejection: { - boundary: "apple_events_authorization", - reason: "not_authorized", - }, + launchRejection: hopperAppleEventsAuthorizationRejection, }), ], ] as const)( diff --git a/src/hopper/HopperErrors.ts b/src/hopper/HopperErrors.ts index 55ded31a8f..2ae93171b6 100644 --- a/src/hopper/HopperErrors.ts +++ b/src/hopper/HopperErrors.ts @@ -93,11 +93,13 @@ const RESTART_UNREACHABLE_HOPPER = `${RESTART_OWNED_PROVIDER} close_binary prese const RERUN_HOPPER_INVOCATION = "Review the reported Hopper state and resolve any incomplete cleanup before rerunning the command."; -const HOPPER_APPLE_EVENTS_AUTHORIZATION_MESSAGE = - "macOS denied permission to send Apple Events to Hopper. A hardened-runtime application starting REA requires the com.apple.security.automation.apple-events entitlement before macOS will prompt for permission."; +/** Hardened-runtime entitlement macOS requires before an Apple Events prompt. */ +const HOPPER_APPLE_EVENTS_ENTITLEMENT_ID = + "com.apple.security.automation.apple-events" as const; -const HOPPER_APPLE_EVENTS_AUTHORIZATION_REMEDIATION = - "Allow the application that starts REA under System Settings > Privacy & Security > Automation. If the client lacks the com.apple.security.automation.apple-events entitlement, ask the client developer to add it or start REA from a client macOS can authorize, such as Terminal. Retrying from the same unauthorized client will not succeed until authorization changes."; +const HOPPER_APPLE_EVENTS_AUTHORIZATION_MESSAGE = `macOS denied permission to send Apple Events to Hopper. A hardened-runtime application starting REA requires the ${HOPPER_APPLE_EVENTS_ENTITLEMENT_ID} entitlement before macOS will prompt for permission.`; + +const HOPPER_APPLE_EVENTS_AUTHORIZATION_REMEDIATION = `Allow the application that macOS identifies as responsible for REA under System Settings > Privacy & Security > Automation. Some MCP clients, including Claude Desktop, disclaim responsibility so macOS attributes the request to the REA runtime (such as node), which cannot be authorized by changing the client's Automation setting. In that case start REA from a client macOS can authorize, such as Claude Code or Terminal. If the responsible client lacks the ${HOPPER_APPLE_EVENTS_ENTITLEMENT_ID} entitlement, ask its developer to add it. Retrying from the same unauthorized client will not succeed until authorization changes.`; export class HopperTimeoutError extends HopperError { readonly _tag = providerErrorTag("HopperTimeoutError"); @@ -487,14 +489,44 @@ export type HopperLaunchRejection = | { /** * macOS refused the launcher's Apple Event. The helper's stderr does not - * show whether the responsible client lacks an Automation grant or the - * hardened-runtime Apple Events entitlement. Another launch from that - * same client cannot succeed until authorization changes. + * show whether the responsible client lacks an Automation grant, lacks + * the hardened-runtime Apple Events entitlement, or disclaimed TCC + * responsibility so macOS attributed the event to the REA runtime. + * Another launch from that same client cannot succeed until + * authorization changes. */ readonly boundary: "apple_events_authorization"; readonly reason: "not_authorized"; + /** + * The helper did not observe which process is responsible. Recovery + * covers an authorizable client and a client that disclaims TCC + * responsibility. + */ + readonly responsibility: "client_or_disclaimed_runtime"; + /** System Settings > Privacy & Security > Automation. */ + readonly settings_pane: "privacy_security_automation"; + /** + * Entitlement a hardened-runtime responsible process needs before macOS + * prompts. + */ + readonly entitlement_id: typeof HOPPER_APPLE_EVENTS_ENTITLEMENT_ID; }; +/** + * The one Apple Events denial REA can recognize. The helper does not identify + * the responsible process, so these facts stay constant for that denial. + */ +export const hopperAppleEventsAuthorizationRejection = { + boundary: "apple_events_authorization", + reason: "not_authorized", + responsibility: "client_or_disclaimed_runtime", + settings_pane: "privacy_security_automation", + entitlement_id: HOPPER_APPLE_EVENTS_ENTITLEMENT_ID, +} as const satisfies Extract< + HopperLaunchRejection, + { readonly boundary: "apple_events_authorization" } +>; + /** Recognize the Apple Events refusal that the same client cannot retry. */ export const hopperAppleEventsAuthorizationDenied = ( rejection: HopperLaunchRejection | undefined, diff --git a/tests/acceptance/providers/hopperStartupRecovery.test.ts b/tests/acceptance/providers/hopperStartupRecovery.test.ts index b93052fdc0..1f73eab9f8 100644 --- a/tests/acceptance/providers/hopperStartupRecovery.test.ts +++ b/tests/acceptance/providers/hopperStartupRecovery.test.ts @@ -204,6 +204,13 @@ test("recovers a denied Hopper launch through the same stdio MCP session and CLI throw new Error(`${name}: ${stderr}`, { cause }); }); expect((await call("open_binary", { path: target })).isError).not.toBe(true); + const appleEventsRejection = { + boundary: "apple_events_authorization", + reason: "not_authorized", + responsibility: "client_or_disclaimed_runtime", + settings_pane: "privacy_security_automation", + entitlement_id: "com.apple.security.automation.apple-events", + }; for (const operation of ["current_document", "list_procedures"]) { const { error } = parseMcpToolError(await call(operation)); expect(error).toMatchObject({ @@ -214,10 +221,7 @@ test("recovers a denied Hopper launch through the same stdio MCP session and CLI stage: "launch", provider_state: "unknown", retry_action: "unknown", - launch_rejection: { - boundary: "apple_events_authorization", - reason: "not_authorized", - }, + launch_rejection: appleEventsRejection, launcher: { exit_code: 2, stderr: { @@ -228,11 +232,6 @@ test("recovers a denied Hopper launch through the same stdio MCP session and CLI }, }, }); - expect(error.remediation.action).toContain("client developer"); - expect(error.remediation.action).toContain("Terminal"); - expect(error.remediation.action).toContain( - "Retrying from the same unauthorized client will not succeed until authorization changes", - ); const bootstrap = await readFile(receipt, "utf8"); await expect(access(dirname(bootstrap))).rejects.toMatchObject({ code: "ENOENT", @@ -250,10 +249,7 @@ test("recovers a denied Hopper launch through the same stdio MCP session and CLI retryable: false, details: { retry_action: "unknown", - launch_rejection: { - boundary: "apple_events_authorization", - reason: "not_authorized", - }, + launch_rejection: appleEventsRejection, launcher: { exit_code: 2 }, }, }); diff --git a/tests/boundary/providers/hopper/hopperClient.helperFailure.test.ts b/tests/boundary/providers/hopper/hopperClient.helperFailure.test.ts index 2bed5d9ef1..fa0430367d 100644 --- a/tests/boundary/providers/hopper/hopperClient.helperFailure.test.ts +++ b/tests/boundary/providers/hopper/hopperClient.helperFailure.test.ts @@ -248,6 +248,9 @@ it("classifies a pre-handoff Apple Events denial as not retryable from the same launchRejection: { boundary: "apple_events_authorization", reason: "not_authorized", + responsibility: "client_or_disclaimed_runtime", + settings_pane: "privacy_security_automation", + entitlement_id: "com.apple.security.automation.apple-events", }, }, }); @@ -263,6 +266,9 @@ it("classifies a pre-handoff Apple Events denial as not retryable from the same launch_rejection: { boundary: "apple_events_authorization", reason: "not_authorized", + responsibility: "client_or_disclaimed_runtime", + settings_pane: "privacy_security_automation", + entitlement_id: "com.apple.security.automation.apple-events", }, launcher: { exit_code: 2, signal: null }, },