cc-hooks-ts 2.0.56 → 2.0.70

package/README.md

@@ -1,37 +1,68 @@
 # cc-hooks-ts
 
-Define Claude Code hooks with full type safety using TypeScript and Valibot validation.
+Define Claude Code hooks with full type safety using TypeScript.
+
+See [examples](./examples) for more usage examples.
+
+<!-- TOC -->
+
+- [cc-hooks-ts](#cc-hooks-ts)
+  - [Installation](#installation)
+  - [Basic Usage](#basic-usage)
+    - [Define a Hook](#define-a-hook)
+    - [Configure Claude Code](#configure-claude-code)
+  - [Tool Specific Hooks](#tool-specific-hooks)
+    - [Custom Tool Types Support](#custom-tool-types-support)
+  - [Advanced Usage](#advanced-usage)
+    - [Conditional Hook Execution](#conditional-hook-execution)
+    - [Advanced JSON Output](#advanced-json-output)
+  - [Documentation](#documentation)
+  - [Development](#development)
+    - [How to follow the upstream changes](#how-to-follow-the-upstream-changes)
+  - [License](#license)
+  - [Contributing](#contributing)
+
+<!-- /TOC -->
 
 > [!NOTE]
-> Beginning with versions equal to 2.0.0 or 2.0.42 and above, we started releasing using the same version numbers as Claude Code.
-> This enables us to support newer type definitions while preserving maximum compatibility.
+> Starting with versions 2.0.42, we will raise our version number to match Claude Code whenever Hook-related changes occur.
+>
+> This ensures we can adopt newer type definitions while maintaining compatibility.
 
 ## Installation
 
 ```bash
-npx nypm add cc-hooks-ts
+# npm
+npm i cc-hooks-ts
+
+# yarn
+yarn add cc-hooks-ts
+
+# pnpm
+pnpm add cc-hooks-ts
+
+# Bun
+bun add cc-hooks-ts
+
+# Deno
+deno add npm:cc-hooks-ts
 ```
 
 ## Basic Usage
 
 ### Define a Hook
 
-Example of running a simple SessionStart hook on Bun:
-
 ```typescript
 import { defineHook } from "cc-hooks-ts";
 
-const sessionHook = defineHook({
+const hook = defineHook({
+  // Specify the event(s) that trigger this hook.
   trigger: {
-    // Specify the hook event to listen for
-    SessionStart: true,
-    PreToolUse: {
-      // PreToolUser and PostToolUse can be tool-specific. (affects type of context)
-      Read: true
-    }
+    SessionStart: true
   },
+  // Implement what you want to do.
   run: (context) => {
-    // do something great
+    // Do something great here
     return context.success({
       messageForUser: "Welcome to your coding session!"
     });
@@ -41,11 +72,11 @@ const sessionHook = defineHook({
 // 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);
+  await runHook(hook);
 }
 ```
 
-### Call from Claude Code
+### Configure Claude Code
 
 Then, load defined hooks in your Claude Code settings at `~/.claude/settings.json`.
 
@@ -57,7 +88,7 @@ Then, load defined hooks in your Claude Code settings at `~/.claude/settings.jso
         "hooks": [
           {
             "type": "command",
-            "command": "bun run --silent path/to/your/sessionHook.ts"
+            "command": "bun run -i --silent path/to/your/sessionHook.ts"
           }
         ]
       }
@@ -66,111 +97,122 @@ Then, load defined hooks in your Claude Code settings at `~/.claude/settings.jso
 }
 ```
 
-## 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:
+## Tool Specific Hooks
 
-### Adding Custom Tool Definitions
+In `PreToolUse`, `PostToolUse`, and `PostToolUseFailure` events, you can define hooks specific to tools by specifying tool names in the trigger configuration.
 
-Extend the `ToolSchema` interface to add custom tool definitions:
+For example, you can create a hook that only runs before the `Read` tool is used:
 
 ```typescript
-// Use "npm:cc-hooks-ts" for Deno
-declare module "cc-hooks-ts" {
-  interface ToolSchema {
-    MyCustomTool: {
-      input: {
-        customParam: string;
-        optionalParam?: number;
-      };
-      response: {
-        result: string;
-      };
-    };
+const preReadHook = defineHook({
+  trigger: { PreToolUse: { Read: true } },
+  run: (context) => {
+    // context.input.tool_input is typed as { file_path: string; limit?: number; offset?: number; }
+    const { file_path } = context.input.tool_input;
+
+    if (file_path.includes('.env')) {
+      return context.blockingError('Cannot read environment files');
+    }
+
+    return context.success();
   }
+});
+
+if (import.meta.main) {
+  const { runHook } = await import("cc-hooks-ts");
+  await runHook(preReadHook);
 }
 ```
 
-Now you can use your custom tool with full type safety:
+Then configure it in Claude Code settings:
 
-```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();
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run -i --silent path/to/your/preReadHook.ts"
+          }
+        ]
+      }
+    ]
   }
-});
+}
 ```
 
-## API Reference
+### Custom Tool Types Support
 
-### defineHook Function
+You can add support for custom tools by extending the tool type definitions.
 
-Creates type-safe hook definitions with full TypeScript inference:
+This is useful when you want to your MCP-defined tools to have type-safe hook inputs.
 
 ```typescript
-// Tool-specific PreToolUse hook
-const readHook = defineHook({
-  trigger: { PreToolUse: { Read: true } },
+import { defineHook } from "cc-hooks-ts";
+
+// Example: type-safe hooks for DeepWiki MCP Server tools
+declare module "cc-hooks-ts" {
+  interface ToolSchema {
+    mcp__deepwiki__ask_question: {
+      input: {
+        question: string;
+        repoName: string;
+      };
+      response: unknown;
+    };
+  }
+}
+
+const deepWikiHook = defineHook({
+  trigger: { PreToolUse: { mcp__deepwiki__ask_question: true } },
   run: (context) => {
-    // context.input.tool_input is typed as { file_path: string }
-    const { file_path } = context.input.tool_input;
+    // context.input.tool_input is typed as { question: string; repoName: string; }
+    const { question, repoName } = context.input.tool_input;
 
-    if (file_path.includes('.env')) {
-      return context.blockingError('Cannot read environment files');
+    if (question.length > 500) {
+      return context.blockingError('Question is too long');
     }
 
     return context.success();
   }
 });
+```
+
+## Advanced Usage
+
+### Conditional Hook Execution
 
-// Multiple event triggers
-const multiEventHook = defineHook({
+You can conditionally execute hooks based on runtime logic using the `shouldRun` function.
+If `shouldRun` returns `false`, the hook will be skipped.
+
+```ts
+import { defineHook } from "cc-hooks-ts";
+
+const hook = defineHook({
   trigger: {
-    PreToolUse: { Read: true, WebFetch: true },
-    PostToolUse: { Read: true }
+    Notification: true
   },
-  // Optional: Define when the hook should run.
-  shouldRun: () => process.env.NODE_ENV === 'development',
+  // Only run this hook on macOS
+  shouldRun: () => process.platform === "darwin",
   run: (context) => {
-    // Handle different events and tools based on context.input
-    return context.success();
+    // Some macOS-specific logic like sending a notification using AppleScript
+    return context.success()
   }
 });
 ```
 
-### runHook Function
-
-Executes hooks with complete lifecycle management:
+### Advanced JSON Output
 
-- Reads input from stdin
-- Validates input using Valibot schemas
-- Creates typed context
-- Executes hook handler
-- Formats and outputs results
+Use `context.json()` to return structured JSON output with advanced control over hook behavior.
 
-```typescript
-await runHook(hook);
-```
-
-### Hook Context
+For detailed information about available JSON fields and their behavior, see the [official documentation](https://docs.anthropic.com/en/docs/claude-code/hooks#advanced:-json-output).
 
-The context provides strongly typed input access and response helpers:
+## Documentation
 
-```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: {...} });
-}
-```
+For more detailed information about Claude Code hooks, visit the [official documentation](https://docs.anthropic.com/en/docs/claude-code/hooks).
 
 ## Development
 
@@ -191,9 +233,28 @@ pnpm format
 pnpm typecheck
 ```
 
-## Documentation
+### How to follow the upstream changes
 
-For more detailed information about Claude Code hooks, visit the [official documentation](https://docs.anthropic.com/en/docs/claude-code/hooks).
+1. Install the latest version of `@anthropic-ai/claude-agent-sdk` and run `pnpm run check`.
+   - If the command passes without errors, there are no type changes.
+
+2. Get diff of the types. This example gets the diff between Claude Code 2.0.69 and 2.0.70:
+
+   ```bash
+   npm diff --diff=@anthropic-ai/claude-agent-sdk@0.1.69 --diff=@anthropic-ai/claude-agent-sdk@0.1.70 '**/*.d.ts'
+
+   # You can use dandavison/delta for better diff visualization
+   npm diff --diff=@anthropic-ai/claude-agent-sdk@0.1.69 --diff=@anthropic-ai/claude-agent-sdk@0.1.70 '**/*.d.ts' | delta --side-by-side
+   ```
+
+3. Reflect the changes.
+   - Edit `src/hooks/` for changed hook input / output types.
+     - No need for adding tests in most cases since we are testing the whole type definitions in these files:
+       - `src/hooks/input/schemas.test-d.ts`
+       - `src/hooks/output/index.test-d.ts`
+       - `src/hooks/event.test-d.ts`
+       - `src/hooks/permission.test-d.ts`
+   - Edit `src/index.ts` for changed tool input / output types.
 
 ## License
 

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 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";
+import { AgentInput, BashInput, ExitPlanModeInput, FileEditInput, FileReadInput, FileWriteInput, GlobInput, GrepInput, KillShellInput, ListMcpResourcesInput, NotebookEditInput, ReadMcpResourceInput, TaskOutputInput, TodoWriteInput, WebFetchInput, WebSearchInput } from "@anthropic-ai/claude-agent-sdk/sdk-tools";
 
 //#region src/utils/types.d.ts
 type Awaitable<T> = Promise<T> | T;
@@ -157,7 +157,7 @@ declare const HookInputSchemas: {
       readonly type: v.LiteralSchema<"removeRules", undefined>;
     }, undefined>, v.ObjectSchema<{
       readonly destination: v.UnionSchema<[v.LiteralSchema<"userSettings", undefined>, v.LiteralSchema<"projectSettings", undefined>, v.LiteralSchema<"localSettings", undefined>, v.LiteralSchema<"session", undefined>, v.LiteralSchema<"cliArg", undefined>], undefined>;
-      readonly mode: v.UnionSchema<[v.LiteralSchema<"acceptEdits", undefined>, v.LiteralSchema<"bypassPermissions", undefined>, v.LiteralSchema<"default", undefined>, v.LiteralSchema<"dontAsk", undefined>, v.LiteralSchema<"plan", undefined>], undefined>;
+      readonly mode: v.UnionSchema<[v.LiteralSchema<"acceptEdits", undefined>, v.LiteralSchema<"bypassPermissions", undefined>, v.LiteralSchema<"default", undefined>, v.LiteralSchema<"dontAsk", undefined>, v.LiteralSchema<"delegate", undefined>, v.LiteralSchema<"plan", undefined>], undefined>;
       readonly type: v.LiteralSchema<"setMode", undefined>;
     }, undefined>, v.ObjectSchema<{
       readonly destination: v.UnionSchema<[v.LiteralSchema<"userSettings", undefined>, v.LiteralSchema<"projectSettings", undefined>, v.LiteralSchema<"localSettings", undefined>, v.LiteralSchema<"session", undefined>, v.LiteralSchema<"cliArg", undefined>], undefined>;
@@ -290,7 +290,7 @@ declare const permissionUpdateSchema: v.VariantSchema<"type", [v.ObjectSchema<{
   readonly type: v.LiteralSchema<"removeRules", undefined>;
 }, undefined>, v.ObjectSchema<{
   readonly destination: v.UnionSchema<[v.LiteralSchema<"userSettings", undefined>, v.LiteralSchema<"projectSettings", undefined>, v.LiteralSchema<"localSettings", undefined>, v.LiteralSchema<"session", undefined>, v.LiteralSchema<"cliArg", undefined>], undefined>;
-  readonly mode: v.UnionSchema<[v.LiteralSchema<"acceptEdits", undefined>, v.LiteralSchema<"bypassPermissions", undefined>, v.LiteralSchema<"default", undefined>, v.LiteralSchema<"dontAsk", undefined>, v.LiteralSchema<"plan", undefined>], undefined>;
+  readonly mode: v.UnionSchema<[v.LiteralSchema<"acceptEdits", undefined>, v.LiteralSchema<"bypassPermissions", undefined>, v.LiteralSchema<"default", undefined>, v.LiteralSchema<"dontAsk", undefined>, v.LiteralSchema<"delegate", undefined>, v.LiteralSchema<"plan", undefined>], undefined>;
   readonly type: v.LiteralSchema<"setMode", undefined>;
 }, undefined>, v.ObjectSchema<{
   readonly destination: v.UnionSchema<[v.LiteralSchema<"userSettings", undefined>, v.LiteralSchema<"projectSettings", undefined>, v.LiteralSchema<"localSettings", undefined>, v.LiteralSchema<"session", undefined>, v.LiteralSchema<"cliArg", undefined>], undefined>;
@@ -747,7 +747,7 @@ interface ToolSchema {
     };
   };
   BashOutput: {
-    input: BashOutputInput;
+    input: TaskOutputInput;
     response: unknown;
   };
   Edit: {

package/dist/index.mjs

@@ -70,6 +70,7 @@ const permissionUpdateSchema = v.variant("type", [
 			v.literal("bypassPermissions"),
 			v.literal("default"),
 			v.literal("dontAsk"),
+			v.literal("delegate"),
 			v.literal("plan")
 		]),
 		type: v.literal("setMode")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-hooks-ts",
-  "version": "2.0.56",
+  "version": "2.0.70",
   "type": "module",
   "description": "Write claude code hooks with type safety",
   "sideEffects": false,
@@ -43,33 +43,33 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.2",
-    "@biomejs/biome": "2.3.8",
-    "@types/node": "24.10.1",
+    "@types/node": "25.0.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": "9.39.2",
     "eslint-plugin-import-access": "3.1.0",
-    "pkg-pr-new": "0.0.60",
-    "publint": "0.3.15",
-    "release-it": "19.0.6",
+    "oxfmt": "0.17.0",
+    "pkg-pr-new": "0.0.62",
+    "publint": "0.3.16",
+    "release-it": "19.1.0",
     "release-it-pnpm": "4.6.6",
-    "tsdown": "0.16.8",
-    "type-fest": "5.2.0",
+    "tsdown": "0.17.2",
+    "type-fest": "5.3.1",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.48.0",
+    "typescript-eslint": "8.49.0",
     "unplugin-unused": "0.5.6",
-    "vitest": "4.0.14"
+    "vitest": "4.0.15"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.1.56",
+    "@anthropic-ai/claude-agent-sdk": "0.1.70",
     "valibot": "^1.1.0"
   },
   "scripts": {
     "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",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
     "typecheck": "tsgo --noEmit",
     "test": "vitest --run",
     "build": "tsdown",