From 0e1407362d4e52d3f6f0737520c77ee30d51e0cc Mon Sep 17 00:00:00 2001
From: Shakker <shakkerdroid@gmail.com>
Date: Thu, 23 Apr 2026 06:46:03 +0100
Subject: [PATCH] docs: mark external oauth hook deprecated

---
 src/plugins/provider-runtime.ts | 6 +++---
 src/plugins/providers.ts        | 6 +++---
 src/plugins/types.ts            | 6 +++---
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/src/plugins/provider-runtime.ts b/src/plugins/provider-runtime.ts
index 5a7d4d4429e..7f80aa1b612 100644
--- a/src/plugins/provider-runtime.ts
+++ b/src/plugins/provider-runtime.ts
@@ -797,9 +797,9 @@ export function resolveExternalAuthProfilesWithPlugins(params: {
     }
     if (!declaredPluginIds.has(plugin.id) && !warnedExternalAuthFallbackPluginIds.has(plugin.id)) {
       warnedExternalAuthFallbackPluginIds.add(plugin.id);
-      // Deprecated compatibility path for plugins that predate the manifest
-      // contract. Remove this warning with the fallback resolver after the
-      // externalAuthProviders migration window closes.
+      // Deprecated compatibility path for plugins that still implement
+      // resolveExternalOAuthProfiles or omit contracts.externalAuthProviders.
+      // Remove this warning with the fallback resolver after the migration window.
       log.warn(
         `Provider plugin "${plugin.id}" uses external auth hooks without declaring contracts.externalAuthProviders. This compatibility fallback is deprecated and will be removed in a future release.`,
       );
diff --git a/src/plugins/providers.ts b/src/plugins/providers.ts
index adb43761385..6c624576413 100644
--- a/src/plugins/providers.ts
+++ b/src/plugins/providers.ts
@@ -137,9 +137,9 @@ export function resolveExternalAuthProfileCompatFallbackPluginIds(params: {
   workspaceDir?: string;
   env?: PluginLoadOptions["env"];
 }): string[] {
-  // Compatibility fallback for provider plugins that implemented the public
-  // external auth hook before contracts.externalAuthProviders existed. Remove
-  // this with the warning path in provider-runtime after the deprecation window.
+  // Deprecated compatibility fallback for provider plugins that still implement
+  // resolveExternalOAuthProfiles or omit contracts.externalAuthProviders. Remove
+  // this with the warning path in provider-runtime after the migration window.
   const declaredPluginIds = new Set(resolveExternalAuthProfileProviderPluginIds(params));
   const registry = loadProviderManifestRegistry(params);
   const normalizedConfig = normalizePluginsConfig(params.config?.plugins);
diff --git a/src/plugins/types.ts b/src/plugins/types.ts
index e99cc12625a..b1ebf91e9f5 100644
--- a/src/plugins/types.ts
+++ b/src/plugins/types.ts
@@ -1583,9 +1583,9 @@ export type ProviderPlugin = {
     | null
     | undefined;
   /**
-   * @deprecated Use `resolveExternalAuthProfiles`.
-   *
-   * Kept for compatibility with existing provider plugins.
+   * @deprecated Declare `contracts.externalAuthProviders` in the plugin manifest
+   * and implement `resolveExternalAuthProfiles` instead. This compatibility hook
+   * is loaded through a slower fallback path and will be removed in a future release.
    */
   resolveExternalOAuthProfiles?: (
     ctx: ProviderResolveExternalOAuthProfilesContext,