Máquina de estados em um hook impede que agentes de IA travem o Bash: todos os 122 testes passam
Quando um agente de IA perde a aspa de fechamento, o Bash espera a continuação da entrada e o agente fica pendurado até o timeout. O Quote Guard trocou as regex por uma máquina de estados finitos (FSM): ela lê o comando caractere por caractere, seguindo as regras do shell, direto no hook PreToolUse, antes da execução. Quando Bash e PowerShell divergem, o agente recebe uma dica e corrige a chamada sozinho. A proteção contra travamentos deve ficar na infraestrutura, não no prompt.
Processado por IA de Habr AI; editado por Hamidun News
Imagine a cena: um agente autônomo monta um comando para o terminal e perde a aspa de fechamento. Para um texto, isso é um erro de digitação; para o Bash, é motivo para parar e esperar. O shell conclui que a entrada vai continuar na linha seguinte, exibe o prompt «>>» e fica em silêncio.
Se o agente lê o processo de forma síncrona, o fim da saída (EOF) nunca chega, o processo não termina, a sessão estoura o timeout e o agente cai. O autor do projeto Quote Guard descreveu no Habr como fechar essa brecha sem pedir nada no prompt. Ele colocou, antes da execução do comando, uma máquina de estados finitos (FSM): um programa pequeno que lê a linha caractere por caractere e sabe, a cada momento, onde está: em texto comum, dentro de aspas ou depois de um caractere de escape.
Ela está embutida no hook PreToolUse, um interceptador que dispara antes de o agente entregar o comando ao sistema operacional. A confiabilidade é sustentada por 122 verificações automáticas, e todas passam.
Por que regex não funciona
A primeira ideia é checar a paridade das aspas, por exemplo com count % 2 == 0. Mas a mesma linha é lida de formas diferentes em shells diferentes. Tome dir "C:\". No PowerShell, a barra invertida é um separador de caminho comum: a aspa abre, vê C:\, fecha, e o comando está pronto. No Bash, a mesma barra escapa a aspa seguinte, que deixa de ser de fechamento, e o shell fica esperando uma continuação que não virá.
Com o segundo exemplo acontece o mesmo: em echo "a"b"`, o acento grave no PowerShell é o caractere de escape, enquanto no Bash ele inicia uma substituição de comando; o shell procura o acento grave correspondente e novamente entra no modo multilinha. Não dá para adivinhar o shell pelo sistema operacional do host: em contêineres Windows pode haver Bash, no WSL pode haver PowerShell, e o agente executa scripts de forma multiplataforma. Um validador ingênuo ou deixa passar um travamento no Linux ou bloqueia um caminho legítimo do Windows. Depois do primeiro falso positivo desse tipo, o engenheiro simplesmente desliga a proteção.
A máquina de estados e a «trava dupla»
O autor substituiu as regex por uma máquina de estados determinística com três gramáticas isoladas: posix, powershell e cmd. Ela troca de estado (texto comum, aspas duplas, aspas simples, escape) estritamente conforme as regras do ambiente de destino.
Para ferramentas desconhecidas, como um plugin de terceiros ou um agente customizado, funciona o modo Strict Intersect. O comando é verificado ao mesmo tempo por duas gramáticas, posix e powershell:
- seguro nas duas: deixa passar;
- leva a travamento nas duas: bloqueia;
- os veredictos divergem, como no caso de
dir "C:\": a execução é interrompida com o código Exit 2.
Em vez de um travamento silencioso, o modelo recebe uma recusa legível por máquina: ferramenta desconhecida, linha segura no PowerShell, mas que trava o POSIX, com a sugestão de definir a variável QUOTE_GUARD_MAP=MyTool=powershell. O agente lê a instrução e, já na segunda tentativa, envia uma chamada correta. Isso economiza tanto o tempo da sessão quanto os tokens gastos em novas tentativas após o timeout.
A história do heredoc e as 122 verificações
A parte mais útil do material é a análise honesta de um erro. Heredoc é um bloco de texto no Bash entre marcadores como <<EOF e EOF. Na versão v3.0, o hook via o marcador <<EOF, concluía que as aspas lá dentro eram «cruas» e deixava o comando inteiro passar. Um teste expôs a brecha: o modelo gerou cat <<EOF … EOF e, logo em seguida, echo "unclosed. O hook viu o marcador e liberou tudo, e a aspa não fechada depois do bloco travou o shell.
Na v3.1 foi adicionado o mascaramento do corpo do heredoc: o conteúdo é apagado com espaços, preservando os deslocamentos para não confundir o parser, e tudo o que vem antes e depois é verificado pela máquina de estados. Se o próprio terminador EOF não estiver fechado, o hook registra o estado HEREDOC e bloqueia a execução. Agora cat <<EOF com um script dentro passa, mas EOF seguido de echo "broken não passa.
O projeto é validado em um conjunto multilinguagem comum, o cases.jsonl, com 31 casos gramaticais. São 122 verificações no total: 46 para cada implementação do lexer, em Python e em Node.js (elas devem se comportar de forma idêntica byte a byte), 25 para a integração do hook PreToolUse e 5 para a autoverificação do detector de duplicação. Todas passam. Os testes são adversariais: incluem tentativas de escapar das aspas, construções aninhadas, injeções multilinha e formas de contornar o hook.
O que isso significa na prática
Para quem constrói agentes com acesso a shell, a conclusão é simples: a geração probabilística deve ser cercada por um portão determinístico. Também é positivo que a recusa volte como instrução para o modelo, e não como silêncio.
O próprio autor aponta as limitações. A garantia só vale se o hook estiver instalado no host e as variáveis de ambiente não tiverem sido adulteradas. Três gramáticas estão cobertas; outros shells, como fish ou zsh com extensões específicas, precisarão ser descritos à parte. Os resultados dos testes, por ora, são confirmados apenas no repositório do projeto, sem auditoria independente. Mesmo assim, como modelo para o runtime de agentes, a abordagem funciona: máquina de estados no lugar de regex, recusa estruturada no lugar de travamento e um teste obrigatório para cada brecha encontrada.
- 21 de nov. de 2026No MLPerf Training, pela primeira vez, aparecem Nvidia Rubin e TPU Ironwood: 153 sistemas
- 21 de nov. de 2026Microsoft transforma o Copilot em "sistema operacional do trabalho": Word e Excel viram plugins do agente
- 21 de nov. de 2026OpenAI começa a liberar agentes em segundo plano dots para parte dos assinantes do ChatGPT Plus por US$ 20
- 21 de nov. de 2026OpenAI e ModRetro lançam console de jogos feito com o Codex por US$ 200; primeiro lote esgota em menos de um dia
Perguntas frequentes sobre a notícia
Por que regex não funciona?
A primeira ideia é checar a paridade das aspas, por exemplo com count % 2 == 0. Mas a mesma linha é lida de formas diferentes em shells diferentes. Tome dir "C:\". No PowerShell, a barra invertida é um separador de caminho comum: a aspa abre, vê C:\, fecha, e o comando está pronto. No Bash, a mesma barra escapa a aspa seguinte, que deixa de ser de fechamento, e o shell fica esperando uma continuação que não virá.
O que se sabe sobre A máquina de estados e a «trava dupla»?
O autor substituiu as regex por uma máquina de estados determinística com três gramáticas isoladas: posix, powershell e cmd. Ela troca de estado (texto comum, aspas duplas, aspas simples, escape) estritamente conforme as regras do ambiente de destino. Para ferramentas desconhecidas, como um plugin de terceiros ou um agente customizado, funciona o modo Strict Intersect.
O que se sabe sobre A história do heredoc e as 122 verificações?
A parte mais útil do material é a análise honesta de um erro. Heredoc é um bloco de texto no Bash entre marcadores como <<EOF e EOF. Na versão v3.0, o hook via o marcador <<EOF, concluía que as aspas lá dentro eram «cruas» e deixava o comando inteiro passar. Um teste expôs a brecha: o modelo gerou cat <<EOF … EOF e, logo em seguida, echo "unclosed. O hook viu o marcador e liberou tudo, e a aspa não fechada depois do bloco travou o shell.
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.
O essencial da IA — uma vez por semana
Sete histórias que realmente importaram, escolhidas a dedo. Sem ruído nem releases.
Pronto! Verifique seu e-mail para a confirmação.