> ## Documentation Index
> Fetch the complete documentation index at: https://exosphere-auto-translate-docs-20260624-1149.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Políticas Integradas

> Todas as 39 políticas integradas que detectam modos comuns de falha em agentes

failproofai vem com 39 políticas integradas que detectam modos comuns de falha em 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 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 contexto adicional ao agente para que ele possa se autocorrigir.
* **`sanitize-`** — remove dados sensíveis da saída de ferramentas antes que o agente os visualize.

### Namespaces

Toda política reside em um slot `<namespace>/<name>`. 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.

Em 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 contiver `/`, 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 Claude recebe, fornecendo orientações práticas 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`.

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 evita 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 semelhantes de exclusão recursiva.

**Parâmetros:**

| Parâmetro    | Tipo       | Padrão | Descrição                                                           |
| ------------ | ---------- | ------ | ------------------------------------------------------------------- |
| `allowPaths` | `string[]` | `[]`   | Caminhos que são seguros para excluir recursivamente (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 semelhantes.

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.

***

## 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, cada 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 de [`block-sudo`](#block-sudo): os tokens são comparados com argv analisado, `*` é um caractere curinga para um token, e qualquer comando contendo um operador shell isolado (`&&`, `||`, `|`, `;`) ou um token com metacaracteres shell embutidos é rejeitado antes da verificação da 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 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 do CLI `aws`.

**Parâmetros:**

| Parâmetro       | Tipo       | Padrão | Descrição                                           |
| --------------- | ---------- | ------ | --------------------------------------------------- |
| `allowPatterns` | `string[]` | `[]`   | Prefixos de comandos do 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 do 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 do CLI `az` (Azure).

**Parâmetros:**

| Parâmetro       | Tipo       | Padrão | Descrição                                          |
| --------------- | ---------- | ------ | -------------------------------------------------- |
| `allowPatterns` | `string[]` | `[]`   | Prefixos de comandos do 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 do CLI `gh` que alteram 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 abrangidos 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 para permitir 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 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 que a saída seja 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 do arquivo, etc.

Não bloqueia `.envrc` ou outros arquivos relacionados ao ambiente — apenas arquivos nomeados exatamente `.env`.

Sem parâmetros.

***

### `protect-env-vars`

**Evento:** PreToolUse (Bash)\
**Padrão:** Nega comandos que exibem 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 do diretório raiz do projeto. O limite é definido por `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 depois que Claude entra em um subdiretório com `cd`.

**Parâmetros:**

| Parâmetro    | Tipo       | Padrão | Descrição                                                                                     |
| ------------ | ---------- | ------ | --------------------------------------------------------------------------------------------- |
| `allowPaths` | `string[]` | `[]`   | Prefixos de caminhos absolutos que são permitidos mesmo se estiverem 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 gravações 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) para bloquear. |

**Exemplo:**

```json theme={null}
{
  "policyParams": {
    "block-secrets-write": {
      "additionalPatterns": [".token", ".secret"]
    }
  }
}
```

***

## Git

Previne pushes acidentais, force-pushes e erros de branch que são 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 para os quais não é possível fazer push diretamente. |

**Exemplo:**

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

<Tip>
  Para permitir push em todas as 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`. A criação e troca de branches (`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 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 da 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 Claude a proceder 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 preparado ao executar `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 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 adicional 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 gravar arquivos maiores que 1024 KB.

**Parâmetros:**

| Parâmetro     | Tipo     | Padrão | Descrição                                                                   |
| ------------- | -------- | ------ | --------------------------------------------------------------------------- |
| `thresholdKb` | `number` | `1024` | Limite de tamanho do 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` com 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 não tem efeito. |
| `blocked` | string\[] | `[]`   | Nomes de gerenciadores adicionais para bloquear além da lista integrada (ex.: `['pdm', 'pipx']`).                                                             |

A lista de bloqueio integrada inclui: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Use `blocked` para adicionar gerenciadores não presentes 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 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 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 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 (negação causa 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 do Stop funciona de forma ligeiramente diferente entre os sete CLIs suportados, pois cada um expõe um contrato de hook de "agente finalizado" diferente. O **resultado** é o mesmo — o agente não consegue parar enquanto uma condição 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 | 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 contra o Copilot CLI 1.0.41).                                                                                                                                                                                                                                                  |
| Cursor Agent             | No mesmo loop do agente, imediatamente | Igual ao Claude (usa o canal `{followup_message}` do Cursor — limitado por `loop_limit`, padrão de 5 tentativas).                                                                                                                                                                                                                                                                       |
| Gemini CLI               | No mesmo loop do agente, imediatamente | Igual ao Claude (usa o canal `{decision:"block", reason}` do Gemini em `AfterAgent`).                                                                                                                                                                                                                                                                                                   |
| OpenCode                 | No mesmo loop do agente, imediatamente | Igual ao Claude (usa a chamada SDK `client.session.prompt(...)` do OpenCode roteada via `hookSpecificOutput.additionalContext`).                                                                                                                                                                                                                                                        |
| **Pi (pi-coding-agent)** | **Próximo turno do usuário**           | **Pi para visivelmente** quando o gate é acionado — seu loop de agente encerra e você retorna ao prompt. O gate então é acionado na próxima vez que você envia um prompt: o failproofai prefixa uma diretiva `MANDATORY ACTION REQUIRED` ao system prompt 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 (equivalente ao hook `Stop` do Claude no upstream) não possui tipo Result — quando ele é acionado, o loop do agente do Pi já encerrou. O Pi não pode ser forçado a tentar novamente o mesmo loop como Claude / Copilot / Cursor / Gemini / OpenCode. O failproofai desloca o gate para o evento `before_agent_start` do Pi (que é acionado após o próximo prompt do usuário), de modo que a verificação do fluxo de trabalho ainda é 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 em memória, indexado 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 de seu system prompt, faz o commit (ou push / abre o PR / aguarda o CI) e só então continua com sua solicitação. O motivo da negação capturado é de uso único — após ser consumido, o gate é liberado.
  * O gate é limitado ao tempo de vida do processo Pi. Se você pressionar `Ctrl+C` no Pi ou sair entre os turnos, a entrada em memória é descartada junto com o processo e o gate é perdido. Claude, Copilot, Cursor, Gemini e OpenCode têm o mesmo comportamento (encerrar o agente faz o gate ser perdido) — o Pi apenas o torna mais visível porque o agente encerra visivelmente antes de o gate ser acionado.
  * Uma negação pendente também é apagada em `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 Pi.

  Se você precisar do retry no mesmo loop ao estilo Claude, execute suas políticas `Stop` em qualquer um dos outros seis CLIs suportados. Estamos acompanhando o Pi upstream em busca de um futuro tipo Result em `AgentEndEvent` que nos permita fechar essa lacuna.
</Note>

### `require-commit-before-stop`

**Evento:** Stop\
**Padrão:** Nega a parada quando há alterações não commitadas (arquivos modificados, preparados 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 a branch atual não possui branch de rastreamento remoto. Sugere `git push -u` para criar uma branch de rastreamento, se necessário. Falha abertamente 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 a 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 sair da branch (`git checkout main && git pull`).

Sem parâmetros.

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

***

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

**Evento:** Stop\
**Padrão:** Nega a parada quando a branch atual não pode ser mergeada de forma limpa na branch base. A política primeiro confirma que há um PR `OPEN` no GitHub para a branch — sem ele, não há destino de merge para impor, então toda a política causa 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 lista os arquivos conflitantes 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. Detecta 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 verificar novamente antes de tentar parar — isso evita falsos negativos enquanto o GitHub recalcula.

Ignora completamente (permite) quando: `gh` não está instalado, não existe PR para a branch, o estado do PR não é `OPEN` (ex.: `MERGED`, `CLOSED`), ou `gh pr view` retorna saída não parseável. Também falha abertamente quando `origin/<baseBranch>` está ausente localmente ou quando não há commits à frente da base — esses fallbacks da Camada 1 ainda consultam a mergeabilidade 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 sondagem de conflito — sem `gh`, a política
  causa curto-circuito para allow. Execute `gh auth login` com um personal access token que tenha
  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 na branch atual. Verifica tanto as execuções de workflow do GitHub Actions quanto verificações de bots de terceiros (ex.: CodeRabbit, SonarCloud, Codecov). Trata as conclusões `skipped`, `cancelled` e `neutral` como não-falhas (esta última 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 a instalação e autenticação do [GitHub CLI](https://cli.github.com/) (`gh`).
  Execute `gh auth login` com um personal access token que tenha escopo `repo` para acesso de leitura a
  execuções de workflow do Actions e à API de Verificações. Se `gh` não estiver instalado ou autenticado, a política falha abertamente e informa o motivo ao Claude.
</Note>

***

***

## Desabilitando políticas individuais

Remova uma política específica de `enabledPolicies` em sua configuração, ou desative-a na aba Policies 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 em `policyParams` para elas.