@softspark/ai-toolkit 4.3.0 → 4.3.1

package/CHANGELOG.md

@@ -7,6 +7,28 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.3.1 - per-session search-first flag (2026-05-19)
+
+Patch release. Fixes a cross-session race condition in the search-first enforcement trio (`user-prompt-submit.sh` + `search-tracker.sh` + `stop-search-check.sh`): the single global flag file `~/.softspark/ai-toolkit/state/search-required.flag` was shared by every parallel Claude Code window, so a Stop in session B could consume session A's flag (or vice versa), blocking unrelated turns with someone else's prompt. Also unblocks `bats 1.13` regression in the test-cohesion runner default.
+
+### Fixed
+
+- **Search-first flag is now per-session** - `user-prompt-submit.sh`, `search-tracker.sh`, and `stop-search-check.sh` key the flag by `session_id` from the hook stdin payload (`search-required-<session_id>.flag`), falling back to `transcript_path` basename, then `default`. Parallel sessions no longer interfere with each other. Each Stop check reads only its own session's flag.
+- **`bats 1.13` regression in test-cohesion runner** - `scripts/test_cohesion.py` no longer passes `--no-parallelize-within-files` (now requires `--jobs 2` in bats 1.13). Default sequential mode is used, which is what the hook expected anyway.
+
+### Added
+
+- **`hook_session_id()` helper in `_hook-io.sh`** - Resolves and sanitizes the per-session key for any hook that needs to scope state to a single Claude Code window.
+- **`session-start.sh` GC** - Stale per-session search-required flags older than 60 minutes are deleted on every `SessionStart`, so crashed sessions do not leave residue.
+- **Two new bats tests** in `tests/test_search_first_flow.bats` verifying per-session isolation and that `search-tracker` only clears its own session's flag.
+
+### Changed
+
+- **`kb/reference/hooks-catalog.md`** - Documents the new per-session flag layout, GC behavior, and isolation guarantee.
+- **`README.md`** - Test count badge 1131 → 1133.
+
+---
+
 ## 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`.

package/README.md

@@ -6,16 +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-1131%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1133%20passing-success)](tests/)
 
-## What's New in v4.3.0
+## What's New in v4.3.1
 
-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.
+Patch release. Fixes a cross-session race in the search-first enforcement trio: the single global `search-required.flag` was shared by every parallel Claude Code window, so a Stop in one session could block another with someone else's prompt. Also unblocks the `bats 1.13` regression in the test-cohesion runner.
 
-- **`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.
+- **Per-session search-first flag**: `user-prompt-submit.sh`, `search-tracker.sh`, and `stop-search-check.sh` now key the flag by `session_id` (`search-required-<session_id>.flag`), so parallel Claude Code windows no longer interfere with each other.
+- **Stale-flag GC**: `session-start.sh` deletes per-session flags older than 60 minutes, so crashed sessions leave no residue.
+- **`bats 1.13` compatibility**: `scripts/test_cohesion.py` no longer passes `--no-parallelize-within-files` (it now requires `--jobs 2` in bats 1.13 and was redundant in sequential mode anyway).
+- **Two new isolation tests**: `tests/test_search_first_flow.bats` verifies per-session flag scoping for both Stop and PostToolUse paths.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -148,7 +148,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (1131 tests)
+├── tests/               # Bats test suite (1133 tests)
 └── CHANGELOG.md
 ```
 

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

package/app/hooks/_hook-io.sh

@@ -19,6 +19,20 @@ hook_prompt() {
     hook_json '.prompt // .tool_info.user_prompt // .user_prompt // .input // empty'
 }
 
+hook_session_id() {
+    local sid
+    sid=$(hook_json '.session_id // empty')
+    if [ -z "$sid" ] || [ "$sid" = "null" ]; then
+        local tp
+        tp=$(hook_json '.transcript_path // empty')
+        if [ -n "$tp" ] && [ "$tp" != "null" ]; then
+            sid=$(basename "$tp" .jsonl)
+        fi
+    fi
+    [ -z "$sid" ] && sid="default"
+    printf '%s' "$sid" | LC_ALL=C tr -c 'a-zA-Z0-9_-' '_'
+}
+
 hook_command() {
     hook_json '.tool_input.command // .tool_input.command_line // .tool_info.command // .tool_info.command_line // .command // empty'
 }

package/app/hooks/commit-quality.sh

@@ -4,6 +4,7 @@
 # Fires on: PreToolUse (Bash)
 # Non-blocking: always exits 0 (warnings only).
 
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 # shellcheck source=_hook-io.sh
 source "$(dirname "$0")/_hook-io.sh"

package/app/hooks/governance-capture.sh

@@ -13,6 +13,7 @@ LOG_FILE="$LOG_DIR/governance.log"
 TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 SESSION="${CLAUDE_SESSION_ID:-unknown}"
 
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 # shellcheck source=_hook-io.sh
 source "$(dirname "$0")/_hook-io.sh"

package/app/hooks/guard-config.sh

@@ -4,6 +4,7 @@
 # Fires on: PreToolUse (Edit|Write|MultiEdit)
 # Exit 2 = block the tool call. Stderr message goes to Claude as feedback.
 
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 # shellcheck source=_hook-io.sh
 source "$(dirname "$0")/_hook-io.sh"

package/app/hooks/guard-destructive.sh

@@ -4,6 +4,7 @@
 # Fires on: PreToolUse (Bash)
 # Exit 2 = block the command. Stderr message goes to Claude as feedback.
 
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 # shellcheck source=_hook-io.sh
 source "$(dirname "$0")/_hook-io.sh"

package/app/hooks/revert-guard.sh

@@ -22,6 +22,7 @@ source "$(dirname "$0")/_locate-toolkit.sh"
 # shellcheck source=_hook-io.sh
 source "$(dirname "$0")/_hook-io.sh"
 
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 COMMAND=$(hook_command)
 

package/app/hooks/search-tracker.sh

@@ -12,7 +12,11 @@
 
 # shellcheck source=_profile-check.sh
 source "$(dirname "$0")/_profile-check.sh"
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.sh"
 
-FLAG="$HOME/.softspark/ai-toolkit/state/search-required.flag"
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
+INPUT=$(cat 2>/dev/null || true)
+FLAG="$HOME/.softspark/ai-toolkit/state/search-required-$(hook_session_id).flag"
 rm -f "$FLAG" 2>/dev/null
 exit 0

package/app/hooks/session-start.sh

@@ -22,6 +22,10 @@ if [ -n "$TOOLKIT_DIR" ] && command -v python3 >/dev/null 2>&1; then
         ${SESSION_ID_INPUT:+--session-id "$SESSION_ID_INPUT"} >/dev/null 2>&1 || true
 fi
 
+# 1b. GC stale per-session search-required flags (older than 60 min)
+find "$HOME/.softspark/ai-toolkit/state" -maxdepth 1 -name 'search-required-*.flag' \
+    -type f -mmin +60 -delete 2>/dev/null || true
+
 # 2. Check for updates (cached, max once per 24h, non-blocking)
 VERSION_MSG=$(python3 "$TOOLKIT_DIR/scripts/version_check.py" 2>/dev/null)
 if [ -n "$VERSION_MSG" ]; then

package/app/hooks/stop-search-check.sh

@@ -21,7 +21,9 @@ source "$(dirname "$0")/_search-capability.sh"
 
 [ "${CLAUDE_SKIP_SEARCH_FIRST:-0}" = "1" ] && exit 0
 
-FLAG="$HOME/.softspark/ai-toolkit/state/search-required.flag"
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
+INPUT=$(cat 2>/dev/null || true)
+FLAG="$HOME/.softspark/ai-toolkit/state/search-required-$(hook_session_id).flag"
 [ -f "$FLAG" ] || exit 0
 
 if ! ai_toolkit_has_search_provider; then

package/app/hooks/test-cohesion.sh

@@ -32,6 +32,7 @@ source "$(dirname "$0")/_hook-io.sh"
 [ "${CLAUDE_HOOK_BOOTSTRAP:-0}" = "1" ] && exit 0
 [ "${CLAUDE_SKIP_COHESION:-0}" = "1" ] && exit 0
 
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 FILE_PATH=$(hook_file_path)
 

package/app/hooks/track-usage.sh

@@ -10,6 +10,7 @@
 STATS_FILE="${HOME}/.softspark/ai-toolkit/stats.json"
 
 # Read prompt from stdin (Claude Code passes JSON with .prompt field)
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 # shellcheck source=_hook-io.sh
 source "$(dirname "$0")/_hook-io.sh"

package/app/hooks/user-prompt-submit.sh

@@ -13,6 +13,7 @@ source "$(dirname "$0")/_hook-io.sh"
 source "$(dirname "$0")/_search-capability.sh"
 
 # Read prompt from stdin (Claude Code passes JSON with .prompt field)
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 PROMPT_TEXT=$(hook_prompt)
 LOWERED="$(printf '%s' "$PROMPT_TEXT" | tr '[:upper:]' '[:lower:]')"
@@ -22,7 +23,7 @@ LOWERED="$(printf '%s' "$PROMPT_TEXT" | tr '[:upper:]' '[:lower:]')"
 # Cleared by search-tracker.sh after smart_query / hybrid_search_kb / web runs.
 PROMPT_LEN=${#PROMPT_TEXT}
 STATE_DIR="$HOME/.softspark/ai-toolkit/state"
-FLAG="$STATE_DIR/search-required.flag"
+FLAG="$STATE_DIR/search-required-$(hook_session_id).flag"
 mkdir -p "$STATE_DIR" 2>/dev/null
 if [ "$PROMPT_LEN" -gt 30 ] && \
    [ "${CLAUDE_SKIP_SEARCH_FIRST:-0}" != "1" ] && \

package/kb/reference/hooks-catalog.md

@@ -381,7 +381,7 @@ First-match-wins per file. Built-in runners: `bats`, `pytest`, `vitest`, `jest`.
 | Script | `~/.softspark/ai-toolkit/hooks/search-tracker.sh` |
 | Fires | After any search-style tool call |
 
-**Action:** Clears `~/.softspark/ai-toolkit/state/search-required.flag`. Pairs with `user-prompt-submit.sh` (sets flag on long technical prompts only when a search provider is detected or strict mode is enabled) and `stop-search-check.sh` (blocks Stop if flag still set). Together they enforce the global CLAUDE.md GOLDEN RULE without breaking offline/no-RAG installs.
+**Action:** Clears `~/.softspark/ai-toolkit/state/search-required-<session_id>.flag` (per-session, keyed by `session_id` from the hook stdin payload, falling back to `transcript_path` basename, then `default`). Pairs with `user-prompt-submit.sh` (sets the flag on long technical prompts only when a search provider is detected or strict mode is enabled) and `stop-search-check.sh` (blocks Stop if the calling session's flag is still set). Together they enforce the global CLAUDE.md GOLDEN RULE without breaking offline/no-RAG installs and without cross-session interference when multiple Claude Code windows run in parallel.
 
 Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -394,7 +394,7 @@ Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/stop-search-check.sh` |
 | Fires | When Claude finishes a response |
 
-**Action:** If `search-required.flag` is still present (no search tool ran during this turn) and a search provider is still detectable, emits `{"decision":"block","reason":"..."}` to continue the conversation with a search-first reminder. If no RAG/Web provider is detected, it clears the stale flag and exits 0, so offline/no-MCP users are not blocked.
+**Action:** If `search-required-<session_id>.flag` for the calling session is still present (no search tool ran during this turn) and a search provider is still detectable, emits `{"decision":"block","reason":"..."}` to continue the conversation with a search-first reminder. If no RAG/Web provider is detected, it clears the stale flag and exits 0, so offline/no-MCP users are not blocked. Flags are scoped by `session_id` from the hook stdin payload so a Stop in session B never consumes session A's flag (and vice versa). Stale per-session flags older than 60 minutes are GC'd on the next `SessionStart`.
 
 **Overrides:** `CLAUDE_SKIP_SEARCH_FIRST=1`, `AI_TOOLKIT_SEARCH_FIRST=off`, or `AI_TOOLKIT_SEARCH_FIRST=strict` to force enforcement. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -456,7 +456,7 @@ Set in `.claude/settings.local.json`:
 ├── rules/          # Registered rules (add-rule.sh)
 ├── state/          # Per-session runtime state (NEW)
 │   ├── session-edits.json         # Append-only edit log per session
-│   ├── search-required.flag       # Set by user-prompt-submit, cleared by search-tracker
+│   ├── search-required-<sid>.flag # Per-session: set by user-prompt-submit, cleared by search-tracker/stop-search-check, GC'd at SessionStart (>60min)
 │   ├── loaded-instructions.log    # Audit trail of which rules entered context
 │   └── test-cohesion-last.log     # Last cohesion test command output
 └── hooks/          # Hook scripts (copied on install)

package/llms-full.txt

@@ -8186,11 +8186,11 @@ Run `ai-toolkit update --local` to re-resolve and update the lock file.
 title: "Extension API Reference"
 category: reference
 service: ai-toolkit
-tags: [extension-api, inject-rule, inject-hook, mcp-templates, integration, editors]
-version: "1.4.0"
+tags: [extension-api, inject-rule, inject-hook, inject-mcp, mcp-templates, integration, editors]
+version: "1.5.0"
 created: "2026-04-07"
-last_updated: "2026-04-15"
-description: "Reference for ai-toolkit's extension API: inject-rule, inject-hook, remove-rule, remove-hook, and editor-aware MCP template management."
+last_updated: "2026-05-12"
+description: "Reference for ai-toolkit's extension API: inject-rule, inject-hook, inject-mcp, remove-* variants, and editor-aware MCP template management."
 ---
 
 # Extension API Reference
@@ -8209,8 +8209,10 @@ This design is intentional: ai-toolkit is a generic toolkit. Consumers (MCP serv
 | `remove-rule <name>` | `~/.claude/CLAUDE.md` | Strip markers by block name | Yes |
 | `inject-hook <file.json\|url> [name]` | `~/.claude/settings.json` | JSON `_source` tag per entry, URL cached + registered | Yes |
 | `remove-hook <name>` | `~/.claude/settings.json` | Strip all entries with matching `_source`, unregister URL source | Yes |
+| `inject-mcp <file.json\|url> [name] [--force]` | `~/.mcp.json` + every editor with `global_path` | JSON `_source` tag per server, URL cached + registered, full editor propagation | Yes |
+| `remove-mcp <name>` | `~/.mcp.json` + every editor with `global_path` | Strip all servers with matching `_source`, clean editor configs, unregister URL | Yes |
 | `add-rule <file.md\|url>` | `~/.softspark/ai-toolkit/rules/` | File copy + re-inject all rules on next `update` | Yes |
-| `mcp add <name...>` | `.mcp.json` | Merge `mcpServers` block from template | Yes |
+| `mcp add <name...>` | `.mcp.json` | Merge `mcpServers` block from built-in template | Yes |
 | `mcp install --editor <name...>` | Native editor MCP config | Render canonical template into editor format | Yes |
 
 ## inject-rule
@@ -8299,6 +8301,67 @@ npx @softspark/ai-toolkit remove-hook my-tool-hooks
 
 The argument is the source name (file stem used during `inject-hook`). If no entries with that source are present, the command exits 0 silently.
 
+## inject-mcp
+
+Injects an external MCP server template into `~/.mcp.json` (toolkit source-of-truth) and propagates it to every editor that exposes a `global_path` in `EDITOR_SPECS`. Symmetric with `inject-hook` -- accepts both local file paths and HTTPS URLs, with cache + auto-refresh on `ai-toolkit update`.
+
+```bash
+# From local file
+npx @softspark/ai-toolkit inject-mcp ./rag-mcp-template.json
+
+# From URL (cached locally, auto-refreshed on update)
+npx @softspark/ai-toolkit inject-mcp https://example.com/rag-mcp-template.json
+
+# With explicit source name (preferred when filename stem is generic)
+npx @softspark/ai-toolkit inject-mcp ./mcp/mcp-template.json --name rag-mcp
+
+# With explicit target dir
+npx @softspark/ai-toolkit inject-mcp ./template.json /custom/target --name my-rag
+
+# Force overwrite of servers with a different _source (collision resolution)
+npx @softspark/ai-toolkit inject-mcp ./conflict.json --force
+```
+
+**Flags:** `--name <name>` overrides the auto-derived source name (works for both local files and URLs). `--force` overwrites servers tagged with a different `_source`. Positional `template-name` is supported only for URL sources (legacy positional grammar inherited from `inject-hook`); for local files use `--name`.
+
+**Implementation:** `scripts/inject_mcp_cli.py`, `scripts/mcp_sources.py`, `scripts/url_fetch.py`.
+
+**Input format:** Same as built-in templates in `app/mcp-templates/`:
+```json
+{
+  "name": "rag-mcp",
+  "description": "Multi-tenant RAG over knowledge bases",
+  "mcpServers": {
+    "rag-mcp": {
+      "type": "http",
+      "url": "http://localhost:8081/mcp/sse?secret_key=${RAG_MCP_SECRET_KEY}"
+    }
+  }
+}
+```
+
+**Source name derivation:** `rag-mcp-template.json` → `"rag-mcp-template"`. For URLs: `https://example.com/rag-mcp-template.json` → `"rag-mcp-template"`. Every server in the `mcpServers` block is tagged with `"_source": "<source-name>"` inside `~/.mcp.json` only; native editor configs receive the same servers **without** the `_source` field (some clients reject unknown keys).
+
+**URL support:** When an HTTPS URL is provided, the JSON is fetched, validated, cached in `~/.softspark/ai-toolkit/mcp-templates/external/<name>.json`, and registered in `sources.json`. On every `ai-toolkit update`, URL-sourced templates are re-fetched and re-injected automatically. If the fetch fails during update, the cached version is used.
+
+**Editor propagation:** Every editor with a `global_path` in `EDITOR_SPECS` is updated -- Claude (`~/.claude.json`), Cursor (`~/.cursor/mcp.json`), GitHub Copilot (`~/.copilot/mcp-config.json`), Gemini CLI (`~/.gemini/settings.json`), Windsurf (`~/.codeium/windsurf/mcp_config.json`), Cline (`~/.cline/data/settings/cline_mcp_settings.json`), Augment (`~/.augment/settings.json`), Codex CLI (`~/.codex/config.toml`). Per-editor failures are non-fatal -- the command reports a warning and continues.
+
+**Idempotency:** Re-running with the same source overwrites entries for that source cleanly -- no duplicates accumulate.
+
+**Collisions:** If a server name in `~/.mcp.json` already exists under a *different* `_source` tag, the command exits with code 3 unless `--force` is passed. Entries tagged `"_source": "ai-toolkit"` are protected even with `--force` -- the built-in template namespace cannot be hijacked.
+
+**Safety:** Only HTTPS URLs are accepted. The source name `ai-toolkit` is reserved.
+
+## remove-mcp
+
+Strips all server entries from `~/.mcp.json` that carry a given `_source` tag, cleans the same server names from every editor `global_path`, and (if URL-sourced) unregisters from `sources.json` and removes the cached file.
+
+```bash
+npx @softspark/ai-toolkit remove-mcp rag-mcp-template
+```
+
+The argument is the source name (file stem used during `inject-mcp`). If no entries with that source are present, the command exits 0 silently. `ai-toolkit` source is reserved and cannot be removed via this command.
+
 ## mcp add / install
 
 Merges one or more MCP server templates from `app/mcp-templates/` into the project's `.mcp.json`.
@@ -8337,6 +8400,8 @@ When `install` runs with `--scope project`, ai-toolkit also updates `.mcp.json`
 │    remove-rule  <name>        → CLAUDE.md            │
 │    inject-hook  <file|url>    → settings.json        │
 │    remove-hook  <name>        → settings.json        │
+│    inject-mcp   <file|url>    → .mcp.json + editors  │
+│    remove-mcp   <name>        → .mcp.json + editors  │
 │    add-rule     <file|url>    → rules/ registry      │
 │    mcp add      <template>    → .mcp.json            │
 │    mcp install  <template>    → editor-native MCP    │
@@ -8352,7 +8417,7 @@ When `install` runs with `--scope project`, ai-toolkit also updates `.mcp.json`
    (consumer)       (consumer)      (consumer)
 ```
 
-## Example: Registering Rules and Hooks from an External Tool
+## Example: Registering Rules, Hooks, and MCP Servers from an External Tool
 
 An external tool's install script would call:
 
@@ -8360,14 +8425,14 @@ An external tool's install script would call:
 # Register rules into CLAUDE.md
 npx @softspark/ai-toolkit inject-rule ./rules/my-tool-rules.md
 
-# Register hooks into settings.json
+# Register hooks into settings.json (auto-propagates to Codex)
 npx @softspark/ai-toolkit inject-hook ./hooks/my-tool-hooks.json
 
-# Add an MCP server template
-npx @softspark/ai-toolkit mcp add github
+# Register MCP server template into .mcp.json + all editor MCP configs
+npx @softspark/ai-toolkit inject-mcp ./mcp-template.json
 
-# Render the same template into Cursor project config
-npx @softspark/ai-toolkit mcp install --editor cursor --scope project github --target .
+# Alternative: pull MCP template from a URL (auto-refreshed on update)
+npx @softspark/ai-toolkit inject-mcp https://example.com/mcp-template.json
 ```
 
 To uninstall:
@@ -8375,6 +8440,7 @@ To uninstall:
 ```bash
 npx @softspark/ai-toolkit remove-rule my-tool-rules
 npx @softspark/ai-toolkit remove-hook my-tool-hooks
+npx @softspark/ai-toolkit remove-mcp my-tool
 ```
 
 All operations are idempotent — safe to run on every install or update.
@@ -9136,7 +9202,7 @@ First-match-wins per file. Built-in runners: `bats`, `pytest`, `vitest`, `jest`.
 | Script | `~/.softspark/ai-toolkit/hooks/search-tracker.sh` |
 | Fires | After any search-style tool call |
 
-**Action:** Clears `~/.softspark/ai-toolkit/state/search-required.flag`. Pairs with `user-prompt-submit.sh` (sets flag on long technical prompts only when a search provider is detected or strict mode is enabled) and `stop-search-check.sh` (blocks Stop if flag still set). Together they enforce the global CLAUDE.md GOLDEN RULE without breaking offline/no-RAG installs.
+**Action:** Clears `~/.softspark/ai-toolkit/state/search-required-<session_id>.flag` (per-session, keyed by `session_id` from the hook stdin payload, falling back to `transcript_path` basename, then `default`). Pairs with `user-prompt-submit.sh` (sets the flag on long technical prompts only when a search provider is detected or strict mode is enabled) and `stop-search-check.sh` (blocks Stop if the calling session's flag is still set). Together they enforce the global CLAUDE.md GOLDEN RULE without breaking offline/no-RAG installs and without cross-session interference when multiple Claude Code windows run in parallel.
 
 Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -9149,7 +9215,7 @@ Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/stop-search-check.sh` |
 | Fires | When Claude finishes a response |
 
-**Action:** If `search-required.flag` is still present (no search tool ran during this turn) and a search provider is still detectable, emits `{"decision":"block","reason":"..."}` to continue the conversation with a search-first reminder. If no RAG/Web provider is detected, it clears the stale flag and exits 0, so offline/no-MCP users are not blocked.
+**Action:** If `search-required-<session_id>.flag` for the calling session is still present (no search tool ran during this turn) and a search provider is still detectable, emits `{"decision":"block","reason":"..."}` to continue the conversation with a search-first reminder. If no RAG/Web provider is detected, it clears the stale flag and exits 0, so offline/no-MCP users are not blocked. Flags are scoped by `session_id` from the hook stdin payload so a Stop in session B never consumes session A's flag (and vice versa). Stale per-session flags older than 60 minutes are GC'd on the next `SessionStart`.
 
 **Overrides:** `CLAUDE_SKIP_SEARCH_FIRST=1`, `AI_TOOLKIT_SEARCH_FIRST=off`, or `AI_TOOLKIT_SEARCH_FIRST=strict` to force enforcement. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -9211,7 +9277,7 @@ Set in `.claude/settings.local.json`:
 ├── rules/          # Registered rules (add-rule.sh)
 ├── state/          # Per-session runtime state (NEW)
 │   ├── session-edits.json         # Append-only edit log per session
-│   ├── search-required.flag       # Set by user-prompt-submit, cleared by search-tracker
+│   ├── search-required-<sid>.flag # Per-session: set by user-prompt-submit, cleared by search-tracker/stop-search-check, GC'd at SessionStart (>60min)
 │   ├── loaded-instructions.log    # Audit trail of which rules entered context
 │   └── test-cohesion-last.log     # Last cohesion test command output
 └── hooks/          # Hook scripts (copied on install)
@@ -9911,11 +9977,11 @@ Global-only clients are configured explicitly via `ai-toolkit mcp install --edit
 title: "MCP Server Templates"
 category: reference
 service: ai-toolkit
-tags: [mcp, templates, servers, configuration, editors]
-version: "1.1.0"
+tags: [mcp, templates, servers, configuration, editors, inject-mcp, external-templates]
+version: "1.2.0"
 created: "2026-04-07"
-last_updated: "2026-04-12"
-description: "Reference for 26 MCP server templates plus native editor MCP installation support."
+last_updated: "2026-05-12"
+description: "Reference for 26 built-in MCP server templates, external template injection via inject-mcp, and native editor MCP installation support."
 ---
 
 # MCP Server Templates
@@ -9924,6 +9990,8 @@ description: "Reference for 26 MCP server templates plus native editor MCP insta
 
 ai-toolkit ships 26 ready-to-use MCP server configuration templates in `app/mcp-templates/`. Each template is a JSON file that defines the canonical `mcpServers` block for a specific service. Templates can be merged into the project's `.mcp.json` and rendered into editor-native MCP config files via the `ai-toolkit mcp` CLI subcommand.
 
+**External templates:** Tools outside the toolkit (MCP servers, plugins, custom integrations) can register their own MCP templates via `ai-toolkit inject-mcp <file|url>` -- the toolkit caches the template, tags every server with a `_source` field, and propagates the config to every editor that exposes a `global_path`. URL-sourced templates are auto-refreshed on every `ai-toolkit update`. See [PATH: kb/reference/extension-api.md] for the inject-mcp / remove-mcp reference.
+
 ## CLI
 
 ```bash

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.3.0",
+  "version": "4.3.1",
   "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.3.0",
+  "version": "4.3.1",
   "description": "AI coding toolkit: 107 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",

package/scripts/test_cohesion.py

@@ -33,7 +33,7 @@ import sys
 from pathlib import Path
 
 DEFAULT_RUNNERS: dict[str, str] = {
-    "bats": "bats --no-parallelize-within-files",
+    "bats": "bats",
     "pytest": "pytest -x",
     "vitest": "npx vitest run",
     "jest": "npx jest --bail",