failproofai 1.0.1-beta.1 → 1.0.1

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

@@ -0,0 +1,858 @@
+---
+title: Políticas Integradas
+description: "Todas as 39 políticas integradas que detectam modos de falha comuns de agentes"
+icon: shield
+---
+
+failproofai vem com 39 políticas integradas que detectam modos de falha comuns de agentes. Cada política é disparada em um tipo de evento de hook específico e nome de ferramenta. Dezenove políticas aceitam parâmetros que permitem ajustar seu comportamento sem escrever código. Cinco políticas de fluxo de trabalho impõem um pipeline de commit → push → PR → CI antes que Claude pare.
+
+---
+
+## Visão geral
+
+As políticas são agrupadas em categorias:
+
+| Categoria | Políticas | Tipo de hook |
+|----------|----------|-----------|
+| [Comandos perigosos](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse |
+| [Comandos de infraestrutura](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse |
+| [Segredos (sanitizadores)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse |
+| [Ambiente](#environment) | block-env-files, protect-env-vars | PreToolUse |
+| [Acesso a arquivos](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse |
+| [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse |
+| [Banco de dados](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse |
+| [Avisos](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse |
+| [Gerenciadores de pacotes](#package-managers) | prefer-package-manager | PreToolUse |
+| [Fluxo de trabalho](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop |
+
+- **`block-`** — impede o agente de prosseguir.
+- **`warn-`** — fornece ao agente contexto adicional para que ele possa se autocorrigir.
+- **`sanitize-`** — remove dados sensíveis da saída da ferramenta antes que o agente os veja.
+
+### Namespaces
+
+Toda política reside em um slot `<namespace>/<nome>`. As políticas integradas pertencem ao
+namespace **`failproofai/`** — por exemplo, `failproofai/sanitize-jwt`. O
+namespace evita colisões quando você também carrega políticas personalizadas ou de terceiros
+com nomes curtos semelhantes.
+
+Na sua configuração, você pode referenciar uma política integrada pelo nome curto ou pelo
+nome qualificado; ambas as formas resolvem para a mesma política:
+
+```json
+{
+  "enabledPolicies": [
+    "sanitize-jwt",
+    "failproofai/block-rm-rf"
+  ]
+}
+```
+
+Se um nome não contém `/`, failproofai o trata como pertencente ao namespace padrão
+`failproofai`. Nomes que já contêm `/` (ex.: `myorg/foo`, `custom/my-hook`) são mantidos como estão.
+- **`require-`** — bloqueia o evento Stop até que as condições sejam atendidas.
+
+---
+
+<Tip>
+Toda política suporta um campo opcional `hint` em `policyParams`. O hint é adicionado à mensagem de deny ou instruct que Claude vê, fornecendo orientação acionável sem modificar o código da política. Funciona com políticas integradas, personalizadas e de convenção. Veja [Configuração → hint](/pt-br/configuration#hint-cross-cutting) para detalhes.
+</Tip>
+
+---
+
+## Comandos perigosos
+
+Impede agentes de executar operações difíceis de desfazer ou que possam danificar o sistema hospedeiro.
+
+### `block-sudo`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Nega qualquer comando `sudo` ou `doas`.
+
+Bloqueia um comando que executa um binário de elevação **na posição de comando**. A correspondência é estrutural, não textual: o comando é dividido em segmentos como um shell faria, atribuições de prefixo (`FOO=bar`), redirecionamentos e executores com seus flags (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) são removidos, e o binário resultante é comparado pelo **basename**. Portanto, `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` e `bash -c "sudo …"` são todos negados, e `doas` é tratado como a mesma capacidade sob um nome diferente.
+
+Como ancora na posição de comando e não na ocorrência da palavra em qualquer lugar, ele **não** é disparado em comandos que apenas o mencionam — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, ou uma alternância de `grep` contendo a palavra são executados normalmente.
+
+<Warning>
+Isso detém a tentativa óbvia; não fecha a classe inteira. Um agente que pode executar shell arbitrário ainda pode alcançar elevação indiretamente — por meio de uma variável (`S=sudo; $S …`), um pipe com base64 decodificado, ou um script wrapper em disco — porque nenhuma inspeção de uma única string de comando pode seguir esses caminhos. Trate isso como uma proteção contra erros e escalação casual, não como uma barreira de segurança contra um agente determinado. Uma barreira real precisa ser imposta abaixo do shell.
+</Warning>
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefixos de comando exatos que são permitidos. Cada entrada é comparada contra os tokens argv analisados. |
+
+**Exemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    }
+  }
+}
+```
+
+Com esta configuração, `sudo systemctl status nginx` é permitido, mas `sudo rm /etc/hosts` é negado.
+
+<Note>
+Os padrões são comparados contra os tokens analisados, não a string de comando bruta. Isso evita bypass por meio de operadores de shell anexados (ex.: `sudo systemctl status x; rm -rf /` não corresponde a `sudo systemctl status *`).
+</Note>
+
+---
+
+### `block-rm-rf`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Nega `rm -rf`, `rm -fr` e formas similares de exclusão recursiva.
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-------|------|---------|-------------|
+| `allowPaths` | `string[]` | `[]` | Caminhos que são seguros para exclusão recursiva (ex.: `/tmp`). |
+
+**Exemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-rm-rf": {
+      "allowPaths": ["/tmp", "/var/cache"]
+    }
+  }
+}
+```
+
+---
+
+### `block-curl-pipe-sh`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Nega `curl <url> | bash`, `curl <url> | sh`, `wget <url> | bash` e padrões similares.
+
+Sem parâmetros.
+
+---
+
+### `block-failproofai-commands`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Nega comandos que desinstalariam ou desativariam o próprio failproofai (ex.: `npm uninstall failproofai`, `failproofai policies --uninstall`).
+
+Sem parâmetros.
+
+---
+
+### `block-self-pause`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Nega `failproofai config --pause`, que suspende a aplicação para uma sessão. Pausar é uma decisão humana — um agente capaz de executar isso poderia desativar todas as outras políticas com um único comando.
+
+Mais restrito que [`block-failproofai-commands`](#block-failproofai-commands) propositalmente, e não coberto por ele: essa política ancora em um limite de comando, então `npx -y failproofai config --pause` não corresponde a ela, e por ser abrangente é frequentemente desativada para que agentes possam executar `failproofai audit`. `--resume` e `--status` são permitidos — nenhum remove a aplicação.
+
+Isso detém a tentativa direta, não a classe inteira: um agente ainda pode alcançar o mesmo estado por meio de um alias ou script wrapper. Fechar completamente requer que a pausa seja inacessível a partir de uma chamada de ferramenta.
+
+Sem parâmetros.
+
+---
+
+## Comandos de infraestrutura
+
+Impede agentes de codificação de executar CLIs de infraestrutura ou acionar pipelines de CI/CD. Todas as políticas nesta categoria são **opt-in** (`defaultEnabled: false`) — agentes que legitimamente precisam chamar `kubectl`, `terraform`, etc. não serão perturbados, a menos que você habilite a política. Quando habilitado, toda invocação do CLI correspondente é negada, a menos que o comando corresponda a uma entrada em `allowPatterns`.
+
+A gramática de padrões é a mesma que [`block-sudo`](#block-sudo): os tokens são comparados contra argv analisado, `*` é um curinga para um token, e qualquer comando contendo um operador de shell autônomo (`&&`, `||`, `|`, `;`) ou um token com metacaracteres de shell embutidos é rejeitado antes da correspondência com a lista de permissões para evitar bypasses por injeção.
+
+### `block-kubectl`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Nega qualquer invocação de `kubectl`.
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefixos de comando kubectl que são permitidos. |
+
+**Exemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-kubectl": {
+      "allowPatterns": ["kubectl get *", "kubectl describe *", "kubectl logs *"]
+    }
+  }
+}
+```
+
+Com esta configuração, `kubectl get pods` é permitido, mas `kubectl apply -f deploy.yaml` é negado.
+
+---
+
+### `block-terraform`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Nega qualquer invocação de `terraform` ou `tofu` (OpenTofu).
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefixos de comando terraform/tofu que são permitidos. |
+
+**Exemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-terraform": {
+      "allowPatterns": ["terraform plan", "terraform validate", "terraform show *"]
+    }
+  }
+}
+```
+
+---
+
+### `block-aws-cli`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Nega qualquer invocação do CLI `aws`.
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefixos de comando aws CLI que são permitidos. |
+
+**Exemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-aws-cli": {
+      "allowPatterns": ["aws s3 ls *", "aws sts get-caller-identity"]
+    }
+  }
+}
+```
+
+---
+
+### `block-gcloud`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Nega qualquer invocação do CLI `gcloud` (Google Cloud).
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefixos de comando gcloud que são permitidos. |
+
+**Exemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-gcloud": {
+      "allowPatterns": ["gcloud auth list", "gcloud config list"]
+    }
+  }
+}
+```
+
+---
+
+### `block-az-cli`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Nega qualquer invocação do CLI `az` (Azure).
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefixos de comando az CLI que são permitidos. |
+
+**Exemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-az-cli": {
+      "allowPatterns": ["az account show", "az group list"]
+    }
+  }
+}
+```
+
+---
+
+### `block-helm`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Nega qualquer invocação de `helm`.
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Prefixos de comando helm que são permitidos. |
+
+**Exemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-helm": {
+      "allowPatterns": ["helm list", "helm status *"]
+    }
+  }
+}
+```
+
+---
+
+### `block-gh-pipeline`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Nega os seguintes subcomandos do CLI `gh` que mutam estado ou acionam pipelines:
+
+- `gh workflow run`, `gh workflow enable`, `gh workflow disable`
+- `gh run rerun`, `gh run cancel`
+- `gh pr merge`
+- `gh release create`, `gh release delete`
+- `gh cache delete`
+- `gh secret set`, `gh secret delete`
+
+Subcomandos `gh` somente leitura como `gh pr view`, `gh pr list`, `gh run list`, `gh release view` e `gh api repos/.../...` **não** são correspondidos por esta política — eles são rotineiramente necessários para verificações de fluxo de trabalho (incluindo o próprio `require-ci-green-before-stop` do failproofai).
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Invocações scriptadas específicas a serem permitidas, mesmo que de outra forma seriam negadas. |
+
+**Exemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-gh-pipeline": {
+      "allowPatterns": ["gh run rerun *"]
+    }
+  }
+}
+```
+
+---
+
+## Segredos (sanitizadores)
+
+Impede agentes de vazar credenciais em seu contexto ou saída. Políticas de sanitização são disparadas em eventos **PostToolUse**. Quando Claude executa um comando Bash, lê um arquivo ou chama qualquer ferramenta, essas políticas inspecionam a saída antes que ela seja retornada a Claude. Se um padrão de segredo for detectado, a política retorna uma decisão de deny que impede a saída de ser passada de volta.
+
+### `sanitize-jwt`
+
+**Evento:** PostToolUse (todas as ferramentas)  
+**Padrão:** Redige tokens JWT (três segmentos base64url separados por `.`).
+
+Sem parâmetros.
+
+---
+
+### `sanitize-api-keys`
+
+**Evento:** PostToolUse (todas as ferramentas)  
+**Padrão:** Redige formatos comuns de chave de API: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), chaves de acesso AWS (`AKIA`), chaves Stripe (`sk_live_`, `sk_test_`) e chaves Google API (`AIza`).
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-------|------|---------|-------------|
+| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Padrões de regex adicionais a serem tratados como segredos. |
+
+**Exemplo:**
+
+```json
+{
+  "policyParams": {
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" },
+        { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" }
+      ]
+    }
+  }
+}
+```
+
+---
+
+### `sanitize-connection-strings`
+
+**Evento:** PostToolUse (todas as ferramentas)  
+**Padrão:** Redige strings de conexão de banco de dados que contêm credenciais embutidas (ex.: `postgresql://user:password@host/db`).
+
+Sem parâmetros.
+
+---
+
+### `sanitize-private-key-content`
+
+**Evento:** PostToolUse (todas as ferramentas)  
+**Padrão:** Redige blocos PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, etc.).
+
+Sem parâmetros.
+
+---
+
+### `sanitize-bearer-tokens`
+
+**Evento:** PostToolUse (todas as ferramentas)  
+**Padrão:** Redige cabeçalhos `Authorization: Bearer <token>` onde o token tem 20 ou mais caracteres.
+
+Sem parâmetros.
+
+---
+
+## Ambiente
+
+Protege a configuração sensível do ambiente de ser lida ou exposta por agentes.
+
+### `block-env-files`
+
+**Evento:** PreToolUse (Bash, Read)  
+**Padrão:** Nega a leitura de arquivos `.env` via `cat .env`, chamadas da ferramenta `Read` com `.env` como caminho do arquivo, etc.
+
+Não bloqueia `.envrc` ou outros arquivos adjacentes ao ambiente — apenas arquivos nomeados exatamente `.env`.
+
+Sem parâmetros.
+
+---
+
+### `protect-env-vars`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Nega comandos que imprimem variáveis de ambiente: `printenv`, `env`, `echo $VAR`.
+
+Sem parâmetros.
+
+---
+
+## Acesso a arquivos
+
+Mantém os agentes trabalhando dentro dos limites do projeto e longe de arquivos sensíveis.
+
+### `block-read-outside-cwd`
+
+**Evento:** PreToolUse (Read, Bash)  
+**Padrão:** Nega a leitura de arquivos fora da raiz do projeto. O limite é `CLAUDE_PROJECT_DIR` (definido uma vez por sessão pelo Claude Code), com fallback para o diretório de trabalho atual da sessão quando essa variável não estiver definida. Usar a raiz do projeto em vez do `cwd` atual significa que o limite permanece estável mesmo após Claude entrar com `cd` em um subdiretório.
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-------|------|---------|-------------|
+| `allowPaths` | `string[]` | `[]` | Prefixos de caminho absoluto que são permitidos mesmo fora da raiz do projeto. |
+
+**Exemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-read-outside-cwd": {
+      "allowPaths": ["/shared/data", "/opt/company/config"]
+    }
+  }
+}
+```
+
+---
+
+### `block-secrets-write`
+
+**Evento:** PreToolUse (Write, Edit)  
+**Padrão:** Nega escritas em arquivos comumente usados para chaves privadas e certificados: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`.
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-------|------|---------|-------------|
+| `additionalPatterns` | `string[]` | `[]` | Padrões de nome de arquivo adicionais (estilo glob) a serem bloqueados. |
+
+**Exemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-secrets-write": {
+      "additionalPatterns": [".token", ".secret"]
+    }
+  }
+}
+```
+
+---
+
+## Git
+
+Previne pushes acidentais, force-pushes e erros de branch difíceis de desfazer.
+
+### `block-push-master`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Nega `git push origin main` e `git push origin master`.
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-------|------|---------|-------------|
+| `protectedBranches` | `string[]` | `["main", "master"]` | Nomes de branch que não podem receber push diretamente. |
+
+**Exemplo:**
+
+```json
+{
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "master", "release", "prod"]
+    }
+  }
+}
+```
+
+<Tip>
+Para permitir push para todos os branches (efetivamente desativando esta política sem removê-la de `enabledPolicies`), defina `protectedBranches: []`.
+</Tip>
+
+---
+
+### `block-work-on-main`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Nega `git commit`, `git merge`, `git rebase` e `git cherry-pick` enquanto a árvore de trabalho está em `main` ou `master`. A criação e troca de branch (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) não são afetadas.
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-------|------|---------|-------------|
+| `protectedBranches` | `string[]` | `["main", "master"]` | Nomes de branch nos quais commit/merge/rebase/cherry-pick é negado. |
+
+---
+
+### `block-force-push`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Nega `git push --force` e `git push -f`.
+
+Sem parâmetros específicos de política. Use o [`hint`](/pt-br/configuration#hint-cross-cutting) transversal para sugerir alternativas:
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b <new-branch>`) and push that instead."
+    }
+  }
+}
+```
+
+---
+
+### `warn-git-amend`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Instrui Claude a prosseguir com cuidado ao executar `git commit --amend`. Não bloqueia o comando.
+
+Sem parâmetros.
+
+---
+
+### `warn-git-stash-drop`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Instrui Claude a confirmar antes de executar `git stash drop`. Não bloqueia o comando.
+
+Sem parâmetros.
+
+---
+
+### `warn-all-files-staged`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Instrui Claude a revisar o que está sendo staged ao executar `git add -A` ou `git add .`. Não bloqueia o comando.
+
+Sem parâmetros.
+
+---
+
+## Banco de dados
+
+Captura operações SQL destrutivas antes que sejam executadas em seu banco de dados.
+
+### `warn-destructive-sql`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Instrui Claude a confirmar antes de executar SQL contendo `DROP TABLE`, `DROP DATABASE` ou `DELETE` sem uma cláusula `WHERE`.
+
+Sem parâmetros.
+
+---
+
+### `warn-schema-alteration`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Instrui Claude a confirmar antes de executar instruções `ALTER TABLE`.
+
+Sem parâmetros.
+
+---
+
+## Avisos
+
+Fornece contexto extra aos agentes antes de operações potencialmente arriscadas, mas não destrutivas.
+
+### `warn-large-file-write`
+
+**Evento:** PreToolUse (Write)  
+**Padrão:** Instrui Claude a confirmar antes de escrever arquivos maiores que 1024 KB.
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-------|------|---------|-------------|
+| `thresholdKb` | `number` | `1024` | Limite de tamanho de arquivo em kilobytes acima do qual um aviso é emitido. |
+
+**Exemplo:**
+
+```json
+{
+  "policyParams": {
+    "warn-large-file-write": {
+      "thresholdKb": 256
+    }
+  }
+}
+```
+
+<Note>
+O handler do hook impõe um limite de 1 MB de stdin em payloads. Para testar esta política com conteúdo pequeno, defina `thresholdKb` para um valor bem abaixo de 1024.
+</Note>
+
+---
+
+### `warn-package-publish`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Instrui Claude a confirmar antes de executar `npm publish`.
+
+Sem parâmetros.
+
+---
+
+### `warn-background-process`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Instrui Claude a ter cuidado ao iniciar processos em segundo plano via `nohup`, `&`, `disown` ou `screen`.
+
+Sem parâmetros.
+
+---
+
+### `warn-global-package-install`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Instrui Claude a confirmar antes de executar `npm install -g`, `yarn global add` ou `pip install` sem um ambiente virtual.
+
+Sem parâmetros.
+
+---
+
+## Gerenciadores de pacotes
+
+Impõe quais gerenciadores de pacotes o agente tem permissão para usar.
+
+### `prefer-package-manager`
+
+**Evento:** PreToolUse (Bash)  
+**Padrão:** Desabilitado. Quando habilitado, bloqueia qualquer comando de gerenciador de pacotes que não esteja na lista `allowed` e instrui Claude a reescrever o comando usando um gerenciador permitido.
+
+Detecta: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo.
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-----------|------|---------|-------------|
+| `allowed` | string[] | `[]` | Nomes de gerenciadores de pacotes permitidos. Qualquer gerenciador detectado que não esteja nesta lista é bloqueado. Quando vazio, a política é uma no-op. |
+| `blocked` | string[] | `[]` | Nomes adicionais de gerenciadores a bloquear além da lista integrada (ex.: `['pdm', 'pipx']`). |
+
+A lista de bloqueio integrada cobre: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Use `blocked` para adicionar gerenciadores que não estão nesta lista.
+
+**Exemplo de configuração:**
+
+```json
+{
+  "enabledPolicies": ["prefer-package-manager"],
+  "policyParams": {
+    "prefer-package-manager": {
+      "allowed": ["uv", "bun"],
+      "blocked": ["pdm", "pipx"]
+    }
+  }
+}
+```
+
+Com esta configuração, `pip install flask` e `pdm install flask` são ambos negados com uma mensagem instruindo Claude a usar `uv` ou `bun` em vez disso. Comandos como `uv pip install flask` são permitidos porque `uv` está na lista de permissões e é verificado primeiro.
+
+---
+
+## Comportamento de IA
+
+Detecta quando agentes travam ou se comportam de forma inesperada.
+
+### `warn-repeated-tool-calls`
+
+**Evento:** PreToolUse (todas as ferramentas)  
+**Padrão:** Instrui Claude a reconsiderar quando a mesma ferramenta é chamada 3 ou mais vezes com parâmetros idênticos — um sinal comum de que o agente está preso em um loop.
+
+Sem parâmetros.
+
+---
+
+## Fluxo de trabalho
+
+Impõe um fluxo de trabalho disciplinado ao final da sessão. Essas políticas são disparadas no evento **Stop** e negam ao agente a possibilidade de parar até que cada condição seja atendida. Elas seguem uma cadeia de dependência natural: commit → push → PR → CI. Se uma política negar, as políticas posteriores na cadeia são ignoradas (deny curto-circuita).
+
+Todas as políticas de fluxo de trabalho são **fail-open**: se a ferramenta necessária não estiver disponível (ex.: `gh` não instalado, sem remote git), a política permite com uma mensagem informativa explicando por que a verificação foi ignorada.
+
+### Semântica de Stop por CLI
+
+A aplicação de Stop parece ligeiramente diferente entre os seis CLIs suportados porque cada um expõe um contrato de hook de "agente finalizado" diferente. O **resultado** é o mesmo — o agente não consegue parar enquanto um gate de fluxo de trabalho está falhando — mas os **mecanismos** diferem. A tabela abaixo resume; apenas o Pi tem uma peculiaridade visível ao usuário que vale entender antes de habilitar uma política `require-*-before-stop`.
+
+| CLI | Quando o gate dispara | O que você vê |
+|---|---|---|
+| Claude Code | Mesmo loop de agente, imediatamente | Claude continua trabalhando — corrige o problema e então tenta terminar novamente. Sem interrupção visível para você. |
+| Codex | Mesmo loop de agente, imediatamente | Igual ao Claude. |
+| GitHub Copilot CLI | Mesmo loop de agente, imediatamente | Igual ao Claude (usa o canal de retry `{decision:"block", reason}` do Copilot — verificado empiricamente contra o Copilot CLI 1.0.41). |
+| Cursor Agent | Mesmo loop de agente, imediatamente | Igual ao Claude (usa o canal `{followup_message}` do Cursor — limitado ao `loop_limit`, padrão de 5 tentativas). |
+| OpenCode | Mesmo loop de agente, imediatamente | Igual ao Claude (usa a chamada SDK `client.session.prompt(...)` do OpenCode roteada através de `hookSpecificOutput.additionalContext`). |
+| **Pi (pi-coding-agent)** | **Próximo turno do usuário** | **Pi para visivelmente** quando o gate dispara — seu loop de agente sai e você é retornado ao prompt. O gate então dispara na próxima vez que você enviar um prompt: failproofai adiciona uma diretiva `MANDATORY ACTION REQUIRED` ao prompt de sistema daquele turno, instruindo o LLM a completar a etapa de fluxo de trabalho (commit, push, etc.) antes de fazer o que você pediu. |
+
+<Note>
+**Limitação do Pi.** O `AgentEndEvent` do Pi (o equivalente upstream do hook `Stop` do Claude) não tem tipo Result — quando dispara, o loop de agente do Pi já saiu. O Pi não pode ser forçado a repetir o mesmo loop da forma que Claude / Copilot / Cursor / OpenCode podem. failproofai desloca o gate para o evento `before_agent_start` do Pi (que dispara após o próximo prompt do usuário) para que a verificação de fluxo de trabalho ainda seja aplicada, apenas no próximo turno em vez do atual.
+
+**O que isso significa na prática:**
+
+- Após o Pi parar, o motivo da negação é capturado na memória com chave pelo id de sessão do Pi. O próximo prompt que você enviar no mesmo processo Pi o consome: o LLM vê a diretiva `MANDATORY ACTION REQUIRED` no topo do seu prompt de sistema, faz o commit (ou push / abre o PR / aguarda o CI) e somente então continua com sua solicitação. O motivo de negação capturado é de uso único — uma vez consumido, o gate está limpo.
+- O gate é limitado pelo tempo de vida do processo do Pi. Se você der `Ctrl+C` no Pi ou sair entre os turnos, a entrada na memória é descartada junto com o processo e o gate é perdido. Claude, Copilot, Cursor e OpenCode têm o mesmo limite (encerrar o agente e o gate é perdido) — o Pi apenas o torna mais visível porque o agente sai visivelmente antes do gate disparar.
+- Uma negação pendente também é limpa em `session_shutdown` por qualquer motivo (`new` / `resume` / `fork` / `quit`), portanto um gate obsoleto de uma sessão anterior não pode vazar para uma nova sessão iniciada no mesmo processo Pi.
+
+Se você precisar de retry no mesmo loop no estilo Claude, execute suas políticas `Stop` sob qualquer um dos outros cinco CLIs suportados. Estamos acompanhando o Pi upstream para um futuro tipo Result em `AgentEndEvent` que nos permitiria fechar essa lacuna.
+</Note>
+
+### `require-commit-before-stop`
+
+**Evento:** Stop  
+**Padrão:** Nega a parada quando há alterações não commitadas (arquivos modificados, staged ou não rastreados). Retorna uma mensagem informativa quando o diretório de trabalho está limpo.
+
+Sem parâmetros.
+
+---
+
+### `require-push-before-stop`
+
+**Evento:** Stop  
+**Padrão:** Nega a parada quando há commits não enviados por push ou quando o branch atual não tem um branch de rastreamento remoto. Sugere `git push -u` para criar um branch de rastreamento se necessário. Falha aberto se nenhum remote estiver configurado.
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-------|------|---------|-------------|
+| `remote` | `string` | `"origin"` | Nome do remote para o qual fazer push. |
+
+**Exemplo:**
+
+```json
+{
+  "policyParams": {
+    "require-push-before-stop": {
+      "remote": "upstream"
+    }
+  }
+}
+```
+
+---
+
+### `require-pr-before-stop`
+
+**Evento:** Stop  
+**Padrão:** Nega a parada quando não existe pull request para o branch atual, ou quando o PR existente está fechado sem merge. Instrui Claude a criar um PR com `gh pr create`. Quando o PR é **mergeado**, a política permite (o trabalho foi entregue) e a mensagem sugere mudar do branch (`git checkout main && git pull`).
+
+Sem parâmetros.
+
+<Note>
+Esta política requer o [GitHub CLI](https://cli.github.com/) (`gh`) instalado e autenticado.
+Execute `gh auth login` com um personal access token que tenha o escopo `repo` para acesso de leitura a
+pull requests. Se `gh` não estiver instalado ou autenticado, a política falha aberta e reporta o motivo a Claude.
+</Note>
+
+---
+
+### `require-no-conflicts-before-stop`
+
+**Evento:** Stop  
+**Padrão:** Nega a parada quando o branch atual não consegue fazer merge limpo no branch base. A política primeiro confirma que há um PR `OPEN` no GitHub para o branch — sem um, não há alvo de merge a impor, então toda a política curto-circuita para permitir. Uma vez que um PR `OPEN` é confirmado, dois probes independentes são executados:
+
+1. **Local** — `git merge-tree --write-tree --name-only origin/<baseBranch> HEAD`. Em caso de conflito, a mensagem de negação nomeia os arquivos em conflito para que Claude saiba exatamente o que resolver.
+2. **GitHub** — reutiliza o resultado de `gh pr view --json mergeable,state` já obtido na pré-verificação. Captura conflitos que um `origin/<baseBranch>` local desatualizado perderia (ex.: alguém fez merge de um PR conflitante em `main` desde o último fetch). Um resultado `CONFLICTING` nega. Um resultado `UNKNOWN` também nega e instrui Claude a aguardar ~10 segundos e re-verificar antes de tentar parar novamente — isso previne falsos negativos enquanto o GitHub recalcula.
+
+Ignora completamente (permite) quando: `gh` não está instalado, não há PR para o branch, o estado do PR não é `OPEN` (ex.: `MERGED`, `CLOSED`), ou `gh pr view` retorna saída não analisável. Também falha aberto quando `origin/<baseBranch>` está ausente localmente ou quando não há commits à frente da base — esses fall-throughs da Camada 1 ainda consultam a mesclabilidade do PR em cache antes de permitir.
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-------|------|---------|-------------|
+| `baseBranch` | `string` | `"main"` | Branch base para verificar conflitos. |
+
+<Note>
+O GitHub CLI (`gh`) é necessário para esta política. A política usa `gh pr view` para confirmar
+que existe um PR `OPEN` antes de executar qualquer probe de conflito — sem `gh`, a política
+curto-circuita para permitir. Execute `gh auth login` com um personal access token que tenha
+o escopo `repo` para acesso de leitura a pull requests.
+</Note>
+
+---
+
+### `require-ci-green-before-stop`
+
+**Evento:** Stop  
+**Padrão:** Nega a parada quando verificações de CI estão falhando ou ainda em execução no branch atual. Verifica tanto as execuções de fluxo de trabalho do GitHub Actions quanto as verificações de bots de terceiros (ex.: CodeRabbit, SonarCloud, Codecov). Trata conclusões `skipped`, `cancelled` e `neutral` como não-falhas (este último cobre, por exemplo, alertas do Socket Security em PRs de contribuidores externos, onde o app intencionalmente reporta neutro em vez de sucesso/falha). Retorna uma mensagem informativa quando todas as verificações passam.
+
+Sem parâmetros.
+
+<Note>
+Esta política requer o [GitHub CLI](https://cli.github.com/) (`gh`) instalado e autenticado.
+Execute `gh auth login` com um personal access token que tenha o escopo `repo` para acesso de leitura a
+execuções de fluxo de trabalho do Actions e à API de Verificações. Se `gh` não estiver instalado ou autenticado, a política falha aberta e reporta o motivo a Claude.
+</Note>
+
+---
+
+---
+
+## Desabilitando políticas individuais
+
+Remova uma política específica de `enabledPolicies` na sua configuração, ou desative-a na aba Políticas do dashboard.
+
+```json
+{
+  "enabledPolicies": [
+    "block-rm-rf",
+    "sanitize-api-keys"
+  ]
+}
+```
+
+Políticas não listadas em `enabledPolicies` não são executadas, mesmo que existam entradas de `policyParams` para elas.