agent-gauntlet 0.10.0 → 0.11.0

package/src/hooks/adapters/claude-stop-hook.ts

@@ -1,99 +0,0 @@
-import type {
-	StopHookAdapter,
-	StopHookContext,
-	StopHookResult,
-} from "./types.js";
-
-/**
- * Claude Code hook response format.
- */
-interface ClaudeHookResponse {
-	decision: "block" | "approve";
-	reason?: string;
-	stopReason: string;
-	systemMessage?: string;
-	status: string;
-	message: string;
-}
-
-/**
- * Adapter for Claude Code stop hook protocol.
- *
- * Claude Code protocol:
- * - Input: { cwd, stop_hook_active, session_id, transcript_path, hook_event_name, permission_mode }
- * - Output: { decision: "block"|"approve", reason?, stopReason, systemMessage?, status, message }
- * - Block mechanism: decision: "block" with reason (fed back to Claude as prompt)
- * - Allow mechanism: decision: "approve"
- */
-export class ClaudeStopHookAdapter implements StopHookAdapter {
-	name = "claude";
-
-	/**
-	 * Detect if this adapter should handle the given input.
-	 * Claude Code doesn't send cursor_version, so we detect by absence.
-	 */
-	detect(raw: Record<string, unknown>): boolean {
-		// Claude Code doesn't send cursor_version
-		return !("cursor_version" in raw);
-	}
-
-	/**
-	 * Parse Claude Code input into normalized context.
-	 */
-	parseInput(raw: Record<string, unknown>): StopHookContext {
-		return {
-			cwd: (raw.cwd as string) ?? process.cwd(),
-			isNestedHook: raw.stop_hook_active === true,
-			sessionId: raw.session_id as string | undefined,
-			rawInput: raw,
-		};
-	}
-
-	/**
-	 * Get the block reason for a given result based on status.
-	 */
-	private getBlockReason(result: StopHookResult): string | undefined {
-		const reasonMap: Record<string, string | undefined> = {
-			failed: result.instructions,
-			pr_push_required: result.pushPRReason,
-			ci_failed: result.ciFixReason,
-			ci_pending: result.ciPendingReason,
-		};
-		return reasonMap[result.status];
-	}
-
-	/**
-	 * Format handler result into Claude Code protocol output.
-	 */
-	formatOutput(result: StopHookResult): string {
-		const blockReason = this.getBlockReason(result);
-		const stopReason =
-			result.shouldBlock && blockReason ? blockReason : result.message;
-
-		const response: ClaudeHookResponse = {
-			decision: result.shouldBlock ? "block" : "approve",
-			stopReason,
-			systemMessage: result.message,
-			status: result.status,
-			message: result.message,
-		};
-
-		if (result.shouldBlock && blockReason) {
-			response.reason = blockReason;
-		}
-
-		return JSON.stringify(response);
-	}
-
-	/**
-	 * Check if execution should be skipped based on Claude-specific conditions.
-	 * Note: stop_hook_active from stdin is currently disabled in the main entry point
-	 * because Claude Code sends it after blocking twice, but we need to re-run.
-	 */
-	shouldSkipExecution(_ctx: StopHookContext): StopHookResult | null {
-		// The isNestedHook check is handled at the entry point level
-		// via the marker file mechanism, not here.
-		// This method is available for future protocol-specific skip conditions.
-		return null;
-	}
-}

package/src/hooks/adapters/cursor-stop-hook.ts

@@ -1,122 +0,0 @@
-import type {
-	StopHookAdapter,
-	StopHookContext,
-	StopHookResult,
-} from "./types.js";
-
-/**
- * Cursor hook response format.
- * - Empty object {} = allow stop (no feedback)
- * - { systemMessage: "..." } = allow stop with user-visible message
- * - { followup_message: "..." } = block stop and continue with message
- */
-interface CursorHookResponse {
-	followup_message?: string;
-	systemMessage?: string;
-}
-
-/**
- * Default maximum loop count before allowing stop.
- * Cursor has built-in loop_limit (default 5, configurable in hooks.json),
- * but we provide defense-in-depth with our own check.
- */
-const DEFAULT_MAX_LOOPS = 10;
-
-/**
- * Adapter for Cursor IDE stop hook protocol.
- *
- * Cursor protocol:
- * - Input: { status, loop_count, cursor_version, workspace_roots, conversation_id, ... }
- * - Output: { followup_message?: "..." } or {}
- * - Block mechanism: { followup_message: "instructions" } - continues agent with message
- * - Allow mechanism: {} (empty object) - allows stop
- * - Loop prevention: loop_count field (Cursor has built-in loop_limit)
- */
-export class CursorStopHookAdapter implements StopHookAdapter {
-	name = "cursor";
-
-	/**
-	 * Maximum loop count before forcing stop.
-	 * Can be configured via hooks.json loop_limit.
-	 */
-	private maxLoops: number;
-
-	constructor(maxLoops: number = DEFAULT_MAX_LOOPS) {
-		this.maxLoops = maxLoops;
-	}
-
-	/**
-	 * Detect if this adapter should handle the given input.
-	 * Cursor sends cursor_version in hook input.
-	 */
-	detect(raw: Record<string, unknown>): boolean {
-		return "cursor_version" in raw;
-	}
-
-	/**
-	 * Parse Cursor input into normalized context.
-	 */
-	parseInput(raw: Record<string, unknown>): StopHookContext {
-		const workspaceRoots = raw.workspace_roots;
-		const loopCount = raw.loop_count as number | undefined;
-
-		return {
-			cwd:
-				(Array.isArray(workspaceRoots) ? workspaceRoots[0] : null) ??
-				process.cwd(),
-			isNestedHook: false, // Cursor uses loop_count instead of nested hook flag
-			loopCount,
-			sessionId: raw.conversation_id as string | undefined,
-			rawInput: raw,
-		};
-	}
-
-	/**
-	 * Get the block message for a given result based on status.
-	 */
-	private getBlockMessage(result: StopHookResult): string {
-		const messageMap: Record<string, string | undefined> = {
-			failed: result.instructions,
-			pr_push_required: result.pushPRReason,
-			ci_failed: result.ciFixReason,
-			ci_pending: result.ciPendingReason,
-		};
-		return messageMap[result.status] || result.message;
-	}
-
-	/**
-	 * Format handler result into Cursor protocol output.
-	 */
-	formatOutput(result: StopHookResult): string {
-		if (result.shouldBlock) {
-			const response: CursorHookResponse = {
-				followup_message: this.getBlockMessage(result),
-			};
-			return JSON.stringify(response);
-		}
-
-		// Include systemMessage for user feedback even when not blocking
-		const response: CursorHookResponse = {
-			systemMessage: result.message,
-		};
-		return JSON.stringify(response);
-	}
-
-	/**
-	 * Check if execution should be skipped based on Cursor-specific conditions.
-	 * Returns early if loop_count exceeds threshold.
-	 */
-	shouldSkipExecution(ctx: StopHookContext): StopHookResult | null {
-		// Cursor has built-in loop_limit (default 5), but we can check here too
-		// for defense-in-depth
-		if (ctx.loopCount !== undefined && ctx.loopCount >= this.maxLoops) {
-			return {
-				status: "retry_limit_exceeded",
-				shouldBlock: false,
-				message:
-					"Loop limit reached — run `agent-gauntlet clean` to archive and continue.",
-			};
-		}
-		return null;
-	}
-}

package/src/hooks/adapters/types.ts

@@ -1,94 +0,0 @@
-import type { GauntletStatus, RunResult } from "../../types/gauntlet-status.js";
-
-/**
- * Protocol-agnostic context passed from adapter to handler.
- * Contains normalized fields from either Claude Code or Cursor input.
- */
-export interface StopHookContext {
-	/** Working directory for the project */
-	cwd: string;
-	/** True if this is a nested hook invocation (Claude: stop_hook_active, Cursor: high loop_count) */
-	isNestedHook: boolean;
-	/** Cursor-specific: current loop iteration count */
-	loopCount?: number;
-	/** Session/conversation identifier for logging */
-	sessionId?: string;
-	/** Original parsed JSON input for diagnostics */
-	rawInput: Record<string, unknown>;
-}
-
-/**
- * Protocol-agnostic result from handler to adapter.
- * Contains all information needed to format protocol-specific output.
- */
-export interface StopHookResult {
-	/** Machine-readable status code */
-	status: GauntletStatus;
-	/** Whether the stop should be blocked */
-	shouldBlock: boolean;
-	/** Fix instructions when blocking due to failed gates */
-	instructions?: string;
-	/** PR push instructions when blocking due to pr_push_required */
-	pushPRReason?: string;
-	/** CI fix instructions when blocking due to ci_failed */
-	ciFixReason?: string;
-	/** CI pending instructions when blocking due to ci_pending */
-	ciPendingReason?: string;
-	/** Human-friendly status message */
-	message: string;
-	/** Interval minutes (when status is interval_not_elapsed) */
-	intervalMinutes?: number;
-	/** Individual gate results for detailed failure information */
-	gateResults?: RunResult["gateResults"];
-}
-
-/**
- * Result from PR status check.
- */
-export interface PRStatusResult {
-	/** Whether a PR exists for the current branch */
-	prExists: boolean;
-	/** Whether the PR is up to date with local HEAD */
-	upToDate: boolean;
-	/** Error message if check failed (graceful degradation) */
-	error?: string;
-	/** PR number if it exists */
-	prNumber?: number;
-}
-
-/**
- * Adapter interface for protocol-specific stop hook handling.
- * Each adapter handles input parsing, output formatting, and protocol-specific behavior.
- */
-export interface StopHookAdapter {
-	/** Human-readable name for logging */
-	name: string;
-
-	/**
-	 * Detect if this adapter should handle the given input.
-	 * @param raw Parsed JSON from stdin
-	 * @returns true if this adapter should handle the input
-	 */
-	detect(raw: Record<string, unknown>): boolean;
-
-	/**
-	 * Parse protocol-specific input into normalized context.
-	 * @param raw Parsed JSON from stdin
-	 * @returns Normalized context for the handler
-	 */
-	parseInput(raw: Record<string, unknown>): StopHookContext;
-
-	/**
-	 * Format handler result into protocol-specific output.
-	 * @param result Handler result
-	 * @returns JSON string to output to stdout
-	 */
-	formatOutput(result: StopHookResult): string;
-
-	/**
-	 * Check if execution should be skipped based on protocol-specific conditions.
-	 * @param ctx Parsed context
-	 * @returns Result to output immediately, or null to continue execution
-	 */
-	shouldSkipExecution(ctx: StopHookContext): StopHookResult | null;
-}