Skip to content

aitools: install hints for non-Claude coding agents - #7586

Open
anton-107 wants to merge 1 commit into
aitools/claude-code-native-hintfrom
aitools/agent-install-hints
Open

anton-107 wants to merge 1 commit into
aitools/claude-code-native-hintfrom
aitools/agent-install-hints

Conversation

@anton-107

Copy link
Copy Markdown
Contributor

Stacked on #7585.

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:

Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents <agent> --scope global
 MaybeHint(ctx, cmd, pluginRecorded)          # cmd/root passes installer.GlobalPluginRecorded
   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)
  • The throttle lasts one hour (hintSessionTTL). Session keys carry the agent name as a prefix, 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. Otherwise they would get it on every command.
  • 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 in.
  • The telemetry README and the AitoolsHintEvent doc now describe the event for every agent.
  • Changelog fragment: .nextchanges/cli/aitools-hint-other-agents.md.

Evidence

With hintForAgent's new registry-agent branch temporarily removed (tests unchanged), then restored, at this head:

  • Before:
    --- FAIL: TestMaybeHint_PerAgent
    --- FAIL: TestMaybeHint_CodexThrottledPerThread
    --- FAIL: TestHintForAgent
    --- FAIL: TestAccept/cmd/aitools/agent-hints
    
    After: ok libs/aitools/agents (48 tests and subtests pass) and ok acceptance for TestAccept/cmd/aitools/agent-hints.
  • The agent-hints golden shows a Codex hint once per thread, Cursor once per machine, Copilot mapped to copilot, no hint for Gemini when its skills are installed, and no hint for Windsurf, the VS Code agent or nested agents.
  • On Linux at this head: build, aitools unit and acceptance tests, the cmdio/telemetry/root/version/apps/air tests, lint, fmt and task checks all pass. go vet passes with GOOS=windows and GOOS=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

  • Every CLI command run by one of these nine agents now does a filesystem probe and a cache read/write. Users whose tooling is missing see one extra stderr line per session (Codex) or per machine-hour (the others). Each printed line logs one aitools_hint_event, which uploads at exit only if the command resolved auth.
  • A plugin installed with the Codex or Copilot CLI directly, not via databricks aitools install, isn't detected, so those users keep getting the hint once per throttle window.
  • For Codex and Copilot, the hinted --agents <name> --scope global fails if the agent's own CLI isn't on PATH.
  • A Codex session in its default workspace-write sandbox can't write the user cache, so it never gets the hint.
  • Not tested on Windows or macOS beyond go vet. On Windows, the read-only-cache test is skipped.

This pull request and its description were written by Isaac.

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>
@anton-107
anton-107 force-pushed the aitools/agent-install-hints branch from f49b71b to 735415e Compare November 13, 2026 06:08
@github-actions

Copy link
Copy Markdown
Contributor

Commit: 735415ead | Workflow run

Regression test report

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

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

main (eeb4ef9):

acceptance_test.go:1378: Diff:
        --- air/image-push/output.txt
        +++ /tmp/TestAcceptairimage-push4151239088/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): same output as main (eeb4ef9)

TestAccept/cmd/aitools/agent-hints: branch ✅ | main (eeb4ef9) ❌ | latest (v1.26.0) ❌

main (eeb4ef9):

acceptance_test.go:1378: Diff:
        --- cmd/aitools/agent-hints/output.txt
        +++ /tmp/TestAcceptcmdaitoolsagent-hints3605627700/002/output.txt
        @@ -2,20 +2,17 @@
         === Codex is hinted once per thread
         
         >>> CODEX_CI=1 CODEX_THREAD_ID=thread-1 [CLI] version
        -Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents codex --scope global
         Databricks CLI v[CLI_VERSION]
         
         >>> CODEX_CI=1 CODEX_THREAD_ID=thread-1 [CLI] version
         Databricks CLI v[CLI_VERSION]
         
         >>> CODEX_CI=1 CODEX_THREAD_ID=thread-2 [CLI] version
        -Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents codex --scope global
         Databricks CLI v[CLI_VERSION]
         
         === Cursor exposes no session id, so it is hinted once per machine
         
         >>> CURSOR_AGENT=1 [CLI] version
        -Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents cursor --scope global
         Databricks CLI v[CLI_VERSION]
         
         >>> CURSOR_AGENT=1 [CLI] version
        @@ -24,7 +10,6 @@
         === Copilot CLI maps to the copilot registry agent
         
         >>> COPILOT_CLI=1 [CLI] version
        -Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents copilot --scope global
         Databricks CLI v[CLI_VERSION]
         
         === Gemini CLI with its own Databricks skills is not hinted

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

TestAccept/cmd/aitools/claude-config-dir: branch ✅ | main (eeb4ef9) ❌ | latest (v1.26.0) ❌

main (eeb4ef9):

acceptance_test.go:1378: Diff:
        --- cmd/aitools/claude-config-dir/output.txt
        +++ /tmp/TestAcceptcmdaitoolsclaude-config-dir2712797152/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 (eeb4ef9)

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

main (eeb4ef9):

acceptance_test.go:1246: Substituted DATABRICKS_CLI_GITHUB_API_URL "$DATABRICKS_HOST" -> "http://127.0.0.1:39535" ("[DATABRICKS_HOST]")
    acceptance_test.go:1246: Substituted DATABRICKS_SKILLS_BASE_URL "$DATABRICKS_HOST" -> "http://127.0.0.1:39535" ("[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/TestAcceptcmdaitoolstelemetryhint568842013/002/output.txt

latest (v1.26.0):

acceptance_test.go:1246: Substituted DATABRICKS_CLI_GITHUB_API_URL "$DATABRICKS_HOST" -> "http://127.0.0.1:34039" ("[DATABRICKS_HOST]")
    acceptance_test.go:1246: Substituted DATABRICKS_SKILLS_BASE_URL "$DATABRICKS_HOST" -> "http://127.0.0.1:34039" ("[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/TestAcceptcmdaitoolstelemetryhint4124195765/002/output.txt

@eng-dev-ecosystem-bot

Copy link
Copy Markdown
Collaborator

✅ Integration test report

Commit: 735415e

Run: 43376776735

Env 💚​RECOVERED ✅​pass 🙈​skip Time
💚​ aws linux-2core-8gb 1 270 19 6:00
💚​ aws-windows-latest-4core-16gb 1 272 17 4:16
💚​ azure linux-2core-8gb 1 269 19 5:19
💚​ azure-windows-latest-4core-16gb 1 271 17 4:00
💚​ gcp linux-2core-8gb 1 270 19 5:30
💚​ gcp-windows-latest-4core-16gb 1 272 17 3:15
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 6 slowest tests (at least 2 minutes):
duration env testname
4:10 aws-windows-latest-4core-16gb TestAccept
3:59 gcp linux-2core-8gb TestAccept
3:55 aws linux-2core-8gb TestAccept
3:54 azure-windows-latest-4core-16gb TestAccept
3:53 azure linux-2core-8gb TestAccept
3:07 gcp-windows-latest-4core-16gb TestAccept

@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 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

  1. 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 case durableThrottle prevents 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 the durableThrottle comment say why? (non-blocking)
  2. The hint relies only on each agent's SDK env marker. For Claude Code, the code notes that CLAUDECODE also 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 {

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] 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.

Comment thread cmd/root/root.go
// 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)

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] 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.

// 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 {

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] 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.

Comment on lines +28 to +32
// 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.

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 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",

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

[nit] This 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".

Comment on lines +109 to +123
// 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

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 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").

Comment on lines +23 to +26
// 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.

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] 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.

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/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) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

[nit] This 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.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants