@goodfoot/claude-code-hooks 1.0.21 → 1.1.0

package/dist/cli.js

@@ -416,6 +416,17 @@ execute(hook);
         sourcefile: `${baseName}-entry.ts`,
         loader: "ts",
     };
+    // Banner to polyfill CJS globals for dependencies bundled into ESM.
+    // Some packages (e.g. typescript) use require(), __filename, and __dirname
+    // internally, which are unavailable in ESM scope.
+    const esmRequireBanner = [
+        `import { createRequire as __createRequire } from "node:module";`,
+        `import { fileURLToPath as __fileURLToPath } from "node:url";`,
+        `import { dirname as __pathDirname } from "node:path";`,
+        `const require = __createRequire(import.meta.url);`,
+        `const __filename = __fileURLToPath(import.meta.url);`,
+        `const __dirname = __pathDirname(__filename);`,
+    ].join("\n");
     // Common esbuild options
     const commonOptions = {
         stdin: stdinOptions,
@@ -425,6 +436,7 @@ execute(hook);
         bundle: true,
         minify: false,
         write: false, // Return content directly via outputFiles
+        banner: { js: esmRequireBanner },
         // Keep node built-ins external
         external: [
             "node:*",

package/dist/outputs.js

@@ -69,6 +69,23 @@ function createDecisionOutputBuilder(hookType) {
         stdout: options,
     });
 }
+/**
+ * Factory for exit-code-based hooks (TeammateIdle, TaskCompleted).
+ *
+ * These hooks don't use JSON decision control (no CommonOptions).
+ * The only option is `stderr` — when present, it triggers exit code 2 (BLOCK).
+ * Stdout always receives `{}` (empty JSON object).
+ * @param hookType - The hook type name used as the _type discriminator
+ * @returns A builder function that creates the output object
+ * @internal
+ */
+function createExitCodeOutputBuilder(hookType) {
+    return ({ stderr } = {}) => ({
+        _type: hookType,
+        stdout: {},
+        ...(stderr !== undefined ? { stderr } : {}),
+    });
+}
 /**
  * Creates an output for PreToolUse hooks.
  * @param options - Configuration options for the hook output
@@ -303,17 +320,25 @@ export const setupOutput = /* @__PURE__ */ createHookSpecificOutputBuilder("Setu
  * @returns A TeammateIdleOutput object ready for the runtime
  * @example
  * ```typescript
+ * // Allow teammate to go idle
  * teammateIdleOutput({});
+ *
+ * // Block with feedback
+ * teammateIdleOutput({ stderr: 'Continue working: unfinished tasks remain.' });
  * ```
  */
-export const teammateIdleOutput = /* @__PURE__ */ createSimpleOutputBuilder("TeammateIdle");
+export const teammateIdleOutput = /* @__PURE__ */ createExitCodeOutputBuilder("TeammateIdle");
 /**
  * Creates an output for TaskCompleted hooks.
  * @param options - Configuration options for the hook output
  * @returns A TaskCompletedOutput object ready for the runtime
  * @example
  * ```typescript
+ * // Allow task completion
  * taskCompletedOutput({});
+ *
+ * // Block with feedback
+ * taskCompletedOutput({ stderr: 'Cannot complete: tests are failing.' });
  * ```
  */
-export const taskCompletedOutput = /* @__PURE__ */ createSimpleOutputBuilder("TaskCompleted");
+export const taskCompletedOutput = /* @__PURE__ */ createExitCodeOutputBuilder("TaskCompleted");

package/dist/runtime.js

@@ -106,8 +106,8 @@ function handleHandlerError(error) {
 /**
  * Converts a SpecificHookOutput to HookOutput for wire format.
  *
- * SpecificHookOutput types have: { _type, exitCode, stdout, stderr? }
- * HookOutput has: { exitCode, stdout, stderr? }
+ * SpecificHookOutput types have: { _type, stdout, stderr? }
+ * HookOutput has: { stdout, stderr? }
  *
  * Since output builders now produce wire-format directly, this function
  * simply strips the `_type` discriminator field.
@@ -118,11 +118,12 @@ function handleHandlerError(error) {
  * ```typescript
  * const specificOutput = preToolUseOutput({ hookSpecificOutput: { permissionDecision: 'allow' } });
  * const hookOutput = convertToHookOutput(specificOutput);
- * // hookOutput: { exitCode: 0, stdout: { hookSpecificOutput: { ... } } }
+ * // hookOutput: { stdout: { hookSpecificOutput: { ... } } }
  * ```
  */
 export function convertToHookOutput(specificOutput) {
-    return { stdout: specificOutput.stdout };
+    const { stdout, stderr } = specificOutput;
+    return stderr !== undefined ? { stdout, stderr } : { stdout };
 }
 // ============================================================================
 // Execute Function
@@ -216,9 +217,16 @@ export async function execute(hookFn) {
         if (output !== undefined) {
             writeStdout(output.stdout);
         }
-        // Clear logger context
+        // Clean up logger (single cleanup path)
         logger.clearContext();
         logger.close();
+        // Exit-code BLOCK: unlike handler throw (no stdout), this path still writes
+        // structured JSON to stdout (as empty {}) alongside the stderr message.
+        // The caller controls stderr formatting (no appended newline).
+        if (output?.stderr !== undefined) {
+            process.stderr.write(output.stderr);
+            process.exit(EXIT_CODES.BLOCK);
+        }
         // Exit with success (handler errors exit via handleHandlerError with code 2)
         process.exit(EXIT_CODES.SUCCESS);
     }

package/dist/scaffold.js

@@ -119,7 +119,7 @@ function generatePackageJson(projectName, outputPath) {
             "@goodfoot/claude-code-hooks": "^1.0.9",
         },
         devDependencies: {
-            "@biomejs/biome": "2.3.14",
+            "@biomejs/biome": "2.4.1",
             "@types/node": "^22.0.0",
             typescript: "^5.9.3",
             vitest: "^4.0.16",
@@ -162,7 +162,7 @@ function generateTsConfig() {
  */
 function generateBiomeConfig() {
     return `{
-  "$schema": "https://biomejs.dev/schemas/2.3.14/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.4.1/schema.json",
   "formatter": {
     "enabled": true,
     "indentStyle": "space",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodfoot/claude-code-hooks",
-  "version": "1.0.21",
+  "version": "1.1.0",
   "description": "Type-safe Claude Code hooks library with camelCase types and output builders",
   "homepage": "https://github.com/goodfoot-io/marketplace/tree/main/packages/claude-code-hooks",
   "repository": {
@@ -53,8 +53,8 @@
     "typescript": "^5.9.3"
   },
   "devDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.39",
-    "@biomejs/biome": "2.3.14",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.42",
+    "@biomejs/biome": "2.4.1",
     "@types/node": "^24",
     "ts-morph": "^25.0.0",
     "tsx": "^4.20.3",

package/types/index.d.ts

@@ -13,7 +13,7 @@ export type { LogEvent, LogEventError, LogEventHandler, LoggerConfig, LogLevel,
 export { LOG_LEVELS, Logger, logger } from "./logger.js";
 export type { 
 /** @deprecated Use CommonOptions instead */
-BaseOptions, CommonOptions, ExitCode, HookOutput, HookSpecificOutput, NotificationOptions, PermissionRequestAllowDecision, PermissionRequestDecision, PermissionRequestDenyDecision, PermissionRequestHookSpecificOutput, PermissionRequestOptions, PostToolUseFailureHookSpecificOutput, PostToolUseFailureOptions, PostToolUseHookSpecificOutput, PostToolUseOptions, PreCompactOptions, PreToolUseHookSpecificOutput, PreToolUseOptions, SessionEndOptions, SessionStartHookSpecificOutput, SessionStartOptions, SetupHookSpecificOutput, SetupOptions, StopOptions, SubagentStartHookSpecificOutput, SubagentStartOptions, SubagentStopOptions, SyncHookJSONOutput, TaskCompletedOptions, TeammateIdleOptions, UserPromptSubmitHookSpecificOutput, UserPromptSubmitOptions, } from "./outputs.js";
+BaseOptions, CommonOptions, ExitCode, ExitCodeOptions, HookOutput, HookSpecificOutput, NotificationHookSpecificOutput, NotificationOptions, PermissionRequestAllowDecision, PermissionRequestDecision, PermissionRequestDenyDecision, PermissionRequestHookSpecificOutput, PermissionRequestOptions, PostToolUseFailureHookSpecificOutput, PostToolUseFailureOptions, PostToolUseHookSpecificOutput, PostToolUseOptions, PreCompactOptions, PreToolUseHookSpecificOutput, PreToolUseOptions, SessionEndOptions, SessionStartHookSpecificOutput, SessionStartOptions, SetupHookSpecificOutput, SetupOptions, StopOptions, SubagentStartHookSpecificOutput, SubagentStartOptions, SubagentStopOptions, SyncHookJSONOutput, TaskCompletedOptions, TeammateIdleOptions, UserPromptSubmitHookSpecificOutput, UserPromptSubmitOptions, } from "./outputs.js";
 export { EXIT_CODES, notificationOutput, permissionRequestOutput, postToolUseFailureOutput, postToolUseOutput, preCompactOutput, preToolUseOutput, sessionEndOutput, sessionStartOutput, setupOutput, stopOutput, subagentStartOutput, subagentStopOutput, taskCompletedOutput, teammateIdleOutput, userPromptSubmitOutput, } from "./outputs.js";
 export { execute, } from "./runtime.js";
 export type { ContentContext, PatternCheckResult, ToolUseInput } from "./tool-helpers.js";

package/types/outputs.d.ts

@@ -7,7 +7,7 @@
  * @see https://code.claude.com/docs/en/hooks
  * @module
  */
-import type { PermissionRequestHookSpecificOutput as SDKPermissionRequestHookSpecificOutput, PostToolUseFailureHookSpecificOutput as SDKPostToolUseFailureHookSpecificOutput, PostToolUseHookSpecificOutput as SDKPostToolUseHookSpecificOutput, PreToolUseHookSpecificOutput as SDKPreToolUseHookSpecificOutput, SessionStartHookSpecificOutput as SDKSessionStartHookSpecificOutput, SetupHookSpecificOutput as SDKSetupHookSpecificOutput, SubagentStartHookSpecificOutput as SDKSubagentStartHookSpecificOutput, SyncHookJSONOutput as SDKSyncHookJSONOutput, UserPromptSubmitHookSpecificOutput as SDKUserPromptSubmitHookSpecificOutput } from "@anthropic-ai/claude-agent-sdk/sdk.js";
+import type { NotificationHookSpecificOutput as SDKNotificationHookSpecificOutput, PermissionRequestHookSpecificOutput as SDKPermissionRequestHookSpecificOutput, PostToolUseFailureHookSpecificOutput as SDKPostToolUseFailureHookSpecificOutput, PostToolUseHookSpecificOutput as SDKPostToolUseHookSpecificOutput, PreToolUseHookSpecificOutput as SDKPreToolUseHookSpecificOutput, SessionStartHookSpecificOutput as SDKSessionStartHookSpecificOutput, SetupHookSpecificOutput as SDKSetupHookSpecificOutput, SubagentStartHookSpecificOutput as SDKSubagentStartHookSpecificOutput, SyncHookJSONOutput as SDKSyncHookJSONOutput, UserPromptSubmitHookSpecificOutput as SDKUserPromptSubmitHookSpecificOutput } from "@anthropic-ai/claude-agent-sdk/sdk.js";
 /**
  * Exit codes used by Claude Code hooks.
  *
@@ -36,7 +36,7 @@ export type { SDKSyncHookJSONOutput };
 /**
  * Re-export SDK hook-specific output types (includes hookEventName discriminator).
  */
-export type { SDKPreToolUseHookSpecificOutput, SDKPostToolUseHookSpecificOutput, SDKPostToolUseFailureHookSpecificOutput, SDKUserPromptSubmitHookSpecificOutput, SDKSessionStartHookSpecificOutput, SDKSetupHookSpecificOutput, SDKSubagentStartHookSpecificOutput, SDKPermissionRequestHookSpecificOutput, };
+export type { SDKNotificationHookSpecificOutput, SDKPreToolUseHookSpecificOutput, SDKPostToolUseHookSpecificOutput, SDKPostToolUseFailureHookSpecificOutput, SDKUserPromptSubmitHookSpecificOutput, SDKSessionStartHookSpecificOutput, SDKSetupHookSpecificOutput, SDKSubagentStartHookSpecificOutput, SDKPermissionRequestHookSpecificOutput, };
 /**
  * PreToolUse hook-specific output fields.
  * Omits `hookEventName` which is added automatically by the builder.
@@ -98,18 +98,13 @@ export type PermissionRequestDenyDecision = Extract<SDKPermissionRequestHookSpec
 export type PermissionRequestDecision = SDKPermissionRequestHookSpecificOutput["decision"];
 /**
  * Notification hook-specific output fields.
- * Note: Not in SDK, defined here for completeness.
+ * Omits `hookEventName` which is added automatically by the builder.
  */
-export interface NotificationHookSpecificOutput {
-    /** Additional context to add about the notification. */
-    additionalContext?: string;
-}
+export type NotificationHookSpecificOutput = Omit<SDKNotificationHookSpecificOutput, "hookEventName">;
 /**
  * Full hook-specific output with hookEventName discriminator.
  */
-export type HookSpecificOutput = SDKPreToolUseHookSpecificOutput | SDKPostToolUseHookSpecificOutput | SDKPostToolUseFailureHookSpecificOutput | SDKUserPromptSubmitHookSpecificOutput | SDKSessionStartHookSpecificOutput | SDKSetupHookSpecificOutput | SDKSubagentStartHookSpecificOutput | SDKPermissionRequestHookSpecificOutput | ({
-    hookEventName: "Notification";
-} & NotificationHookSpecificOutput);
+export type HookSpecificOutput = SDKPreToolUseHookSpecificOutput | SDKPostToolUseHookSpecificOutput | SDKPostToolUseFailureHookSpecificOutput | SDKUserPromptSubmitHookSpecificOutput | SDKSessionStartHookSpecificOutput | SDKSetupHookSpecificOutput | SDKSubagentStartHookSpecificOutput | SDKPermissionRequestHookSpecificOutput | SDKNotificationHookSpecificOutput;
 /**
  * The JSON output format expected by Claude Code (sync hooks only).
  * Extends SDK's SyncHookJSONOutput to include Notification hook support.
@@ -137,6 +132,8 @@ export interface SyncHookJSONOutput {
 export interface HookOutput {
     /** JSON-serializable output to write to stdout. */
     stdout: SyncHookJSONOutput;
+    /** Optional message to write to stderr. When present, the runtime exits with code 2 (BLOCK). */
+    stderr?: string;
 }
 /**
  * Common options available to all output builders.
@@ -152,12 +149,24 @@ export interface CommonOptions {
     /** Reason for stopping/blocking (sets exit code to BLOCK). */
     stopReason?: string;
 }
+/**
+ * Options for exit-code-based hooks (TeammateIdle, TaskCompleted).
+ *
+ * These hooks use exit codes only, not JSON decision control.
+ * When `stderr` is provided, the runtime writes it to stderr and exits with code 2 (BLOCK).
+ * When absent, the hook exits with code 0 (SUCCESS).
+ */
+export interface ExitCodeOptions {
+    /** Message to write to stderr. When present, exits with code 2 (BLOCK). */
+    stderr?: string;
+}
 /**
  * Base structure for all specific outputs.
  */
 interface BaseSpecificOutput<T extends string> {
     readonly _type: T;
     stdout: SyncHookJSONOutput;
+    stderr?: string;
 }
 /**
  *
@@ -611,39 +620,49 @@ export declare const setupOutput: (options?: CommonOptions & {
 };
 /**
  * Options for the TeammateIdle output builder.
- * TeammateIdle hooks only support common options.
+ * TeammateIdle hooks use exit codes only, not JSON decision control.
  */
-export type TeammateIdleOptions = CommonOptions;
+export type TeammateIdleOptions = ExitCodeOptions;
 /**
  * Creates an output for TeammateIdle hooks.
  * @param options - Configuration options for the hook output
  * @returns A TeammateIdleOutput object ready for the runtime
  * @example
  * ```typescript
+ * // Allow teammate to go idle
  * teammateIdleOutput({});
+ *
+ * // Block with feedback
+ * teammateIdleOutput({ stderr: 'Continue working: unfinished tasks remain.' });
  * ```
  */
-export declare const teammateIdleOutput: (options?: CommonOptions) => {
+export declare const teammateIdleOutput: ({ stderr }?: ExitCodeOptions) => {
     readonly _type: "TeammateIdle";
     stdout: SyncHookJSONOutput;
+    stderr?: string;
 };
 /**
  * Options for the TaskCompleted output builder.
- * TaskCompleted hooks only support common options.
+ * TaskCompleted hooks use exit codes only, not JSON decision control.
  */
-export type TaskCompletedOptions = CommonOptions;
+export type TaskCompletedOptions = ExitCodeOptions;
 /**
  * Creates an output for TaskCompleted hooks.
  * @param options - Configuration options for the hook output
  * @returns A TaskCompletedOutput object ready for the runtime
  * @example
  * ```typescript
+ * // Allow task completion
  * taskCompletedOutput({});
+ *
+ * // Block with feedback
+ * taskCompletedOutput({ stderr: 'Cannot complete: tests are failing.' });
  * ```
  */
-export declare const taskCompletedOutput: (options?: CommonOptions) => {
+export declare const taskCompletedOutput: ({ stderr }?: ExitCodeOptions) => {
     readonly _type: "TaskCompleted";
     stdout: SyncHookJSONOutput;
+    stderr?: string;
 };
 /**
  * @deprecated Use CommonOptions instead

package/types/runtime.d.ts

@@ -24,8 +24,8 @@ import type { HookInput } from "./types.js";
 /**
  * Converts a SpecificHookOutput to HookOutput for wire format.
  *
- * SpecificHookOutput types have: { _type, exitCode, stdout, stderr? }
- * HookOutput has: { exitCode, stdout, stderr? }
+ * SpecificHookOutput types have: { _type, stdout, stderr? }
+ * HookOutput has: { stdout, stderr? }
  *
  * Since output builders now produce wire-format directly, this function
  * simply strips the `_type` discriminator field.
@@ -36,7 +36,7 @@ import type { HookInput } from "./types.js";
  * ```typescript
  * const specificOutput = preToolUseOutput({ hookSpecificOutput: { permissionDecision: 'allow' } });
  * const hookOutput = convertToHookOutput(specificOutput);
- * // hookOutput: { exitCode: 0, stdout: { hookSpecificOutput: { ... } } }
+ * // hookOutput: { stdout: { hookSpecificOutput: { ... } } }
  * ```
  */
 export declare function convertToHookOutput(specificOutput: SpecificHookOutput): HookOutput;

package/types/types.d.ts

@@ -45,10 +45,11 @@ export type PreCompactTrigger = "manual" | "auto";
  * - `'logout'` - User logged out
  * - `'prompt_input_exit'` - User exited at prompt input
  * - `'other'` - Other reasons
+ * - `'bypass_permissions_disabled'` - Session ended because bypass permissions was disabled
  *
  * Note: SDK's ExitReason resolves to string. This type provides concrete literals for better DX.
  */
-export type SessionEndReason = "clear" | "logout" | "prompt_input_exit" | "other";
+export type SessionEndReason = "clear" | "logout" | "prompt_input_exit" | "other" | "bypass_permissions_disabled";
 /**
  * Common fields present in all hook inputs.
  *