State machine guardrails are rules that decide which actions an AI agent, an assistant that carries out tasks with tools, may take in each phase of a job. A bookkeeping agent may only read while it collects receipts and may only enter bookings once that phase has started. Ordinary software checks every action against the current phase, so the agent cannot argue its way past a limit.
Where does the term come from?
The term is how Statewright describes itself on GitHub: "State machine guardrails for AI agents". Ben Cochran presented it in a Show HN on 12 May 2026. It combines two older ideas: a state machine that is always in exactly one phase and moves between phases by fixed rules (deterministic agent state machine), and guardrails, checks placed around a model. Simpler versions exist elsewhere. In the plan mode of Claude Code (September 2026), Claude reads files and writes a plan, and edits stay blocked until you approve that plan.
How does it work?
A workflow definition sets the limits per state. In the bugfix workflow from Statewright's README of May 2026:
- planning allows only Read, Grep and Glob, for at most 8 iterations;
- implementing adds Edit and Write, with edits of at most 20 lines in at most 3 files;
- testing adds Bash, but only commands that start with
pytest,cargo testornpm test; - a failed test sends the agent back to implementing, and the move to done has a guard in code that checks the test result.
The README lists more guardrails. Shell commands that write or delete files, such as echo > file, rm -rf or sed -i, stay blocked in states without edit rights, even when the shell itself is allowed. Environment variables such as a production database URL can be hidden. A transition can wait for a person's approval (human-in-the-loop).
What matters is where the check happens. The README calls enforcement hard when a tool call is intercepted before it runs, and advisory when the rules are only placed in the model's context. In May 2026 the Claude Code integration, through hooks and MCP, was hard; Cursor's was advisory, because MCP alone could not block tool calls there. A rejected call returns a message that says which tools are available and how to move on.
Why does it help?
Statewright names the failures it aims at: given 40 or more tools, an agent "re-reads the same file five times, calls Edit during review, deploys before tests pass". With the guardrails "the model sees 5 tools instead of 30". Cochran's reasoning in the Show HN is that a tightly scoped context per step works better than a model with access to everything. The evidence is the maker's own small test: on five SWE-bench tasks, two local models went from 2 of 10 passing attempts to 10 of 10. Models under about 13 GB still could not make accurate edits.
Where does it go wrong?
- Too strict. A workflow that blocks what the task needs leaves the agent stuck; Statewright has a command that switches the workflow off.
- Handwork. Someone writes the workflow, although an agent can draft it.
- Advisory mode. Where a platform cannot intercept calls, the rules are a request the model can ignore.
- Cache cost. An HN commenter noted that a tool list that changes per state breaks prompt caching; Anthropic's documentation says modifying tool definitions invalidates the entire cache.
- Limited scope. The guardrails control which tools run and in what order. Whether a step's output is correct still depends on checks such as tests.
Example
Suppose a webshop lets an agent handle return requests. In the state check, the agent may only read the order and the return policy. In the state resolve, it may also create a return label. The tool that refunds money is only available after a staff member approves the move to refund. If the agent tries to refund while it is still checking, the call is rejected with a list of the tools it may use now.