@softspark/ai-toolkit 4.3.0 → 4.3.2

package/CHANGELOG.md

@@ -7,6 +7,62 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.3.2 - quiet hooks and no-RAG search-first hardening (2026-05-21)
+
+Patch release. Fixes noisy lifecycle hook output in Codex and Claude prompt-submit flows while preserving search-first enforcement and blocking decisions.
+
+### Fixed
+
+- **Quiet Codex startup hooks** - `scripts/generate_codex_hooks.py` now prefixes generated Codex hook commands with `AI_TOOLKIT_HOOK_QUIET=1`, preventing informational `SessionStart` and prompt reminders from appearing as visible hook context.
+- **Quiet Claude prompt-submit hook** - `app/hooks.json` now installs `user-prompt-submit.sh` with `AI_TOOLKIT_HOOK_QUIET=1`, suppressing non-blocking prompt governance output while still arming the per-session search-first flag.
+- **No-RAG false positives** - `_search-capability.sh` now detects search providers from actual MCP server definitions only, so hook matchers and permission allowlists no longer make no-RAG installs block incorrectly.
+- **Codex search tracking gap** - `stop-search-check.sh` now checks the Codex TUI log for search tool calls after the search-first flag timestamp before blocking, covering Codex MCP calls that do not fire the shared `PostToolUse` tracker.
+
+### Changed
+
+- **Hook output helper** - `_hook-io.sh` supports `AI_TOOLKIT_HOOK_QUIET=1` for non-blocking context output.
+- **Runtime hook docs** - `kb/reference/hooks-catalog.md` and `kb/reference/codex-cli-compatibility.md` document quiet mode and the Codex search-first fallback.
+- **Manifest hook count** - `manifest.json` now describes the current 28 hook entries across 14 lifecycle events.
+
+### Tests
+
+- **Hook quiet-mode coverage** - `tests/test_hooks.bats`, `tests/test_codex.bats`, and `tests/test_install.bats` cover quiet mode for `SessionStart`, `UserPromptSubmit`, `PostToolUse`, Codex hook generation, and installed Claude hook configuration.
+- **Search-first flow coverage** - `tests/test_search_first_flow.bats` covers real-provider detection, no-RAG behavior, custom `customer-rag` style providers, and Codex log fallback.
+
+### Ecosystem
+
+- **Snapshot refresh** - `benchmarks/ecosystem-doctor-snapshot.json` refreshed after class A/C upstream documentation and version drift review. No generator contract changes were required.
+
+### Verification
+
+- `npm test` - 1142 passing.
+- `python3 scripts/validate.py --strict` - passed.
+- `python3 scripts/audit_skills.py --ci` - passed with 0 HIGH / 0 WARN.
+
+---
+
+## 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,17 @@
 [![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-1142%20passing-success)](tests/)
 
-## What's New in v4.3.0
+## What's New in v4.3.2
 
-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 noisy hook output and hardens search-first behavior across Claude and Codex.
 
-- **`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.
+- **Quiet hook context**: Codex startup hooks and Claude/Codex `UserPromptSubmit` now suppress non-blocking reminder output while preserving side effects and blocking decisions.
+- **Search provider detection**: search-first hooks now count only real MCP server definitions, not hook matchers or permission allowlists, so no-RAG installs stay advisory instead of blocked.
+- **Codex search-first fallback**: `stop-search-check.sh` recognizes search calls recorded in the Codex TUI log when MCP tool calls do not trigger `PostToolUse`.
+- **Runtime refresh coverage**: installer tests now assert that Claude `UserPromptSubmit` is installed with quiet mode enabled.
+- **Ecosystem snapshot refresh**: release prep refreshed upstream editor/tool drift baselines after class A/C documentation and version drift review.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -125,7 +126,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | `skills/` (hybrid) | 30 | Slash commands with agent knowledge base |
 | `skills/` (knowledge) | 45 | Domain knowledge auto-loaded by agents (includes 13 `<lang>-rules` skills) |
 | `agents/` | 44 | Specialized agents across 10 categories |
-| `hooks/` | 22 global + 5 skill-scoped | Quality gates, path safety, prompt governance, session lifecycle |
+| `hooks/` | 28 entries / 14 events | Quality gates, path safety, prompt governance, session lifecycle |
 | `plugins/` | 11 packs | Opt-in domain bundles (security, research, frontend, enterprise, 6 language packs) |
 | `constitution.md` | 6 articles | Machine-enforced safety rules |
 | `rules/` | auto-injected | Language-specific and custom rules injected into your configs |
@@ -148,7 +149,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 (1142 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.2",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -8,7 +8,7 @@ Universal multi-agent system for software development. Works across all reposito
 |-----------|-------|
 | Agents | See agents catalog |
 | Skills | See skills catalog |
-| Hooks | 12 events / 22 entries (SessionStart ×3, Notification ×1, PreToolUse ×4, UserPromptSubmit ×2, PostToolUse ×2, Stop ×3, TaskCompleted ×1, TeammateIdle ×1, SubagentStart ×1, SubagentStop ×1, PreCompact ×2, SessionEnd ×1) |
+| Hooks | 14 events / 28 entries (SessionStart ×3, Notification ×1, PreToolUse ×5, UserPromptSubmit ×2, PostToolUse ×4, Stop ×4, TaskCompleted ×1, TeammateIdle ×1, SubagentStart ×1, SubagentStop ×1, PreCompact ×2, SessionEnd ×1, InstructionsLoaded ×1, ConfigChange ×1) |
 
 ---
 
@@ -332,7 +332,9 @@ Lead Session (You)
 | `UserPromptSubmit` | Before prompt execution | Prompt governance reminder |
 | `UserPromptSubmit` | Before prompt execution | Usage tracking (skill invocations) |
 | `PostToolUse` | After edit/write tools | Lightweight validation reminder |
+| `PostToolUse` | After search tools | Clears the per-session search-first flag |
 | `Stop` | After Claude response | Multi-language quality check + saves session context |
+| `Stop` | After Claude response | Blocks skipped search-first only when a real MCP/Web search provider is configured, with Codex log fallback |
 | `TaskCompleted` | Teammate marks task done | Multi-language lint + type check (blocking) |
 | `TeammateIdle` | Teammate goes idle | Reminds to verify completeness |
 | `SubagentStart` | Subagent starts | Scope reminder for spawned subagents |
@@ -353,6 +355,9 @@ Lead Session (You)
 
 Language rules are propagated to **all configured editors** — not just Claude. `dir_rules_shared.build_language_rules()` reads `app/rules/<lang>/*.md`, strips frontmatter, and returns combined content per language. Each directory-based generator (Cursor, Windsurf, Cline, Roo, Augment, Antigravity, Codex) emits `ai-toolkit-lang-<lang>` files in its native format. Registered custom rules (`~/.softspark/ai-toolkit/rules/`) are similarly propagated as `ai-toolkit-custom-<name>` files via `build_registered_rules()`.
 
+### Codex Integration
+Codex receives `AGENTS.md`, `.agents/rules/*.md`, optional `.agents/skills/*`, and `.codex/hooks.json`. `generate_codex_hooks.py` emits only Codex-supported lifecycle events and prefixes commands with `AI_TOOLKIT_HOOK_QUIET=1`, so informational hook context is not shown at session start or prompt submit while side effects and blocking Stop decisions still run. Claude's bundled `UserPromptSubmit` hook also runs in quiet mode for the same reason.
+
 ### opencode Integration (v2.5.0+)
 opencode is the 11th supported editor. Five generators handle its integration surface:
 

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'
 }
@@ -44,6 +58,9 @@ hook_new_content() {
 
 hook_emit_context() {
     local message="$1"
+    if [ "${AI_TOOLKIT_HOOK_QUIET:-0}" = "1" ]; then
+        return 0
+    fi
     if [ "${AI_TOOLKIT_HOOK_FORMAT:-}" = "json" ]; then
         jq -nc --arg msg "$message" \
             '{"hookSpecificOutput":{"additionalContext":$msg},"suppressOutput":true}'

package/app/hooks/_search-capability.sh

@@ -24,23 +24,71 @@ ai_toolkit_has_search_provider() {
     [ -n "${AI_TOOLKIT_SEARCH_PROVIDER:-}" ] && return 0
     [ -n "${CLAUDE_SEARCH_PROVIDER:-}" ] && return 0
 
-    local candidates=(
+    local json_candidates=(
         "$PWD/.mcp.json"
+        "$PWD/.claude/settings.local.json"
+        "$PWD/.claude/settings.json"
         "$PWD/.claude/mcp.json"
         "$PWD/.cursor/mcp.json"
         "$PWD/.gemini/settings.json"
+        "$HOME/.mcp.json"
         "$HOME/.claude.json"
         "$HOME/.claude/settings.json"
-        "$HOME/.codex/config.toml"
+        "$HOME/.cursor/mcp.json"
         "$HOME/.gemini/settings.json"
     )
     local path
-    for path in "${candidates[@]}"; do
+    for path in "${json_candidates[@]}"; do
+        [ -f "$path" ] || continue
+        if ai_toolkit_json_has_search_provider "$path"; then
+            return 0
+        fi
+    done
+
+    local toml_candidates=(
+        "$HOME/.codex/config.toml"
+    )
+    for path in "${toml_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
+        if ai_toolkit_toml_has_search_provider "$path"; then
             return 0
         fi
     done
 
     return 1
 }
+
+ai_toolkit_search_provider_pattern() {
+    printf '%s\n' '(^|[^[:alnum:]])(([^[:space:]]*[-_])?rag([-_][^[:space:]]*)?|rag[-_]?mcp|web[-_]?search|search)([^[:alnum:]]|$)'
+}
+
+ai_toolkit_json_has_search_provider() {
+    local path="$1"
+    local pattern
+    pattern="$(ai_toolkit_search_provider_pattern)"
+
+    command -v jq >/dev/null 2>&1 || return 1
+    jq -er '
+        [
+            (.mcpServers // {} | to_entries[]? | .key),
+            (.mcp_servers // {} | to_entries[]? | .key),
+            (.mcp // {} | to_entries[]? | .key)
+        ] | join(" ")
+    ' "$path" 2>/dev/null | grep -Eiq "$pattern"
+}
+
+ai_toolkit_toml_has_search_provider() {
+    local path="$1"
+    local pattern
+    pattern="$(ai_toolkit_search_provider_pattern)"
+
+    awk '
+        /^\[mcp_servers[."]/ {
+            line=$0
+            sub(/^\[mcp_servers[."]?/, "", line)
+            sub(/"\]$/, "", line)
+            sub(/\]$/, "", line)
+            print line
+        }
+    ' "$path" 2>/dev/null | grep -Eiq "$pattern"
+}

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/mcp-health.sh

@@ -45,7 +45,9 @@ for CONFIG in "${CONFIG_FILES[@]}"; do
         [ -z "$CMD" ] && continue
         if ! command -v "$CMD" >/dev/null 2>&1; then
             HINT=$(get_install_hint "$CMD")
-            echo "MCP health: ${SERVER_NAME} command not found (${CMD}). Install with: ${HINT}"
+            if [ "${AI_TOOLKIT_HOOK_QUIET:-0}" != "1" ]; then
+                echo "MCP health: ${SERVER_NAME} command not found (${CMD}). Install with: ${HINT}"
+            fi
         fi
     done <<< "$SERVERS"
 done

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

@@ -2,7 +2,7 @@
 # search-tracker.sh — Clear search-required flag when a search tool runs.
 #
 # Fires on: PostToolUse
-# Matcher: mcp__rag-mcp__smart_query|mcp__rag-mcp__hybrid_search_kb|mcp__rag-mcp__crag_search|mcp__rag-mcp__multi_hop_search|WebSearch|WebFetch
+# Matcher: mcp__.*__(smart_query|hybrid_search_kb|crag_search|multi_hop_search|verify_answer)|WebSearch|WebFetch
 # Non-blocking: always exits 0.
 # Skipped when TOOLKIT_HOOK_PROFILE=minimal.
 #
@@ -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

@@ -4,13 +4,19 @@
 # Fires on: SessionStart (startup|compact)
 # Output goes to Claude's context as plain text.
 
-# 1. Mandatory rules reminder
-echo "MANDATORY: Before answering ANY technical question, apply ALL rules from your CLAUDE.md files (global + project). Follow the exact order of operations defined there. Do NOT skip mandatory steps even if you think you already know the answer."
-echo "REMINDER: When writing features or fixing bugs, ensure tests cover the changes. When modifying API, config, or setup, update relevant documentation. Propose these steps to the user — do not silently skip them."
-
 # shellcheck source=_locate-toolkit.sh
 source "$(dirname "$0")/_locate-toolkit.sh"
 
+emit_context() {
+    if [ "${AI_TOOLKIT_HOOK_QUIET:-0}" != "1" ]; then
+        printf '%s\n' "$1"
+    fi
+}
+
+# 1. Mandatory rules reminder
+emit_context "MANDATORY: Before answering ANY technical question, apply ALL rules from your CLAUDE.md files (global + project). Follow the exact order of operations defined there. Do NOT skip mandatory steps even if you think you already know the answer."
+emit_context "REMINDER: When writing features or fixing bugs, ensure tests cover the changes. When modifying API, config, or setup, update relevant documentation. Propose these steps to the user — do not silently skip them."
+
 # 1a. Reset per-session edit state (used by revert-guard, test-cohesion, quality-gate)
 SESSION_ID_INPUT=""
 if [ ! -t 0 ]; then
@@ -22,10 +28,14 @@ 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
-    echo "$VERSION_MSG"
+    emit_context "$VERSION_MSG"
     # Strip shell/AppleScript/PowerShell metacharacters before interpolating into
     # notification commands. VERSION_MSG is version_check.py output which should
     # be plain ASCII, but sanitize anyway as defense in depth.
@@ -42,20 +52,20 @@ fi
 
 # 3. Load session context (if available)
 SESSION_FILE=".claude/session-context.md"
-if [ -f "$SESSION_FILE" ]; then
-    echo "=== Session Context ==="
+if [ -f "$SESSION_FILE" ] && [ "${AI_TOOLKIT_HOOK_QUIET:-0}" != "1" ]; then
+    printf '%s\n' "=== Session Context ==="
     cat "$SESSION_FILE"
-    echo "====================="
+    printf '%s\n' "====================="
 fi
 
 # 3. Load active instincts (if any)
 INSTINCTS_DIR=".claude/instincts"
-if [ -d "$INSTINCTS_DIR" ] && ls "$INSTINCTS_DIR"/*.md >/dev/null 2>&1; then
-    echo "=== Active Instincts ==="
+if [ -d "$INSTINCTS_DIR" ] && [ "${AI_TOOLKIT_HOOK_QUIET:-0}" != "1" ] && ls "$INSTINCTS_DIR"/*.md >/dev/null 2>&1; then
+    printf '%s\n' "=== Active Instincts ==="
     for f in "$INSTINCTS_DIR"/*.md; do
-        echo "- $(head -1 "$f")"
+        printf '%s\n' "- $(head -1 "$f")"
     done
-    echo "========================"
+    printf '%s\n' "========================"
 fi
 
 exit 0

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
@@ -29,6 +31,59 @@ if ! ai_toolkit_has_search_provider; then
     exit 0
 fi
 
+ai_toolkit_codex_log_has_search_since() {
+    local flag="$1"
+    local log="$HOME/.codex/log/codex-tui.log"
+    [ -f "$log" ] || return 1
+
+    python3 - "$flag" "$log" <<'PY' 2>/dev/null
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+flag_path = Path(sys.argv[1])
+log_path = Path(sys.argv[2])
+try:
+    since = int(flag_path.read_text(encoding="utf-8").splitlines()[0])
+except (OSError, ValueError, IndexError):
+    sys.exit(1)
+
+tool_pattern = re.compile(
+    r"(ToolCall: (mcp__[^ ]*__(smart_query|hybrid_search_kb|crag_search|multi_hop_search|verify_answer)|web_(search|fetch))|"
+    r'tool\.name="(smart_query|hybrid_search_kb|crag_search|multi_hop_search|verify_answer)")',
+    re.IGNORECASE,
+)
+
+try:
+    with log_path.open("rb") as handle:
+        handle.seek(0, 2)
+        size = handle.tell()
+        handle.seek(max(0, size - 2_000_000))
+        lines = handle.read().decode("utf-8", errors="replace").splitlines()
+except OSError:
+    sys.exit(1)
+
+for line in lines:
+    if not tool_pattern.search(line):
+        continue
+    raw_ts = line.split(" ", 1)[0]
+    try:
+        ts = datetime.fromisoformat(raw_ts.replace("Z", "+00:00")).timestamp()
+    except ValueError:
+        continue
+    if ts >= since:
+        sys.exit(0)
+
+sys.exit(1)
+PY
+}
+
+if ai_toolkit_codex_log_has_search_since "$FLAG"; then
+    rm -f "$FLAG" 2>/dev/null
+    exit 0
+fi
+
 # Read the original prompt (line 2 of the flag file) for the reminder.
 PROMPT_PREVIEW=$(sed -n '2p' "$FLAG" 2>/dev/null | head -c 200)
 rm -f "$FLAG" 2>/dev/null  # one-shot; do not loop forever

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/app/hooks.json

@@ -103,7 +103,7 @@
                 "hooks": [
                     {
                         "type": "command",
-                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/user-prompt-submit.sh\""
+                        "command": "AI_TOOLKIT_HOOK_QUIET=1 \"$HOME/.softspark/ai-toolkit/hooks/user-prompt-submit.sh\""
                     }
                 ]
             },
@@ -151,7 +151,7 @@
             },
             {
                 "_source": "ai-toolkit",
-                "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",
+                "matcher": "mcp__.*__(smart_query|hybrid_search_kb|crag_search|multi_hop_search|verify_answer)|WebSearch|WebFetch",
                 "hooks": [
                     {
                         "type": "command",