Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 124 additions & 0 deletions .agents/scripts/guard.test.ts
Original file line number Diff line number Diff line change
@@ -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<string, unknown> = { session_id: 's1' },
options: { cwd?: string; env?: Record<string, string | undefined> } = {},
) {
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('')
})
67 changes: 67 additions & 0 deletions .agents/scripts/guard.ts
Original file line number Diff line number Diff line change
@@ -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<string, unknown>): 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<string, unknown> {
// 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<string, unknown>) : {}
}

async function main(): Promise<void> {
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 })
}
}
80 changes: 80 additions & 0 deletions .agents/scripts/hook-wiring.test.ts
Original file line number Diff line number Diff line change
@@ -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<string, { hooks: { command: string }[] }[]> }

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)
})
5 changes: 3 additions & 2 deletions .agents/scripts/lib/test-repo.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,15 @@ export function isolatedEnv(overrides: Record<string, string | undefined> = {}):
// 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]
}
Expand Down
7 changes: 7 additions & 0 deletions .agents/scripts/lib/tree.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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'])
Expand Down
14 changes: 8 additions & 6 deletions .agents/scripts/lib/tree.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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)}`)
Expand Down Expand Up @@ -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
Expand All @@ -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) =>
Expand Down
Loading
Loading