@agiflowai/hooks-adapter 0.0.14 → 0.0.15

package/dist/index.cjs

@@ -42,6 +42,7 @@ node_crypto = __toESM(node_crypto);
 * DESIGN PATTERNS:
 * - Strongly-typed constant exports for compile-time safety
 * - Immutable by default (as const assertions)
+* - Related constants grouped into const objects
 *
 * CODING STANDARDS:
 * - Primitive constants: UPPER_SNAKE_CASE or PascalCase for event names
@@ -52,15 +53,36 @@ node_crypto = __toESM(node_crypto);
 * - Magic strings without explanation
 */
 /**
-* Hook type identifiers for Claude Code hook events
+* Grouped hook type identifiers for Claude Code hook events
 */
-const PRE_TOOL_USE = "PreToolUse";
-const POST_TOOL_USE = "PostToolUse";
+const ClaudeCodeHookTypes = {
+	PRE_TOOL_USE: "PreToolUse",
+	POST_TOOL_USE: "PostToolUse",
+	STOP: "Stop",
+	USER_PROMPT_SUBMIT: "UserPromptSubmit",
+	TASK_COMPLETED: "TaskCompleted"
+};
 /**
-* Hook type identifiers for Gemini CLI hook events
+* Grouped hook type identifiers for Gemini CLI hook events
 */
-const BEFORE_TOOL_USE = "BeforeTool";
-const AFTER_TOOL_USE = "AfterTool";
+const GeminiCliHookTypes = {
+	BEFORE_TOOL_USE: "BeforeTool",
+	AFTER_TOOL_USE: "AfterTool"
+};
+/** Hook event fired before a tool is executed in Claude Code */
+const PRE_TOOL_USE = ClaudeCodeHookTypes.PRE_TOOL_USE;
+/** Hook event fired after a tool has executed in Claude Code */
+const POST_TOOL_USE = ClaudeCodeHookTypes.POST_TOOL_USE;
+/** Hook event fired when a Claude Code session is about to stop */
+const STOP = ClaudeCodeHookTypes.STOP;
+/** Hook event fired when the user submits a new prompt in Claude Code */
+const USER_PROMPT_SUBMIT = ClaudeCodeHookTypes.USER_PROMPT_SUBMIT;
+/** Hook event fired when an agentic task completes in Claude Code */
+const TASK_COMPLETED = ClaudeCodeHookTypes.TASK_COMPLETED;
+/** Hook event fired before a tool is executed in Gemini CLI */
+const BEFORE_TOOL_USE = GeminiCliHookTypes.BEFORE_TOOL_USE;
+/** Hook event fired after a tool is executed in Gemini CLI */
+const AFTER_TOOL_USE = GeminiCliHookTypes.AFTER_TOOL_USE;
 
 //#endregion
 //#region src/constants/decisions.ts
@@ -91,12 +113,13 @@ var BaseAdapter = class {
 			const stdin = await this.readStdin();
 			const response = await callback(this.parseInput(stdin));
 			if (response.decision === "skip") {
-				process.exit(0);
+				process.exit(response.exitCode ?? 0);
 				return;
 			}
+			if (response.userMessage) process.stderr.write(`${response.userMessage}\n`);
 			const output = this.formatOutput(response);
 			console.log(output);
-			process.exit(0);
+			process.exit(response.exitCode ?? 0);
 		} catch (error) {
 			this.handleError(error);
 		}
@@ -125,9 +148,10 @@ var BaseAdapter = class {
 				process.exit(0);
 				return;
 			}
+			if (finalResponse.userMessage) process.stderr.write(`${finalResponse.userMessage}\n`);
 			const output = this.formatOutput(finalResponse);
 			console.log(output);
-			process.exit(0);
+			process.exit(finalResponse.exitCode ?? 0);
 		} catch (error) {
 			this.handleError(error);
 		}
@@ -170,18 +194,18 @@ var BaseAdapter = class {
 //#endregion
 //#region src/adapters/ClaudeCodeAdapter.ts
 /**
-* ClaudeCodeAdapter - Unified adapter for Claude Code hook format (PreToolUse & PostToolUse)
+* ClaudeCodeAdapter - Unified adapter for Claude Code hook format
 *
 * DESIGN PATTERNS:
 * - Adapter pattern: Converts Claude Code format to normalized format
 * - Parser pattern: Extracts file paths and operations from tool inputs
-* - State pattern: Stores hook event type to morph behavior between PreToolUse and PostToolUse
+* - State pattern: Stores hook event type to morph behavior between hook events
 *
 * CODING STANDARDS:
 * - Parse Claude Code JSON stdin format exactly as specified
 * - Format output to match Claude Code hook response schema
 * - Handle missing/optional fields gracefully
-* - Support both PreToolUse and PostToolUse events in one adapter
+* - Support PreToolUse, PostToolUse, Stop, UserPromptSubmit, TaskCompleted events
 *
 * AVOID:
 * - Assuming all fields are present
@@ -189,7 +213,15 @@ var BaseAdapter = class {
 * - Mutating input objects
 */
 /**
-* Unified adapter for Claude Code hook format (PreToolUse & PostToolUse)
+* Blockable hook event names
+*/
+const BLOCKABLE_EVENTS = new Set([
+	"Stop",
+	"UserPromptSubmit",
+	"TaskCompleted"
+]);
+/**
+* Unified adapter for Claude Code hook format
 */
 var ClaudeCodeAdapter = class extends BaseAdapter {
 	hookEventName = "PreToolUse";
@@ -211,7 +243,7 @@ var ClaudeCodeAdapter = class extends BaseAdapter {
 	}
 	/**
 	* Format normalized HookResponse into Claude Code output
-	* Morphs output based on hook event type (PreToolUse vs PostToolUse)
+	* Morphs output based on hook event type
 	*
 	* @param response - Normalized hook response
 	* @returns JSON string for Claude Code
@@ -226,6 +258,7 @@ var ClaudeCodeAdapter = class extends BaseAdapter {
 			__agiflowai_aicode_utils.log.debug("ClaudeCodeAdapter: Skip decision, returning empty output");
 			return emptyOutput;
 		}
+		if (BLOCKABLE_EVENTS.has(this.hookEventName)) return this.formatBlockableOutput(response);
 		if (this.hookEventName === "PostToolUse") return this.formatPostToolUseOutput(response);
 		return this.formatPreToolUseOutput(response);
 	}
@@ -258,6 +291,20 @@ var ClaudeCodeAdapter = class extends BaseAdapter {
 		__agiflowai_aicode_utils.log.debug("ClaudeCodeAdapter: Formatted PostToolUse output", { output: formattedOutput });
 		return formattedOutput;
 	}
+	/**
+	* Format blockable output for Stop, UserPromptSubmit, and TaskCompleted hooks
+	* Maps 'deny' decision to 'block', otherwise returns empty object
+	*/
+	formatBlockableOutput(response) {
+		const output = {};
+		if (response.decision === "deny") {
+			output.decision = "block";
+			output.reason = response.message;
+		}
+		const formattedOutput = JSON.stringify(output, null, 2);
+		__agiflowai_aicode_utils.log.debug(`ClaudeCodeAdapter: Formatted ${this.hookEventName} output`, { output: formattedOutput });
+		return formattedOutput;
+	}
 };
 
 //#endregion
@@ -348,6 +395,12 @@ function isNodeError(error) {
 	return error instanceof Error && "code" in error;
 }
 /**
+* Type guard for LogEntry — validates required fields at runtime
+*/
+function isLogEntry(value) {
+	return typeof value === "object" && value !== null && "filePath" in value && typeof value.filePath === "string" && "operation" in value && typeof value.operation === "string";
+}
+/**
 * Service for tracking hook executions using an append-only log
 * Prevents duplicate hook actions (e.g., showing design patterns twice for same file)
 * Each session has its own log file for isolation
@@ -444,8 +497,10 @@ var ExecutionLogService = class ExecutionLogService {
 			const lines = (await node_fs_promises.readFile(this.logFile, "utf-8")).trim().split("\n").filter(Boolean);
 			const entries = [];
 			for (const line of lines) try {
-				entries.push(JSON.parse(line));
-			} catch (parseError) {
+				const parsed = JSON.parse(line);
+				if (isLogEntry(parsed)) entries.push(parsed);
+				else console.warn("Skipping malformed log entry:", line.substring(0, 100));
+			} catch (_parseError) {
 				console.warn("Skipping malformed log entry:", line.substring(0, 100));
 			}
 			this.cache = entries.slice(-ExecutionLogService.MAX_CACHE_SIZE);
@@ -508,10 +563,10 @@ var ExecutionLogService = class ExecutionLogService {
 	*/
 	async getFileMetadata(filePath) {
 		try {
-			const content = await node_fs_promises.readFile(filePath, "utf-8");
+			const [content, stats] = await Promise.all([node_fs_promises.readFile(filePath, "utf-8"), node_fs_promises.stat(filePath)]);
 			const checksum = node_crypto.createHash("md5").update(content).digest("hex");
 			return {
-				mtime: (await node_fs_promises.stat(filePath)).mtimeMs,
+				mtime: stats.mtimeMs,
 				checksum
 			};
 		} catch (error) {
@@ -597,7 +652,7 @@ var ExecutionLogService = class ExecutionLogService {
 			for (let i = entries.length - 1; i >= 0; i--) {
 				const entry = entries[i];
 				if (entry.operation === "scaffold") {
-					if (entry.generatedFiles && entry.generatedFiles.includes(filePath)) return true;
+					if (entry.generatedFiles?.includes(filePath)) return true;
 				}
 			}
 			return false;
@@ -608,6 +663,50 @@ var ExecutionLogService = class ExecutionLogService {
 	}
 };
 
+//#endregion
+//#region src/utils/guards.ts
+/**
+* Set of valid decision values for efficient runtime lookup.
+* Mirrors the Decision type: 'allow' | 'deny' | 'ask' | 'skip'
+*/
+const VALID_DECISIONS = new Set([
+	"allow",
+	"deny",
+	"ask",
+	"skip"
+]);
+/**
+* Type guard for HookResponse objects.
+* Validates that a value conforms to the HookResponse interface at runtime.
+*
+* @param value - Unknown value to check
+* @returns True if value is a valid HookResponse
+*/
+function isHookResponse(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("decision" in value) || typeof value.decision !== "string") return false;
+	if (!VALID_DECISIONS.has(value.decision)) return false;
+	if (!("message" in value) || typeof value.message !== "string") return false;
+	return true;
+}
+/**
+* Type guard for HookContext objects.
+* Validates that a value conforms to the HookContext interface at runtime.
+* toolInput is shallowly validated because its internal structure varies by tool
+* and is not constrained by the interface.
+*
+* @param value - Unknown value to check
+* @returns True if value is a valid HookContext
+*/
+function isHookContext(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("toolName" in value) || typeof value.toolName !== "string") return false;
+	if (!("toolInput" in value) || typeof value.toolInput !== "object" || value.toolInput === null) return false;
+	if (!("cwd" in value) || typeof value.cwd !== "string") return false;
+	if (!("sessionId" in value) || typeof value.sessionId !== "string") return false;
+	return true;
+}
+
 //#endregion
 //#region src/utils/parseHookType.ts
 /**
@@ -639,12 +738,19 @@ exports.AFTER_TOOL_USE = AFTER_TOOL_USE;
 exports.BEFORE_TOOL_USE = BEFORE_TOOL_USE;
 exports.BaseAdapter = BaseAdapter;
 exports.ClaudeCodeAdapter = ClaudeCodeAdapter;
+exports.ClaudeCodeHookTypes = ClaudeCodeHookTypes;
 exports.DECISION_ALLOW = DECISION_ALLOW;
 exports.DECISION_ASK = DECISION_ASK;
 exports.DECISION_DENY = DECISION_DENY;
 exports.DECISION_SKIP = DECISION_SKIP;
 exports.ExecutionLogService = ExecutionLogService;
 exports.GeminiCliAdapter = GeminiCliAdapter;
+exports.GeminiCliHookTypes = GeminiCliHookTypes;
 exports.POST_TOOL_USE = POST_TOOL_USE;
 exports.PRE_TOOL_USE = PRE_TOOL_USE;
+exports.STOP = STOP;
+exports.TASK_COMPLETED = TASK_COMPLETED;
+exports.USER_PROMPT_SUBMIT = USER_PROMPT_SUBMIT;
+exports.isHookContext = isHookContext;
+exports.isHookResponse = isHookResponse;
 exports.parseHookType = parseHookType;

package/dist/index.d.cts

@@ -5,6 +5,7 @@
  * DESIGN PATTERNS:
  * - Strongly-typed constant exports for compile-time safety
  * - Immutable by default (as const assertions)
+ * - Related constants grouped into const objects
  *
  * CODING STANDARDS:
  * - Primitive constants: UPPER_SNAKE_CASE or PascalCase for event names
@@ -15,19 +16,55 @@
  * - Magic strings without explanation
  */
 /**
- * Hook type identifiers for Claude Code hook events
+ * Grouped hook type identifiers for Claude Code hook events
  */
-declare const PRE_TOOL_USE = "PreToolUse";
-declare const POST_TOOL_USE = "PostToolUse";
+declare const ClaudeCodeHookTypes: {
+  /** Fires before a tool is executed, allowing interception or modification */
+  readonly PRE_TOOL_USE: "PreToolUse";
+  /** Fires after a tool has executed, allowing post-processing or blocking */
+  readonly POST_TOOL_USE: "PostToolUse";
+  /** Fires when a session is about to stop */
+  readonly STOP: "Stop";
+  /** Fires when the user submits a new prompt */
+  readonly USER_PROMPT_SUBMIT: "UserPromptSubmit";
+  /** Fires when an agentic task completes */
+  readonly TASK_COMPLETED: "TaskCompleted";
+};
 /**
- * Hook type identifiers for Gemini CLI hook events
+ * Grouped hook type identifiers for Gemini CLI hook events
  */
-declare const BEFORE_TOOL_USE = "BeforeTool";
-declare const AFTER_TOOL_USE = "AfterTool";
+declare const GeminiCliHookTypes: {
+  /** Fires before a tool is executed in Gemini CLI */
+  readonly BEFORE_TOOL_USE: "BeforeTool";
+  /** Fires after a tool is executed in Gemini CLI */
+  readonly AFTER_TOOL_USE: "AfterTool";
+};
+/** Hook event fired before a tool is executed in Claude Code */
+declare const PRE_TOOL_USE: "PreToolUse";
+/** Hook event fired after a tool has executed in Claude Code */
+declare const POST_TOOL_USE: "PostToolUse";
+/** Hook event fired when a Claude Code session is about to stop */
+declare const STOP: "Stop";
+/** Hook event fired when the user submits a new prompt in Claude Code */
+declare const USER_PROMPT_SUBMIT: "UserPromptSubmit";
+/** Hook event fired when an agentic task completes in Claude Code */
+declare const TASK_COMPLETED: "TaskCompleted";
+/** Hook event fired before a tool is executed in Gemini CLI */
+declare const BEFORE_TOOL_USE: "BeforeTool";
+/** Hook event fired after a tool is executed in Gemini CLI */
+declare const AFTER_TOOL_USE: "AfterTool";
 /**
- * Union type of all supported hook types
+ * Union type of all supported Claude Code hook types
  */
-type HookType = typeof PRE_TOOL_USE | typeof POST_TOOL_USE | typeof BEFORE_TOOL_USE | typeof AFTER_TOOL_USE;
+type ClaudeCodeHookType = (typeof ClaudeCodeHookTypes)[keyof typeof ClaudeCodeHookTypes];
+/**
+ * Union type of all supported Gemini CLI hook types
+ */
+type GeminiCliHookType = (typeof GeminiCliHookTypes)[keyof typeof GeminiCliHookTypes];
+/**
+ * Union type of all supported hook types across all agents
+ */
+type HookType = ClaudeCodeHookType | GeminiCliHookType;
 //#endregion
 //#region src/types/index.d.ts
 /**
@@ -85,6 +122,8 @@ interface HookResponse {
   userMessage?: string;
   /** Optional updated input parameters for the tool */
   updatedInput?: Record<string, unknown>;
+  /** Optional exit code for process termination (default: 0) */
+  exitCode?: number;
 }
 /**
  * Content item in tool result from Claude Code
@@ -102,17 +141,6 @@ interface ToolResult {
   /** Array of content items returned by the tool */
   readonly content?: readonly ToolResultContentItem[];
 }
-/**
- * Scaffold execution data from execution log
- */
-interface ScaffoldExecution {
-  /** Unique scaffold execution ID */
-  readonly scaffoldId: string;
-  /** List of files generated by the scaffold */
-  readonly generatedFiles: readonly string[];
-  /** Name of the scaffold feature/method */
-  readonly featureName?: string;
-}
 /**
  * Log entry structure from ExecutionLogService
  */
@@ -132,7 +160,7 @@ interface LogEntry {
   /** File path */
   readonly filePath: string;
   /** Decision made */
-  readonly decision?: string;
+  readonly decision?: Decision;
   /** File pattern matched */
   readonly filePattern?: string;
   /** File modification timestamp */
@@ -143,15 +171,16 @@ interface LogEntry {
   readonly projectPath?: string;
 }
 /**
- * Pending scaffold log entry for temp file storage
+ * Scaffold execution data derived from LogEntry
  */
-interface PendingScaffoldLogEntry {
-  /** Unique scaffold execution ID */
-  readonly scaffoldId: string;
-  /** List of files generated */
-  readonly generatedFiles: readonly string[];
-  /** Project path where scaffold was executed */
-  readonly projectPath: string;
+interface ScaffoldExecution extends Required<Pick<LogEntry, 'scaffoldId' | 'generatedFiles'>> {
+  /** Name of the scaffold feature/method */
+  readonly featureName?: string;
+}
+/**
+ * Pending scaffold log entry for temp file storage, derived from LogEntry
+ */
+interface PendingScaffoldLogEntry extends Required<Pick<LogEntry, 'scaffoldId' | 'generatedFiles' | 'projectPath'>> {
   /** Scaffold feature name */
   readonly featureName?: string;
 }
@@ -214,42 +243,67 @@ declare abstract class BaseAdapter<TContext = any> {
 //#endregion
 //#region src/adapters/ClaudeCodeAdapter.d.ts
 /**
- * Claude Code hook input format (PreToolUse)
+ * Common fields shared by all Claude Code hook inputs
  */
-interface ClaudeCodePreToolUseInput {
-  tool_name: string;
-  tool_input: Record<string, any>;
+interface ClaudeCodeCommonFields {
   cwd: string;
   session_id: string;
-  hook_event_name: 'PreToolUse';
-  tool_use_id: string;
   transcript_path: string;
   permission_mode: string;
+}
+/**
+ * Claude Code hook input format (PreToolUse)
+ */
+interface ClaudeCodePreToolUseInput extends ClaudeCodeCommonFields {
+  hook_event_name: 'PreToolUse';
+  tool_name: string;
+  tool_input: Record<string, any>;
+  tool_use_id: string;
   llm_tool?: string;
   tool_config?: Record<string, unknown>;
 }
 /**
  * Claude Code hook input format (PostToolUse)
  */
-interface ClaudeCodePostToolUseInput {
+interface ClaudeCodePostToolUseInput extends ClaudeCodeCommonFields {
+  hook_event_name: 'PostToolUse';
   tool_name: string;
   tool_input: Record<string, any>;
   tool_response: Record<string, any>;
-  cwd: string;
-  session_id: string;
-  hook_event_name: 'PostToolUse';
   tool_use_id: string;
-  transcript_path: string;
-  permission_mode: string;
   llm_tool?: string;
   tool_config?: Record<string, unknown>;
 }
 /**
- * Union type for both hook input formats
+ * Claude Code hook input format (Stop)
  */
-type ClaudeCodeHookInput = ClaudeCodePreToolUseInput | ClaudeCodePostToolUseInput;
+interface ClaudeCodeStopInput extends ClaudeCodeCommonFields {
+  hook_event_name: 'Stop';
+  stop_hook_active: boolean;
+  last_assistant_message: string;
+}
+/**
+ * Claude Code hook input format (UserPromptSubmit)
+ */
+interface ClaudeCodeUserPromptSubmitInput extends ClaudeCodeCommonFields {
+  hook_event_name: 'UserPromptSubmit';
+  prompt: string;
+}
+/**
+ * Claude Code hook input format (TaskCompleted)
+ */
+interface ClaudeCodeTaskCompletedInput extends ClaudeCodeCommonFields {
+  hook_event_name: 'TaskCompleted';
+  task_id: string;
+  task_subject: string;
+  task_description: string;
+}
 /**
- * Unified adapter for Claude Code hook format (PreToolUse & PostToolUse)
+ * Union type for all hook input formats
+ */
+type ClaudeCodeHookInput = ClaudeCodePreToolUseInput | ClaudeCodePostToolUseInput | ClaudeCodeStopInput | ClaudeCodeUserPromptSubmitInput | ClaudeCodeTaskCompletedInput;
+/**
+ * Unified adapter for Claude Code hook format
  */
 declare class ClaudeCodeAdapter extends BaseAdapter<ClaudeCodeHookInput> {
   private hookEventName;
@@ -262,7 +316,7 @@ declare class ClaudeCodeAdapter extends BaseAdapter<ClaudeCodeHookInput> {
   parseInput(stdin: string): ClaudeCodeHookInput;
   /**
    * Format normalized HookResponse into Claude Code output
-   * Morphs output based on hook event type (PreToolUse vs PostToolUse)
+   * Morphs output based on hook event type
    *
    * @param response - Normalized hook response
    * @returns JSON string for Claude Code
@@ -276,6 +330,11 @@ declare class ClaudeCodeAdapter extends BaseAdapter<ClaudeCodeHookInput> {
    * Format PostToolUse output
    */
   private formatPostToolUseOutput;
+  /**
+   * Format blockable output for Stop, UserPromptSubmit, and TaskCompleted hooks
+   * Maps 'deny' decision to 'block', otherwise returns empty object
+   */
+  formatBlockableOutput(response: HookResponse): string;
 }
 //#endregion
 //#region src/adapters/GeminiCliAdapter.d.ts
@@ -326,7 +385,7 @@ interface LogExecutionParams {
   sessionId: string;
   filePath: string;
   operation: string;
-  decision: string;
+  decision: Decision;
   filePattern?: string;
   /** File modification timestamp (mtime) at time of execution */
   fileMtime?: number;
@@ -348,7 +407,7 @@ interface HasExecutedParams {
   /** File path to check */
   filePath: string;
   /** Decision to check for (e.g., 'deny' means we already showed patterns) */
-  decision: string;
+  decision: Decision;
   /** Optional file pattern to match */
   filePattern?: string;
   /** Optional project path to distinguish same patterns in different projects */
@@ -439,7 +498,7 @@ declare class ExecutionLogService {
    * @param decision - Decision type to check for
    * @returns true if file has changed or no previous execution found, true on error (fail-open)
    */
-  hasFileChanged(filePath: string, decision: string): Promise<boolean>;
+  hasFileChanged(filePath: string, decision: Decision): Promise<boolean>;
   /**
    * Check if file was recently reviewed (within debounce window)
    * Prevents noisy feedback during rapid successive edits
@@ -465,6 +524,26 @@ declare class ExecutionLogService {
   wasGeneratedByScaffold(filePath: string): Promise<boolean>;
 }
 //#endregion
+//#region src/utils/guards.d.ts
+/**
+ * Type guard for HookResponse objects.
+ * Validates that a value conforms to the HookResponse interface at runtime.
+ *
+ * @param value - Unknown value to check
+ * @returns True if value is a valid HookResponse
+ */
+declare function isHookResponse(value: unknown): value is HookResponse;
+/**
+ * Type guard for HookContext objects.
+ * Validates that a value conforms to the HookContext interface at runtime.
+ * toolInput is shallowly validated because its internal structure varies by tool
+ * and is not constrained by the interface.
+ *
+ * @param value - Unknown value to check
+ * @returns True if value is a valid HookContext
+ */
+declare function isHookContext(value: unknown): value is HookContext;
+//#endregion
 //#region src/utils/parseHookType.d.ts
 /**
  * parseHookType Utilities
@@ -513,4 +592,4 @@ interface ParsedHookType {
  */
 declare function parseHookType(hookType: string): ParsedHookType;
 //#endregion
-export { AFTER_TOOL_USE, BEFORE_TOOL_USE, BaseAdapter, ClaudeCodeAdapter, ClaudeCodeHookInput, ClaudeCodePostToolUseInput, ClaudeCodePreToolUseInput, DECISION_ALLOW, DECISION_ASK, DECISION_DENY, DECISION_SKIP, Decision, ExecutionLogService, GeminiCliAdapter, GeminiCliHookInput, HasExecutedParams, HookContext, HookResponse, HookType, LogEntry, LogExecutionParams, LogStats, POST_TOOL_USE, PRE_TOOL_USE, ParsedHookType, PendingScaffoldLogEntry, ScaffoldExecution, ToolResult, ToolResultContentItem, parseHookType };
+export { AFTER_TOOL_USE, BEFORE_TOOL_USE, BaseAdapter, ClaudeCodeAdapter, ClaudeCodeHookInput, ClaudeCodeHookType, ClaudeCodeHookTypes, ClaudeCodePostToolUseInput, ClaudeCodePreToolUseInput, ClaudeCodeStopInput, ClaudeCodeTaskCompletedInput, ClaudeCodeUserPromptSubmitInput, DECISION_ALLOW, DECISION_ASK, DECISION_DENY, DECISION_SKIP, Decision, ExecutionLogService, GeminiCliAdapter, GeminiCliHookInput, GeminiCliHookType, GeminiCliHookTypes, HasExecutedParams, HookContext, HookResponse, HookType, LogEntry, LogExecutionParams, LogStats, POST_TOOL_USE, PRE_TOOL_USE, PendingScaffoldLogEntry, STOP, ScaffoldExecution, TASK_COMPLETED, ToolResult, ToolResultContentItem, USER_PROMPT_SUBMIT, isHookContext, isHookResponse, parseHookType };

package/dist/index.d.mts

@@ -5,6 +5,7 @@
  * DESIGN PATTERNS:
  * - Strongly-typed constant exports for compile-time safety
  * - Immutable by default (as const assertions)
+ * - Related constants grouped into const objects
  *
  * CODING STANDARDS:
  * - Primitive constants: UPPER_SNAKE_CASE or PascalCase for event names
@@ -15,19 +16,55 @@
  * - Magic strings without explanation
  */
 /**
- * Hook type identifiers for Claude Code hook events
+ * Grouped hook type identifiers for Claude Code hook events
  */
-declare const PRE_TOOL_USE = "PreToolUse";
-declare const POST_TOOL_USE = "PostToolUse";
+declare const ClaudeCodeHookTypes: {
+  /** Fires before a tool is executed, allowing interception or modification */
+  readonly PRE_TOOL_USE: "PreToolUse";
+  /** Fires after a tool has executed, allowing post-processing or blocking */
+  readonly POST_TOOL_USE: "PostToolUse";
+  /** Fires when a session is about to stop */
+  readonly STOP: "Stop";
+  /** Fires when the user submits a new prompt */
+  readonly USER_PROMPT_SUBMIT: "UserPromptSubmit";
+  /** Fires when an agentic task completes */
+  readonly TASK_COMPLETED: "TaskCompleted";
+};
 /**
- * Hook type identifiers for Gemini CLI hook events
+ * Grouped hook type identifiers for Gemini CLI hook events
  */
-declare const BEFORE_TOOL_USE = "BeforeTool";
-declare const AFTER_TOOL_USE = "AfterTool";
+declare const GeminiCliHookTypes: {
+  /** Fires before a tool is executed in Gemini CLI */
+  readonly BEFORE_TOOL_USE: "BeforeTool";
+  /** Fires after a tool is executed in Gemini CLI */
+  readonly AFTER_TOOL_USE: "AfterTool";
+};
+/** Hook event fired before a tool is executed in Claude Code */
+declare const PRE_TOOL_USE: "PreToolUse";
+/** Hook event fired after a tool has executed in Claude Code */
+declare const POST_TOOL_USE: "PostToolUse";
+/** Hook event fired when a Claude Code session is about to stop */
+declare const STOP: "Stop";
+/** Hook event fired when the user submits a new prompt in Claude Code */
+declare const USER_PROMPT_SUBMIT: "UserPromptSubmit";
+/** Hook event fired when an agentic task completes in Claude Code */
+declare const TASK_COMPLETED: "TaskCompleted";
+/** Hook event fired before a tool is executed in Gemini CLI */
+declare const BEFORE_TOOL_USE: "BeforeTool";
+/** Hook event fired after a tool is executed in Gemini CLI */
+declare const AFTER_TOOL_USE: "AfterTool";
 /**
- * Union type of all supported hook types
+ * Union type of all supported Claude Code hook types
  */
-type HookType = typeof PRE_TOOL_USE | typeof POST_TOOL_USE | typeof BEFORE_TOOL_USE | typeof AFTER_TOOL_USE;
+type ClaudeCodeHookType = (typeof ClaudeCodeHookTypes)[keyof typeof ClaudeCodeHookTypes];
+/**
+ * Union type of all supported Gemini CLI hook types
+ */
+type GeminiCliHookType = (typeof GeminiCliHookTypes)[keyof typeof GeminiCliHookTypes];
+/**
+ * Union type of all supported hook types across all agents
+ */
+type HookType = ClaudeCodeHookType | GeminiCliHookType;
 //#endregion
 //#region src/types/index.d.ts
 /**
@@ -85,6 +122,8 @@ interface HookResponse {
   userMessage?: string;
   /** Optional updated input parameters for the tool */
   updatedInput?: Record<string, unknown>;
+  /** Optional exit code for process termination (default: 0) */
+  exitCode?: number;
 }
 /**
  * Content item in tool result from Claude Code
@@ -102,17 +141,6 @@ interface ToolResult {
   /** Array of content items returned by the tool */
   readonly content?: readonly ToolResultContentItem[];
 }
-/**
- * Scaffold execution data from execution log
- */
-interface ScaffoldExecution {
-  /** Unique scaffold execution ID */
-  readonly scaffoldId: string;
-  /** List of files generated by the scaffold */
-  readonly generatedFiles: readonly string[];
-  /** Name of the scaffold feature/method */
-  readonly featureName?: string;
-}
 /**
  * Log entry structure from ExecutionLogService
  */
@@ -132,7 +160,7 @@ interface LogEntry {
   /** File path */
   readonly filePath: string;
   /** Decision made */
-  readonly decision?: string;
+  readonly decision?: Decision;
   /** File pattern matched */
   readonly filePattern?: string;
   /** File modification timestamp */
@@ -143,15 +171,16 @@ interface LogEntry {
   readonly projectPath?: string;
 }
 /**
- * Pending scaffold log entry for temp file storage
+ * Scaffold execution data derived from LogEntry
  */
-interface PendingScaffoldLogEntry {
-  /** Unique scaffold execution ID */
-  readonly scaffoldId: string;
-  /** List of files generated */
-  readonly generatedFiles: readonly string[];
-  /** Project path where scaffold was executed */
-  readonly projectPath: string;
+interface ScaffoldExecution extends Required<Pick<LogEntry, 'scaffoldId' | 'generatedFiles'>> {
+  /** Name of the scaffold feature/method */
+  readonly featureName?: string;
+}
+/**
+ * Pending scaffold log entry for temp file storage, derived from LogEntry
+ */
+interface PendingScaffoldLogEntry extends Required<Pick<LogEntry, 'scaffoldId' | 'generatedFiles' | 'projectPath'>> {
   /** Scaffold feature name */
   readonly featureName?: string;
 }
@@ -214,42 +243,67 @@ declare abstract class BaseAdapter<TContext = any> {
 //#endregion
 //#region src/adapters/ClaudeCodeAdapter.d.ts
 /**
- * Claude Code hook input format (PreToolUse)
+ * Common fields shared by all Claude Code hook inputs
  */
-interface ClaudeCodePreToolUseInput {
-  tool_name: string;
-  tool_input: Record<string, any>;
+interface ClaudeCodeCommonFields {
   cwd: string;
   session_id: string;
-  hook_event_name: 'PreToolUse';
-  tool_use_id: string;
   transcript_path: string;
   permission_mode: string;
+}
+/**
+ * Claude Code hook input format (PreToolUse)
+ */
+interface ClaudeCodePreToolUseInput extends ClaudeCodeCommonFields {
+  hook_event_name: 'PreToolUse';
+  tool_name: string;
+  tool_input: Record<string, any>;
+  tool_use_id: string;
   llm_tool?: string;
   tool_config?: Record<string, unknown>;
 }
 /**
  * Claude Code hook input format (PostToolUse)
  */
-interface ClaudeCodePostToolUseInput {
+interface ClaudeCodePostToolUseInput extends ClaudeCodeCommonFields {
+  hook_event_name: 'PostToolUse';
   tool_name: string;
   tool_input: Record<string, any>;
   tool_response: Record<string, any>;
-  cwd: string;
-  session_id: string;
-  hook_event_name: 'PostToolUse';
   tool_use_id: string;
-  transcript_path: string;
-  permission_mode: string;
   llm_tool?: string;
   tool_config?: Record<string, unknown>;
 }
 /**
- * Union type for both hook input formats
+ * Claude Code hook input format (Stop)
  */
-type ClaudeCodeHookInput = ClaudeCodePreToolUseInput | ClaudeCodePostToolUseInput;
+interface ClaudeCodeStopInput extends ClaudeCodeCommonFields {
+  hook_event_name: 'Stop';
+  stop_hook_active: boolean;
+  last_assistant_message: string;
+}
+/**
+ * Claude Code hook input format (UserPromptSubmit)
+ */
+interface ClaudeCodeUserPromptSubmitInput extends ClaudeCodeCommonFields {
+  hook_event_name: 'UserPromptSubmit';
+  prompt: string;
+}
+/**
+ * Claude Code hook input format (TaskCompleted)
+ */
+interface ClaudeCodeTaskCompletedInput extends ClaudeCodeCommonFields {
+  hook_event_name: 'TaskCompleted';
+  task_id: string;
+  task_subject: string;
+  task_description: string;
+}
 /**
- * Unified adapter for Claude Code hook format (PreToolUse & PostToolUse)
+ * Union type for all hook input formats
+ */
+type ClaudeCodeHookInput = ClaudeCodePreToolUseInput | ClaudeCodePostToolUseInput | ClaudeCodeStopInput | ClaudeCodeUserPromptSubmitInput | ClaudeCodeTaskCompletedInput;
+/**
+ * Unified adapter for Claude Code hook format
  */
 declare class ClaudeCodeAdapter extends BaseAdapter<ClaudeCodeHookInput> {
   private hookEventName;
@@ -262,7 +316,7 @@ declare class ClaudeCodeAdapter extends BaseAdapter<ClaudeCodeHookInput> {
   parseInput(stdin: string): ClaudeCodeHookInput;
   /**
    * Format normalized HookResponse into Claude Code output
-   * Morphs output based on hook event type (PreToolUse vs PostToolUse)
+   * Morphs output based on hook event type
    *
    * @param response - Normalized hook response
    * @returns JSON string for Claude Code
@@ -276,6 +330,11 @@ declare class ClaudeCodeAdapter extends BaseAdapter<ClaudeCodeHookInput> {
    * Format PostToolUse output
    */
   private formatPostToolUseOutput;
+  /**
+   * Format blockable output for Stop, UserPromptSubmit, and TaskCompleted hooks
+   * Maps 'deny' decision to 'block', otherwise returns empty object
+   */
+  formatBlockableOutput(response: HookResponse): string;
 }
 //#endregion
 //#region src/adapters/GeminiCliAdapter.d.ts
@@ -326,7 +385,7 @@ interface LogExecutionParams {
   sessionId: string;
   filePath: string;
   operation: string;
-  decision: string;
+  decision: Decision;
   filePattern?: string;
   /** File modification timestamp (mtime) at time of execution */
   fileMtime?: number;
@@ -348,7 +407,7 @@ interface HasExecutedParams {
   /** File path to check */
   filePath: string;
   /** Decision to check for (e.g., 'deny' means we already showed patterns) */
-  decision: string;
+  decision: Decision;
   /** Optional file pattern to match */
   filePattern?: string;
   /** Optional project path to distinguish same patterns in different projects */
@@ -439,7 +498,7 @@ declare class ExecutionLogService {
    * @param decision - Decision type to check for
    * @returns true if file has changed or no previous execution found, true on error (fail-open)
    */
-  hasFileChanged(filePath: string, decision: string): Promise<boolean>;
+  hasFileChanged(filePath: string, decision: Decision): Promise<boolean>;
   /**
    * Check if file was recently reviewed (within debounce window)
    * Prevents noisy feedback during rapid successive edits
@@ -465,6 +524,26 @@ declare class ExecutionLogService {
   wasGeneratedByScaffold(filePath: string): Promise<boolean>;
 }
 //#endregion
+//#region src/utils/guards.d.ts
+/**
+ * Type guard for HookResponse objects.
+ * Validates that a value conforms to the HookResponse interface at runtime.
+ *
+ * @param value - Unknown value to check
+ * @returns True if value is a valid HookResponse
+ */
+declare function isHookResponse(value: unknown): value is HookResponse;
+/**
+ * Type guard for HookContext objects.
+ * Validates that a value conforms to the HookContext interface at runtime.
+ * toolInput is shallowly validated because its internal structure varies by tool
+ * and is not constrained by the interface.
+ *
+ * @param value - Unknown value to check
+ * @returns True if value is a valid HookContext
+ */
+declare function isHookContext(value: unknown): value is HookContext;
+//#endregion
 //#region src/utils/parseHookType.d.ts
 /**
  * parseHookType Utilities
@@ -513,4 +592,4 @@ interface ParsedHookType {
  */
 declare function parseHookType(hookType: string): ParsedHookType;
 //#endregion
-export { AFTER_TOOL_USE, BEFORE_TOOL_USE, BaseAdapter, ClaudeCodeAdapter, ClaudeCodeHookInput, ClaudeCodePostToolUseInput, ClaudeCodePreToolUseInput, DECISION_ALLOW, DECISION_ASK, DECISION_DENY, DECISION_SKIP, Decision, ExecutionLogService, GeminiCliAdapter, GeminiCliHookInput, HasExecutedParams, HookContext, HookResponse, HookType, LogEntry, LogExecutionParams, LogStats, POST_TOOL_USE, PRE_TOOL_USE, ParsedHookType, PendingScaffoldLogEntry, ScaffoldExecution, ToolResult, ToolResultContentItem, parseHookType };
+export { AFTER_TOOL_USE, BEFORE_TOOL_USE, BaseAdapter, ClaudeCodeAdapter, ClaudeCodeHookInput, ClaudeCodeHookType, ClaudeCodeHookTypes, ClaudeCodePostToolUseInput, ClaudeCodePreToolUseInput, ClaudeCodeStopInput, ClaudeCodeTaskCompletedInput, ClaudeCodeUserPromptSubmitInput, DECISION_ALLOW, DECISION_ASK, DECISION_DENY, DECISION_SKIP, Decision, ExecutionLogService, GeminiCliAdapter, GeminiCliHookInput, GeminiCliHookType, GeminiCliHookTypes, HasExecutedParams, HookContext, HookResponse, HookType, LogEntry, LogExecutionParams, LogStats, POST_TOOL_USE, PRE_TOOL_USE, PendingScaffoldLogEntry, STOP, ScaffoldExecution, TASK_COMPLETED, ToolResult, ToolResultContentItem, USER_PROMPT_SUBMIT, isHookContext, isHookResponse, parseHookType };

package/dist/index.mjs

@@ -11,6 +11,7 @@ import * as crypto from "node:crypto";
 * DESIGN PATTERNS:
 * - Strongly-typed constant exports for compile-time safety
 * - Immutable by default (as const assertions)
+* - Related constants grouped into const objects
 *
 * CODING STANDARDS:
 * - Primitive constants: UPPER_SNAKE_CASE or PascalCase for event names
@@ -21,15 +22,36 @@ import * as crypto from "node:crypto";
 * - Magic strings without explanation
 */
 /**
-* Hook type identifiers for Claude Code hook events
+* Grouped hook type identifiers for Claude Code hook events
 */
-const PRE_TOOL_USE = "PreToolUse";
-const POST_TOOL_USE = "PostToolUse";
+const ClaudeCodeHookTypes = {
+	PRE_TOOL_USE: "PreToolUse",
+	POST_TOOL_USE: "PostToolUse",
+	STOP: "Stop",
+	USER_PROMPT_SUBMIT: "UserPromptSubmit",
+	TASK_COMPLETED: "TaskCompleted"
+};
 /**
-* Hook type identifiers for Gemini CLI hook events
+* Grouped hook type identifiers for Gemini CLI hook events
 */
-const BEFORE_TOOL_USE = "BeforeTool";
-const AFTER_TOOL_USE = "AfterTool";
+const GeminiCliHookTypes = {
+	BEFORE_TOOL_USE: "BeforeTool",
+	AFTER_TOOL_USE: "AfterTool"
+};
+/** Hook event fired before a tool is executed in Claude Code */
+const PRE_TOOL_USE = ClaudeCodeHookTypes.PRE_TOOL_USE;
+/** Hook event fired after a tool has executed in Claude Code */
+const POST_TOOL_USE = ClaudeCodeHookTypes.POST_TOOL_USE;
+/** Hook event fired when a Claude Code session is about to stop */
+const STOP = ClaudeCodeHookTypes.STOP;
+/** Hook event fired when the user submits a new prompt in Claude Code */
+const USER_PROMPT_SUBMIT = ClaudeCodeHookTypes.USER_PROMPT_SUBMIT;
+/** Hook event fired when an agentic task completes in Claude Code */
+const TASK_COMPLETED = ClaudeCodeHookTypes.TASK_COMPLETED;
+/** Hook event fired before a tool is executed in Gemini CLI */
+const BEFORE_TOOL_USE = GeminiCliHookTypes.BEFORE_TOOL_USE;
+/** Hook event fired after a tool is executed in Gemini CLI */
+const AFTER_TOOL_USE = GeminiCliHookTypes.AFTER_TOOL_USE;
 
 //#endregion
 //#region src/constants/decisions.ts
@@ -60,12 +82,13 @@ var BaseAdapter = class {
 			const stdin = await this.readStdin();
 			const response = await callback(this.parseInput(stdin));
 			if (response.decision === "skip") {
-				process.exit(0);
+				process.exit(response.exitCode ?? 0);
 				return;
 			}
+			if (response.userMessage) process.stderr.write(`${response.userMessage}\n`);
 			const output = this.formatOutput(response);
 			console.log(output);
-			process.exit(0);
+			process.exit(response.exitCode ?? 0);
 		} catch (error) {
 			this.handleError(error);
 		}
@@ -94,9 +117,10 @@ var BaseAdapter = class {
 				process.exit(0);
 				return;
 			}
+			if (finalResponse.userMessage) process.stderr.write(`${finalResponse.userMessage}\n`);
 			const output = this.formatOutput(finalResponse);
 			console.log(output);
-			process.exit(0);
+			process.exit(finalResponse.exitCode ?? 0);
 		} catch (error) {
 			this.handleError(error);
 		}
@@ -139,18 +163,18 @@ var BaseAdapter = class {
 //#endregion
 //#region src/adapters/ClaudeCodeAdapter.ts
 /**
-* ClaudeCodeAdapter - Unified adapter for Claude Code hook format (PreToolUse & PostToolUse)
+* ClaudeCodeAdapter - Unified adapter for Claude Code hook format
 *
 * DESIGN PATTERNS:
 * - Adapter pattern: Converts Claude Code format to normalized format
 * - Parser pattern: Extracts file paths and operations from tool inputs
-* - State pattern: Stores hook event type to morph behavior between PreToolUse and PostToolUse
+* - State pattern: Stores hook event type to morph behavior between hook events
 *
 * CODING STANDARDS:
 * - Parse Claude Code JSON stdin format exactly as specified
 * - Format output to match Claude Code hook response schema
 * - Handle missing/optional fields gracefully
-* - Support both PreToolUse and PostToolUse events in one adapter
+* - Support PreToolUse, PostToolUse, Stop, UserPromptSubmit, TaskCompleted events
 *
 * AVOID:
 * - Assuming all fields are present
@@ -158,7 +182,15 @@ var BaseAdapter = class {
 * - Mutating input objects
 */
 /**
-* Unified adapter for Claude Code hook format (PreToolUse & PostToolUse)
+* Blockable hook event names
+*/
+const BLOCKABLE_EVENTS = new Set([
+	"Stop",
+	"UserPromptSubmit",
+	"TaskCompleted"
+]);
+/**
+* Unified adapter for Claude Code hook format
 */
 var ClaudeCodeAdapter = class extends BaseAdapter {
 	hookEventName = "PreToolUse";
@@ -180,7 +212,7 @@ var ClaudeCodeAdapter = class extends BaseAdapter {
 	}
 	/**
 	* Format normalized HookResponse into Claude Code output
-	* Morphs output based on hook event type (PreToolUse vs PostToolUse)
+	* Morphs output based on hook event type
 	*
 	* @param response - Normalized hook response
 	* @returns JSON string for Claude Code
@@ -195,6 +227,7 @@ var ClaudeCodeAdapter = class extends BaseAdapter {
 			log.debug("ClaudeCodeAdapter: Skip decision, returning empty output");
 			return emptyOutput;
 		}
+		if (BLOCKABLE_EVENTS.has(this.hookEventName)) return this.formatBlockableOutput(response);
 		if (this.hookEventName === "PostToolUse") return this.formatPostToolUseOutput(response);
 		return this.formatPreToolUseOutput(response);
 	}
@@ -227,6 +260,20 @@ var ClaudeCodeAdapter = class extends BaseAdapter {
 		log.debug("ClaudeCodeAdapter: Formatted PostToolUse output", { output: formattedOutput });
 		return formattedOutput;
 	}
+	/**
+	* Format blockable output for Stop, UserPromptSubmit, and TaskCompleted hooks
+	* Maps 'deny' decision to 'block', otherwise returns empty object
+	*/
+	formatBlockableOutput(response) {
+		const output = {};
+		if (response.decision === "deny") {
+			output.decision = "block";
+			output.reason = response.message;
+		}
+		const formattedOutput = JSON.stringify(output, null, 2);
+		log.debug(`ClaudeCodeAdapter: Formatted ${this.hookEventName} output`, { output: formattedOutput });
+		return formattedOutput;
+	}
 };
 
 //#endregion
@@ -317,6 +364,12 @@ function isNodeError(error) {
 	return error instanceof Error && "code" in error;
 }
 /**
+* Type guard for LogEntry — validates required fields at runtime
+*/
+function isLogEntry(value) {
+	return typeof value === "object" && value !== null && "filePath" in value && typeof value.filePath === "string" && "operation" in value && typeof value.operation === "string";
+}
+/**
 * Service for tracking hook executions using an append-only log
 * Prevents duplicate hook actions (e.g., showing design patterns twice for same file)
 * Each session has its own log file for isolation
@@ -413,8 +466,10 @@ var ExecutionLogService = class ExecutionLogService {
 			const lines = (await fs.readFile(this.logFile, "utf-8")).trim().split("\n").filter(Boolean);
 			const entries = [];
 			for (const line of lines) try {
-				entries.push(JSON.parse(line));
-			} catch (parseError) {
+				const parsed = JSON.parse(line);
+				if (isLogEntry(parsed)) entries.push(parsed);
+				else console.warn("Skipping malformed log entry:", line.substring(0, 100));
+			} catch (_parseError) {
 				console.warn("Skipping malformed log entry:", line.substring(0, 100));
 			}
 			this.cache = entries.slice(-ExecutionLogService.MAX_CACHE_SIZE);
@@ -477,10 +532,10 @@ var ExecutionLogService = class ExecutionLogService {
 	*/
 	async getFileMetadata(filePath) {
 		try {
-			const content = await fs.readFile(filePath, "utf-8");
+			const [content, stats] = await Promise.all([fs.readFile(filePath, "utf-8"), fs.stat(filePath)]);
 			const checksum = crypto.createHash("md5").update(content).digest("hex");
 			return {
-				mtime: (await fs.stat(filePath)).mtimeMs,
+				mtime: stats.mtimeMs,
 				checksum
 			};
 		} catch (error) {
@@ -566,7 +621,7 @@ var ExecutionLogService = class ExecutionLogService {
 			for (let i = entries.length - 1; i >= 0; i--) {
 				const entry = entries[i];
 				if (entry.operation === "scaffold") {
-					if (entry.generatedFiles && entry.generatedFiles.includes(filePath)) return true;
+					if (entry.generatedFiles?.includes(filePath)) return true;
 				}
 			}
 			return false;
@@ -577,6 +632,50 @@ var ExecutionLogService = class ExecutionLogService {
 	}
 };
 
+//#endregion
+//#region src/utils/guards.ts
+/**
+* Set of valid decision values for efficient runtime lookup.
+* Mirrors the Decision type: 'allow' | 'deny' | 'ask' | 'skip'
+*/
+const VALID_DECISIONS = new Set([
+	"allow",
+	"deny",
+	"ask",
+	"skip"
+]);
+/**
+* Type guard for HookResponse objects.
+* Validates that a value conforms to the HookResponse interface at runtime.
+*
+* @param value - Unknown value to check
+* @returns True if value is a valid HookResponse
+*/
+function isHookResponse(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("decision" in value) || typeof value.decision !== "string") return false;
+	if (!VALID_DECISIONS.has(value.decision)) return false;
+	if (!("message" in value) || typeof value.message !== "string") return false;
+	return true;
+}
+/**
+* Type guard for HookContext objects.
+* Validates that a value conforms to the HookContext interface at runtime.
+* toolInput is shallowly validated because its internal structure varies by tool
+* and is not constrained by the interface.
+*
+* @param value - Unknown value to check
+* @returns True if value is a valid HookContext
+*/
+function isHookContext(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("toolName" in value) || typeof value.toolName !== "string") return false;
+	if (!("toolInput" in value) || typeof value.toolInput !== "object" || value.toolInput === null) return false;
+	if (!("cwd" in value) || typeof value.cwd !== "string") return false;
+	if (!("sessionId" in value) || typeof value.sessionId !== "string") return false;
+	return true;
+}
+
 //#endregion
 //#region src/utils/parseHookType.ts
 /**
@@ -604,4 +703,4 @@ function parseHookType(hookType) {
 }
 
 //#endregion
-export { AFTER_TOOL_USE, BEFORE_TOOL_USE, BaseAdapter, ClaudeCodeAdapter, DECISION_ALLOW, DECISION_ASK, DECISION_DENY, DECISION_SKIP, ExecutionLogService, GeminiCliAdapter, POST_TOOL_USE, PRE_TOOL_USE, parseHookType };
+export { AFTER_TOOL_USE, BEFORE_TOOL_USE, BaseAdapter, ClaudeCodeAdapter, ClaudeCodeHookTypes, DECISION_ALLOW, DECISION_ASK, DECISION_DENY, DECISION_SKIP, ExecutionLogService, GeminiCliAdapter, GeminiCliHookTypes, POST_TOOL_USE, PRE_TOOL_USE, STOP, TASK_COMPLETED, USER_PROMPT_SUBMIT, isHookContext, isHookResponse, parseHookType };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agiflowai/hooks-adapter",
   "description": "Hook adapters for normalizing AI agent hook formats (Claude Code, Gemini, etc.)",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "license": "AGPL-3.0",
   "author": "AgiflowIO",
   "repository": {
@@ -25,8 +25,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@agiflowai/aicode-utils": "1.0.13",
-    "@agiflowai/coding-agent-bridge": "1.0.16"
+    "@agiflowai/aicode-utils": "1.0.14",
+    "@agiflowai/coding-agent-bridge": "1.0.17"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",