> ## 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 personalizadas

> Escreva uma política para um modo de falha exclusivo do seu fluxo de trabalho de agente.

Crie um arquivo com extensão `policies.js`, `policies.mjs` ou `policies.ts` dentro de `.failproofai/policies/`. Arquivos de convenção são carregados automaticamente nos escopos de projeto e usuário.

## Teste a política antes de publicar na nuvem

<Tabs>
  <Tab title="Dashboard">
    1. Instale a política personalizada em uma máquina de teste e acione tanto uma ação correspondente quanto uma não correspondente legítima.
    2. Vá em **Observe → policy** e compare as duas decisões.
    3. Abra cada sessão vinculada e verifique se o payload do evento contém evidências suficientes para a regra.
    4. Quando o comportamento estiver correto, mova o código revisado para **Admin → policy editor** e publique uma versão.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    failproofai policies --install --custom ./security.policies.ts \
      --cli claude --scope project
    failproofai policies
    ```

    Arquivos de convenção em `.failproofai/policies/` são carregados sem `--custom`. Mantenha um comando de instalação explícito no CI quando a validação deve falhar em caso de módulo inválido.
  </Tab>
</Tabs>

```ts theme={null}
import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "protect-production-paths",
  description: "Block writes to production configuration",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
    const path = String(ctx.toolInput?.file_path ?? "").replaceAll("\\", "/");
    if (path.split("/").includes("production")) {
      return deny("Writes to production configuration require approval.");
    }
    return allow();
  },
});
```

Isso corresponde a `production/config.yml`, `/srv/production/config.yml`, `/srv/production` e `C:\\production\\config.yml` tanto para `Write` quanto para `Edit`. Não corresponde a nomes como `production-backup`, pois `production` deve ser um segmento completo do caminho.

Valide e instale um arquivo explícito:

```bash theme={null}
failproofai policies --install --custom ./security.policies.ts
```

O contexto da política inclui o tipo de evento, payload normalizado, nome e entrada da ferramenta, metadados da sessão, parâmetros e o CLI de origem quando disponível.

## Teste os caminhos de falha

Execute a validação após alterar o arquivo de entrada ou qualquer módulo local que ele importe:

```bash theme={null}
failproofai policies --install --custom ./security.policies.ts --scope project
```

O caminho de CLI estrito falha para arquivos ausentes, erros de sintaxe, importações não resolvidas, exceções em nível superior e timeouts de carregamento de módulo. No momento da aplicação, um arquivo personalizado inválido é registrado em log e ignorado para que as políticas integradas possam continuar. Trate qualquer aviso de carregamento como uma perda de aplicação esperada e monitore-o nos logs de produção.

Use nomes globalmente únicos em políticas explícitas, de convenção e gerenciadas pela nuvem. Mantenha as funções de política determinísticas, limite chamadas externas com timeouts curtos e retorne um `allow`, `instruct` ou `deny` intencional em todos os caminhos.

<Warning>
  Uma política personalizada é código de aplicação. Teste campos ausentes, nomes de ferramentas alternativos e entradas malformadas — não apenas a correspondência esperada.
</Warning>