@diottodev/runic 1.0.0 → 1.1.0

package/engineering/security-guidance/hooks/security_reminder_hook.py

@@ -0,0 +1,291 @@
+#!/usr/bin/env python3
+"""
+Security Reminder Hook for Claude Code
+
+PreToolUse hook that checks Edit/Write/MultiEdit operations for security
+anti-patterns and emits a structured warning before the tool runs.
+
+Ported from David Dworken's MIT-licensed plugin at:
+  https://github.com/alirezarezvani/aeo-box/blob/main/.claude/plugins/security-guidance/
+
+Modifications from upstream:
+  - Verbatim pattern table preserved (12 patterns)
+  - Session-state caching unchanged (one warning per file+rule per session)
+  - 30-day state-file cleanup unchanged
+  - Debug log location moved from /tmp to ~/.claude/security-warnings-log.txt
+    (more portable, persists across reboots)
+  - ENABLE_SECURITY_REMINDER=0 env var disables the hook (unchanged)
+
+Wire-up: see hooks.json in the same directory.
+"""
+
+import json
+import os
+import random
+import sys
+from datetime import datetime
+from pathlib import Path
+
+# Debug log location (moved to ~/.claude/ for persistence)
+DEBUG_LOG_FILE = str(Path.home() / ".claude" / "security-warnings-log.txt")
+
+
+def debug_log(message):
+    """Append debug message to log file with timestamp."""
+    try:
+        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
+        Path(DEBUG_LOG_FILE).parent.mkdir(parents=True, exist_ok=True)
+        with open(DEBUG_LOG_FILE, "a") as f:
+            f.write(f"[{timestamp}] {message}\n")
+    except Exception:
+        # Silently ignore logging errors to avoid disrupting the hook
+        pass
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Security patterns (verbatim from upstream — David Dworken @ Anthropic)
+# ─────────────────────────────────────────────────────────────────────
+
+SECURITY_PATTERNS = [
+    {
+        "ruleName": "github_actions_workflow",
+        "path_check": lambda path: ".github/workflows/" in path
+        and (path.endswith(".yml") or path.endswith(".yaml")),
+        "reminder": """You are editing a GitHub Actions workflow file. Be aware of these security risks:
+
+1. **Command Injection**: Never use untrusted input (like issue titles, PR descriptions, commit messages) directly in run: commands without proper escaping
+2. **Use environment variables**: Instead of ${{ github.event.issue.title }}, use env: with proper quoting
+3. **Review the guide**: https://github.blog/security/vulnerability-research/how-to-catch-github-actions-workflow-injections-before-attackers-do/
+
+Example of UNSAFE pattern to avoid:
+run: echo "${{ github.event.issue.title }}"
+
+Example of SAFE pattern:
+env:
+  TITLE: ${{ github.event.issue.title }}
+run: echo "$TITLE"
+
+Other risky inputs to be careful with:
+- github.event.issue.body
+- github.event.pull_request.title
+- github.event.pull_request.body
+- github.event.comment.body
+- github.event.review.body
+- github.event.review_comment.body
+- github.event.pages.*.page_name
+- github.event.commits.*.message
+- github.event.head_commit.message
+- github.event.head_commit.author.email
+- github.event.head_commit.author.name
+- github.event.commits.*.author.email
+- github.event.commits.*.author.name
+- github.event.pull_request.head.ref
+- github.event.pull_request.head.label
+- github.event.pull_request.head.repo.default_branch
+- github.head_ref""",
+    },
+    {
+        "ruleName": "child_process_exec",
+        "substrings": ["child_process.exec", "exec(", "execSync("],
+        "reminder": """⚠️ Security Warning: Using child_process.exec() can lead to command injection vulnerabilities.
+
+Instead of:
+  exec(`command ${userInput}`)
+
+Use:
+  execFile('command', [userInput])  // Node built-in; no shell
+
+execFile (or spawn with shell:false):
+- Prevents shell injection
+- Handles arguments as a list (no interpolation)
+- Recommended whenever you don't actually need shell features
+
+Only use exec() if you absolutely need shell features AND the input is guaranteed to be safe (e.g., from a hardcoded allowlist).""",
+    },
+    {
+        "ruleName": "new_function_injection",
+        "substrings": ["new Function"],
+        "reminder": "⚠️ Security Warning: Using new Function() with dynamic strings can lead to code injection vulnerabilities. Consider alternative approaches that don't evaluate arbitrary code. Only use new Function() if you truly need to evaluate arbitrary dynamic code.",
+    },
+    {
+        "ruleName": "eval_injection",
+        "substrings": ["eval("],
+        "reminder": "⚠️ Security Warning: eval() executes arbitrary code and is a major security risk. Consider using JSON.parse() for data parsing or alternative design patterns that don't require code evaluation. Only use eval() if you truly need to evaluate arbitrary code.",
+    },
+    {
+        "ruleName": "react_dangerously_set_html",
+        "substrings": ["dangerouslySetInnerHTML"],
+        "reminder": "⚠️ Security Warning: dangerouslySetInnerHTML can lead to XSS vulnerabilities if used with untrusted content. Ensure all content is properly sanitized using an HTML sanitizer library like DOMPurify, or use safe alternatives.",
+    },
+    {
+        "ruleName": "document_write_xss",
+        "substrings": ["document.write"],
+        "reminder": "⚠️ Security Warning: document.write() can be exploited for XSS attacks and has performance issues. Use DOM manipulation methods like createElement() and appendChild() instead.",
+    },
+    {
+        "ruleName": "innerHTML_xss",
+        "substrings": [".innerHTML =", ".innerHTML="],
+        "reminder": "⚠️ Security Warning: Setting innerHTML with untrusted content can lead to XSS vulnerabilities. Use textContent for plain text or safe DOM methods for HTML content. If you need HTML support, consider using an HTML sanitizer library such as DOMPurify.",
+    },
+    {
+        "ruleName": "pickle_deserialization",
+        "substrings": ["pickle"],
+        "reminder": "⚠️ Security Warning: Using pickle with untrusted content can lead to arbitrary code execution. Consider using JSON or other safe serialization formats instead. Only use pickle if it is explicitly needed or requested by the user.",
+    },
+    {
+        "ruleName": "os_system_injection",
+        "substrings": ["os.system", "from os import system"],
+        "reminder": "⚠️ Security Warning: This code appears to use os.system. This should only be used with static arguments and never with arguments that could be user-controlled.",
+    },
+    {
+        "ruleName": "subprocess_shell_true",
+        "substrings": ["shell=True", "shell = True"],
+        "reminder": "⚠️ Security Warning: subprocess with shell=True can lead to command injection. Pass args as a list instead and omit shell=True (the default). Only use shell=True for static commands without user input.",
+    },
+    {
+        "ruleName": "sql_format_string",
+        "substrings": [".format(", "f\"SELECT", "f'SELECT", "f\"INSERT", "f'INSERT", "f\"UPDATE", "f'UPDATE", "f\"DELETE", "f'DELETE"],
+        "reminder": "⚠️ Security Warning: Building SQL queries with .format() or f-strings can lead to SQL injection. Use parameterized queries (cursor.execute(sql, params)) or an ORM. Only inline values if they come from a trusted, validated source.",
+    },
+    {
+        "ruleName": "yaml_unsafe_load",
+        "substrings": ["yaml.load(", "yaml.unsafe_load"],
+        "reminder": "⚠️ Security Warning: yaml.load() without Loader= or yaml.unsafe_load() can execute arbitrary code. Use yaml.safe_load() instead, which only parses standard YAML types.",
+    },
+]
+
+
+def get_state_file(session_id):
+    """Get session-specific state file path."""
+    return os.path.expanduser(f"~/.claude/security_warnings_state_{session_id}.json")
+
+
+def cleanup_old_state_files():
+    """Remove state files older than 30 days."""
+    try:
+        state_dir = os.path.expanduser("~/.claude")
+        if not os.path.exists(state_dir):
+            return
+
+        current_time = datetime.now().timestamp()
+        thirty_days_ago = current_time - (30 * 24 * 60 * 60)
+
+        for filename in os.listdir(state_dir):
+            if filename.startswith("security_warnings_state_") and filename.endswith(".json"):
+                file_path = os.path.join(state_dir, filename)
+                try:
+                    file_mtime = os.path.getmtime(file_path)
+                    if file_mtime < thirty_days_ago:
+                        os.remove(file_path)
+                except (OSError, IOError):
+                    pass
+    except Exception:
+        pass
+
+
+def load_state(session_id):
+    """Load the state of shown warnings from file."""
+    state_file = get_state_file(session_id)
+    if os.path.exists(state_file):
+        try:
+            with open(state_file, "r") as f:
+                return set(json.load(f))
+        except (json.JSONDecodeError, IOError):
+            return set()
+    return set()
+
+
+def save_state(session_id, shown_warnings):
+    """Save the state of shown warnings to file."""
+    state_file = get_state_file(session_id)
+    try:
+        os.makedirs(os.path.dirname(state_file), exist_ok=True)
+        with open(state_file, "w") as f:
+            json.dump(list(shown_warnings), f)
+    except IOError as e:
+        debug_log(f"Failed to save state file: {e}")
+
+
+def check_patterns(file_path, content):
+    """Check if file path or content matches any security patterns.
+
+    Returns (ruleName, reminder) on match, or (None, None).
+    """
+    normalized_path = file_path.lstrip("/")
+
+    for pattern in SECURITY_PATTERNS:
+        if "path_check" in pattern and pattern["path_check"](normalized_path):
+            return pattern["ruleName"], pattern["reminder"]
+
+        if "substrings" in pattern and content:
+            for substring in pattern["substrings"]:
+                if substring in content:
+                    return pattern["ruleName"], pattern["reminder"]
+
+    return None, None
+
+
+def extract_content_from_input(tool_name, tool_input):
+    """Extract the content that will be written/edited."""
+    if tool_name == "Write":
+        return tool_input.get("content", "")
+    elif tool_name == "Edit":
+        return tool_input.get("new_string", "")
+    elif tool_name == "MultiEdit":
+        edits = tool_input.get("edits", [])
+        if edits:
+            return " ".join(edit.get("new_string", "") for edit in edits)
+        return ""
+    return ""
+
+
+def main():
+    """Main hook function."""
+    # Check if security reminders are enabled
+    if os.environ.get("ENABLE_SECURITY_REMINDER", "1") == "0":
+        sys.exit(0)
+
+    # Periodically clean up old state files (10% chance per run)
+    if random.random() < 0.1:
+        cleanup_old_state_files()
+
+    # Read hook input from stdin
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except json.JSONDecodeError as e:
+        debug_log(f"JSON decode error: {e}")
+        sys.exit(0)
+
+    session_id = input_data.get("session_id", "default")
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+
+    # Only run on file-edit tools
+    if tool_name not in ["Edit", "Write", "MultiEdit"]:
+        sys.exit(0)
+
+    file_path = tool_input.get("file_path", "")
+    if not file_path:
+        sys.exit(0)
+
+    content = extract_content_from_input(tool_name, tool_input)
+
+    rule_name, reminder = check_patterns(file_path, content)
+
+    if rule_name and reminder:
+        # Suppress duplicates within the same session for the same file+rule
+        warning_key = f"{file_path}-{rule_name}"
+        shown_warnings = load_state(session_id)
+
+        if warning_key not in shown_warnings:
+            shown_warnings.add(warning_key)
+            save_state(session_id, shown_warnings)
+            # Emit warning + block the tool. Exit code 2 = block in PreToolUse hooks.
+            print(reminder, file=sys.stderr)
+            sys.exit(2)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/engineering/security-guidance/skills/security-guidance/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: security-guidance
+description: PreToolUse security-anti-pattern hook for Claude Code. Catches 12 common security risks (command injection, XSS, SQL injection, unsafe deserialization, GitHub Actions workflow injection, eval/new Function code injection) BEFORE the Edit/Write/MultiEdit operation completes. Session-state caching prevents duplicate warnings on the same file+rule combo. Stdlib only — no dependencies. Use when you want a safety net during Claude Code sessions that touch security-sensitive code (auth, payments, user input handling, IaC). Disable with ENABLE_SECURITY_REMINDER=0 if you need to perform a verified-safe operation that would otherwise trip a pattern. Triggers — "add security hook", "block unsafe code", "detect command injection before write", "prevent SQL injection patterns", "security warning hook".
+---
+
+# Security Guidance Hook
+
+**A PreToolUse hook that blocks 12 common security anti-patterns before Claude Code writes them.**
+
+This skill is a **hook**, not a slash command. Once installed, it runs automatically before every `Edit`, `Write`, or `MultiEdit` operation and warns + blocks if it detects a known dangerous pattern.
+
+## What It Catches
+
+The hook scans both:
+
+- **The file path being edited** — flags GitHub Actions workflow files with risky `${{ }}` patterns
+- **The content being written** — substring matches against 11 anti-patterns
+
+| Pattern | Category | Risk |
+|---|---|---|
+| GitHub Actions workflow expressions | Path-based | Workflow command injection via untrusted inputs |
+| `child_process.exec`, `exec(`, `execSync(` | Substring | Node.js command injection |
+| `new Function` | Substring | JS code injection |
+| `eval(` | Substring | JS code injection |
+| `dangerouslySetInnerHTML` | Substring | React XSS |
+| `document.write` | Substring | DOM XSS |
+| `.innerHTML =` | Substring | DOM XSS |
+| `pickle` | Substring | Python deserialization RCE |
+| `os.system`, `from os import system` | Substring | Python command injection |
+| `shell=True` (subprocess) | Substring | Python command injection |
+| f-string SQL or `.format` SQL | Substring | SQL injection |
+| `yaml.load(`, `yaml.unsafe_load` | Substring | YAML deserialization RCE |
+
+## How It Works
+
+1. Claude Code is about to run `Edit`, `Write`, or `MultiEdit`
+2. PreToolUse hook fires → invokes `security_reminder_hook.py` with the tool input as JSON on stdin
+3. The hook extracts file_path + content + checks against the pattern table
+4. If a pattern matches AND this warning hasn't been shown for this file+rule in this session:
+   - Print the warning to stderr (Claude sees it)
+   - Exit code 2 → blocks the tool call
+   - Save the warning key to `~/.claude/security_warnings_state_<session>.json`
+5. If a pattern matches BUT the warning was already shown this session:
+   - Allow the tool call (exit code 0) — Claude already saw the warning once
+6. If no pattern matches:
+   - Allow the tool call (exit code 0)
+
+## Installation
+
+This plugin ships as a Claude Code plugin with `hooks.json` wiring:
+
+```bash
+# In Claude Code:
+/plugin marketplace add alirezarezvani/claude-skills
+/plugin install security-guidance@claude-code-skills
+```
+
+Once installed, no further configuration needed — the hook runs automatically.
+
+## Configuration
+
+Disable per-session via environment variable:
+
+```bash
+ENABLE_SECURITY_REMINDER=0 claude
+# Hook is bypassed for this session
+```
+
+Use sparingly — the hook is most useful exactly when you're tempted to disable it (because you're under deadline pressure to ship something you know is sketchy).
+
+## Per-File Override Pattern
+
+If a specific file legitimately needs `eval()` or `pickle` (e.g., a sandboxed REPL, a deliberately unsafe parser for a fuzzer), document it in the file with a comment:
+
+```python
+# SAFETY: pickle is the required serialization format for this internal tool.
+# This file does NOT accept untrusted input. See SECURITY.md for boundary analysis.
+import pickle
+```
+
+The hook will still warn on first edit per session. After acknowledging, subsequent edits in the same session are allowed (session-state caching).
+
+## Why The Patterns Are Substring-Based (Not AST-Based)
+
+Trade-off: AST-based detection would be more precise (no false positives on string literals containing "eval("). Substring-based is:
+
+- **Faster** — runs in ms, doesn't parse the file
+- **Cross-language** — same hook works for JS/TS/Python/YAML/etc.
+- **Conservative** — false positives are easy to dismiss (one keystroke); false negatives are dangerous
+
+For 90%+ of cases, substring detection is sufficient. If you need stricter detection, layer in a proper SAST tool (semgrep, CodeQL) as a CI step.
+
+## State Files
+
+The hook caches "warning shown" state in `~/.claude/security_warnings_state_<session_id>.json`. These files:
+
+- Are auto-cleaned after 30 days (10% chance per hook invocation)
+- Are session-scoped (each Claude session gets its own)
+- Contain a JSON list of `<file_path>-<rule_name>` keys
+
+You can safely delete `~/.claude/security_warnings_state_*.json` files at any time — the hook regenerates them on next run.
+
+## Debug Log
+
+The hook writes to `~/.claude/security-warnings-log.txt` for debugging hook misfires:
+
+```bash
+tail -f ~/.claude/security-warnings-log.txt
+# Shows JSON decode errors, state-file save failures, etc.
+```
+
+(Upstream version wrote to `/tmp/security-warnings-log.txt` — we moved it to `~/.claude/` for persistence across reboots.)
+
+## Source + Attribution
+
+This plugin is ported from David Dworken's MIT-licensed implementation in [`alirezarezvani/aeo-box`](https://github.com/alirezarezvani/aeo-box/tree/main/.claude/plugins/security-guidance).
+
+**Verbatim:** the original 9 patterns (GitHub Actions, child_process.exec, new Function, eval, dangerouslySetInnerHTML, document.write, innerHTML, pickle, os.system) are preserved with their exact warning text.
+
+**Modifications:**
+- Added 3 patterns: `subprocess shell=True`, SQL injection via f-string or `.format`, `yaml.unsafe_load`
+- Debug log moved from `/tmp/security-warnings-log.txt` → `~/.claude/security-warnings-log.txt`
+- Restructured as a claude-skills plugin with `attribution` block in `plugin.json`
+
+## Anti-Patterns
+
+### Disabling the hook by default
+
+Defeats the purpose. If `ENABLE_SECURITY_REMINDER=0` becomes your default, you've trained yourself to ignore the safety net. Use it only for specific verified-safe operations.
+
+### Modifying the pattern list without security review
+
+Anyone can add a pattern. Removing one requires a security review — patterns exist because they map to real CVE classes.
+
+### Treating session-state as immutable security policy
+
+The cache prevents nag-spam but is per-session. Don't rely on "I dismissed this once" as long-term policy — use the per-file documentation pattern instead (comment justifying the use).
+
+## Related Skills
+
+- `engineering-team/skills/red-team` — adversarial pen-testing
+- `engineering-team/skills/threat-detection` — threat modeling + detection design
+- `engineering-team/skills/ai-security` — AI-specific security (prompt injection, etc.)
+- `engineering/ship-gate` — pre-production audit (8-category, ~89 checks)
+- `engineering/skill-security-auditor` — security scan for skill packages
+
+## Trigger Phrases
+
+- "add security hook"
+- "block unsafe code before write"
+- "detect command injection"
+- "prevent SQL injection patterns"
+- "warn on eval / pickle / os.system"
+- "GitHub Actions security hook"
+
+---
+
+**Version:** 2.7.3
+**Source:** Ported from [`alirezarezvani/aeo-box`](https://github.com/alirezarezvani/aeo-box) `.claude/plugins/security-guidance/` (originally by David Dworken at Anthropic, MIT)
+**License:** MIT

package/engineering/security-guidance/skills/security-guidance/references/pretooluse_hook_canon.md

@@ -0,0 +1,141 @@
+# PreToolUse Hook Discipline — When To Block, When To Warn
+
+This reference answers one decision: **when designing a PreToolUse hook for Claude Code, when should it block the tool call (exit 2) vs. just warn (exit 0 with stderr message)?** The answer depends on **reversibility × severity × false-positive rate**.
+
+## The Three Exit Codes
+
+Claude Code PreToolUse hooks have three meaningful exit codes:
+
+| Exit code | Effect | Use when |
+|---|---|---|
+| `0` | Allow the tool call to proceed | No issue detected, or warning-only emission |
+| `1` | Allow but log error | Hook itself errored — don't block the user |
+| `2` | Block the tool call | Detected pattern is severe enough to require Claude to revisit |
+
+## The Decision Matrix
+
+```
+                  High severity     Low severity
+                  ─────────────     ───────────────
+Hard to reverse   BLOCK (exit 2)    WARN (stderr + exit 0)
+Easy to reverse   WARN              ALLOW (exit 0, no message)
+```
+
+Examples:
+
+- **`eval(<user_input>)`** in production code: high severity (RCE), hard to reverse if it ships → **BLOCK**
+- **`document.write` in a test file**: medium severity, easy to reverse → **WARN** (so the user can override deliberately)
+- **`pickle.load` in a one-off script for the user's own data**: low severity in context, easy to reverse → **WARN**
+- **Editing `.env` file**: high severity (secrets), but the user explicitly asked → **WARN** (let the user proceed)
+
+## Session-State Caching
+
+The security-guidance hook caches "warning shown" state per session. This is critical UX:
+
+**Without caching:** Every Edit/Write to the same file triggers the same warning. Claude burns through tokens re-explaining + the user trains themselves to ignore. **Anti-pattern.**
+
+**With caching:** First trigger blocks → Claude/user acknowledges → subsequent edits to same file+rule allowed for rest of session. **Correct.**
+
+The caching is keyed by `<file_path>-<rule_name>`. Different rules on the same file each trigger independently (a file might warn for both `eval(` and `os.system` — and should).
+
+## False-Positive Tolerance
+
+A PreToolUse hook with a 50% false-positive rate is a hook nobody listens to. The pattern table needs to be calibrated for **high precision, accepting some recall loss**.
+
+Calibration questions per pattern:
+
+1. **Specificity:** Does the pattern uniquely identify the anti-pattern, or does it match many safe uses?
+2. **Context-blindness:** Does the substring trigger inside string literals or comments? (Acceptable cost for cross-language detection.)
+3. **Override path:** Can the user document a legitimate use case? (E.g., comment annotation.)
+
+For the security-guidance hook's 12 patterns, false-positive rates are roughly:
+
+| Pattern | FP rate (estimated) | Why |
+|---|---|---|
+| `eval(` | ~5% | Mostly only appears in code-eval contexts; very low FP |
+| `pickle` | ~30% | Includes `import pickle` and any reference to the module |
+| `innerHTML =` | ~10% | Pretty specific to the anti-pattern |
+| GitHub Actions path-check | ~0% | Path-based, never false-positive |
+| SQL f-string | ~15% | Could match harmless f-strings |
+
+Higher-FP patterns rely on session-caching: user dismisses once, no nag for rest of session.
+
+## When Substring Detection Is Enough
+
+For Claude Code PreToolUse hooks, substring detection is sufficient when:
+
+- The substring is rare in non-anti-pattern contexts (e.g., `dangerouslySetInnerHTML`)
+- The user can quickly dismiss a false positive (one-key acknowledgment)
+- The cost of a false negative is high (security regression)
+
+When substring detection is **NOT** enough:
+
+- Patterns with high natural occurrence (e.g., the word "password" — appears in legitimate docs)
+- Patterns where context matters semantically (a function called `safe_eval` should not match `eval(`)
+- Patterns that require taint analysis (knowing if data came from user input)
+
+For taint-aware analysis, layer in proper SAST in CI — don't push that complexity into the PreToolUse hook.
+
+## Hook Performance Discipline
+
+The hook runs **before every Edit/Write/MultiEdit**. Performance matters:
+
+- Substring scan of 12 patterns: ~1ms for typical file content
+- State file load/save: ~5ms (JSON, single file)
+- Total overhead: ~10ms per tool call
+
+This is well within tolerance. If a hook adds >100ms per tool call, it slows down Claude Code interactively.
+
+**Don't:** Spawn child processes from the hook (kills latency).
+**Don't:** Make network calls from the hook (kills latency + introduces failure modes).
+**Do:** Keep all logic in-process; only use stdlib.
+
+## Disable-Via-Env-Var Discipline
+
+`ENABLE_SECURITY_REMINDER=0` disables the hook for a session. Use sparingly. The pattern:
+
+- **Default ON** (this is the safe default)
+- **Disable when:** doing a verified-safe operation that would otherwise trip a pattern (e.g., writing a deliberately-unsafe sandboxed REPL, doing security research)
+- **Re-enable immediately** after the operation
+
+Don't put `export ENABLE_SECURITY_REMINDER=0` in your shell rc file. That's the anti-pattern of training-yourself-to-ignore-warnings.
+
+## Anti-Patterns
+
+### Hook that always exits 0
+
+If a hook never blocks and never warns, it has no effect. Remove it.
+
+### Hook that always exits 2 on a pattern hit
+
+If a hook always blocks, even on the 5th occurrence of a pattern the user already saw 4 times, the user disables the hook. Session-state caching is required.
+
+### Hook with network I/O
+
+Defeats latency budget + adds failure modes (what if the API is down?). Hooks should be hermetic.
+
+### Hook that modifies state Claude can't see
+
+If the hook silently mutates files or env vars, Claude doesn't know about the changes and may produce inconsistent next actions. Hooks should be observation-only or emit explicit warnings.
+
+### Hook with regex that's hard to read
+
+The pattern table should be reviewable by a non-author. If the regex is dense Perl-style, port to plain substring or simplify the regex. Maintainability >> cleverness for security code.
+
+## Citations (7 sources)
+
+1. **Anthropic — Claude Code hooks documentation (2024-2026).** Source for the canonical PreToolUse exit code semantics, hook input/output format, and ~10ms latency budget. https://docs.claude.com/en/docs/claude-code/hooks
+
+2. **OWASP — Top 10 Web Application Security Risks (2021, current ed.).** Source for which patterns to detect: injection (A03), insecure design (A04), security misconfiguration (A05), broken authentication (A07). The hook's pattern table maps directly to these categories.
+
+3. **CWE (Common Weakness Enumeration) — Top 25 Most Dangerous Software Weaknesses (current ed.).** Source for the specific weakness classes the hook catches: CWE-78 (OS command injection), CWE-79 (XSS), CWE-89 (SQL injection), CWE-94 (code injection), CWE-502 (deserialization). https://cwe.mitre.org/top25/
+
+4. **GitHub Security Lab — "How to catch GitHub Actions workflow injections before attackers do" (2023).** Source for the GitHub Actions workflow path-based pattern. The cited blog post is referenced in the hook's warning text. https://github.blog/security/vulnerability-research/how-to-catch-github-actions-workflow-injections-before-attackers-do/
+
+5. **Python.org — `pickle` module documentation (security warnings).** Source for the warning text on pickle deserialization RCE risk. https://docs.python.org/3/library/pickle.html
+
+6. **PyYAML — Documentation on yaml.load vs yaml.safe_load (security warnings).** Source for the yaml.unsafe_load pattern. https://pyyaml.org/wiki/PyYAMLDocumentation
+
+7. **React documentation — `dangerouslySetInnerHTML` security warnings.** Source for the React XSS pattern. https://react.dev/reference/react-dom/components/common#dangerously-setting-the-inner-html
+
+8. **NIST — Secure Software Development Framework (SSDF, current ed.).** Source for the "shift-left" principle that motivates PreToolUse hooks: detect security issues at the earliest possible point in the development lifecycle, before they hit version control.