Repository navigation
chore(agents): send agents back once when a turn ends unverified - #109
Merged
scottlovegrove merged 3 commits intoNov 5, 2026
Merged
scottlovegrove merged 3 commits into
scottlovegrove merged 3 commits into
Conversation
doistbot
reviewed
Nov 5, 2026
doistbot
left a comment
Member
There was a problem hiding this comment.
This PR adds an end-of-turn guard that sends agents back once when their turn changed code without a passing npm run verify, wired into the Claude Code, Codex, and Cursor hooks, with solid fail-open behavior and good test coverage.
Few things worth tightening:
- Deletions staged after verification invalidate the recorded fingerprint:
snapshot()represents an unstaged deletion aspath: 'missing', but drops it once Git removes the file from the index, so the tree hash changes without any content change and a verified turn gets sent back. Normalize absent files independently of index state, and add a verify → stage deletion → stop regression test. - The multi-session test doesn't prove each session is compared against its own turn-start snapshot — both sessions start before the same edit, so the assertions would pass even with a single global snapshot. Start the second session after the edit and assert the first is blocked while the second is allowed.
I also included a few optional follow-up notes in the details below.
Optional follow-up notes (6)
.agents/scripts/lib/turn-gate.ts:99: This second-stop allow path drops
ciNote, so when a turn changes both code and a CI-only file and the agent stops again without verifying, the systemMessage names only the code files. AppendciNotehere so the "only CI checks ...; say so in your report" reminder is not lost..agents/scripts/lib/turn-gate.ts:51: statSync here can throw ENOENT if another guard process prunes the same stale record between readdirSync and statSync. Two sessions in one checkout is a documented scenario, and every turn-start prunes, so concurrent turn starts after a week of idle time can hit this. The throw propagates out of startTurn, so the whole turn goes un-snapshotted and the gate is skipped with a "no turn-start record" note. Wrapping statSync in the same kind of try/catch used for readdirSync (or relying on rmSync's force flag) keeps the pruning best-effort.
.agents/scripts/lib/turn-gate.ts:28:
sessionId.replace(/[^\w.-]/g, '_')duplicates the same filename-sanitizing expression in.agents/scripts/lib/verify.ts(line 120, step names to log filenames). Both produce a safe filename from a variable string; a smallsafeName()helper instate.ts(which both files already import) would keep the one pattern in one place..agents/scripts/lib/turn-gate.ts:58:
baseis a defaulted parameter that no caller ever supplies, and the defaultbranchBase(root)is evaluated on everyendTurncall before the turn state is even read. That spawns several git subprocesses for turns that changed nothing (and even when there is no turn-start record). ComputebranchBase(root)lazily in the single branch that needs it and drop the unused parameter..agents/scripts/lib/turn-gate.ts:76:
changedCodePaths(state.start, now)internally callschangedPathsagain (see tree.ts), so the full key-union, compare and sort over every file in the snapshot runs twice per turn end. Sincechangedis already in hand, derive the code paths from it:const code = changed.filter((file) => classify(file) === 'code'). Snapshots can cover every file in the checkout, so this halves the redundant pass for free..agents/scripts/guard.test.ts:76: The tests cover session_id and the missing-id 'default' fallback, but not the conversation_id and thread_id branches of the session-id lookup in guard.ts. That mapping is the cross-agent contract this PR relies on: if a fallback regressed, that agent's turns would all share the 'default' record, so one session could consume another's single send-back or see its tree snapshot. A one-line it.each row starting a turn and ending it with { thread_id: 't1' } and { conversation_id: 'c1' } (expecting 'block') would pin it.
scottlovegrove
force-pushed
the
scottlovegrove/agents-5-turn-gate
branch
from
November 5, 2026 11:22
9fc72b2 to
3e62471
Compare
scottlovegrove
force-pushed
the
scottlovegrove/agents-5-turn-gate
branch
from
November 5, 2026 11:27
3e62471 to
30b01bb
Compare
When an agent's turn changed code that npm run verify has not passed, the agent is sent back once, naming the files. The second stop is allowed, with a note for the person, so an agent can stop on purpose and say what is unfinished. One script, .agents/scripts/guard.ts, is called from the Claude Code hooks (.claude/settings.json, which Cursor also runs) and the Codex hooks (.codex/hooks.json). At turn start it hashes the checkout; at turn end it compares the tree with that snapshot and with the last verify pass. Turns that changed nothing, only docs, or undid their edits pass silently. A broken guard never blocks work: it lets the turn end and says why. DISABLE_AGENT_GUARD=1 turns it off.
A tracked file deleted from disk no longer appears in the snapshot as 'missing'; it is left out, exactly as once the deletion is staged, so staging a deletion verify already saw keeps the pass. The per-session test now starts the two sessions from different trees, so it fails if the gate reads the wrong session's record. The gate's back-to-main rule now uses needsChecks too, so a turn that deletes a doc the agent docs may name is sent back like a code change.
.tmp/agents/verified.json was committed by mistake before .gitignore listed .tmp/. It is per-checkout state that verify rewrites on every pass.
scottlovegrove
force-pushed
the
scottlovegrove/agents-5-turn-gate
branch
from
November 5, 2026 11:53
30b01bb to
14d349e
Compare
Contributor
|
🎉 This PR is included in version 3.10.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
Part 5 of 5. When an agent's turn changed code that
npm run verifyhasn't passed, the agent is sent back once.What was changed
.agents/scripts/guard.ts, called from the Claude Code hooks (.claude/settings.json, which Cursor also runs) and the Codex hooks (.codex/hooks.json).DISABLE_AGENT_GUARD=1turns it off.Please check
Proof
Not verified
/hooks.