When you dictate into a terminal, a misheard word isn't a typo. It can be a command.
So of course a dictation tool should have safety checks. "Are you sure you want to type rm -rf?" Easy.
What took me longer to learn is that a safety check has a cost every time it fires, including when it's right to. And when it fires on something harmless, it does more damage than no check at all, because it teaches you to dismiss it.
Three guards that turned out to be one idea
YazSes, the offline dictation tool I work on, grew three guards over time, each built separately for a different symptom:
- Command safety. If the text about to be typed looks like a dangerous shell command (
rm -rf,mkfs,dd of=, a force-push,curl ... | sh, a fork bomb: 13 patterns in all), hold it and ask. - Staged dictation. Speak, review, then commit: bursts collect in a buffer instead of typing straight into a terminal or a source file, so a misheard word is caught before it lands.
- No text target. If the focused window has nowhere to type, don't fire keystrokes into the void. Put the text on the clipboard instead, so nothing you said is lost.
When I wrote them up together in a design record (ADR-021), I noticed they're the same idea: this text is about to go somewhere where being wrong is expensive. And they share the same risk, which the ADR names directly: becoming "an app that asks 'are you sure?' too often".
The rule
So every guard is judged on how rarely it fires, not on how much it catches. In practice that means two rules:
Hold only on a specific, checkable signal. Never a heuristic.
The first new guard built under this rule shows what that means. It catches long dictated numbers, like a card number or an ISBN, where Whisper probably misheard a digit. It would be easy to warn on "long numbers". Instead it fires only when all of these hold:
- the text is a bare digit string,
- it is 12 digits or longer,
- and it fails every checksum scheme (Luhn, ISBN-13, ISBN-10) whose length fits.
A house number never triggers it. A phone number never triggers it. A valid card number never triggers it. Only a number that claims to be one of those formats and provably isn't.
Make letting it through one word. When a guard does fire, releasing it costs you a single spoken word, not a dialog box hunt. And the command-safety and check-digit guards share the same release word, so you learn one confirm phrase, not one per guard.
Measure the firing rate before you ship
The command-safety patterns were run against a corpus of 1,422 real dictations from my own use. They fired zero times. That's the number I wanted: not "caught 100% of my test attacks" (any regex does that) but "never interrupted normal work".
The check that taught me this rule the hard way was a different one. I had an experimental "cognitive load" gate: if you sound tired or rushed, slow down and confirm. In unit tests it computed its scores correctly. When I wired it into the real pipeline and replayed realistic bursts through it, it fired on nearly every one. A guard that fires on everything is just a slower app. I reverted it, and it's still not wired in.
The tests had passed. The tests proved it calculated. They didn't prove it was calibrated.
One more lesson from the same pattern list: a chmod -R 777 pattern once shipped that could never match, because the text is lower-cased before matching and the pattern had a capital R. Nothing failed. It just silently didn't guard. Now a test checks that every pattern can fire on at least one example.
Defaults follow the same logic
Command safety, staged dictation and the check-digit guard are all off by default, because they only matter for some people, and an interruption you didn't ask for is a cost. The no-text-target guard is on, because typing letters into a window with no text field is never what you meant, and the fallback (put it on the clipboard) costs almost nothing.
[cmdsafety] enabled = false [staged] enabled = false [checkdigit] enabled = false schemes = ["luhn", "isbn13", "isbn10"] min_digits = 12 [injection] target_guard = "clipboard" # or "warn" / "off" What I took away
- Every interruption has a price, even a correct one. A dismissed guard costs attention and catches nothing.
- Fire on a fact, not a feeling. "Fails a checksum" is a fact. "Looks like a long number" is a feeling.
- Replay real input before you ship a gate, and look at the firing rate. Passing tests prove the code runs, not that it's calibrated.
- Test that each rule can fire. A rule that can never match looks exactly like a rule that's working.
This applies far beyond voice: linters, CI gates, permission prompts, cookie banners. If people click through it without reading, it has already failed.
YazSes is offline, open source (Apache-2.0) dictation for Linux, macOS and Windows: github.com/MSKazemi/yazses.
I wrote this with help from an AI assistant for drafting and editing; the design, the measurements and the mistakes are mine, and I checked the facts against the code and ADR.
