O que sai da sua máquina

Esta página descreve o tráfego automático que o @valorbrain/connect (versão 0.9.0, protocolo de hook v2) instala em cada harness: o que os hooks mandam sem o agente pedir. As chamadas de ferramenta MCP que o próprio agente faz (memory_store, memory_retrieve…) levam o que o modelo decidir enviar e não estão cobertas aqui.

Hooks instalados por versões anteriores passam para a 0.9.0 pelo self-heal (abaixo), menos os do Codex: o self-heal não reescreve hooks do Codex sem mudança de contrato, então uma instalação do Codex anterior à 0.9.0 continua com os hooks da 0.8.1 até você rodar o instalador de novo (e confiar nos hooks em /hooks). Enquanto isso, o --checkpoint off salvo não vale no Codex; só VALORBRAIN_CHECKPOINT=off desliga o checkpoint ali.

Cada número abaixo vem do código-fonte. Quando o código não determina algo, a página diz não determinado no código.

Resumo

OpenClaw não é instalado pelo @valorbrain/connect e fica fora desta página.

O cliente de hook comum

Claude Code, Codex, Gemini CLI, Kiro, Cursor, Grok e OpenCode rodam o mesmo cliente: npx -y @valorbrain/connect@0.9.0 hook <evento> --harness=<id>. A versão é fixa (nunca latest): o hook roda a cada prompt, então só uma versão revisada entra na sua máquina. Ele lê o JSON que o harness entrega no stdin e envia somente os campos abaixo.

Endpoint

POST https://valorbrain-api.valor.digital/api/v1/hooks/cue, com Authorization: Bearer <token> e content-type: application/json.

Se a rota responder 404 ou 405 (engine sem hooks/cue; o resultado fica em cache por 6 horas) ou 403 (engine antigo que trata o POST como escrita), o cliente usa o caminho legado: uma chamada MCP memory_prepare em POST https://valorbrain-api.valor.digital/mcp com message (o prompt cortado em 8.000 caracteres, ou "session start") e fast_mode: true.

Corpo por evento

O stop não manda texto da conversa. Quando o servidor responde com um checkpoint, o cliente entrega esse texto ao modelo do próprio harness, que decide o que gravar pelo MCP. O que o modelo gravar sai por essa chamada MCP, não pelo hook. A única exceção é o envio do transcript abaixo, que só existe com opt-in.

Transcript (opt-in: Claude Code e Grok com connect ≥ 0.10.1; Codex, Gemini CLI, Kiro, Cursor e OpenCode com connect ≥ 0.12.0)

Desligado por padrão. Liga por harness com npx -y @valorbrain/connect --harness <id> --transcript on (grava send_transcript: true na entrada do harness em ~/.valorbrain/connect.json; --transcript off grava false) ou na máquina inteira com VALORBRAIN_SEND_TRANSCRIPT=on, que vence o arquivo nos dois sentidos (off, 0, false, no / on, 1, true, yes). Só um "ligado" explícito envia. Este envio no stop existe do hook 0.10.1 em diante no Claude Code e no Grok, e do 0.12.0 em diante no Codex, Gemini CLI, Kiro, Cursor e OpenCode: o hook roda a versão fixada pelo engine, e um hook de versão anterior não faz este envio mesmo com a chave ligada.

Onde o hook acha o arquivo:

Execuções que nunca enviam, mesmo com a chave ligada:

• Claude Code: sessão dirigida por SDK (CLAUDE_CODE_ENTRYPOINT começando com sdk) e toda sessão que o Claude Code marca como sem ninguém (CLAUDE_CODE_SESSION_ATTENDED=0: -p/SDK, sessões em segundo plano e um claude aberto por outro). Com =1, o envio leva sessionAttended: "1", e o engine só tira fatos dos turnos digitados por uma pessoa. Sem a variável, o campo não vai.
• Codex: codex exec (é o que o SDK do Codex roda), codex mcp-server, clientes SDK do app-server e threads de sub-agente. O hook lê isso na linha session_meta do rollout (source, thread_source, originator); um rollout sem essa linha também não envia.
• Gemini CLI: gemini -p / --prompt, Gemini com a pergunta na linha de comando (sem -i) e Gemini em CI (CI=true ou GITHUB_ACTIONS=true), a mesma regra de "headless" do Gemini; sessões de sub-agente (kind: "subagent" no arquivo). Num runner do GitHub o Gemini não passa CI nem GITHUB_ACTIONS ao hook (veja a seção do Gemini CLI); ali vale só a checagem da linha de comando.
• Kiro: kiro-cli chat --no-interactive; no motor legado, as sessões que um cliente ACP abriu (session_created_reason: "subagent" em ~/.kiro/sessions/cli/<id>.json).
• Cursor: cursor-agent -p / --print. O stop do Cursor só dispara para a conversa principal; subagentes têm o subagentStop, que o connect não liga.
• OpenCode: sessões de subagente (com parentID) nunca são lidas.

Gemini CLI, Kiro e Cursor não dizem no payload nem no ambiente que a execução é não interativa. O hook roda um ps (Linux e macOS), sobe a árvore de processos a partir do pai e lê a linha de comando do processo do harness. Nada disso sai da máquina. Onde não há ps (Windows) ou ele falha, essa checagem não acontece e a execução conta como interativa: só vale o mínimo de 3 stops.

Hooks de extração legados ligados à mão (decision-extractor, episode-extractor, handoff-generator, feedback-loop, precompact-extract) continuam enviando o transcript quando a chave não foi escolhida: ligá-los à mão já é o opt-in. Com --transcript off (ou VALORBRAIN_SEND_TRANSCRIPT=off), um hook 0.10.1 ou posterior não lê nem envia o transcript, e os que só leem o transcript nem são chamados.

Credencial

O token é procurado nesta ordem, e o primeiro encontrado vence:

1. --token= na linha de comando (só instalações anteriores ao protocolo v2; o self-heal migra para o arquivo).
2. Variável de ambiente VALORBRAIN_TOKEN.
3. A entrada deste harness em ~/.valorbrain/connect.json (arquivo 0600, uma entrada por harness). É o token vbm_… que o instalador gravou.
4. api_key em ~/.valorbrain/config.json (o arquivo da CLI).

A base da API é --api=, depois VALORBRAIN_API_URL, depois a base salva com o token e, por fim, https://valorbrain-api.valor.digital. Sem token, o hook não faz nenhuma chamada de rede e escreve uma linha no stderr.

Ritmo

• Síncrono, não fire-and-forget: o harness espera a resposta, porque ela vira contexto. O cliente corta cada requisição em 4 s (VALORBRAIN_HOOK_TIMEOUT_MS muda esse valor). O harness corta o processo em 10 s (Gemini: 10.000 ms).
• Início de sessão: uma chamada. Um segundo início na mesma sessão em menos de 20 s não chama a rede.
• Prompt: uma chamada por prompt. Prompt vazio não chama. Com o envio de prompt desligado para o harness (--prompt off, abaixo), o hook de prompt não chama a rede.
• Stop: na maioria dos stops nada sai. A decisão é local, e o cliente só chama o servidor quando um checkpoint está devido. Política padrão (a resposta do servidor substitui): no mínimo 3 turnos, ou 2 turnos somando 8 min de trabalho; intervalo mínimo de 10 min (nunca menos de 1 min); no máximo 6 checkpoints por sessão. Stop sem session_id não chama.
• Limite no servidor: 300 chamadas a cada 10 min por token (VALORBRAIN_HOOK_CUE_MAX_PER_10MIN no engine).
• Qualquer erro sai com código 0 e no máximo uma linha no stderr; o prompt nunca é bloqueado pelo hook.

Tráfego de manutenção (self-heal)

Toda execução do hook também tenta um self-heal, limitado a uma vez a cada 6 horas por máquina (marcado em ~/.valorbrain/connect-state.json; VALORBRAIN_HEAL_INTERVAL_MS muda o intervalo) e a 2,5 s de espera no caminho do hook:

• GET https://valorbrain-api.valor.digital/setup/artifacts?agent=<id>&hooks=2, sem credencial. O manifesto só é usado se trouxer uma assinatura ed25519 válida de uma das chaves embutidas no connect (a ativa ou a reserva; cabeçalhos X-ValorBrain-Manifest-*; a chave pública em uso está em /setup/manifest-keys); sem ela, nada é escrito. Se o contrato mudou, reescreve localmente as regras e os hooks do harness (o Codex fica fora da migração automática de hooks), menos os arquivos que você editou à mão: esses ficam como estão e o aviso vai para o stderr e para ~/.valorbrain/connect.log. Rodar o instalador de novo mostra o diff e pergunta antes de sobrescrever.
• POST https://valorbrain-api.valor.digital/api/v1/runtimes/register com o token, em até 2,5 s. Envia runtime_key (<harness>:<hostname>:<caminho do home>), agent_platform, display_name, hostname, plugin_version: "0.9.0" e capabilities (harness, versão do contrato instalada, connector: "connect", self_heal: true, protocolo de hook).

A mesma declaração sai uma vez ao final de cada instalação.

Durante a instalação

Sem --token, o instalador abre a aprovação do computador: POST https://valorbrain.valor.digital/api/v1/cli/device/code com client: "connect", a lista de harnesses, device_label (<hostname> (<sistema operacional>), até 80 caracteres) e install_id (16 caracteres hexadecimais aleatórios guardados em ~/.valorbrain/install-id). Em seguida consulta /api/v1/cli/device/token até a aprovação.

Fonte: /www/valorbrain-cli/packages/connect/hook.mjs, /www/valorbrain-cli/packages/connect/index.mjs, /www/valorbrain-cli/packages/connect/login.mjs, /opt/valorbrain/src/hooks/cue.ts, /opt/valorbrain/src/server.ts

Por harness

Claude Code

Sessões do Claude Code dirigidas por SDK (CLAUDE_CODE_ENTRYPOINT começando com sdk) nunca recebem checkpoint e não chamam a rede no stop. Com o transcript ligado, uma sessão com CLAUDE_CODE_SESSION_ATTENDED=0 também não envia o transcript, e com =1 o envio leva sessionAttended: "1" (connect ≥ 0.12.0; veja "Transcript" acima).

Fonte: /opt/valorbrain/src/harness/adapters.ts (adapter claude-code), /www/valorbrain-cli/packages/connect/hook.mjs

Codex

O Codex pede que você revise e confie nos hooks alterados uma vez, em /hooks. Por isso o self-heal não migra os hooks do Codex sozinho: uma instalação anterior à 0.9.0 fica com os hooks da 0.8.1, que não leem o --checkpoint off salvo, até você rodar o instalador de novo.

Fonte: /opt/valorbrain/src/harness/adapters.ts (codexHooksArtifact), /opt/valorbrain/src/harness/hosted.ts

Gemini CLI

O Gemini CLI (0.43) passa aos hooks o ambiente do próprio processo, mais as variáveis GEMINI_*. Ele só filtra esse ambiente em dois casos:

• com security.environmentVariableRedaction.enabled: true no settings.json do Gemini: saem as variáveis com nome de segredo (TOKEN, KEY, SECRET, AUTH, PASSWORD…), alguns nomes fixos e as listadas em blocked;
• num runner do GitHub (GITHUB_SHA definido, ou SURFACE=Github): só passa uma lista curta (PATH, HOME, TERM…) e as listadas em allowed.

Por isso VALORBRAIN_SEND_PROMPT, VALORBRAIN_CHECKPOINT e VALORBRAIN_SEND_TRANSCRIPT chegam ao hook e valem como nos outros harnesses, menos num runner do GitHub. As escolhas salvas em ~/.valorbrain/connect.json (--prompt, --checkpoint, --transcript) valem sempre. Num runner do GitHub também não chegam CI nem GITHUB_ACTIONS; ali, o que impede o envio do transcript é a checagem da linha de comando (-p ou pergunta no argv).

Fonte: /opt/valorbrain/src/harness/adapters.ts (geminiHooksArtifact), /opt/valorbrain/src/harness/hosted.ts

Kiro

Com --scope workspace, o arquivo vai para .kiro/ dentro do projeto.

Fonte: /opt/valorbrain/src/harness/adapters.ts (adapter kiro), /www/valorbrain-cli/packages/connect/index.mjs (scopedManifest)

Cursor

O Cursor também carrega ~/.claude/settings.json. Quando ele dispara o hook de prompt do Claude Code, o cliente reconhece o Cursor pelo payload e não chama o hooks/cue. Um stop do Cursor que chega por esse arquivo não envia o transcript: só o ~/.cursor/hooks.json envia, com a credencial cursor.

Fonte: /opt/valorbrain/src/harness/adapters.ts (cursorHooksArtifact), /www/valorbrain-cli/packages/connect/hook.mjs

Grok CLI

O Grok também carrega ~/.cursor/hooks.json. O início de sessão que chega por esse arquivo com o payload do Grok não chama o hooks/cue.

Fonte: /opt/valorbrain/src/harness/adapters.ts (adapter grok), /www/valorbrain-cli/packages/connect/hook.mjs

OpenCode

Uma vez por carregamento, o plugin também busca GET https://valorbrain-api.valor.digital/setup/artifacts?agent=opencode (ou a base em VALORBRAIN_URL), sem credencial, e envia POST <origem da URL MCP em opencode.json>/api/v1/runtimes/register com o token do opencode.json, hostname, o caminho do home e a versão do contrato (timeout de 2,5 s). VALORBRAIN_OPENCODE_DISABLE=true desliga isso também.

Fonte: /opt/valorbrain/src/harness/adapters.ts (opencodePluginSource)

Hermes Agent

O Hermes não usa o cliente de hook comum. O connect grava um plugin MemoryProvider em Python que, sem o binário valorbrain local, roda os hooks no engine.

O Hermes não tem hooks no manifesto: --mcp-only não muda nada nele. O plugin de memória continua instalado e envia o prompt de cada turno; para parar, use --prompt off (ou --remove, que tira tudo).

Outras chamadas do plugin: GET /foundations?limit=10 e GET /health no início; POST /api/v1/runtimes/register no início (com hostname); POST /api/v1/runtimes/heartbeat no máximo a cada 300 s; e GET /setup/instructions quando a mensagem pede setup do ValorBrain.

Contextos que não são o principal (subagente, cron, flush) não gravam transcript nem rodam a extração de fim de sessão e de compressão.

O engine aceita no máximo 40 chamadas de hooks/run a cada 10 min por tenant.

Fonte: /opt/valorbrain/src/hermes/__init__.py, /opt/valorbrain/src/harness/adapters.ts (adapter hermes), /www/valorbrain-cli/packages/connect/index.mjs (mergeYaml)

Oh My Pi (OMP)

O OMP não tem hook por comando: carrega fábricas TS de ~/.omp/agent/hooks/pre/. No modo hospedado (manifesto hooks=2, a partir do engine que publica a ponte hospedada), o connect grava a ponte em ~/.omp/agent/hooks/pre/valorbrain.ts. Ela fala HTTP direto com o engine (fetch), sem npx por evento. Antes dessa versão do engine, o connect grava só a entrada MCP e as regras, e não há tráfego automático.

Falhas vão para ~/.omp/agent/valorbrain-hooks.log (0600), uma linha por falha ou por envio, sem conteúdo e sem token. A ponte não roda o cliente do connect, então o self-heal não a atualiza: uma versão nova chega quando você roda o instalador de novo.

Fonte: /opt/valorbrain/src/harness/omp-bridge-hosted.ts, /opt/valorbrain/src/harness/adapters.ts (adapter omp)

O que não sai

Isto vale para o cliente de hook comum (todos os harnesses acima, menos o Hermes e o OMP, que têm cliente próprio). Na ponte do OMP, com o transcript desligado (o padrão), o mesmo vale: nada além dos três corpos do hooks/cue.

• Transcript: os hooks que o instalador liga (session-start, prompt, stop) não leem o arquivo de transcript enquanto a chave não estiver ligada. Além dos três corpos acima, do fallback legado e do self-heal, eles não enviam nada. Com --transcript on, o Claude Code e o Grok, e do connect 0.12.0 em diante o Codex, o Gemini CLI, o Kiro, o Cursor e o OpenCode, enviam o transcript como descrito em "Transcript" acima. Para achar o arquivo e decidir se a execução é de uma pessoa, o hook lê só na máquina: a primeira linha do rollout do Codex, o começo do arquivo do Gemini, ~/.kiro/sessions/ e ~/.cursor/projects/<workspace>/agent-transcripts/, e a linha de comando dos processos acima dele (ps). Exceção: com a chave sem escolha (o padrão), um hook de extração legado que você ligou à mão (decision-extractor, episode-extractor, handoff-generator, feedback-loop, precompact-extract), em qualquer harness, ainda lê e envia o transcript; só --transcript off (ou VALORBRAIN_SEND_TRANSCRIPT=off) impede.
• Diretório de trabalho e o resto do payload: cwd, transcript_path e os demais campos que o harness entrega ficam na máquina. O cwd só entra num hash local que identifica a sessão (no Kiro, também no hash que acha o diretório da sessão). Com o transcript ligado, o arquivo de transcript e o cwd (como workingDir) vão no envio do transcript; um hook de extração ligado à mão envia também o cwd, o prompt e a última resposta do assistente, quando o harness os entrega.
• Respostas do assistente e saídas de ferramentas: não fazem parte dos corpos do hooks/cue. Vão dentro do transcript quando ele é enviado (chave ligada, ou hook de extração ligado à mão com a chave sem escolha).
• Token na linha de comando: no protocolo v2 o token fica em ~/.valorbrain/connect.json (0600), nunca no argv do hook.

No servidor, a trilha de leitura do hooks/cue guarda só o hash da consulta, não o texto.

Fonte: /www/valorbrain-cli/packages/connect/hook.mjs, /opt/valorbrain/src/harness/adapters.ts, /opt/valorbrain/src/server.ts, /opt/valorbrain/src/access-tracker.ts

Como desligar

• Tudo: npx -y @valorbrain/connect --remove. Desfaz a instalação inteira dos harnesses detectados: entradas MCP, regras, hooks e as credenciais em ~/.valorbrain/connect.json.
• Um harness: npx -y @valorbrain/connect --harness <id> --remove (o mesmo, só para ele).
• Só os hooks, mantendo o MCP e as regras: rode a instalação de novo com --mcp-only (npx -y @valorbrain/connect --token <vbm_…> --harness <id> --mcp-only). Nada sai por turno; rodar de novo sem --mcp-only põe os hooks de volta. Hooks que você editou à mão só saem com --force ou com um sim na pergunta. A nova execução precisa do token (--token <vbm_…>, como na instalação): sem ninguém no teclado, como no shell de um agente, o connect para sem ele. No Hermes, que não tem hooks, a flag não muda nada (o plugin continua enviando o prompt); no OMP ela tira a ponte de hooks.
• Só o checkpoint do stop, por harness: npx -y @valorbrain/connect --harness <id> --checkpoint off (grava checkpoint: false na entrada do harness; --checkpoint on religa). Na máquina inteira: VALORBRAIN_CHECKPOINT=off (ou 0, ou false) no ambiente do harness, que vence o arquivo nos dois sentidos. No Gemini CLI a variável não chega ao hook num runner do GitHub (veja a seção do Gemini CLI), e ali só o --checkpoint off funciona; no Codex instalado antes da 0.9.0, só a variável, até reinstalar.
• Só o prompt, por harness: npx -y @valorbrain/connect --harness <id> --prompt off (grava send_prompt: false na entrada do harness em ~/.valorbrain/connect.json; --prompt on religa). Na máquina inteira: VALORBRAIN_SEND_PROMPT=off no ambiente do harness (num runner do GitHub o Gemini CLI não passa essa variável aos hooks; ali, use o --prompt off). Sem o prompt, o início de sessão e o checkpoint continuam; o recall por prompt para.
• Transcript (Claude Code, Grok, Codex, Gemini CLI, Kiro, Cursor, OpenCode, Hermes e OMP): desligado por padrão; liga com npx -y @valorbrain/connect --harness <id> --transcript on, ou com VALORBRAIN_SEND_TRANSCRIPT=on no ambiente do harness, que vence o arquivo nos dois sentidos. --transcript off desliga.
• À mão: apague as entradas cujo comando contém @valorbrain/connect no arquivo do harness (tabela abaixo). Apagar só ~/.valorbrain/connect.json não basta se ~/.valorbrain/config.json tiver api_key, porque o hook usa essa chave como último recurso.

Como verificar

• npx -y @valorbrain/connect --status mostra, por harness, se os hooks estão ligados, em qual protocolo e para qual engine, e o modo (mcp-only ou hooks).
• npx -y @valorbrain/connect --token <vbm_…> --dry-run mostra o que seria escrito, sem escrever nada.
• Os arquivos que você pode abrir:

Veja também Tokens e Hosts.