strray-ai 1.15.6 → 1.15.7

package/README.md

@@ -2,7 +2,7 @@
 
 **Enterprise AI Orchestration Framework for OpenCode/Claude Code**
 
-[![Version](https://img.shields.io/badge/version-1.15.6-blue?style=flat-square)](https://npmjs.com/package/strray-ai)
+[![Version](https://img.shields.io/badge/version-1.15.7-blue?style=flat-square)](https://npmjs.com/package/strray-ai)
 [![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
 [![Tests](https://img.shields.io/badge/tests-2311%20passed-brightgreen?style=flat-square)](src/__tests__)
 [![GitHub stars](https://img.shields.io/github/stars/htafolla/stringray?style=social)](https://github.com/htafolla/stringray)

package/package.json

@@ -164,5 +164,5 @@
   "optionalDependencies": {
     "@rollup/rollup-linux-x64-gnu": "^4.30.1"
   },
-  "version": "1.15.6"
+  "version": "1.15.7"
 }

package/src/integrations/hermes-agent/__init__.py

@@ -413,6 +413,62 @@ def _strray_command(args: str) -> str:
 
 # ── Registration ──────────────────────────────────────────────
 
+# Session tracking for new lifecycle hooks
+_modified_files: list = []
+_validation_results: list = []
+_errors: list = []
+
+
+def _on_file_write(file_path: str, content: str, tool_name: str, **kwargs):
+    """Fires when a code-producing tool writes a file.
+
+    Validates the file was written correctly and logs the event.
+    """
+    _log_to_file("activity.log",
+        f"[file-write] path={file_path} tool={tool_name} size={len(content) if content else 0}")
+
+    _modified_files.append({
+        "path": file_path,
+        "tool": tool_name,
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+    })
+
+
+def _on_validation_result(tool_name: str, passed: bool, violations: list, **kwargs):
+    """Fires when a validation/check completes.
+
+    Tracks validation outcomes for session context.
+    """
+    _log_to_file("activity.log",
+        f"[validation] tool={tool_name} passed={passed} violations={len(violations)}")
+
+    _validation_results.append({
+        "tool": tool_name,
+        "passed": passed,
+        "violation_count": len(violations),
+        "violations": violations[:5],
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+    })
+
+
+def _on_error(tool_name: str, error: str, args: dict, **kwargs):
+    """Fires when a tool call fails.
+
+    Logs the error and tracks it for session context.
+    """
+    _log_to_file("activity.log",
+        f"[error] tool={tool_name} error={str(error)[:200]}")
+
+    _session_stats["bridge_errors"] += 1
+
+    _errors.append({
+        "tool": tool_name,
+        "error": str(error)[:200],
+        "args_keys": list((args or {}).keys()),
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+    })
+
+
 def register(ctx):
     """Wire schemas to handlers and register lifecycle hooks."""
     # ── Register tools ────────────────────────────────────────
@@ -434,6 +490,12 @@ def register(ctx):
         schema=schemas.STRRAY_HEALTH,
         handler=tools.strray_health,
     )
+    ctx.register_tool(
+        name="strray_hooks",
+        toolset="strray-hermes",
+        schema=schemas.STRRAY_HOOKS,
+        handler=tools.strray_hooks,
+    )
 
     # ── Register hooks ────────────────────────────────────────
     ctx.register_hook("pre_tool_call", _on_pre_tool_call)
@@ -445,12 +507,23 @@ def register(ctx):
     except (AttributeError, TypeError):
         logger.debug("[strray] on_session_start hook not yet available")
 
+    # Try to register new lifecycle hooks
+    for hook_name, hook_fn in [
+        ("on_file_write", _on_file_write),
+        ("on_validation_result", _on_validation_result),
+        ("on_error", _on_error),
+    ]:
+        try:
+            ctx.register_hook(hook_name, hook_fn)
+        except (AttributeError, TypeError):
+            logger.debug("[strray] %s hook not yet available", hook_name)
+
     # ── Register slash command ────────────────────────────────
     try:
         ctx.register_command(
             name="strray",
             handler=_strray_command,
-            description="StringRay status, stats, and enforcement info",
+            description="StringRay status, stats, hooks, and enforcement info",
             args_hint="[status|stats|help]",
             aliases=("sr",),
         )
@@ -460,11 +533,11 @@ def register(ctx):
     # ── Bootstrap ─────────────────────────────────────────────
     _ensure_log_dir()
     _log_to_file("activity.log",
-        f"[plugin-loaded] StringRay Hermes Plugin v2.0 — "
-        f"3 tools, 2 hooks, bridge={BRIDGE_PATH.exists()}")
+        f"[plugin-loaded] StringRay Hermes Plugin v2.1 — "
+        f"4 tools, 5 hooks, bridge={BRIDGE_PATH.exists()}")
 
     logger.info(
-        "[strray] Plugin v2.0 loaded: 3 tools, 2 hooks, "
+        "[strray] Plugin v2.1 loaded: 4 tools, 5 hooks, "
         "bridge=%s — full framework pipeline active",
         BRIDGE_PATH.exists(),
     )

package/src/integrations/hermes-agent/after-install.md

@@ -9,8 +9,46 @@
 | `strray_validate` | Pre-commit validation with quality gates |
 | `strray_codex_check` | Code review against 60 Codex error-prevention rules |
 | `strray_health` | Framework health check |
+| `strray_hooks` | Git hooks management (install, uninstall, list, status) |
 | `pre_tool_call` hook | Quality gates + nudges before every tool call |
 | `post_tool_call` hook | Post-processors + file tracking after every tool call |
+| `on_file_write` hook | File write tracking and logging |
+| `on_validation_result` hook | Validation outcome tracking |
+| `on_error` hook | Error logging and session tracking |
+
+## Git Hooks
+
+The plugin can install git hooks for automated validation:
+
+| Hook | Type | Description |
+|------|------|-------------|
+| `pre-commit` | Blocking | TypeScript check + Codex validation before commit |
+| `post-commit` | Non-blocking | Log archival + cleanup after commit |
+| `pre-push` | Blocking | Full validation suite before push |
+| `post-push` | Non-blocking | Comprehensive monitoring after push |
+
+### Install Hooks
+
+```
+/strray hooks install
+```
+
+Or use the tool directly:
+```
+strray_hooks(action="install")
+```
+
+### Check Hook Status
+
+```
+/strray hooks status
+```
+
+### Uninstall Hooks
+
+```
+/strray hooks uninstall
+```
 
 ## Quick Test
 
@@ -18,6 +56,7 @@ After restarting Hermes, try:
 
 ```
 /strray status
+/strray stats
 ```
 
 Or use the tools directly — `strray_health` will confirm the bridge is connected.

package/src/integrations/hermes-agent/bridge.mjs

@@ -14,6 +14,7 @@
  *   health        - Quick framework health check
  *   codex-check   - Check code against codex rules
  *   stats         - Return bridge/framework statistics
+ *   hooks         - Manage git hooks (install, uninstall, list, status)
  *
  * Usage:
  *   echo '{"command":"health"}' | node bridge.mjs [--cwd /path]   # stdin mode
@@ -28,8 +29,12 @@ import {
   appendFileSync,
   mkdirSync,
   readdirSync,
+  lstatSync,
+  symlinkSync,
+  unlinkSync,
+  renameSync,
 } from "fs";
-import { join, dirname } from "path";
+import { join, dirname, relative } from "path";
 import { fileURLToPath } from "url";
 import { homedir } from "os";
 
@@ -446,6 +451,136 @@ async function handleCodexCheck(input, projectRoot, logDir) {
   };
 }
 
+function handleHooks(input, projectRoot) {
+  const { action, hooks } = input;
+  const hookTypes = hooks || ["pre-commit", "post-commit", "pre-push", "post-push"];
+  const gitHooksDir = join(projectRoot, ".git", "hooks");
+  const strrayHooksDir = join(projectRoot, "hooks");
+
+  if (!existsSync(gitHooksDir)) {
+    return { error: "Not a git repository — no .git/hooks directory" };
+  }
+
+  const result = { managed: [], missing: [], external: [], stale: [] };
+
+  // ── list / status ───────────────────────────────────────
+  if (action === "list" || action === "status") {
+    for (const hookName of hookTypes) {
+      const gitHook = join(gitHooksDir, hookName);
+      const strrayHook = join(strrayHooksDir, hookName);
+
+      if (!existsSync(gitHook)) {
+        result.missing.push(hookName);
+      } else {
+        try {
+          const content = readFileSync(gitHook, "utf-8");
+          if (content.includes("StringRay") || content.includes("strray") || content.includes("run-hook.js")) {
+            result.managed.push(hookName);
+          } else {
+            result.external.push(hookName);
+          }
+        } catch {
+          result.external.push(hookName);
+        }
+      }
+
+      // Check if strray source hook exists
+      if (!existsSync(strrayHook)) {
+        result.stale.push(hookName);
+      }
+    }
+
+    return {
+      status: "ok",
+      action,
+      hooks: result,
+      gitHooksDir,
+      strrayHooksDir,
+    };
+  }
+
+  // ── install ─────────────────────────────────────────────
+  if (action === "install") {
+    const installed = [];
+    const skipped = [];
+    const errors = [];
+
+    for (const hookName of hookTypes) {
+      const src = join(strrayHooksDir, hookName);
+      const dst = join(gitHooksDir, hookName);
+
+      if (!existsSync(src)) {
+        skipped.push(hookName);
+        continue;
+      }
+
+      try {
+        // Backup existing non-strray hooks
+        if (existsSync(dst)) {
+          const content = readFileSync(dst, "utf-8");
+          if (!content.includes("StringRay") && !content.includes("strray") && !content.includes("run-hook.js")) {
+            renameSync(dst, `${dst}.strray-backup`);
+          } else {
+            unlinkSync(dst);
+          }
+        }
+
+        // Create symlink
+        const rel = relative(join(gitHooksDir), src);
+        try {
+          // symlinkSync with 'junction' on Windows
+          symlinkSync(rel, dst);
+        } catch {
+          // Symlink may fail (permissions, cross-device) — copy instead
+          const srcContent = readFileSync(src, "utf-8");
+          writeFileSync(dst, srcContent, { mode: 0o755 });
+        }
+        installed.push(hookName);
+      } catch (err) {
+        errors.push({ hook: hookName, error: err.message });
+      }
+    }
+
+    return { status: "ok", action: "install", installed, skipped, errors };
+  }
+
+  // ── uninstall ───────────────────────────────────────────
+  if (action === "uninstall") {
+    const removed = [];
+    const restored = [];
+
+    for (const hookName of hookTypes) {
+      const dst = join(gitHooksDir, hookName);
+      const backup = `${dst}.strray-backup`;
+
+      if (!existsSync(dst)) continue;
+
+      try {
+        const content = readFileSync(dst, "utf-8");
+        const isStrray = content.includes("StringRay") || content.includes("strray") || content.includes("run-hook.js");
+
+        if (isStrray || lstatSync(dst).isSymbolicLink()) {
+          unlinkSync(dst);
+
+          // Restore backup if exists
+          if (existsSync(backup)) {
+            renameSync(backup, dst);
+            restored.push(hookName);
+          } else {
+            removed.push(hookName);
+          }
+        }
+      } catch {
+        // Skip unremovable hooks
+      }
+    }
+
+    return { status: "ok", action: "uninstall", removed, restored };
+  }
+
+  return { error: `Unknown hooks action: ${action}. Use: install, uninstall, list, status` };
+}
+
 function handleStats() {
   return {
     frameworkReady,
@@ -458,7 +593,7 @@ function handleStats() {
 
 // ── Known commands for positional-arg mode ──────────────────
 const KNOWN_COMMANDS = new Set([
-  "health", "stats", "pre-process", "post-process", "validate", "codex-check",
+  "health", "stats", "pre-process", "post-process", "validate", "codex-check", "hooks",
 ]);
 
 // ── Main ─────────────────────────────────────────────────────
@@ -540,6 +675,9 @@ async function main() {
     case "stats":
       response = handleStats();
       break;
+    case "hooks":
+      response = handleHooks(command, projectRoot);
+      break;
     default:
       response = { error: `Unknown command: ${cmd}` };
   }

package/src/integrations/hermes-agent/plugin.yaml

@@ -1,11 +1,15 @@
 name: strray-hermes
-version: 1.0.0
-description: StringRay AI integration plugin — auto-enforcement hooks, quality gates, and tool awareness for Hermes Agent
+version: 2.1.0
+description: StringRay AI integration plugin — auto-enforcement hooks, quality gates, git hooks, and tool awareness for Hermes Agent
 author: StringRay AI
 provides_tools:
   - strray_validate
   - strray_codex_check
   - strray_health
+  - strray_hooks
 provides_hooks:
-  - post_tool_call
   - pre_tool_call
+  - post_tool_call
+  - on_file_write
+  - on_validation_result
+  - on_error

package/src/integrations/hermes-agent/schemas.py

@@ -69,3 +69,32 @@ STRRAY_HEALTH = {
         "properties": {},
     },
 }
+
+STRRAY_HOOKS = {
+    "name": "strray_hooks",
+    "description": (
+        "Manage StringRay git hooks (install, uninstall, list, status). "
+        "Installs pre-commit, post-commit, pre-push, and post-push hooks "
+        "that run TypeScript validation, Codex checks, and monitoring. "
+        "Use 'install' to set up all hooks, 'list' to see current status."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string",
+                "enum": ["install", "uninstall", "list", "status"],
+                "description": "Action to perform on git hooks",
+            },
+            "hooks": {
+                "type": "array",
+                "items": {
+                    "type": "string",
+                    "enum": ["pre-commit", "post-commit", "pre-push", "post-push"],
+                },
+                "description": "Specific hooks to manage (default: all)",
+            },
+        },
+        "required": ["action"],
+    },
+}

package/src/integrations/hermes-agent/test_plugin.py

@@ -492,7 +492,7 @@ class TestRegisterIntegration(unittest.TestCase):
         ctx = MagicMock()
         pi.register(ctx)
         names = [c[1]["name"] for c in ctx.register_tool.call_args_list]
-        self.assertEqual(set(names), {"strray_validate", "strray_codex_check", "strray_health"})
+        self.assertEqual(set(names), {"strray_validate", "strray_codex_check", "strray_health", "strray_hooks"})
 
     def test_toolset_name(self):
         ctx = MagicMock()
@@ -537,7 +537,8 @@ class TestRegisterIntegration(unittest.TestCase):
 
     def test_survives_missing_session_hook(self):
         ctx = MagicMock()
-        ctx.register_hook.side_effect = [None, None, (AttributeError, None)]
+        # pre_tool_call, post_tool_call succeed; on_session_start fails; 3 lifecycle hooks fail
+        ctx.register_hook.side_effect = [None, None, AttributeError("nope"), AttributeError("nope"), AttributeError("nope"), AttributeError("nope")]
         pi.register(ctx)  # should not raise
 
     def test_survives_missing_command_reg(self):
@@ -935,10 +936,256 @@ class TestBridgeHelperTimeoutDefault(unittest.TestCase):
     def test_custom_timeout(self):
         """_call_bridge respects custom timeout."""
         with patch("subprocess.run") as m:
-            m.return_value = MagicMock(returncode=0, stdout='{"ok":true}', stderr="")
+            m.return_value = MagicMock(returncode=0, stdout='{\"ok\":true}', stderr="")
             tools_mod._call_bridge({"command": "health"}, timeout=5)
             self.assertEqual(m.call_args[1]["timeout"], 5)
 
 
+class TestStrrayHooksTool(unittest.TestCase):
+    """Tests for the strray_hooks tool."""
+
+    def test_list_via_bridge(self):
+        """list action uses bridge when available."""
+        with patch.object(tools_mod, "_call_bridge", return_value={
+            "status": "ok", "action": "list",
+            "hooks": {"managed": ["pre-commit"], "missing": [], "external": [], "stale": []},
+        }) as m:
+            r = json.loads(tools_mod.strray_hooks({"action": "list"}))
+            self.assertEqual(r["status"], "ok")
+            self.assertEqual(r["via"], "bridge")
+            m.assert_called_once()
+            call_cmd = m.call_args[0][0]
+            self.assertEqual(call_cmd["command"], "hooks")
+            self.assertEqual(call_cmd["action"], "list")
+
+    def test_install_via_bridge(self):
+        """install action uses bridge."""
+        with patch.object(tools_mod, "_call_bridge", return_value={
+            "status": "ok", "action": "install", "installed": ["pre-commit", "post-commit"],
+            "skipped": [], "errors": [],
+        }) as m:
+            r = json.loads(tools_mod.strray_hooks({"action": "install"}))
+            self.assertEqual(r["via"], "bridge")
+            self.assertEqual(len(r["result"]["installed"]), 2)
+
+    def test_uninstall_via_bridge(self):
+        """uninstall action uses bridge."""
+        with patch.object(tools_mod, "_call_bridge", return_value={
+            "status": "ok", "action": "uninstall", "removed": ["pre-commit"], "restored": [],
+        }) as m:
+            r = json.loads(tools_mod.strray_hooks({"action": "uninstall"}))
+            self.assertEqual(r["via"], "bridge")
+
+    def test_bridge_error_fallback(self):
+        """Falls back to file-based when bridge errors."""
+        with patch.object(tools_mod, "_call_bridge", return_value={"error": "node not found"}):
+            # Without a real git repo, should return error
+            r = json.loads(tools_mod.strray_hooks({"action": "list"}))
+            self.assertIn("via", r)
+
+    def test_specific_hooks(self):
+        """Can request specific hooks."""
+        with patch.object(tools_mod, "_call_bridge", return_value={
+            "status": "ok", "action": "list",
+            "hooks": {"managed": [], "missing": ["pre-commit"], "external": [], "stale": []},
+        }) as m:
+            tools_mod.strray_hooks({"action": "list", "hooks": ["pre-commit"]})
+            call_cmd = m.call_args[0][0]
+            self.assertEqual(call_cmd["hooks"], ["pre-commit"])
+
+    def test_status_defaults_to_list(self):
+        """status action works like list."""
+        with patch.object(tools_mod, "_call_bridge", return_value={
+            "status": "ok", "action": "status",
+            "hooks": {"managed": [], "missing": [], "external": [], "stale": []},
+        }) as m:
+            r = json.loads(tools_mod.strray_hooks({"action": "status"}))
+            self.assertEqual(r["status"], "ok")
+            m.assert_called_once()
+
+    def test_default_action_is_list(self):
+        """Missing action defaults to list."""
+        with patch.object(tools_mod, "_call_bridge", return_value={
+            "status": "ok", "action": "list",
+            "hooks": {"managed": [], "missing": [], "external": [], "stale": []},
+        }) as m:
+            tools_mod.strray_hooks({})
+            call_cmd = m.call_args[0][0]
+            self.assertEqual(call_cmd["action"], "list")
+
+
+class TestStrrayHooksSchema(unittest.TestCase):
+    """Tests for the STRRAY_HOOKS schema."""
+
+    def test_schema_has_required_fields(self):
+        s = schemas.STRRAY_HOOKS
+        self.assertEqual(s["name"], "strray_hooks")
+        self.assertIn("action", s["parameters"]["properties"])
+        self.assertIn("hooks", s["parameters"]["properties"])
+        self.assertIn("action", s["parameters"]["required"])
+
+    def test_action_enum(self):
+        s = schemas.STRRAY_HOOKS
+        action = s["parameters"]["properties"]["action"]
+        self.assertIn("install", action["enum"])
+        self.assertIn("uninstall", action["enum"])
+        self.assertIn("list", action["enum"])
+        self.assertIn("status", action["enum"])
+
+    def test_hooks_enum(self):
+        s = schemas.STRRAY_HOOKS
+        hooks = s["parameters"]["properties"]["hooks"]
+        self.assertIn("pre-commit", hooks["items"]["enum"])
+        self.assertIn("post-commit", hooks["items"]["enum"])
+        self.assertIn("pre-push", hooks["items"]["enum"])
+        self.assertIn("post-push", hooks["items"]["enum"])
+
+    def test_description_mentions_hooks(self):
+        s = schemas.STRRAY_HOOKS
+        self.assertIn("git hooks", s["description"])
+
+
+class TestLifecycleHooks(unittest.TestCase):
+    """Tests for the new lifecycle hooks: on_file_write, on_validation_result, on_error."""
+
+    def setUp(self):
+        # Reset tracking lists
+        pi._modified_files = []
+        pi._validation_results = []
+        pi._errors = []
+
+    def test_on_file_write_logs(self):
+        with tempfile.TemporaryDirectory() as td:
+            log_dir = Path(td)
+            original = pi.LOG_DIR
+            pi.LOG_DIR = log_dir
+
+            pi._on_file_write("src/index.ts", "hello world", "write_file")
+
+            self.assertEqual(len(pi._modified_files), 1)
+            self.assertEqual(pi._modified_files[0]["path"], "src/index.ts")
+            self.assertEqual(pi._modified_files[0]["tool"], "write_file")
+
+            content = (log_dir / "activity.log").read_text()
+            self.assertIn("[file-write]", content)
+
+            pi.LOG_DIR = original
+
+    def test_on_file_write_empty_content(self):
+        pi._on_file_write("a.ts", "", "write_file")
+        self.assertEqual(len(pi._modified_files), 1)
+
+    def test_on_validation_result_passed(self):
+        with tempfile.TemporaryDirectory() as td:
+            log_dir = Path(td)
+            original = pi.LOG_DIR
+            pi.LOG_DIR = log_dir
+
+            pi._on_validation_result("strray_validate", True, [])
+
+            self.assertEqual(len(pi._validation_results), 1)
+            self.assertTrue(pi._validation_results[0]["passed"])
+
+            content = (log_dir / "activity.log").read_text()
+            self.assertIn("[validation]", content)
+
+            pi.LOG_DIR = original
+
+    def test_on_validation_result_failed(self):
+        pi._on_validation_result("strray_codex_check", False, ["console.log found"])
+        self.assertFalse(pi._validation_results[0]["passed"])
+        self.assertEqual(pi._validation_results[0]["violation_count"], 1)
+        self.assertEqual(len(pi._validation_results[0]["violations"]), 1)
+
+    def test_on_validation_result_truncates_violations(self):
+        many = [f"violation-{i}" for i in range(20)]
+        pi._on_validation_result("test", False, many)
+        # Should keep only first 5
+        self.assertEqual(len(pi._validation_results[0]["violations"]), 5)
+
+    def test_on_error_logs(self):
+        with tempfile.TemporaryDirectory() as td:
+            log_dir = Path(td)
+            original = pi.LOG_DIR
+            pi.LOG_DIR = log_dir
+
+            pi._on_error("write_file", "disk full", {"path": "a.ts"})
+
+            self.assertEqual(len(pi._errors), 1)
+            self.assertEqual(pi._errors[0]["tool"], "write_file")
+
+            content = (log_dir / "activity.log").read_text()
+            self.assertIn("[error]", content)
+
+            pi.LOG_DIR = original
+
+    def test_on_error_increments_stats(self):
+        initial = pi._session_stats["bridge_errors"]
+        pi._on_error("terminal", "timeout", None)
+        self.assertEqual(pi._session_stats["bridge_errors"], initial + 1)
+
+    def test_on_error_truncates_long_error(self):
+        long_error = "x" * 500
+        pi._on_error("tool", long_error, {})
+        self.assertLessEqual(len(pi._errors[0]["error"]), 200)
+
+    def test_on_error_no_args(self):
+        pi._on_error("tool", "crash", None)
+        self.assertEqual(pi._errors[0]["args_keys"], [])
+
+
+class TestRegisterIntegrationV2_1(unittest.TestCase):
+    """Test that register() wires all 4 tools and 5 hooks in v2.1."""
+
+    def test_wires_four_tools(self):
+        ctx = MagicMock()
+        pi.register(ctx)
+        names = [c[1]["name"] for c in ctx.register_tool.call_args_list]
+        self.assertEqual(set(names), {
+            "strray_validate", "strray_codex_check",
+            "strray_health", "strray_hooks",
+        })
+
+    def test_strray_hooks_schema_wired(self):
+        ctx = MagicMock()
+        pi.register(ctx)
+        sm = {c[1]["name"]: c[1]["schema"] for c in ctx.register_tool.call_args_list}
+        self.assertIs(sm["strray_hooks"], schemas.STRRAY_HOOKS)
+
+    def test_strray_hooks_handler_wired(self):
+        ctx = MagicMock()
+        pi.register(ctx)
+        hm = {c[1]["name"]: c[1]["handler"] for c in ctx.register_tool.call_args_list}
+        self.assertIs(hm["strray_hooks"], tools_mod.strray_hooks)
+
+    def test_registers_five_hooks(self):
+        ctx = MagicMock()
+        pi.register(ctx)
+        hook_names = [c[0][0] for c in ctx.register_hook.call_args_list]
+        self.assertIn("pre_tool_call", hook_names)
+        self.assertIn("post_tool_call", hook_names)
+        self.assertIn("on_file_write", hook_names)
+        self.assertIn("on_validation_result", hook_names)
+        self.assertIn("on_error", hook_names)
+
+    def test_survives_missing_lifecycle_hooks(self):
+        """New hooks should fail gracefully if not supported."""
+        ctx = MagicMock()
+        # All 5 hook registrations: pre_tool_call, post_tool_call, on_session_start, on_file_write, on_validation_result, on_error
+        # Let the 3 new ones raise
+        def side_effect(*args):
+            raise AttributeError("not available")
+        ctx.register_hook.side_effect = [None, None, None, side_effect, side_effect, side_effect]
+        pi.register(ctx)  # should not raise
+
+    def test_v2_1_log_message(self):
+        ctx = MagicMock()
+        with self.assertLogs("strray-hermes", level="INFO") as cm:
+            pi.register(ctx)
+        self.assertTrue(any("v2.1" in m for m in cm.output))
+        self.assertTrue(any("4 tools" in m for m in cm.output))
+        self.assertTrue(any("5 hooks" in m for m in cm.output))
+
+
 if __name__ == "__main__":
     unittest.main(verbosity=2)

package/src/integrations/hermes-agent/tools.py

@@ -5,6 +5,8 @@ Falls back to CLI (npx strray-ai) when bridge is unavailable.
 """
 
 import json
+import os
+import shutil
 import subprocess
 import sys
 from pathlib import Path
@@ -206,3 +208,112 @@ def strray_health(args: dict, **kwargs) -> str:
 
     # Fallback to CLI
     return _run_strray(["health"], timeout=15)
+
+
+# ── Tool: strray_hooks ───────────────────────────────────────
+
+def strray_hooks(args: dict, **kwargs) -> str:
+    """Manage StringRay git hooks.
+
+    Actions: install, uninstall, list, status
+    Uses bridge for hook management when available.
+    Falls back to direct file-based management when bridge unavailable.
+    """
+    action = args.get("action", "list")
+    hooks = args.get("hooks", ["pre-commit", "post-commit", "pre-push", "post-push"])
+
+    # Try bridge first
+    bridge_result = _call_bridge({
+        "command": "hooks",
+        "action": action,
+        "hooks": hooks,
+    }, timeout=15)
+
+    if "error" not in bridge_result:
+        return json.dumps({
+            "status": "ok",
+            "action": action,
+            "hooks": hooks,
+            "result": bridge_result,
+            "via": "bridge",
+        })
+
+    # Fallback: direct file-based hook management
+    git_hooks_dir = Path(PROJECT_ROOT) / ".git" / "hooks"
+    strray_hooks_dir = Path(PROJECT_ROOT) / "hooks"
+
+    if not git_hooks_dir.exists():
+        return json.dumps({"error": "Not a git repository", "via": "fallback"})
+
+    if action in ("list", "status"):
+        result = {"managed": [], "missing": [], "external": [], "stale": []}
+        for hook_name in hooks:
+            git_hook = git_hooks_dir / hook_name
+            strray_hook = strray_hooks_dir / hook_name
+            if not git_hook.exists():
+                result["missing"].append(hook_name)
+            else:
+                try:
+                    content = git_hook.read_text()[:500]
+                    if "StringRay" in content or "strray" in content or "run-hook.js" in content:
+                        result["managed"].append(hook_name)
+                    else:
+                        result["external"].append(hook_name)
+                except OSError:
+                    result["external"].append(hook_name)
+            if not strray_hook.exists():
+                result["stale"].append(hook_name)
+        return json.dumps({"status": "ok", "action": action, **result, "via": "fallback"})
+
+    if action == "install":
+        installed = []
+        skipped = []
+        for hook_name in hooks:
+            src = strray_hooks_dir / hook_name
+            dst = git_hooks_dir / hook_name
+            if not src.exists():
+                skipped.append(hook_name)
+                continue
+            try:
+                if dst.exists():
+                    try:
+                        content = dst.read_text()[:500]
+                        if "StringRay" not in content and "strray" not in content:
+                            dst.rename(dst.with_suffix(".strray-backup"))
+                        else:
+                            dst.unlink()
+                    except OSError:
+                        pass
+                try:
+                    rel = os.path.relpath(str(src), str(git_hooks_dir))
+                    os.symlink(rel, dst)
+                except OSError:
+                    shutil.copy2(src, dst)
+                installed.append(hook_name)
+            except OSError:
+                pass
+        return json.dumps({"status": "ok", "action": "install", "installed": installed, "skipped": skipped, "via": "fallback"})
+
+    if action == "uninstall":
+        removed = []
+        restored = []
+        for hook_name in hooks:
+            dst = git_hooks_dir / hook_name
+            backup = dst.with_suffix(".strray-backup")
+            if not dst.exists():
+                continue
+            try:
+                content = dst.read_text()[:500]
+                is_strray = "StringRay" in content or "strray" in content or "run-hook.js" in content
+                if is_strray or dst.is_symlink():
+                    dst.unlink()
+                    if backup.exists():
+                        shutil.move(str(backup), str(dst))
+                        restored.append(hook_name)
+                    else:
+                        removed.append(hook_name)
+            except OSError:
+                pass
+        return json.dumps({"status": "ok", "action": "uninstall", "removed": removed, "restored": restored, "via": "fallback"})
+
+    return json.dumps({"error": f"Unknown action: {action}", "via": "fallback"})