Skip to content
Open
1 change: 1 addition & 0 deletions .nextchanges/cli/aitools-hint-exempt-commands.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
* Stop printing the Databricks AI tooling install hint on `auth`, `configure`, `current-user me`, `version`, `help`, and shell-completion commands. ([#7452](https://github.com/databricks/cli/pull/7452))
29 changes: 21 additions & 8 deletions acceptance/cmd/aitools/claude-config-dir/output.txt
Original file line number Diff line number Diff line change
@@ -1,21 +1,34 @@

=== Plugin installed only in the custom config directory

>>> CLAUDE_CONFIG_DIR=custom [CLI] version
Databricks CLI v[CLI_VERSION]
>>> CLAUDE_CONFIG_DIR=custom [CLI] clusters list
ID Name State
4321 some-test-cluster
9876 some-other-cluster

=== Custom directory takes precedence over the default installation

>>> CLAUDE_CONFIG_DIR=missing [CLI] version
>>> CLAUDE_CONFIG_DIR=missing [CLI] clusters list
Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install
Databricks CLI v[CLI_VERSION]
ID Name State
4321 some-test-cluster
9876 some-other-cluster

=== Exempt commands never hint, even without the tooling

>>> CLAUDE_CONFIG_DIR=missing [CLI] current-user me
"[USERNAME]"

=== Empty override uses the default installation

>>> CLAUDE_CONFIG_DIR= [CLI] version
Databricks CLI v[CLI_VERSION]
>>> CLAUDE_CONFIG_DIR= [CLI] clusters list
ID Name State
4321 some-test-cluster
9876 some-other-cluster

=== Unset override uses the default installation

>>> [CLI] version
Databricks CLI v[CLI_VERSION]
>>> [CLI] clusters list
ID Name State
4321 some-test-cluster
9876 some-other-cluster
14 changes: 9 additions & 5 deletions acceptance/cmd/aitools/claude-config-dir/script
Original file line number Diff line number Diff line change
@@ -1,18 +1,22 @@
export CLAUDECODE=1
unset CLAUDE_CODE_SESSION_ID

# aitools commands skip the install hint; version exercises it without auth or network.
# Hint-exempt commands (aitools, auth, one-shot lookups such as version and current-user me,
# completion) skip the install hint; clusters list exercises it against the fake server.
sethome ./empty-home
title "Plugin installed only in the custom config directory"
trace CLAUDE_CONFIG_DIR=custom $CLI version
trace CLAUDE_CONFIG_DIR=custom $CLI clusters list

sethome ./installed-home
title "Custom directory takes precedence over the default installation"
trace CLAUDE_CONFIG_DIR=missing $CLI version
trace CLAUDE_CONFIG_DIR=missing $CLI clusters list

title "Exempt commands never hint, even without the tooling"
trace CLAUDE_CONFIG_DIR=missing $CLI current-user me | jq .userName

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 step pulls one field with inline jq .userName, but .agents/rules/testing.md prefers gron.py | grep <field> for single-value lookups, because gron prints the JSON path into the golden output. Consider trace CLAUDE_CONFIG_DIR=missing $CLI current-user me | gron.py | grep userName.


title "Empty override uses the default installation"
trace CLAUDE_CONFIG_DIR= $CLI version
trace CLAUDE_CONFIG_DIR= $CLI clusters list

title "Unset override uses the default installation"
unset CLAUDE_CONFIG_DIR
trace $CLI version
trace $CLI clusters list
48 changes: 33 additions & 15 deletions libs/aitools/agents/hint.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ package agents
import (
"context"
"path/filepath"
"strings"
"time"

"github.com/databricks/cli/libs/cache"
Expand All @@ -25,11 +26,6 @@ const (
// https://github.com/databricks/databricks-sdk-go/blob/main/useragent/agent.go
claudeAgentProvider = "claude-code"

// aiToolsCommandName is the top-level command whose subtree is never hinted:
// telling the agent to run `databricks aitools install` while it is already
// running an aitools command makes no sense.
aiToolsCommandName = "aitools"

// claudeSessionEnv is Claude Code's per-session identifier. It keys the
// per-session throttle (at most one hint per hintSessionTTL per session);
// when unset (older Claude) the hint degrades to per-command.
Expand All @@ -47,15 +43,15 @@ const hintSessionTTL = time.Hour

// MaybeHint prints a one-line recommendation to install the Databricks AI
// tooling when Claude Code drives the CLI without it installed. It is a no-op
// for human callers, other agents, aitools commands themselves, when there is
// no output stream, once the tooling is present, and when the session was
// hinted within the last hintSessionTTL. Best-effort: it writes only to stderr
// and never fails the command.
// for human callers, other agents, hint-exempt commands (isHintExemptCommand),
// when there is no output stream, once the tooling is present, and when the
// session was hinted within the last hintSessionTTL. Best-effort: it writes
// only to stderr and never fails the command.
func MaybeHint(ctx context.Context, cmd *cobra.Command) {
if useragent.AgentProvider() != claudeAgentProvider {
return
}
if isAIToolsCommand(cmd) {
if isHintExemptCommand(cmd) {
return
}
if !cmdio.HasIO(ctx) {
Expand All @@ -75,11 +71,33 @@ func MaybeHint(ctx context.Context, cmd *cobra.Command) {
recordSessionHint(ctx)
}

// isAIToolsCommand reports whether cmd is the aitools command or one of its
// subcommands, walking the parent chain (mirrors versioncheck.isExemptCommand).
func isAIToolsCommand(cmd *cobra.Command) bool {
for c := cmd; c != nil; c = c.Parent() {
if c.Name() == aiToolsCommandName {
// hintExemptCommands are the commands, with their subcommands, on which no
// tooling hint prints. Paths are relative to the root command. The aitools
// trees are exempt because telling the agent to run aitools while it already
// runs aitools makes no sense. The rest are plumbing or one-shot lookups (auth
// checks, "who am I", version, help, shell completion): the agent has no task to apply

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 line of the hintExemptCommands doc comment is 87 characters, while the lines around it wrap near 78, so the paragraph reads raggedly ("...(auth" / "checks, ... to apply" / "the skills to."). It looks like it wasn't reflowed after version was added. Please re-wrap the paragraph to the same width as the rest of the comment.

// the skills to. Evaluations showed that conversion on these commands is low,
// so a hint on them wastes the prompt.
var hintExemptCommands = []string{

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 entries in hintExemptCommands are hard-coded path strings, and TestIsHintExemptCommand builds fake trees with commandAt. Nothing checks that each path exists in the real CLI. If codegen renames current-user/me, or an aitools command moves, the exemption silently stops matching and the unit tests still pass; only the single current-user me acceptance step would catch it. Consider adding a test in an external package (or under cmd/) that builds cmd.New(ctx), resolves each entry with Find(strings.Fields(p)), and asserts an exact match.

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.

I'd rather not add this one. current-user me is the only generated entry, and the claude-config-dir step already runs it against the real tree; the rest are hand-written commands or cobra constants. The test would also need special cases for cobra's lazily registered help and __complete, and with the predicate now package-private it would have to live in the agents test binary and pull in cmd. Happy to revisit if you feel strongly.

"aitools",
"experimental aitools",
"auth",
"configure",
"current-user me",
"version",
"completion",
"help",
cobra.ShellCompRequestCmd,
}

// isHintExemptCommand reports whether cmd is one of hintExemptCommands or a
// subcommand of one.
func isHintExemptCommand(cmd *cobra.Command) bool {
path := cmd.CommandPath()
root := cmd.Root().CommandPath()
for _, exempt := range hintExemptCommands {
full := root + " " + exempt
if path == full || strings.HasPrefix(path, full+" ") {
return true
}
}
Expand Down
48 changes: 42 additions & 6 deletions libs/aitools/agents/hint_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import (
"log/slog"
"os"
"path/filepath"
"strings"
"testing"

"github.com/databricks/cli/libs/cmdio"
Expand Down Expand Up @@ -60,7 +61,7 @@ func claudeCtx(t *testing.T, home string) (context.Context, *bytes.Buffer) {
return ctx, stderr
}

func regularCmd() *cobra.Command { return &cobra.Command{Use: "current-user"} }
func regularCmd() *cobra.Command { return commandAt("clusters list") }

func writePluginManifest(t *testing.T, home, body string) {
dir := filepath.Join(home, ".claude", "plugins")
Expand Down Expand Up @@ -192,14 +193,49 @@ func TestMaybeHint_AIToolsCommandSilent(t *testing.T) {
setClaudeAgent(t)
ctx, stderr := claudeCtx(t, t.TempDir())

parent := &cobra.Command{Use: aiToolsCommandName}
child := &cobra.Command{Use: "install"}
parent.AddCommand(child)

MaybeHint(ctx, child)
MaybeHint(ctx, commandAt("aitools install"))

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] regularCmd() (line 64) returns a parentless current-user command, so under the new path logic its path is "". The tests that expect a hint pass because the path is empty, not because a real non-exempt command is used. Now that commandAt exists, have regularCmd() return something like commandAt("clusters list") so those tests exercise a realistic non-exempt path.

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.

Done in 3238771, it is commandAt("clusters list") now.

assert.Empty(t, stderr.String())
}

// commandAt builds a command tree under a "databricks" root and returns the
// command at the space-separated path, e.g. "current-user me".
func commandAt(path string) *cobra.Command {
cmd := &cobra.Command{Use: "databricks"}
for name := range strings.FieldsSeq(path) {
child := &cobra.Command{Use: name}
cmd.AddCommand(child)
cmd = child
}
return cmd
}

func TestIsHintExemptCommand(t *testing.T) {

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] If strings.HasPrefix(path, exempt+" ") is changed to strings.HasPrefix(path, exempt), every case in TestIsHintExemptCommand still passes. A future top-level command like authz or helpers would then be exempted by mistake. Add a negative case such as {"authz", false} or {"current-user meh", false}.

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.

Added authz in 3238771.

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] No case in the table puts an exempt name under a non-exempt parent. If the matching went back to the old walk that compares Name() at any depth, every current case, including authz and current-user, would still pass. Add a case such as {"bundle help", false} or {"clusters version", false} so that regression fails.

tests := []struct {
path string
want bool
}{
{"aitools install", true},
{"experimental aitools skills install", true},
{"auth login", true},
{"auth token", true},
{"configure", true},
{"current-user me", true},
{"completion bash", true},
{"help", true},
{cobra.ShellCompRequestCmd, true},
{"version", true},
{"authz", false},
{"current-user", false},
{"clusters list", false},
{"jobs run-now", false},
}
for _, tc := range tests {
t.Run(tc.path, func(t *testing.T) {
assert.Equal(t, tc.want, isHintExemptCommand(commandAt(tc.path)))
})
}
}

func TestMaybeHint_NoIONoPanic(t *testing.T) {
setClaudeAgent(t)
// Bare context without cmdio installed: cobra resolves --help and bare
Expand Down
Loading