Políticas personalizadas

Políticas personalizadas transformam um padrão de falha encontrado nos seus traces ou auditorias em uma decisão que é executada enquanto o agente trabalha. Uma política pode permitir uma ação, fornecer orientação ao agente ou bloquear a ação antes que ela cause um novo incidente. Use uma política personalizada quando o comportamento depende das suas ferramentas, caminhos, comandos, ambientes ou regras operacionais. Consulte primeiro o pacote de políticas do Failproof AI para não recriar um controle já existente.

Criar uma política personalizada

Dashboard
CLI

Acesse Admin → editor de políticas, selecione Nova política e descreva a falha que você deseja prevenir.
Adicione o código-fonte da política, depois teste as correspondências esperadas e os casos seguros que não devem corresponder no editor. Resolva todos os erros de validação.
Salve o rascunho e selecione Publicar versão para criar uma versão imutável.
Acesse Admin → enforcement, implante a versão em uma máquina de teste no modo observe e verifique suas decisões em Observe → policy antes de aplicá-la.

Crie .failproofai/policies/checkout-policies.ts. O nome do arquivo deve terminar em policies.js, policies.mjs ou policies.ts.
Registre uma ou mais políticas com customPolicies.add().
Valide e instale o arquivo com failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project.
Acione uma ação que deve corresponder e uma ação segura. Execute failproofai policies e inspecione as decisões atribuídas em Observe → policy.

Comece com uma regra restrita

Esta política bloqueia comandos destrutivos do Kubernetes somente quando o comando tem como alvo o ambiente de produção. Tudo fora desse padrão de falha exato retorna allow().

import { customPolicies, allow, deny } from "failproofai";

const DESTRUCTIVE_KUBECTL = /\bkubectl\s+(delete|replace)\b/i;
const PRODUCTION_TARGET = /(?:--context|--namespace|-n)\s+(prod|production)\b/i;

customPolicies.add({
  name: "block-destructive-production-kubectl",
  description: "Block destructive Kubernetes commands against production",
  match: { events: ["PreToolUse"] },
  fn: async ({ toolName, toolInput }) => {
    if (toolName !== "Bash") return allow();

    const command = String(toolInput?.command ?? "");
    if (!DESTRUCTIVE_KUBECTL.test(command)) return allow();
    if (!PRODUCTION_TARGET.test(command)) return allow();

    return deny(
      "Destructive production Kubernetes commands require the approved deployment workflow.",
    );
  },
});

Boas políticas são restritas o suficiente para serem explicadas em uma única frase. Corresponda à ação observável — não à intenção que você espera que o agente tenha — e retorne allow() assim que a regra não se aplicar.

Escolha uma decisão

Helper	Resultado	Quando usar
`allow(reason?)`	A operação continua.	A política não se aplica ou a ação é segura.
`instruct(reason)`	A operação continua com orientação quando o harness suporta.	Você quer direcionar o agente para uma abordagem melhor sem impor uma invariante.
`deny(reason)`	A operação é bloqueada quando o evento e o harness suportam bloqueio.	A ação não deve prosseguir.

Escreva o motivo para o agente que precisará se recuperar. Explique o que foi detectado e o que ele deve fazer em vez disso.

Não use instruct() para um limite de segurança. A entrega de orientações varia conforme o harness do agente. Use deny() quando a ação deve ser impedida.

Objeto de política

customPolicies.add({
  name: "policy-name",
  description: "What this policy prevents",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => allow(),
});

Campo	Obrigatório	Descrição
`name`	Sim	Identificador estável da política. Mantenha os nomes únicos entre arquivos.
`description`	Não	Descrição legível exibida nas listagens de políticas e nas decisões.
`match.events`	Não	Tipos de eventos que invocam a política. Omitir `match` faz com que ela seja invocada para todos os eventos disponíveis.
`fn`	Sim	Função síncrona ou assíncrona que retorna um resultado `allow`, `instruct` ou `deny`.

Filtre as ferramentas dentro de fn. O campo match.toolNames não faz parte do tipo público de política personalizada.

Contexto da política

Toda política recebe um PolicyContext.

Campo	Tipo	O que contém
`eventType`	`HookEventType`	Evento normalizado sendo avaliado no momento.
`toolName`	`string \| undefined`	Nome canônico da ferramenta, como `Bash`, `Read`, `Write` ou `Edit`.
`toolInput`	`Record<string, unknown> \| undefined`	Entrada canônica para a chamada de ferramenta atual.
`payload`	`Record<string, unknown>`	Payload completo do evento normalizado.
`session`	`SessionMetadata \| undefined`	ID da sessão, diretório de trabalho, caminho do transcript, modo de permissão e metadados do harness quando disponíveis.
`cli`	`string \| undefined`	Harness do agente de origem, como `claude`, `codex` ou `cursor`.
`params`	`Record<string, unknown>`	Parâmetros de políticas integradas. Políticas personalizadas atualmente recebem um objeto vazio.

Trate todos os valores opcionais como genuinamente opcionais. Versões de agentes e tipos de eventos nem sempre fornecem os mesmos campos.

Entradas comuns de ferramentas

O Failproof AI normaliza ferramentas comuns entre os harnesses suportados para que uma política geralmente possa usar um único formato de entrada.

Ferramenta	Campos comuns
`Bash`	`command`
`Read`	`file_path`
`Write`	`file_path`, `content`
`Edit`	`file_path`, `old_string`, `new_string`
`Grep`	`pattern`, `path`

Use coerção defensiva porque os valores de entrada das ferramentas são tipados como unknown:

const command = String(ctx.toolInput?.command ?? "");
const filePath = String(ctx.toolInput?.file_path ?? "");

Escolha o evento

Evento	Quando é executado	Uso típico
`PreToolUse`	Antes de uma ferramenta ser executada.	Bloquear ou orientar comandos, escritas, leituras e ações externas.
`PostToolUse`	Após uma ferramenta retornar.	Inspecionar resultados antes de chegarem ao agente. Um deny bloqueia o resultado inteiro; não redige campos selecionados.
`PermissionRequest`	Quando o agente solicita permissão.	Aplicar regras de permissão específicas da organização.
`UserPromptSubmit`	Antes de um prompt enviado continuar.	Rejeitar instruções proibidas ou adicionar orientações de fluxo de trabalho.
`Stop`	Quando o agente tenta finalizar.	Exigir uma condição de conclusão alcançável, como uma etapa de verificação local.
`SubagentStop`	Quando um subagente tenta finalizar.	Controlar o trabalho delegado antes de retorná-lo ao agente pai.
`SessionStart` / `SessionEnd`	Em limites de sessão.	Registrar ou verificar estado no nível da sessão.

A disponibilidade dos eventos e o comportamento de bloqueio dependem do harness do agente. Consulte Harnesses de agentes antes de depender de um evento em uma frota heterogênea.

Todos os nomes de eventos de política

SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure, Notification, SubagentStart, SubagentStop, TaskCreated, TaskCompleted, Stop, StopFailure, TeammateIdle, InstructionsLoaded, ConfigChange, CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove, PreCompact, PostCompact, Elicitation, ElicitationResult, UserPromptExpansion, PostToolBatch e Setup.

Padrões comuns de políticas

Bloquear escritas em caminhos protegidos

import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "block-generated-file-edits",
  description: "Require generated files to be changed through their generator",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();

    const filePath = String(ctx.toolInput?.file_path ?? "");
    if (!/(^|\/)(dist|generated)\//.test(filePath)) return allow();

    return deny("Edit the source and run the generator instead of changing generated output.");
  },
});

Fornecer orientação sem bloqueio

import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "prefer-reviewed-deploy-command",
  description: "Guide agents toward the reviewed deployment wrapper",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();

    const command = String(ctx.toolInput?.command ?? "");
    if (!/^kubectl\s+apply\b/.test(command.trim())) return allow();

    return instruct("Use ./scripts/deploy-reviewed instead of invoking kubectl directly.");
  },
});

Controlar a conclusão da sessão

import { execFileSync } from "node:child_process";
import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "require-clean-typecheck",
  description: "Require the project typecheck to pass before the agent finishes",
  match: { events: ["Stop"] },
  fn: async (ctx) => {
    const cwd = ctx.session?.cwd;
    if (!cwd) return allow();

    try {
      execFileSync("bunx", ["tsc", "--noEmit"], {
        cwd,
        stdio: "ignore",
        timeout: 8_000,
      });
      return allow();
    } catch {
      return deny("Fix the typecheck errors before finishing the task.");
    }
  },
});

Um evento Stop negado pode fazer o agente tentar novamente. Aplique a condição somente se o agente conseguir satisfazê-la no ambiente atual, e defina limites de tempo para todo subprocesso ou chamada de rede.

Carregar arquivos de política

Arquivos de convenção

Arquivos de convenção são carregados automaticamente:

<project>/.failproofai/policies/security-policies.ts
~/.failproofai/policies/personal-policies.mjs

Os diretórios de políticas do projeto e do usuário são carregados.
Os arquivos são carregados em ordem alfabética dentro de cada diretório.
O arquivo deve terminar em policies.js, policies.mjs ou policies.ts.
Múltiplas chamadas customPolicies.add() em um mesmo arquivo são suportadas.
Importações relativas de módulos locais são suportadas.
As políticas do projeto podem ser versionadas para que as mesmas regras acompanhem o repositório.

Arquivos explícitos

Use caminhos explícitos quando a validação ou configuração precisar nomear diretamente o arquivo de entrada:

failproofai policies --install \
  --custom ./security.policies.ts \
  --custom ./workflow.policies.ts \
  --scope project

Os arquivos explícitos são carregados primeiro, seguidos pelos arquivos de convenção do projeto e depois pelos do usuário. Um arquivo descoberto por ambos os caminhos é carregado apenas uma vez.

Validar e testar

A validação executa o módulo pelo carregador de produção e confirma que ele registra pelo menos uma política.

failproofai policies --install \
  --custom ./.failproofai/policies/checkout-policies.ts \
  --scope project
failproofai policies

A validação detecta arquivos ausentes, erros de sintaxe, importações não resolvidas, exceções no nível superior e timeouts de carregamento de módulo. Ela não comprova que a lógica de correspondência está correta. Teste pelo menos estes casos:

Uma ação que deve corresponder e produzir o motivo de política esperado.
Uma ação próxima, mas segura, que deve retornar allow().
Campos de ferramenta ausentes ou malformados.
Sintaxe alternativa de comandos, caminhos, aspas, capitalização e espaços em branco.
Um subprocesso ou dependência de rede indisponível.

Atribua o resultado à sua política personalizada em Observe → policy. Um teste bloqueado não é suficiente se uma política integrada diferente tomou a decisão.

Comportamento em tempo de execução

As políticas integradas são avaliadas antes das políticas personalizadas.
O primeiro deny interrompe a avaliação das demais políticas.
Múltiplos resultados instruct podem ser combinados quando nenhuma políticanega o evento.
Uma função de política tem um prazo de execução de 10 segundos.
Uma exceção lançada ou timeout é registrado e tratado como allow().
Um arquivo de convenção que falha ao carregar é ignorado; os outros arquivos personalizados e as políticas integradas continuam funcionando.
O carregamento de módulo no nível superior também tem um prazo de 10 segundos.
O modo observe em nuvem executa a política, mas registra uma decisão diferente de allow sem aplicá-la.

Mantenha os módulos de política determinísticos e rápidos. Evite chamadas de rede ou inicialização de servidores no nível superior. Delimite o trabalho dentro de fn, trate falhas de dependência e decida conscientemente se essa falha deve permitir ou bloquear a operação.

Exportações da API

Exportação	Finalidade
`customPolicies.add(policy)`	Registra uma política personalizada quando o módulo é carregado.
`allow(reason?)`	Permite a operação.
`instruct(reason)`	Permite a operação e fornece orientação onde suportado.
`deny(reason)`	Bloqueia a operação onde suportado.
`getCustomHooks()`	Retorna as políticas atualmente registradas no registro do módulo.
`clearCustomHooks()`	Limpa esse registro, principalmente para testes e carregadores.

O TypeScript exporta PolicyContext, PolicyResult, CustomHook, PolicyDecision e PolicyFunction.

Implantar políticas personalizadas

Publique uma versão, implante-a no modo observe, verifique as decisões e passe para a aplicação.

Connect your agents

Reference

Políticas personalizadas

Criar uma política personalizada

Comece com uma regra restrita

Escolha uma decisão

Objeto de política

Contexto da política

Entradas comuns de ferramentas

Escolha o evento

Padrões comuns de políticas

Bloquear escritas em caminhos protegidos

Fornecer orientação sem bloqueio

Controlar a conclusão da sessão

Carregar arquivos de política

Arquivos de convenção

Arquivos explícitos

Validar e testar

Comportamento em tempo de execução

Exportações da API

Implantar políticas personalizadas

​Criar uma política personalizada

​Comece com uma regra restrita

​Escolha uma decisão

​Objeto de política

​Contexto da política

​Entradas comuns de ferramentas

​Escolha o evento

​Padrões comuns de políticas

​Bloquear escritas em caminhos protegidos

​Fornecer orientação sem bloqueio

​Controlar a conclusão da sessão

​Carregar arquivos de política

​Arquivos de convenção

​Arquivos explícitos

​Validar e testar

​Comportamento em tempo de execução

​Exportações da API

Implantar políticas personalizadas

Criar uma política personalizada

Comece com uma regra restrita

Escolha uma decisão

Objeto de política

Contexto da política

Entradas comuns de ferramentas

Escolha o evento

Padrões comuns de políticas

Bloquear escritas em caminhos protegidos

Fornecer orientação sem bloqueio

Controlar a conclusão da sessão

Carregar arquivos de política

Arquivos de convenção

Arquivos explícitos

Validar e testar

Comportamento em tempo de execução

Exportações da API