@softspark/ai-toolkit 4.3.2 → 4.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +8 -9
  3. package/app/.claude-plugin/plugin.json +1 -1
  4. package/app/hooks/_hook-io.sh +1 -1
  5. package/app/hooks/session-start.sh +5 -5
  6. package/kb/reference/codex-cli-compatibility.md +5 -1
  7. package/kb/reference/hooks-catalog.md +17 -12
  8. package/llms-full.txt +22 -13
  9. package/manifest.json +1 -1
  10. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -7,6 +7,31 @@ Versioning follows [Semantic Versioning](https://semver.org/).
7
7
 
8
8
  ---
9
9
 
10
+ ## v4.3.3 - silent hook context roll-forward (2026-05-21)
11
+
12
+ 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`.
13
+
14
+ ### Fixed
15
+
16
+ - **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.
17
+ - **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.
18
+
19
+ ### Changed
20
+
21
+ - **Hook output helper** - `_hook-io.sh` supports `AI_TOOLKIT_HOOK_VERBOSE=1` for local debugging while keeping plain-text context silent by default.
22
+ - **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.
23
+
24
+ ### Tests
25
+
26
+ - **Silent default coverage** - `tests/test_hooks.bats` now verifies default silence for `SessionStart` and `UserPromptSubmit`, plus verbose opt-in for the same context messages.
27
+
28
+ ### Verification
29
+
30
+ - `npm test` - 1144 passing.
31
+ - `python3 scripts/validate.py --strict` - passed.
32
+
33
+ ---
34
+
10
35
  ## v4.3.2 - quiet hooks and no-RAG search-first hardening (2026-05-21)
11
36
 
12
37
  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 CHANGED
@@ -6,17 +6,16 @@
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
7
7
  [![Skills](https://img.shields.io/badge/skills-107-brightgreen)](app/skills/)
8
8
  [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
9
- [![Tests](https://img.shields.io/badge/tests-1142%20passing-success)](tests/)
9
+ [![Tests](https://img.shields.io/badge/tests-1144%20passing-success)](tests/)
10
10
 
11
- ## What's New in v4.3.2
11
+ ## What's New in v4.3.3
12
12
 
13
- Patch release. Fixes noisy hook output and hardens search-first behavior across Claude and Codex.
13
+ 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.
14
14
 
15
- - **Quiet hook context**: Codex startup hooks and Claude/Codex `UserPromptSubmit` now suppress non-blocking reminder output while preserving side effects and blocking decisions.
16
- - **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.
17
- - **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`.
18
- - **Runtime refresh coverage**: installer tests now assert that Claude `UserPromptSubmit` is installed with quiet mode enabled.
19
- - **Ecosystem snapshot refresh**: release prep refreshed upstream editor/tool drift baselines after class A/C documentation and version drift review.
15
+ - **Silent hook context by default**: `SessionStart`, `UserPromptSubmit`, and other non-blocking plain-text context output now require `AI_TOOLKIT_HOOK_VERBOSE=1`.
16
+ - **Side effects preserved**: search-first flags, session-state reset, stale-flag cleanup, and blocking decisions still run without printing reminder text.
17
+ - **Runtime refresh applied**: installed hook scripts and Codex/Claude hook config pick up the silent default.
18
+ - **Test coverage updated**: hook tests now cover default silence and verbose opt-in, bringing the suite to 1144 tests.
20
19
 
21
20
  See [CHANGELOG.md](CHANGELOG.md) for full history.
22
21
 
@@ -149,7 +148,7 @@ ai-toolkit/
149
148
  │ └── ARCHITECTURE.md # Full system design
150
149
  ├── kb/ # Reference docs, procedures, plans
151
150
  ├── scripts/ # Validation, install, evaluation scripts
152
- ├── tests/ # Bats test suite (1142 tests)
151
+ ├── tests/ # Bats test suite (1144 tests)
153
152
  └── CHANGELOG.md
154
153
  ```
155
154
 
package/app/.claude-plugin/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "ai-toolkit",
3
3
  "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.",
4
- "version": "4.3.2",
4
+ "version": "4.3.3",
5
5
  "author": {
6
6
  "name": "SoftSpark",
7
7
  "url": "https://github.com/softspark"
package/app/hooks/_hook-io.sh CHANGED
@@ -64,7 +64,7 @@ hook_emit_context() {
64
64
  if [ "${AI_TOOLKIT_HOOK_FORMAT:-}" = "json" ]; then
65
65
  jq -nc --arg msg "$message" \
66
66
  '{"hookSpecificOutput":{"additionalContext":$msg},"suppressOutput":true}'
67
- else
67
+ elif [ "${AI_TOOLKIT_HOOK_VERBOSE:-0}" = "1" ]; then
68
68
  printf '%s\n' "$message"
69
69
  fi
70
70
  }
package/app/hooks/session-start.sh CHANGED
@@ -8,9 +8,9 @@
8
8
  source "$(dirname "$0")/_locate-toolkit.sh"
9
9
 
10
10
  emit_context() {
11
- if [ "${AI_TOOLKIT_HOOK_QUIET:-0}" != "1" ]; then
12
- printf '%s\n' "$1"
13
- fi
11
+ [ "${AI_TOOLKIT_HOOK_QUIET:-0}" = "1" ] && return 0
12
+ [ "${AI_TOOLKIT_HOOK_VERBOSE:-0}" != "1" ] && return 0
13
+ printf '%s\n' "$1"
14
14
  }
15
15
 
16
16
  # 1. Mandatory rules reminder
@@ -52,7 +52,7 @@ fi
52
52
 
53
53
  # 3. Load session context (if available)
54
54
  SESSION_FILE=".claude/session-context.md"
55
- if [ -f "$SESSION_FILE" ] && [ "${AI_TOOLKIT_HOOK_QUIET:-0}" != "1" ]; then
55
+ if [ -f "$SESSION_FILE" ] && [ "${AI_TOOLKIT_HOOK_QUIET:-0}" != "1" ] && [ "${AI_TOOLKIT_HOOK_VERBOSE:-0}" = "1" ]; then
56
56
  printf '%s\n' "=== Session Context ==="
57
57
  cat "$SESSION_FILE"
58
58
  printf '%s\n' "====================="
@@ -60,7 +60,7 @@ fi
60
60
 
61
61
  # 3. Load active instincts (if any)
62
62
  INSTINCTS_DIR=".claude/instincts"
63
- if [ -d "$INSTINCTS_DIR" ] && [ "${AI_TOOLKIT_HOOK_QUIET:-0}" != "1" ] && ls "$INSTINCTS_DIR"/*.md >/dev/null 2>&1; then
63
+ 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
64
64
  printf '%s\n' "=== Active Instincts ==="
65
65
  for f in "$INSTINCTS_DIR"/*.md; do
66
66
  printf '%s\n' "- $(head -1 "$f")"
package/kb/reference/codex-cli-compatibility.md CHANGED
@@ -3,7 +3,7 @@ title: "AI Toolkit - Codex CLI Compatibility"
3
3
  category: reference
4
4
  service: ai-toolkit
5
5
  tags: [codex, compatibility, install, skills, hooks]
6
- version: "1.0.1"
6
+ version: "1.0.2"
7
7
  created: "2026-04-12"
8
8
  last_updated: "2026-05-21"
9
9
  description: "Reference for how ai-toolkit maps Claude-oriented skills, hooks, and plugin packs to Codex CLI."
@@ -115,6 +115,10 @@ non-blocking reminders and startup context out of the visible Codex hook output
115
115
  while preserving hook side effects and blocking decisions such as search-first
116
116
  Stop enforcement.
117
117
 
118
+ Plain-text informational hook context is also silent by default in the shared
119
+ hook helper. Set `AI_TOOLKIT_HOOK_VERBOSE=1` only when debugging hook output
120
+ outside the Codex UI.
121
+
118
122
  ## Behavioral Limits
119
123
 
120
124
  Codex wrappers preserve workflow intent, but not every Claude runtime behavior
package/kb/reference/hooks-catalog.md CHANGED
@@ -3,7 +3,7 @@ title: "Hooks Catalog"
3
3
  category: reference
4
4
  service: ai-toolkit
5
5
  tags: [hooks, quality, safety, enforcement, settings.json]
6
- version: "1.5.2"
6
+ version: "1.5.3"
7
7
  created: "2026-03-27"
8
8
  last_updated: "2026-05-21"
9
9
  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)
50
50
  3. Loads session context from `.claude/session-context.md` (if exists)
51
51
  4. Loads active instincts from `.claude/instincts/*.md` (if any)
52
52
 
53
- When `AI_TOOLKIT_HOOK_QUIET=1`, the hook still performs session-state reset,
54
- stale search-flag cleanup, and update notification side effects, but suppresses
55
- all informational stdout so runtimes such as Codex do not show startup hook
56
- context in the UI.
53
+ By default the hook performs session-state reset, stale search-flag cleanup, and
54
+ update notification side effects without printing informational stdout. Set
55
+ `AI_TOOLKIT_HOOK_VERBOSE=1` to print the startup reminders and loaded context
56
+ for debugging; `AI_TOOLKIT_HOOK_QUIET=1` keeps it silent explicitly.
57
57
 
58
58
  ### Notification — `notify-waiting.sh`
59
59
 
@@ -107,12 +107,16 @@ context in the UI.
107
107
  | Script | `~/.softspark/ai-toolkit/hooks/user-prompt-submit.sh` |
108
108
  | Fires | Before Claude starts working on a submitted prompt |
109
109
 
110
- **Action:** Adds a lightweight governance reminder: plan mode for architectural work, evidence-first debugging, KB-first research, and validation expectations.
110
+ **Action:** Maintains the per-session search-first flag used by Stop enforcement
111
+ and can provide a lightweight governance reminder: plan mode for architectural
112
+ work, evidence-first debugging, KB-first research, and validation expectations.
111
113
 
112
114
  Skipped when `TOOLKIT_HOOK_PROFILE=minimal`. The bundled `app/hooks.json`
113
115
  registers this command with `AI_TOOLKIT_HOOK_QUIET=1`, so it still arms or
114
116
  clears the per-session search-first flag but suppresses the informational
115
- reminder output.
117
+ reminder output. In plain-text mode, informational reminders are silent by
118
+ default and require `AI_TOOLKIT_HOOK_VERBOSE=1`; JSON hook output remains
119
+ available with `AI_TOOLKIT_HOOK_FORMAT=json`.
116
120
 
117
121
  ### UserPromptSubmit (usage tracking) — `track-usage.sh`
118
122
 
@@ -440,7 +444,7 @@ Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
440
444
  | `scripts/test_cohesion.py` | Resolves changed paths → test commands via cohesion map. First-match-wins. Stdlib-only. |
441
445
  | `app/hooks/test-cohesion-map.json` | Toolkit-default path → tests mapping (used when no project map exists). |
442
446
  | `app/hooks/_locate-toolkit.sh` | Shared bash helper that exports `$TOOLKIT_DIR` for hooks needing scripts/. |
443
- | `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. |
447
+ | `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. |
444
448
  | `app/hooks/_search-capability.sh` | Shared bash helper that enables search-first blocking only when RAG/Web is configured or strict mode is requested. |
445
449
 
446
450
  ## Runtime Profiles
@@ -457,10 +461,11 @@ Set in `.claude/settings.local.json`:
457
461
  | `standard` | All hooks (default) |
458
462
  | `strict` | Standard + mypy --strict on task completion |
459
463
 
460
- Set `AI_TOOLKIT_HOOK_QUIET=1` on hook commands to suppress non-blocking
461
- informational context while preserving side effects and blocking decisions.
462
- Codex-generated hooks use this mode by default, and Claude's bundled
463
- `UserPromptSubmit` entry uses it to avoid visible prompt hook context.
464
+ Non-blocking informational context is silent in plain-text mode by default while
465
+ side effects and blocking decisions still run. Set `AI_TOOLKIT_HOOK_VERBOSE=1`
466
+ only when debugging hook context locally. `AI_TOOLKIT_HOOK_QUIET=1` keeps hook
467
+ commands explicitly silent, and Codex-generated hooks plus Claude's bundled
468
+ `UserPromptSubmit` entry use it to avoid visible prompt hook context.
464
469
 
465
470
  ## Architecture
466
471
 
package/llms-full.txt CHANGED
@@ -6928,7 +6928,7 @@ title: "AI Toolkit - Codex CLI Compatibility"
6928
6928
  category: reference
6929
6929
  service: ai-toolkit
6930
6930
  tags: [codex, compatibility, install, skills, hooks]
6931
- version: "1.0.1"
6931
+ version: "1.0.2"
6932
6932
  created: "2026-04-12"
6933
6933
  last_updated: "2026-05-21"
6934
6934
  description: "Reference for how ai-toolkit maps Claude-oriented skills, hooks, and plugin packs to Codex CLI."
@@ -7040,6 +7040,10 @@ non-blocking reminders and startup context out of the visible Codex hook output
7040
7040
  while preserving hook side effects and blocking decisions such as search-first
7041
7041
  Stop enforcement.
7042
7042
 
7043
+ Plain-text informational hook context is also silent by default in the shared
7044
+ hook helper. Set `AI_TOOLKIT_HOOK_VERBOSE=1` only when debugging hook output
7045
+ outside the Codex UI.
7046
+
7043
7047
  ## Behavioral Limits
7044
7048
 
7045
7049
  Codex wrappers preserve workflow intent, but not every Claude runtime behavior
@@ -8835,7 +8839,7 @@ title: "Hooks Catalog"
8835
8839
  category: reference
8836
8840
  service: ai-toolkit
8837
8841
  tags: [hooks, quality, safety, enforcement, settings.json]
8838
- version: "1.5.2"
8842
+ version: "1.5.3"
8839
8843
  created: "2026-03-27"
8840
8844
  last_updated: "2026-05-21"
8841
8845
  description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
@@ -8882,10 +8886,10 @@ ai-toolkit update # re-copies scripts, re-merges (idempotent)
8882
8886
  3. Loads session context from `.claude/session-context.md` (if exists)
8883
8887
  4. Loads active instincts from `.claude/instincts/*.md` (if any)
8884
8888
 
8885
- When `AI_TOOLKIT_HOOK_QUIET=1`, the hook still performs session-state reset,
8886
- stale search-flag cleanup, and update notification side effects, but suppresses
8887
- all informational stdout so runtimes such as Codex do not show startup hook
8888
- context in the UI.
8889
+ By default the hook performs session-state reset, stale search-flag cleanup, and
8890
+ update notification side effects without printing informational stdout. Set
8891
+ `AI_TOOLKIT_HOOK_VERBOSE=1` to print the startup reminders and loaded context
8892
+ for debugging; `AI_TOOLKIT_HOOK_QUIET=1` keeps it silent explicitly.
8889
8893
 
8890
8894
  ### Notification — `notify-waiting.sh`
8891
8895
 
@@ -8939,12 +8943,16 @@ context in the UI.
8939
8943
  | Script | `~/.softspark/ai-toolkit/hooks/user-prompt-submit.sh` |
8940
8944
  | Fires | Before Claude starts working on a submitted prompt |
8941
8945
 
8942
- **Action:** Adds a lightweight governance reminder: plan mode for architectural work, evidence-first debugging, KB-first research, and validation expectations.
8946
+ **Action:** Maintains the per-session search-first flag used by Stop enforcement
8947
+ and can provide a lightweight governance reminder: plan mode for architectural
8948
+ work, evidence-first debugging, KB-first research, and validation expectations.
8943
8949
 
8944
8950
  Skipped when `TOOLKIT_HOOK_PROFILE=minimal`. The bundled `app/hooks.json`
8945
8951
  registers this command with `AI_TOOLKIT_HOOK_QUIET=1`, so it still arms or
8946
8952
  clears the per-session search-first flag but suppresses the informational
8947
- reminder output.
8953
+ reminder output. In plain-text mode, informational reminders are silent by
8954
+ default and require `AI_TOOLKIT_HOOK_VERBOSE=1`; JSON hook output remains
8955
+ available with `AI_TOOLKIT_HOOK_FORMAT=json`.
8948
8956
 
8949
8957
  ### UserPromptSubmit (usage tracking) — `track-usage.sh`
8950
8958
 
@@ -9272,7 +9280,7 @@ Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
9272
9280
  | `scripts/test_cohesion.py` | Resolves changed paths → test commands via cohesion map. First-match-wins. Stdlib-only. |
9273
9281
  | `app/hooks/test-cohesion-map.json` | Toolkit-default path → tests mapping (used when no project map exists). |
9274
9282
  | `app/hooks/_locate-toolkit.sh` | Shared bash helper that exports `$TOOLKIT_DIR` for hooks needing scripts/. |
9275
- | `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. |
9283
+ | `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. |
9276
9284
  | `app/hooks/_search-capability.sh` | Shared bash helper that enables search-first blocking only when RAG/Web is configured or strict mode is requested. |
9277
9285
 
9278
9286
  ## Runtime Profiles
@@ -9289,10 +9297,11 @@ Set in `.claude/settings.local.json`:
9289
9297
  | `standard` | All hooks (default) |
9290
9298
  | `strict` | Standard + mypy --strict on task completion |
9291
9299
 
9292
- Set `AI_TOOLKIT_HOOK_QUIET=1` on hook commands to suppress non-blocking
9293
- informational context while preserving side effects and blocking decisions.
9294
- Codex-generated hooks use this mode by default, and Claude's bundled
9295
- `UserPromptSubmit` entry uses it to avoid visible prompt hook context.
9300
+ Non-blocking informational context is silent in plain-text mode by default while
9301
+ side effects and blocking decisions still run. Set `AI_TOOLKIT_HOOK_VERBOSE=1`
9302
+ only when debugging hook context locally. `AI_TOOLKIT_HOOK_QUIET=1` keeps hook
9303
+ commands explicitly silent, and Codex-generated hooks plus Claude's bundled
9304
+ `UserPromptSubmit` entry use it to avoid visible prompt hook context.
9296
9305
 
9297
9306
  ## Architecture
9298
9307
 
package/manifest.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "4.3.2",
2
+ "version": "4.3.3",
3
3
  "components": {
4
4
  "agents": {
5
5
  "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@softspark/ai-toolkit",
3
- "version": "4.3.2",
3
+ "version": "4.3.3",
4
4
  "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.",
5
5
  "keywords": [
6
6
  "claude",