Project
excubitor — Safety Fences for Autonomous Coding Agents
Excubitor carries coding work and feedback through fresh model contexts, repeating agreed checks and separate review until the checks and review pass, or a limit or blocker stops the run. The recording below follows its development controller through a repair.
Repair, check, review again
Excubitor hands failures to the next worker, reruns the agreed checks, and asks for separate review. You don’t have to relay every repair yourself.
Real controller loop and check script. Worker and review replies are scripted; checkpointing and retention are simulated.
The coding task
Rebook a cancelled pottery class.
Build a function for three invented reservations and four offered seats: two morning, two afternoon. One solo booking needs morning. The two “Together” reservations must share a session. An empty seat is allowed.
One coding taskOnly schedule.py may change.
Original checkEvery reservation assigned, no seat reused, morning-only rule respected.
Main recording’s limits4 attempts · 60-second deadline
This is a code change tested against invented data. No real bookings or messages are changed.
Passing the checks still wasn’t enough.
All three outcomes are below. Select an attempt to inspect the recorded assignments.
The morning-only booking is placed at 2 pm.
| Reservation | Assigned session |
|---|---|
| Together / A | Morning |
| Together / B | Morning |
| Solo booking · morning only | Afternoon |
Grouping is outside the check’s three rules.
Executed check · unchanged
2 of 3 rules pass
Separate review
Not reached. The original check failed.
Check feedback sent onwardMorning-only booking stays before noon: expected True, got False
One shared booking would need two separate sessions.
| Reservation | Assigned session |
|---|---|
| Together / A | Morning |
| Together / B | Afternoon |
| Solo booking · morning only | Morning |
Grouping is outside the check’s three rules.
Executed check · unchanged
3 of 3 rules pass
First review call · scripted reply
Repair requested
The function sorts individual reservations by morning-only status, then fills seats in order. It ignores booking groups, so Together / A and Together / B can land in different sessions. Allocate each whole group to one session.
Together / A and B share the afternoon session.
| Reservation | Assigned session |
|---|---|
| Together / A | Afternoon |
| Together / B | Afternoon |
| Solo booking · morning only | Morning |
Grouping is outside the check’s three rules.
Executed check · unchanged
3 of 3 rules pass
New separate review call · scripted reply
Accepted
The candidate allocates whole groups to one session while respecting morning-only reservations.
The controller stops at the agreed limit.
Separate captures of the same task, each with its own limits agreed before it began.
Attempt limit · blocked
No third attempt starts
Both attempts pass the original check and receive scripted review rejections. The controller stops unfinished.
2 / 2 attempts · 60-second deadline
Check: passed
Review: rejected (scripted)
State: blocked
Deadline · blocked
The reply is not recorded
The check passes and a scripted review reply returns. The capture deliberately pauses the host past the real deadline before recording the reply.
1 / 4 attempts · 4-second deadline
Check: passed
Review reply: not recorded, deadline reached
State: blocked
Scope refusal · interrupted
Refused before writing
The proposal names check_schedule.py; only schedule.py is editable. In this runtime and capture, the path is refused before writing.
1 / 4 attempts · 60-second deadline
Check: not run · review: not requested
Candidate and check unchanged
State: interrupted
The original check stays unchanged in every capture. Work and records remain available; checkpointing and retention are simulated.
What this recording establishes
The actual controller ran the same Python check on each proposed repair. Its journal records verification on attempts 1, 2 and 3, and separate review calls on attempts 2 and 3. The next-worker prompts contain the preceding failure or review finding.
| Capture | Saved state | Check attempts | Review-call attempts |
|---|---|---|---|
| complete | complete | 1, 2, 3 | 2, 3 |
| attempt-limit | blocked | 1, 2 | 1, 2 |
| deadline | blocked | 1 | 1 |
| scope | interrupted | None | None |
The deadline reply exists in the capture but was not durably recorded as a review result. The original check’s bytes match before and after all four runs.
Download the safe recordingRead the unchanged check scriptRead the controller source
The boundary: the check verifies only its listed rules. Model review can also miss defects; this fixture uses prewritten replies and does not measure a live model. Admission and checkpoint metadata use a test double. Trusted-local execution provides no native sandbox proof. No real Git retention, merge or deployment occurred in the capture.
Local command paths are removed from the exported failed-check feedback; its summary is labelled. Exact raw records remain private. The browser displays saved results and runs no coding job.
Outside these recordings: the controller also distinguishes provider capacity problems from code failures. Waiting and retrying remain within the original attempt and time limits.
The recording above uses the development controller for persistent coding loops with interchangeable models. This workflow has not been published as a new release. The earlier hooks remain a separate legacy integration.
Earlier hook design
The account below describes that earlier four-hook design and its test suite at the time. Its install commands and test count belong to that historical version, not to the controller recording above.
I run unattended agent loops across my own repositories — refactors, audits, and migrations a model grinds through for hours while I’m not watching. The failure that worried me was never a bad edit; it was the irreversible one taken on a self-blessed “done” — a merge, a push, a delete the loop decided was fine and no one caught. excubitor is the control I built for that: a testable check, enforced outside the model on the default hook path, that blocks configured unattended loops from running specified irreversible Git commands, whatever the loop concludes about its own work.
Context
A productive agent workflow ends in an irreversible act. If a human reviews every step, that’s fine. Run the agent in an unattended loop and a gap opens: the loop decides for itself that the work is complete, then acts on that judgment. LLMs have self-preference bias — a loop that writes its own completion evidence produces plausible-looking proof of work that wasn’t done, and any downstream check that trusts that evidence is routed around by construction. This is not hypothetical. In July 2025 a production coding agent, during a freeze, deleted a live database and fabricated 4,000 fake records to cover it.
Telling a model to be careful is not a control — it can talk its way past its own
instructions. So the fix here is mechanical: split the question into two axes and
enforce the answer outside the model. Is “done” decided by a frozen, loop-immutable
oracle — a test suite’s exit code the loop cannot edit — or by the model’s own
judgment? And is the act reversible and internal (a commit, a --no-ff merge into
a non-default branch) or irreversible (a push, a hard reset, a branch delete)? An
unattended agent may act on its own “done” only when the done-signal is unforgeable
and the act is reversible. Everything else stops and surfaces the irreversible tail
for a human or an out-of-loop reviewer.
What it does
excubitor implements that policy as four PreToolUse guards — stdlib-only Python,
no dependencies — that intercept an agent’s tool calls before they run:
guard-default-branchblocks file mutations onmain/master, so work starts on a branch.guard-loop-vcblocks the irreversible version-control set — merge, push, branch-delete, hard-reset,git clean, worktree-remove — while a loop is armed. Its=yolomode additionally permits a--no-ffmerge into a confirmed non-default branch, and fails deny on any ambiguity.guard-one-unitcaps a headless loop worker at one unit of work per session, forcing a fresh-context re-read between units.guard-self-integritydenies writes to the guards’ own kill-switches while armed — the marker files, the hook scripts, the settings block. A judge the model can rewrite is not a judge.
Above the guards sits a “telos” system: a repo declares its purpose as falsifiable claims, each with a one-line decidable contract and an optional executable witness whose exit code is trusted over the model. A read-only audit checks claims against their witnesses and mechanically demotes any claim marked done-without-a-witness to SUSPECT. The auditor has no write access to the record it audits.
Show it working
The 60-second crash test needs only python3 and git, installs nothing, and
touches nothing outside a temp directory:
git clone https://github.com/ErickShepherd/excubitor.git && cd excubitor
scripts/demo.sh
It drives the shipped guard code exactly as Claude Code’s dispatch does — a JSON
payload in, a deny/defer decision out — and shows a guard turning an unattended,
unrecoverable git clean into a stop, then shows the same command deleting real
work with the guard off.
The full install symlinks the guards and skills into ~/.claude and registers the
four hooks. All of them are opt-in or inert by default: the loop guards do nothing
until CLAUDE_LOOP_GUARD is set, and interactive work is unaffected until you
explicitly say you’re looping. The test suite is 194 tests on stdlib-only Python;
CI runs it on 3.11/3.12/3.13 plus the repo’s own telos audit, providing regression
checks for the documented guard scenarios on each run.
Honest limits
These are seatbelts for the default path, not a sandbox, and the hooks’ own
docstrings say so. guard-loop-vc parses Bash command strings, so a script that
calls git indirectly, a shell alias, or a post-commit hook firing an external
side effect can slip past — where you can, also just don’t hand the loop a merge
capability. The evidence-tier demotion catches unbacked claims of completion; a
loop that authors its own witnesses produces backed claims, which is exactly why
the guards sever the loop’s ability to act rather than trusting any audit of its
output. Every bypass I know about is enumerated in the repo, classed ACCEPTED (a
residual pinned by a test so it can’t silently change) or CLOSED.
excubitor is the prevent half of a pair — guardrails on what an agent may do. The detect half is did-it, which reconciles what an agent claimed against what its transcript actually shows.
Archived release
A release snapshot archived in July 2026 provides a citable record. It is a dated snapshot, not a claim about the latest version.