@andespindola/crow-skills 0.7.1 → 0.9.0

package/crow_skills/hook.py

@@ -0,0 +1,616 @@
+"""crow-skills mode, per-prompt hook and event bus (crow-event/1).
+
+Self-contained on purpose (standard library only, no package-relative
+imports): the integrations copy this file next to the CLI state as
+``crow_hook.py`` and every agent CLI runs it from its hooks, so it keeps
+working when the npm/Homebrew path of the CLI changes. The CLI imports the
+same functions for ``crow-skills mode`` and ``crow-skills events``.
+
+Contract for hooks: return fast, never block the agent, fail open. Any error
+is swallowed and the hook exits 0 with no output. Nothing from a prompt,
+message or tool input is ever stored or printed: only ids, host, cwd, model,
+permission mode, event type, tool name, counters and timestamps.
+
+  crow_hook.py hook --host claude|codex|gemini|agy|devin --event NAME [--home DIR]
+  crow_hook.py mode on|off|status [--home DIR] [--by HOST] [--json]
+
+On a prompt event the hook also appends one memory line to the context, only
+when the machine is under pressure or the recommended parallelism is not
+"parallel" (crow_resources.py, copied beside this file; cached for a few
+seconds, so most prompts cost one small file read).
+"""
+from datetime import datetime, timezone
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import sys
+import time
+import uuid
+
+MODE_SCHEMA = "crow-mode/1"
+EVENT_SCHEMA = "crow-event/1"
+SESSION_SCHEMA = "crow-session/1"
+MODES = ("on", "off")
+DEFAULT_MODE = "on"
+HOSTS = ("claude", "codex", "gemini", "agy", "devin")
+MAX_EVENTS_FILE = 1024 * 1024  # bytes before rotation
+ROTATED = 2  # events.jsonl.1 .. events.jsonl.N are kept
+SESSION_TTL = 24 * 3600  # snapshot files untouched for this long are pruned
+MAX_SESSIONS = 200
+MAX_STDIN = 4 * 1024 * 1024
+TOKEN = re.compile(r"[^A-Za-z0-9_.:@/+-]")
+COMMAND = re.compile(r"\s*/crow[ \t]+(on|off|status)\s*\Z", re.IGNORECASE)
+
+# Host event name -> normalised event. Unknown names are recorded as "other".
+EVENTS = {
+    "SessionStart": "session_start", "SessionEnd": "session_end",
+    "UserPromptSubmit": "prompt", "BeforeAgent": "prompt", "PreInvocation": "prompt",
+    "PreToolUse": "tool_start", "BeforeTool": "tool_start",
+    "PostToolUse": "tool_end", "AfterTool": "tool_end", "PostToolUseFailure": "tool_error",
+    "PermissionRequest": "permission_request", "Notification": "notification",
+    "SubagentStart": "subagent_start", "SubagentStop": "subagent_stop",
+    "Stop": "stop", "AfterAgent": "stop", "PostInvocation": "stop", "StopFailure": "error",
+    "PreCompact": "compact", "PostCompact": "compact", "PreCompress": "compact", "PostCompaction": "compact",
+    "Interrupt": "interrupt",
+}
+PROMPT_EVENTS = ("UserPromptSubmit", "BeforeAgent", "PreInvocation")
+
+
+# --- paths and small helpers ------------------------------------------------------------
+
+def mode_path(home):
+    return Path(home) / ".config" / "crow-skills" / "mode.json"
+
+
+def events_dir(home):
+    return Path(home) / ".local" / "state" / "crow-skills" / "events"
+
+
+def now_iso():
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def token(value, limit=128):
+    """An id, model or tool name as a short single token; anything else is dropped."""
+    if value is None or isinstance(value, (dict, list, bool)):
+        return None
+    text = TOKEN.sub("", str(value))[:limit]
+    return text or None
+
+
+def plain_path(value):
+    if not isinstance(value, str) or not value.startswith("/") or len(value) > 4096:
+        return None
+    return "".join(c for c in value if c.isprintable())
+
+
+def no_follow_dir(path):
+    """Create a private directory chain; refuse when any component is a symlink."""
+    path = Path(os.path.abspath(path))
+    for part in reversed((path, *path.parents)):
+        if part.is_symlink():
+            raise OSError("symlink in state path")
+    path.mkdir(parents=True, exist_ok=True, mode=0o700)
+    return path
+
+
+def write_json(path, data, mode=0o600):
+    path = Path(path)
+    no_follow_dir(path.parent)
+    temp = path.parent / ("." + path.name + "." + uuid.uuid4().hex)
+    try:
+        fd = os.open(temp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), mode)
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(data, handle, ensure_ascii=False, sort_keys=True, indent=2)
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp, path)
+    finally:
+        if os.path.lexists(temp):
+            os.unlink(temp)
+
+
+def read_json(path, limit=1024 * 1024):
+    path = Path(path)
+    if path.is_symlink() or not path.is_file() or path.stat().st_size > limit:
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+# --- mode -----------------------------------------------------------------------------------
+
+def read_mode(home):
+    """Current mode; a missing or invalid file means the default (on)."""
+    data = read_json(mode_path(home), 64 * 1024)
+    if isinstance(data, dict) and data.get("mode") in MODES:
+        return {"mode": data["mode"], "updatedAt": data.get("updatedAt"), "updatedBy": data.get("updatedBy"),
+                "source": "file", "path": str(mode_path(home))}
+    return {"mode": DEFAULT_MODE, "updatedAt": None, "updatedBy": None, "source": "default", "path": str(mode_path(home))}
+
+
+def write_mode(home, value, by=None):
+    if value not in MODES:
+        raise ValueError("mode must be on or off")
+    data = {"schema": MODE_SCHEMA, "mode": value, "updatedAt": now_iso(), "updatedBy": token(by, 40) or "cli"}
+    write_json(mode_path(home), data, 0o644)
+    record(home, {"event": "mode_change", "host": token(by, 20) or "cli", "mode": value})
+    return read_mode(home)
+
+
+def indicator(mode, unicode=True):
+    return ("▸▸ " if unicode else ">> ") + "crow " + mode
+
+
+def context_line(mode):
+    """The additionalContext a prompt hook injects; short, so it costs little per prompt."""
+    if mode == "on":
+        return ("[crow-skills] modo crow: ON. Modo de orquestração permanente declarado pelo usuário: em toda tarefa "
+                "substantiva desta sessão, carregue e siga a skill crow-behaviour (conversa e ajuste trivial seguem diretos). "
+                "Vale até o usuário desligar com /crow off ou crow-skills mode off.")
+    return ("[crow-skills] modo crow: OFF. Não carregue nem aplique a skill crow-behaviour, salvo se o usuário a invocar "
+            "explicitamente neste pedido. Religar: /crow on ou crow-skills mode on.")
+
+
+# --- machine resources ------------------------------------------------------------------
+
+_RESOURCES = None
+
+
+def resources_module():
+    """The resource probe: the package module, or crow_resources.py beside this file.
+
+    Loaded by path because the hooks run with ``python -I`` (the script's directory is
+    not on sys.path). None when it is missing: the hook then adds nothing.
+    """
+    global _RESOURCES
+    if _RESOURCES is None:
+        _RESOURCES = False
+        try:
+            if __package__:
+                from . import resources as module  # type: ignore[attr-defined]
+                _RESOURCES = module
+            else:
+                import importlib.util
+                here = Path(os.path.abspath(__file__)).parent
+                for name in ("crow_resources.py", "resources.py"):
+                    path = here / name
+                    if path.is_file() and not path.is_symlink():
+                        spec = importlib.util.spec_from_file_location("crow_resources", path)
+                        module = importlib.util.module_from_spec(spec)
+                        # Bytecode is cached in __pycache__ beside it (~5 ms less per prompt);
+                        # the integrations uninstall removes that directory with the scripts.
+                        spec.loader.exec_module(module)
+                        _RESOURCES = module
+                        break
+        except Exception:  # noqa: BLE001 - a broken probe never breaks the hook
+            _RESOURCES = False
+    return _RESOURCES or None
+
+
+def resource_hint(home):
+    """The one-line memory hint, or None (no pressure, no probe, or any failure)."""
+    module = resources_module()
+    if module is None:
+        return None
+    try:
+        return module.hint(module.probe(home, processes=False, use_cache=True))
+    except Exception:  # noqa: BLE001
+        return None
+
+
+# --- event bus ----------------------------------------------------------------------------
+
+def append_event(home, event):
+    """Append one compact JSON line; rotate the file at MAX_EVENTS_FILE, keeping ROTATED files."""
+    directory = no_follow_dir(events_dir(home))
+    path = directory / "events.jsonl"
+    line = (json.dumps(event, ensure_ascii=False, separators=(",", ":"), sort_keys=True) + "\n").encode("utf-8")
+    try:
+        size = path.stat().st_size if path.exists() else 0
+    except OSError:
+        size = 0
+    if size + len(line) > MAX_EVENTS_FILE:
+        rotate(directory)
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_APPEND | getattr(os, "O_NOFOLLOW", 0), 0o600)
+    try:
+        os.write(fd, line)  # one write per line: concurrent hooks never interleave a line
+    finally:
+        os.close(fd)
+
+
+def rotate(directory):
+    try:
+        import fcntl
+    except ImportError:  # pragma: no cover - POSIX only
+        return
+    lock = os.open(directory / ".rotate.lock", os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0), 0o600)
+    try:
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            return  # another hook is rotating; this line goes to the current file
+        path = directory / "events.jsonl"
+        if not path.exists() or path.stat().st_size <= MAX_EVENTS_FILE // 2:
+            return
+        for index in range(ROTATED, 0, -1):
+            older = directory / ("events.jsonl." + str(index))
+            if index == ROTATED and older.exists():
+                older.unlink()
+            elif older.exists():
+                os.replace(older, directory / ("events.jsonl." + str(index + 1)))
+        os.replace(path, directory / "events.jsonl.1")
+    finally:
+        os.close(lock)
+
+
+def session_key(host, session, cwd):
+    basis = (host or "other") + ":" + (session or ("cwd:" + (cwd or "")))
+    return hashlib.sha256(basis.encode("utf-8")).hexdigest()[:20]
+
+
+def git_branch(cwd):
+    """Branch from .git/HEAD walking up from cwd; no subprocess, so it costs microseconds."""
+    if not cwd:
+        return None
+    path = Path(cwd)
+    for directory in (path, *path.parents):
+        dot = directory / ".git"
+        try:
+            if dot.is_file():
+                text = dot.read_text(encoding="utf-8", errors="replace").strip()
+                if text.startswith("gitdir:"):
+                    gitdir = Path(text[7:].strip())
+                    dot = gitdir if gitdir.is_absolute() else directory / gitdir
+            if dot.is_dir():
+                head = (dot / "HEAD").read_text(encoding="utf-8", errors="replace").strip()
+                if head.startswith("ref: refs/heads/"):
+                    return token(head[16:], 120)
+                return "detached:" + head[:12] if re.fullmatch(r"[0-9a-f]{7,64}", head) else None
+        except OSError:
+            return None
+    return None
+
+
+def update_session(home, event, extra=None, fallback_cwd=None):
+    """Fold one event into the per-session snapshot (state, counters, last action)."""
+    directory = no_follow_dir(events_dir(home) / "sessions")
+    key = session_key(event.get("host"), event.get("session"), event.get("cwd"))
+    path = directory / (key + ".json")
+    try:
+        import fcntl
+    except ImportError:  # pragma: no cover
+        fcntl = None
+    lock = os.open(directory / (key + ".lock"), os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0), 0o600)
+    try:
+        if fcntl:
+            fcntl.flock(lock, fcntl.LOCK_EX)
+        snap = read_json(path) or {}
+        if snap.get("schema") != SESSION_SCHEMA:
+            snap = {"schema": SESSION_SCHEMA, "key": key, "host": event.get("host"), "session": event.get("session"),
+                    "startedAt": event.get("ts") or now_iso(), "state": "idle", "subagents": 0, "shellsStarted": 0, "tools": 0,
+                    "blocked": False}
+        for field in ("cwd", "model", "permissionMode"):
+            if event.get(field):
+                snap[field] = event[field]
+        if not snap.get("cwd") and fallback_cwd:
+            snap["cwd"] = fallback_cwd  # hosts that send no cwd: the hook runs in the session's directory
+        kind = event["event"]
+        if kind in ("session_start", "prompt") and snap.get("cwd"):
+            snap["branch"] = git_branch(snap["cwd"])
+        if kind == "prompt":
+            snap.update(state="working", blocked=False, currentTool=None)
+        elif kind == "tool_start":
+            snap.update(state="working", blocked=False, currentTool=event.get("tool"))
+            snap["tools"] = int(snap.get("tools") or 0) + 1
+            if event.get("background"):
+                snap["shellsStarted"] = int(snap.get("shellsStarted") or 0) + 1
+        elif kind in ("tool_end", "tool_error"):
+            snap.update(currentTool=None, blocked=False)
+            if snap.get("state") == "blocked":
+                snap["state"] = "working"
+        elif kind == "permission_request" or (kind == "notification" and event.get("blocked")):
+            snap.update(state="blocked", blocked=True)
+        elif kind == "subagent_start":
+            snap["subagents"] = int(snap.get("subagents") or 0) + 1
+        elif kind == "subagent_stop":
+            snap["subagents"] = max(0, int(snap.get("subagents") or 0) - 1)
+        elif kind == "stop":
+            snap.update(state="idle", blocked=False, currentTool=None)
+        elif kind in ("error",):
+            snap.update(state="error", blocked=False, currentTool=None)
+        elif kind == "session_end":
+            snap.update(state="ended", blocked=False, currentTool=None, endedAt=event.get("ts") or now_iso(), subagents=0)
+        if kind != "other":
+            snap["lastEvent"] = kind
+            snap["lastAction"] = kind + (":" + event["tool"] if event.get("tool") else "")
+        snap["updatedAt"] = event.get("ts") or now_iso()
+        if extra:
+            snap.update(extra)
+        write_json(path, snap)
+        return snap
+    finally:
+        os.close(lock)
+
+
+def prune_sessions(home, now=None):
+    directory = events_dir(home) / "sessions"
+    if not directory.is_dir() or directory.is_symlink():
+        return
+    now = now or time.time()
+    files = sorted(directory.glob("*.json"), key=lambda p: p.stat().st_mtime)
+    for index, path in enumerate(files):
+        try:
+            if now - path.stat().st_mtime > SESSION_TTL or index < len(files) - MAX_SESSIONS:
+                path.unlink()  # the .lock stays: a hook may hold it; a lock file is empty
+        except OSError:
+            pass
+
+
+def record(home, fields, snapshot=False, fallback_cwd=None):
+    """Stamp and append an event; optionally fold it into the session snapshot."""
+    event = {"v": 1, "schema": EVENT_SCHEMA, "ts": now_iso()}
+    event.update({k: v for k, v in fields.items() if v is not None})
+    append_event(home, event)
+    if snapshot:
+        return event, update_session(home, event, fallback_cwd=fallback_cwd)
+    return event, None
+
+
+def sessions(home, live_only=True, now=None):
+    directory = events_dir(home) / "sessions"
+    result = []
+    if not directory.is_dir() or directory.is_symlink():
+        return result
+    now = now or time.time()
+    for path in directory.glob("*.json"):
+        try:
+            snap = read_json(path)
+            age = now - path.stat().st_mtime
+        except OSError:
+            continue  # pruned meanwhile
+        if not isinstance(snap, dict) or snap.get("schema") != SESSION_SCHEMA:
+            continue
+        if live_only and (age > SESSION_TTL or (snap.get("state") == "ended" and age > 300)):
+            continue
+        snap["ageSeconds"] = int(age)
+        result.append(snap)
+    return sorted(result, key=lambda s: s.get("updatedAt") or "", reverse=True)
+
+
+def tail(home, limit=50):
+    directory = events_dir(home)
+    files = [directory / ("events.jsonl." + str(i)) for i in range(ROTATED, 0, -1)] + [directory / "events.jsonl"]
+    lines = []
+    for path in files:
+        if path.is_file() and not path.is_symlink():
+            with open(path, "rb") as handle:
+                lines.extend(handle.read().splitlines())
+    events = []
+    for raw in lines[-limit:] if limit else lines:
+        try:
+            events.append(json.loads(raw))
+        except ValueError:
+            continue
+    return events
+
+
+# --- host payloads ------------------------------------------------------------------------
+
+def first(payload, *keys):
+    for key in keys:
+        value = payload.get(key)
+        if value not in (None, ""):
+            return value
+    return None
+
+
+def genuine_claude(payload, env, home):
+    """The claude-installed hook is also read by Devin (it imports ~/.claude/settings.json
+    hooks). Run only when the caller really is Claude Code: its transcript lives under
+    ~/.claude/projects (or $CLAUDE_CONFIG_DIR/projects); without a transcript, Claude Code
+    exports CLAUDECODE=1 to every child. Devin-only fields mean Devin."""
+    if "tool_provenance" in payload:
+        return False
+    transcript = payload.get("transcript_path")
+    if isinstance(transcript, str) and transcript:
+        roots = [Path(home) / ".claude" / "projects"]
+        if env.get("CLAUDE_CONFIG_DIR"):
+            roots.append(Path(env["CLAUDE_CONFIG_DIR"]).expanduser() / "projects")
+        real = os.path.abspath(os.path.expanduser(transcript))
+        return any(real.startswith(os.path.abspath(r) + os.sep) for r in roots)
+    return env.get("CLAUDECODE") == "1"
+
+
+def foreign(host, payload, env, home):
+    """True when this installation must stay silent because another CLI is running it."""
+    if host == "claude":
+        return not genuine_claude(payload, env, home)
+    if host == "gemini":
+        return env.get("ANTIGRAVITY_AGENT") == "1"  # agy has its own hooks.json entry
+    return False
+
+
+def normalise(host, raw, payload):
+    kind = EVENTS.get(raw, "other")
+    tool = token(first(payload, "tool_name", "toolName", "tool"), 64)
+    tool_input = payload.get("tool_input") if isinstance(payload.get("tool_input"), dict) else {}
+    event = {
+        "host": host, "event": kind, "raw": token(raw, 40),
+        "session": token(first(payload, "session_id", "sessionId", "conversation_id", "conversationId", "thread_id"), 128),
+        "cwd": plain_path(first(payload, "cwd", "workspace_root", "workspaceRoot")),
+        "model": token(first(payload, "model", "model_name", "modelName"), 80) if not isinstance(payload.get("model"), dict)
+        else token(payload["model"].get("id") or payload["model"].get("display_name"), 80),
+        "permissionMode": token(first(payload, "permission_mode", "permissionMode", "approval_policy", "approvalMode"), 40),
+        "tool": tool if kind in ("tool_start", "tool_end", "tool_error", "permission_request") else None,
+        "agent": token(first(payload, "agent_type", "subagent_type", "agent_name"), 64) if kind.startswith("subagent") else None,
+    }
+    if kind == "tool_start" and tool_input.get("run_in_background") is True:
+        event["background"] = True
+    if kind == "notification":
+        kind_name = str(first(payload, "notification_type", "type") or "")
+        event["blocked"] = kind_name in ("permission_prompt", "permission", "elicitation_dialog", "ToolPermission")
+        event["notification"] = token(kind_name, 40)
+    if kind == "permission_request":
+        event["blocked"] = True
+    return {k: v for k, v in event.items() if v is not None}
+
+
+def process_cwd():
+    try:
+        return plain_path(os.getcwd())
+    except OSError:
+        return None
+
+
+def prompt_text(payload):
+    value = first(payload, "prompt", "user_prompt", "lastUserInput", "last_user_input")
+    return value if isinstance(value, str) else None
+
+
+def output_for(host, raw, context=None, system=None, block=None):
+    """The JSON each host reads from a hook's stdout, or None for no output."""
+    if block is not None:
+        if host == "agy":
+            return {"injectSteps": [{"ephemeralMessage": block + " Responda só confirmando isso em uma linha."}]}
+        return {"decision": "block", "reason": block}
+    if host == "agy":
+        steps = []
+        if context:
+            steps.append({"ephemeralMessage": context})
+        out = {"injectSteps": steps} if steps else {}
+        if system:
+            out["systemMessage"] = system
+        return out or None
+    out = {}
+    if context:
+        out["hookSpecificOutput"] = {"hookEventName": raw, "additionalContext": context}
+    if system:
+        out["systemMessage"] = system
+    return out or None
+
+
+def handle(host, raw, payload, home, env=None):
+    """Process one hook call; returns the JSON to print (or None). Never raises to the caller."""
+    env = os.environ if env is None else env
+    if host not in HOSTS or not isinstance(payload, dict) or foreign(host, payload, env, home):
+        return None
+    event = normalise(host, raw, payload)
+    current = read_mode(home)
+    if raw in PROMPT_EVENTS:
+        text = prompt_text(payload)
+        match = COMMAND.match(text) if text and len(text) < 64 else None
+        if match and host in ("codex", "devin", "agy"):
+            # CLIs without a shell slash command toggle here and block the prompt with the result.
+            wanted = match.group(1).lower()
+            if wanted != "status":
+                current = write_mode(home, wanted, host)
+            record(home, dict(event, event="mode_command", mode=current["mode"]), snapshot=True, fallback_cwd=process_cwd())
+            return output_for(host, raw, block=indicator(current["mode"]) + " (crow-skills; vale para todos os CLIs a partir do próximo prompt)")
+    stamped, snap = record(home, dict(event, mode=current["mode"]), snapshot=True, fallback_cwd=process_cwd())
+    if raw not in PROMPT_EVENTS and raw != "SessionStart":
+        return None
+    system = None
+    seen = (snap or {}).get("modeSeen")
+    stamp = current["mode"] + "@" + str(current["updatedAt"])
+    if host in ("codex", "gemini", "devin") and (raw == "SessionStart" or (seen and seen != stamp)):
+        system = indicator(current["mode"])  # visible line only at start or when the mode changed
+    if snap is not None and seen != stamp:
+        update_session(home, dict(stamped, event="other"), {"modeSeen": stamp, "mode": current["mode"]})
+    if raw == "SessionStart":
+        return output_for(host, raw, system=system) if system else None
+    context = context_line(current["mode"])
+    memory = resource_hint(home)
+    if memory:
+        context += "\n" + memory
+    return output_for(host, raw, context=context, system=system)
+
+
+def update_metrics(home, host, payload):
+    """Status line payloads carry model, cost and usage: keep them in the session snapshot.
+
+    Only numbers and ids are kept; writes happen only when a value changed.
+    """
+    if not isinstance(payload, dict):
+        return
+    session = token(first(payload, "session_id", "sessionId", "conversation_id", "conversationId"), 128)
+    cwd = plain_path(((payload.get("workspace") or {}) if isinstance(payload.get("workspace"), dict) else {}).get("current_dir")
+                     or payload.get("cwd"))
+    metrics = {}
+    model = payload.get("model")
+    if isinstance(model, dict):
+        metrics["model"] = token(model.get("id") or model.get("display_name"), 80)
+    elif model:
+        metrics["model"] = token(model, 80)
+    cost = payload.get("cost")
+    if isinstance(cost, dict):
+        value = cost.get("total_cost_usd", cost.get("totalCostUsd"))
+        if isinstance(value, (int, float)):
+            metrics["costUsd"] = round(float(value), 6)
+    elif isinstance(cost, (int, float)):
+        metrics["costUsd"] = round(float(cost), 6)
+    usage = payload.get("usage") if isinstance(payload.get("usage"), dict) else (payload.get("context_window") or {})
+    if isinstance(usage, dict):
+        numbers = {k: int(v) for k, v in usage.items() if isinstance(v, (int, float)) and not isinstance(v, bool) and len(k) < 40}
+        if numbers:
+            metrics["usage"] = numbers
+    metrics = {k: v for k, v in metrics.items() if v is not None}
+    if not metrics or not (session or cwd):
+        return
+    path = events_dir(home) / "sessions" / (session_key(host, session, cwd) + ".json")
+    snap = read_json(path) or {}
+    if all(snap.get(k) == v for k, v in metrics.items()):
+        return
+    update_session(home, {"host": host, "session": session, "cwd": cwd, "event": "other", "ts": now_iso()}, metrics)
+
+
+# --- entry point --------------------------------------------------------------------------
+
+def main(argv=None):
+    import argparse
+    p = argparse.ArgumentParser(prog="crow_hook", description="Hook e modo do crow-skills.")
+    sub = p.add_subparsers(dest="command", required=True)
+    hook = sub.add_parser("hook")
+    hook.add_argument("--host", required=True)
+    hook.add_argument("--event", required=True)
+    hook.add_argument("--home")
+    mode = sub.add_parser("mode")
+    mode.add_argument("action", nargs="?", default="status", choices=("on", "off", "status", "toggle"))
+    mode.add_argument("--home")
+    mode.add_argument("--by")
+    mode.add_argument("--json", action="store_true")
+    args = p.parse_args(argv)
+    home = Path(args.home).expanduser() if args.home else Path.home()
+    if args.command == "mode":
+        current = read_mode(home)
+        try:
+            if args.action in MODES:
+                current = write_mode(home, args.action, args.by)
+            elif args.action == "toggle":
+                current = write_mode(home, "off" if current["mode"] == "on" else "on", args.by)
+        except OSError:
+            print("crow: não foi possível gravar " + str(mode_path(home)) + "; modo mantido: " + current["mode"])
+            return 1
+        print(json.dumps(current, ensure_ascii=False) if args.json else indicator(current["mode"]) +
+              " (vale para todos os CLIs a partir do próximo prompt)")
+        return 0
+    try:
+        raw = sys.stdin.buffer.read(MAX_STDIN + 1) if not sys.stdin.isatty() else b""
+        payload = json.loads(raw.decode("utf-8")) if raw.strip() and len(raw) <= MAX_STDIN else {}
+        result = handle(args.host, args.event, payload, home)
+        if args.event == "SessionStart":
+            prune_sessions(home)
+        if result:
+            sys.stdout.write(json.dumps(result, ensure_ascii=False) + "\n")
+    except Exception:  # noqa: BLE001 - a hook must never break the agent
+        return 0
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())