Tool Substitution

When the agent reaches for a legacy CLI tool, Warden can either rewrite the command to a modern alternative or teach the agent to use it. The result is faster execution, less noisy output, and better defaults.

Substitutions only fire when the target tool is installed. The warden init wizard detects and offers to install missing tools.

Why Substitutions Exist

AI agents default to the tools they’ve seen most in training data — grep, find, curl, cat. Modern alternatives are faster, produce less output (saving context tokens), and have better defaults for the kinds of searches agents perform.

Warden intercepts the call at the hook level and either rewrites it directly or teaches the agent the modern equivalent. Since agents self-correct after denials, the substitution typically sticks for the rest of the session. This isn’t about tool ideology — it’s about practical outcomes: faster results, less context waste.

Before and After

grep vs rg — The agent searches for a function name across a large codebase:

# What the agent writes:
grep -r "handlePayment" --include="*.ts" src/

# What Warden tells the agent:
BLOCKED: Use rg (ripgrep) instead of grep. Same flags: rg PATTERN [PATH].

# What the agent runs next:
rg "handlePayment" src/ -t ts

The rg version is 10-50x faster, respects .gitignore by default (no node_modules noise), and produces a cleaner output format that consumes fewer context tokens.

find vs fd — The agent looks for config files:

# What the agent writes:
find . -name "*.config.js" -type f

# What Warden tells the agent:
BLOCKED: Use fd instead of find. Example: fd PATTERN [PATH]. Regex by default.

# What the agent runs next:
fd "\.config\.js$"

fd ignores hidden files and .gitignore patterns by default, uses regex, and produces colored output with less noise.

cat vs bat — The agent reads a source file:

# What the agent writes:
cat src/main.rs

# What Warden tells the agent:
BLOCKED: Use bat instead of cat. Example: bat FILE (syntax highlighting).

# What the agent runs next:
bat src/main.rs

bat adds line numbers and syntax highlighting, making the output more useful for the model to parse. It also handles large files better with built-in paging.

Availability Check

Substitutions are not unconditional. Before denying a grep call, Warden checks whether rg is actually installed on the system. If the target tool isn’t available, the substitution rule is skipped and the original command runs normally.

The warden init wizard detects which modern tools are missing and offers to install them via cargo install or your system package manager. You can also install them manually at any time — Warden will start using them on the next session.

Disabling Specific Substitutions

If a substitution doesn’t fit your workflow, disable it by rule ID in ~/.warden/config.toml:

[restrictions]
disabled = ["substitution.0"]  # Stops redirecting grep → rg

Use warden describe --all to see the full list of substitution rule IDs:

Windows Note: sd Is Blocked, Not Substituted

On Windows, sd (the sed replacement) is blocked entirely rather than substituted. It mangles line endings and file encodings on Windows. Warden’s deny message directs the agent to use the Edit tool for file modifications instead, which preserves encoding correctly.