fix(hopper): explain disclaimed Apple Events responsibility (#12309)

* fix(hopper): explain disclaimed Apple Events responsibility

* test(hopper): cover disclaimed Apple Events guidance

* docs(hopper): document runtime Apple Events attribution
This commit is contained in:
ShuaixinHuang authored and GitHub committed 2026-11-19 13:12:42 +00:00
1 parent 29b2f96f74
commit 0c672c19a9
6 files changed
+78 -39

No files matched your search

+16 -7
View File
@@ -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,
+2 -4
View File
@@ -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,
});
}
+6 -8
View File
@@ -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)(
+39 -7
View File
@@ -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,
@@ -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 },
},
});
@@ -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 },
},