State machine guardrails

State machine guardrails zijn regels die bepalen welke acties een AI-agent, een assistent die met tools taken uitvoert, in elke fase van een klus mag doen. Een boekhoudagent mag alleen lezen zolang hij bonnetjes verzamelt, en mag pas boekingen invoeren als die fase begonnen is. Gewone software toetst elke actie aan de huidige fase, zodat de agent zich niet langs een grens kan praten.

Waar komt de term vandaan?

De term is hoe Statewright zichzelf op GitHub omschrijft: "State machine guardrails for AI agents". Ben Cochran presenteerde het op 12 mei 2026 in een Show HN. Het combineert twee oudere ideeën: een state machine die altijd in precies één fase is en volgens vaste regels van fase wisselt (deterministische agent state machine), en guardrails, controles rond een model. Eenvoudigere versies bestaan ook elders. In de plan mode van Claude Code (september 2026) leest Claude bestanden en schrijft het een plan, en blijven wijzigingen geblokkeerd tot je dat plan goedkeurt.

Hoe werkt het?

Een workflowdefinitie legt de grenzen per toestand vast. In de bugfix-workflow uit de README van Statewright van mei 2026:

• planning staat alleen Read, Grep en Glob toe, voor hoogstens 8 rondes;
• implementing voegt Edit en Write toe, met wijzigingen van hoogstens 20 regels in hoogstens 3 bestanden;
• testing voegt Bash toe, maar alleen commando's die beginnen met pytest, cargo test of npm test;
• een mislukte test stuurt de agent terug naar implementing, en de stap naar klaar heeft een controle in code (een guard) die de testuitslag nakijkt.

De README noemt meer guardrails. Shell-commando's die bestanden schrijven of wissen, zoals echo > file, rm -rf of sed -i, blijven geblokkeerd in toestanden zonder schrijfrechten, ook als de shell zelf is toegestaan. Omgevingsvariabelen zoals het adres van een productiedatabase kunnen worden verborgen. Een overgang kan wachten op goedkeuring door een mens (human-in-the-loop).

Het gaat erom waar de controle plaatsvindt. De README noemt de handhaving hard als een toolaanroep wordt onderschept voordat hij draait, en adviserend als de regels alleen in de context van het model staan. In mei 2026 was de koppeling met Claude Code, via hooks en MCP, hard; die met Cursor was adviserend, omdat MCP daar toolaanroepen niet kon tegenhouden. Een geweigerde aanroep geeft een melding terug met de tools die beschikbaar zijn en hoe de agent verder kan.

Waarom helpt het?

Statewright noemt de fouten waar het op mikt: met 40 of meer tools leest een agent hetzelfde bestand vijf keer opnieuw, roept hij Edit aan tijdens de review en zet hij code live voordat de tests slagen. Met de guardrails ziet het model 5 tools in plaats van 30. Cochrans redenering in de Show HN is dat een strak afgebakende context per stap beter werkt dan een model dat overal bij kan. Het bewijs is een kleine eigen test van de maker: op vijf SWE-bench-taken gingen twee lokale modellen van 2 op 10 geslaagde pogingen naar 10 op 10. Modellen onder ongeveer 13 GB konden nog steeds geen nauwkeurige wijzigingen maken.

Waar gaat het mis?

• Te streng. Een workflow die blokkeert wat de taak nodig heeft, laat de agent vastlopen; Statewright heeft een commando dat de workflow uitzet.
• Handwerk. Iemand moet de workflow schrijven, al kan een agent een eerste versie maken.
• Adviserende modus. Waar een platform aanroepen niet kan onderscheppen, zijn de regels een verzoek dat het model kan negeren.
• Cachekosten. Een reageerder op HN merkte op dat een toollijst die per toestand verandert de prompt caching breekt; de documentatie van Anthropic zegt dat het wijzigen van tooldefinities de hele cache ongeldig maakt.
• Beperkte reikwijdte. De guardrails bepalen welke tools draaien en in welke volgorde. Of de uitkomst van een stap klopt, hangt nog steeds af van controles zoals tests.

Voorbeeld

Stel: een webshop laat een agent retourverzoeken afhandelen. In de toestand controleren mag de agent alleen de bestelling en het retourbeleid lezen. In de toestand afhandelen mag hij ook een retourlabel aanmaken. De tool die geld terugstort, komt pas beschikbaar nadat een medewerker de overgang naar terugbetalen heeft goedgekeurd. Probeert de agent terug te betalen terwijl hij nog controleert, dan wordt de aanroep geweigerd met een lijst van de tools die hij nu mag gebruiken.