🧱 Guarda e painel

Nos vídeos que circularam sobre mods do Claude Code apareceram duas proteções: uma guarda de colisão (dois agentes no mesmo arquivo) e uma de "raio de explosão" (o tamanho do estrago de um comando que apaga).

A ideia é ótima. O kit faz a versão própria, só com recursos oficiais: os hooks do Claude Code. A divisão é simples: a regra fica no script, a tela fica no mod.

Como ler o desenho: a caixa âmbar é o ponto de controle. Toda edição e todo comando passam por ela antes de acontecer. Sem risco, segue pela seta azul. Com risco, a guarda não bloqueia nem libera: ela devolve a pergunta para você (N2).

"PreToolUse": [
  {
    "matcher": "Edit|Write|MultiEdit|NotebookEdit",
    "hooks": [ { "type": "command",
      "command": "node \"$CLAUDE_PROJECT_DIR/runtime/mods/runtime-guarda/hooks/colisao.mjs\" pre",
      "timeout": 10 } ]
  },
  {
    "matcher": "Bash",
    "hooks": [ { "type": "command",
      "command": "node \"$CLAUDE_PROJECT_DIR/runtime/mods/runtime-guarda/hooks/raio.mjs\"",
      "timeout": 15 } ]
  }
]
…
"PostToolUse": [ … colisao.mjs pos … ]

A dor é real. Aconteceu num projeto nosso: uma sessão esvaziou um arquivo que outra estava editando. Nenhuma das duas errou sozinha. Cada uma achava que o arquivo era só dela.

A colisão resolve isso com memória. Depois de cada edição, ela anota "esta sessão mexeu neste arquivo agora". Antes da próxima edição, confere a anotação e a data do arquivo.

Como ler o desenho: a seta azul é a edição normal da sessão A, que fica anotada. A seta vermelha é a sessão B chegando dentro da janela de 30 minutos. Quem responde à pergunta da caixa âmbar é você.

Provado no CHANGELOG 0.3.0: com 5 casos (arquivo velho, alterado por fora, mesma sessão, outra sessão, inexistente), a colisão só pergunta nos casos de outra sessão e de alteração por fora. Dentro do Claude, um Edit em arquivo de outra sessão foi barrado e o arquivo ficou intacto.

O raio entra antes de um rm ou git clean. Ele conta quantos arquivos existentes seriam apagados, soma o tamanho e lista os primeiros caminhos. Depois pergunta: "Tem backup? Confirme para seguir."

O raio não apaga nada: só lê o disco. E se o comando não apagaria nenhum arquivo existente, ele fica quieto. Você pode testar o script sozinho, sem abrir o Claude, mandando para ele o mesmo pedido que o Claude mandaria.

mkdir -p /tmp/teste-raio/x && echo a > /tmp/teste-raio/x/a && cd /tmp/teste-raio
printf '{"cwd":"%s","tool_name":"Bash","tool_input":{"command":"rm -r x"}}' "$PWD" \
  | node /caminho/do/kit/runtime/mods/runtime-guarda/hooks/raio.mjs

a saída traz "permissionDecision":"ask"
e o texto Raio: este comando apaga 1 arquivo(s)

Na pasta do kit a guarda já está ligada. Mas a Sônia tem outra pasta, a dos fechamentos mensais, onde também roda agentes. Ela quer a mesma proteção lá.

A receita R7 dá dois jeitos. Escolha um, não os dois.

claude --plugin-dir /caminho/do/kit/runtime/mods/runtime-guarda

com --plugin-dir runtime-guarda e o modo que libera tudo,
rm -r pasta foi barrado pelo "Raio" e a pasta ficou intacta;
Edit em arquivo editado por outra sessão foi barrado pela "colisão".

No módulo 3.3 você soltou sessões com claude --bg e acompanhou pelo observar.mjs, em outro terminal. O painel traz essa lista para dentro do Claude Code. É opcional.

Ele mostra cada sessão em segundo plano com nome, estado e minutos, um botão Atualizar e um botão Parar nas que estão rodando. Só o seu clique para uma sessão.

claude --plugin-dir runtime/mods/runtime-painel

claude plugin validate runtime/mods/runtime-painel
claude plugin test runtime/mods/runtime-painel

validate: passa
test: 1 pass

Como ler o desenho: é uma ilustração, não um print. A linha r4-revisor · done · 7 é a mesma sessão que o observar.mjs mostrou no módulo 3.3. O botão vermelho só aparece em sessão que ainda está rodando.

O que olhar na tabela: os dois leem a mesma lista de sessões. Escolha pelo conforto, não pela função.

Mods e plugins rodam com as mesmas permissões do Claude Code. Um hook pode ler seus arquivos, rodar comandos e acessar a rede, sem perguntar. É por isso que ele protege bem e é por isso que um mod mal-intencionado estraga bem.

A regra da receita R7: leia o código de qualquer mod de terceiro antes de instalar. Você não precisa programar para isso. Peça ao agente para ler e explicar, sem rodar nada.

Leia runtime/mods/runtime-guarda/.claude-plugin/plugin.json, runtime/mods/runtime-guarda/hooks/hooks.json, colisao.mjs e raio.mjs. Me diga em linguagem simples: em que momento cada hook roda, o que ele lê, o que ele grava e se acessa a rede. Não instale nem rode nada.