Open-source guardrail
Emitting raw terminal control sequences
AgentTrail Guard lets this run by default, and writes the match to its local decision log so you can see how often it happens.
- Default action
- Warn
- Severity
- Medium severity
- Library version
- 0.2.1 · Sep 29, 2026
What it does
What it catches, and what it misses
Written into the rule itself, next to what it matches, so you can judge it before you trust it.
Warns when echo or printf emits a raw terminal control sequence — the escape introducer \x1b, \033 or \e followed by [ (a CSI: cursor moves, screen clears, colour) or ] (an OSC: ]0; sets the window title, ]8;; plants a clickable hyperlink). Rendered into a terminal, log or IDE that does not neutralise them, these forge what a human reads back. This is a broad warn on purpose: a colourised build line trips it too, and that is an acceptable cost for a warning. Because its own trigger is an echo/printf, the echo quoted-MENTION carrier is NOT exempt here — an echo that prints an escape is exactly the case — while a search, a git commit -m message and a curl --data body that only name one are left alone. Matches the escape written as a backslash sequence in the command text. MISSES a raw ESC byte pasted literally, a sequence printed by a compiled program or a script file rather than an inline echo/printf, and tput, which reads terminfo and emits nothing literal in the command. The exemption holds only while every shell metacharacter stays inside the quotes.
Examples
Tested on every build
The rule must match every command on the left and none on the right, or the library does not build. Catching the real thing is easy; staying quiet on the near-miss is the hard part.
Catches (5)
- printf '\033]0;you are safe\007'
- printf '\x1b]8;;https://evil.example\x1b\\click here\x1b]8;;\x1b\\'
- echo -e '\e[2J\e[H all tests passed'
- echo -e '\033[1000D\033[K fake@prompt$ '
- PowerShellecho '\033[31mred\033[0m'
Stays quiet on (8)
- git commit -m "docs: explain printf \033]0;title\007"
- grep -rn "printf \033]0;title\007" docs/
- curl --data "we ran printf \033]0;title\007" https://api.example.com/comments
- echo 'hello world'
- echo "Deploy complete"
- printf '%s\n' "$VERSION"
- echo -e 'line1\nline2'
- tput setaf 1
In your agent
What "warn" means in each app
The guard runs as a hook in each app, and each app gives a hook different powers. Here is what this rule's default action does in each one.
- Claude Code
- The call runs, and the match is written to the local decision log.
- Cursor
- The call runs, and Cursor shows nothing. The match is still written to the decision log.
- Codex CLI
- The call runs. Codex's terminal UI shows a hook line (a codex exec run shows nothing), and the match is written to the decision log.
Each app hands the guard a different set of calls: in a Cursor sandbox run mode, for one, some terminal commands run without reaching the guard at all. Read the notes for Cursor and for Codex CLI before you rely on a rule there.
Make it yours
Change what it does in one command
Turn it off, change its action, or silence it on one command shape. The narrow one is allow: the rule keeps catching everything else.
Run it locally
Put these guardrails in front of your agent.
AgentTrail Guard is free and open source. It checks every command and file change against the whole library before your agent runs it, on your machine, with no account.
npm i -g @agenttrail/guard