> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Políticas Integradas

> Todas as 39 políticas integradas que detectam falhas comuns de agentes

failproofai vem com 39 políticas integradas que detectam falhas comuns de agentes. Cada política é acionada em um tipo específico de evento de hook 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 o 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                                                                      | 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 corrigir.
* **`sanitize-`** — remove dados sensíveis da saída da ferramenta antes que o agente os veja.

### Namespaces

Cada política vive em um slot `<namespace>/<nome>`. As políticas integradas pertencem ao namespace **`failproofai/`** — por exemplo, `failproofai/sanitize-jwt`. O namespace previne colisões quando você também carrega políticas personalizadas ou de terceiros com nomes curtos similares.

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 theme={null}
{
  "enabledPolicies": [
    "sanitize-jwt",
    "failproofai/block-rm-rf"
  ]
}
```

Se um nome não contém `/`, o 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 é anexado à mensagem de deny ou instruct que o Claude vê, fornecendo orientação prática 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 host.

### `block-sudo`

**Evento:** PreToolUse (Bash)\
**Padrão:** Nega qualquer comando `sudo`.

Bloqueia invocações que incluem a palavra-chave `sudo`. A correspondência de padrões é feita em tokens de comando analisados, não na string bruta, para evitar bypass via injeção de operadores shell.

**Parâmetros:**

| Parâmetro       | Tipo       | Padrão | Descrição                                                                                              |
| --------------- | ---------- | ------ | ------------------------------------------------------------------------------------------------------ |
| `allowPatterns` | `string[]` | `[]`   | Prefixos de comando exatos que são permitidos. Cada entrada é comparada com os tokens argv analisados. |

**Exemplo:**

```json theme={null}
{
  "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 com tokens analisados, não com a string de comando bruta. Isso previne bypass via operadores 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 seguros para exclusão recursiva (ex.: `/tmp`). |

**Exemplo:**

```json theme={null}
{
  "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 desabilitariam o próprio failproofai (ex.: `npm uninstall failproofai`, `failproofai policies --uninstall`).

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 afetados a menos que você habilite a política. Quando habilitada, toda invocação da CLI correspondente é negada, a menos que o comando corresponda a uma entrada em `allowPatterns`.

A gramática de padrões é a mesma de [`block-sudo`](#block-sudo): os tokens são comparados com argv analisado, `*` é um curinga para um token, e qualquer comando contendo um operador shell autônomo (`&&`, `||`, `|`, `;`) ou um token com metacaracteres shell embutidos é rejeitado antes da correspondência da lista de permissões para evitar bypasses de 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 comandos kubectl que são permitidos. |

**Exemplo:**

```json theme={null}
{
  "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 comandos terraform/tofu que são permitidos. |

**Exemplo:**

```json theme={null}
{
  "policyParams": {
    "block-terraform": {
      "allowPatterns": ["terraform plan", "terraform validate", "terraform show *"]
    }
  }
}
```

***

### `block-aws-cli`

**Evento:** PreToolUse (Bash)\
**Padrão:** Nega qualquer invocação da CLI `aws`.

**Parâmetros:**

| Parâmetro       | Tipo       | Padrão | Descrição                                           |
| --------------- | ---------- | ------ | --------------------------------------------------- |
| `allowPatterns` | `string[]` | `[]`   | Prefixos de comandos da CLI aws que são permitidos. |

**Exemplo:**

```json theme={null}
{
  "policyParams": {
    "block-aws-cli": {
      "allowPatterns": ["aws s3 ls *", "aws sts get-caller-identity"]
    }
  }
}
```

***

### `block-gcloud`

**Evento:** PreToolUse (Bash)\
**Padrão:** Nega qualquer invocação da CLI `gcloud` (Google Cloud).

**Parâmetros:**

| Parâmetro       | Tipo       | Padrão | Descrição                                       |
| --------------- | ---------- | ------ | ----------------------------------------------- |
| `allowPatterns` | `string[]` | `[]`   | Prefixos de comandos gcloud que são permitidos. |

**Exemplo:**

```json theme={null}
{
  "policyParams": {
    "block-gcloud": {
      "allowPatterns": ["gcloud auth list", "gcloud config list"]
    }
  }
}
```

***

### `block-az-cli`

**Evento:** PreToolUse (Bash)\
**Padrão:** Nega qualquer invocação da CLI `az` (Azure).

**Parâmetros:**

| Parâmetro       | Tipo       | Padrão | Descrição                                          |
| --------------- | ---------- | ------ | -------------------------------------------------- |
| `allowPatterns` | `string[]` | `[]`   | Prefixos de comandos da CLI az que são permitidos. |

**Exemplo:**

```json theme={null}
{
  "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 comandos helm que são permitidos. |

**Exemplo:**

```json theme={null}
{
  "policyParams": {
    "block-helm": {
      "allowPatterns": ["helm list", "helm status *"]
    }
  }
}
```

***

### `block-gh-pipeline`

**Evento:** PreToolUse (Bash)\
**Padrão:** Nega os seguintes subcomandos da 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 específicas com script a serem permitidas mesmo que normalmente seriam negadas. |

**Exemplo:**

```json theme={null}
{
  "policyParams": {
    "block-gh-pipeline": {
      "allowPatterns": ["gh run rerun *"]
    }
  }
}
```

***

## Segredos (sanitizadores)

Impede agentes de vazar credenciais em seu contexto ou saída. As políticas de sanitização são acionadas em eventos **PostToolUse**. Quando o Claude executa um comando Bash, lê um arquivo ou chama qualquer ferramenta, essas políticas inspecionam a saída antes que ela seja retornada ao 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 repassada.

### `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 chaves de API: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), chaves de acesso AWS (`AKIA`), chaves Stripe (`sk_live_`, `sk_test_`), e chaves de API do Google (`AIza`).

**Parâmetros:**

| Parâmetro            | Tipo                                 | Padrão | Descrição                                                |
| -------------------- | ------------------------------------ | ------ | -------------------------------------------------------- |
| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]`   | Padrões regex adicionais a serem tratados como segredos. |

**Exemplo:**

```json theme={null}
{
  "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 configurações de ambiente sensíveis de serem lidas ou expostas 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 de arquivo, etc.

Não bloqueia `.envrc` ou outros arquivos relacionados a ambiente — somente arquivos com o nome exato `.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 está definida. Usar a raiz do projeto em vez do `cwd` ativo significa que o limite permanece estável mesmo após o Claude fazer `cd` para um subdiretório.

**Parâmetros:**

| Parâmetro    | Tipo       | Padrão | Descrição                                                                                  |
| ------------ | ---------- | ------ | ------------------------------------------------------------------------------------------ |
| `allowPaths` | `string[]` | `[]`   | Prefixos de caminho absoluto que são permitidos mesmo que estejam fora da raiz do projeto. |

**Exemplo:**

```json theme={null}
{
  "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 theme={null}
{
  "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 branches que não podem receber push diretamente. |

**Exemplo:**

```json theme={null}
{
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "master", "release", "prod"]
    }
  }
}
```

<Tip>
  Para permitir push em todos os branches (desabilitando efetivamente 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`. Criação e troca de branches (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) não são afetados.

**Parâmetros:**

| Parâmetro           | Tipo       | Padrão               | Descrição                                                             |
| ------------------- | ---------- | -------------------- | --------------------------------------------------------------------- |
| `protectedBranches` | `string[]` | `["main", "master"]` | Nomes de branches 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 theme={null}
{
  "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 o 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 o 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 o Claude a revisar o que está sendo adicionado ao stage quando executa `git add -A` ou `git add .`. Não bloqueia o comando.

Sem parâmetros.

***

## Banco de dados

Detecta operações SQL destrutivas antes que sejam executadas no banco de dados.

### `warn-destructive-sql`

**Evento:** PreToolUse (Bash)\
**Padrão:** Instrui o 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 o 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 o 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 theme={null}
{
  "policyParams": {
    "warn-large-file-write": {
      "thresholdKb": 256
    }
  }
}
```

<Note>
  O handler do hook impõe um limite de 1 MB no stdin para 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 o Claude a confirmar antes de executar `npm publish`.

Sem parâmetros.

***

### `warn-background-process`

**Evento:** PreToolUse (Bash)\
**Padrão:** Instrui o 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 o 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

Define quais gerenciadores de pacotes o agente está autorizado a 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 o 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 vazia, a política é uma no-op. |
| `blocked` | string\[] | `[]`   | Nomes de gerenciadores adicionais a serem bloqueados 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 theme={null}
{
  "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 o Claude a usar `uv` ou `bun`. 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 ficam presos ou se comportam de forma inesperada.

### `warn-repeated-tool-calls`

**Evento:** PreToolUse (todas as ferramentas)\
**Padrão:** Instrui o 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 fim da sessão. Estas políticas são acionadas 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 provoca curto-circuito).

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 funciona de forma ligeiramente diferente entre os sete CLIs suportados, pois cada um expõe um contrato de hook diferente para "agente finalizado". O **resultado** é o mesmo — o agente não consegue parar enquanto um gate de fluxo de trabalho estiver falhando — mas a **mecânica** difere. 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 é acionado               | O que você vê                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Claude Code              | No mesmo loop do agente, imediatamente | O Claude continua trabalhando — corrige o problema e então tenta finalizar novamente. Nenhuma interrupção visível para você.                                                                                                                                                                                                                                                               |
| Codex                    | No mesmo loop do agente, imediatamente | Igual ao Claude.                                                                                                                                                                                                                                                                                                                                                                           |
| GitHub Copilot CLI       | No mesmo loop do agente, imediatamente | Igual ao Claude (usa o canal de retry `{decision:"block", reason}` do Copilot — verificado empiricamente no Copilot CLI 1.0.41).                                                                                                                                                                                                                                                           |
| Cursor Agent             | No mesmo loop do agente, imediatamente | Igual ao Claude (usa o canal `{followup_message}` do Cursor — limitado ao `loop_limit`, padrão 5 tentativas).                                                                                                                                                                                                                                                                              |
| OpenCode                 | No mesmo loop do 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**           | **O Pi para visivelmente** quando o gate é acionado — seu loop de agente sai e você retorna ao prompt. O gate é então acionado na próxima vez que você enviar um prompt: o failproofai antepõe uma diretiva `MANDATORY ACTION REQUIRED` ao prompt do sistema daquele turno, instruindo o LLM a concluir a etapa do 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 ele é acionado, o loop do 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. O failproofai desloca o gate para o evento `before_agent_start` do Pi (que é acionado após o próximo prompt do usuário), para que a verificação do 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, indexado pelo ID de sessão do Pi. O próximo prompt que você enviar no mesmo processo do Pi o consome: o LLM vê a diretiva `MANDATORY ACTION REQUIRED` no topo de seu prompt de sistema, faz o commit (ou push / abre o PR / aguarda o CI), e só então continua com sua solicitação. O motivo de negação capturado é de uso único — uma vez consumido, o gate é liberado.
  * O gate é limitado ao tempo de vida do processo do Pi. Se você der `Ctrl+C` no Pi ou sair entre 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 (matar o agente faz o gate ser perdido) — o Pi apenas torna isso mais visível porque o agente sai visivelmente antes do gate ser acionado.
  * Uma negação pendente também é limpa no `session_shutdown` por qualquer motivo (`new` / `resume` / `fork` / `quit`), então um gate obsoleto de uma sessão anterior não pode vazar para uma nova sessão iniciada no mesmo processo do Pi.

  Se você precisar do retry no mesmo loop no estilo Claude, execute suas políticas `Stop` em qualquer um dos outros cinco CLIs suportados. Estamos acompanhando o upstream do Pi para um futuro tipo Result no `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 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 de forma aberta 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 theme={null}
{
  "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 o Claude a criar um PR com `gh pr create`. Quando o PR está **merged**, a política permite (o trabalho foi entregue) e a mensagem sugere sair do branch (`git checkout main && git pull`).

Sem parâmetros.

<Note>
  Esta política requer que o [GitHub CLI](https://cli.github.com/) (`gh`) esteja instalado e autenticado.
  Execute `gh auth login` com um token de acesso pessoal que tenha o escopo `repo` para acesso de leitura a pull requests. Se `gh` não estiver instalado ou não estiver autenticado, a política falha de forma aberta e reporta o motivo ao Claude.
</Note>

***

### `require-no-conflicts-before-stop`

**Evento:** Stop\
**Padrão:** Nega a parada quando o branch atual não pode ser mesclado de forma limpa no branch base. A política primeiro confirma se há um PR `OPEN` no GitHub para o branch — sem um, não há alvo de merge a aplicar, então toda a política provoca curto-circuito para allow. Uma vez confirmado um PR `OPEN`, duas sondagens independentes são executadas:

1. **Local** — `git merge-tree --write-tree --name-only origin/<baseBranch> HEAD`. Em caso de conflito, a mensagem de deny nomeia os arquivos em conflito para que o Claude saiba exatamente o que resolver.
2. **GitHub** — reutiliza o resultado de `gh pr view --json mergeable,state` já obtido na verificação prévia. Detecta conflitos que um `origin/<baseBranch>` local desatualizado perderia (ex.: alguém lançou um PR conflitante em `main` desde o último fetch). Um resultado `CONFLICTING` nega. Um resultado `UNKNOWN` também nega e instrui o Claude a aguardar \~10 segundos e verificar novamente antes de tentar parar — isso previne falsos negativos enquanto o GitHub recomputa.

Ignora completamente (permite) quando: `gh` não está instalado, nenhum PR existe 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 de forma aberta quando `origin/<baseBranch>` está faltando localmente ou quando não há commits à frente do 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 um PR `OPEN` existe antes de executar qualquer sondagem de conflito — sem `gh`, a política provoca curto-circuito para allow. Execute `gh auth login` com um token de acesso pessoal 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 as verificações de CI estão falhando ou ainda em execução no branch atual. Verifica tanto execuções de workflow do GitHub Actions quanto verificações de bots de terceiros (ex.: CodeRabbit, SonarCloud, Codecov). Trata conclusões `skipped`, `cancelled` e `neutral` como não-falhando (o último cobre, por exemplo, alertas do Socket Security em PRs de contribuidores externos, onde o aplicativo 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 que o [GitHub CLI](https://cli.github.com/) (`gh`) esteja instalado e autenticado.
  Execute `gh auth login` com um token de acesso pessoal que tenha o escopo `repo` para acesso de leitura a execuções de workflow do Actions e à API de Checks. Se `gh` não estiver instalado ou não estiver autenticado, a política falha de forma aberta e reporta o motivo ao 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 painel.

```json theme={null}
{
  "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.