@softspark/ai-toolkit 4.28.0 → 4.29.0

package/CHANGELOG.md

@@ -7,6 +7,44 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.29.0 — Stale plugin uploads stop hiding (2026-08-21)
+
+### Added
+
+- **`doctor` reports Claude app plugin version drift.** Check 11 now compares the
+  `version` recorded for every `ai-toolkit@…` entry in
+  `~/.claude/plugins/installed_plugins.json` against the installed toolkit's
+  `package.json` and warns when they differ. The upload is a point-in-time ZIP:
+  once the toolkit moves on, Chat and Cowork keep running the skills, agents,
+  hooks, and rules from whenever the export was made, with no signal anywhere
+  that they are behind. `--fix` deliberately cannot clear this warning — the
+  export can be regenerated but the upload itself happens by hand in the app's
+  Customize > Plugins panel, so the check names the two steps instead of
+  pretending to do them.
+
+### Changed
+
+- **Version drift is checked before the enabled/disabled branch.** A plugin
+  disabled for Claude Code still feeds Chat and Cowork, which have no other
+  channel for toolkit content. The old flow returned `OK: registered but
+  disabled` and never looked at versions, so the state a user reaches by running
+  `doctor --fix` was also the state where a stale upload passed silently. That
+  was the wrong place to stop looking.
+- **`ai-toolkit install` re-asserts the plugin as disabled for Claude Code.**
+  Uploading the ZIP re-enables the plugin every time, which put the double-load
+  fix back on whoever remembered to run `doctor --fix` afterwards. Global
+  installs and updates now flip enabled toolkit plugins to `false` in
+  `~/.claude/settings.json` and print each key they touched. `--local` and
+  `--dry-run` are untouched, and non-toolkit plugins are never modified. The
+  disable logic moved into `disable_toolkit_plugins_for_claude_code()` in
+  `scripts/doctor.py`, shared by both call sites.
+- Test count: 1659 → 1666.
+- Skill body budget threshold unchanged. The largest body (`medplum-rules`, 16760
+  bytes) sits 1240 bytes under the 18000-byte warn line, short of the 2000-byte
+  margin the ratchet requires, so the threshold stays where it is this release.
+
+---
+
 ## v4.28.0 — MCP servers reach Chat and Cowork (2026-08-21)
 
 ### Added

package/README.md

@@ -6,22 +6,24 @@
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-109-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1659%20passing-success)](tests/)
-
-## What's New in v4.28.0
-
-**v4.28.0** gives Claude Chat and Cowork their MCP servers:
-
-- The Claude app parses `claude_desktop_config.json` on startup and reports bad
-  entries in its own warning dialog, but ai-toolkit never wrote to it. A user
-  with seven servers configured for Claude Code still had an empty `mcpServers`
-  block in Cowork.
-- `ai-toolkit mcp install --editor claude-app --scope global <template>` now
-  writes it, on macOS, Windows, and Linux, honoring `CLAUDE_USER_DATA_DIR` the
-  way the app does. `--editor claude` remains Claude Code -- different runtime,
-  different file.
-- The app accepts stdio entries only, so HTTP/SSE templates are bridged as
-  `npx -y mcp-remote <url>` rather than written verbatim and silently skipped.
+[![Tests](https://img.shields.io/badge/tests-1666%20passing-success)](tests/)
+
+## What's New in v4.29.0
+
+**v4.29.0** stops a stale Claude app upload from passing as healthy:
+
+- The plugin ZIP is a point-in-time snapshot. Once the toolkit moves on, Chat and
+  Cowork keep running the skills, agents, hooks, and rules from whenever you
+  exported it, with nothing anywhere saying so.
+- `ai-toolkit doctor` now compares the version recorded in
+  `~/.claude/plugins/installed_plugins.json` against the installed toolkit and
+  warns when they differ -- including when the plugin is disabled for Claude
+  Code, since Chat and Cowork still load it.
+- `--fix` cannot clear that warning. It can regenerate the export; the upload
+  itself is manual, so the check names both steps instead of pretending.
+- `ai-toolkit install` now re-asserts the plugin as disabled for Claude Code.
+  Uploading the ZIP re-enables it every time, which had left the double-load fix
+  to whoever remembered to re-run `doctor --fix`.
 
 ## Table of Contents
 

package/app/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "ai-toolkit",
   "displayName": "AI Toolkit",
   "description": "Professional-grade engineering skills, agents, rules, and lifecycle guardrails for Claude Code, Claude Chat, and Cowork.",
-  "version": "4.28.0",
+  "version": "4.29.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.28.0",
+  "version": "4.29.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.28.0",
+  "version": "4.29.0",
   "description": "AI coding toolkit: 109 skills, 44 agents, 12 developer-tool integrations, recoverable native tool-output filtering, Claude Chat/Cowork export, safety constitution, SARIF audit, and signed npm provenance.",
   "keywords": [
     "claude",

package/scripts/doctor.py

@@ -683,6 +683,68 @@ def _registered_toolkit_plugins(registry: dict) -> list[str]:
     return [key for key in plugins if str(key).split("@", 1)[0] == "ai-toolkit"]
 
 
+def _registered_plugin_versions(registry: dict, keys: list[str]) -> dict[str, str]:
+    """Map plugin key to the version recorded in the Claude Code registry."""
+    plugins = registry.get("plugins", {})
+    versions: dict[str, str] = {}
+    for key in keys:
+        entries = plugins.get(key)
+        if not isinstance(entries, list):
+            continue
+        for entry in entries:
+            if isinstance(entry, dict) and isinstance(entry.get("version"), str):
+                versions[key] = entry["version"]
+                break
+    return versions
+
+
+def _toolkit_package_version() -> str | None:
+    """Version of the installed toolkit package, or None when unreadable."""
+    try:
+        data = json.loads((toolkit_dir / "package.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    version = data.get("version")
+    return version if isinstance(version, str) else None
+
+
+def disable_toolkit_plugins_for_claude_code() -> list[str]:
+    """Disable every enabled ai-toolkit plugin in ``~/.claude/settings.json``.
+
+    Returns the keys that were flipped. Uploading the Claude app plugin re-enables
+    it for Claude Code every time, so this is re-asserted rather than fixed once.
+    Raises OSError when settings.json cannot be written.
+    """
+    if not PLUGIN_REGISTRY.is_file():
+        return []
+    try:
+        registry = json.loads(PLUGIN_REGISTRY.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return []
+
+    keys = _registered_toolkit_plugins(registry)
+    if not keys:
+        return []
+
+    settings_json = CLAUDE_DIR / "settings.json"
+    try:
+        settings = json.loads(settings_json.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return []
+    enabled = settings.get("enabledPlugins", {})
+    if not isinstance(enabled, dict):
+        enabled = {}
+
+    active = [key for key in keys if enabled.get(key, True)]
+    if not active:
+        return []
+
+    enabled.update({key: False for key in active})
+    settings["enabledPlugins"] = enabled
+    settings_json.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+    return active
+
+
 def check_plugin_double_load(dr: DiagResult, fix_mode: bool) -> None:
     """Warn when the Claude app plugin and the global install both feed Claude Code.
 
@@ -709,6 +771,22 @@ def check_plugin_double_load(dr: DiagResult, fix_mode: bool) -> None:
         dr.ok("no ai-toolkit plugin registered in Claude Code")
         return
 
+    # Version drift is independent of whether the plugin is enabled here: a
+    # plugin disabled for Claude Code still feeds Chat and Cowork, and those
+    # runtimes have no other channel for skills, agents, hooks, or rules. Report
+    # it before the enabled/disabled branch, which returns early on the healthy
+    # path and would otherwise let a stale upload pass unnoticed.
+    toolkit_version = _toolkit_package_version()
+    if toolkit_version:
+        for key, plugin_version in _registered_plugin_versions(registry, keys).items():
+            if plugin_version != toolkit_version:
+                dr.warn(
+                    f"{key} is v{plugin_version} but the toolkit is v{toolkit_version}: "
+                    "Chat and Cowork keep running the older skills, agents, hooks, and "
+                    "rules until you re-run `ai-toolkit claude-app export` and upload "
+                    "the ZIP again (--fix cannot do this; the upload is manual)"
+                )
+
     settings_json = CLAUDE_DIR / "settings.json"
     try:
         settings = json.loads(settings_json.read_text(encoding="utf-8"))
@@ -738,14 +816,12 @@ def check_plugin_double_load(dr: DiagResult, fix_mode: bool) -> None:
     if not fix_mode:
         return
 
-    enabled.update({key: False for key in active})
-    settings["enabledPlugins"] = enabled
     try:
-        settings_json.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+        disabled = disable_toolkit_plugins_for_claude_code()
     except OSError as exc:
         dr.fail(f"could not disable plugin in settings.json: {exc}")
         return
-    for key in active:
+    for key in disabled:
         dr.fixed(f"disabled {key} for Claude Code (global install stays authoritative)")
 
 

package/scripts/install.py

@@ -831,6 +831,18 @@ def main() -> None:
             if is_new:
                 print(f"  Registered project in {TOOLKIT_DATA_DIR / 'projects.json'}")
 
+    # A global install is authoritative for Claude Code, so an uploaded Claude
+    # app plugin must not feed it in parallel. Uploading the ZIP re-enables the
+    # plugin every time, so this is re-asserted on every install/update rather
+    # than left to whoever remembers to run `doctor --fix` afterwards.
+    if not local and not dry_run:
+        from doctor import disable_toolkit_plugins_for_claude_code
+        try:
+            for key in disable_toolkit_plugins_for_claude_code():
+                print(f"  Disabled Claude app plugin for Claude Code: {key}")
+        except OSError as error:
+            print(f"  WARNING: could not disable Claude app plugin: {error}")
+
     print_summary(local=local)