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] 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"` }