Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

fix(hooks): keep hooks.json within Claude Code's schema

zpearce-28141ac07903ec99
diff --git a/hooks/README.md b/hooks/README.md
index 144bc89ad..620ef981f 100644
--- a/hooks/README.md
+++ b/hooks/README.md
@@ -19,6 +19,10 @@ User request → Claude picks a tool → PreToolUse hook runs → Tool executes
Memory persistence lifecycle definitions live in `hooks/memory-persistence/`.
The executable hook graph remains `hooks/hooks.json`; the memory persistence directory is the stable contract for SessionStart, PreCompact, observation, activity tracking, and SessionEnd behavior.
+Stable hook IDs and descriptions live in `hooks/hooks.metadata.json`, aligned by event and index with `hooks/hooks.json`. Claude Code validates a plugin's `hooks.json` against its own schema and reports any other key (`$schema`, `id`, `description`) as unknown at load time, so `hooks.json` carries only what the harness accepts. ECC's installer, validator, and dashboard merge the sidecar back in through `scripts/lib/hooks-config.js`; `node scripts/ci/validate-hooks.js` fails if the two files drift apart.
+
+Each sidecar entry also carries a `fingerprint` of the matcher entry it describes (matcher plus hook commands), so reordering `hooks.json` without reordering the sidecar, or editing a command without updating the sidecar, is caught rather than silently swapping IDs. When reordering hooks, move the matching sidecar entries first. Then run `node scripts/ci/validate-hooks.js --update-fingerprints` to refresh changed commands and commit both files. The updater rejects known fingerprints at different positions and writes only after validation succeeds.
+
## Installing These Hooks Manually
For Claude Code manual installs, do not paste the raw repo `hooks.json` into `~/.claude/settings.json` or copy it directly into `~/.claude/hooks/hooks.json`. The checked-in file is plugin/repo-oriented and is meant to be installed through the ECC installer or loaded as a plugin.
diff --git a/hooks/hooks.json b/hooks/hooks.json
index 62053904e..641873396 100644
--- a/hooks/hooks.json
+++ b/hooks/hooks.json
@@ -1,5 +1,4 @@
{
- "$schema": "https://json.schemastore.org/claude-code-settings.json",
"hooks": {
"PreToolUse": [
{
@@ -9,9 +8,7 @@
"type": "command",
"command": "node -e \"const p=require('path');const r=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const s=p.join(r,'scripts/hooks/plugin-hook-bootstrap.js');process.env.CLAUDE_PLUGIN_ROOT=r;process.argv.splice(1,0,s);require(s)\" node scripts/hooks/pre-bash-dispatcher.js"
}
- ],
- "description": "Consolidated Bash preflight dispatcher for quality, tmux, push, and GateGuard checks",
- "id": "pre:bash:dispatcher"
+ ]
},
{
"matcher": "PowerShell",
@@ -21,9 +18,7 @@
"command": "node -e \"const p=require('path');const r=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const s=p.join(r,'scripts/hooks/plugin-hook-bootstrap.js');process.env.CLAUDE_PLUGIN_ROOT=r;process.argv.splice(1,0,s);require(s)\" node scripts/hooks/run-with-flags.js pre:powershell:gateguard-fact-force scripts/hooks/gateguard-fact-force.js standard,strict",
"timeout": 5
}
- ],
- "description": "PowerShell fact-forcing gate: inspect destructive commands without running unrelated Bash-only preflight hooks",
- "id": "pre:powershell:gateguard-fact-force"
+ ]
},
{
"matcher": "Write",
@@ -32,9 +27,7 @@
"type": "command",
"command": "node -e \"const p=require('path');const r=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const s=p.join(r,'scripts/hooks/plugin-hook-bootstrap.js');process.env.CLAUDE_PLUGIN_ROOT=r;process.argv.splice(1,0,s);require(s)\" node scripts/hooks/run-with-flags.js pre:write:doc-file-warning scripts/hooks/doc-file-warning.js standard,strict"
}
- ],
- "description": "Doc file warning: warn about non-standard documentation files (exit code 0; warns only)",
- "id": "pre:write:doc-file-warning"
+ ]
},
{
"matcher": "Edit|Write",
@@ -43,9 +36,7 @@
"type": "command",
"command": "node -e \"const p=require('path');const r=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const s=p.join(r,'scripts/hooks/plugin-hook-bootstrap.js');process.env.CLAUDE_PLUGIN_ROOT=r;process.argv.splice(1,0,s);require(s)\" node scripts/hooks/run-with-flags.js pre:edit-write:suggest-compact scripts/hooks/suggest-compact.js standard,strict"
}
- ],
- "description": "Suggest manual compaction at logical intervals",
- "id": "pre:edit-write:suggest-compact"
+ ]
},
{
"matcher": ".*",
@@ -56,9 +47,7 @@
"async": true,
"timeout": 10
}
- ],
- "description": "Capture tool use observations for continuous learning",
- "id": "pre:observe:continuous-learning"
+ ]
},
{
"matcher": "Bash|PowerShell|Write|Edit|MultiEdit",
@@ -68,9 +57,7 @@
"command": "node -e \"const p=require('path');const r=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const s=p.join(r,'scripts/hooks/plugin-hook-bootstrap.js');process.env.CLAUDE_PLUGIN_ROOT=r;process.argv.splice(1,0,s);require(s)\" node scripts/hooks/run-with-flags.js pre:governance-capture scripts/hooks/governance-capture.js standard,strict",
"timeout": 10
}
- ],
- "description": "Capture governance events (secrets, policy violations, approval requests). Enable with ECC_GOVERNANCE_CAPTURE=1",
- "id": "pre:governance-capture"
+ ]
},
{
"matcher": "Write|Edit|MultiEdit",
@@ -80,9 +67,7 @@
"command": "node -e \"const p=require('path');const r=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const s=p.join(r,'scripts/hooks/plugin-hook-bootstrap.js');process.env.CLAUDE_PLUGIN_ROOT=r;process.argv.splice(1,0,s);require(s)\" node scripts/hooks/run-with-flags.js pre:config-protection scripts/hooks/config-protection.js standard,strict",
"timeout": 5
}
- ],
- "description": "Block modifications to linter/formatter config files. Steers agent to fix code instead of weakening configs.",
- "id": "pre:config-protection"
+ ]
},
{
"matcher": ".*",
@@ -91,9 +76,7 @@
"type": "command",
"command": "node -e \"const p=require('path');const r=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const s=p.join(r,'scripts/hooks/plugin-hook-bootstrap.js');process.env.CLAUDE_PLUGIN_ROOT=r;process.argv.splice(1,0,s);require(s)\" node scripts/hooks/run-with-flags.js pre:mcp-health-check scripts/hooks/mcp-health-check.js standard,strict"
}
- ],
- "description": "Check MCP server health before MCP tool execution and block unhealthy MCP calls",
- "id": "pre:mcp-health-check"
+ ]
},
{
"matcher": "Edit|Write|MultiEdit",
@@ -103,9 +86,7 @@
"command": "node -e \"const p=require('path');const r=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const s=p.join(r,'scripts/hooks/plugin-hook-bootstrap.js');process.env.CLAUDE_PLUGIN_ROOT=r;process.argv.splice(1,0,s);require(s)\" node scripts/hooks/run-with-flags.js pre:edit-write:gateguard-fact-force scripts/hooks/gateguard-fact-force.js standard,strict",
"timeout": 5
}
- ],
- "description": "Fact-forcing gate: block first Edit/Write/MultiEdit per file and demand investigation (importers, data schemas, user instruction) before allowing",
- "id": "pre:edit-write:gateguard-fact-force"
+ ]
}
],
"PreCompact": [
@@ -116,9 +97,7 @@
"type": "command",
"command": "node -e \"const p=require('path');const r=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const s=p.join(r,'scripts/hooks/plugin-hook-bootstrap.js');process.env.CLAUDE_PLUGIN_ROOT=r;process.argv.splice(1,0,s);require(s)\" node scripts/hooks/run-with-flags.js pre:compact scripts/hooks/pre-compact.js standard,strict"
}
- ],
- "description": "Save state before context compaction",
- "id": "pre:compact"
+ ]
}
],
"SessionStart": [
@@ -129,9 +108,7 @@
"type": "command",
"command": "node -e \"const p=require('path');const r=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const s=p.join(r,'scripts/hooks/plugin-hook-bootstrap.js');process.env.CLAUDE_PLUGIN_ROOT=r;process.argv.splice(1,0,s);require(s)\" node scripts/hooks/session-start-bootstrap.js"
}
- ],
- "description": "Load previous context and detect package manager on new session",
- "id": "session:start"
+ ]
},
{
"matcher": ".*",
@@ -140,9 +117,7 @@
"type": "command",
"command": "node -e \"const p=require('path');const r=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const s=p.join(r,'scripts/hooks/plugin-hook-bootstrap.js');process.env.CLAUDE_PLUGIN_ROOT=r;process.argv.splice(1,0,s);require(s)\" node scripts/hooks/run-with-flags.js session-start:plan-canvas-sessions scripts/hooks/plan-canvas-sessions.js standard,strict"
}
- ],
- "description": "Surface open Plan Canvas review sessions so a fresh session can resume the loop",
- "id": "session-start:plan-canvas-sessions"
+ ]
}
],
"PostToolUse": [
@@ -154,9 +129,7 @@
"command": "node -e \"const p=require('path');const r=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const s=p.join(r,'scripts/hooks/posttooluse-dispatcher.js');process.env.CLAUDE_PLUGIN_ROOT=r;process.env.ECC_POSTTOOLUSE_PASSTHROUGH='1';process.argv.splice(1,0,s);require(s).cli()\" sync",
"timeout": 30
}
- ],
- "description": "Run synchronous PostToolUse hooks in one process while preserving per-hook controls",
- "id": "post:dispatcher:sync"
+ ]
},
{
"matcher": ".*",
@@ -167,9 +140,7 @@
"async": true,
"timeout": 45
}
- ],
- "description": "Run background PostToolUse hooks in one process while preserving per-hook controls",
- "id": "post:dispatcher:async"
+ ]
}
],
"PostToolUseFailure": [
@@ -180,9 +151,7 @@
"type": "command",
"command": "node -e \"const p=require('path');const r=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const s=p.join(r,'scripts/hooks/plugin-hook-bootstrap.js');process.env.CLAUDE_PLUGIN_ROOT=r;process.argv.splice(1,0,s);require(s)\" node scripts/hooks/run-with-flags.js post:mcp-health-check scripts/hooks/mcp-health-check.js standard,strict"
}
- ],
- "description": "Track failed MCP tool calls, mark unhealthy servers, and attempt reconnect",
- "id": "post:mcp-health-check"
+ ]
},
{
"matcher": "Skill",
@@ -191,9 +160,7 @@
"type": "command",
"command": "node -e \"const p=require('path');const r=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const s=p.join(r,'scripts/hooks/plugin-hook-bootstrap.js');process.env.CLAUDE_PLUGIN_ROOT=r;process.argv.splice(1,0,s);require(s)\" node scripts/hooks/run-with-flags.js post:skill:track scripts/hooks/skill-run-tracker.js standard,strict"
}
- ],
- "description": "Record hard Skill tool failures for skill-health telemetry",
- "id": "post:skill:track"
+ ]
}
],
"Stop": [
@@ -204,9 +171,7 @@
"type": "command",
"command": "node -e \"const fs=require('fs');const path=require('path');const {spawnSync}=require('child_process');const raw=fs.readFileSync(0,'utf8');const finish=(out,err,code)=>{let pending=1;const done=()=>{pending-=1;if(pending===0)process.exit(code);};if(out){pending+=1;process.stdout.write(out,done);}if(err){pending+=1;process.stderr.write(err,done);}process.nextTick(done);};const rel=path.join('scripts','hooks','run-with-flags.js');const root=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const script=path.join(root,rel);if(fs.existsSync(script)){const result=spawnSync(process.execPath,[script,'stop:plan-canvas-pending','scripts/hooks/plan-canvas-pending.js','minimal,standard,strict'],{input:raw,encoding:'utf8',env:process.env,cwd:process.cwd(),timeout:30000,maxBuffer:16*1024*1024});const failed=result.error||result.status===null||result.signal;const stdout=!failed&&typeof result.stdout==='string'?result.stdout:'';let stderr=typeof result.stderr==='string'?result.stderr:'';let code=Number.isInteger(result.status)?result.status:0;if(failed){const reason=result.error?result.error.message:(result.signal?'signal '+result.signal:'missing exit status');stderr+='[Stop] ERROR: hook runner failed: '+reason+String.fromCharCode(10);code=1;}finish(stdout,stderr,code);}else{finish(raw,'[Stop] WARNING: could not resolve ECC plugin root; skipping hook'+String.fromCharCode(10),0);}\""
}
- ],
- "description": "Deliver undelivered Plan Canvas browser feedback before the agent stops",
- "id": "stop:plan-canvas-pending"
+ ]
},
{
"matcher": ".*",
@@ -216,9 +181,7 @@
"command": "node -e \"const fs=require('fs');const path=require('path');const {spawnSync}=require('child_process');const raw=fs.readFileSync(0,'utf8');const finish=(out,err,code)=>{let pending=1;const done=()=>{pending-=1;if(pending===0)process.exit(code);};if(out){pending+=1;process.stdout.write(out,done);}if(err){pending+=1;process.stderr.write(err,done);}process.nextTick(done);};const rel=path.join('scripts','hooks','run-with-flags.js');const root=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const script=path.join(root,rel);if(fs.existsSync(script)){const result=spawnSync(process.execPath,[script,'stop:format-typecheck','scripts/hooks/stop-format-typecheck.js','standard,strict'],{input:raw,encoding:'utf8',env:process.env,cwd:process.cwd(),timeout:300000,maxBuffer:16*1024*1024});const failed=result.error||result.status===null||result.signal;const stdout=!failed&&typeof result.stdout==='string'?result.stdout:'';let stderr=typeof result.stderr==='string'?result.stderr:'';let code=Number.isInteger(result.status)?result.status:0;if(failed){const reason=result.error?result.error.message:(result.signal?'signal '+result.signal:'missing exit status');stderr+='[Stop] ERROR: hook runner failed: '+reason+String.fromCharCode(10);code=1;}finish(stdout,stderr,code);}else{finish(raw,'[Stop] WARNING: could not resolve ECC plugin root; skipping hook'+String.fromCharCode(10),0);}\"",
"timeout": 300
}
- ],
- "description": "Batch format (Biome/Prettier) and typecheck (tsc) all JS/TS files edited this response — runs once at Stop instead of after every Edit",
- "id": "stop:format-typecheck"
+ ]
},
{
"matcher": ".*",
@@ -227,9 +190,7 @@
"type": "command",
"command": "node -e \"const fs=require('fs');const path=require('path');const {spawnSync}=require('child_process');const raw=fs.readFileSync(0,'utf8');const finish=(out,err,code)=>{let pending=1;const done=()=>{pending-=1;if(pending===0)process.exit(code);};if(out){pending+=1;process.stdout.write(out,done);}if(err){pending+=1;process.stderr.write(err,done);}process.nextTick(done);};const rel=path.join('scripts','hooks','run-with-flags.js');const root=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const script=path.join(root,rel);if(fs.existsSync(script)){const result=spawnSync(process.execPath,[script,'stop:check-console-log','scripts/hooks/check-console-log.js','standard,strict'],{input:raw,encoding:'utf8',env:process.env,cwd:process.cwd(),timeout:30000,maxBuffer:16*1024*1024});const failed=result.error||result.status===null||result.signal;const stdout=!failed&&typeof result.stdout==='string'?result.stdout:'';let stderr=typeof result.stderr==='string'?result.stderr:'';let code=Number.isInteger(result.status)?result.status:0;if(failed){const reason=result.error?result.error.message:(result.signal?'signal '+result.signal:'missing exit status');stderr+='[Stop] ERROR: hook runner failed: '+reason+String.fromCharCode(10);code=1;}finish(stdout,stderr,code);}else{finish(raw,'[Stop] WARNING: could not resolve ECC plugin root; skipping hook'+String.fromCharCode(10),0);}\""
}
- ],
- "description": "Check for console.log in modified files after each response",
- "id": "stop:check-console-log"
+ ]
},
{
"matcher": ".*",
@@ -240,9 +201,7 @@
"async": true,
"timeout": 10
}
- ],
- "description": "Persist session state after each response (Stop carries transcript_path)",
- "id": "stop:session-end"
+ ]
},
{
"matcher": ".*",
@@ -253,9 +212,7 @@
"async": true,
"timeout": 10
}
- ],
- "description": "Evaluate session for extractable patterns",
- "id": "stop:evaluate-session"
+ ]
},
{
"matcher": ".*",
@@ -266,9 +223,7 @@
"async": true,
"timeout": 10
}
- ],
- "description": "Track token and cost metrics per session",
- "id": "stop:cost-tracker"
+ ]
},
{
"matcher": ".*",
@@ -279,9 +234,7 @@
"async": true,
"timeout": 10
}
- ],
- "description": "Send desktop notification (macOS/WSL) with task summary when Claude responds",
- "id": "stop:desktop-notify"
+ ]
}
],
"SessionEnd": [
@@ -294,9 +247,7 @@
"async": true,
"timeout": 10
}
- ],
- "description": "Session end lifecycle marker (non-blocking)",
- "id": "session:end:marker"
+ ]
}
]
}
diff --git a/hooks/hooks.metadata.json b/hooks/hooks.metadata.json
new file mode 100644
index 000000000..dc315fd6a
--- /dev/null
+++ b/hooks/hooks.metadata.json
@@ -0,0 +1,139 @@
+{
+ "$schema": "../schemas/hooks-metadata.schema.json",
+ "entries": {
+ "PreToolUse": [
+ {
+ "id": "pre:bash:dispatcher",
+ "description": "Consolidated Bash preflight dispatcher for quality, tmux, push, and GateGuard checks",
+ "fingerprint": "0d30f37d2148"
+ },
+ {
+ "id": "pre:powershell:gateguard-fact-force",
+ "description": "PowerShell fact-forcing gate: inspect destructive commands without running unrelated Bash-only preflight hooks",
+ "fingerprint": "63877b632223"
+ },
+ {
+ "id": "pre:write:doc-file-warning",
+ "description": "Doc file warning: warn about non-standard documentation files (exit code 0; warns only)",
+ "fingerprint": "595406f864e2"
+ },
+ {
+ "id": "pre:edit-write:suggest-compact",
+ "description": "Suggest manual compaction at logical intervals",
+ "fingerprint": "d99998a8f039"
+ },
+ {
+ "id": "pre:observe:continuous-learning",
+ "description": "Capture tool use observations for continuous learning",
+ "fingerprint": "17f73ac2a883"
+ },
+ {
+ "id": "pre:governance-capture",
+ "description": "Capture governance events (secrets, policy violations, approval requests). Enable with ECC_GOVERNANCE_CAPTURE=1",
+ "fingerprint": "ffa978692652"
+ },
+ {
+ "id": "pre:config-protection",
+ "description": "Block modifications to linter/formatter config files. Steers agent to fix code instead of weakening configs.",
+ "fingerprint": "2b2be80bbeb3"
+ },
+ {
+ "id": "pre:mcp-health-check",
+ "description": "Check MCP server health before MCP tool execution and block unhealthy MCP calls",
+ "fingerprint": "922686364d01"
+ },
+ {
+ "id": "pre:edit-write:gateguard-fact-force",
+ "description": "Fact-forcing gate: block first Edit/Write/MultiEdit per file and demand investigation (importers, data schemas, user instruction) before allowing",
+ "fingerprint": "32c4a312b4c2"
+ }
+ ],
+ "PreCompact": [
+ {
+ "id": "pre:compact",
+ "description": "Save state before context compaction",
+ "fingerprint": "5a4ef4aaa985"
+ }
+ ],
+ "SessionStart": [
+ {
+ "id": "session:start",
+ "description": "Load previous context and detect package manager on new session",
+ "fingerprint": "3bbe414382a5"
+ },
+ {
+ "id": "session-start:plan-canvas-sessions",
+ "description": "Surface open Plan Canvas review sessions so a fresh session can resume the loop",
+ "fingerprint": "ad75ab423357"
+ }
+ ],
+ "PostToolUse": [
+ {
+ "id": "post:dispatcher:sync",
+ "description": "Run synchronous PostToolUse hooks in one process while preserving per-hook controls",
+ "fingerprint": "cc868baab727"
+ },
+ {
+ "id": "post:dispatcher:async",
+ "description": "Run background PostToolUse hooks in one process while preserving per-hook controls",
+ "fingerprint": "5e256d15db44"
+ }
+ ],
+ "PostToolUseFailure": [
+ {
+ "id": "post:mcp-health-check",
+ "description": "Track failed MCP tool calls, mark unhealthy servers, and attempt reconnect",
+ "fingerprint": "9e25549c1229"
+ },
+ {
+ "id": "post:skill:track",
+ "description": "Record hard Skill tool failures for skill-health telemetry",
+ "fingerprint": "a4dbe0729f30"
+ }
+ ],
+ "Stop": [
+ {
+ "id": "stop:plan-canvas-pending",
+ "description": "Deliver undelivered Plan Canvas browser feedback before the agent stops",
+ "fingerprint": "e1a0fd79c26f"
+ },
+ {
+ "id": "stop:format-typecheck",
+ "description": "Batch format (Biome/Prettier) and typecheck (tsc) all JS/TS files edited this response — runs once at Stop instead of after every Edit",
+ "fingerprint": "9836d01e962e"
+ },
+ {
+ "id": "stop:check-console-log",
+ "description": "Check for console.log in modified files after each response",
+ "fingerprint": "235c7f182b76"
+ },
+ {
+ "id": "stop:session-end",
+ "description": "Persist session state after each response (Stop carries transcript_path)",
+ "fingerprint": "981212c32849"
+ },
+ {
+ "id": "stop:evaluate-session",
+ "description": "Evaluate session for extractable patterns",
+ "fingerprint": "d874ecf69ef7"
+ },
+ {
+ "id": "stop:cost-tracker",
+ "description": "Track token and cost metrics per session",
+ "fingerprint": "57d255146fc0"
+ },
+ {
+ "id": "stop:desktop-notify",
+ "description": "Send desktop notification (macOS/WSL) with task summary when Claude responds",
+ "fingerprint": "668cdbae027d"
+ }
+ ],
+ "SessionEnd": [
+ {
+ "id": "session:end:marker",
+ "description": "Session end lifecycle marker (non-blocking)",
+ "fingerprint": "23a3832480e1"
+ }
+ ]
+ }
+}
diff --git a/schemas/hooks-metadata.schema.json b/schemas/hooks-metadata.schema.json
new file mode 100644
index 000000000..7cae9d4a4
--- /dev/null
+++ b/schemas/hooks-metadata.schema.json
@@ -0,0 +1,67 @@
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "title": "ECC Hooks Metadata",
+ "description": "Stable ids and human-readable descriptions for the matcher entries in hooks/hooks.json. Kept in a sidecar because Claude Code reports any key outside its own hooks schema as an unknown key when the plugin loads.",
+ "type": "object",
+ "required": [
+ "entries"
+ ],
+ "properties": {
+ "$schema": {
+ "type": "string"
+ },
+ "entries": {
+ "type": "object",
+ "description": "Event name to an array aligned by index with the same event's entries in hooks.json.",
+ "propertyNames": {
+ "enum": [
+ "SessionStart",
+ "UserPromptSubmit",
+ "PreToolUse",
+ "PermissionRequest",
+ "PostToolUse",
+ "PostToolUseFailure",
+ "Notification",
+ "SubagentStart",
+ "Stop",
+ "SubagentStop",
+ "PreCompact",
+ "InstructionsLoaded",
+ "TeammateIdle",
+ "TaskCompleted",
+ "ConfigChange",
+ "WorktreeCreate",
+ "WorktreeRemove",
+ "SessionEnd"
+ ]
+ },
+ "additionalProperties": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "required": [
+ "id",
+ "fingerprint"
+ ],
+ "properties": {
+ "id": {
+ "type": "string",
+ "pattern": "\\S",
+ "description": "Stable, globally unique identifier for the matcher entry at this index."
+ },
+ "description": {
+ "type": "string"
+ },
+ "fingerprint": {
+ "type": "string",
+ "pattern": "^[0-9a-f]{12}$",
+ "description": "First 12 hex characters of the SHA-256 of the matcher entry (matcher + hooks, keys sorted) at this index in hooks.json. Binds the sidecar entry to a specific matcher so a reorder is detected. Regenerate with `node scripts/ci/validate-hooks.js --update-fingerprints`."
+ }
+ },
+ "additionalProperties": false
+ }
+ }
+ }
+ },
+ "additionalProperties": false
+}
diff --git a/scripts/ci/validate-hooks.js b/scripts/ci/validate-hooks.js
index d59807f1d..2156b07dd 100644
--- a/scripts/ci/validate-hooks.js
+++ b/scripts/ci/validate-hooks.js
@@ -8,8 +8,49 @@ const path = require('path');
const vm = require('vm');
const Ajv = require('ajv');
+/**
+ * Resolve a module by its repo-relative path.
+ *
+ * Test harnesses copy this validator to the repo root before running it, so a
+ * plain relative require would break. Walk up from __dirname until the module
+ * is found instead.
+ *
+ * @param {string} repoRelativePath - e.g. 'scripts/lib/hooks-config.js'
+ * @returns {string} absolute path to the module
+ */
+function resolveRepoModule(repoRelativePath) {
+ let dir = __dirname;
+ for (;;) {
+ const candidate = path.join(dir, repoRelativePath);
+ if (fs.existsSync(candidate)) {
+ return candidate;
+ }
+ const parent = path.dirname(dir);
+ if (parent === dir) {
+ throw new Error(`Cannot locate ${repoRelativePath} above ${__dirname}`);
+ }
+ dir = parent;
+ }
+}
+
+const {
+ METADATA_FILENAME,
+ applyHooksMetadata,
+ findMetadataMismatches,
+ metadataPathFor,
+ withRefreshedFingerprints,
+} = require(resolveRepoModule('scripts/lib/hooks-config.js'));
+
const HOOKS_FILE = path.join(__dirname, '../../hooks/hooks.json');
const HOOKS_SCHEMA_PATH = path.join(__dirname, '../../schemas/hooks.schema.json');
+const METADATA_SCHEMA_PATH = path.join(__dirname, '../../schemas/hooks-metadata.schema.json');
+// `--update-fingerprints` rewrites the sidecar's fingerprints from the current
+// hooks.json instead of validating. Run it after changing a hook command.
+const UPDATE_FINGERPRINTS = process.argv.includes('--update-fingerprints');
+// Keys Claude Code's own hooks schema rejects. Keeping them out of hooks.json is
+// what stops "unknown keys ... ignored" warnings when the plugin loads.
+const HARNESS_UNKNOWN_ROOT_KEYS = ['$schema'];
+const HARNESS_UNKNOWN_MATCHER_KEYS = ['id', 'description'];
const VALID_EVENTS = [
'SessionStart',
'UserPromptSubmit',
@@ -124,6 +165,78 @@ function validateHookEntry(hook, label) {
return hasErrors;
}
+/**
+ * Reject keys the Claude Code harness does not understand.
+ *
+ * Claude Code validates a plugin's hooks.json against its own schema and prints
+ * every unrecognised key at load time. Once a hooks.metadata.json sidecar is
+ * present it owns the stable ids and descriptions, so hooks.json must not
+ * carry them as well.
+ *
+ * @param {object} data - Parsed hooks.json.
+ * @returns {boolean} true if errors were found
+ */
+function validateHarnessCompatibility(data) {
+ if (!data || typeof data !== 'object' || Array.isArray(data)) {
+ return false;
+ }
+
+ let hasErrors = false;
+ for (const key of HARNESS_UNKNOWN_ROOT_KEYS) {
+ if (key in data) {
+ console.error(
+ `ERROR: hooks.json must not define "${key}" - Claude Code reports it as an unknown key`
+ );
+ hasErrors = true;
+ }
+ }
+
+ const events = data.hooks && typeof data.hooks === 'object' && !Array.isArray(data.hooks)
+ ? data.hooks
+ : {};
+ for (const [eventType, matchers] of Object.entries(events)) {
+ if (!Array.isArray(matchers)) continue;
+ matchers.forEach((matcher, index) => {
+ if (!matcher || typeof matcher !== 'object') return;
+ for (const key of HARNESS_UNKNOWN_MATCHER_KEYS) {
+ if (key in matcher) {
+ console.error(
+ `ERROR: hooks.json ${eventType}[${index}] must not define "${key}" - `
+ + `move it to ${METADATA_FILENAME}`
+ );
+ hasErrors = true;
+ }
+ }
+ });
+ }
+
+ return hasErrors;
+}
+
+/**
+ * Validate a parsed document against a JSON schema file, if the schema exists.
+ *
+ * @param {object} document - Parsed JSON to validate.
+ * @param {string} schemaPath - Path to the schema; skipped when absent.
+ * @param {string} label - Name used in error output.
+ * @returns {boolean} true if errors were found
+ */
+function validateAgainstSchema(document, schemaPath, label) {
+ if (!fs.existsSync(schemaPath)) {
+ return false;
+ }
+ const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf-8'));
+ const ajv = new Ajv({ allErrors: true });
+ const validate = ajv.compile(schema);
+ if (validate(document)) {
+ return false;
+ }
+ for (const err of validate.errors) {
+ console.error(`ERROR: ${label} schema: ${err.instancePath || '/'} ${err.message}`);
+ }
+ return true;
+}
+
function validateHooks() {
if (!fs.existsSync(HOOKS_FILE)) {
console.log('No hooks.json found, skipping validation');
@@ -138,18 +251,51 @@ function validateHooks() {
process.exit(1);
}
- // Validate against JSON schema
- if (fs.existsSync(HOOKS_SCHEMA_PATH)) {
- const schema = JSON.parse(fs.readFileSync(HOOKS_SCHEMA_PATH, 'utf-8'));
- const ajv = new Ajv({ allErrors: true });
- const validate = ajv.compile(schema);
- const valid = validate(data);
- if (!valid) {
- for (const err of validate.errors) {
- console.error(`ERROR: hooks.json schema: ${err.instancePath || '/'} ${err.message}`);
+ // Without a sidecar, hooks.json keeps its legacy inline ids. With one, the
+ // sidecar is the sole owner of id/description and hooks.json must stay
+ // within Claude Code's schema.
+ let metadata = null;
+ const metadataPath = metadataPathFor(HOOKS_FILE);
+ if (fs.existsSync(metadataPath)) {
+ try {
+ metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+ } catch (e) {
+ console.error(`ERROR: Invalid JSON in ${METADATA_FILENAME}: ${e.message}`);
+ process.exit(1);
+ }
+
+ if (validateHarnessCompatibility(data)) {
+ process.exit(1);
+ }
+
+ if (UPDATE_FINGERPRINTS) {
+ try {
+ metadata = withRefreshedFingerprints(data, metadata);
+ } catch (error) {
+ console.error(`ERROR: ${error.message}`);
+ process.exit(1);
+ }
+ }
+
+ if (validateAgainstSchema(metadata, METADATA_SCHEMA_PATH, METADATA_FILENAME)) {
+ process.exit(1);
+ }
+
+ const mismatches = findMetadataMismatches(data, metadata);
+ if (mismatches.length > 0) {
+ for (const mismatch of mismatches) {
+ console.error(`ERROR: ${mismatch}`);
}
process.exit(1);
}
+
+ // Validate the merged view so the id/description rules below still apply.
+ data = applyHooksMetadata(data, metadata);
+ }
+
+ // Validate against JSON schema
+ if (validateAgainstSchema(data, HOOKS_SCHEMA_PATH, 'hooks.json')) {
+ process.exit(1);
}
// Support both object format { hooks: {...} } and array format
@@ -254,6 +400,11 @@ function validateHooks() {
process.exit(1);
}
+ if (UPDATE_FINGERPRINTS && metadata) {
+ fs.writeFileSync(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`);
+ console.log(`Updated fingerprints in ${METADATA_FILENAME}`);
+ }
+
console.log(`Validated ${totalMatchers} hook matchers`);
}
diff --git a/scripts/dashboard-web.js b/scripts/dashboard-web.js
index 044a20fd7..5524853bd 100644
--- a/scripts/dashboard-web.js
+++ b/scripts/dashboard-web.js
@@ -19,6 +19,7 @@ const {
isAllowedOrigin,
} = require('./lib/loopback-guard');
const { normalizeAgentTools } = require('./lib/agent-tools');
+const { readHooksConfig } = require('./lib/hooks-config');
const DEFAULT_HOST = '127.0.0.1';
@@ -129,7 +130,9 @@ function loadHooks(_root) {
const hooksPath = path.join(root, 'hooks', 'hooks.json');
if (!fs.existsSync(hooksPath)) return [];
try {
- const data = JSON.parse(fs.readFileSync(hooksPath, 'utf8'));
+ // Ids and descriptions live in hooks/hooks.metadata.json so that hooks.json
+ // stays within the key set Claude Code's hooks schema accepts.
+ const data = readHooksConfig(hooksPath);
const hooks = [];
for (const [eventName, entries] of Object.entries(data.hooks || {})) {
for (const entry of entries || []) {
diff --git a/scripts/lib/hooks-config.js b/scripts/lib/hooks-config.js
new file mode 100644
index 000000000..11515c4bc
--- /dev/null
+++ b/scripts/lib/hooks-config.js
@@ -0,0 +1,318 @@
+'use strict';
+
+/**
+ * Read hooks/hooks.json together with its sibling hooks/hooks.metadata.json.
+ *
+ * Claude Code validates a plugin's hooks.json against its own schema and warns
+ * about every key it does not recognise, so ECC's stable matcher ids and
+ * human-readable descriptions cannot live in that file. They are kept in a
+ * sidecar keyed by event name and aligned with hooks.json entry order, and
+ * merged back here so the rest of ECC keeps seeing one object with `id` and
+ * `description` on each matcher entry.
+ *
+ * Index alignment alone cannot tell a reordered hooks.json from a correct one,
+ * so every sidecar entry also carries a fingerprint of the matcher entry it
+ * describes. A mismatch means the two files drifted apart.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const HOOKS_FILENAME = 'hooks.json';
+const METADATA_FILENAME = 'hooks.metadata.json';
+const FINGERPRINT_LENGTH = 12;
+const FINGERPRINT_PATTERN = /^[0-9a-f]{12}$/;
+
+function readJsonObject(filePath, label) {
+ let raw;
+ try {
+ raw = fs.readFileSync(filePath, 'utf8');
+ } catch (error) {
+ throw new Error(`Unable to read ${label} at ${filePath}: ${error.message}`);
+ }
+
+ let parsed;
+ try {
+ parsed = JSON.parse(raw);
+ } catch (error) {
+ throw new Error(`Invalid JSON in ${label} at ${filePath}: ${error.message}`);
+ }
+
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+ throw new Error(`Invalid ${label} at ${filePath}: expected a JSON object`);
+ }
+
+ return parsed;
+}
+
+function metadataPathFor(hooksPath) {
+ return path.join(path.dirname(hooksPath), METADATA_FILENAME);
+}
+
+/**
+ * JSON.stringify with object keys sorted, so a fingerprint does not change when
+ * someone reorders the keys inside a hook object.
+ */
+function stableStringify(value) {
+ if (Array.isArray(value)) {
+ return `[${value.map(stableStringify).join(',')}]`;
+ }
+ if (value && typeof value === 'object') {
+ return `{${Object.keys(value).sort().map(
+ key => `${JSON.stringify(key)}:${stableStringify(value[key])}`
+ ).join(',')}}`;
+ }
+ return JSON.stringify(value);
+}
+
+/**
+ * Fingerprint the parts of a hooks.json matcher entry that identify it: its
+ * matcher and its hook commands. Ids and descriptions are excluded so the
+ * fingerprint is the same whether or not metadata has been merged in.
+ *
+ * @param {object} entry - A matcher entry from hooks.json.
+ * @returns {string} short hex digest
+ */
+function fingerprintHookEntry(entry) {
+ const subject = {
+ matcher: entry && 'matcher' in entry ? entry.matcher : null,
+ hooks: entry && Array.isArray(entry.hooks) ? entry.hooks : [],
+ };
+ return crypto.createHash('sha256')
+ .update(stableStringify(subject))
+ .digest('hex')
+ .slice(0, FINGERPRINT_LENGTH);
+}
+
+function eventsOf(hooksConfig) {
+ return hooksConfig && typeof hooksConfig.hooks === 'object' && hooksConfig.hooks
+ && !Array.isArray(hooksConfig.hooks)
+ ? hooksConfig.hooks
+ : null;
+}
+
+function metadataEntriesOf(metadata) {
+ return metadata && typeof metadata.entries === 'object' && metadata.entries
+ && !Array.isArray(metadata.entries)
+ ? metadata.entries
+ : null;
+}
+
+/**
+ * Merge sidecar metadata into a parsed hooks.json object.
+ *
+ * Neither argument is mutated; the returned config shares untouched matcher
+ * entries with the input and copies the ones that receive metadata.
+ *
+ * @param {object} hooksConfig - Parsed hooks.json.
+ * @param {object|null} metadata - Parsed hooks.metadata.json, or null when absent.
+ * @returns {object} a new hooks configuration with id/description restored.
+ */
+function applyHooksMetadata(hooksConfig, metadata) {
+ const events = eventsOf(hooksConfig);
+ const entriesByEvent = metadataEntriesOf(metadata);
+ if (!events || !entriesByEvent) {
+ return hooksConfig;
+ }
+
+ const mergedEvents = {};
+ for (const [event, entries] of Object.entries(events)) {
+ const eventMetadata = entriesByEvent[event];
+ if (!Array.isArray(entries) || !Array.isArray(eventMetadata)) {
+ mergedEvents[event] = entries;
+ continue;
+ }
+
+ mergedEvents[event] = entries.map((entry, index) => {
+ const entryMetadata = eventMetadata[index];
+ if (!entry || typeof entry !== 'object') return entry;
+ if (!entryMetadata || typeof entryMetadata !== 'object') return entry;
+
+ const merged = { ...entry };
+ if (typeof entryMetadata.id === 'string' && !('id' in entry)) {
+ merged.id = entryMetadata.id;
+ }
+ if (typeof entryMetadata.description === 'string' && !('description' in entry)) {
+ merged.description = entryMetadata.description;
+ }
+ return merged;
+ });
+ }
+
+ return { ...hooksConfig, hooks: mergedEvents };
+}
+
+/**
+ * Report entries whose metadata is missing, misaligned, or bound to a
+ * different matcher entry than the one at the same index.
+ *
+ * @param {object} hooksConfig - Parsed hooks.json.
+ * @param {object|null} metadata - Parsed hooks.metadata.json.
+ * @returns {string[]} human-readable problems; empty when the sidecar lines up.
+ */
+function findMetadataMismatches(hooksConfig, metadata) {
+ const problems = [];
+ const idLocations = new Map();
+ const events = eventsOf(hooksConfig) || {};
+ const entriesByEvent = metadataEntriesOf(metadata) || {};
+
+ for (const [event, entries] of Object.entries(events)) {
+ if (!Array.isArray(entries)) continue;
+ const eventMetadata = entriesByEvent[event];
+
+ if (!Array.isArray(eventMetadata)) {
+ problems.push(`${METADATA_FILENAME} is missing entries for event "${event}"`);
+ continue;
+ }
+ if (eventMetadata.length !== entries.length) {
+ problems.push(
+ `${METADATA_FILENAME} lists ${eventMetadata.length} entr(ies) for event "${event}" `
+ + `but ${HOOKS_FILENAME} has ${entries.length}`
+ );
+ continue;
+ }
+
+ eventMetadata.forEach((entry, index) => {
+ const label = `${METADATA_FILENAME} ${event}[${index}]`;
+ if (!entry || typeof entry !== 'object') {
+ problems.push(`${label} is not an object`);
+ return;
+ }
+ if (typeof entry.id !== 'string' || entry.id.trim() === '') {
+ problems.push(`${label} is missing a non-empty "id"`);
+ } else if (idLocations.has(entry.id)) {
+ problems.push(`${label} has duplicate id "${entry.id}" already used by ${idLocations.get(entry.id)}`);
+ } else {
+ idLocations.set(entry.id, label);
+ }
+ if ('description' in entry && typeof entry.description !== 'string') {
+ problems.push(`${label} has a non-string "description"`);
+ }
+ if (typeof entry.fingerprint !== 'string' || !FINGERPRINT_PATTERN.test(entry.fingerprint)) {
+ problems.push(`${label} is missing a valid "fingerprint"`);
+ return;
+ }
+ const expected = fingerprintHookEntry(entries[index]);
+ if (entry.fingerprint !== expected) {
+ problems.push(
+ `${label} (id "${entry.id}") fingerprint ${entry.fingerprint} does not match `
+ + `${HOOKS_FILENAME} ${event}[${index}] (${expected}); the entries were reordered `
+ + 'or the hook command changed - regenerate with '
+ + 'node scripts/ci/validate-hooks.js --update-fingerprints'
+ );
+ }
+ });
+ }
+
+ for (const event of Object.keys(entriesByEvent)) {
+ if (!Array.isArray(events[event])) {
+ problems.push(`${METADATA_FILENAME} describes event "${event}" which ${HOOKS_FILENAME} does not define`);
+ }
+ }
+
+ return problems;
+}
+
+/**
+ * Return a copy of the sidecar with every fingerprint recomputed from the
+ * matcher entry at the same index. Used to refresh the sidecar after hook
+ * commands change.
+ *
+ * @param {object} hooksConfig - Parsed hooks.json.
+ * @param {object} metadata - Parsed hooks.metadata.json.
+ * @returns {object} a new metadata object
+ */
+function withRefreshedFingerprints(hooksConfig, metadata) {
+ const events = eventsOf(hooksConfig) || {};
+ const entriesByEvent = metadataEntriesOf(metadata) || {};
+ const refreshed = {};
+
+ // A known fingerprint at another position signals a reorder, not a command
+ // edit. Require the author to move its metadata before refreshing anything.
+ const positions = new Map();
+ for (const [event, entries] of Object.entries(events)) {
+ if (!Array.isArray(entries)) continue;
+ entries.forEach((entry, index) => {
+ const fingerprint = fingerprintHookEntry(entry);
+ const locations = positions.get(fingerprint) || [];
+ positions.set(fingerprint, [...locations, `${event}[${index}]`]);
+ });
+ }
+ for (const [event, entries] of Object.entries(entriesByEvent)) {
+ if (!Array.isArray(entries)) continue;
+ entries.forEach((entry, index) => {
+ const locations = positions.get(entry?.fingerprint);
+ const location = `${event}[${index}]`;
+ if (locations && !locations.includes(location)) {
+ throw new Error(`Metadata reorder detected at ${location}; move the matching sidecar entry before refreshing fingerprints`);
+ }
+ });
+ }
+
+ for (const [event, eventMetadata] of Object.entries(entriesByEvent)) {
+ const entries = Array.isArray(events[event]) ? events[event] : [];
+ refreshed[event] = Array.isArray(eventMetadata)
+ ? eventMetadata.map((entry, index) => (
+ entry && typeof entry === 'object' && index < entries.length
+ ? { ...entry, fingerprint: fingerprintHookEntry(entries[index]) }
+ : entry
+ ))
+ : eventMetadata;
+ }
+
+ return { ...metadata, entries: refreshed };
+}
+
+function assertMetadataAligned(hooksConfig, metadata, hooksPath) {
+ const mismatches = findMetadataMismatches(hooksConfig, metadata);
+ if (mismatches.length > 0) {
+ throw new Error(
+ `${METADATA_FILENAME} does not line up with ${hooksPath}:\n ${mismatches.join('\n ')}`
+ );
+ }
+}
+
+/**
+ * Merge a sidecar into a hooks config, rejecting a sidecar that does not line
+ * up. Shared by the readers below so a truncated or reordered sidecar fails
+ * loudly instead of producing entries with the wrong or missing ids.
+ *
+ * @param {object} hooksConfig - Parsed hooks.json.
+ * @param {object} metadata - Parsed hooks.metadata.json.
+ * @param {string} hooksPath - Used in the error message.
+ * @returns {object} a new merged hooks configuration
+ */
+function mergeHooksMetadata(hooksConfig, metadata, hooksPath = HOOKS_FILENAME) {
+ assertMetadataAligned(hooksConfig, metadata, hooksPath);
+ return applyHooksMetadata(hooksConfig, metadata);
+}
+
+/**
+ * Read hooks.json and return it with sidecar metadata merged in.
+ *
+ * @param {string} hooksPath - Path to hooks/hooks.json.
+ * @param {string} [label] - Label used in error messages.
+ * @returns {object} the merged hooks configuration.
+ */
+function readHooksConfig(hooksPath, label = HOOKS_FILENAME) {
+ const hooksConfig = readJsonObject(hooksPath, label);
+ const metadataPath = metadataPathFor(hooksPath);
+ if (!fs.existsSync(metadataPath)) {
+ return hooksConfig;
+ }
+ return mergeHooksMetadata(hooksConfig, readJsonObject(metadataPath, METADATA_FILENAME), hooksPath);
+}
+
+module.exports = {
+ HOOKS_FILENAME,
+ METADATA_FILENAME,
+ applyHooksMetadata,
+ findMetadataMismatches,
+ fingerprintHookEntry,
+ mergeHooksMetadata,
+ metadataPathFor,
+ readHooksConfig,
+ readJsonObject,
+ withRefreshedFingerprints,
+};
diff --git a/scripts/lib/install-lifecycle.js b/scripts/lib/install-lifecycle.js
index 99ec19614..ec9cb1d80 100644
--- a/scripts/lib/install-lifecycle.js
+++ b/scripts/lib/install-lifecycle.js
@@ -36,6 +36,7 @@ const { adaptAntigravityAgent } = require('./install/antigravity-agent');
const { buildInstallIndex, rewriteRelativeLinks } = require('./install/link-rewrite');
const { getInstallTargetAdapter, listInstallTargetAdapters } = require('./install-targets/registry');
const { resolveInvocationEnvironment } = require('./invocation-environment');
+const { mergeHooksMetadata, metadataPathFor } = require('./hooks-config');
const OPENCODE_BUILD_ARTIFACT = path.join('.opencode', 'dist');
const OPENCODE_BUILD_SCRIPT = path.join('scripts', 'build-opencode.js');
const OPENCODE_PLUGIN_NOT_BUILT_CODE = 'opencode-plugin-not-built';
@@ -535,6 +536,25 @@ function readJsonNoFollow(filePath) {
return JSON.parse(readFileNoFollow(filePath, 'utf8'));
}
+/**
+ * Read hooks.json and merge in hooks/hooks.metadata.json without following
+ * symlinks. The sidecar holds the stable matcher ids that hooks.json cannot
+ * carry, because Claude Code reports unknown keys when the plugin loads. A
+ * sidecar that does not line up with hooks.json is rejected before repair can
+ * reconcile matchers under the wrong ids.
+ *
+ * @param {string} hooksPath - Path to the source hooks.json.
+ * @returns {object} the hooks configuration with ids and descriptions restored.
+ */
+function readHooksConfigNoFollow(hooksPath) {
+ const hooksConfig = readJsonNoFollow(hooksPath);
+ const metadataPath = metadataPathFor(hooksPath);
+ if (!fs.existsSync(metadataPath)) {
+ return hooksConfig;
+ }
+ return mergeHooksMetadata(hooksConfig, readJsonNoFollow(metadataPath), hooksPath);
+}
+
function assertClaudeSettingsDestination(operation, trustedRoot, target = null) {
if (target && target !== 'claude' && target !== 'claude-project') {
throw new Error('Refusing to manage Claude hooks for a non-Claude target.');
@@ -720,7 +740,7 @@ function hydrateRecordedOperations(repoRoot, operations, trustedRoot) {
sourcePath,
previousManagedHooks: operation.managedHooks,
managedHooks: materializeManagedHooks(
- readJsonNoFollow(sourcePath),
+ readHooksConfigNoFollow(sourcePath),
trustedRoot
),
};
diff --git a/scripts/lib/install-targets/helpers.js b/scripts/lib/install-targets/helpers.js
index dbb5b44e5..f69d75e86 100644
--- a/scripts/lib/install-targets/helpers.js
+++ b/scripts/lib/install-targets/helpers.js
@@ -5,6 +5,7 @@ const {
CLAUDE_HOOKS_CONFIG_PATH,
getClaudeSettingsPath,
} = require('../install/claude-settings');
+const { METADATA_FILENAME } = require('../hooks-config');
const PLATFORM_SOURCE_PATH_OWNERS = Object.freeze({
'.claude-plugin': 'claude',
@@ -176,7 +177,9 @@ function planClaudeHooksOperations(adapter, module, input) {
return [
...operations,
...fs.readdirSync(sourceHooksRoot, { withFileTypes: true })
- .filter(entry => entry.name !== 'hooks.json')
+ // hooks.json is merged into settings.json above, and its metadata sidecar
+ // is consumed with it, so neither is scaffolded into the target hooks dir.
+ .filter(entry => entry.name !== 'hooks.json' && entry.name !== METADATA_FILENAME)
.sort((left, right) => left.name.localeCompare(right.name))
.map(entry => adapter.createScaffoldOperation(
module.id,
diff --git a/scripts/lib/install/plan.js b/scripts/lib/install/plan.js
index 08173a672..1400557c7 100644
--- a/scripts/lib/install/plan.js
+++ b/scripts/lib/install/plan.js
@@ -7,6 +7,7 @@ const { execFileSync } = require('child_process');
const { resolveInstallPlan } = require('../install-manifests');
const { getInstallTargetAdapter } = require('../install-targets/registry');
const { resolveInvocationEnvironment } = require('../invocation-environment');
+const { readHooksConfig } = require('../hooks-config');
const {
materializeManagedHooks,
} = require('./claude-settings');
@@ -136,7 +137,9 @@ function materializeClaudeSettingsOperation(sourceRoot, operation) {
return [];
}
- const hooksConfig = readJsonObject(sourcePath, operation.sourceRelativePath);
+ // Stable ids and descriptions live in hooks/hooks.metadata.json; readHooksConfig
+ // merges them back so managed settings entries keep their ids.
+ const hooksConfig = readHooksConfig(sourcePath, operation.sourceRelativePath);
const managedHooks = materializeManagedHooks(
hooksConfig,
path.dirname(operation.destinationPath)
diff --git a/tests/hooks/continuous-learning-observe-runner.test.js b/tests/hooks/continuous-learning-observe-runner.test.js
index 37ca3ce31..9445a3c1d 100644
--- a/tests/hooks/continuous-learning-observe-runner.test.js
+++ b/tests/hooks/continuous-learning-observe-runner.test.js
@@ -17,6 +17,7 @@ const hooksJsonPath = path.join(repoRoot, 'hooks', 'hooks.json');
const runWithFlagsPath = path.join(repoRoot, 'scripts', 'hooks', 'run-with-flags.js');
const observeRunner = require(path.join(repoRoot, 'scripts', 'hooks', 'observe-runner.js'));
const postToolUseDispatcher = require(path.join(repoRoot, 'scripts', 'hooks', 'posttooluse-dispatcher.js'));
+const { readHooksConfig } = require(path.join(repoRoot, 'scripts', 'lib', 'hooks-config.js'));
function test(name, fn) {
try {
@@ -31,7 +32,7 @@ function test(name, fn) {
}
function loadHook(id) {
- const hookGroups = JSON.parse(fs.readFileSync(hooksJsonPath, 'utf8')).hooks;
+ const hookGroups = readHooksConfig(hooksJsonPath).hooks;
const hooks = Object.values(hookGroups).flat();
const hook = hooks.find(candidate => candidate.id === id);
assert.ok(hook, `Expected ${id} in hooks/hooks.json`);
diff --git a/tests/hooks/hooks-metadata.test.js b/tests/hooks/hooks-metadata.test.js
new file mode 100644
index 000000000..5294d91fe
--- /dev/null
+++ b/tests/hooks/hooks-metadata.test.js
@@ -0,0 +1,293 @@
+/**
+ * Tests for the hooks.json / hooks.metadata.json split.
+ *
+ * Claude Code validates a plugin's hooks.json against its own schema and prints
+ * every key it does not recognise when the plugin loads. These tests keep the
+ * unknown keys out of hooks.json and keep the sidecar aligned with it.
+ *
+ * Run with: node tests/hooks/hooks-metadata.test.js
+ */
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const {
+ applyHooksMetadata,
+ findMetadataMismatches,
+ fingerprintHookEntry,
+ metadataPathFor,
+ readHooksConfig,
+ withRefreshedFingerprints,
+} = require('../../scripts/lib/hooks-config');
+
+const REPO_ROOT = path.resolve(__dirname, '../..');
+const HOOKS_PATH = path.join(REPO_ROOT, 'hooks', 'hooks.json');
+const METADATA_PATH = metadataPathFor(HOOKS_PATH);
+
+function readJson(filePath) {
+ return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function eachMatcher(hooksConfig, visit) {
+ for (const [event, entries] of Object.entries(hooksConfig.hooks || {})) {
+ (entries || []).forEach((entry, index) => visit(entry, `${event}[${index}]`));
+ }
+}
+
+const tests = [];
+function test(name, fn) {
+ tests.push({ name, fn });
+}
+
+test('hooks.json does not declare $schema', () => {
+ const hooksConfig = readJson(HOOKS_PATH);
+ assert.ok(
+ !('$schema' in hooksConfig),
+ 'hooks.json must not define "$schema" - Claude Code reports it as an unknown key'
+ );
+});
+
+test('hooks.json matcher entries carry no id or description', () => {
+ const hooksConfig = readJson(HOOKS_PATH);
+ eachMatcher(hooksConfig, (entry, label) => {
+ assert.ok(!('id' in entry), `${label} must not define "id" - it belongs in hooks.metadata.json`);
+ assert.ok(
+ !('description' in entry),
+ `${label} must not define "description" - it belongs in hooks.metadata.json`
+ );
+ });
+});
+
+test('metadata sidecar exists and lines up with hooks.json', () => {
+ assert.ok(fs.existsSync(METADATA_PATH), 'hooks/hooks.metadata.json is missing');
+ const mismatches = findMetadataMismatches(readJson(HOOKS_PATH), readJson(METADATA_PATH));
+ assert.deepStrictEqual(mismatches, [], `metadata is misaligned:\n${mismatches.join('\n')}`);
+});
+
+test('every matcher entry has a unique id after merging', () => {
+ const merged = readHooksConfig(HOOKS_PATH);
+ const seen = new Map();
+ let count = 0;
+
+ eachMatcher(merged, (entry, label) => {
+ count += 1;
+ assert.ok(
+ typeof entry.id === 'string' && entry.id.trim() !== '',
+ `${label} has no id after merging metadata`
+ );
+ assert.ok(!seen.has(entry.id), `duplicate id "${entry.id}" at ${label} and ${seen.get(entry.id)}`);
+ seen.set(entry.id, label);
+ });
+
+ assert.ok(count > 0, 'expected at least one matcher entry');
+});
+
+test('merging leaves hook commands untouched', () => {
+ const raw = readJson(HOOKS_PATH);
+ const merged = readHooksConfig(HOOKS_PATH);
+
+ const commandsOf = config => Object.entries(config.hooks || {}).flatMap(([event, entries]) => (
+ (entries || []).flatMap((entry, index) => (entry.hooks || []).map(
+ (hook, hookIndex) => `${event}[${index}].hooks[${hookIndex}]:${JSON.stringify(hook)}`
+ ))
+ ));
+
+ assert.deepStrictEqual(commandsOf(merged), commandsOf(raw));
+});
+
+test('applyHooksMetadata does not overwrite an id already present', () => {
+ const hooksConfig = { hooks: { PreToolUse: [{ id: 'existing', matcher: 'Bash', hooks: [] }] } };
+ const merged = applyHooksMetadata(hooksConfig, { entries: { PreToolUse: [{ id: 'from-sidecar' }] } });
+ assert.strictEqual(merged.hooks.PreToolUse[0].id, 'existing');
+});
+
+test('applyHooksMetadata returns a new config and leaves its inputs untouched', () => {
+ const entry = { matcher: 'Bash', hooks: [{ type: 'command', command: 'node a.js' }] };
+ const hooksConfig = { hooks: { PreToolUse: [entry] } };
+ const metadata = { entries: { PreToolUse: [{ id: 'a', description: 'A' }] } };
+
+ const merged = applyHooksMetadata(hooksConfig, metadata);
+
+ assert.notStrictEqual(merged, hooksConfig);
+ assert.notStrictEqual(merged.hooks.PreToolUse[0], entry);
+ assert.deepStrictEqual(merged.hooks.PreToolUse[0], { ...entry, id: 'a', description: 'A' });
+ assert.deepStrictEqual(hooksConfig, { hooks: { PreToolUse: [entry] } });
+ assert.ok(!('id' in entry) && !('description' in entry), 'input entry must not be mutated');
+ assert.strictEqual(merged.hooks.PreToolUse[0].hooks, entry.hooks, 'untouched nested data is shared');
+});
+
+const alpha = { matcher: 'Bash', hooks: [{ type: 'command', command: 'node alpha.js' }] };
+const beta = { matcher: 'Bash', hooks: [{ type: 'command', command: 'node beta.js' }] };
+const alphaMeta = { id: 'a', fingerprint: fingerprintHookEntry(alpha) };
+const betaMeta = { id: 'b', fingerprint: fingerprintHookEntry(beta) };
+
+test('findMetadataMismatches reports length and coverage problems', () => {
+ const hooksConfig = { hooks: { PreToolUse: [alpha, beta] } };
+
+ assert.strictEqual(findMetadataMismatches(hooksConfig, { entries: {} }).length, 1);
+ assert.strictEqual(
+ findMetadataMismatches(hooksConfig, { entries: { PreToolUse: [alphaMeta] } }).length,
+ 1
+ );
+ assert.strictEqual(
+ findMetadataMismatches(hooksConfig, {
+ entries: { PreToolUse: [alphaMeta, { ...betaMeta, id: '' }] },
+ }).length,
+ 1
+ );
+ assert.strictEqual(
+ findMetadataMismatches(hooksConfig, {
+ entries: { PreToolUse: [alphaMeta, { ...betaMeta, description: 1 }] },
+ }).length,
+ 1
+ );
+ assert.strictEqual(
+ findMetadataMismatches(hooksConfig, {
+ entries: { PreToolUse: [alphaMeta, betaMeta], Stop: [] },
+ }).length,
+ 1
+ );
+ assert.deepStrictEqual(
+ findMetadataMismatches(hooksConfig, { entries: { PreToolUse: [alphaMeta, betaMeta] } }),
+ []
+ );
+});
+
+test('findMetadataMismatches detects reordered entries and missing fingerprints', () => {
+ const hooksConfig = { hooks: { PreToolUse: [alpha, beta] } };
+
+ const reordered = findMetadataMismatches(hooksConfig, { entries: { PreToolUse: [betaMeta, alphaMeta] } });
+ assert.strictEqual(reordered.length, 2, 'each swapped entry is reported');
+ assert.match(reordered[0], /PreToolUse\[0\] \(id "b"\) fingerprint .* does not match/);
+
+ const changed = findMetadataMismatches(
+ { hooks: { PreToolUse: [alpha, { ...beta, matcher: 'Write' }] } },
+ { entries: { PreToolUse: [alphaMeta, betaMeta] } }
+ );
+ assert.strictEqual(changed.length, 1, 'a changed matcher invalidates the fingerprint');
+
+ const missing = findMetadataMismatches(hooksConfig, {
+ entries: { PreToolUse: [{ id: 'a' }, { id: 'b', fingerprint: 'nope' }] },
+ });
+ assert.strictEqual(missing.length, 2);
+ assert.match(missing[0], /missing a valid "fingerprint"/);
+});
+
+test('fingerprintHookEntry ignores id, description, and key order', () => {
+ const base = fingerprintHookEntry(alpha);
+ assert.match(base, /^[0-9a-f]{12}$/);
+ assert.strictEqual(fingerprintHookEntry({ ...alpha, id: 'x', description: 'y' }), base);
+ assert.strictEqual(
+ fingerprintHookEntry({ hooks: [{ command: 'node alpha.js', type: 'command' }], matcher: 'Bash' }),
+ base
+ );
+ assert.notStrictEqual(fingerprintHookEntry(beta), base);
+});
+
+test('withRefreshedFingerprints rewrites fingerprints without touching ids', () => {
+ const hooksConfig = { hooks: { PreToolUse: [alpha, beta] } };
+ const stale = {
+ $schema: 's',
+ entries: { PreToolUse: [{ id: 'a', fingerprint: '000000000000' }, { id: 'b' }] },
+ };
+
+ const refreshed = withRefreshedFingerprints(hooksConfig, stale);
+
+ assert.deepStrictEqual(refreshed, { $schema: 's', entries: { PreToolUse: [alphaMeta, betaMeta] } });
+ assert.deepStrictEqual(findMetadataMismatches(hooksConfig, refreshed), []);
+ assert.strictEqual(stale.entries.PreToolUse[0].fingerprint, '000000000000', 'input is not mutated');
+});
+
+test('readHooksConfig rejects a sidecar that does not line up', () => {
+ const tempDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'ecc-hooks-'));
+ const tempHooks = path.join(tempDir, 'hooks.json');
+ fs.writeFileSync(tempHooks, JSON.stringify({ hooks: { PreToolUse: [alpha, beta] } }));
+ fs.writeFileSync(
+ metadataPathFor(tempHooks),
+ JSON.stringify({ entries: { PreToolUse: [betaMeta, alphaMeta] } })
+ );
+
+ try {
+ assert.throws(() => readHooksConfig(tempHooks), /does not line up with .*hooks\.json[\s\S]*fingerprint/);
+
+ fs.writeFileSync(
+ metadataPathFor(tempHooks),
+ JSON.stringify({ entries: { PreToolUse: [alphaMeta, betaMeta] } })
+ );
+ const merged = readHooksConfig(tempHooks);
+ assert.deepStrictEqual(merged.hooks.PreToolUse.map(entry => entry.id), ['a', 'b']);
+ } finally {
+ fs.rmSync(tempDir, { recursive: true, force: true });
+ }
+});
+
+test('readHooksConfig returns raw config when the sidecar is absent', () => {
+ const tempDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'ecc-hooks-'));
+ const tempHooks = path.join(tempDir, 'hooks.json');
+ fs.writeFileSync(tempHooks, JSON.stringify({ hooks: { Stop: [{ hooks: [] }] } }));
+
+ try {
+ const config = readHooksConfig(tempHooks);
+ assert.deepStrictEqual(config, { hooks: { Stop: [{ hooks: [] }] } });
+ } finally {
+ fs.rmSync(tempDir, { recursive: true, force: true });
+ }
+});
+
+test('failed refresh validation preserves the original sidecar bytes', () => {
+ const root = fs.mkdtempSync(path.join(require('os').tmpdir(), 'ecc-metadata-refresh-'));
+ try {
+ for (const relative of ['scripts/ci/validate-hooks.js', 'scripts/lib/hooks-config.js',
+ 'schemas/hooks.schema.json', 'schemas/hooks-metadata.schema.json']) {
+ const destination = path.join(root, relative);
+ fs.mkdirSync(path.dirname(destination), { recursive: true });
+ fs.copyFileSync(path.join(REPO_ROOT, relative), destination);
+ }
+ fs.mkdirSync(path.join(root, 'hooks'));
+ fs.writeFileSync(path.join(root, 'hooks/hooks.json'), JSON.stringify({ hooks: { PreToolUse: [alpha] } }));
+ const sidecar = path.join(root, 'hooks/hooks.metadata.json');
+ const original = JSON.stringify({ entries: { PreToolUse: [{ ...alphaMeta, id: '', fingerprint: '000000000000' }] } });
+ fs.writeFileSync(sidecar, original);
+ const result = require('child_process').spawnSync(process.execPath,
+ [path.join(root, 'scripts/ci/validate-hooks.js'), '--update-fingerprints'], {
+ encoding: 'utf8', env: { ...process.env, NODE_PATH: path.join(REPO_ROOT, 'node_modules') },
+ });
+ assert.strictEqual(result.status, 1, result.stderr);
+ assert.match(result.stderr, /id|non-empty/);
+ assert.strictEqual(fs.readFileSync(sidecar, 'utf8'), original);
+ } finally {
+ fs.rmSync(root, { recursive: true, force: true });
+ }
+});
+
+test('refresh refuses reordered hooks instead of rebinding stable ids', () => {
+ const config = { hooks: { PreToolUse: [beta, alpha] } };
+ const metadata = { entries: { PreToolUse: [alphaMeta, betaMeta] } };
+ assert.throws(() => withRefreshedFingerprints(config, metadata), /reorder/i);
+ assert.deepStrictEqual(metadata.entries.PreToolUse, [alphaMeta, betaMeta]);
+});
+
+test('alignment rejects duplicate ids across events', () => {
+ const config = { hooks: { PreToolUse: [alpha], PostToolUse: [beta] } };
+ const metadata = { entries: {
+ PreToolUse: [alphaMeta], PostToolUse: [{ ...betaMeta, id: alphaMeta.id }],
+ } };
+ assert.ok(findMetadataMismatches(config, metadata).some(problem =>
+ /duplicate/.test(problem) && /PreToolUse/.test(problem) && /PostToolUse/.test(problem)));
+});
+
+let failures = 0;
+for (const { name, fn } of tests) {
+ try {
+ fn();
+ console.log(` PASS ${name}`);
+ } catch (error) {
+ failures += 1;
+ console.error(` FAIL ${name}`);
+ console.error(` ${error.message}`);
+ }
+}
+
+console.log(`\nResults: Passed: ${tests.length - failures}, Failed: ${failures}`);
+process.exit(failures === 0 ? 0 : 1);
diff --git a/tests/hooks/hooks.test.js b/tests/hooks/hooks.test.js
index 93ad6133b..635566b27 100644
--- a/tests/hooks/hooks.test.js
+++ b/tests/hooks/hooks.test.js
@@ -9,6 +9,7 @@ const path = require('path');
const fs = require('fs');
const os = require('os');
const { execFileSync, spawn, spawnSync } = require('child_process');
+const { readHooksConfig } = require('../../scripts/lib/hooks-config');
const SKIP_BASH = process.platform === 'win32';
@@ -2573,7 +2574,7 @@ async function runTests() {
if (
test('hooks.json consolidates PreToolUse Bash and all PostToolUse hooks', () => {
const hooksPath = path.join(__dirname, '..', '..', 'hooks', 'hooks.json');
- const hooks = JSON.parse(fs.readFileSync(hooksPath, 'utf8'));
+ const hooks = readHooksConfig(hooksPath);
const preBash = hooks.hooks.PreToolUse.filter(entry => entry.matcher === 'Bash');
const postEntries = hooks.hooks.PostToolUse;
@@ -2602,7 +2603,7 @@ async function runTests() {
if (
test('hooks.json gives PowerShell dedicated GateGuard and governance routes', () => {
const hooksPath = path.join(__dirname, '..', '..', 'hooks', 'hooks.json');
- const hooks = JSON.parse(fs.readFileSync(hooksPath, 'utf8'));
+ const hooks = readHooksConfig(hooksPath);
const powerShellRoutes = hooks.hooks.PreToolUse.filter(entry => entry.matcher === 'PowerShell');
const governanceRoute = hooks.hooks.PreToolUse.find(entry => entry.id === 'pre:governance-capture');
@@ -2641,7 +2642,7 @@ async function runTests() {
if (
test('configured PowerShell routes enforce denial and emit redacted governance evidence', () => {
const root = path.join(__dirname, '..', '..');
- const hooks = JSON.parse(fs.readFileSync(path.join(root, 'hooks', 'hooks.json'), 'utf8'));
+ const hooks = readHooksConfig(path.join(root, 'hooks', 'hooks.json'));
const gateRoute = hooks.hooks.PreToolUse.find(entry => entry.id === 'pre:powershell:gateguard-fact-force');
const governanceRoute = hooks.hooks.PreToolUse.find(entry => entry.id === 'pre:governance-capture');
const stateDir = createTestDir();
diff --git a/tests/hooks/posttooluse-dispatcher.test.js b/tests/hooks/posttooluse-dispatcher.test.js
index c21f003f3..ae6dbaaa1 100644
--- a/tests/hooks/posttooluse-dispatcher.test.js
+++ b/tests/hooks/posttooluse-dispatcher.test.js
@@ -13,6 +13,7 @@ const { spawnSync } = require('child_process');
const repoRoot = path.join(__dirname, '..', '..');
const hooksPath = path.join(repoRoot, 'hooks', 'hooks.json');
const dispatcherPath = path.join(repoRoot, 'scripts', 'hooks', 'posttooluse-dispatcher.js');
+const { readHooksConfig } = require(path.join(repoRoot, 'scripts', 'lib', 'hooks-config.js'));
function test(name, fn) {
try {
@@ -78,7 +79,7 @@ function runTests() {
if (
test('hooks.json exposes one sync and one async PostToolUse entry', () => {
- const entries = JSON.parse(fs.readFileSync(hooksPath, 'utf8')).hooks.PostToolUse;
+ const entries = readHooksConfig(hooksPath).hooks.PostToolUse;
assert.strictEqual(entries.length, 2, 'PostToolUse should launch at most two commands');
assert.deepStrictEqual(
entries.map(entry => entry.id),
@@ -162,7 +163,7 @@ function runTests() {
if (
test('actual hooks.json commands preserve Edit dry-run output and IDs', () => {
- const entries = JSON.parse(fs.readFileSync(hooksPath, 'utf8')).hooks.PostToolUse;
+ const entries = readHooksConfig(hooksPath).hooks.PostToolUse;
const raw = JSON.stringify({
hook_event_name: 'PostToolUse',
tool_name: 'Edit',
@@ -194,7 +195,7 @@ function runTests() {
if (
test('actual hooks.json commands never echo truncated oversized input', () => {
- const entries = JSON.parse(fs.readFileSync(hooksPath, 'utf8')).hooks.PostToolUse;
+ const entries = readHooksConfig(hooksPath).hooks.PostToolUse;
const values = ['x'.repeat(1024 * 1024 + 1024), 'é'.repeat(600000), '\u{1F600}'.repeat(300000)];
for (const value of values) {
@@ -270,7 +271,7 @@ function runTests() {
if (
test('public dispatcher IDs disable their complete phase', () => {
- const entries = JSON.parse(fs.readFileSync(hooksPath, 'utf8')).hooks.PostToolUse;
+ const entries = readHooksConfig(hooksPath).hooks.PostToolUse;
const raw = JSON.stringify({
hook_event_name: 'PostToolUse',
tool_name: 'Edit',
@@ -480,7 +481,7 @@ function runTests() {
assert.strictEqual(result.status, 0, result.stderr);
assert.strictEqual(result.stdout, '', 'require() alone must not run main() or echo stdin');
- const entries = JSON.parse(fs.readFileSync(hooksPath, 'utf8')).hooks.PostToolUse;
+ const entries = readHooksConfig(hooksPath).hooks.PostToolUse;
assert.ok(
entries.every(entry => entry.hooks[0].command.includes('require(s).cli()')),
'hooks.json must invoke the explicit cli() entrypoint'
diff --git a/tests/hooks/skill-run-tracker.test.js b/tests/hooks/skill-run-tracker.test.js
index bd97b50c8..d3e63e247 100644
--- a/tests/hooks/skill-run-tracker.test.js
+++ b/tests/hooks/skill-run-tracker.test.js
@@ -16,6 +16,7 @@ const os = require('os');
const path = require('path');
const { buildRecord, deriveOutcome, extractSkillId, run } = require('../../scripts/hooks/skill-run-tracker');
+const { readHooksConfig } = require('../../scripts/lib/hooks-config');
const {
MAX_RUN_RECORDS,
RUNS_FILE_MODE,
@@ -238,9 +239,7 @@ test('an end-to-end Skill hook run lands exactly one non-sensitive record', () =
// needs its own hooks.json entry. Without it, hard Skill failures are silently
// dropped and the dashboard's success rate is inflated.
test('the tracker is registered for PostToolUseFailure so hard failures are recorded', () => {
- const hooksConfig = JSON.parse(
- fs.readFileSync(path.join(__dirname, '..', '..', 'hooks', 'hooks.json'), 'utf8')
- );
+ const hooksConfig = readHooksConfig(path.join(__dirname, '..', '..', 'hooks', 'hooks.json'));
const entries = (hooksConfig.hooks.PostToolUseFailure || [])
.filter(entry => entry.id === 'post:skill:track');
diff --git a/tests/hooks/stop-hooks-stdout.test.js b/tests/hooks/stop-hooks-stdout.test.js
index 3d0617c57..5d3efdf86 100644
--- a/tests/hooks/stop-hooks-stdout.test.js
+++ b/tests/hooks/stop-hooks-stdout.test.js
@@ -24,9 +24,8 @@ const { spawnSync } = require('child_process');
const repoRoot = path.join(__dirname, '..', '..');
const runner = path.join(repoRoot, 'scripts', 'hooks', 'run-with-flags.js');
-const hooksConfig = JSON.parse(
- fs.readFileSync(path.join(repoRoot, 'hooks', 'hooks.json'), 'utf8')
-);
+const { readHooksConfig } = require(path.join(repoRoot, 'scripts', 'lib', 'hooks-config.js'));
+const hooksConfig = readHooksConfig(path.join(repoRoot, 'hooks', 'hooks.json'));
const MAX_STDIN = 1024 * 1024;
const SUBPROCESS_TIMEOUT_MS = process.platform === 'darwin' && process.env.CI === 'true'
diff --git a/tests/integration/hooks.test.js b/tests/integration/hooks.test.js
index 677e2b952..96ad9b4d1 100644
--- a/tests/integration/hooks.test.js
+++ b/tests/integration/hooks.test.js
@@ -12,6 +12,7 @@ const path = require('path');
const fs = require('fs');
const os = require('os');
const { spawn } = require('child_process');
+const { readHooksConfig } = require('../../scripts/lib/hooks-config');
const REPO_ROOT = path.join(__dirname, '..', '..');
// Test helper
@@ -282,7 +283,7 @@ async function runTests() {
const scriptsDir = path.join(__dirname, '..', '..', 'scripts', 'hooks');
const hooksJsonPath = path.join(__dirname, '..', '..', 'hooks', 'hooks.json');
- const hooks = JSON.parse(fs.readFileSync(hooksJsonPath, 'utf8'));
+ const hooks = readHooksConfig(hooksJsonPath);
// ==========================================
// Input Format Tests
diff --git a/tests/lib/install-lifecycle.test.js b/tests/lib/install-lifecycle.test.js
index ab20e54ca..1eed5071b 100644
--- a/tests/lib/install-lifecycle.test.js
+++ b/tests/lib/install-lifecycle.test.js
@@ -27,6 +27,7 @@ const {
assertClaudeSettingsPath,
materializeManagedHooks,
} = require('../../scripts/lib/install/claude-settings');
+const { readHooksConfig } = require('../../scripts/lib/hooks-config');
const REPO_ROOT = path.join(__dirname, '..', '..');
const CURRENT_PACKAGE_VERSION = JSON.parse(
@@ -158,7 +159,7 @@ function managedHookEntry(id, command) {
function currentManagedHooks(targetRoot) {
return materializeManagedHooks(
- JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'hooks', 'hooks.json'), 'utf8')),
+ readHooksConfig(path.join(REPO_ROOT, 'hooks', 'hooks.json')),
targetRoot
);
}
diff --git a/tests/plugin-manifest.test.js b/tests/plugin-manifest.test.js
index 8f4ac1ba0..74bd25ec4 100644
--- a/tests/plugin-manifest.test.js
+++ b/tests/plugin-manifest.test.js
@@ -17,6 +17,7 @@
const assert = require('assert');
const fs = require('fs');
const path = require('path');
+const { readHooksConfig } = require('../scripts/lib/hooks-config');
const repoRoot = path.resolve(__dirname, '..');
const packageJsonPath = path.join(repoRoot, 'package.json');
@@ -394,7 +395,7 @@ test('codex lifecycle hook bundle contains only Codex 0.146-supported schema', (
}
}
- const claudeConfig = loadJsonObject(path.join(repoRoot, 'hooks', 'hooks.json'), 'hooks/hooks.json');
+ const claudeConfig = readHooksConfig(path.join(repoRoot, 'hooks', 'hooks.json'), 'hooks/hooks.json');
const sourceSessionStart = claudeConfig.hooks.SessionStart.find(group => group.id === 'session:start');
const expectedSessionStart = {
...sourceSessionStart,