Skip to content

aitools: emit Claude Code's native plugin install hint - #7585

Merged
anton-107 merged 2 commits into
mainfrom
aitools/claude-code-native-hint
Nov 16, 2026
Merged

anton-107 merged 2 commits into
mainfrom
aitools/claude-code-native-hint

Conversation

@anton-107

@anton-107 anton-107 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Changes

When Claude Code runs the CLI without the Databricks plugin or skills, the install hint now also prints Claude Code's native <claude-code-hint> line, which makes Claude Code offer a one-click install of databricks@claude-plugins-official.

 MaybeHint(ctx, cmd)                         # libs/aitools/agents/hint.go
   hint := hintForAgent(AgentProvider())     # only Claude Code has one
   skip: aitools commands
+  skip: `auth token`, `auth docker token`   # their stderr is embedded in other tools' errors
+  skip: DATABRICKS_CLI_SELF_EXEC set        # CLI started by the CLI (air images push, apps init)
   skip: no IO, hinted this session within 1h
-  skip: plugin, or skills in ~/.databricks/aitools/skills or legacy store
+  skip: Agent.DatabricksTooling != none     # only what Claude Code itself loads
+  if CLAUDE_CODE_CHILD_SESSION set and not CI and no stdin/stdout/stderr terminal
+    print <claude-code-hint .../>, log hint event CLAUDE_CODE_NATIVE
   print text hint, log hint event INSTALL_TEXT
   record session marker                     # throttles both lines together
  • Claude Code detection now uses Agent.DatabricksTooling: skills only in the shared ~/.databricks/aitools/skills store (or the legacy ~/.databricks/agent-skills) no longer count, and a plugin recorded with project or local scope counts only when the CLI's working directory is inside the recorded project.
  • CI counts as unset for the same false values env.GetBool accepts (0, false, no, off, ...); any other value, such as a provider name, means CI.
  • cmdio.HasTerminal (any standard stream is a TTY) and cmdio.FakeTTYReader for tests.
  • agents.SelfExecEnv is set on the child processes of air images push (auth docker configure) and apps init (post-create deploy/dev runs).
  • Telemetry docs (protos/README.md, aitools_events.go): one aitools_hint_event per printed hint line.
  • Changelog fragment: .nextchanges/cli/claude-code-native-hint.md.

Why

The text hint asks the model to run databricks aitools install; the native line lets Claude Code offer the user the plugin install directly. Claude Code shows that dialog only in an attended session, at most once per session and once ever per plugin, and strips the tag before the model sees the output. The native line is gated so a human never sees the raw tag: it needs CLAUDE_CODE_CHILD_SESSION (IDE terminals don't set it), no terminal on any standard stream (tmux or a shell started from inside Claude Code inherit the env), and no CI. auth token, auth docker token and CLI-spawned CLI processes are skipped because their stderr is embedded mid-line in another tool's error, where Claude Code can't strip the tag.

Detection follows what Claude Code itself loads, so the hint fires exactly when Claude Code has no Databricks tooling. Claude Code loads project and local plugins from the directory it started in, which the CLI can't see, so the CLI's cwd stands in for it. As a result a session started in ~/repo with a project-scoped plugin that runs cd /tmp/x && databricks ... now gets the hint; before this PR any plugin record kept it quiet.

Door: two-way. Pure CLI output and telemetry change; reverting removes the line. No exit code changes and no extra network calls.

Blast radius: small.

  • New stderr line under Claude Code on the first eligible command per session per hour; a 2>&1 | jq pipeline in that command reads it raw. With the file cache disabled, both lines print on every eligible command.
  • Skills only in ~/.databricks/aitools/skills or ~/.databricks/agent-skills no longer silence the hint for Claude Code, and project/local plugins silence it only inside their project.
  • auth token, auth docker token and CLI-spawned CLI processes no longer print any install hint.
  • A new hint kind, CLAUDE_CODE_NATIVE, is logged.
  • Not tested on Windows or macOS.

Tests

Run with the host's agent and CI env scrubbed.

  • Before (the native-print block in MaybeHint removed, tests unchanged):
    --- FAIL: TestMaybeHint_NativeHint (claude child session prints native then text, CI=false still prints native, ...)
    --- FAIL: TestMaybeHint_NativeHintThrottledPerSession
    --- FAIL: TestMaybeHint_LogsEventsOncePerSession
    --- FAIL: TestAccept/cmd/aitools/telemetry/hint
    --- FAIL: TestAccept/cmd/aitools/claude-config-dir
    
    After:
    ok  libs/aitools/agents, libs/cmdio, libs/telemetry/..., cmd/air
    ok  TestAccept/cmd/aitools/... (10 cases), TestAccept/air/image-push
    
  • TestAccept/air/image-push: inside a simulated Claude Code session, the auth docker configure child adds no hint to the parent's output or to its error text.
  • TestMaybeHint_NativeHint also covers: CI (CI=true, CI=<provider name>, TF_BUILD) prints the text only, CI=false/no/OFF still print the native line; plugin or Claude skills installed prints nothing; auth token, auth docker token, self-exec and aitools commands print nothing.
  • TestMaybeHint_ProjectPluginCountsOnlyInItsProject: a project-scoped plugin silences the hint only inside its project.
  • TestMaybeHint_NativeHintSilentOnTerminal: a terminal on stdin, stdout or stderr drops the native line.

This pull request and its description were written by Isaac.

@anton-107
anton-107 requested review from a team and lennartkats-db as code owners November 13, 2026 06:01
@anton-107
anton-107 requested review from misha-db and rauchy November 13, 2026 06:01
When Claude Code runs the CLI without the Databricks plugin or skills, the
install hint now also prints Claude Code's native `<claude-code-hint>` 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 <no-reply@databricks.com>
@anton-107
anton-107 force-pushed the aitools/claude-code-native-hint branch from 028eb23 to 07a831d Compare November 13, 2026 06:01
@github-actions github-actions Bot added the AIR Databricks AI Runtime CLI label Nov 13, 2026
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Commit: a057fddf3 | Workflow run

Regression test report

Selected 3 changed tests (limit=20, 0 not selected)

3 tests: regression=3 unreleased=0 coverage=0 failing=0
test branch main (e1316e5) latest (v1.26.0)
TestAccept/air/image-push ✅ ❌ ❌
TestAccept/cmd/aitools/claude-config-dir ✅ ❌ ❌
TestAccept/cmd/aitools/telemetry/hint ✅ ❌ ❌
TestAccept/air/image-push: branch ✅ | main (e1316e5) ❌ | latest (v1.26.0) ❌

main (e1316e5):

acceptance_test.go:1378: Diff:
        --- air/image-push/output.txt
        +++ /tmp/TestAcceptairimage-push2593210454/002/output.txt
        @@ -217,10 +217,10 @@
         === 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
        -<claude-code-hint v="1" type="plugin" value="databricks@claude-plugins-official" />
         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
        +Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install
         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
        @@ -232,8 +229,8 @@
         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
        -<claude-code-hint v="1" type="plugin" value="databricks@claude-plugins-official" />
         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
        +Error: configure Docker authentication: run auth docker configure: exit status 1: Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install
        +Error: profile "pat-test" uses auth_type "pat". Docker credential helper requires a profile created by databricks auth login
        
FAIL

latest (v1.26.0):

acceptance_test.go:1378: Diff:
        --- air/image-push/output.txt
        +++ /tmp/TestAcceptairimage-push134363756/002/output.txt
        @@ -150,18 +150,18 @@
           databricks air images push [flags]
         
         Flags:
        -      --artifact string     Destination ARTIFACT[:TAG]; defaults to the source image name and tag (latest if untagged); maximum 255 characters for catalog.schema.artifact and 128 for the tag
        -      --catalog string      Destination Unity Catalog catalog; use lowercase letters and digits separated by one or two underscores or one or more hyphens
        -  -h, --help[=true|false]   help for push
        -      --pull[=true|false]   Pull the source image even when it is already available locally
        -      --schema string       Destination Unity Catalog schema; use lowercase letters and digits separated by one or two underscores or one or more hyphens
        -  -s, --source string       Source container image to push (NAME[:TAG] or NAME@DIGEST)
        +      --artifact string   Destination ARTIFACT[:TAG]; defaults to the source image name and tag (latest if untagged); maximum 255 characters for catalog.schema.artifact and 128 for the tag
        +      --catalog string    Destination Unity Catalog catalog; use lowercase letters and digits separated by one or two underscores or one or more hyphens
        +  -h, --help              help for push
        +      --pull              Pull the source image even when it is already available locally
        +      --schema string     Destination Unity Catalog schema; use lowercase letters and digits separated by one or two underscores or one or more hyphens
        +  -s, --source string     Source container image to push (NAME[:TAG] or NAME@DIGEST)
         
         Global Flags:
        -      --debug[=true|false]   enable debug logging
        -  -o, --output type          output type: text or json (default text)
        -  -p, --profile string       ~/.databrickscfg profile
        -  -t, --target string        bundle target to use (if applicable)
        +      --debug            enable debug logging
        +  -o, --output type      output type: text or json (default text)
        +  -p, --profile string   ~/.databrickscfg profile
        +  -t, --target string    bundle target to use (if applicable)
         
         
         >>> musterr databricks air images push --image artifact
        @@ -171,18 +169,18 @@
           databricks air images push [flags]
         
         Flags:
        -      --artifact string     Destination ARTIFACT[:TAG]; defaults to the source image name and tag (latest if untagged); maximum 255 characters for catalog.schema.artifact and 128 for the tag
        -      --catalog string      Destination Unity Catalog catalog; use lowercase letters and digits separated by one or two underscores or one or more hyphens
        -  -h, --help[=true|false]   help for push
        -      --pull[=true|false]   Pull the source image even when it is already available locally
        -      --schema string       Destination Unity Catalog schema; use lowercase letters and digits separated by one or two underscores or one or more hyphens
        -  -s, --source string       Source container image to push (NAME[:TAG] or NAME@DIGEST)
        +      --artifact string   Destination ARTIFACT[:TAG]; defaults to the source image name and tag (latest if untagged); maximum 255 characters for catalog.schema.artifact and 128 for the tag
        +      --catalog string    Destination Unity Catalog catalog; use lowercase letters and digits separated by one or two underscores or one or more hyphens
        +  -h, --help              help for push
        +      --pull              Pull the source image even when it is already available locally
        +      --schema string     Destination Unity Catalog schema; use lowercase letters and digits separated by one or two underscores or one or more hyphens
        +  -s, --source string     Source container image to push (NAME[:TAG] or NAME@DIGEST)
         
         Global Flags:
        -      --debug[=true|false]   enable debug logging
        -  -o, --output type          output type: text or json (default text)
        -  -p, --profile string       ~/.databrickscfg profile
        -  -t, --target string        bundle target to use (if applicable)
        +      --debug            enable debug logging
        +  -o, --output type      output type: text or json (default text)
        +  -p, --profile string   ~/.databrickscfg profile
        +  -t, --target string    bundle target to use (if applicable)
         
         
         === reject oversized catalog.schema.artifact before Docker operations
        @@ -217,10 +213,10 @@
         === 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
        -<claude-code-hint v="1" type="plugin" value="databricks@claude-plugins-official" />
         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
        +Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install
         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
        @@ -232,8 +225,8 @@
         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
        -<claude-code-hint v="1" type="plugin" value="databricks@claude-plugins-official" />
         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
        +Error: configure Docker authentication: run auth docker configure: exit status 1: Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install
        +Error: profile "pat-test" uses auth_type "pat". Docker credential helper requires a profile created by databricks auth login
        
FAIL
TestAccept/cmd/aitools/claude-config-dir: branch ✅ | main (e1316e5) ❌ | latest (v1.26.0) ❌

main (e1316e5):

acceptance_test.go:1378: Diff:
        --- cmd/aitools/claude-config-dir/output.txt
        +++ /tmp/TestAcceptcmdaitoolsclaude-config-dir3341432099/002/output.txt
        @@ -7,7 +7,6 @@
         === Custom directory takes precedence over the default installation
         
         >>> CLAUDE_CONFIG_DIR=missing [CLI] version
        -<claude-code-hint v="1" type="plugin" value="databricks@claude-plugins-official" />
         Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install
         Databricks CLI v[CLI_VERSION]
         
        @@ -30,7 +29,6 @@
         === Within one session both lines print once, so 2>&1 pipelines see them only on the first command
         
         >>> [CLI] version
        -<claude-code-hint v="1" type="plugin" value="databricks@claude-plugins-official" />
         Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install
         Databricks CLI v[CLI_VERSION]

latest (v1.26.0): same output as main (e1316e5)

TestAccept/cmd/aitools/telemetry/hint: branch ✅ | main (e1316e5) ❌ | latest (v1.26.0) ❌

main (e1316e5):

acceptance_test.go:1246: Substituted DATABRICKS_CLI_GITHUB_API_URL "$DATABRICKS_HOST" -> "http://127.0.0.1:40345" ("[DATABRICKS_HOST]")
    acceptance_test.go:1246: Substituted DATABRICKS_SKILLS_BASE_URL "$DATABRICKS_HOST" -> "http://127.0.0.1:40345" ("[DATABRICKS_HOST]")
    acceptance_test.go:1378: 
        	Error Trace:	/home/runner/work/cli/cli/libs/testdiff/testdiff.go:22
        	            				/home/runner/work/cli/cli/acceptance/acceptance_test.go:1378
        	            				/home/runner/work/cli/cli/acceptance/acceptance_test.go:1119
        	            				/home/runner/work/cli/cli/acceptance/acceptance_test.go:664
        	Error:      	Not equal: 
        	            	expected: "\n=== hint printed on an authenticated command: one hint-shown event per printed line is uploaded\n\n>>> [CLI] jobs list\n<claude-code-hint v=\"1\" type=\"plugin\" value=\"databricks@claude-plugins-official\" />\nDatabricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install\n\n>>> print_telemetry\n{\"command\":\"jobs_list\",\"exit_code\":0,\"aitools_hint_event\":{\"hint_kind\":\"CLAUDE_CODE_NATIVE\"}}\n{\"command\":\"jobs_list\",\"exit_code\":0,\"aitools_hint_event\":{\"hint_kind\":\"INSTALL_TEXT\"}}\n\n=== hint printed on a command that resolves no auth: nothing is uploaded\n\n>>> [CLI] version\n<claude-code-hint v=\"1\" type=\"plugin\" value=\"databricks@claude-plugins-official\" />\nDatabricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install\nDatabricks CLI v[CLI_VERSION]\n\n>>> print_telemetry\n\n=== plugin installed: no hint, no event\n\n>>> [CLI] jobs list\n\n>>> print_telemetry\n"
        	            	actual  : "\n=== hint printed on an authenticated command: one hint-shown event per printed line is uploaded\n\n>>> [CLI] jobs list\nDatabricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install\n\n>>> print_telemetry\n{\"command\":\"jobs_list\",\"exit_code\":0,\"aitools_hint_event\":{\"hint_kind\":\"INSTALL_TEXT\"}}\n\n=== hint printed on a command that resolves no auth: nothing is uploaded\n\n>>> [CLI] version\nDatabricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install\nDatabricks CLI v[CLI_VERSION]\n\n>>> print_telemetry\n\n=== plugin installed: no hint, no event\n\n>>> [CLI] jobs list\n\n>>> print_telemetry\n"
        	            	
        	            	Diff:
        	            	--- Expected
        	            	+++ Actual
        	            	@@ -4,3 +4,2 @@
        	            	 >>> [CLI] jobs list
        	            	-<claude-code-hint v="1" type="plugin" value="databricks@claude-plugins-official" />
        	            	 Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install
        	            	@@ -8,3 +7,2 @@
        	            	 >>> 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"}}
        	            	@@ -14,3 +12,2 @@
        	            	 >>> [CLI] version
        	            	-<claude-code-hint v="1" type="plugin" value="databricks@claude-plugins-official" />
        	            	 Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install
        	Test:       	TestAccept/cmd/aitools/telemetry/hint
        	Messages:   	cmd/aitools/telemetry/hint/output.txt vs /tmp/TestAcceptcmdaitoolstelemetryhint151532107/002/output.txt

latest (v1.26.0):

acceptance_test.go:1246: Substituted DATABRICKS_CLI_GITHUB_API_URL "$DATABRICKS_HOST" -> "http://127.0.0.1:43519" ("[DATABRICKS_HOST]")
    acceptance_test.go:1246: Substituted DATABRICKS_SKILLS_BASE_URL "$DATABRICKS_HOST" -> "http://127.0.0.1:43519" ("[DATABRICKS_HOST]")
    acceptance_test.go:1378: 
        	Error Trace:	/home/runner/work/cli/cli/libs/testdiff/testdiff.go:22
        	            				/home/runner/work/cli/cli/acceptance/acceptance_test.go:1378
        	            				/home/runner/work/cli/cli/acceptance/acceptance_test.go:1119
        	            				/home/runner/work/cli/cli/acceptance/acceptance_test.go:664
        	Error:      	Not equal: 
        	            	expected: "\n=== hint printed on an authenticated command: one hint-shown event per printed line is uploaded\n\n>>> [CLI] jobs list\n<claude-code-hint v=\"1\" type=\"plugin\" value=\"databricks@claude-plugins-official\" />\nDatabricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install\n\n>>> print_telemetry\n{\"command\":\"jobs_list\",\"exit_code\":0,\"aitools_hint_event\":{\"hint_kind\":\"CLAUDE_CODE_NATIVE\"}}\n{\"command\":\"jobs_list\",\"exit_code\":0,\"aitools_hint_event\":{\"hint_kind\":\"INSTALL_TEXT\"}}\n\n=== hint printed on a command that resolves no auth: nothing is uploaded\n\n>>> [CLI] version\n<claude-code-hint v=\"1\" type=\"plugin\" value=\"databricks@claude-plugins-official\" />\nDatabricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install\nDatabricks CLI v[CLI_VERSION]\n\n>>> print_telemetry\n\n=== plugin installed: no hint, no event\n\n>>> [CLI] jobs list\n\n>>> print_telemetry\n"
        	            	actual  : "\n=== hint printed on an authenticated command: one hint-shown event per printed line is uploaded\n\n>>> [CLI] jobs list\nDatabricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install\n\n>>> print_telemetry\n\n=== hint printed on a command that resolves no auth: nothing is uploaded\n\n>>> [CLI] version\nDatabricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install\nDatabricks CLI v[CLI_VERSION]\n\n>>> print_telemetry\n\n=== plugin installed: no hint, no event\n\n>>> [CLI] jobs list\n\n>>> print_telemetry\n"
        	            	
        	            	Diff:
        	            	--- Expected
        	            	+++ Actual
        	            	@@ -4,3 +4,2 @@
        	            	 >>> [CLI] jobs list
        	            	-<claude-code-hint v="1" type="plugin" value="databricks@claude-plugins-official" />
        	            	 Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install
        	            	@@ -8,4 +7,2 @@
        	            	 >>> 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"}}
        	            	 
        	            	@@ -14,3 +11,2 @@
        	            	 >>> [CLI] version
        	            	-<claude-code-hint v="1" type="plugin" value="databricks@claude-plugins-official" />
        	            	 Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install
        	Test:       	TestAccept/cmd/aitools/telemetry/hint
        	Messages:   	cmd/aitools/telemetry/hint/output.txt vs /tmp/TestAcceptcmdaitoolstelemetryhint883844450/002/output.txt

@eng-dev-ecosystem-bot

eng-dev-ecosystem-bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

✅ Integration test report

Commit: a057fdd

Run: 43903300361

Env 💚​RECOVERED ✅​pass 🙈​skip Time
💚​ aws linux-2core-8gb 1 270 18 10:17
💚​ aws-windows-latest-4core-16gb 1 272 16 8:30
💚​ azure linux-2core-8gb 1 269 18 10:06
💚​ azure-windows-latest-4core-16gb 1 271 16 7:02
💚​ gcp linux-2core-8gb 1 270 18 13:28
💚​ gcp-windows-latest-4core-16gb 1 272 16 10:35
Test Name aws linux-2core-8gb aws-windows-latest-4core-16gb azure linux-2core-8gb azure-windows-latest-4core-16gb gcp linux-2core-8gb gcp-windows-latest-4core-16gb
💚​ TestAccept 💚​R 💚​R 💚​R 💚​R 💚​R 💚​R
Top 4 slowest tests (at least 2 minutes):
duration env testname
4:44 aws-windows-latest-4core-16gb TestAccept
3:39 azure-windows-latest-4core-16gb TestAccept
3:37 gcp-windows-latest-4core-16gb TestAccept
2:25 aws-windows-latest-4core-16gb TestWorkspaceFilesExtensions_ExportFormatIsPreserved/source_r

@simonfaltum simonfaltum left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

🤖 Automated review from simonfaltum's review agent (pr-review skill) at 07a831d. Each finding was verified against the code; simonfaltum may follow up.

No blocking issues found, approving. 10 non-blocking comment(s) and 3 question(s) below.

This PR prints Claude Code's native <claude-code-hint> line next to the existing text hint, bases Claude Code install detection on what Claude Code itself loads, and stops hinting in auth token, auth docker token and CLI processes started by the CLI. The tag format, stderr placement and CLAUDE_CODE_CHILD_SESSION gate match Claude Code's docs, the tests are thorough, and CI is green. I found nothing blocking. There are two nice-to-have points: a subagent or hook call can use up the session's throttle without ever showing the dialog, and apps init still treats shared-store skills as installed for Claude Code. There are also a few nits and three non-blocking questions about scope, the single-agent abstraction and the extra CI and terminal gates.

Questions

  1. This PR changes four things: the native hint; which installs count for Claude Code (shared-store skills no longer count, and project or local plugins count only inside their project); the auth token / auth docker token and self-exec exclusions; and the agentHint refactor. AGENTS.md asks for one change per PR. The exclusions look like a prerequisite for the native line, because Claude Code can't strip a tag embedded mid-line. Would you move the detection change, and possibly the refactor, into separate PRs, or do they need to land together? (non-blocking)
  2. agentHint, hintForAgent (a switch with one case), the nil check in nativeLine, the empty check in sessionID and TestAgentHint_NativeLineNilIsEmpty exist for agents that don't have a hint yet. AGENTS.md asks for simplicity and no speculative flexibility. Would you keep the direct Claude Code check plus a few lines for the native line, and add the table when a second agent needs it? (non-blocking)
  3. The cli-hints docs only ask for the CLAUDECODE / CLAUDE_CODE_CHILD_SESSION gate, and Claude Code itself never prompts in -p, subagent, hook or unattended runs. The CI and terminal checks add an 11-variable CI list to three acceptance scripts. If some Claude Code surface runs tools with a terminal on any stream, the native line silently never prints, and telemetry would not show it because it only counts printed lines. Was the dialog checked end to end in an attended session (the description notes Windows and macOS were not tested)? Are both checks needed? (non-blocking)

Comments outside the changed lines

  • [nit] libs/aitools/agents/hint_test.go:254: This test still writes some-other-skill into the shared store, which claudeToolingInstalled no longer reads, so it passes whatever the prefix filter does. Use writeClaudeSkill so it checks that a non-Databricks skill in ~/.claude/skills doesn't silence the hint.
  • [nit] .github/PULL_REQUEST_TEMPLATE.md: The description uses ## Summary, ## Evidence and ## Merge Danger. .agents/skills/pr-checklist/SKILL.md asks for the template's ## Changes, ## Why and ## Tests, in that order and with no extra sections, and recent merged PRs follow it. Suggest moving the content under those headings.

Comment on lines +180 to +186
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)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

[nice to have] The session marker is written whenever the text line prints, including when the native line printed somewhere Claude Code never shows the dialog. A subagent's Bash calls carry the parent's CLAUDE_CODE_SESSION_ID and CLAUDE_CODE_CHILD_SESSION=1, and the cli-hints docs say subagent runs and hook output strip the tag without prompting. So when a subagent or a hook makes the session's first databricks call, the main loop's commands print neither line for the next hour, and a session shorter than an hour never sees the dialog. The same happens when the native line is withheld because a terminal is attached. Consider throttling the native line under its own key, and not writing that key when the line was withheld. A shorter TTL for the native line would also limit the subagent and hook case, since Claude Code already shows the dialog at most once per session.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Good catch. Addressed in #7692 (stacked on this one): the native line now has its own per-session marker with a 10-minute TTL, separate from the text hint's hour, and it is written only when the native line actually prints, so a withheld line (terminal attached, CI, no child-session marker) no longer burns it. The CLI can't tell a subagent or hook from the main loop, so the short TTL is what bounds that case; Claude Code shows the dialog at most once per session, so repeating the line is cheap.

Comment thread libs/aitools/agents/hint.go Outdated
Comment on lines +246 to +251
// 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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

[nice to have] This comment now says Claude Code doesn't load skills from the shared ~/.databricks/aitools/skills store. But HasDatabricksToolingInstalled (skills.go:23-33), which apps init uses, still treats shared-store skills as covering every agent, Claude Code included. With skills only in the shared store, databricks apps init under Claude Code prints this hint ("Databricks skills are not installed…") from the root hook, while the command's own check reports the tooling as installed and skips its tip. A human running apps init with Claude Code detected is never offered the install either. Either switch HasDatabricksToolingInstalled to per-agent DatabricksTooling, or say in both comments why they differ. A follow-up PR is fine.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Agreed, the two shouldn't disagree. I'll move HasDatabricksToolingInstalled to per-agent DatabricksTooling in a separate follow-up PR to keep this one scoped.

Comment thread libs/aitools/agents/hint.go Outdated
Comment on lines 261 to 264
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)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

[nit] WithCallingAgentToolingInUserAgent (cmd/root/root.go:88) already computes DatabricksTooling for Claude Code right before MaybeHint. On the plugin path, DatabricksPluginVersion then parses installed_plugins.json a third time just for a debug log, and because the throttle is never written once the plugin is installed, this runs on every command. Also, func() bool { return false } duplicates noRecordedPlugin in recommend.go:45, and the Go style guide asks for a named function. Suggest dropping the version from the debug line and adding a package-level noRecordedPlugin for both callers.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Done in a057fdd: a single package-level noRecordedPlugin in calling.go, shared with recommend.go, and the debug line no longer reads the plugin version, so installed_plugins.json isn't parsed again on every command.

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

[nit] The same unset CI GITHUB_ACTIONS … TFC_RUN_ID line, which mirrors the SDK's CI provider list, appears here, in telemetry/hint/script:7 and in air/image-push/script:69, and again as hintEnvVars in hint_test.go. If the SDK adds a provider, the native line disappears only when tests run on that provider's CI, and four copies need updating. .agents/rules/testing.md says shared bash helpers go in a parent script.prepare, and an unset_ci_env helper there would keep a single copy.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Moved into one unset_ci_env helper in the root acceptance/script.prepare in #7691 (the only parent the three scripts share; it only defines a function, so other tests are unaffected). Its comment points at the SDK's listCiCdProviders so the list stays in sync. Goldens are unchanged, and the three tests pass with CI=true GITHUB_ACTIONS=true exported.

Comment thread libs/aitools/agents/hint_test.go Outdated
Comment on lines +48 to +57
// 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)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

[nit] testutil.SetAgentEnv already clears the environment (NullEnvironment → os.Clearenv) and keeps TMPDIR, TEMP and TMP. So unsetEnv(t, hintEnvVars) right after it, here and at line 467, does nothing, and the sentence saying SetAgentEnv clears TMPDIR/TEMP is wrong. Suggest dropping those two calls and that sentence. hintEnvVars is then needed only in TestClaudeToolingInstalled_LogsPluginVersion, where only CLAUDE_CONFIG_DIR matters.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

You're right, those calls did nothing. Removed in a057fdd together with the wrong sentence; hintEnvVars and unsetEnv had no callers left, so they're gone too. The plugin-log test now just calls testutil.SetAgentEnv(t).

Comment thread libs/aitools/agents/hint.go Outdated
Comment on lines +259 to +261
// 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 })

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

[nit] Plugin records with project or local scope now count only when the CLI's working directory is inside the recorded project. Claude Code loads them from the directory it started in, which the CLI can't see. So a session started in ~/repo with a project-scoped plugin that runs cd /tmp/scratch && databricks jobs list is now told "Databricks skills are not installed". Before this PR, any plugin record kept the hint quiet. The description and the changelog mention the shared-store change but not this one. Please add it there, or keep counting project and local records if a false hint is worse than a missed one.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Keeping the behaviour, since it matches what Claude Code actually loads for that directory, but it's now documented in the claudeToolingInstalled comment, the changelog fragment and the PR description, with the cd /tmp/x && databricks ... example (a057fdd).

Comment thread libs/aitools/agents/hint.go Outdated
// 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 {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

[nit] strconv.ParseBool fails on no and off, so CI=no or CI=off counts as CI here and the native line is dropped. libs/versioncheck reads the same variable with env.GetBool, which treats those values as false. Treat no and off as false too, by checking them before the ParseBool fallback.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in a057fdd, though not via env.GetBool: it returns false for values it can't parse, so CI=woodpecker (providers that set CI to their own name) would stop counting as CI. inCI now treats the same false values GetBool accepts ("", 0, f, false, no, off, case-insensitive) as not CI and anything else as CI; a comment explains why, and tests cover CI=no and CI=OFF.

@@ -0,0 +1 @@
* When Claude Code runs the CLI without the Databricks plugin or skills, the CLI now also prints Claude Code's native `<claude-code-hint>` 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))

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

[nit] .agents/skills/pr-checklist/SKILL.md asks for entries that start with a verb, or with the affected command followed by "now". This one opens with a "When…" clause. At 678 characters it is also the longest fragment in .nextchanges/cli and puts four changes in one line. Suggest leading with the change, e.g. "Print Claude Code's native plugin install hint when…", and keeping the detection and auth token notes short.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Rewritten in a057fdd to lead with "Print Claude Code's native plugin install hint…", cut from 678 to 498 characters, and it now mentions the project/local plugin scope change.

@pietern pietern added the aitools AI tools (databricks aitools) related changes label Nov 16, 2026
- 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 <no-reply@databricks.com>
@anton-107

Copy link
Copy Markdown
Contributor Author

Thanks for the review! Fixes are in a057fdd, plus two stacked follow-ups: #7692 (native-line throttle) and #7691 (shared CI-env helper for the acceptance scripts).

Nits from the review body: TestMaybeHint_NonDatabricksSkillStillHints now writes to ~/.claude/skills via writeClaudeSkill (the unused writeCanonicalSkill is removed), and the description follows the Changes / Why / Tests template.

Q1 (split): the auth token / auth docker token and self-exec exclusions have to land with the native line, since Claude Code can't strip a tag embedded mid-line. The detection change belongs here too: if shared-store skills still counted, a Claude Code user whose skills live only in ~/.databricks/aitools/skills would never be offered the plugin, even though Claude Code doesn't load skills from there, which is exactly the case the native hint is for.

Q2 (single-agent table): fair point; with one agent it's more structure than strictly needed. I kept it to avoid more churn on this PR, and I'm happy to collapse it to a direct Claude Code check in a follow-up if you'd prefer.

Q3 (CI and terminal checks): we measured Claude Code's Bash tool: stdin is /dev/null and stdout/stderr go to a file, with no terminal on any stream even when Claude Code itself runs under tmux, so the terminal check doesn't drop the line for normal tool calls. It exists for shells and tmux sessions started from inside Claude Code, which inherit CLAUDE_CODE_CHILD_SESSION but where a person reads the raw tag. The CI check covers unattended runs that still carry the marker. The dialog itself isn't covered by an automated test, and as you note, Windows and macOS weren't tried by hand.

@anton-107
anton-107 enabled auto-merge November 16, 2026 16:24
@anton-107
anton-107 added this pull request to the merge queue Nov 16, 2026
Merged via the queue into main with commit 10fe968 Nov 16, 2026
27 checks passed
@anton-107
anton-107 deleted the aitools/claude-code-native-hint branch November 16, 2026 16:40
anshul0713 added a commit that referenced this pull request Nov 16, 2026
…d install

#7585 made the hint ask DatabricksTooling, which already walks Claude's
project skills dirs, so the false "skills are not installed" warning an
agent hit right after `aitools install --scope project` is fixed. The hint
tests cover project-scoped plugins and HOME skills but not this layout, so
add regression tests for a project install (relative symlink from
.claude/skills into .databricks/aitools/skills) seen from the project root
and from a subdirectory of the repository.

Co-authored-by: Isaac <no-reply@databricks.com>
anshul0713 added a commit that referenced this pull request Nov 17, 2026
…d install

#7585 made the hint ask DatabricksTooling, which already walks Claude's
project skills dirs, so the false "skills are not installed" warning an
agent hit right after `aitools install --scope project` is fixed. The hint
tests cover project-scoped plugins and HOME skills but not this layout, so
add regression tests for a project install (relative symlink from
.claude/skills into .databricks/aitools/skills) seen from the project root
and from a subdirectory of the repository.

Co-authored-by: Isaac <no-reply@databricks.com>
deco-sdk-tagging Bot added a commit that referenced this pull request Nov 19, 2026
## Release v1.27.0

### Notable Changes

 * `databricks aitools install`, `update` and `uninstall` now exit with code 1 when they do nothing they were asked to. `install` fails when it sets up nothing: no coding agent is detected, every agent is skipped or fails to install, or no skill in the release can be installed (also with `--path`). `update` fails when every update or check it attempts fails, and `uninstall` when every removal it attempts fails. Scripts that ran these commands as a best-effort step and relied on exit code 0 should handle the new exit code. ([#7481](#7481))
 * Add `file:<path>` selectors to `pipelines run` and pipeline `bundle run`. `--refresh` and `--full-refresh` now use space-separated lists, such as `--refresh "orders payments"`, instead of comma-separated lists. Single names containing spaces now require backticks, e.g. ``--refresh 'table:`order details`'``. ([#7184](#7184))
 * The Databricks CLI is now available on PyPI as `databricks`: run it with `uvx databricks`, or install it with `uv tool install databricks`, `pipx install databricks` or `pip install databricks`. The package contains only the prebuilt CLI binary. Uninstall the legacy `databricks-cli` package first, since both install a `databricks` command. ([#7704](#7704), [#7777](#7777))

### CLI

 * Add `databricks sandbox fs` commands (`cp`, `ls`, `cat`, `mkdir`, `rm`) to transfer files between your local filesystem and sandboxes using `<sandbox-id>:/path`. ([#7372](#7372))
 * `databricks fs` commands retry reads (stat, list, open) and deletes on DBFS and Volumes when the server returns a transient error or does not respond within the HTTP timeout. ([#7556](#7556))
 * Retry UC Volumes file operations (`fs cp`, `fs ls`, `fs rm`, bundle uploads to Volumes) when the Files API returns HTTP 408, 429, 502, 503 or 504 (for example "AWS S3 is throttling requests"), or on a transient network error; this regressed in v1.10.0. ([#7559](#7559))
 * Stop warning when the host metadata request (`/.well-known/databricks-config`) times out; the CLI already falls back to your config, and the message is still shown with `--debug`. ([#7752](#7752))
 * Add `databricks aitools auto-install disable` and `enable` to turn off (or back on) the automatic installation of Databricks AI tools on CLI upgrades. A global-scope `databricks aitools uninstall` also turns it off. ([#7701](#7701))
 * Stop printing the Databricks AI tooling install hint on `auth`, `configure`, `current-user me`, `version`, `help`, and shell-completion commands. ([#7452](#7452))
 * When Codex, Cursor, GitHub Copilot CLI, OpenCode, Gemini CLI, Antigravity, Pi, Goose or Kiro run the CLI without Databricks skills installed for that agent, the CLI now prints a one-line hint to install them with `databricks aitools install --agents <agent> --scope global`, previously shown only to Claude Code. ([#7586](#7586))
 * `databricks aitools install` now rejects an unknown `--agents` name before it shows the scope prompt, instead of after. ([#7469](#7469))
 * `databricks aitools install` no longer asks "Proceed?" after the agent picker; the picker selection confirms the plan. The picker title now shows the install scope, its hint says Enter installs, `--skills-only` runs label plugin agents "skills" and pre-check every agent whose config dir exists, and the plan summary after it is reduced to the scope line. ([#7478](#7478))
 * `databricks aitools install --output json` reports more specific `error_category` values: `SKILLS_FETCH_FAILED`, `RELEASE_LOOKUP_FAILED`, `RATE_LIMITED`, `MANIFEST_INVALID`, `STATE_INVALID` and `PLUGIN_CLI_TIMEOUT`. A coding agent CLI that does not answer in time is now reported as `timed out after <duration>`, followed by any stderr it wrote before it was stopped. ([#7475](#7475))
 * `databricks aitools install` no longer prompts when a coding agent runs it, even in a pseudo-terminal; it uses the non-interactive defaults instead and prints a note saying so. ([#7477](#7477))
 * `databricks aitools install` now prints the directory it installed skills into (for example `Installed 1 skill in ~/.databricks/aitools/skills.`), so agents can open the installed `SKILL.md` files without searching for them. ([#7668](#7668))
 * `databricks aitools install` now ends a failed install with a step to recover, in the text output and in a new `recovery` field of `--output json`. ([#7480](#7480))
 * `databricks aitools install` now installs plugins for the other coding agents even when installing skill files fails. ([#7479](#7479))
 * `databricks aitools install` now installs skill files for a detected coding agent whose CLI is not on PATH (for example a Claude Code desktop or IDE install), unless it already has the plugin, says how to switch to the plugin later, and warns when the current project also has the plugin. `databricks aitools update` no longer tries to install the plugin for such an agent, and no longer writes skill files next to a plugin that such an agent already has. ([#7482](#7482))
 * Fix `databricks aitools install` waiting a long time on an unreachable or slow workspace while it resolves authentication for telemetry; that wait is now limited to a few seconds. ([#7468](#7468))
 * `databricks aitools install`, `update` and `list` now refuse a skills manifest that names a skill or file outside the skills directory, before writing any skill files. A skill whose name or file paths are not portable is skipped with a warning, and `update` keeps its installed copy. ([#7722](#7722))
 * `databricks aitools install` and `databricks aitools update` refresh only the marketplace the Databricks plugin is listed in, so another unreachable marketplace no longer blocks them. When that refresh fails, both commands warn, install or update the plugin from the local copy of the marketplace, and record the plugin version as unknown. ([#7473](#7473))
 * `databricks aitools install` and `databricks aitools update` now wait up to 20 seconds instead of 5 for a coding agent's CLI to answer the plugin capability check, so a slow first start is less likely to report the agent as unavailable. ([#7472](#7472))
 * `databricks aitools install` no longer fails a plugin-only install when the lookup of the latest skills release on GitHub fails or is rate-limited. The plugin is installed and its version is recorded as unknown. ([#7474](#7474))
 * `databricks aitools` commands now send usage telemetry, and the CLI records when it recommends installing Databricks AI tools. When the configured workspace is slow or unreachable, `aitools install`, `update` and `uninstall` can take up to about 6 seconds longer, and `list`, `version` and runs that stop early up to about 3 seconds. Set `DATABRICKS_CLI_DISABLE_TELEMETRY=1` to opt out. ([#7467](#7467), [#7469](#7469), [#7470](#7470))
 * `databricks aitools install` and `databricks aitools update` now report a coding agent CLI shim (`.cmd` or `.bat`) on Windows that prints its plugin help and then exits with an error as `shim-exited-with-error`, with the command to run to see the error, instead of reporting the CLI as not on PATH. ([#7476](#7476))
 * `apps init` no longer suggests installing skills when every detected coding agent already has the Databricks plugin. ([#7467](#7467))
 * `databricks auth login` now gives up on the optional workspace lookup after about 5 seconds instead of retrying for about 5 minutes, and explains the fallback to the manual workspace ID prompt. ([#7522](#7522))
 * Throttle Claude Code's native plugin install hint separately from the text hint: it prints at most once per 10 minutes per session, so the install dialog still comes up when a subagent, a hook, or a command outside a Claude Code subprocess runs the session's first `databricks` command. ([#7692](#7692))
 * 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](#7585))
 * Interactive prompts and pagers now work in Git for Windows' bash and other MSYS2 shells when they run under ConPTY (the default since Git for Windows 2.47) or directly in a Windows console. ([#7699](#7699))
 * Add the `databricks feedback` command to send feedback about the CLI to Databricks. ([#7724](#7724))
 * Fix shell completion in `databricks fs` commands for local paths typed with a leading `./` or repeated separators, which previously offered no suggestions. ([#7679](#7679))
 * Fix a panic in `databricks labs` commands when a non-string SDK setting such as `DATABRICKS_DEBUG_HEADERS` or `DATABRICKS_RATE_LIMIT` is set in the environment. ([#7673](#7673))
 * Fix a panic in `databricks labs install` for projects whose `labs.yml` has no `install` section. ([#7673](#7673))
 * `NO_COLOR` no longer disables prompts, spinners or the list pager; they run without color. ([#7700](#7700))
 * Add the Beta `databricks pipelines test` command, which runs the tests of a pipeline, and the `testing` property of pipelines in bundles. ([#7429](#7429))
 * Add `databricks sandbox forward`, which serves an app running in a sandbox at a local URL. ([#7395](#7395))
 * Bound the whole telemetry upload at exit, including config resolution and authentication, by its timeout, so a stalled auth or telemetry endpoint no longer keeps a command from exiting. ([#7467](#7467))
 * `databricks version --check` now suggests `databricks aitools install` on stderr when a coding agent is detected without the Databricks plugin or skills. ([#7471](#7471))

### AI Runtime

 * `air get -o json` now reports `PENDING` while the run waits for compute, matching `air list`, and includes the run's `status_message`. ([#7455](#7455))
 * Wrap long failure reasons and log lines in the `air list` info and logs panes, keep the MLflow link (labeled with its retry) when a run's last retry failed before starting, and point `air logs` at earlier retries when the last one has no logs. ([#7456](#7456))
 * `databricks air logs --node` now reports an out-of-range node index when it can determine the run's node count, instead of looking like a successful run with no logs. ([#7516](#7516))
 * Add experiment, duration, accelerator, and dashboard metadata to `air list --output json`. For retried runs, `started_at` now reports the latest attempt, matching `air get`. ([#7568](#7568))
 * `air list` shortens MLflow run names and unnamed-run IDs by keeping their end behind a leading `…`, and its columns no longer overflow on wide (for example CJK) text; `air get` shows an unnamed run's full MLflow run ID. ([#7582](#7582))
 * Shrink the Experiment and User columns of the interactive `air list` table to fit the terminal width, keeping the end of a shortened experiment name. ([#7583](#7583))
 * Show the experiment, accelerators and configuration in the `air list` info pane for runs where it showed `N/A`. ([#7587](#7587))
 * Strip terminal control characters from the MLflow run, experiment and user names shown by `air list` and `air get`, so a run name cannot clear or retitle the terminal of whoever lists it. ([#7601](#7601))
 * `air logs`, `air get`, and `air run --watch` no longer make an extra credential-check request before fetching the run, and `air get` reuses the configured workspace ID instead of looking it up. ([#7613](#7613))
 * `air list` no longer waits on extra current-user requests before listing runs, which makes the default list about 150ms faster. ([#7615](#7615))
 * `air list --all-status` requests larger index pages, so it makes far fewer round trips once the server supports `page_size`. ([#7616](#7616))
 * Fit the interactive `air list` table to narrow terminals: when the Experiment and User columns are at their floors, shorten Started to `MM-DD HH:MM` and size the MLflow column to its labels, then hide Accelerators, User, MLflow and Progress in that order, naming the hidden columns in the hint line. ([#7629](#7629))
 * `air get -o json` now includes `mlflow_run_id` and `mlflow_experiment_id`, so a run can be handed to MLflow-based steps without parsing `mlflow_url`. They identify the MLflow run `mlflow_url` links to, including one from an earlier retry that `mlflow_retry` names. ([#7636](#7636))
 * `air get` and the `air list` info pane now show the environment of runs on the Databricks AI environment (`databricks_ai_v*`) instead of `N/A`. ([#7637](#7637))
 * `air run` now rejects a `code_source.include_paths` path that selects no files instead of uploading a snapshot without it; glob patterns and pathspec magic are left to git. ([#7643](#7643))
 * `air convert-to-dabs` now suggests the `--output-dir` that converts a working-tree workload whose `code_source.root_path` is outside the bundle directory, instead of suggesting `sync.paths`. ([#7644](#7644))
 * `air run` now lists a `code_source.root_path` outside a git repository relative to `root_path`, so running from a subdirectory of `root_path` no longer uploads an empty or partial snapshot. ([#7646](#7646))
 * `air list --all-status` now fills `--limit` past purged or inaccessible indexed runs. ([#7743](#7743))
 * `air run` now warns about missing PyTorch when a pinned snapshot's `include_paths` selects a Python file. ([#7744](#7744))
 * `air cancel JOB_RUN_ID` now rejects run IDs that are not AI Runtime runs instead of cancelling unrelated Jobs runs. In `-o json` output, the `failed[].error` text for a run that does not exist or that you cannot view now starts with `failed to get run <id>:` instead of the cancel API error. ([#7569](#7569))
 * `air get -o json` now reports `mlflow_retry` when the MLflow link comes from an earlier retry because the run's last retry never reached MLflow. ([#7620](#7620))
 * `databricks air run --help` now shows how to install the databricks-ai-runtime coding agent skill. ([#7652](#7652))
 * `air run --watch -o json` now reports each lifecycle `STATUS` transition once and never reports a non-terminal state after the run has ended, including when logs are served from MLflow artifacts. ([#7621](#7621))
 * `air convert-to-dabs` now explains the `--output-dir` workaround when `code_source.root_path` resolves to the bundle root, and notes when the generated job carries the default `max_retries`. ([#7579](#7579))
 * `air run` now refuses to upload a `code_source` snapshot that selects no files (for example when `root_path` is git-ignored) and explains the cause, and `--dry-run` runs the snapshot file selection and reports the file count. ([#7570](#7570))
 * Repeat the Jobs run link after live log streaming ends. ([#7571](#7571))
 * `air get -o json` includes run details including flat `accelerator_type` and `num_accelerators`. Use `--include-config` to include stored config, which may contain plaintext `env_variables` and parameters; downloads over 1 MiB are omitted, and config-dependent `max_retries` is otherwise null. ([#7624](#7624))
 * `air get` and the `air list` info pane no longer show `Max Retries 0` when the Jobs API leaves the task's retry limit out. For a run submitted with `air run`, the limit now comes from the run's uploaded config, shown as `3 (CLI default)` when the config doesn't set `max_retries`; it shows `N/A` when the limit can't be known (job runs, multi-container runs, legacy runs with no explicit value, or an unreadable config). ([#7623](#7623))
 * Reorganize `databricks air` help: subcommands are grouped by task, `air run` has examples, and YAML fields are listed under headings, with pool fields marked optional and `command`, `compute.num_accelerators`, and `compute.accelerator_type` correctly marked required. ([#7512](#7512))
 * `air run -h config` now lists the environment variables AI Runtime sets on every node (such as `MLFLOW_RUN_ID` and `CODE_SOURCE_PATH`), and `air logs --help` notes that `--download-to` cannot be combined with `--tail` or `--minutes`. ([#7655](#7655))
 * Support full workspace accelerator types in `air list` filters while preserving family matching, and reject invalid filter values. ([#7515](#7515))
 * `databricks air list --all-status` now warns when the AI Runtime run index is unavailable and it falls back to scanning Jobs runs. That fallback scan is capped at 250 runs, and a stuck index request fails after 15 seconds instead of retrying for minutes. `--all-status --filter user=<your email>` now uses the run index instead of scanning the workspace's full run history. ([#7619](#7619))
 * Return structured JSON errors for invalid `air list --filter` values when `-o json` is used. ([#7612](#7612))
 * `air list --all-status` no longer fails when a listed run has been purged. ([#7523](#7523))
 * **Behavior change:** `databricks air logs` now prints the logs available now and exits, also for an active run, matching `kubectl logs`, `docker logs` and `databricks apps logs`. Pass `--follow` (`-f`) to stream new lines until the run completes; `--tail N --follow` prints the last N lines first. `databricks air run --watch` still submits and streams. ([#7658](#7658))
 * `databricks air logs -o json` and `databricks air run --watch -o json` now emit a `WAITING` event, for example `{"type":"WAITING","message":"Waiting for accelerator compute capacity..."}`, when the reported waiting status changes. ([#7695](#7695))
 * `databricks air logs` on a run that ended in the last two minutes now waits for the log index to settle before printing, instead of sometimes dropping lines that were indexed late. ([#7663](#7663))
 * `air logs` and `air run --watch` now print the waiting status (for example `Waiting for accelerator compute capacity...`) as a line on stderr when stderr is not a terminal, instead of printing nothing until the run produces logs. ([#7657](#7657))
 * Route AIR log links to the MLflow Logs page instead of the hidden artifact path. ([#7491](#7491))
 * Invalid `compute.accelerator_type` errors and `air run -h config.compute` no longer list the CLI's built-in accelerator types, which could differ from the workspace's. ([#7520](#7520))
 * `databricks air --help` now notes that GPU pools are not required to run workloads. ([#7581](#7581))
 * `air run` now prints the job run URL with the `?o=<workspace-id>` suffix, matching `air get` and `air list`; `dashboard_url` in `air run -o json` and the `--watch` events gains it too. When `air list` cannot resolve the workspace ID, its links now omit `?o=` instead of ending in `?o=0`. ([#7573](#7573))
 * `databricks air run` now reports an unknown workload YAML key by its field path, suggests the closest valid field, and points to `-h config` instead of naming an internal Go type. ([#7574](#7574))
 * `air run` (including `--dry-run`) now warns before submitting when the `code_source` imports `torch` but PyTorch is not declared: the environment is the Standard environment (version 5 or later) with no `torch` dependency, so the run may fail after it waits for a GPU. ([#7656](#7656))

### Bundles

 * Add `isolation_mode` to the `catalogs` resource, so a catalog can be deployed as `OPEN` or `ISOLATED`. ([#7463](#7463))
 * `bundle validate` no longer warns when resource permissions and top-level or target permissions name the same principal. ([#7291](#7291))
 * Retry bundle file uploads, reads and deletes when the server does not respond within the HTTP timeout ("request timed out after ... of inactivity"). ([#7521](#7521))
 * Show how to recover when `bundle deploy` fails because an app's service principal does not exist or was deleted. ([#7533](#7533))
 * Retry transient server errors when creating Lakebase (`postgres_*`) resources in the direct deployment engine. ([#7557](#7557))
 * Fix `bundle plan` reporting the `spark_conf` and `custom_tags` the backend derives from `is_single_node: true` as drift on clusters. ([#7577](#7577))
 * Stop planning a spurious update for Lakeflow Connect pipelines whose `ingestion_definition.data_staging_options` is filled in by the backend. ([#7603](#7603))
 * Retry the root path check in `bundle destroy` on transient errors, so a dropped connection no longer fails the destroy. ([#7597](#7597))
 * Use the Lakebase branch when its create request times out but the branch was created, instead of failing the deploy, in the direct deployment engine. ([#7602](#7602))
 * Retry transient server errors when deleting resources in the direct deployment engine. ([#7708](#7708))
 * Use the Lakebase project when its create request times out but the project was created, instead of failing the deploy with "already exists", in the direct deployment engine. ([#7747](#7747))
 * Use the feature, model serving endpoint or dashboard that a create request created despite timing out, instead of failing the deploy, in the direct deployment engine. ([#7757](#7757))
 * Use the Lakebase role when its create request fails with a transient error but the role was created, instead of failing the deploy, in the direct deployment engine. ([#7767](#7767))
 * Use the MCP service, model service or model provider service that a create request created despite failing with a timeout, a 499 or a reset stream, instead of failing the deploy, in the direct deployment engine. Create recovery for features, serving endpoints and dashboards now also covers 499 and reset streams. ([#7782](#7782))
 * Retry app updates and deletes in the direct deployment engine when they fail with 400 BAD_REQUEST because the app compute is `UPDATING`, after waiting for the compute to settle. ([#7606](#7606))
 * Enable drift detection for `source_code_path` and `git_source` on apps. ([#6399](#6399))
 * `bundle destroy` and `bundle deploy` no longer fail with "internal error, missing in state" when the state holds an empty-ID entry left by an interrupted recreate in an older CLI. ([#7676](#7676))
 * Fix a feature whose `full_name` contains uppercase letters being recreated on every deploy. ([#7398](#7398))
 * Fix `bundle deployment bind` (and `bundle generate --bind`) failing with `no such node "resources.internal_immutable_snapshots.immutable"` when `workspace.sync_mode` is `immutable`, as reported in [#7306](#7306). ([#7329](#7329))
 * Retry creating the deployment lock (without `--force-lock`) when the request fails with a transient server error, times out ("request timed out after ... of inactivity") or loses its connection ("unexpected EOF"). ([#7594](#7594))
 * Fix a materialization set member whose `feature_name` contains uppercase letters failing to deploy, or recreating the set on every deploy. ([#7398](#7398))
 * Delete the old resource when its name follows a renamed schema. ([#7718](#7718))
 * Fix `pipelines dry-run` starting a real run when given a job KEY, and a crash in its shell completion. ([#7672](#7672))
 * Rename schemas in place; schemas and volumes follow a renamed catalog or schema. ([#7343](#7343))
 * Fix a panic when validating or deploying jobs with local libraries and serverless job clusters. ([#7725](#7725))
 * Fix `tgz` artifacts with `git` set producing an empty tarball or failing when the bundle is in a subdirectory of the git repository. ([#7674](#7674))
 * Apply `presets.trigger_pause_status` and the development mode pause default to `triggers[]` entries on jobs. ([#7450](#7450))

### Dependency Updates

 * Bump dependencies with known vulnerabilities. ([#7750](#7750))
 * Update the Go SDK to [v0.198.0](https://github.com/databricks/databricks-sdk-go/releases/tag/v0.198.0). ([#7530](#7530))
 * Update the Go SDK to [v0.199.0](https://github.com/databricks/databricks-sdk-go/releases/tag/v0.199.0). ([#7584](#7584))
 * Update the Go SDK to [v0.200.0](https://github.com/databricks/databricks-sdk-go/releases/tag/v0.200.0). ([#7653](#7653))
 * Update the Go SDK to [v0.201.0](https://github.com/databricks/databricks-sdk-go/releases/tag/v0.201.0). ([#7769](#7769))
idelafuente-oc pushed a commit to idelafuente-oc/cli that referenced this pull request Nov 20, 2026
databricks#7692)

## Changes
The native `<claude-code-hint>` line now has its own throttle (a
separate cache bucket, 10-minute TTL), keyed by the hint's throttle key
from databricks#7586 and written only when the line actually prints. The text hint
keeps its one-hour marker, and other agents' durable claim
(`claimHintMarker`) now goes through the same text throttle. The native
throttle applies only to Claude Code, the one agent with a native line.
All throttles are still checked before the plugin/skills filesystem
probe.

The `CLAUDE_CODE_NATIVE` hint-shown event stays on the text hint's
hourly clock. It is logged only for the first native line printed since
the text line last printed, so a native-only repeat logs no event.

## Why
This addresses simonfaltum's review comment on `hint.go` in databricks#7585. The
single shared marker was written whenever the text hint printed. That
included commands where the native line was withheld (no
`CLAUDE_CODE_CHILD_SESSION`, CI, a terminal attached), and commands
where Claude Code strips the tag without prompting (subagents, hooks).
After that, the main loop got neither line for an hour.

The CLI can't tell a subagent from the main loop, because both carry the
same session id and child-session marker. So a separate key alone
doesn't fix the subagent case; the shorter TTL is what bounds it. Claude
Code shows the dialog at most once per session, so repeating the line is
cheap: a raw tag reaches a `2>&1 | jq` reader at most once per 10
minutes. Telemetry costs nothing extra, because a native-only repeat
logs no event and so triggers no exit-time upload
(`hintOnlyUploadTimeout`). Native-event counts stay at most one per text
window instead of growing with session length. In return, a session
waits at most 10 minutes for the dialog.

## Tests
- New unit tests:
- A withheld native line (no child session, CI) leaves the next
command's native line due. Only that line prints, and it logs its event.
- The native line reappears after its TTL while the text hint stays
throttled, and that repeat logs no event. A new text window logs both
events again.
- A text-only print starts a new event window, so the next native print
logs its event.
- New `acceptance/cmd/aitools/claude-config-dir` case for the
withheld-then-native sequence. The existing throttle case's title now
describes both clocks.
- `libs/telemetry/protos/README.md` describes both clocks and the hourly
native event.
- `go test ./libs/aitools/... ./cmd/root/...`, `go test ./acceptance
-run 'TestAccept/cmd/aitools'`, `./task test-exp-aitools`, `./task
checks` and `./task lint-q` all pass.

This pull request and its description were written by Isaac.

---------

Co-authored-by: Isaac <no-reply@databricks.com>
idelafuente-oc pushed a commit to idelafuente-oc/cli that referenced this pull request Nov 20, 2026
## Changes
Adds an `unset_ci_env` helper to `acceptance/script.prepare`. It
replaces the three copies of the CI and CI/CD provider `unset` line in
`cmd/aitools/claude-config-dir`, `cmd/aitools/telemetry/hint` and
`air/image-push`. The helper's comment points at `listCiCdProviders` in
the Go SDK's `useragent/cicd.go` so the list stays in sync. The helper
is also listed in the built-in helpers section of
`.agents/rules/testing.md`.

## Why
Addresses simonfaltum's review comment on databricks#7585 about the duplicated
line. The helper lives in the root `script.prepare` because that is the
only prepare file that covers both `cmd/aitools` and `air`. After this
change, `unset_ci_env` is the only copy of the list.

## Tests
- Rebased on current main, which includes databricks#7692. `go test ./acceptance
-run TestAccept/cmd/aitools` (14 dirs) and `-run TestAccept/air` (24
dirs) both pass with no golden changes. They pass in a clean env and
with `CI=true GITHUB_ACTIONS=true` exported.
- Negative control: I turned the helper into a no-op and exported the CI
vars. `cmd/aitools/telemetry/hint`, `cmd/aitools/claude-config-dir` and
`air/image-push` all fail.

This pull request and its description were written by Isaac.

---------

Co-authored-by: Isaac <no-reply@databricks.com>
idelafuente-oc pushed a commit to idelafuente-oc/cli that referenced this pull request Nov 20, 2026
…d install (databricks#7667)

## Changes
Test-only: adds `TestMaybeHint_ProjectSkillsInstalledSilent` and
`TestMaybeHint_ProjectSkillsInParentOfRepoSubdirSilent`. They lay out an
install the way `databricks aitools install --scope project` does (a
relative symlink from `.claude/skills/<skill>` to the project's
`.databricks/aitools/skills/<skill>`). Then they check that the
"Databricks skills are not installed" hint stays quiet, both from the
project root and from a subdirectory of the repository.

## Why
A coding agent in an AI Runtime trial ran `databricks aitools install
--scope project`. The very next command, `databricks air list`, said
skills were not installed and suggested reinstalling. This PR originally
fixed that in `claudeToolingInstalled`. databricks#7585 has since made the hint
ask `DatabricksTooling`, which already walks Claude's project skills
folders, so the fix is no longer needed.

The hint tests cover project-scoped plugins and skills under HOME, but
not a project-scoped skills install, so I kept the regression tests.
Both fail on the commit before databricks#7585.

## Tests
`go test ./libs/aitools/...` passes.

This pull request and its description were written by Isaac.

---------

Co-authored-by: Isaac <no-reply@databricks.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

AIR Databricks AI Runtime CLI aitools AI tools (databricks aitools) related changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants