Intensivo Grátis 21–22/11Intensivo gratuito de 2 dias em Vibecoding (21–22/11 às 16:00 MSK) · Turma 3 começa 23/11Inscrever-se grátis →Turma 3 (23/11)
LançamentoAnálise · No radarHabr AI→ original

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
Máquina de estados em um hook impede que agentes de IA travem o Bash: todos os 122 testes passam
Fonte: Habr AI. Colagem: Hamidun News.
Ouvir artigo
Ficha técnica e números-chave
ParâmetroDados
Fonte originalHabr AI ↗
Editor-chefe
A linha dir "C\" é segura no PowerShell, mas trava o Bash
Dado-chave #2A v3.0 deixava passar o heredoc inteiro; na v3.1 o corpo é mascarado com espaços
Dado-chave #3122 verificações em Python e Node.js passam, incluindo as adversariais

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.

História

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.

ZK
Zhemal Khamidun — CPO da Alpina Digital, gerente de produto do AlpinaGPT. Cria produtos de IA desde 2019. O Hamidun News é um projeto pessoal que virou um agregador em produção com mais de 6.000 leitores.
✦ 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
O que você acha?
Carregando comentários…