Make explicit env vars win over AGENT fallback in agent detection

Previously, agents like amp and goose had dual matchers: their explicit
env var (AMP_CURRENT_THREAD_ID, GOOSE_TERMINAL) plus AGENT=<name>. This
caused asymmetric ambiguity: AGENT=goose + CLAUDECODE=1 resolved to ""
(both matchers fired on different products), while AGENT=cursor +
CLAUDECODE=1 resolved to "claude-code" (only claude-code matched,
cursor was handled by the AGENT fallback which does not trigger once
an explicit matcher has fired).

The rule is now uniform: explicit env var matchers always take
precedence over the generic AGENT=<name> signal. AGENT is treated
purely as a fallback for agents without an explicit matcher, or for
products we do not yet specifically recognize.

Changes:
- Remove per-agent AGENT=<name> matchers from amp and goose entries.
  Those products still set AGENT=<name>; the central fallback in
  lookupAgentProvider handles them.
- Update the lookupAgentProvider doc comment to reflect the new rule.
- Flip the existing AGENT=goose + CLAUDECODE=1 test to expect
  "claude-code" and rename accordingly.
- Add test for GOOSE_TERMINAL=1 + AGENT=cursor -> "goose".
- Add test for COPILOT_CLI=1 + COPILOT_MODEL=gpt-4 -> "" (documents
  the known, intentional ambiguity for Copilot CLI BYOK users).
- Update NEXT_CHANGELOG entry to mention precedence rule.

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.
+* 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.
 
 ### 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

@@ -295,11 +295,11 @@ boolean fires(Environment env) {
   // Agents are listed alphabetically by product name.
   private static List<KnownAgent> listKnownAgents() {
     return Arrays.asList(
+        // Amp also sets AGENT=amp; handled by the central AGENT fallback.
         new KnownAgent(
             "amp",
-            Arrays.asList(
-                new EnvMatcher("AMP_CURRENT_THREAD_ID"),
-                new EnvMatcher(AGENT_ENV_VAR, "amp"))), // https://ampcode.com/
+            Collections.singletonList(
+                new EnvMatcher("AMP_CURRENT_THREAD_ID"))), // https://ampcode.com/
         new KnownAgent(
             "antigravity",
             Collections.singletonList(
@@ -333,11 +333,11 @@ private static List<KnownAgent> listKnownAgents() {
             "gemini-cli",
             Collections.singletonList(
                 new EnvMatcher("GEMINI_CLI"))), // https://google-gemini.github.io/gemini-cli
+        // Goose also sets AGENT=goose; handled by the central AGENT fallback.
         new KnownAgent(
             "goose",
-            Arrays.asList(
-                new EnvMatcher("GOOSE_TERMINAL"),
-                new EnvMatcher(AGENT_ENV_VAR, "goose"))), // https://block.github.io/goose/
+            Collections.singletonList(
+                new EnvMatcher("GOOSE_TERMINAL"))), // https://block.github.io/goose/
         new KnownAgent(
             "kiro",
             Collections.singletonList(new EnvMatcher("KIRO"))), // https://kiro.dev/ (Amazon)
@@ -357,6 +357,11 @@ private static List<KnownAgent> listKnownAgents() {
 
   // Looks up the active agent provider based on environment variables.
   //
+  // Explicit env var matchers (e.g. CLAUDECODE, GOOSE_TERMINAL) always take
+  // precedence over the generic AGENT=<name> signal. The AGENT env var is
+  // 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:
   //   - Exactly one agent matched: return its product name.
@@ -367,8 +372,9 @@ private static List<KnownAgent> listKnownAgents() {
   //
   // 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). Known matchers always win over the AGENT
-  // fallback, so e.g. AGENT=cursor + CLAUDECODE=1 yields "claude-code".
+  // 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".
   private static String lookupAgentProvider(Environment env) {
     List<KnownAgent> knownAgents = listKnownAgents();
     String detected = "";

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

@@ -385,15 +385,49 @@ public void testAgentProviderAgentEnvEmpty() {
   }
 
   @Test
-  public void testAgentProviderAgentEnvAmbiguity() {
-    // AGENT=goose fires goose, CLAUDECODE=1 fires claude-code. Ambiguity.
+  public void testAgentProviderExplicitEnvWinsOverAgentEnv() {
+    // CLAUDECODE=1 is an explicit matcher and wins over AGENT=goose (which
+    // is only consulted as a fallback when no explicit matcher fires).
     setupAgentEnv(
         new HashMap<String, String>() {
           {
             put("AGENT", "goose");
             put("CLAUDECODE", "1");
           }
         });
+    Assertions.assertTrue(UserAgent.asString().contains("agent/claude-code"));
+  }
+
+  @Test
+  public void testAgentProviderExplicitEnvWinsOverKnownAgentEnv() {
+    // GOOSE_TERMINAL=1 is an explicit matcher; AGENT=cursor (even though
+    // "cursor" is a known product name) is ignored because an explicit
+    // matcher already fired.
+    setupAgentEnv(
+        new HashMap<String, String>() {
+          {
+            put("GOOSE_TERMINAL", "1");
+            put("AGENT", "cursor");
+          }
+        });
+    Assertions.assertTrue(UserAgent.asString().contains("agent/goose"));
+    Assertions.assertFalse(UserAgent.asString().contains("agent/cursor"));
+  }
+
+  @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.
+    setupAgentEnv(
+        new HashMap<String, String>() {
+          {
+            put("COPILOT_CLI", "1");
+            put("COPILOT_MODEL", "gpt-4");
+          }
+        });
     Assertions.assertFalse(UserAgent.asString().contains("agent/"));
   }