hooks.json file fix (needed on my system anyway)

[darval]

hooks.json uses flat structure instead of required nested hooks array

Affected repos: zetetic-team-subagents (v2.0.0), Cortex (v3.9.0)
Files: hooks/hooks.json (subagents), .claude/hooks/hooks.json (Cortex)
Severity: Plugin fails to load — all hooks are broken

Problem

Claude Code's hook schema requires each hook entry to wrap type/command inside a nested hooks array. Both repos use a flat structure that puts type and command as siblings of matcher/when, which causes validation to reject every single hook entry:

Failed to load hooks from hooks.json:
  expected: "array", code: "invalid_type",
  path: ["hooks", "PreToolUse", 0, "hooks"],
  message: "Invalid input: expected array, received undefined"

This repeats for all 14 hook entries across PreToolUse (5), PostToolUse (4), PostToolUseFailure (1), SessionStart (2), Stop (1), and Notification (1).

Diff

The fix is mechanical — wrap each entry's type/command in a hooks: [...] array. The matcher and when fields stay at the outer level.

 {
   "hooks": {
     "PreToolUse": [
       {
         "matcher": "Bash",
         "when": "command contains 'git commit'",
-        "type": "command",
-        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-commit-zetetic.sh"
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-commit-zetetic.sh"
+          }
+        ]
       },
       {
         "matcher": "Bash",
         "when": "command contains 'git push'",
-        "type": "command",
-        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-push-review.sh"
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-push-review.sh"
+          }
+        ]
       },
       {
         "matcher": "Bash",
         "when": "command contains 'git push'",
-        "type": "command",
-        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-push-provenance.sh"
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-push-provenance.sh"
+          }
+        ]
       },
       {
         "matcher": "Edit|Write",
-        "type": "command",
-        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-edit-layer-check.sh"
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-edit-layer-check.sh"
+          }
+        ]
       },
       {
         "matcher": "Edit|Write",
-        "type": "command",
-        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-tool-claim-gate.sh"
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-tool-claim-gate.sh"
+          }
+        ]
       }
     ],
     "PostToolUse": [
       {
         "matcher": "Bash",
         "when": "command contains 'git commit'",
-        "type": "command",
-        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-commit-difficulty.sh"
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-commit-difficulty.sh"
+          }
+        ]
       },
       {
         "matcher": "Bash",
         "when": "command contains 'git commit'",
-        "type": "command",
-        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-commit-lab-notebook.sh"
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-commit-lab-notebook.sh"
+          }
+        ]
       },
       {
         "matcher": "Edit|Write",
-        "type": "command",
-        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-edit-balance.sh"
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-edit-balance.sh"
+          }
+        ]
       },
       {
         "matcher": "WebFetch|WebSearch",
-        "type": "command",
-        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-research-provenance.sh"
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-research-provenance.sh"
+          }
+        ]
       }
     ],
     "PostToolUseFailure": [
       {
-        "type": "command",
-        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-tool-error-routing.sh"
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-tool-error-routing.sh"
+          }
+        ]
       }
     ],
     "SessionStart": [
       {
-        "type": "command",
-        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+          }
+        ]
       },
       {
-        "type": "command",
-        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start-research.sh"
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start-research.sh"
+          }
+        ]
       }
     ],
     "Stop": [
       {
-        "type": "command",
-        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-end.sh"
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-end.sh"
+          }
+        ]
       }
     ],
     "Notification": [
       {
-        "type": "command",
-        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/notification-handler.sh"
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/notification-handler.sh"
+          }
+        ]
       }
     ]
   }
 }

Reference

Working example from token-optimizer (v5.1.0) that uses the correct nested schema:

{
  "matcher": "Read",
  "hooks": [
    {
      "type": "command",
      "command": "python3 '${CLAUDE_PLUGIN_ROOT}/skills/token-optimizer/scripts/read_cache.py' --quiet"
    }
  ]
}

[cdeust]

Thanks @darval — fix landed in 703c8ce on main.

Before merging I ran a three-agent review (Liskov / Dijkstra / Wu) to audit the fix.

Accepted — your diff applied verbatim

All 14 hook entries now wrap type/command in a nested hooks array while matcher and when stay at the outer level:

Bucket	Count	Status
PreToolUse	5	✓
PostToolUse	4	✓
PostToolUseFailure	1	✓ (see below)
SessionStart	2	✓
Stop	1	✓
Notification	1	✓

Liskov + Dijkstra agreed: the file now satisfies the nested-hooks-array contract you cited from token-optimizer v5.1.0, and JSON parse is clean (json.load passes).

Flagged for follow-up — not part of this commit

Wu's audit surfaced two things beyond the schema-nesting issue you reported:

1. PostToolUseFailure is likely not a canonical Claude Code event. Claude Code's documented hook events are PreToolUse, PostToolUse, Notification, UserPromptSubmit, SessionStart, SessionEnd, Stop, SubagentStop, PreCompact. Failure routing in the current runtime is handled inside a PostToolUse handler inspecting exit status, not via a separate event. The entry will pass schema validation but may silently never fire. Tracking separately — out of scope for this fix since your report was specifically about the schema shape.

2. when clause grammar is unverified. The "when": "command contains 'git commit'" shape is not present in Anthropic's documented schema or in the sibling .claude-plugin/plugin.json (which uses only matcher). May be dead configuration. Also tracked separately.

Explicitly not done

• Worktree copies in .claude/worktrees/agent-*. These are ephemeral per-agent workspaces (git-untracked). Fixing them would be defeated on the next worktree creation; they'll inherit the fixed file once deleted and recreated.
• Canonical-event lint / CI test. Wu noted there's no automated guard against this class of regression. Worth adding but out of scope for a point fix.

Appreciate the clean report with working-example reference — that shortened the review cycle considerably.

[cdeust]

Shipped in v3.9.1 — https://github.com/cdeust/Cortex/releases/tag/v3.9.1

Install / upgrade:

uvx --from neuro-cortex-memory[postgresql]==3.9.1 neuro-cortex-memory

Closing as fixed. Thanks again for the clean report.