Skip to content

chore(agents): send agents back once when a turn ends unverified - #109

Merged
scottlovegrove merged 3 commits into
scottlovegrove/agents-4-reviewfrom
scottlovegrove/agents-5-turn-gate
Nov 5, 2026
Merged

scottlovegrove merged 3 commits into
scottlovegrove/agents-4-reviewfrom
scottlovegrove/agents-5-turn-gate

Conversation

@scottlovegrove

@scottlovegrove scottlovegrove commented Nov 5, 2026 •

Copy link
Copy Markdown
Collaborator

Context

Part 5 of 5. When an agent's turn changed code that npm run verify hasn't passed, the agent is sent back once.

What was changed

  • One script, .agents/scripts/guard.ts, 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, if code changed and verify didn't pass on exactly that tree, it sends the agent back once, naming the files.
  • The second stop is allowed, with a note for you, so an agent can stop on purpose and say what's unfinished.
  • Turns that changed nothing, only docs, or undid their edits pass silently. Deleting a doc counts as a change; staging a deletion verify already saw keeps the pass.
  • A broken guard never blocks work: it lets the turn end and says why. DISABLE_AGENT_GUARD=1 turns it off.

Please check

  • Strictness: "send back once" is the default todoist-mcp settled on.

Proof

  • Tests for each case, plus tests that run the exact hook commands from each agent's config.
  • The same tests and hook commands as in todoist-cli, where breaking the gate in four ways each turned them red.

Not verified

  • A real session being sent back, in Claude Code, Codex or Cursor. Codex also needs each person to trust the project and review the hooks in /hooks.

@scottlovegrove scottlovegrove added the 🚢 Ship PR requires passing checks before merge, but no independent human review. label Nov 5, 2026
@scottlovegrove scottlovegrove self-assigned this Nov 5, 2026

@doistbot doistbot left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 as path: '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)
  • P3 .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. Append ciNote here so the "only CI checks ...; say so in your report" reminder is not lost.
  • P3 .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.
  • P3 .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 small safeName() helper in state.ts (which both files already import) would keep the one pattern in one place.
  • P3 .agents/scripts/lib/turn-gate.ts:58: base is a defaulted parameter that no caller ever supplies, and the default branchBase(root) is evaluated on every endTurn call 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). Compute branchBase(root) lazily in the single branch that needs it and drop the unused parameter.
  • P3 .agents/scripts/lib/turn-gate.ts:76: changedCodePaths(state.start, now) internally calls changedPaths again (see tree.ts), so the full key-union, compare and sort over every file in the snapshot runs twice per turn end. Since changed is 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.
  • P3 .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.

Share Feedback • Review Logs

Comment thread .agents/scripts/lib/turn-gate.ts Resolved
Comment thread .agents/scripts/lib/turn-gate.test.ts Resolved
@scottlovegrove
scottlovegrove force-pushed the scottlovegrove/agents-5-turn-gate branch from 9fc72b2 to 3e62471 Compare November 5, 2026 11:22
@scottlovegrove
scottlovegrove force-pushed the scottlovegrove/agents-5-turn-gate branch from 3e62471 to 30b01bb Compare November 5, 2026 11:27
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
scottlovegrove added this pull request to stack #110 November 5, 2026 11:53
@scottlovegrove
scottlovegrove force-pushed the scottlovegrove/agents-5-turn-gate branch from 30b01bb to 14d349e Compare November 5, 2026 11:53
@scottlovegrove
scottlovegrove merged commit ee82e37 into main Nov 5, 2026
6 checks passed
@scottlovegrove
scottlovegrove deleted the scottlovegrove/agents-5-turn-gate branch November 5, 2026 11:55
@doist-release-bot

Copy link
Copy Markdown
Contributor

🎉 This PR is included in version 3.10.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

released 🚢 Ship PR requires passing checks before merge, but no independent human review.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants