cc-hooks-ts 2.1.63 → 2.1.74

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as v from "valibot";
-import { AgentInput, AgentOutput, AskUserQuestionInput, AskUserQuestionOutput, BashInput, BashOutput, ExitPlanModeInput, ExitPlanModeOutput, FileEditInput, FileEditOutput, FileReadInput, FileReadOutput, FileWriteInput, FileWriteOutput, GlobInput, GlobOutput, GrepInput, GrepOutput, ListMcpResourcesInput, ListMcpResourcesOutput, NotebookEditInput, NotebookEditOutput, ReadMcpResourceInput, ReadMcpResourceOutput, TaskOutputInput, TaskStopInput, TaskStopOutput, TodoWriteInput, TodoWriteOutput, WebFetchInput, WebFetchOutput, WebSearchInput, WebSearchOutput } from "@anthropic-ai/claude-agent-sdk/sdk-tools";
+import { AgentInput, AgentOutput, AskUserQuestionInput, AskUserQuestionOutput, BashInput, BashOutput, ExitPlanModeInput, ExitPlanModeOutput, ExitWorktreeInput, ExitWorktreeOutput, FileEditInput, FileEditOutput, FileReadInput, FileReadOutput, FileWriteInput, FileWriteOutput, GlobInput, GlobOutput, GrepInput, GrepOutput, ListMcpResourcesInput, ListMcpResourcesOutput, NotebookEditInput, NotebookEditOutput, ReadMcpResourceInput, ReadMcpResourceOutput, TaskOutputInput, TaskStopInput, TaskStopOutput, TodoWriteInput, TodoWriteOutput, WebFetchInput, WebFetchOutput, WebSearchInput, WebSearchOutput } from "@anthropic-ai/claude-agent-sdk/sdk-tools";
 
 //#region src/utils/types.d.ts
 type Awaitable<T> = Promise<T> | T;
@@ -11,6 +11,8 @@ type AutoComplete<T extends string> = Record<string, never> & T;
  */
 declare const HookInputSchemas: {
   readonly PreToolUse: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
@@ -22,6 +24,8 @@ declare const HookInputSchemas: {
     tool_use_id: v.StringSchema<undefined>;
   }, undefined>;
   readonly PostToolUse: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
@@ -34,6 +38,8 @@ declare const HookInputSchemas: {
     tool_use_id: v.StringSchema<undefined>;
   }, undefined>;
   readonly PostToolUseFailure: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
@@ -47,6 +53,8 @@ declare const HookInputSchemas: {
     tool_use_id: v.StringSchema<undefined>;
   }, undefined>;
   readonly Notification: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
@@ -58,6 +66,8 @@ declare const HookInputSchemas: {
     title: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
   }, undefined>;
   readonly UserPromptSubmit: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
@@ -67,6 +77,8 @@ declare const HookInputSchemas: {
     prompt: v.StringSchema<undefined>;
   }, undefined>;
   readonly Stop: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
@@ -76,30 +88,37 @@ declare const HookInputSchemas: {
     last_assistant_message: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     stop_hook_active: v.BooleanSchema<undefined>;
   }, undefined>;
-  readonly SubagentStart: v.ObjectSchema<{
+  readonly SubagentStart: v.ObjectSchema<Omit<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
     readonly transcript_path: v.StringSchema<undefined>;
     readonly hook_event_name: v.LiteralSchema<"SubagentStart", undefined>;
-  } & {
-    agent_id: v.StringSchema<undefined>;
-    agent_type: v.StringSchema<undefined>;
+  }, "agent_id" | "agent_type"> & {
+    readonly agent_id: v.StringSchema<undefined>;
+    readonly agent_type: v.StringSchema<undefined>;
   }, undefined>;
-  readonly SubagentStop: v.ObjectSchema<{
+  readonly SubagentStop: v.ObjectSchema<Omit<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
     readonly transcript_path: v.StringSchema<undefined>;
     readonly hook_event_name: v.LiteralSchema<"SubagentStop", undefined>;
   } & {
-    agent_id: v.StringSchema<undefined>;
     agent_transcript_path: v.StringSchema<undefined>;
-    agent_type: v.StringSchema<undefined>;
     last_assistant_message: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     stop_hook_active: v.BooleanSchema<undefined>;
+  }, "agent_id" | "agent_type"> & {
+    readonly agent_id: v.StringSchema<undefined>;
+    readonly agent_type: v.StringSchema<undefined>;
   }, undefined>;
   readonly PreCompact: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
@@ -110,6 +129,8 @@ declare const HookInputSchemas: {
     trigger: v.PicklistSchema<["manual", "auto"], undefined>;
   }, undefined>;
   readonly SessionStart: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
@@ -121,6 +142,8 @@ declare const HookInputSchemas: {
     source: v.PicklistSchema<["startup", "resume", "clear", "compact"], undefined>;
   }, undefined>;
   readonly SessionEnd: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
@@ -130,6 +153,8 @@ declare const HookInputSchemas: {
     reason: v.PicklistSchema<["clear", "logout", "prompt_input_exit", "other", "bypass_permissions_disabled"], undefined>;
   }, undefined>;
   readonly PermissionRequest: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
@@ -177,6 +202,8 @@ declare const HookInputSchemas: {
     tool_name: v.StringSchema<undefined>;
   }, undefined>;
   readonly Setup: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
@@ -186,6 +213,8 @@ declare const HookInputSchemas: {
     trigger: v.PicklistSchema<["init", "maintenance"], undefined>;
   }, undefined>;
   readonly TeammateIdle: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
@@ -196,6 +225,8 @@ declare const HookInputSchemas: {
     teammate_name: v.StringSchema<undefined>;
   }, undefined>;
   readonly TaskCompleted: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
@@ -209,6 +240,8 @@ declare const HookInputSchemas: {
     teammate_name: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
   }, undefined>;
   readonly ConfigChange: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
@@ -219,6 +252,8 @@ declare const HookInputSchemas: {
     source: v.PicklistSchema<["local_settings", "policy_settings", "project_settings", "skills", "user_settings"], undefined>;
   }, undefined>;
   readonly WorktreeCreate: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
@@ -228,6 +263,8 @@ declare const HookInputSchemas: {
     name: v.StringSchema<undefined>;
   }, undefined>;
   readonly WorktreeRemove: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
@@ -237,6 +274,8 @@ declare const HookInputSchemas: {
     worktree_path: v.StringSchema<undefined>;
   }, undefined>;
   readonly Elicitation: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
@@ -251,6 +290,8 @@ declare const HookInputSchemas: {
     url: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
   }, undefined>;
   readonly ElicitationResult: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
@@ -263,6 +304,22 @@ declare const HookInputSchemas: {
     mcp_server_name: v.StringSchema<undefined>;
     mode: v.ExactOptionalSchema<v.PicklistSchema<["form", "url"], undefined>, undefined>;
   }, undefined>;
+  readonly InstructionsLoaded: v.ObjectSchema<{
+    readonly agent_id: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly cwd: v.StringSchema<undefined>;
+    readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly session_id: v.StringSchema<undefined>;
+    readonly transcript_path: v.StringSchema<undefined>;
+    readonly hook_event_name: v.LiteralSchema<"InstructionsLoaded", undefined>;
+  } & {
+    file_path: v.StringSchema<undefined>;
+    globs: v.ExactOptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+    load_reason: v.PicklistSchema<["session_start", "nested_traversal", "path_glob_match", "include"], undefined>;
+    memory_type: v.PicklistSchema<["User", "Project", "Local", "Managed"], undefined>;
+    parent_file_path: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+    trigger_file_path: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
+  }, undefined>;
 };
 //#endregion
 //#region src/hooks/event.d.ts
@@ -271,7 +328,7 @@ declare const HookInputSchemas: {
  *
  * @package
  */
-type SupportedHookEvent = "PreToolUse" | "PostToolUse" | "PostToolUseFailure" | "Notification" | "UserPromptSubmit" | "SessionStart" | "SessionEnd" | "Stop" | "SubagentStart" | "SubagentStop" | "PreCompact" | "PermissionRequest" | "Setup" | "TeammateIdle" | "TaskCompleted" | "ConfigChange" | "WorktreeCreate" | "WorktreeRemove" | "Elicitation" | "ElicitationResult";
+type SupportedHookEvent = "PreToolUse" | "PostToolUse" | "PostToolUseFailure" | "Notification" | "UserPromptSubmit" | "SessionStart" | "SessionEnd" | "Stop" | "SubagentStart" | "SubagentStop" | "PreCompact" | "PermissionRequest" | "Setup" | "TeammateIdle" | "TaskCompleted" | "ConfigChange" | "WorktreeCreate" | "WorktreeRemove" | "Elicitation" | "ElicitationResult" | "InstructionsLoaded";
 //#endregion
 //#region src/hooks/input/types.d.ts
 /**
@@ -414,6 +471,7 @@ type HookOutput = {
   Elicitation: ElicitationHookOutput;
   ElicitationResult: ElicitationResultHookOutput;
   ConfigChange: CommonHookOutputs;
+  InstructionsLoaded: CommonHookOutputs;
   PreCompact: CommonHookOutputs;
   SessionEnd: CommonHookOutputs;
   TaskCompleted: CommonHookOutputs;
@@ -1038,6 +1096,10 @@ interface ToolSchema {
     input: ExitPlanModeInput;
     response: ExitPlanModeOutput;
   };
+  ExitWorktree: {
+    input: ExitWorktreeInput;
+    response: ExitWorktreeOutput;
+  };
   Glob: {
     input: GlobInput;
     response: GlobOutput;

package/dist/index.mjs

@@ -1,9 +1,63 @@
 import getStdin from "get-stdin";
 import process from "node:process";
 import * as v from "valibot";
+//#region src/define.ts
+/**
+* Creates a type-safe Claude Code hook definition.
+*
+* This function provides a way to define hooks with full TypeScript type safety,
+* including input validation using Valibot schemas and strongly typed context.
+*
+* @param definition - The hook definition object containing trigger events and handler function
+* @returns The same hook definition, but with enhanced type safety
+*
+* @example
+* ```ts
+* // Basic session start hook
+* const sessionHook = defineHook({
+*   trigger: { SessionStart: true },
+*   run: (context) => {
+*     console.log(`Session started: ${context.input.session_id}`);
+*     return context.success({
+*       messageForUser: "Welcome to your coding session!"
+*     });
+*   }
+* });
+*
+* // Tool-specific PreToolUse hook
+* const readHook = defineHook({
+*   trigger: { PreToolUse: { Read: true } },
+*   run: (context) => {
+*     // context.input.tool_input is typed as { file_path: string }
+*     const { file_path } = context.input.tool_input;
+*
+*     if (file_path.includes('.env')) {
+*       return context.blockingError('Cannot read environment files');
+*     }
+*
+*     return context.success();
+*   }
+* });
+*
+* // Multiple event triggers with conditional logic
+* const multiEventHook = defineHook({
+*   trigger: {
+*     PreToolUse: { Read: true, WebFetch: true },
+*     PostToolUse: { Read: true }
+*   },
+*   shouldRun: () => process.env.NODE_ENV === 'development',
+*   run: (context) => {
+*     // Handle different events and tools based on context.input
+*     return context.success();
+*   }
+* });
+* ```
+*/
 function defineHook(definition) {
 	return definition;
 }
+//#endregion
+//#region src/context.ts
 function createContext(input) {
 	return {
 		defer: (handler, options) => ({
@@ -33,6 +87,8 @@ function createContext(input) {
 		})
 	};
 }
+//#endregion
+//#region src/hooks/permission.ts
 const permissionBehaviorSchema = v.picklist([
 	"allow",
 	"deny",
@@ -49,6 +105,9 @@ const permissionRuleValueSchema = v.object({
 	ruleContent: v.exactOptional(v.string()),
 	toolName: v.string()
 });
+/**
+* @package
+*/
 const permissionUpdateSchema = v.variant("type", [
 	v.object({
 		behavior: permissionBehaviorSchema,
@@ -90,7 +149,11 @@ const permissionUpdateSchema = v.variant("type", [
 		type: v.literal("removeDirectories")
 	})
 ]);
+//#endregion
+//#region src/hooks/input/schemas.ts
 const baseHookInputSchema = v.object({
+	agent_id: v.exactOptional(v.string()),
+	agent_type: v.exactOptional(v.string()),
 	cwd: v.string(),
 	permission_mode: v.exactOptional(v.string()),
 	session_id: v.string(),
@@ -103,6 +166,17 @@ function buildHookInputSchema(hook_event_name, entries) {
 		...entries
 	});
 }
+function buildSubagentInputSchema(hook_event_name, entries) {
+	const base = buildHookInputSchema(hook_event_name, entries);
+	return v.object({
+		...v.omit(base, ["agent_id", "agent_type"]).entries,
+		agent_id: v.string(),
+		agent_type: v.string()
+	});
+}
+/**
+* @package
+*/
 const HookInputSchemas = {
 	PreToolUse: buildHookInputSchema("PreToolUse", {
 		tool_name: v.pipe(v.string(), v.transform((s) => s)),
@@ -132,14 +206,9 @@ const HookInputSchemas = {
 		last_assistant_message: v.exactOptional(v.string()),
 		stop_hook_active: v.boolean()
 	}),
-	SubagentStart: buildHookInputSchema("SubagentStart", {
-		agent_id: v.string(),
-		agent_type: v.string()
-	}),
-	SubagentStop: buildHookInputSchema("SubagentStop", {
-		agent_id: v.string(),
+	SubagentStart: buildSubagentInputSchema("SubagentStart", {}),
+	SubagentStop: buildSubagentInputSchema("SubagentStop", {
 		agent_transcript_path: v.string(),
-		agent_type: v.string(),
 		last_assistant_message: v.exactOptional(v.string()),
 		stop_hook_active: v.boolean()
 	}),
@@ -211,11 +280,77 @@ const HookInputSchemas = {
 		elicitation_id: v.exactOptional(v.string()),
 		mcp_server_name: v.string(),
 		mode: v.exactOptional(v.picklist(["form", "url"]))
+	}),
+	InstructionsLoaded: buildHookInputSchema("InstructionsLoaded", {
+		file_path: v.string(),
+		globs: v.exactOptional(v.array(v.string())),
+		load_reason: v.picklist([
+			"session_start",
+			"nested_traversal",
+			"path_glob_match",
+			"include"
+		]),
+		memory_type: v.picklist([
+			"User",
+			"Project",
+			"Local",
+			"Managed"
+		]),
+		parent_file_path: v.exactOptional(v.string()),
+		trigger_file_path: v.exactOptional(v.string())
 	})
 };
+//#endregion
+//#region src/utils/string.ts
 function isNonEmptyString(value) {
 	return typeof value === "string" && value.length > 0;
 }
+//#endregion
+//#region src/run.ts
+/**
+* Executes a Claude Code hook with runtime input validation and error handling.
+*
+* This function handles the complete lifecycle of hook execution including:
+* - Reading input from stdin
+* - Validating input against Valibot schemas
+* - Creating typed context
+* - Executing the hook handler
+* - Formatting and outputting results
+*
+* @param definition - The hook definition to execute
+*
+* @example
+* ```ts
+* // CLI usage: echo '{"hook_event_name":"SessionStart",...}' | node hook.js
+* const hook = defineHook({
+*   trigger: { SessionStart: true },
+*   run: (context) => context.success()
+* });
+*
+* // Execute the hook (typically called from CLI)
+* await runHook(hook);
+*
+* // Hook with error handling
+* const validationHook = defineHook({
+*   trigger: { PreToolUse: { Read: true } },
+*   run: (context) => {
+*     try {
+*       const { file_path } = context.input.tool_input;
+*
+*       if (!file_path.endsWith('.ts')) {
+*         return context.nonBlockingError('Warning: Non-TypeScript file detected');
+*       }
+*
+*       return context.success();
+*     } catch (error) {
+*       return context.blockingError(`Validation failed: ${error.message}`);
+*     }
+*   }
+* });
+*
+* await runHook(validationHook);
+* ```
+*/
 async function runHook(def) {
 	const { run, shouldRun = true, trigger } = def;
 	let eventName = null;
@@ -296,4 +431,5 @@ function extractInputSchemaFromTrigger(trigger) {
 	});
 	return v.union(schemas);
 }
+//#endregion
 export { defineHook, runHook };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-hooks-ts",
-  "version": "2.1.63",
+  "version": "2.1.74",
   "type": "module",
   "description": "Write claude code hooks with type safety",
   "sideEffects": false,
@@ -43,26 +43,26 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.2",
-    "@types/node": "25.2.1",
-    "@typescript/native-preview": "^7.0.0-dev.20251108.1",
+    "@types/node": "25.4.0",
+    "@typescript/native-preview": "7.0.0-dev.20260311.1",
     "@virtual-live-lab/eslint-config": "2.3.1",
     "@virtual-live-lab/tsconfig": "2.1.21",
     "eslint": "9.39.2",
     "eslint-plugin-import-access": "3.1.0",
     "oxfmt": "0.28.0",
-    "pkg-pr-new": "0.0.63",
-    "publint": "0.3.17",
+    "pkg-pr-new": "0.0.65",
+    "publint": "0.3.18",
     "release-it": "19.2.4",
     "release-it-pnpm": "4.6.6",
-    "tsdown": "0.20.3",
-    "type-fest": "5.4.3",
+    "tsdown": "0.21.2",
+    "type-fest": "5.4.4",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.54.0",
+    "typescript-eslint": "8.57.0",
     "unplugin-unused": "0.5.7",
     "vitest": "4.0.18"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.2.63",
+    "@anthropic-ai/claude-agent-sdk": "0.2.74",
     "get-stdin": "10.0.0",
     "valibot": "^1.1.0"
   },