@softspark/ai-toolkit 4.4.0 → 4.4.1

package/CHANGELOG.md

@@ -7,6 +7,22 @@ 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.

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-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.1
 
-Minor release. Adds native skill pointers for more editor surfaces and hardens quiet hook governance for Claude and Codex.
+Patch release. Fixes Codex `UserPromptSubmit` hook output validation and visible hook-context noise while preserving hook side effects.
 
-- **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.
+- **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.
 
@@ -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 (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.1",
   "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/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/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.4.0",
+  "version": "4.4.1",
   "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.1",
   "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/generate_codex_hooks.py

@@ -25,10 +25,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 +62,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)