cc-hooks-ts 2.0.55 → 2.0.65

package/README.md

@@ -1,37 +1,67 @@
 # 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)
+  - [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 +71,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 +87,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 +96,122 @@ Then, load defined hooks in your Claude Code settings at `~/.claude/settings.jso
 }
 ```
 
-## Custom Tool Type Support
+## Tool Specific Hooks
 
-For better type inference in PreToolUse and PostToolUse hooks, you can extend the `ToolSchema` interface to define your own tool types:
+In `PreToolUse`, `PostToolUse`, and `PostToolUseFailure` events, you can define hooks specific to tools by specifying tool names in the trigger configuration.
 
-### Adding Custom Tool Definitions
-
-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
+
+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";
 
-// Multiple event triggers
-const multiEventHook = defineHook({
+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
-
-```typescript
-await runHook(hook);
-```
+Use `context.json()` to return structured JSON output with advanced control over hook behavior.
 
-### 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,10 +232,6 @@ pnpm format
 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

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;
@@ -33,6 +33,19 @@ declare const HookInputSchemas: {
     tool_response: v.UnknownSchema;
     tool_use_id: v.StringSchema<undefined>;
   }, undefined>;
+  readonly PostToolUseFailure: 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<"PostToolUseFailure", undefined>;
+  } & {
+    tool_name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TransformAction<string, AutoComplete<string>>]>;
+    error: v.StringSchema<undefined>;
+    is_interrupt: v.ExactOptionalSchema<v.BooleanSchema<undefined>, undefined>;
+    tool_input: v.UnknownSchema;
+    tool_use_id: v.StringSchema<undefined>;
+  }, undefined>;
   readonly Notification: v.ObjectSchema<{
     readonly cwd: v.StringSchema<undefined>;
     readonly permission_mode: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
@@ -166,7 +179,7 @@ declare const HookInputSchemas: {
  *
  * @package
  */
-type SupportedHookEvent = "PreToolUse" | "PostToolUse" | "Notification" | "UserPromptSubmit" | "SessionStart" | "SessionEnd" | "Stop" | "SubagentStart" | "SubagentStop" | "PreCompact" | "PermissionRequest";
+type SupportedHookEvent = "PreToolUse" | "PostToolUse" | "PostToolUseFailure" | "Notification" | "UserPromptSubmit" | "SessionStart" | "SessionEnd" | "Stop" | "SubagentStart" | "SubagentStop" | "PreCompact" | "PermissionRequest";
 //#endregion
 //#region src/hooks/input/types.d.ts
 /**
@@ -184,6 +197,8 @@ type HookInput = { [EventKey in SupportedHookEvent]: EventKey extends "PreToolUs
   default: BaseHookInputs["PreToolUse"];
 } : EventKey extends "PostToolUse" ? ToolSpecificPostToolUseInput & {
   default: BaseHookInputs["PostToolUse"];
+} : EventKey extends "PostToolUseFailure" ? ToolSpecificPostToolUseFailureInput & {
+  default: BaseHookInputs["PostToolUseFailure"];
 } : {
   default: BaseHookInputs[EventKey];
 } };
@@ -240,6 +255,10 @@ type ToolSpecificPostToolUseInput = { [K in keyof ToolSchema]: Omit<BaseHookInpu
   tool_name: K;
   tool_response: ToolSchema[K]["response"];
 } };
+type ToolSpecificPostToolUseFailureInput = { [K in keyof ToolSchema]: Omit<BaseHookInputs["PostToolUseFailure"], "tool_input" | "tool_name"> & {
+  tool_input: ToolSchema[K]["input"];
+  tool_name: K;
+} };
 //#endregion
 //#region src/hooks/permission.d.ts
 /**
@@ -291,6 +310,7 @@ type PermissionUpdate = v.InferOutput<typeof permissionUpdateSchema>;
 type HookOutput = {
   PreToolUse: PreToolUseHookOutput;
   PostToolUse: PostToolUseHookOutput;
+  PostToolUseFailure: PostToolUseFailureHookOutput;
   UserPromptSubmit: UserPromptSubmitHookOutput;
   Stop: StopHookOutput;
   SubagentStart: SubagentStartHookOutput;
@@ -382,6 +402,15 @@ interface PostToolUseHookOutput extends CommonHookOutputs {
   };
   reason?: string;
 }
+interface PostToolUseFailureHookOutput extends CommonHookOutputs {
+  hookSpecificOutput?: {
+    hookEventName: "PostToolUseFailure";
+    /**
+     * Adds context for Claude to consider.
+     */
+    additionalContext?: string;
+  };
+}
 /**
  * @see {@link https://docs.anthropic.com/en/docs/claude-code/hooks#userpromptsubmit-decision-control}
  */
@@ -718,7 +747,7 @@ interface ToolSchema {
     };
   };
   BashOutput: {
-    input: BashOutputInput;
+    input: TaskOutputInput;
     response: unknown;
   };
   Edit: {

package/dist/index.mjs

@@ -110,6 +110,13 @@ const HookInputSchemas = {
 		tool_response: v.unknown(),
 		tool_use_id: v.string()
 	}),
+	PostToolUseFailure: buildHookInputSchema("PostToolUseFailure", {
+		tool_name: v.pipe(v.string(), v.transform((s) => s)),
+		error: v.string(),
+		is_interrupt: v.exactOptional(v.boolean()),
+		tool_input: v.unknown(),
+		tool_use_id: v.string()
+	}),
 	Notification: buildHookInputSchema("Notification", {
 		message: v.string(),
 		notification_type: v.string(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-hooks-ts",
-  "version": "2.0.55",
+  "version": "2.0.65",
   "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.7",
     "@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.1.0",
-    "pkg-pr-new": "0.0.60",
+    "oxfmt": "0.16.0",
+    "pkg-pr-new": "0.0.62",
     "publint": "0.3.15",
     "release-it": "19.0.6",
     "release-it-pnpm": "4.6.6",
-    "tsdown": "0.16.6",
-    "type-fest": "5.2.0",
+    "tsdown": "0.17.0",
+    "type-fest": "5.3.1",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.47.0",
+    "typescript-eslint": "8.48.1",
     "unplugin-unused": "0.5.6",
-    "vitest": "4.0.13"
+    "vitest": "4.0.15"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.1.55",
+    "@anthropic-ai/claude-agent-sdk": "0.1.65",
     "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",