cc-hooks-ts 2.0.42 → 2.0.43

package/README.md

@@ -14,43 +14,22 @@ npx nypm add cc-hooks-ts
 
 ## Basic Usage
 
-> [!NOTE]
-> We highly recommend using Bun or Deno for automatic dependency downloading at runtime.
->
-> - Bun: <https://bun.com/docs/runtime/autoimport>
-> - Deno: <https://docs.deno.com/runtime/fundamentals/modules/#managing-third-party-modules-and-libraries>
-
 ### Define a Hook
 
-With Bun:
-
-```typescript
-#!/usr/bin/env -S bun run --silent
-import { defineHook, runHook } from "cc-hooks-ts";
-
-// Session start hook
-const sessionHook = defineHook({
-  trigger: { SessionStart: true },
-  run: (context) => {
-    // do something great
-    return context.success({
-      messageForUser: "Welcome to your coding session!"
-    });
-  }
-});
-
-await runHook(sessionHook);
-```
-
-Or with Deno:
+Example of running a simple SessionStart hook on Bun:
 
 ```typescript
-#!/usr/bin/env -S deno run --quiet --allow-env --allow-read
-import { defineHook, runHook } from "npm:cc-hooks-ts";
+import { defineHook } from "cc-hooks-ts";
 
-// Session start hook
 const sessionHook = defineHook({
-  trigger: { SessionStart: true },
+  trigger: {
+    // Specify the hook event to listen for
+    SessionStart: true,
+    PreToolUse: {
+      // PreToolUser and PostToolUse can be tool-specific. (affects type of context)
+      Read: true
+    }
+  },
   run: (context) => {
     // do something great
     return context.success({
@@ -59,7 +38,11 @@ const sessionHook = defineHook({
   }
 });
 
-await runHook(sessionHook);
+// import.meta.main is available in Node.js 24.2+ and Bun and Deno
+if (import.meta.main) {
+  const { runHook } = await import("cc-hooks-ts");
+  await runHook(sessionHook);
+}
 ```
 
 ### Call from Claude Code
@@ -74,7 +57,7 @@ Then, load defined hooks in your Claude Code settings at `~/.claude/settings.jso
         "hooks": [
           {
             "type": "command",
-            "command": "$HOME/.claude/<name-of-your-hooks>.ts"
+            "command": "bun run --silent path/to/your/sessionHook.ts"
           }
         ]
       }
@@ -149,6 +132,7 @@ const multiEventHook = defineHook({
     PreToolUse: { Read: true, WebFetch: true },
     PostToolUse: { Read: true }
   },
+  // Optional: Define when the hook should run.
   shouldRun: () => process.env.NODE_ENV === 'development',
   run: (context) => {
     // Handle different events and tools based on context.input

package/dist/index.d.mts

@@ -1,164 +1,11 @@
 import * as v from "valibot";
 import { AgentInput, BashInput, BashOutputInput, ExitPlanModeInput, FileEditInput, FileReadInput, FileWriteInput, GlobInput, GrepInput, KillShellInput, ListMcpResourcesInput, NotebookEditInput, ReadMcpResourceInput, TodoWriteInput, WebFetchInput, WebSearchInput } from "@anthropic-ai/claude-agent-sdk/sdk-tools";
 
-//#region src/event.d.ts
-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}
- */
-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$1 extends SupportedHookEvent> = HookOutput extends Record<SupportedHookEvent, unknown> ? HookOutput[TEvent$1] : 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;
-  /**
-   * 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}
- */
-interface PreToolUseHookOutput extends CommonHookOutputs {
-  hookSpecificOutput?: {
-    hookEventName: "PreToolUse";
-    /**
-     * - `allow` bypasses the permission system. `permissionDecisionReason` is shown to the user but not to Claude.
-     * - `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;
-    updatedInput?: Record<string, unknown>;
-  };
-}
-/**
- * @see {@link https://docs.anthropic.com/en/docs/claude-code/hooks#posttooluse-decision-control}
- */
-interface PostToolUseHookOutput extends CommonHookOutputs {
-  /**
-   * - `approve` has no effect; the tool response is processed normally.
-   * - `block` automatically prompts Claude with `reason`.
-   */
-  decision?: "approve" | "block";
-  hookSpecificOutput?: {
-    hookEventName: "PostToolUse";
-    /**
-     * Adds context for Claude to consider.
-     */
-    additionalContext?: string;
-    updatedMCPToolOutput?: unknown;
-  };
-  reason?: string;
-}
-/**
- * @see {@link https://docs.anthropic.com/en/docs/claude-code/hooks#userpromptsubmit-decision-control}
- */
-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.
-   */
-  decision?: "approve" | "block";
-  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 {
-  /**
-   * - `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.
-   */
-  decision?: "approve" | "block";
-  /**
-   * 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 {
-  /**
-   * - `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.
-   */
-  /**
-   * Reason for the decision.
-   */
-  reason?: string;
-}
-interface SessionStartHookOutput extends CommonHookOutputs {
-  hookSpecificOutput?: {
-    hookEventName: "SessionStart";
-    /**
-     * Adds the string to the context.
-     */
-    additionalContext?: string;
-  };
-}
-//#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
+//#region src/hooks/input/schemas.d.ts
 /**
  * @package
  */
@@ -172,6 +19,7 @@ declare const HookInputSchemas: {
   } & {
     tool_name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TransformAction<string, AutoComplete<string>>]>;
     tool_input: v.UnknownSchema;
+    tool_use_id: v.StringSchema<undefined>;
   }, undefined>;
   readonly PostToolUse: v.ObjectSchema<{
     readonly cwd: v.StringSchema<undefined>;
@@ -183,6 +31,7 @@ declare const HookInputSchemas: {
     tool_name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TransformAction<string, AutoComplete<string>>]>;
     tool_input: v.UnknownSchema;
     tool_response: v.UnknownSchema;
+    tool_use_id: v.StringSchema<undefined>;
   }, undefined>;
   readonly Notification: v.ObjectSchema<{
     readonly cwd: v.StringSchema<undefined>;
@@ -213,6 +62,16 @@ declare const HookInputSchemas: {
   } & {
     stop_hook_active: v.BooleanSchema<undefined>;
   }, undefined>;
+  readonly SubagentStart: v.ObjectSchema<{
+    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>;
+  }, undefined>;
   readonly SubagentStop: v.ObjectSchema<{
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
@@ -254,7 +113,15 @@ declare const HookInputSchemas: {
   }, undefined>;
 };
 //#endregion
-//#region src/input/types.d.ts
+//#region src/hooks/event.d.ts
+/**
+ * @see {@link https://docs.anthropic.com/en/docs/claude-code/hooks#hook-events}
+ *
+ * @package
+ */
+type SupportedHookEvent = "PreToolUse" | "PostToolUse" | "Notification" | "UserPromptSubmit" | "SessionStart" | "SessionEnd" | "Stop" | "SubagentStop" | "PreCompact" | "SubagentStart";
+//#endregion
+//#region src/hooks/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.
@@ -266,7 +133,7 @@ declare const HookInputSchemas: {
  * ```
  * @package
  */
-type HookInputs = { [EventKey in SupportedHookEvent]: EventKey extends "PreToolUse" ? ToolSpecificPreToolUseInput & {
+type HookInput = { [EventKey in SupportedHookEvent]: EventKey extends "PreToolUse" ? ToolSpecificPreToolUseInput & {
   default: BaseHookInputs["PreToolUse"];
 } : EventKey extends "PostToolUse" ? ToolSpecificPostToolUseInput & {
   default: BaseHookInputs["PostToolUse"];
@@ -290,7 +157,7 @@ type HookInputs = { [EventKey in SupportedHookEvent]: EventKey extends "PreToolU
  * ```
  * @package
  */
-type ExtractAllHookInputsForEvent<TEvent$1 extends SupportedHookEvent> = { [K in keyof HookInputs[TEvent$1]]: HookInputs[TEvent$1][K] }[keyof HookInputs[TEvent$1]];
+type ExtractAllHookInputsForEvent<TEvent$1 extends SupportedHookEvent> = { [K in keyof HookInput[TEvent$1]]: HookInput[TEvent$1][K] }[keyof HookInput[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.
@@ -311,11 +178,11 @@ type ExtractAllHookInputsForEvent<TEvent$1 extends SupportedHookEvent> = { [K in
  * ```
  * @package
  */
-type ExtractSpecificHookInputForEvent<TEvent$1 extends SupportedHookEvent, TSpecificKey extends ExtractExtendedSpecificKeys<TEvent$1>> = TSpecificKey extends keyof HookInputs[TEvent$1] ? HookInputs[TEvent$1][TSpecificKey] : never;
+type ExtractSpecificHookInputForEvent<TEvent$1 extends SupportedHookEvent, TSpecificKey extends ExtractExtendedSpecificKeys<TEvent$1>> = TSpecificKey extends keyof HookInput[TEvent$1] ? HookInput[TEvent$1][TSpecificKey] : never;
 /**
  * @package
  */
-type ExtractExtendedSpecificKeys<TEvent$1 extends SupportedHookEvent> = Exclude<keyof HookInputs[TEvent$1], "default">;
+type ExtractExtendedSpecificKeys<TEvent$1 extends SupportedHookEvent> = Exclude<keyof HookInput[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"];
@@ -327,6 +194,168 @@ type ToolSpecificPostToolUseInput = { [K in keyof ToolSchema]: Omit<BaseHookInpu
   tool_response: ToolSchema[K]["response"];
 } };
 //#endregion
+//#region src/hooks/output/index.d.ts
+/**
+ * @package
+ */
+type HookOutput = {
+  PreToolUse: PreToolUseHookOutput;
+  PostToolUse: PostToolUseHookOutput;
+  UserPromptSubmit: UserPromptSubmitHookOutput;
+  Stop: StopHookOutput;
+  SubagentStart: SubagentStartHookOutput;
+  SubagentStop: SubagentStopHookOutput;
+  SessionStart: SessionStartHookOutput;
+  Notification: CommonHookOutputs;
+  PreCompact: CommonHookOutputs;
+  SessionEnd: CommonHookOutputs;
+};
+/**
+ * @package
+ */
+type ExtractHookOutput<TEvent$1 extends SupportedHookEvent> = HookOutput extends Record<SupportedHookEvent, unknown> ? HookOutput[TEvent$1] : 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;
+  /**
+   * 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}
+ */
+interface PreToolUseHookOutput extends CommonHookOutputs {
+  hookSpecificOutput?: {
+    hookEventName: "PreToolUse";
+    /**
+     * - `allow` bypasses the permission system. `permissionDecisionReason` is shown to the user but not to Claude.
+     * - `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;
+    updatedInput?: Record<string, unknown>;
+  };
+}
+/**
+ * @see {@link https://docs.anthropic.com/en/docs/claude-code/hooks#posttooluse-decision-control}
+ */
+interface PostToolUseHookOutput extends CommonHookOutputs {
+  /**
+   * - `approve` has no effect; the tool response is processed normally.
+   * - `block` automatically prompts Claude with `reason`.
+   */
+  decision?: "approve" | "block";
+  hookSpecificOutput?: {
+    hookEventName: "PostToolUse";
+    /**
+     * Adds context for Claude to consider.
+     */
+    additionalContext?: string;
+    updatedMCPToolOutput?: unknown;
+  };
+  reason?: string;
+}
+/**
+ * @see {@link https://docs.anthropic.com/en/docs/claude-code/hooks#userpromptsubmit-decision-control}
+ */
+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.
+   */
+  decision?: "approve" | "block";
+  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 {
+  /**
+   * - `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.
+   */
+  decision?: "approve" | "block";
+  /**
+   * Reason for the decision.
+   */
+  reason?: string;
+}
+interface SubagentStartHookOutput extends CommonHookOutputs {
+  hookSpecificOutput?: {
+    hookEventName: "SubagentStart";
+    /**
+     * Adds the string to the context.
+     */
+    additionalContext?: string;
+  };
+}
+/**
+ * @see {@link https://docs.anthropic.com/en/docs/claude-code/hooks#stop%2Fsubagentstop-decision-control}
+ */
+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.
+   */
+  /**
+   * Reason for the decision.
+   */
+  reason?: string;
+}
+interface SessionStartHookOutput extends CommonHookOutputs {
+  hookSpecificOutput?: {
+    hookEventName: "SessionStart";
+    /**
+     * Adds the string to the context.
+     */
+    additionalContext?: string;
+  };
+}
+//#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];

package/dist/index.mjs

@@ -44,12 +44,14 @@ function buildHookInputSchema(hook_event_name, entries) {
 const HookInputSchemas = {
 	PreToolUse: buildHookInputSchema("PreToolUse", {
 		tool_name: v.pipe(v.string(), v.transform((s) => s)),
-		tool_input: v.unknown()
+		tool_input: v.unknown(),
+		tool_use_id: v.string()
 	}),
 	PostToolUse: buildHookInputSchema("PostToolUse", {
 		tool_name: v.pipe(v.string(), v.transform((s) => s)),
 		tool_input: v.unknown(),
-		tool_response: v.unknown()
+		tool_response: v.unknown(),
+		tool_use_id: v.string()
 	}),
 	Notification: buildHookInputSchema("Notification", {
 		message: v.string(),
@@ -58,6 +60,10 @@ const HookInputSchemas = {
 	}),
 	UserPromptSubmit: buildHookInputSchema("UserPromptSubmit", { prompt: v.string() }),
 	Stop: buildHookInputSchema("Stop", { stop_hook_active: v.boolean() }),
+	SubagentStart: buildHookInputSchema("SubagentStart", {
+		agent_id: v.string(),
+		agent_type: v.string()
+	}),
 	SubagentStop: buildHookInputSchema("SubagentStop", {
 		agent_id: v.string(),
 		agent_transcript_path: v.string(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-hooks-ts",
-  "version": "2.0.42",
+  "version": "2.0.43",
   "type": "module",
   "description": "Write claude code hooks with type safety",
   "sideEffects": false,
@@ -43,32 +43,33 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.2",
-    "@biomejs/biome": "2.3.4",
-    "@types/node": "24.10.0",
+    "@biomejs/biome": "2.3.5",
+    "@types/node": "24.10.1",
     "@typescript/native-preview": "^7.0.0-dev.20251108.1",
     "@virtual-live-lab/eslint-config": "2.3.1",
     "@virtual-live-lab/tsconfig": "2.1.21",
     "eslint": "9.39.1",
-    "eslint-plugin-import-access": "3.0.0",
+    "eslint-plugin-import-access": "3.1.0",
     "pkg-pr-new": "0.0.60",
     "publint": "0.3.15",
     "release-it": "19.0.6",
     "release-it-pnpm": "4.6.6",
-    "tsdown": "0.16.0",
+    "tsdown": "0.16.4",
     "type-fest": "5.2.0",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.46.3",
-    "unplugin-unused": "0.5.5",
-    "vitest": "4.0.7"
+    "typescript-eslint": "8.46.4",
+    "unplugin-unused": "0.5.6",
+    "vitest": "4.0.9"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.1.42",
+    "@anthropic-ai/claude-agent-sdk": "0.1.43",
     "valibot": "^1.1.0"
   },
   "scripts": {
-    "lint": "eslint --max-warnings 0 --fix .",
-    "format": "biome format --write .",
-    "format:check": "biome format . --reporter=github",
+    "check": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run build",
+    "lint": "eslint --max-warnings 0",
+    "format": "biome format --write",
+    "format:check": "biome format --reporter=github",
     "typecheck": "tsgo --noEmit",
     "test": "vitest --run",
     "build": "tsdown",