@softspark/ai-toolkit 4.3.3 → 4.4.1

package/CHANGELOG.md

@@ -7,6 +7,60 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.4.1 - Codex hook output compatibility fix (2026-05-25)
+
+Patch release. Fixes Codex `UserPromptSubmit` hook JSON validation failures and visible hook-context noise while preserving hook side effects.
+
+### Fixed
+
+- **Codex `UserPromptSubmit` default output** - generated Codex hooks now keep `user-prompt-submit.sh` in quiet plain-text mode, preserving search-first flag side effects without emitting visible `additionalContext` in the Codex TUI.
+- **Event-specific JSON context** - `hook_emit_context` can include `hookSpecificOutput.hookEventName`, and `user-prompt-submit.sh` emits `"UserPromptSubmit"` with `additionalContext` when JSON context mode is explicitly enabled.
+- **Prompt hook output corruption** - `user-prompt-submit.sh` now suppresses filesystem redirection errors when search-first state writes are blocked by sandboxing or local permissions, keeping JSON output parseable.
+- **Usage tracking tracebacks** - `track-usage.sh` now treats stats writes as best-effort and suppresses Python tracebacks when `~/.softspark/ai-toolkit/stats.json` cannot be written.
+
+### Verification
+
+- `bats tests/test_hooks.bats --filter 'track-usage|user-prompt-submit|post-tool-use'`
+- `python3 scripts/validate.py --strict`
+
+## 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`.

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-1144%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1151%20passing-success)](tests/)
 
-## What's New in v4.3.3
+## What's New in v4.4.1
 
-Patch release. Rolls forward quiet hook handling so informational hook context stays out of the visible chat window even with stale or manually copied hook commands.
+Patch release. Fixes Codex `UserPromptSubmit` hook output validation and visible hook-context noise while preserving hook side effects.
 
-- **Silent hook context by default**: `SessionStart`, `UserPromptSubmit`, and other non-blocking plain-text context output now require `AI_TOOLKIT_HOOK_VERBOSE=1`.
-- **Side effects preserved**: search-first flags, session-state reset, stale-flag cleanup, and blocking decisions still run without printing reminder text.
-- **Runtime refresh applied**: installed hook scripts and Codex/Claude hook config pick up the silent default.
-- **Test coverage updated**: hook tests now cover default silence and verbose opt-in, bringing the suite to 1144 tests.
+- **Codex-safe prompt hook defaults**: generated Codex hooks keep `UserPromptSubmit` side effects quiet without emitting visible `additionalContext` in the TUI.
+- **Event-specific hook context**: JSON context output now includes `hookSpecificOutput.hookEventName` when enabled, matching Codex's event-specific schema.
+- **Silent best-effort stats**: `track-usage.sh` no longer leaks Python tracebacks when local stats writes are blocked.
+- **Sandbox-safe search flags**: search-first flag write failures no longer corrupt JSON hook output.
+- **Release coverage updated**: hook regression coverage now includes blocked state and stats writes; suite count is 1151 tests.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -101,11 +102,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 |
@@ -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 (1144 tests)
+├── tests/               # Bats test suite (1151 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.3",
+  "version": "4.4.1",
   "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

@@ -57,13 +57,18 @@ hook_new_content() {
 }
 
 hook_emit_context() {
-    local message="$1"
-    if [ "${AI_TOOLKIT_HOOK_QUIET:-0}" = "1" ]; then
-        return 0
-    fi
+    local event="${2:+$1}"
+    local message="${2:-$1}"
     if [ "${AI_TOOLKIT_HOOK_FORMAT:-}" = "json" ]; then
-        jq -nc --arg msg "$message" \
-            '{"hookSpecificOutput":{"additionalContext":$msg},"suppressOutput":true}'
+        if [ -n "$event" ]; then
+            jq -nc --arg event "$event" --arg msg "$message" \
+                '{"hookSpecificOutput":{"hookEventName":$event,"additionalContext":$msg},"suppressOutput":true}'
+        else
+            jq -nc --arg msg "$message" \
+                '{"hookSpecificOutput":{"additionalContext":$msg},"suppressOutput":true}'
+        fi
+    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/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/track-usage.sh

@@ -22,10 +22,10 @@ SKILL_NAME=$(printf '%s' "$PROMPT_TEXT" | grep -oE '^/[a-z][a-z0-9-]*' | head -1
 [ -z "$SKILL_NAME" ] && exit 0
 
 # Ensure directory exists
-mkdir -p "$(dirname "$STATS_FILE")"
+mkdir -p "$(dirname "$STATS_FILE")" 2>/dev/null || true
 
 # Atomic update via python3
-python3 - "$STATS_FILE" "$SKILL_NAME" <<'PY'
+python3 - "$STATS_FILE" "$SKILL_NAME" 2>/dev/null <<'PY' || true
 import json
 import sys
 import os

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

@@ -28,9 +28,9 @@ mkdir -p "$STATE_DIR" 2>/dev/null
 if [ "$PROMPT_LEN" -gt 30 ] && \
    [ "${CLAUDE_SKIP_SEARCH_FIRST:-0}" != "1" ] && \
    ai_toolkit_has_search_provider; then
-    printf '%s\n%s\n' "$(date -u +%s)" "$PROMPT_TEXT" > "$FLAG" 2>/dev/null
+    { printf '%s\n%s\n' "$(date -u +%s)" "$PROMPT_TEXT" > "$FLAG"; } 2>/dev/null
 else
-    rm -f "$FLAG" 2>/dev/null
+    { rm -f "$FLAG"; } 2>/dev/null
 fi
 
 if ai_toolkit_has_search_provider; then
@@ -50,6 +50,6 @@ else
 UserPromptSubmit: apply KB-first research, keep changes minimal, and update tests/docs when behavior changes."
 fi
 
-hook_emit_context "$CONTEXT_MSG"
+hook_emit_context "UserPromptSubmit" "$CONTEXT_MSG"
 
 exit 0

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,9 +3,9 @@ title: "AI Toolkit - Codex CLI Compatibility"
 category: reference
 service: ai-toolkit
 tags: [codex, compatibility, install, skills, hooks]
-version: "1.0.2"
+version: "1.0.3"
 created: "2026-04-12"
-last_updated: "2026-05-21"
+last_updated: "2026-05-25"
 description: "Reference for how ai-toolkit maps Claude-oriented skills, hooks, and plugin packs to Codex CLI."
 ---
 
@@ -110,10 +110,27 @@ 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 generated
+`UserPromptSubmit` governance hook does not set `AI_TOOLKIT_HOOK_FORMAT=json`
+by default because Codex currently renders `additionalContext` as visible hook
+context in the TUI. This keeps prompt-submit output quiet while preserving hook
+side effects and blocking decisions such as search-first Stop enforcement.
+
+Codex `UserPromptSubmit` JSON output is event-specific. When emitting context,
+the hook must include the event name alongside the context:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "..."
+  },
+  "suppressOutput": true
+}
+```
+
+Older `{"hookSpecificOutput":{"additionalContext":"..."}}` output can be valid
+JSON but fail newer Codex event-output validation.
 
 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
@@ -133,6 +150,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.3"
+version: "1.5.6"
 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."
 ---
 
@@ -112,11 +112,30 @@ 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. In plain-text mode, informational reminders are silent by
-default and require `AI_TOOLKIT_HOOK_VERBOSE=1`; JSON hook output remains
-available with `AI_TOOLKIT_HOOK_FORMAT=json`.
+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 event-specific JSON context before Claude starts working in runtimes
+that consume hidden context:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "..."
+  },
+  "suppressOutput": true
+}
+```
+
+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`.
+
+Codex-generated hooks intentionally run this script without
+`AI_TOOLKIT_HOOK_FORMAT=json` by default because Codex renders
+`additionalContext` visibly in the TUI; the search-first flag side effect still
+arms the corrective Stop hook.
 
 ### UserPromptSubmit (usage tracking) — `track-usage.sh`
 
@@ -127,7 +146,7 @@ available with `AI_TOOLKIT_HOOK_FORMAT=json`.
 | Script | `~/.softspark/ai-toolkit/hooks/track-usage.sh` |
 | Fires | Before Claude starts working on a submitted prompt |
 
-**Action:** Records skill invocations (slash commands like `/commit`, `/review`) to `~/.softspark/ai-toolkit/stats.json` for local usage analytics. Non-slash prompts are ignored.
+**Action:** Records skill invocations (slash commands like `/commit`, `/review`) to `~/.softspark/ai-toolkit/stats.json` for local usage analytics. Non-slash prompts are ignored. Stats writes are best-effort and stay silent if the local state path is not writable.
 
 ### PostToolUse (edit feedback) — `post-tool-use.sh`
 
@@ -393,7 +412,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`.
 
@@ -444,7 +463,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` and `AI_TOOLKIT_HOOK_VERBOSE=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