rules.toml

Rules control what Warden blocks, redirects, and advises on. They come from three sources, merged in order.

The 3-Tier Override Model

1. Built-in defaults — shipped with Warden. These are the immutable floor. Safety rules at this tier cannot be disabled.
2. Global rules (~/.warden/rules.toml) — your personal overrides across all projects. Add custom patterns, disable non-critical rules, adjust thresholds.
3. Project rules (.warden/rules.toml in the project root) — per-project overrides. Team conventions, project-specific safety rules, custom filters.

Each tier merges on top of the previous one. Patterns from a TOML file are appended to the defaults. Setting replace = true in a section replaces the defaults entirely for that category.

# ~/.warden/rules.toml — example global override

[safety]
# Append a custom safety rule
patterns = [
  { match = "DROP TABLE", msg = "BLOCKED: DROP TABLE in raw SQL. Use migrations." }
]

[substitutions]
# Replace ALL default substitutions with your own list
replace = true
patterns = [
  { match = "\\bgrep\\s", msg = "Use rg instead of grep." }
  # Only grep→rg, no other substitutions
]

Adding Custom Rules

Add a custom safety rule:

# In ~/.warden/rules.toml or .warden/rules.toml
[safety]
patterns = [
  { match = "DROP DATABASE", msg = "BLOCKED: DROP DATABASE. Use migration rollbacks." },
  { match = "TRUNCATE TABLE", msg = "BLOCKED: TRUNCATE TABLE. Too destructive for AI." }
]

Add a shadow-mode rule for testing:

[hallucination]
patterns = [
  { match = "my-suspicious-pattern", msg = "Would block this pattern", shadow = true }
]

Shadow-mode rules log but don’t block. Check warden stats to see if they would have fired correctly before removing the shadow = true.

Project-Level Overrides

Create .warden/rules.toml in your project root. This is committed to version control so the whole team shares the same rules:

# .warden/rules.toml — project-specific

[thresholds]
max_read_size = 80000  # This project has large generated files

[[command_filters]]
match = "my-build-tool"
strategy = "keep_matching"
keep = ["ERROR", "WARN", "FAIL"]

[safety]
patterns = [
  { match = "migrate:reset", msg = "BLOCKED: Full database reset. Use migrate:rollback." }
]

Disabling Rules

Disable rules by ID in config.toml:

# In ~/.warden/config.toml
[restrictions]
disabled = ["substitution.0", "substitution.2"]

Not all rules can be disabled. Safety rules with HardDeny severity are the immutable floor — they protect against rm -rf /, sudo, and other universally dangerous operations. Use warden describe to see which rules support disabling.

Viewing Active Rules

# Show all active rules and their IDs
warden describe --all