Repository navigation
aitools: install hints for non-Claude coding agents - #7586
Conversation
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>
Until now the install hint was printed only to Claude Code. The nine other registry agents (Codex, Cursor, GitHub Copilot CLI, OpenCode, Gemini CLI, Antigravity, Pi, Goose, Kiro) now also get a one-line hint, but only when that agent's own Databricks tooling is missing: Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents <agent> --scope global - The throttle lasts one hour (hintSessionTTL). Keys are "<agent>:session:<id>" (Codex: CODEX_THREAD_ID) or "<agent>:machine" for agents without a session id, so a Claude marker never silences Codex when both report the same id. - If the user cache can't be written (read-only sandbox, or DATABRICKS_CACHE_ENABLED=false), non-Claude agents get no hint at all. - Agents the CLI can't install for (Windsurf, VS Code agent, Amp, ...) and nested agents get no hint. - installer.globalPluginRecorded is now exported as GlobalPluginRecorded, so cmd/root can pass it to MaybeHint. - The telemetry README and the AitoolsHintEvent doc now describe the event for every agent; the new line logs AGENT_INSTALL_TEXT. Co-authored-by: Isaac <no-reply@databricks.com>
f49b71b to
735415e
Compare
|
Commit: Regression test reportSelected 2 changed tests (limit=20, 0 not selected) 2 tests: regression=2 unreleased=0 coverage=0 failing=0
TestAccept/cmd/aitools/agent-hints: branch ✅ | main (2665e39) ❌ | latest (v1.26.0) ❌main (2665e39): latest (v1.26.0): same output as main (2665e39) TestAccept/cmd/version: branch ✅ | main (2665e39) ❌ | latest (v1.26.0) ❌main (2665e39): latest (v1.26.0): |
✅ Integration test reportCommit: 11c9532
Top 4 slowest tests (at least 2 minutes):
|
simonfaltum
left a comment
There was a problem hiding this comment.
🤖 Automated review from simonfaltum's review agent (pr-review skill) at 735415e. Each finding was verified against the code; simonfaltum may follow up.
No blocking issues found, approving. 9 non-blocking comment(s) and 2 question(s) below.
This PR extends the stderr install hint from Claude Code to the nine other registry agents. Each agent is hinted only when its own Databricks tooling is missing. The hint is throttled per Codex thread or per agent per machine, and prints only when the throttle marker persisted. The implementation and tests look solid, CI is green, and nothing is blocking. Two things are worth fixing: the version --check tip still assumes only Claude Code gets the root hint, and the tooling probe now runs twice per command. The hint can also be wrong or unhelpful in two cases: Codex/Copilot without their CLI on PATH, and Cursor's own plugin.
Questions
- Claude Code's throttle marker stays best-effort, while the other agents print only after their marker is persisted (
durableThrottle). So with an unwritable cache (a sandbox, a read-only home), Claude Code still prints its hint lines on every command. That is the casedurableThrottleprevents for the others. Is the difference intended, for example so Claude Code users in a sandbox still see the hint? Or should all agents use the durable claim? If it's intended, could thedurableThrottlecomment say why? (non-blocking) - The hint relies only on each agent's SDK env marker. For Claude Code, the code notes that
CLAUDECODEalso leaks into IDE terminals people type in, and the native line has an extra agent-only gate. For the IDE-first agents (KIRO,ANTIGRAVITY_AGENT), has anyone checked that the marker is set only for commands the agent runs, and not in the integrated terminal or the extension host? If it isn't, a person (or the Databricks IDE extension) running the CLI there would get the hint on stderr once an hour. (non-blocking)
| nativeKind: protos.AitoolsHintKindClaudeCodeNative, | ||
| } | ||
| default: | ||
| if a := AgentForProvider(provider); a != nil { |
There was a problem hiding this comment.
[nice to have] MaybeVersionCheckTip (libs/aitools/agents/recommend.go:33) still skips only Claude Code, on the grounds that "MaybeHint already covers them". This PR makes MaybeHint cover nine more agents but leaves that skip unchanged. So with CODEX_CI=1 (or CURSOR_AGENT=1, …), no Databricks tooling and ~/.codex present, databricks version --check prints the new … install --agents codex --scope global line from the root hook. It then prints Tip: … Run 'databricks aitools install'. That is two different commands in one run, and the tip isn't throttled. Skip the tip whenever the calling agent gets a root hint (hintForAgent(...) != nil, or CallingAgent() != nil), update that comment, and add a non-Claude case next to the Claude one in acceptance/cmd/version/script.
| // Recommend installing Databricks AI tooling to the calling coding agent | ||
| // when it drives the CLI without the tooling installed (best-effort: a | ||
| // stderr line and a telemetry event that is uploaded at exit). | ||
| agents.MaybeHint(ctx, cmd, installer.GlobalPluginRecorded) |
There was a problem hiding this comment.
[nice to have] installer.WithCallingAgentToolingInUserAgent (root.go:88) already runs a.DatabricksTooling(ctx, GlobalPluginRecorded) for the same calling agent, and MaybeHint then runs it again (hint_agents.go:35-38). Users who have the tooling never get a throttle marker. So under these nine agents, every one of their commands reads the skills dir, walks the project dirs up to the repo root and reads the install state twice. The "check the throttle before the filesystem probe" ordering in MaybeHint doesn't save anything either, because the first probe has already run. Compute the Tooling once in PersistentPreRunE and pass it to both (e.g. MaybeHint(ctx, cmd, tooling)). That also makes PluginRecordedFunc and the GlobalPluginRecorded export unnecessary.
There was a problem hiding this comment.
Agreed, the probe runs twice and the throttle-first ordering saves nothing once WithCallingAgentToolingInUserAgent has run. Computing Tooling once in PersistentPreRunE changes signatures across cmd/root, installer and agents (and drops PluginRecordedFunc/the GlobalPluginRecorded export), so I'll do it in a follow-up PR rather than widen this one. The probe is local-filesystem only.
| // installed with the agent's own CLI rather than `databricks aitools install` | ||
| // leaves no trace there for those two, so their users are hinted; the | ||
| // throttle bounds that to once per session or per TTL. | ||
| func agentInstallHint(a *Agent, pluginRecorded PluginRecordedFunc) *agentHint { |
There was a problem hiding this comment.
[nice to have] For Codex and Copilot, --agents <name> without --skills-only takes the plugin path. When codex/copilot isn't on PATH (for example an IDE extension or desktop app that bundles its own binary), that path returns cli-not-on-path and exits non-zero, with no fallback to skills. Nothing gets recorded, so each new Codex thread is told again to "first run" the same failing command. The description lists this as a known risk. A cheap mitigation: when the hint is about to print, check exec.LookPath(a.Binary), and if it fails, hint --skills-only instead. That writes to the agent's own skills dir, so the hint stops afterwards.
There was a problem hiding this comment.
Good idea. Leaving it for a follow-up: it makes the hint text depend on PATH, and hintText is wording we only change after testing how agents react to it. Until then this stays listed under Merge Danger.
| // The hint is gated on the agent's own tooling (Agent.DatabricksTooling, with | ||
| // pluginRecorded as the plugin source for Codex and Copilot). A plugin | ||
| // installed with the agent's own CLI rather than `databricks aitools install` | ||
| // leaves no trace there for those two, so their users are hinted; the | ||
| // throttle bounds that to once per session or per TTL. |
There was a problem hiding this comment.
[nice to have] The registry notes that Cursor has a Databricks plugin, which users install from Cursor itself because the CLI can't install it headlessly. Cursor has neither Plugin nor a manifest reader, so DatabricksTooling only looks at ~/.cursor/skills. A Cursor user who has that plugin (and no raw skills) is told "Databricks skills are not installed" every hour, and following the hint adds raw skills next to the plugin. OpenCode has a similar gap for skills it loads from Claude-compatible dirs such as ~/.claude/skills. Either detect where the Cursor plugin is installed, or at least name Cursor here and in the Merge Danger section, next to Codex and Copilot.
| recorded := func() bool { return pluginRecorded(ctx, a.Name) } | ||
| return a.DatabricksTooling(ctx, recorded) != ToolingNone | ||
| }, | ||
| text: "Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents " + a.Name + " --scope global", |
There was a problem hiding this comment.
[nit] This literal repeats hintText, whose comment says the wording should change only after thorough testing. The next wording change to hintText would leave the other nine agents on the old text. .agents/rules/style-guide-go.md asks to build on an existing constant in cases like this: hintText + " --agents " + a.Name + " --scope global".
| // sessionKeyPrefix namespaces the session id in the throttle key, so one | ||
| // agent's marker never silences another agent that reuses the same id. | ||
| // Empty for Claude Code, whose key is the raw session id. | ||
| sessionKeyPrefix string | ||
|
|
||
| // fallbackKey keys the throttle when there is no session id, so the hint | ||
| // prints at most once per hintSessionTTL on this machine. Empty means no | ||
| // throttle without a session id (Claude Code). | ||
| fallbackKey string | ||
|
|
||
| // durableThrottle prints the text only once its throttle marker is | ||
| // persisted (see claimHintMarker), so an unwritable cache can't turn the | ||
| // hint into a line on every command. False for | ||
| // Claude Code, whose marker write stays best-effort. | ||
| durableThrottle bool |
There was a problem hiding this comment.
[nit] The throttleKey comment (hint.go:305) says Claude's key "is the raw id and must not change". But cache.NewCache stores markers under a per-CLI-version directory, and nothing else reads this bucket, so prefixing Claude's key would break nothing. With the same <agent>:session:<id> key for Claude, throttleKey could derive the prefix from the agent name, and sessionKeyPrefix could go. At minimum, the comment should drop that reason. The durableThrottle comment also has a stray line break ("False for" / "Claude Code").
| // agentInstallHint returns the hint for a non-Claude registry agent. The text | ||
| // keeps Claude Code's imperative wording (hintText) and names the agent and | ||
| // scope, so the install acts on the calling agent and never stops at the agent | ||
| // picker or the scope prompt when the agent's shell is a terminal. |
There was a problem hiding this comment.
[nit] Agent callers never see the agent picker or the scope prompt anyway: installPromptsSupported (cmd/aitools/install.go:41-43) turns prompts off whenever AgentProvider() is set, and the non-interactive scope defaults to global. What --agents <name> actually does is target the calling agent, even when it isn't detected on the machine; --scope global only makes the default explicit. Could the comment say that instead?
| // in the shells it spawns. Only verified variables are listed; an agent missing | ||
| // here is throttled per machine instead (see agentInstallHint). | ||
| var agentSessionEnv = map[string]string{ | ||
| // Set by codex-cli (0.166.0) for every shell tool call, next to CODEX_CI. |
There was a problem hiding this comment.
[nit] .agents/rules/comments.md asks for a source reference URL when detecting environment variables. This comment names the codex-cli version but not where the variable is set. Please link the Codex source that exports CODEX_THREAD_ID, as hint.go does for the Claude hint format.
| assert.Equal(t, agentInstallHint(ByName(NameCodex), noPluginRecorded).text+"\n", stderr.String()) | ||
| } | ||
|
|
||
| func TestMaybeHint_UnwritableCacheSkipsHint(t *testing.T) { |
There was a problem hiding this comment.
[nit] This chmod-based test is skipped on Windows and when running as root, so on Windows nothing covers the "no persisted marker, no hint" rule. A second case with DATABRICKS_CACHE_ENABLED=false, which the claimHintMarker comment and the description both mention, reaches the same branch on every OS without chmod.
|
Replies to the two questions in the review:
|
- 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>
MaybeVersionCheckTip skipped only Claude Code, but MaybeHint now hints the registry agents too, so a Codex caller saw the root hook's `install --agents codex --scope global` line followed by the generic tip. Skip the tip whenever hintForAgent would hint the caller. Co-authored-by: Isaac <no-reply@databricks.com>
Build the agent hint from hintText, correct the doc comments on what --agents/--scope do for agent callers and on Claude's throttle key, cite the Codex source for CODEX_THREAD_ID, note the Cursor plugin gap, and add a portable DATABRICKS_CACHE_ENABLED=false test next to the chmod-based one. Co-authored-by: Isaac <no-reply@databricks.com>
… into aitools/agent-install-hints
The base dropped unsetEnv/hintEnvVars (testutil.SetAgentEnv now clears the whole environment) and writeCanonicalSkill, which only these tests use. Co-authored-by: Isaac <no-reply@databricks.com>
…-hints # Conflicts: # libs/aitools/agents/hint.go # libs/aitools/agents/hint_test.go # libs/aitools/installer/useragent.go # libs/telemetry/protos/README.md # libs/telemetry/protos/aitools_events.go
MaybeHint gained a pluginRecorded argument in #7586. Co-authored-by: Isaac <no-reply@databricks.com>
## 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))
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>
Summary
Until now the install hint was printed only to Claude Code. With this PR, the nine other registry agents (Codex, Cursor, GitHub Copilot CLI, OpenCode, Gemini CLI, Antigravity, Pi, Goose, Kiro) also get a one-line hint, but only when that agent's own Databricks tooling is missing:
MaybeHint(ctx, cmd, pluginRecorded) # cmd/root passes installer.PluginRecorded (global scope) hintForAgent(provider) claude-code -> existing Claude hint + registry agent -> agentInstallHint(agent) + installed = Agent.DatabricksTooling (install record is the plugin source for Codex/Copilot) skip aitools commands, auth token, CLI-spawned processes, no output stream - throttle per Claude session id + throttle key = "<agent>:session:<id>" (Codex: CODEX_THREAD_ID) + | "<agent>:machine" (agents without a session id) if installed: return + claim marker; non-Claude agents print only if the marker persisted print line(s), log aitools_hint_event (AGENT_INSTALL_TEXT for the new line)hintSessionTTL). Session keys carry the agent name as a prefix, so a Claude marker never silences Codex when both report the same id.DATABRICKS_CACHE_ENABLED=false), non-Claude agents get no hint at all. Otherwise they would get it on every command.cmd/rootpassesinstaller.PluginRecordedfor the global scope intoMaybeHint, the same record the calling-agent User-Agent reads.AitoolsHintEventdoc now describe the event for every agent..nextchanges/cli/aitools-hint-other-agents.md.Evidence
With
hintForAgent's new registry-agent branch temporarily removed (tests unchanged), then restored, at this head:ok libs/aitools/agents(48 tests and subtests pass) andok acceptanceforTestAccept/cmd/aitools/agent-hints.agent-hintsgolden shows a Codex hint once per thread, Cursor once per machine, Copilot mapped tocopilot, no hint for Gemini when its skills are installed, and no hint for Windsurf, the VS Code agent or nested agents.task checksall pass.go vetpasses withGOOS=windowsandGOOS=darwin.Merge Danger
Door: two-way
The hint is stderr-only and best-effort. It never changes exit codes or stdout, and it does no network calls. Reverting this PR removes it.
Blast Radius: agent-sessions
aitools_hint_event, which uploads at exit only if the command resolved auth.databricks aitools install, isn't detected, so those users keep getting the hint once per throttle window.--agents <name> --scope globalfails if the agent's own CLI isn't on PATH.go vet. On Windows, the read-only-cache test is skipped.This pull request and its description were written by Isaac.