Report agent/multiple when agents are stacked

Nested agents (e.g. a Cursor CLI subagent spawned by Claude Code) set
multiple agent env vars on the same process. The previous ambiguity
guard silently dropped the signal in that case. Report "multiple"
instead so the stacked case is visible in telemetry.

Also collapse the known BYOK false positive where Copilot CLI users
have COPILOT_MODEL set alongside COPILOT_CLI: that pair now reports
"copilot-cli" rather than "multiple".

Co-authored-by: Isaac
Signed-off-by: simon <simon.faltum@databricks.com>

Author: simonfaltum

NEXT_CHANGELOG.md

@@ -5,7 +5,7 @@
 ### New Features and Improvements
 * Add support for authentication through Azure Managed Service Identity (MSI) via the new `azure-msi` credential provider.
 * Support `default_profile` in `[__settings__]` section of `.databrickscfg` for consistent default profile resolution across CLI and SDKs.
-* Added automatic detection of AI coding agents (Amp, Antigravity, Augment, Claude Code, Cline, Codex, Copilot CLI, Copilot VS Code, Cursor, Gemini CLI, Goose, Kiro, OpenClaw, OpenCode, Windsurf) in the user-agent string. The SDK now appends `agent/<name>` to HTTP request headers when running inside a known AI agent environment. Also honors the `AGENT=<name>` standard: when `AGENT` is set to a known product name the SDK reports that product, and when set to an unrecognized non-empty value the SDK reports `agent/unknown`. Environment variables set to the empty string (e.g. `CLAUDECODE=""`) now count as "set" for presence-only matchers, matching `databricks-sdk-go` semantics; previously they were treated as unset. Explicit agent env vars (e.g. `CLAUDECODE`, `GOOSE_TERMINAL`) always take precedence over the generic `AGENT=<name>` signal.
+* Added automatic detection of AI coding agents (Amp, Antigravity, Augment, Claude Code, Cline, Codex, Copilot CLI, Copilot VS Code, Cursor, Gemini CLI, Goose, Kiro, OpenClaw, OpenCode, Windsurf) in the user-agent string. The SDK now appends `agent/<name>` to HTTP request headers when running inside a known AI agent environment. Also honors the `AGENT=<name>` standard: when `AGENT` is set to a known product name the SDK reports that product, and when set to an unrecognized non-empty value the SDK reports `agent/unknown`. Environment variables set to the empty string (e.g. `CLAUDECODE=""`) now count as "set" for presence-only matchers, matching `databricks-sdk-go` semantics; previously they were treated as unset. Explicit agent env vars (e.g. `CLAUDECODE`, `GOOSE_TERMINAL`) always take precedence over the generic `AGENT=<name>` signal. When multiple agent env vars are present (e.g. a Cursor CLI subagent invoked from Claude Code), the user-agent reports `agent/multiple`.
 
 ### Bug Fixes
 * Fixed non-JSON error responses (e.g. plain-text "Invalid Token" with HTTP 403) producing `Unknown` instead of the correct typed exception (`PermissionDenied`, `Unauthenticated`, etc.). The error message no longer contains Jackson deserialization internals.

databricks-sdk-java/src/main/java/com/databricks/sdk/core/UserAgent.java

@@ -287,19 +287,19 @@ private static List<KnownAgent> listKnownAgents() {
   // treated purely as a fallback for agents that have no explicit matcher, or
   // for agents we do not yet specifically recognize.
   //
-  // For each agent, it fires if ANY of its matchers fires. The function counts
-  // how many distinct agents matched:
+  // The function counts how many distinct agents matched via explicit env vars:
   //   - Exactly one agent matched: return its product name.
-  //   - More than one agent matched: return "" (ambiguity).
+  //   - More than one agent matched: return "multiple". Agent env vars can be
+  //     stacked when one agent invokes another as a subagent (e.g. Claude Code
+  //     spawning a Cursor CLI subprocess), so the child process inherits env
+  //     vars from multiple layers.
   //   - Zero agents matched: if the agents.md standard AGENT env var is set to
   //     a known product name, return that product name. If it is set to any
   //     other non-empty value, return "unknown". Otherwise return "".
   //
-  // Unlike CI/CD detection (which returns the first match), agent detection
-  // uses an ambiguity guard because agent env vars can be stacked (e.g.,
-  // running Cline inside Cursor). Because explicit matchers win over AGENT,
-  // e.g. AGENT=cursor + CLAUDECODE=1 yields "claude-code", and
-  // AGENT=goose + CLAUDECODE=1 also yields "claude-code".
+  // Because explicit matchers win over AGENT, e.g. AGENT=cursor + CLAUDECODE=1
+  // yields "claude-code", and AGENT=goose + CLAUDECODE=1 also yields
+  // "claude-code".
   private static String lookupAgentProvider(Environment env) {
     List<KnownAgent> agents = listKnownAgents();
 
@@ -310,11 +310,18 @@ private static String lookupAgentProvider(Environment env) {
       }
     }
 
+    // Known BYOK false positive: Copilot CLI users often set COPILOT_MODEL
+    // alongside COPILOT_CLI. Treat that pair as a single copilot-cli signal
+    // rather than a stacked multi-agent setup.
+    if (matches.contains("copilot-cli") && matches.contains("copilot-vscode")) {
+      matches.removeIf(m -> m.equals("copilot-vscode"));
+    }
+
     if (matches.size() == 1) {
       return matches.get(0);
     }
     if (matches.size() > 1) {
-      return ""; // ambiguity
+      return "multiple";
     }
     return agentEnvFallback(env, agents);
   }

databricks-sdk-java/src/test/java/com/databricks/sdk/core/UserAgentTest.java

@@ -415,20 +415,33 @@ public void testAgentProviderExplicitEnvWinsOverKnownAgentEnv() {
   }
 
   @Test
-  public void testAgentProviderCopilotCliAndCopilotVscodeAmbiguous() {
-    // Copilot CLI can be invoked with BYOK models, which may also set
-    // COPILOT_MODEL. In that case both copilot-cli and copilot-vscode
-    // matchers fire on different products, so detection is ambiguous.
-    // This is intentional: ambiguity is preferred over silently picking
-    // one product.
+  public void testAgentProviderCopilotCliAndCopilotVscodeCollapseToCopilotCli() {
+    // Copilot CLI users (BYOK mode) often set COPILOT_MODEL alongside
+    // COPILOT_CLI. Treat the pair as a single copilot-cli signal rather
+    // than a stacked multi-agent setup.
     setupAgentEnv(
         new HashMap<String, String>() {
           {
             put("COPILOT_CLI", "1");
             put("COPILOT_MODEL", "gpt-4");
           }
         });
-    Assertions.assertFalse(UserAgent.asString().contains("agent/"));
+    Assertions.assertTrue(UserAgent.asString().contains("agent/copilot-cli"));
+  }
+
+  @Test
+  public void testAgentProviderCopilotByokCollapseStillMultiple() {
+    // The Copilot BYOK collapse only drops the copilot-vscode match. If
+    // another agent is also present, the result is still "multiple".
+    setupAgentEnv(
+        new HashMap<String, String>() {
+          {
+            put("COPILOT_CLI", "1");
+            put("COPILOT_MODEL", "gpt-4");
+            put("CLAUDECODE", "1");
+          }
+        });
+    Assertions.assertTrue(UserAgent.asString().contains("agent/multiple"));
   }
 
   @Test
@@ -439,14 +452,29 @@ public void testAgentProviderNoAgent() {
 
   @Test
   public void testAgentProviderMultipleAgents() {
+    // Nested agents (e.g. Claude Code spawning a Cursor CLI subagent) set
+    // multiple explicit matchers on the same process.
     setupAgentEnv(
         new HashMap<String, String>() {
           {
             put("CLAUDECODE", "1");
             put("CURSOR_AGENT", "1");
           }
         });
-    Assertions.assertFalse(UserAgent.asString().contains("agent/"));
+    Assertions.assertTrue(UserAgent.asString().contains("agent/multiple"));
+  }
+
+  @Test
+  public void testAgentProviderThreeStackedAgents() {
+    setupAgentEnv(
+        new HashMap<String, String>() {
+          {
+            put("CLAUDECODE", "1");
+            put("CURSOR_AGENT", "1");
+            put("AUGMENT_AGENT", "1");
+          }
+        });
+    Assertions.assertTrue(UserAgent.asString().contains("agent/multiple"));
   }
 
   @Test