diff --git a/.agents/scripts/guard.test.ts b/.agents/scripts/guard.test.ts new file mode 100644 index 0000000..99594d5 --- /dev/null +++ b/.agents/scripts/guard.test.ts @@ -0,0 +1,124 @@ +import { mkdtempSync, rmSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { afterEach, beforeEach, expect, it } from 'vitest' +import { createTempRepo, type TempRepo } from './lib/test-repo.ts' + +// guard.ts as the agents' hooks run it: a separate node process, the hook's JSON on stdin, in a +// throwaway repo holding a copy of .agents/scripts. +let repo: TempRepo + +function guard( + event: string, + payload: Record = { session_id: 's1' }, + options: { cwd?: string; env?: Record } = {}, +) { + const result = repo.run(process.execPath, [join(repo.dir, '.agents/scripts/guard.ts'), event], { + input: JSON.stringify(payload), + ...options, + }) + return { ...result, json: result.stdout ? JSON.parse(result.stdout) : undefined } +} + +beforeEach(() => { + repo = createTempRepo() + repo.copyFromCheckout('.agents/scripts/guard.ts', '.agents/scripts/lib') + repo.write('.gitignore', '.tmp/\n') + repo.write('src/a.ts', 'export const a = 1\n') + repo.git(['add', '.']) + repo.git(['commit', '--quiet', '-m', 'initial']) +}) + +afterEach(() => repo.cleanup()) + +it('prints nothing for a turn that changed nothing', () => { + expect(guard('turn-start').status).toBe(0) + const end = guard('turn-end') + expect(end.status).toBe(0) + expect(end.stdout).toBe('') +}) + +it('sends the agent back with the block decision every agent reads', () => { + guard('turn-start') + repo.write('src/a.ts', 'export const a = 2\n') + const end = guard('turn-end') + expect(end.status).toBe(0) + expect(end.json).toEqual({ decision: 'block', reason: expect.stringContaining('src/a.ts') }) +}) + +it('sends the agent back on the first stop even if another hook set stop_hook_active or loop_count', () => { + for (const reentry of [{ stop_hook_active: true }, { loop_count: 1 }]) { + guard('turn-start') + repo.write('src/a.ts', `export const a = ${JSON.stringify(reentry)}\n`) + expect(guard('turn-end', { session_id: 's1', ...reentry }).json?.decision).toBe('block') + const second = guard('turn-end', { session_id: 's1', ...reentry }) + expect(second.json).toEqual({ systemMessage: expect.stringContaining('agent-guard:') }) + } +}) + +it('guards the checkout it lives in, whatever the working directory and git variables', () => { + const elsewhere = mkdtempSync(join(tmpdir(), 'agent-elsewhere-')) + try { + const other = { GIT_DIR: join(elsewhere, '.git'), GIT_WORK_TREE: elsewhere } + guard('turn-start', { session_id: 's1' }, { cwd: elsewhere, env: other }) + repo.write('src/a.ts', 'export const a = 2\n') + const end = guard('turn-end', { session_id: 's1' }, { cwd: elsewhere, env: other }) + expect(end.json?.decision).toBe('block') + } finally { + rmSync(elsewhere, { recursive: true, force: true }) + } +}) + +it('uses one default session when the payload has no id', () => { + guard('turn-start', {}) + repo.write('src/a.ts', 'export const a = 2\n') + expect(guard('turn-end', {}).json?.decision).toBe('block') +}) + +it('fails open, visibly, when a library file is broken', () => { + guard('turn-start') + repo.write('.agents/scripts/lib/turn-gate.ts', 'this is not valid typescript (\n') + const end = guard('turn-end') + expect(end.status).toBe(0) + expect(end.json).toEqual({ + systemMessage: expect.stringContaining('turn-end hook failed, so it allowed the action'), + }) +}) + +it('fails open on input that is not JSON', () => { + const result = repo.run( + process.execPath, + [join(repo.dir, '.agents/scripts/guard.ts'), 'turn-end'], + { + input: 'not json', + }, + ) + expect(result.status).toBe(0) + expect(JSON.parse(result.stdout).systemMessage).toContain('hook failed') +}) + +it('fails open on an unknown event', () => { + const result = guard('turn-middle') + expect(result.status).toBe(0) + expect(result.json.systemMessage).toContain('unknown event "turn-middle"') +}) + +it('runs the gate even when the agent running the tests has DISABLE_AGENT_GUARD=1', () => { + const previous = process.env.DISABLE_AGENT_GUARD + process.env.DISABLE_AGENT_GUARD = '1' + try { + guard('turn-start') + repo.write('src/a.ts', 'export const a = 2\n') + expect(guard('turn-end').json?.decision).toBe('block') + } finally { + if (previous === undefined) delete process.env.DISABLE_AGENT_GUARD + else process.env.DISABLE_AGENT_GUARD = previous + } +}) + +it('does nothing with DISABLE_AGENT_GUARD=1', () => { + guard('turn-start') + repo.write('src/a.ts', 'export const a = 2\n') + const end = guard('turn-end', { session_id: 's1' }, { env: { DISABLE_AGENT_GUARD: '1' } }) + expect(end.stdout).toBe('') +}) diff --git a/.agents/scripts/guard.ts b/.agents/scripts/guard.ts new file mode 100644 index 0000000..8524a00 --- /dev/null +++ b/.agents/scripts/guard.ts @@ -0,0 +1,67 @@ +// The one entry point every agent's hooks call, so the rules can't drift apart per agent. +// +// node .agents/scripts/guard.ts turn-start when the person sends a message: snapshot the tree +// node .agents/scripts/guard.ts turn-end when the agent stops: may send it back once +// +// Input is the hook's JSON on stdin; Claude Code, Codex and Cursor send compatible shapes, and +// all three read `{"decision":"block","reason":...}` from a Stop hook. The guard keeps its own +// record of having sent the agent back, rather than trusting stop_hook_active or loop_count. It +// guards the checkout this file lives in, not the hook's working directory. A broken guard never +// blocks work: any error allows the action and says why. DISABLE_AGENT_GUARD=1 turns it off. +// See docs/agents.md. + +import { readFileSync } from 'node:fs' + +const event = process.argv[2] + +function reply(value: Record): void { + // No process.exit(): stdout to a hook can be an asynchronous pipe, and exiting early could + // cut off the JSON. + process.stdout.write(JSON.stringify(value)) +} + +function readPayload(): Record { + // Run by hand in a terminal, there is no hook payload; reading would wait for EOF. + if (process.stdin.isTTY) return {} + let text = '' + try { + text = readFileSync(0, 'utf8') + } catch { + return {} + } + return text.trim() ? (JSON.parse(text) as Record) : {} +} + +async function main(): Promise { + if (event !== 'turn-start' && event !== 'turn-end') { + throw new Error(`unknown event "${event}"`) + } + // Imported inside the try, so a broken library file fails open like any other error. + const { CHECKOUT_ROOT } = await import('./lib/git.ts') + const { endTurn, startTurn } = await import('./lib/turn-gate.ts') + + const payload = readPayload() + const sessionId = String( + payload.session_id ?? payload.conversation_id ?? payload.thread_id ?? 'default', + ) + if (event === 'turn-start') { + startTurn({ root: CHECKOUT_ROOT, sessionId }) + return + } + const verdict = endTurn({ root: CHECKOUT_ROOT, sessionId }) + if (verdict.decision === 'block') { + reply({ decision: 'block', reason: verdict.reason }) + } else if (verdict.note) { + reply({ systemMessage: `agent-guard: ${verdict.note}` }) + } +} + +if (process.env.DISABLE_AGENT_GUARD !== '1') { + try { + await main() + } catch (error) { + const message = `agent-guard: ${event ?? 'unknown'} hook failed, so it allowed the action. ${(error as Error)?.message ?? error}` + process.stderr.write(`${message}\n`) + reply({ systemMessage: message }) + } +} diff --git a/.agents/scripts/hook-wiring.test.ts b/.agents/scripts/hook-wiring.test.ts new file mode 100644 index 0000000..3fc7efb --- /dev/null +++ b/.agents/scripts/hook-wiring.test.ts @@ -0,0 +1,80 @@ +import { existsSync, readFileSync, rmSync } from 'node:fs' +import { join } from 'node:path' +import { afterEach, beforeEach, describe, expect, it } from 'vitest' +import { createTempRepo, REPO_ROOT, type TempRepo } from './lib/test-repo.ts' + +// Runs the exact hook commands from each agent's config, the way the agent would, in a +// throwaway repo with a copy of .agents/scripts. +type HookConfig = { hooks: Record } + +const AGENTS = [ + { + name: 'Claude Code', + config: '.claude/settings.json', + env: (dir: string) => ({ CLAUDE_PROJECT_DIR: dir }), + }, + // Hostile git variables, as a hook may inherit: the command must unset them to find the + // checkout. + { + name: 'Codex', + config: '.codex/hooks.json', + env: () => ({ GIT_DIR: '/nonexistent/.git', GIT_WORK_TREE: '/nonexistent' }), + }, + // Cursor runs the Claude Code hooks. If it does not set CLAUDE_PROJECT_DIR, the command falls + // back to the git root. + { + name: 'Cursor (Claude Code hooks, no CLAUDE_PROJECT_DIR)', + config: '.claude/settings.json', + env: () => ({ CLAUDE_PROJECT_DIR: undefined }), + }, +] + +function command(config: string, event: string): string { + const parsed = JSON.parse(readFileSync(join(REPO_ROOT, config), 'utf8')) as HookConfig + const commands = parsed.hooks[event]?.flatMap((entry) => + entry.hooks.map((hook) => hook.command), + ) + expect(commands, `${config} ${event}`).toHaveLength(1) + return commands?.[0] ?? '' +} + +let repo: TempRepo + +beforeEach(() => { + repo = createTempRepo() + repo.copyFromCheckout('.agents/scripts/guard.ts', '.agents/scripts/lib') + repo.write('.gitignore', '.tmp/\n') + repo.write('src/a.ts', 'export const a = 1\n') + repo.git(['add', '.']) + repo.git(['commit', '--quiet', '-m', 'initial']) +}) + +afterEach(() => repo.cleanup()) + +describe.each(AGENTS)('$name', ({ config, env }) => { + const run = (event: string) => + repo.run('sh', ['-c', command(config, event)], { + cwd: join(repo.dir, 'src'), + env: env(repo.dir), + input: JSON.stringify({ session_id: 'wiring' }), + }) + + it('sends the agent back after an unverified code change', () => { + expect(run('UserPromptSubmit').status).toBe(0) + repo.write('src/a.ts', 'export const a = 2\n') + const stop = run('Stop') + expect(stop.status).toBe(0) + expect(JSON.parse(stop.stdout)).toMatchObject({ decision: 'block' }) + }) + + it('says so, and lets work continue, in a checkout without the guard', () => { + rmSync(join(repo.dir, '.agents'), { recursive: true }) + const stop = run('Stop') + expect(stop.status).toBe(0) + expect(JSON.parse(stop.stdout).systemMessage).toContain('has no .agents/scripts/guard.ts') + }) +}) + +it('has no Cursor hooks file: Cursor runs the Claude Code hooks, and a second file runs them twice', () => { + expect(existsSync(join(REPO_ROOT, '.cursor/hooks.json'))).toBe(false) +}) diff --git a/.agents/scripts/lib/test-repo.ts b/.agents/scripts/lib/test-repo.ts index 7beab9c..a3f0d36 100644 --- a/.agents/scripts/lib/test-repo.ts +++ b/.agents/scripts/lib/test-repo.ts @@ -14,14 +14,15 @@ export function isolatedEnv(overrides: Record = {}): // Clears the variables git exports to hooks. Left in place, a git command in a test would // act on the real repository: `npm test` runs inside the pre-push hook. const env = cleanGitEnv() - // LEFTHOOK=0 may be set by the person or agent running the tests; it would turn off what the - // tests check. + // DISABLE_AGENT_GUARD and LEFTHOOK=0 may be set by the person or agent running the tests; they + // would turn off what the tests check. for (const name of [ 'GITHUB_ACTIONS', 'LEFTHOOK', 'LEFTHOOK_BIN', 'LEFTHOOK_CONFIG', 'GIT_CONFIG_PARAMETERS', + 'DISABLE_AGENT_GUARD', ]) { delete env[name] } diff --git a/.agents/scripts/lib/tree.test.ts b/.agents/scripts/lib/tree.test.ts index ef10bb2..0852438 100644 --- a/.agents/scripts/lib/tree.test.ts +++ b/.agents/scripts/lib/tree.test.ts @@ -52,6 +52,13 @@ describe('snapshot', () => { expect(changedPaths(before, snapshot(repo.dir))).toEqual(['src/a.ts']) }) + it('is the same before and after a deletion is staged', () => { + rmSync(join(repo.dir, 'src/a.ts')) + const unstaged = snapshot(repo.dir) + repo.git(['add', '--all']) + expect(snapshot(repo.dir)).toEqual(unstaged) + }) + it('sees an executable bit change', () => { const before = codeFingerprint(snapshot(repo.dir)) repo.run('chmod', ['+x', 'src/a.ts']) diff --git a/.agents/scripts/lib/tree.ts b/.agents/scripts/lib/tree.ts index b8a0220..51a84c9 100644 --- a/.agents/scripts/lib/tree.ts +++ b/.agents/scripts/lib/tree.ts @@ -14,17 +14,20 @@ export function snapshot(root: string): Snapshot { if (!listed.ok) throw new Error(`git ls-files failed: ${listed.stderr.trim()}`) const files: Snapshot = {} for (const path of new Set(listed.stdout.split('\0').filter(Boolean))) { - files[path] = hashPath(join(root, path)) + const hash = hashPath(join(root, path)) + // A tracked file deleted from disk is left out, exactly as it is once the deletion is + // staged, so staging a deletion doesn't change the snapshot. + if (hash !== undefined) files[path] = hash } return files } -function hashPath(path: string): string { +function hashPath(path: string): string | undefined { let stat try { stat = lstatSync(path) } catch { - return 'missing' + return undefined } const hash = createHash('sha256') if (stat.isSymbolicLink()) hash.update(`link:${readlinkSync(path)}`) @@ -70,8 +73,7 @@ export function classify(path: string): FileKind { return 'code' } -const present = (files: Snapshot, path: string) => - files[path] !== undefined && files[path] !== 'missing' +const present = (files: Snapshot, path: string) => files[path] !== undefined /** * Hash of every file local checks read, so editing docs, or files only CI reads, after a pass @@ -88,7 +90,7 @@ export function codeFingerprint(files: Snapshot): string { return hash.digest('hex') } -/** Changed files local checks read. */ +/** Changed files local checks read: what verify and the turn gate both act on. */ export function changedCodePaths(before: Snapshot, after: Snapshot): string[] { return changedPaths(before, after).filter( (path) => diff --git a/.agents/scripts/lib/turn-gate.test.ts b/.agents/scripts/lib/turn-gate.test.ts new file mode 100644 index 0000000..e973902 --- /dev/null +++ b/.agents/scripts/lib/turn-gate.test.ts @@ -0,0 +1,187 @@ +import { existsSync, rmSync, utimesSync } from 'node:fs' +import { join } from 'node:path' +import { afterEach, beforeEach, describe, expect, it } from 'vitest' +import { writeVerified } from './state.ts' +import { createTempRepo, type TempRepo } from './test-repo.ts' +import { codeFingerprint, snapshot } from './tree.ts' +import { endTurn, startTurn } from './turn-gate.ts' + +let repo: TempRepo +const session = 'session-1' + +const start = () => startTurn({ root: repo.dir, sessionId: session }) +const end = () => endTurn({ root: repo.dir, sessionId: session }) +const markVerified = () => + writeVerified(repo.dir, { + fingerprint: codeFingerprint(snapshot(repo.dir)), + head: 'x', + at: 'now', + }) + +beforeEach(() => { + repo = createTempRepo() + repo.write('.gitignore', '.tmp/\n') + repo.write('src/a.ts', 'export const a = 1\n') + repo.write('README.md', 'readme\n') + repo.git(['add', '.']) + repo.git(['commit', '--quiet', '-m', 'initial']) +}) + +afterEach(() => repo.cleanup()) + +describe('turns that pass', () => { + it('lets a turn that changed nothing end', () => { + start() + expect(end()).toEqual({ decision: 'allow' }) + }) + + it('lets a docs-only turn end without a reminder', () => { + start() + repo.write('README.md', 'changed\n') + repo.write('docs/new.md', 'new\n') + expect(end()).toEqual({ decision: 'allow' }) + }) + + it('lets a turn that undid its edits end', () => { + start() + repo.write('src/a.ts', 'export const a = 2\n') + repo.write('src/a.ts', 'export const a = 1\n') + repo.write('src/tmp.ts', 'scratch\n') + rmSync(join(repo.dir, 'src/tmp.ts')) + expect(end()).toEqual({ decision: 'allow' }) + }) + + it('lets a turn end when verify passed on the exact tree', () => { + start() + repo.write('src/a.ts', 'export const a = 2\n') + markVerified() + expect(end()).toEqual({ decision: 'allow' }) + }) + + it('keeps the pass when a deletion verify saw is then staged', () => { + repo.git(['switch', '--quiet', '-c', 'feature']) + start() + rmSync(join(repo.dir, 'src/a.ts')) + markVerified() + repo.git(['add', '--all']) + expect(end()).toEqual({ decision: 'allow' }) + }) + + it('keeps the pass when only docs changed after verify', () => { + start() + repo.write('src/a.ts', 'export const a = 2\n') + markVerified() + repo.write('README.md', 'changed after verify\n') + expect(end()).toEqual({ decision: 'allow' }) + }) + + it('notes a change only CI checks, without sending the agent back', () => { + start() + repo.write('renovate.json', '{}\n') + const verdict = end() + expect(verdict.decision).toBe('allow') + expect(verdict).toHaveProperty('note', expect.stringContaining('only CI checks')) + }) +}) + +describe('turns that changed code without verifying', () => { + it('sends the agent back once, naming the files and what to do', () => { + start() + repo.write('src/a.ts', 'export const a = 2\n') + const verdict = end() + expect(verdict.decision).toBe('block') + expect(verdict).toHaveProperty('reason', expect.stringContaining('src/a.ts')) + expect(verdict).toHaveProperty('reason', expect.stringContaining('npm run verify')) + }) + + it('lets the agent stop the second time, with a note for the person', () => { + start() + repo.write('src/a.ts', 'export const a = 2\n') + expect(end().decision).toBe('block') + const second = end() + expect(second.decision).toBe('allow') + expect(second).toHaveProperty('note', expect.stringContaining('src/a.ts')) + }) + + it('sends the agent back again in the next turn', () => { + start() + repo.write('src/a.ts', 'export const a = 2\n') + end() + end() + start() + repo.write('src/a.ts', 'export const a = 3\n') + expect(end().decision).toBe('block') + }) + + it('catches an edit that keeps the file size', () => { + start() + repo.write('src/a.ts', 'export const a = 9\n') + expect(end().decision).toBe('block') + }) + + it('catches a deleted doc, which the agent docs may name', () => { + start() + rmSync(join(repo.dir, 'README.md')) + expect(end().decision).toBe('block') + }) + + it('catches a new untracked file', () => { + start() + repo.write('src/new.ts', 'new\n') + expect(end().decision).toBe('block') + }) + + it('catches code changed after verify passed', () => { + start() + repo.write('src/a.ts', 'export const a = 2\n') + markVerified() + repo.write('src/a.ts', 'export const a = 3\n') + expect(end().decision).toBe('block') + }) + + it('checks each session against the tree it saw at its own turn start', () => { + repo.write('src/a.ts', 'export const a = 2\n') + start() + repo.write('src/a.ts', 'export const a = 3\n') + startTurn({ root: repo.dir, sessionId: 'other' }) + repo.write('src/a.ts', 'export const a = 2\n') + // Back at the tree this session started from; the other session started from a = 3. + expect(end()).toEqual({ decision: 'allow' }) + expect(endTurn({ root: repo.dir, sessionId: 'other' }).decision).toBe('block') + }) +}) + +describe('a branch', () => { + beforeEach(() => repo.git(['switch', '--quiet', '-c', 'feature'])) + + it('lets the turn end when the code is back to what main has', () => { + repo.write('src/a.ts', 'export const a = 2\n') + repo.git(['commit', '--quiet', '-am', 'change']) + start() + repo.git(['revert', '--no-edit', '--quiet', 'HEAD']) + repo.write('docs/note.md', 'note\n') + expect(end()).toEqual({ decision: 'allow' }) + }) + + it('still sends the agent back when the branch differs from main', () => { + start() + repo.write('src/a.ts', 'export const a = 2\n') + expect(end().decision).toBe('block') + }) +}) + +it('removes turn records older than a week when a turn starts', () => { + startTurn({ root: repo.dir, sessionId: 'old' }) + const old = join(repo.dir, '.tmp/agents/turns/old.json') + const weekAgo = new Date(Date.now() - 8 * 24 * 60 * 60 * 1000) + utimesSync(old, weekAgo, weekAgo) + start() + expect(existsSync(old)).toBe(false) + expect(existsSync(join(repo.dir, `.tmp/agents/turns/${session}.json`))).toBe(true) +}) + +it('allows the turn, and says why, without a turn-start record', () => { + const verdict = end() + expect(verdict.decision).toBe('allow') + expect(verdict).toHaveProperty('note', expect.stringContaining('no turn-start record')) +}) diff --git a/.agents/scripts/lib/turn-gate.ts b/.agents/scripts/lib/turn-gate.ts new file mode 100644 index 0000000..25db931 --- /dev/null +++ b/.agents/scripts/lib/turn-gate.ts @@ -0,0 +1,112 @@ +// The end-of-turn gate. At turn start it snapshots the tree; at turn end it sends the agent back +// once if the turn changed code that `npm run verify` has not passed. "Once" lets an agent stop on +// purpose and say what is unfinished. + +import { readdirSync, rmSync, statSync } from 'node:fs' +import { join } from 'node:path' +import { branchBase } from './git.ts' +import { readJson, readVerified, stateDir, writeJson } from './state.ts' +import { + changedCodePaths, + changedPaths, + changedSince, + classify, + codeFingerprint, + needsChecks, + type Snapshot, + snapshot, +} from './tree.ts' + +type TurnState = { start: Snapshot; sentBack: boolean } + +export type Verdict = { decision: 'allow'; note?: string } | { decision: 'block'; reason: string } + +const MAX_LISTED = 5 +// Turn records older than this belong to sessions that are gone. +const STALE_TURN_MS = 7 * 24 * 60 * 60 * 1000 + +function turnPath(root: string, sessionId: string): string { + return join(stateDir(root), 'turns', `${sessionId.replace(/[^\w.-]/g, '_')}.json`) +} + +function list(paths: string[]): string { + const shown = paths.slice(0, MAX_LISTED).join(', ') + return paths.length > MAX_LISTED ? `${shown} and ${paths.length - MAX_LISTED} more` : shown +} + +export function startTurn({ root, sessionId }: { root: string; sessionId: string }): void { + pruneStaleTurns(root) + writeJson(turnPath(root, sessionId), { start: snapshot(root), sentBack: false }) +} + +function pruneStaleTurns(root: string, now = Date.now()): void { + const dir = join(stateDir(root), 'turns') + let names: string[] + try { + names = readdirSync(dir) + } catch { + return + } + for (const name of names) { + const path = join(dir, name) + if (now - statSync(path).mtimeMs > STALE_TURN_MS) rmSync(path, { force: true }) + } +} + +export function endTurn({ + root, + sessionId, + base = branchBase(root), +}: { + root: string + sessionId: string + /** Where the branch left the default branch; undefined when there is none. */ + base?: string +}): Verdict { + const path = turnPath(root, sessionId) + const state = readJson(path) + if (!state?.start) { + return { + decision: 'allow', + note: 'no turn-start record for this session, so the end-of-turn check was skipped', + } + } + + const now = snapshot(root) + const changed = changedPaths(state.start, now) + const code = changedCodePaths(state.start, now) + const ciOnly = changed.filter((file) => classify(file) === 'unchecked') + const ciNote = ciOnly.length + ? `only CI checks ${list(ciOnly)}; say so in your report` + : undefined + + if (code.length === 0) return { decision: 'allow', note: ciNote } + const verified = readVerified(root) + if (verified && verified.fingerprint === codeFingerprint(now)) { + return { decision: 'allow', note: ciNote } + } + // The code is back to what the default branch has (an undo, a stash, a branch switch), which + // CI already checked. verify says "only docs changed" here and records nothing, so asking for + // it would send the agent back for nothing. + if (base && !changedSince(root, base).some((file) => needsChecks(root, file))) { + return { decision: 'allow', note: ciNote } + } + + // Only this guard's own record counts: stop_hook_active or loop_count can also be set by + // another hook sending the agent back, which would skip this one. + if (state.sentBack) { + return { + decision: 'allow', + note: `the turn ended with changes npm run verify has not passed: ${list(code)}`, + } + } + + writeJson(path, { ...state, sentBack: true }) + return { + decision: 'block', + reason: + `You changed code this turn that \`npm run verify\` has not passed: ${list(code)}. ` + + 'Run `npm run verify` and fix what fails. If you are stopping on purpose, say what ' + + 'is unfinished and what you did not verify; you will not be sent back again this turn.', + } +} diff --git a/.agents/scripts/verify.ts b/.agents/scripts/verify.ts index 92fb519..762d236 100644 --- a/.agents/scripts/verify.ts +++ b/.agents/scripts/verify.ts @@ -1,5 +1,5 @@ // `npm run verify`: every check CI runs on a pull request, in about fifteen seconds. -// Records a fingerprint of the tree only when everything passed. +// Records a fingerprint of the tree only when everything passed; the end-of-turn gate reads it. import { CHECKOUT_ROOT, branchBase, defaultBranchRef } from './lib/git.ts' import { clearVerified } from './lib/state.ts' diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..fbc275c --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,26 @@ +{ + "hooks": { + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "root=\"$CLAUDE_PROJECT_DIR\"; [ -n \"$root\" ] || root=$(unset $(git rev-parse --local-env-vars 2>/dev/null); git rev-parse --show-toplevel 2>/dev/null) || root=.; f=\"$root/.agents/scripts/guard.ts\"; if [ -f \"$f\" ]; then node \"$f\" turn-start; else echo '{\"systemMessage\":\"agent-guard: this checkout has no .agents/scripts/guard.ts, so turn-start was skipped\"}'; fi", + "timeout": 30 + } + ] + } + ], + "Stop": [ + { + "hooks": [ + { + "type": "command", + "command": "root=\"$CLAUDE_PROJECT_DIR\"; [ -n \"$root\" ] || root=$(unset $(git rev-parse --local-env-vars 2>/dev/null); git rev-parse --show-toplevel 2>/dev/null) || root=.; f=\"$root/.agents/scripts/guard.ts\"; if [ -f \"$f\" ]; then node \"$f\" turn-end; else echo '{\"systemMessage\":\"agent-guard: this checkout has no .agents/scripts/guard.ts, so turn-end was skipped\"}'; fi", + "timeout": 30 + } + ] + } + ] + } +} diff --git a/.codex/hooks.json b/.codex/hooks.json new file mode 100644 index 0000000..6386ac3 --- /dev/null +++ b/.codex/hooks.json @@ -0,0 +1,26 @@ +{ + "hooks": { + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "unset $(git rev-parse --local-env-vars 2>/dev/null); root=$(git rev-parse --show-toplevel 2>/dev/null) || root=.; f=\"$root/.agents/scripts/guard.ts\"; if [ -f \"$f\" ]; then node \"$f\" turn-start; else echo '{\"systemMessage\":\"agent-guard: this checkout has no .agents/scripts/guard.ts, so turn-start was skipped\"}'; fi", + "timeout": 30 + } + ] + } + ], + "Stop": [ + { + "hooks": [ + { + "type": "command", + "command": "unset $(git rev-parse --local-env-vars 2>/dev/null); root=$(git rev-parse --show-toplevel 2>/dev/null) || root=.; f=\"$root/.agents/scripts/guard.ts\"; if [ -f \"$f\" ]; then node \"$f\" turn-end; else echo '{\"systemMessage\":\"agent-guard: this checkout has no .agents/scripts/guard.ts, so turn-end was skipped\"}'; fi", + "timeout": 30 + } + ] + } + ] + } +} diff --git a/.tmp/agents/verified.json b/.tmp/agents/verified.json deleted file mode 100644 index 61604cc..0000000 --- a/.tmp/agents/verified.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "fingerprint": "c3b3b61844ff7597bfa198795421f6eb8f3d8cb7338f4ce03b2b56ccd195c40c", - "head": "508fdd1db454b59ecac99170d1544cdc49097807", - "at": "2026-11-05T11:20:48.660Z" -} diff --git a/AGENTS.md b/AGENTS.md index 648df99..d995af9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -109,6 +109,7 @@ throw new CliError('ERROR_CODE', 'User-facing message', ['Optional hint']) ## Git hooks and agent tooling - Lefthook refuses commits and pushes to `main`, runs oxlint, oxfmt and the type check on pre-commit, and the tests on pre-push. Work on a branch. +- When a turn changes code that `npm run verify` has not passed, the end-of-turn hook (Claude Code, Codex, Cursor) sends you back once. Run verify, or stop on purpose and say what is unverified. - Agent tooling lives in `.agents/scripts/`, never in `scripts/` (which ships in the npm package). - How it all fits together: [`docs/agents.md`](docs/agents.md). diff --git a/CODEBASE.md b/CODEBASE.md index 53cfa39..626b8bd 100644 --- a/CODEBASE.md +++ b/CODEBASE.md @@ -34,8 +34,10 @@ come from `@doist/cli-core`. │ │ # review-changes) │ ├─ checks/ # Review checks reviewers and Doistbot apply (AGENTS.md links them) │ └─ scripts/ # Agent tooling (verify, git hook branch guard, review -│ # worktree) and its tests. Not published, unlike scripts/ +│ # worktree, end-of-turn gate) and its tests. Not +│ # published, unlike scripts/ ├─ .claude/skills/ # Links to .agents/skills/, where Claude Code finds them +├─ .claude/settings.json # End-of-turn gate hooks (.codex/hooks.json for Codex) ├─ docs/agents.md # How the agent tooling fits together ├─ AGENTS.md # Prescriptive rules (definition of done, build cmds, JSON flag, │ # skill-sync, errors) diff --git a/docs/agents.md b/docs/agents.md index 6136786..c1e4b62 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -9,6 +9,7 @@ This repository is set up so coding agents prove their work before they call it 3. **`AGENTS.md`** tells agents what done means. Claude Code reads it through `CLAUDE.md`; Codex and other agents read it directly. 4. **Skills** in `.agents/skills/` give step-by-step procedures for recurring work. They load only when a task needs them. 5. **Review**: fresh reviewers and Doistbot check a finished change against the checks in `.agents/checks/`. +6. **The end-of-turn gate** sends an agent back once when its turn changed code that `npm run verify` has not passed. ## Rules and what holds them @@ -21,7 +22,7 @@ This repository is set up so coding agents prove their work before they call it | Tests pass before a push | `pre-push`; CI | Enforced in CI | | Agent tooling never ships in the npm package | `.agents/scripts/package-contents.test.ts` | Enforced in CI | | `npm run verify` runs what CI runs | `.agents/scripts/lib/steps.test.ts` compares it with the pull-request workflows | Enforced in CI | -| Run `npm run verify` before calling work done | `AGENTS.md` | Asked | +| Run `npm run verify` before calling work done | `AGENTS.md` | Enforced at turn end (once); `AGENTS.md` | | Never weaken a check to pass it | `AGENTS.md` | Asked | | Instructions name only files, links and scripts that exist | `.agents/scripts/instructions.test.ts` | Enforced in CI | | Every skill says when to use it and is linked for Claude Code | `.agents/scripts/instructions.test.ts` | Enforced in CI | @@ -55,12 +56,34 @@ One command, every check the pull-request workflows run (`lint.yml`, `test.yml`, - **Order:** every check starts together, except the skill sync check, which imports from `dist/` and so waits for the build. - **`CI=true`** is set for the build, the tests and the skill sync check, as GitHub Actions sets it. Variables that change what the CLI does (`COMMS_API_TOKEN`, `COMMS_AS_URL`, `COMMS_BASE_URL`, `COMMS_INCLUDE_PRIVATE_CHANNELS`, `TWIST_AUTH_TOKEN`, `TWIST_BASE_URL`, `TDC_ACCESSIBLE`, `TDC_SPINNER`, `FORCE_COLOR`) are removed, with a note, since CI never sets them. A real token or server never reaches the tests. - **Output:** one line per step. A failing step prints the last 30 lines of its log and the log's path under `.tmp/agents/logs/`. -- **The record:** after a full pass it writes a content hash of every file local checks read (not docs, not CI-only files) to `.tmp/agents/verified.json`. A run that fails, or sees files change while it runs, deletes it. +- **The record:** after a full pass it writes a content hash of every file local checks read (not docs, not CI-only files) to `.tmp/agents/verified.json`. A run that fails, or sees files change while it runs, deletes it. The end-of-turn gate reads it. - **Platforms:** macOS, Linux and WSL. Like the git hooks, it assumes a POSIX shell and runs npm's POSIX launchers in `node_modules/.bin`; on native Windows, run it in WSL. - **What it cannot see:** the real Comms API, output in a real terminal, the other Node version CI tests on, and the `gh skill publish --dry-run` spec check. It prints these after every pass. If a pull-request workflow gains a step, `.agents/scripts/lib/steps.test.ts` fails until verify gains it too, or says why it can't. +## The end-of-turn gate + +Every agent's hooks call one script, `.agents/scripts/guard.ts`, so the agents can't drift apart. + +- **Turn start** (you send a message): it hashes every file in the checkout, untracked ones included, into `.tmp/agents/turns/`. +- **Turn end** (the agent stops): it compares the tree with the turn's start and with the last `npm run verify` pass. If the turn changed code and verify has not passed on exactly this tree, it sends the agent back once, naming the files. The second time, it lets the agent stop and shows you a note. +- **Passes without a word:** turns that changed nothing, changed only docs, or undid their edits. +- **"Once"** is deliberate: an agent can stop on purpose and say what is unfinished. + +| Agent | Wiring | Known limits | +| ----------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Claude Code | `.claude/settings.json`: `UserPromptSubmit` and `Stop` | `hook-wiring.test.ts` runs the exact commands. Not yet seen sending a real session back. | +| Codex | `.codex/hooks.json`: `UserPromptSubmit` and `Stop` | Runs only in a trusted project, after each person reviews the hooks in `/hooks`. Some versions run no project hooks in a linked worktree. Not yet tried here. | +| Cursor | Runs the Claude Code hooks itself; the command falls back to the git root if Cursor does not set `CLAUDE_PROJECT_DIR` | No Cursor hooks file: a second one would run every hook twice. A test keeps it out. Not yet tried here. | + +**Other limits:** + +- Two sessions in one checkout share its files, so each may be told about the other's edits. Use a worktree per session. +- If the branch's code is back to what `main` has (an undo, a stash, a switch), the turn passes: CI already checked that code. + +**Fails open, visibly:** a broken guard, bad input or a checkout without the script lets the turn end and says why in a message. `DISABLE_AGENT_GUARD=1` in the agent's environment turns the gate off for you. + ## Skills Each skill is a short procedure with a check at the end of every step. Agents load one when the task matches its description. @@ -130,4 +153,5 @@ semantic-release publishes from `main` on every merge, and a pre-release from `n - No node on `PATH` in a GUI client: the hooks skip lint, the type check and the tests, with a message. The branch rule still applies. - `git commit --no-verify`: every local hook is skipped. CI and branch protection still apply. +- The end-of-turn gate: any error lets the turn end, with a message saying why. `DISABLE_AGENT_GUARD=1` turns it off. - Worktrees share the hooks in `.git/hooks`, so the branch rule works in a new worktree at once. Lint, format, types and tests need `npm ci` in that worktree first. Without the lefthook binary anywhere the hooks look, they print "Can't find lefthook in PATH" and let the commit through.