fix(hooks): Claude never saw hook messages — systemMessage is user-only

CHANGELOG.md

@@ -6,6 +6,15 @@ and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Fixed
+
+- **`hookify/rule_engine.py`**: Fixed PreToolUse deny putting message in `systemMessage` (user-only display) instead of `permissionDecisionReason` (the field Claude actually receives). Root cause of Claude never seeing hook guidance when tools are blocked. Also split PreToolUse/PostToolUse into separate branches with correct response formats per Claude Code hooks spec
+- **`hookify/hook_runner.py`**: Fixed error reporting — hookify crashes now use exit code 2 + stderr (Claude-visible) instead of `systemMessage` (user-only)
+- **`hookify/global-rules/mtp-smart-test-filtering`**: Rewrote rule message to be directive — shorter (8 lines vs 80) with explicit "pick one and retry" action items
+- **`metacognitive-guard/epistemic-guard.sh`**: Migrated all 5 blocks from deprecated `decision`/`reason` format to modern `hookSpecificOutput.permissionDecision`/`permissionDecisionReason`. Removed dead `message` field that was ignored by Claude Code
+- **`metacognitive-guard/integrity-check.sh`**: Fixed exit code 1 (non-blocking, commit proceeds) → exit code 2 (blocking, stderr fed to Claude). Violations now actually block commits instead of being silently ignored
+- **`metacognitive-guard/struggle-detector`**: Split into two hooks — async Stop (analysis + blackboard write) and new `struggle-inject.sh` on UserPromptSubmit (reads blackboard, injects `additionalContext` that Claude actually sees). Removed dead `systemMessage` output from Stop hook
+
 ### Added
 
 - **`plugins/council`**: New plugin — five-agent council (opus-captain, sonnet-researcher, sonnet-synthesizer, sonnet-clarity, haiku-janitor). Each agent identity inlined directly in its `agents/*.md` file as passive context. Researcher + synthesizer run in parallel; clarity reads their raw output; haiku-janitor flags bloat; captain removes cuts. Inspired by Grok 4.20's multi-agent architecture. Invoke via `/council [task]`.

plugins/hookify/CLAUDE.md

@@ -35,5 +35,5 @@ Rules loaded from TWO locations:
 ## Key Behavior
 
 - Hades permit exemption: active `.smart/delete-permit.json` bypasses ALL blocking rules.
-- Python hooks read stdin JSON, return JSON with `systemMessage` or `block` action.
+- Python hooks read stdin JSON, return JSON with event-specific fields: `permissionDecisionReason` (PreToolUse deny), `reason` (Stop/PostToolUse block), `additionalContext` (warnings on PostToolUse/UserPromptSubmit/SessionStart). `systemMessage` is user-display only — Claude never sees it.
 - Conversation analyzer searches for "Don't use X", frustrated reactions, repeated issues.

plugins/hookify/global-rules/hookify.mtp-smart-test.local.md

@@ -15,8 +15,12 @@ conditions:
     pattern: "# VERIFY"
 ---
 
-Full test suite detected. If previous tests failed, filter to just those tests.
+This hookify rule blocked a full test suite run. This is intentional, not a bug.
 
-**Bypass:** append `# VERIFY` to the command.
-**Filter:** `dotnet test --filter-method "*FailingTestName"`
-**Help:** use `dotnet-mtp-advisor` agent for MTP filter syntax.
+**Action required — pick one:**
+
+1. **Verify all tests pass** → Re-run the exact same command with `# VERIFY` appended
+2. **Run only failing tests** → Use `--filter-method "*FailingTestName"` or `--filter-class "*ClassName"`
+3. **Need MTP filter help** → Spawn the `dotnet-mtp-advisor` agent
+
+Do NOT tell the user this is a bug. Do NOT tell the user to run the command themselves. Just pick option 1 or 2 and retry.

plugins/hookify/hookify/core/hook_runner.py

@@ -25,8 +25,9 @@ def run_hook(hook_event_name: str, fixed_event: Optional[str] = None):
         from hookify.core.config_loader import load_rules
         from hookify.core.rule_engine import RuleEngine
     except ImportError as e:
-        print(json.dumps({"systemMessage": f"Hookify import error: {e}"}), file=sys.stdout)
-        sys.exit(0)
+        # stderr with exit 2 ensures Claude sees the error on PreToolUse
+        print(f"Hookify import error: {e}", file=sys.stderr)
+        sys.exit(2)
 
     try:
         input_data = json.load(sys.stdin)
@@ -51,7 +52,6 @@ def run_hook(hook_event_name: str, fixed_event: Optional[str] = None):
         print(json.dumps(result), file=sys.stdout)
 
     except Exception as e:
-        print(json.dumps({"systemMessage": f"Hookify error: {str(e)}"}), file=sys.stdout)
-
-    finally:
-        sys.exit(0)
+        # stderr with exit 2 ensures Claude sees the error on PreToolUse
+        print(f"Hookify error: {str(e)}", file=sys.stderr)
+        sys.exit(2)

plugins/hookify/hookify/core/rule_engine.py

@@ -72,7 +72,9 @@ def evaluate_rules(self, rules: List[Rule], input_data: Dict[str, Any]) -> Dict[
             input_data: Hook input JSON (tool_name, tool_input, etc.)
 
         Returns:
-            Response dict with systemMessage, hookSpecificOutput, etc.
+            Response dict with event-appropriate fields per Claude Code hooks spec.
+            Uses permissionDecisionReason (PreToolUse), reason (Stop/PostToolUse),
+            additionalContext (warnings on PostToolUse/UserPromptSubmit/SessionStart).
             Empty dict {} if no rules match.
         """
         # Hades god mode — active permit bypasses all rules
@@ -99,29 +101,47 @@ def evaluate_rules(self, rules: List[Rule], input_data: Dict[str, Any]) -> Dict[
             if hook_event == 'Stop':
                 return {
                     "decision": "block",
-                    "reason": combined_message,
-                    "systemMessage": combined_message
+                    "reason": combined_message
                 }
-            elif hook_event in ['PreToolUse', 'PostToolUse']:
+            elif hook_event == 'PreToolUse':
                 return {
                     "hookSpecificOutput": {
                         "hookEventName": hook_event,
-                        "permissionDecision": "deny"
-                    },
-                    "systemMessage": combined_message
+                        "permissionDecision": "deny",
+                        "permissionDecisionReason": combined_message
+                    }
                 }
-            else:
-                # For other events, just show message
+            elif hook_event == 'PostToolUse':
+                return {
+                    "decision": "block",
+                    "reason": combined_message
+                }
+            elif hook_event == 'UserPromptSubmit':
                 return {
-                    "systemMessage": combined_message
+                    "decision": "block",
+                    "reason": combined_message
                 }
+            else:
+                # SessionStart, Notification — no blocking mechanism, no audience
+                return {}
 
         # If only warnings, show them but allow operation
         if warning_rules:
             messages = [f"**[{r.name}]**\n{r.message}" for r in warning_rules]
-            return {
-                "systemMessage": "\n\n".join(messages)
-            }
+            combined_warning = "\n\n".join(messages)
+
+            # Use additionalContext where Claude can see it
+            if hook_event in ['PostToolUse', 'UserPromptSubmit', 'SessionStart']:
+                return {
+                    "hookSpecificOutput": {
+                        "hookEventName": hook_event,
+                        "additionalContext": combined_warning
+                    }
+                }
+            else:
+                # PreToolUse warnings can't reach Claude without blocking
+                # No audience for the message — skip
+                return {}
 
         # No matches - allow operation
         return {}

plugins/metacognitive-guard/CLAUDE.md

@@ -10,7 +10,8 @@ agents amplify thinking. Absorbs completion-integrity and autonomous-ci.
 | Truth Beacon | SessionStart | `truth-beacon.sh` | Injects `blackboard/assertions.yaml` as authoritative facts |
 | Epistemic Guard | PreToolUse (Write/Edit) | `epistemic-guard.sh` | Blocks writes with wrong versions, banned APIs, AGENTS.md in plugins |
 | Commit Integrity | PreToolUse (Bash) | `commit-integrity-hook.sh` | Blocks `git commit` with suppressions, commented tests, deleted assertions |
-| Struggle Detector | Stop (async) | `struggle-detector.sh` | Scores response for uncertainty, triggers deep-think suggestion |
+| Struggle Detector | Stop (async) | `struggle-detector.sh` | Scores response for uncertainty, writes to blackboard |
+| Struggle Inject | UserPromptSubmit | `struggle-inject.sh` | Reads blackboard, injects deep-think suggestion as `additionalContext` |
 | Ralph Loop | PostToolUse (Write/Edit) | prompt (haiku) + `ralph-loop.sh` | Two-layer drift detection: haiku analyzes context (over-engineering, complexity, premature optimization), grep catches surface patterns (TODO, suppressions, catch-all). Both inject via additionalContext. Silent when clean |
 | Task Completion Gate | TaskCompleted | prompt (haiku) | Validates task completions in team workflows aren't premature |
 
@@ -52,7 +53,7 @@ agents amplify thinking. Absorbs completion-integrity and autonomous-ci.
 - verify-local.sh and wait-for-ci.sh are utility scripts for the verification workflow, not hook triggers.
 - Hades god mode: active delete permit causes epistemic-guard to exit early.
 - Struggle detector tracks consecutive struggling responses via `.blackboard/.struggle-count`.
-- Struggle detector runs async (non-blocking) — feedback delivered next turn, never delays responses.
+- Struggle detector is a two-part system: Stop hook (async) does analysis + blackboard writes, UserPromptSubmit hook reads blackboard and injects `additionalContext` so Claude actually sees the suggestion. No latency on responses.
 - TaskCompleted prompt hook fires on every task completion in team contexts (haiku, 15s timeout).
 - Ralph Loop fires PostToolUse on Write/Edit — two layers run in parallel:
   (1) Haiku prompt analyzes context for deep drift (over-engineering, complexity creep, premature

plugins/metacognitive-guard/hooks/hooks.json

@@ -36,6 +36,18 @@
         ]
       }
     ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/struggle-inject.sh",
+            "timeout": 3,
+            "statusMessage": "Checking struggle state..."
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "hooks": [

plugins/metacognitive-guard/hooks/scripts/epistemic-guard.sh

@@ -45,9 +45,11 @@ fi
 if [[ "$FILE_PATH" == */plugins/*/AGENTS.md ]]; then
     cat << 'EOF'
 {
-  "decision": "block",
-  "reason": "EPISTEMIC GUARD: Anti-pattern - AGENTS.md in plugin directory",
-  "message": "AGENTS.md is NOT auto-loaded by Claude Code plugins.\n\nRouting intelligence belongs in skill description frontmatter (passive context).\nUse the Vercel pattern: encode WHEN to use each skill in the description field.\n\nIf you need human documentation, use README.md instead."
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "EPISTEMIC GUARD: Anti-pattern - AGENTS.md in plugin directory.\n\nAGENTS.md is NOT auto-loaded by Claude Code plugins.\nRouting intelligence belongs in skill description frontmatter (passive context).\nUse the Vercel pattern: encode WHEN to use each skill in the description field.\nIf you need human documentation, use README.md instead."
+  }
 }
 EOF
     exit 0
@@ -73,9 +75,11 @@ esac
 if echo "$CONTENT" | grep -qiE "\.NET 10.*(preview|not.*(released|LTS|available))|\.NET 10 is still|net9\.0"; then
     cat << 'EOF'
 {
-  "decision": "block",
-  "reason": "EPISTEMIC GUARD: Incorrect .NET version claim",
-  "message": "FACT CHECK: .NET 10 is LTS (Long Term Support) since November 11, 2025.\n\nIt is NOT preview. Use net10.0 in TargetFramework.\n\nSource: https://dotnet.microsoft.com/download/dotnet/10.0\n\nPlease correct your response before writing."
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "EPISTEMIC GUARD: Incorrect .NET version claim. FACT: .NET 10 is LTS since November 11, 2025. It is NOT preview. Use net10.0 in TargetFramework. Correct your content before writing."
+  }
 }
 EOF
     exit 0
@@ -88,9 +92,11 @@ if [[ "$IS_DOCS" == false ]]; then
 if echo "$CONTENT" | grep -qE 'DateTime\.(Now|UtcNow)|DateTimeOffset\.(Now|UtcNow)'; then
     cat << 'EOF'
 {
-  "decision": "block",
-  "reason": "EPISTEMIC GUARD: Banned API - DateTime.Now",
-  "message": "DateTime.Now/UtcNow should be avoided.\n\nUse: TimeProvider.System.GetUtcNow()\n\nThis enables testability and follows .NET 8+ best practices."
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "EPISTEMIC GUARD: Banned API - DateTime.Now/UtcNow. Use TimeProvider.System.GetUtcNow() instead. This enables testability and follows .NET 8+ best practices."
+  }
 }
 EOF
     exit 0
@@ -100,9 +106,11 @@ fi
 if echo "$CONTENT" | grep -qE 'object\s+_?lock\s*='; then
     cat << 'EOF'
 {
-  "decision": "block",
-  "reason": "EPISTEMIC GUARD: Banned pattern - object lock",
-  "message": "object-based locking should be avoided.\n\nUse: Lock _lock = new();\n\n.NET 9+ Lock type is more efficient and type-safe."
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "EPISTEMIC GUARD: Banned pattern - object lock. Use Lock _lock = new() instead. .NET 9+ Lock type is more efficient and type-safe."
+  }
 }
 EOF
     exit 0
@@ -112,9 +120,11 @@ fi
 if echo "$CONTENT" | grep -qE 'Newtonsoft\.Json|JsonConvert\.'; then
     cat << 'EOF'
 {
-  "decision": "block",
-  "reason": "EPISTEMIC GUARD: Banned dependency - Newtonsoft.Json",
-  "message": "Newtonsoft.Json should be avoided in new code.\n\nUse: System.Text.Json with source generators.\n\nExample: JsonSerializer.Serialize(obj, MyContext.Default.MyType)"
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "EPISTEMIC GUARD: Banned dependency - Newtonsoft.Json. Use System.Text.Json with source generators instead. Example: JsonSerializer.Serialize(obj, MyContext.Default.MyType)"
+  }
 }
 EOF
     exit 0

plugins/metacognitive-guard/hooks/scripts/integrity-check.sh

@@ -203,8 +203,11 @@ elif [[ "$VIOLATION_COUNT" -eq 0 ]]; then
     echo -e "${YELLOW}WARNINGS|$WARNING_COUNT warnings (review recommended)${NC}"
     exit 0
 else
-    echo -e "${RED}BLOCKED|$VIOLATION_COUNT violations, $WARNING_COUNT warnings${NC}"
-    echo ""
-    echo "Fix violations before committing. These patterns indicate shortcuts that will cause problems later."
-    exit 1
+    # Exit code 2 = blocking error, stderr is fed to Claude
+    echo "COMMIT INTEGRITY: $VIOLATION_COUNT violations found. Fix these before committing:" >&2
+    for v in "${VIOLATIONS[@]}"; do
+        echo "  - $v" >&2
+    done
+    echo "These patterns indicate shortcuts that will cause problems later." >&2
+    exit 2
 fi

plugins/metacognitive-guard/hooks/scripts/struggle-detector.sh

@@ -140,6 +140,10 @@ fi
 if [[ "$score" -gt 10 ]]; then
     PREV_COUNT=$(cat "$STRUGGLE_COUNT_FILE" 2>/dev/null || echo "0")
     NEW_COUNT=$((PREV_COUNT + 1))
+    # High severity (score > 25) triggers inject on next prompt immediately
+    if [[ "$score" -gt 25 && "$NEW_COUNT" -lt 2 ]]; then
+        NEW_COUNT=2
+    fi
     echo "$NEW_COUNT" > "$STRUGGLE_COUNT_FILE"
 else
     echo "0" > "$STRUGGLE_COUNT_FILE"
@@ -164,19 +168,8 @@ CONSECUTIVE=$(cat "$STRUGGLE_COUNT_FILE" 2>/dev/null || echo "0")
     done
 } >> "$STRUGGLE_FILE"
 
-# Trigger after 2+ consecutive struggling responses OR high single score
-if [[ "$CONSECUTIVE" -ge 2 ]] || [[ "$score" -gt 25 ]]; then
-    # Build signals list with proper escaping
-    SIGNALS_LIST=""
-    for sig in "${signals[@]}"; do
-        SIGNALS_LIST="${SIGNALS_LIST}- ${sig}\\n"
-    done
-
-    cat <<EOF
-{
-  "systemMessage": "<struggle-detected score=\"$score\" consecutive=\"$CONSECUTIVE\">\\n\\nClaude appears to be struggling with this problem.\\n\\nSignals detected:\\n${SIGNALS_LIST}\\nSuggestion: Use the Task tool with subagent_type='deep-think-partner' for thorough analysis.\\n\\nExample: \\\"I'm finding this complex. Want me to spawn a deep-thinker for a more thorough analysis?\\\"\\n</struggle-detected>"
-}
-EOF
-fi
+# Note: No JSON output needed here. The struggle-inject.sh (UserPromptSubmit)
+# reads .blackboard/.struggle-count and injects additionalContext to Claude
+# on the next prompt. This async Stop hook only does analysis + blackboard writes.
 
 exit 0

plugins/metacognitive-guard/hooks/scripts/struggle-inject.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# =============================================================================
+# STRUGGLE INJECT - Delivers struggle detection to Claude via UserPromptSubmit
+# =============================================================================
+# Trigger: UserPromptSubmit (before Claude processes the next prompt)
+# Purpose: Read blackboard state from async struggle-detector and inject
+#          suggestion as additionalContext so Claude actually sees it.
+#
+# The struggle-detector.sh (Stop, async) writes scoring data to:
+#   .blackboard/.struggle-count   — consecutive struggling responses
+#   .blackboard/.struggle-signals — detailed signal log
+#
+# This hook reads those files and injects context when threshold is met.
+# After injection, resets the counter to prevent repeated suggestions.
+# =============================================================================
+
+set -euo pipefail
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
+[[ -z "$PLUGIN_ROOT" ]] && exit 0
+
+BLACKBOARD="$PLUGIN_ROOT/.blackboard"
+STRUGGLE_COUNT_FILE="$BLACKBOARD/.struggle-count"
+
+# Check consecutive struggle count
+CONSECUTIVE=$(cat "$STRUGGLE_COUNT_FILE" 2>/dev/null || echo "0")
+[[ "$CONSECUTIVE" -lt 2 ]] && exit 0
+
+# Read recent signals for context
+SIGNALS_FILE="$BLACKBOARD/.struggle-signals"
+RECENT_SIGNALS=""
+if [[ -f "$SIGNALS_FILE" ]]; then
+    RECENT_SIGNALS=$( (tail -20 "$SIGNALS_FILE" | grep '  - ' || true) | sed 's/  - //' | tr '\n' ', ' | sed 's/, $//')
+fi
+
+# Inject as additionalContext — use jq for safe JSON construction
+MSG="STRUGGLE DETECTOR ($CONSECUTIVE consecutive uncertain responses): Signals — $RECENT_SIGNALS. Consider spawning a deep-think-partner agent (Task tool, subagent_type='deep-think-partner') for thorough analysis instead of continuing to iterate."
+jq -n --arg ctx "$MSG" '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":$ctx}}'
+
+# Reset after delivering to prevent repeated suggestions
+echo "0" > "$STRUGGLE_COUNT_FILE"
+
+exit 0