cc-hooks-ts 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 sushichan044
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,217 @@
+# cc-hooks-ts
+
+Define Claude Code hooks with full type safety using TypeScript and Valibot validation.
+
+## Installation
+
+```bash
+npx npym add cc-hooks-ts
+```
+
+## Basic Usage
+
+> [!NOTE]
+> We highly recommend using Bun or Deno for automatic dependency downloading at runtime.
+>
+> - Deno: <https://docs.deno.com/runtime/fundamentals/modules/#managing-third-party-modules-and-libraries>
+> - Bun: <https://bun.com/docs/runtime/autoimport>
+
+### Define a Hook
+
+With Deno:
+
+```typescript
+#!/usr/bin/env -S deno run --quiet --allow-env --allow-read
+import { defineHook, runHook } from "cc-hooks-ts";
+
+// 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!"
+    });
+  }
+});
+
+await runHook(sessionHook);
+```
+
+Or with Bun:
+
+```typescript
+#!/usr/bin/env -S bun run --silent
+import { defineHook, runHook } from "cc-hooks-ts";
+
+const sessionHook = defineHook({
+  trigger: { SessionStart: true },
+  run: (context) => {
+    return context.success({
+      messageForUser: "Session started!"
+    });
+  }
+});
+
+await runHook(sessionHook);
+```
+
+### Call from Claude Code
+
+Then, load defined hooks in your Claude Code settings at `~/.claude/settings.json`.
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$HOME/.claude/<name-of-your-hooks>.ts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Custom Tool Type Support
+
+For better type inference in PreToolUse and PostToolUse hooks, you can extend the `ToolSchema` interface to define your own tool types:
+
+### Adding Custom Tool Definitions
+
+Extend the `ToolSchema` interface to add custom tool definitions:
+
+```typescript
+declare module "cc-hooks-ts" {
+  interface ToolSchema {
+    MyCustomTool: {
+      input: {
+        customParam: string;
+        optionalParam?: number;
+      };
+      response: {
+        result: string;
+      };
+    };
+  }
+}
+```
+
+Now you can use your custom tool with full type safety:
+
+```typescript
+const customToolHook = defineHook({
+  trigger: { PreToolUse: { MyCustomTool: true } },
+  run: (context) => {
+    // context.input.tool_input is typed as { customParam: string; optionalParam?: number; }
+    const { customParam, optionalParam } = context.input.tool_input;
+    return context.success();
+  }
+});
+```
+
+## API Reference
+
+### defineHook Function
+
+Creates type-safe hook definitions with full TypeScript inference:
+
+```typescript
+// 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
+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();
+  }
+});
+```
+
+### runHook Function
+
+Executes hooks with complete lifecycle management:
+
+- Reads input from stdin
+- Validates input using Valibot schemas
+- Creates typed context
+- Executes hook handler
+- Formats and outputs results
+
+```typescript
+await runHook(hook);
+```
+
+### Hook Context
+
+The context provides strongly typed input access and response helpers:
+
+```typescript
+run: (context) => {
+  // Typed input based on trigger configuration
+  const input = context.input;
+
+  // Response helpers
+  return context.success({ messageForUser: "Success!" });
+  // or context.blockingError("Error occurred");
+  // or context.nonBlockingError("Warning message");
+  // or context.json({ event: "EventName", output: {...} });
+}
+```
+
+## Development
+
+```bash
+# Run tests
+pnpm test
+
+# Build
+pnpm build
+
+# Lint
+pnpm lint
+
+# Format
+pnpm format
+
+# Type check
+pnpm typecheck
+```
+
+## Documentation
+
+For more detailed information about Claude Code hooks, visit the [official documentation](https://docs.anthropic.com/en/docs/claude-code/hooks).
+
+## License
+
+MIT
+
+## Contributing
+
+We welcome contributions! Feel free to open issues or submit pull requests.
+
+---
+
+**Made with ❤️ for hackers using Claude Code**

package/dist/index.d.mts

@@ -0,0 +1,562 @@
+import * as v from "valibot";
+
+//#region src/event.d.ts
+declare const SUPPORTED_HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "Notification", "UserPromptSubmit", "Stop", "SubagentStop", "PreCompact", "SessionStart", "SessionEnd"];
+/**
+ * @see {@link https://docs.anthropic.com/en/docs/claude-code/hooks#hook-events}
+ */
+type SupportedHookEvent = (typeof SUPPORTED_HOOK_EVENTS)[number];
+//#endregion
+//#region src/output.d.ts
+type HookOutput = {
+  PreToolUse: PreToolUseHookOutput;
+  PostToolUse: PostToolUseHookOutput;
+  UserPromptSubmit: UserPromptSubmitHookOutput;
+  Stop: StopHookOutput;
+  SubagentStop: SubagentStopHookOutput;
+  SessionStart: SessionStartHookOutput;
+  Notification: CommonHookOutputs;
+  PreCompact: CommonHookOutputs;
+  SessionEnd: CommonHookOutputs;
+};
+type ExtractHookOutput<TEvent extends SupportedHookEvent> = HookOutput extends Record<SupportedHookEvent, unknown> ? HookOutput[TEvent] : never;
+/**
+ * Common fields of hook outputs
+ *
+ * @see {@link https://docs.anthropic.com/en/docs/claude-code/hooks#common-json-fields}
+ */
+type CommonHookOutputs = {
+  /**
+   * Whether Claude should continue after hook execution
+   *
+   * If `continue` is false, Claude stops processing after the hooks run.
+   * @default true
+   */
+  continue?: boolean;
+  /**
+   * Accompanies `continue` with a `reason` shown to the user, not shown to Claude.
+   *
+   * NOT FOR CLAUDE
+   */
+  stopReason?: string;
+  /**
+   * If `true`, user cannot see the stdout of this hook.
+   *
+   * @default false
+   */
+  suppressOutput?: boolean;
+  /**
+   * Optional warning message shown to the user
+   */
+  systemMessage?: string;
+};
+/**
+ * @see {@link https://docs.anthropic.com/en/docs/claude-code/hooks#pretooluse-decision-control}
+ */
+interface PreToolUseHookOutput extends CommonHookOutputs {
+  /**
+   * - `block` automatically prompts Claude with `reason`.
+   * - `undefined` does nothing. `reason` is ignored.
+   */
+  decision: "block" | undefined;
+  hookSpecificOutput?: {
+    hookEventName: "PreToolUse";
+    /**
+     * Adds context for Claude to consider.
+     */
+    additionalContext?: string;
+  };
+  reason?: string;
+}
+/**
+ * @see {@link https://docs.anthropic.com/en/docs/claude-code/hooks#posttooluse-decision-control}
+ */
+interface PostToolUseHookOutput extends CommonHookOutputs {
+  /**
+   * - `block` automatically prompts Claude with `reason`.
+   * - `undefined` does nothing. `reason` is ignored.
+   */
+  decision: "block" | undefined;
+  hookSpecificOutput?: {
+    hookEventName: "PostToolUse";
+    /**
+     * Adds context for Claude to consider.
+     */
+    additionalContext?: string;
+  };
+  reason?: string;
+}
+/**
+ * @see {@link https://docs.anthropic.com/en/docs/claude-code/hooks#userpromptsubmit-decision-control}
+ */
+interface UserPromptSubmitHookOutput extends CommonHookOutputs {
+  /**
+   * - `block` prevents the prompt from being processed.
+   *   The submitted prompt is erased from context. `reason` is shown to the user but not added to context.
+   *
+   * - `undefined` allows the prompt to proceed normally. `reason` is ignored.
+   */
+  decision?: "block" | undefined;
+  hookSpecificOutput?: {
+    hookEventName: "UserPromptSubmit";
+    /**
+     * Adds the string to the context if not blocked.
+     */
+    additionalContext?: string;
+  };
+  reason?: string;
+}
+/**
+ * @see {@link https://docs.anthropic.com/en/docs/claude-code/hooks#stop%2Fsubagentstop-decision-control}
+ */
+interface StopHookOutput extends CommonHookOutputs {
+  /**
+   * - `block` prevents Claude from stopping. You must populate `reason` for Claude to know how to proceed.
+   *
+   * - `undefined` allows Claude to stop. `reason` is ignored.
+   */
+  decision: "block" | undefined;
+  /**
+   * Reason for the decision.
+   */
+  reason?: string;
+}
+/**
+ * @see {@link https://docs.anthropic.com/en/docs/claude-code/hooks#stop%2Fsubagentstop-decision-control}
+ */
+interface SubagentStopHookOutput extends CommonHookOutputs {
+  /**
+   * - `block` prevents Claude from stopping. You must populate `reason` for Claude to know how to proceed.
+   *
+   * - `undefined` allows Claude to stop. `reason` is ignored.
+   */
+  decision: "block" | undefined;
+  /**
+   * Reason for the decision.
+   */
+  reason?: string;
+}
+interface SessionStartHookOutput extends CommonHookOutputs {
+  hookSpecificOutput?: {
+    hookEventName: "SessionStart";
+    /**
+     * Adds the string to the context.
+     */
+    additionalContext?: string;
+  };
+}
+//#endregion
+//#region src/input/schemas.d.ts
+/**
+ * @package
+ */
+declare const HookInputSchemas: {
+  readonly PreToolUse: v.ObjectSchema<{
+    readonly hook_event_name: v.LiteralSchema<"PreToolUse", undefined>;
+    readonly cwd: v.StringSchema<undefined>;
+    readonly session_id: v.StringSchema<undefined>;
+    readonly transcript_path: v.StringSchema<undefined>;
+  } & {
+    tool_input: v.UnknownSchema;
+    tool_name: v.IntersectSchema<[v.StringSchema<undefined>, v.RecordSchema<v.StringSchema<undefined>, v.NeverSchema<undefined>, undefined>], undefined>;
+  }, undefined>;
+  readonly PostToolUse: v.ObjectSchema<{
+    readonly hook_event_name: v.LiteralSchema<"PostToolUse", undefined>;
+    readonly cwd: v.StringSchema<undefined>;
+    readonly session_id: v.StringSchema<undefined>;
+    readonly transcript_path: v.StringSchema<undefined>;
+  } & {
+    tool_input: v.UnknownSchema;
+    tool_name: v.StringSchema<undefined>;
+    tool_response: v.UnknownSchema;
+  }, undefined>;
+  readonly Notification: v.ObjectSchema<{
+    readonly hook_event_name: v.LiteralSchema<"Notification", undefined>;
+    readonly cwd: v.StringSchema<undefined>;
+    readonly session_id: v.StringSchema<undefined>;
+    readonly transcript_path: v.StringSchema<undefined>;
+  } & {
+    message: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+  }, undefined>;
+  readonly UserPromptSubmit: v.ObjectSchema<{
+    readonly hook_event_name: v.LiteralSchema<"UserPromptSubmit", undefined>;
+    readonly cwd: v.StringSchema<undefined>;
+    readonly session_id: v.StringSchema<undefined>;
+    readonly transcript_path: v.StringSchema<undefined>;
+  } & {
+    prompt: v.StringSchema<undefined>;
+  }, undefined>;
+  readonly Stop: v.ObjectSchema<{
+    readonly hook_event_name: v.LiteralSchema<"Stop", undefined>;
+    readonly cwd: v.StringSchema<undefined>;
+    readonly session_id: v.StringSchema<undefined>;
+    readonly transcript_path: v.StringSchema<undefined>;
+  } & {
+    stop_hook_active: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+  }, undefined>;
+  readonly SubagentStop: v.ObjectSchema<{
+    readonly hook_event_name: v.LiteralSchema<"SubagentStop", undefined>;
+    readonly cwd: v.StringSchema<undefined>;
+    readonly session_id: v.StringSchema<undefined>;
+    readonly transcript_path: v.StringSchema<undefined>;
+  } & {
+    stop_hook_active: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+  }, undefined>;
+  readonly PreCompact: v.ObjectSchema<{
+    readonly hook_event_name: v.LiteralSchema<"PreCompact", undefined>;
+    readonly cwd: v.StringSchema<undefined>;
+    readonly session_id: v.StringSchema<undefined>;
+    readonly transcript_path: v.StringSchema<undefined>;
+  } & {
+    custom_instructions: v.StringSchema<undefined>;
+    trigger: v.UnionSchema<[v.LiteralSchema<"manual", undefined>, v.LiteralSchema<"auto", undefined>], undefined>;
+  }, undefined>;
+  readonly SessionStart: v.ObjectSchema<{
+    readonly hook_event_name: v.LiteralSchema<"SessionStart", undefined>;
+    readonly cwd: v.StringSchema<undefined>;
+    readonly session_id: v.StringSchema<undefined>;
+    readonly transcript_path: v.StringSchema<undefined>;
+  } & {
+    source: v.StringSchema<undefined>;
+  }, undefined>;
+  readonly SessionEnd: v.ObjectSchema<{
+    readonly hook_event_name: v.LiteralSchema<"SessionEnd", undefined>;
+    readonly cwd: v.StringSchema<undefined>;
+    readonly session_id: v.StringSchema<undefined>;
+    readonly transcript_path: v.StringSchema<undefined>;
+  } & {
+    reason: v.StringSchema<undefined>;
+  }, undefined>;
+};
+//#endregion
+//#region src/input/types.d.ts
+/**
+ * Internal type that combines base hook inputs with tool-specific inputs for PreToolUse events.
+ * For non-PreToolUse events, this is equivalent to BaseHookInputs.
+ *
+ * @example
+ * ```ts
+ * type PreToolUseInputs = HookInputs["PreToolUse"]
+ * // Result: Base inputs + { Read: SpecifiedToolUseInput<"Read">, WebFetch: SpecifiedToolUseInput<"WebFetch"> }
+ * ```
+ * @package
+ */
+type HookInputs = { [EventKey in SupportedHookEvent]: EventKey extends "PreToolUse" ? ToolSpecificPreToolUseInput & {
+  default: BaseHookInputs["PreToolUse"];
+} : EventKey extends "PostToolUse" ? ToolSpecificPostToolUseInput & {
+  default: BaseHookInputs["PostToolUse"];
+} : {
+  default: BaseHookInputs[EventKey];
+} };
+/**
+ * Extracts all possible hook input types for a specific event type.
+ * For non-tool-specific events, this returns only the default input type.
+ * For tool-specific events (PreToolUse/PostToolUse), this returns a union of all possible inputs including default and tool-specific variants.
+ *
+ * @example
+ * ```ts
+ * // For non-tool-specific events
+ * type SessionStartInputs = ExtractAllHookInputsForEvent<"SessionStart">
+ * // Result: { cwd: string; hook_event_name: "SessionStart"; session_id: string; transcript_path: string }
+ *
+ * // For tool-specific events
+ * type PreToolUseInputs = ExtractAllHookInputsForEvent<"PreToolUse">
+ * // Result: Union of default input + all tool-specific inputs (Read, WebFetch, etc.)
+ * ```
+ * @package
+ */
+type ExtractAllHookInputsForEvent<TEvent extends SupportedHookEvent> = { [K in keyof HookInputs[TEvent]]: HookInputs[TEvent][K] }[keyof HookInputs[TEvent]];
+/**
+ * Extracts the hook input type for a specific tool within a given event type.
+ * This type utility is used to get strongly-typed inputs for tool-specific hook handlers.
+ * The second parameter is constrained to valid tool names for the given event type.
+ *
+ * @example
+ * ```ts
+ * // Extract Read tool input for PreToolUse event
+ * type ReadPreInput = ExtractSpecificHookInputForEvent<"PreToolUse", "Read">
+ * // Result: { cwd: string; hook_event_name: "PreToolUse"; session_id: string; transcript_path: string; tool_input: ReadInput; tool_name: "Read" }
+ *
+ * // Extract WebFetch tool input for PostToolUse event
+ * type WebFetchPostInput = ExtractSpecificHookInputForEvent<"PostToolUse", "WebFetch">
+ * // Result: { cwd: string; hook_event_name: "PostToolUse"; session_id: string; transcript_path: string; tool_input: WebFetchInput; tool_name: "WebFetch"; tool_response: WebFetchResponse }
+ *
+ * // Type error: "Read" is not valid for non-tool-specific events
+ * type Invalid = ExtractSpecificHookInputForEvent<"SessionStart", "Read"> // ❌ Compile error
+ * ```
+ * @package
+ */
+type ExtractSpecificHookInputForEvent<TEvent extends SupportedHookEvent, TSpecificKey extends ExtractExtendedSpecificKeys<TEvent>> = { [K in keyof HookInputs[TEvent]]: K extends TSpecificKey ? HookInputs[TEvent][K] : never }[keyof HookInputs[TEvent]];
+/**
+ * @package
+ */
+type ExtractExtendedSpecificKeys<TEvent extends SupportedHookEvent> = Exclude<keyof HookInputs[TEvent], "default">;
+type BaseHookInputs = { [EventKey in SupportedHookEvent]: v.InferOutput<(typeof HookInputSchemas)[EventKey]> };
+type ToolSpecificPreToolUseInput = { [K in keyof ToolSchema]: Omit<BaseHookInputs["PreToolUse"], "tool_input" | "tool_name"> & {
+  tool_input: ToolSchema[K]["input"];
+  tool_name: K;
+} };
+type ToolSpecificPostToolUseInput = { [K in keyof ToolSchema]: Omit<BaseHookInputs["PostToolUse"], "tool_input" | "tool_name" | "tool_response"> & {
+  tool_input: ToolSchema[K]["input"];
+  tool_name: K;
+  tool_response: ToolSchema[K]["response"];
+} };
+//#endregion
+//#region src/types.d.ts
+type HookTrigger = Partial<{ [TEvent in SupportedHookEvent]: true | Partial<{ [SchemaKey in ExtractExtendedSpecificKeys<TEvent>]?: true }> }>;
+type ExtractTriggeredHookInput<TTrigger extends HookTrigger> = { [EventKey in keyof TTrigger]: EventKey extends SupportedHookEvent ? TTrigger[EventKey] extends true ? ExtractAllHookInputsForEvent<EventKey> : TTrigger[EventKey] extends Record<PropertyKey, true> ? { [SpecificKey in keyof TTrigger[EventKey]]: SpecificKey extends ExtractExtendedSpecificKeys<EventKey> ? ExtractSpecificHookInputForEvent<EventKey, SpecificKey> : never }[keyof TTrigger[EventKey]] : never : never }[keyof TTrigger];
+//#endregion
+//#region src/context.d.ts
+interface HookContext<THookTrigger extends HookTrigger> {
+  /**
+   * Cause a blocking error.
+   *
+   * @param error `error` is fed back to Claude to process automatically
+   */
+  blockingError: (error: string) => HookResponseBlockingError;
+  input: ExtractTriggeredHookInput<THookTrigger>;
+  /**
+   * Direct access to advanced JSON output.
+   *
+   * @see {@link https://docs.anthropic.com/en/docs/claude-code/hooks#advanced%3A-json-output}
+   */
+  json: (payload: HookResultJSON<THookTrigger>) => HookResponseJSON<THookTrigger>;
+  /**
+   * Cause a non-blocking error.
+   *
+   * @param message `message` is shown to the user and execution continues.
+   */
+  nonBlockingError: (message?: string) => HookResponseNonBlockingError;
+  /**
+   * Indicate successful handling of the hook.
+   */
+  success: (payload?: HookSuccessPayload) => HookResponseSuccess;
+}
+type HookResponse<THookTrigger extends HookTrigger> = HookResponseBlockingError | HookResponseJSON<THookTrigger> | HookResponseNonBlockingError | HookResponseSuccess;
+type HookResponseNonBlockingError = {
+  kind: "non-blocking-error";
+  payload?: string;
+};
+type HookResponseBlockingError = {
+  kind: "blocking-error";
+  payload: string;
+};
+type HookResponseSuccess = {
+  kind: "success";
+  payload: HookSuccessPayload;
+};
+type HookSuccessPayload = {
+  /**
+   * Message shown to the user in transcript mode.
+   */
+  messageForUser?: string | undefined;
+  /**
+   * Additional context for Claude.
+   *
+   * Only works for `UserPromptSubmit` and `SessionStart` hooks.
+   */
+  additionalClaudeContext?: string | undefined;
+};
+type HookResponseJSON<TTrigger extends HookTrigger> = {
+  kind: "json";
+  payload: HookResultJSON<TTrigger>;
+};
+type HookResultJSON<TTrigger extends HookTrigger> = { [EventKey in keyof TTrigger]: EventKey extends SupportedHookEvent ? TTrigger[EventKey] extends true | Record<PropertyKey, true> ? {
+  /**
+   * The name of the event being triggered.
+   *
+   * Required for proper TypeScript inference.
+   */
+  event: EventKey;
+  /**
+   * The output data for the event.
+   */
+  output: ExtractHookOutput<EventKey>;
+} : never : never }[keyof TTrigger];
+//#endregion
+//#region src/utils/types.d.ts
+type Awaitable<T> = Promise<T> | T;
+//#endregion
+//#region src/define.d.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();
+ *   }
+ * });
+ * ```
+ */
+declare function defineHook<THookTrigger extends HookTrigger = HookTrigger>(definition: HookDefinition<THookTrigger>): HookDefinition<THookTrigger>;
+type HookDefinition<THookTrigger extends HookTrigger = HookTrigger> = {
+  /**
+   * The event that triggers the hook.
+   */
+  trigger: THookTrigger;
+  /**
+   * The function to run when the hook is triggered.
+   *
+   * @example
+   * ```ts
+   * // Example usage
+   * (context) => {
+   *   const input = context.input;
+   *
+   *   // Your hook logic here
+   *
+   *   return context.success();
+   * }
+   */
+  run: HookHandler<THookTrigger>;
+  /**
+   * Determines whether the hook should run.
+   *
+   * @default true
+   *
+   * @returns Whether the hook should run.
+   */
+  shouldRun?: (() => Awaitable<boolean>) | boolean;
+};
+type HookHandler<THookTrigger extends HookTrigger> = (context: HookContext<THookTrigger>) => Awaitable<HookResponse<THookTrigger>>;
+//#endregion
+//#region src/run.d.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);
+ * ```
+ */
+declare function runHook<THookTrigger extends HookTrigger = HookTrigger>(def: HookDefinition<THookTrigger>): Promise<void>;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Represents the input schema for each tool in the `PreToolUse` and `PostToolUse` hooks.
+ *
+ * This interface enables type-safe hook handling with tool-specific inputs and responses.
+ * Users can extend this interface with declaration merging to add custom tool definitions.
+ *
+ * @example
+ * ```ts
+ * // Extend with custom tools
+ * declare module "cc-hooks-ts" {
+ *   interface ToolSchema {
+ *     MyCustomTool: {
+ *       input: {
+ *         customParam: string;
+ *         optionalParam?: number;
+ *       };
+ *       response: {
+ *         result: string;
+ *       };
+ *     };
+ *   }
+ * }
+ *
+ * // Use in hook definition
+ * const hook = defineHook({
+ *   trigger: { PreToolUse: { MyCustomTool: true } },
+ *   run: (context) => {
+ *     // context.input.tool_input is now typed as { customParam: string; optionalParam?: number; }
+ *     const { customParam, optionalParam } = context.input.tool_input;
+ *     return context.success();
+ *   }
+ * });
+ * ```
+ */
+interface ToolSchema {
+  Read: {
+    input: {
+      file_path: string;
+    };
+    response: unknown;
+  };
+  WebFetch: {
+    input: {
+      prompt: string;
+      url: string;
+    };
+    response: unknown;
+  };
+}
+//#endregion
+export { type ExtractAllHookInputsForEvent, type ExtractSpecificHookInputForEvent, ToolSchema, defineHook, runHook };

package/dist/index.mjs

@@ -0,0 +1,130 @@
+import { readFileSync } from "node:fs";
+import process from "node:process";
+import * as v from "valibot";
+function defineHook(definition) {
+	return definition;
+}
+function createContext(input) {
+	return {
+		blockingError: (error) => ({
+			kind: "blocking-error",
+			payload: error
+		}),
+		input,
+		nonBlockingError: (message) => ({
+			kind: "non-blocking-error",
+			payload: message
+		}),
+		success: (result) => ({
+			kind: "success",
+			payload: {
+				additionalClaudeContext: result?.additionalClaudeContext,
+				messageForUser: result?.messageForUser
+			}
+		}),
+		json: (payload) => ({
+			kind: "json",
+			payload
+		})
+	};
+}
+const SUPPORTED_HOOK_EVENTS = [
+	"PreToolUse",
+	"PostToolUse",
+	"Notification",
+	"UserPromptSubmit",
+	"Stop",
+	"SubagentStop",
+	"PreCompact",
+	"SessionStart",
+	"SessionEnd"
+];
+const baseHookInputSchema = v.object({
+	cwd: v.string(),
+	hook_event_name: v.union(SUPPORTED_HOOK_EVENTS.map((e) => v.literal(e))),
+	session_id: v.string(),
+	transcript_path: v.string()
+});
+function buildHookInputSchema(hook_event_name, entries) {
+	return v.object({
+		...baseHookInputSchema.entries,
+		hook_event_name: v.literal(hook_event_name),
+		...entries
+	});
+}
+const HookInputSchemas = {
+	PreToolUse: buildHookInputSchema("PreToolUse", {
+		tool_input: v.unknown(),
+		tool_name: v.intersect([v.string(), v.record(v.string(), v.never())])
+	}),
+	PostToolUse: buildHookInputSchema("PostToolUse", {
+		tool_input: v.unknown(),
+		tool_name: v.string(),
+		tool_response: v.unknown()
+	}),
+	Notification: buildHookInputSchema("Notification", { message: v.optional(v.string()) }),
+	UserPromptSubmit: buildHookInputSchema("UserPromptSubmit", { prompt: v.string() }),
+	Stop: buildHookInputSchema("Stop", { stop_hook_active: v.optional(v.boolean()) }),
+	SubagentStop: buildHookInputSchema("SubagentStop", { stop_hook_active: v.optional(v.boolean()) }),
+	PreCompact: buildHookInputSchema("PreCompact", {
+		custom_instructions: v.string(),
+		trigger: v.union([v.literal("manual"), v.literal("auto")])
+	}),
+	SessionStart: buildHookInputSchema("SessionStart", { source: v.string() }),
+	SessionEnd: buildHookInputSchema("SessionEnd", { reason: v.string() })
+};
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.length > 0;
+}
+async function runHook(def) {
+	const { run, shouldRun = true, trigger } = def;
+	let eventName = null;
+	try {
+		const proceed = typeof shouldRun === "function" ? await shouldRun() : shouldRun;
+		if (!proceed) return handleHookResult(eventName, {
+			kind: "success",
+			payload: {}
+		});
+		const inputSchema = extractInputSchemaFromTrigger(trigger);
+		const rawInput = readFileSync(process.stdin.fd, "utf-8");
+		const parsed = v.parse(inputSchema, JSON.parse(rawInput));
+		eventName = parsed.hook_event_name;
+		const context = createContext(parsed);
+		const result = await run(context);
+		handleHookResult(eventName, result);
+	} catch (error) {
+		handleHookResult(eventName, {
+			kind: "non-blocking-error",
+			payload: `Error in hook: ${error instanceof Error ? error.message : String(error)}`
+		});
+	}
+}
+function handleHookResult(eventName, hookResult) {
+	switch (hookResult.kind) {
+		case "success":
+			if (eventName === "UserPromptSubmit" || eventName === "SessionStart") {
+				if (isNonEmptyString(hookResult.payload.additionalClaudeContext)) {
+					console.log(hookResult.payload.additionalClaudeContext);
+					return process.exit(0);
+				}
+			}
+			if (isNonEmptyString(hookResult.payload.messageForUser)) console.log(hookResult.payload.messageForUser);
+			return process.exit(0);
+		case "blocking-error":
+			if (hookResult.payload) console.error(hookResult.payload);
+			return process.exit(2);
+		case "non-blocking-error":
+			if (isNonEmptyString(hookResult.payload)) console.error(hookResult.payload);
+			return process.exit(1);
+		case "json":
+			console.log(JSON.stringify(hookResult.payload));
+			return process.exit(0);
+	}
+}
+function extractInputSchemaFromTrigger(trigger) {
+	const schemas = Object.keys(trigger).map((hookEvent) => {
+		return HookInputSchemas[hookEvent];
+	});
+	return v.union(schemas);
+}
+export { defineHook, runHook };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "cc-hooks-ts",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Write claude code hooks with type safety",
+  "sideEffects": false,
+  "license": "MIT",
+  "author": {
+    "name": "sushichan044",
+    "url": "https://github.com/sushichan044"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sushichan044/cc-hooks-ts.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": true
+  },
+  "bugs": {
+    "url": "https://github.com/sushichan044/cc-hooks-ts/issues"
+  },
+  "engines": {
+    "node": "^20.12.0 || ^22.0.0 || >=24.0.0"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "hooks",
+    "typescript",
+    "type-safety",
+    "anthropic"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "devDependencies": {
+    "@arethetypeswrong/core": "0.18.2",
+    "@biomejs/biome": "2.1.2",
+    "@types/node": "24.3.0",
+    "@virtual-live-lab/eslint-config": "2.2.24",
+    "@virtual-live-lab/tsconfig": "2.1.21",
+    "eslint": "9.31.0",
+    "eslint-plugin-import-access": "3.0.0",
+    "pkg-pr-new": "0.0.54",
+    "publint": "0.3.12",
+    "release-it": "19.0.4",
+    "release-it-pnpm": "4.6.6",
+    "tsdown": "0.14.1",
+    "typescript": "5.9.2",
+    "typescript-eslint": "8.39.0",
+    "unplugin-unused": "0.5.2",
+    "vitest": "3.2.4"
+  },
+  "dependencies": {
+    "valibot": "^1.1.0"
+  },
+  "scripts": {
+    "lint": "eslint --max-warnings 0 --fix .",
+    "format": "biome format --write .",
+    "format:check": "biome format . --reporter=github",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run",
+    "build": "tsdown",
+    "pkg-pr-new": "pkg-pr-new publish --compact --comment=update --pnpm"
+  }
+}