@softspark/ai-toolkit 4.3.0 → 4.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +56 -0
- package/README.md +10 -9
- package/app/.claude-plugin/plugin.json +1 -1
- package/app/ARCHITECTURE.md +6 -1
- package/app/hooks/_hook-io.sh +17 -0
- package/app/hooks/_search-capability.sh +52 -4
- package/app/hooks/commit-quality.sh +1 -0
- package/app/hooks/governance-capture.sh +1 -0
- package/app/hooks/guard-config.sh +1 -0
- package/app/hooks/guard-destructive.sh +1 -0
- package/app/hooks/mcp-health.sh +3 -1
- package/app/hooks/revert-guard.sh +1 -0
- package/app/hooks/search-tracker.sh +6 -2
- package/app/hooks/session-start.sh +22 -12
- package/app/hooks/stop-search-check.sh +56 -1
- package/app/hooks/test-cohesion.sh +1 -0
- package/app/hooks/track-usage.sh +1 -0
- package/app/hooks/user-prompt-submit.sh +2 -1
- package/app/hooks.json +2 -2
- package/benchmarks/ecosystem-doctor-snapshot.json +42 -37
- package/kb/procedures/release-verification-sop.md +7 -5
- package/kb/reference/codex-cli-compatibility.md +11 -2
- package/kb/reference/hooks-catalog.md +21 -8
- package/llms-full.txt +122 -30
- package/manifest.json +2 -2
- package/package.json +1 -1
- package/scripts/generate_codex_hooks.py +1 -1
- package/scripts/test_cohesion.py +1 -1
package/llms-full.txt
CHANGED
|
@@ -5250,10 +5250,10 @@ title: "SOP: Release Verification"
|
|
|
5250
5250
|
category: procedures
|
|
5251
5251
|
service: ai-toolkit
|
|
5252
5252
|
tags: [sop, verification, release, smoke-test, install, update, qa, provenance, sarif]
|
|
5253
|
-
version: "1.4.
|
|
5253
|
+
version: "1.4.3"
|
|
5254
5254
|
created: "2026-04-08"
|
|
5255
|
-
last_updated: "2026-
|
|
5256
|
-
description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. Reflects the v2.8.0 supply-chain standard. v1.3.0 added the single-run npm test discipline; v1.4.0 adds v3.0.0 deep-coverage checks (--profile full, --codex-skills, breaking-change surfaces, idempotence, registry drift, live-JSON parse) and refreshes stale thresholds. v1.4.2 makes the Phase 9.4 idempotence check deterministic by sorting file paths before hashing."
|
|
5255
|
+
last_updated: "2026-05-19"
|
|
5256
|
+
description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. Reflects the v2.8.0 supply-chain standard. v1.3.0 added the single-run npm test discipline; v1.4.0 adds v3.0.0 deep-coverage checks (--profile full, --codex-skills, breaking-change surfaces, idempotence, registry drift, live-JSON parse) and refreshes stale thresholds. v1.4.2 makes the Phase 9.4 idempotence check deterministic by sorting file paths before hashing. v1.4.3 tightens the Phase 8.4 URL pin check so the success-message count includes only entries with a `url:` field, not local `path:` entries, and documents the `sources.json` envelope shape."
|
|
5257
5257
|
---
|
|
5258
5258
|
|
|
5259
5259
|
# SOP: Release Verification
|
|
@@ -5550,11 +5550,13 @@ python3 scripts/audit_skills.py --permissions | head -40
|
|
|
5550
5550
|
|
|
5551
5551
|
### 8.4 URL-sourced rules/hooks are checksum-pinned
|
|
5552
5552
|
|
|
5553
|
+
`sources.json` is an envelope of the form `{"schema_version": 1, "rules"|"hooks": {...}}`, so the jq filter must pick the nested map before piping into the pin assertion. The URL-count in the success message ignores local `path:`-only entries — only entries with a `url:` field are pinned and counted.
|
|
5554
|
+
|
|
5553
5555
|
```bash
|
|
5554
5556
|
jq '.rules // .hooks // {}' ~/.softspark/ai-toolkit/rules/sources.json 2>/dev/null \
|
|
5555
|
-
| python3 -c "import json, sys; d=json.load(sys.stdin) or {}; bad=[n for n,v in d.items() if v.get('url') and not v.get('sha256')]; assert not bad, f'UNPINNED: {bad}'; print(f'RULE PIN OK: {
|
|
5557
|
+
| python3 -c "import json, sys; d=json.load(sys.stdin) or {}; bad=[n for n,v in d.items() if v.get('url') and not v.get('sha256')]; assert not bad, f'UNPINNED: {bad}'; url_n=sum(1 for v in d.values() if v.get('url')); print(f'RULE PIN OK: {url_n} URL rules, all with sha256')"
|
|
5556
5558
|
jq '.hooks // {}' ~/.softspark/ai-toolkit/hooks/external/sources.json 2>/dev/null \
|
|
5557
|
-
| python3 -c "import json, sys; d=json.load(sys.stdin) or {}; bad=[n for n,v in d.items() if v.get('url') and not v.get('sha256')]; assert not bad, f'UNPINNED: {bad}'; print(f'HOOK PIN OK: {
|
|
5559
|
+
| python3 -c "import json, sys; d=json.load(sys.stdin) or {}; bad=[n for n,v in d.items() if v.get('url') and not v.get('sha256')]; assert not bad, f'UNPINNED: {bad}'; url_n=sum(1 for v in d.values() if v.get('url')); print(f'HOOK PIN OK: {url_n} URL hooks, all with sha256')"
|
|
5558
5560
|
```
|
|
5559
5561
|
|
|
5560
5562
|
**Verify:**
|
|
@@ -6926,9 +6928,9 @@ title: "AI Toolkit - Codex CLI Compatibility"
|
|
|
6926
6928
|
category: reference
|
|
6927
6929
|
service: ai-toolkit
|
|
6928
6930
|
tags: [codex, compatibility, install, skills, hooks]
|
|
6929
|
-
version: "1.0.
|
|
6931
|
+
version: "1.0.1"
|
|
6930
6932
|
created: "2026-04-12"
|
|
6931
|
-
last_updated: "2026-
|
|
6933
|
+
last_updated: "2026-05-21"
|
|
6932
6934
|
description: "Reference for how ai-toolkit maps Claude-oriented skills, hooks, and plugin packs to Codex CLI."
|
|
6933
6935
|
---
|
|
6934
6936
|
|
|
@@ -7033,6 +7035,11 @@ This means Claude-only events such as `TaskCompleted`, `TeammateIdle`,
|
|
|
7033
7035
|
`~/.codex/hooks.json` (global layer). Non-Codex events are silently skipped.
|
|
7034
7036
|
`remove-hook` cleans both Claude and Codex targets.
|
|
7035
7037
|
|
|
7038
|
+
Generated Codex hook commands include `AI_TOOLKIT_HOOK_QUIET=1`. This keeps
|
|
7039
|
+
non-blocking reminders and startup context out of the visible Codex hook output
|
|
7040
|
+
while preserving hook side effects and blocking decisions such as search-first
|
|
7041
|
+
Stop enforcement.
|
|
7042
|
+
|
|
7036
7043
|
## Behavioral Limits
|
|
7037
7044
|
|
|
7038
7045
|
Codex wrappers preserve workflow intent, but not every Claude runtime behavior
|
|
@@ -7043,6 +7050,10 @@ Known limits:
|
|
|
7043
7050
|
- No native Codex equivalent of tmux-backed Agent Teams lifecycle events
|
|
7044
7051
|
- No separate task object model equivalent to Claude `Task*` APIs
|
|
7045
7052
|
- Hook event coverage is narrower than Claude Code
|
|
7053
|
+
- MCP search tool calls may not fire the shared `PostToolUse` search tracker,
|
|
7054
|
+
so `stop-search-check.sh` also checks `~/.codex/log/codex-tui.log` for
|
|
7055
|
+
`smart_query`, `hybrid_search_kb`, `crag_search`, `multi_hop_search`, and
|
|
7056
|
+
`verify_answer` calls after the search-first flag timestamp before blocking.
|
|
7046
7057
|
|
|
7047
7058
|
These are runtime platform limits, not installation defects.
|
|
7048
7059
|
|
|
@@ -8186,11 +8197,11 @@ Run `ai-toolkit update --local` to re-resolve and update the lock file.
|
|
|
8186
8197
|
title: "Extension API Reference"
|
|
8187
8198
|
category: reference
|
|
8188
8199
|
service: ai-toolkit
|
|
8189
|
-
tags: [extension-api, inject-rule, inject-hook, mcp-templates, integration, editors]
|
|
8190
|
-
version: "1.
|
|
8200
|
+
tags: [extension-api, inject-rule, inject-hook, inject-mcp, mcp-templates, integration, editors]
|
|
8201
|
+
version: "1.5.0"
|
|
8191
8202
|
created: "2026-04-07"
|
|
8192
|
-
last_updated: "2026-
|
|
8193
|
-
description: "Reference for ai-toolkit's extension API: inject-rule, inject-hook,
|
|
8203
|
+
last_updated: "2026-05-12"
|
|
8204
|
+
description: "Reference for ai-toolkit's extension API: inject-rule, inject-hook, inject-mcp, remove-* variants, and editor-aware MCP template management."
|
|
8194
8205
|
---
|
|
8195
8206
|
|
|
8196
8207
|
# Extension API Reference
|
|
@@ -8209,8 +8220,10 @@ This design is intentional: ai-toolkit is a generic toolkit. Consumers (MCP serv
|
|
|
8209
8220
|
| `remove-rule <name>` | `~/.claude/CLAUDE.md` | Strip markers by block name | Yes |
|
|
8210
8221
|
| `inject-hook <file.json\|url> [name]` | `~/.claude/settings.json` | JSON `_source` tag per entry, URL cached + registered | Yes |
|
|
8211
8222
|
| `remove-hook <name>` | `~/.claude/settings.json` | Strip all entries with matching `_source`, unregister URL source | Yes |
|
|
8223
|
+
| `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 |
|
|
8224
|
+
| `remove-mcp <name>` | `~/.mcp.json` + every editor with `global_path` | Strip all servers with matching `_source`, clean editor configs, unregister URL | Yes |
|
|
8212
8225
|
| `add-rule <file.md\|url>` | `~/.softspark/ai-toolkit/rules/` | File copy + re-inject all rules on next `update` | Yes |
|
|
8213
|
-
| `mcp add <name...>` | `.mcp.json` | Merge `mcpServers` block from template | Yes |
|
|
8226
|
+
| `mcp add <name...>` | `.mcp.json` | Merge `mcpServers` block from built-in template | Yes |
|
|
8214
8227
|
| `mcp install --editor <name...>` | Native editor MCP config | Render canonical template into editor format | Yes |
|
|
8215
8228
|
|
|
8216
8229
|
## inject-rule
|
|
@@ -8299,6 +8312,67 @@ npx @softspark/ai-toolkit remove-hook my-tool-hooks
|
|
|
8299
8312
|
|
|
8300
8313
|
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.
|
|
8301
8314
|
|
|
8315
|
+
## inject-mcp
|
|
8316
|
+
|
|
8317
|
+
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`.
|
|
8318
|
+
|
|
8319
|
+
```bash
|
|
8320
|
+
# From local file
|
|
8321
|
+
npx @softspark/ai-toolkit inject-mcp ./rag-mcp-template.json
|
|
8322
|
+
|
|
8323
|
+
# From URL (cached locally, auto-refreshed on update)
|
|
8324
|
+
npx @softspark/ai-toolkit inject-mcp https://example.com/rag-mcp-template.json
|
|
8325
|
+
|
|
8326
|
+
# With explicit source name (preferred when filename stem is generic)
|
|
8327
|
+
npx @softspark/ai-toolkit inject-mcp ./mcp/mcp-template.json --name rag-mcp
|
|
8328
|
+
|
|
8329
|
+
# With explicit target dir
|
|
8330
|
+
npx @softspark/ai-toolkit inject-mcp ./template.json /custom/target --name my-rag
|
|
8331
|
+
|
|
8332
|
+
# Force overwrite of servers with a different _source (collision resolution)
|
|
8333
|
+
npx @softspark/ai-toolkit inject-mcp ./conflict.json --force
|
|
8334
|
+
```
|
|
8335
|
+
|
|
8336
|
+
**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`.
|
|
8337
|
+
|
|
8338
|
+
**Implementation:** `scripts/inject_mcp_cli.py`, `scripts/mcp_sources.py`, `scripts/url_fetch.py`.
|
|
8339
|
+
|
|
8340
|
+
**Input format:** Same as built-in templates in `app/mcp-templates/`:
|
|
8341
|
+
```json
|
|
8342
|
+
{
|
|
8343
|
+
"name": "rag-mcp",
|
|
8344
|
+
"description": "Multi-tenant RAG over knowledge bases",
|
|
8345
|
+
"mcpServers": {
|
|
8346
|
+
"rag-mcp": {
|
|
8347
|
+
"type": "http",
|
|
8348
|
+
"url": "http://localhost:8081/mcp/sse?secret_key=${RAG_MCP_SECRET_KEY}"
|
|
8349
|
+
}
|
|
8350
|
+
}
|
|
8351
|
+
}
|
|
8352
|
+
```
|
|
8353
|
+
|
|
8354
|
+
**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).
|
|
8355
|
+
|
|
8356
|
+
**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.
|
|
8357
|
+
|
|
8358
|
+
**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.
|
|
8359
|
+
|
|
8360
|
+
**Idempotency:** Re-running with the same source overwrites entries for that source cleanly -- no duplicates accumulate.
|
|
8361
|
+
|
|
8362
|
+
**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.
|
|
8363
|
+
|
|
8364
|
+
**Safety:** Only HTTPS URLs are accepted. The source name `ai-toolkit` is reserved.
|
|
8365
|
+
|
|
8366
|
+
## remove-mcp
|
|
8367
|
+
|
|
8368
|
+
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.
|
|
8369
|
+
|
|
8370
|
+
```bash
|
|
8371
|
+
npx @softspark/ai-toolkit remove-mcp rag-mcp-template
|
|
8372
|
+
```
|
|
8373
|
+
|
|
8374
|
+
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.
|
|
8375
|
+
|
|
8302
8376
|
## mcp add / install
|
|
8303
8377
|
|
|
8304
8378
|
Merges one or more MCP server templates from `app/mcp-templates/` into the project's `.mcp.json`.
|
|
@@ -8337,6 +8411,8 @@ When `install` runs with `--scope project`, ai-toolkit also updates `.mcp.json`
|
|
|
8337
8411
|
│ remove-rule <name> → CLAUDE.md │
|
|
8338
8412
|
│ inject-hook <file|url> → settings.json │
|
|
8339
8413
|
│ remove-hook <name> → settings.json │
|
|
8414
|
+
│ inject-mcp <file|url> → .mcp.json + editors │
|
|
8415
|
+
│ remove-mcp <name> → .mcp.json + editors │
|
|
8340
8416
|
│ add-rule <file|url> → rules/ registry │
|
|
8341
8417
|
│ mcp add <template> → .mcp.json │
|
|
8342
8418
|
│ mcp install <template> → editor-native MCP │
|
|
@@ -8352,7 +8428,7 @@ When `install` runs with `--scope project`, ai-toolkit also updates `.mcp.json`
|
|
|
8352
8428
|
(consumer) (consumer) (consumer)
|
|
8353
8429
|
```
|
|
8354
8430
|
|
|
8355
|
-
## Example: Registering Rules and
|
|
8431
|
+
## Example: Registering Rules, Hooks, and MCP Servers from an External Tool
|
|
8356
8432
|
|
|
8357
8433
|
An external tool's install script would call:
|
|
8358
8434
|
|
|
@@ -8360,14 +8436,14 @@ An external tool's install script would call:
|
|
|
8360
8436
|
# Register rules into CLAUDE.md
|
|
8361
8437
|
npx @softspark/ai-toolkit inject-rule ./rules/my-tool-rules.md
|
|
8362
8438
|
|
|
8363
|
-
# Register hooks into settings.json
|
|
8439
|
+
# Register hooks into settings.json (auto-propagates to Codex)
|
|
8364
8440
|
npx @softspark/ai-toolkit inject-hook ./hooks/my-tool-hooks.json
|
|
8365
8441
|
|
|
8366
|
-
#
|
|
8367
|
-
npx @softspark/ai-toolkit mcp
|
|
8442
|
+
# Register MCP server template into .mcp.json + all editor MCP configs
|
|
8443
|
+
npx @softspark/ai-toolkit inject-mcp ./mcp-template.json
|
|
8368
8444
|
|
|
8369
|
-
#
|
|
8370
|
-
npx @softspark/ai-toolkit mcp
|
|
8445
|
+
# Alternative: pull MCP template from a URL (auto-refreshed on update)
|
|
8446
|
+
npx @softspark/ai-toolkit inject-mcp https://example.com/mcp-template.json
|
|
8371
8447
|
```
|
|
8372
8448
|
|
|
8373
8449
|
To uninstall:
|
|
@@ -8375,6 +8451,7 @@ To uninstall:
|
|
|
8375
8451
|
```bash
|
|
8376
8452
|
npx @softspark/ai-toolkit remove-rule my-tool-rules
|
|
8377
8453
|
npx @softspark/ai-toolkit remove-hook my-tool-hooks
|
|
8454
|
+
npx @softspark/ai-toolkit remove-mcp my-tool
|
|
8378
8455
|
```
|
|
8379
8456
|
|
|
8380
8457
|
All operations are idempotent — safe to run on every install or update.
|
|
@@ -8758,9 +8835,9 @@ title: "Hooks Catalog"
|
|
|
8758
8835
|
category: reference
|
|
8759
8836
|
service: ai-toolkit
|
|
8760
8837
|
tags: [hooks, quality, safety, enforcement, settings.json]
|
|
8761
|
-
version: "1.5.
|
|
8838
|
+
version: "1.5.2"
|
|
8762
8839
|
created: "2026-03-27"
|
|
8763
|
-
last_updated: "2026-05-
|
|
8840
|
+
last_updated: "2026-05-21"
|
|
8764
8841
|
description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
|
|
8765
8842
|
---
|
|
8766
8843
|
|
|
@@ -8805,6 +8882,11 @@ ai-toolkit update # re-copies scripts, re-merges (idempotent)
|
|
|
8805
8882
|
3. Loads session context from `.claude/session-context.md` (if exists)
|
|
8806
8883
|
4. Loads active instincts from `.claude/instincts/*.md` (if any)
|
|
8807
8884
|
|
|
8885
|
+
When `AI_TOOLKIT_HOOK_QUIET=1`, the hook still performs session-state reset,
|
|
8886
|
+
stale search-flag cleanup, and update notification side effects, but suppresses
|
|
8887
|
+
all informational stdout so runtimes such as Codex do not show startup hook
|
|
8888
|
+
context in the UI.
|
|
8889
|
+
|
|
8808
8890
|
### Notification — `notify-waiting.sh`
|
|
8809
8891
|
|
|
8810
8892
|
| Field | Value |
|
|
@@ -8859,7 +8941,10 @@ ai-toolkit update # re-copies scripts, re-merges (idempotent)
|
|
|
8859
8941
|
|
|
8860
8942
|
**Action:** Adds a lightweight governance reminder: plan mode for architectural work, evidence-first debugging, KB-first research, and validation expectations.
|
|
8861
8943
|
|
|
8862
|
-
Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
|
|
8944
|
+
Skipped when `TOOLKIT_HOOK_PROFILE=minimal`. The bundled `app/hooks.json`
|
|
8945
|
+
registers this command with `AI_TOOLKIT_HOOK_QUIET=1`, so it still arms or
|
|
8946
|
+
clears the per-session search-first flag but suppresses the informational
|
|
8947
|
+
reminder output.
|
|
8863
8948
|
|
|
8864
8949
|
### UserPromptSubmit (usage tracking) — `track-usage.sh`
|
|
8865
8950
|
|
|
@@ -9132,11 +9217,11 @@ First-match-wins per file. Built-in runners: `bats`, `pytest`, `vitest`, `jest`.
|
|
|
9132
9217
|
| Field | Value |
|
|
9133
9218
|
|-------|-------|
|
|
9134
9219
|
| Event | `PostToolUse` |
|
|
9135
|
-
| Matcher | `
|
|
9220
|
+
| Matcher | `mcp__.*__(smart_query\|hybrid_search_kb\|crag_search\|multi_hop_search\|verify_answer)\|WebSearch\|WebFetch` |
|
|
9136
9221
|
| Script | `~/.softspark/ai-toolkit/hooks/search-tracker.sh` |
|
|
9137
9222
|
| Fires | After any search-style tool call |
|
|
9138
9223
|
|
|
9139
|
-
**Action:** Clears `~/.softspark/ai-toolkit/state/search-required
|
|
9224
|
+
**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). Search provider detection parses actual MCP server names from `mcpServers`, `mcp_servers`, or `mcp` config blocks; hook matchers and permission allowlists do not count as providers. Together the hooks 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.
|
|
9140
9225
|
|
|
9141
9226
|
Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
|
|
9142
9227
|
|
|
@@ -9149,7 +9234,7 @@ Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
|
|
|
9149
9234
|
| Script | `~/.softspark/ai-toolkit/hooks/stop-search-check.sh` |
|
|
9150
9235
|
| Fires | When Claude finishes a response |
|
|
9151
9236
|
|
|
9152
|
-
**Action:** If `search-required
|
|
9237
|
+
**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. On Codex, where MCP search tools may not trigger the shared `PostToolUse` tracker, the hook also checks `~/.codex/log/codex-tui.log` for search tool calls after the flag timestamp before blocking. 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`.
|
|
9153
9238
|
|
|
9154
9239
|
**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`.
|
|
9155
9240
|
|
|
@@ -9187,7 +9272,7 @@ Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
|
|
|
9187
9272
|
| `scripts/test_cohesion.py` | Resolves changed paths → test commands via cohesion map. First-match-wins. Stdlib-only. |
|
|
9188
9273
|
| `app/hooks/test-cohesion-map.json` | Toolkit-default path → tests mapping (used when no project map exists). |
|
|
9189
9274
|
| `app/hooks/_locate-toolkit.sh` | Shared bash helper that exports `$TOOLKIT_DIR` for hooks needing scripts/. |
|
|
9190
|
-
| `app/hooks/_hook-io.sh` | Shared bash helper that normalizes hook payloads across Claude, Augment, Gemini, Windsurf, and Cursor-style JSON. |
|
|
9275
|
+
| `app/hooks/_hook-io.sh` | Shared bash helper that normalizes hook payloads across Claude, Augment, Gemini, Windsurf, and Cursor-style JSON. Honors `AI_TOOLKIT_HOOK_QUIET=1` for non-blocking context output. |
|
|
9191
9276
|
| `app/hooks/_search-capability.sh` | Shared bash helper that enables search-first blocking only when RAG/Web is configured or strict mode is requested. |
|
|
9192
9277
|
|
|
9193
9278
|
## Runtime Profiles
|
|
@@ -9204,6 +9289,11 @@ Set in `.claude/settings.local.json`:
|
|
|
9204
9289
|
| `standard` | All hooks (default) |
|
|
9205
9290
|
| `strict` | Standard + mypy --strict on task completion |
|
|
9206
9291
|
|
|
9292
|
+
Set `AI_TOOLKIT_HOOK_QUIET=1` on hook commands to suppress non-blocking
|
|
9293
|
+
informational context while preserving side effects and blocking decisions.
|
|
9294
|
+
Codex-generated hooks use this mode by default, and Claude's bundled
|
|
9295
|
+
`UserPromptSubmit` entry uses it to avoid visible prompt hook context.
|
|
9296
|
+
|
|
9207
9297
|
## Architecture
|
|
9208
9298
|
|
|
9209
9299
|
```
|
|
@@ -9211,7 +9301,7 @@ Set in `.claude/settings.local.json`:
|
|
|
9211
9301
|
├── rules/ # Registered rules (add-rule.sh)
|
|
9212
9302
|
├── state/ # Per-session runtime state (NEW)
|
|
9213
9303
|
│ ├── session-edits.json # Append-only edit log per session
|
|
9214
|
-
│ ├── search-required
|
|
9304
|
+
│ ├── search-required-<sid>.flag # Per-session: set by user-prompt-submit, cleared by search-tracker/stop-search-check, GC'd at SessionStart (>60min)
|
|
9215
9305
|
│ ├── loaded-instructions.log # Audit trail of which rules entered context
|
|
9216
9306
|
│ └── test-cohesion-last.log # Last cohesion test command output
|
|
9217
9307
|
└── hooks/ # Hook scripts (copied on install)
|
|
@@ -9911,11 +10001,11 @@ Global-only clients are configured explicitly via `ai-toolkit mcp install --edit
|
|
|
9911
10001
|
title: "MCP Server Templates"
|
|
9912
10002
|
category: reference
|
|
9913
10003
|
service: ai-toolkit
|
|
9914
|
-
tags: [mcp, templates, servers, configuration, editors]
|
|
9915
|
-
version: "1.
|
|
10004
|
+
tags: [mcp, templates, servers, configuration, editors, inject-mcp, external-templates]
|
|
10005
|
+
version: "1.2.0"
|
|
9916
10006
|
created: "2026-04-07"
|
|
9917
|
-
last_updated: "2026-
|
|
9918
|
-
description: "Reference for 26 MCP server templates
|
|
10007
|
+
last_updated: "2026-05-12"
|
|
10008
|
+
description: "Reference for 26 built-in MCP server templates, external template injection via inject-mcp, and native editor MCP installation support."
|
|
9919
10009
|
---
|
|
9920
10010
|
|
|
9921
10011
|
# MCP Server Templates
|
|
@@ -9924,6 +10014,8 @@ description: "Reference for 26 MCP server templates plus native editor MCP insta
|
|
|
9924
10014
|
|
|
9925
10015
|
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.
|
|
9926
10016
|
|
|
10017
|
+
**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.
|
|
10018
|
+
|
|
9927
10019
|
## CLI
|
|
9928
10020
|
|
|
9929
10021
|
```bash
|
package/manifest.json
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
{
|
|
2
|
-
"version": "4.3.
|
|
2
|
+
"version": "4.3.2",
|
|
3
3
|
"components": {
|
|
4
4
|
"agents": {
|
|
5
5
|
"description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",
|
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
"tags": ["core", "skills", "commands"]
|
|
17
17
|
},
|
|
18
18
|
"hooks": {
|
|
19
|
-
"description": "
|
|
19
|
+
"description": "28 hook entries across 14 lifecycle events",
|
|
20
20
|
"path": "app/hooks.json + app/hooks/*.sh",
|
|
21
21
|
"target": "~/.claude/settings.json (merge) + ~/.softspark/ai-toolkit/hooks/ (copy)",
|
|
22
22
|
"type": "merge+copy",
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@softspark/ai-toolkit",
|
|
3
|
-
"version": "4.3.
|
|
3
|
+
"version": "4.3.2",
|
|
4
4
|
"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.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude",
|
|
@@ -24,7 +24,7 @@ import sys
|
|
|
24
24
|
from pathlib import Path
|
|
25
25
|
|
|
26
26
|
|
|
27
|
-
HOOKS_PREFIX = '"$HOME/.softspark/ai-toolkit/hooks/'
|
|
27
|
+
HOOKS_PREFIX = 'AI_TOOLKIT_HOOK_QUIET=1 "$HOME/.softspark/ai-toolkit/hooks/'
|
|
28
28
|
|
|
29
29
|
# Hooks compatible with Codex, grouped by event.
|
|
30
30
|
# Format: (matcher, script_name)
|
package/scripts/test_cohesion.py
CHANGED