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.

feat(hooks): add Hermes-native config-protection and console-log guards

ravitejarenangi879a17092cb1
diff --git a/docs/HERMES-HOOKS.md b/docs/HERMES-HOOKS.md
new file mode 100644
index 000000000..0ced4ea77
--- /dev/null
+++ b/docs/HERMES-HOOKS.md
@@ -0,0 +1,83 @@
+# Hermes Hooks — Native Guards Without the Hook Runtime
+
+Hermes ships its own shell-hook system: a `hooks:` block in `~/.hermes/config.yaml`,
+Claude-Code-compatible JSON payloads on stdin, per-tool regex matchers, a
+first-use consent allowlist, and `hermes hooks list | test | doctor` for
+inspection. ECC's `hooks/hooks.json` is Claude Code format, and the Hermes
+install target (`--target hermes`) deliberately does not install the hook
+runtime — so Hermes operators get ECC's rules, skills, and commands with no
+hooks at all.
+
+This directory ports the two ECC hooks that matter outside Claude Code as
+self-contained Hermes-native hooks. No ECC runtime, no `run-with-flags.js`, no
+`.pi` extension — just two Python scripts and a config block.
+
+## Why only these two
+
+ECC's hook graph is 24 commands. Most of it is Claude Code-specific
+(plugin bootstrap, plan canvas, Claude session transcripts, cost tracking
+against Claude's usage API) or duplicates the target harness's own gates.
+These two are harness-independent policy:
+
+1. **config-protection** — blocks edits to existing linter/formatter configs
+ (`.eslintrc*`, `eslint.config.*`, `.prettierrc*`, `biome.json`, `ruff.toml`,
+ `.stylelintrc*`, markdownlint) and lint ratchet baselines. An agent under
+ pressure weakens the check instead of fixing the code; this hook refuses
+ that path. Creating a config from scratch and reading configs stay allowed.
+2. **check-console-log** — warns (stderr, never blocks) when an edited
+ TS/JS file now contains `console.log()`. Tests, `.d.ts`, and scripts are
+ excluded.
+
+## Install
+
+```bash
+# 1. Put the scripts anywhere stable (they are referenced by absolute path):
+mkdir -p ~/.hermes/hooks
+cp hooks/hermes/config-protection.py ~/.hermes/hooks/ecc-config-protection.py
+cp hooks/hermes/check-console-log.py ~/.hermes/hooks/ecc-check-console-log.py
+chmod +x ~/.hermes/hooks/ecc-*.py
+
+# 2. Append to ~/.hermes/config.yaml (Hermes wants the mapping keyed by event):
+hooks:
+ pre_tool_call:
+ - matcher: "patch|write_file|edit|write|apply_patch|str_replace_editor"
+ command: "python3 /Users/YOU/.hermes/hooks/ecc-config-protection.py"
+ timeout: 10
+ post_tool_call:
+ - matcher: "patch|write_file|edit|write|apply_patch|str_replace_editor"
+ command: "python3 /Users/YOU/.hermes/hooks/ecc-check-console-log.py"
+ timeout: 10
+```
+
+Restart Hermes (hooks are registered at session start), then approve the
+consent prompt on first use of each hook, or pre-approve with:
+
+```bash
+hermes hooks test pre_tool_call --for-tool patch
+hermes hooks test post_tool_call --for-tool write_file
+```
+
+## Verify
+
+```bash
+hermes hooks list # both hooks, with consent status
+hermes hooks doctor # exec bit, allowlist, timing
+```
+
+Payload-level proof (block case must print a JSON decision; allow cases stay silent):
+
+```bash
+echo '{"hook_event_name":"pre_tool_call","tool_name":"patch","tool_input":{"path":"/repo/eslint.config.mjs","old_string":"a","new_string":"b"}}' \
+ | python3 ~/.hermes/hooks/ecc-config-protection.py
+# {"decision": "block", "reason": "BLOCKED: modifying eslint.config.mjs ..."}
+```
+
+## Notes
+
+- Match only the editing tools your Hermes config exposes; the shipped matcher
+ covers the common file-edit tool names.
+- Hermes matches tool names against the regex with `fullmatch`.
+- `post_tool_call` hooks cannot block; stderr is surfaced as a warning line.
+- Hooks fail open on malformed payloads by design (a broken hook must not
+ brick the agent); the config-protection hook emits its refusal as a JSON
+ `decision`, not an exit code, so a parse error can never block.
diff --git a/hooks/hermes/check-console-log.py b/hooks/hermes/check-console-log.py
new file mode 100755
index 000000000..c5a615075
--- /dev/null
+++ b/hooks/hermes/check-console-log.py
@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""
+Hermes native hook (ported from ECC's scripts/hooks/check-console-log.js).
+
+post_tool_call observer: after any file edit, WARN (never block) when the
+edited file now contains console.log(). Print to stderr only — Hermes shows
+hook stderr as a warning line.
+
+Contract (agent/shell_hooks.py):
+ stdin : JSON payload {"hook_event_name":"post_tool_call","tool_name":"...",
+ "tool_input":{...},"tool_result":{...}}
+ exit : 0 (observer, no stdout JSON)
+"""
+import json
+import os
+import re
+import sys
+
+EDIT_TOOLS = {"patch", "write_file", "edit", "write", "apply_patch", "str_replace_editor"}
+EXCLUDE = re.compile(r"(\.d\.ts$|/__tests?__/|\.test\.[tj]sx?$|\.spec\.[tj]sx?$|/scripts/|console-safety)")
+
+
+def main() -> int:
+ try:
+ raw = sys.stdin.read()
+ payload = json.loads(raw) if raw.strip() else {}
+ except Exception:
+ return 0
+
+ tool = str(payload.get("tool_name") or "")
+ if tool not in EDIT_TOOLS:
+ return 0
+
+ ti = payload.get("tool_input") or {}
+ path = None
+ for key in ("path", "file_path", "filePath", "target"):
+ v = ti.get(key)
+ if isinstance(v, str) and v.strip():
+ path = v.strip()
+ break
+ if not path or not os.path.isfile(path):
+ return 0
+ if not re.search(r"\.[tj]sx?$", path) or EXCLUDE.search(path):
+ return 0
+
+ try:
+ with open(path, "r", errors="replace") as f:
+ content = f.read()
+ except OSError:
+ return 0
+
+ if "console.log(" in content:
+ sys.stderr.write(
+ f"[hook] console.log() present in {path} — remove it before committing "
+ "(use the project logger instead)."
+ )
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
\ No newline at end of file
diff --git a/hooks/hermes/config-protection.py b/hooks/hermes/config-protection.py
new file mode 100755
index 000000000..8e68a222d
--- /dev/null
+++ b/hooks/hermes/config-protection.py
@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""
+Hermes native hook (ported from ECC's scripts/hooks/config-protection.js).
+
+pre_tool_call guard: BLOCK edits to existing linter/formatter config files.
+Agents under pressure weaken configs to make checks pass instead of fixing
+the source; this hook forces the fix to land in code.
+
+Contract (agent/shell_hooks.py):
+ stdin : JSON payload {"hook_event_name":"pre_tool_call","tool_name":"...",
+ "tool_input": {...}}
+ stdout : JSON {"decision":"block","reason":...} to block, nothing to allow
+ exit : 0 always (we speak JSON, not exit codes)
+
+Blocks ONLY file-editing tools, ONLY when the target already exists on disk.
+Creating a config from scratch is allowed (new project), and so is reading.
+"""
+import json
+import os
+import sys
+
+PROTECTED = {
+ ".eslintrc", ".eslintrc.js", ".eslintrc.cjs", ".eslintrc.json", ".eslintrc.yml", ".eslintrc.yaml",
+ "eslint.config.js", "eslint.config.mjs", "eslint.config.cjs", "eslint.config.ts",
+ "eslint.config.mts", "eslint.config.cts",
+ ".prettierrc", ".prettierrc.js", ".prettierrc.cjs", ".prettierrc.json", ".prettierrc.yml", ".prettierrc.yaml",
+ "prettier.config.js", "prettier.config.cjs", "prettier.config.mjs",
+ "biome.json", "biome.jsonc", ".ruff.toml", "ruff.toml", ".shellcheckrc",
+ ".stylelintrc", ".stylelintrc.json", ".stylelintrc.yml",
+ ".markdownlint.json", ".markdownlint.yaml", ".markdownlintrc",
+ # Aarogya ratchets — same class of "weaken the check instead of fixing code"
+ "lint-ratchet-baseline.json",
+}
+
+EDIT_TOOLS = {"patch", "write_file", "edit", "write", "apply_patch", "str_replace_editor"}
+
+
+def main() -> int:
+ try:
+ raw = sys.stdin.read()
+ payload = json.loads(raw) if raw.strip() else {}
+ except Exception:
+ return 0 # unparseable payload never blocks
+
+ tool = str(payload.get("tool_name") or "")
+ if tool not in EDIT_TOOLS:
+ return 0
+
+ ti = payload.get("tool_input") or {}
+ # Every Hermes/CLI editing tool puts the target somewhere obvious.
+ candidates = []
+ for key in ("path", "file_path", "filePath", "target", "filename", "notebook_path"):
+ v = ti.get(key)
+ if isinstance(v, str) and v.strip():
+ candidates.append(v.strip())
+ for k in ("edits", "operations"):
+ seq = ti.get(k)
+ if isinstance(seq, list):
+ for item in seq:
+ if isinstance(item, dict):
+ for key in ("path", "file_path", "filePath"):
+ v = item.get(key)
+ if isinstance(v, str) and v.strip():
+ candidates.append(v.strip())
+ if not candidates:
+ return 0
+
+ for p in candidates:
+ base = os.path.basename(p)
+ if base in PROTECTED and os.path.exists(p):
+ print(
+ json.dumps(
+ {
+ "decision": "block",
+ "reason": (
+ f"BLOCKED: modifying {base} is not allowed. Fix the source code so the "
+ "linter/formatter passes instead of weakening the config. For a legitimate "
+ "config change, ask the owner to edit it directly."
+ ),
+ }
+ )
+ )
+ return 0
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
\ No newline at end of file