Guardrails & o esquema das regras (YAML)

Esta página é a referência do YAML que você cola nos editores de Governança. Cada editor (Organization Rules, User Type Rules, Profile Rules, Skill Group Rules) recebe um documento YAML — um ruleset — que descreve o que o agente pode ou não pode fazer naquele escopo. Aqui você encontra o esquema completo, um exemplo real comentado e as receitas para liberar ou bloquear cada dimensão.

Para o modelo mental (camadas, deny-wins, simulador), comece por Governança & políticas.

As duas regras que governam tudo

Antes do esquema, internalize estas duas regras — elas explicam todo o comportamento:

1. Ausência = herda · presença = explícito. Um bloco omitido (ex.: sem tool_policy:) significa "não tenho opinião" — o escopo herda o que vem das camadas acima. Um bloco presente, mesmo com listas vazias, é uma decisão explícita daquele escopo. É assim que você opta por participar (ou não) de cada dimensão.
2. Deny-wins: você só restringe. As camadas se combinam de modo que uma negação em qualquer escopo vence. Um escopo mais específico (perfil) pode apertar o que vem de um mais amplo (org), nunca afrouxar.

Valide e simule antes de salvar

O ciclo é sempre: cole o YAML → Validate → use o Policy Simulator para conferir o efeito deny-wins → salve. Veja Governança & políticas.

O envelope obrigatório

Todo ruleset começa com três chaves obrigatórias. Sem nenhum bloco de política, ele é válido — apenas não opina sobre nada.

schema: 1                    # versão do esquema — só 1 é aceito

metadata:
  name: "Baseline da organização"   # rótulo livre, obrigatório
  scope_type: org                   # a que camada este ruleset se aplica
  # scope_key: premium              # opcional (ver tabela abaixo)

policy:
  effect_mode: deny_wins     # único valor aceito

Campo	Obrigatório	Valores	O que faz
schema	✅	1	Versão do esquema. Só 1 existe.
metadata.name	✅	texto	Rótulo humano do ruleset (aparece na listagem).
metadata.scope_type	✅	org · user_type · skill_group · profile · skill · platform	Em que camada o ruleset vale. Define a precedência no merge.
metadata.scope_key	depende	texto	Para user_type, obrigatório: premium ou full. Para profile/skill_group, é um rótulo livre — o vínculo real é o editor onde você cola (você abre as regras daquele perfil/grupo).
policy.effect_mode	✅	deny_wins	Único modo aceito. Uma negação em qualquer camada vence.

platform é só leitura

O escopo platform é a linha de base da NNumbers e não é editável por você. Seus rulesets vivem em org, user_type, skill_group e profile.

Um exemplo completo, comentado

Este é o tipo de documento que você realmente cola — um baseline de organização que toca os blocos mais usados. Cada bloco abaixo é opcional; omita um bloco inteiro para herdar a camada acima.

schema: 1

metadata:
  name: "Baseline da organização"
  scope_type: org

policy:
  effect_mode: deny_wins

# ── Ferramentas ────────────────────────────────────────────────
# Contrato: o que está em denied vence sempre; allowed são exceções
# que passam apesar do default; default decide todo o resto.
tool_policy:
  default: allow            # tudo liberado, exceto o que for negado
  denied_tools:
    - Execute               # nesta org, o agente não roda shell/comandos
  allowed_tools: []         # sem exceções (o default já libera o resto)

# ── Execução ───────────────────────────────────────────────────
# Tri-estado: campo ausente = herda; true/false = decisão explícita.
execution_policy:
  allow_local_skill_execution: true   # skills locais (~/.imaginne/skills) podem rodar
  allow_outside_workspace: false      # o agente escreve só dentro do workspace

# ── Dados ──────────────────────────────────────────────────────
data_policy:
  allow_pii: false          # redige e-mail/telefone/CEP dos resultados de ferramentas
  classification: confidential

# ── Conteúdo ───────────────────────────────────────────────────
content_policy:
  language: pt-BR           # idioma forçado das respostas

Cuidado com & e * no YAML

O validador bloqueia âncoras e aliases. Na prática: evite o caractere & e evite linhas que começam com *, inclusive em comentários. Para "todas as ferramentas", prefira a palavra ALL ao curinga *.

Os blocos de política, campo a campo

Cada bloco abaixo é opcional. Os tipos bool são tri-estado: ausente = herda; true/false = explícito.

tool_policy — quais ferramentas o agente usa

O contrato canônico de liberação/bloqueio de ferramentas:

• denied_tools vence sempre. O que estiver aqui é recusado, ponto.
• allowed_tools são exceções que passam independente do default.
• default decide o resto e nunca é ignorado.

Campo	Tipo	Padrão	O que faz
default	allow · deny	allow	Destino de uma ferramenta que não está em nenhuma lista.
allowed_tools	lista	[]	Exceções que passam apesar do default. [ALL] = todas.
denied_tools	lista	[]	Sempre recusadas. [ALL] = nega todas.

Nomes de ferramenta aceitos: Read, Write, Edit, Execute, Grep, Glob, WebSearch — mais o curinga ALL (ou *). Qualquer outro nome é recusado na validação.

allowed_tools: [] não é "libera tudo"

A lista vazia sozinha não decide nada — quem decide é o default. [] + default: allow = libera tudo (menos o negado). [] + default: deny = nega tudo. E nenhuma ferramenta pode estar em allowed e denied ao mesmo tempo.

output_policy — quais artefatos o agente produz

Mesmo contrato de tool_policy, mas sobre tipos de artefato gerados.

Campo	Tipo	Padrão	O que faz
default	allow · deny	allow	Destino de um artefato fora das listas.
allowed_artifacts	lista	[]	Exceções que passam apesar do default.
denied_artifacts	lista	[]	Sempre recusados.

Artefatos válidos: software_source_code, automation_script, infrastructure_code, query_language, markup_document, template_document, formula_expression, data_transformation_snippet, pseudocode, structured_data_document.

execution_policy — execução de comandos e skills

Campo	Tipo	Padrão (herdado)	O que faz
allow_execution	bool	true	false = modo somente-leitura: ferramentas com efeito colateral (Bash/Execute/Edit/Write/Skill) são recusadas.
allow_simulation	bool	true	Permite o agente simular/ensaiar uma ação sem executá-la.
allow_suggestions	bool	true	Permite o agente sugerir comandos/ações em vez de executar.
allow_copy_paste_ready_output	bool	true	Permite produzir saída pronta para copiar e colar.
sandbox_only	bool	false	true = toda proposta de execução roda em sandbox.
allow_local_skill_execution	bool	true	false = skills locais (~/.imaginne/skills) são recusadas (o Imaginne emite local_skill_execution_denied_by_policy).
allow_outside_workspace	bool	false	true = libera escrever fora do workspace (ops destrutivas ainda pedem confirmação). Só vale em superfícies locais confiáveis (Desktop/TUI), nunca no runtime em nuvem.
allow_raw_shell	bool	false	true = libera o shell cru (Execute com linha de comando livre) nas execuções hospedadas — chat web, Cloud Runs e demais superfícies em nuvem.

Onde execution_policy se cruza com perfis e usuários

allow_local_skill_execution e allow_outside_workspace também aparecem como toggles em Perfis e como overrides por usuário em Usuários & papéis. allow_raw_shell segue o mesmo modelo — baseline no perfil, override por usuário —, resolvido no servidor. Tudo entra no mesmo merge deny-wins: o override por usuário pode apertar o baseline do perfil.

allow_raw_shell é concessão, não padrão

O padrão é negado: nas execuções hospedadas, o agente usa as ferramentas governadas, não uma linha de comando livre. Conceder shell cru a um usuário amplia bastante o que ele pode fazer no ambiente de execução — trate como exceção, com trilha de auditoria (Auditoria), e revogue quando a necessidade passar. A revogação vale imediatamente, inclusive para sessões já abertas.

data_policy — dados sensíveis

Campo	Tipo	O que faz
allow_pii	bool	false = o verificador de conteúdo redige PII (e-mail/telefone/CEP) dos resultados de ferramentas. Resultados de ferramentas Google (tool:google_*) têm isenção de escopo; segredos/CPF/CNPJ continuam sendo redigidos.
allow_data_export	bool	Permite o agente exportar dados para fora.
allow_internal_data_access	bool	Permite acesso a dados internos.
allow_sensitive_data_summary	bool	Permite resumir dados sensíveis.
allow_sensitive_data_extraction	bool	Permite extrair dados sensíveis.
allow_cross_document_aggregation	allow · limited · deny	Quanto o agente pode cruzar informação entre documentos.
redact_sensitive_fields	bool	true = redige os campos listados em sensitive_fields.
sensitive_fields	lista	Nomes de campos a redigir.
classification	public · internal · confidential · restricted	Nível de sensibilidade dos dados desta camada (ordem crescente de restrição).

content_policy — forma do conteúdo gerado

Campo	Tipo	O que faz
language	texto	Idioma forçado das respostas (ex.: pt-BR).
tone	texto	Tom desejado.
require_disclaimers	bool	Exige um aviso na resposta.
disclaimer_text	texto	O texto do aviso.
max_response_length	inteiro	Teto de tamanho da resposta.
forbidden_topics	lista	Assuntos proibidos.
require_references	bool	Exige citar fontes/referências.

interaction_policy — como o agente interage

Campo	Tipo	O que faz
formality	texto	Nível de formalidade.
require_summary	bool	Exige um resumo ao final.
step_by_step	bool	Exige raciocínio/entrega passo a passo.

model_policy não é escrito aqui

A allow-list de modelos, modelo padrão e fonte de credencial não são autorais no YAML do ruleset — o resolver os injeta na política compilada a partir da BYOK e das atribuições de modelo. Não adicione um bloco model_policy: ao seu YAML.

Como liberar e como bloquear (receitas)

Cada receita abaixo é um bloco que entra no envelope obrigatório.

Liberar tudo (org permissiva):

tool_policy:
  default: allow
  denied_tools: []

Bloquear uma ferramenta específica, mantendo o resto:

tool_policy:
  default: allow
  denied_tools: [Execute]    # tira só o shell

Liberar só um conjunto (allowlist somente-leitura):

tool_policy:
  default: deny
  allowed_tools: [Read, Grep, Glob, WebSearch]

Bloquear todas as ferramentas:

tool_policy:
  default: deny
  denied_tools: [ALL]        # ou simplesmente default: deny com allowed: []

Modo somente-leitura de verdade (recusa Bash/Edit/Write/Skill):

execution_policy:
  allow_execution: false

Bloquear PII nos resultados de ferramentas:

data_policy:
  allow_pii: false

Travar exportação e cruzamento de dados:

data_policy:
  allow_data_export: false
  allow_cross_document_aggregation: deny
  classification: restricted

Forçar idioma e um aviso obrigatório:

content_policy:
  language: pt-BR
  require_disclaimers: true
  disclaimer_text: "Conteúdo gerado por IA; revise antes de usar."

Exigir sandbox para toda execução:

execution_policy:
  sandbox_only: true

Por escopo: o que colar em cada editor

O mesmo esquema, mudando só scope_type (e, no caso de user_type, o scope_key). Você cola cada um no editor correspondente da Governança.

Organização (Organization Rules) — vale para todos:

schema: 1
metadata:
  name: "Baseline da organização"
  scope_type: org
policy:
  effect_mode: deny_wins
tool_policy:
  default: allow
  denied_tools: [Execute]

Tipo de usuário (User Type Rules) — scope_key obrigatório (premium ou full):

schema: 1
metadata:
  name: "Premium — somente leitura"
  scope_type: user_type
  scope_key: premium
policy:
  effect_mode: deny_wins
tool_policy:
  default: deny
  allowed_tools: [Read, Grep, Glob, WebSearch]
execution_policy:
  allow_execution: false

Perfil (Profile Rules) — o vínculo é o editor do perfil que você abriu:

schema: 1
metadata:
  name: "Financeiro — sem exportar dados"
  scope_type: profile
  scope_key: financeiro
policy:
  effect_mode: deny_wins
data_policy:
  allow_data_export: false
  classification: restricted

Grupo de skills (Skill Group Rules):

schema: 1
metadata:
  name: "Jurídico — disclaimer obrigatório"
  scope_type: skill_group
  scope_key: juridico
policy:
  effect_mode: deny_wins
content_policy:
  require_disclaimers: true
  disclaimer_text: "Conteúdo gerado por IA; valide com um advogado."

Como as camadas se combinam (deny-wins, em detalhe)

Quando vários rulesets se aplicam à mesma sessão, eles são combinados na ordem de precedência (platform → org → user_type → skill_group → profile → skill). Cada dimensão tem uma regra de fusão:

Dimensão	Como combina entre escopos
denied_tools · denied_artifacts · forbidden_topics · sensitive_fields	União — toda negação de qualquer camada permanece.
allowed_tools · allowed_artifacts	Interseção — cada camada só pode estreitar a lista.
default (tool/output)	Se qualquer camada usa deny, o resultado é deny.
allow_* (execução e dados)	false vence — basta uma camada negar.
require_* · sandbox_only · redact_sensitive_fields	true vence — basta uma camada exigir.
classification	A mais restritiva vence (public < internal < confidential < restricted).
allow_cross_document_aggregation	A mais restritiva vence (allow < limited < deny).
max_response_length	O menor valor vence.
language · tone · formality	Prevalece o valor da camada mais ampla que o define; camadas mais específicas não o sobrescrevem.

A consequência prática: um perfil nunca consegue reabrir algo que a org fechou. Para liberar, você relaxa na camada mais ampla; para restringir, aperta em qualquer camada.

Validação (o botão Validate)

O editor recusa o ruleset se:

• schema ≠ 1.
• metadata.name vazio, ou scope_type inválido.
• scope_type: user_type sem scope_key igual a premium ou full.
• policy.effect_mode ≠ deny_wins.
• Houver chave desconhecida (modo estrito — um campo escrito errado é erro, não é ignorado).
• O documento passar de 64 KB.
• Houver âncora/alias YAML (caractere &, ou linha começando com *).
• tool_policy.default / output_policy.default fora de allow/deny.
• A mesma ferramenta/artefato aparecer em allowed e denied.
• Um nome de ferramenta ou artefato fora das listas válidas.
• classification fora de public · internal · confidential · restricted.

Limite de rulesets ativos

Uma organização pode ter no máximo 50 rulesets ativos. Arquive os que não usa mais (o histórico de versões é preservado).

Veja também

🛡️Governança & políticas

O dashboard, os editores e o simulador de política.

Abrir →🏢Organizações & políticas

O modelo mental das camadas e do deny-wins.

Abrir →🎭Perfis

A camada mais específica — e onde os toggles de execução vivem.

Abrir →🗂️Grupos de skills

O escopo entre organização e perfil.

Abrir →