@softspark/ai-toolkit 1.3.11 → 1.3.13

package/CHANGELOG.md

@@ -7,6 +7,27 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v1.3.13 — CLI --version flag (2026-04-08)
+
+### Added
+- **`--version` / `-v` / `version` CLI flag** — prints clean semver string and exits 0 (previously fell through to "Unknown command" with exit 1).
+- **3 new CLI tests** for `--version`, `-v`, and `version` subcommand.
+
+---
+
+## v1.3.12 — Cross-platform notifications + version check fix (2026-04-08)
+
+### Fixed
+- **Version check**: `ai-toolkit status` and session-start hook now read installed version from `state.json` instead of `package.json`, fixing false "up to date" when npm package was upgraded but `ai-toolkit update` not yet run.
+- **Version check**: `status` forces a fresh npm check (no 24h cache) so user always sees real state.
+- **Session-start hook**: `TOOLKIT_DIR` resolved via `npm root -g` instead of broken `../../` relative path from `~/.ai-toolkit/hooks/`.
+
+### Changed
+- **Notification hook**: replaced inline macOS-only `osascript` with cross-platform `notify-waiting.sh` script (macOS/Linux/Windows WSL).
+- **Update notification**: session-start hook now shows desktop notification (macOS/Linux/Windows) when a new version is available.
+
+---
+
 ## v1.3.11 — Proactive Context Checkpointing + Augment CLI (2026-04-08)
 
 ### Added

package/README.md

@@ -6,7 +6,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-90-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-374%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-377%20passing-success)](tests/)
 
 ---
 
@@ -181,7 +181,8 @@ ai-toolkit/
 │   │   ├── governance-capture.sh # Security-sensitive op logging
 │   │   ├── commit-quality.sh     # Conventional commit advisory
 │   │   ├── session-context.sh    # Environment snapshot on start
-│   │   └── track-usage.sh        # Skill invocation tracking
+│   │   ├── track-usage.sh        # Skill invocation tracking
+│   │   └── notify-waiting.sh     # Cross-platform "Claude waiting" notification
 │   ├── hooks.json       # Hook definitions (merged into settings.json)
 │   ├── plugins/         # Experimental plugin packs (opt-in, not part of default install)
 │   ├── output-styles/   # System prompt output style overrides

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

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "1.3.11",
+  "version": "1.3.12",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/hooks/notify-waiting.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# notify-waiting.sh — Cross-platform desktop notification when Claude is waiting.
+#
+# Fires on: Notification
+# Non-blocking (always exits 0).
+
+MSG="Claude Code needs your attention"
+TITLE="Claude Code"
+
+if command -v osascript >/dev/null 2>&1; then
+    osascript -e "display notification \"$MSG\" with title \"$TITLE\"" 2>/dev/null &
+elif command -v notify-send >/dev/null 2>&1; then
+    notify-send "$TITLE" "$MSG" 2>/dev/null &
+elif command -v powershell.exe >/dev/null 2>&1; then
+    powershell.exe -Command "[void](New-Object -ComObject WScript.Shell).Popup('$MSG',5,'$TITLE',64)" 2>/dev/null &
+fi
+
+exit 0

package/app/hooks/session-start.sh

@@ -9,10 +9,19 @@ echo "MANDATORY: Before answering ANY technical question, apply ALL rules from y
 echo "REMINDER: When writing features or fixing bugs, ensure tests cover the changes. When modifying API, config, or setup, update relevant documentation. Propose these steps to the user — do not silently skip them."
 
 # 2. Check for updates (cached, max once per 24h, non-blocking)
-TOOLKIT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+TOOLKIT_DIR="$(npm root -g 2>/dev/null)/@softspark/ai-toolkit"
+[ ! -d "$TOOLKIT_DIR" ] && TOOLKIT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
 VERSION_MSG=$(python3 "$TOOLKIT_DIR/scripts/version_check.py" 2>/dev/null)
 if [ -n "$VERSION_MSG" ]; then
     echo "$VERSION_MSG"
+    # Desktop notification so user sees update before typing
+    if command -v osascript >/dev/null 2>&1; then
+        osascript -e "display notification \"$VERSION_MSG\" with title \"ai-toolkit\"" 2>/dev/null &
+    elif command -v notify-send >/dev/null 2>&1; then
+        notify-send "ai-toolkit" "$VERSION_MSG" 2>/dev/null &
+    elif command -v powershell.exe >/dev/null 2>&1; then
+        powershell.exe -Command "[void](New-Object -ComObject WScript.Shell).Popup('$VERSION_MSG',5,'ai-toolkit',64)" 2>/dev/null &
+    fi
 fi
 
 # 3. Load session context (if available)

package/app/hooks.json

@@ -39,7 +39,7 @@
                 "hooks": [
                     {
                         "type": "command",
-                        "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
+                        "command": "bash ~/.ai-toolkit/hooks/notify-waiting.sh"
                     }
                 ]
             }

package/bin/ai-toolkit.js

@@ -440,6 +440,8 @@ const [,, command, ...args] = process.argv;
 
 if (!command || command === 'help' || command === '--help' || command === '-h') {
   showHelp();
+} else if (command === '--version' || command === '-v' || command === 'version') {
+  console.log(require('../package.json').version);
 } else if (SPECIAL_HANDLERS[command]) {
   SPECIAL_HANDLERS[command](args);
 } else if (SCRIPT_COMMANDS[command]) {

package/kb/reference/hooks-catalog.md

@@ -44,15 +44,19 @@ ai-toolkit update     # re-copies scripts, re-merges (idempotent)
 3. Loads session context from `.claude/session-context.md` (if exists)
 4. Loads active instincts from `.claude/instincts/*.md` (if any)
 
-### Notification — inline
+### Notification — `notify-waiting.sh`
 
 | Field | Value |
 |-------|-------|
 | Event | `Notification` |
 | Matcher | *(all)* |
+| Script | `~/.ai-toolkit/hooks/notify-waiting.sh` |
 | Fires | Claude Code waiting for user input |
 
-**Action:** macOS desktop notification via `osascript`.
+**Action:** Cross-platform desktop notification ("Claude Code needs your attention"):
+- macOS: `osascript` (native)
+- Linux: `notify-send` (libnotify)
+- Windows/WSL: `powershell.exe` WScript popup (5s auto-close)
 
 ### PreToolUse (Bash) — `guard-destructive.sh`
 

package/llms-full.txt

@@ -2783,15 +2783,19 @@ ai-toolkit update     # re-copies scripts, re-merges (idempotent)
 3. Loads session context from `.claude/session-context.md` (if exists)
 4. Loads active instincts from `.claude/instincts/*.md` (if any)
 
-### Notification — inline
+### Notification — `notify-waiting.sh`
 
 | Field | Value |
 |-------|-------|
 | Event | `Notification` |
 | Matcher | *(all)* |
+| Script | `~/.ai-toolkit/hooks/notify-waiting.sh` |
 | Fires | Claude Code waiting for user input |
 
-**Action:** macOS desktop notification via `osascript`.
+**Action:** Cross-platform desktop notification ("Claude Code needs your attention"):
+- macOS: `osascript` (native)
+- Linux: `notify-send` (libnotify)
+- Windows/WSL: `powershell.exe` WScript popup (5s auto-close)
 
 ### PreToolUse (Bash) — `guard-destructive.sh`
 

package/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "1.3.11",
+  "version": "1.3.13",
   "description": "Professional-grade AI coding toolkit: 90 skills, 44 agents, multi-platform support (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment), machine-enforced safety constitution, persona presets, skill security auditor, expanded lifecycle hooks, 11 plugin packs, and benchmark tooling.",
   "keywords": [
     "claude",

package/scripts/install_steps/install_state.py

@@ -126,7 +126,7 @@ def print_status() -> None:
         import sys as _sys
         _sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
         from version_check import check
-        result = check()
+        result = check(force=True)
         if result["update_available"]:
             print()
             print(f"  Update available: {result['installed']} -> {result['latest']}")

package/scripts/version_check.py

@@ -27,7 +27,23 @@ PACKAGE_NAME = "@softspark/ai-toolkit"
 
 
 def _get_installed_version() -> str:
-    """Read version from the toolkit's own package.json."""
+    """Read version from state.json (what user actually has configured).
+
+    Falls back to package.json if state.json is missing (e.g. fresh install).
+    state.json is the source of truth because it reflects what was last
+    installed/updated, while package.json may be newer if the npm package
+    was upgraded but `ai-toolkit update` was not run yet.
+    """
+    state_file = Path.home() / ".ai-toolkit" / "state.json"
+    if state_file.is_file():
+        try:
+            with open(state_file, encoding="utf-8") as f:
+                version = json.load(f).get("installed_version")
+                if version:
+                    return version
+        except (json.JSONDecodeError, OSError):
+            pass
+    # Fallback: package.json
     pkg = Path(__file__).resolve().parent.parent / "package.json"
     if pkg.is_file():
         with open(pkg, encoding="utf-8") as f: