[PECOBLR-1928] Add AI coding agent detection to User-Agent header (#1230)

## Summary
- Adds `AgentDetector` utility class that detects 7 AI coding agents
(Claude Code, Cursor, Gemini CLI, Cline, Codex, OpenCode, Antigravity)
by checking well-known environment variables they set in spawned shell
processes
- Integrates detection into `UserAgentManager` to append
`agent/<product>` to the User-Agent header on both SDK-based and
connector-service UA paths
- Uses exactly-one detection rule: if zero or multiple agent env vars
are set, no agent is attributed (avoids ambiguity)

## Approach
Mirrors the implementation in
[databricks/cli#4287](databricks/cli#4287) and
aligns with the latest agent list in
[`libs/agent/agent.go`](https://github.com/databricks/cli/blob/main/libs/agent/agent.go#L35).

| Agent | Product String | Environment Variable |
|-------|---------------|---------------------|
| Google Antigravity | `antigravity` | `ANTIGRAVITY_AGENT` |
| Claude Code | `claude-code` | `CLAUDECODE` |
| Cline | `cline` | `CLINE_ACTIVE` |
| OpenAI Codex | `codex` | `CODEX_CI` |
| Cursor | `cursor` | `CURSOR_AGENT` |
| Gemini CLI | `gemini-cli` | `GEMINI_CLI` |
| OpenCode | `opencode` | `OPENCODE` |

Adding a new agent requires only a new constant and a new entry in the
`KNOWN_AGENTS` array.

## Changes
- **New**: `AgentDetector.java` — environment-variable-based agent
detection with injectable env lookup for testability
- **Modified**: `UserAgentManager.java` — calls `AgentDetector.detect()`
in both `setUserAgent()` and `buildUserAgentForConnectorService()`
- **New**: `AgentDetectorTest.java` — 12 test cases covering single
agent, no agent, multiple agents, empty values, null values, and full
coverage of all known agents

## Test plan
- [x] `AgentDetectorTest` — 12 tests pass (single agent detection for
all 7 agents, no agent, multiple agents, empty/null values)
- [x] `UserAgentManagerTest` — all 7 existing tests continue to pass
- [x] Manual: verify User-Agent header contains `agent/claude-code` when
run from Claude Code

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Signed-off-by: Vikrant Puppala <vikrant.puppala@databricks.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: vikrantpuppala

NEXT_CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 - Added `CallableStatement` support with IN parameters. `Connection.prepareCall()` now returns a working `DatabricksCallableStatement` that supports positional parameter binding and execution via `{call proc(?)}` JDBC escape syntax. OUT/INOUT parameters and named parameters throw `SQLFeatureNotSupportedException`.
+- Added AI coding agent detection to the User-Agent header. When the driver is invoked by a known AI coding agent (e.g. Claude Code, Cursor, Gemini CLI), `agent/<product>` is appended to the User-Agent string.
 
 ### Updated
 

src/main/java/com/databricks/jdbc/common/util/AgentDetector.java

@@ -0,0 +1,79 @@
+package com.databricks.jdbc.common.util;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
+import java.util.function.Function;
+
+/**
+ * Detects whether the JDBC driver is being invoked by an AI coding agent by checking for well-known
+ * environment variables that agents set in their spawned shell processes.
+ *
+ * <p>Detection only succeeds when exactly one agent environment variable is present, to avoid
+ * ambiguous attribution when multiple agent environments overlap.
+ *
+ * <p>Adding a new agent requires only a new constant and a new entry in {@link #KNOWN_AGENTS}.
+ *
+ * <p>References for each environment variable:
+ *
+ * <ul>
+ *   <li>ANTIGRAVITY_AGENT: Closed source. Google Antigravity sets this variable.
+ *   <li>CLAUDECODE: https://github.com/anthropics/claude-code (sets CLAUDECODE=1)
+ *   <li>CLINE_ACTIVE: https://github.com/cline/cline (shipped in v3.24.0)
+ *   <li>CODEX_CI: https://github.com/openai/codex (part of UNIFIED_EXEC_ENV array in codex-rs)
+ *   <li>CURSOR_AGENT: Closed source. Referenced in a gist by johnlindquist.
+ *   <li>GEMINI_CLI: https://google-gemini.github.io/gemini-cli/docs/tools/shell.html (sets
+ *       GEMINI_CLI=1)
+ *   <li>OPENCODE: https://github.com/opencode-ai/opencode (sets OPENCODE=1)
+ * </ul>
+ */
+public class AgentDetector {
+
+  public static final String ANTIGRAVITY = "antigravity";
+  public static final String CLAUDE_CODE = "claude-code";
+  public static final String CLINE = "cline";
+  public static final String CODEX = "codex";
+  public static final String CURSOR = "cursor";
+  public static final String GEMINI_CLI = "gemini-cli";
+  public static final String OPEN_CODE = "opencode";
+
+  static final String[][] KNOWN_AGENTS = {
+    {"ANTIGRAVITY_AGENT", ANTIGRAVITY},
+    {"CLAUDECODE", CLAUDE_CODE},
+    {"CLINE_ACTIVE", CLINE},
+    {"CODEX_CI", CODEX},
+    {"CURSOR_AGENT", CURSOR},
+    {"GEMINI_CLI", GEMINI_CLI},
+    {"OPENCODE", OPEN_CODE},
+  };
+
+  /**
+   * Detects which AI coding agent (if any) is driving the current process.
+   *
+   * @return the agent product string if exactly one agent is detected, or empty otherwise
+   */
+  public static Optional<String> detect() {
+    return detect(System::getenv);
+  }
+
+  /**
+   * Detects which AI coding agent (if any) is present, using the provided function to look up
+   * environment variables. This overload exists for testability.
+   *
+   * @param envLookup function that returns the value of an environment variable, or null if unset
+   * @return the agent product string if exactly one agent is detected, or empty otherwise
+   */
+  static Optional<String> detect(Function<String, String> envLookup) {
+    List<String> detected = new ArrayList<>();
+    for (String[] entry : KNOWN_AGENTS) {
+      String value = envLookup.apply(entry[0]);
+      if (value != null && !value.isEmpty()) {
+        detected.add(entry[1]);
+      }
+    }
+    if (detected.size() == 1) {
+      return Optional.of(detected.get(0));
+    }
+    return Optional.empty();
+  }
+}

src/main/java/com/databricks/jdbc/common/util/UserAgentManager.java

@@ -16,6 +16,7 @@ public class UserAgentManager {
   public static final String USER_AGENT_SEA_CLIENT = "SQLExecHttpClient";
   public static final String USER_AGENT_THRIFT_CLIENT = "THttpClient";
   private static final String VERSION_FILLER = "version";
+  private static final String AGENT_KEY = "agent";
 
   /**
    * Parse custom user agent string into name and version components.
@@ -62,6 +63,9 @@ public static void setUserAgent(IDatabricksConnectionContext connectionContext)
         }
       }
     }
+
+    // Detect AI coding agent and append to user agent
+    AgentDetector.detect().ifPresent(product -> UserAgent.withOtherInfo(AGENT_KEY, product));
   }
 
   /**
@@ -106,6 +110,10 @@ public static String buildUserAgentForConnectorService(
       }
     }
 
+    // Detect AI coding agent and append to user agent
+    AgentDetector.detect()
+        .ifPresent(product -> userAgent.append(" ").append(AGENT_KEY).append("/").append(product));
+
     return userAgent.toString();
   }
 

src/test/java/com/databricks/jdbc/common/util/AgentDetectorTest.java

@@ -0,0 +1,81 @@
+package com.databricks.jdbc.common.util;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+import java.util.stream.Stream;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+
+public class AgentDetectorTest {
+
+  /** Creates an env lookup function that returns values from the given map. */
+  private static java.util.function.Function<String, String> envWith(Map<String, String> env) {
+    return env::get;
+  }
+
+  @ParameterizedTest
+  @MethodSource("singleAgentCases")
+  void testDetectsSingleAgent(String envVar, String expectedProduct) {
+    Map<String, String> env = new HashMap<>();
+    env.put(envVar, "1");
+    assertEquals(Optional.of(expectedProduct), AgentDetector.detect(envWith(env)));
+  }
+
+  static Stream<Arguments> singleAgentCases() {
+    return Stream.of(
+        Arguments.of("ANTIGRAVITY_AGENT", AgentDetector.ANTIGRAVITY),
+        Arguments.of("CLAUDECODE", AgentDetector.CLAUDE_CODE),
+        Arguments.of("CLINE_ACTIVE", AgentDetector.CLINE),
+        Arguments.of("CODEX_CI", AgentDetector.CODEX),
+        Arguments.of("CURSOR_AGENT", AgentDetector.CURSOR),
+        Arguments.of("GEMINI_CLI", AgentDetector.GEMINI_CLI),
+        Arguments.of("OPENCODE", AgentDetector.OPEN_CODE));
+  }
+
+  @Test
+  void testReturnsEmptyWhenNoAgentDetected() {
+    Map<String, String> env = new HashMap<>();
+    assertTrue(AgentDetector.detect(envWith(env)).isEmpty());
+  }
+
+  @Test
+  void testReturnsEmptyWhenMultipleAgentsDetected() {
+    Map<String, String> env = new HashMap<>();
+    env.put("CLAUDECODE", "1");
+    env.put("CURSOR_AGENT", "1");
+    assertTrue(AgentDetector.detect(envWith(env)).isEmpty());
+  }
+
+  @Test
+  void testIgnoresEmptyEnvVarValues() {
+    Map<String, String> env = new HashMap<>();
+    env.put("CLAUDECODE", "");
+    assertTrue(AgentDetector.detect(envWith(env)).isEmpty());
+  }
+
+  @Test
+  void testIgnoresNullEnvVarValues() {
+    Map<String, String> env = new HashMap<>();
+    env.put("CLAUDECODE", null);
+    assertTrue(AgentDetector.detect(envWith(env)).isEmpty());
+  }
+
+  @Test
+  void testAllKnownAgentsAreCovered() {
+    // Verify every entry in KNOWN_AGENTS can be detected individually
+    for (String[] entry : AgentDetector.KNOWN_AGENTS) {
+      Map<String, String> env = new HashMap<>();
+      env.put(entry[0], "1");
+      assertEquals(
+          Optional.of(entry[1]),
+          AgentDetector.detect(envWith(env)),
+          "Agent with env var " + entry[0] + " should be detected as " + entry[1]);
+    }
+  }
+}