Guardrails & the rules schema (YAML)

This page is the YAML reference for what you paste into the Governance editors. Each editor (Organization Rules, User Type Rules, Profile Rules, Skill Group Rules) takes a YAML document — a ruleset — that describes what the agent can and cannot do in that scope. Here you'll find the complete schema, a real commented example, and the recipes to allow or block each dimension.

For the mental model (layers, deny-wins, simulator), start with Governance & policies.

The two rules that govern everything

Before the schema, internalize these two rules — they explain all the behavior:

1. Absent = inherit · present = explicit. An omitted block (e.g., no tool_policy:) means "I have no opinion" — the scope inherits what comes from the layers above. A present block, even with empty lists, is an explicit decision by that scope. That's how you opt in to (or out of) each dimension.
2. Deny-wins: you can only restrict. The layers combine so that a denial in any scope wins. A more specific scope (profile) can tighten what comes from a broader one (org), but never loosen it.

Validate and simulate before saving

The cycle is always: paste the YAML → Validate → use the Policy Simulator to check the deny-wins effect → save. See Governance & policies.

The required envelope

Every ruleset starts with three required keys. With no policy blocks at all, it is valid — it just doesn't have an opinion about anything.

schema: 1                    # schema version — only 1 is accepted

metadata:
  name: "Organization baseline"   # free-form label, required
  scope_type: org                 # which layer this ruleset applies to
  # scope_key: premium            # optional (see table below)

policy:
  effect_mode: deny_wins     # the only accepted value

Field	Required	Values	What it does
schema	✅	1	Schema version. Only 1 exists.
metadata.name	✅	text	Human label for the ruleset (appears in the listing).
metadata.scope_type	✅	org · user_type · skill_group · profile · skill · platform	Which layer the ruleset applies to. Sets the precedence in the merge.
metadata.scope_key	depends	text	For user_type, required: premium or full. For profile/skill_group, it's a free-form label — the real binding is the editor you paste into (you open the rules of that profile/group).
policy.effect_mode	✅	deny_wins	The only accepted mode. A denial in any layer wins.

platform is read-only

The platform scope is the NNumbers baseline and is not editable by you. Your rulesets live in org, user_type, skill_group, and profile.

A complete, commented example

This is the kind of document you actually paste — an organization baseline that touches the most-used blocks. Each block below is optional; omit an entire block to inherit the layer above.

schema: 1

metadata:
  name: "Organization baseline"
  scope_type: org

policy:
  effect_mode: deny_wins

# ── Tools ──────────────────────────────────────────────────────
# Contract: whatever is in denied always wins; allowed are exceptions
# that pass despite the default; default decides everything else.
tool_policy:
  default: allow            # everything allowed, except what's denied
  denied_tools:
    - Execute               # in this org, the agent doesn't run shell/commands
  allowed_tools: []         # no exceptions (the default already allows the rest)

# ── Execution ──────────────────────────────────────────────────
# Tri-state: field absent = inherit; true/false = explicit decision.
execution_policy:
  allow_local_skill_execution: true   # local skills (~/.imaginne/skills) may run
  allow_outside_workspace: false      # the agent writes only inside the workspace

# ── Data ───────────────────────────────────────────────────────
data_policy:
  allow_pii: false          # redacts email/phone/postal code from tool results
  classification: confidential

# ── Content ────────────────────────────────────────────────────
content_policy:
  language: en-US           # forced response language

Watch out for & and * in YAML

The validator blocks anchors and aliases. In practice: avoid the & character and avoid lines that start with *, including in comments. For "all tools", prefer the word ALL over the * wildcard.

The policy blocks, field by field

Each block below is optional. The bool types are tri-state: absent = inherit; true/false = explicit.

tool_policy — which tools the agent uses

The canonical contract for allowing/blocking tools:

• denied_tools always wins. Whatever is here is refused, period.
• allowed_tools are exceptions that pass regardless of default.
• default decides the rest and is never ignored.

Field	Type	Default	What it does
default	allow · deny	allow	Destination of a tool that isn't in any list.
allowed_tools	list	[]	Exceptions that pass despite the default. [ALL] = all.
denied_tools	list	[]	Always refused. [ALL] = deny all.

Accepted tool names: Read, Write, Edit, Execute, Grep, Glob, WebSearch — plus the ALL (or *) wildcard. Any other name is refused at validation.

allowed_tools: [] is not "allow everything"

The empty list alone decides nothing — the default is what decides. [] + default: allow = allow everything (except what's denied). [] + default: deny = deny everything. And no tool can be in both allowed and denied at the same time.

output_policy — which artifacts the agent produces

Same contract as tool_policy, but about the artifact types generated.

Field	Type	Default	What it does
default	allow · deny	allow	Destination of an artifact not in the lists.
allowed_artifacts	list	[]	Exceptions that pass despite the default.
denied_artifacts	list	[]	Always refused.

Valid artifacts: software_source_code, automation_script, infrastructure_code, query_language, markup_document, template_document, formula_expression, data_transformation_snippet, pseudocode, structured_data_document.

execution_policy — command and skill execution

Field	Type	Default (inherited)	What it does
allow_execution	bool	true	false = read-only mode: tools with side effects (Bash/Execute/Edit/Write/Skill) are refused.
allow_simulation	bool	true	Lets the agent simulate/rehearse an action without executing it.
allow_suggestions	bool	true	Lets the agent suggest commands/actions instead of executing.
allow_copy_paste_ready_output	bool	true	Lets it produce copy-and-paste-ready output.
sandbox_only	bool	false	true = every execution proposal runs in a sandbox.
allow_local_skill_execution	bool	true	false = local skills (~/.imaginne/skills) are refused (Imaginne emits local_skill_execution_denied_by_policy).
allow_outside_workspace	bool	false	true = allows writing outside the workspace (destructive ops still ask for confirmation). Only applies on trusted local surfaces (Desktop/TUI), never on the cloud runtime.
allow_raw_shell	bool	false	true = allows the raw shell (Execute with a free-form command line) on hosted runs — web chat, Cloud Runs, and other cloud surfaces.

Where execution_policy intersects with profiles and users

allow_local_skill_execution and allow_outside_workspace also appear as toggles in Profiles and as per-user overrides in Users & roles. allow_raw_shell follows the same model — a profile baseline plus a per-user override — resolved on the server. Everything goes into the same deny-wins merge: the per-user override can tighten the profile's baseline.

allow_raw_shell is a grant, not a default

The default is denied: on hosted runs, the agent uses governed tools rather than a free-form command line. Granting raw shell to a user substantially widens what they can do in the execution environment — treat it as an exception, with an audit trail (Audit), and revoke it when the need passes. Revocation takes effect immediately, including for sessions already open.

data_policy — sensitive data

Field	Type	What it does
allow_pii	bool	false = the content checker redacts PII (email/phone/postal code) from tool results. Google tool results (tool:google_*) have a scoped exemption; secrets/national IDs are still redacted.
allow_data_export	bool	Lets the agent export data outward.
allow_internal_data_access	bool	Allows access to internal data.
allow_sensitive_data_summary	bool	Allows summarizing sensitive data.
allow_sensitive_data_extraction	bool	Allows extracting sensitive data.
allow_cross_document_aggregation	allow · limited · deny	How much the agent can cross-reference information between documents.
redact_sensitive_fields	bool	true = redacts the fields listed in sensitive_fields.
sensitive_fields	list	Names of fields to redact.
classification	public · internal · confidential · restricted	Sensitivity level of this layer's data (increasing order of restriction).

content_policy — the shape of generated content

Field	Type	What it does
language	text	Forced response language (e.g., en-US).
tone	text	Desired tone.
require_disclaimers	bool	Requires a notice in the response.
disclaimer_text	text	The text of the notice.
max_response_length	integer	Cap on the response size.
forbidden_topics	list	Forbidden subjects.
require_references	bool	Requires citing sources/references.

interaction_policy — how the agent interacts

Field	Type	What it does
formality	text	Level of formality.
require_summary	bool	Requires a summary at the end.
step_by_step	bool	Requires step-by-step reasoning/delivery.

model_policy is not authored here

The model allow-list, default model, and credential source are not authored in the ruleset YAML — the resolver injects them into the compiled policy from BYOK and the model assignments. Do not add a model_policy: block to your YAML.

How to allow and how to block (recipes)

Each recipe below is a block that goes inside the required envelope.

Allow everything (permissive org):

tool_policy:
  default: allow
  denied_tools: []

Block a specific tool, keeping the rest:

tool_policy:
  default: allow
  denied_tools: [Execute]    # remove only the shell

Allow only a set (read-only allowlist):

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

Block all tools:

tool_policy:
  default: deny
  denied_tools: [ALL]        # or simply default: deny with allowed: []

A true read-only mode (refuses Bash/Edit/Write/Skill):

execution_policy:
  allow_execution: false

Block PII in tool results:

data_policy:
  allow_pii: false

Lock down data export and cross-referencing:

data_policy:
  allow_data_export: false
  allow_cross_document_aggregation: deny
  classification: restricted

Force a language and a mandatory notice:

content_policy:
  language: en-US
  require_disclaimers: true
  disclaimer_text: "AI-generated content; review before use."

Require a sandbox for all execution:

execution_policy:
  sandbox_only: true

By scope: what to paste into each editor

The same schema, changing only scope_type (and, for user_type, the scope_key). You paste each one into the corresponding editor in Governance.

Organization (Organization Rules) — applies to everyone:

schema: 1
metadata:
  name: "Organization baseline"
  scope_type: org
policy:
  effect_mode: deny_wins
tool_policy:
  default: allow
  denied_tools: [Execute]

User type (User Type Rules) — scope_key required (premium or full):

schema: 1
metadata:
  name: "Premium — read only"
  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

Profile (Profile Rules) — the binding is the profile editor you opened:

schema: 1
metadata:
  name: "Finance — no data export"
  scope_type: profile
  scope_key: finance
policy:
  effect_mode: deny_wins
data_policy:
  allow_data_export: false
  classification: restricted

Skill group (Skill Group Rules):

schema: 1
metadata:
  name: "Legal — mandatory disclaimer"
  scope_type: skill_group
  scope_key: legal
policy:
  effect_mode: deny_wins
content_policy:
  require_disclaimers: true
  disclaimer_text: "AI-generated content; validate with a lawyer."

How the layers combine (deny-wins, in detail)

When several rulesets apply to the same session, they are combined in precedence order (platform → org → user_type → skill_group → profile → skill). Each dimension has a merge rule:

Dimension	How it combines across scopes
denied_tools · denied_artifacts · forbidden_topics · sensitive_fields	Union — every denial from any layer remains.
allowed_tools · allowed_artifacts	Intersection — each layer can only narrow the list.
default (tool/output)	If any layer uses deny, the result is deny.
allow_* (execution and data)	false wins — one layer denying is enough.
require_* · sandbox_only · redact_sensitive_fields	true wins — one layer requiring is enough.
classification	The most restrictive wins (public < internal < confidential < restricted).
allow_cross_document_aggregation	The most restrictive wins (allow < limited < deny).
max_response_length	The smallest value wins.
language · tone · formality	The value from the broadest layer that defines it prevails; more specific layers don't override it.

The practical consequence: a profile can never reopen something the org closed. To allow, you loosen at the broadest layer; to restrict, you tighten at any layer.

Validation (the Validate button)

The editor refuses the ruleset if:

• schema ≠ 1.
• metadata.name is empty, or scope_type is invalid.
• scope_type: user_type without a scope_key equal to premium or full.
• policy.effect_mode ≠ deny_wins.
• There is an unknown key (strict mode — a misspelled field is an error, not ignored).
• The document exceeds 64 KB.
• There is a YAML anchor/alias (the & character, or a line starting with *).
• tool_policy.default / output_policy.default outside allow/deny.
• The same tool/artifact appears in both allowed and denied.
• A tool or artifact name outside the valid lists.
• classification outside public · internal · confidential · restricted.

Active ruleset limit

An organization can have at most 50 active rulesets. Archive the ones you no longer use (the version history is preserved).

See also

🛡️Governance & policies

The dashboard, the editors, and the policy simulator.

Open →🏢Organizations & policies

The mental model of layers and deny-wins.

Open →🎭Profiles

The most specific layer — and where the execution toggles live.

Open →🗂️Skill groups

The scope between organization and profile.

Open →