What are State Machine Guardrails?

What are State Machine Guardrails?

State machine guardrails are a deterministic control mechanism for AI agents that restricts which tools, commands, and environment variables an agent can access based on its current workflow phase. Rather than relying on the model's judgment to avoid harmful or unnecessary actions, state machine guardrails physically constrain the solution space at the protocol layer.

Why It Matters

AI agents with large tool sets consistently over-use, mis-sequence, or recursively loop on tools — even when instructed otherwise. Larger prompts and more capable models reduce these failures but don't eliminate them. State machine guardrails eliminate them categorically: an agent in a "planning" state literally cannot call a destructive shell command because that tool isn't registered for that state.

Statewright, the leading open-source implementation, specifically prevents read-loop death spirals — a failure mode where agents repeatedly call read tools without making progress. By making it structurally impossible to read indefinitely without transitioning to an action state, these loops are broken at the architecture level, not the prompt level.

How It Works

A state machine guardrail system defines:

1. States — discrete workflow phases (e.g., planning, reading, implementing, reviewing)
2. Tool permissions per state — each state has an explicit allowlist of permitted tools, commands, and environment variables; everything else is invisible to the model
3. Transitions — rules for how the agent moves between states, triggered by tool results, agent output, or elapsed time

The state machine integrates at the protocol layer — typically via MCP (Model Context Protocol) — so tool restrictions are enforced before the model even sees the tool list for a given turn.

Practical Example

A coding agent using Statewright operates in four states:

• planning: only read_file, list_dir, search available
• implementing: edit_file, create_file, run_tests unlock; delete_file stays locked
• reviewing: only read_file and run_tests available; no edit tools
• done: session closes

The agent cannot accidentally delete a file while planning, cannot get stuck reading without taking action, and cannot edit while reviewing.

Source

Ben Cochran / Statewright (2026): GitHub — statewright/statewright