@goodfoot/claude-code-hooks 1.0.23 → 1.1.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodfoot/claude-code-hooks",
-  "version": "1.0.23",
+  "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": {

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, 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";
+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

@@ -132,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.
@@ -147,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;
 }
 /**
  *
@@ -606,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;