Hold the add until the plugin's access check passes

Author: RhysSullivan

packages/plugins/mcp/src/react/CodexPluginAdd.tsx

@@ -10,6 +10,7 @@ import { integrationWriteKeys } from "@executor-js/react/api/reactivity-keys";
 import { addIntegrationErrorMessage } from "@executor-js/react/lib/integration-add";
 
 import { addMcpServer, checkCodexPluginAccess, codexPluginsAtom } from "./atoms";
+import { accessBlocked, accessPending, type CodexAccessState } from "./codex-access-gate";
 import { CODEX_PERMISSIONS } from "../sdk/codex-permissions";
 
 // ---------------------------------------------------------------------------
@@ -31,7 +32,7 @@ export default function CodexPluginAdd(props: {
   const doCheckAccess = useAtomSet(checkCodexPluginAccess, { mode: "promiseExit" });
 
   const [adding, setAdding] = useState(false);
-  const [access, setAccess] = useState<{ status: string; message?: string } | null>(null);
+  const [access, setAccess] = useState<CodexAccessState | null>(null);
   const [checking, setChecking] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
@@ -46,6 +47,17 @@ export default function CodexPluginAdd(props: {
     AsyncResult.isSuccess(integrationsResult) &&
     integrationsResult.value.some((integration) => String(integration.slug) === plugin.slug);
 
+  // Adding is held back until the probe says the plugin can actually run: an
+  // integration added while macOS is blocking it looks connected and fails on
+  // its first real call, by which point the person has left the one card that
+  // explains the fix.
+  const blocked = accessBlocked(access);
+  const pending = accessPending({
+    checking,
+    declaresPermissions: permissions.length > 0,
+    access,
+  });
+
   const handleAdd = async () => {
     if (plugin === undefined) return;
     setAdding(true);
@@ -101,7 +113,7 @@ export default function CodexPluginAdd(props: {
     const exit = await doCheckAccess({ params: { id: props.presetId }, reactivityKeys: [] });
     setAccess(
       Exit.isSuccess(exit)
-        ? (exit.value as { status: string; message?: string })
+        ? (exit.value as CodexAccessState)
         : { status: "blocked", message: "Could not reach the plugin." },
     );
     setChecking(false);
@@ -200,8 +212,9 @@ export default function CodexPluginAdd(props: {
             macOS access
           </span>
           <p className="text-[12px] text-muted-foreground">
-            macOS asks the first time this runs. If you miss the prompt, it will not ask again —
-            enable it here.
+            {blocked
+              ? "This has to be on before the plugin can be added — turn it on below, then check again."
+              : "macOS asks the first time this runs. If you miss the prompt, it will not ask again — enable it here."}
           </p>
           <div className="flex items-center gap-3">
             <span
@@ -243,6 +256,19 @@ export default function CodexPluginAdd(props: {
         </div>
       )}
 
+      {/* A block on a plugin that declares no macOS access has no panel above
+          to carry it, so state the reason next to the action it is holding. */}
+      {blocked && permissions.length === 0 && (
+        <div className="flex items-center gap-3">
+          <p className="text-[12px] text-destructive">
+            {access?.message ?? "This plugin cannot run yet."}
+          </p>
+          <Button type="button" variant="secondary" onClick={() => void handleCheck()}>
+            Check again
+          </Button>
+        </div>
+      )}
+
       {error !== null && <p className="text-[12px] text-destructive">{error}</p>}
 
       <FloatActions>
@@ -254,8 +280,13 @@ export default function CodexPluginAdd(props: {
             View integration
           </Button>
         ) : plugin.available ? (
-          <Button type="button" onClick={() => void handleAdd()} loading={adding}>
-            Add integration
+          <Button
+            type="button"
+            onClick={() => void handleAdd()}
+            loading={adding}
+            disabled={blocked || pending}
+          >
+            {pending ? "Checking access…" : "Add integration"}
           </Button>
         ) : (
           <Button asChild>

packages/plugins/mcp/src/react/codex-access-gate.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "@effect/vitest";
+
+import { accessBlocked, accessPending } from "./codex-access-gate";
+
+describe("accessBlocked", () => {
+  it("holds the add only on a refusal", () => {
+    expect(accessBlocked({ status: "blocked", message: "macOS blocked this" })).toBe(true);
+  });
+
+  it("lets through every answer that is not a refusal", () => {
+    // `unsupported` and `nothing-to-check` are answers about the HOST and the
+    // PLUGIN, not about permission. Treating either as a block would strand a
+    // plugin that needs no grant at all.
+    for (const status of ["ok", "unsupported", "nothing-to-check", "unknown", "not-installed"]) {
+      expect(accessBlocked({ status })).toBe(false);
+    }
+  });
+
+  it("does not hold before an answer exists", () => {
+    // `accessPending` owns that window; a card without permissions has no
+    // probe to wait for and must not be blocked by its own silence.
+    expect(accessBlocked(null)).toBe(false);
+  });
+});
+
+describe("accessPending", () => {
+  it("waits while the probe runs", () => {
+    expect(accessPending({ checking: true, declaresPermissions: true, access: null })).toBe(true);
+    // Still pending on a re-check, even though a previous answer is in hand:
+    // that answer is what the user just acted on.
+    expect(
+      accessPending({ checking: true, declaresPermissions: true, access: { status: "blocked" } }),
+    ).toBe(true);
+  });
+
+  it("waits for the first answer on a plugin that declares permissions", () => {
+    expect(accessPending({ checking: false, declaresPermissions: true, access: null })).toBe(true);
+  });
+
+  it("does not wait once an answer has arrived", () => {
+    expect(
+      accessPending({ checking: false, declaresPermissions: true, access: { status: "ok" } }),
+    ).toBe(false);
+  });
+
+  it("does not wait when nothing will be checked", () => {
+    expect(accessPending({ checking: false, declaresPermissions: false, access: null })).toBe(
+      false,
+    );
+  });
+});

packages/plugins/mcp/src/react/codex-access-gate.ts

@@ -0,0 +1,43 @@
+// ---------------------------------------------------------------------------
+// When the Codex plugin card may hand over its Add button.
+//
+// The probe behind this is the only way to know whether macOS will let the
+// plugin run: privacy decisions are not readable, so the card tries the real
+// path and reads the answer. Adding before that answer arrives produces an
+// integration that looks connected and fails on its first call, at a point
+// where the explanation — and the switch that fixes it — are no longer on
+// screen.
+// ---------------------------------------------------------------------------
+
+/** The `checkCodexPluginAccess` result, as the card holds it. */
+export interface CodexAccessState {
+  readonly status: string;
+  readonly message?: string;
+}
+
+/**
+ * The plugin was reached and refused.
+ *
+ * Only `blocked` counts. `unsupported` (a host that cannot spawn stdio at all)
+ * and `nothing-to-check` (a plugin with no probe) are answers, not blocks, and
+ * holding the button on either would strand plugins that need no permission.
+ */
+export const accessBlocked = (access: CodexAccessState | null): boolean =>
+  access !== null && access.status === "blocked";
+
+/**
+ * The answer is still coming.
+ *
+ * A card that declares permissions runs the probe on open, so `null` there
+ * means the check has not reported yet rather than that nothing will check.
+ * Without permissions there is nothing to wait for, and the button stays live.
+ */
+export const accessPending = ({
+  checking,
+  declaresPermissions,
+  access,
+}: {
+  readonly checking: boolean;
+  readonly declaresPermissions: boolean;
+  readonly access: CodexAccessState | null;
+}): boolean => checking || (declaresPermissions && access === null);