From 07a831d8a446409681b2c3d1349187444e2ac034 Mon Sep 17 00:00:00 2001 From: Anton Nekipelov <226657+anton-107@users.noreply.github.com> Date: Fri, 13 Nov 2026 05:53:37 +0000 Subject: [PATCH 1/6] aitools: emit Claude Code's native plugin install hint When Claude Code runs the CLI without the Databricks plugin or skills, the install hint now also prints Claude Code's native `` line (https://code.claude.com/docs/en/plugins/cli-hints), which makes Claude Code offer a one-click install of `databricks@claude-plugins-official`. - The native line prints only when CLAUDE_CODE_CHILD_SESSION is set, outside CI, and when no standard stream is a terminal. It shares the text hint's per-session throttle and logs a CLAUDE_CODE_NATIVE hint event. - Only tooling Claude Code itself loads (Agent.DatabricksTooling) silences the hint; skills only in the shared ~/.databricks stores no longer do. - `auth token`, `auth docker token` and CLI processes started by the CLI (DATABRICKS_CLI_SELF_EXEC, set by `air images push` and `apps init`) print no install hint. - `cmdio.HasTerminal` (any standard stream is a TTY) and `cmdio.FakeTTYReader` for tests. - Telemetry docs: one `aitools_hint_event` per printed hint line. Co-authored-by: Isaac --- .nextchanges/cli/claude-code-native-hint.md | 1 + acceptance/acceptance_test.go | 4 + acceptance/air/image-push/output.txt | 24 ++ acceptance/air/image-push/script | 19 + .../cmd/aitools/claude-config-dir/output.txt | 17 + .../cmd/aitools/claude-config-dir/script | 17 + .../cmd/aitools/telemetry/hint/output.txt | 5 +- acceptance/cmd/aitools/telemetry/hint/script | 6 +- cmd/air/image.go | 2 + cmd/apps/init.go | 2 + libs/aitools/agents/calling.go | 4 +- libs/aitools/agents/hint.go | 255 +++++++++-- libs/aitools/agents/hint_test.go | 407 +++++++++++++++++- libs/cmdio/io.go | 7 + libs/cmdio/io_test.go | 30 ++ libs/cmdio/tty.go | 14 + libs/cmdio/tty_test.go | 12 + libs/telemetry/protos/README.md | 10 +- libs/telemetry/protos/aitools_events.go | 22 +- 19 files changed, 785 insertions(+), 73 deletions(-) create mode 100644 .nextchanges/cli/claude-code-native-hint.md diff --git a/.nextchanges/cli/claude-code-native-hint.md b/.nextchanges/cli/claude-code-native-hint.md new file mode 100644 index 00000000000..64e8dfec9cb --- /dev/null +++ b/.nextchanges/cli/claude-code-native-hint.md @@ -0,0 +1 @@ +* When Claude Code runs the CLI without the Databricks plugin or skills, the CLI now also prints Claude Code's native `` line, at most once per hour per Claude Code session together with the text hint, so Claude Code offers a one-click install of the Databricks plugin. Skills stored only in `~/.databricks/aitools/skills` or the legacy `~/.databricks/agent-skills` no longer count as installed for Claude Code, and `databricks auth token`, `databricks auth docker token` and the CLI commands that `databricks air images push` and `databricks apps init` run as subprocesses no longer print install hints. ([#7585](https://github.com/databricks/cli/pull/7585)) diff --git a/acceptance/acceptance_test.go b/acceptance/acceptance_test.go index 74ab59d4419..3cdea48bddf 100644 --- a/acceptance/acceptance_test.go +++ b/acceptance/acceptance_test.go @@ -282,6 +282,10 @@ func testAccept(t *testing.T, inprocessMode bool, selectedTests []string, skipTo os.Unsetenv(v) //nolint:usetesting // t.Setenv cannot unset } + // Claude Code sets this in the commands it runs; it enables the native + // line, so a host Claude Code session must not leak it. + os.Unsetenv("CLAUDE_CODE_CHILD_SESSION") //nolint:usetesting // t.Setenv cannot unset + // environments setup-local follows uv's UV_PROJECT_ENVIRONMENT, so a value // from the host shell would move the venv the localenv tests expect. os.Unsetenv("UV_PROJECT_ENVIRONMENT") //nolint:usetesting // t.Setenv cannot unset diff --git a/acceptance/air/image-push/output.txt b/acceptance/air/image-push/output.txt index 7f2dce10ac9..d4805f2f58f 100644 --- a/acceptance/air/image-push/output.txt +++ b/acceptance/air/image-push/output.txt @@ -213,3 +213,27 @@ image inspect --format {{.Os}}/{{.Architecture}} example/image:v1 pull --platform linux/amd64 example/image:v1 image inspect --format {{.Os}}/{{.Architecture}} example/image:v1 pull --platform linux/amd64 example/image:v1 + +=== in a Claude Code session the auth docker configure child adds no install hint + +>>> databricks air images push -p docker-test -s example/image:v1 --catalog main --schema training + +Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install +Warning: This feature is in Preview. APIs may change, and the workspace must enable the Preview features. +Pushing example/image:v1 as main.training.image:v1 using profile docker-test +Configured Docker credential helper for [WORKSPACE_ID].container.us-west-2.localhost +Updated Docker config: [TEST_TMP_DIR]/home/docker/config.json +Installed Docker credential helper: [TEST_TMP_DIR]/home/bin/docker-credential-databricks +Using local source image example/image:v1 +Tagging image as [WORKSPACE_ID].container.us-west-2.localhost/main.training.image:v1 +Pushing image to [WORKSPACE_ID].container.us-west-2.localhost/main.training.image:v1 +Docker push progress +Pushed image. +Now you can set `environment.unity_catalog_image = main.training.image:v1` in your YAML config and create a workload with `databricks air run -f config.yaml`. + +>>> musterr databricks air images push -p pat-test -s example/image:v1 --catalog main --schema training + +Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install +Warning: This feature is in Preview. APIs may change, and the workspace must enable the Preview features. +Pushing example/image:v1 as main.training.image:v1 using profile pat-test +Error: configure Docker authentication: run auth docker configure: exit status 1: Error: profile "pat-test" uses auth_type "pat". Docker credential helper requires a profile created by databricks auth login diff --git a/acceptance/air/image-push/script b/acceptance/air/image-push/script index 4863b27b366..86e0c4ccf69 100644 --- a/acceptance/air/image-push/script +++ b/acceptance/air/image-push/script @@ -61,3 +61,22 @@ cmp "$DOCKER_LOG" "$HOME/docker.before-length.log" title "all docker commands" cat "$DOCKER_LOG" + +title "in a Claude Code session the auth docker configure child adds no install hint" +# As in a Claude Code tool call, with no session id, so the session throttle +# can't be what keeps the child quiet. The CI variables would drop the native +# line in CI only. +unset CI GITHUB_ACTIONS GITLAB_CI JENKINS_URL TF_BUILD CIRCLECI TRAVIS BITBUCKET_BUILD_NUMBER PROJECT_ID CODEBUILD_BUILD_ARN TFC_RUN_ID CLAUDE_CODE_SESSION_ID +# A host CLAUDE_CONFIG_DIR would move the plugin lookup away from the isolated HOME. +unset CLAUDE_CONFIG_DIR +export CLAUDECODE=1 CLAUDE_CODE_CHILD_SESSION=1 +trace databricks air images push -p docker-test -s example/image:v1 --catalog main --schema training +cat >> "$HOME/.databrickscfg" <>> CLAUDE_CONFIG_DIR=missing [CLI] version + Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install Databricks CLI v[CLI_VERSION] @@ -19,3 +20,19 @@ Databricks CLI v[CLI_VERSION] >>> [CLI] version Databricks CLI v[CLI_VERSION] + +=== Outside a Claude Code subprocess only the text hint prints + +>>> CLAUDE_CODE_CHILD_SESSION= [CLI] version +Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install +Databricks CLI v[CLI_VERSION] + +=== Within one session both lines print once, so 2>&1 pipelines see them only on the first command + +>>> [CLI] version + +Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install +Databricks CLI v[CLI_VERSION] + +>>> [CLI] version +Databricks CLI v[CLI_VERSION] diff --git a/acceptance/cmd/aitools/claude-config-dir/script b/acceptance/cmd/aitools/claude-config-dir/script index 26f51369813..ce77b7d518a 100644 --- a/acceptance/cmd/aitools/claude-config-dir/script +++ b/acceptance/cmd/aitools/claude-config-dir/script @@ -1,5 +1,10 @@ export CLAUDECODE=1 +# Claude Code sets CLAUDE_CODE_CHILD_SESSION in the commands it runs, which +# enables the native line; CI suppresses it. +export CLAUDE_CODE_CHILD_SESSION=1 unset CLAUDE_CODE_SESSION_ID +# CI and the CI/CD provider markers the SDK detects (GitHub Actions sets both). +unset CI GITHUB_ACTIONS GITLAB_CI JENKINS_URL TF_BUILD CIRCLECI TRAVIS BITBUCKET_BUILD_NUMBER PROJECT_ID CODEBUILD_BUILD_ARN TFC_RUN_ID # aitools commands skip the install hint; version exercises it without auth or network. sethome ./empty-home @@ -16,3 +21,15 @@ trace CLAUDE_CONFIG_DIR= $CLI version title "Unset override uses the default installation" unset CLAUDE_CONFIG_DIR trace $CLI version + +sethome ./empty-home +title "Outside a Claude Code subprocess only the text hint prints" +trace CLAUDE_CODE_CHILD_SESSION= $CLI version + +# The session throttle lives in the file cache, which a host could disable. +export DATABRICKS_CACHE_ENABLED=true +title "Within one session both lines print once, so 2>&1 pipelines see them only on the first command" +export CLAUDE_CODE_SESSION_ID=session-1 +trace $CLI version +trace $CLI version +unset CLAUDE_CODE_SESSION_ID diff --git a/acceptance/cmd/aitools/telemetry/hint/output.txt b/acceptance/cmd/aitools/telemetry/hint/output.txt index 1283eb52109..0cf25cd970e 100644 --- a/acceptance/cmd/aitools/telemetry/hint/output.txt +++ b/acceptance/cmd/aitools/telemetry/hint/output.txt @@ -1,15 +1,18 @@ -=== hint printed on an authenticated command: one hint-shown event is uploaded +=== hint printed on an authenticated command: one hint-shown event per printed line is uploaded >>> [CLI] jobs list + Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install >>> print_telemetry +{"command":"jobs_list","exit_code":0,"aitools_hint_event":{"hint_kind":"CLAUDE_CODE_NATIVE"}} {"command":"jobs_list","exit_code":0,"aitools_hint_event":{"hint_kind":"INSTALL_TEXT"}} === hint printed on a command that resolves no auth: nothing is uploaded >>> [CLI] version + Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install Databricks CLI v[CLI_VERSION] diff --git a/acceptance/cmd/aitools/telemetry/hint/script b/acceptance/cmd/aitools/telemetry/hint/script index 1289a90535e..4aa3253b9f1 100644 --- a/acceptance/cmd/aitools/telemetry/hint/script +++ b/acceptance/cmd/aitools/telemetry/hint/script @@ -1,11 +1,15 @@ # Isolate HOME so the real machine's plugins and skills are not seen. sethome home export CLAUDECODE=1 +# As inside Claude Code: enables the native line (not in CI). +export CLAUDE_CODE_CHILD_SESSION=1 +# CI and the CI/CD provider markers the SDK detects (GitHub Actions sets both). +unset CI GITHUB_ACTIONS GITLAB_CI JENKINS_URL TF_BUILD CIRCLECI TRAVIS BITBUCKET_BUILD_NUMBER PROJECT_ID CODEBUILD_BUILD_ARN TFC_RUN_ID unset CLAUDE_CODE_SESSION_ID # A host CLAUDE_CONFIG_DIR would move the plugin file away from the isolated HOME. unset CLAUDE_CONFIG_DIR -title "hint printed on an authenticated command: one hint-shown event is uploaded" +title "hint printed on an authenticated command: one hint-shown event per printed line is uploaded" trace $CLI jobs list trace print_telemetry diff --git a/cmd/air/image.go b/cmd/air/image.go index 72003f33c91..68bd8d0e9ca 100644 --- a/cmd/air/image.go +++ b/cmd/air/image.go @@ -13,6 +13,7 @@ import ( "sync" "github.com/databricks/cli/cmd/root" + "github.com/databricks/cli/libs/aitools/agents" "github.com/databricks/cli/libs/cmdctx" "github.com/databricks/cli/libs/cmdio" "github.com/databricks/cli/libs/flags" @@ -72,6 +73,7 @@ func configureImageDocker(ctx context.Context, profile string) (string, error) { var output bytes.Buffer cmd := exec.CommandContext(ctx, executable, "auth", "docker", "configure", profile) + cmd.Env = agents.SelfExecEnv(os.Environ()) cmd.Stdout = &output cmd.Stderr = &output if err := cmd.Run(); err != nil { diff --git a/cmd/apps/init.go b/cmd/apps/init.go index 6c02d9879dc..ed79271d25f 100644 --- a/cmd/apps/init.go +++ b/cmd/apps/init.go @@ -1964,6 +1964,7 @@ func runPostCreateDeploy(ctx context.Context, profile string) error { args = append(args, "--profile", profile) } cmd := exec.CommandContext(ctx, executable, args...) + cmd.Env = agents.SelfExecEnv(os.Environ()) cmd.Stdout = os.Stdout cmd.Stderr = os.Stderr cmd.Stdin = os.Stdin @@ -1992,6 +1993,7 @@ func runPostCreateDev(ctx context.Context, mode prompt.RunMode, projectInit init args = append(args, "--profile", profile) } cmd := exec.CommandContext(ctx, executable, args...) + cmd.Env = agents.SelfExecEnv(os.Environ()) cmd.Stdout = os.Stdout cmd.Stderr = os.Stderr cmd.Stdin = os.Stdin diff --git a/libs/aitools/agents/calling.go b/libs/aitools/agents/calling.go index 6e91d7fc9f1..4dcf73d6c6f 100644 --- a/libs/aitools/agents/calling.go +++ b/libs/aitools/agents/calling.go @@ -62,8 +62,8 @@ func (t Tooling) String() string { // record. For Codex and Copilot, pluginRecorded (the CLI install state) is the // only plugin source, so it misses plugins installed with the agent's own CLI // and includes plugins later removed with it. The shared skills store is not consulted: it cannot attribute skills. -// The install hint's claudeToolingInstalled differs on purpose: it stays quiet -// for any trace of an install, while this reports what the agent loads. +// The install hint uses it too, so Claude Code is hinted exactly when it loads +// no Databricks tooling. func (a *Agent) DatabricksTooling(ctx context.Context, pluginRecorded func() bool) Tooling { // An unknown working directory skips the project lookups below. cwd := "" diff --git a/libs/aitools/agents/hint.go b/libs/aitools/agents/hint.go index b37bcd6060c..dce48cd4503 100644 --- a/libs/aitools/agents/hint.go +++ b/libs/aitools/agents/hint.go @@ -2,6 +2,7 @@ package agents import ( "context" + "strconv" "time" "github.com/databricks/cli/libs/cache" @@ -21,19 +22,58 @@ const ( hintText = "Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install" // claudeAgentProvider is the useragent.AgentProvider() value for Claude Code. - // The SDK maps the CLAUDECODE env var to this product name. The hint is - // Claude-only for now (detection reads Claude's own on-disk state). + // The SDK maps the CLAUDECODE env var to this product name. // https://github.com/databricks/databricks-sdk-go/blob/main/useragent/agent.go claudeAgentProvider = "claude-code" + // claudeNativeHint makes Claude Code offer the user a one-click install of + // the Databricks plugin. Claude Code strips the line before the model sees + // the output and decides when to prompt: only in an attended interactive + // session, at most once per session, and once ever per plugin for that + // Claude Code user config (so in practice once per machine), whatever the + // answer. It is still throttled with the text hint: Claude Code strips it + // only from the tool output, so in a `2>&1 | jq` pipeline the next process + // reads it raw, and after a "No" repeating it can't lead to an install. The + // format is fixed by Claude Code: https://code.claude.com/docs/en/plugins/cli-hints + claudeNativeHint = `` + + // claudeChildSessionEnv is set only in subprocesses Claude Code itself + // spawns (v2.1.172+). Unlike CLAUDECODE, IDE extensions don't set it in + // their integrated terminals, so gating the native hint on it keeps the raw + // tag away from humans, who would see it unstripped. + claudeChildSessionEnv = "CLAUDE_CODE_CHILD_SESSION" + + // ciEnv is the generic CI marker. Together with the SDK's CI/CD provider + // detection it keeps the native hint out of CI: Claude Code never prompts in + // unattended runs. + ciEnv = "CI" + // 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" + // authCommandName and tokenCommandName name `databricks auth token`, the + // credential helper the SDKs and Terraform run. They embed its stderr + // mid-line in their own errors, where Claude Code can't strip the native + // line and neither hint is addressed to anyone, so it is never hinted. + authCommandName = "auth" + tokenCommandName = "token" + + // dockerCommandName names `databricks auth docker token`, which Docker runs + // through docker-credential-databricks and treats the same way. + dockerCommandName = "docker" + + // selfExecEnv marks a CLI process that the CLI itself started (see + // SelfExecEnv). Its output goes to the parent CLI, which already hinted + // if a hint was due and may embed that output mid-line in its own errors, + // where Claude Code can't strip the native line. + selfExecEnv = "DATABRICKS_CLI_SELF_EXEC" + // 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. + // per-session throttle shared by the text and native lines (at most one + // hint per hintSessionTTL per session); when unset (older Claude) the hint + // degrades to per-command. claudeSessionEnv = "CLAUDE_CODE_SESSION_ID" // hintCacheComponent names the cache bucket holding per-session "already @@ -46,36 +86,150 @@ const ( // fire again for the same session. 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 never fails the -// command. Besides the stderr line, it logs a telemetry event for each hint -// shown, which makes a command that resolved auth upload telemetry at exit. +// agentHint describes how one calling agent is nudged to install the +// Databricks AI tooling. +type agentHint struct { + // installed reports whether the agent already has the tooling; when it + // does, nothing is printed. + 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. + 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. + sessionEnv string + + // 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. + native func(ctx context.Context) string + + // nativeKind tags the hint-shown event logged when the native line prints. + nativeKind protos.AitoolsHintKind +} + +// 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 { + switch provider { + case claudeAgentProvider: + return &agentHint{ + installed: claudeToolingInstalled, + text: hintText, + textKind: protos.AitoolsHintKindInstallText, + sessionEnv: claudeSessionEnv, + native: claudeNativeHintLine, + nativeKind: protos.AitoolsHintKindClaudeCodeNative, + } + default: + return nil + } +} + +// nativeLine returns the agent-native line due for this invocation, or "". +func (h *agentHint) nativeLine(ctx context.Context) string { + if h.native == nil { + return "" + } + return h.native(ctx) +} + +// MaybeHint recommends installing the Databricks AI tooling when a supported +// agent drives the CLI without it installed. It is a no-op for human callers, +// unsupported agents, aitools commands themselves, the `auth token` and `auth +// 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. +// 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) { - if useragent.AgentProvider() != claudeAgentProvider { + hint := hintForAgent(useragent.AgentProvider()) + if hint == nil { return } if isAIToolsCommand(cmd) { return } + if isCredentialHelperCommand(cmd) { + return + } + if env.Get(ctx, selfExecEnv) != "" { + return + } if !cmdio.HasIO(ctx) { return } - // Check the session throttle before the filesystem probe: once a session has - // been hinted, later commands short-circuit here and skip the plugin/skills - // detection. The throttle token is written only after a hint prints (below), - // so an already-installed environment never burns it. - if alreadyHintedThisSession(ctx) { + // 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) { return } - if claudeToolingInstalled(ctx) { + if hint.installed(ctx) { return } - cmdio.LogString(ctx, hintText) - logHintShown(ctx, protos.AitoolsHintKindInstallText) - recordSessionHint(ctx) + 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) +} + +// claudeNativeHintLine returns claudeNativeHint when Claude Code itself spawned +// this process outside CI and no standard stream is a terminal, and "" +// otherwise. +// +// Claude Code runs its tools with no terminal (stdin from /dev/null, output +// captured) and strips the tag from the captured output. tmux, screen or a +// shell started from inside Claude Code inherit claudeChildSessionEnv, and +// nothing strips the tag there. A person typing in one has the terminal on +// stdin even when the output goes through a pipe (`2>&1 | less`), so any +// terminal means a human may read the tag raw. +func claudeNativeHintLine(ctx context.Context) string { + if env.Get(ctx, claudeChildSessionEnv) == "" || inCI(ctx) { + return "" + } + if cmdio.HasTerminal(ctx) { + return "" + } + return claudeNativeHint +} + +// inCI reports whether the CLI runs in CI: the generic CI variable set to +// anything but an explicit false (some providers set it to their own name), or +// any provider the SDK detects for its user agent (e.g. Azure Pipelines' +// TF_BUILD, which doesn't set CI). +func inCI(ctx context.Context) bool { + if v := env.Get(ctx, ciEnv); v != "" { + if b, err := strconv.ParseBool(v); err != nil || b { + return true + } + } + return useragent.CiCdProvider() != "" +} + +// isCredentialHelperCommand reports whether cmd is `databricks auth token` or +// `databricks auth docker token`. +func isCredentialHelperCommand(cmd *cobra.Command) bool { + if cmd.Name() != tokenCommandName { + return false + } + parent := cmd.Parent() + if parent != nil && parent.Name() == dockerCommandName { + parent = parent.Parent() + } + return parent != nil && parent.Name() == authCommandName } // isAIToolsCommand reports whether cmd is the aitools command or one of its @@ -89,15 +243,12 @@ func isAIToolsCommand(cmd *cobra.Command) bool { return false } -// claudeToolingInstalled reports whether Databricks AI tooling is present for -// Claude Code. It checks two signals: the databricks plugin in Claude's own -// plugin manifest (written both by `databricks aitools install` and by a direct -// `claude plugin install`), and databricks skill files in the shared canonical -// skills dir (written by `aitools install --skills-only`). Any read/parse -// failure reports false, so an unreadable state errs toward hinting. -// (*Agent).DatabricksTooling, which feeds the User-Agent, differs on purpose: -// it ignores the shared store and out-of-project records, and counts -// .claude/skills dirs, to report what the calling agent loads. +// claudeToolingInstalled reports whether Claude Code has Databricks AI tooling +// in its own locations (see Agent.DatabricksTooling): the databricks plugin, or +// databricks skills in Claude's skills dirs. Skills present only in the shared +// ~/.databricks/aitools/skills store don't count, because Claude Code doesn't +// load them from there. Any read/parse failure reports false, so an unreadable +// state errs toward hinting. func claudeToolingInstalled(ctx context.Context) bool { claude := ByName(NameClaudeCode) if claude == nil { @@ -105,22 +256,21 @@ func claudeToolingInstalled(ctx context.Context) bool { // best-effort rather than panicking in a persistent pre-run hook. return false } - if version, ok := claude.DatabricksPluginVersion(ctx); ok { + // Claude Code's own manifest decides, so the CLI's install record is never + // consulted for it. + tooling := claude.DatabricksTooling(ctx, func() bool { return false }) + if tooling == ToolingPlugin { + version, _ := claude.DatabricksPluginVersion(ctx) log.Debugf(ctx, "Databricks plugin detected for Claude Code (version %q); skipping install hint", version) - return true } - - // The canonical dir always holds a real databricks* subdir after a skills - // install, regardless of whether the agent copy is a symlink or a copy. The - // legacy dir is checked too so users of an older install aren't hinted. - return hasSharedSkills(ctx) + return tooling != ToolingNone } -// alreadyHintedThisSession reports whether this Claude session was hinted -// within the last hintSessionTTL. With no session id it returns false so the -// hint fires per command. -func alreadyHintedThisSession(ctx context.Context) bool { - session := env.Get(ctx, claudeSessionEnv) +// 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 == "" { return false } @@ -129,11 +279,11 @@ func alreadyHintedThisSession(ctx context.Context) bool { return seen } -// recordSessionHint marks the current Claude session as hinted, so later +// 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) { - session := env.Get(ctx, claudeSessionEnv) +func recordSessionHint(ctx context.Context, sessionEnv string) { + session := sessionID(ctx, sessionEnv) if session == "" { return } @@ -141,6 +291,21 @@ func recordSessionHint(ctx context.Context) { cache.Put(ctx, c, session, true) } +// sessionID returns the value of sessionEnv, or "" when the agent has no +// session env var or it is unset. +func sessionID(ctx context.Context, sessionEnv string) string { + if sessionEnv == "" { + return "" + } + return env.Get(ctx, sessionEnv) +} + +// SelfExecEnv returns environ plus the marker that keeps a CLI process the +// CLI starts of itself from hinting. Use it as the child's exec.Cmd.Env. +func SelfExecEnv(environ []string) []string { + return append(environ, selfExecEnv+"=1") +} + // logHintShown records that a recommendation to install Databricks AI tools of // the given kind was shown. Call it once per hint shown; for a prompt, call it // before asking so a declined prompt still counts. The upload's diff --git a/libs/aitools/agents/hint_test.go b/libs/aitools/agents/hint_test.go index 3add0417795..e92d02af488 100644 --- a/libs/aitools/agents/hint_test.go +++ b/libs/aitools/agents/hint_test.go @@ -3,6 +3,8 @@ package agents import ( "bytes" "context" + "encoding/json" + "io" "log/slog" "os" "path/filepath" @@ -11,19 +13,48 @@ import ( "github.com/databricks/cli/internal/testutil" "github.com/databricks/cli/libs/cmdio" "github.com/databricks/cli/libs/env" + "github.com/databricks/cli/libs/flags" "github.com/databricks/cli/libs/log" "github.com/databricks/cli/libs/telemetry" "github.com/databricks/cli/libs/telemetry/protos" + "github.com/databricks/databricks-sdk-go/useragent" "github.com/spf13/cobra" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" ) +// hintEnvVars are the non-detection env vars MaybeHint reads. They are cleared +// so a test run from inside Claude Code or CI sees none of the host's values. +var hintEnvVars = []string{ + claudeChildSessionEnv, claudeSessionEnv, ciEnv, "CLAUDE_CONFIG_DIR", + // CI/CD provider markers read by useragent.CiCdProvider(). + "GITHUB_ACTIONS", "GITLAB_CI", "JENKINS_URL", "TF_BUILD", "CIRCLECI", "TRAVIS", + "BITBUCKET_BUILD_NUMBER", "PROJECT_ID", "CODEBUILD_BUILD_ARN", "TFC_RUN_ID", +} + +// unsetEnv unsets vars for the test and restores them afterwards. t.Setenv +// cannot unset, hence the manual save/restore. +func unsetEnv(t *testing.T, vars []string) { + for _, v := range vars { + if orig, ok := os.LookupEnv(v); ok { + t.Cleanup(func() { os.Setenv(v, orig) }) //nolint:usetesting // restoring, not setting fresh + os.Unsetenv(v) //nolint:usetesting // t.Setenv cannot unset + } + } +} + // setClaudeAgent makes useragent.AgentProvider() report Claude Code for this -// test, with the host's environment cleared. These tests must not run in -// parallel (see testutil.SetAgentEnv). +// test, with the host's agent and hint env cleared. These tests must not run +// in parallel (see testutil.SetAgentEnv). The first t.TempDir call runs before +// SetAgentEnv clears TMPDIR / TEMP, so later calls in the test still work. +// It also moves into an empty project with its own .git boundary, so project +// skills in the checkout running the tests are not detected. func setClaudeAgent(t *testing.T) { + cwd := t.TempDir() + require.NoError(t, os.Mkdir(filepath.Join(cwd, ".git"), 0o755)) + t.Chdir(cwd) testutil.SetAgentEnv(t, "CLAUDECODE", "1") + unsetEnv(t, hintEnvVars) } // claudeCtx returns a context with a captured stderr buffer and an isolated @@ -59,6 +90,13 @@ func hintKinds(t *testing.T, ctx context.Context) []protos.AitoolsHintKind { return out } +// writeClaudeSkill puts a skill dir in Claude Code's own skills dir. It is a +// real dir rather than the installer's symlink so the fixture needs no symlink +// privilege on Windows; HasDatabricksSkillsIn treats both alike. +func writeClaudeSkill(t *testing.T, home, name string) { + require.NoError(t, os.MkdirAll(filepath.Join(home, ".claude", "skills", name), 0o755)) +} + func TestMaybeHint_HumanCallerSilent(t *testing.T) { // No agent env: AgentProvider() == "", so no hint even with nothing installed. testutil.SetAgentEnv(t) @@ -93,7 +131,41 @@ func TestMaybeHint_PluginInstalledSilent(t *testing.T) { assert.Empty(t, hintKinds(t, ctx)) } +// A project or local plugin only loads inside its own project, so elsewhere +// Claude Code still lacks the tooling and gets the hint. +func TestMaybeHint_ProjectPluginCountsOnlyInItsProject(t *testing.T) { + project, other := t.TempDir(), t.TempDir() + for _, tc := range []struct { + name string + projectPath string + wantHint bool + }{ + {name: "plugin for this project", projectPath: project}, + {name: "plugin for another project", projectPath: other, wantHint: true}, + } { + t.Run(tc.name, func(t *testing.T) { + setClaudeAgent(t) + home := t.TempDir() + ctx, stderr := claudeCtx(t, home) + manifest, err := json.Marshal(map[string]any{"plugins": map[string]any{ + "databricks@claude-plugins-official": []map[string]string{{"scope": "project", "projectPath": tc.projectPath}}, + }}) + require.NoError(t, err) + writePluginManifest(t, home, string(manifest)) + t.Chdir(project) + + MaybeHint(ctx, regularCmd()) + if tc.wantHint { + assert.Contains(t, stderr.String(), hintText) + } else { + assert.Empty(t, stderr.String()) + } + }) + } +} + func TestClaudeToolingInstalled_LogsPluginVersion(t *testing.T) { + unsetEnv(t, hintEnvVars) home := t.TempDir() writePluginManifest(t, home, `{"plugins":{"databricks@claude-plugins-official":[{"version":"0.2.6"}]}}`) @@ -153,20 +225,26 @@ func TestMaybeHint_SkillsInstalledSilent(t *testing.T) { setClaudeAgent(t) home := t.TempDir() ctx, stderr := claudeCtx(t, home) - writeCanonicalSkill(t, home, "databricks") + writeClaudeSkill(t, home, "databricks") MaybeHint(ctx, regularCmd()) assert.Empty(t, stderr.String()) } -func TestMaybeHint_LegacySkillsInstalledSilent(t *testing.T) { - setClaudeAgent(t) - home := t.TempDir() - ctx, stderr := claudeCtx(t, home) - require.NoError(t, os.MkdirAll(filepath.Join(home, ".databricks", "agent-skills", "databricks"), 0o755)) +func TestMaybeHint_SharedStoreOnlyStillHints(t *testing.T) { + // Skills in the shared store (or the legacy store) but not in Claude Code's + // own skills dir were installed for another agent; Claude doesn't load them. + for _, dir := range []string{CanonicalSkillsDir, LegacySkillsDir} { + t.Run(dir, func(t *testing.T) { + setClaudeAgent(t) + home := t.TempDir() + ctx, stderr := claudeCtx(t, home) + require.NoError(t, os.MkdirAll(filepath.Join(home, dir, "databricks"), 0o755)) - MaybeHint(ctx, regularCmd()) - assert.Empty(t, stderr.String()) + MaybeHint(ctx, regularCmd()) + assert.Equal(t, hintText+"\n", stderr.String()) + }) + } } func TestMaybeHint_NonDatabricksSkillStillHints(t *testing.T) { @@ -226,3 +304,312 @@ func TestMaybeHint_ThrottledPerSession(t *testing.T) { assert.Empty(t, stderr2.String()) assert.Empty(t, hintKinds(t, ctx2)) } + +// wantNativeHint is the exact line Claude Code parses; see +// https://code.claude.com/docs/en/plugins/cli-hints. Spelled out rather than built +// from constants so a change to the plugin id or marketplace fails here. +const wantNativeHint = `` + +func TestClaudeNativeHint_Format(t *testing.T) { + assert.Equal(t, wantNativeHint, claudeNativeHint) +} + +// authDockerCmd returns `auth docker ` as a leaf command. +func authDockerCmd(use string) *cobra.Command { + auth := &cobra.Command{Use: authCommandName} + docker := &cobra.Command{Use: "docker"} + leaf := &cobra.Command{Use: use} + auth.AddCommand(docker) + docker.AddCommand(leaf) + return leaf +} + +func TestSelfExecEnv(t *testing.T) { + assert.Equal(t, []string{"A=1", selfExecEnv + "=1"}, SelfExecEnv([]string{"A=1"})) +} + +func TestMaybeHint_NativeHint(t *testing.T) { + for _, tc := range []struct { + name string + env map[string]string + setup func(t *testing.T, home string) + cmd func() *cobra.Command + wantStderr string + }{ + { + name: "claude child session prints native then text", + env: map[string]string{claudeChildSessionEnv: "1"}, + wantStderr: wantNativeHint + "\n" + hintText + "\n", + }, + { + name: "no child session prints text only", + wantStderr: hintText + "\n", + }, + { + name: "CI prints text only", + env: map[string]string{claudeChildSessionEnv: "1", ciEnv: "true"}, + wantStderr: hintText + "\n", + }, + { + name: "CI=false still prints native", + env: map[string]string{claudeChildSessionEnv: "1", ciEnv: "false"}, + wantStderr: wantNativeHint + "\n" + hintText + "\n", + }, + { + // Some providers set CI to their own name. + name: "CI set to a provider name prints text only", + env: map[string]string{claudeChildSessionEnv: "1", ciEnv: "woodpecker"}, + wantStderr: hintText + "\n", + }, + { + // Azure Pipelines sets TF_BUILD but not CI. + name: "CI provider without CI var prints text only", + env: map[string]string{claudeChildSessionEnv: "1", "TF_BUILD": "True"}, + wantStderr: hintText + "\n", + }, + { + name: "plugin installed prints nothing", + env: map[string]string{claudeChildSessionEnv: "1"}, + setup: func(t *testing.T, home string) { + writePluginManifest(t, home, `{"plugins":{"databricks@claude-plugins-official":[{"scope":"user"}]}}`) + }, + }, + { + name: "skills installed prints nothing", + env: map[string]string{claudeChildSessionEnv: "1"}, + setup: func(t *testing.T, home string) { + writeClaudeSkill(t, home, "databricks") + }, + }, + { + name: "auth token prints nothing", + env: map[string]string{claudeChildSessionEnv: "1"}, + cmd: func() *cobra.Command { + parent := &cobra.Command{Use: authCommandName} + child := &cobra.Command{Use: "token [PROFILE]"} + parent.AddCommand(child) + return child + }, + }, + { + name: "other auth command still hints", + env: map[string]string{claudeChildSessionEnv: "1"}, + wantStderr: wantNativeHint + "\n" + hintText + "\n", + cmd: func() *cobra.Command { + parent := &cobra.Command{Use: authCommandName} + child := &cobra.Command{Use: "profiles"} + parent.AddCommand(child) + return child + }, + }, + { + name: "auth docker token prints nothing", + env: map[string]string{claudeChildSessionEnv: "1"}, + cmd: func() *cobra.Command { return authDockerCmd("token") }, + }, + { + name: "other auth docker command still hints", + env: map[string]string{claudeChildSessionEnv: "1"}, + wantStderr: wantNativeHint + "\n" + hintText + "\n", + cmd: func() *cobra.Command { return authDockerCmd("configure [PROFILE]") }, + }, + { + // air images push runs `auth docker configure` and embeds its + // output in an error; the child must add nothing to it. + name: "CLI self-exec child prints nothing", + env: map[string]string{claudeChildSessionEnv: "1", selfExecEnv: "1"}, + }, + { + name: "aitools command prints nothing", + env: map[string]string{claudeChildSessionEnv: "1"}, + cmd: func() *cobra.Command { + parent := &cobra.Command{Use: aiToolsCommandName} + child := &cobra.Command{Use: "install"} + parent.AddCommand(child) + return child + }, + }, + } { + t.Run(tc.name, func(t *testing.T) { + setClaudeAgent(t) + home := t.TempDir() + ctx, stderr := claudeCtx(t, home) + for k, v := range tc.env { + t.Setenv(k, v) + } + // CiCdProvider caches its first answer process-wide. + useragent.ClearCache() + if tc.setup != nil { + tc.setup(t, home) + } + cmd := regularCmd() + if tc.cmd != nil { + cmd = tc.cmd() + } + + MaybeHint(ctx, cmd) + assert.Equal(t, tc.wantStderr, stderr.String()) + }) + } +} + +func TestMaybeHint_NativeHintSilentForOtherCallers(t *testing.T) { + for _, tc := range []struct { + name string + agentEnv []string + }{ + {"human", nil}, + {"other agent", []string{"CURSOR_AGENT", "1"}}, + {"multiple agents", []string{"CLAUDECODE", "1", "CURSOR_AGENT", "1"}}, + } { + t.Run(tc.name, func(t *testing.T) { + testutil.SetAgentEnv(t, tc.agentEnv...) + unsetEnv(t, hintEnvVars) + ctx, stderr := claudeCtx(t, t.TempDir()) + // Even with Claude's child-session marker present, only a sole + // Claude Code caller gets the native hint. + ctx = env.Set(ctx, claudeChildSessionEnv, "1") + + MaybeHint(ctx, regularCmd()) + assert.Empty(t, stderr.String()) + }) + } +} + +func TestMaybeHint_NativeHintThrottledPerSession(t *testing.T) { + setClaudeAgent(t) + home := t.TempDir() + cacheDir := t.TempDir() + newCtx := func() (context.Context, *bytes.Buffer) { + ctx, stderr := cmdio.NewTestContextWithStderr(t.Context()) + ctx = env.WithUserHomeDir(ctx, home) + ctx = env.Set(ctx, "DATABRICKS_CACHE_DIR", cacheDir) + ctx = env.Set(ctx, "DATABRICKS_CACHE_ENABLED", "true") + ctx = env.Set(ctx, claudeSessionEnv, "session-abc") + ctx = env.Set(ctx, claudeChildSessionEnv, "1") + return ctx, stderr + } + + ctx1, stderr1 := newCtx() + MaybeHint(ctx1, regularCmd()) + assert.Equal(t, wantNativeHint+"\n"+hintText+"\n", stderr1.String()) + + // Same session, second command: both lines stay quiet, so the tag doesn't + // reach a downstream reader such as `2>&1 | jq` on every command. + ctx2, stderr2 := newCtx() + MaybeHint(ctx2, regularCmd()) + assert.Empty(t, stderr2.String()) + + // Another session: both lines print again. + ctx3, stderr3 := newCtx() + ctx3 = env.Set(ctx3, claudeSessionEnv, "session-def") + MaybeHint(ctx3, regularCmd()) + assert.Equal(t, wantNativeHint+"\n"+hintText+"\n", stderr3.String()) +} + +func TestMaybeHint_NativeHintSilentOnTerminal(t *testing.T) { + // The fakes make one stream look like a terminal, as in tmux or screen + // started from inside Claude Code, where nothing strips the tag. A person + // typing there has the terminal on stdin even when the output is piped, as + // in `databricks ... 2>&1 | less`. + for _, tc := range []struct { + name string + stdin, stdout, stderr bool + }{ + {name: "stdin", stdin: true}, + {name: "stdout", stdout: true}, + {name: "stderr", stderr: true}, + } { + t.Run(tc.name, func(t *testing.T) { + setClaudeAgent(t) + stderr := &bytes.Buffer{} + var in io.Reader + out := io.Discard + var errOut io.Writer = stderr + if tc.stdin { + in = cmdio.FakeTTYReader(&bytes.Buffer{}) + } + if tc.stdout { + out = cmdio.FakeTTY(out) + } + if tc.stderr { + errOut = cmdio.FakeTTY(errOut) + } + ctx := cmdio.InContext(t.Context(), cmdio.NewIO(t.Context(), flags.OutputText, in, out, errOut, "", "")) + ctx = env.WithUserHomeDir(ctx, t.TempDir()) + ctx = env.Set(ctx, "DATABRICKS_CACHE_DIR", t.TempDir()) + ctx = env.Set(ctx, claudeChildSessionEnv, "1") + + MaybeHint(ctx, regularCmd()) + assert.Equal(t, hintText+"\n", stderr.String()) + }) + } +} + +func TestAgentHint_NativeLineNilIsEmpty(t *testing.T) { + h := &agentHint{} + assert.Empty(t, h.nativeLine(t.Context())) +} + +func TestHintForAgent(t *testing.T) { + claude := hintForAgent(claudeAgentProvider) + require.NotNil(t, claude) + assert.Equal(t, hintText, claude.text) + assert.Equal(t, claudeSessionEnv, claude.sessionEnv) + + assert.Nil(t, hintForAgent("")) + assert.Nil(t, hintForAgent("multiple")) + assert.Nil(t, hintForAgent("cursor")) +} + +func TestMaybeHint_LogsEventsOncePerSession(t *testing.T) { + setClaudeAgent(t) + home := t.TempDir() + cacheDir := t.TempDir() + newCtx := func(childSession bool) (context.Context, *bytes.Buffer) { + ctx, stderr := cmdio.NewTestContextWithStderr(t.Context()) + ctx = telemetry.WithNewLogger(ctx) + ctx = env.WithUserHomeDir(ctx, home) + ctx = env.Set(ctx, "DATABRICKS_CACHE_DIR", cacheDir) + ctx = env.Set(ctx, "DATABRICKS_CACHE_ENABLED", "true") + ctx = env.Set(ctx, claudeSessionEnv, "session-abc") + if childSession { + ctx = env.Set(ctx, claudeChildSessionEnv, "1") + } + return ctx, stderr + } + + ctx1, _ := newCtx(true) + MaybeHint(ctx1, regularCmd()) + assert.Equal(t, []protos.AitoolsHintKind{ + protos.AitoolsHintKindClaudeCodeNative, + protos.AitoolsHintKindInstallText, + }, hintKinds(t, ctx1)) + events := telemetry.BufferedEvents(ctx1) + require.Len(t, events, 2) + + // Throttled for the session: nothing prints and nothing logs, so the + // command doesn't pay for a telemetry upload at exit. + ctx2, stderr2 := newCtx(true) + MaybeHint(ctx2, regularCmd()) + assert.Empty(t, stderr2.String()) + assert.Empty(t, telemetry.BufferedEvents(ctx2)) + + // Throttled and not a Claude Code subprocess: nothing prints, nothing logs. + ctx3, stderr3 := newCtx(false) + MaybeHint(ctx3, regularCmd()) + assert.Empty(t, stderr3.String()) + assert.Empty(t, telemetry.BufferedEvents(ctx3)) +} + +func TestMaybeHint_InstalledLogsNothing(t *testing.T) { + setClaudeAgent(t) + home := t.TempDir() + ctx, _ := claudeCtx(t, home) + ctx = telemetry.WithNewLogger(ctx) + ctx = env.Set(ctx, claudeChildSessionEnv, "1") + writePluginManifest(t, home, `{"plugins":{"databricks@claude-plugins-official":[{"scope":"user"}]}}`) + + MaybeHint(ctx, regularCmd()) + assert.Empty(t, telemetry.BufferedEvents(ctx)) +} diff --git a/libs/cmdio/io.go b/libs/cmdio/io.go index 7f0dd853e8c..368317e8ed5 100644 --- a/libs/cmdio/io.go +++ b/libs/cmdio/io.go @@ -101,6 +101,13 @@ func IsPagerSupported(ctx context.Context) bool { return c.capabilities.SupportsPager() } +// HasTerminal reports whether stdin, stdout or stderr is a terminal. Unlike +// GetInteractiveMode it ignores colour preferences (NO_COLOR, TERM=dumb). +func HasTerminal(ctx context.Context) bool { + c := fromContext(ctx) + return c.capabilities.stdinIsTTY || c.capabilities.stdoutIsTTY || c.capabilities.stderrIsTTY +} + // SupportsColor returns true if the given writer supports colored output. // This checks both TTY status and environment variables (NO_COLOR, TERM=dumb). func SupportsColor(ctx context.Context, w io.Writer) bool { diff --git a/libs/cmdio/io_test.go b/libs/cmdio/io_test.go index 7c5aad9a6a6..c573e78ccce 100644 --- a/libs/cmdio/io_test.go +++ b/libs/cmdio/io_test.go @@ -1,9 +1,13 @@ package cmdio import ( + "bytes" + "io" "testing" "time" + "github.com/databricks/cli/libs/env" + "github.com/databricks/cli/libs/flags" "github.com/stretchr/testify/assert" ) @@ -47,3 +51,29 @@ func TestIsInputTTY(t *testing.T) { ctx = InContext(t.Context(), &cmdIO{capabilities: Capabilities{stderrIsTTY: true, color: true}}) assert.False(t, IsInputTTY(ctx)) } + +func TestHasTerminal(t *testing.T) { + for _, tc := range []struct { + name string + in io.Reader + out io.Writer + err io.Writer + noColor bool + want bool + }{ + {name: "no terminal", out: io.Discard, err: io.Discard}, + {name: "stdin", in: FakeTTYReader(&bytes.Buffer{}), out: io.Discard, err: io.Discard, want: true}, + {name: "stdout", out: FakeTTY(io.Discard), err: io.Discard, want: true}, + {name: "stderr", out: io.Discard, err: FakeTTY(io.Discard), want: true}, + {name: "stderr with NO_COLOR", out: io.Discard, err: FakeTTY(io.Discard), noColor: true, want: true}, + } { + t.Run(tc.name, func(t *testing.T) { + ctx := t.Context() + if tc.noColor { + ctx = env.Set(ctx, "NO_COLOR", "1") + } + ctx = InContext(ctx, NewIO(ctx, flags.OutputText, tc.in, tc.out, tc.err, "", "")) + assert.Equal(t, tc.want, HasTerminal(ctx)) + }) + } +} diff --git a/libs/cmdio/tty.go b/libs/cmdio/tty.go index c2607b8909f..4c2fbe9a92a 100644 --- a/libs/cmdio/tty.go +++ b/libs/cmdio/tty.go @@ -23,6 +23,9 @@ func isTTY(v any) bool { if _, ok := v.(*fakeTTY); ok { return true } + if _, ok := v.(*fakeTTYReader); ok { + return true + } // Check if it's an actual TTY. f, ok := v.(*os.File) @@ -44,3 +47,14 @@ type fakeTTY struct { func FakeTTY(w io.Writer) io.Writer { return &fakeTTY{Writer: w} } + +// fakeTTYReader is fakeTTY for a reader, so stdin can pose as a terminal. +type fakeTTYReader struct { + io.Reader +} + +// FakeTTYReader creates a reader that IsTTY will recognize as a TTY, for +// testing behavior that depends on stdin being a terminal. +func FakeTTYReader(r io.Reader) io.Reader { + return &fakeTTYReader{Reader: r} +} diff --git a/libs/cmdio/tty_test.go b/libs/cmdio/tty_test.go index 189692146be..8424af884bb 100644 --- a/libs/cmdio/tty_test.go +++ b/libs/cmdio/tty_test.go @@ -69,6 +69,18 @@ func TestFakeTTY(t *testing.T) { assert.Equal(t, "test", buf.String()) } +func TestFakeTTYReader(t *testing.T) { + src := bytes.NewBufferString("input") + assert.False(t, isTTY(src)) + + fake := FakeTTYReader(src) + assert.True(t, isTTY(fake)) + + got, err := io.ReadAll(fake) + assert.NoError(t, err) + assert.Equal(t, "input", string(got)) +} + func TestFakeTTY_PreservesWriterBehavior(t *testing.T) { buf := &bytes.Buffer{} fake := FakeTTY(buf) diff --git a/libs/telemetry/protos/README.md b/libs/telemetry/protos/README.md index 176144d96a7..d07f4790963 100644 --- a/libs/telemetry/protos/README.md +++ b/libs/telemetry/protos/README.md @@ -6,10 +6,12 @@ which config options were set, the outcome and latency, and how long packaging a uploading the code snapshot took. It never includes code, paths, names, parameters, or image references. Set `DATABRICKS_CLI_DISABLE_TELEMETRY=1` to opt out. -The CLI logs an `aitools_hint_event` each time it prints the Claude Code install hint (any -non-aitools command) or the `apps init` skills tip or install prompt. It carries only the kind of -hint (`hint_kind`); the command it was shown on is the entry's `execution_context.command`. The -event uploads at exit only when the command resolved auth. The install hint prints at most once per +The CLI logs an `aitools_hint_event` for each Claude Code install-hint line it prints (the native +`` line and the text line are one event each) and for the `apps init` skills tip +or install prompt. The install hint is never printed on aitools commands, `auth token`, +`auth docker token` or in CLI processes the CLI started itself. It carries only the kind of hint +(`hint_kind`); the command it was shown on is the entry's `execution_context.command`. The event +uploads at exit only when the command resolved auth. The install hint prints at most once per Claude Code session per hour, so when the command that printed it resolves no auth (e.g. `databricks version`), that session logs no install hint event for the next hour even though the agent saw the hint. diff --git a/libs/telemetry/protos/aitools_events.go b/libs/telemetry/protos/aitools_events.go index 9a39ef8c6b0..50d7260aff9 100644 --- a/libs/telemetry/protos/aitools_events.go +++ b/libs/telemetry/protos/aitools_events.go @@ -9,10 +9,12 @@ const ( // AitoolsHintKindInstallText is the generic stderr line asking the agent to // run `databricks aitools install`. AitoolsHintKindInstallText AitoolsHintKind = "INSTALL_TEXT" - // AitoolsHintKindClaudeCodeNative and AitoolsHintKindAgentInstallText - // mirror enum values of the proto for hints the CLI does not print. - // Nothing logs them today. + // AitoolsHintKindClaudeCodeNative is Claude Code's native + // `` line, which makes Claude Code offer to install the + // Databricks plugin. AitoolsHintKindClaudeCodeNative AitoolsHintKind = "CLAUDE_CODE_NATIVE" + // AitoolsHintKindAgentInstallText mirrors an enum value of the proto for a + // hint the CLI does not print. Nothing logs it today. AitoolsHintKindAgentInstallText AitoolsHintKind = "AGENT_INSTALL_TEXT" // AitoolsHintKindAppsInitTip is the non-interactive tip printed by // `databricks apps init`. @@ -22,13 +24,13 @@ const ( AitoolsHintKindAppsInitPrompt AitoolsHintKind = "APPS_INIT_PROMPT" ) -// AitoolsHintEvent is emitted once each time the CLI prints the Claude Code -// install hint or the `apps init` skills tip or install prompt; other messages -// that mention `databricks aitools install` log nothing. It carries no -// user-authored strings. The command it was shown on is ExecutionContext.Command -// of the enclosing log entry. The CLI sets no calling-agent field on this -// event: the calling agent is reported by the User-Agent of the telemetry -// upload (`agent/`). +// AitoolsHintEvent is emitted once for each Claude Code install-hint line the +// CLI prints (the native line and the text line are one event each) and for the +// `apps init` skills tip or install prompt; other messages that mention +// `databricks aitools install` log nothing. It carries no user-authored strings. +// The command it was shown on is ExecutionContext.Command of the enclosing log +// entry. The CLI sets no calling-agent field on this event: the calling agent +// is reported by the User-Agent of the telemetry upload (`agent/`). type AitoolsHintEvent struct { HintKind AitoolsHintKind `json:"hint_kind"` } From 735415ead21ac9f5122454945e57b88731b6b1ce Mon Sep 17 00:00:00 2001 From: Anton Nekipelov <226657+anton-107@users.noreply.github.com> Date: Fri, 13 Nov 2026 06:01:56 +0000 Subject: [PATCH 2/6] aitools: install hints for non-Claude coding agents Until now the install hint was printed only to Claude Code. The nine other registry agents (Codex, Cursor, GitHub Copilot CLI, OpenCode, Gemini CLI, Antigravity, Pi, Goose, Kiro) now also get a one-line hint, but only when that agent's own Databricks tooling is missing: Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents --scope global - The throttle lasts one hour (hintSessionTTL). Keys are ":session:" (Codex: CODEX_THREAD_ID) or ":machine" for agents without a session id, so a Claude marker never silences Codex when both report the same id. - If the user cache can't be written (read-only sandbox, or DATABRICKS_CACHE_ENABLED=false), non-Claude agents get no hint at all. - Agents the CLI can't install for (Windsurf, VS Code agent, Amp, ...) and nested agents get no hint. - installer.globalPluginRecorded is now exported as GlobalPluginRecorded, so cmd/root can pass it to MaybeHint. - The telemetry README and the AitoolsHintEvent doc now describe the event for every agent; the new line logs AGENT_INSTALL_TEXT. Co-authored-by: Isaac --- .nextchanges/cli/aitools-hint-other-agents.md | 1 + .../.gemini/skills/databricks-core/SKILL.md | 4 + .../cmd/aitools/agent-hints/out.test.toml | 1 + acceptance/cmd/aitools/agent-hints/output.txt | 46 +++ acceptance/cmd/aitools/agent-hints/script | 27 ++ acceptance/cmd/aitools/agent-hints/test.toml | 3 + cmd/root/root.go | 8 +- libs/aitools/agents/hint.go | 98 ++++-- libs/aitools/agents/hint_agents.go | 60 ++++ libs/aitools/agents/hint_agents_test.go | 309 ++++++++++++++++++ libs/aitools/agents/hint_test.go | 69 ++-- libs/aitools/installer/useragent.go | 6 +- libs/telemetry/protos/README.md | 19 +- libs/telemetry/protos/aitools_events.go | 19 +- 14 files changed, 587 insertions(+), 83 deletions(-) create mode 100644 .nextchanges/cli/aitools-hint-other-agents.md create mode 100644 acceptance/cmd/aitools/agent-hints/gemini-home/.gemini/skills/databricks-core/SKILL.md create mode 100644 acceptance/cmd/aitools/agent-hints/out.test.toml create mode 100644 acceptance/cmd/aitools/agent-hints/output.txt create mode 100644 acceptance/cmd/aitools/agent-hints/script create mode 100644 acceptance/cmd/aitools/agent-hints/test.toml create mode 100644 libs/aitools/agents/hint_agents.go create mode 100644 libs/aitools/agents/hint_agents_test.go diff --git a/.nextchanges/cli/aitools-hint-other-agents.md b/.nextchanges/cli/aitools-hint-other-agents.md new file mode 100644 index 00000000000..4093d961770 --- /dev/null +++ b/.nextchanges/cli/aitools-hint-other-agents.md @@ -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 --scope global`, previously shown only to Claude Code. ([#7586](https://github.com/databricks/cli/pull/7586)) diff --git a/acceptance/cmd/aitools/agent-hints/gemini-home/.gemini/skills/databricks-core/SKILL.md b/acceptance/cmd/aitools/agent-hints/gemini-home/.gemini/skills/databricks-core/SKILL.md new file mode 100644 index 00000000000..4c0f09c4d63 --- /dev/null +++ b/acceptance/cmd/aitools/agent-hints/gemini-home/.gemini/skills/databricks-core/SKILL.md @@ -0,0 +1,4 @@ +--- +name: databricks-core +description: Fixture marking Databricks skills as installed for Gemini CLI. +--- diff --git a/acceptance/cmd/aitools/agent-hints/out.test.toml b/acceptance/cmd/aitools/agent-hints/out.test.toml new file mode 100644 index 00000000000..18b1a88417e --- /dev/null +++ b/acceptance/cmd/aitools/agent-hints/out.test.toml @@ -0,0 +1 @@ +Cloud = false diff --git a/acceptance/cmd/aitools/agent-hints/output.txt b/acceptance/cmd/aitools/agent-hints/output.txt new file mode 100644 index 00000000000..ed22089e902 --- /dev/null +++ b/acceptance/cmd/aitools/agent-hints/output.txt @@ -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] diff --git a/acceptance/cmd/aitools/agent-hints/script b/acceptance/cmd/aitools/agent-hints/script new file mode 100644 index 00000000000..405596d991b --- /dev/null +++ b/acceptance/cmd/aitools/agent-hints/script @@ -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 diff --git a/acceptance/cmd/aitools/agent-hints/test.toml b/acceptance/cmd/aitools/agent-hints/test.toml new file mode 100644 index 00000000000..c6ac528b986 --- /dev/null +++ b/acceptance/cmd/aitools/agent-hints/test.toml @@ -0,0 +1,3 @@ +# The throttle markers live in the file cache, which a host could disable. +Env.DATABRICKS_CACHE_ENABLED = "true" +Ignore = ["home"] diff --git a/cmd/root/root.go b/cmd/root/root.go index 59b9777ef69..967c2afa0c6 100644 --- a/cmd/root/root.go +++ b/cmd/root/root.go @@ -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) return nil } diff --git a/libs/aitools/agents/hint.go b/libs/aitools/agents/hint.go index dce48cd4503..fde8b25bb04 100644 --- a/libs/aitools/agents/hint.go +++ b/libs/aitools/agents/hint.go @@ -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" ) @@ -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 + // 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. @@ -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{ @@ -128,6 +145,9 @@ func hintForAgent(provider string) *agentHint { nativeKind: protos.AitoolsHintKindClaudeCodeNative, } default: + if a := AgentForProvider(provider); a != nil { + return agentInstallHint(a, pluginRecorded) + } return nil } } @@ -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 } @@ -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 @@ -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 diff --git a/libs/aitools/agents/hint_agents.go b/libs/aitools/agents/hint_agents.go new file mode 100644 index 00000000000..a566eec993a --- /dev/null +++ b/libs/aitools/agents/hint_agents.go @@ -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. + 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. +// +// 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. +func agentInstallHint(a *Agent, pluginRecorded PluginRecordedFunc) *agentHint { + 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", + 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 +} diff --git a/libs/aitools/agents/hint_agents_test.go b/libs/aitools/agents/hint_agents_test.go new file mode 100644 index 00000000000..e8f954dc1eb --- /dev/null +++ b/libs/aitools/agents/hint_agents_test.go @@ -0,0 +1,309 @@ +package agents + +import ( + "bytes" + "context" + "os" + "path/filepath" + "runtime" + "strings" + "testing" + + "github.com/databricks/cli/internal/testutil" + "github.com/databricks/cli/libs/cmdio" + "github.com/databricks/cli/libs/env" + "github.com/databricks/cli/libs/telemetry" + "github.com/databricks/cli/libs/telemetry/protos" + "github.com/spf13/cobra" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestAgentHintText(t *testing.T) { + const prefix = "Databricks skills are not installed. To work with Databricks reliably, first run: " + cases := map[string]string{ + NameCursor: "databricks aitools install --agents cursor --scope global", + NameCodex: "databricks aitools install --agents codex --scope global", + NameOpenCode: "databricks aitools install --agents opencode --scope global", + NameCopilot: "databricks aitools install --agents copilot --scope global", + NameAntigravity: "databricks aitools install --agents antigravity --scope global", + NamePi: "databricks aitools install --agents pi --scope global", + NameGemini: "databricks aitools install --agents gemini --scope global", + NameGoose: "databricks aitools install --agents goose --scope global", + NameKiro: "databricks aitools install --agents kiro --scope global", + } + for name, command := range cases { + t.Run(name, func(t *testing.T) { + a := ByName(name) + require.NotNil(t, a) + assert.Equal(t, prefix+command, agentInstallHint(a, noPluginRecorded).text) + }) + } +} + +func TestAgentInstallHintThrottleKey(t *testing.T) { + codex := agentInstallHint(ByName(NameCodex), noPluginRecorded) + cursor := agentInstallHint(ByName(NameCursor), noPluginRecorded) + + ctx := env.Set(t.Context(), "CODEX_THREAD_ID", "thread-1") + assert.Equal(t, "codex:session:thread-1", codex.throttleKey(ctx)) + + // No session id: fall back to one key per agent on this machine. + assert.Equal(t, "codex:machine", codex.throttleKey(env.Set(t.Context(), "CODEX_THREAD_ID", ""))) + + // Agents without a verified session variable always use the per-agent key, + // and never pick up another agent's session id. + assert.Equal(t, "cursor:machine", cursor.throttleKey(ctx)) +} + +// agentDetectEnv is the SDK env var that makes AgentProvider() report each +// registry agent. +var agentDetectEnv = map[string]string{ + NameClaudeCode: "CLAUDECODE", + NameCursor: "CURSOR_AGENT", + NameCodex: "CODEX_CI", + NameOpenCode: "OPENCODE", + NameCopilot: "COPILOT_CLI", + NameAntigravity: "ANTIGRAVITY_AGENT", + NamePi: "PI_CODING_AGENT", + NameGemini: "GEMINI_CLI", + NameGoose: "GOOSE_TERMINAL", + NameKiro: "KIRO", +} + +// setAgentEnv makes useragent.AgentProvider() report the given env var's agent, +// with the host's agent and hint env cleared (see testutil.SetAgentEnv). +func setAgentEnv(t *testing.T, envVar string) { + testutil.SetAgentEnv(t, envVar, "1") + unsetEnv(t, append([]string{"CODEX_THREAD_ID"}, hintEnvVars...)) +} + +// agentCtx returns a hint test context whose agent config dirs all resolve +// under home, so fixtures never touch the host's real agent directories. It +// also changes into a repository root under home, so project skills around +// the directory the tests run from are never read. +func agentCtx(t *testing.T, home, cacheDir string) (context.Context, *bytes.Buffer) { + project := filepath.Join(home, "project") + require.NoError(t, os.MkdirAll(filepath.Join(project, ".git"), 0o755)) + t.Chdir(project) + + ctx, stderr := cmdio.NewTestContextWithStderr(t.Context()) + ctx = env.WithUserHomeDir(ctx, home) + ctx = env.Set(ctx, "DATABRICKS_CACHE_DIR", cacheDir) + // The throttle marker lives in the file cache, which a host could disable. + ctx = env.Set(ctx, "DATABRICKS_CACHE_ENABLED", "true") + ctx = env.Set(ctx, "CLAUDE_CONFIG_DIR", "") + ctx = env.Set(ctx, "XDG_CONFIG_HOME", "") + ctx = env.Set(ctx, "APPDATA", "") + ctx = env.Set(ctx, "GEMINI_CLI_HOME", "") + ctx = env.Set(ctx, "PI_CODING_AGENT_DIR", "") + ctx = env.Set(ctx, "GOOSE_PATH_ROOT", "") + ctx = env.Set(ctx, "CODEX_THREAD_ID", "") + return ctx, stderr +} + +func TestAgentCtxIgnoresProjectSkillsAroundTheTest(t *testing.T) { + // Project skills in the directory the tests run from (e.g. the checkout) + // must not count as installed. + gemini := ByName(NameGemini) + outer := t.TempDir() + require.NoError(t, os.Mkdir(filepath.Join(outer, ".git"), 0o755)) + require.NoError(t, os.MkdirAll(filepath.Join(gemini.ProjectSkillsDir(outer), "databricks-core"), 0o755)) + t.Chdir(outer) + + setAgentEnv(t, agentDetectEnv[NameGemini]) + ctx, stderr := agentCtx(t, t.TempDir(), t.TempDir()) + MaybeHint(ctx, regularCmd(), noPluginRecorded) + assert.Equal(t, agentInstallHint(gemini, noPluginRecorded).text+"\n", stderr.String()) +} + +func writeAgentSkill(t *testing.T, ctx context.Context, home string, a *Agent) { + dir, err := a.SkillsDir(ctx) + require.NoError(t, err) + rel, err := filepath.Rel(home, dir) + require.NoError(t, err) + require.False(t, strings.HasPrefix(rel, ".."), "skills dir %s escapes the test home", dir) + require.NoError(t, os.MkdirAll(filepath.Join(dir, "databricks-core"), 0o755)) +} + +func TestMaybeHint_PerAgent(t *testing.T) { + for _, a := range Registry { + if a.Name == NameClaudeCode { + continue // Claude's hint is covered by hint_test.go. + } + t.Run(a.Name, func(t *testing.T) { + setAgentEnv(t, agentDetectEnv[a.Name]) + + t.Run("not installed hints", func(t *testing.T) { + ctx, stderr := agentCtx(t, t.TempDir(), t.TempDir()) + ctx = telemetry.WithNewLogger(ctx) + MaybeHint(ctx, regularCmd(), noPluginRecorded) + assert.Equal(t, agentInstallHint(a, noPluginRecorded).text+"\n", stderr.String()) + + events := telemetry.BufferedEvents(ctx) + require.Len(t, events, 1) + assert.Equal(t, &protos.AitoolsHintEvent{ + HintKind: protos.AitoolsHintKindAgentInstallText, + }, events[0].AitoolsHintEvent) + }) + + t.Run("own skills installed is silent", func(t *testing.T) { + home := t.TempDir() + ctx, stderr := agentCtx(t, home, t.TempDir()) + ctx = telemetry.WithNewLogger(ctx) + writeAgentSkill(t, ctx, home, a) + MaybeHint(ctx, regularCmd(), noPluginRecorded) + assert.Empty(t, stderr.String()) + assert.Empty(t, telemetry.BufferedEvents(ctx)) + }) + + t.Run("canonical skills alone still hint", func(t *testing.T) { + // Skills in the shared store are not loaded by the agent unless + // they are also linked into its own skills dir. + home := t.TempDir() + ctx, stderr := agentCtx(t, home, t.TempDir()) + writeCanonicalSkill(t, home, "databricks") + MaybeHint(ctx, regularCmd(), noPluginRecorded) + assert.Equal(t, agentInstallHint(a, noPluginRecorded).text+"\n", stderr.String()) + }) + + t.Run("throttled per machine without session id", func(t *testing.T) { + home, cacheDir := t.TempDir(), t.TempDir() + ctx1, stderr1 := agentCtx(t, home, cacheDir) + MaybeHint(ctx1, regularCmd(), noPluginRecorded) + assert.NotEmpty(t, stderr1.String()) + + ctx2, stderr2 := agentCtx(t, home, cacheDir) + MaybeHint(ctx2, regularCmd(), noPluginRecorded) + assert.Empty(t, stderr2.String()) + }) + }) + } +} + +// noPluginRecorded is the CLI install record of a machine where `databricks +// aitools install` recorded no plugin. +func noPluginRecorded(context.Context, string) bool { return false } + +func TestMaybeHint_RecordedPluginSilent(t *testing.T) { + // Codex and Copilot have no plugin manifest reader: the CLI install record + // is their plugin source. + for _, name := range []string{NameCodex, NameCopilot} { + t.Run(name, func(t *testing.T) { + setAgentEnv(t, agentDetectEnv[name]) + var asked []string + recorded := func(_ context.Context, agentName string) bool { + asked = append(asked, agentName) + return agentName == name + } + ctx, stderr := agentCtx(t, t.TempDir(), t.TempDir()) + ctx = telemetry.WithNewLogger(ctx) + MaybeHint(ctx, regularCmd(), recorded) + assert.Empty(t, stderr.String()) + assert.Empty(t, telemetry.BufferedEvents(ctx)) + assert.Equal(t, []string{name}, asked) + }) + } +} + +func TestMaybeHint_CodexThrottledPerThread(t *testing.T) { + setAgentEnv(t, "CODEX_CI") + home, cacheDir := t.TempDir(), t.TempDir() + run := func(thread string) string { + ctx, stderr := agentCtx(t, home, cacheDir) + ctx = env.Set(ctx, "CODEX_THREAD_ID", thread) + MaybeHint(ctx, regularCmd(), noPluginRecorded) + return stderr.String() + } + + assert.Contains(t, run("thread-1"), "--agents codex") + assert.Empty(t, run("thread-1")) + // A new Codex session is hinted again even within the TTL. + assert.Contains(t, run("thread-2"), "--agents codex") +} + +func TestMaybeHint_NoInstallTargetSilent(t *testing.T) { + for _, envVar := range []string{"AMP_CURRENT_THREAD_ID", "AUGMENT_AGENT", "CLINE_ACTIVE", "OPENCLAW_SHELL", "VSCODE_AGENT", "WINDSURF_AGENT"} { + t.Run(envVar, func(t *testing.T) { + setAgentEnv(t, envVar) + ctx, stderr := agentCtx(t, t.TempDir(), t.TempDir()) + MaybeHint(ctx, regularCmd(), noPluginRecorded) + assert.Empty(t, stderr.String()) + }) + } +} + +func TestMaybeHint_MultipleAgentsSilent(t *testing.T) { + setAgentEnv(t, "CODEX_CI") + t.Setenv("CURSOR_AGENT", "1") + ctx, stderr := agentCtx(t, t.TempDir(), t.TempDir()) + MaybeHint(ctx, regularCmd(), noPluginRecorded) + assert.Empty(t, stderr.String()) +} + +func TestMaybeHint_AgentAuthTokenSilent(t *testing.T) { + setAgentEnv(t, "CODEX_CI") + ctx, stderr := agentCtx(t, t.TempDir(), t.TempDir()) + parent := &cobra.Command{Use: authCommandName} + child := &cobra.Command{Use: tokenCommandName} + parent.AddCommand(child) + MaybeHint(ctx, child, noPluginRecorded) + assert.Empty(t, stderr.String()) +} + +func TestMaybeHint_AgentAIToolsCommandSilent(t *testing.T) { + setAgentEnv(t, "CODEX_CI") + ctx, stderr := agentCtx(t, t.TempDir(), t.TempDir()) + parent := &cobra.Command{Use: aiToolsCommandName} + child := &cobra.Command{Use: "install"} + parent.AddCommand(child) + MaybeHint(ctx, child, noPluginRecorded) + assert.Empty(t, stderr.String()) +} + +func TestMaybeHint_SessionMarkersAreIsolatedPerAgent(t *testing.T) { + // Claude and Codex both report the same session id. A Claude marker must not + // silence Codex's first hint. + home, cacheDir := t.TempDir(), t.TempDir() + + setClaudeAgent(t) + ctx, stderr := agentCtx(t, home, cacheDir) + ctx = env.Set(ctx, claudeSessionEnv, "shared-id") + MaybeHint(ctx, regularCmd(), noPluginRecorded) + require.Contains(t, stderr.String(), hintText) + + setAgentEnv(t, "CODEX_CI") + ctx, stderr = agentCtx(t, home, cacheDir) + ctx = env.Set(ctx, "CODEX_THREAD_ID", "shared-id") + MaybeHint(ctx, regularCmd(), noPluginRecorded) + assert.Equal(t, agentInstallHint(ByName(NameCodex), noPluginRecorded).text+"\n", stderr.String()) +} + +func TestMaybeHint_UnwritableCacheSkipsHint(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("chmod does not make a directory read-only on Windows") + } + if os.Getuid() == 0 { + t.Skip("root can write to a read-only directory") + } + setAgentEnv(t, "CODEX_CI") + readOnly := t.TempDir() + require.NoError(t, os.Chmod(readOnly, 0o555)) + t.Cleanup(func() { _ = os.Chmod(readOnly, 0o755) }) + tmp := t.TempDir() + t.Setenv("TMPDIR", tmp) + + // Without a kept marker the hint would repeat on every command, so none is + // printed, on every call, and no other store (e.g. under TMPDIR) is used. + for range 2 { + ctx, stderr := agentCtx(t, t.TempDir(), readOnly) + ctx = telemetry.WithNewLogger(ctx) + ctx = env.Set(ctx, "CODEX_THREAD_ID", "thread-1") + MaybeHint(ctx, regularCmd(), noPluginRecorded) + assert.Empty(t, stderr.String()) + assert.Empty(t, telemetry.BufferedEvents(ctx)) + } + entries, err := os.ReadDir(tmp) + require.NoError(t, err) + assert.Empty(t, entries) +} diff --git a/libs/aitools/agents/hint_test.go b/libs/aitools/agents/hint_test.go index e92d02af488..d550afcbeea 100644 --- a/libs/aitools/agents/hint_test.go +++ b/libs/aitools/agents/hint_test.go @@ -64,6 +64,8 @@ func claudeCtx(t *testing.T, home string) (context.Context, *bytes.Buffer) { ctx, stderr := cmdio.NewTestContextWithStderr(t.Context()) ctx = env.WithUserHomeDir(ctx, home) ctx = env.Set(ctx, "DATABRICKS_CACHE_DIR", t.TempDir()) + // Throttle markers live in the file cache, which a host could disable. + ctx = env.Set(ctx, "DATABRICKS_CACHE_ENABLED", "true") return ctx, stderr } @@ -103,7 +105,7 @@ func TestMaybeHint_HumanCallerSilent(t *testing.T) { ctx, stderr := cmdio.NewTestContextWithStderr(t.Context()) ctx = env.WithUserHomeDir(ctx, t.TempDir()) ctx = telemetry.WithNewLogger(ctx) - MaybeHint(ctx, regularCmd()) + MaybeHint(ctx, regularCmd(), noPluginRecorded) assert.Empty(t, stderr.String()) assert.Empty(t, hintKinds(t, ctx)) } @@ -112,7 +114,7 @@ func TestMaybeHint_ClaudeNotInstalledHints(t *testing.T) { setClaudeAgent(t) ctx, stderr := claudeCtx(t, t.TempDir()) ctx = telemetry.WithNewLogger(ctx) - MaybeHint(ctx, regularCmd()) + MaybeHint(ctx, regularCmd(), noPluginRecorded) assert.Contains(t, stderr.String(), hintText) assert.Equal(t, []protos.AitoolsHintKind{protos.AitoolsHintKindInstallText}, hintKinds(t, ctx)) } @@ -126,7 +128,7 @@ func TestMaybeHint_PluginInstalledSilent(t *testing.T) { writePluginManifest(t, home, `{"plugins":{"databricks@claude-plugins-official":[{"scope":"user"}]}}`) ctx = telemetry.WithNewLogger(ctx) - MaybeHint(ctx, regularCmd()) + MaybeHint(ctx, regularCmd(), noPluginRecorded) assert.Empty(t, stderr.String()) assert.Empty(t, hintKinds(t, ctx)) } @@ -154,7 +156,7 @@ func TestMaybeHint_ProjectPluginCountsOnlyInItsProject(t *testing.T) { writePluginManifest(t, home, string(manifest)) t.Chdir(project) - MaybeHint(ctx, regularCmd()) + MaybeHint(ctx, regularCmd(), noPluginRecorded) if tc.wantHint { assert.Contains(t, stderr.String(), hintText) } else { @@ -211,7 +213,7 @@ func TestMaybeHint_CustomClaudeConfigDir(t *testing.T) { writePluginManifest(t, home, manifest) } - MaybeHint(ctx, regularCmd()) + MaybeHint(ctx, regularCmd(), noPluginRecorded) if tc.wantHint { assert.Contains(t, stderr.String(), hintText) } else { @@ -227,7 +229,7 @@ func TestMaybeHint_SkillsInstalledSilent(t *testing.T) { ctx, stderr := claudeCtx(t, home) writeClaudeSkill(t, home, "databricks") - MaybeHint(ctx, regularCmd()) + MaybeHint(ctx, regularCmd(), noPluginRecorded) assert.Empty(t, stderr.String()) } @@ -241,7 +243,7 @@ func TestMaybeHint_SharedStoreOnlyStillHints(t *testing.T) { ctx, stderr := claudeCtx(t, home) require.NoError(t, os.MkdirAll(filepath.Join(home, dir, "databricks"), 0o755)) - MaybeHint(ctx, regularCmd()) + MaybeHint(ctx, regularCmd(), noPluginRecorded) assert.Equal(t, hintText+"\n", stderr.String()) }) } @@ -253,7 +255,7 @@ func TestMaybeHint_NonDatabricksSkillStillHints(t *testing.T) { ctx, stderr := claudeCtx(t, home) writeCanonicalSkill(t, home, "some-other-skill") - MaybeHint(ctx, regularCmd()) + MaybeHint(ctx, regularCmd(), noPluginRecorded) assert.Contains(t, stderr.String(), hintText) } @@ -266,7 +268,7 @@ func TestMaybeHint_AIToolsCommandSilent(t *testing.T) { child := &cobra.Command{Use: "install"} parent.AddCommand(child) - MaybeHint(ctx, child) + MaybeHint(ctx, child, noPluginRecorded) assert.Empty(t, stderr.String()) assert.Empty(t, hintKinds(t, ctx)) } @@ -277,7 +279,7 @@ func TestMaybeHint_NoIONoPanic(t *testing.T) { // invocations before PersistentPreRunE runs, so HasIO can be false here. ctx := env.WithUserHomeDir(t.Context(), t.TempDir()) ctx = telemetry.WithNewLogger(ctx) - assert.NotPanics(t, func() { MaybeHint(ctx, regularCmd()) }) + assert.NotPanics(t, func() { MaybeHint(ctx, regularCmd(), noPluginRecorded) }) assert.Empty(t, hintKinds(t, ctx)) } @@ -294,13 +296,13 @@ func TestMaybeHint_ThrottledPerSession(t *testing.T) { } ctx1, stderr1 := newCtx() - MaybeHint(ctx1, regularCmd()) + MaybeHint(ctx1, regularCmd(), noPluginRecorded) assert.Contains(t, stderr1.String(), hintText) assert.Equal(t, []protos.AitoolsHintKind{protos.AitoolsHintKindInstallText}, hintKinds(t, ctx1)) // Same session id, second command: must stay quiet and log nothing. ctx2, stderr2 := newCtx() - MaybeHint(ctx2, regularCmd()) + MaybeHint(ctx2, regularCmd(), noPluginRecorded) assert.Empty(t, stderr2.String()) assert.Empty(t, hintKinds(t, ctx2)) } @@ -447,7 +449,7 @@ func TestMaybeHint_NativeHint(t *testing.T) { cmd = tc.cmd() } - MaybeHint(ctx, cmd) + MaybeHint(ctx, cmd, noPluginRecorded) assert.Equal(t, tc.wantStderr, stderr.String()) }) } @@ -457,10 +459,12 @@ func TestMaybeHint_NativeHintSilentForOtherCallers(t *testing.T) { for _, tc := range []struct { name string agentEnv []string + wantText string }{ - {"human", nil}, - {"other agent", []string{"CURSOR_AGENT", "1"}}, - {"multiple agents", []string{"CLAUDECODE", "1", "CURSOR_AGENT", "1"}}, + {"human", nil, ""}, + // Other agents get only their own text hint. + {"other agent", []string{"CURSOR_AGENT", "1"}, agentInstallHint(ByName(NameCursor), noPluginRecorded).text + "\n"}, + {"multiple agents", []string{"CLAUDECODE", "1", "CURSOR_AGENT", "1"}, ""}, } { t.Run(tc.name, func(t *testing.T) { testutil.SetAgentEnv(t, tc.agentEnv...) @@ -470,8 +474,8 @@ func TestMaybeHint_NativeHintSilentForOtherCallers(t *testing.T) { // Claude Code caller gets the native hint. ctx = env.Set(ctx, claudeChildSessionEnv, "1") - MaybeHint(ctx, regularCmd()) - assert.Empty(t, stderr.String()) + MaybeHint(ctx, regularCmd(), noPluginRecorded) + assert.Equal(t, tc.wantText, stderr.String()) }) } } @@ -491,19 +495,19 @@ func TestMaybeHint_NativeHintThrottledPerSession(t *testing.T) { } ctx1, stderr1 := newCtx() - MaybeHint(ctx1, regularCmd()) + MaybeHint(ctx1, regularCmd(), noPluginRecorded) assert.Equal(t, wantNativeHint+"\n"+hintText+"\n", stderr1.String()) // Same session, second command: both lines stay quiet, so the tag doesn't // reach a downstream reader such as `2>&1 | jq` on every command. ctx2, stderr2 := newCtx() - MaybeHint(ctx2, regularCmd()) + MaybeHint(ctx2, regularCmd(), noPluginRecorded) assert.Empty(t, stderr2.String()) // Another session: both lines print again. ctx3, stderr3 := newCtx() ctx3 = env.Set(ctx3, claudeSessionEnv, "session-def") - MaybeHint(ctx3, regularCmd()) + MaybeHint(ctx3, regularCmd(), noPluginRecorded) assert.Equal(t, wantNativeHint+"\n"+hintText+"\n", stderr3.String()) } @@ -540,7 +544,7 @@ func TestMaybeHint_NativeHintSilentOnTerminal(t *testing.T) { ctx = env.Set(ctx, "DATABRICKS_CACHE_DIR", t.TempDir()) ctx = env.Set(ctx, claudeChildSessionEnv, "1") - MaybeHint(ctx, regularCmd()) + MaybeHint(ctx, regularCmd(), noPluginRecorded) assert.Equal(t, hintText+"\n", stderr.String()) }) } @@ -552,14 +556,19 @@ func TestAgentHint_NativeLineNilIsEmpty(t *testing.T) { } func TestHintForAgent(t *testing.T) { - claude := hintForAgent(claudeAgentProvider) + claude := hintForAgent(claudeAgentProvider, noPluginRecorded) require.NotNil(t, claude) assert.Equal(t, hintText, claude.text) assert.Equal(t, claudeSessionEnv, claude.sessionEnv) - assert.Nil(t, hintForAgent("")) - assert.Nil(t, hintForAgent("multiple")) - assert.Nil(t, hintForAgent("cursor")) + assert.Nil(t, hintForAgent("", noPluginRecorded)) + assert.Nil(t, hintForAgent("multiple", noPluginRecorded)) + assert.Nil(t, hintForAgent("windsurf", noPluginRecorded)) + + cursor := hintForAgent("cursor", noPluginRecorded) + require.NotNil(t, cursor) + assert.Equal(t, protos.AitoolsHintKindAgentInstallText, cursor.textKind) + assert.Nil(t, cursor.native) } func TestMaybeHint_LogsEventsOncePerSession(t *testing.T) { @@ -580,7 +589,7 @@ func TestMaybeHint_LogsEventsOncePerSession(t *testing.T) { } ctx1, _ := newCtx(true) - MaybeHint(ctx1, regularCmd()) + MaybeHint(ctx1, regularCmd(), noPluginRecorded) assert.Equal(t, []protos.AitoolsHintKind{ protos.AitoolsHintKindClaudeCodeNative, protos.AitoolsHintKindInstallText, @@ -591,13 +600,13 @@ func TestMaybeHint_LogsEventsOncePerSession(t *testing.T) { // Throttled for the session: nothing prints and nothing logs, so the // command doesn't pay for a telemetry upload at exit. ctx2, stderr2 := newCtx(true) - MaybeHint(ctx2, regularCmd()) + MaybeHint(ctx2, regularCmd(), noPluginRecorded) assert.Empty(t, stderr2.String()) assert.Empty(t, telemetry.BufferedEvents(ctx2)) // Throttled and not a Claude Code subprocess: nothing prints, nothing logs. ctx3, stderr3 := newCtx(false) - MaybeHint(ctx3, regularCmd()) + MaybeHint(ctx3, regularCmd(), noPluginRecorded) assert.Empty(t, stderr3.String()) assert.Empty(t, telemetry.BufferedEvents(ctx3)) } @@ -610,6 +619,6 @@ func TestMaybeHint_InstalledLogsNothing(t *testing.T) { ctx = env.Set(ctx, claudeChildSessionEnv, "1") writePluginManifest(t, home, `{"plugins":{"databricks@claude-plugins-official":[{"scope":"user"}]}}`) - MaybeHint(ctx, regularCmd()) + MaybeHint(ctx, regularCmd(), noPluginRecorded) assert.Empty(t, telemetry.BufferedEvents(ctx)) } diff --git a/libs/aitools/installer/useragent.go b/libs/aitools/installer/useragent.go index 95a7cab6492..ff628e1d40d 100644 --- a/libs/aitools/installer/useragent.go +++ b/libs/aitools/installer/useragent.go @@ -63,15 +63,15 @@ func WithCallingAgentToolingInUserAgent(ctx context.Context) context.Context { if a == nil { return ctx } - tooling := a.DatabricksTooling(ctx, func() bool { return globalPluginRecorded(ctx, a.Name) }) + tooling := a.DatabricksTooling(ctx, func() bool { return GlobalPluginRecorded(ctx, a.Name) }) return useragent.InContext(ctx, callingAgentToolingUserAgentKey, tooling.String()) } -// globalPluginRecorded reports whether the global CLI install state records a +// GlobalPluginRecorded reports whether the global CLI install state records a // databricks plugin install for the agent. Only the global state is read: the // CLI installs plugins in project scope only for agents with SupportsProjectScope // (see mapAgentScope in cmd/aitools), and those have a manifest reader. -func globalPluginRecorded(ctx context.Context, agentName string) bool { +func GlobalPluginRecorded(ctx context.Context, agentName string) bool { dir, err := GlobalSkillsDir(ctx) if err != nil { return false diff --git a/libs/telemetry/protos/README.md b/libs/telemetry/protos/README.md index d07f4790963..4186b6614d7 100644 --- a/libs/telemetry/protos/README.md +++ b/libs/telemetry/protos/README.md @@ -6,15 +6,16 @@ which config options were set, the outcome and latency, and how long packaging a uploading the code snapshot took. It never includes code, paths, names, parameters, or image references. Set `DATABRICKS_CLI_DISABLE_TELEMETRY=1` to opt out. -The CLI logs an `aitools_hint_event` for each Claude Code install-hint line it prints (the native -`` line and the text line are one event each) and for the `apps init` skills tip -or install prompt. The install hint is never printed on aitools commands, `auth token`, -`auth docker token` or in CLI processes the CLI started itself. It carries only the kind of hint -(`hint_kind`); the command it was shown on is the entry's `execution_context.command`. The event -uploads at exit only when the command resolved auth. The install hint prints at most once per -Claude Code session per hour, so when the command that printed it resolves no auth (e.g. -`databricks version`), that session logs no install hint event for the next hour even though the -agent saw the hint. +The CLI logs an `aitools_hint_event` for each install-hint line it prints for a coding agent +(Claude Code's native `` line and its text line are one event each; another +agent's text line is one event) and for the `apps init` skills tip or install prompt. The install +hint is never printed on aitools commands, `auth token`, `auth docker token` or in CLI processes the +CLI started itself. It carries only the kind of hint (`hint_kind`); the command it was shown on is +the entry's `execution_context.command`. The event uploads at exit only when the command resolved +auth. The install hint prints at most once per hour per agent session (or per agent on the machine, +for agents without a session id), so when the command that printed it resolves no auth (e.g. +`databricks version`), no install hint event is logged for that hour even though the agent saw the +hint. `databricks aitools` install, update, list, version and uninstall log an `aitools_command_event` funnel per run: STARTED, one STEP_COMPLETED per install step reached (install only), and FINISHED diff --git a/libs/telemetry/protos/aitools_events.go b/libs/telemetry/protos/aitools_events.go index 50d7260aff9..37e0c548f41 100644 --- a/libs/telemetry/protos/aitools_events.go +++ b/libs/telemetry/protos/aitools_events.go @@ -13,8 +13,8 @@ const ( // `` line, which makes Claude Code offer to install the // Databricks plugin. AitoolsHintKindClaudeCodeNative AitoolsHintKind = "CLAUDE_CODE_NATIVE" - // AitoolsHintKindAgentInstallText mirrors an enum value of the proto for a - // hint the CLI does not print. Nothing logs it today. + // AitoolsHintKindAgentInstallText is the stderr line asking a non-Claude + // coding agent to run `databricks aitools install` for itself. AitoolsHintKindAgentInstallText AitoolsHintKind = "AGENT_INSTALL_TEXT" // AitoolsHintKindAppsInitTip is the non-interactive tip printed by // `databricks apps init`. @@ -24,13 +24,14 @@ const ( AitoolsHintKindAppsInitPrompt AitoolsHintKind = "APPS_INIT_PROMPT" ) -// AitoolsHintEvent is emitted once for each Claude Code install-hint line the -// CLI prints (the native line and the text line are one event each) and for the -// `apps init` skills tip or install prompt; other messages that mention -// `databricks aitools install` log nothing. It carries no user-authored strings. -// The command it was shown on is ExecutionContext.Command of the enclosing log -// entry. The CLI sets no calling-agent field on this event: the calling agent -// is reported by the User-Agent of the telemetry upload (`agent/`). +// AitoolsHintEvent is emitted once for each install-hint line the CLI prints +// for a coding agent (Claude Code's native and text lines are one event each) +// and for the `apps init` skills tip or install prompt; other messages that +// mention `databricks aitools install` log nothing. It carries no +// user-authored strings. The command it was shown on is ExecutionContext.Command +// of the enclosing log entry. The CLI sets no calling-agent field on this +// event: the calling agent is reported by the User-Agent of the telemetry +// upload (`agent/`). type AitoolsHintEvent struct { HintKind AitoolsHintKind `json:"hint_kind"` } From a057fddf37877bda9e72b3e59f3ddf52cbafbf48 Mon Sep 17 00:00:00 2001 From: Anton Nekipelov <226657+anton-107@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:02:46 +0000 Subject: [PATCH 3/6] aitools: address review feedback on the Claude Code native hint - inCI: treat CI=no/off as not CI, matching env.GetBool's false values, while any other non-empty value (e.g. a provider name) still means CI. - claudeToolingInstalled: share a package-level noRecordedPlugin with MaybeVersionCheckTip and drop the plugin version from the debug log, which re-parsed installed_plugins.json on every command. - Document that project/local plugin records count only when the CLI's cwd is inside the recorded project. - Tests: check a non-Databricks skill in ~/.claude/skills, drop the no-op env unsets after testutil.SetAgentEnv, cover CI=no/OFF. - Shorten the changelog fragment and lead with a verb. Co-authored-by: Isaac --- .nextchanges/cli/claude-code-native-hint.md | 2 +- libs/aitools/agents/calling.go | 4 ++ libs/aitools/agents/hint.go | 27 ++++++---- libs/aitools/agents/hint_test.go | 57 +++++++-------------- libs/aitools/agents/recommend.go | 1 - 5 files changed, 39 insertions(+), 52 deletions(-) diff --git a/.nextchanges/cli/claude-code-native-hint.md b/.nextchanges/cli/claude-code-native-hint.md index 64e8dfec9cb..c702be4dc0b 100644 --- a/.nextchanges/cli/claude-code-native-hint.md +++ b/.nextchanges/cli/claude-code-native-hint.md @@ -1 +1 @@ -* When Claude Code runs the CLI without the Databricks plugin or skills, the CLI now also prints Claude Code's native `` line, at most once per hour per Claude Code session together with the text hint, so Claude Code offers a one-click install of the Databricks plugin. Skills stored only in `~/.databricks/aitools/skills` or the legacy `~/.databricks/agent-skills` no longer count as installed for Claude Code, and `databricks auth token`, `databricks auth docker token` and the CLI commands that `databricks air images push` and `databricks apps init` run as subprocesses no longer print install hints. ([#7585](https://github.com/databricks/cli/pull/7585)) +* Print Claude Code's native plugin install hint alongside the text hint, so Claude Code offers a one-click install of the Databricks plugin. Claude Code now counts as having the tooling only when it loads it: skills only in `~/.databricks/aitools/skills` don't count, and a project- or local-scope plugin counts only when the CLI runs inside that project. `auth token`, `auth docker token` and CLI subprocesses no longer print install hints. ([#7585](https://github.com/databricks/cli/pull/7585)) diff --git a/libs/aitools/agents/calling.go b/libs/aitools/agents/calling.go index 4dcf73d6c6f..721d6eef145 100644 --- a/libs/aitools/agents/calling.go +++ b/libs/aitools/agents/calling.go @@ -93,6 +93,10 @@ func (a *Agent) DatabricksTooling(ctx context.Context, pluginRecorded func() boo return ToolingNone } +// noRecordedPlugin is the pluginRecorded argument to DatabricksTooling for +// callers that don't consult the CLI install record. +func noRecordedPlugin() bool { return false } + // projectDirs returns cwd and each of its parents up to the repository root, // the nearest directory holding .git (a file in a git worktree, so the walk // stops at the worktree root). Claude Code loads project skills the same way, diff --git a/libs/aitools/agents/hint.go b/libs/aitools/agents/hint.go index dce48cd4503..f443ba28142 100644 --- a/libs/aitools/agents/hint.go +++ b/libs/aitools/agents/hint.go @@ -2,7 +2,7 @@ package agents import ( "context" - "strconv" + "strings" "time" "github.com/databricks/cli/libs/cache" @@ -209,12 +209,14 @@ func claudeNativeHintLine(ctx context.Context) string { // inCI reports whether the CLI runs in CI: the generic CI variable set to // anything but an explicit false (some providers set it to their own name), or // any provider the SDK detects for its user agent (e.g. Azure Pipelines' -// TF_BUILD, which doesn't set CI). +// TF_BUILD, which doesn't set CI). The false values are the ones env.GetBool +// accepts; GetBool itself can't be used because it also maps a provider name +// to false. func inCI(ctx context.Context) bool { - if v := env.Get(ctx, ciEnv); v != "" { - if b, err := strconv.ParseBool(v); err != nil || b { - return true - } + switch strings.ToLower(env.Get(ctx, ciEnv)) { + case "", "0", "f", "false", "no", "off": + default: + return true } return useragent.CiCdProvider() != "" } @@ -247,8 +249,12 @@ func isAIToolsCommand(cmd *cobra.Command) bool { // in its own locations (see Agent.DatabricksTooling): the databricks plugin, or // databricks skills in Claude's skills dirs. Skills present only in the shared // ~/.databricks/aitools/skills store don't count, because Claude Code doesn't -// load them from there. Any read/parse failure reports false, so an unreadable -// state errs toward hinting. +// load them from there. A plugin recorded with project or local scope counts +// only when the CLI's working directory is inside the recorded project: Claude +// Code loads it from the directory it started in, which the CLI can't see, so +// a session started in the project that runs `cd /tmp/x && databricks ...` is +// hinted. Any read/parse failure reports false, so an unreadable state errs +// toward hinting. func claudeToolingInstalled(ctx context.Context) bool { claude := ByName(NameClaudeCode) if claude == nil { @@ -258,10 +264,9 @@ func claudeToolingInstalled(ctx context.Context) bool { } // Claude Code's own manifest decides, so the CLI's install record is never // consulted for it. - tooling := claude.DatabricksTooling(ctx, func() bool { return false }) + tooling := claude.DatabricksTooling(ctx, noRecordedPlugin) if tooling == ToolingPlugin { - version, _ := claude.DatabricksPluginVersion(ctx) - log.Debugf(ctx, "Databricks plugin detected for Claude Code (version %q); skipping install hint", version) + log.Debugf(ctx, "Databricks plugin detected for Claude Code; skipping install hint") } return tooling != ToolingNone } diff --git a/libs/aitools/agents/hint_test.go b/libs/aitools/agents/hint_test.go index e92d02af488..910fb789982 100644 --- a/libs/aitools/agents/hint_test.go +++ b/libs/aitools/agents/hint_test.go @@ -23,38 +23,16 @@ import ( "github.com/stretchr/testify/require" ) -// hintEnvVars are the non-detection env vars MaybeHint reads. They are cleared -// so a test run from inside Claude Code or CI sees none of the host's values. -var hintEnvVars = []string{ - claudeChildSessionEnv, claudeSessionEnv, ciEnv, "CLAUDE_CONFIG_DIR", - // CI/CD provider markers read by useragent.CiCdProvider(). - "GITHUB_ACTIONS", "GITLAB_CI", "JENKINS_URL", "TF_BUILD", "CIRCLECI", "TRAVIS", - "BITBUCKET_BUILD_NUMBER", "PROJECT_ID", "CODEBUILD_BUILD_ARN", "TFC_RUN_ID", -} - -// unsetEnv unsets vars for the test and restores them afterwards. t.Setenv -// cannot unset, hence the manual save/restore. -func unsetEnv(t *testing.T, vars []string) { - for _, v := range vars { - if orig, ok := os.LookupEnv(v); ok { - t.Cleanup(func() { os.Setenv(v, orig) }) //nolint:usetesting // restoring, not setting fresh - os.Unsetenv(v) //nolint:usetesting // t.Setenv cannot unset - } - } -} - // setClaudeAgent makes useragent.AgentProvider() report Claude Code for this // test, with the host's agent and hint env cleared. These tests must not run -// in parallel (see testutil.SetAgentEnv). The first t.TempDir call runs before -// SetAgentEnv clears TMPDIR / TEMP, so later calls in the test still work. -// It also moves into an empty project with its own .git boundary, so project -// skills in the checkout running the tests are not detected. +// in parallel (see testutil.SetAgentEnv). It also moves into an empty project +// with its own .git boundary, so project skills in the checkout running the +// tests are not detected. func setClaudeAgent(t *testing.T) { cwd := t.TempDir() require.NoError(t, os.Mkdir(filepath.Join(cwd, ".git"), 0o755)) t.Chdir(cwd) testutil.SetAgentEnv(t, "CLAUDECODE", "1") - unsetEnv(t, hintEnvVars) } // claudeCtx returns a context with a captured stderr buffer and an isolated @@ -75,10 +53,6 @@ func writePluginManifest(t *testing.T, home, body string) { require.NoError(t, os.WriteFile(filepath.Join(dir, "installed_plugins.json"), []byte(body), 0o600)) } -func writeCanonicalSkill(t *testing.T, home, name string) { - require.NoError(t, os.MkdirAll(filepath.Join(home, ".databricks", "aitools", "skills", name), 0o755)) -} - // hintKinds returns the kinds of the hint-shown events buffered on ctx, // failing on any other event so a stray event cannot hide behind the filter. func hintKinds(t *testing.T, ctx context.Context) []protos.AitoolsHintKind { @@ -164,8 +138,9 @@ func TestMaybeHint_ProjectPluginCountsOnlyInItsProject(t *testing.T) { } } -func TestClaudeToolingInstalled_LogsPluginVersion(t *testing.T) { - unsetEnv(t, hintEnvVars) +func TestClaudeToolingInstalled_LogsPluginDetected(t *testing.T) { + // Clears the host's CLAUDE_CONFIG_DIR, which would move the manifest. + testutil.SetAgentEnv(t) home := t.TempDir() writePluginManifest(t, home, `{"plugins":{"databricks@claude-plugins-official":[{"version":"0.2.6"}]}}`) @@ -177,12 +152,7 @@ func TestClaudeToolingInstalled_LogsPluginVersion(t *testing.T) { assert.True(t, claudeToolingInstalled(ctx)) - // The text handler escapes the inner quotes around the version, so assert on - // the stable, unescaped fragments rather than the full quoted message. - out := buf.String() - assert.Contains(t, out, "Databricks plugin detected for Claude Code") - assert.Contains(t, out, "0.2.6") - assert.Contains(t, out, "skipping install hint") + assert.Contains(t, buf.String(), "Databricks plugin detected for Claude Code; skipping install hint") } func TestMaybeHint_CustomClaudeConfigDir(t *testing.T) { @@ -251,7 +221,7 @@ func TestMaybeHint_NonDatabricksSkillStillHints(t *testing.T) { setClaudeAgent(t) home := t.TempDir() ctx, stderr := claudeCtx(t, home) - writeCanonicalSkill(t, home, "some-other-skill") + writeClaudeSkill(t, home, "some-other-skill") MaybeHint(ctx, regularCmd()) assert.Contains(t, stderr.String(), hintText) @@ -355,6 +325,16 @@ func TestMaybeHint_NativeHint(t *testing.T) { env: map[string]string{claudeChildSessionEnv: "1", ciEnv: "false"}, wantStderr: wantNativeHint + "\n" + hintText + "\n", }, + { + name: "CI=no still prints native", + env: map[string]string{claudeChildSessionEnv: "1", ciEnv: "no"}, + wantStderr: wantNativeHint + "\n" + hintText + "\n", + }, + { + name: "CI=OFF still prints native", + env: map[string]string{claudeChildSessionEnv: "1", ciEnv: "OFF"}, + wantStderr: wantNativeHint + "\n" + hintText + "\n", + }, { // Some providers set CI to their own name. name: "CI set to a provider name prints text only", @@ -464,7 +444,6 @@ func TestMaybeHint_NativeHintSilentForOtherCallers(t *testing.T) { } { t.Run(tc.name, func(t *testing.T) { testutil.SetAgentEnv(t, tc.agentEnv...) - unsetEnv(t, hintEnvVars) ctx, stderr := claudeCtx(t, t.TempDir()) // Even with Claude's child-session marker present, only a sole // Claude Code caller gets the native hint. diff --git a/libs/aitools/agents/recommend.go b/libs/aitools/agents/recommend.go index 14a4da5b00b..f54dc5c3548 100644 --- a/libs/aitools/agents/recommend.go +++ b/libs/aitools/agents/recommend.go @@ -42,7 +42,6 @@ func MaybeVersionCheckTip(ctx context.Context, installedPlugins func(context.Con // Recorded plugins are checked above, so DatabricksTooling only needs the // agent's own manifest, its skills dir and the project dirs up to the // repository root. - noRecordedPlugin := func() bool { return false } for _, a := range Registry { if a.DatabricksTooling(ctx, noRecordedPlugin) != ToolingNone { return From 2bb6ce5bd39850419d99e50d03ce5b96e73d22db Mon Sep 17 00:00:00 2001 From: Anton Nekipelov <226657+anton-107@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:02:21 +0000 Subject: [PATCH 4/6] aitools: skip the version --check tip for every hinted agent MaybeVersionCheckTip skipped only Claude Code, but MaybeHint now hints the registry agents too, so a Codex caller saw the root hook's `install --agents codex --scope global` line followed by the generic tip. Skip the tip whenever hintForAgent would hint the caller. Co-authored-by: Isaac --- acceptance/cmd/version/output.txt | 7 +++++++ acceptance/cmd/version/script | 10 +++++++++- libs/aitools/agents/hint.go | 8 ++++++++ libs/aitools/agents/recommend.go | 10 ++++++---- libs/aitools/agents/recommend_test.go | 2 ++ 5 files changed, 32 insertions(+), 5 deletions(-) diff --git a/acceptance/cmd/version/output.txt b/acceptance/cmd/version/output.txt index 56a4d16ed95..7fc22af691d 100644 --- a/acceptance/cmd/version/output.txt +++ b/acceptance/cmd/version/output.txt @@ -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. diff --git a/acceptance/cmd/version/script b/acceptance/cmd/version/script index 3e72d659289..58a59538f05 100644 --- a/acceptance/cmd/version/script +++ b/acceptance/cmd/version/script @@ -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 diff --git a/libs/aitools/agents/hint.go b/libs/aitools/agents/hint.go index fde8b25bb04..1061191884e 100644 --- a/libs/aitools/agents/hint.go +++ b/libs/aitools/agents/hint.go @@ -152,6 +152,14 @@ func hintForAgent(provider string, pluginRecorded PluginRecordedFunc) *agentHint } } +// 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 { diff --git a/libs/aitools/agents/recommend.go b/libs/aitools/agents/recommend.go index 14a4da5b00b..e54b98fd8c8 100644 --- a/libs/aitools/agents/recommend.go +++ b/libs/aitools/agents/recommend.go @@ -22,15 +22,17 @@ func PrintSkillsTip(ctx context.Context) { } // MaybeVersionCheckTip prints skillsTipText after `databricks version --check` -// when a coding agent is detected without Databricks tooling. Claude Code -// callers are skipped because MaybeHint already covers them, with its -// per-session throttle. installedPlugins is a parameter because this package +// when a coding agent is detected without Databricks tooling. Callers that +// MaybeHint hints (Claude Code and the registry agents, see isHintedAgent) are +// skipped: the root hook already names the install command for them, with its +// own throttle, and a second, different command in the same run would compete +// with it. installedPlugins is a parameter because this package // cannot import the installer; callers pass installer.InstalledPluginAgents, // which counts a plugin recorded in the CLI install state with or without a // known version. No telemetry is logged: `databricks version` never resolves // auth, so the event would not be uploaded (see logHintShown). func MaybeVersionCheckTip(ctx context.Context, installedPlugins func(context.Context) []string) { - if useragent.AgentProvider() == claudeAgentProvider { + if isHintedAgent(useragent.AgentProvider()) { return } if dbr.HasDetection(ctx) && dbr.RunsOnRuntime(ctx) { diff --git a/libs/aitools/agents/recommend_test.go b/libs/aitools/agents/recommend_test.go index 02b110f149e..aaf978bb9d1 100644 --- a/libs/aitools/agents/recommend_test.go +++ b/libs/aitools/agents/recommend_test.go @@ -162,6 +162,8 @@ func TestMaybeVersionCheckTip(t *testing.T) { {name: "skills only in the agent's own skills dir", agentDirs: []string{".cursor"}, agentSkills: true, installedPlugins: noPlugins}, {name: "databricks runtime", agentDirs: []string{".codex"}, onDBR: true, installedPlugins: noPlugins}, {name: "claude code caller is left to MaybeHint", agentEnv: []string{"CLAUDECODE", "1"}, agentDirs: []string{".claude"}, installedPlugins: noPlugins}, + {name: "codex caller is left to MaybeHint", agentEnv: []string{"CODEX_CI", "1"}, agentDirs: []string{".codex"}, installedPlugins: noPlugins}, + {name: "several agents calling get the tip, since MaybeHint skips them", agentEnv: []string{"CLAUDECODE", "1", "CODEX_CI", "1"}, agentDirs: []string{".codex"}, installedPlugins: noPlugins, wantTip: true}, } { t.Run(tc.name, func(t *testing.T) { home := t.TempDir() From 84c0701d62ea9b95587e05f9a3373c4d8438d383 Mon Sep 17 00:00:00 2001 From: Anton Nekipelov <226657+anton-107@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:02:41 +0000 Subject: [PATCH 5/6] aitools: address review on non-Claude agent install hints Build the agent hint from hintText, correct the doc comments on what --agents/--scope do for agent callers and on Claude's throttle key, cite the Codex source for CODEX_THREAD_ID, note the Cursor plugin gap, and add a portable DATABRICKS_CACHE_ENABLED=false test next to the chmod-based one. Co-authored-by: Isaac --- libs/aitools/agents/hint.go | 10 +++++----- libs/aitools/agents/hint_agents.go | 19 +++++++++++-------- libs/aitools/agents/hint_agents_test.go | 17 +++++++++++++++++ 3 files changed, 33 insertions(+), 13 deletions(-) diff --git a/libs/aitools/agents/hint.go b/libs/aitools/agents/hint.go index 1061191884e..f9f0a8cd1d7 100644 --- a/libs/aitools/agents/hint.go +++ b/libs/aitools/agents/hint.go @@ -108,7 +108,8 @@ type agentHint struct { // 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. + // 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 @@ -118,8 +119,8 @@ type agentHint struct { // 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. + // 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 // native returns a line the agent itself acts on (for Claude Code, its @@ -310,8 +311,7 @@ func claudeToolingInstalled(ctx context.Context) bool { } // 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. +// 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 diff --git a/libs/aitools/agents/hint_agents.go b/libs/aitools/agents/hint_agents.go index a566eec993a..20789749e5c 100644 --- a/libs/aitools/agents/hint_agents.go +++ b/libs/aitools/agents/hint_agents.go @@ -11,7 +11,8 @@ import ( // 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. + // 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", } @@ -21,22 +22,24 @@ var agentSessionEnv = map[string]string{ 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. +// 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 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. +// 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 { 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", + text: hintText + " --agents " + a.Name + " --scope global", textKind: protos.AitoolsHintKindAgentInstallText, sessionEnv: agentSessionEnv[a.Name], sessionKeyPrefix: a.Name + ":session:", diff --git a/libs/aitools/agents/hint_agents_test.go b/libs/aitools/agents/hint_agents_test.go index e8f954dc1eb..8248c86b1e4 100644 --- a/libs/aitools/agents/hint_agents_test.go +++ b/libs/aitools/agents/hint_agents_test.go @@ -307,3 +307,20 @@ func TestMaybeHint_UnwritableCacheSkipsHint(t *testing.T) { require.NoError(t, err) assert.Empty(t, entries) } + +func TestMaybeHint_DisabledCacheSkipsHint(t *testing.T) { + // The portable twin of TestMaybeHint_UnwritableCacheSkipsHint: with caching + // off no marker reads back, so the hint is skipped rather than repeated. + setAgentEnv(t, "CODEX_CI") + home, cacheDir := t.TempDir(), t.TempDir() + + for range 2 { + ctx, stderr := agentCtx(t, home, cacheDir) + ctx = env.Set(ctx, "DATABRICKS_CACHE_ENABLED", "false") + ctx = telemetry.WithNewLogger(ctx) + ctx = env.Set(ctx, "CODEX_THREAD_ID", "thread-1") + MaybeHint(ctx, regularCmd(), noPluginRecorded) + assert.Empty(t, stderr.String()) + assert.Empty(t, telemetry.BufferedEvents(ctx)) + } +} From 6664c2d299e91943e5042bd7a870464ea88c445f Mon Sep 17 00:00:00 2001 From: Anton Nekipelov <226657+anton-107@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:26:11 +0000 Subject: [PATCH 6/6] aitools: adapt agent hint tests to the base's test helpers The base dropped unsetEnv/hintEnvVars (testutil.SetAgentEnv now clears the whole environment) and writeCanonicalSkill, which only these tests use. Co-authored-by: Isaac --- libs/aitools/agents/hint_agents_test.go | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/libs/aitools/agents/hint_agents_test.go b/libs/aitools/agents/hint_agents_test.go index 8248c86b1e4..7d00aa1840d 100644 --- a/libs/aitools/agents/hint_agents_test.go +++ b/libs/aitools/agents/hint_agents_test.go @@ -75,7 +75,12 @@ var agentDetectEnv = map[string]string{ // with the host's agent and hint env cleared (see testutil.SetAgentEnv). func setAgentEnv(t *testing.T, envVar string) { testutil.SetAgentEnv(t, envVar, "1") - unsetEnv(t, append([]string{"CODEX_THREAD_ID"}, hintEnvVars...)) +} + +// writeCanonicalSkill creates a skill in the shared ~/.databricks/aitools/skills +// store, which no agent loads by itself. +func writeCanonicalSkill(t *testing.T, home, name string) { + require.NoError(t, os.MkdirAll(filepath.Join(home, ".databricks", "aitools", "skills", name), 0o755)) } // agentCtx returns a hint test context whose agent config dirs all resolve