@andespindola/crow-skills 0.9.0 → 0.10.0

package/crow_skills/cli.py

@@ -7,6 +7,7 @@ import sys
 
 from . import __version__
 from . import autoupdate
+from . import broadcast
 from . import events
 from . import guide
 from . import hook
@@ -78,6 +79,20 @@ def parser():
     child.add_argument("action", nargs="?", default="snapshot", choices=("snapshot", "tail"))
     child.add_argument("--limit", type=int, default=50, help="tail: quantos eventos (padrão 50; 0 = todos os retidos)")
     child.add_argument("--follow", action="store_true", help="tail: transmitir eventos novos em JSONL até Ctrl-C")
+    child = sub.add_parser("broadcast", parents=[common],
+                           help="crow-broadcast: sessões vivas dos CLIs, arquivos em edição, conflitos e reservas")
+    child.add_argument("action", nargs="?", default="status", choices=("status", "list", "claim", "release", "watch"))
+    child.add_argument("targets", nargs="*", help="claim: caminhos, globs ou área; release: ids das reservas")
+    child.add_argument("--ttl", default="30m", help="claim: validade (ex.: 30m, 2h; máximo 24h)")
+    child.add_argument("--note", help="claim: nota curta (o que será feito)")
+    child.add_argument("--session", help="claim/release/status: id da sessão dona; padrão: detectada pelo processo pai")
+    child.add_argument("--host", help="claim/release/status: CLI da sessão (claude, codex, gemini, agy, devin)")
+    child.add_argument("--cwd", help="Diretório de referência; padrão: o atual")
+    child.add_argument("--force", action="store_true",
+                       help="claim: registrar mesmo com reserva conflitante; release: liberar reserva de outra sessão (decisão do usuário)")
+    child.add_argument("--all", action="store_true", help="release: todas as reservas desta sessão")
+    child.add_argument("--interval", type=float, default=2.0, help=argparse.SUPPRESS)
+    child.add_argument("--max-frames", type=int, default=None, help=argparse.SUPPRESS)
     child = sub.add_parser("resources", parents=[common],
                            help="Memória, pressão, agentes em execução e paralelismo recomendado (somente leitura)")
     child.add_argument("--no-processes", action="store_true", help="Não varrer os processos dos CLIs de agente (mais rápido)")
@@ -361,6 +376,146 @@ def events_command(args, home, store):
     return data
 
 
+def ancestors(limit=16):
+    """Process ids above this CLI (best effort): the agent CLI that runs it is one of them."""
+    pids, pid = [], os.getpid()
+    for _ in range(limit):
+        parent = None
+        try:
+            with open("/proc/" + str(pid) + "/stat", "rb") as handle:
+                parent = int(handle.read().rsplit(b")", 1)[1].split()[1])
+        except (OSError, ValueError, IndexError):
+            try:
+                import subprocess
+                done = subprocess.run(["ps", "-o", "ppid=", "-p", str(pid)], capture_output=True, text=True, timeout=2)
+                parent = int(done.stdout.strip() or 0)
+            except (OSError, ValueError, subprocess.SubprocessError):
+                parent = None
+        if not parent or parent <= 1 or parent in pids:
+            break
+        pids.append(parent)
+        pid = parent
+    return pids
+
+
+def broadcast_owner(args, home, cwd):
+    """The session that runs this command: --session/--host, else the live session whose CLI pid is an ancestor."""
+    live = broadcast.live_sessions(home)
+    host = getattr(args, "host", None)
+    if host and host not in hook.HOSTS:
+        raise CrowError("usage", "--host deve ser um de: " + ", ".join(hook.HOSTS))
+    if getattr(args, "session", None):
+        session = hook.token(args.session, 128)
+        matches = [s for s in live if s.get("session") == session and (not host or s.get("host") == host)]
+        if matches:
+            s = matches[0]
+            return {"key": s["key"], "host": s.get("host"), "session": s.get("session"), "detected": "session"}
+        if not host:
+            raise CrowError("not_found", "Sessão " + str(session) + " não está viva no broadcast; informe também --host.")
+        return {"key": broadcast.session_key(host, session, None), "host": host, "session": session, "detected": "session"}
+    chain = ancestors()
+    for s in live:
+        pid = broadcast.presence_of(s).get("pid")
+        if pid and pid in chain and (not host or s.get("host") == host):
+            return {"key": s["key"], "host": s.get("host"), "session": s.get("session"), "detected": "pid"}
+    return None
+
+
+def broadcast_text(view, full=False):
+    me = view.get("me") or {}
+    repo = me.get("repo") or {}
+    lines = ["crow-broadcast · " + str(len(view["sessions"])) + " outra(s) sessão(ões) viva(s) · " + str(len(view["claims"])) +
+             " reserva(s)"]
+    if me:
+        lines.append("aqui: " + (repo.get("remote") or repo.get("root") or me.get("cwd") or "?") +
+                     (" · branch " + str(me.get("branch")) if me.get("branch") else "") +
+                     (" · sessão " + str(view.get("owner", {}).get("host")) if view.get("owner") else ""))
+    shown = view["sessions"] if full else broadcast.relevant(view)
+    now = broadcast.parse_time(view["generatedAt"]) or 0
+    for s in shown:
+        lines += broadcast.session_lines(s, view["_home"], now)
+    if not full and len(shown) < len(view["sessions"]):
+        lines.append("(+" + str(len(view["sessions"]) - len(shown)) + " em outros repositórios; crow-skills broadcast list)")
+    live = {s.get("key"): s for s in view["_live"]}
+    for claim in view["claims"]:
+        lines.append(broadcast.claim_line(claim, live, now))
+    if not shown and not view["claims"]:
+        lines.append("Nenhuma outra sessão viva neste repositório." if not full else "Nenhuma outra sessão viva.")
+    return "\n".join(lines)
+
+
+def broadcast_view(args, home, owner=None):
+    cwd = os.path.abspath(getattr(args, "cwd", None) or os.getcwd())
+    owner = owner if owner is not None else broadcast_owner(args, home, cwd)
+    me_key = owner["key"] if owner else None
+    view = broadcast.overview(home, me_key, cwd=cwd)
+    if view["me"] is not None and view["me"].get("cwd") is None:
+        view["me"]["cwd"] = cwd
+    view["owner"] = owner
+    return view
+
+
+def public(view):
+    return {k: v for k, v in view.items() if not k.startswith("_")}
+
+
+def broadcast_command(args, home):
+    action = args.action
+    cwd = os.path.abspath(getattr(args, "cwd", None) or os.getcwd())
+    if action in ("status", "list"):
+        view = broadcast_view(args, home)
+        view["_home"] = home
+        text = broadcast_text(view, full=action == "list")
+        data = public(view)
+        if action == "status":
+            data["relevant"] = [s["key"] for s in broadcast.relevant(view)]
+        data["text"] = text
+        return data
+    if action == "watch":
+        if getattr(args, "json", False):
+            raise CrowError("usage", "watch redesenha em texto; para JSON use status --json em polling.")
+        frames = 0
+        try:
+            while True:
+                view = broadcast_view(args, home)
+                view["_home"] = home
+                sys.stdout.write("\x1b[H\x1b[2J" + broadcast_text(view) + "\n")
+                sys.stdout.flush()
+                frames += 1
+                if args.max_frames is not None and frames >= args.max_frames:
+                    return None
+                import time as _time
+                _time.sleep(max(0.2, args.interval))
+        except KeyboardInterrupt:
+            return None
+    owner = broadcast_owner(args, home, cwd)
+    if action == "claim":
+        if not args.targets:
+            raise CrowError("usage", "Informe o que reservar: caminhos, globs ou área (ex.: crow-skills broadcast claim src/api --ttl 30m).")
+        try:
+            ttl = broadcast.parse_ttl(args.ttl)
+        except ValueError:
+            raise CrowError("usage", "--ttl inválido: use 30m, 2h, 90s (máximo 24h).") from None
+        try:
+            claim, conflicts = broadcast.add_claim(home, args.targets, ttl, owner=owner, cwd=cwd, note=args.note, force=args.force)
+        except ValueError:
+            raise CrowError("usage", "Nenhum alvo válido para reservar.") from None
+        if claim is None:
+            holders = "; ".join(broadcast.claim_line(c, {}, broadcast.time.time()).lstrip("- ") for c in conflicts[:3])
+            raise CrowError("claim_conflict", "Área já reservada por outra sessão viva: " + holders +
+                            ". Coordene com ela ou use --force se o usuário decidir seguir.")
+        return {"claim": claim, "owner": owner, "conflicts": conflicts,
+                "note": None if owner else "Sessão dona não detectada; a reserva expira só pelo TTL. Use --session/--host."}
+    if not owner and (args.all or not args.targets):
+        raise CrowError("usage", "Sessão dona não detectada: informe --session/--host (ou os ids das reservas).")
+    removed, refused = broadcast.release_claims(home, ids=set(args.targets), owner_key=owner["key"] if owner else None,
+                                                everything=args.all or not args.targets, force=args.force)
+    if refused and not removed:
+        raise CrowError("claim_owner", "Reserva(s) de outra sessão: " + ", ".join(refused) +
+                        ". Só a sessão dona libera; --force só por decisão do usuário.")
+    return {"released": [c["id"] for c in removed], "refused": refused, "owner": owner}
+
+
 def autoupdate_command(args, home, store, interactive):
     if args.action == "status":
         return autoupdate.status(store, home)
@@ -464,6 +619,8 @@ def run(args):
         return mode_command(args, home)
     if args.command == "events":
         return events_command(args, home, store)
+    if args.command == "broadcast":
+        return broadcast_command(args, home)
     if args.command == "resources":
         data = resources.probe(home, processes=not args.no_processes)
         data["text"] = resources.render(data)
@@ -596,6 +753,15 @@ def emit(command, data, machine):
             print(data["text"] or "crow: nenhuma execução registrada neste diretório.")
     elif command == "resources":
         print(data["text"])
+    elif command == "broadcast":
+        if data is not None:
+            if "text" in data:
+                print(data["text"])
+            elif "claim" in data:
+                print("reserva " + data["claim"]["id"] + ": " + ", ".join(data["claim"]["patterns"]) + " até " +
+                      data["claim"]["expiresAt"] + ("" if data["owner"] else " (" + data["note"] + ")"))
+            else:
+                print("liberadas: " + (", ".join(data["released"]) or "nenhuma"))
     elif command == "mode":
         print(data["indicator"] + " — " + data["applies"])
     elif command == "events":

package/crow_skills/events.py

@@ -11,7 +11,7 @@ import json
 import sys
 import time
 
-from . import autoupdate, hook, progress, resources
+from . import autoupdate, broadcast, hook, progress, resources
 from .source import CrowError
 
 SNAPSHOT_SCHEMA = "crow-snapshot/1"
@@ -58,9 +58,42 @@ def snapshot(home, store):
         machine = resources_field(home)
     except Exception:  # noqa: BLE001 - the snapshot never fails because of the probe
         machine = None
+    try:
+        presence = broadcast_field(home)
+    except Exception:  # noqa: BLE001 - the snapshot never fails because of the broadcast
+        presence = None
     return {"schema": SNAPSHOT_SCHEMA, "generatedAt": datetime.now(timezone.utc).isoformat(timespec="seconds"),
             "mode": {k: mode[k] for k in ("mode", "updatedAt", "updatedBy", "source")}, "indicator": hook.indicator(mode["mode"]),
-            "sessions": live, "runs": runs, "autoupdate": update, "resources": machine}
+            "sessions": live, "runs": runs, "autoupdate": update, "resources": machine, "broadcast": presence}
+
+
+def broadcast_field(home):
+    """crow-broadcast/1 for terminals: live sessions grouped by repository, recent files, claims, conflicts.
+
+    Added in 0.10.0 without changing crow-snapshot/1 (consumers ignore unknown fields); the
+    field carries its own schema. ``conflicts`` lists files touched by two or more live
+    sessions within the conflict window and clones used by two or more live sessions.
+    """
+    view = broadcast.overview(home)
+    window = view["config"]["conflict_window_minutes"] * 60
+    now = broadcast.parse_time(view["generatedAt"]) or 0
+    repos, files, clones = {}, {}, {}
+    for s in view["sessions"]:
+        repo = s.get("repo") or {}
+        if repo.get("id"):
+            repos.setdefault(repo["id"], {"id": repo["id"], "remote": repo.get("remote"), "sessions": []})["sessions"].append(s["key"])
+            clones.setdefault(repo.get("root"), []).append(s["key"])
+        for f in s["files"]:
+            if now - (broadcast.parse_time(f.get("ts")) or 0) <= window:
+                label = (f.get("repo") + ":" + f["rel"]) if f.get("repo") and f.get("rel") else f["path"]
+                keys = files.setdefault(label, [])
+                if s["key"] not in keys:
+                    keys.append(s["key"])
+    conflicts = [{"kind": "file", "file": k, "sessions": v} for k, v in files.items() if len(v) > 1] + \
+                [{"kind": "clone", "root": k, "sessions": v} for k, v in clones.items() if k and len(v) > 1]
+    return {"schema": view["schema"], "generatedAt": view["generatedAt"], "config": view["config"],
+            "sessions": [{k: v for k, v in s.items() if k != "relation"} for s in view["sessions"]],
+            "repos": list(repos.values()), "claims": view["claims"], "conflicts": conflicts}
 
 
 def resources_field(home):
@@ -97,6 +130,12 @@ def render(data, unicode=True):
         lines.append("")
         lines.append("memória: " + (machine["segment"] or "") + " · pressão " + machine["pressure"]["level"] + " · " + rec["mode"] +
                      " (até " + str(rec["maxParallelAgents"]) + " agente(s), " + str(rec["maxParallelHeavyJobs"]) + " job(s) pesado(s))")
+    shared = data.get("broadcast")
+    if shared and (shared.get("conflicts") or shared.get("claims")):
+        lines.append("")
+        lines.append("broadcast: " + str(len([c for c in shared["conflicts"] if c["kind"] == "file"])) + " arquivo(s) em mais de uma sessão · " +
+                     str(len([c for c in shared["conflicts"] if c["kind"] == "clone"])) + " clone(s) compartilhado(s) · " +
+                     str(len(shared["claims"])) + " reserva(s) (crow-skills broadcast list)")
     lines.append("")
     lines.append("autoupdate: " + ("ligado" if update.get("enabled") else "desligado") +
                  ((" · última execução " + str(update["lastRun"]["startedAt"]) + (" ok" if update["lastRun"]["ok"] else " com falha"))

package/crow_skills/hook.py

@@ -18,6 +18,15 @@ 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).
+
+crow-broadcast (crow_broadcast.py, copied beside this file): every event also
+keeps the session's presence (git repository, CLI pid, PATHS of files its edit
+tools target) in the snapshot; a prompt event appends a short digest of other
+live sessions in the same repository, only when there are any; ``--check``
+(a synchronous PreToolUse entry for edit and shell tools) warns about another
+live session on the same file or clone without writing anything.
+
+  crow_hook.py hook --host HOST --event PreToolUse --check [--home DIR]
 """
 from datetime import datetime, timezone
 import hashlib
@@ -193,6 +202,34 @@ def resources_module():
     return _RESOURCES or None
 
 
+_BROADCAST = None
+
+
+def broadcast_module():
+    """crow-broadcast: the package module, or crow_broadcast.py beside this file; None when missing."""
+    global _BROADCAST
+    if _BROADCAST is None:
+        _BROADCAST = False
+        try:
+            if __package__:
+                from . import broadcast as module  # type: ignore[attr-defined]
+                _BROADCAST = module
+            else:
+                import importlib.util
+                here = Path(os.path.abspath(__file__)).parent
+                for name in ("crow_broadcast.py", "broadcast.py"):
+                    path = here / name
+                    if path.is_file() and not path.is_symlink():
+                        spec = importlib.util.spec_from_file_location("crow_broadcast", path)
+                        module = importlib.util.module_from_spec(spec)
+                        spec.loader.exec_module(module)
+                        _BROADCAST = module
+                        break
+        except Exception:  # noqa: BLE001 - a broken module never breaks the hook
+            _BROADCAST = False
+    return _BROADCAST or None
+
+
 def resource_hint(home):
     """The one-line memory hint, or None (no pressure, no probe, or any failure)."""
     module = resources_module()
@@ -277,8 +314,11 @@ def git_branch(cwd):
     return None
 
 
-def update_session(home, event, extra=None, fallback_cwd=None):
-    """Fold one event into the per-session snapshot (state, counters, last action)."""
+def update_session(home, event, extra=None, fallback_cwd=None, presence=None):
+    """Fold one event into the per-session snapshot (state, counters, last action).
+
+    presence: (broadcast module, touched paths, parent pid) to fold the crow-broadcast
+    presence in the same locked write; a failure there never loses the event."""
     directory = no_follow_dir(events_dir(home) / "sessions")
     key = session_key(event.get("host"), event.get("session"), event.get("cwd"))
     path = directory / (key + ".json")
@@ -332,6 +372,12 @@ def update_session(home, event, extra=None, fallback_cwd=None):
         snap["updatedAt"] = event.get("ts") or now_iso()
         if extra:
             snap.update(extra)
+        if presence:
+            module, touched, ppid = presence
+            try:
+                module.fold(snap, event, touched, ppid=ppid)
+            except Exception:  # noqa: BLE001 - presence is best effort
+                pass
         write_json(path, snap)
         return snap
     finally:
@@ -352,13 +398,13 @@ def prune_sessions(home, now=None):
             pass
 
 
-def record(home, fields, snapshot=False, fallback_cwd=None):
+def record(home, fields, snapshot=False, fallback_cwd=None, presence=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, update_session(home, event, fallback_cwd=fallback_cwd, presence=presence)
     return event, None
 
 
@@ -380,7 +426,7 @@ def sessions(home, live_only=True, now=None):
             continue
         snap["ageSeconds"] = int(age)
         result.append(snap)
-    return sorted(result, key=lambda s: s.get("updatedAt") or "", reverse=True)
+    return sorted(result, key=lambda s: str(s.get("updatedAt") or ""), reverse=True)
 
 
 def tail(home, limit=50):
@@ -436,14 +482,26 @@ def foreign(host, payload, env, home):
     return False
 
 
+def tool_call(payload):
+    """Antigravity sends the tool as {"toolCall": {"name", "args"}}."""
+    call = payload.get("toolCall")
+    return call if isinstance(call, dict) else {}
+
+
+def workspace(payload):
+    """Antigravity runs hooks from the hooks.json directory and sends the workspace as workspacePaths."""
+    paths = payload.get("workspacePaths")
+    return paths[0] if isinstance(paths, list) and paths and isinstance(paths[0], str) else None
+
+
 def normalise(host, raw, payload):
     kind = EVENTS.get(raw, "other")
-    tool = token(first(payload, "tool_name", "toolName", "tool"), 64)
+    tool = token(first(payload, "tool_name", "toolName", "tool") or tool_call(payload).get("name"), 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")),
+        "cwd": plain_path(first(payload, "cwd", "workspace_root", "workspaceRoot") or workspace(payload)),
         "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),
@@ -495,11 +553,107 @@ def output_for(host, raw, context=None, system=None, block=None):
     return out or None
 
 
-def handle(host, raw, payload, home, env=None):
+TOOL_START_EVENTS = ("PreToolUse", "BeforeTool")
+SHELL_NAMES = frozenset(("Bash", "shell", "exec_command", "local_shell", "run_shell_command", "run_command", "exec", "bash"))
+# Edit and shell tool names of every host (crow_broadcast.EDIT_TOOLS and SHELL_TOOLS; a test keeps
+# them equal): only these tool events load the broadcast module.
+BROADCAST_TOOLS = frozenset((
+    "Edit", "Write", "MultiEdit", "NotebookEdit", "apply_patch", "write_file", "replace", "code_action", "file_change",
+    "propose_code", "edit_notebook", "write_blob", "write_to_file", "replace_file_content", "multi_replace_file_content",
+    "edit", "write", "notebook_edit",
+    "Bash", "shell", "exec_command", "local_shell", "run_shell_command", "run_command", "exec", "bash"))
+# Hosts whose tool-start hook is synchronous in our install (its output is read): the warning goes
+# out from the same call. Claude Code and Codex record asynchronously and get a separate --check entry.
+SYNC_TOOL_HOSTS = ("gemini", "agy", "devin")
+
+
+def tool_input_of(payload):
+    args = tool_call(payload).get("args")
+    if isinstance(args, dict):
+        return args
+    for key in ("tool_input", "toolInput", "input", "tool_args", "arguments", "args"):
+        value = payload.get(key)
+        if isinstance(value, dict):
+            return value
+        if isinstance(value, str) and key in ("arguments", "tool_input") and value[:1] == "{" and len(value) < MAX_STDIN:
+            try:
+                parsed = json.loads(value)
+            except ValueError:
+                continue
+            if isinstance(parsed, dict):
+                return parsed
+    return {}
+
+
+# Where a warning can reach the model before/after a tool, per host (checked on the installed
+# versions, see docs/broadcast.md): Claude Code and Codex read additionalContext on PreToolUse;
+# Gemini CLI and Devin only on AfterTool/PostToolUse (their pre-tool hook can only block);
+# Antigravity's PreToolUse reads only a decision (the next PreInvocation digest carries the warning).
+PRE_CONTEXT_HOSTS = ("claude", "codex")
+POST_CONTEXT_HOSTS = ("gemini", "devin")
+POST_TOOL_EVENTS = ("PostToolUse", "AfterTool")
+
+
+def tool_output(host, raw, text, block=False):
+    """Tool-hook warning (model-visible where the host reads it) or, with block, a refusal."""
+    if block:
+        if host == "claude":
+            return {"hookSpecificOutput": {"hookEventName": raw, "permissionDecision": "deny", "permissionDecisionReason": text,
+                                           "additionalContext": text}}
+        if host in ("agy", "gemini"):
+            return {"decision": "deny", "reason": text}
+        return {"decision": "block", "reason": text}
+    if raw in TOOL_START_EVENTS and host not in PRE_CONTEXT_HOSTS:
+        return None
+    return {"hookSpecificOutput": {"hookEventName": raw, "additionalContext": text}, "systemMessage": text.split("\n", 1)[0]}
+
+
+def broadcast_check(host, raw, home, module, me, touched, tree):
+    """Run the conflict check; returns the host output or None. Never raises."""
+    try:
+        cfg = module.config(home)
+        pre = raw in TOOL_START_EVENTS
+        block = pre and bool(cfg["block_on_conflict"])
+        if pre and not block and host not in PRE_CONTEXT_HOSTS:
+            return None  # nothing this host would show before the tool; the post-tool or prompt hook warns
+        text, conflict = module.check(home, (me or {}).get("key"), me, touched, tree, cfg=cfg)
+        if not text:
+            return None
+        return tool_output(host, raw, text, block=block and conflict)
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def check_only(host, raw, payload, home):
+    """--check: read-only conflict check before an edit/shell tool (no event, no snapshot write)."""
+    tool = first(payload, "tool_name", "toolName", "tool") or tool_call(payload).get("name")
+    shell_input = tool_input_of(payload)
+    command = shell_input.get("command") or shell_input.get("cmd") or shell_input.get("CommandLine") or shell_input.get("commandLine")
+    if tool in SHELL_NAMES and "git" not in json.dumps(command or ""):
+        return None  # a shell command without git cannot switch the clone's branch: nothing to load
+    module = broadcast_module()
+    if module is None or raw not in TOOL_START_EVENTS:
+        return None
+    event = normalise(host, raw, payload)
+    cwd = event.get("cwd") or process_cwd()
+    tool_input = tool_input_of(payload)
+    touched = module.edit_paths(host, event.get("tool"), tool_input, cwd)
+    tree = module.tree_command(host, event.get("tool"), tool_input, cwd)
+    if not touched and not tree:
+        return None
+    key = session_key(host, event.get("session"), event.get("cwd"))
+    me = read_json(events_dir(home) / "sessions" / (key + ".json")) or {}
+    me = dict(me, key=key, cwd=me.get("cwd") or cwd)
+    return broadcast_check(host, raw, home, module, me, touched, tree)
+
+
+def handle(host, raw, payload, home, env=None, check=False):
     """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
+    if check:
+        return check_only(host, raw, payload, home)
     event = normalise(host, raw, payload)
     current = read_mode(home)
     if raw in PROMPT_EVENTS:
@@ -512,7 +666,49 @@ def handle(host, raw, payload, home, env=None):
                 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())
+    # The broadcast module is loaded only where it has work: prompts and session start (repo,
+    # pid, digest) and tool events of edit/shell tools (paths, checks). Other events keep the
+    # 0.9.0 cost; the snapshot's updatedAt is the heartbeat.
+    wanted = raw in PROMPT_EVENTS or raw == "SessionStart" or \
+        (event["event"] in ("tool_start", "tool_end") and event.get("tool") in BROADCAST_TOOLS)
+    module, presence, touched, tree, checked = broadcast_module() if wanted else None, None, [], [], []
+    if module is not None:
+        try:
+            cfg = module.config(home)
+            if cfg["enabled"]:
+                if event["event"] == "tool_start":
+                    tool_input = tool_input_of(payload)
+                    cwd = event.get("cwd") or process_cwd()
+                    touched = module.edit_paths(host, event.get("tool"), tool_input, cwd)
+                    checked = list(touched)
+                    tree = module.tree_command(host, event.get("tool"), tool_input, cwd)
+                    if touched and cfg["block_on_conflict"]:
+                        # An edit the conflict check is about to refuse is not published as this
+                        # session's: otherwise the session that edited first would be locked out too.
+                        key = session_key(host, event.get("session"), event.get("cwd"))
+                        mine = read_json(events_dir(home) / "sessions" / (key + ".json")) or {}
+                        mine = dict(mine, key=key, cwd=mine.get("cwd") or cwd)
+                        if module.check(home, key, mine, touched, (), cfg=cfg)[1]:
+                            touched = []
+                presence = (module, touched, os.getppid())
+            else:
+                module = None
+        except Exception:  # noqa: BLE001 - the broadcast never breaks the event
+            module, presence = None, None
+    stamped, snap = record(home, dict(event, mode=current["mode"]), snapshot=True, fallback_cwd=process_cwd(), presence=presence)
+    if module is not None and host in SYNC_TOOL_HOSTS:
+        if raw in TOOL_START_EVENTS and (touched or tree or checked):
+            return broadcast_check(host, raw, home, module, snap, checked or touched, tree)
+        if raw in POST_TOOL_EVENTS and host in POST_CONTEXT_HOSTS:
+            try:
+                tool_input = tool_input_of(payload)
+                cwd = event.get("cwd") or process_cwd()
+                after = module.edit_paths(host, event.get("tool"), tool_input, cwd)
+                tree_after = module.tree_command(host, event.get("tool"), tool_input, cwd)
+            except Exception:  # noqa: BLE001
+                after, tree_after = [], []
+            if after or tree_after:
+                return broadcast_check(host, raw, home, module, snap, after, tree_after)
     if raw not in PROMPT_EVENTS and raw != "SessionStart":
         return None
     system = None
@@ -528,6 +724,13 @@ def handle(host, raw, payload, home, env=None):
     memory = resource_hint(home)
     if memory:
         context += "\n" + memory
+    if module is not None and snap is not None:
+        try:
+            others = module.digest(home, snap.get("key"), me=snap)
+        except Exception:  # noqa: BLE001
+            others = None
+        if others:
+            context += "\n" + others
     return output_for(host, raw, context=context, system=system)
 
 
@@ -571,7 +774,36 @@ def update_metrics(home, host, payload):
 
 # --- entry point --------------------------------------------------------------------------
 
+def fast_hook_args(argv):
+    """The hook's own argv parsed without argparse (~5 ms per call); None when it is anything else."""
+    if not argv or argv[0] != "hook":
+        return None
+    values, flags, i = {}, set(), 1
+    while i < len(argv):
+        name = argv[i]
+        if name in ("--host", "--event", "--home") and i + 1 < len(argv):
+            values[name[2:]] = argv[i + 1]
+            i += 2
+        elif name == "--check":
+            flags.add("check")
+            i += 1
+        else:
+            return None
+    if "host" not in values or "event" not in values:
+        return None
+    import types
+    return types.SimpleNamespace(command="hook", host=values["host"], event=values["event"], home=values.get("home"),
+                                 check="check" in flags)
+
+
 def main(argv=None):
+    args = fast_hook_args(list(sys.argv[1:] if argv is None else argv))
+    if args is None:
+        args = parse_args(argv)
+    return run_main(args)
+
+
+def parse_args(argv):
     import argparse
     p = argparse.ArgumentParser(prog="crow_hook", description="Hook e modo do crow-skills.")
     sub = p.add_subparsers(dest="command", required=True)
@@ -579,12 +811,16 @@ def main(argv=None):
     hook.add_argument("--host", required=True)
     hook.add_argument("--event", required=True)
     hook.add_argument("--home")
+    hook.add_argument("--check", action="store_true")
     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)
+    return p.parse_args(argv)
+
+
+def run_main(args):
     home = Path(args.home).expanduser() if args.home else Path.home()
     if args.command == "mode":
         current = read_mode(home)
@@ -602,11 +838,18 @@ def main(argv=None):
     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)
+        result = handle(args.host, args.event, payload, home, check=args.check)
         if result:
             sys.stdout.write(json.dumps(result, ensure_ascii=False) + "\n")
+            sys.stdout.flush()
+        if args.event == "SessionStart" and not args.check:
+            prune_sessions(home)
+            module = broadcast_module()
+            if module is not None:
+                try:
+                    module.prune_claims(home)
+                except Exception:  # noqa: BLE001 - pruning is housekeeping; the output already went out
+                    pass
     except Exception:  # noqa: BLE001 - a hook must never break the agent
         return 0
     return 0