@andespindola/crow-skills 0.9.0 → 0.10.1

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