The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
fix: address CodeRabbit review — convert to PreToolUse, add type annotations, logging
Nomadu2744dc96d2c6a9
diff --git a/hooks/README.md b/hooks/README.mdindex 1fc1fb230..dde8a0209 100644--- a/hooks/README.md+++ b/hooks/README.md@@ -25,6 +25,7 @@ User request → Claude picks a tool → PreToolUse hook runs → Tool executes| **Git push reminder** | `Bash` | Reminds to review changes before `git push` | 0 (warns) || **Doc file warning** | `Write` | Warns about non-standard `.md`/`.txt` files (allows README, CLAUDE, CONTRIBUTING, CHANGELOG, LICENSE, SKILL, docs/, skills/); cross-platform path handling | 0 (warns) || **Strategic compact** | `Edit\|Write` | Suggests manual `/compact` at logical intervals (every ~50 tool calls) | 0 (warns) |+| **InsAIts security monitor** | `*` | Detects credential exposure, prompt injection, hallucinations, and behavioral anomalies (23 types) before tool execution. Blocks on critical findings, warns on non-critical. Writes audit log to `.insaits_audit_session.jsonl`. Requires `pip install insa-its`. [Details](../scripts/hooks/insaits-security-monitor.py) | 2 (blocks critical) / 0 (warns) |### PostToolUse Hooks@@ -36,7 +37,6 @@ User request → Claude picks a tool → PreToolUse hook runs → Tool executes| **Prettier format** | `Edit` | Auto-formats JS/TS files with Prettier after edits || **TypeScript check** | `Edit` | Runs `tsc --noEmit` after editing `.ts`/`.tsx` files || **console.log warning** | `Edit` | Warns about `console.log` statements in edited files |-| **InsAIts security monitor** | `.*` | Real-time AI security: catches credential exposure, prompt injection, hallucinations, behavioral anomalies (23 types). Writes audit log to `.insaits_audit_session.jsonl`. Requires `pip install insa-its`. [Details](../scripts/hooks/insaits-security-monitor.py) |### Lifecycle Hooksdiff --git a/hooks/hooks.json b/hooks/hooks.jsonindex 096a1ac63..3edc67787 100644--- a/hooks/hooks.json+++ b/hooks/hooks.json@@ -63,6 +63,18 @@}],"description": "Capture tool use observations for continuous learning"+ },+ {+ "matcher": "*",+ "hooks": [+ {+ "type": "command",+ "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js\" \"pre:insaits-security\" \"scripts/hooks/insaits-security-wrapper.js\" \"standard,strict\"",+ "async": true,+ "timeout": 15+ }+ ],+ "description": "InsAIts AI security monitor: detects credential exposure, prompt injection, hallucinations, and 20+ anomaly types before tool execution. Requires: pip install insa-its"}],"PreCompact": [@@ -165,17 +177,6 @@}],"description": "Capture tool use results for continuous learning"- },- {- "matcher": "*",- "hooks": [- {- "type": "command",- "command": "python \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/insaits-security-monitor.py\"",- "timeout": 15- }- ],- "description": "InsAIts AI security monitor: catches credential exposure, prompt injection, hallucinations, and 20+ anomaly types. Requires: pip install insa-its"}],"Stop": [diff --git a/mcp-configs/mcp-servers.json b/mcp-configs/mcp-servers.jsonindex aa4044e43..64b1ad004 100644--- a/mcp-configs/mcp-servers.json+++ b/mcp-configs/mcp-servers.json@@ -90,7 +90,7 @@"description": "Filesystem operations (set your path)"},"insaits": {- "command": "python",+ "command": "python3","args": ["-m", "insa_its.mcp_server"],"description": "AI-to-AI security monitoring — anomaly detection, credential exposure, hallucination checks, forensic tracing. 23 anomaly types, OWASP MCP Top 10 coverage. 100% local. Install: pip install insa-its"}diff --git a/scripts/hooks/insaits-security-monitor.py b/scripts/hooks/insaits-security-monitor.pyindex 97129e8fa..e0a8ab148 100644--- a/scripts/hooks/insaits-security-monitor.py+++ b/scripts/hooks/insaits-security-monitor.py@@ -1,11 +1,11 @@#!/usr/bin/env python3"""-InsAIts Security Monitor — PostToolUse Hook for Claude Code+InsAIts Security Monitor -- PreToolUse Hook for Claude Code============================================================-Real-time security monitoring for Claude Code tool outputs.-Catches credential exposure, prompt injection, behavioral anomalies,-hallucination chains, and 20+ other anomaly types — runs 100% locally.+Real-time security monitoring for Claude Code tool inputs.+Detects credential exposure, prompt injection, behavioral anomalies,+hallucination chains, and 20+ other anomaly types -- runs 100% locally.Writes audit events to .insaits_audit_session.jsonl for forensic tracing.@@ -15,13 +15,13 @@ Setup:Add to .claude/settings.json:{"hooks": {- "PostToolUse": [+ "PreToolUse": [{"matcher": ".*","hooks": [{"type": "command",- "command": "python scripts/hooks/insaits-security-monitor.py"+ "command": "python3 scripts/hooks/insaits-security-monitor.py"}]}@@ -30,73 +30,97 @@ Setup:}How it works:- Claude Code passes tool result as JSON on stdin.- This script runs InsAIts anomaly detection on the output.+ Claude Code passes tool input as JSON on stdin.+ This script runs InsAIts anomaly detection on the content.Exit code 0 = clean (pass through).- Exit code 2 = critical issue found (blocks action, shows feedback to Claude).+ Exit code 2 = critical issue found (blocks tool execution).+ Stderr output = non-blocking warning shown to Claude.Detections include:- - Credential exposure (API keys, tokens, passwords in output)+ - Credential exposure (API keys, tokens, passwords)- Prompt injection patterns- Hallucination indicators (phantom citations, fact contradictions)- Behavioral anomalies (context loss, semantic drift)- Tool description divergence- Shorthand emergence / jargon drift-All processing is local — no data leaves your machine.+All processing is local -- no data leaves your machine.-Author: Cristi Bogdan — YuyAI (https://github.com/Nomadu27/InsAIts)+Author: Cristi Bogdan -- YuyAI (https://github.com/Nomadu27/InsAIts)License: Apache 2.0"""-import sys+from __future__ import annotations++import hashlibimport json+import loggingimport os-import hashlib+import sysimport time+from typing import Any, Dict, List, Optional, Tuple++# Configure logging to stderr so it does not interfere with stdout protocol+logging.basicConfig(+ stream=sys.stderr,+ format="[InsAIts] %(message)s",+ level=logging.DEBUG if os.environ.get("INSAITS_VERBOSE") else logging.WARNING,+)+log = logging.getLogger("insaits-hook")# Try importing InsAIts SDKtry:from insa_its import insAItsMonitor- INSAITS_AVAILABLE = True+ INSAITS_AVAILABLE: bool = Trueexcept ImportError:INSAITS_AVAILABLE = False-AUDIT_FILE = ".insaits_audit_session.jsonl"+AUDIT_FILE: str = ".insaits_audit_session.jsonl"++def extract_content(data: Dict[str, Any]) -> Tuple[str, str]:+ """Extract inspectable text from a Claude Code tool input payload.-def extract_content(data):- """Extract inspectable text from a Claude Code tool result."""- tool_name = data.get("tool_name", "")- tool_input = data.get("tool_input", {})- tool_result = data.get("tool_response", {})+ Returns:+ A (text, context) tuple where *text* is the content to scan and+ *context* is a short label for the audit log.+ """+ tool_name: str = data.get("tool_name", "")+ tool_input: Dict[str, Any] = data.get("tool_input", {})+ tool_result: Any = data.get("tool_response", {})- text = ""- context = ""+ text: str = ""+ context: str = ""if tool_name in ("Write", "Edit", "MultiEdit"):text = tool_input.get("content", "") or tool_input.get("new_string", "")- context = "file:" + tool_input.get("file_path", "")[:80]+ context = "file:" + str(tool_input.get("file_path", ""))[:80]elif tool_name == "Bash":+ command: str = str(tool_input.get("command", ""))+ # For PreToolUse we inspect the command itself+ text = command+ # Also check tool_response if present (for flexibility)if isinstance(tool_result, dict):- text = tool_result.get("output", "") or tool_result.get("stdout", "")- elif isinstance(tool_result, str):- text = tool_result- context = "bash:" + str(tool_input.get("command", ""))[:80]+ output = tool_result.get("output", "") or tool_result.get("stdout", "")+ if output:+ text = text + "\n" + output+ elif isinstance(tool_result, str) and tool_result:+ text = text + "\n" + tool_result+ context = "bash:" + command[:80]elif "content" in data:- content = data["content"]+ content: Any = data["content"]if isinstance(content, list):text = "\n".join(b.get("text", "") for b in content if b.get("type") == "text")elif isinstance(content, str):text = content- context = data.get("task", "")+ context = str(data.get("task", ""))return text, context-def write_audit(event):+def write_audit(event: Dict[str, Any]) -> None:"""Append an audit event to the JSONL audit log."""try:event["timestamp"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())@@ -105,20 +129,24 @@ def write_audit(event):).hexdigest()[:16]with open(AUDIT_FILE, "a", encoding="utf-8") as f:f.write(json.dumps(event) + "\n")- except OSError:- pass+ except OSError as exc:+ log.warning("Failed to write audit log %s: %s", AUDIT_FILE, exc)++def format_feedback(anomalies: List[Any]) -> str:+ """Format detected anomalies as feedback for Claude Code.-def format_feedback(anomalies):- """Format detected anomalies as feedback for Claude Code."""- lines = [- "== InsAIts Security Monitor — Issues Detected ==",+ Returns:+ A human-readable multi-line string describing each finding.+ """+ lines: List[str] = [+ "== InsAIts Security Monitor -- Issues Detected ==","",]for i, a in enumerate(anomalies, 1):- sev = getattr(a, "severity", "MEDIUM")- atype = getattr(a, "type", "UNKNOWN")- detail = getattr(a, "detail", "")+ sev: str = getattr(a, "severity", "MEDIUM")+ atype: str = getattr(a, "type", "UNKNOWN")+ detail: str = getattr(a, "detail", "")lines.extend([f"{i}. [{sev}] {atype}",f" {detail[:120]}",@@ -132,40 +160,38 @@ def format_feedback(anomalies):return "\n".join(lines)-def main():- raw = sys.stdin.read().strip()+def main() -> None:+ """Entry point for the Claude Code PreToolUse hook."""+ raw: str = sys.stdin.read().strip()if not raw:sys.exit(0)try:- data = json.loads(raw)+ data: Dict[str, Any] = json.loads(raw)except json.JSONDecodeError:data = {"content": raw}text, context = extract_content(data)- # Skip very short or binary content+ # Skip very short content (e.g. "OK", empty bash results)if len(text.strip()) < 10:sys.exit(0)if not INSAITS_AVAILABLE:- print(- "[InsAIts] Not installed. Run: pip install insa-its",- file=sys.stderr,- )+ log.warning("Not installed. Run: pip install insa-its")sys.exit(0)- # Enable dev mode (no API key needed for local detection)- os.environ.setdefault("INSAITS_DEV_MODE", "true")-- monitor = insAItsMonitor(session_name="claude-code-hook")- result = monitor.send_message(+ monitor: insAItsMonitor = insAItsMonitor(+ session_name="claude-code-hook",+ dev_mode=True,+ )+ result: Dict[str, Any] = monitor.send_message(text=text[:4000],sender_id="claude-code",llm_id=os.environ.get("INSAITS_MODEL", "claude-opus"),)- anomalies = result.get("anomalies", [])+ anomalies: List[Any] = result.get("anomalies", [])# Write audit event regardless of findingswrite_audit({@@ -177,22 +203,23 @@ def main():})if not anomalies:- if os.environ.get("INSAITS_VERBOSE"):- print("[InsAIts] Clean — no anomalies.", file=sys.stderr)+ log.debug("Clean -- no anomalies detected.")sys.exit(0)- # Check severity- has_critical = any(+ # Determine maximum severity+ has_critical: bool = any(getattr(a, "severity", "") in ("CRITICAL", "critical") for a in anomalies)- feedback = format_feedback(anomalies)+ feedback: str = format_feedback(anomalies)if has_critical:- print(feedback) # stdout -> Claude Code shows to model- sys.exit(2) # block action+ # stdout feedback -> Claude Code shows to the model+ sys.stdout.write(feedback + "\n")+ sys.exit(2) # PreToolUse exit 2 = block tool executionelse:- print(feedback, file=sys.stderr) # stderr -> logged only+ # Non-critical: warn via stderr (non-blocking)+ log.warning("\n%s", feedback)sys.exit(0)diff --git a/scripts/hooks/insaits-security-wrapper.js b/scripts/hooks/insaits-security-wrapper.jsnew file mode 100644index 000000000..6223b3683--- /dev/null+++ b/scripts/hooks/insaits-security-wrapper.js@@ -0,0 +1,62 @@+#!/usr/bin/env node+/**+ * InsAIts Security Monitor — wrapper for run-with-flags compatibility.+ *+ * This thin wrapper receives stdin from the hooks infrastructure and+ * delegates to the Python-based insaits-security-monitor.py script.+ *+ * The wrapper exists because run-with-flags.js spawns child scripts+ * via `node`, so a JS entry point is needed to bridge to Python.+ */++'use strict';++const path = require('path');+const { spawnSync } = require('child_process');++const MAX_STDIN = 1024 * 1024;++let raw = '';+process.stdin.setEncoding('utf8');+process.stdin.on('data', chunk => {+ if (raw.length < MAX_STDIN) {+ raw += chunk.substring(0, MAX_STDIN - raw.length);+ }+});++process.stdin.on('end', () => {+ const scriptDir = __dirname;+ const pyScript = path.join(scriptDir, 'insaits-security-monitor.py');++ // Try python3 first (macOS/Linux), fall back to python (Windows)+ const pythonCandidates = ['python3', 'python'];+ let result;++ for (const pythonBin of pythonCandidates) {+ result = spawnSync(pythonBin, [pyScript], {+ input: raw,+ encoding: 'utf8',+ env: process.env,+ cwd: process.cwd(),+ timeout: 14000,+ });++ // ENOENT means binary not found — try next candidate+ if (result.error && result.error.code === 'ENOENT') {+ continue;+ }+ break;+ }++ if (!result || (result.error && result.error.code === 'ENOENT')) {+ process.stderr.write('[InsAIts] python3/python not found. Install Python 3.9+ and: pip install insa-its\n');+ process.stdout.write(raw);+ process.exit(0);+ }++ if (result.stdout) process.stdout.write(result.stdout);+ if (result.stderr) process.stderr.write(result.stderr);++ const code = Number.isInteger(result.status) ? result.status : 0;+ process.exit(code);+});