@softspark/ai-toolkit 4.2.4 → 4.3.0

package/CHANGELOG.md

@@ -7,6 +7,73 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.3.0 - inject-mcp extension API (2026-05-12)
+
+Minor release. Closes the asymmetry between `inject-rule` / `inject-hook` and MCP servers by adding `inject-mcp` and `remove-mcp` as first-class members of the extension API. External tools (rag-mcp, jira-mcp, custom integrations) can now register their MCP templates the same way they register rules and hooks -- from a local file or HTTPS URL, with full editor propagation and auto-refresh on `ai-toolkit update`.
+
+### Added
+
+- **`ai-toolkit inject-mcp <file|url> [--name <name>] [--force]`** - Inject an external MCP server template into `~/.mcp.json` (toolkit source-of-truth) and propagate it to every editor with a `global_path` (Claude, Cursor, Codex, Gemini, Windsurf, Cline, Augment, Copilot). Servers in `~/.mcp.json` are tagged with `_source` for idempotent re-injection; native editor configs receive the same servers without `_source`.
+- **`ai-toolkit remove-mcp <name>`** - Strip all servers tagged with the given source from `~/.mcp.json` and every editor config, unregister URL sources, and remove cached template files.
+- **`--name <name>` flag** - Override the auto-derived source name for both local files and URLs. Required when filename stem is generic (e.g., `mcp-template.json` → `--name rag-mcp`).
+- **`--force` flag** - Overwrite servers tagged with a different `_source`. Without `--force`, collisions exit with code 3. Entries tagged `"_source": "ai-toolkit"` are protected even with `--force`.
+- **URL fetch + cache + auto-refresh** - HTTPS templates are cached in `~/.softspark/ai-toolkit/mcp-templates/external/<name>.json` and registered in `sources.json` with sha256 pin. On every `ai-toolkit update`, URL-sourced templates are re-fetched and re-injected; cached version is used on fetch failure.
+- **`scripts/mcp_sources.py`** - Source registry for external MCP templates, mirroring `hook_sources.py`.
+- **`scripts/inject_mcp_cli.py`** - CLI entry point implementing both inject and remove modes.
+- **`refresh_url_mcp()` in `install_steps/markers.py`** - Update flow integration, called from `install.py` alongside `refresh_url_hooks()`.
+
+### Changed
+
+- **`paths.py`** - Added `MCP_TEMPLATES_DIR` and `EXTERNAL_MCP_DIR` constants.
+- **`bin/ai-toolkit.js`** - Registered `inject-mcp` / `remove-mcp` handlers and help text.
+- **`kb/reference/extension-api.md`** - Documented inject-mcp / remove-mcp + flags. Version bumped to 1.5.0.
+- **`kb/reference/mcp-templates.md`** - Added External Templates section pointing to inject-mcp. Version bumped to 1.2.0.
+
+### Tests
+
+- **`tests/test_inject_mcp.bats`** - 15 bats cases covering local-file inject, URL fetch via fixture, `--name` override, `--force` collision override, ai-toolkit source protection, idempotent re-inject, editor propagation to Cursor (JSON) and Codex (TOML), `_source` strip from native configs, sources.json registry, `--remove` cleanup, HTTPS-only enforcement.
+
+### Verification
+
+- 15/15 bats cases passing in `test_inject_mcp.bats`.
+- E2E smoke test: injecting an external `mcp-template.json` writes 9 files (`~/.mcp.json` + 8 editor configs) with `_source` only in source-of-truth and stripped from native configs.
+- No regressions in `test_inject_hook.bats` or `test_mcp_manager.bats`.
+
+---
+
+## v4.2.5 - Hook safety and no-RAG compatibility (2026-05-12)
+
+Patch release. Hardens Claude Code hook enforcement while keeping the toolkit safe for users who do not have RAG/MCP search providers installed.
+
+### Added
+
+- **Capability-aware search hooks** - Added shared search capability detection so search-first enforcement uses RAG/MCP when available and degrades to guidance when no provider is installed.
+- **Revert guard** - Added destructive Git restore/checkout protection that blocks unsafe rollback commands when they would discard unrelated user work.
+- **Test cohesion hook** - Added source-to-test mapping for focused Bats verification after relevant edits, with project-level override support.
+- **Hook payload adapter** - Added shared hook input/output helpers for consistent Claude, Gemini, Augment, Codex, Cursor, and Windsurf hook payload handling.
+
+### Changed
+
+- **Hook installation** - Installs hook JSON maps and runtime helper scripts needed by the new hooks into the global toolkit runtime directory.
+- **Generated editor configs** - Regenerated multi-editor hook guidance and project agent surfaces after the hook expansion.
+
+### Fixed
+
+- **No-RAG installs** - Search-first hooks no longer block users who installed the toolkit without `rag-mcp` or another supported search provider.
+- **Doctor coverage** - `ai-toolkit doctor` now verifies the new hook helper scripts and runtime hook files.
+
+### Ecosystem
+
+- Refreshed `benchmarks/ecosystem-doctor-snapshot.json` after class-A documentation drift only: upstream docs changed content hashes without heading or marker deltas.
+
+### Verification
+
+- `npm view @softspark/ai-toolkit version`: latest published version is `4.2.4`; `4.2.5` is available.
+- Local Claude test confirmed RAG-backed prompts still call `rag-mcp` when present.
+- Local Claude destructive-revert scenario was refused before data loss.
+
+---
+
 ## v4.2.4 - GitHub Actions Node 24 readiness (2026-05-12)
 
 Patch release. Removes GitHub Actions Node 20 action-runtime deprecation warnings from CI, publish, and reusable action surfaces.

package/README.md

@@ -6,15 +6,16 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-107-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1051%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1131%20passing-success)](tests/)
 
-## What's New in v4.2.4
+## What's New in v4.3.0
 
-Patch release removing Node 20 action-runtime warnings from GitHub Actions.
+Minor release. Closes the asymmetry between `inject-rule` / `inject-hook` and MCP servers -- external tools (rag-mcp, jira-mcp, custom integrations) can now register MCP templates the same way they register rules and hooks.
 
-- **CI action runtime**: `ci.yml`, `publish.yml`, and the reusable `action.yml` now use `actions/setup-node@v6`.
-- **Generated guidance**: CI templates and CI/CD skill examples now use current GitHub Actions versions.
-- **Release readiness**: the next publish run executes on the Node 24-compatible action runtime.
+- **`ai-toolkit inject-mcp <file|url>`**: register an external MCP template into `~/.mcp.json` + every editor with a `global_path` (Claude, Cursor, Codex, Gemini, Windsurf, Cline, Augment, Copilot) in one command.
+- **`ai-toolkit remove-mcp <name>`**: strip injected servers from `~/.mcp.json` and every editor config in one command.
+- **URL templates + auto-refresh**: HTTPS-sourced templates are cached and re-fetched on every `ai-toolkit update`, just like URL rules and hooks.
+- **`--name` and `--force` flags**: explicit source naming for both files and URLs, plus collision-safe overwrites that still protect `ai-toolkit` built-in entries.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -140,14 +141,14 @@ ai-toolkit/
 │   ├── agents/          # 44 agent definitions
 │   ├── skills/          # 107 skills (task / hybrid / knowledge)
 │   ├── rules/           # Auto-injected into your CLAUDE.md
-│   ├── hooks/           # Hook scripts (22 entries, 12 lifecycle events)
+│   ├── hooks/           # Hook scripts (28 entries, 14 lifecycle events)
 │   ├── plugins/         # 11 experimental plugin packs (opt-in)
 │   ├── output-styles/   # System prompt output style overrides
 │   ├── constitution.md  # 6 immutable safety articles
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (1051 tests)
+├── tests/               # Bats test suite (1131 tests)
 └── CHANGELOG.md
 ```
 
@@ -159,7 +160,7 @@ ai-toolkit/
 
 **Machine-enforced constitution** — 6-article safety constitution enforced via `PreToolUse` hooks that actually block `rm -rf`, `DROP TABLE`, and irreversible operations. Not just documentation.
 
-**22 lifecycle hooks** — Executable scripts across 12 events (SessionStart → SessionEnd). Guards, governance, quality gates, session persistence, MCP health checks. See [Hooks Catalog](kb/reference/hooks-catalog.md).
+**28 lifecycle hooks** — Executable scripts across 14 events (SessionStart → SessionEnd, plus InstructionsLoaded + ConfigChange). Guards, governance, quality gates, session persistence, MCP health checks, revert protection, test-cohesion enforcement, search-first discipline. See [Hooks Catalog](kb/reference/hooks-catalog.md).
 
 **Security scanning** — `/skill-audit` for code-level risks, `/cve-scan` for dependency CVEs. Both CI-ready with exit codes.
 

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

package/app/hooks/_hook-io.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# _hook-io.sh — shared JSON input/output helpers for multi-editor hooks.
+#
+# Source this file from hook scripts. It expects the caller to set INPUT to the
+# hook payload JSON before calling helper functions.
+
+hook_json() {
+    local filter="$1"
+    echo "${INPUT:-}" | jq -r "$filter" 2>/dev/null
+}
+
+hook_tool_name() {
+    local value
+    value=$(hook_json '.tool_name // .toolInfo.name // .tool_info.name // .tool // empty')
+    [ -n "$value" ] && [ "$value" != "null" ] && printf '%s\n' "$value"
+}
+
+hook_prompt() {
+    hook_json '.prompt // .tool_info.user_prompt // .user_prompt // .input // empty'
+}
+
+hook_command() {
+    hook_json '.tool_input.command // .tool_input.command_line // .tool_info.command // .tool_info.command_line // .command // empty'
+}
+
+hook_file_path() {
+    hook_json '
+        .tool_input.file_path //
+        .tool_input.path //
+        .tool_info.file_path //
+        .tool_info.path //
+        (.file_changes[0].path? // empty) //
+        empty
+    '
+}
+
+hook_old_content() {
+    hook_json '(.tool_input.old_string // .tool_input.old_str_1 // .tool_info.old_string // .tool_info.old_str_1 // .tool_info.edits[0].old_string // "")'
+}
+
+hook_new_content() {
+    hook_json '(.tool_input.new_string // .tool_input.new_str_1 // .tool_input.content // .tool_info.new_string // .tool_info.new_str_1 // .tool_info.content // .tool_info.edits[0].new_string // .file_changes[0].content? // "")'
+}
+
+hook_emit_context() {
+    local message="$1"
+    if [ "${AI_TOOLKIT_HOOK_FORMAT:-}" = "json" ]; then
+        jq -nc --arg msg "$message" \
+            '{"hookSpecificOutput":{"additionalContext":$msg},"suppressOutput":true}'
+    else
+        printf '%s\n' "$message"
+    fi
+}
+
+hook_emit_block() {
+    local event="$1"
+    local reason="$2"
+    if [ "${AI_TOOLKIT_HOOK_FORMAT:-}" = "json" ]; then
+        jq -nc --arg event "$event" --arg reason "$reason" \
+            '{"hookSpecificOutput":{"hookEventName":$event,"decision":"block","reason":$reason},"decision":"block","reason":$reason,"suppressOutput":false}'
+    else
+        jq -nc --arg reason "$reason" '{"decision":"block","reason":$reason}'
+    fi
+}

package/app/hooks/_locate-toolkit.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# _locate-toolkit.sh — shared toolkit-root locator for hooks needing scripts/.
+#
+# Source this file to get $TOOLKIT_DIR set to the ai-toolkit checkout root.
+# Resolution order:
+#   1. $AI_TOOLKIT_DIR env override (used by tests)
+#   2. npm global install: $(npm root -g)/@softspark/ai-toolkit
+#   3. Fallback: installed runtime at ~/.softspark/ai-toolkit
+#   4. Fallback: parent of the hook script directory (repo checkout)
+#
+# Sets:
+#   TOOLKIT_DIR — absolute path to toolkit root, or empty if not findable.
+
+_ai_toolkit_hook_dir() {
+    local src="${BASH_SOURCE[1]:-$0}"
+    (cd "$(dirname "$src")" 2>/dev/null && pwd)
+}
+
+if [ -n "${AI_TOOLKIT_DIR:-}" ] && [ -d "$AI_TOOLKIT_DIR" ]; then
+    TOOLKIT_DIR="$AI_TOOLKIT_DIR"
+else
+    TOOLKIT_DIR="$(npm root -g 2>/dev/null)/@softspark/ai-toolkit"
+    if [ ! -d "$TOOLKIT_DIR" ]; then
+        TOOLKIT_DIR="$HOME/.softspark/ai-toolkit"
+    fi
+    if [ ! -d "$TOOLKIT_DIR" ]; then
+        _hook_dir="$(_ai_toolkit_hook_dir)"
+        if [ -f "$_hook_dir/../app/hooks.json" ]; then
+            TOOLKIT_DIR="$(cd "$_hook_dir/.." 2>/dev/null && pwd)"
+        else
+            TOOLKIT_DIR="$(cd "$_hook_dir/../.." 2>/dev/null && pwd)"
+        fi
+        unset _hook_dir
+    fi
+fi
+
+[ -d "$TOOLKIT_DIR" ] || TOOLKIT_DIR=""
+unset -f _ai_toolkit_hook_dir
+export TOOLKIT_DIR

package/app/hooks/_search-capability.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# _search-capability.sh — determine whether strict search-first enforcement is safe.
+#
+# Default is conservative: do not block users unless a search provider is
+# explicitly configured or strict mode is requested.
+
+ai_toolkit_search_first_mode() {
+    printf '%s\n' "${AI_TOOLKIT_SEARCH_FIRST:-${CLAUDE_SEARCH_FIRST:-auto}}" \
+        | tr '[:upper:]' '[:lower:]'
+}
+
+ai_toolkit_has_search_provider() {
+    local mode
+    mode="$(ai_toolkit_search_first_mode)"
+    case "$mode" in
+        off|false|0|disabled|none)
+            return 1
+            ;;
+        strict|required|require|on|true|1)
+            return 0
+            ;;
+    esac
+
+    [ -n "${AI_TOOLKIT_SEARCH_PROVIDER:-}" ] && return 0
+    [ -n "${CLAUDE_SEARCH_PROVIDER:-}" ] && return 0
+
+    local candidates=(
+        "$PWD/.mcp.json"
+        "$PWD/.claude/mcp.json"
+        "$PWD/.cursor/mcp.json"
+        "$PWD/.gemini/settings.json"
+        "$HOME/.claude.json"
+        "$HOME/.claude/settings.json"
+        "$HOME/.codex/config.toml"
+        "$HOME/.gemini/settings.json"
+    )
+    local path
+    for path in "${candidates[@]}"; do
+        [ -f "$path" ] || continue
+        if grep -Eqi 'rag[-_]?mcp|smart_query|hybrid_search_kb|crag_search|multi_hop_search|websearch|web-fetch|web_fetch|web_search' "$path"; then
+            return 0
+        fi
+    done
+
+    return 1
+}

package/app/hooks/commit-quality.sh

@@ -5,7 +5,9 @@
 # Non-blocking: always exits 0 (warnings only).
 
 INPUT=$(cat)
-COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.sh"
+COMMAND=$(hook_command)
 
 if [ -z "$COMMAND" ]; then
     exit 0

package/app/hooks/config-desync-guard.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# config-desync-guard.sh — Warn when ~/.claude/settings.json drifts from
+# the ai-toolkit source manifest (app/hooks.json).
+#
+# Fires on: ConfigChange
+# Matcher: user_settings
+# Non-blocking by design: exits 0 even on drift. We never want to block a
+# user's legitimate settings edit. Output goes to stderr so Claude Code
+# surfaces it as a notice.
+# Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+#
+# Override (silence advisory): CLAUDE_SKIP_CONFIG_DESYNC=1
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+# shellcheck source=_locate-toolkit.sh
+source "$(dirname "$0")/_locate-toolkit.sh"
+
+[ "${CLAUDE_SKIP_CONFIG_DESYNC:-0}" = "1" ] && exit 0
+[ -z "$TOOLKIT_DIR" ] && exit 0
+command -v python3 >/dev/null 2>&1 || exit 0
+
+SETTINGS="$HOME/.claude/settings.json"
+SOURCE="$TOOLKIT_DIR/app/hooks.json"
+[ -f "$SETTINGS" ] || exit 0
+[ -f "$SOURCE" ] || exit 0
+
+# Compare the set of ai-toolkit-tagged commands in each file.
+DIFF=$(python3 - "$SETTINGS" "$SOURCE" <<'PY'
+import json
+import sys
+
+
+def toolkit_commands(path):
+    try:
+        data = json.load(open(path))
+    except Exception:
+        return set()
+    hooks = data.get("hooks", {}) if isinstance(data, dict) else {}
+    out = set()
+    for event, entries in hooks.items():
+        if not isinstance(entries, list):
+            continue
+        for entry in entries:
+            if not isinstance(entry, dict):
+                continue
+            tagged_top = entry.get("_source") == "ai-toolkit"
+            for hook in entry.get("hooks", []):
+                if not isinstance(hook, dict):
+                    continue
+                tagged_inner = hook.get("_source") == "ai-toolkit"
+                if not (tagged_top or tagged_inner):
+                    continue
+                cmd = hook.get("command", "")
+                out.add((event, entry.get("matcher", ""), cmd))
+    return out
+
+
+installed = toolkit_commands(sys.argv[1])
+source = toolkit_commands(sys.argv[2])
+
+missing = source - installed  # in source, not installed (toolkit got new hooks)
+extra = installed - source    # in installed, not source (stale toolkit hook)
+
+if not (missing or extra):
+    sys.exit(0)
+
+if missing:
+    print(f"  Missing from settings.json ({len(missing)}):")
+    for event, matcher, cmd in sorted(missing):
+        print(f"    - [{event}] {cmd}")
+if extra:
+    print(f"  Stale in settings.json ({len(extra)}):")
+    for event, matcher, cmd in sorted(extra):
+        print(f"    - [{event}] {cmd}")
+sys.exit(1)
+PY
+)
+
+if [ $? -ne 0 ] && [ -n "$DIFF" ]; then
+    cat >&2 <<EOF
+config-desync-guard: ai-toolkit hooks drifted from source manifest.
+
+$DIFF
+
+Fix: re-install canonical state:
+    ai-toolkit update
+or auto-repair:
+    ai-toolkit doctor --fix
+
+Silence advisory (one-off): CLAUDE_SKIP_CONFIG_DESYNC=1
+EOF
+fi
+
+exit 0

package/app/hooks/governance-capture.sh

@@ -14,7 +14,9 @@ TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 SESSION="${CLAUDE_SESSION_ID:-unknown}"
 
 INPUT=$(cat)
-TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.sh"
+TOOL_NAME=$(hook_tool_name)
 
 if [ -z "$TOOL_NAME" ]; then
     TOOL_NAME="${CLAUDE_TOOL_NAME:-unknown}"
@@ -39,7 +41,7 @@ log_event() {
 
 case "$TOOL_NAME" in
     Bash)
-        COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+        COMMAND=$(hook_command)
         [ -z "$COMMAND" ] && exit 0
 
         # Check for dangerous command patterns
@@ -64,7 +66,7 @@ case "$TOOL_NAME" in
         ;;
 
     Write|Edit|MultiEdit)
-        FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+        FILE_PATH=$(hook_file_path)
         [ -z "$FILE_PATH" ] && exit 0
 
         BASENAME=$(basename "$FILE_PATH")

package/app/hooks/guard-config.sh

@@ -5,7 +5,9 @@
 # Exit 2 = block the tool call. Stderr message goes to Claude as feedback.
 
 INPUT=$(cat)
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.sh"
+FILE_PATH=$(hook_file_path)
 
 if [ -z "$FILE_PATH" ]; then
     exit 0
@@ -30,8 +32,8 @@ case "$BASENAME" in
         BLOCKED=1 ;;
     pyproject.toml)
         # Only block if editing [tool.ruff] section — check new_string/content for ruff markers
-        CONTENT=$(echo "$INPUT" | jq -r '(.tool_input.new_string // .tool_input.content // "")' 2>/dev/null)
-        OLD=$(echo "$INPUT" | jq -r '(.tool_input.old_string // "")' 2>/dev/null)
+        CONTENT=$(hook_new_content)
+        OLD=$(hook_old_content)
         if printf '%s\n%s' "$OLD" "$CONTENT" | grep -qi '\[tool\.ruff'; then
             BLOCKED=1
         fi

package/app/hooks/guard-destructive.sh

@@ -5,7 +5,9 @@
 # Exit 2 = block the command. Stderr message goes to Claude as feedback.
 
 INPUT=$(cat)
-COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.sh"
+COMMAND=$(hook_command)
 
 if [ -z "$COMMAND" ]; then
     # Fallback: try CLAUDE_TOOL_INPUT env var

package/app/hooks/guard-path.sh

@@ -29,7 +29,14 @@ ALL_PATHS=$(echo "$INPUT" | jq -r '
         .tool_input.source,
         .tool_input.destination,
         .tool_input.command,
-        (.tool_input.paths[]? // empty)
+        .tool_input.command_line,
+        (.tool_input.paths[]? // empty),
+        .tool_info.file_path,
+        .tool_info.path,
+        .tool_info.command,
+        .tool_info.command_line,
+        (.tool_info.paths[]? // empty),
+        (.file_changes[]?.path // empty)
     ] | map(select(. != null and . != "")) | .[]
 ' 2>/dev/null)
 

package/app/hooks/instructions-audit.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# instructions-audit.sh — Log which CLAUDE.md / rules / skills loaded.
+#
+# Fires on: InstructionsLoaded
+# Matcher: all
+# Non-blocking: always exits 0.
+# Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+#
+# Provides an audit trail so we can see whether a CLAUDE.md rule actually
+# entered the agent's context (vs. silently dropped due to token budget,
+# nested include limits, or path-glob misses).
+#
+# Output: ~/.softspark/ai-toolkit/state/loaded-instructions.log
+# Schema: ISO-8601 ts \t memory_type \t load_reason \t file_path
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+
+INPUT=$(cat 2>/dev/null)
+[ -z "$INPUT" ] && exit 0
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // empty' 2>/dev/null)
+MEMORY_TYPE=$(echo "$INPUT" | jq -r '.memory_type // "unknown"' 2>/dev/null)
+LOAD_REASON=$(echo "$INPUT" | jq -r '.load_reason // "unknown"' 2>/dev/null)
+
+[ -z "$FILE_PATH" ] && exit 0
+
+LOG_DIR="$HOME/.softspark/ai-toolkit/state"
+LOG_FILE="$LOG_DIR/loaded-instructions.log"
+mkdir -p "$LOG_DIR" 2>/dev/null || exit 0
+
+TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+printf '%s\t%s\t%s\t%s\n' "$TS" "$MEMORY_TYPE" "$LOAD_REASON" "$FILE_PATH" >> "$LOG_FILE"
+
+# Cap log at 2000 lines to avoid unbounded growth.
+if [ -f "$LOG_FILE" ]; then
+    line_count=$(wc -l < "$LOG_FILE" 2>/dev/null | tr -d ' ')
+    if [ -n "$line_count" ] && [ "$line_count" -gt 2000 ]; then
+        tail -1500 "$LOG_FILE" > "${LOG_FILE}.tmp" && mv "${LOG_FILE}.tmp" "$LOG_FILE"
+    fi
+fi
+
+exit 0

package/app/hooks/post-tool-use.sh

@@ -7,31 +7,43 @@
 
 # shellcheck source=_profile-check.sh
 source "$(dirname "$0")/_profile-check.sh"
+# shellcheck source=_locate-toolkit.sh
+source "$(dirname "$0")/_locate-toolkit.sh"
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.sh"
 
 # Read from stdin (Claude Code passes JSON with .tool_name, .tool_input)
 INPUT=$(cat)
-TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"' 2>/dev/null)
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+TOOL_NAME=$(hook_tool_name)
+[ -z "$TOOL_NAME" ] && TOOL_NAME="unknown"
+FILE_PATH=$(hook_file_path)
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+
+# Append edit to session state (used by revert-guard, test-cohesion, quality-gate).
+if [ -n "$FILE_PATH" ] && [ -n "$TOOLKIT_DIR" ] && command -v python3 >/dev/null 2>&1; then
+    python3 "$TOOLKIT_DIR/scripts/session_state.py" append \
+        --tool "$TOOL_NAME" --path "$FILE_PATH" \
+        ${SESSION_ID:+--session-id "$SESSION_ID"} >/dev/null 2>&1 || true
+fi
 
 if [ -z "$FILE_PATH" ]; then
-    echo "PostToolUse: ${TOOL_NAME} completed. Consider validating lint, tests, and docs if behavior changed."
+    hook_emit_context "PostToolUse: ${TOOL_NAME} completed. Consider validating lint, tests, and docs if behavior changed."
     exit 0
 fi
 
 case "$FILE_PATH" in
     *.md|*.txt)
-        echo "PostToolUse: updated ${FILE_PATH}. If behavior or workflow changed, refresh related docs and examples."
+        hook_emit_context "PostToolUse: updated ${FILE_PATH}. If behavior or workflow changed, refresh related docs and examples."
         ;;
     *.bats|*.test.*|*.spec.*)
-        echo "PostToolUse: updated test file ${FILE_PATH}. Run the most relevant targeted test command next."
+        hook_emit_context "PostToolUse: updated test file ${FILE_PATH}. Run the most relevant targeted test command next."
         ;;
     *.json|*.yml|*.yaml|*.toml)
-        echo "PostToolUse: updated config file ${FILE_PATH}. Validate syntax and any generated artifacts affected by this change."
+        hook_emit_context "PostToolUse: updated config file ${FILE_PATH}. Validate syntax and any generated artifacts affected by this change."
         ;;
     *)
-        echo "PostToolUse: updated ${FILE_PATH}. If behavior changed, run validation, targeted tests, and update docs if needed."
+        hook_emit_context "PostToolUse: updated ${FILE_PATH}. If behavior changed, run validation, targeted tests, and update docs if needed."
         ;;
 esac
 
 exit 0
-

package/app/hooks/quality-gate.sh

@@ -7,6 +7,8 @@
 
 # shellcheck source=_profile-check.sh
 source "$(dirname "$0")/_profile-check.sh"
+# shellcheck source=_locate-toolkit.sh
+source "$(dirname "$0")/_locate-toolkit.sh"
 
 run_required() {
     local label="$1"
@@ -35,6 +37,51 @@ require_command() {
     return 1
 }
 
+cohesion_for_session_edits() {
+    # Run cohesion-mapped tests for every path touched this session.
+    # Used by projects that ship a test-cohesion-map.json (e.g. ai-toolkit).
+    [ -z "$TOOLKIT_DIR" ] && return 0
+    command -v python3 >/dev/null 2>&1 || return 0
+
+    local edits
+    edits=$(python3 "$TOOLKIT_DIR/scripts/session_state.py" list 2>/dev/null)
+    [ -z "$edits" ] && return 0
+
+    # shellcheck disable=SC2206  # word-splitting is intentional, paths have no spaces
+    local edits_array=()
+    while IFS= read -r line; do
+        [ -n "$line" ] && edits_array+=("$line")
+    done <<<"$edits"
+    [ "${#edits_array[@]}" -eq 0 ] && return 0
+
+    local commands
+    commands=$(python3 "$TOOLKIT_DIR/scripts/test_cohesion.py" resolve \
+        --changed-paths "${edits_array[@]}" --repo-root "$PWD" 2>/dev/null)
+    [ -z "$commands" ] && return 0
+
+    local tmp
+    tmp="$(mktemp "${TMPDIR:-/tmp}/ai-toolkit-cohesion.XXXXXX")"
+    while IFS= read -r cmd; do
+        [ -z "$cmd" ] && continue
+        if ! bash -c "$cmd" >"$tmp" 2>&1; then
+            echo "QUALITY GATE FAILED: cohesion tests failed." >&2
+            echo "Command: $cmd" >&2
+            tail -25 "$tmp" >&2
+            rm -f "$tmp"
+            exit 2
+        fi
+    done <<<"$commands"
+    rm -f "$tmp"
+}
+
+# Cohesion-driven branch (ai-toolkit-style repos): runs ONLY tests mapped to
+# files edited in this session via .claude/test-cohesion-map.json (or the
+# toolkit default at app/hooks/test-cohesion-map.json).
+if [ -f .claude/test-cohesion-map.json ] || \
+   { [ -f app/hooks.json ] && [ -d tests ] && [ -f scripts/validate.py ]; }; then
+    cohesion_for_session_edits
+fi
+
 if [ -f pyproject.toml ] || [ -f setup.py ]; then
     if require_command ruff; then
         run_required "ruff found errors" "head -30" ruff check .