Stull — Máquinas de Estado para Claude Code Hooks
justinstimatze/stull
State machines guardadas que compilam hooks seguros para Claude
Ver no GitHubFramework Go que constrói Claude Code hooks como máquinas de estado guardadas, onde células LLM ficam atrás de guardas determinísticos. Compila para settings.json garantindo segurança — código inseguro não compila. Permite declarar loops de validação (ex: verificar se tarefa acabou, bloquear stop prematuro) sem hand-rolling scripts.
Instalação
npx convez-ai justinstimatze/stull1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Criar loops de validação onde Claude prova que a tarefa terminou antes de parar
- Bloquear ações inseguras com guardas determinísticos ou células LLM fenceadas
- Simular e testar máquinas de estado antes de gastar tokens com a API
Veredito

Ferramenta sofisticada para quem constrói agents críticos em Go. Resolve um problema real (loops de validação seguros), mas exige compreensão de máquinas de estado e Go. A compilação contra unsafety é o diferencial — recomendado para sistemas que precisam de garantias de não-halting e injeção segura.
README
A tradução para o português deste README ainda está na fila.
stull
The easy way to build Claude Code hook meshes that an agent won't fumble. You
wire LLM judgment and deterministic code checks into a little state machine; stull
compiles it to the settings.json hooks that run it — and won't compile one
that's unsafe (injects on a trigger that can't, loops forever, or branches on the
model's raw output).
Take the loop everyone ends up hand-rolling — after Claude stops, make it prove the task is actually done, and push it to keep going if not:
flowchart LR
S([Claude tries to stop]) --> C{"fenced LLM cell:<br/>task actually done?"}
C -->|incomplete| B["Block the stop —<br/>keep going"]
B --> S
C -->|complete| A["Allow + inject<br/>'verified'"]
A --> E([done])
By hand that's a Stop-hook script plus a state file you babysit. As a stull
machine it's a declaration you can watch run on scripted answers before spending a
token — it blocks until the cell says done, and a fuel budget caps the
retries so the loop is guaranteed to end:
scenario "converges"
trigger from to fuel kind detail
Stop loop loop 4->3 block exit2: Task not yet complete — continue with the next concrete step.
Stop loop loop 3->2 block exit2: Task not yet complete — continue with the next concrete step.
Stop loop done 2->1 inject ctx: Verified: the task is complete.
-> final state "done", fuel 1
The whole machine is one LLM cell that judges done / not-done — its answer can't reach your code until it's been checked — and two guards that let the stop through or block it. It's about fifteen lines of Go; the source is below.
go install ./cmd/stull # put `stull` on $PATH (once; or `make install`)
stull sim review-loop # play the whole loop out on scripted answers — no tokens spent
stull compile review-loop # emit the settings.json hooks
Adding a step is one more transition, not another hand-wired script — and check
proves the machine sound before you ship it. (Full source: examples/reviewloop,
run as
stull sim review-loop; a pure-code guard with no LLM — "block git add -A
every time" — is examples/denyguard, run as stull sim deny-add-all.)
Swap the judgment without touching the wiring
examples/hedgeverify rebuilds a real shipped hook
(likely — catch Claude hedging, nudge it
to verify next turn) as a single machine. The cheap version spots a hedge with
a regexp; the smart version swaps in an LLM cell that tells a load-bearing hedge
from genuine uncertainty. The only line that changes is the lens:
build("hedge-verify", spec.TranscriptMatches(hedge)) // regexp lens — zero model calls
build("hedge-verify-smart", spec.TermIs("assess", "load-bearing"), assess) // LLM lens — same substrate, gate, action
Same memory (SetVar into the machine's vars), same session scoping, same
two-trigger hook emission — all of which likely hand-rolls across two scripts, a
signal file with atomic writes and a TTL, and two installers. Snap the cheap one
together in minutes; upgrade the judgment in place when it earns it.
This is a working, self-contained Go module; the remaining edges (a real bus
behind Emit, an analyzer over the calibration log, cross-host state) are in
What's stubbed.
Beyond hooks: fence any LLM call
A Cell is useful on its own — you don't need a machine to get the fence. Build a
NewConfinedCell, drive the model yourself, and hand the completion to
Cell.Check; trust only a WellFormed && Safe term. The schema confines
generation to a vetted set; Grammar + Safety are the parse-time backstop, so
an answer outside that set is WellFormed-but-not-Safe and fails safe instead
of acting on something the model invented.
basanite uses
spec.Cellstandalone as a fenced-oracle library — a deterministic frequency detector manufactures a vetted candidate ladder, the Cell fences an LLM to select from it (never invent), andCell.Check's grammar + safety make a malformed or incoherent verdict fail safe to a deterministic default.
The whole pattern is the runnable ExampleCell_standaloneFence in spec (~20
lines). So stull is two things: a hook state-machine framework, and a
standalone primitive to fence any LLM call to a formal language + safety check.
How it maps to hybrid loops
If you've seen hybrid loops — LLM
judgment and deterministic code in alternating layers, each feeding the other's
working surface (lens → gate → reasoner → action) — that's exactly the shape
above. A cell is the lens/reasoner, fenced so its
answer lands in a small language you define before any code trusts it; a
guard is the gate, a deterministic decision; an effect is the action
(Block a tool call, Inject context, Run a cell, Emit to another machine);
and fuel keeps the loop honest — it always halts. stull is how you wire one
together as real Claude Code hooks: it generates the settings.json, manages the
per-session state, runs one generic dispatcher, and (nice, but not the point)
won't compile a broken one. Self-contained Go module, stdlib only, with the model
call live-bound to the Anthropic Messages API.
Glossary
stull leans on a few load-bearing terms. Plain-language here; the formal version is in docs/DESIGN.md:
- machine — a state machine: states, plus transitions between them that fire on a hook event.
- trigger — the hook event a transition fires on (
PreToolUse,Stop, …). - guard — a deterministic, no-LLM condition on a transition; it fires only if the guard holds.
- cell — a fenced LLM call. Its output must parse into a formal language you
define (its grammar) and pass a safety check before any guard may read
it — so a model answer can never gate the machine unchecked. (A pure-code guard
has no cell at all — see
examples/denyguard.) - effect — what a fired transition does:
Block(refuse the action; on aStopthat's the "keep going" primitive),Inject(add context),SetVar(write to the machine's cross-turn memory — how it accumulates a structure over a session),Run(run a cell),Emit(message another machine). - fuel — a step budget: every fired transition spends one, and at zero the machine stops gating. It's what guarantees the machine always halts. For a standing guard it's effectively a denial budget — a safe event fires nothing, so it costs nothing.
- total — always-terminating. stull guarantees it via the fuel bound.
E-…/W-…— checker codes:E-is a hard error (won't compile),W-a warning (compiles, but loudly).
Why this shape
Snapping the loop together is the pitch; this section is the safety net under it — why a mesh you wired up in minutes can't be an unsafe one. (Skip it if you just want to ship; come back when you want to know what the checker is buying you.)
A hook mesh is trivially Turing complete (arbitrary programs as nodes + a Stop
hook that refuses to halt = an unbounded loop). But Turing-completeness brings
the halting problem, so an LLM-in-the-loop mesh that is TC cannot be formally
guaranteed to behave. stull deliberately targets the class one rung below: a
total (always-terminating) guarded statechart, where
- the control-flow skeleton is deterministic and analyzable, and
- the LLM is a fenced oracle whose output can never move the machine into an unverified state.
A Cell is a formal oracle (Russell's sense): an LLM whose output is
confined to a formal language and checked for safe actions before it can
influence anything. Its contract is two decidable stages, both mandatory:
- Grammar — formal-language membership: parse raw output into a well-formed
term, or reject it as outside the language
L. - Safety — over a well-formed term, decide whether the action it denotes is safe.
A term reaches control flow only if it is WellFormed && Safe; otherwise the
machine takes its fail-safe path. (Generation-time confinement — constrained
decoding so the model can only emit L — is the runtime's job; the Grammar is
the parse-time backstop. See What's stubbed.)
The load-bearing invariant: an LLM output may never gate a transition without a
deterministic check between it and the transition. stull makes the unsafe
shapes inexpressible:
| Unsafe shape | How it is made impossible |
|---|---|
| An oracle that emits unconstrained or unchecked output | spec.NewCell requires both a grammar and a safety check; the fields are unexported, so a Cell literal without them won't compile elsewhere |
| A guard branching on raw oracle output | check rejects any guard reading cells.X.raw (only .term/.wellformed/.safe) — code E-ORACLE |
| Injecting on a trigger that can't inject | E-INJECT (e.g. Inject on PreToolUse) |
| Blocking on a trigger that can't block | E-BLOCK (e.g. Block on PostToolUse) |
| A loop that can never end | a mandatory positive Fuel bound (E-FUEL) makes every machine total — once fuel hits 0 it stops gating. A machine with no reachable terminal is not rejected (a standing guard wants exactly that); it compiles with a loud W-HALT warning, since fuel already guarantees it stops |
| A hook crash bricking the session | runtime.SafeDispatch recovers and fails open (exit 0, no output) |
Mapping to prior art
stull is the type system over primitives that already exist separately:
| Layer | Prior art it abstracts |
|---|---|
| typed guard/effect split | Claude Code's own hook model (Pre*=decision, Post*=fire-and-forget), Windsurf Cascade |
the bus / inbox transport (Emit) | mcp-dispatch (piggyback delivery + Stop-hook fallback) |
the read-once legitimacy Contract | slimemold (behavioral contract vs data-only injection) |
| fail-open dispatcher, calibration tap | hindcast (Guard, bounded logging) |
the Stop-loop clock + Fuel bound | Ralph Wiggum loop, made total |
| whole-mesh observation | disler multi-agent-observability (star tap) |
Layout
spec/ the statechart language (pure data + deterministic predicates)
check/ the static checker — makes unsafe meshes inexpressible
runtime/ the generic hook dispatcher (fail-open, total)
compile/ machine -> settings.json hooks fragment
sim/ deterministic simulator (scripted oracle, no model call)
registry/ name -> machine, for the CLI
examples/ reviewloop: a worked Stop-loop, oracle-gated (stull sim review-loop)
denyguard: a standing guard, oracle-free (stull sim deny-add-all)
hedgeverify: the bridge — accumulate across turns, swap a regexp lens
for an LLM lens on the SAME wiring; rebuilds `likely`
(stull sim hedge-verify / hedge-verify-smart)
cmd/stull/ the CLI
Use
go install ./cmd/stull # put `stull` on $PATH (or: make install)
stull check review-loop # static soundness report
stull explain review-loop --json # the machine's shape + soundness, machine-readable
stull compile review-loop /path/to/stull # settings.json hooks fragment (prints only)
stull install review-loop # merge those hooks into settings.json (--write to apply)
stull sim review-loop # run the demo scenarios
STULL_TRACE=1 stull run --machine review-loop # hook dispatcher; trace each step to stderr
(No install? Every command works as go run ./cmd/stull <args> from the repo.)
explain is the introspection an agent reads instead of the Go source — every
trigger, what each transition reads and does, the cells, and whether it is sound
— as text or --json. install closes the "now where does the fragment go?"
gap: it merges a machine's hooks into ~/.claude/settings.json (--project for
./.claude/settings.json), idempotently, dry-run by default and backing the file
up before it writes. And STULL_TRACE=1 makes a live stull run narrate each
step to stderr — so a hand-run hook isn't a silent black box. None of these touch
the hook protocol on stdout or change an exit code; the live path stays fail-open.
stull sim review-loop shows the worked example converging, failing safe on
invalid oracle output, and staying total under a stuck oracle:
scenario "converges"
trigger from to fuel kind detail
Stop loop loop 4->3 block exit2: Task not yet complete — continue ...
Stop loop loop 3->2 block exit2: Task not yet complete — continue ...
Stop loop done 2->1 inject ctx: Verified: the task is complete.
Use it in your own project
stull is a library — you don't fork this repo to add machines. Build a small binary that imports stull, defines your machine, and calls the same fail-open hook path the bundled CLI runs:
package main
import (
"os"
"github.com/justinstimatze/stull/runtime"
"yourmod/machines/denyguard"
)
func main() {
// RunHook is the whole live path: read the event on stdin, advance the
// machine, persist, deliver Emits, write the hook protocol — fail-open.
os.Exit(runtime.RunHook(denyguard.Machine(), runtime.AnthropicModel))
}
Point a settings.json hook command at that binary — stull install <machine>
will merge it in for you (idempotent, backs up first), or generate the fragment
with compile.SettingsJSON(machine, "your-binary") and merge it yourself with
compile.MergeHooks. The authoring side is plain
library calls on an in-memory spec.Machine: check.Inspect(m) to prove it,
compile.SettingsJSON(m, …) to emit hooks — the whole discover → build → check
→ compile → run path, no fork. See Public surface & stability for what's safe
to depend on.
Defining a machine
assess := spec.NewCell("assess", "claude-sonnet-4-6",
"Output exactly 'complete' or 'incomplete'.",
func(raw string) (string, bool) { // Grammar: membership in L
v := strings.ToLower(strings.TrimSpace(raw))
return v, v == "complete" || v == "incomplete"
},
func(string) bool { return true }) // Safety: a classification is safe
loop := spec.State{Name: "loop", On: []spec.Transition{
{On: spec.Stop, To: "done",
Guard: &spec.Guard{Reads: []string{"cells.assess.term"}, // formal output only
When: func(c *spec.Context) bool { return c.Cell("assess").WellFormed && c.Cell("assess").Term == "complete" }},
Do: []spec.Effect{spec.Inject{Text: spec.S("Verified complete.")}}},
{On: spec.Stop, To: "loop",
Guard: &spec.Guard{Reads: []string{"cells.assess.term"},
When: func(c *spec.Context) bool { return c.Cell("assess").WellFormed && c.Cell("assess").Term == "incomplete" }},
Do: []spec.Effect{spec.Block{Reason: spec.S("Not done — continue.")}}},
}}
m := spec.Machine{Name: "review-loop", Fuel: 4, Initial: "loop",
Contract: "You installed review-loop ...",
States: []spec.State{loop, {Name: "done", Terminal: true}},
Cells: []spec.Cell{assess}}
Register it in registry, then check / compile / sim / run it.
(The two guards above are spelled out longhand to show the shape; in practice
write spec.TermIs("assess", "complete"), which declares Reads for you.)
Execution semantics worth knowing
Four contracts the runtime guarantees — none can bite you silently (the checker
or sim catches the misuse), but knowing them up front saves a round-trip:
- Transitions fire in declaration order. Per event the first transition whose
trigger matches and whose guard holds (or is nil) wins; the rest are skipped.
Order specific-first, catch-all last — an earlier unconditional transition
shadows later ones on the same trigger (
checkflags it: W-SHADOW). - Guards are pure. A
Whenreads the context and returns a bool — it must not writeVarsor any state (use aSetVareffect). A guard that mutatesVarsis caught and surfaced as asimlint; a panicking guard fails open to a no-op. SetVaris cross-event. A write lands inVarsfor the next event, not the current one — each event fires one transition, whose effects run after its guard already evaluated. Accumulation is always read-old-then-write-new.- A guard can only read validated cell output (
.Term/.WellFormed/.Safe) — the raw completion isn't retained, so it won't compile, andcheckrejects acells.X.rawdeclaration. Reading a cell you forgot to declare inReadsis asimlint (the cell never runs, so the guard is silently false).
What's stubbed
- The model call and generation-time confinement are bound (and live-verified
against the real Messages API).
runtime.AnthropicModeluses only the standard library and is fail-safe on every error (no key / network / non-200 / refusal →"", so cells fall outsideLand the machine takes its fail-safe path). The cell's instruction is the system block (frozen, with acache_controlbreakpoint that activates once a system prompt exceeds the model's minimum cacheable size); the hook context the cell declares viaReading(...)—NeedTranscript(read fromtranscript_path, tail-bounded),NeedEvent,NeedPrompt— is the user turn. Aspec.NewConfinedCell(..., schema, ...)is confined at generation time: a forced strict tool call overschema, so the model can only emit a value inL, withGrammaras the parse-time backstop. Honest remaining edges: unconfined cells (NewCell) rely onGrammaralone;strictschemas are limited to the supported subset (objects +additionalProperties:false; no min/max, recursion); the transcript is tail-bounded for recency, which forgoes prefix caching of the transcript; and thinking is off (fine for a hot-path classifier, could be per-cell later). Emitwrites a local inbox, not a live bus.runtime.WriteInboxdelivers each emitted message as an atomic JSON file under{dir}/{target}/(cmd/stull runuses$STULL_INBOX_DIRor~/.cache/stull/inbox, fail-open, target collapsed to one path segment so it can't escape). This is a stull-defined local artifact — forwarding it onto a real bus (mcp-dispatch) is a separate adapter, deliberately not built until that on-disk contract is verified.- The calibration tap is a substrate, not a closed loop.
runtime.Calibrate(off by default;cmd/stull runinstallsFileCalibrator, fail-open, local JSONL) records two joinable halves per session+machine: the per-cell prediction (term/wellformed/safe) and the per-step outcome (the machine's own block/inject/fuel-halt behavior — a proxy verdict, not correctness). It makes the calibration join possible; it deliberately does not close back onto the oracle (stull contains the stochastic part, it doesn't steer it), and the correctness verdict still needs an external join.
Properties the checker buys you
Because the skeleton is deterministic, these are decidable on the spec, before a
single turn runs: reachability, termination (the mandatory Fuel bound —
the one hard floor), and the safety property no transition is gated on
unvalidated oracle output. A reachable terminal is checked too, but as a
loud W-HALT warning, not a hard error: fuel already guarantees the machine
stops, and a standing guard legitimately has no natural terminal — stull's job is
to make sure that shape can't pass silently, not to forbid it. What is not
guaranteed — and cannot be — is the correctness of an individual cell's output.
That is the irreducible stochastic part; stull's job is to contain it, not
eliminate it.
Public surface & stability
If you import stull as a library to emit and prove your own machines, this is the authoring contract — the surface meant to be depended on:
spec— the language. Build machines withspec.Machineand its parts (State,Transition,Guard, theEffecttypesInject/Block/Run/Emit,Triggerconstants); fenced oracles withNewCell/NewConfinedCell(.Reading(...)for hook context); oracle-free guards with the event helpersToolIs/CommandMatches/And.Injecting/Gatingreport a trigger's capabilities.check— the proof.Check(m) []string(hard errors only, empty == it compiles),Validate(m) error(same, as one error),Inspect(m) Report(errors and warnings, withReport.Sound()). TheE-…/W-…codes are stable identifiers you can match on.compile—SettingsFragment(m, binary)/SettingsJSON(m, binary), both over an in-memoryspec.Machine(no registry needed). They validate first, so they only emit a fragment for a machine with no hard errors.
The full discover → build → Inspect → compile path runs in one process against
these three packages. runtime is the execution seam (SafeDispatch,
AnthropicModel, the calibration/inbox sinks) — depend on it only if you embed
the dispatcher rather than shell out to stull run; treat its internals as less
stable than the authoring surface above.
Stability: stull is pre-1.0 and untagged — pin to a commit. The authoring
surface above is the intended-stable contract and changes here will be
deliberate and called out; everything else (runtime internals, the calibration
record shape — versioned by runtime.SchemaVersion, the local inbox layout) may
move without ceremony until a tagged 1.0.
Design notes
See docs/DESIGN.md for the formal-oracle model, the total-statechart-vs-Turing-completeness argument, and the Russell / reflective-oracle readings.