Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .nextchanges/cli/claude-code-native-hint-throttle.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
* 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](https://github.com/databricks/cli/pull/7692))
16 changes: 15 additions & 1 deletion acceptance/cmd/aitools/claude-config-dir/output.txt
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ ID Name State
4321 some-test-cluster
9876 some-other-cluster

=== Within one session both lines print once, so 2>&1 pipelines see them only on the first command
=== Within one session the text line prints at most once per hour and the native line at most once per 10 minutes, so a 2>&1 pipeline on the next command sees neither

>>> [CLI] clusters list
<claude-code-hint v="1" type="plugin" value="databricks@claude-plugins-official" />
Expand All @@ -55,3 +55,17 @@ ID Name State
ID Name State
4321 some-test-cluster
9876 some-other-cluster

=== A command outside a Claude Code subprocess leaves the native line due, so the next Claude Code command prints only that line

>>> CLAUDE_CODE_CHILD_SESSION= [CLI] clusters list
Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install
ID Name State
4321 some-test-cluster
9876 some-other-cluster

>>> [CLI] clusters list
<claude-code-hint v="1" type="plugin" value="databricks@claude-plugins-official" />
ID Name State
4321 some-test-cluster
9876 some-other-cluster
8 changes: 7 additions & 1 deletion acceptance/cmd/aitools/claude-config-dir/script
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,14 @@ trace CLAUDE_CODE_CHILD_SESSION= $CLI clusters list

# The session throttle lives in the file cache, which a host could disable.
export DATABRICKS_CACHE_ENABLED=true
title "Within one session both lines print once, so 2>&1 pipelines see them only on the first command"
title "Within one session the text line prints at most once per hour and the native line at most once per 10 minutes, so a 2>&1 pipeline on the next command sees neither"
export CLAUDE_CODE_SESSION_ID=session-1
trace $CLI clusters list
trace $CLI clusters list
unset CLAUDE_CODE_SESSION_ID

title "A command outside a Claude Code subprocess leaves the native line due, so the next Claude Code command prints only that line"
export CLAUDE_CODE_SESSION_ID=session-2
trace CLAUDE_CODE_CHILD_SESSION= $CLI clusters list
trace $CLI clusters list
unset CLAUDE_CODE_SESSION_ID
151 changes: 102 additions & 49 deletions libs/aitools/agents/hint.go
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,11 @@ const (
// the output and decides when to prompt: only in an attended interactive
// session, at most once per session, and once ever per plugin for that
// Claude Code user config (so in practice once per machine), whatever the
// answer. It is still throttled with the text hint: Claude Code strips it
// only from the tool output, so in a `2>&1 | jq` pipeline the next process
// reads it raw, and after a "No" repeating it can't lead to an install. The
// format is fixed by Claude Code: https://code.claude.com/docs/en/plugins/cli-hints
// answer. It is still throttled per session (see nativeHintThrottle): Claude
// Code strips it only from the tool output, so in a `2>&1 | jq` pipeline the
// next process reads it raw, and after a "No" repeating it can't lead to an
// install. The format is fixed by Claude Code:
// https://code.claude.com/docs/en/plugins/cli-hints
claudeNativeHint = `<claude-code-hint v="1" type="plugin" value="` + databricksPluginID + "@" + claudeOfficialMarketplace + `" />`

// claudeChildSessionEnv is set only in subprocesses Claude Code itself
Expand Down Expand Up @@ -66,20 +67,44 @@ const (
selfExecEnv = "DATABRICKS_CLI_SELF_EXEC"

// claudeSessionEnv is Claude Code's per-session identifier. It keys the
// per-session throttle shared by the text and native lines (at most one
// hint per hintSessionTTL per session); when unset (older Claude) the hint
// degrades to per-command.
// per-session throttles of the text and native lines; when unset (older
// Claude) both lines degrade to per-command.
claudeSessionEnv = "CLAUDE_CODE_SESSION_ID"

// hintCacheComponent names the cache bucket holding "already hinted"
// markers (per session, or per agent on this machine).
hintCacheComponent = "aitools-hint"
)

// hintSessionTTL is how long a session's "already hinted" marker lives. Within
// that window a session is hinted at most once; after it expires the hint may
// fire again for the same session.
const hintSessionTTL = time.Hour
// hintThrottle is an "already hinted" marker in the file cache, per throttle
// key (see agentHint.throttleKey): a line it guards prints at most once per
// ttl per key.
type hintThrottle struct {
// component names the cache bucket holding the markers. Each throttle needs
// its own: a cache expires every file in its bucket by its own ttl.
component string
ttl time.Duration
}

var (
// textHintThrottle throttles the model-facing text hint, which the model
// reads in every tool output it lands in.
textHintThrottle = hintThrottle{component: "aitools-hint", ttl: time.Hour}

// nativeHintThrottle throttles the agent-native line on its own, shorter
// clock. The session id doesn't tell the main loop from a subagent or a
// hook (a subagent's commands carry the parent's session id and the
// child-session marker), and Claude Code strips the line there without
// prompting; with the text hint's hour, a subagent making the session's
// first call would hide the dialog from the main loop for that hour.
// Claude Code prompts at most once per session anyway, so repeating the
// line costs only a raw tag in a `2>&1` pipeline every ten minutes, and a
// session waits at most that long for the dialog.
nativeHintThrottle = hintThrottle{component: "aitools-native-hint", ttl: 10 * time.Minute}

// nativeEventThrottle keeps the native line's hint-shown event on the text
// hint's clock, so a native-only repeat triggers no telemetry upload at
// exit and native-event counts don't grow with session length. Its marker
// holds whether that event was logged in the current text window: each
// text print starts a window and rewrites it.
nativeEventThrottle = hintThrottle{component: "aitools-native-hint-event", ttl: textHintThrottle.ttl}
)

// agentHint describes how one calling agent is nudged to install the
// Databricks AI tooling.
Expand All @@ -89,16 +114,16 @@ type agentHint struct {
installed func(ctx context.Context) bool

// text is the model-facing recommendation, printed at most once per
// hintSessionTTL per session (see sessionEnv), or per agent on this machine
// when there is no session id (see fallbackKey), together with native.
// textHintThrottle per session (see sessionEnv), or per agent on this
// machine when there is no session id (see fallbackKey).
text string

// textKind tags the hint-shown event logged when text prints.
textKind protos.AitoolsHintKind

// sessionEnv names the env var carrying the agent's session id, which keys
// the throttle for both lines. When it is empty or unset at runtime,
// fallbackKey keys the throttle instead.
// the throttles of both lines. When it is empty or unset at runtime,
// fallbackKey keys them instead.
sessionEnv string

// sessionKeyPrefix namespaces the session id in the throttle key, so one
Expand All @@ -108,7 +133,7 @@ type agentHint struct {
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
// prints at most once per textHintThrottle on this machine. Empty means no
// throttle without a session id (Claude Code).
fallbackKey string

Expand All @@ -119,8 +144,9 @@ type agentHint struct {
durableThrottle bool

// native returns a line the agent itself acts on (for Claude Code, its
// plugin install prompt), or "" when none applies to this invocation. It
// shares the text's per-session throttle. Nil for agents without one.
// plugin install prompt), or "" when none applies to this invocation. It is
// throttled per session by nativeHintThrottle, only when it prints. Nil for
// agents without one (all but Claude Code).
native func(ctx context.Context) string

// nativeKind tags the hint-shown event logged when the native line prints.
Expand Down Expand Up @@ -170,9 +196,10 @@ func (h *agentHint) nativeLine(ctx context.Context) string {
// token` and `auth docker token` credential helpers, a CLI process the CLI
// started itself, when there is no output stream, and once the tooling is
// present.
// Both lines, the agent-native one (if any) and the model-facing text, and
// their hint-shown events are throttled together per session, or per agent on
// this machine for agents without a session id (fallbackKey).
// The agent-native line (if any) and the model-facing text are throttled
// independently, per session or, for agents without a session id, per agent
// on this machine (fallbackKey). Both hint-shown events follow the text's
// clock (see nativeEventThrottle).
// pluginRecorded reads the CLI install record for agents whose plugin has no
// manifest reader here (see Agent.DatabricksTooling).
// Best-effort: it never fails the command. Besides the stderr lines, it logs a
Expand All @@ -195,34 +222,52 @@ func MaybeHint(ctx context.Context, cmd *cobra.Command, pluginRecorded PluginRec
if !cmdio.HasIO(ctx) {
return
}
// Check the throttle before the filesystem probe, so a throttled session
// skips the plugin/skills detection. The marker is written only once a hint
// is due, so an already-installed environment never burns it.
// Check the throttles before the filesystem probe, so a throttled session
// skips the plugin/skills detection. A marker is written only once its
// line is due, so an already-installed environment never burns one, and
// neither does a native line withheld from this invocation.
key := hint.throttleKey(ctx)
if alreadyHintedThisSession(ctx, key) {
native := hint.nativeLine(ctx)
if native != "" && nativeHintThrottle.seen(ctx, key) {
native = ""
}
textDue := !textHintThrottle.seen(ctx, key)
if native == "" && !textDue {
return
}
if hint.installed(ctx) {
return
}
if !hint.claim(ctx, key) {
// Only agents without a native line have a durable throttle, so a failed
// claim leaves nothing to print.
if textDue && !hint.claim(ctx, key) {
return
}
if native := hint.nativeLine(ctx); native != "" {
if native != "" {
cmdio.LogString(ctx, native)
logHintShown(ctx, hint.nativeKind)
nativeHintThrottle.record(ctx, key)
// A text print starts a new text window, in which this is the first
// native print.
if textDue || !nativeEventThrottle.seen(ctx, key) {

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] No test covers the textDue || half of this condition. With it removed, go test ./libs/aitools/agents/ still passes, because every test that prints the text and native lines together starts with the event marker missing or aged out.

It matters when the previous window's first native line printed late. Say a text-only command runs at T0 and the first native line at T0+55m, which writes a true event marker that lasts until T0+115m. A command at T0+61m then prints both lines. Without textDue ||, that command logs only INSTALL_TEXT, so the new window's CLAUDE_CODE_NATIVE event is lost.

Please add a test for this sequence:

  1. Run a text-only command.
  2. Age the text marker by 55 minutes and run a Claude Code command.
  3. Age the text marker past 1 hour and the native marker past 10 minutes, leaving the event marker fresh.
  4. Run another Claude Code command and expect both lines and both events.

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.

Added TestMaybeHint_TextAndNativePrintStartsNewNativeEventWindow in feeecc5, following your sequence. It fails with textDue || removed.

logHintShown(ctx, hint.nativeKind)
nativeEventThrottle.set(ctx, key, true)
}
} else if textDue && hint.native != nil {
nativeEventThrottle.set(ctx, key, false)
}
Comment on lines +246 to +257

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 description counts the cost of the 10-minute clock as a raw tag in a 2>&1 | jq pipeline. It leaves out telemetry. Each native-only repeat logs a CLAUDE_CODE_NATIVE event, and a command that resolved auth then uploads telemetry at exit. That upload waits up to hintOnlyUploadTimeout (1s); without the event, the command wouldn't upload at all.

Take a long session without the plugin, where an agent runs databricks jobs list every few minutes. It now makes up to 6 of these uploads per hour instead of 1, and native-event counts grow with session length rather than with the number of dialog chances. Consider keeping the native event on the text hint's hourly clock. Otherwise, mention the extra uploads in the description and the README. (in reply to #7692)

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.

Went with keeping the native event on the text hint's hourly clock (9d0ae56). The CLAUDE_CODE_NATIVE event is logged only for the first native line since the text last printed, so a native-only repeat logs nothing and triggers no exit-time upload. TestMaybeHint_NativeOnlyRepeatLogsNoEvent covers this, and the description's cost paragraph is updated.

if textDue {
cmdio.LogString(ctx, hint.text)
logHintShown(ctx, hint.textKind)
}
Comment on lines +225 to +261

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.

[blocking] This branch conflicts with main, and the conflict isn't mechanical. After this commit, #7586 (d285909) rewrote MaybeHint on main in three ways. It keys the throttle by throttleKey: an agent-prefixed session id, or a per-machine fallbackKey. It prints non-Claude hints only after claim/claimHintMarker has persisted the marker. And it takes a third pluginRecorded argument. Main's hint_agents.go:59 (claimHintMarker) still uses hintCacheComponent and hintSessionTTL, which this PR deletes. The new tests also call the two-argument MaybeHint. If the conflict is resolved by taking this branch's hint.go, the build breaks and the non-Claude throttle is lost.

Please rebase onto main and then:

  • key hintThrottle by the throttle key;
  • have claimHintMarker use textHintThrottle, or keep the constants;
  • keep the native throttle for Claude Code only;
  • update the new tests and the acceptance output.

The green CI ran before #7585 and #7586 landed, so it needs a fresh run after the rebase.

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.

Rebased onto main as one commit, 9d0ae56. hintThrottle is now keyed by throttleKey, and claimHintMarker uses textHintThrottle, so non-Claude hints still print only after the claim persists. The native 10-minute throttle applies only to Claude Code. The tests use the three-argument MaybeHint, and the acceptance output is regenerated. Fresh CI is running.

cmdio.LogString(ctx, hint.text)
logHintShown(ctx, hint.textKind)
}

// claim records the throttle key and reports whether the hint may print. A
// durable throttle allows it only once the marker has persisted.
// claim records the text's throttle key and reports whether the text may
// print. A durable throttle allows it only once the marker has persisted.
func (h *agentHint) claim(ctx context.Context, key string) bool {
if h.durableThrottle {
return claimHintMarker(ctx, key)
}
recordSessionHint(ctx, key)
textHintThrottle.record(ctx, key)
return true
}

Expand Down Expand Up @@ -342,26 +387,34 @@ func (h *agentHint) throttleKey(ctx context.Context) string {
return h.fallbackKey
}

// alreadyHintedThisSession reports whether the throttle key was hinted within
// the last hintSessionTTL. With no key it returns false so the hint fires per
// command.
func alreadyHintedThisSession(ctx context.Context, key string) bool {
// markers returns the file cache holding t's markers.
func (t hintThrottle) markers(ctx context.Context) *cache.Cache {
return cache.NewCache(ctx, t.component, t.ttl, nil)
}

// seen reports whether key was marked true within the last t.ttl. With no key
// it returns false so the line prints per command.
func (t hintThrottle) seen(ctx context.Context, key string) bool {
if key == "" {
return false
}
c := cache.NewCache(ctx, hintCacheComponent, hintSessionTTL, nil)
_, seen := cache.Get[bool](ctx, c, key)
return seen
marked, ok := cache.Get[bool](ctx, t.markers(ctx), key)
return ok && marked
}

// record marks key, so later commands skip the line until the marker expires
// (t.ttl). No-op when the key is "".
func (t hintThrottle) record(ctx context.Context, key string) {
t.set(ctx, key, true)
}

// recordSessionHint marks the throttle key as hinted, so later commands stay
// quiet until the marker expires (hintSessionTTL). No-op when the key is "".
func recordSessionHint(ctx context.Context, key string) {
// set writes key's marker, restarting its ttl; seen reports it only when
// marked is true. No-op when the key is "".
func (t hintThrottle) set(ctx context.Context, key string, marked bool) {
if key == "" {
return
}
c := cache.NewCache(ctx, hintCacheComponent, hintSessionTTL, nil)
cache.Put(ctx, c, key, true)
cache.Put(ctx, t.markers(ctx), key, marked)
}

// sessionID returns the value of sessionEnv, or "" when the agent has no
Expand Down
2 changes: 1 addition & 1 deletion libs/aitools/agents/hint_agents.go
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ func agentInstallHint(a *Agent, pluginRecorded PluginRecordedFunc) *agentHint {
// caching turned off (DATABRICKS_CACHE_ENABLED=false): nothing persists, so
// these agents get no hint.
func claimHintMarker(ctx context.Context, key string) bool {
c := cache.NewCache(ctx, hintCacheComponent, hintSessionTTL, nil)
c := textHintThrottle.markers(ctx)
cache.Put(ctx, c, key, true)
_, ok := cache.Get[bool](ctx, c, key)
return ok
Expand Down
Loading
Loading