rules.toml

Rules control what Warden blocks, redirects, and advises on. This is also where thresholds, engine tuning, output filters, and git_readonly live — config.toml parses none of them.

The 4-Tier Override Model

1. Compiled defaults — shipped in the binary. 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. Installed packs (~/.warden/packs/*.toml) — domain-specific bundles. See Rule Packs.
4. 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 user-added patterns for that category — never the compiled floor. Project rules win the threshold merge.

# ~/.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 user-added substitutions with your own list
replace = true
patterns = [
  { match = "\\bgrep\\s", msg = "Use rg instead of grep." }
]

Pattern Sections

Each takes a patterns list of { match, msg } entries, plus an optional replace and a per-entry shadow:

[safety], [destructive], [chain], [substitutions], [advisories], [hallucination], [hallucination_advisory], [sensitive_paths_deny], [sensitive_paths_warn].

[chain] patterns are matched against the raw, unsplit command line rather than each program in a pipeline.

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. Watch the dashboard or warden --debug export to see whether they would have fired correctly before removing 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_kb = 80   # kilobytes; this project has large generated files

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

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

[[command_filters]] entries take match, strategy (strip_matching, keep_matching, dedup, head_tail, passthrough), keep_patterns, strip_patterns, keep_first, keep_last, summary_template, and max_lines. The line lists are keep_patterns and strip_patterns — not keep and strip.

See Thresholds for every key under [thresholds] and the per-engine sections.

Git Read-Only Mode

git_readonly = true

A top-level key, off by default. When on, the compiled git-mutation patterns are added to the safety set: add, commit, tag, push, pull, merge, rebase, cherry-pick, stash, reset, clean, checkout, restore, revert, bisect, am, apply, branch -d/-D, and force pushes. Read-only git — log, status, diff, show, blame — is untouched.

Disabling Rules

# ~/.warden/rules.toml
[restrictions]
disable = ["substitution.cat", "read.post-edit"]

The key is disable, and it lives in rules.toml. IDs in the safety, destructive, hallucination, zero_trace, permission, and git_readonly namespaces are refused — they are the immutable floor, and a rule Warden refuses to disable is logged and skipped rather than failing the parse.

A project-level .warden/rules.toml is narrower: it may only disable substitution.* and advisory.*. Cloning an untrusted repository can never switch off enforcement.

Viewing Active Rules

# Every rule ID, category, severity, and whether it can be disabled
warden --debug restrictions list

# JSON dump of the compiled patterns plus your overrides
warden --debug describe --all