@softspark/ai-toolkit 4.26.0 → 4.27.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.27.0 — Doctor sees the Claude app plugin (2026-08-21)
+
+### Added
+
+- **Doctor check 11: plugin double-load.** `ai-toolkit doctor` now reads the
+  Claude Code plugin registry (`~/.claude/plugins/installed_plugins.json`) and
+  `enabledPlugins` in `~/.claude/settings.json`. When an uploaded Claude app
+  plugin is active next to the global install, both feed the same session:
+  Claude Code merges plugin hooks with user hooks without deduplication, so every
+  toolkit hook fires twice per event and skills and agents load twice. The check
+  warns with the hook count, and `--fix` disables the plugin for Claude Code
+  while leaving the global install authoritative. Previously this passed as a
+  healthy install with no signal at all.
+- `kb/troubleshooting/plugin-double-load.md` documents the symptom, the debug-log
+  evidence, and the fix.
+
+---
+
 ## v4.26.0 — Python floor is declared and enforced (2026-08-21)
 
 ### Added

package/README.md

@@ -6,19 +6,23 @@
 [![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-1640%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1645%20passing-success)](tests/)
 
-## What's New in v4.26.0
+## What's New in v4.27.0
 
-**v4.26.0** declares and enforces the Python floor the scripts already needed:
+**v4.27.0** teaches `doctor` about a collision it used to report as healthy:
 
-- `ai-toolkit` now checks `python3` before running anything and requires 3.11+.
-- macOS `/usr/bin/python3` is 3.9, which used to crash `update --local` with a
-  raw `dataclass() got an unexpected keyword argument 'slots'` traceback. You
-  now get the version, the requirement, and `brew install python@3.13`.
-- `python3 scripts/*.py` run directly fails the same way, via `_common.py`.
-- CI runs the syntax check plus a full import sweep on both 3.11 and 3.13, so a
-  version-gated runtime feature cannot slip through `py_compile` again.
+- Uploading the Claude app plugin ZIP registers it under `~/.claude/plugins`,
+  which Claude Code reads too. The plugin then carries the same skills, agents,
+  and hooks as the global install.
+- Claude Code merges plugin hooks with user hooks without deduplication, so
+  every toolkit hook fired twice per event and skills and agents loaded twice.
+  `doctor` printed `HEALTH CHECK PASSED` through all of it.
+- New check 11 reports the collision with the hook count; `doctor --fix`
+  disables the plugin for Claude Code and leaves the global install
+  authoritative.
+- `kb/troubleshooting/plugin-double-load.md` documents the debug-log evidence
+  and the verification steps.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -188,7 +192,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats and Python test suite (1640 tests)
+├── tests/               # Bats and Python test suite (1645 tests)
 └── CHANGELOG.md
 ```
 

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.26.0",
+  "version": "4.27.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-08-21T08:34:52Z",
+  "last_run": "2026-08-21T15:52:27Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -66,7 +66,7 @@
       }
     },
     "claude-app": {
-      "docs_hash": "7e06a1985d5bb822",
+      "docs_hash": "cacc8b579baa5e86",
       "headings": [
         "Add global and folder instructions",
         "Availability",
@@ -223,7 +223,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "fc1c7e43bec9f748",
+      "docs_hash": "df3b133739abfa24",
       "headings": [
         "API",
         "API Reference",
@@ -397,7 +397,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "a2c9759e0296670d",
+      "docs_hash": "c66bb0647b70c7cf",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -438,7 +438,7 @@
       "version": "0.55.1"
     },
     "github-copilot": {
-      "docs_hash": "ab9b7f5b4b692e05",
+      "docs_hash": "2e595a058e906644",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot automations",
@@ -475,7 +475,7 @@
       }
     },
     "google-antigravity": {
-      "docs_hash": "9fe532d247c3e361",
+      "docs_hash": "8cbf9aaffb6b57bf",
       "headings": [],
       "markers": {
         "AGENTS.md": false,
@@ -502,7 +502,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "4287f7d767dda4a8",
+      "docs_hash": "3e9f45631e71a28c",
       "headings": [
         "Add features",
         "Ask questions",
@@ -564,7 +564,7 @@
       }
     },
     "windsurf": {
-      "docs_hash": "60e25f8cb4c381be",
+      "docs_hash": "b08c4f883c276129",
       "headings": [
         "Accounts",
         "Advanced",

package/kb/troubleshooting/README.md

@@ -3,10 +3,12 @@ title: "Troubleshooting"
 service: ai-toolkit
 category: troubleshooting
 tags: [troubleshooting, debugging]
-last_updated: "2026-03-25"
-description: "Section index for ai-toolkit troubleshooting. No documents are filed here yet; new ones follow the troubleshooting template."
+last_updated: "2026-08-21"
+description: "Section index for ai-toolkit troubleshooting, covering the Claude app plugin double-load collision."
 ---
 
 # Troubleshooting
 
-Problem resolution guides. Guides will be added here as they are created.
+Problem resolution guides.
+
+- [Claude App Plugin Loads Twice in Claude Code](plugin-double-load.md) -- hooks fire twice after the plugin ZIP is uploaded next to a global install.

package/kb/troubleshooting/plugin-double-load.md

@@ -0,0 +1,97 @@
+---
+title: "Claude App Plugin Loads Twice in Claude Code"
+category: troubleshooting
+service: ai-toolkit
+tags: [plugin, claude-app, hooks, duplication, doctor]
+created: "2026-08-21"
+last_updated: "2026-08-21"
+description: "Every toolkit hook fires twice and skills and agents load twice after the Claude app plugin ZIP is uploaded on a machine that already has the global install. Cause: the app registers the plugin under ~/.claude/plugins, which Claude Code also reads."
+---
+
+# Claude App Plugin Loads Twice in Claude Code
+
+## Symptom
+
+After uploading `ai-toolkit-claude-app.zip` through `Customize > Plugins`, Claude
+Code sessions get slower and every hook side effect appears twice: duplicate rows
+in `governance.log`, duplicate session state writes, two Stop gates per turn.
+`ai-toolkit doctor` reports a healthy install because it only inspected
+`~/.claude` and `app/plugins`.
+
+## Cause
+
+The Claude app writes uploaded plugins into
+`~/.claude/plugins/marketplaces/local-desktop-app-uploads/` and sets
+`enabledPlugins` in `~/.claude/settings.json`. Both paths belong to Claude Code
+as well, so Claude Code loads the plugin on top of the global install. The
+bundle carries the same catalog as `~/.claude`, and plugin hooks merge with user
+hooks without deduplication.
+
+Confirmed in a Claude Code debug log (`claude --debug -p ...`, then read
+`~/.claude/debug/latest`):
+
+```
+Loaded 111 unique skills (... user: 111 ...)
+Total plugin skills loaded: 111 (0 duplicate/user-owned entries skipped)
+Total plugin agents loaded: 44
+Read manifest hooks for plugin ai-toolkit (enabled=true): ./claude-app/hooks/hooks.json
+```
+
+The `skills` manifest field adds to the default `skills/` directory instead of
+replacing it, so the plugin contributes its 109 catalog skills plus the 2
+app-only rule skills.
+
+## Diagnosis
+
+```bash
+ai-toolkit doctor
+```
+
+Check 11 reports the collision:
+
+```
+## 11. Plugin Double-Load
+  WARN: ai-toolkit@local-desktop-app-uploads is active next to the global install: 28 toolkit hooks fire twice per event and skills/agents load twice (run: ai-toolkit doctor --fix)
+```
+
+To see the duplication directly, count hook invocations per source in a fresh
+session log:
+
+```bash
+grep -oE "[^\"' ]*hooks/[a-z0-9._-]+\.sh" ~/.claude/debug/latest | sort | uniq -c
+```
+
+## Fix
+
+```bash
+ai-toolkit doctor --fix
+```
+
+That sets the plugin to `false` in `enabledPlugins` and leaves the global
+install authoritative. Claude Code then logs
+`enabled=false; will NOT register, plugin is disabled`, and plugin skills and
+agents drop to 0.
+
+The global install is the richer surface for Claude Code: it delivers rules as
+real files under `~/.claude/rules/`, which are always in context, while the
+plugin exposes them as an `ai-toolkit-rules` skill the model has to load. The
+plugin also has no `session-context.sh` hook.
+
+Keep the plugin enabled only when Claude Code has no global install, for example
+a machine that runs the Claude app alone. In that case the plugin is the single
+source and check 11 stays quiet.
+
+## Verification
+
+```bash
+claude --debug -p "ok"
+grep -E "Total plugin (skills|agents) loaded|enabled=" ~/.claude/debug/latest
+```
+
+Expect `Total plugin skills loaded: 0`, `Total plugin agents loaded: 0`, and the
+`plugin is disabled` line.
+
+## Related
+
+- `kb/reference/global-install-model.md`
+- `kb/procedures/maintenance-sop.md`

package/llms-full.txt

@@ -73,6 +73,7 @@
 - [Unique Features & Differentiators](kb/reference/unique-features.md)
 - [Windows Support](kb/reference/windows-support.md)
 - [Troubleshooting](kb/troubleshooting/README.md)
+- [Claude App Plugin Loads Twice in Claude Code](kb/troubleshooting/plugin-double-load.md)
 
 ## Skills
 
@@ -16130,13 +16131,117 @@ title: "Troubleshooting"
 service: ai-toolkit
 category: troubleshooting
 tags: [troubleshooting, debugging]
-last_updated: "2026-03-25"
-description: "Section index for ai-toolkit troubleshooting. No documents are filed here yet; new ones follow the troubleshooting template."
+last_updated: "2026-08-21"
+description: "Section index for ai-toolkit troubleshooting, covering the Claude app plugin double-load collision."
 ---
 
 # Troubleshooting
 
-Problem resolution guides. Guides will be added here as they are created.
+Problem resolution guides.
+
+- [Claude App Plugin Loads Twice in Claude Code](plugin-double-load.md) -- hooks fire twice after the plugin ZIP is uploaded next to a global install.
+
+---
+
+## kb/troubleshooting/plugin-double-load.md
+
+---
+title: "Claude App Plugin Loads Twice in Claude Code"
+category: troubleshooting
+service: ai-toolkit
+tags: [plugin, claude-app, hooks, duplication, doctor]
+created: "2026-08-21"
+last_updated: "2026-08-21"
+description: "Every toolkit hook fires twice and skills and agents load twice after the Claude app plugin ZIP is uploaded on a machine that already has the global install. Cause: the app registers the plugin under ~/.claude/plugins, which Claude Code also reads."
+---
+
+# Claude App Plugin Loads Twice in Claude Code
+
+## Symptom
+
+After uploading `ai-toolkit-claude-app.zip` through `Customize > Plugins`, Claude
+Code sessions get slower and every hook side effect appears twice: duplicate rows
+in `governance.log`, duplicate session state writes, two Stop gates per turn.
+`ai-toolkit doctor` reports a healthy install because it only inspected
+`~/.claude` and `app/plugins`.
+
+## Cause
+
+The Claude app writes uploaded plugins into
+`~/.claude/plugins/marketplaces/local-desktop-app-uploads/` and sets
+`enabledPlugins` in `~/.claude/settings.json`. Both paths belong to Claude Code
+as well, so Claude Code loads the plugin on top of the global install. The
+bundle carries the same catalog as `~/.claude`, and plugin hooks merge with user
+hooks without deduplication.
+
+Confirmed in a Claude Code debug log (`claude --debug -p ...`, then read
+`~/.claude/debug/latest`):
+
+```
+Loaded 111 unique skills (... user: 111 ...)
+Total plugin skills loaded: 111 (0 duplicate/user-owned entries skipped)
+Total plugin agents loaded: 44
+Read manifest hooks for plugin ai-toolkit (enabled=true): ./claude-app/hooks/hooks.json
+```
+
+The `skills` manifest field adds to the default `skills/` directory instead of
+replacing it, so the plugin contributes its 109 catalog skills plus the 2
+app-only rule skills.
+
+## Diagnosis
+
+```bash
+ai-toolkit doctor
+```
+
+Check 11 reports the collision:
+
+```
+## 11. Plugin Double-Load
+  WARN: ai-toolkit@local-desktop-app-uploads is active next to the global install: 28 toolkit hooks fire twice per event and skills/agents load twice (run: ai-toolkit doctor --fix)
+```
+
+To see the duplication directly, count hook invocations per source in a fresh
+session log:
+
+```bash
+grep -oE "[^\"' ]*hooks/[a-z0-9._-]+\.sh" ~/.claude/debug/latest | sort | uniq -c
+```
+
+## Fix
+
+```bash
+ai-toolkit doctor --fix
+```
+
+That sets the plugin to `false` in `enabledPlugins` and leaves the global
+install authoritative. Claude Code then logs
+`enabled=false; will NOT register, plugin is disabled`, and plugin skills and
+agents drop to 0.
+
+The global install is the richer surface for Claude Code: it delivers rules as
+real files under `~/.claude/rules/`, which are always in context, while the
+plugin exposes them as an `ai-toolkit-rules` skill the model has to load. The
+plugin also has no `session-context.sh` hook.
+
+Keep the plugin enabled only when Claude Code has no global install, for example
+a machine that runs the Claude app alone. In that case the plugin is the single
+source and check 11 stays quiet.
+
+## Verification
+
+```bash
+claude --debug -p "ok"
+grep -E "Total plugin (skills|agents) loaded|enabled=" ~/.claude/debug/latest
+```
+
+Expect `Total plugin skills loaded: 0`, `Total plugin agents loaded: 0`, and the
+`plugin is disabled` line.
+
+## Related
+
+- `kb/reference/global-install-model.md`
+- `kb/procedures/maintenance-sop.md`
 
 ---
 

package/llms.txt

@@ -73,3 +73,4 @@
 - [Unique Features & Differentiators](kb/reference/unique-features.md)
 - [Windows Support](kb/reference/windows-support.md)
 - [Troubleshooting](kb/troubleshooting/README.md)
+- [Claude App Plugin Loads Twice in Claude Code](kb/troubleshooting/plugin-double-load.md)

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.26.0",
+  "version": "4.27.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.26.0",
+  "version": "4.27.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

@@ -15,6 +15,8 @@ Checks:
   7. Benchmark freshness
   8. Stale rules
   9. URL hook sources
+  10. Language rules drift (project-local)
+  11. Plugin double-load (Claude app plugin vs global install)
 
 Exit codes:
   0  all checks pass
@@ -44,6 +46,7 @@ HOOKS_DIR = _HOOKS_DIR
 RULES_DIR = _RULES_DIR
 EXTERNAL_HOOKS_DIR = _EXTERNAL_HOOKS_DIR
 BENCHMARK_DASHBOARD = toolkit_dir / "benchmarks" / "ecosystem-dashboard.json"
+PLUGIN_REGISTRY = CLAUDE_DIR / "plugins" / "installed_plugins.json"
 
 VALID_EVENTS = frozenset({
     "SessionStart", "Notification", "PreToolUse", "PostToolUse", "Stop",
@@ -668,6 +671,84 @@ def check_language_drift(dr: DiagResult) -> None:
         dr.warn(f"{lang} detected but {skill} not injected — run: ai-toolkit install --local --lang {lang}")
 
 
+# ---------------------------------------------------------------------------
+# Check 11: Plugin Double-Load
+# ---------------------------------------------------------------------------
+
+def _registered_toolkit_plugins(registry: dict) -> list[str]:
+    """Return ai-toolkit plugin keys from the Claude Code plugin registry."""
+    plugins = registry.get("plugins", {})
+    if not isinstance(plugins, dict):
+        return []
+    return [key for key in plugins if str(key).split("@", 1)[0] == "ai-toolkit"]
+
+
+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.
+
+    Uploading the ``claude-app export`` ZIP from the Claude app registers it under
+    ``~/.claude/plugins``, which Claude Code reads as well. The plugin carries the
+    same skills, agents, and hooks as the global install, and Claude Code merges
+    plugin hooks with user hooks without deduplication, so every toolkit hook runs
+    twice per event.
+    """
+    print()
+    print("## 11. Plugin Double-Load")
+
+    if not PLUGIN_REGISTRY.is_file():
+        dr.skip("no Claude Code plugin registry")
+        return
+    try:
+        registry = json.loads(PLUGIN_REGISTRY.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        dr.warn(f"{PLUGIN_REGISTRY} is not valid JSON")
+        return
+
+    keys = _registered_toolkit_plugins(registry)
+    if not keys:
+        dr.ok("no ai-toolkit plugin registered in Claude Code")
+        return
+
+    settings_json = CLAUDE_DIR / "settings.json"
+    try:
+        settings = json.loads(settings_json.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        settings = {}
+    enabled = settings.get("enabledPlugins", {})
+    if not isinstance(enabled, dict):
+        enabled = {}
+
+    active = [key for key in keys if enabled.get(key, True)]
+    if not active:
+        dr.ok("ai-toolkit plugin registered but disabled for Claude Code")
+        return
+
+    hook_count, _ = _installed_toolkit_hook_count(settings)
+    if hook_count == 0:
+        dr.ok("ai-toolkit plugin active without global hooks (single source)")
+        return
+
+    for key in active:
+        dr.warn(
+            f"{key} is active next to the global install: {hook_count} toolkit hooks "
+            "fire twice per event and skills/agents load twice "
+            "(run: ai-toolkit doctor --fix)"
+        )
+
+    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")
+    except OSError as exc:
+        dr.fail(f"could not disable plugin in settings.json: {exc}")
+        return
+    for key in active:
+        dr.fixed(f"disabled {key} for Claude Code (global install stays authoritative)")
+
+
 # ---------------------------------------------------------------------------
 # Main
 # ---------------------------------------------------------------------------
@@ -691,6 +772,7 @@ def main() -> None:
     check_stale_rules(dr, fix_mode)
     check_url_hooks(dr, fix_mode)
     check_language_drift(dr)
+    check_plugin_double_load(dr, fix_mode)
 
     # Summary
     print("========================")