@softspark/ai-toolkit 4.2.4 → 4.3.0

package/llms-full.txt

@@ -5391,7 +5391,7 @@ ai-toolkit doctor
 - Environment: node, bash, python3, bats
 - Global Install: .claude exists, agents/skills symlinks (0 broken), settings.json hooks
 - Hook Scripts: all present and executable
-- Hook Configuration: 12 events registered
+- Hook Configuration: 14 events registered
 - Generated Artifacts: AGENTS.md, llms.txt, llms-full.txt
 - Planned Assets: plugin.json, benchmarks, plugin packs
 - Benchmark Freshness: < 30 days
@@ -5441,7 +5441,7 @@ python3 scripts/audit_skills.py --ci
 
 **Verify validate.py:**
 - [ ] Agents >= 44, Skills >= 99, Tests >= 900
-- [ ] Hook events: 12, Hook scripts: >= 20
+- [ ] Hook events: 14, Hook scripts: >= 30
 - [ ] Plugin packs >= 10, KB documents >= 20
 - [ ] `Errors: 0 | Warnings: 0` → `VALIDATION PASSED`
 
@@ -6352,7 +6352,7 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 
 ## Quality Hooks
 
-22 entries across 12 lifecycle events. See [hooks-catalog.md](hooks-catalog.md) for full details.
+28 entries across 14 lifecycle events. See [hooks-catalog.md](hooks-catalog.md) for full details.
 
 | Hook | Trigger | Script | Action |
 |------|---------|--------|--------|
@@ -8768,7 +8768,7 @@ description: "Complete reference of all ai-toolkit hooks: events, scripts, insta
 
 ## Overview
 
-ai-toolkit provides 22 global hook entries across 12 lifecycle events that enforce quality, safety, and workflow rules across all Claude Code sessions. Hooks are merged into `~/.claude/settings.json` on install, with logic in standalone scripts at `~/.softspark/ai-toolkit/hooks/`.
+ai-toolkit provides 28 global hook entries across 14 lifecycle events that enforce quality, safety, and workflow rules across all Claude Code sessions. Hooks are merged into `~/.claude/settings.json` on install, with logic in standalone scripts at `~/.softspark/ai-toolkit/hooks/`.
 
 ## Supported Surface
 
@@ -9082,6 +9082,114 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
 **Action:** Captures an environment snapshot to `~/.softspark/ai-toolkit/sessions/current-context.json`. Records working directory, git branch, git status summary, Node.js version, Python version, and timestamp. Used by other hooks and tools to access session metadata without re-running discovery commands. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
+---
+
+## New Hooks (Constitution Art. VI Enforcement)
+
+These six hooks turn Constitution Article VI ("Repair Discipline") from prose into executable enforcement. Each one closes a specific gap that previously relied on agent goodwill.
+
+### PreToolUse (revert protection) — `revert-guard.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `PreToolUse` |
+| Matcher | `Bash` |
+| Script | `~/.softspark/ai-toolkit/hooks/revert-guard.sh` |
+| Fires | Before any Bash command |
+
+**Action:** Blocks (exit 2) `git checkout/restore -- <file>`, `git reset --hard`, or `git clean -fd` when the affected files were edited in the current session (per `session_state.py` log). Forces the agent to fix root causes instead of reverting work-in-progress (Art. VI.2). Branch switches (`git checkout main`) and reverts on untouched files pass through unchanged.
+
+**Override (one-off):** `CLAUDE_REVERT_OK=1`. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+
+### PostToolUse (test cohesion) — `test-cohesion.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `PostToolUse` |
+| Matcher | `Edit\|MultiEdit\|Write` |
+| Script | `~/.softspark/ai-toolkit/hooks/test-cohesion.sh` |
+| Fires | After every file edit |
+
+**Action:** Runs the test commands mapped to the edited path via `test-cohesion-map.json`. Lookup order: project-local `.claude/test-cohesion-map.json`, then toolkit default `app/hooks/test-cohesion-map.json`. Blocks (exit 2) when the related test command fails. Runs **only** related tests, not the full suite (one of the user-stated requirements).
+
+Map schema:
+```json
+[
+  {
+    "match": "src/auth/*.py",
+    "tests": ["tests/test_auth.py"],
+    "runner": "pytest",
+    "command": null
+  }
+]
+```
+First-match-wins per file. Built-in runners: `bats`, `pytest`, `vitest`, `jest`. Use `"command"` for full overrides.
+
+**Overrides:** `CLAUDE_SKIP_COHESION=1` (one-off), `CLAUDE_HOOK_BOOTSTRAP=1` (when editing the hook itself). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+
+### PostToolUse (search-first tracker) — `search-tracker.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `PostToolUse` |
+| Matcher | `mcp__rag-mcp__smart_query\|mcp__rag-mcp__hybrid_search_kb\|mcp__rag-mcp__crag_search\|mcp__rag-mcp__multi_hop_search\|mcp__rag-mcp__verify_answer\|WebSearch\|WebFetch` |
+| 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.
+
+Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+
+### Stop (search-first enforcement) — `stop-search-check.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `Stop` |
+| Matcher | *(all)* |
+| 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.
+
+**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`.
+
+### InstructionsLoaded — `instructions-audit.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `InstructionsLoaded` |
+| Matcher | *(all)* |
+| Script | `~/.softspark/ai-toolkit/hooks/instructions-audit.sh` |
+| Fires | Whenever CLAUDE.md / `.claude/rules/*.md` is loaded into context |
+
+**Action:** Appends `<ts>\t<memory_type>\t<load_reason>\t<file_path>` to `~/.softspark/ai-toolkit/state/loaded-instructions.log`. Provides audit visibility: when a rule does NOT enter context (silently dropped, token budget, glob miss), the absence is observable. Auto-rotates at 2000 lines.
+
+Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+
+### ConfigChange — `config-desync-guard.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `ConfigChange` |
+| Matcher | `user_settings` |
+| Script | `~/.softspark/ai-toolkit/hooks/config-desync-guard.sh` |
+| Fires | When `~/.claude/settings.json` changes |
+
+**Action:** Compares `_source: ai-toolkit` entries between `~/.claude/settings.json` (installed) and the toolkit source `app/hooks.json`. If they diverge (missing/stale entries), emits an advisory to stderr suggesting `ai-toolkit update` or `ai-toolkit doctor --fix`. Non-blocking by design — user's legitimate settings edits never get rejected.
+
+**Override (silence advisory):** `CLAUDE_SKIP_CONFIG_DESYNC=1`. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+
+### Supporting Infrastructure
+
+| Component | Purpose |
+|-----------|---------|
+| `scripts/session_state.py` | Append-only edit log keyed by session_id. Cleared on SessionStart. Read by revert-guard, test-cohesion, quality-gate. |
+| `scripts/test_cohesion.py` | Resolves changed paths → test commands via cohesion map. First-match-wins. Stdlib-only. |
+| `app/hooks/test-cohesion-map.json` | Toolkit-default path → tests mapping (used when no project map exists). |
+| `app/hooks/_locate-toolkit.sh` | Shared bash helper that exports `$TOOLKIT_DIR` for hooks needing scripts/. |
+| `app/hooks/_hook-io.sh` | Shared bash helper that normalizes hook payloads across Claude, Augment, Gemini, Windsurf, and Cursor-style JSON. |
+| `app/hooks/_search-capability.sh` | Shared bash helper that enables search-first blocking only when RAG/Web is configured or strict mode is requested. |
+
 ## Runtime Profiles
 
 Set in `.claude/settings.local.json`:
@@ -9101,42 +9209,59 @@ Set in `.claude/settings.local.json`:
 ```
 ~/.softspark/ai-toolkit/
 ├── 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
+│   ├── 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)
-    ├── _profile-check.sh    # Shared: profile skip logic (sourced by hooks)
+    ├── _profile-check.sh         # Shared: profile skip logic (sourced by hooks)
+    ├── _locate-toolkit.sh        # NEW: shared $TOOLKIT_DIR locator
+    ├── _hook-io.sh               # NEW: shared multi-editor payload/output adapter
+    ├── _search-capability.sh     # NEW: capability-aware search-first enforcement
     ├── session-start.sh
-    ├── session-context.sh   # NEW: capture session env snapshot
+    ├── session-context.sh
     ├── guard-destructive.sh
     ├── guard-path.sh
-    ├── guard-config.sh      # NEW: block config file edits
-    ├── mcp-health.sh        # NEW: check MCP runtime availability
-    ├── user-prompt-submit.sh
-    ├── post-tool-use.sh
-    ├── governance-capture.sh # NEW: log security-sensitive operations
+    ├── guard-config.sh
+    ├── revert-guard.sh           # NEW: block revert on session-edited files (Art. VI.2)
+    ├── mcp-health.sh
+    ├── user-prompt-submit.sh     # extended: arms search-required flag
+    ├── post-tool-use.sh          # extended: appends edits to session state
+    ├── governance-capture.sh
+    ├── test-cohesion.sh          # NEW: runs mapped tests after edits (Art. VI.3)
+    ├── test-cohesion-map.json    # NEW: path → tests mapping
+    ├── search-tracker.sh         # NEW: clears search-required flag
     ├── quality-check.sh
-    ├── quality-gate.sh
+    ├── quality-gate.sh           # extended: cohesion-tests session edits
+    ├── stop-search-check.sh      # NEW: enforces search-first on Stop
     ├── save-session.sh
     ├── subagent-start.sh
     ├── subagent-stop.sh
     ├── track-usage.sh
     ├── pre-compact.sh
-    ├── pre-compact-save.sh  # NEW: timestamped context snapshot
-    ├── commit-quality.sh    # NEW: advisory commit message check
+    ├── pre-compact-save.sh
+    ├── commit-quality.sh
+    ├── instructions-audit.sh     # NEW: logs CLAUDE.md / rules loads
+    ├── config-desync-guard.sh    # NEW: warns on settings ↔ source drift
     └── session-end.sh
 
 ~/.claude/settings.json
 └── hooks:          # Hook definitions referencing ~/.softspark/ai-toolkit/hooks/
-    ├── SessionStart     → session-start.sh, mcp-health.sh, session-context.sh
-    ├── Notification     → osascript (inline)
-    ├── PreToolUse       → guard-destructive.sh, guard-path.sh, guard-config.sh, commit-quality.sh
-    ├── UserPromptSubmit → user-prompt-submit.sh, track-usage.sh
-    ├── PostToolUse      → post-tool-use.sh, governance-capture.sh
-    ├── Stop             → quality-check.sh, save-session.sh, quality-gate.sh
-    ├── TaskCompleted    → quality-gate.sh
-    ├── TeammateIdle     → echo (inline)
-    ├── SubagentStart    → subagent-start.sh
-    ├── SubagentStop     → subagent-stop.sh
-    ├── PreCompact       → pre-compact.sh, pre-compact-save.sh
-    └── SessionEnd       → session-end.sh
+    ├── SessionStart       → session-start.sh, mcp-health.sh, session-context.sh
+    ├── Notification       → notify-waiting.sh
+    ├── PreToolUse         → guard-destructive.sh, guard-path.sh, guard-config.sh, commit-quality.sh, revert-guard.sh
+    ├── UserPromptSubmit   → user-prompt-submit.sh, track-usage.sh
+    ├── PostToolUse        → post-tool-use.sh, governance-capture.sh, test-cohesion.sh, search-tracker.sh
+    ├── Stop               → quality-check.sh, save-session.sh, quality-gate.sh, stop-search-check.sh
+    ├── TaskCompleted      → quality-gate.sh
+    ├── TeammateIdle       → echo (inline)
+    ├── SubagentStart      → subagent-start.sh
+    ├── SubagentStop       → subagent-stop.sh
+    ├── PreCompact         → pre-compact.sh, pre-compact-save.sh
+    ├── SessionEnd         → session-end.sh
+    ├── InstructionsLoaded → instructions-audit.sh
+    └── ConfigChange       → config-desync-guard.sh
 ```
 
 **Key design decisions:**
@@ -9154,7 +9279,7 @@ Set in `.claude/settings.local.json`:
 
 **Hook script not found:**
 ```bash
-ls ~/.softspark/ai-toolkit/hooks/     # should list 21 .sh files (plus _profile-check.sh helper)
+ls ~/.softspark/ai-toolkit/hooks/     # should list 27 .sh files (plus _profile-check.sh + _locate-toolkit.sh + _hook-io.sh + _search-capability.sh helpers + test-cohesion-map.json)
 ai-toolkit update            # re-copies scripts
 ```
 
@@ -11780,11 +11905,11 @@ Unlike other toolkits that put safety rules in documentation only, ai-toolkit en
 
 Hook logic lives in `app/hooks/*.sh` — not inline JSON one-liners. Scripts are copied to `~/.softspark/ai-toolkit/hooks/` on install and referenced from `~/.claude/settings.json`. Easy to read, debug, and extend.
 
-**12 lifecycle events / 22 global hook entries:**
+**14 lifecycle events / 28 global hook entries:**
 
 | Event | Script | Action |
 |-------|--------|--------|
-| SessionStart | `session-start.sh` | MANDATORY rules reminder + session context + instincts |
+| SessionStart | `session-start.sh` | MANDATORY rules reminder + session context + instincts + reset session-edit state |
 | SessionStart | `mcp-health.sh` | Check MCP server command availability (non-blocking warning) |
 | SessionStart | `session-context.sh` | Capture environment snapshot to `~/.softspark/ai-toolkit/sessions/current-context.json` |
 | Notification | `notify-waiting.sh` | Cross-platform desktop notification |
@@ -11792,19 +11917,25 @@ Hook logic lives in `app/hooks/*.sh` — not inline JSON one-liners. Scripts are
 | PreToolUse | `guard-path.sh` | Block wrong-user path hallucination |
 | PreToolUse | `guard-config.sh` | Block edits to linter/formatter config files unless explicitly requested |
 | PreToolUse | `commit-quality.sh` | Advisory validation of git commit messages |
-| UserPromptSubmit | `user-prompt-submit.sh` | Prompt governance reminder |
+| PreToolUse | `revert-guard.sh` | Block `git checkout/restore/reset --hard/clean` on files edited this session (Art. VI.2) |
+| UserPromptSubmit | `user-prompt-submit.sh` | Prompt governance reminder + arm search-first flag only when RAG/Web is available |
 | UserPromptSubmit | `track-usage.sh` | Record skill invocations to local stats |
-| PostToolUse | `post-tool-use.sh` | Lightweight validation reminders after edits |
+| PostToolUse | `post-tool-use.sh` | Lightweight validation reminders + append edit to session state |
 | PostToolUse | `governance-capture.sh` | Log security-sensitive operations to JSONL |
+| PostToolUse | `test-cohesion.sh` | Run cohesion-mapped tests after edits; block on failure (Art. VI.3) |
+| PostToolUse | `search-tracker.sh` | Clear search-first flag when smart_query/hybrid_search_kb/Web* runs |
 | Stop | `quality-check.sh` | Multi-language lint (ruff/tsc/phpstan/dart/go) |
 | Stop | `save-session.sh` | Persist session context for cross-session continuity |
-| Stop | `quality-gate.sh` | Block final response on lint/type errors |
+| Stop | `quality-gate.sh` | Block final response on lint/type errors + cohesion tests for session edits |
+| Stop | `stop-search-check.sh` | Continue conversation if search-first rule was skipped and a provider exists; no-op offline |
 | TaskCompleted | `quality-gate.sh` | Block task completion on lint/type errors |
 | SubagentStart | `subagent-start.sh` | Narrow-scope reminder for spawned subagents |
 | SubagentStop | `subagent-stop.sh` | Completion checklist for subagent handoff |
 | PreCompact | `pre-compact.sh` | Smart compaction: prioritized context |
 | PreCompact | `pre-compact-save.sh` | Save timestamped context backup |
 | SessionEnd | `session-end.sh` | Persist a session-end handoff note |
+| InstructionsLoaded | `instructions-audit.sh` | Append every CLAUDE.md / rules load to audit log (which rules actually entered context) |
+| ConfigChange | `config-desync-guard.sh` | Warn when `~/.claude/settings.json` drifts from `app/hooks.json` (advisory) |
 | TeammateIdle | *(inline)* | Completeness reminder |
 
 **5 skill-scoped hooks:**

package/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.2.4",
+  "version": "4.3.0",
   "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/doctor.py

@@ -45,16 +45,29 @@ VALID_EVENTS = frozenset({
     "SessionStart", "Notification", "PreToolUse", "PostToolUse", "Stop",
     "PreCompact", "SubagentStop", "UserPromptSubmit", "TaskCompleted",
     "TeammateIdle", "SubagentStart", "SessionEnd", "PermissionRequest", "Setup",
+    "InstructionsLoaded", "ConfigChange", "PostToolUseFailure", "PostToolBatch",
+    "UserPromptExpansion", "PostCompact", "StopFailure", "CwdChanged",
+    "FileChanged", "PermissionDenied", "Elicitation", "ElicitationResult",
+    "WorktreeCreate", "WorktreeRemove",
 })
 
 EXPECTED_HOOKS = [
+    "_hook-io.sh",
+    "_locate-toolkit.sh",
+    "_search-capability.sh",
     "guard-destructive.sh",
     "guard-path.sh",
+    "config-desync-guard.sh",
+    "instructions-audit.sh",
     "post-tool-use.sh",
     "quality-check.sh",
     "quality-gate.sh",
+    "revert-guard.sh",
+    "search-tracker.sh",
     "save-session.sh",
     "session-start.sh",
+    "stop-search-check.sh",
+    "test-cohesion.sh",
     "pre-compact.sh",
     "user-prompt-submit.sh",
     "track-usage.sh",

package/scripts/generate_augment_hooks.py

@@ -32,7 +32,7 @@ import os
 import sys
 from pathlib import Path
 
-HOOKS_PREFIX = '"$HOME/.softspark/ai-toolkit/hooks/'
+HOOKS_PREFIX = 'AI_TOOLKIT_HOOK_FORMAT=json "$HOME/.softspark/ai-toolkit/hooks/'
 SOURCE_TAG = "ai-toolkit"
 
 # Event -> list of (matcher, script). Matcher is a regex over tool_name.
@@ -45,16 +45,20 @@ AUGMENT_HOOKS: dict[str, list[tuple[str, str]]] = {
     "PreToolUse": [
         ("launch-process", "guard-destructive.sh"),
         ("launch-process", "commit-quality.sh"),
+        ("launch-process", "revert-guard.sh"),
         ("view|str-replace-editor|save-file|remove-files", "guard-path.sh"),
         ("str-replace-editor|save-file", "guard-config.sh"),
     ],
     "PostToolUse": [
         ("str-replace-editor|save-file", "post-tool-use.sh"),
+        ("str-replace-editor|save-file", "test-cohesion.sh"),
         ("launch-process|str-replace-editor|save-file", "governance-capture.sh"),
+        ("web-fetch|web-search|codebase-retrieval", "search-tracker.sh"),
     ],
     "Stop": [
         ("", "quality-check.sh"),
         ("", "save-session.sh"),
+        ("", "stop-search-check.sh"),
     ],
     "SessionEnd": [
         ("", "session-end.sh"),

package/scripts/generate_codex_hooks.py

@@ -37,6 +37,7 @@ CODEX_HOOKS: dict[str, list[tuple[str, str]]] = {
     "PreToolUse": [
         ("Bash", "guard-destructive.sh"),
         ("Bash", "commit-quality.sh"),
+        ("Bash", "revert-guard.sh"),
     ],
     "PermissionRequest": [
         # Fires when Codex asks the user to approve a tool call. Our guard
@@ -51,6 +52,7 @@ CODEX_HOOKS: dict[str, list[tuple[str, str]]] = {
     "Stop": [
         ("", "quality-check.sh"),
         ("", "save-session.sh"),
+        ("", "stop-search-check.sh"),
     ],
 }
 

package/scripts/generate_cursor_hooks.py

@@ -43,6 +43,7 @@ CURSOR_HOOKS: dict[str, list[tuple[str, str]]] = {
     "beforeShellExecution": [
         ("", "guard-destructive.sh"),
         ("", "commit-quality.sh"),
+        ("", "revert-guard.sh"),
     ],
     "beforeReadFile": [
         ("", "guard-path.sh"),
@@ -50,6 +51,7 @@ CURSOR_HOOKS: dict[str, list[tuple[str, str]]] = {
     "afterFileEdit": [
         ("", "post-tool-use.sh"),
         ("", "governance-capture.sh"),
+        ("", "test-cohesion.sh"),
     ],
     "beforeSubmitPrompt": [
         ("", "user-prompt-submit.sh"),
@@ -58,6 +60,9 @@ CURSOR_HOOKS: dict[str, list[tuple[str, str]]] = {
     "beforeMCPExecution": [
         ("", "guard-config.sh"),
     ],
+    "afterMCPExecution": [
+        ("", "search-tracker.sh"),
+    ],
     "preCompact": [
         ("", "pre-compact.sh"),
         ("", "pre-compact-save.sh"),
@@ -71,6 +76,7 @@ CURSOR_HOOKS: dict[str, list[tuple[str, str]]] = {
     "stop": [
         ("", "quality-check.sh"),
         ("", "save-session.sh"),
+        ("", "stop-search-check.sh"),
     ],
     "sessionEnd": [
         ("", "session-end.sh"),

package/scripts/generate_gemini_hooks.py

@@ -29,7 +29,7 @@ import json
 import sys
 from pathlib import Path
 
-HOOKS_PREFIX = '"$HOME/.softspark/ai-toolkit/hooks/'
+HOOKS_PREFIX = 'AI_TOOLKIT_HOOK_FORMAT=json "$HOME/.softspark/ai-toolkit/hooks/'
 SOURCE_TAG = "ai-toolkit"
 
 # Event -> list of (matcher, script) pairs. Matcher semantics:
@@ -46,13 +46,16 @@ GEMINI_HOOKS: dict[str, list[tuple[str, str]]] = {
         # run_shell_command covers Bash-equivalent destructive patterns
         ("run_shell_command", "guard-destructive.sh"),
         ("run_shell_command", "commit-quality.sh"),
+        ("run_shell_command", "revert-guard.sh"),
         # File-touching tools — guard paths + config
         ("write_file|edit|replace|read_file", "guard-path.sh"),
         ("write_file|edit|replace", "guard-config.sh"),
     ],
     "AfterTool": [
         ("write_file|edit|replace", "post-tool-use.sh"),
+        ("write_file|edit|replace", "test-cohesion.sh"),
         ("run_shell_command|write_file|edit|replace", "governance-capture.sh"),
+        ("google_web_search|web_fetch", "search-tracker.sh"),
     ],
     "BeforeAgent": [
         ("", "user-prompt-submit.sh"),
@@ -62,6 +65,7 @@ GEMINI_HOOKS: dict[str, list[tuple[str, str]]] = {
         # Closest equivalent to Claude's Stop event. Gemini has no native Stop.
         ("", "quality-check.sh"),
         ("", "save-session.sh"),
+        ("", "stop-search-check.sh"),
     ],
     "BeforeModel": [
         # Light-weight observability slot. Reuses the session-context probe.

package/scripts/generate_windsurf_hooks.py

@@ -41,10 +41,12 @@ WINDSURF_HOOKS: dict[str, list[str]] = {
     "post_write_code": [
         "post-tool-use.sh",
         "governance-capture.sh",
+        "test-cohesion.sh",
     ],
     "pre_run_command": [
         "guard-destructive.sh",
         "commit-quality.sh",
+        "revert-guard.sh",
     ],
     "post_run_command": [
         "governance-capture.sh",
@@ -52,6 +54,9 @@ WINDSURF_HOOKS: dict[str, list[str]] = {
     "pre_mcp_tool_use": [
         "guard-config.sh",
     ],
+    "post_mcp_tool_use": [
+        "search-tracker.sh",
+    ],
     "pre_user_prompt": [
         "user-prompt-submit.sh",
         "track-usage.sh",
@@ -59,6 +64,7 @@ WINDSURF_HOOKS: dict[str, list[str]] = {
     "post_cascade_response": [
         "quality-check.sh",
         "save-session.sh",
+        "stop-search-check.sh",
     ],
     "post_setup_worktree": [
         "session-context.sh",