cc-hooks-ts 0.0.6 → 0.1.0

package/README.md

@@ -2,6 +2,9 @@
 
 Define Claude Code hooks with full type safety using TypeScript and Valibot validation.
 
+> [!WARNING]
+> This library is expected to be used with Claude Code v2.0.0 or higher for better compatibility.
+
 ## Installation
 
 ```bash

package/dist/index.d.mts

@@ -1,18 +1,12 @@
 import * as v from "valibot";
+import { BashInput, FileEditInput, FileReadInput, FileWriteInput, GlobInput, GrepInput, NotebookEditInput, TodoWriteInput, WebFetchInput, WebSearchInput } from "@anthropic-ai/claude-code/sdk-tools.js";
 
-//#region src/hook-types/index.d.ts
-type ClaudeCodeTodo = {
-  activeForm: string;
-  content: string;
-  status: "completed" | "in_progress" | "pending";
-};
-//#endregion
 //#region src/utils/types.d.ts
 type Awaitable<T> = Promise<T> | T;
 type AutoComplete<T extends string> = Record<string, never> & T;
 //#endregion
 //#region src/event.d.ts
-declare const SUPPORTED_HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "Notification", "UserPromptSubmit", "Stop", "SubagentStop", "PreCompact", "SessionStart", "SessionEnd"];
+declare const SUPPORTED_HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "Notification", "UserPromptSubmit", "SessionStart", "SessionEnd", "Stop", "SubagentStop", "PreCompact"];
 /**
  * @see {@link https://docs.anthropic.com/en/docs/claude-code/hooks#hook-events}
  */
@@ -30,7 +24,7 @@ type HookOutput = {
   PreCompact: CommonHookOutputs;
   SessionEnd: CommonHookOutputs;
 };
-type ExtractHookOutput<TEvent extends SupportedHookEvent> = HookOutput extends Record<SupportedHookEvent, unknown> ? HookOutput[TEvent] : never;
+type ExtractHookOutput<TEvent$1 extends SupportedHookEvent> = HookOutput extends Record<SupportedHookEvent, unknown> ? HookOutput[TEvent$1] : never;
 /**
  * Common fields of hook outputs
  *
@@ -60,6 +54,18 @@ type CommonHookOutputs = {
    * Optional warning message shown to the user
    */
   systemMessage?: string;
+  /**
+   * Use `hookSpecificOutput` in appropriate hook events instead.
+   *
+   * @deprecated
+   */
+  reason?: string;
+  /**
+   * Use `hookSpecificOutput` in appropriate hook events instead.
+   *
+   * @deprecated
+   */
+  decision?: "approve" | "block";
 };
 /**
  * @see {@link https://docs.anthropic.com/en/docs/claude-code/hooks#pretooluse-decision-control}
@@ -72,8 +78,8 @@ interface PreToolUseHookOutput extends CommonHookOutputs {
      * - `deny` prevents the tool call from executing. `permissionDecisionReason` is shown to Claude.
      * - `ask` asks the user to confirm the tool call in the UI. `permissionDecisionReason` is shown to the user but not to Claude.
      */
-    permissionDecision: "allow" | "ask" | "deny";
-    permissionDecisionReason: string;
+    permissionDecision?: "allow" | "ask" | "deny";
+    permissionDecisionReason?: string;
   };
 }
 /**
@@ -81,10 +87,10 @@ interface PreToolUseHookOutput extends CommonHookOutputs {
  */
 interface PostToolUseHookOutput extends CommonHookOutputs {
   /**
+   * - `approve` has no effect; the tool response is processed normally.
    * - `block` automatically prompts Claude with `reason`.
-   * - `undefined` does nothing. `reason` is ignored.
    */
-  decision: "block" | undefined;
+  decision?: "approve" | "block";
   hookSpecificOutput?: {
     hookEventName: "PostToolUse";
     /**
@@ -99,12 +105,11 @@ interface PostToolUseHookOutput extends CommonHookOutputs {
  */
 interface UserPromptSubmitHookOutput extends CommonHookOutputs {
   /**
+   * - `approve` has no effect; the tool response is processed normally.
    * - `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;
+  decision?: "approve" | "block";
   hookSpecificOutput?: {
     hookEventName: "UserPromptSubmit";
     /**
@@ -119,11 +124,10 @@ interface UserPromptSubmitHookOutput extends CommonHookOutputs {
  */
 interface StopHookOutput extends CommonHookOutputs {
   /**
+   * - `approve` has no effect; the tool response is processed normally.
    * - `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;
+  decision?: "approve" | "block";
   /**
    * Reason for the decision.
    */
@@ -134,11 +138,9 @@ interface StopHookOutput extends CommonHookOutputs {
  */
 interface SubagentStopHookOutput extends CommonHookOutputs {
   /**
+   * - `approve` has no effect; the tool response is processed normally.
    * - `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.
    */
@@ -162,6 +164,7 @@ declare const HookInputSchemas: {
   readonly PreToolUse: v.ObjectSchema<{
     readonly hook_event_name: v.LiteralSchema<"PreToolUse", 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>;
   } & {
@@ -171,6 +174,7 @@ declare const HookInputSchemas: {
   readonly PostToolUse: v.ObjectSchema<{
     readonly hook_event_name: v.LiteralSchema<"PostToolUse", 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>;
   } & {
@@ -181,14 +185,17 @@ declare const HookInputSchemas: {
   readonly Notification: v.ObjectSchema<{
     readonly hook_event_name: v.LiteralSchema<"Notification", 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>;
   } & {
-    message: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    message: v.StringSchema<undefined>;
+    title: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
   }, undefined>;
   readonly UserPromptSubmit: v.ObjectSchema<{
     readonly hook_event_name: v.LiteralSchema<"UserPromptSubmit", 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>;
   } & {
@@ -197,39 +204,44 @@ declare const HookInputSchemas: {
   readonly Stop: v.ObjectSchema<{
     readonly hook_event_name: v.LiteralSchema<"Stop", 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>;
   } & {
-    stop_hook_active: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+    stop_hook_active: v.BooleanSchema<undefined>;
   }, undefined>;
   readonly SubagentStop: v.ObjectSchema<{
     readonly hook_event_name: v.LiteralSchema<"SubagentStop", 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>;
   } & {
-    stop_hook_active: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+    stop_hook_active: v.BooleanSchema<undefined>;
   }, undefined>;
   readonly PreCompact: v.ObjectSchema<{
     readonly hook_event_name: v.LiteralSchema<"PreCompact", 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>;
   } & {
-    custom_instructions: v.StringSchema<undefined>;
+    custom_instructions: v.NullableSchema<v.StringSchema<undefined>, 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 permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly session_id: v.StringSchema<undefined>;
     readonly transcript_path: v.StringSchema<undefined>;
   } & {
-    source: v.StringSchema<undefined>;
+    source: v.UnionSchema<[v.LiteralSchema<"startup", undefined>, v.LiteralSchema<"resume", undefined>, v.LiteralSchema<"clear", undefined>, v.LiteralSchema<"compact", undefined>], undefined>;
   }, undefined>;
   readonly SessionEnd: v.ObjectSchema<{
     readonly hook_event_name: v.LiteralSchema<"SessionEnd", 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>;
   } & {
@@ -273,7 +285,7 @@ type HookInputs = { [EventKey in SupportedHookEvent]: EventKey extends "PreToolU
  * ```
  * @package
  */
-type ExtractAllHookInputsForEvent<TEvent extends SupportedHookEvent> = { [K in keyof HookInputs[TEvent]]: HookInputs[TEvent][K] }[keyof HookInputs[TEvent]];
+type ExtractAllHookInputsForEvent<TEvent$1 extends SupportedHookEvent> = { [K in keyof HookInputs[TEvent$1]]: HookInputs[TEvent$1][K] }[keyof HookInputs[TEvent$1]];
 /**
  * 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.
@@ -294,11 +306,11 @@ type ExtractAllHookInputsForEvent<TEvent extends SupportedHookEvent> = { [K in k
  * ```
  * @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]];
+type ExtractSpecificHookInputForEvent<TEvent$1 extends SupportedHookEvent, TSpecificKey extends ExtractExtendedSpecificKeys<TEvent$1>> = { [K in keyof HookInputs[TEvent$1]]: K extends TSpecificKey ? HookInputs[TEvent$1][K] : never }[keyof HookInputs[TEvent$1]];
 /**
  * @package
  */
-type ExtractExtendedSpecificKeys<TEvent extends SupportedHookEvent> = Exclude<keyof HookInputs[TEvent], "default">;
+type ExtractExtendedSpecificKeys<TEvent$1 extends SupportedHookEvent> = Exclude<keyof HookInputs[TEvent$1], "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"];
@@ -550,15 +562,7 @@ declare function runHook<THookTrigger extends HookTrigger = HookTrigger>(def: Ho
  */
 interface ToolSchema {
   Bash: {
-    input: {
-      command: string;
-      description?: string;
-      run_in_background?: boolean;
-      /**
-       * Timeout in milliseconds for the process (ignored if run_in_background is true).
-       */
-      timeout?: number;
-    };
+    input: BashInput;
     response: {
       interrupted: boolean;
       isImage: boolean;
@@ -567,15 +571,7 @@ interface ToolSchema {
     };
   };
   Edit: {
-    input: {
-      file_path: string;
-      new_string: string;
-      old_string: string;
-      /**
-       * @default false
-       */
-      replace_all?: boolean;
-    };
+    input: FileEditInput;
     response: {
       filePath: string;
       newString: string;
@@ -593,13 +589,7 @@ interface ToolSchema {
     };
   };
   Glob: {
-    input: {
-      /**
-       * @default process.cwd()
-       */
-      path?: string;
-      pattern: string;
-    };
+    input: GlobInput;
     response: {
       durationMs: number;
       filenames: string[];
@@ -608,23 +598,7 @@ interface ToolSchema {
     };
   };
   Grep: {
-    input: {
-      "-A"?: number;
-      "-B"?: number;
-      "-C"?: number;
-      "-i"?: boolean;
-      "-n"?: boolean;
-      glob?: string;
-      head_limit?: number;
-      multiline?: boolean;
-      /**
-       * @default "files_with_matches"
-       */
-      output_mode?: "content" | "count" | "files_with_matches";
-      path?: string;
-      pattern: string;
-      type?: string;
-    };
+    input: GrepInput;
     response: {
       content: string;
       mode: "content" | "count" | "files_with_matches";
@@ -672,27 +646,7 @@ interface ToolSchema {
     };
   };
   NotebookEdit: {
-    /**
-     * @default edit_mode: "replace"
-     */
-    input: {
-      cell_id: string;
-      edit_mode: "delete";
-      new_source: string;
-      notebook_path: string;
-    } | {
-      cell_id: string;
-      cell_type?: "code" | "markdown";
-      edit_mode: "replace";
-      new_source: string;
-      notebook_path: string;
-    } | {
-      cell_id?: string;
-      cell_type: "code" | "markdown";
-      edit_mode: "insert";
-      new_source: string;
-      notebook_path: string;
-    };
+    input: NotebookEditInput;
     response: {
       cell_type: "code" | "markdown";
       edit_mode: "delete" | "insert" | "replace";
@@ -702,11 +656,7 @@ interface ToolSchema {
     };
   };
   Read: {
-    input: {
-      file_path: string;
-      limit?: number;
-      offset?: number;
-    };
+    input: FileReadInput;
     response: {
       file: {
         cells: Array<{
@@ -760,23 +710,11 @@ interface ToolSchema {
     };
   };
   TodoWrite: {
-    input: {
-      todos: ClaudeCodeTodo[];
-    };
-    response: {
-      newTodos: ClaudeCodeTodo[];
-      oldTodos: ClaudeCodeTodo[];
-    };
+    input: TodoWriteInput;
+    response: unknown;
   };
   WebFetch: {
-    input: {
-      /**
-       * @default 100
-       */
-      charThreshold?: number;
-      prompt: string;
-      url: string;
-    };
+    input: WebFetchInput;
     response: {
       bytes: number;
       code: number;
@@ -786,11 +724,12 @@ interface ToolSchema {
       url: string;
     };
   };
+  WebSearch: {
+    input: WebSearchInput;
+    response: unknown;
+  };
   Write: {
-    input: {
-      content: string;
-      file_path: string;
-    };
+    input: FileWriteInput;
     response: {
       content: string;
       filePath: string;

package/dist/index.mjs

@@ -28,20 +28,9 @@ function createContext(input) {
 		})
 	};
 }
-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))),
+	permission_mode: v.exactOptional(v.string()),
 	session_id: v.string(),
 	transcript_path: v.string()
 });
@@ -62,15 +51,23 @@ const HookInputSchemas = {
 		tool_input: v.unknown(),
 		tool_response: v.unknown()
 	}),
-	Notification: buildHookInputSchema("Notification", { message: v.optional(v.string()) }),
+	Notification: buildHookInputSchema("Notification", {
+		message: v.string(),
+		title: v.exactOptional(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()) }),
+	Stop: buildHookInputSchema("Stop", { stop_hook_active: v.boolean() }),
+	SubagentStop: buildHookInputSchema("SubagentStop", { stop_hook_active: v.boolean() }),
 	PreCompact: buildHookInputSchema("PreCompact", {
-		custom_instructions: v.string(),
+		custom_instructions: v.nullable(v.string()),
 		trigger: v.union([v.literal("manual"), v.literal("auto")])
 	}),
-	SessionStart: buildHookInputSchema("SessionStart", { source: v.string() }),
+	SessionStart: buildHookInputSchema("SessionStart", { source: v.union([
+		v.literal("startup"),
+		v.literal("resume"),
+		v.literal("clear"),
+		v.literal("compact")
+	]) }),
 	SessionEnd: buildHookInputSchema("SessionEnd", { reason: v.string() })
 };
 function isNonEmptyString(value) {
@@ -80,8 +77,7 @@ 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, {
+		if (!(typeof shouldRun === "function" ? await shouldRun() : shouldRun)) return handleHookResult(eventName, {
 			kind: "success",
 			payload: {}
 		});
@@ -89,8 +85,7 @@ async function runHook(def) {
 		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);
+		const result = await run(createContext(parsed));
 		handleHookResult(eventName, result);
 	} catch (error) {
 		handleHookResult(eventName, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-hooks-ts",
-  "version": "0.0.6",
+  "version": "0.1.0",
   "type": "module",
   "description": "Write claude code hooks with type safety",
   "sideEffects": false,
@@ -42,22 +42,24 @@
     }
   },
   "devDependencies": {
+    "@anthropic-ai/claude-code": "2.0.0",
     "@arethetypeswrong/core": "0.18.2",
-    "@biomejs/biome": "2.1.2",
-    "@types/node": "24.3.0",
-    "@virtual-live-lab/eslint-config": "2.2.24",
+    "@biomejs/biome": "2.3.4",
+    "@types/node": "24.10.0",
+    "@virtual-live-lab/eslint-config": "2.3.1",
     "@virtual-live-lab/tsconfig": "2.1.21",
-    "eslint": "9.31.0",
+    "eslint": "9.39.1",
     "eslint-plugin-import-access": "3.0.0",
-    "pkg-pr-new": "0.0.54",
-    "publint": "0.3.12",
-    "release-it": "19.0.4",
+    "pkg-pr-new": "0.0.60",
+    "publint": "0.3.15",
+    "release-it": "19.0.6",
     "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"
+    "tsdown": "0.16.0",
+    "type-fest": "5.2.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.46.3",
+    "unplugin-unused": "0.5.5",
+    "vitest": "4.0.7"
   },
   "dependencies": {
     "valibot": "^1.1.0"