@softspark/ai-toolkit 4.3.2 → 4.4.0

package/CHANGELOG.md

@@ -7,6 +7,69 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.4.0 - native editor skill pointers and hook governance hardening (2026-05-25)
+
+Minor release. Adds native skill pointer generation for more editor surfaces and hardens search-first governance so quiet hooks still inject model context without noisy transcript output.
+
+### Added
+
+- **Native editor skill pointers** - Added Cursor, Windsurf, and Cline skill pointer generators so supported editors can discover the ai-toolkit skill catalog through their native skill directories.
+- **Shared skill pointer builder** - Added `scripts/skill_pointer.py` to keep generated skill pointer metadata consistent across editor-specific generators.
+- **Release coverage** - Added generator and hook tests covering the new skill pointer outputs, quiet JSON `UserPromptSubmit` context, and noisy Codex search-first log fallback.
+
+### Changed
+
+- **Editor registry and install flow** - Updated supported-tool metadata and install behavior for Cursor, Windsurf, and Cline native skill pointer targets.
+- **Codex hook generation** - `scripts/generate_codex_hooks.py` now emits quiet JSON context for `user-prompt-submit.sh`, matching Claude Code's installed hook behavior.
+- **Hook runtime documentation** - Updated the hooks catalog, Codex compatibility notes, global install model, supported tools registry, and maintenance SOP with the new runtime behavior.
+
+### Fixed
+
+- **Quiet hook context injection** - `_hook-io.sh` now lets `AI_TOOLKIT_HOOK_FORMAT=json` emit `hookSpecificOutput.additionalContext` even when `AI_TOOLKIT_HOOK_QUIET=1` is set.
+- **Search-first false positives in Codex** - `stop-search-check.sh` now scans a larger recent Codex log window and recognizes both `ToolCall: mcp__...__smart_query` and `tool.name="smart_query"` log shapes.
+- **Installed runtime drift** - Claude and Codex hook manifests now install `UserPromptSubmit` with `AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json`.
+
+### Ecosystem
+
+- **Snapshot refresh** - Refreshed the ecosystem doctor snapshot after upstream documentation/content drift review and generator updates.
+
+### Verification
+
+- `bats tests/test_generators.bats`
+- `bats tests/test_cli.bats`
+- `bats tests/test_skills_native.bats tests/test_native_surfaces.bats`
+- `bats tests/test_hooks.bats tests/test_search_first_flow.bats`
+- `bats tests/test_install.bats tests/test_codex.bats`
+- `python3 scripts/validate.py --strict`
+- `git diff --check`
+
+---
+
+## v4.3.3 - silent hook context roll-forward (2026-05-21)
+
+Patch release. Rolls forward the quiet-hook release with a stricter default: non-blocking plain-text hook context is now silent even when a runtime uses a stale or manually copied command without `AI_TOOLKIT_HOOK_QUIET=1`.
+
+### Fixed
+
+- **Silent plain-text context by default** - non-blocking hook context output now requires `AI_TOOLKIT_HOOK_VERBOSE=1` in plain-text mode, so prompt-submit and startup reminders do not leak into the visible chat window.
+- **SessionStart default output** - `session-start.sh` keeps session-state reset, stale search-flag cleanup, and update-notification side effects, but no longer prints startup reminders or loaded context unless verbose mode is enabled.
+
+### Changed
+
+- **Hook output helper** - `_hook-io.sh` supports `AI_TOOLKIT_HOOK_VERBOSE=1` for local debugging while keeping plain-text context silent by default.
+- **Runtime hook docs** - `kb/reference/hooks-catalog.md` and `kb/reference/codex-cli-compatibility.md` document the new silent-by-default behavior and verbose opt-in.
+
+### Tests
+
+- **Silent default coverage** - `tests/test_hooks.bats` now verifies default silence for `SessionStart` and `UserPromptSubmit`, plus verbose opt-in for the same context messages.
+
+### Verification
+
+- `npm test` - 1144 passing.
+- `python3 scripts/validate.py --strict` - passed.
+
+---
+
 ## 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.

package/README.md

@@ -6,17 +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-1142%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1149%20passing-success)](tests/)
 
-## What's New in v4.3.2
+## What's New in v4.4.0
 
-Patch release. Fixes noisy hook output and hardens search-first behavior across Claude and Codex.
+Minor release. Adds native skill pointers for more editor surfaces and hardens quiet hook governance for Claude and Codex.
 
-- **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.
+- **Native editor skills**: Cursor, Windsurf, and Cline now get generated skill pointer catalogs alongside existing rule surfaces.
+- **Quiet JSON governance**: `UserPromptSubmit` keeps output quiet while still injecting `additionalContext` for search-first and workflow reminders.
+- **Codex search-first hardening**: Stop enforcement recognizes current Codex MCP log shapes and tolerates noisy skill-loader output.
+- **Release coverage updated**: generator, install, Codex, hook, and search-first tests cover the new behavior; suite count is 1149 tests.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -102,11 +101,11 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | Platform | Config Files | Scope |
 |----------|-------------|-------|
 | Claude Code | `~/.claude/` | global |
-| Cursor | `.cursor/rules/*.mdc` + `.cursor/mcp.json` | project (`~/.cursor/mcp.json` for MCP only) |
-| Windsurf | `~/.codeium/.../global_rules.md` + `.windsurf/rules/*.md` | global + project |
+| Cursor | `.cursor/rules/*.mdc` + `.cursor/mcp.json` + `.cursor/skills/*` | project (`~/.cursor/mcp.json` for MCP only) |
+| Windsurf | `~/.codeium/.../global_rules.md` + `~/.codeium/windsurf/skills/*` + `.windsurf/rules/*.md` | global + project |
 | Gemini CLI | `~/.gemini/GEMINI.md` | global |
 | GitHub Copilot | `.github/copilot-instructions.md` | project |
-| Cline | `~/Documents/Cline/Rules/*.md` + `.clinerules/*.md` | global + project |
+| Cline | `~/.cline/rules/*.md` + `~/.cline/skills/*` + `.clinerules/*.md` | global + project |
 | Roo Code | `~/.roo/rules/*.md` + `.roomodes` + `.roo/rules/*.md` | global rules + project |
 | Aider | `~/.aider.conf.yml` + `.aider.conf.yml` + `CONVENTIONS.md` | global + project |
 | Augment | `~/.augment/rules/*.md` + `.augment/rules/ai-toolkit-*.md` | global + project |
@@ -149,7 +148,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (1142 tests)
+├── tests/               # Bats test suite (1149 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.2",
+  "version": "4.4.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -356,7 +356,7 @@ 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.
+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 output is not shown at session start or prompt submit while side effects and blocking Stop decisions still run. The `UserPromptSubmit` governance hook also sets `AI_TOOLKIT_HOOK_FORMAT=json` so proactive `additionalContext` reaches the model quietly. Claude's bundled `UserPromptSubmit` hook uses the same quiet JSON context path.
 
 ### opencode Integration (v2.5.0+)
 opencode is the 11th supported editor. Five generators handle its integration surface:

package/app/hooks/_hook-io.sh

@@ -58,13 +58,12 @@ 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}'
-    else
+    elif [ "${AI_TOOLKIT_HOOK_QUIET:-0}" = "1" ]; then
+        return 0
+    elif [ "${AI_TOOLKIT_HOOK_VERBOSE:-0}" = "1" ]; then
         printf '%s\n' "$message"
     fi
 }

package/app/hooks/session-start.sh

@@ -8,9 +8,9 @@
 source "$(dirname "$0")/_locate-toolkit.sh"
 
 emit_context() {
-    if [ "${AI_TOOLKIT_HOOK_QUIET:-0}" != "1" ]; then
-        printf '%s\n' "$1"
-    fi
+    [ "${AI_TOOLKIT_HOOK_QUIET:-0}" = "1" ] && return 0
+    [ "${AI_TOOLKIT_HOOK_VERBOSE:-0}" != "1" ] && return 0
+    printf '%s\n' "$1"
 }
 
 # 1. Mandatory rules reminder
@@ -52,7 +52,7 @@ fi
 
 # 3. Load session context (if available)
 SESSION_FILE=".claude/session-context.md"
-if [ -f "$SESSION_FILE" ] && [ "${AI_TOOLKIT_HOOK_QUIET:-0}" != "1" ]; then
+if [ -f "$SESSION_FILE" ] && [ "${AI_TOOLKIT_HOOK_QUIET:-0}" != "1" ] && [ "${AI_TOOLKIT_HOOK_VERBOSE:-0}" = "1" ]; then
     printf '%s\n' "=== Session Context ==="
     cat "$SESSION_FILE"
     printf '%s\n' "====================="
@@ -60,7 +60,7 @@ fi
 
 # 3. Load active instincts (if any)
 INSTINCTS_DIR=".claude/instincts"
-if [ -d "$INSTINCTS_DIR" ] && [ "${AI_TOOLKIT_HOOK_QUIET:-0}" != "1" ] && ls "$INSTINCTS_DIR"/*.md >/dev/null 2>&1; then
+if [ -d "$INSTINCTS_DIR" ] && [ "${AI_TOOLKIT_HOOK_QUIET:-0}" != "1" ] && [ "${AI_TOOLKIT_HOOK_VERBOSE:-0}" = "1" ] && ls "$INSTINCTS_DIR"/*.md >/dev/null 2>&1; then
     printf '%s\n' "=== Active Instincts ==="
     for f in "$INSTINCTS_DIR"/*.md; do
         printf '%s\n' "- $(head -1 "$f")"

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

@@ -59,7 +59,10 @@ try:
     with log_path.open("rb") as handle:
         handle.seek(0, 2)
         size = handle.tell()
-        handle.seek(max(0, size - 2_000_000))
+        # Codex logs can be noisy between the search call and Stop hook
+        # execution, especially when skill loading emits repeated warnings.
+        # Keep this bounded, but large enough to avoid false positives.
+        handle.seek(max(0, size - 20_000_000))
         lines = handle.read().decode("utf-8", errors="replace").splitlines()
 except OSError:
     sys.exit(1)

package/app/hooks.json

@@ -103,7 +103,7 @@
                 "hooks": [
                     {
                         "type": "command",
-                        "command": "AI_TOOLKIT_HOOK_QUIET=1 \"$HOME/.softspark/ai-toolkit/hooks/user-prompt-submit.sh\""
+                        "command": "AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json \"$HOME/.softspark/ai-toolkit/hooks/user-prompt-submit.sh\""
                     }
                 ]
             },

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-05-21T08:27:23Z",
+  "last_run": "2026-05-25T11:12:53Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,14 +24,21 @@
       }
     },
     "augment": {
-      "docs_hash": "8be23f4fb78816c3",
+      "docs_hash": "2546ce56fc2d92e4",
       "headings": [
+        "Admin",
+        "Auggie CLI",
         "Code",
+        "Cosmos",
         "Documentation Index",
+        "Getting Started",
         "Introduction",
+        "Models & Pricing",
         "On this page",
         "Other automation",
+        "Other clients",
         "Review",
+        "Troubleshooting",
         "\u200bAuggie CLI",
         "\u200bAutomate your SDLC",
         "\u200bCosmos",
@@ -58,7 +65,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "0518086bd4527849",
+      "docs_hash": "78dbdbf9b1b09fe8",
       "headings": [
         "Documentation Index",
         "On this page",
@@ -105,15 +112,20 @@
         "slash command": true,
         "sub-agent": true
       },
-      "version": "2.1.146 (Claude Code)"
+      "version": "2.1.150 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "c2ce2443743365fa",
+      "docs_hash": "0d30b8f46cb45976",
       "headings": [
         "API Reference",
+        "Best Practices",
         "CLI",
         "Cline Overview",
+        "Configurations",
         "Documentation Index",
+        "Features",
+        "Getting Started",
+        "IDE Specific Features",
         "JetBrains Plugin",
         "Kanban",
         "Observability",
@@ -121,6 +133,8 @@
         "SDK",
         "Security & Governance",
         "Team Management",
+        "Troubleshooting",
+        "Usage",
         "VS Code Extension",
         "\u200bAgent Core (SDK)",
         "\u200bApplications",
@@ -142,7 +156,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "70f184b6cdd1f765",
+      "docs_hash": "8cad495445dd03e0",
       "headings": [
         "About",
         "Contributing",
@@ -161,7 +175,7 @@
         "Packages 0",
         "Provide feedback",
         "Quickstart",
-        "Releases 795",
+        "Releases 799",
         "Repository files navigation",
         "Resources",
         "Saved searches",
@@ -191,10 +205,10 @@
         "mcp_servers": false,
         "sandbox": true
       },
-      "version": "codex-cli 0.132.0"
+      "version": "codex-cli 0.133.0"
     },
     "cursor": {
-      "docs_hash": "60edb30c9ddcdadd",
+      "docs_hash": "56c9209877480e01",
       "headings": [],
       "markers": {
         ".cursor/rules": false,
@@ -210,7 +224,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "c6aab087667f7717",
+      "docs_hash": "6a47f9b11ff1527d",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -249,7 +263,7 @@
       }
     },
     "github-copilot": {
-      "docs_hash": "ab274112faeec90f",
+      "docs_hash": "a5b81592ca646743",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot integrations",
@@ -281,7 +295,7 @@
       }
     },
     "google-antigravity": {
-      "docs_hash": "2c48c702b9e592a7",
+      "docs_hash": "6f089d2c7caabceb",
       "headings": [],
       "markers": {
         "AGENTS.md": false,
@@ -297,7 +311,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "5277673e235393f7",
+      "docs_hash": "74eb2d934df9b613",
       "headings": [
         "Add features",
         "Ask questions",
@@ -357,18 +371,23 @@
       }
     },
     "windsurf": {
-      "docs_hash": "fa29ba621f291d81",
+      "docs_hash": "eddf51fabbcaa0a3",
       "headings": [
+        "Accounts",
         "Advanced",
+        "Agent Command Center",
         "App Deploys",
         "Cascade",
         "Context Awareness",
         "Documentation Index",
+        "Editor",
         "MCP",
         "Memories",
         "On this page",
         "Recommended Plugins",
+        "Security",
         "Terminal",
+        "Troubleshooting",
         "Usage",
         "Welcome to Windsurf",
         "Workflows",
@@ -390,11 +409,13 @@
         "AGENTS.md": true,
         "Cascade": true,
         "MCP": true,
+        "SKILL.md": false,
         "always_on": false,
         "glob": true,
         "hooks": true,
         "memories": true,
         "model_decision": false,
+        "skills": true,
         "windsurfrules": false,
         "workflows": true
       }

package/kb/procedures/maintenance-sop.md

@@ -3,9 +3,9 @@ title: "SOP: Claude Toolkit Maintenance"
 category: procedures
 service: ai-toolkit
 tags: [sop, maintenance, agents, skills, install]
-version: "3.0.0"
+version: "3.0.1"
 created: "2026-03-23"
-last_updated: "2026-04-23"
+last_updated: "2026-05-25"
 description: "Standard operating procedures for installing, maintaining, and evolving the ai-toolkit."
 ---
 
@@ -34,7 +34,7 @@ ai-toolkit install --local --editors all                  # all supported editor
 ai-toolkit install --local --editors cursor,aider         # specific editors only
 ```
 
-Supported editors: `cursor`, `windsurf`, `cline`, `roo`, `aider`, `augment`, `copilot`, `antigravity`, `codex`.
+Supported editors: `cursor`, `windsurf`, `cline`, `roo`, `aider`, `augment`, `copilot`, `antigravity`, `codex`, `gemini`, `opencode`.
 
 To restrict which language rules are injected, use `--lang`:
 
@@ -202,6 +202,43 @@ Manual path:
 
 Use `PreToolUse` for blocking validations, `PostToolUse` for non-blocking feedback, `UserPromptSubmit` for prompt governance, and `PreCompact` / `SessionEnd` for context preservation and handoff.
 
+## Troubleshooting Rule Enforcement in Claude Code
+
+Use this when Claude appears to ignore `CLAUDE.md`, `.claude/rules/*.md`, output styles, or search-first rules.
+
+1. **Check current Claude docs first.** Confirm the live contract for memory, settings, output styles, and hooks:
+   - `https://code.claude.com/docs/en/memory`
+   - `https://code.claude.com/docs/en/settings`
+   - `https://code.claude.com/docs/en/output-styles`
+   - `https://code.claude.com/docs/en/hooks`
+2. **Verify instruction loading.** Run `/memory` in Claude Code and confirm the expected `CLAUDE.md`, `CLAUDE.local.md`, and `.claude/rules/*.md` files are listed. Remember that Claude Code reads `CLAUDE.md`, not `AGENTS.md`, unless `CLAUDE.md` imports it.
+3. **Verify the active output style.** Check `.claude/settings.local.json` or `/config`. Output style changes apply after `/clear` or a new session.
+4. **Inspect installed hooks.** Ensure `~/.claude/settings.json` contains the ai-toolkit `UserPromptSubmit` and `Stop` entries. The governance hook must run with `AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json` so it injects `additionalContext` without noisy transcript output.
+5. **Reproduce the hook path directly.**
+   ```bash
+   printf '{"session_id":"debug","prompt":"debug this technical rule issue"}' \
+     | AI_TOOLKIT_SEARCH_FIRST=strict AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json \
+       ~/.softspark/ai-toolkit/hooks/user-prompt-submit.sh
+   ```
+   The output must be valid JSON with `hookSpecificOutput.additionalContext`.
+6. **Check corrective enforcement.** If the assistant still skips required research, `stop-search-check.sh` should block Stop with the search-first message. If it does not, inspect `~/.softspark/ai-toolkit/state/search-required-*.flag` and the Codex/Claude transcript logs.
+7. **Repair drift.** Run:
+   ```bash
+   ai-toolkit update --only hooks
+   python3 scripts/ecosystem_doctor.py --tool claude-code --format text
+   scripts/validate.py
+   ```
+
+## Verification
+
+After changing rule-enforcement behavior, run at minimum:
+
+```bash
+bats tests/test_hooks.bats tests/test_search_first_flow.bats
+bats tests/test_install.bats tests/test_codex.bats
+python3 scripts/validate.py --strict
+```
+
 ## Managing Plugins
 
 ```bash

package/kb/reference/architecture-overview.md

@@ -105,11 +105,11 @@ Machine (global)                              Project (local)
 **`ai-toolkit update`** — re-apply after `npm install -g @softspark/ai-toolkit@latest` or after `add-rule` / `remove-rule`. Same as `install` but semantically correct for update flows.
 
 **`ai-toolkit install --local`** — run per project. Always installs Claude Code configs (CLAUDE.md, settings.local.json, constitution.md, language rules). Editor configs are opt-in via `--editors`:
-- `--editors all` — install all 9 editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity, Codex)
+- `--editors all` — install all 11 editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity, Codex, Gemini, opencode)
 - `--editors cursor,aider` — install only selected editors
 - (no flag) — auto-detect from existing project files; `update --local` picks up whatever editors already have configs
 
-Each editor gets directory-based format (`.cursor/rules/*.mdc`, `.windsurf/rules/*.md`, `.clinerules/*.md`, `.roo/rules/*.md`, `.augment/rules/ai-toolkit-*.md`, `.agent/rules/*.md`, `CONVENTIONS.md`). Codex local install additionally generates `AGENTS.md`, `.agents/rules/*.md`, `.agents/skills/*`, and `.codex/hooks.json`. Hooks are global-only — not merged into project settings except for editor-native local hook files such as Codex `.codex/hooks.json`. Experimental plugin packs can also layer a global Codex target in `HOME` (`~/AGENTS.md`, `~/.agents/`, `~/.codex/hooks.json`) when installed with `ai-toolkit plugin install --editor codex`.
+Each editor gets directory-based format (`.cursor/rules/*.mdc`, `.windsurf/rules/*.md`, `.clinerules/*.md`, `.roo/rules/*.md`, `.augment/rules/ai-toolkit-*.md`, `.agent/rules/*.md`, `CONVENTIONS.md`). Full-profile installs also emit native skill pointer catalogues for Cursor, Windsurf, and Cline. Codex local install additionally generates `AGENTS.md`, `.agents/rules/*.md`, `.agents/skills/*`, and `.codex/hooks.json`. Hooks are global-only — not merged into project settings except for editor-native local hook files such as Codex `.codex/hooks.json`. Experimental plugin packs can also layer a global Codex target in `HOME` (`~/AGENTS.md`, `~/.agents/`, `~/.codex/hooks.json`) when installed with `ai-toolkit plugin install --editor codex`.
 
 If a project already has `.mcp.json`, local install mirrors its `mcpServers` entries into `.claude/settings.local.json` plus any selected editors with project-scoped native MCP files (`.cursor/mcp.json`, `.github/mcp.json`).
 

package/kb/reference/codex-cli-compatibility.md

@@ -3,7 +3,7 @@ title: "AI Toolkit - Codex CLI Compatibility"
 category: reference
 service: ai-toolkit
 tags: [codex, compatibility, install, skills, hooks]
-version: "1.0.1"
+version: "1.0.2"
 created: "2026-04-12"
 last_updated: "2026-05-21"
 description: "Reference for how ai-toolkit maps Claude-oriented skills, hooks, and plugin packs to Codex CLI."
@@ -110,10 +110,16 @@ This means Claude-only events such as `TaskCompleted`, `TeammateIdle`,
 `~/.codex/hooks.json` (global layer). Non-Codex events are silently skipped.
 `remove-hook` cleans both Claude and Codex targets.
 
-Generated Codex hook commands include `AI_TOOLKIT_HOOK_QUIET=1`. This keeps
-non-blocking reminders and startup context out of the visible Codex hook output
-while preserving hook side effects and blocking decisions such as search-first
-Stop enforcement.
+Generated Codex hook commands include `AI_TOOLKIT_HOOK_QUIET=1`. The
+`UserPromptSubmit` governance hook additionally sets `AI_TOOLKIT_HOOK_FORMAT=json`
+so it can pass quiet `additionalContext` before the model responds. This keeps
+non-blocking reminders and startup context out of visible hook output while
+preserving hook side effects, proactive search-first context, and blocking
+decisions such as search-first Stop enforcement.
+
+Plain-text informational hook context is also silent by default in the shared
+hook helper. Set `AI_TOOLKIT_HOOK_VERBOSE=1` only when debugging hook output
+outside the Codex UI.
 
 ## Behavioral Limits
 
@@ -129,6 +135,8 @@ Known limits:
   so `stop-search-check.sh` also checks `~/.codex/log/codex-tui.log` for
   `smart_query`, `hybrid_search_kb`, `crag_search`, `multi_hop_search`, and
   `verify_answer` calls after the search-first flag timestamp before blocking.
+  The scan is bounded to a recent log window, but sized to tolerate noisy Codex
+  skill-loader output between the search call and the Stop hook.
 
 These are runtime platform limits, not installation defects.
 

package/kb/reference/global-install-model.md

@@ -60,10 +60,10 @@ The `--profile` flag controls how much of each editor's native surface is activa
 `ai-toolkit install --editors <name>` can write global files only for editors
 with documented, file-based config surfaces:
 
-- `windsurf`: `~/.codeium/windsurf/memories/global_rules.md`
+- `windsurf`: `~/.codeium/windsurf/memories/global_rules.md` plus `~/.codeium/windsurf/skills/ai-toolkit-skill-catalogue/SKILL.md`
 - `gemini`: `~/.gemini/GEMINI.md`
 - `augment`: `~/.augment/rules/ai-toolkit.md`
-- `cline`: `~/Documents/Cline/Rules/ai-toolkit-*.md`
+- `cline`: `~/.cline/rules/ai-toolkit-*.md` plus `~/.cline/skills/ai-toolkit-skill-catalogue/SKILL.md`
 - `roo`: `~/.roo/rules/ai-toolkit-*.md`
 - `aider`: `~/.aider.conf.yml` plus `~/.aider-ai-toolkit-CONVENTIONS.md` when the YAML file does not already exist
 - `codex`: `~/AGENTS.md`, `~/.agents/rules/*`, `~/.agents/skills/*`, `~/.codex/hooks.json`

package/kb/reference/hooks-catalog.md

@@ -3,9 +3,9 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.5.2"
+version: "1.5.5"
 created: "2026-03-27"
-last_updated: "2026-05-21"
+last_updated: "2026-05-25"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
 ---
 
@@ -50,10 +50,10 @@ ai-toolkit update     # re-copies scripts, re-merges (idempotent)
 3. Loads session context from `.claude/session-context.md` (if exists)
 4. Loads active instincts from `.claude/instincts/*.md` (if any)
 
-When `AI_TOOLKIT_HOOK_QUIET=1`, the hook still performs session-state reset,
-stale search-flag cleanup, and update notification side effects, but suppresses
-all informational stdout so runtimes such as Codex do not show startup hook
-context in the UI.
+By default the hook performs session-state reset, stale search-flag cleanup, and
+update notification side effects without printing informational stdout. Set
+`AI_TOOLKIT_HOOK_VERBOSE=1` to print the startup reminders and loaded context
+for debugging; `AI_TOOLKIT_HOOK_QUIET=1` keeps it silent explicitly.
 
 ### Notification — `notify-waiting.sh`
 
@@ -107,12 +107,18 @@ context in the UI.
 | Script | `~/.softspark/ai-toolkit/hooks/user-prompt-submit.sh` |
 | Fires | Before Claude starts working on a submitted prompt |
 
-**Action:** Adds a lightweight governance reminder: plan mode for architectural work, evidence-first debugging, KB-first research, and validation expectations.
+**Action:** Maintains the per-session search-first flag used by Stop enforcement
+and can provide a lightweight governance reminder: plan mode for architectural
+work, evidence-first debugging, KB-first research, and validation expectations.
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`. The bundled `app/hooks.json`
-registers this command with `AI_TOOLKIT_HOOK_QUIET=1`, so it still arms or
-clears the per-session search-first flag but suppresses the informational
-reminder output.
+registers this command with `AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json`.
+This keeps the hook visually quiet (`suppressOutput: true`) while still
+injecting `hookSpecificOutput.additionalContext` before Claude starts working.
+That context is the proactive half of search-first enforcement; the paired
+`stop-search-check.sh` remains the corrective half. In plain-text mode,
+informational reminders are silent by default and require
+`AI_TOOLKIT_HOOK_VERBOSE=1`.
 
 ### UserPromptSubmit (usage tracking) — `track-usage.sh`
 
@@ -389,7 +395,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-<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.
+**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. Codex Stop enforcement also scans the recent `~/.codex/log/codex-tui.log` window for `ToolCall: mcp__...__smart_query` and `tool.name="smart_query"`-style entries because Codex MCP tool calls may not fire the shared `PostToolUse` tracker. 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.
 
 Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -440,7 +446,7 @@ Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | `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. Honors `AI_TOOLKIT_HOOK_QUIET=1` for non-blocking context output. |
+| `app/hooks/_hook-io.sh` | Shared bash helper that normalizes hook payloads across Claude, Augment, Gemini, Windsurf, and Cursor-style JSON. JSON context output takes precedence over `AI_TOOLKIT_HOOK_QUIET=1`, so quiet hooks can still emit `additionalContext` with `suppressOutput: true`; plain-text output requires `AI_TOOLKIT_HOOK_VERBOSE=1`. |
 | `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
@@ -457,10 +463,11 @@ Set in `.claude/settings.local.json`:
 | `standard` | All hooks (default) |
 | `strict` | Standard + mypy --strict on task completion |
 
-Set `AI_TOOLKIT_HOOK_QUIET=1` on hook commands to suppress non-blocking
-informational context while preserving side effects and blocking decisions.
-Codex-generated hooks use this mode by default, and Claude's bundled
-`UserPromptSubmit` entry uses it to avoid visible prompt hook context.
+Non-blocking informational context is silent in plain-text mode by default while
+side effects and blocking decisions still run. Set `AI_TOOLKIT_HOOK_VERBOSE=1`
+only when debugging hook context locally. `AI_TOOLKIT_HOOK_QUIET=1` keeps hook
+commands explicitly silent, and Codex-generated hooks plus Claude's bundled
+`UserPromptSubmit` entry use it to avoid visible prompt hook context.
 
 ## Architecture