cc-hooks-ts 2.0.70 → 2.0.76

package/README.md

@@ -16,6 +16,7 @@ See [examples](./examples) for more usage examples.
   - [Advanced Usage](#advanced-usage)
     - [Conditional Hook Execution](#conditional-hook-execution)
     - [Advanced JSON Output](#advanced-json-output)
+    - [Async JSON Output (Experimental)](#async-json-output-experimental)
   - [Documentation](#documentation)
   - [Development](#development)
     - [How to follow the upstream changes](#how-to-follow-the-upstream-changes)
@@ -210,6 +211,45 @@ Use `context.json()` to return structured JSON output with advanced control over
 
 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).
 
+### Async JSON Output (Experimental)
+
+> [!WARNING]
+> This behavior is undocumented by Anthropic and may change.
+
+> [!CAUTION]
+> You must enable verbose output if you want to see async hook outputs like `systemMessage` or `hookSpecificOutput.additionalContext`.
+>
+> You can enable it in Claude Code by going to `/config` and setting "verbose" to true.
+
+Claude Code also accepts async hook responses.
+
+Use `context.defer()` when you need extra time to compute hook output.
+
+```ts
+import { defineHook } from "cc-hooks-ts";
+
+const hook = defineHook({
+  trigger: { PostToolUse: { Read: true } },
+  run: (context) =>
+    context.defer(
+      async () => {
+        // Simulate long-running computation
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+
+        return {
+          event: "PostToolUse",
+          output: {
+            systemMessage: "Read tool used successfully after async processing!"
+          }
+        };
+      },
+      {
+        timeoutMs: 5000 // Optional timeout for the async operation.
+      }
+    )
+});
+```
+
 ## Documentation
 
 For more detailed information about Claude Code hooks, visit the [official documentation](https://docs.anthropic.com/en/docs/claude-code/hooks).
@@ -243,7 +283,7 @@ pnpm typecheck
    ```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
+   # Only for humans, 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
    ```
 

package/dist/index.d.mts

@@ -324,7 +324,28 @@ type HookOutput = {
 /**
  * @package
  */
-type ExtractHookOutput<TEvent$1 extends SupportedHookEvent> = HookOutput extends Record<SupportedHookEvent, unknown> ? HookOutput[TEvent$1] : never;
+type ExtractSyncHookOutput<TEvent$1 extends SupportedHookEvent> = HookOutput extends Record<SupportedHookEvent, unknown> ? HookOutput[TEvent$1] : never;
+/**
+ * @package
+ */
+type ExtractAsyncHookOutput<TEvent$1 extends SupportedHookEvent> = _InternalExtractAsyncHookOutput<ExtractSyncHookOutput<TEvent$1>>;
+/**
+ * Compute ExtractSyncHookOutput<TEvent> only once for better performance.
+ *
+ * Only `systemMessage` and `hookSpecificOutput.additionalContext` are read by Claude Code if we are using async hook.
+ * (This feature is not documented)
+ *
+ * @internal
+ */
+type _InternalExtractAsyncHookOutput<Output extends CommonHookOutputs> = Output extends {
+  hookSpecificOutput?: {
+    additionalContext?: infer TAdditionalContext;
+  };
+} ? Pick<Output, "systemMessage"> & {
+  hookSpecificOutput?: {
+    additionalContext?: TAdditionalContext;
+  };
+} : Pick<Output, "systemMessage">;
 /**
  * Common fields of hook outputs
  *
@@ -507,28 +528,142 @@ interface HookContext<THookTrigger extends HookTrigger> {
   /**
    * Cause a blocking error.
    *
-   * @param error `error` is fed back to Claude to process automatically
+   * When called, Claude Code stops processing and reports the error to Claude.
+   * The hook exits with code 2, and the error message is fed back to Claude for automatic processing.
+   *
+   * @example
+   * // Block access to sensitive files
+   * const hook = defineHook({
+   *   trigger: { PreToolUse: { Read: true } },
+   *   run: (context) => {
+   *     const { file_path } = context.input.tool_input;
+   *
+   *     if (file_path.includes('.env') || file_path.includes('secrets')) {
+   *       return context.blockingError('Access to sensitive files is not allowed');
+   *     }
+   *
+   *     return context.success();
+   *   }
+   * });
    */
   blockingError: (error: string) => HookResponseBlockingError;
+  /**
+   * Defer processing and produce JSON output after long-running computation.
+   *
+   * @experimental This behavior is undocumented by Anthropic and may change in future versions
+   *
+   * @example
+   * // Compute analysis with timeout protection
+   * const hook = defineHook({
+   *   trigger: { PostToolUse: { Grep: true } },
+   *   run: (context) => {
+   *    return context.defer(
+   *      async () => {
+   *        const analysis = await analyzeGrepResults(context.input.tool_response);
+   *
+   *        return {
+   *          event: "PostToolUse",
+   *          output: {
+   *            systemMessage: `Found ${analysis.matchCount} matches`,
+   *            hookSpecificOutput: {
+   *              additionalContext: analysis.summary
+   *            }
+   *          }
+   *        };
+   *      },
+   *      { timeoutMs: 5000 } // Fail fast if analysis takes too long
+   *    );
+   *   }
+   * });
+   */
+  defer: (handler: () => Awaitable<AsyncHookResultJSON<THookTrigger>>, options?: {
+    /**
+     * Optional timeout in milliseconds.
+     *
+     * Claude Code has its own internal timeouts; this setting allows you to specify a shorter timeout
+     * and cc-hooks-ts will abort the operation as circuit breaker.
+     *
+     * @default
+     * Claude Code has its own internal timeouts.
+     */
+    timeoutMs?: number | undefined;
+  }) => HookResponseAsyncJSON<THookTrigger>;
   input: ExtractTriggeredHookInput<THookTrigger>;
   /**
    * Direct access to advanced JSON output.
    *
+   * Provides fine-grained control over hook behavior through structured JSON output.
+   * This is the most powerful way to control Claude Code's behavior, including
+   * permission decisions, input modifications, and additional context.
+   *
    * @see {@link https://docs.anthropic.com/en/docs/claude-code/hooks#advanced%3A-json-output}
+   *
+   * @example
+   * // PreToolUse: Deny access with reason
+   * const hook = defineHook({
+   *   trigger: { PreToolUse: { Read: true } },
+   *   run: (context) => {
+   *     const { file_path } = context.input.tool_input;
+   *
+   *     if (file_path.includes('.env')) {
+   *       return context.json({
+   *         event: "PreToolUse",
+   *         output: {
+   *           hookSpecificOutput: {
+   *             permissionDecision: "deny",
+   *             permissionDecisionReason: "Access to .env files is restricted for security."
+   *           }
+   *         }
+   *       });
+   *     }
+   *
+   *     return context.success();
+   *   }
+   * });
    */
-  json: (payload: HookResultJSON<THookTrigger>) => HookResponseJSON<THookTrigger>;
+  json: (payload: SyncHookResultJSON<THookTrigger>) => HookResponseSyncJSON<THookTrigger>;
   /**
    * Cause a non-blocking error.
    *
-   * @param message `message` is shown to the user and execution continues.
+   * The message is shown to the user and execution continues.
+   *
+   * The hook exits with code 1, but Claude Code proceeds with normal operation.
+   *
+   * @example
+   * // Optional notification without message
+   * const hook = defineHook({
+   *   trigger: { Notification: true },
+   *   run: (context) => {
+   *     try {
+   *       // Attempt to send notification
+   *       sendNotification(context.input.message);
+   *       return context.success();
+   *     } catch (error) {
+   *       // Fail silently - notification is optional
+   *       return context.nonBlockingError();
+   *     }
+   *   }
+   * });
    */
   nonBlockingError: (message?: string) => HookResponseNonBlockingError;
   /**
    * Indicate successful handling of the hook.
+   *
+   * The hook exits with code 0. Optionally provides a message for the user or additional context for Claude.
+   *
+   * @example
+   * // Basic success without payload
+   * const hook = defineHook({
+   *   trigger: { PreToolUse: { Read: true } },
+   *   run: (context) => {
+   *     // Validation passed
+   *     return context.success();
+   *   }
+   * });
    */
   success: (payload?: HookSuccessPayload) => HookResponseSuccess;
 }
-type HookResponse<THookTrigger extends HookTrigger> = HookResponseBlockingError | HookResponseJSON<THookTrigger> | HookResponseNonBlockingError | HookResponseSuccess;
+type HookResponse<THookTrigger extends HookTrigger> = HookResponseBlockingError | HookResponseSyncJSON<THookTrigger> | HookResponseAsyncJSON<THookTrigger> | HookResponseNonBlockingError | HookResponseSuccess;
 type HookResponseNonBlockingError = {
   kind: "non-blocking-error";
   payload?: string;
@@ -553,11 +688,28 @@ type HookSuccessPayload = {
    */
   additionalClaudeContext?: string | undefined;
 };
-type HookResponseJSON<TTrigger extends HookTrigger> = {
-  kind: "json";
-  payload: HookResultJSON<TTrigger>;
+type HookResponseSyncJSON<TTrigger extends HookTrigger> = {
+  kind: "json-sync";
+  payload: SyncHookResultJSON<TTrigger>;
 };
-type HookResultJSON<TTrigger extends HookTrigger> = { [EventKey in keyof TTrigger]: EventKey extends SupportedHookEvent ? TTrigger[EventKey] extends true | Record<PropertyKey, true> ? {
+type HookResponseAsyncJSON<TTrigger extends HookTrigger> = {
+  kind: "json-async";
+  timeoutMs?: number | undefined;
+  run: () => Awaitable<AsyncHookResultJSON<TTrigger>>;
+};
+type SyncHookResultJSON<TTrigger extends HookTrigger> = { [EventKey in keyof TTrigger]: EventKey extends SupportedHookEvent ? TTrigger[EventKey] extends true | Record<PropertyKey, true> ? {
+  /**
+   * The name of the event being triggered.
+   *
+   * Required for proper TypeScript inference.
+   */
+  event: EventKey;
+  /**
+   * The output data for the event.
+   */
+  output: ExtractSyncHookOutput<EventKey>;
+} : never : never }[keyof TTrigger];
+type AsyncHookResultJSON<TTrigger extends HookTrigger> = { [EventKey in keyof TTrigger]: EventKey extends SupportedHookEvent ? TTrigger[EventKey] extends true | Record<PropertyKey, true> ? {
   /**
    * The name of the event being triggered.
    *
@@ -567,7 +719,7 @@ type HookResultJSON<TTrigger extends HookTrigger> = { [EventKey in keyof TTrigge
   /**
    * The output data for the event.
    */
-  output: ExtractHookOutput<EventKey>;
+  output: ExtractAsyncHookOutput<EventKey>;
 } : never : never }[keyof TTrigger];
 //#endregion
 //#region src/define.d.ts

package/dist/index.mjs

@@ -6,6 +6,11 @@ function defineHook(definition) {
 }
 function createContext(input) {
 	return {
+		defer: (handler, options) => ({
+			kind: "json-async",
+			run: handler,
+			timeoutMs: options?.timeoutMs
+		}),
 		blockingError: (error) => ({
 			kind: "blocking-error",
 			payload: error
@@ -23,7 +28,7 @@ function createContext(input) {
 			}
 		}),
 		json: (payload) => ({
-			kind: "json",
+			kind: "json-sync",
 			payload
 		})
 	};
@@ -167,32 +172,66 @@ async function runHook(def) {
 		const parsed = v.parse(inputSchema, JSON.parse(rawInput));
 		eventName = parsed.hook_event_name;
 		const result = await run(createContext(parsed));
-		handleHookResult(eventName, result);
+		await handleHookResult(eventName, result);
 	} catch (error) {
-		handleHookResult(eventName, {
+		await handleHookResult(eventName, {
 			kind: "non-blocking-error",
 			payload: `Error in hook: ${error instanceof Error ? error.message : String(error)}`
 		});
 	}
 }
-function handleHookResult(eventName, hookResult) {
+async function handleHookResult(eventName, hookResult) {
 	switch (hookResult.kind) {
-		case "success":
-			if (eventName === "UserPromptSubmit" || eventName === "SessionStart") {
-				if (isNonEmptyString(hookResult.payload.additionalClaudeContext)) console.log(hookResult.payload.additionalClaudeContext);
-				return process.exit(0);
-			}
-			if (isNonEmptyString(hookResult.payload.messageForUser)) console.log(hookResult.payload.messageForUser);
-			return process.exit(0);
 		case "blocking-error":
 			if (hookResult.payload) console.error(hookResult.payload);
 			return process.exit(2);
+		case "json-async": {
+			const userTimeout = hookResult.timeoutMs;
+			const startAsync = {
+				async: true,
+				asyncTimeout: userTimeout ?? void 0
+			};
+			console.log(JSON.stringify(startAsync));
+			const safeInvokeDeferredHook = async () => {
+				try {
+					return {
+						isError: false,
+						payload: await hookResult.run()
+					};
+				} catch (error) {
+					return {
+						isError: true,
+						reason: error instanceof Error ? error.message : String(error)
+					};
+				}
+			};
+			let deferredResult;
+			if (userTimeout == null) deferredResult = await safeInvokeDeferredHook();
+			else deferredResult = await Promise.race([safeInvokeDeferredHook(), new Promise((resolve) => setTimeout(() => resolve({
+				isError: true,
+				reason: `Exceeded user specified timeout: ${userTimeout}ms`
+			}), userTimeout + 5e3))]);
+			if (deferredResult.isError) {
+				if (isNonEmptyString(deferredResult.reason)) console.error(`Async hook execution failed: ${deferredResult.reason}`);
+				return process.exit(1);
+			}
+			console.log(JSON.stringify(deferredResult.payload.output));
+			return process.exit(0);
+		}
+		case "json-sync":
+			console.log(JSON.stringify(hookResult.payload.output));
+			return process.exit(0);
 		case "non-blocking-error":
 			if (isNonEmptyString(hookResult.payload)) console.error(hookResult.payload);
 			return process.exit(1);
-		case "json":
-			console.log(JSON.stringify(hookResult.payload.output));
+		case "success":
+			if (eventName === "UserPromptSubmit" || eventName === "SessionStart") {
+				if (isNonEmptyString(hookResult.payload.additionalClaudeContext)) console.log(hookResult.payload.additionalClaudeContext);
+				return process.exit(0);
+			}
+			if (isNonEmptyString(hookResult.payload.messageForUser)) console.log(hookResult.payload.messageForUser);
 			return process.exit(0);
+		default: throw new Error(`Unknown hook result kind: ${JSON.stringify(hookResult)}`);
 	}
 }
 function extractInputSchemaFromTrigger(trigger) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-hooks-ts",
-  "version": "2.0.70",
+  "version": "2.0.76",
   "type": "module",
   "description": "Write claude code hooks with type safety",
   "sideEffects": false,
@@ -43,26 +43,26 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.2",
-    "@types/node": "25.0.1",
+    "@types/node": "25.0.3",
     "@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.2",
     "eslint-plugin-import-access": "3.1.0",
-    "oxfmt": "0.17.0",
+    "oxfmt": "0.19.0",
     "pkg-pr-new": "0.0.62",
     "publint": "0.3.16",
     "release-it": "19.1.0",
     "release-it-pnpm": "4.6.6",
-    "tsdown": "0.17.2",
+    "tsdown": "0.18.1",
     "type-fest": "5.3.1",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.49.0",
+    "typescript-eslint": "8.50.0",
     "unplugin-unused": "0.5.6",
-    "vitest": "4.0.15"
+    "vitest": "4.0.16"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.1.70",
+    "@anthropic-ai/claude-agent-sdk": "0.1.76",
     "valibot": "^1.1.0"
   },
   "scripts": {