Skip to content
Merged
1 change: 1 addition & 0 deletions .nextchanges/cli/aitools-hint-other-agents.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
* When Codex, Cursor, GitHub Copilot CLI, OpenCode, Gemini CLI, Antigravity, Pi, Goose or Kiro run the CLI without Databricks skills installed for that agent, the CLI now prints a one-line hint to install them with `databricks aitools install --agents <agent> --scope global`, previously shown only to Claude Code. ([#7586](https://github.com/databricks/cli/pull/7586))
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
name: databricks-core
description: Fixture marking Databricks skills as installed for Gemini CLI.
---
1 change: 1 addition & 0 deletions acceptance/cmd/aitools/agent-hints/out.test.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Cloud = false
46 changes: 46 additions & 0 deletions acceptance/cmd/aitools/agent-hints/output.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@

=== Codex is hinted once per thread

>>> CODEX_CI=1 CODEX_THREAD_ID=thread-1 [CLI] version
Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents codex --scope global
Databricks CLI v[CLI_VERSION]

>>> CODEX_CI=1 CODEX_THREAD_ID=thread-1 [CLI] version
Databricks CLI v[CLI_VERSION]

>>> CODEX_CI=1 CODEX_THREAD_ID=thread-2 [CLI] version
Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents codex --scope global
Databricks CLI v[CLI_VERSION]

=== Cursor exposes no session id, so it is hinted once per machine

>>> CURSOR_AGENT=1 [CLI] version
Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents cursor --scope global
Databricks CLI v[CLI_VERSION]

>>> CURSOR_AGENT=1 [CLI] version
Databricks CLI v[CLI_VERSION]

=== Copilot CLI maps to the copilot registry agent

>>> COPILOT_CLI=1 [CLI] version
Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents copilot --scope global
Databricks CLI v[CLI_VERSION]

=== Gemini CLI with its own Databricks skills is not hinted

>>> GEMINI_CLI=1 [CLI] version
Databricks CLI v[CLI_VERSION]

=== Agents the CLI cannot install for are not hinted

>>> WINDSURF_AGENT=1 [CLI] version
Databricks CLI v[CLI_VERSION]

>>> VSCODE_AGENT=1 [CLI] version
Databricks CLI v[CLI_VERSION]

=== Nested agents are not hinted

>>> CODEX_CI=1 CURSOR_AGENT=1 CODEX_THREAD_ID=thread-3 [CLI] version
Databricks CLI v[CLI_VERSION]
27 changes: 27 additions & 0 deletions acceptance/cmd/aitools/agent-hints/script
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# aitools commands skip the install hint; version exercises it without auth or network.
sethome ./home
unset XDG_CONFIG_HOME GEMINI_CLI_HOME CODEX_THREAD_ID

title "Codex is hinted once per thread"
trace CODEX_CI=1 CODEX_THREAD_ID=thread-1 $CLI version
trace CODEX_CI=1 CODEX_THREAD_ID=thread-1 $CLI version
trace CODEX_CI=1 CODEX_THREAD_ID=thread-2 $CLI version

title "Cursor exposes no session id, so it is hinted once per machine"
trace CURSOR_AGENT=1 $CLI version
trace CURSOR_AGENT=1 $CLI version

title "Copilot CLI maps to the copilot registry agent"
trace COPILOT_CLI=1 $CLI version

title "Gemini CLI with its own Databricks skills is not hinted"
sethome ./gemini-home
trace GEMINI_CLI=1 $CLI version
sethome ./home

title "Agents the CLI cannot install for are not hinted"
trace WINDSURF_AGENT=1 $CLI version
trace VSCODE_AGENT=1 $CLI version

title "Nested agents are not hinted"
trace CODEX_CI=1 CURSOR_AGENT=1 CODEX_THREAD_ID=thread-3 $CLI version
3 changes: 3 additions & 0 deletions acceptance/cmd/aitools/agent-hints/test.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# The throttle markers live in the file cache, which a host could disable.
Env.DATABRICKS_CACHE_ENABLED = "true"
Ignore = ["home"]
7 changes: 7 additions & 0 deletions acceptance/cmd/version/output.txt
Original file line number Diff line number Diff line change
Expand Up @@ -41,3 +41,10 @@ Tip: coding agents detected without Databricks skills. Run 'databricks aitools i
Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install
Databricks CLI v[CLI_VERSION]
This is a development build; skipping the update check.

=== version --check from Codex prints only the root hint

>>> [CLI] version --check
Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents codex --scope global
Databricks CLI v[CLI_VERSION]
This is a development build; skipping the update check.
10 changes: 9 additions & 1 deletion acceptance/cmd/version/script
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,17 @@ trace $CLI version --check
title "version --check --output json with a coding agent prints no tip"
trace $CLI version --check --output json

# Claude Code callers get only the root hint (agents.MaybeHint), not the tip.
# Callers that agents.MaybeHint hints get only the root hint, not the tip.
title "version --check from Claude Code prints only the root hint"
sethome ./claude-home
export CLAUDECODE=1
unset CLAUDE_CODE_SESSION_ID
trace $CLI version --check
unset CLAUDECODE

title "version --check from Codex prints only the root hint"
sethome ./codex-home
export CODEX_CI=1
unset CODEX_THREAD_ID
trace $CLI version --check
unset CODEX_CI
11 changes: 7 additions & 4 deletions cmd/root/root.go
Original file line number Diff line number Diff line change
Expand Up @@ -89,10 +89,13 @@ func New(ctx context.Context) *cobra.Command {
ctx = InjectTestPidToUserAgent(ctx)
cmd.SetContext(ctx)

// Recommend installing Databricks AI tooling to Claude Code when it is
// driving the CLI without the tooling installed (best-effort: a stderr
// line and a telemetry event that is uploaded at exit).
agents.MaybeHint(ctx, cmd)
// Recommend installing Databricks AI tooling to the calling coding agent
// when it drives the CLI without the tooling installed (best-effort: a
// stderr line and a telemetry event that is uploaded at exit). Only the
// global install state is read, as for the calling-agent User-Agent.
agents.MaybeHint(ctx, cmd, func(ctx context.Context, agentName string) bool {
return installer.PluginRecorded(ctx, installer.ScopeGlobal, agentName)
})
return nil
}

Expand Down
106 changes: 78 additions & 28 deletions libs/aitools/agents/hint.go
Original file line number Diff line number Diff line change
Expand Up @@ -76,8 +76,8 @@ const (
// degrades to per-command.
claudeSessionEnv = "CLAUDE_CODE_SESSION_ID"

// hintCacheComponent names the cache bucket holding per-session "already
// hinted" markers.
// hintCacheComponent names the cache bucket holding "already hinted"
// markers (per session, or per agent on this machine).
hintCacheComponent = "aitools-hint"
)

Expand All @@ -94,17 +94,35 @@ type agentHint struct {
installed func(ctx context.Context) bool

// text is the model-facing recommendation, printed at most once per
// hintSessionTTL per session (see sessionEnv), together with native.
// hintSessionTTL per session (see sessionEnv), or per agent on this machine
// when there is no session id (see fallbackKey), together with native.
text string

// textKind tags the hint-shown event logged when text prints.
textKind protos.AitoolsHintKind

// sessionEnv names the env var carrying the agent's session id, which keys
// the throttle for both lines. Empty, or unset at runtime, means no
// throttle.
// the throttle for both lines. When it is empty or unset at runtime,
// fallbackKey keys the throttle instead.
sessionEnv string

// sessionKeyPrefix namespaces the session id in the throttle key, so one
// agent's marker never silences another agent that reuses the same id.
// Empty for Claude Code, whose key stays the raw session id so its
// throttle is unchanged.
sessionKeyPrefix string

// fallbackKey keys the throttle when there is no session id, so the hint
// prints at most once per hintSessionTTL on this machine. Empty means no
// throttle without a session id (Claude Code).
fallbackKey string

// durableThrottle prints the text only once its throttle marker is
// persisted (see claimHintMarker), so an unwritable cache can't turn the
// hint into a line on every command. False for Claude Code, whose marker
// write stays best-effort so its existing throttle behaviour is unchanged.
durableThrottle bool
Comment on lines +109 to +124

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nit] The throttleKey comment (hint.go:305) says Claude's key "is the raw id and must not change". But cache.NewCache stores markers under a per-CLI-version directory, and nothing else reads this bucket, so prefixing Claude's key would break nothing. With the same <agent>:session:<id> key for Claude, throttleKey could derive the prefix from the agent name, and sessionKeyPrefix could go. At minimum, the comment should drop that reason. The durableThrottle comment also has a stray line break ("False for" / "Claude Code").


// native returns a line the agent itself acts on (for Claude Code, its
// plugin install prompt), or "" when none applies to this invocation. It
// shares the text's per-session throttle. Nil for agents without one.
Expand All @@ -116,7 +134,7 @@ type agentHint struct {

// hintForAgent returns the hint for an agent, keyed by its
// useragent.AgentProvider() value, or nil when that agent is not hinted.
func hintForAgent(provider string) *agentHint {
func hintForAgent(provider string, pluginRecorded PluginRecordedFunc) *agentHint {
switch provider {
case claudeAgentProvider:
return &agentHint{
Expand All @@ -128,10 +146,21 @@ func hintForAgent(provider string) *agentHint {
nativeKind: protos.AitoolsHintKindClaudeCodeNative,
}
default:
if a := AgentForProvider(provider); a != nil {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nice to have] MaybeVersionCheckTip (libs/aitools/agents/recommend.go:33) still skips only Claude Code, on the grounds that "MaybeHint already covers them". This PR makes MaybeHint cover nine more agents but leaves that skip unchanged. So with CODEX_CI=1 (or CURSOR_AGENT=1, …), no Databricks tooling and ~/.codex present, databricks version --check prints the new … install --agents codex --scope global line from the root hook. It then prints Tip: … Run 'databricks aitools install'. That is two different commands in one run, and the tip isn't throttled. Skip the tip whenever the calling agent gets a root hint (hintForAgent(...) != nil, or CallingAgent() != nil), update that comment, and add a non-Claude case next to the Claude one in acceptance/cmd/version/script.

return agentInstallHint(a, pluginRecorded)
}
return nil
}
}

// isHintedAgent reports whether MaybeHint hints the agent with this
// useragent.AgentProvider() value. It defers to hintForAgent so both follow
// the same dispatch; pluginRecorded is only read when the hint's installed
// check runs, so none is needed here.
func isHintedAgent(provider string) bool {
return hintForAgent(provider, nil) != nil
}

// nativeLine returns the agent-native line due for this invocation, or "".
func (h *agentHint) nativeLine(ctx context.Context) string {
if h.native == nil {
Expand All @@ -146,12 +175,15 @@ func (h *agentHint) nativeLine(ctx context.Context) string {
// docker token` credential helpers, a CLI process the CLI started itself, when
// there is no output stream, and once the tooling is present.
// Both lines, the agent-native one (if any) and the model-facing text, and
// their hint-shown events are throttled together per session.
// their hint-shown events are throttled together per session, or per agent on
// this machine for agents without a session id (fallbackKey).
// pluginRecorded reads the CLI install record for agents whose plugin has no
// manifest reader here (see Agent.DatabricksTooling).
// Best-effort: it never fails the command. Besides the stderr lines, it logs a
// telemetry event for each hint line shown, which makes a command that resolved
// auth upload telemetry at exit.
func MaybeHint(ctx context.Context, cmd *cobra.Command) {
hint := hintForAgent(useragent.AgentProvider())
func MaybeHint(ctx context.Context, cmd *cobra.Command, pluginRecorded PluginRecordedFunc) {
hint := hintForAgent(useragent.AgentProvider(), pluginRecorded)
if hint == nil {
return
}
Expand All @@ -168,22 +200,34 @@ func MaybeHint(ctx context.Context, cmd *cobra.Command) {
return
}
// Check the throttle before the filesystem probe, so a throttled session
// skips the plugin/skills detection. The throttle token is written only
// after the hint prints, so an already-installed environment never burns
// it.
if alreadyHintedThisSession(ctx, hint.sessionEnv) {
// skips the plugin/skills detection. The marker is written only once a hint
// is due, so an already-installed environment never burns it.
key := hint.throttleKey(ctx)
if alreadyHintedThisSession(ctx, key) {
return
}
if hint.installed(ctx) {
return
}
if !hint.claim(ctx, key) {
return
}
if native := hint.nativeLine(ctx); native != "" {
cmdio.LogString(ctx, native)
logHintShown(ctx, hint.nativeKind)
}
cmdio.LogString(ctx, hint.text)
logHintShown(ctx, hint.textKind)
recordSessionHint(ctx, hint.sessionEnv)
}

// claim records the throttle key and reports whether the hint may print. A
// durable throttle allows it only once the marker has persisted.
func (h *agentHint) claim(ctx context.Context, key string) bool {
if h.durableThrottle {
return claimHintMarker(ctx, key)
}
recordSessionHint(ctx, key)
return true
}

// claudeNativeHintLine returns claudeNativeHint when Claude Code itself spawned
Expand Down Expand Up @@ -271,29 +315,35 @@ func claudeToolingInstalled(ctx context.Context) bool {
return tooling != ToolingNone
}

// alreadyHintedThisSession reports whether the session named by sessionEnv was
// hinted within the last hintSessionTTL. With no session id it returns false
// so the hint fires per command.
func alreadyHintedThisSession(ctx context.Context, sessionEnv string) bool {
session := sessionID(ctx, sessionEnv)
if session == "" {
// throttleKey returns the cache key throttling the hint: the session id behind
// sessionKeyPrefix, else fallbackKey. "" means no throttle.
func (h *agentHint) throttleKey(ctx context.Context) string {
if session := sessionID(ctx, h.sessionEnv); session != "" {
return h.sessionKeyPrefix + session
}
return h.fallbackKey
}

// alreadyHintedThisSession reports whether the throttle key was hinted within
// the last hintSessionTTL. With no key it returns false so the hint fires per
// command.
func alreadyHintedThisSession(ctx context.Context, key string) bool {
if key == "" {
return false
}
c := cache.NewCache(ctx, hintCacheComponent, hintSessionTTL, nil)
_, seen := cache.Get[bool](ctx, c, session)
_, seen := cache.Get[bool](ctx, c, key)
return seen
}

// recordSessionHint marks the session named by sessionEnv as hinted, so later
// commands in the same session stay quiet until the marker expires
// (hintSessionTTL). No-op when the session id is unset.
func recordSessionHint(ctx context.Context, sessionEnv string) {
session := sessionID(ctx, sessionEnv)
if session == "" {
// recordSessionHint marks the throttle key as hinted, so later commands stay
// quiet until the marker expires (hintSessionTTL). No-op when the key is "".
func recordSessionHint(ctx context.Context, key string) {
if key == "" {
return
}
c := cache.NewCache(ctx, hintCacheComponent, hintSessionTTL, nil)
cache.Put(ctx, c, session, true)
cache.Put(ctx, c, key, true)
}

// sessionID returns the value of sessionEnv, or "" when the agent has no
Expand Down
63 changes: 63 additions & 0 deletions libs/aitools/agents/hint_agents.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
package agents

import (
"context"

"github.com/databricks/cli/libs/cache"
"github.com/databricks/cli/libs/telemetry/protos"
)

// agentSessionEnv names the env var a non-Claude agent sets to a per-session id
// in the shells it spawns. Only verified variables are listed; an agent missing
// here is throttled per machine instead (see agentInstallHint).
var agentSessionEnv = map[string]string{
// Set by codex-cli (0.166.0) for every shell tool call, next to CODEX_CI:
// https://github.com/openai/codex/blob/main/codex-rs/core/src/exec_env.rs
NameCodex: "CODEX_THREAD_ID",
}

// PluginRecordedFunc reports whether the CLI install state records a
// databricks plugin install for the named agent. The installer package owns
// that state and provides it (installer.PluginRecorded for the global scope).
type PluginRecordedFunc func(ctx context.Context, agentName string) bool

// agentInstallHint returns the hint for a non-Claude registry agent. The text
// is hintText plus --agents and --scope. An agent caller never sees install's
// prompts (installPromptsSupported), so --agents is what matters: it targets
// the calling agent even when it isn't detected on this machine, instead of
// every detected one. --scope global only makes the non-interactive default
// explicit.
//
// The hint is gated on the agent's own tooling (Agent.DatabricksTooling, with
// pluginRecorded as the plugin source for Codex and Copilot). A plugin
// installed outside `databricks aitools install` (with the Codex or Copilot
// CLI, or from Cursor itself) leaves no trace there, so those users are
// hinted; the throttle bounds that to once per session or per TTL.
func agentInstallHint(a *Agent, pluginRecorded PluginRecordedFunc) *agentHint {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nice to have] For Codex and Copilot, --agents <name> without --skills-only takes the plugin path. When codex/copilot isn't on PATH (for example an IDE extension or desktop app that bundles its own binary), that path returns cli-not-on-path and exits non-zero, with no fallback to skills. Nothing gets recorded, so each new Codex thread is told again to "first run" the same failing command. The description lists this as a known risk. A cheap mitigation: when the hint is about to print, check exec.LookPath(a.Binary), and if it fails, hint --skills-only instead. That writes to the agent's own skills dir, so the hint stops afterwards.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good idea. Leaving it for a follow-up: it makes the hint text depend on PATH, and hintText is wording we only change after testing how agents react to it. Until then this stays listed under Merge Danger.

return &agentHint{
installed: func(ctx context.Context) bool {
recorded := func() bool { return pluginRecorded(ctx, a.Name) }
return a.DatabricksTooling(ctx, recorded) != ToolingNone
},
text: hintText + " --agents " + a.Name + " --scope global",
textKind: protos.AitoolsHintKindAgentInstallText,
sessionEnv: agentSessionEnv[a.Name],
sessionKeyPrefix: a.Name + ":session:",
fallbackKey: a.Name + ":machine",
durableThrottle: true,
}
}

// claimHintMarker writes the throttle marker to the user cache and reports
// whether it reads back. libs/cache silently drops writes it can't make (e.g.
// a read-only home in an agent sandbox), and without a kept marker the hint
// would repeat on every command, so the caller then skips it. A sandbox that
// can't write the user cache can't run the install either. The same holds with
// caching turned off (DATABRICKS_CACHE_ENABLED=false): nothing persists, so
// these agents get no hint.
func claimHintMarker(ctx context.Context, key string) bool {
c := cache.NewCache(ctx, hintCacheComponent, hintSessionTTL, nil)
cache.Put(ctx, c, key, true)
_, ok := cache.Get[bool](ctx, c, key)
return ok
}
Loading
Loading