Free Intensive Nov 21–22Free 2-day hands-on Vibecoding Intensive on Nov 21–22 at 16:00 MSK (Sat–Sun) · Live Cohort 3 starts Nov 23Join Free →Cohort 3 (Nov 23)
ReleaseInsight · On RadarHabr AI→ original

A State Machine in a Hook Stops an AI Agent from Hanging Bash: All 122 Tests Pass

If an AI agent drops a closing quote, Bash waits for more input, and the agent hangs until it times out. Quote Guard replaces regular expressions with a finite state machine (FSM). It reads the command character by character, following shell rules, inside the PreToolUse hook, before anything runs. When Bash and PowerShell disagree, the agent gets a hint and fixes the call itself. Protection against hangs belongs in the infrastructure, not in the prompt.

AI-processed from Habr AI; edited by Hamidun News
A State Machine in a Hook Stops an AI Agent from Hanging Bash: All 122 Tests Pass
Source: Habr AI. Collage: Hamidun News.
Listen to article
Article Fact Sheet & Key Figures
ParameterDetails
Primary sourceHabr AI ↗
Editor-in-Chief
The string dir "C\" is safe in PowerShell but hangs Bash
Key metric #2v3.0 passed heredocs through whole; in v3.1 the body is masked with spaces
Key metric #3122 checks in Python and Node.js pass, including adversarial ones

Picture this: an autonomous agent assembles a terminal command and drops a closing quote. For text, that's a typo. For Bash, it's a reason to stop and wait.

The shell decides the input will continue on the next line, prints the ">>" prompt, and goes silent. If the agent reads the process synchronously, the end of output (EOF) never arrives, the process never terminates, the session burns out on a timeout, and the agent fails. The author of the Quote Guard project described on Habr how to close this gap without asking for anything in the prompt.

Before a command runs, he puts a finite state machine (FSM) in front of it: a small program that reads the string character by character and knows at every moment where it is: in plain text, inside quotes, or after an escape character. It is built into a PreToolUse hook, an interceptor that fires before the agent hands the command to the operating system. Reliability rests on 122 automated checks, and all of them pass.

Why regular expressions don't work

The first idea is to check quote parity, for example count % 2 == 0. But the same string is read differently by different shells. Take dir "C:\". In PowerShell, the backslash is an ordinary path separator: the quote opens, sees C:\, closes, and the command is ready. In Bash, the same backslash escapes the next quote, so that quote stops being a closing one, and the shell waits for a continuation that will never come.

The second example follows the same pattern: in echo "a"b"`, the backtick is an escape character in PowerShell, but in Bash it triggers command substitution, so the shell looks for a matching backtick and again drops into multiline mode. You can't guess the shell from the host's operating system: Windows containers may run Bash, WSL may run PowerShell, and agents run scripts across platforms. A naive validator will either miss the hang on Linux or block a legitimate Windows path. After the first false alarm, an engineer will simply turn the protection off.

The finite state machine and the "double lock"

The author replaced the regular expressions with a deterministic automaton that has three isolated grammars: posix, powershell, and cmd. It switches states (plain text, double quotes, single quotes, escaping) strictly according to the rules of the target environment.

For unknown tools, such as a third-party plugin or a custom agent, a Strict Intersect mode applies. The command is checked against two grammars at once, posix and powershell:

  • safe under both: allowed;
  • leads to a hang under both: blocked;
  • the verdicts diverge, as with dir "C:\": execution is aborted with Exit 2.

Instead of a silent hang, the model receives a machine-readable refusal: unknown tool, the string is safe in PowerShell but hangs POSIX, and a hint to set the variable QUOTE_GUARD_MAP=MyTool=powershell. The agent reads the instruction and sends a correct call on the second attempt. This saves both session time and the tokens spent on retries after a timeout.

The heredoc story and the 122 checks

The most useful part of the material is its candid account of a bug. A heredoc is a block of text in Bash delimited by markers such as <<EOF and EOF. In v3.0, the hook saw the <<EOF marker, decided that the contents were "raw" quotes, and let the whole command through. A test exposed the hole: the model generated cat <<EOF … EOF followed by echo "unclosed. The hook saw the marker and passed everything, and the unclosed quote after the block hung the shell.

In v3.1, the heredoc body is masked: its contents are overwritten with spaces while offsets are preserved so the parser isn't thrown off, and everything before and after is checked by the automaton. If the EOF terminator itself is not closed, the hook records a HEREDOC state and blocks the launch. Now cat <<EOF with a script inside passes, while EOF followed by echo "broken does not.

The project is tested against a shared cross-language suite, cases.jsonl, with 31 grammar cases. In total there are 122 checks: 46 each for the Python and Node.js lexer implementations (they must behave byte-for-byte identically), 25 for the PreToolUse hook integration, and 5 for a self-test of the duplication detector. All pass. The tests are adversarial: they include attempts to escape quotes, nested constructs, multiline injections, and attempts to bypass the hook.

What this means in practice

For anyone building agents with shell access, the takeaway is simple: probabilistic generation should be guarded by a deterministic gateway. It's also useful that the refusal comes back as an instruction for the model, not as silence.

The author names the limitations himself. The guarantee holds only if the hook is installed on the host and the environment variables haven't been tampered with. Three grammars are covered; other shells, such as fish or zsh with its special extensions, would need separate descriptions. The test results have so far been confirmed only within the project's repository, with no independent audit. Still, as a template for agent runtimes the approach works: an automaton instead of regular expressions, a structured refusal instead of a hang, and a mandatory test for every hole found.

Story

Key Questions Answered

Why regular expressions don't work?

The first idea is to check quote parity, for example count % 2 == 0. But the same string is read differently by different shells. Take dir "C:\". In PowerShell, the backslash is an ordinary path separator: the quote opens, sees C:\, closes, and the command is ready. In Bash, the same backslash escapes the next quote, so that quote stops being a closing one, and the shell waits for a continuation that will never come.

What are the key details on The finite state machine and the "double lock"?

The author replaced the regular expressions with a deterministic automaton that has three isolated grammars: posix, powershell, and cmd. It switches states (plain text, double quotes, single quotes, escaping) strictly according to the rules of the target environment. For unknown tools, such as a third-party plugin or a custom agent, a Strict Intersect mode applies.

What are the key details on The heredoc story and the 122 checks?

The most useful part of the material is its candid account of a bug. A heredoc is a block of text in Bash delimited by markers such as <<EOF and EOF. In v3.0, the hook saw the <<EOF marker, decided that the contents were "raw" quotes, and let the whole command through. A test exposed the hole: the model generated cat <<EOF … EOF followed by echo "unclosed. The hook saw the marker and passed everything, and the unclosed quote after the block hung the shell.

ZK
Zhemal Khamidun — CPO at Alpina Digital, product manager of AlpinaGPT. Building AI products since 2019. Hamidun News is a pet project that grew into a production aggregator with 6,000+ readers.
✦ Unified AI Workspace · Nomad

Test Frontier LLMs & Autonomous Agents in One Workspace

Run Claude Opus 5.5, GPT-6, Gemini 3.1, and DeepSeek side-by-side in Nomad AI (nomadnet.ai) — unified model routing, deep research, and multimodal workflows under one subscription.

Try Nomad AI →Launch Nomad Agent
What do you think?
Loading comments…