cc-hooks-ts 0.0.5 → 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,7 +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/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}
  */
@@ -19,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
  *
@@ -49,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}
@@ -61,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;
   };
 }
 /**
@@ -70,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";
     /**
@@ -88,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";
     /**
@@ -108,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.
    */
@@ -123,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.
    */
@@ -143,10 +156,6 @@ interface SessionStartHookOutput extends CommonHookOutputs {
   };
 }
 //#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/input/schemas.d.ts
 /**
  * @package
@@ -155,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>;
   } & {
@@ -164,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>;
   } & {
@@ -174,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>;
   } & {
@@ -190,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>;
   } & {
@@ -266,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.
@@ -287,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"];
@@ -542,19 +561,182 @@ declare function runHook<THookTrigger extends HookTrigger = HookTrigger>(def: Ho
  * ```
  */
 interface ToolSchema {
-  Read: {
+  Bash: {
+    input: BashInput;
+    response: {
+      interrupted: boolean;
+      isImage: boolean;
+      stderr: string;
+      stdout: string;
+    };
+  };
+  Edit: {
+    input: FileEditInput;
+    response: {
+      filePath: string;
+      newString: string;
+      oldString: string;
+      originalFile: string;
+      replaceAll: boolean;
+      structuredPatch: Array<{
+        lines: string[];
+        newLines: number;
+        newStart: number;
+        oldLines: number;
+        oldStart: number;
+      }>;
+      userModified: boolean;
+    };
+  };
+  Glob: {
+    input: GlobInput;
+    response: {
+      durationMs: number;
+      filenames: string[];
+      numFiles: number;
+      truncated: boolean;
+    };
+  };
+  Grep: {
+    input: GrepInput;
+    response: {
+      content: string;
+      mode: "content" | "count" | "files_with_matches";
+      numFiles: number;
+      numLines: number;
+    };
+  };
+  LS: {
+    input: {
+      path: string;
+    };
+    response: string;
+  };
+  MultiEdit: {
     input: {
+      edits: Array<{
+        new_string: string;
+        old_string: string;
+        /**
+         * @default false
+         */
+        replace_all?: boolean;
+      }>;
       file_path: string;
     };
-    response: unknown;
+    response: {
+      edits: Array<{
+        new_string: string;
+        old_string: string;
+        /**
+         * @default false
+         */
+        replace_all?: boolean;
+      }>;
+      filePath: string;
+      originalFileContents: string;
+      structuredPatch: Array<{
+        lines: string[];
+        newLines: number;
+        newStart: number;
+        oldLines: number;
+        oldStart: number;
+      }>;
+      userModified: boolean;
+    };
   };
-  WebFetch: {
+  NotebookEdit: {
+    input: NotebookEditInput;
+    response: {
+      cell_type: "code" | "markdown";
+      edit_mode: "delete" | "insert" | "replace";
+      error: string;
+      language: string;
+      new_source: string;
+    };
+  };
+  Read: {
+    input: FileReadInput;
+    response: {
+      file: {
+        cells: Array<{
+          cell_id: string;
+          cellType: "code";
+          language: string;
+          source: string;
+        } | {
+          cell_id: string;
+          cellType: "markdown";
+          source: string;
+        }>;
+        filePath: string;
+      };
+      type: "notebook";
+    } | {
+      file: {
+        content: string;
+        filePath: string;
+        numLines: number;
+        startLine: number;
+        totalLines: number;
+      };
+      type: "text";
+    };
+  };
+  Task: {
     input: {
+      description: string;
       prompt: string;
+      subagent_type: AutoComplete<"general-purpose" | "output-style-setup" | "statusline-setup">;
+    };
+    response: {
+      content: Array<{
+        text: string;
+        type: "text";
+      }>;
+      totalDurationMs: number;
+      totalTokens: number;
+      totalToolUseCount: number;
+      usage: {
+        cache_creation: {
+          ephemeral_1h_input_tokens: number;
+          ephemeral_5m_input_tokens: number;
+        };
+        cache_creation_input_tokens: number;
+        cache_read_input_tokens: number;
+        input_tokens: number;
+        output_tokens: number;
+      };
+    };
+  };
+  TodoWrite: {
+    input: TodoWriteInput;
+    response: unknown;
+  };
+  WebFetch: {
+    input: WebFetchInput;
+    response: {
+      bytes: number;
+      code: number;
+      codeText: string;
+      durationMs: number;
+      result: string;
       url: string;
     };
+  };
+  WebSearch: {
+    input: WebSearchInput;
     response: unknown;
   };
+  Write: {
+    input: FileWriteInput;
+    response: {
+      content: string;
+      filePath: string;
+      structuredPatch: unknown[];
+      type: "create";
+    };
+  };
 }
 //#endregion
 export { type ExtractAllHookInputsForEvent, type ExtractSpecificHookInputForEvent, ToolSchema, defineHook, runHook };

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.5",
+  "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"