@kintsugi-ai/hook 0.1.0

package/dist/index.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfig, listFlows, loadFlow, captureCurrentState, compareFlow, formatAgentFeedback, buildClassifierContext, loadKintsugiEnv, DiffResult } from '@kintsugi-ai/core';
+import { detectAgent, outputFeedback, exitWithResult } from './agent-detect.js';
+import { extractTurnContext } from './context.js';
+import { writeEscalation, readEscalation, clearEscalation } from './escalation.js';
+import { createLogger } from './logger.js';
+async function main() {
+    const earlyWarnings = [];
+    // Check command line arguments for explicit event flags (e.g. --event stop)
+    const isExplicitStopEvent = process.argv.includes('stop') ||
+        process.argv.some(arg => arg.toLowerCase().includes('stop'));
+    let stdinData = '';
+    try {
+        stdinData = fs.readFileSync(0, 'utf-8');
+    }
+    catch {
+        // stdin may not be available
+        earlyWarnings.push('could not read stdin (no piped hook payload?)');
+    }
+    let input = {};
+    if (stdinData.trim()) {
+        try {
+            input = JSON.parse(stdinData);
+        }
+        catch (e) {
+            earlyWarnings.push(`stdin is not valid JSON: ${e.message} preview=${stdinData.slice(0, 500)}`);
+        }
+    }
+    else {
+        earlyWarnings.push('stdin was empty — agent sent no hook payload');
+    }
+    const agent = detectAgent(input);
+    // Stop events arrive as terminationReason (agy), hook_event_name: "Stop"
+    // (Claude Code), or the explicit --event stop flag in registered configs.
+    const eventName = typeof input.hook_event_name === 'string'
+        ? input.hook_event_name.toLowerCase()
+        : undefined;
+    const isStopEvent = isExplicitStopEvent || Boolean(input.terminationReason) || eventName === 'stop';
+    // Some agents (Antigravity/agy) run hooks with cwd set to their config
+    // dir (e.g. <workspace>/.agents) rather than the workspace root. Resolve
+    // the real project dir from the payload's workspacePaths when available.
+    const projectDir = input.workspacePaths?.[0] ?? process.cwd();
+    const log = createLogger(projectDir);
+    log.info('hook invoked', {
+        argv: process.argv.slice(2),
+        cwd: process.cwd(),
+        projectDir,
+        stdinBytes: stdinLength(),
+    });
+    for (const w of earlyWarnings)
+        log.warn(w);
+    log.info('agent detected', { agent, isStopEvent, isExplicitStopEvent, inputKeys: Object.keys(input) });
+    if (!isStopEvent) {
+        // Kintsugi checks once per turn (Stop event), not on every file edit —
+        // per-edit checks would replay flows dozens of times per turn.
+        log.info('non-stop event — deferring visual check to turn end');
+        outputFeedback(agent, '', { isStopEvent: false, hasRegression: false });
+        process.exit(0);
+    }
+    await runTurnEndCheck(agent, input, projectDir, log);
+}
+/**
+ * Turn-end visual check: verifies every recorded flow in parallel (each in
+ * its own browser context), classifies oversized diffs in parallel, and on a
+ * regression blocks the agent's stop with fix-it feedback until it passes or
+ * maxAttempts is reached.
+ */
+async function runTurnEndCheck(agent, input, projectDir, log) {
+    // Pick up gitignored <project>/.kintsugi/.env before resolving the token
+    loadKintsugiEnv(projectDir);
+    const config = await loadConfig(projectDir);
+    log.info('config loaded', { devServerUrl: config.devServerUrl, classifierModel: config.classifier.model });
+    // Shared builder (also used by `kintsugi check` and MCP) — bootstraps an
+    // anonymous hosted key on first use so the classifier is never silently dark.
+    const classifierContext = await buildClassifierContext(config, {
+        context: extractTurnContext(input),
+        logger: log,
+        bootstrapKey: true,
+        projectDir,
+    });
+    const flows = await listFlows(projectDir);
+    log.info('flows discovered', {
+        flowsDir: path.join(projectDir, '.kintsugi', 'flows'),
+        count: flows.length,
+        names: flows.map(f => f.name),
+    });
+    if (flows.length === 0) {
+        log.info('no recorded flows — nothing to check');
+        outputFeedback(agent, '', { isStopEvent: true, hasRegression: false });
+        process.exit(0);
+    }
+    const maxAttempts = config.agent.maxRetries;
+    const outcomes = await Promise.all(flows.map(async (flow) => {
+        try {
+            return await checkFlow(flow.name, config, classifierContext, projectDir, log);
+        }
+        catch (err) {
+            log.error('flow check crashed', { flowName: flow.name, error: err.message });
+            return { flowName: flow.name, isRegression: false };
+        }
+    }));
+    const broken = outcomes.filter(o => o.isRegression);
+    if (broken.length === 0) {
+        // Clean pass — either nothing broke or the agent just fixed the
+        // previous regression. Either way the agent may stop.
+        log.info('turn-end check passed — clearing any previous escalation');
+        await clearEscalation(projectDir);
+        outputFeedback(agent, '', { isStopEvent: true, hasRegression: false });
+        process.exit(0);
+    }
+    // The fresh check above is the source of truth; only treat a pending
+    // escalation as "still unfixed" now that the current state is known broken.
+    const pendingEscalation = await readEscalation(projectDir);
+    if (pendingEscalation && pendingEscalation.attempt >= maxAttempts) {
+        log.info('max fix attempts reached — allowing agent to stop', {
+            flowName: pendingEscalation.flowName,
+            attempt: pendingEscalation.attempt,
+            maxAttempts,
+        });
+        await clearEscalation(projectDir);
+        outputFeedback(agent, '', { isStopEvent: true, hasRegression: false });
+        process.exit(0);
+    }
+    const first = broken[0];
+    const attempt = (pendingEscalation?.attempt || 0) + 1;
+    await writeEscalation(projectDir, {
+        flowName: first.flowName,
+        result: first.comparisonResult,
+        oldVideoPath: first.oldPath ?? '',
+        newVideoPath: first.newPath ?? '',
+        timestamp: new Date().toISOString(),
+        attempt,
+        maxAttempts,
+    });
+    // Fix-it feedback covers every broken flow: aria diffs, image pairs, per-pair fixes
+    const combinedFeedback = broken
+        .map(o => formatAgentFeedback(o.comparisonResult, o.flowName))
+        .join('\n\n');
+    log.warn('turn-end regression — blocking agent stop with feedback', {
+        flows: broken.map(b => b.flowName),
+        attempt,
+        maxAttempts,
+    });
+    outputFeedback(agent, combinedFeedback, { isStopEvent: true, hasRegression: true });
+    exitWithResult(agent, true);
+}
+/** Replays one flow and compares it against its baseline. */
+async function checkFlow(flowName, config, classifierContext, projectDir, log) {
+    const flowRecord = await loadFlow(projectDir, flowName);
+    if (!flowRecord) {
+        log.warn('flow metadata listed but could not be loaded', { flowName });
+        return { flowName, isRegression: false };
+    }
+    log.info('checking flow', { flowName, stepCount: flowRecord.steps.length, baselineScreenshots: flowRecord.screenshotPaths.length });
+    const outputDir = path.join(projectDir, '.kintsugi', '.tmp', flowName);
+    fs.mkdirSync(outputDir, { recursive: true });
+    const currentState = await captureCurrentState({
+        url: config.devServerUrl,
+        flow: flowRecord,
+        outputDir,
+        viewport: config.viewport,
+    });
+    log.info('current state captured', { flowName, url: config.devServerUrl, screenshots: currentState.screenshots.length, errors: currentState.errors.length });
+    const comparisonResult = await compareFlow(flowRecord, currentState, { outputDir, classifier: classifierContext });
+    log.info('comparison finished', { flowName, result: comparisonResult.result });
+    // Any definite visual change (CHANGED) or broken capture is a regression —
+    // the baseline flow no longer matches the live page. INTENTIONAL means the
+    // classifier accepted the change.
+    const isRegression = comparisonResult.result !== DiffResult.IDENTICAL &&
+        comparisonResult.result !== DiffResult.MINOR &&
+        comparisonResult.result !== DiffResult.INTENTIONAL;
+    if (!isRegression) {
+        if (comparisonResult.result === DiffResult.INTENTIONAL) {
+            log.info('large visual change accepted as intentional by classifier', { flowName });
+        }
+        return { flowName, isRegression: false, comparisonResult };
+    }
+    log.warn('REGRESSION detected', { flowName, result: comparisonResult.result });
+    const failedIndex = comparisonResult.failedStep ?? 0;
+    return {
+        flowName,
+        isRegression: true,
+        comparisonResult,
+        oldPath: flowRecord.screenshotPaths[failedIndex] ?? flowRecord.screenshotPaths[0] ?? '',
+        newPath: currentState.screenshotPaths[failedIndex] ?? currentState.screenshotPaths[0] ?? '',
+    };
+}
+function stdinLength() {
+    try {
+        return fs.fstatSync(0).size;
+    }
+    catch {
+        return -1;
+    }
+}
+main().catch((e) => {
+    try {
+        const log = createLogger(process.cwd());
+        log.error('hook crashed', e);
+    }
+    catch { /* ignore */ }
+    // Exit non-zero so the agent knows something went wrong.
+    // Write a diagnostic to stderr for agents that capture it.
+    process.stderr.write(`kintsugi hook crashed: ${e instanceof Error ? e.message : String(e)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/logger.d.ts

@@ -0,0 +1,7 @@
+export declare function createLogger(projectDir: string): {
+    info: (message: string, data?: unknown) => void;
+    warn: (message: string, data?: unknown) => void;
+    error: (message: string, error?: unknown) => void;
+    logPath: string;
+};
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAiBA,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM;oBAkBvB,MAAM,SAAS,OAAO;oBAGtB,MAAM,SAAS,OAAO;qBAGrB,MAAM,UAAU,OAAO;;EAK/C"}

package/dist/logger.js

@@ -0,0 +1,58 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Debug logging for the kintsugi hook.
+ *
+ * The #1 failure mode for agent hooks is silent early-exit: the hook runs,
+ * decides "nothing to do", and exits 0 without any trace. To debug why a
+ * regression was NOT caught, we log every decision point to
+ * `<projectDir>/.kintsugi/logs/hook.log` (always) and to stderr (when
+ * KINTSUGI_DEBUG=1, since agent CLIs may otherwise swallow or misrender
+ * unexpected stderr).
+ */
+const LOG_DIRNAME = path.join('.kintsugi', 'logs');
+const LOG_FILENAME = 'hook.log';
+export function createLogger(projectDir) {
+    const debugToStderr = process.env.KINTSUGI_DEBUG === '1';
+    const logPath = path.join(projectDir, LOG_DIRNAME, LOG_FILENAME);
+    function write(line) {
+        const entry = `[${new Date().toISOString()}] ${line}\n`;
+        try {
+            fs.mkdirSync(path.dirname(logPath), { recursive: true });
+            fs.appendFileSync(logPath, entry);
+        }
+        catch {
+            // Never let logging break the hook
+        }
+        if (debugToStderr) {
+            process.stderr.write(`[kintsugi-hook] ${entry}`);
+        }
+    }
+    return {
+        info: (message, data) => {
+            write(data === undefined ? message : `${message} ${safeStringify(data)}`);
+        },
+        warn: (message, data) => {
+            write(`WARN: ${data === undefined ? message : `${message} ${safeStringify(data)}`}`);
+        },
+        error: (message, error) => {
+            write(`ERROR: ${message}${error ? ` ${formatError(error)}` : ''}`);
+        },
+        logPath,
+    };
+}
+function safeStringify(data) {
+    try {
+        return JSON.stringify(data);
+    }
+    catch {
+        return String(data);
+    }
+}
+function formatError(error) {
+    if (error instanceof Error) {
+        return `${error.message}\n${error.stack ?? ''}`;
+    }
+    return safeStringify(error);
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;;;;;GASG;AAEH,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;AACnD,MAAM,YAAY,GAAG,UAAU,CAAC;AAEhC,MAAM,UAAU,YAAY,CAAC,UAAkB;IAC3C,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,KAAK,GAAG,CAAC;IACzD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;IAEjE,SAAS,KAAK,CAAC,IAAY;QACvB,MAAM,KAAK,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,IAAI,IAAI,CAAC;QACxD,IAAI,CAAC;YACD,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACzD,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACL,mCAAmC;QACvC,CAAC;QACD,IAAI,aAAa,EAAE,CAAC;YAChB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mBAAmB,KAAK,EAAE,CAAC,CAAC;QACrD,CAAC;IACL,CAAC;IAED,OAAO;QACH,IAAI,EAAE,CAAC,OAAe,EAAE,IAAc,EAAE,EAAE;YACtC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC9E,CAAC;QACD,IAAI,EAAE,CAAC,OAAe,EAAE,IAAc,EAAE,EAAE;YACtC,KAAK,CAAC,SAAS,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,aAAa,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;QACzF,CAAC;QACD,KAAK,EAAE,CAAC,OAAe,EAAE,KAAe,EAAE,EAAE;YACxC,KAAK,CAAC,UAAU,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACvE,CAAC;QACD,OAAO;KACV,CAAC;AACN,CAAC;AAED,SAAS,aAAa,CAAC,IAAa;IAChC,IAAI,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;AACL,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IAC/B,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QACzB,OAAO,GAAG,KAAK,CAAC,OAAO,KAAK,KAAK,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;IACpD,CAAC;IACD,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC"}

package/dist/ui-file-detector.d.ts

@@ -0,0 +1,9 @@
+export declare const DEFAULT_UI_PATTERNS: string[];
+/**
+ * Detects if a file is a UI file that might require visual regression testing.
+ * @param filePath The path to the modified file.
+ * @param patterns Optional array of glob patterns to match against.
+ * @returns True if the file is considered a UI file.
+ */
+export declare function isUIFile(filePath: string, patterns?: string[]): boolean;
+//# sourceMappingURL=ui-file-detector.d.ts.map

package/dist/ui-file-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-file-detector.d.ts","sourceRoot":"","sources":["../src/ui-file-detector.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,mBAAmB,UAG/B,CAAC;AAKF;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,EAAwB,GAAG,OAAO,CAuB5F"}

package/dist/ui-file-detector.js

@@ -0,0 +1,34 @@
+import path from 'node:path';
+export const DEFAULT_UI_PATTERNS = [
+    '**/*.tsx', '**/*.jsx', '**/*.vue', '**/*.svelte',
+    '**/*.html', '**/*.css', '**/*.scss'
+];
+const UI_EXTENSIONS = new Set(['.tsx', '.jsx', '.vue', '.svelte', '.html', '.css', '.scss']);
+const NON_UI_SUBSTRINGS = ['.test.', '.spec.', '.config.', '/test/', '/tests/'];
+/**
+ * Detects if a file is a UI file that might require visual regression testing.
+ * @param filePath The path to the modified file.
+ * @param patterns Optional array of glob patterns to match against.
+ * @returns True if the file is considered a UI file.
+ */
+export function isUIFile(filePath, patterns = DEFAULT_UI_PATTERNS) {
+    const ext = path.extname(filePath).toLowerCase();
+    for (const sub of NON_UI_SUBSTRINGS) {
+        if (filePath.includes(sub)) {
+            return false;
+        }
+    }
+    if (UI_EXTENSIONS.has(ext)) {
+        return true;
+    }
+    // Simplified pattern matching if not matched by extension
+    for (const pattern of patterns) {
+        // Extract extension from glob patterns like '**/*.tsx' or '*.css'
+        const extMatch = pattern.match(/\*\.([a-zA-Z0-9]+)$/);
+        if (extMatch && ext === '.' + extMatch[1]) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=ui-file-detector.js.map

package/dist/ui-file-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-file-detector.js","sourceRoot":"","sources":["../src/ui-file-detector.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,CAAC,MAAM,mBAAmB,GAAG;IAC/B,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa;IACjD,WAAW,EAAE,UAAU,EAAE,WAAW;CACvC,CAAC;AAEF,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAC7F,MAAM,iBAAiB,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,QAAgB,EAAE,WAAqB,mBAAmB;IAC/E,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IAEjD,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE,CAAC;QAClC,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,OAAO,KAAK,CAAC;QACjB,CAAC;IACL,CAAC;IAED,IAAI,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,0DAA0D;IAC1D,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC7B,kEAAkE;QAClE,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;QACtD,IAAI,QAAQ,IAAI,GAAG,KAAK,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;YACxC,OAAO,IAAI,CAAC;QAChB,CAAC;IACL,CAAC;IAED,OAAO,KAAK,CAAC;AACjB,CAAC"}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@kintsugi-ai/hook",
+  "version": "0.1.0",
+  "description": "Agent hook script for Kintsugi visual regression checks",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "kintsugi-hook": "./dist/index.js"
+  },
+  "dependencies": {
+    "@kintsugi-ai/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test dist/**/*.test.js"
+  }
+}

package/src/agent-detect.test.ts

@@ -0,0 +1,53 @@
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+    detectAgent,
+    getModifiedFilePath,
+    type HookInput
+} from './agent-detect.js';
+
+describe('Agent Detection & Protocol Adaptation', () => {
+    test('detects Antigravity (agy) from stdin payload markers', () => {
+        const agyPayload: HookInput = {
+            conversationId: '550e8400-e29b-41d4-a716-446655440000',
+            workspacePaths: ['/workspace/kintsugi'],
+            toolCall: {
+                name: 'write_to_file',
+                args: {
+                    TargetFile: 'src/components/Checkout.tsx',
+                }
+            }
+        };
+
+        const detected = detectAgent(agyPayload);
+        assert.equal(detected, 'agy');
+
+        const filePath = getModifiedFilePath(detected, agyPayload);
+        assert.equal(filePath, 'src/components/Checkout.tsx');
+    });
+
+    test('detects Antigravity from Stop event payload', () => {
+        const stopPayload: HookInput = {
+            conversationId: '550e8400-e29b-41d4-a716-446655440000',
+            terminationReason: 'model_stop',
+            fullyIdle: true
+        };
+
+        const detected = detectAgent(stopPayload);
+        assert.equal(detected, 'agy');
+    });
+
+    test('extracts modified file path from Codex tool input', () => {
+        const codexPayload: HookInput = {
+            tool_input: {
+                file_path: 'src/Navbar.tsx'
+            }
+        };
+
+        const detected = detectAgent(codexPayload);
+        assert.equal(detected, 'codex');
+
+        const filePath = getModifiedFilePath(detected, codexPayload);
+        assert.equal(filePath, 'src/Navbar.tsx');
+    });
+});

package/src/agent-detect.ts

@@ -0,0 +1,167 @@
+/**
+ * Agent type detection and protocol helpers for Claude Code, Codex CLI, and Antigravity (agy).
+ */
+
+export type AgentType = 'claude-code' | 'codex' | 'agy' | 'unknown';
+
+export interface HookInput {
+    // Antigravity (agy) protocol fields
+    conversationId?: string;
+    workspacePaths?: string[];
+    transcriptPath?: string;
+    artifactDirectoryPath?: string;
+    terminationReason?: string;
+    toolCall?: {
+        name: string;
+        args?: {
+            TargetFile?: string;
+            CommandLine?: string;
+            [key: string]: unknown;
+        };
+    };
+
+    // Claude / Codex protocol fields
+    hook_event_name?: string;
+    tool_input?: {
+        file_path?: string;
+        path?: string;
+        TargetFile?: string;
+        [key: string]: unknown;
+    };
+    tool_name?: string;
+    session_id?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * Detects the type of agent invoking the hook.
+ * @param stdin Optional parsed stdin payload to inspect markers.
+ * @returns The detected agent type.
+ */
+export function detectAgent(stdin?: HookInput): AgentType {
+    // 1. Explicit Antigravity (agy) payload markers in stdin
+    if (
+        stdin?.conversationId ||
+        stdin?.transcriptPath ||
+        stdin?.toolCall
+    ) {
+        return 'agy';
+    }
+
+    // 2. Explicit Claude Code markers
+    if (process.env.CLAUDE_SESSION_ID || process.env.CLAUDE_FILE_PATH) {
+        return 'claude-code';
+    }
+
+    // 3. Explicit Codex payload marker (tool_input without agy headers)
+    if (stdin?.tool_input && !stdin?.conversationId) {
+        return 'codex';
+    }
+
+    // 4. Ambient environment markers
+    if (process.env.ANTIGRAVITY_AGENT || process.env.GEMINI_CLI) {
+        return 'agy';
+    }
+
+    // 5. Default fallback
+    return 'codex';
+}
+
+/**
+ * Extracts the modified file path from the agent context.
+ * @param agent The type of agent.
+ * @param stdin The input from standard input.
+ * @returns The modified file path, if found.
+ */
+export function getModifiedFilePath(agent: AgentType, stdin: HookInput): string | undefined {
+    if (agent === 'agy') {
+        return (
+            stdin?.toolCall?.args?.TargetFile ||
+            (stdin?.toolCall?.args?.['target_file'] as string | undefined) ||
+            stdin?.tool_input?.TargetFile ||
+            stdin?.tool_input?.file_path
+        );
+    }
+
+    if (agent === 'claude-code') {
+        return (
+            process.env.CLAUDE_FILE_PATH ||
+            stdin?.tool_input?.file_path ||
+            (stdin?.tool_input?.['filePath'] as string | undefined)
+        );
+    }
+
+    return (
+        stdin?.tool_input?.file_path ||
+        stdin?.tool_input?.path ||
+        stdin?.tool_input?.TargetFile
+    );
+}
+
+/**
+ * Outputs feedback based on the agent type protocols.
+ * @param agent The type of agent.
+ * @param feedback The formatted feedback string.
+ * @param options Additional metadata such as whether this is a Stop event.
+ */
+export function outputFeedback(
+    agent: AgentType,
+    feedback: string,
+    options?: { isStopEvent?: boolean; hasRegression?: boolean }
+): void {
+    if (agent === 'agy') {
+        if (options?.isStopEvent) {
+            if (options.hasRegression) {
+                // Antigravity Stop Hook protocol: continue execution loop with reason
+                const response = {
+                    decision: 'continue',
+                    reason: feedback
+                };
+                process.stdout.write(JSON.stringify(response, null, 2) + '\n');
+            } else {
+                process.stdout.write('{}\n');
+            }
+        } else {
+            // Antigravity PostToolUse contract expects empty JSON {}
+            process.stdout.write('{}\n');
+        }
+    } else if (agent === 'claude-code') {
+        if (options?.isStopEvent) {
+            // Claude Code Stop-hook contract: {"decision":"block"} keeps the
+            // agent working with `reason` as the feedback. Plain stdout text
+            // would not reach the model on a Stop event.
+            if (options.hasRegression) {
+                const response = {
+                    decision: 'block',
+                    reason: feedback
+                };
+                process.stdout.write(JSON.stringify(response, null, 2) + '\n');
+            } else {
+                process.stdout.write('{}\n');
+            }
+        } else {
+            process.stdout.write(feedback + '\n');
+        }
+    } else {
+        process.stderr.write(feedback + '\n');
+    }
+}
+
+/**
+ * Exits the process with the appropriate code for the agent.
+ * @param agent The type of agent.
+ * @param hasRegression Whether a regression was detected.
+ */
+export function exitWithResult(agent: AgentType, hasRegression: boolean): never {
+    if (agent === 'agy') {
+        // Antigravity communicates decisions via JSON on stdout, with exit code 0
+        process.exit(0);
+    } else if (agent === 'claude-code') {
+        // Claude always expects exit 0; feedback is passed via stdout
+        process.exit(0);
+    } else if (agent === 'codex') {
+        // Codex expects exit 2 for failure (reject action)
+        process.exit(hasRegression ? 2 : 0);
+    }
+    process.exit(0);
+}