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.mdnew file mode 100644index 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.pynew file mode 100755index 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 filediff --git a/hooks/hermes/config-protection.py b/hooks/hermes/config-protection.pynew file mode 100755index 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