← All projects

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.

Code ↗ (opens in a new tab)

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.

The whole repair loopWorker edits, run the original check, then request separate review. A failed check returns to the edit stage. A rejected review also returns to the edit stage, then the original check runs again before another review. Accepted review leads to complete. The agreed attempt and time limits can stop continuation as blocked. Actual attempts are listed below. Worker editsRun theoriginal checkSeparate reviewscripted reply hereComplete PassAccept Check fails → repair Review requests repair → edit, check again, review again Both gates can send work backAn edit goes through the original check and separate review. The inner return arrow sends a failed check back to edit. The outer return arrow sends rejected review back to edit, followed by the original check and a new review. Accepted review leads to complete. Attempts below show what actually happened. Worker editsRun theoriginal checkSeparate reviewscripted replyComplete PassAccept Checkfails Reviewrejects
Both kinds of failure return to work. A review repair must pass the original check again, then receive a new review.

Passing the checks still wasn’t enough.

All three outcomes are below. Select an attempt to inspect the recorded assignments.

One shared booking would need two separate sessions.

Actual output from the original check
ReservationAssigned session
Together / AMorning
Together / BAfternoon
Solo booking · morning onlyMorning

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.

What Excubitor doesFinding sent to the next worker → same original check again → new separate review call.

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.

Attempts where the controller requested each gate
CaptureSaved stateCheck attemptsReview-call attempts
completecomplete1, 2, 32, 3
attempt-limitblocked1, 21, 2
deadlineblocked11
scopeinterruptedNoneNone

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.

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-branch blocks file mutations on main/master, so work starts on a branch.
  • guard-loop-vc blocks the irreversible version-control set — merge, push, branch-delete, hard-reset, git clean, worktree-remove — while a loop is armed. Its =yolo mode additionally permits a --no-ff merge into a confirmed non-default branch, and fails deny on any ambiguity.
  • guard-one-unit caps a headless loop worker at one unit of work per session, forcing a fresh-context re-read between units.
  • guard-self-integrity denies 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.

Skills & tools