aitools: installed plugin version differs from the version recorded and reported by `aitools list`

Trace the databricks aitools install, list, and update entry points, then compare the compatibility manifest with .databricks/aitools/skills/.state.json, .ai-dev-kit/skills.lock, and Claude Code’s installed_plugins.json. Determine which resolver supplies the installed version and make the CLI’s recorded and reported version match the plugin actually installed; verify that list and update use consistent state.

Describe the issue

On Claude Code, databricks aitools install delegates the plugin installation to Claude Code's own marketplace, which resolves and installs 0.2.18. The CLI then records 0.2.10 in its own state files, and databricks aitools list afterwards reports v0.2.10 - up to date.

The reported number comes from a stale compatibility pin, not from what was installed. Two independent resolvers disagree, and the CLI presents the wrong one as authoritative — about an installation it performed itself.

Where the 0.2.10 comes from — %LOCALAPPDATA%/databricks/compat-manifest.json:

{"0.299.2":{"appkit":"0.24.0","skills":"0.1.5"},
 "1.0.0":{"appkit":"0.57.0","skills":"0.2.10"}}

This is fetched from https://raw.githubusercontent.com/databricks/cli/main/internal/build/cli-compat.json, which returns the same content today — so it is a live upstream pin, not a stale local cache. CLI v1.17.0 falls in the >= 1.0.0 band and inherits a pin to skills 0.2.10, while databricks-agent-skills is currently at v0.2.19.

There appear to be two distinct problems:

1. The compatibility pin is stale. The 1.0.0 band has not been updated as skills releases shipped, so every CLI from 1.0.0 onward resolves to the same number.
2. The recorded version does not reflect what was installed. Observed behavior suggests aitools delegates to Claude Code's plugin installer without passing a version — the marketplace resolves independently — but then records the pinned number rather than the resolved one. (Inferred from the resulting file state; not verified against the implementation.)

Steps to reproduce the behavior

1. In a clean project directory, run the AI Dev Kit installer (irm https://raw.githubusercontent.com/databricks-solutions/ai-dev-kit/main/install.ps1 | iex), selecting: Claude Code, project scope, all skills. It calls databricks aitools install.
2. Observe the installer output: Claude Code databricks plugin v0.2.10
3. Run databricks aitools list in the project directory — it reports v0.2.10 - up to date.
4. Inspect ~/.claude/plugins/installed_plugins.json and filter by the project path — it shows 0.2.18.

Expected Behavior

The version the CLI records and reports is the version that ended up installed. aitools list should reflect the plugin that Claude Code will actually load.

Actual Behavior

Three state files, two different answers.

What Claude Code actually installed (~/.claude/plugins/installed_plugins.json):

{ "scope": "project",
  "version": "0.2.18",
  "installPath": "…/cache/claude-plugins-official/databricks/0.2.18",
  "installedAt": "2026-09-18T15:03:04.010Z",
  "gitCommitSha": "0fbf9ba4cdb2fd5a0efd952e8225acc1d5099809" }

What the CLI recorded (<project>/.databricks/aitools/skills/.state.json):

{ "release": "v0.2.10",
  "last_updated": "2026-09-18T10:05:17-05:00",
  "plugins": { "claude-code": { "version": "0.2.10" } } }

And (<project>/.ai-dev-kit/skills.lock): "skills_release": "0.2.10"

Timeline — the CLI wrote its record after the install it triggered:

15:03:04Z   Claude Code installs 0.2.18, writes installed_plugins.json
15:03:17Z   skills.lock written with 0.2.10
15:05:17Z   .state.json written with 0.2.10   <- two minutes later

Verification that 0.2.18 is what is really on disk and loaded: the cached 0.2.18/skills/ contains 31 skills including databricks-setup-local, which does not exist in 0.2.10/skills/ (30 skills). 0.2.18/.claude-plugin/plugin.json declares "version": "0.2.18".

Downstream impact. The stale .state.json is the CLI's own input. A subsequent databricks aitools update would evaluate against 0.2.10, and if it reinstalls it would rewrite installed_plugins.json — the file that actually governs what Claude Code loads. Incorrect bookkeeping can therefore propagate into real state.

OS and CLI version

• Databricks CLI v1.17.0
• Windows 11, PowerShell
• Claude Code, project-scoped installation

Is this a regression?

Not tested on earlier CLI versions, so this is not confirmed as a regression.

Worth noting from the compat manifest itself: it declares two bands, 0.299.2 -> skills 0.1.5 and 1.0.0 -> skills 0.2.10. A CLI below 1.0.0 would resolve to a different (also pinned) number, so the mismatch mechanism would presumably be present there too — but that is reasoning from the manifest, not an observation.

Debug Logs

Debug-level logs were not captured at install time. The relevant command output is:

$ databricks aitools list

Plugin installs:

  AGENT        STATUS
  Claude Code  databricks plugin - v0.2.10 - up to date


Available raw skill directories (v0.2.10):
...
0/32 raw skill directories installed (project)

Note that the listed skill catalogue is also the 0.2.10 one — it does not include databricks-setup-local, which is present in the 0.2.18 that is actually installed.

Happy to re-run with --log-level=debug and attach the output if that helps.

Suggested fixes

• Record the version actually resolved by the agent's plugin installer, not the pinned one.
• Make aitools list read the agent's own registry (installed_plugins.json for Claude Code) rather than, or in addition to, .state.json.
• Refresh the cli-compat.json pin, or document that it is a floor rather than a target.