ecoportal-api 0.10.16 → 0.10.17

data/.ai-assistance/scripts/log-skill-usage.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# log-skill-usage.sh -- PreToolUse hook (matcher: Skill) that DETERMINISTICALLY
+# records every Skill-tool invocation to the ISO-week usage log. This replaces
+# the old per-skill self-report instruction (which never fired -- 575 fleet
+# records were ALL the scheduler heartbeat, ZERO skill/* events), matching the
+# token-frugality rule: hard-wire the deterministic part, no inline inference.
+#
+# Standard: standards/kpi/usage-tracking.md ("Who writes usage records").
+#
+# Wired in .claude/settings.json:
+#   "PreToolUse": [{ "matcher": "Skill",
+#       "hooks": [{ "type": "command",
+#                   "command": "bash .ai-assistance/scripts/log-skill-usage.sh" }] }]
+#
+# Reads:  stdin -- the PreToolUse JSON (tool_name, tool_input.skill, session_id, cwd)
+# Writes: .ai-assistance/local/kpi/usage-<YYYY-WNN>.jsonl (one appended line)
+#
+# NOTE: uses `python -c` (NOT a heredoc) so the hook's stdin -- the PreToolUse
+# JSON -- reaches python. A heredoc would replace stdin with the script itself.
+# Fails OPEN and SILENT on any error: a KPI logger must never wedge or slow a
+# session, and PreToolUse must not deny the tool. Always exits 0 with no stdout.
+PY=python3
+command -v python3 >/dev/null 2>&1 || PY=python
+exec "$PY" -c '
+import sys, json, os, datetime
+
+def week_id(now):
+    y, w, _ = now.isocalendar()
+    return "%04d-W%02d" % (y, w)
+
+try:
+    raw = sys.stdin.buffer.read()
+    # Tolerate cp1252/latin-1 on Windows shells; never choke on odd bytes.
+    try:
+        text = raw.decode("utf-8")
+    except Exception:
+        text = raw.decode("cp1252", "replace")
+    data = json.loads(text)
+except Exception:
+    sys.exit(0)  # cannot parse -> record nothing, allow the tool (fail open)
+
+if data.get("tool_name") != "Skill":
+    sys.exit(0)
+
+tool_input = data.get("tool_input") or {}
+skill = tool_input.get("skill") or "unknown"
+# Slash-form or plugin-namespaced skills: keep the leaf name, kebab-safe.
+skill = str(skill).strip().lstrip("/")
+if ":" in skill:          # plugin:skill -> skill
+    skill = skill.split(":")[-1]
+skill = skill.replace(" ", "-")
+
+session_id = data.get("session_id") or ""
+cwd = data.get("cwd") or os.getcwd()
+repo = os.path.basename(os.path.normpath(cwd)) if cwd else ""
+
+now = datetime.datetime.now(datetime.timezone.utc)
+ts = now.strftime("%Y-%m-%dT%H:%M:%SZ")
+week = week_id(now)
+
+log_dir = os.path.join(".ai-assistance", "local", "kpi")
+log_file = os.path.join(log_dir, "usage-%s.jsonl" % week)
+record = {
+    "component": "skill/%s" % skill,
+    "action": "invoked",
+    "detail": "Skill tool invoked",
+    "ts": ts,
+    "session_id": session_id,
+    "repo": repo,
+}
+try:
+    os.makedirs(log_dir, exist_ok=True)
+    with open(log_file, "a", encoding="utf-8") as fh:
+        fh.write(json.dumps(record) + "\n")
+except Exception:
+    pass  # never fail the session over a KPI write
+
+sys.exit(0)
+'

data/.ai-assistance/scripts/log_mcp_access.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""
+log_mcp_access.py -- MCP access-audit capture (PostToolUse hook, matcher mcp__.*).
+
+Standard: standards/security/access-audit-ledger.md ("Record schema" -- the fields this
+script writes are exactly the ones marked CAPTURED there; nothing else is fabricated).
+
+Hook mode (no flags, the only mode used in production): reads the PostToolUse JSON from
+stdin and, IF tool_name looks like an MCP tool call (mcp__<server>__<tool>), appends ONE
+JSON record to the v0 local ledger:
+    .ai-assistance/local/audit/access-<ISO-week>.jsonl
+
+CAPTURE ALLOW-LIST -- only what is cheaply and honestly derivable from the hook payload:
+  - tool_name                          (direct from the hook JSON)
+  - session_id                         (direct from the hook JSON, "" if absent)
+  - repo                               (basename of cwd, same convention as
+                                         log-skill-usage.sh)
+  - ep_ai_standards_version            (see standard doc: standards-version.json first,
+                                         this repo's own CHANGELOG.md as a fallback)
+  - tool_input_summary                 (top-level ARGUMENT KEY NAMES only -- sorted list
+                                         + count -- never a single argument VALUE)
+  - result                             ("ok" / "error" / "unknown" from
+                                         tool_response.isError when it is a real bool)
+  - ts                                 (wall clock at capture time, UTC ISO 8601)
+
+NEVER captured, ever, by design (PII/secret risk -- see the standard's "PII / secret risk"
+section): tool_input VALUES, tool_response body/output/stdout/stderr content, prompt or
+response text, file contents. Only shapes (key names, booleans, counts) are recorded.
+
+Fields the owner's spec asked for that are NOT written here because they are not honestly
+capturable from this hook payload today (see the standard doc for the full PLANNED list
+and why): related_mr_task_id, model, reason, associated_cost, triggering_skill,
+skill_version, api_key_sha256, latency. None of them are written as null/empty guesses --
+they are simply absent from the record.
+
+Never blocks a session (hook mode): any error -> exit 0, write nothing. ASCII-only output
+(json.dumps with ensure_ascii=True) regardless of what bytes arrive on stdin.
+"""
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+_MCP_TOOL_RE = re.compile(r"^mcp__")
+_CHANGELOG_VERSION_RE = re.compile(r"^##\s*\[(\d+\.\d+\.\d+)\]", re.MULTILINE)
+
+
+def _iso_now():
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _iso_week(now=None):
+    now = now or datetime.now(timezone.utc)
+    y, w, _ = now.isocalendar()
+    return "%04d-W%02d" % (y, w)
+
+
+def _ep_ai_standards_version(root):
+    """Best-effort, cheap, no network. See standard doc for the two sources tried."""
+    vf = root / ".ai-assistance" / "standards-version.json"
+    try:
+        if vf.is_file():
+            data = json.loads(vf.read_text(encoding="utf-8"))
+            v = data.get("ep-ai-standards-version")
+            if isinstance(v, str) and v:
+                return v
+    except Exception:
+        pass
+    changelog = root / "CHANGELOG.md"
+    try:
+        if changelog.is_file():
+            text = changelog.read_text(encoding="utf-8", errors="replace")
+            m = _CHANGELOG_VERSION_RE.search(text)
+            if m:
+                return m.group(1)
+    except Exception:
+        pass
+    return None
+
+
+def _tool_input_summary(tool_input):
+    """Top-level argument KEY NAMES only -- never a value. Tolerates any shape."""
+    if not isinstance(tool_input, dict):
+        return {"n_keys": 0, "keys": []}
+    keys = sorted(str(k) for k in tool_input.keys())
+    return {"n_keys": len(keys), "keys": keys}
+
+
+def _result_status(tool_response):
+    if isinstance(tool_response, dict) and isinstance(tool_response.get("isError"), bool):
+        return "error" if tool_response["isError"] else "ok"
+    return "unknown"
+
+
+def build_record(data):
+    """Pure: given a parsed PostToolUse payload dict, return a record dict, or None if
+    this event is not an MCP tool call (nothing to log). Never raises -- any malformed
+    shape inside `data` degrades a field to its safe default instead of erroring out."""
+    if not isinstance(data, dict):
+        return None
+    tool_name = data.get("tool_name")
+    if not isinstance(tool_name, str) or not _MCP_TOOL_RE.match(tool_name):
+        return None  # not an MCP tool call -- nothing for this ledger
+
+    cwd = data.get("cwd") or os.getcwd()
+    root = Path(cwd)
+    repo = os.path.basename(os.path.normpath(str(cwd))) if cwd else ""
+    session_id = data.get("session_id") or ""
+
+    record = {
+        "ts": _iso_now(),
+        "session_id": session_id,
+        "repo": repo,
+        "tool_name": tool_name,
+        "tool_input_summary": _tool_input_summary(data.get("tool_input")),
+        "result": _result_status(data.get("tool_response")),
+    }
+    version = _ep_ai_standards_version(root)
+    if version:
+        record["ep_ai_standards_version"] = version
+    return record
+
+
+def _write_record(root, record):
+    week = _iso_week()
+    log_dir = root / ".ai-assistance" / "local" / "audit"
+    log_file = log_dir / ("access-%s.jsonl" % week)
+    log_dir.mkdir(parents=True, exist_ok=True)
+    with log_file.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(record, ensure_ascii=True) + "\n")
+
+
+def main(argv=None):  # noqa: ARG001 -- no flags; argv kept for test-call symmetry
+    try:
+        raw = sys.stdin.buffer.read()
+        try:
+            text = raw.decode("utf-8")
+        except Exception:
+            text = raw.decode("cp1252", "replace")
+        data = json.loads(text) if text.strip() else {}
+    except Exception:
+        return 0  # malformed payload -> allow the tool, log nothing (fail open)
+
+    try:
+        record = build_record(data)
+        if record is None:
+            return 0
+        cwd = data.get("cwd") or os.getcwd()
+        _write_record(Path(cwd), record)
+    except Exception:
+        pass  # an audit logger must never wedge or fail a session
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

data/.ai-assistance/scripts/observe-session.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# observe-session.sh -- thin Stop/SessionEnd wrapper for the procedural-memory OBSERVE stage.
+# Opt-in (off by default): does nothing unless .ai-assistance/local/procedural-observe.enabled
+# exists or PROCEDURAL_OBSERVE=1 is set. Enable/disable/status (human-run, one command):
+#   python .ai-assistance/scripts/observe_session.py --enable | --disable | --status
+# Writes to the dedicated stream .ai-assistance/local/observe-<ISO-week>.jsonl (separate from
+# the kpi/usage heartbeat stream). Never blocks a session (always exits 0).
+# Logic + privacy allow-list + scrub-before-write live in observe_session.py.
+# Standard: standards/workflows/procedural-memory.md (D2).
+PY=python3
+command -v python3 >/dev/null 2>&1 || PY=python
+"$PY" "$(dirname "$0")/observe_session.py" || true
+exit 0

data/.ai-assistance/scripts/observe_session.py

@@ -0,0 +1,287 @@
+#!/usr/bin/env python3
+"""
+observe_session.py -- Procedural-memory OBSERVE stage (Stop / SessionEnd hook).
+
+Standard: standards/workflows/procedural-memory.md (D2 -- logging privacy).
+
+Hook mode (no flags): reads the Stop-hook JSON from stdin, and IF the developer has opted
+in, appends ONE low-sensitivity session-summary record to the DEDICATED observe stream
+.ai-assistance/local/observe-<ISO-week>.jsonl. The observe stream is deliberately separate
+from the KPI stream (.ai-assistance/local/kpi/usage-*.jsonl), which is dominated by
+scheduler heartbeats -- mixing the two buried the behavioral signal (2026-07-20 inventory).
+
+CLI mode (one-command opt-in management; run by a HUMAN, never by automation):
+  python observe_session.py --status    # is Observe enabled here? what has it captured?
+  python observe_session.py --enable    # create the consent flag (explicit human opt-in)
+  python observe_session.py --disable   # remove the consent flag (streams are kept)
+
+CONSENT (opt-in, off by default). Observe runs only when the developer has opted in, by
+either:
+  - creating the marker file  .ai-assistance/local/procedural-observe.enabled
+    (preferred; `--enable` above is the one-command way), or
+  - exporting  PROCEDURAL_OBSERVE=1  in the environment.
+If neither is set, this script writes nothing and exits 0. The distill pass applies the same
+gate (refuses to read the log without consent). Nothing in the toolchain may create the flag
+automatically -- enabling is a human decision (consent is load-bearing).
+
+CAPTURE ALLOW-LIST (D2) -- only structured, low-sensitivity signal:
+  - tool/command NAMES (the verb, e.g. Edit, Bash, git) -- never arguments
+  - file paths + extensions touched, RELATIVE to the repo root -- never file contents/diffs
+  - coarse counts (n tools, n files) and a duration bucket
+  - session id, ISO week, timestamp
+NEVER captured: command arguments, file contents/diffs, prompt/response text, the literal
+text of corrections/redirects, secrets/tokens/credentials.
+
+REDACTION: every string that could carry a path is passed through scripts/lib/scrub.py
+BEFORE it is written. If scrub reports it could not run cleanly, the field is dropped.
+
+Never blocks a session (hook mode): any error -> exit 0, write nothing.
+"""
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+# ISO-week + timestamp without Date.now()-style nondeterminism concerns: this runs on the
+# host at session end, so real wall-clock is correct and expected here.
+from datetime import datetime, timezone
+
+_ALLOWED_FILE_TOOLS = {"Read", "Edit", "Write", "NotebookEdit", "MultiEdit"}
+_DUR_BUCKETS = [(300, "short"), (1800, "medium"), (7200, "long")]  # secs -> label; else "xlong"
+
+FLAG_NAME = "procedural-observe.enabled"
+
+
+def _iso_now():
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _iso_week():
+    y, w, _ = datetime.now(timezone.utc).isocalendar()
+    return f"{y}-W{w:02d}"
+
+
+def _load_scrub(root):
+    """Import scrub() from scrub.py if available; else None.
+
+    Returns None when the redactor cannot be loaded. Privacy FAILS CLOSED: the caller must
+    write NOTHING when scrub is unavailable, rather than logging unscrubbed signal. (A prior
+    version fell back to an identity function -- that would log file paths, which can carry a
+    username, without redaction on a repo where scrub.py was not deployed.)"""
+    for cand in (root / ".ai-assistance" / "scripts", root / "scripts" / "lib"):
+        p = cand / "scrub.py"
+        if p.exists():
+            sys.path.insert(0, str(cand))
+            try:
+                import scrub  # type: ignore
+                return scrub.scrub
+            except Exception:
+                pass
+    return None
+
+
+def _consent(local_dir):
+    if os.environ.get("PROCEDURAL_OBSERVE", "").lower() in ("1", "true", "yes"):
+        return True
+    return (local_dir / FLAG_NAME).exists()
+
+
+# --- opt-in management CLI (--enable / --disable / --status) -------------------
+
+def _cli_enable(local_dir):
+    """Create the consent flag. This command exists to make the HUMAN opt-in trivial;
+    it must only ever be run by a developer, never by a hook/scheduler/agent."""
+    flag = local_dir / FLAG_NAME
+    if flag.exists():
+        print(f"[observe] already enabled ({flag})")
+        return 0
+    local_dir.mkdir(parents=True, exist_ok=True)
+    flag.write_text(
+        "Procedural-memory Observe opt-in (standard D2 consent flag).\n"
+        "Created by observe_session.py --enable at the developer's request.\n"
+        f"Enabled: {_iso_now()}\n",
+        encoding="utf-8",
+    )
+    print(f"[observe] ENABLED -- consent flag created: {flag}")
+    print("[observe] capture allow-list (D2): tool names, repo-relative paths, coarse counts.")
+    print("[observe] never captured: arguments, file contents, diffs, prompt/response text.")
+    print("[observe] stream: .ai-assistance/local/observe-<ISO-week>.jsonl (machine-local, gitignored).")
+    print("[observe] disable any time: observe_session.py --disable (streams kept; delete them freely).")
+    return 0
+
+
+def _cli_disable(local_dir):
+    flag = local_dir / FLAG_NAME
+    if not flag.exists():
+        print("[observe] already disabled (no consent flag)")
+        return 0
+    flag.unlink()
+    print(f"[observe] DISABLED -- consent flag removed: {flag}")
+    print("[observe] existing observe-*.jsonl streams were kept; delete them if you want them gone.")
+    return 0
+
+
+def _cli_status(local_dir):
+    flag = local_dir / FLAG_NAME
+    env_on = os.environ.get("PROCEDURAL_OBSERVE", "").lower() in ("1", "true", "yes")
+    if flag.exists():
+        state = f"ENABLED (flag: {flag})"
+    elif env_on:
+        state = "ENABLED (PROCEDURAL_OBSERVE env var; no flag file)"
+    else:
+        state = "disabled (no consent flag; enable with: observe_session.py --enable)"
+    print(f"[observe] status: {state}")
+    streams = sorted(local_dir.glob("observe-*.jsonl")) if local_dir.is_dir() else []
+    if not streams:
+        print("[observe] streams: none captured yet")
+    for s in streams:
+        try:
+            n = sum(1 for ln in s.read_text(encoding="utf-8", errors="replace").splitlines() if ln.strip())
+        except OSError:
+            n = "?"
+        print(f"[observe] stream: {s.name} ({n} record(s))")
+    return 0
+
+
+def _duration_bucket(secs):
+    try:
+        secs = float(secs)
+    except (TypeError, ValueError):
+        return "unknown"
+    for lim, label in _DUR_BUCKETS:
+        if secs <= lim:
+            return label
+    return "xlong"
+
+
+def _extract_from_transcript(path, root, scrub):
+    """Return (tool_counts, files) reading ONLY tool-use verbs + file paths from the
+    transcript. Never reads prompt/response text or tool arguments beyond a file path."""
+    tool_counts = {}
+    files = []
+    seen = set()
+    try:
+        lines = Path(path).read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return tool_counts, files
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            rec = json.loads(line)
+        except ValueError:
+            continue
+        # Anthropic transcript: assistant messages carry content blocks; tool_use blocks
+        # have {"type":"tool_use","name":...,"input":{...}}. We read name + a file path only.
+        msg = rec.get("message") or rec
+        content = msg.get("content") if isinstance(msg, dict) else None
+        if not isinstance(content, list):
+            continue
+        for block in content:
+            if not isinstance(block, dict) or block.get("type") != "tool_use":
+                continue
+            name = block.get("name") or "unknown"
+            tool_counts[name] = tool_counts.get(name, 0) + 1
+            if name in _ALLOWED_FILE_TOOLS:
+                inp = block.get("input") or {}
+                fp = inp.get("file_path") or inp.get("path") or inp.get("notebook_path")
+                if not fp:
+                    continue
+                # Make repo-relative; keep only path + extension, then scrub.
+                try:
+                    rel = os.path.relpath(fp, str(root))
+                except ValueError:
+                    rel = fp
+                rel = rel.replace("\\", "/")
+                scrubbed, findings = scrub(rel)
+                if any(f.get("type") == "error" for f in findings):
+                    continue  # scrub could not run cleanly -> drop
+                ext = os.path.splitext(scrubbed)[1].lower()
+                key = (ext, scrubbed)
+                if key not in seen:
+                    seen.add(key)
+                    files.append({"ext": ext, "path": scrubbed})
+    return tool_counts, files
+
+
+def _hook_mode():
+    try:
+        raw = sys.stdin.read()
+        data = json.loads(raw) if raw.strip() else {}
+    except Exception:
+        return 0
+
+    cwd = data.get("cwd") or os.getcwd()
+    root = Path(cwd)
+    local_dir = root / ".ai-assistance" / "local"
+    if not _consent(local_dir):
+        return 0  # not opted in -> observe nothing
+
+    scrub = _load_scrub(root)
+    if scrub is None:
+        # Fail CLOSED: redactor unavailable -> do not log anything (never write unscrubbed).
+        sys.stderr.write("[observe] scrub.py not found; skipping session log (privacy fail-closed).\n")
+        return 0
+    session_id = data.get("session_id") or data.get("sessionId") or ""
+    transcript = data.get("transcript_path") or data.get("transcriptPath")
+
+    tool_counts, files = ({}, [])
+    if transcript:
+        tool_counts, files = _extract_from_transcript(transcript, root, scrub)
+
+    record = {
+        "component": "procedural/observe",
+        "action": "session-summary",
+        "ts": _iso_now(),
+        "session_id": session_id,
+        "week": _iso_week(),
+        "detail": {
+            "tools": tool_counts,
+            "files": files,
+            "n_tools": sum(tool_counts.values()),
+            "n_files": len(files),
+            "duration_bucket": _duration_bucket(data.get("duration_seconds")),
+        },
+    }
+
+    # Dedicated observe stream -- NOT the kpi/usage-*.jsonl heartbeat stream.
+    try:
+        local_dir.mkdir(parents=True, exist_ok=True)
+        out = local_dir / f"observe-{record['week']}.jsonl"
+        with out.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(record) + "\n")
+    except OSError:
+        return 0
+    return 0
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="Procedural-memory Observe stage: Stop-hook logger (default) "
+                    "+ human opt-in management (--enable/--disable/--status).")
+    ap.add_argument("--enable", action="store_true",
+                    help="create the consent flag (HUMAN opt-in -- run this yourself)")
+    ap.add_argument("--disable", action="store_true", help="remove the consent flag")
+    ap.add_argument("--status", action="store_true",
+                    help="show whether Observe is enabled and what it has captured")
+    ap.add_argument("--cwd", default=os.getcwd(),
+                    help="repo root for CLI mode (default: current directory)")
+    a = ap.parse_args(argv)
+
+    if sum((a.enable, a.disable, a.status)) > 1:
+        print("[observe] pick ONE of --enable / --disable / --status")
+        return 2
+    local_dir = Path(a.cwd) / ".ai-assistance" / "local"
+    if a.enable:
+        return _cli_enable(local_dir)
+    if a.disable:
+        return _cli_disable(local_dir)
+    if a.status:
+        return _cli_status(local_dir)
+    return _hook_mode()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

data/.ai-assistance/scripts/protect-host-paths.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# protect-host-paths.sh -- PreToolUse hook (matcher: Bash) that blocks commands
+# writing to / deleting host-OS system paths. Defense-in-depth: this decision is
+# enforced regardless of permission mode, so it holds even under
+# --dangerously-skip-permissions (where the deny-list prompts are off).
+# Standard: standards/tooling/host-protection.md (Layer 4).
+#
+# Emits a structured deny decision on stdout + exit 0 (NOT exit 2, whose behavior
+# in dangerous mode is unclear). Uses python3 (a documented prereq) -- no jq needed.
+# Fails OPEN on any internal error (a guard must never wedge the session): if it
+# cannot parse, it allows and lets the normal permission flow decide.
+#
+# NOTE: uses `python -c` (NOT a `<<HEREDOC`) so the hook's stdin -- the PreToolUse
+# JSON -- reaches python. A heredoc would replace stdin with the script itself.
+PY=python3
+command -v python3 >/dev/null 2>&1 || PY=python
+exec "$PY" -c '
+import sys, json, re
+try:
+    data = json.loads(sys.stdin.read())
+except Exception:
+    sys.exit(0)  # cannot parse -> allow (fail open); normal permissions still apply
+if data.get("tool_name") != "Bash":
+    sys.exit(0)
+cmd = (data.get("tool_input") or {}).get("command", "") or ""
+
+verbs = r"(?:\brm\b|\brmdir\b|\bmv\b|\bcp\b|\bdd\b|\btee\b|\btruncate\b|\bchown\b|\bchmod\b|>>?|\bmkfs\S*|\bdiskutil\b)"
+
+# Anchor: a root only counts as a true filesystem root when the leading `/`, `~`,
+# or drive-letter is at a path boundary -- start-of-token, whitespace, quote, `=`,
+# or start-of-string -- and NOT preceded by a path character. Without this, an
+# unanchored `/lib` etc. matches mid-path substrings like `scripts/lib/x.py` or
+# `tmp/var/x`, producing false positives (proven 2026-07-22). The negative
+# lookbehind rules out being preceded by a word char, `.`, `/`, `\`, or `-`.
+BOUNDARY = r"(?<![\w./\\-])"
+roots = [
+    BOUNDARY + r"/System(?:/|\b)", BOUNDARY + r"/Library(?:/|\b)", BOUNDARY + r"~/Library(?:/|\b)",
+    BOUNDARY + r"/usr(?:/|\b)", BOUNDARY + r"/bin(?:/|\b)", BOUNDARY + r"/sbin(?:/|\b)", BOUNDARY + r"/etc(?:/|\b)",
+    BOUNDARY + r"/boot(?:/|\b)", BOUNDARY + r"/lib(?:/|\b)", BOUNDARY + r"/opt(?:/|\b)", BOUNDARY + r"/var(?:/|\b)",
+    BOUNDARY + r"[A-Za-z]:\\+Windows", BOUNDARY + r"[A-Za-z]:\\+Program Files",
+    BOUNDARY + r"/[A-Za-z]/Windows", BOUNDARY + r"/[A-Za-z]/Program Files",
+    # User-level persistence / credential targets (literal ~ form; shell-expanded forms
+    # can still bypass -- this is a heuristic layer, not a sandbox). NOT ~/.config (too broad).
+    BOUNDARY + r"~/\.ssh(?:/|\b)", BOUNDARY + r"~/\.aws(?:/|\b)", BOUNDARY + r"~/\.gnupg(?:/|\b)",
+    BOUNDARY + r"~/\.bashrc\b", BOUNDARY + r"~/\.zshrc\b", BOUNDARY + r"~/\.bash_profile\b", BOUNDARY + r"~/\.zprofile\b",
+    BOUNDARY + r"~/\.profile\b", BOUNDARY + r"~/\.gitconfig\b",
+]
+danger = [
+    r"\brm\s+-rf\s+/(?:\s|$)",
+    r"\brm\s+-rf\s+~(?:/|\s|$)",
+    r"\bsudo\b",
+    r":\(\)\s*\{",
+]
+
+# Strip commit-message DATA before scanning for danger verbs -- a `git commit
+# -m "..."` (or `--message`) argument, or a message piped in via a quoted
+# heredoc, is text handed to git as the commit message; it is never executed
+# by the shell. Without this, a message merely *mentioning* a danger word --
+# e.g. `git commit -m "docs: mention sudo usage"` -- was denied even though
+# nothing runs. Proven 2026-07-22.
+#
+# Kept conservative on purpose (never widen this to "any quoted string" --
+# a `bash -c "..."` payload IS executed and must keep scanning):
+#   - single-quoted -m/--message values: single quotes disable ALL shell
+#     expansion, so the content can never itself be executed code -> always
+#     safe to strip.
+#   - double-quoted -m/--message values: only stripped if they contain no
+#     `$(` / backtick command substitution (plain literal text), OR are
+#     exactly the standard multi-line idiom, e.g. $(cat <<EOF with a QUOTED
+#     delimiter ... EOF) -- in which case only the inert heredoc body is
+#     stripped, so something like -m "$(sudo rm -rf /)" (a real, executed
+#     command substitution smuggled into a -m value) is left untouched and
+#     still blocked.
+#   - git commit ... -F - <<EOF (with a QUOTED delimiter) ... EOF: message
+#     read directly from a quoted (non-expanding) heredoc attached to
+#     `git commit` -- also inert text. An UNQUOTED heredoc delimiter (plain
+#     <<EOF, no quotes around it) is deliberately left alone: its body still
+#     undergoes shell expansion, so it is not guaranteed to be inert.
+def _strip_commit_message_data(cmd):
+    out = cmd
+
+    out = re.sub(
+        r"(-m|--message)(=|\s+)\x27[^\x27]*\x27",
+        lambda m: m.group(1) + m.group(2) + "\x27\x27",
+        out,
+    )
+
+    def _strip_dq_message(m):
+        prefix, sep, body = m.group(1), m.group(2), m.group(3)
+        idiom = re.match(
+            r"^\$\(\s*cat\s+<<[-~]?\s*([\x27\"])(\w+)\1\s*\r?\n(.*?)\r?\n[ \t]*\2\s*\)\s*$",
+            body, re.DOTALL,
+        )
+        if idiom:
+            quote, delim = idiom.group(1), idiom.group(2)
+            return prefix + sep + "\"$(cat <<" + quote + delim + quote + "\n\n" + delim + ")\""
+        if "$(" not in body and "`" not in body:
+            return prefix + sep + "\"\""
+        return m.group(0)  # contains a real substitution -- leave it, keep scanning
+
+    out = re.sub(
+        r"(-m|--message)(=|\s+)\"((?:\\.|[^\"\\])*)\"",
+        _strip_dq_message,
+        out,
+        flags=re.DOTALL,
+    )
+
+    out = re.sub(
+        r"(git\s+commit\b[^\n]*<<[-~]?\s*([\x27\"])(\w+)\2[^\n]*\n)(.*?)(\n[ \t]*\3\b)",
+        lambda m: m.group(1) + m.group(5),
+        out,
+        flags=re.DOTALL,
+    )
+
+    return out
+
+def blocked(reason):
+    print(json.dumps({"hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "deny",
+        "permissionDecisionReason": reason}}))
+    sys.exit(0)
+
+scan_cmd = _strip_commit_message_data(cmd)
+
+for d in danger:
+    if re.search(d, scan_cmd):
+        blocked("Blocked: destructive/privileged command (host-protection hook).")
+
+root_re = "(?:" + "|".join(roots) + ")"
+if re.search(verbs + r"[^\n]*" + root_re, scan_cmd) or re.search(root_re + r"[^\n]*" + verbs, scan_cmd):
+    blocked("Blocked: command writes/deletes a host-OS system path (host-protection hook).")
+
+sys.exit(0)
+'