Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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"]
8 changes: 4 additions & 4 deletions cmd/root/root.go
Original file line number Diff line number Diff line change
Expand Up @@ -89,10 +89,10 @@ 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).
agents.MaybeHint(ctx, cmd, installer.GlobalPluginRecorded)

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] installer.WithCallingAgentToolingInUserAgent (root.go:88) already runs a.DatabricksTooling(ctx, GlobalPluginRecorded) for the same calling agent, and MaybeHint then runs it again (hint_agents.go:35-38). Users who have the tooling never get a throttle marker. So under these nine agents, every one of their commands reads the skills dir, walks the project dirs up to the repo root and reads the install state twice. The "check the throttle before the filesystem probe" ordering in MaybeHint doesn't save anything either, because the first probe has already run. Compute the Tooling once in PersistentPreRunE and pass it to both (e.g. MaybeHint(ctx, cmd, tooling)). That also makes PluginRecordedFunc and the GlobalPluginRecorded export unnecessary.

return nil
}

Expand Down
98 changes: 70 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,34 @@ 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 is the raw session id.
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.
durableThrottle bool
Comment on lines +109 to +123

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 +133,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,6 +145,9 @@ 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
}
}
Expand All @@ -146,12 +166,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 +191,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 @@ -266,29 +301,36 @@ 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 (Claude's key is the raw id and must not change), 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
60 changes: 60 additions & 0 deletions libs/aitools/agents/hint_agents.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
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.

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] .agents/rules/comments.md asks for a source reference URL when detecting environment variables. This comment names the codex-cli version but not where the variable is set. Please link the Codex source that exports CODEX_THREAD_ID, as hint.go does for the Claude hint format.

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.GlobalPluginRecorded).
type PluginRecordedFunc func(ctx context.Context, agentName string) bool

// agentInstallHint returns the hint for a non-Claude registry agent. The text
// keeps Claude Code's imperative wording (hintText) and names the agent and
// scope, so the install acts on the calling agent and never stops at the agent
// picker or the scope prompt when the agent's shell is a terminal.
Comment on lines +23 to +26

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] Agent callers never see the agent picker or the scope prompt anyway: installPromptsSupported (cmd/aitools/install.go:41-43) turns prompts off whenever AgentProvider() is set, and the non-interactive scope defaults to global. What --agents <name> actually does is target the calling agent, even when it isn't detected on the machine; --scope global only makes the default explicit. Could the comment say that instead?

//
// 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 with the agent's own CLI rather than `databricks aitools install`
// leaves no trace there for those two, so their users are hinted; the
// throttle bounds that to once per session or per TTL.
Comment on lines +28 to +32

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] The registry notes that Cursor has a Databricks plugin, which users install from Cursor itself because the CLI can't install it headlessly. Cursor has neither Plugin nor a manifest reader, so DatabricksTooling only looks at ~/.cursor/skills. A Cursor user who has that plugin (and no raw skills) is told "Databricks skills are not installed" every hour, and following the hint adds raw skills next to the plugin. OpenCode has a similar gap for skills it loads from Claude-compatible dirs such as ~/.claude/skills. Either detect where the Cursor plugin is installed, or at least name Cursor here and in the Merge Danger section, next to Codex and Copilot.

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.

return &agentHint{
installed: func(ctx context.Context) bool {
recorded := func() bool { return pluginRecorded(ctx, a.Name) }
return a.DatabricksTooling(ctx, recorded) != ToolingNone
},
text: "Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents " + a.Name + " --scope global",

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] This literal repeats hintText, whose comment says the wording should change only after thorough testing. The next wording change to hintText would leave the other nine agents on the old text. .agents/rules/style-guide-go.md asks to build on an existing constant in cases like this: 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