@andespindola/crow-skills 0.7.0 → 0.8.0

package/crow_skills/progress.py

@@ -31,6 +31,20 @@ MAX_LEDGER = 2 * 1024 * 1024
 MAX_LOG_LINE = 8 * 1024 * 1024
 RECENT_DONE = 300  # seconds a finished run stays visible in compact views
 STALE = 2 * 3600  # a "running" ledger untouched for this long is treated as abandoned
+MAX_AGENT_ROWS = 6  # process rows shown in a status line before "+N"
+
+
+def hook_module():
+    """The mode/event helpers: the package module, or crow_hook.py copied beside this script."""
+    try:
+        from . import hook  # type: ignore[attr-defined]
+        return hook
+    except ImportError:
+        try:
+            import crow_hook as hook  # sibling copy in the integrations directory
+            return hook
+        except ImportError:
+            return None
 
 
 # --- ledger -------------------------------------------------------------------------
@@ -501,6 +515,7 @@ def render(run, usage=None, now=None, color=False, unicode=True, width=20):
              bar(info["progress"], width, unicode) + " " + str(int(info["progress"] * 100)).rjust(3) + "%  " +
              str(info["done"]) + "/" + str(info["total"]) + " unidades" +
              (" - " + str(info["failed"]) + " falha(s)" if info["failed"] else "") + "  " + token_text(usage, unicode)]
+    lines += ["", *agent_rows(run, unicode, counts=False), ""]
     phase_ids = [p["id"] for p in run["phases"]]
     groups = [(p, [u for u in run["units"] if u["phase"] == p["id"]]) for p in run["phases"]]
     loose = [u for u in run["units"] if u["phase"] not in phase_ids]
@@ -527,6 +542,50 @@ def render(run, usage=None, now=None, color=False, unicode=True, width=20):
     return "\n".join(lines)
 
 
+def owner_label(owner):
+    """subagent:leitor -> leitor; workflow:x and sequential stay as written."""
+    owner = owner or "main"
+    return owner.split(":", 1)[1] if owner.startswith("subagent:") and owner[9:] else owner
+
+
+def agent_rows(run, unicode=True, limit=None, counts=True):
+    """Live process list, like the host's own agent list:
+
+        ● main  <what the coordinator is doing>
+        ○ <owner>  <running unit>
+        ✓ 3 concluídas · ✗ 1 falhou · 2 pendentes
+
+    Rows come only from the ledger (units the coordinator recorded); nothing is invented.
+    """
+    dot, ring = ("●", "○") if unicode else ("*", "o")
+    sep = " · " if unicode else " - "
+    running = [u for u in run["units"] if u["status"] == "running"]
+    mine = [u for u in running if owner_label(u["owner"]) in ("main", "sequential")]
+    others = [u for u in running if u not in mine]
+    head = dot + " main"
+    if mine:
+        head += "  " + safe(mine[0]["title"], 60) + (" (+" + str(len(mine) - 1) + ")" if len(mine) > 1 else "")
+    elif run["status"] == "running":
+        head += "  " + safe(run["title"], 60)
+    lines = [head]
+    shown = others if limit is None else others[:limit]
+    for unit in shown:
+        lines.append(ring + " " + safe(owner_label(unit["owner"]), 32) + "  " + safe(unit["title"], 60))
+    if limit is not None and len(others) > limit:
+        lines.append(ring + " +" + str(len(others) - limit))
+    if counts:
+        done = sum(u["status"] == "done" for u in run["units"])
+        failed = sum(u["status"] == "failed" for u in run["units"])
+        pending = sum(u["status"] == "pending" for u in run["units"])
+        parts = [("✓ " if unicode else "ok ") + str(done) + " concluída(s)"]
+        if failed:
+            parts.append(("✗ " if unicode else "x ") + str(failed) + " falha(s)")
+        if pending:
+            parts.append(str(pending) + " pendente(s)")
+        lines.append(sep.join(parts))
+    return lines
+
+
 def compact(run, usage=None, unicode=True, width=10):
     info = summary(run)
     mark = "✓" if run["status"] == "done" else ("✗" if run["status"] in ("failed", "cancelled") else "▸")
@@ -580,19 +639,41 @@ def watch(cwd, home, run_id=None, interval=1.0, stream=None, linger=5.0, max_fra
         return 0
 
 
-def statusline(home, stdin_text, chain=None):
-    """Claude Code statusLine: one line; the previous status line (if chained) comes first."""
+def mode_text(home, unicode=True):
+    hook = hook_module()
+    if hook is None:
+        return ""
+    try:
+        return hook.indicator(hook.read_mode(home)["mode"], unicode)
+    except (OSError, ValueError, KeyError):
+        return ""
+
+
+def statusline(home, stdin_text, chain=None, host="claude"):
+    """Status line for Claude Code and Antigravity (agy).
+
+    First line: the previous (chained) status line, the mode indicator and the compact
+    run; then one row per running unit of the ledger, like the host's agent list. agy
+    stacks it under its default line (stack_with_default), so no chain is needed there.
+    """
     try:
         payload = json.loads(stdin_text) if stdin_text.strip() else {}
     except ValueError:
         payload = {}
     if not isinstance(payload, dict):
         payload = {}
-    cwd = (payload.get("workspace") or {}).get("current_dir") or payload.get("cwd") or os.getcwd()
+    workspace = payload.get("workspace") if isinstance(payload.get("workspace"), dict) else {}
+    cwd = workspace.get("current_dir") or payload.get("cwd") or os.getcwd()
     transcript = payload.get("transcript_path")
-    session = payload.get("session_id")
+    session = payload.get("session_id") or payload.get("conversation_id")
     if not (isinstance(session, str) and session):
         session = Path(transcript).stem if isinstance(transcript, str) and transcript.endswith(".jsonl") else None
+    hook = hook_module()
+    if hook is not None:
+        try:
+            hook.update_metrics(home, host, payload)
+        except Exception:  # noqa: BLE001 - metrics never break the status line
+            pass
     previous = ""
     if chain:
         try:
@@ -603,9 +684,10 @@ def statusline(home, stdin_text, chain=None):
         except (OSError, subprocess.SubprocessError):
             previous = ""
     run = select(discover(cwd, home), cwd, strict=True, session=session)
-    ours = ""
+    parts = [p for p in (mode_text(home),) if p]
+    rows = []
     if active(run):
-        if run["host"] == "claude" and not run["session"].get("id") and session:
+        if run["host"] == "claude" and host == "claude" and not run["session"].get("id") and session:
             # The status line knows its own session: exact usage instead of every session in the directory.
             try:
                 usage = claude_tokens(dict(run, session={"id": session}), Path(home), *window(run))
@@ -613,19 +695,28 @@ def statusline(home, stdin_text, chain=None):
                 usage = None
         else:
             usage = tokens(run, home)
-        ours = compact(run, usage)
+        parts.append(compact(run, usage))
+        if run["status"] == "running":
+            rows = agent_rows(run, limit=MAX_AGENT_ROWS, counts=False)
+            if len(rows) == 1:
+                rows = []  # only "● main": the compact segment already says it
+    ours = " │ ".join(parts)
     if not previous.strip():
-        return ours
-    if not ours:
-        return previous
-    return previous + " │ " + ours
+        first_line = ours
+    elif not ours:
+        first_line = previous
+    else:
+        first_line = previous + " │ " + ours
+    return "\n".join([first_line, *rows]) if rows else first_line
 
 
 def tmux_segment(home, cwd):
+    mode = mode_text(home)
     run = select(discover(cwd, home), cwd, strict=True)
     if not active(run):
-        return ""
-    return compact(run, tokens(run, home), unicode=True, width=8).replace("#", "##")
+        return mode
+    text = compact(run, tokens(run, home), unicode=True, width=8)
+    return ((mode + " · " if mode else "") + text).replace("#", "##")
 
 
 def main(argv=None):
@@ -636,6 +727,7 @@ def main(argv=None):
     p.add_argument("--cwd", default=None)
     p.add_argument("--home", default=None)
     p.add_argument("--chain-file", default=None, help="JSON com o comando de status line anterior, encadeado antes do crow")
+    p.add_argument("--host", default="claude", choices=("claude", "agy"), help="CLI que chama a status line")
     args = p.parse_args(argv)
     home = Path(args.home).expanduser() if args.home else Path.home()
     cwd = args.cwd or os.getcwd()
@@ -646,7 +738,7 @@ def main(argv=None):
                 chain = json.loads(Path(args.chain_file).read_text(encoding="utf-8")).get("command")
             except (OSError, ValueError, AttributeError):
                 chain = None
-        print(statusline(home, sys.stdin.read() if not sys.stdin.isatty() else "", chain))
+        print(statusline(home, sys.stdin.read() if not sys.stdin.isatty() else "", chain, args.host))
         return 0
     if args.mode == "tmux":
         print(tmux_segment(home, cwd))

package/crow_skills/source.py

@@ -8,6 +8,11 @@ import stat
 import subprocess
 
 NAME = re.compile(r"crow-[a-z0-9]+(?:-[a-z0-9]+)*\Z")
+PACKAGE = "@andespindola/crow-skills"
+# Where a packaged release (npm tarball, also used by the Homebrew formula) lives. The
+# version is part of the Homebrew path and npx caches, so it changes on every upgrade.
+PACKAGED = (re.compile(r"/Cellar/crow-skills/[^/]+/libexec\Z"), re.compile(r"/node_modules/@andespindola/crow-skills\Z"),
+            re.compile(r"/_npx/[^/]+/node_modules/@andespindola/crow-skills\Z"))
 SHA = re.compile(r"[a-f0-9]{40,64}\Z")
 MAX_FILE = 8 * 1024 * 1024
 MAX_PACKAGE = 32 * 1024 * 1024
@@ -80,7 +85,9 @@ class Source:
             if ref not in ("HEAD", self.revision):
                 raise CrowError("immutable_release", "A referência não está neste snapshot npm; selecione um clone Git para outras refs.")
             raw = self.bundle_file("catalog.json")
+            self.identity = self._bundle_identity()
         else:
+            self.identity = "git:" + str(self.path)
             if fetch:
                 self.git("fetch", "--no-recurse-submodules", "origin", timeout=120)
             self.revision = self.git("rev-parse", "--verify", "--end-of-options", ref + "^{commit}").decode().strip()
@@ -138,6 +145,18 @@ class Source:
         except (OSError, ValueError, TypeError, KeyError) as exc:
             raise CrowError("invalid_release", "Manifesto do snapshot npm inválido.") from exc
 
+    def _bundle_identity(self):
+        """A verified snapshot of the published package: same identity on every version/path."""
+        try:
+            name = json.loads(self.bundle_file("package.json")).get("name")
+        except (CrowError, ValueError, AttributeError):
+            name = None
+        # Only where a release really lives (Homebrew Cellar, npm global, npx cache): a folder
+        # elsewhere that merely claims the name is another origin.
+        if name == PACKAGE and any(p.search(str(self.path)) for p in PACKAGED):
+            return "package:" + name
+        return "bundle:" + str(self.path)
+
     def bundle_file(self, name):
         safe_relative(name)
         try:
@@ -254,3 +273,24 @@ class Source:
         except (ValueError, KeyError, UnicodeError) as exc:
             raise CrowError("invalid_package", "Frontmatter/referências do pacote não correspondem ao catálogo.") from exc
         return Package(name, files, entries_for(files))
+
+
+def identity_of(record_source, record_identity=None):
+    """Identity recorded for an installation. Records made before 0.8.0 only kept the path:
+    a packaged-release path (Homebrew Cellar, npm global or npx cache) means the package."""
+    if record_identity:
+        return record_identity
+    if isinstance(record_source, str) and any(p.search(record_source) for p in PACKAGED):
+        return "package:" + PACKAGE
+    return "git:" + str(record_source)
+
+
+def source_identity(source):
+    return getattr(source, "identity", None) or "git:" + str(source.path)
+
+
+def same_source(record, source):
+    """An update keeps the recorded origin: the same path, or the same package at another version."""
+    if record.get("source") == str(source.path):
+        return True
+    return identity_of(record.get("source"), record.get("source_id")) == source_identity(source)

package/crow_skills/storage.py

@@ -16,7 +16,7 @@ import stat
 import uuid
 
 from .agents import uniflow_store
-from .source import CrowError, MAX_FILE, MAX_PACKAGE, MAX_FILES, SHA, digest, file_entry, safe_relative, valid_name
+from .source import CrowError, MAX_FILE, MAX_PACKAGE, MAX_FILES, SHA, digest, file_entry, safe_relative, same_source, source_identity, valid_name
 
 
 def checked(path):
@@ -314,8 +314,9 @@ class Store:
                     raise CrowError("unmanaged_conflict", "Destino já existe e não é gerenciado: " + name + ". Use --replace após revisar.")
                 new = None
                 if command != "uninstall":
-                    if record and command == "update" and record.get("source") != str(source.path):
-                        raise CrowError("source_mismatch", "Update requer a mesma origem; selecione --source explicitamente.")
+                    if record and command == "update" and not same_source(record, source):
+                        raise CrowError("source_mismatch", "Update requer a mesma origem (o mesmo clone, ou o mesmo pacote "
+                                        "publicado em outra versão); para trocar de origem, use install com --source.")
                     if name not in packages:
                         packages[name] = source.package(name)
                     new = packages[name].entries
@@ -337,7 +338,7 @@ class Store:
                     after[key]["installed"].pop(name)
                 else:
                     after[key]["installed"][name] = {
-                        "revision": source.revision, "source": str(source.path), "entries": new,
+                        "revision": source.revision, "source": str(source.path), "source_id": source_identity(source), "entries": new,
                         "package_sha256": digest(new), "agents": target_info["agents"],
                         "installed_at": datetime.now(timezone.utc).isoformat(),
                     }

package/docs/cli.md

@@ -1,6 +1,6 @@
-# crow-skills CLI 0.7.0
+# crow-skills CLI 0.8.0
 
-CLI local-first para humanos e agentes. Python 3.10+, sem bibliotecas Python externas; Git é necessário para fontes em clone, não para o snapshot npm. O launcher npm requer Node 18+. Mutações suportadas em macOS/Linux (locks POSIX). Não instala o agente, não executa scripts das skills e não muda modelos, prompts base ou permissões. Instruções de uso das skills (o guia do agente, abaixo) são gravadas pelo comando `guide` e, por padrão, por `install`/`update`/`uninstall` em `--global` quando a crow-behaviour fica instalada para um agente com mecanismo verificado; `--no-guide` desliga isso. Os mesmos comandos também aplicam as [integrações de interface](#integrações-de-interface-integrations) (status line do Claude Code e do Codex, segmento tmux); `--no-integrations` desliga. `crow-skills progress` mostra o [painel de progresso](#progresso-progress) da execução crow-behaviour ativa.
+CLI local-first para humanos e agentes. Python 3.10+, sem bibliotecas Python externas; Git é necessário para fontes em clone, não para o snapshot npm. O launcher npm requer Node 18+. Mutações suportadas em macOS/Linux (locks POSIX). Não instala o agente, não executa scripts das skills e não muda modelos, prompts base ou permissões. Instruções de uso das skills (o guia do agente, abaixo) são gravadas pelo comando `guide` e, por padrão, por `install`/`update`/`uninstall` em `--global` quando a crow-behaviour fica instalada para um agente com mecanismo verificado; `--no-guide` desliga isso. Os mesmos comandos também aplicam as [integrações de interface](#integrações-de-interface-integrations) (status lines do Claude Code, do Codex e do Antigravity, hooks do modo crow em cada CLI, comando `/crow`, segmento tmux); `--no-integrations` desliga. `crow-skills mode on|off` liga e desliga a crow-behaviour em [todas as sessões e CLIs](#modo-crow-mode); `crow-skills progress` mostra o [painel de progresso](#progresso-progress) da execução ativa; `crow-skills events` expõe o [barramento de eventos](#eventos-events) dos hooks; `crow-skills autoupdate on` liga a [atualização automática](#atualização-automática-autoupdate).
 
 ## Executar
 
@@ -31,7 +31,7 @@ Para testar/distribuir o arquivo local sem registry:
 
 ```sh
 npm pack
-npm install -g ./andespindola-crow-skills-0.7.0.tgz --ignore-scripts
+npm install -g ./andespindola-crow-skills-0.8.0.tgz --ignore-scripts
 ```
 
 O pacote contém o CLI Python e todas as skills do commit, com `release.json` de hashes. Não requer acesso ao GitHub ou clone para list/install. O launcher Node encaminha argumentos sem shell para Python em modo isolado, evitando imports pelo diretório do chamador/PYTHONPATH. `CROW_SKILLS_PYTHON` pode apontar para outro executável Python 3.10+. Não há dependências npm nem hooks de instalação que instalem skills automaticamente.
@@ -80,9 +80,9 @@ A fonte em checkout deve ser um clone Git já existente. O padrão é o checkout
 
 `--fetch` busca `origin` somente quando solicitado, usando credenciais Git externas; não atualiza o checkout. É incompatível com `--dry-run`. Sem fetch, uma ref remota pode estar desatualizada. Git replace-objects e hooks não são usados para interpretar a fonte; erros de Git não imprimem stderr que possa conter credenciais. URL arbitrária/credencial não é argumento suportado de `--source`.
 
-Atualização é explícita. `update` sem nomes atualiza apenas instalações gerenciadas nos destinos selecionados; não instala o catálogo inteiro. A origem deve corresponder à registrada. Mudança intencional de origem requer install/revisão explícita, não troca silenciosa durante update.
+Atualização é explícita (ou agendada com [autoupdate](#atualização-automática-autoupdate)). `update` sem nomes atualiza apenas instalações gerenciadas nos destinos selecionados; não instala o catálogo inteiro. A origem deve corresponder à registrada. Mudança intencional de origem requer install/revisão explícita, não troca silenciosa durante update.
 
-No npm, primeiro atualize o pacote npm e então execute o update das skills, ou escolha uma fonte Git explicitamente. Com npx, o caminho de cache pode mudar entre versões; nesse caso, use install explícito para revisar/registrar a nova origem em vez de contornar source_mismatch.
+Desde a 0.8.0, a origem registrada é também uma identidade (`source_id`): `git:<caminho do clone>` para um clone, ou `package:@andespindola/crow-skills` para o snapshot publicado, só quando ele está onde um release é instalado (Cellar do Homebrew, `lib/node_modules` do npm global, cache do npx); uma pasta em outro lugar que só declare esse nome é `bundle:<caminho>`, outra origem. O caminho do pacote muda a cada versão (`.../Cellar/crow-skills/<versão>/libexec`, cache do npx), mas a identidade não: `update` aceita o mesmo pacote em outro caminho e registra o novo. Registros anteriores à 0.8.0, que só guardavam o caminho, são reconhecidos pelo formato do caminho de um pacote publicado (Cellar do Homebrew, `node_modules/@andespindola/crow-skills`). Um snapshot com outro nome de pacote, ou um clone Git, continua sendo outra origem: `source_mismatch`, e a troca exige install. No npm, primeiro atualize o pacote e então execute o update das skills (o autoupdate faz os dois).
 
 ## Estado, conflitos e recuperação
 
@@ -139,7 +139,7 @@ Erros retornam `ok:false` e `error.code/message`. Saídas reais incluem alteraç
 
 Codex/shared são deduplicados quando apontam para o mesmo diretório. O diretório compartilhado também pode ser lido por outros hosts; não é isolamento entre agentes. `.codex/skills` é uma localização legada encontrada em ambientes existentes; o adaptador usa a localização moderna documentada. Para um destino legado específico, use `--dest` explicitamente.
 
-`agents` só verifica PATH e caminhos, sem iniciar agente/LLM. `status`/`doctor` conferem arquivos e estado de instalação, não provam carregamento, ativação, independência dos workers ou execução correta da skill. Gemini oferece `/skills reload`; para outros hosts, confira sua lista/reload ou reinicie a sessão conforme a versão. Nenhum hook ou system prompt base é alterado para forçar uso; o guia abaixo, aplicado por padrão em `--global` e desligável com `--no-guide`, é aditivo.
+`agents` só verifica PATH e caminhos, sem iniciar agente/LLM. `status`/`doctor` conferem arquivos e estado de instalação, não provam carregamento, ativação, independência dos workers ou execução correta da skill. Gemini oferece `/skills reload`; para outros hosts, confira sua lista/reload ou reinicie a sessão conforme a versão. Nenhum system prompt base é alterado; o guia abaixo e os hooks do modo crow, aplicados por padrão em `--global` e desligáveis com `--no-guide` e `--no-integrations`, são aditivos: só informam ao agente o modo escolhido pelo usuário.
 
 ### Uniflow
 
@@ -177,7 +177,7 @@ crow-skills guide status
 crow-skills guide uninstall --agents codex --global --yes
 ```
 
-`guide` grava, no mecanismo nativo e sempre carregado de cada CLI, instruções curtas em pt-BR para o agente usar as skills instaladas: carregar a crow-behaviour por iniciativa própria antes de tarefas substantivas (várias etapas ou partes, decisões, vários arquivos, verificação), responder direto em conversa ou ajuste trivial, consultar a lista de skills disponíveis no agente (crow ou não) e carregar a especialista pertinente pelo nome. O conteúdo é gerado do catálogo e das skills gerenciadas pelo CLI naquele agente, com a forma de invocação dele. Exige a crow-behaviour instalada para o agente.
+`guide` grava, no mecanismo nativo e sempre carregado de cada CLI, instruções curtas em pt-BR para o agente usar as skills instaladas: obedecer ao [modo crow](#modo-crow-mode) vigente (anunciado pelo hook a cada prompt ou, sem hook, lido de `~/.config/crow-skills/mode.json`), carregar a crow-behaviour por iniciativa própria antes de tarefas substantivas (várias etapas ou partes, decisões, vários arquivos, verificação), responder direto em conversa ou ajuste trivial, consultar a lista de skills disponíveis no agente (crow ou não) e carregar a especialista pertinente pelo nome. O conteúdo é gerado do catálogo e das skills gerenciadas pelo CLI naquele agente, com a forma de invocação dele. Exige a crow-behaviour instalada para o agente.
 
 Aplicação automática (padrão em `install`, `update` e `uninstall` com `--global`, desligada por `--no-guide`):
 
@@ -211,6 +211,8 @@ crow-skills progress --watch         # redesenha a cada segundo; sai sozinho ap
 crow-skills progress --run ID --json # leitura por agente/automação
 ```
 
+O painel começa pela lista de processos no formato da lista de agentes do host: `● main  <atividade do coordenador>` e uma linha `○ <dono>  <atividade>` por unidade em andamento de outro dono (o prefixo `subagent:` sai do nome). É o mesmo bloco que a crow-behaviour mostra na conversa (`crow_ledger.py show`) e que a status line do Claude Code e do Antigravity exibem abaixo da linha principal.
+
 Lê o ledger `crow-run/1` que a crow-behaviour mantém em tarefas substantivas (formato em `skills/crow-behaviour/references/progress-ledger.md`): `$CROW_LEDGER`, `.crow/runs/*.json` no diretório atual e nos pais, e `~/.crow/runs/`. Sem `--run`, prefere execuções do diretório (ou de pais e filhos dele), depois as em andamento, depois a mais recente; um ledger `running` sem atualização há mais de 2 h conta como abandonado. Status line e tmux só mostram execuções do próprio diretório. Somente leitura; não inicia agentes.
 
 Tokens vêm dos logs locais do próprio host, filtrados pela janela da execução (`startedAt` até `endedAt` ou agora) e pela sessão (`session.id` no ledger) ou, sem ela, pelo diretório de trabalho (marcado como aproximado, pois outras sessões no mesmo diretório e janela entram na soma). Só campos numéricos de uso são lidos e impressos; conteúdo de mensagens, prompts e credenciais nunca é exibido.
@@ -237,13 +239,21 @@ crow-skills integrations uninstall --global --yes
 crow-skills install crow-behaviour --agents claude --global --no-integrations --yes   # sem integrações
 ```
 
-Aplicadas por padrão junto com `install`/`update` em `--global` para os agentes selecionados que ficam com a crow-behaviour, e removidas quando ela sai (`uninstall`, `rollback`, `recover`). `--no-integrations` desliga o passo; `--project`/`--dest` não têm integração. São um passo posterior às transações de skills e guia: uma recusa aparece em `integrations.skipped` e não desfaz as skills.
+Aplicadas por padrão junto com `install`/`update` em `--global` para os agentes selecionados que ficam com a crow-behaviour, e removidas quando ela sai (`uninstall`, `rollback`, `recover`). `--no-integrations` desliga o passo; `--project`/`--dest` não têm integração. São um passo posterior às transações de skills e guia: uma recusa aparece em `integrations.skipped` e não desfaz as skills. Integrações de um CLI que não está configurado no perfil (sem `~/.codex`, `~/.gemini/settings.json`, `~/.gemini/antigravity-cli` ou `~/.config/devin/config.json`) são puladas com o motivo, sem criar arquivos.
 
-| Integração | Agentes | Mecanismo | O que mostra |
+| Integração | Agentes | Mecanismo | O que faz |
 |---|---|---|---|
-| claude-statusline | claude | chave `statusLine` (`type: command`) em `~/.claude/settings.json` | `crow ▸ título x/y ████░░ 46% · 1.2M tok` enquanto houver execução ativa no diretório da sessão (nunca de outro projeto, nunca uma execução gravada para outra sessão, nunca um ledger `running` parado há mais de 2 h); tokens da transcrição da sessão, com `~` quando forem aproximados |
+| claude-statusline | claude | chave `statusLine` (`type: command`) em `~/.claude/settings.json` | 1ª linha: `▸▸ crow on │ crow ▸ título x/y ████░░ 46% · 1.2M tok` (o indicador sempre; o resto enquanto houver execução ativa no diretório da sessão, nunca de outro projeto, de outra sessão ou de um ledger parado há mais de 2 h); linhas seguintes: a lista de processos (`● main …`, `○ dono  atividade`, até 6) |
+| claude-hooks | claude | entradas em `hooks` de `~/.claude/settings.json` | modo por prompt (`UserPromptSubmit`, síncrono) e eventos (demais, `async: true`) |
+| claude-command | claude | `~/.claude/commands/crow.md` (arquivo próprio) | `/crow on\|off\|status`: roda o toggle por `!` com `allowed-tools` restrito ao script; `disable-model-invocation` impede o modelo de chamá-lo |
 | codex-statusline | codex | `[tui].status_line` em `~/.codex/config.toml`, em bloco marcado | itens nativos `model-with-reasoning`, `context-remaining`, `current-dir`, `task-progress`, `used-tokens`; `task-progress` reflete o plano nativo que a skill espelha |
-| tmux-status | claude, codex, gemini (agy), devin | `~/.config/crow-skills/tmux.conf` (arquivo próprio) e um bloco `source-file -q` no fim do seu `tmux.conf` | segmento acrescentado ao `status-right` (`set -ag`, sem substituir o seu), com o diretório do painel ativo |
+| codex-hooks | codex | entradas em `~/.codex/hooks.json` | modo por prompt, `/crow on\|off\|status` interceptado e bloqueado com o resultado, `systemMessage` com o modo no início da sessão e quando muda, eventos (`async: true`) |
+| gemini-hooks | gemini (Gemini CLI) | `hooks` em `~/.gemini/settings.json` | modo por prompt (`BeforeAgent`), `systemMessage` quando muda, eventos |
+| gemini-command | gemini (Gemini CLI) | `~/.gemini/commands/crow.toml` (arquivo próprio) | `/crow on\|off\|status` por `!{…}` (o Gemini pede confirmação do shell, salvo política que o permita) |
+| agy-hooks | gemini (Antigravity) | chave `crow-skills` em `~/.gemini/config/hooks.json` | modo por prompt (`PreInvocation` → `injectSteps`), `/crow …` interceptado quando o agy envia o texto (`lastUserInput`, 1.4.7+), eventos |
+| agy-statusline | gemini (Antigravity) | `statusLine` em `~/.gemini/antigravity-cli/settings.json` com `stack_with_default: true` | indicador e lista de processos empilhados sob a linha padrão do agy |
+| devin-hooks | devin | `hooks` em `~/.config/devin/config.json` | modo por prompt, `/crow …` interceptado, `systemMessage` quando muda, eventos |
+| tmux-status | claude, codex, gemini (agy), devin | `~/.config/crow-skills/tmux.conf` (arquivo próprio) e um bloco `source-file -q` no fim do seu `tmux.conf` | `▸▸ crow on · crow ▸ …` acrescentado ao `status-right` (`set -ag`, sem substituir o seu), com o diretório do painel ativo |
 
 Regras de preservação:
 
@@ -251,12 +261,81 @@ Regras de preservação:
 - Claude: um `statusLine` existente do tipo `command` é encadeado: o comando anterior roda primeiro, com o mesmo stdin, sua saída é mantida inteira (todas as linhas, espaços internos) e o segmento crow entra no fim da última linha; as demais chaves dele (`padding` etc.) são preservadas. Outro tipo é mantido e a integração é pulada. Se você mudar o `statusLine` depois, ele não é sobrescrito nem removido. No uninstall, se `settings.json` ainda tiver exatamente o que o crow-skills gravou, os bytes originais do backup voltam; se você editou outra parte do arquivo, a restauração é só da chave `statusLine` (JSON reescrito com indentação 2).
 - Codex: só aplicado se você ainda não definiu `tui.status_line`; um `[tui]` existente recebe o bloco logo após o cabeçalho, senão o bloco cria a tabela no fim do arquivo. A edição é verificada por parse TOML (Python 3.11+). O uninstall só remove o bloco se ele estiver como foi gravado e se o resultado tiver as mesmas chaves que o arquivo atual menos `tui.status_line`; sem outras edições, o arquivo volta byte a byte. Chaves acrescentadas a um `[tui]` criado pelo crow-skills mantêm o cabeçalho `[tui]`; bloco editado ou remoção que mudaria outra chave é recusado e reportado em `skipped`. O Codex não aceita comando externo na status line, então ela não lê o ledger.
 - tmux: só quando o `tmux` está no PATH e já existe `~/.tmux.conf` ou `~/.config/tmux/tmux.conf`. Se o `tmux.conf` for symlink, o snippet é instalado mas o arquivo não é editado: o resultado traz a linha `source-file -q ...` para você adicionar. O snippet acrescenta o segmento só quando `status-right` ainda não o contém, então ele volta depois de cada `tmux source-file` do seu `tmux.conf` sem duplicar. O diretório do painel chega ao script escapado por `#{q:pane_current_path}` (tmux 3.0 ou mais novo): nome de diretório com `$(...)` ou crase não é executado. Depois de remover, o segmento sai da sessão atual quando o `status-right` é redefinido (recarregar um `tmux.conf` que o define) ou quando o servidor tmux reinicia.
-- O script usado pela status line e pelo tmux é uma cópia de `crow_skills/progress.py` em `~/.local/state/crow-skills/integrations/`, executada com o `python3` do PATH no momento da instalação; não depende do caminho do cache npm.
+- Hooks: as entradas do crow-skills são acrescentadas depois das suas, em todos os eventos (no Codex, a aprovação de `/hooks` é por índice, então o hook que você já aprovou continua aprovado), e reconhecidas pelo caminho do script. No Antigravity, ficam numa chave própria (`crow-skills`) de `hooks.json`, ao lado das suas. Uninstall tira só essas entradas; se ninguém mais editou o arquivo, os bytes originais voltam.
+- Arquivos JSON compartilhados por duas integrações (o `settings.json` do Claude Code recebe a status line e os hooks) têm um único ponto de restauração por arquivo: o conteúdo antes da primeira gravação do crow-skills. Removidas as duas, ele volta byte a byte; se o arquivo foi editado por você no meio do caminho, só as chaves/entradas do crow-skills saem.
+- O Devin também lê os hooks do `~/.claude/settings.json`. Para não duplicar nem rotular errado, o hook instalado para o Claude Code só age quando quem o executa é o Claude Code: a transcrição informada fica em `~/.claude/projects` (ou em `$CLAUDE_CONFIG_DIR/projects`), ou, sem transcrição, o ambiente traz `CLAUDECODE=1` (exportado pelo Claude Code para os processos filhos); um campo exclusivo do Devin (`tool_provenance`) também o silencia. O Devin usa a entrada própria, rotulada `devin`. Do mesmo modo, a entrada do Gemini CLI fica em silêncio quando o Antigravity a executa (`ANTIGRAVITY_AGENT=1`).
+- Codex: hooks novos ou alterados só rodam depois de aprovados em `/hooks` dentro do Codex, e só com `[features] hooks = true` no `config.toml`; o crow-skills não altera esse flag e avisa na nota da instalação quando ele falta.
+- Os scripts usados pela status line, pelo tmux, pelos hooks e pelos comandos `/crow` são cópias de `crow_skills/progress.py` (`crow_progress.py`) e `crow_skills/hook.py` (`crow_hook.py`) em `~/.local/state/crow-skills/integrations/`, executadas com o `python3` do PATH no momento da instalação (os hooks com `-I -S`); não dependem do caminho do cache npm ou do Homebrew.
+
+Sem superfície que mostre um valor externo persistente (conferido em 2026-10-28, Codex CLI 0.165.0, Gemini CLI 0.66.0, Devin CLI 3000.11.228):
+
+- Codex: `[tui].status_line` e `terminal_title` só aceitam itens nativos; o rodapé não mostra o modo crow. O hook mostra `▸▸ crow on|off` como `systemMessage` no início da sessão e quando o modo muda.
+- Gemini CLI: `ui.footer.items` aceita só itens nativos; idem, `systemMessage` quando muda.
+- Devin CLI: sem status line ou rodapé configurável; idem, `systemMessage` quando muda.
+- Nenhum CLI aceita alimentar a lista nativa de subagentes de fora; a lista de processos vem do ledger (status line do Claude Code e do agy, `crow-skills progress`, bloco no chat).
+
+O Antigravity (`agy`, agente `gemini` do instalador) ganhou `statusLine` por comando: a integração agy-statusline usa `stack_with_default` (o agy desliga a status line após falhas seguidas; o script sempre sai com código 0). O formato da chave foi lido do binário 1.4.4 e das notas de versão, sem sessão de verificação: se a linha não aparecer, rode `/statusline` no agy. No ledger, o host dele é `agy`; `gemini` no ledger significa Gemini CLI. Para os demais, use o segmento tmux ou `crow-skills progress --watch` num painel ao lado.
+
+## Modo crow (mode)
+
+```sh
+crow-skills mode            # status: ▸▸ crow on
+crow-skills mode off        # desliga em todas as sessões e CLIs, a partir do próximo prompt
+crow-skills mode on
+crow-skills mode toggle --json
+```
+
+O modo é um interruptor único para a crow-behaviour em todos os CLIs. `on` (padrão, também quando o arquivo não existe) é o modo de orquestração permanente: o agente carrega e segue a crow-behaviour em toda tarefa substantiva, sem o usuário pedir. `off`: o agente não a carrega nem aplica, salvo se o usuário a invocar no pedido; as especialistas continuam disponíveis. O estado fica em `~/.config/crow-skills/mode.json` (`crow-mode/1`, gravação atômica com `updatedAt` e quem mudou).
+
+Como cada CLI fica sabendo, sem reiniciar a sessão:
+
+| CLI | A cada prompt | Alternar dentro da sessão | Indicador visível |
+|---|---|---|---|
+| Claude Code | hook `UserPromptSubmit` injeta `[crow-skills] modo crow: ON\|OFF` | `/crow on\|off\|status` (`~/.claude/commands/crow.md`) | status line `▸▸ crow on` |
+| Codex | hook `UserPromptSubmit` (após aprovar em `/hooks`) | prompt exatamente `/crow on\|off\|status`: o hook alterna e bloqueia o prompt com o resultado | `systemMessage` no início e quando muda; o rodapé não aceita item externo |
+| Gemini CLI | hook `BeforeAgent` | `/crow on\|off\|status` (`~/.gemini/commands/crow.toml`) | `systemMessage` quando muda |
+| Antigravity (agy) | hook `PreInvocation` (`injectSteps`) | `/crow …` interceptado só quando o agy envia o texto do prompt (1.4.7+); senão peça ao agente para rodar `crow-skills mode on\|off` | status line `▸▸ crow on` (empilhada) |
+| Devin | hook `UserPromptSubmit` | prompt `/crow on\|off\|status`, como no Codex | `systemMessage` quando muda |
+| qualquer um | — | `crow-skills mode on\|off` num terminal | segmento tmux `▸▸ crow on` |
+
+O guia de cada agente diz para obedecer ao anúncio mais recente e, sem hook (não instalado ou não aprovado), ler o arquivo de modo no início da sessão. O modelo nunca muda o modo por conta própria (no Claude Code, o comando tem `disable-model-invocation`). `mode` sem `--yes` é intencional: alternar é o pedido explícito do usuário e não altera arquivos de configuração dos CLIs.
+
+## Eventos (events)
+
+```sh
+crow-skills events                  # resumo: sessões ativas, execuções crow, autoupdate
+crow-skills events snapshot --json  # crow-snapshot/1 para terminais (crow-term)
+crow-skills events tail --json --limit 100
+crow-skills events tail --follow    # JSONL puro até Ctrl-C
+```
+
+Os hooks gravam eventos compactos (`crow-event/1`) num JSONL rotacionado e um snapshot por sessão (host, sessão, diretório, branch, modelo, modo de permissão, modo crow, estado, ferramenta atual, última ação, subagentes em andamento, shells iniciados, bloqueio em aprovação, custo e uso quando a status line os envia). Nunca entram texto de prompt, mensagem, entrada/saída de ferramenta ou segredos. Contrato completo, campos e limites de disco em [docs/events.md](events.md).
+
+## Atualização automática (autoupdate)
+
+```sh
+crow-skills autoupdate on --dry-run
+crow-skills autoupdate on --yes             # agenda diário e no login
+crow-skills autoupdate status
+crow-skills autoupdate run --yes            # agora, manualmente
+crow-skills autoupdate run --skills-only --yes
+crow-skills autoupdate off --yes
+```
+
+`on` instala um agendador do usuário que roda `crow-skills autoupdate run --yes --json` todo dia e no login:
+
+| Sistema | Arquivos | Quando |
+|---|---|---|
+| macOS | `~/Library/LaunchAgents/com.andersonflima.crow-skills.autoupdate.plist`, carregado com `launchctl bootstrap gui/<uid>` | `RunAtLoad` (login) e `StartCalendarInterval` diário às 10:17 (roda ao acordar se o Mac dormia) |
+| Linux | `~/.config/systemd/user/crow-skills-autoupdate.{service,timer}`, habilitado com `systemctl --user enable --now` | `OnStartupSec=5min` e `OnCalendar=daily` com `Persistent=true` |
+| outros | — | `unsupported_platform`; agende `crow-skills autoupdate run --yes --json` por conta própria (por exemplo, cron) |
+
+O agendador chama o launcher estável (`<prefixo do Homebrew>/bin/crow-skills`, `<prefixo do npm>/bin/crow-skills` ou `bin/crow-skills` do checkout), não o caminho versionado. Um arquivo de agendador que já existe e não foi gravado pelo crow-skills é recusado (`unmanaged_conflict`); `off` não remove um arquivo editado depois da instalação (informa em `kept`). Com `--home` isolado, os arquivos são gravados mas nada é carregado.
 
-Sem superfície que mostre um valor externo (documentado em 2026-10-23, Gemini CLI 0.65.0, agy 1.4.4, Devin CLI 3000.11.92):
+Cada execução:
 
-- Gemini CLI: `ui.footer.items` aceita só itens nativos; hooks podem injetar contexto, não um item de rodapé.
-- Antigravity (`agy`, agente `gemini` do instalador): sem configuração de status line ou rodapé. No ledger, o host dele é `agy`; `gemini` no ledger significa Gemini CLI.
-- Devin CLI: sem status line ou rodapé configurável; hooks e plugins existem, mas não exibem um valor persistente.
+1. Atualiza o próprio crow-skills conforme a instalação: Homebrew (`brew upgrade andersonflima/tap/crow-skills`), npm global (`npm install -g @andespindola/crow-skills@latest`). Checkout Git só com `autoupdate on --git-pull`, e só se estiver limpo em `main`/`master` (`git pull --ff-only`); caso contrário, é pulado com o motivo. Saída de brew/npm/git não é guardada nem impressa, só código de saída e versões.
+2. Se a versão mudou, a versão nova (o launcher) faz o passo seguinte, para usar o snapshot novo como fonte.
+3. Para cada agente com skills gerenciadas (claude, codex/`~/.agents/skills`, gemini, devin, uniflow), roda o equivalente a `update <skills> --agents <agente> --global --yes`: regenera guia, integrações e hooks; a [identidade do pacote](#origem-e-versões) evita `source_mismatch` depois do upgrade. Skills editadas localmente (`modified`), ausentes ou instaladas de outra origem (`other_origin`, por exemplo de um clone Git) ficam como estão e aparecem em `kept`; nada é sobrescrito. Uma reaplicação dos hooks troca as entradas do crow-skills no lugar, sem mudar a posição das suas. Uma recusa num agente (por exemplo, guia editado) aparece em `error` e não interrompe os outros.
 
-Para esses, use o segmento tmux ou `crow-skills progress --watch` num painel ao lado.
+O resultado fica em `~/.local/state/crow-skills/autoupdate/state.json` (`lastRun` e as últimas 20 execuções), aparece em `autoupdate status`, em `status`/`doctor` (doctor `healthy:false` se a última execução falhou ou o agendador foi alterado/removido) e em `events snapshot`. Duas execuções simultâneas são recusadas (`busy`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/crow-skills",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Versioned, complementary agent skills with a protected multi-agent installer",
   "license": "UNLICENSED",
   "repository": {