failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/pt-br/configuration.mdx

@@ -0,0 +1,268 @@
+---
+title: Configuração
+description: "Formato do arquivo de configuração, sistema de três escopos e regras de mesclagem"
+icon: gear
+---
+
+failproofai utiliza arquivos de configuração JSON para controlar quais políticas estão ativas, como elas se comportam e de onde as políticas personalizadas são carregadas. A configuração foi projetada para ser fácil de compartilhar com sua equipe — faça commit no repositório e todos os desenvolvedores terão a mesma rede de segurança do agente.
+
+---
+
+## Escopos de configuração
+
+Existem três escopos de configuração, avaliados em ordem de prioridade:
+
+| Escopo | Caminho do arquivo | Finalidade |
+|-------|-----------|---------|
+| **project** | `.failproofai/policies-config.json` | Configurações por repositório, commitadas no controle de versão |
+| **local** | `.failproofai/policies-config.local.json` | Substituições pessoais por repositório, ignoradas pelo git |
+| **global** | `~/.failproofai/policies-config.json` | Padrões no nível do usuário para todos os projetos |
+
+Quando failproofai recebe um evento de hook, ele carrega e mescla todos os três arquivos que existem para o diretório de trabalho atual.
+
+### Regras de mesclagem
+
+**`enabledPolicies`** — união dos três escopos. Uma política habilitada em qualquer nível está ativa.
+
+```text
+project:  ["block-sudo"]
+local:    ["block-rm-rf"]
+global:   ["block-sudo", "sanitize-api-keys"]
+
+resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← união com deduplicação
+```
+
+**`policyParams`** — o primeiro escopo que define parâmetros para uma determinada política vence completamente. Não há mesclagem profunda de valores dentro dos parâmetros de uma política.
+
+```text
+project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← project vence, global ignorado
+```
+
+```text
+project:  (sem entrada block-sudo)
+local:    (sem entrada block-sudo)
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← cai para o global
+```
+
+**`customPoliciesPaths` / `customPoliciesPath`** — o primeiro escopo que define qualquer uma das formas vence.
+
+**`disabledCustomPolicies`** — união entre todos os escopos. O painel escreve um ID qualificado pela fonte aqui quando você desativa uma política individual de um arquivo de políticas explícito ou de convenção. Políticas não listadas permanecem habilitadas por padrão; os IDs incluem o arquivo de origem para que políticas com o mesmo nome em múltiplos arquivos possam ser controladas de forma independente.
+
+**`llm`** — o primeiro escopo que o define vence.
+
+---
+
+## Formato do arquivo de configuração
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "sanitize-jwt",
+    "block-env-files",
+    "block-read-outside-cwd"
+  ],
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    },
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "prod"]
+    },
+    "block-rm-rf": {
+      "allowPaths": ["/tmp"]
+    },
+    "block-read-outside-cwd": {
+      "allowPaths": ["/shared/data", "/opt/company"]
+    },
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
+      ]
+    },
+    "warn-large-file-write": {
+      "thresholdKb": 512
+    }
+  },
+  "customPoliciesPath": "/home/alice/myproject/my-policies.js"
+}
+```
+
+---
+
+## Referência de campos
+
+### `enabledPolicies`
+
+Tipo: `string[]`
+
+Lista de nomes de políticas a habilitar. Os nomes devem corresponder exatamente aos identificadores de política exibidos por `failproofai policies`. Consulte [Políticas Integradas](/pt-br/built-in-policies) para a lista completa.
+
+Políticas que não estão em `enabledPolicies` estão inativas, mesmo que tenham entradas em `policyParams`.
+
+### `policyParams`
+
+Tipo: `Record<string, Record<string, unknown>>`
+
+Substituições de parâmetros por política. A chave externa é o nome da política; as chaves internas são específicas de cada política. Cada política documenta seus parâmetros disponíveis em [Políticas Integradas](/pt-br/built-in-policies).
+
+Se uma política tiver parâmetros, mas você não os especificar, os padrões integrados da política serão utilizados. Usuários que não configuram `policyParams` obtêm comportamento idêntico às versões anteriores.
+
+Chaves desconhecidas dentro do bloco de parâmetros de uma política são silenciosamente ignoradas no momento do disparo do hook, mas sinalizadas como avisos quando você executa `failproofai policies`.
+
+#### `hint` (transversal)
+
+Tipo: `string` (opcional)
+
+Uma mensagem anexada ao motivo quando uma política retorna `deny` ou `instruct`. Use-a para fornecer orientações acionáveis ao Claude sem modificar a própria política.
+
+Funciona com qualquer tipo de política — integrada, personalizada (`custom/`), convenção de projeto (`.failproofai-project/`) ou convenção de usuário (`.failproofai-user/`).
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Try creating a fresh branch instead."
+    },
+    "block-sudo": {
+      "allowPatterns": ["sudo apt-get"],
+      "hint": "Use apt-get directly without sudo."
+    },
+    "custom/my-policy": {
+      "hint": "Ask the user for approval first."
+    }
+  }
+}
+```
+
+Quando `block-force-push` bloqueia, Claude vê: *"Force-pushing is blocked. Try creating a fresh branch instead."*
+
+Valores não-string e strings vazias são silenciosamente ignorados. Se `hint` não estiver definido, o comportamento permanece inalterado (compatível com versões anteriores).
+
+### `customPoliciesPath`
+
+Tipo: `string` (caminho absoluto)
+
+Caminho para um arquivo JavaScript contendo políticas de hook personalizadas. Isso é definido automaticamente por `failproofai policies --install --custom <path>` (o caminho é resolvido para absoluto antes de ser armazenado).
+
+O arquivo é carregado novamente a cada evento de hook — não há cache. Consulte [Políticas Personalizadas](/pt-br/custom-policies) para detalhes de criação.
+
+### Políticas baseadas em convenção
+
+Além do `customPoliciesPath` explícito, failproofai descobre e carrega automaticamente arquivos de políticas de diretórios `.failproofai/policies/`:
+
+| Nível | Diretório | Escopo |
+|-------|-----------|-------|
+| Projeto | `.failproofai/policies/` | Compartilhado com a equipe via controle de versão |
+| Usuário | `~/.failproofai/policies/custom-policies/` | Pessoal, aplicado a todos os projetos |
+
+<Note>
+  O diretório no nível do usuário foi movido um nível abaixo na reorganização
+  do diretório home. Arquivos deixados no antigo `~/.failproofai/policies/` são
+  movidos para `custom-policies/` automaticamente na primeira vez que você
+  executa qualquer comando `failproofai` após a atualização, e o comando informa
+  quais arquivos foram movidos.
+</Note>
+
+**Correspondência de arquivos:** Somente arquivos que correspondam a `*policies.{js,mjs,ts}` são carregados (por exemplo, `security-policies.mjs`, `workflow-policies.js`). Outros arquivos no diretório são ignorados.
+
+**Sem necessidade de configuração:** Políticas de convenção não requerem entradas em `policies-config.json`. Basta colocar os arquivos no diretório e eles serão detectados no próximo evento de hook.
+
+**Carregamento em união:** Tanto o projeto quanto os diretórios de convenção do usuário são verificados. Todos os arquivos correspondentes de ambos os níveis são carregados (ao contrário de `customPoliciesPath`, que usa o primeiro escopo que vence).
+
+Consulte [Políticas Personalizadas](/pt-br/custom-policies) para mais detalhes e exemplos.
+
+### `llm`
+
+Tipo: `object` (opcional)
+
+Configuração do cliente LLM para políticas que fazem chamadas de IA. Não é necessário para a maioria das configurações.
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## Gerenciando a configuração pela CLI
+
+Os comandos `policies --install` e `policies --uninstall` escrevem no arquivo de configurações de hook da CLI do agente (os pontos de entrada do hook), enquanto `policies-config.json` é o arquivo que você gerencia diretamente. Os dois são separados:
+
+- **Configurações da CLI do agente** — instrui o agente a chamar `failproofai --hook <event>` em cada uso de ferramenta:
+  - **Claude Code**: `~/.claude/settings.json` (usuário), `<cwd>/.claude/settings.json` (projeto), `<cwd>/.claude/settings.local.json` (local)
+  - **OpenAI Codex**: `~/.codex/hooks.json` (usuário), `<cwd>/.codex/hooks.json` (projeto) — Codex não possui escopo `local`
+  - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (usuário), `<cwd>/.github/hooks/failproofai.json` (projeto) — Copilot não possui escopo `local`. As entradas de hook usam os campos de comando `bash`/`powershell` com chave de SO do Copilot com `timeoutSec`; o arquivo carrega um marcador de nível superior `version: 1`. O suporte ao Copilot CLI está em **beta** enquanto verificamos o esquema de registro `events.jsonl` (que os documentos públicos não especificam) em mais sessões do mundo real. **O modo agente do VS Code Copilot Chat (Preview)** lê configurações de hook de `.github/hooks/*.json`, `~/.copilot/hooks/*.json` e `~/.claude/settings.json` (governado pela configuração `chat.hookFilesLocations`) usando o mesmo contrato no formato Claude `{hookSpecificOutput:{permissionDecision:"deny",…}}` — exatamente os caminhos que esta integração `copilot` e a integração `claude` (`~/.claude/settings.json`) já escrevem, então `failproofai policies --install --cli copilot` (ou `--cli claude`) **já aplica no modo agente do VS Code** sem necessidade de uma integração `vscode` separada (confirmado ao vivo pelos logs de descoberta do VS Code).
+  - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (usuário), `<cwd>/.cursor/hooks.json` (projeto) — Cursor não possui escopo `local`. As entradas de hook usam o formato no estilo Claude `{type, command, timeout}` (sem divisão `bash`/`powershell`), mas armazenadas sob chaves de evento em camelCase (`preToolUse`, `beforeSubmitPrompt`, …) em um array plano conforme o [esquema de hooks](https://cursor.com/docs/hooks) do Cursor; o arquivo carrega um marcador de nível superior `version: 1`. O handler canonicaliza camelCase → PascalCase via `CURSOR_EVENT_MAP` para que as políticas integradas existentes disparem sem alterações. O suporte ao Cursor Agent está em **beta** enquanto verificamos o formato de transcrição em disco do Cursor (não especificado nos documentos públicos) em mais instalações do mundo real.
+  - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (usuário), `<cwd>/.opencode/opencode.json` + `<cwd>/.opencode/plugins/failproofai.mjs` (projeto) — OpenCode não possui escopo `local`. Ao contrário das outras cinco CLIs, o OpenCode **não possui sistema de hook de comando externo**: ele carrega plugins JS/TS em processo registrados explicitamente via o array `plugin: []` em `opencode.json` (a autodescoberta de `.opencode/plugins/` **não** é como os plugins carregam no opencode v1.14.33). A instalação inclui um pequeno shim de plugin gerado que chama o binário failproofai em subprocesso e traduz a resposta JSON no formato Claude de volta para a semântica do plugin: `throw new Error()` para negação de evento de ferramenta (cancela a chamada da ferramenta), `client.session.prompt(...)` para instruct E para negação de `Stop` / `SubagentStop` (envia o motivo da negação como a próxima mensagem do usuário — o único canal de força de nova tentativa, já que `session.idle` é apenas notificação e lançar a partir dele é um no-op), e no-op para allow. O shim canonicaliza tanto nomes de ferramentas (minúsculas → PascalCase via `OPENCODE_TOOL_MAP`) quanto chaves de argumentos de entrada de ferramenta (camelCase → snake_case via `OPENCODE_TOOL_INPUT_MAP` para `Read` / `Write` / `Edit`, por exemplo `filePath` → `file_path`, `oldString` → `old_string`) antes de encaminhar para o binário, para que builtins de verificação de caminho como `block-read-outside-cwd`, `block-env-files` e `block-secrets-write` disparem sem alterações nas chamadas de ferramenta do OpenCode. As sessões ficam no banco de dados SQLite do opencode em `~/.local/share/opencode/opencode.db`; o visualizador de sessões do painel as lê via `opencode db --format json` e `opencode export <id>`. O suporte ao OpenCode está em **beta** enquanto verificamos o comportamento em versões diferentes e em mais sessões do mundo real. Veja a [documentação de plugins do OpenCode](https://opencode.ai/docs/plugins/).
+  - **Pi _(beta)_**: `~/.pi/agent/settings.json` (usuário), `<cwd>/.pi/settings.json` (projeto) — Pi não possui escopo `local`. O Pi carrega pacotes de extensão TypeScript na inicialização; o arquivo de configurações é um array de strings plano `{"packages": ["./relative/path", …]}`. failproofai escreve uma única entrada no array de pacotes apontando para seu diretório `pi-extension/` empacotado. A extensão internamente se inscreve nos eventos `tool_call` / `user_bash` / `input` / `session_start` do Pi e executa `failproofai --hook <Event> --cli pi` em shell; o handler canonicaliza underscore_lower_snake_case → PascalCase via `PI_EVENT_MAP` para que as políticas integradas existentes disparem sem alterações. Os argumentos de entrada de ferramenta também são canonicalizados via `PI_TOOL_INPUT_MAP` (Read / Write / Edit do Pi entregam `path` em vez de `file_path`; mapear a chave de nível superior permite que `block-env-files` e `block-secrets-write` disparem — `block-read-outside-cwd` já tinha um fallback para `path`). O suporte ao Pi está em **beta** enquanto a API de extensão e o layout do log de sessão do Pi se estabilizam.
+  - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**somente escopo de usuário** — Hermes não possui configuração de projeto/local). Hermes é um **gateway** Slack/Telegram, então uma única instalação intercepta chamadas de ferramentas de cada plataforma (Slack/Telegram/cli/cron) **e** subagentes internos. As entradas de hook são um par `{command, timeout}` (timeout em **segundos**) sob um mapa `hooks:` com chave pelos eventos snake_case do Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); o handler canonicaliza eventos via `HERMES_EVENT_MAP` e nomes de ferramentas via `HERMES_TOOL_MAP` para que as políticas integradas disparem sem alterações. A configuração é editada por meio de um round-trip YAML `Document` com preservação de comentários para que as outras configurações do operador sobrevivam, e a instalação define `hooks_auto_accept: true` para que o gateway headless (sem TTY) execute os hooks sem um prompt de consentimento. O avaliador emite o contrato stdout `{"decision":"block","reason"}` do Hermes (Hermes ignora códigos de saída). **Limitações:** Hermes não possui evento `Stop` de fim de turno, então os builtins `require-*-before-stop` nunca disparam para ele (não aplicável, não quebrado); `instruct` degrada para allow com nota registrada (sem canal de contexto adicional); e a redação de segredo de saída (`sanitize-*`) não pode reescrever a saída da ferramenta pelo contrato de hook de shell. Hermes é **também** uma fonte de **auditoria** offline — o painel lê suas sessões de gateway diretamente de `~/.hermes/state.db`.
+  - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**somente escopo de usuário** — OpenClaw não possui configuração de projeto/local). Como o Hermes, OpenClaw é um **gateway** multi-canal auto-hospedado, então uma única instalação intercepta chamadas de ferramentas de cada canal e seus subagentes internos. A aplicação é executada por meio dos **hooks de plugin em processo** do OpenClaw (seus hooks internos baseados em arquivo são apenas de observação e não podem bloquear), então — como OpenCode/Pi — failproofai inclui um pacote estático `openclaw-plugin/` que gera o binário failproofai de forma assíncrona e traduz o veredicto. A instalação registra o diretório de plugin incluído em `plugins.load.paths[]` do `openclaw.json` e o habilita em `plugins.entries.failproofai` (com `hooks.allowConversationAccess: true`, necessário para os hooks de conversa bruta). O avaliador emite um veredicto plano `{permission, reason}` e o shim o mapeia para o formato de retorno nativo de cada hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**) e `before_agent_finalize → {action:"revise", reason}` (**Stop** — uma verdadeira barreira de fim de turno, então os builtins `require-*-before-stop` **aplicam** no OpenClaw, ao contrário do Hermes). Eventos e nomes de ferramentas são canonicalizados no lado do binário via `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) para que as políticas integradas disparem sem alterações; o shim falha aberto em qualquer erro de spawn/parse/timeout. OpenClaw é **também** uma fonte de **auditoria** offline — o painel lê suas sessões JSONL em `~/.openclaw/agents/<agentId>/sessions/<uuid>.jsonl`.
+  - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (usuário), `<cwd>/.factory/hooks.json` (projeto) — Factory não possui escopo `local`. droid inclui um sistema de hook de comando externo no estilo Claude, mas com duas peculiaridades verificadas ao vivo contra droid v0.171.0: (1) os nomes dos eventos ficam no **nível superior** de `hooks.json` — **não há wrapper `"hooks"`** (droid rejeita um); eventos de ferramenta (`PreToolUse`/`PostToolUse`) carregam `"matcher": "*"`, eventos sem ferramenta o omitem. (2) A negação é conduzida pelo **código de saída 2 + stderr** do hook, não por uma decisão JSON — o branch `factory` do avaliador retorna saída 2 para eventos de ferramenta/prompt e `{decision:"block", reason}` apenas no evento de fim de turno `Stop` (o único canal de força de nova tentativa do droid). Os eventos já são PascalCase (sem mapa de eventos) e o payload é snake_case do Claude; apenas nomes de ferramentas são canonicalizados via `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory é **também** uma fonte de **auditoria** offline — o painel lê suas sessões JSONL em disco em `~/.factory/sessions/<encoded-cwd>/<sessionId>.jsonl`.
+  - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (usuário), `<cwd>/.devin/config.json` (projeto) — Devin não possui escopo `local`. Devin é um **clone puro do Claude** verificado ao vivo contra devin v3000.1.27: usa o esquema padrão com wrapper `"hooks"` do Claude (as escritas são de mesclagem preservadora para que outras chaves do arquivo de configuração — `org_id`, `theme_mode`, … — sobrevivam), nomes de eventos já em PascalCase (sem mapa de eventos, sem branch de handler) e um payload de stdin snake_case do Claude (sem normalização). O branch `devin` do avaliador nega com JSON `{"decision":"block","reason"}` no stdout na saída 0 para **todos** os eventos (verificado — o bloqueio substituiu `--permission-mode dangerous`); no evento de fim de turno `Stop`, o motivo carrega o texto de força de nova tentativa MANDATORY-ACTION para que os builtins `require-*-before-stop` sejam aplicados. Apenas nomes de ferramentas são canonicalizados via `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` já é canônico). Devin é **também** uma fonte de **auditoria** offline — o painel lê suas sessões SQLite em `~/.local/share/devin/cli/sessions.db` (cada linha `sessions` carrega um `working_directory` real, então as sessões são agrupadas por cwd do projeto como o Claude).
+  - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (usuário), `<cwd>/.agents/hooks.json` (projeto) — Antigravity não possui escopo `local`. Ao contrário do Factory/Devin, Antigravity tem seu **próprio** contrato (não é um clone do Claude), verificado ao vivo contra agy v1.1.2. `hooks.json` usa um esquema de **hook nomeado**: a chave de nível superior é um *nome* de hook (`"failproofai"`) cujo valor é um mapa de evento→handlers — eventos de ferramenta (`PreToolUse`/`PostToolUse`) envolvem handlers em `{matcher:"*", hooks:[…]}`, enquanto `PreInvocation`/`Stop` são arrays de handler **planos** (outros hooks nomeados são preservados). O payload de stdin é **protojson em camelCase** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai o normaliza para snake_case antes das políticas executarem, e mapeia os args PascalCase do `run_command` (`CommandLine`/`Cwd`) via `ANTIGRAVITY_TOOL_INPUT_MAP`. O branch `antigravity` do avaliador usa as **próprias** formas de resposta do Antigravity: `{decision:"deny", reason}` bloqueia uma ferramenta/prompt (saída 0), `{decision:"continue", reason}` no evento de fim de turno `Stop` reingressa no loop (então os builtins `require-*-before-stop` são aplicados) e `{injectSteps:[{ephemeralMessage}]}` injeta uma instrução em `PreInvocation` (→ `UserPromptSubmit`). Nomes de ferramentas são canonicalizados via `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity é **também** uma fonte de **auditoria** offline — o painel lê suas transcrições JSONL simples em `~/.gemini/antigravity-cli/brain/<conversationId>/.system_generated/logs/transcript_full.jsonl` (índice de conversas em `conversation_summaries.db`).
+  - **Goose (codinome goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (usuário), `<cwd>/.agents/plugins/failproofai/hooks/hooks.json` (projeto) — Goose não possui escopo `local`. A aplicação usa o sistema de **hooks** do Goose, a especificação **Open Plugins** entre agentes: o instalador apenas coloca o diretório do plugin `failproofai` e o Goose o autodescobre na inicialização (registrando-o automaticamente em `~/.config/goose/config.yaml`). O `hooks.json` usa um esquema Open Plugins **com** um wrapper `"hooks"` de nível superior, e o matcher é **omitido** em todos os eventos — um `"*"` simples é uma regex inválida que não corresponde a nada (verificado ao vivo contra goose v1.43.0). Os nomes dos eventos já são PascalCase (sem mapa de eventos); o payload de stdin usa `event`/`working_dir`, que o handler normaliza para `hook_event_name`/`cwd`. O branch `goose` do avaliador nega com JSON `{"decision":"block","reason"}` no stdout na saída 0, honrado **apenas** no evento **`PreToolUse`** (incluído no goose ≥ v1.37.0) — que dispara para a ferramenta shell **e dentro de subagentes delegados**, sendo o único ponto de negação suficiente; qualquer outro erro de hook falha **aberto**. Goose **não possui evento `Stop`**, então os builtins `require-*-before-stop` não se aplicam (como no Hermes). Nomes de ferramentas são canonicalizados via `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) e chaves de caminho via `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose é **também** uma fonte de **auditoria** offline — o painel lê suas sessões SQLite em `~/.local/share/goose/sessions/sessions.db` (cada linha `sessions` carrega um `working_dir` real, então as sessões são agrupadas por cwd do projeto como o Devin; execuções rápidas com `--no-session` são filtradas).
+- **`policies-config.json`** — informa ao failproofai quais políticas avaliar e com quais parâmetros (compartilhado entre todas as CLIs de agentes)
+
+Passe `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` para selecionar um agente específico (separado por espaços ou repetido para qualquer subconjunto):
+
+```bash
+failproofai policies --install --cli codex --scope project
+failproofai policies --install --cli copilot --scope project
+failproofai policies --install --cli cursor --scope project
+failproofai policies --install --cli opencode --scope project
+failproofai policies --install --cli pi --scope project
+failproofai policies --install --cli hermes --scope user
+failproofai policies --install --cli openclaw --scope user
+failproofai policies --install --cli factory --scope project
+failproofai policies --install --cli devin --scope project
+failproofai policies --install --cli antigravity --scope project
+failproofai policies --install --cli goose --scope project
+failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose
+```
+
+Quando `--cli` é omitido, `failproofai` detecta quais CLIs de agentes estão instaladas (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`):
+
+- **Uma CLI detectada** — seleciona automaticamente essa CLI sem solicitar confirmação.
+- **Múltiplas CLIs detectadas** em um terminal interativo — exibe um prompt de seleção única com teclas de seta agrupado em uma seção `Detected (N)` (com uma linha agregada `Install for all N detected` + cada CLI detectada individualmente) e uma seção `Not installed (M) · install hooks ahead of time` listando cada CLI suportada não detectada como opção de instalação antecipada (↑↓ para mover, Enter para selecionar, ^C para sair). O fluxo de desinstalação exibe apenas a seção Detected.
+- **Múltiplas CLIs detectadas** em uma execução não interativa (CI, sem TTY) — instala para todas as CLIs detectadas sem solicitar confirmação.
+- **Nenhuma detectada** — usa `claude` como fallback, com um aviso de que nenhum binário de agente foi encontrado no PATH; o comando de hook ainda é escrito para ser ativado assim que você instalar um.
+
+Você pode editar `policies-config.json` diretamente a qualquer momento; as alterações entram em vigor imediatamente no próximo evento de hook sem necessidade de reinicialização.
+
+---
+
+## Exemplo: configuração no nível do projeto com padrões da equipe
+
+Faça commit de `.failproofai/policies-config.json` no seu repositório:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "block-env-files"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "hotfix"]
+    }
+  }
+}
+```
+
+Cada desenvolvedor pode então criar `.failproofai/policies-config.local.json` (ignorado pelo git) para substituições pessoais sem afetar os colegas de equipe.

package/.next/standalone/docs-old/pt-br/custom-policies.mdx

@@ -0,0 +1,358 @@
+---
+title: Políticas Personalizadas
+description: "Escreva suas próprias políticas em JavaScript - aplique convenções, previna desvios, detecte falhas e integre com sistemas externos"
+icon: code
+---
+
+As políticas personalizadas permitem que você escreva regras para qualquer comportamento do agente: aplicar convenções do projeto, prevenir desvios, bloquear operações destrutivas, detectar agentes travados ou integrar com Slack, fluxos de aprovação e muito mais. Elas utilizam o mesmo sistema de eventos de hook e as decisões `allow`, `deny`, `instruct` das políticas embutidas.
+
+---
+
+## Exemplo rápido
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "no-production-writes",
+  description: "Block writes to paths containing 'production'",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("production")) {
+      return deny("Writes to production paths are blocked");
+    }
+    return allow();
+  },
+});
+```
+
+Instale:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## Duas formas de carregar políticas personalizadas
+
+### Opção 1: Baseada em convenção (recomendada)
+
+Coloque arquivos `*policies.{js,mjs,ts}` na pasta `.failproofai/policies/` e eles serão carregados automaticamente — sem flags ou alterações de configuração. Funciona como git hooks: adicione o arquivo e pronto.
+
+```
+# Nível de projeto — commitado no git, compartilhado com o time
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# Nível de usuário — pessoal, aplica-se a todos os projetos
+~/.failproofai/policies/my-policies.mjs
+```
+
+**Como funciona:**
+- Os diretórios de projeto e de usuário são escaneados juntos (união — não é primeiro-escopo-vence)
+- Os arquivos são carregados em ordem alfabética dentro de cada diretório. Use o prefixo `01-`, `02-` para controlar a ordem
+- Somente arquivos que correspondam a `*policies.{js,mjs,ts}` são carregados; outros arquivos são ignorados
+- Cada arquivo é carregado de forma independente (fail-open por arquivo)
+- Funciona junto com `--custom` explícito e políticas embutidas
+
+<Tip>
+As políticas por convenção são a forma mais fácil de construir um padrão de qualidade para sua organização. Faça commit de `.failproofai/policies/` no git e todos os membros do time receberão as mesmas regras automaticamente — sem configuração individual. À medida que o time identifica novos modos de falha, adicione uma política e faça push. Com o tempo, elas se tornam um padrão de qualidade vivo que melhora a cada contribuição.
+</Tip>
+
+### Opção 2: Caminho de arquivo explícito
+
+```bash
+# Instalar com um arquivo de políticas personalizadas
+failproofai policies --install --custom ./my-policies.js
+
+# Substituir os caminhos de políticas personalizadas
+failproofai policies --install --custom ./new-policies.js
+
+# Configurar múltiplos arquivos explícitos (carregados na ordem das flags)
+failproofai policies --install --custom ./security.js --custom ./workflow.js
+
+# Remover todos os caminhos de políticas personalizadas explícitas da configuração
+failproofai policies --uninstall --custom
+```
+
+Os caminhos absolutos resolvidos são armazenados em `policies-config.json` como `customPoliciesPaths`. Repita `--custom` para configurar múltiplos arquivos. Configurações existentes que usam o campo legado `customPoliciesPath` continuam funcionando. Os arquivos são carregados frescos a cada evento de hook — não há cache entre eventos.
+
+Cada política registrada aparece com seu próprio toggle no dashboard. Desativar uma política registra seu ID qualificado por fonte em `disabledCustomPolicies`; o arquivo e suas outras políticas continuam sendo carregados, enquanto a política desativada é excluída antes da correspondência de eventos. Nomes de políticas duplicados entre arquivos têm toggles independentes.
+
+### Usando as duas formas juntas
+
+As políticas por convenção e os arquivos `--custom` explícitos podem coexistir. Ordem de carregamento:
+
+1. Arquivos `customPoliciesPaths` explícitos (na ordem configurada)
+2. Arquivos de convenção do projeto (`{cwd}/.failproofai/policies/`, em ordem alfabética)
+3. Arquivos de convenção do usuário (`~/.failproofai/policies/`, em ordem alfabética)
+
+---
+
+## API
+
+### Import
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+Registra uma política. Chame quantas vezes forem necessárias para múltiplas políticas no mesmo arquivo.
+
+```ts
+customPolicies.add({
+  name: string;                         // obrigatório - identificador único
+  description?: string;                 // exibido na saída de `failproofai policies`
+  match?: { events?: HookEventType[] }; // filtra por tipo de evento; omita para corresponder a todos
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### Helpers de decisão
+
+| Função | Efeito | Quando usar |
+|--------|--------|-------------|
+| `allow()` | Permite a operação silenciosamente | A ação é segura, nenhuma mensagem é necessária |
+| `deny(message)` | Bloqueia a operação | O agente não deve executar esta ação |
+| `instruct(message)` | Adiciona contexto sem bloquear | Fornece contexto extra ao agente para mantê-lo no caminho certo |
+
+`deny(message)` - a mensagem aparece para Claude com o prefixo `"Blocked by failproofai:"`. Um único `deny` interrompe toda avaliação subsequente.
+
+`instruct(message)` - a mensagem é adicionada ao contexto de Claude para a chamada de ferramenta atual. Todas as mensagens `instruct` são acumuladas e entregues juntas.
+
+<Tip>
+Você pode acrescentar orientações extras a qualquer mensagem de `deny` ou `instruct` adicionando um campo `hint` em `policyParams` — sem necessidade de alterar o código. Isso funciona para políticas personalizadas (`custom/`), políticas de convenção de projeto (`.failproofai-project/`) e políticas de convenção de usuário (`.failproofai-user/`) também. Veja [Configuração → hint](/pt-br/configuration#hint-cross-cutting) para detalhes.
+</Tip>
+
+### Mensagens informativas de allow
+
+`allow(message)` permite a operação **e** envia uma mensagem informativa de volta para Claude. A mensagem é entregue como `additionalContext` na resposta stdout do handler de hook — o mesmo mecanismo usado por `instruct`, mas semanticamente diferente: é uma atualização de status, não um aviso.
+
+| Função | Efeito | Quando usar |
+|--------|--------|-------------|
+| `allow(message)` | Permite e envia contexto para Claude | Confirmar que uma verificação passou, ou explicar por que foi ignorada |
+
+Casos de uso:
+- **Confirmações de status:** `allow("All CI checks passed.")` — informa a Claude que tudo está em ordem
+- **Explicações de fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — informa a Claude por que uma verificação foi pulada para que ela tenha contexto completo
+- **Múltiplas mensagens se acumulam:** se várias políticas retornarem `allow(message)`, todas as mensagens são unidas com quebras de linha e entregues juntas
+
+```js
+customPolicies.add({
+  name: "confirm-branch-status",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    const cwd = ctx.session?.cwd;
+    if (!cwd) return allow("No working directory, skipping branch check.");
+
+    // ... check branch status ...
+    if (allPushed) {
+      return allow("Branch is up to date with remote.");
+    }
+    return deny("Unpushed changes detected.");
+  },
+});
+```
+
+### Campos de `PolicyContext`
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | A ferramenta sendo chamada (ex.: `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | Os parâmetros de entrada da ferramenta |
+| `payload` | `Record<string, unknown>` | Payload bruto completo do evento do Claude Code |
+| `session` | `SessionMetadata \| undefined` | Contexto da sessão (veja abaixo) |
+
+### Campos de `SessionMetadata`
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| `sessionId` | `string` | Identificador da sessão do Claude Code |
+| `cwd` | `string` | Diretório de trabalho da sessão do Claude Code |
+| `transcriptPath` | `string` | Caminho para o arquivo de transcrição JSONL da sessão |
+
+### Tipos de evento
+
+| Evento | Quando dispara | Conteúdo de `toolInput` |
+|--------|---------------|------------------------|
+| `PreToolUse` | Antes de Claude executar uma ferramenta | A entrada da ferramenta (ex.: `{ command: "..." }` para Bash) |
+| `PostToolUse` | Após uma ferramenta ser concluída | A entrada da ferramenta + `tool_result` (a saída) |
+| `Notification` | Quando Claude envia uma notificação | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks devem sempre retornar `allow()`, não podem bloquear notificações |
+| `Stop` | Quando a sessão do Claude termina | Vazio |
+
+---
+
+## Ordem de avaliação
+
+As políticas são avaliadas nesta ordem:
+
+1. Políticas embutidas (na ordem de definição)
+2. Políticas personalizadas explícitas de `customPoliciesPath` (na ordem de `.add()`)
+3. Políticas de convenção do projeto em `.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` dentro de cada um)
+4. Políticas de convenção do usuário em `~/.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` dentro de cada um)
+
+<Note>
+O primeiro `deny` interrompe todas as políticas subsequentes. Todas as mensagens `instruct` são acumuladas e entregues juntas.
+</Note>
+
+---
+
+## Imports transitivos
+
+Arquivos de política personalizados podem importar módulos locais usando caminhos relativos:
+
+```js
+// my-policies.js
+import { isBlockedPath } from "./utils.js";
+import { checkApproval } from "./approval-client.js";
+
+customPolicies.add({
+  name: "approval-gate",
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
+    return approved ? allow() : deny("Approval required for this command");
+  },
+});
+```
+
+Todos os imports relativos acessíveis a partir do arquivo de entrada são resolvidos. Isso é implementado reescrevendo os imports `from "failproofai"` para o caminho real do dist e criando arquivos `.mjs` temporários para garantir compatibilidade com ESM.
+
+---
+
+## Filtragem por tipo de evento
+
+Use `match.events` para limitar quando uma política é disparada:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // Só dispara quando a sessão termina
+    // ctx.session.transcriptPath contém o log completo da sessão
+    return allow();
+  },
+});
+```
+
+Omita `match` completamente para disparar em todos os tipos de evento.
+
+---
+
+## Tratamento de erros e modos de falha
+
+As políticas personalizadas são **fail-open**: erros nunca bloqueiam as políticas embutidas nem travam o handler de hook.
+
+| Falha | Comportamento |
+|-------|---------------|
+| `customPoliciesPath` não definido | Nenhuma política personalizada explícita é executada; políticas de convenção e embutidas continuam normalmente |
+| Arquivo não encontrado | Aviso registrado em `~/.failproofai/hook.log`; embutidas continuam |
+| Erro de sintaxe/import (explícito) | Erro registrado em `~/.failproofai/hook.log`; políticas personalizadas explícitas ignoradas |
+| Erro de sintaxe/import (convenção) | Erro registrado; aquele arquivo é ignorado, outros arquivos de convenção ainda são carregados |
+| `fn` lança exceção em tempo de execução | Erro registrado; aquele hook tratado como `allow`; outros hooks continuam |
+| `fn` demora mais de 10s | Timeout registrado; tratado como `allow` |
+| Diretório de convenção ausente | Nenhuma política de convenção é executada; sem erro |
+
+<Tip>
+Para depurar erros de políticas personalizadas, monitore o arquivo de log:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## Exemplo completo: múltiplas políticas
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// Prevent agent from writing to secrets/ directory
+customPolicies.add({
+  name: "block-secrets-dir",
+  description: "Prevent agent from writing to secrets/ directory",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
+    return allow();
+  },
+});
+
+// Keep the agent on track: verify tests before committing
+customPolicies.add({
+  name: "remind-test-before-commit",
+  description: "Keep the agent on track: verify tests pass before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
+    }
+    return allow();
+  },
+});
+
+// Prevent unplanned dependency changes during freeze
+customPolicies.add({
+  name: "dependency-freeze",
+  description: "Prevent unplanned dependency changes during freeze period",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
+    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
+      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
+    }
+    return allow();
+  },
+});
+
+export { customPolicies };
+```
+
+---
+
+## Exemplos
+
+O diretório `examples/` contém arquivos de política prontos para uso:
+
+| Arquivo | Conteúdo |
+|---------|----------|
+| `examples/policies-basic.js` | Cinco políticas iniciais cobrindo modos de falha comuns de agentes |
+| `examples/policies-advanced/index.js` | Padrões avançados: imports transitivos, chamadas assíncronas, limpeza de saída e hooks de fim de sessão |
+| `examples/convention-policies/security-policies.mjs` | Políticas de segurança baseadas em convenção (bloqueio de escrita em .env, prevenção de reescrita de histórico git) |
+| `examples/convention-policies/workflow-policies.mjs` | Políticas de fluxo de trabalho baseadas em convenção (lembretes de testes, auditoria de escrita em arquivos) |
+
+### Usando exemplos de arquivo explícito
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### Usando exemplos baseados em convenção
+
+```bash
+# Copiar para o nível do projeto
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# Ou copiar para o nível do usuário
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+Nenhum comando de instalação é necessário — os arquivos são detectados automaticamente no próximo evento de hook.