@softspark/ai-toolkit 4.4.0 → 4.4.2

package/CHANGELOG.md

@@ -7,6 +7,42 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.4.2 - Ecosystem sync: Claude Code 2.1.158 + Codex 0.134 hook events (2026-05-30)
+
+Patch release. Syncs the tool registry and `hook-creator` skill with newly detected upstream hook events and refreshes the ecosystem drift snapshot. No generated output or runtime behavior changes.
+
+### Changed
+
+- **Claude Code hook events** - Recorded `MessageDisplay` (new in Claude Code 2.1.152) in `scripts/ecosystem_tools.json` and the `hook-creator` skill's Supported Hook Events table. Also added three real-but-untracked events to the registry: `PostToolUseFailure`, `PostToolBatch`, `UserPromptExpansion`.
+- **Codex hook events** - Recorded the four Codex events we did not track (`PreCompact`, `PostCompact`, `SubagentStart`, `SubagentStop`); Codex exposes 10 lifecycle events. Updated the `scripts/generate_codex_hooks.py` docstring (6 to 10) and `kb/reference/supported-tools-registry.md`.
+- **Ecosystem snapshot** - Refreshed `benchmarks/ecosystem-doctor-snapshot.json` to baseline Claude Code 2.1.158 and Codex 0.134, and bumped the registry `last_updated`.
+
+### Ecosystem
+
+- Class-B drift (new Claude Code and Codex hook events) tracked in the registry and skill docs; wiring the Codex subagent/compaction events into generated `.codex/hooks.json` is deferred to a future release. GitHub Copilot docs reorg classified class C (not adopted). Seven editors showed cosmetic-only doc drift (class A).
+
+### Verification
+
+- `python3 scripts/validate.py --strict`
+- `python3 scripts/ecosystem_doctor.py --offline --check`
+- `npm test` (1151 passing)
+
+## 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.

package/README.md

@@ -6,16 +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-1149%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1151%20passing-success)](tests/)
 
-## What's New in v4.4.0
+## What's New in v4.4.2
 
-Minor release. Adds native skill pointers for more editor surfaces and hardens quiet hook governance for Claude and Codex.
+Patch release. Syncs the tool registry and `hook-creator` skill with newly detected upstream hook events and refreshes the ecosystem drift snapshot. No generated output or runtime behavior changes.
 
-- **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.
+- **Claude Code `MessageDisplay`**: the hook event added in Claude Code 2.1.152 is now tracked in the registry and documented in the `hook-creator` skill.
+- **Three more Claude Code events tracked**: `PostToolUseFailure`, `PostToolBatch`, and `UserPromptExpansion` were real but missing from the registry.
+- **Codex hook events**: recorded the four untracked Codex events (`PreCompact`, `PostCompact`, `SubagentStart`, `SubagentStop`); Codex exposes 10 lifecycle events total.
+- **Drift snapshot refreshed**: baselined Claude Code 2.1.158 and Codex 0.134; `ecosystem_doctor.py --check` is green.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -148,7 +148,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (1149 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.4.0",
+  "version": "4.4.2",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/hooks/_hook-io.sh

@@ -57,10 +57,16 @@ hook_new_content() {
 }
 
 hook_emit_context() {
-    local message="$1"
+    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

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/skills/hook-creator/SKILL.md

@@ -23,6 +23,7 @@ Create a new Claude Code hook following ai-toolkit conventions.
 | `SessionEnd` | Session is closing | any | Flush logs, save transcripts |
 | `UserPromptSubmit` | User submits a prompt | any | Prompt governance, usage tracking |
 | `Notification` | Claude sends a notification | any | OS alerts, Slack pings |
+| `MessageDisplay` | Assistant message is about to be shown to the user | any | Transform or hide assistant message text before display |
 
 ### Tool lifecycle
 

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-05-25T11:12:53Z",
+  "last_run": "2026-05-30T19:51:17Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,7 +24,7 @@
       }
     },
     "augment": {
-      "docs_hash": "2546ce56fc2d92e4",
+      "docs_hash": "46ef1d20d537234f",
       "headings": [
         "Admin",
         "Auggie CLI",
@@ -65,11 +65,15 @@
       }
     },
     "claude-code": {
-      "docs_hash": "78dbdbf9b1b09fe8",
+      "docs_hash": "b2ee6850b58cee40",
       "headings": [
+        "Core concepts",
         "Documentation Index",
+        "Getting started",
         "On this page",
         "Overview",
+        "Platforms and integrations",
+        "Use Claude Code",
         "\u200bGet started",
         "\u200bNext steps",
         "\u200bUse Claude Code everywhere",
@@ -83,11 +87,14 @@
         "FileChanged": false,
         "InstructionsLoaded": false,
         "MCP server": true,
+        "MessageDisplay": false,
         "Notification": true,
         "PermissionDenied": false,
         "PermissionRequest": false,
         "PostCompact": false,
+        "PostToolBatch": false,
         "PostToolUse": true,
+        "PostToolUseFailure": false,
         "PreCompact": false,
         "PreToolUse": true,
         "SKILL.md": true,
@@ -101,6 +108,7 @@
         "TaskCompleted": false,
         "TaskCreated": false,
         "TeammateIdle": false,
+        "UserPromptExpansion": false,
         "UserPromptSubmit": false,
         "WorktreeCreate": false,
         "WorktreeRemove": false,
@@ -112,10 +120,10 @@
         "slash command": true,
         "sub-agent": true
       },
-      "version": "2.1.150 (Claude Code)"
+      "version": "2.1.158 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "0d30b8f46cb45976",
+      "docs_hash": "9ec25e5132332d2f",
       "headings": [
         "API Reference",
         "Best Practices",
@@ -156,7 +164,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "8cad495445dd03e0",
+      "docs_hash": "f7a6a5144e0f61a2",
       "headings": [
         "About",
         "Contributing",
@@ -175,7 +183,7 @@
         "Packages 0",
         "Provide feedback",
         "Quickstart",
-        "Releases 799",
+        "Releases 804",
         "Repository files navigation",
         "Resources",
         "Saved searches",
@@ -193,10 +201,14 @@
         "AGENTS.md": true,
         "config.toml": false,
         "hook event: PermissionRequest": false,
+        "hook event: PostCompact": false,
         "hook event: PostToolUse": false,
+        "hook event: PreCompact": false,
         "hook event: PreToolUse": false,
         "hook event: SessionStart": false,
         "hook event: Stop": false,
+        "hook event: SubagentStart": false,
+        "hook event: SubagentStop": false,
         "hook event: UserPromptSubmit": false,
         "hook handler: agent": false,
         "hook handler: command": false,
@@ -205,10 +217,10 @@
         "mcp_servers": false,
         "sandbox": true
       },
-      "version": "codex-cli 0.133.0"
+      "version": "codex-cli 0.134.0"
     },
     "cursor": {
-      "docs_hash": "56c9209877480e01",
+      "docs_hash": "6aa8a8d7cc046f13",
       "headings": [],
       "markers": {
         ".cursor/rules": false,
@@ -224,7 +236,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "6a47f9b11ff1527d",
+      "docs_hash": "5569709cc2e463a8",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -263,16 +275,16 @@
       }
     },
     "github-copilot": {
-      "docs_hash": "a5b81592ca646743",
+      "docs_hash": "56ac2d5768f930b5",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot integrations",
         "About agent management",
         "About agent skills",
         "About billing for GitHub Copilot in organizations and enterprises",
-        "About billing for individual GitHub Copilot plans",
         "About custom agents",
         "About customizing GitHub Copilot responses",
+        "About enterprise accounts for Copilot Business",
         "Articles",
         "Did you find what you needed?",
         "GitHub Copilot",
@@ -295,7 +307,7 @@
       }
     },
     "google-antigravity": {
-      "docs_hash": "6f089d2c7caabceb",
+      "docs_hash": "f933b31ac7414c29",
       "headings": [],
       "markers": {
         "AGENTS.md": false,
@@ -311,7 +323,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "74eb2d934df9b613",
+      "docs_hash": "fe7f7590e4553574",
       "headings": [
         "Add features",
         "Ask questions",
@@ -371,7 +383,7 @@
       }
     },
     "windsurf": {
-      "docs_hash": "eddf51fabbcaa0a3",
+      "docs_hash": "a30041baf564742f",
       "headings": [
         "Accounts",
         "Advanced",

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,12 +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`. 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.
+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

package/kb/reference/hooks-catalog.md

@@ -3,7 +3,7 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.5.5"
+version: "1.5.6"
 created: "2026-03-27"
 last_updated: "2026-05-25"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
@@ -114,12 +114,29 @@ 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 AI_TOOLKIT_HOOK_FORMAT=json`.
 This keeps the hook visually quiet (`suppressOutput: true`) while still
-injecting `hookSpecificOutput.additionalContext` before Claude starts working.
+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`
 
 | Field | Value |
@@ -129,7 +146,7 @@ informational reminders are silent by default and require
 | 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`
 

package/kb/reference/mcp-editor-compatibility.md

@@ -5,7 +5,7 @@ service: ai-toolkit
 tags: [mcp, editors, compatibility, codex, cursor]
 version: "1.1.0"
 created: "2026-04-12"
-last_updated: "2026-04-28"
+last_updated: "2026-05-30"
 description: "Official MCP support matrix and native config targets for editors supported by ai-toolkit."
 ---
 

package/kb/reference/supported-tools-registry.md

@@ -5,7 +5,7 @@ service: ai-toolkit
 tags: [editors, platforms, generators, integration, ecosystem]
 version: "1.3.0"
 created: "2026-04-23"
-last_updated: "2026-05-25"
+last_updated: "2026-05-30"
 description: "Human-readable view of scripts/ecosystem_tools.json — the canonical list of tools ai-toolkit integrates with (Claude Code + 11 editors), their documentation URLs, config paths, our generators, and tracked capability markers."
 ---
 
@@ -30,7 +30,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Release notes | https://github.com/anthropics/claude-code/releases |
 | Config paths | `~/.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, `~/.claude/themes/*.json` (v2.1.118+) |
 | Our generators | — (Claude Code is the primary target; toolkit content ships directly as `.md` files and `settings.json` merges) |
-| Tracked hook events | Core: `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `Notification`. Tool: `PreToolUse`, `PostToolUse`. Turn: `Stop`, `StopFailure`. Subagent: `SubagentStart`, `SubagentStop`. Compaction: `PreCompact`, `PostCompact`. Permissions: `PermissionRequest`, `PermissionDenied`. Elicitation: `Elicitation`, `ElicitationResult`. Teams: `TaskCreated`, `TaskCompleted`, `TeammateIdle`. Worktrees/env: `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `FileChanged`, `ConfigChange`. Setup: `Setup`, `InstructionsLoaded` |
+| Tracked hook events | Core: `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `Notification`, `MessageDisplay`. Tool: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`. Turn: `Stop`, `StopFailure`, `UserPromptExpansion`. Subagent: `SubagentStart`, `SubagentStop`. Compaction: `PreCompact`, `PostCompact`. Permissions: `PermissionRequest`, `PermissionDenied`. Elicitation: `Elicitation`, `ElicitationResult`. Teams: `TaskCreated`, `TaskCompleted`, `TeammateIdle`. Worktrees/env: `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `FileChanged`, `ConfigChange`. Setup: `Setup`, `InstructionsLoaded` |
 | Tracked handler types | `command`, `prompt`, `agent`, `mcp_tool` |
 | Other capabilities | slash commands, MCP server/client, sub-agent, output style, `SKILL.md` (≥500 lines warn) |
 | Version probe | `claude --version` |
@@ -163,7 +163,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Release notes | https://github.com/openai/codex/releases |
 | Config paths | `AGENTS.md`, `.agents/rules/*.md`, `.agents/skills/*/SKILL.md`, `.codex/hooks.json`, `~/.codex/config.toml` |
 | Our generators | `scripts/generate_codex.py`, `scripts/generate_codex_rules.py`, `scripts/generate_codex_hooks.py`, `scripts/generate_codex_skills.py` (opt-in via `--codex-skills`) |
-| Tracked hook events | `PreToolUse`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, `Stop`, `PermissionRequest` (6 events supported upstream in `config.toml`) |
+| Tracked hook events | Upstream canonical (codex-rs `HookEventName` enum): `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`, `SessionStart`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `Stop` (10 events). We currently wire a subset: `SessionStart`, `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`. |
 | Tracked handler types | `command` (emitted by default); `prompt` and `agent` available upstream but authored by hand |
 | Other capabilities | `AGENTS.md`, `config.toml`, `mcp_servers`, sandbox policies, `.agents/skills/*/SKILL.md` (native Codex skill discovery path) |
 | Version probe | `codex --version` |

package/llms-full.txt

@@ -6965,9 +6965,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."
 ---
 
@@ -7072,12 +7072,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`. 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.
+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
@@ -8880,7 +8895,7 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.5.5"
+version: "1.5.6"
 created: "2026-03-27"
 last_updated: "2026-05-25"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
@@ -8991,12 +9006,29 @@ 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 AI_TOOLKIT_HOOK_FORMAT=json`.
 This keeps the hook visually quiet (`suppressOutput: true`) while still
-injecting `hookSpecificOutput.additionalContext` before Claude starts working.
+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`
 
 | Field | Value |
@@ -9006,7 +9038,7 @@ informational reminders are silent by default and require
 | 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`
 
@@ -9988,7 +10020,7 @@ service: ai-toolkit
 tags: [mcp, editors, compatibility, codex, cursor]
 version: "1.1.0"
 created: "2026-04-12"
-last_updated: "2026-04-28"
+last_updated: "2026-05-30"
 description: "Official MCP support matrix and native config targets for editors supported by ai-toolkit."
 ---
 
@@ -11716,7 +11748,7 @@ service: ai-toolkit
 tags: [editors, platforms, generators, integration, ecosystem]
 version: "1.3.0"
 created: "2026-04-23"
-last_updated: "2026-05-25"
+last_updated: "2026-05-30"
 description: "Human-readable view of scripts/ecosystem_tools.json — the canonical list of tools ai-toolkit integrates with (Claude Code + 11 editors), their documentation URLs, config paths, our generators, and tracked capability markers."
 ---
 
@@ -11741,7 +11773,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Release notes | https://github.com/anthropics/claude-code/releases |
 | Config paths | `~/.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, `~/.claude/themes/*.json` (v2.1.118+) |
 | Our generators | — (Claude Code is the primary target; toolkit content ships directly as `.md` files and `settings.json` merges) |
-| Tracked hook events | Core: `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `Notification`. Tool: `PreToolUse`, `PostToolUse`. Turn: `Stop`, `StopFailure`. Subagent: `SubagentStart`, `SubagentStop`. Compaction: `PreCompact`, `PostCompact`. Permissions: `PermissionRequest`, `PermissionDenied`. Elicitation: `Elicitation`, `ElicitationResult`. Teams: `TaskCreated`, `TaskCompleted`, `TeammateIdle`. Worktrees/env: `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `FileChanged`, `ConfigChange`. Setup: `Setup`, `InstructionsLoaded` |
+| Tracked hook events | Core: `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `Notification`, `MessageDisplay`. Tool: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`. Turn: `Stop`, `StopFailure`, `UserPromptExpansion`. Subagent: `SubagentStart`, `SubagentStop`. Compaction: `PreCompact`, `PostCompact`. Permissions: `PermissionRequest`, `PermissionDenied`. Elicitation: `Elicitation`, `ElicitationResult`. Teams: `TaskCreated`, `TaskCompleted`, `TeammateIdle`. Worktrees/env: `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `FileChanged`, `ConfigChange`. Setup: `Setup`, `InstructionsLoaded` |
 | Tracked handler types | `command`, `prompt`, `agent`, `mcp_tool` |
 | Other capabilities | slash commands, MCP server/client, sub-agent, output style, `SKILL.md` (≥500 lines warn) |
 | Version probe | `claude --version` |
@@ -11874,7 +11906,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Release notes | https://github.com/openai/codex/releases |
 | Config paths | `AGENTS.md`, `.agents/rules/*.md`, `.agents/skills/*/SKILL.md`, `.codex/hooks.json`, `~/.codex/config.toml` |
 | Our generators | `scripts/generate_codex.py`, `scripts/generate_codex_rules.py`, `scripts/generate_codex_hooks.py`, `scripts/generate_codex_skills.py` (opt-in via `--codex-skills`) |
-| Tracked hook events | `PreToolUse`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, `Stop`, `PermissionRequest` (6 events supported upstream in `config.toml`) |
+| Tracked hook events | Upstream canonical (codex-rs `HookEventName` enum): `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`, `SessionStart`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `Stop` (10 events). We currently wire a subset: `SessionStart`, `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`. |
 | Tracked handler types | `command` (emitted by default); `prompt` and `agent` available upstream but authored by hand |
 | Other capabilities | `AGENTS.md`, `config.toml`, `mcp_servers`, sandbox policies, `.agents/skills/*/SKILL.md` (native Codex skill discovery path) |
 | Version probe | `codex --version` |

package/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.4.0",
+  "version": "4.4.2",
   "description": "AI coding toolkit: 107 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",

package/scripts/ecosystem_tools.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "description": "Authoritative registry of tools ai-toolkit integrates with. Consumed by scripts/ecosystem_doctor.py to detect upstream doc/version drift.",
-  "last_updated": "2026-05-25",
+  "last_updated": "2026-05-30",
   "tools": [
     {
       "id": "claude-code",
@@ -24,12 +24,16 @@
       "capability_markers": [
         "PreToolUse",
         "PostToolUse",
+        "PostToolUseFailure",
+        "PostToolBatch",
         "SessionStart",
         "SessionEnd",
         "SubagentStart",
         "SubagentStop",
         "UserPromptSubmit",
+        "UserPromptExpansion",
         "Notification",
+        "MessageDisplay",
         "Stop",
         "StopFailure",
         "PreCompact",
@@ -452,6 +456,10 @@
         "hook event: UserPromptSubmit",
         "hook event: Stop",
         "hook event: PermissionRequest",
+        "hook event: PreCompact",
+        "hook event: PostCompact",
+        "hook event: SubagentStart",
+        "hook event: SubagentStop",
         "hook handler: command",
         "hook handler: prompt",
         "hook handler: agent",

package/scripts/generate_codex_hooks.py

@@ -4,10 +4,11 @@
 Maps compatible ai-toolkit hooks to Codex lifecycle events.
 Hook scripts are shared with Claude Code (stored in ~/.softspark/ai-toolkit/hooks/).
 
-Codex supports 6 events (PascalCase in config.toml / hooks.json):
-``PreToolUse``, ``PostToolUse``, ``PermissionRequest``, ``SessionStart``,
-``UserPromptSubmit``, ``Stop``. PreToolUse/PostToolUse only support
-the ``Bash`` matcher.
+Codex exposes 10 lifecycle events (PascalCase in config.toml / hooks.json):
+``PreToolUse``, ``PostToolUse``, ``PermissionRequest``, ``PreCompact``,
+``PostCompact``, ``SessionStart``, ``UserPromptSubmit``, ``SubagentStart``,
+``SubagentStop``, ``Stop``. PreToolUse/PostToolUse only support the ``Bash``
+matcher. We currently wire the subset defined in ``CODEX_HOOKS`` below.
 
 Handler types in Codex: ``command`` (what we emit), ``prompt``, and ``agent``.
 Reference: codex-rs/config/src/hook_config.rs.
@@ -25,10 +26,6 @@ from pathlib import Path
 
 
 HOOKS_PREFIX = 'AI_TOOLKIT_HOOK_QUIET=1 "$HOME/.softspark/ai-toolkit/hooks/'
-HOOKS_JSON_CONTEXT_PREFIX = (
-    'AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json "$HOME/.softspark/ai-toolkit/hooks/'
-)
-
 # Hooks compatible with Codex, grouped by event.
 # Format: (matcher, script_name)
 CODEX_HOOKS: dict[str, list[tuple[str, str]]] = {
@@ -66,12 +63,7 @@ def build_hooks_json() -> dict:
     for event, entries in CODEX_HOOKS.items():
         hooks[event] = []
         for matcher, script in entries:
-            prefix = (
-                HOOKS_JSON_CONTEXT_PREFIX
-                if event == "UserPromptSubmit" and script == "user-prompt-submit.sh"
-                else HOOKS_PREFIX
-            )
-            entry: dict = {"hooks": [{"type": "command", "command": f"{prefix}{script}\""}]}
+            entry: dict = {"hooks": [{"type": "command", "command": f"{HOOKS_PREFIX}{script}\""}]}
             if matcher:
                 entry["matcher"] = matcher
             hooks[event].append(entry)