@goodfoot/claude-code-hooks 1.0.11 → 1.0.16

package/README.md

@@ -107,7 +107,7 @@ npm test        # Run tests
 
 ### Available Hook Types
 
-The `--hooks` argument accepts a comma-separated list of any of these 12 event types:
+The `--hooks` argument accepts a comma-separated list of any of these 13 event types:
 
 | Hook Type            | Description                                |
 | -------------------- | ------------------------------------------ |
@@ -123,6 +123,7 @@ The `--hooks` argument accepts a comma-separated list of any of these 12 event t
 | `SubagentStop`       | When a Task tool completes                 |
 | `PreCompact`         | Before context compaction                  |
 | `PermissionRequest`  | When permission is requested               |
+| `Setup`              | On init, install, or update events         |
 
 Hook names are case-insensitive: `stop`, `Stop`, and `STOP` all work.
 

package/dist/cli.js

@@ -691,6 +691,8 @@ function extractPreservedHooks(existingHooksJson) {
     const generatedFiles = new Set(existingHooksJson.__generated?.files ?? []);
     const preserved = {};
     for (const [eventType, entries] of Object.entries(existingHooksJson.hooks)) {
+        if (!entries)
+            continue;
         const preservedEntries = [];
         for (const entry of entries) {
             // Filter out hooks whose command matches a generated file
@@ -836,7 +838,7 @@ async function main() {
             preservedHooks = extractPreservedHooks(existingHooksJson);
             // Remove old generated files from disk
             removeOldGeneratedFiles(existingHooksJson, buildDir);
-            const preservedCount = Object.values(preservedHooks).reduce((sum, entries) => sum + entries.reduce((s, e) => s + e.hooks.length, 0), 0);
+            const preservedCount = Object.values(preservedHooks).reduce((sum, entries) => sum + (entries?.reduce((s, e) => s + e.hooks.length, 0) ?? 0), 0);
             log("info", `Preserved ${preservedCount} hooks from other sources`);
         }
         // Compile all hooks
@@ -871,7 +873,7 @@ async function main() {
         // Output summary to stdout
         process.stdout.write(`Compiled ${compiledHooks.length} hooks to ${buildDir}\n`);
         if (Object.keys(preservedHooks).length > 0) {
-            const preservedCount = Object.values(preservedHooks).reduce((sum, entries) => sum + entries.reduce((s, e) => s + e.hooks.length, 0), 0);
+            const preservedCount = Object.values(preservedHooks).reduce((sum, entries) => sum + (entries?.reduce((s, e) => s + e.hooks.length, 0) ?? 0), 0);
             process.stdout.write(`Preserved ${preservedCount} hooks from other sources\n`);
         }
         process.stdout.write(`Generated ${outputPath}\n`);

package/dist/constants.js

@@ -18,4 +18,5 @@ export const HOOK_FACTORY_TO_EVENT = {
     subagentStopHook: "SubagentStop",
     preCompactHook: "PreCompact",
     permissionRequestHook: "PermissionRequest",
+    setupHook: "Setup",
 };

package/dist/hooks.js

@@ -389,3 +389,43 @@ export function preCompactHook(config, handler) {
 export function permissionRequestHook(config, handler) {
     return createHookFunction("PermissionRequest", config, handler);
 }
+// ============================================================================
+// Setup Hook Factory
+// ============================================================================
+/**
+ * Creates a Setup hook handler.
+ *
+ * Setup hooks fire during initialization or maintenance, allowing you to:
+ * - Configure initial session state
+ * - Perform setup tasks before the session starts
+ * - Add context for maintenance operations
+ *
+ * **Matcher**: Matches against `trigger` ('init' or 'maintenance')
+ * @param config - Hook configuration with optional matcher and timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { setupHook, setupOutput } from '@goodfoot/claude-code-hooks';
+ *
+ * // Handle all setup events
+ * export default setupHook({}, async (input, { logger }) => {
+ *   logger.info('Setup triggered', { trigger: input.trigger });
+ *   return setupOutput({});
+ * });
+ *
+ * // Only handle initialization
+ * export default setupHook({ matcher: 'init' }, async (input, { logger }) => {
+ *   logger.info('Initializing session');
+ *   return setupOutput({
+ *     hookSpecificOutput: {
+ *       additionalContext: 'Session initialized with custom configuration'
+ *     }
+ *   });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#setup
+ */
+export function setupHook(config, handler) {
+    return createHookFunction("Setup", config, handler);
+}

package/dist/index.js

@@ -11,16 +11,16 @@ export {
 CLAUDE_ENV_VARS, getEnvFilePath, 
 // Getters
 getProjectDir, isRemoteEnvironment, } from "./env.js";
-// Hook factory functions - all 12 hook types
-export { notificationHook, permissionRequestHook, postToolUseFailureHook, postToolUseHook, preCompactHook, preToolUseHook, sessionEndHook, sessionStartHook, stopHook, subagentStartHook, subagentStopHook, userPromptSubmitHook, } from "./hooks.js";
+// Hook factory functions - all 13 hook types
+export { notificationHook, permissionRequestHook, postToolUseFailureHook, postToolUseHook, preCompactHook, preToolUseHook, sessionEndHook, sessionStartHook, setupHook, stopHook, subagentStartHook, subagentStopHook, userPromptSubmitHook, } from "./hooks.js";
 // Logger exports
 export { LOG_LEVELS, Logger, logger } from "./logger.js";
 // Output builder functions
 export { 
 // Exit codes
 EXIT_CODES, notificationOutput, permissionRequestOutput, postToolUseFailureOutput, postToolUseOutput, preCompactOutput, 
-// All 12 output builder functions
-preToolUseOutput, sessionEndOutput, sessionStartOutput, stopOutput, subagentStartOutput, subagentStopOutput, userPromptSubmitOutput, } from "./outputs.js";
+// All 13 output builder functions
+preToolUseOutput, sessionEndOutput, sessionStartOutput, setupOutput, stopOutput, subagentStartOutput, subagentStopOutput, userPromptSubmitOutput, } from "./outputs.js";
 // Runtime exports - execute function
 export { 
 // Main execute function for compiled hooks

package/dist/outputs.js

@@ -279,3 +279,21 @@ export const preCompactOutput = /* @__PURE__ */ createSimpleOutputBuilder("PreCo
  * ```
  */
 export const permissionRequestOutput = /* @__PURE__ */ createHookSpecificOutputBuilder("PermissionRequest");
+/**
+ * Creates an output for Setup hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A SetupOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Add context during setup
+ * setupOutput({
+ *   hookSpecificOutput: {
+ *     additionalContext: 'Project initialized with custom settings'
+ *   }
+ * });
+ *
+ * // Simple passthrough
+ * setupOutput({});
+ * ```
+ */
+export const setupOutput = /* @__PURE__ */ createHookSpecificOutputBuilder("Setup");

package/dist/scaffold.js

@@ -49,6 +49,7 @@ const EVENT_TO_OUTPUT_FUNCTION = {
     SubagentStop: "subagentStopOutput",
     PreCompact: "preCompactOutput",
     PermissionRequest: "permissionRequestOutput",
+    Setup: "setupOutput",
 };
 // ============================================================================
 // Validation
@@ -116,7 +117,7 @@ function generatePackageJson(projectName, outputPath) {
             "@goodfoot/claude-code-hooks": "^1.0.9",
         },
         devDependencies: {
-            "@biomejs/biome": "2.3.11",
+            "@biomejs/biome": "2.3.13",
             "@types/node": "^22.0.0",
             typescript: "^5.9.3",
             vitest: "^4.0.16",
@@ -159,7 +160,7 @@ function generateTsConfig() {
  */
 function generateBiomeConfig() {
     return `{
-  "$schema": "https://biomejs.dev/schemas/2.3.11/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.3.13/schema.json",
   "formatter": {
     "enabled": true,
     "indentStyle": "space",

package/dist/types.js

@@ -32,4 +32,5 @@ export const HOOK_EVENT_NAMES = [
     "SubagentStop",
     "PreCompact",
     "PermissionRequest",
+    "Setup",
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodfoot/claude-code-hooks",
-  "version": "1.0.11",
+  "version": "1.0.16",
   "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": {
@@ -27,7 +27,9 @@
     "release": "bash ../../scripts/release-package.sh claude-code-hooks",
     "release:dry-run": "bash ../../scripts/release-package.sh claude-code-hooks --dry-run",
     "snapshot:sdk-types": "tsx scripts/snapshot-sdk-types.ts",
-    "upgrade:deps": "./scripts/upgrade-deps.sh"
+    "upgrade:deps": "./scripts/upgrade-deps.sh",
+    "update:docs": "./scripts/update-docs.sh",
+    "update:docs:dry-run": "./scripts/update-docs.sh --dry-run"
   },
   "exports": {
     ".": {
@@ -51,8 +53,8 @@
     "typescript": "^5.9.3"
   },
   "devDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.12",
-    "@biomejs/biome": "2.3.11",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.22",
+    "@biomejs/biome": "2.3.13",
     "@types/node": "^24",
     "ts-morph": "^25.0.0",
     "tsx": "^4.20.3",

package/types/hooks.d.ts

@@ -22,8 +22,8 @@
  * @see https://code.claude.com/docs/en/hooks
  */
 import type { Logger } from "./logger.js";
-import type { NotificationOutput, PermissionRequestOutput, PostToolUseFailureOutput, PostToolUseOutput, PreCompactOutput, PreToolUseOutput, SessionEndOutput, SessionStartOutput, SpecificHookOutput, StopOutput, SubagentStartOutput, SubagentStopOutput, UserPromptSubmitOutput } from "./outputs.js";
-import type { HookEventName, KnownToolName, NotificationInput, PermissionRequestInput, PostToolUseFailureInput, PostToolUseInput, PreCompactInput, PreToolUseInput, SessionEndInput, SessionStartInput, StopInput, SubagentStartInput, SubagentStopInput, ToolInputMap, UserPromptSubmitInput } from "./types.js";
+import type { NotificationOutput, PermissionRequestOutput, PostToolUseFailureOutput, PostToolUseOutput, PreCompactOutput, PreToolUseOutput, SessionEndOutput, SessionStartOutput, SetupOutput, SpecificHookOutput, StopOutput, SubagentStartOutput, SubagentStopOutput, UserPromptSubmitOutput } from "./outputs.js";
+import type { HookEventName, KnownToolName, NotificationInput, PermissionRequestInput, PostToolUseFailureInput, PostToolUseInput, PreCompactInput, PreToolUseInput, SessionEndInput, SessionStartInput, SetupInput, StopInput, SubagentStartInput, SubagentStopInput, ToolInputMap, UserPromptSubmitInput } from "./types.js";
 /**
  * Configuration options for hook factories.
  *
@@ -763,3 +763,38 @@ export declare function preCompactHook(config: HookConfig, handler: HookHandler<
  */
 export declare function permissionRequestHook<T extends KnownToolName>(config: TypedHookConfig<T>, handler: HookHandler<TypedPermissionRequestInput<T>, PermissionRequestOutput>): HookFunction<TypedPermissionRequestInput<T>, PermissionRequestOutput>;
 export declare function permissionRequestHook(config: HookConfig, handler: HookHandler<PermissionRequestInput, PermissionRequestOutput>): HookFunction<PermissionRequestInput, PermissionRequestOutput>;
+/**
+ * Creates a Setup hook handler.
+ *
+ * Setup hooks fire during initialization or maintenance, allowing you to:
+ * - Configure initial session state
+ * - Perform setup tasks before the session starts
+ * - Add context for maintenance operations
+ *
+ * **Matcher**: Matches against `trigger` ('init' or 'maintenance')
+ * @param config - Hook configuration with optional matcher and timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { setupHook, setupOutput } from '@goodfoot/claude-code-hooks';
+ *
+ * // Handle all setup events
+ * export default setupHook({}, async (input, { logger }) => {
+ *   logger.info('Setup triggered', { trigger: input.trigger });
+ *   return setupOutput({});
+ * });
+ *
+ * // Only handle initialization
+ * export default setupHook({ matcher: 'init' }, async (input, { logger }) => {
+ *   logger.info('Initializing session');
+ *   return setupOutput({
+ *     hookSpecificOutput: {
+ *       additionalContext: 'Session initialized with custom configuration'
+ *     }
+ *   });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#setup
+ */
+export declare function setupHook(config: HookConfig, handler: HookHandler<SetupInput, SetupOutput>): HookFunction<SetupInput, SetupOutput>;

package/types/index.d.ts

@@ -8,15 +8,15 @@
 export type * from "@anthropic-ai/claude-agent-sdk/sdk-tools.js";
 export { CLAUDE_ENV_VARS, getEnvFilePath, getProjectDir, isRemoteEnvironment, } from "./env.js";
 export type { HookConfig, HookContext, HookFunction, HookHandler, SessionStartContext, TypedHookConfig, TypedPermissionRequestInput, TypedPostToolUseFailureInput, TypedPostToolUseInput, TypedPreToolUseInput, } from "./hooks.js";
-export { notificationHook, permissionRequestHook, postToolUseFailureHook, postToolUseHook, preCompactHook, preToolUseHook, sessionEndHook, sessionStartHook, stopHook, subagentStartHook, subagentStopHook, userPromptSubmitHook, } from "./hooks.js";
+export { notificationHook, permissionRequestHook, postToolUseFailureHook, postToolUseHook, preCompactHook, preToolUseHook, sessionEndHook, sessionStartHook, setupHook, stopHook, subagentStartHook, subagentStopHook, userPromptSubmitHook, } from "./hooks.js";
 export type { LogEvent, LogEventError, LogEventHandler, LoggerConfig, LogLevel, Unsubscribe } from "./logger.js";
 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, StopOptions, SubagentStartHookSpecificOutput, SubagentStartOptions, SubagentStopOptions, SyncHookJSONOutput, UserPromptSubmitHookSpecificOutput, UserPromptSubmitOptions, } from "./outputs.js";
-export { EXIT_CODES, notificationOutput, permissionRequestOutput, postToolUseFailureOutput, postToolUseOutput, preCompactOutput, preToolUseOutput, sessionEndOutput, sessionStartOutput, stopOutput, subagentStartOutput, subagentStopOutput, userPromptSubmitOutput, } from "./outputs.js";
+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, UserPromptSubmitHookSpecificOutput, UserPromptSubmitOptions, } from "./outputs.js";
+export { EXIT_CODES, notificationOutput, permissionRequestOutput, postToolUseFailureOutput, postToolUseOutput, preCompactOutput, preToolUseOutput, sessionEndOutput, sessionStartOutput, setupOutput, stopOutput, subagentStartOutput, subagentStopOutput, userPromptSubmitOutput, } from "./outputs.js";
 export { execute, } from "./runtime.js";
 export type { ContentContext, PatternCheckResult, ToolUseInput } from "./tool-helpers.js";
 export { checkContentForPattern, forEachContent, getFilePath, isAskUserQuestionTool, isBashTool, isEditTool, isExitPlanModeTool, isFileModifyingTool, isGlobTool, isGrepTool, isJsTsFile, isKillShellTool, isMultiEditTool, isNotebookEditTool, isReadTool, isTaskOutputTool, isTaskTool, isTodoWriteTool, isTsFile, isWebFetchTool, isWebSearchTool, isWriteTool, } from "./tool-helpers.js";
-export type { BaseHookInput, FileModifyingToolInput, FileModifyingToolName, HookEventName, HookInput, KnownToolInput, KnownToolName, MultiEditEntry, MultiEditToolInput, NotificationInput, PermissionMode, PermissionRequestInput, PermissionUpdate, PostToolUseFailureInput, PostToolUseInput, PreCompactInput, PreCompactTrigger, PreToolUseInput, SessionEndInput, SessionEndReason, SessionStartInput, SessionStartSource, StopInput, SubagentStartInput, SubagentStopInput, ToolInputMap, UserPromptSubmitInput, } from "./types.js";
+export type { BaseHookInput, FileModifyingToolInput, FileModifyingToolName, HookEventName, HookInput, KnownToolInput, KnownToolName, MultiEditEntry, MultiEditToolInput, NotificationInput, PermissionMode, PermissionRequestInput, PermissionUpdate, PostToolUseFailureInput, PostToolUseInput, PreCompactInput, PreCompactTrigger, PreToolUseInput, SessionEndInput, SessionEndReason, SessionStartInput, SessionStartSource, SetupInput, SetupTrigger, StopInput, SubagentStartInput, SubagentStopInput, ToolInputMap, UserPromptSubmitInput, } from "./types.js";
 export { HOOK_EVENT_NAMES } from "./types.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, SubagentStartHookSpecificOutput as SDKSubagentStartHookSpecificOutput, SyncHookJSONOutput as SDKSyncHookJSONOutput, UserPromptSubmitHookSpecificOutput as SDKUserPromptSubmitHookSpecificOutput } from "@anthropic-ai/claude-agent-sdk/sdk.js";
+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";
 /**
  * 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, SDKSubagentStartHookSpecificOutput, SDKPermissionRequestHookSpecificOutput, };
+export type { SDKPreToolUseHookSpecificOutput, SDKPostToolUseHookSpecificOutput, SDKPostToolUseFailureHookSpecificOutput, SDKUserPromptSubmitHookSpecificOutput, SDKSessionStartHookSpecificOutput, SDKSetupHookSpecificOutput, SDKSubagentStartHookSpecificOutput, SDKPermissionRequestHookSpecificOutput, };
 /**
  * PreToolUse hook-specific output fields.
  * Omits `hookEventName` which is added automatically by the builder.
@@ -72,6 +72,11 @@ export type SubagentStartHookSpecificOutput = Omit<SDKSubagentStartHookSpecificO
  * Omits `hookEventName` which is added automatically by the builder.
  */
 export type PermissionRequestHookSpecificOutput = Omit<SDKPermissionRequestHookSpecificOutput, "hookEventName">;
+/**
+ * Setup hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type SetupHookSpecificOutput = Omit<SDKSetupHookSpecificOutput, "hookEventName">;
 /**
  * Allow decision for permission requests.
  * Derived from SDK's PermissionRequestHookSpecificOutput.
@@ -102,7 +107,7 @@ export interface NotificationHookSpecificOutput {
 /**
  * Full hook-specific output with hookEventName discriminator.
  */
-export type HookSpecificOutput = SDKPreToolUseHookSpecificOutput | SDKPostToolUseHookSpecificOutput | SDKPostToolUseFailureHookSpecificOutput | SDKUserPromptSubmitHookSpecificOutput | SDKSessionStartHookSpecificOutput | SDKSubagentStartHookSpecificOutput | SDKPermissionRequestHookSpecificOutput | ({
+export type HookSpecificOutput = SDKPreToolUseHookSpecificOutput | SDKPostToolUseHookSpecificOutput | SDKPostToolUseFailureHookSpecificOutput | SDKUserPromptSubmitHookSpecificOutput | SDKSessionStartHookSpecificOutput | SDKSetupHookSpecificOutput | SDKSubagentStartHookSpecificOutput | SDKPermissionRequestHookSpecificOutput | ({
     hookEventName: "Notification";
 } & NotificationHookSpecificOutput);
 /**
@@ -202,10 +207,14 @@ export type PreCompactOutput = BaseSpecificOutput<"PreCompact">;
  *
  */
 export type PermissionRequestOutput = BaseSpecificOutput<"PermissionRequest">;
+/**
+ *
+ */
+export type SetupOutput = BaseSpecificOutput<"Setup">;
 /**
  * Union of all specific output types.
  */
-export type SpecificHookOutput = PreToolUseOutput | PostToolUseOutput | PostToolUseFailureOutput | NotificationOutput | UserPromptSubmitOutput | SessionStartOutput | SessionEndOutput | StopOutput | SubagentStartOutput | SubagentStopOutput | PreCompactOutput | PermissionRequestOutput;
+export type SpecificHookOutput = PreToolUseOutput | PostToolUseOutput | PostToolUseFailureOutput | NotificationOutput | UserPromptSubmitOutput | SessionStartOutput | SessionEndOutput | StopOutput | SubagentStartOutput | SubagentStopOutput | PreCompactOutput | PermissionRequestOutput | SetupOutput;
 /**
  * Options for decision-based hooks (Stop, SubagentStop).
  */
@@ -562,6 +571,36 @@ export declare const permissionRequestOutput: (options?: CommonOptions & {
     readonly _type: "PermissionRequest";
     stdout: SyncHookJSONOutput;
 };
+/**
+ * Options for the Setup output builder.
+ */
+export type SetupOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: SetupHookSpecificOutput;
+};
+/**
+ * Creates an output for Setup hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A SetupOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Add context during setup
+ * setupOutput({
+ *   hookSpecificOutput: {
+ *     additionalContext: 'Project initialized with custom settings'
+ *   }
+ * });
+ *
+ * // Simple passthrough
+ * setupOutput({});
+ * ```
+ */
+export declare const setupOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: SetupHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "Setup";
+    stdout: SyncHookJSONOutput;
+};
 /**
  * @deprecated Use CommonOptions instead
  */

package/types/types.d.ts

@@ -12,9 +12,9 @@
  * Re-exports types from @anthropic-ai/claude-agent-sdk with "SDK" prefix.
  * These are used as base types for extension, ensuring synchronization with the SDK.
  */
-export type { BaseHookInput as SDKBaseHookInput, HookEvent as SDKHookEvent, HookInput as SDKHookInput, NotificationHookInput as SDKNotificationHookInput, PermissionMode as SDKPermissionMode, PermissionRequestHookInput as SDKPermissionRequestHookInput, PermissionUpdate as SDKPermissionUpdate, PostToolUseFailureHookInput as SDKPostToolUseFailureHookInput, PostToolUseHookInput as SDKPostToolUseHookInput, PreCompactHookInput as SDKPreCompactHookInput, PreToolUseHookInput as SDKPreToolUseHookInput, SessionEndHookInput as SDKSessionEndHookInput, SessionStartHookInput as SDKSessionStartHookInput, StopHookInput as SDKStopHookInput, SubagentStartHookInput as SDKSubagentStartHookInput, SubagentStopHookInput as SDKSubagentStopHookInput, UserPromptSubmitHookInput as SDKUserPromptSubmitHookInput, } from "@anthropic-ai/claude-agent-sdk/entrypoints/agentSdkTypes.js";
-import type { BaseHookInput as SDKBaseHookInput, NotificationHookInput as SDKNotificationHookInput, PermissionMode as SDKPermissionMode, PermissionRequestHookInput as SDKPermissionRequestHookInput, PermissionUpdate as SDKPermissionUpdate, PostToolUseFailureHookInput as SDKPostToolUseFailureHookInput, PostToolUseHookInput as SDKPostToolUseHookInput, PreCompactHookInput as SDKPreCompactHookInput, PreToolUseHookInput as SDKPreToolUseHookInput, SessionEndHookInput as SDKSessionEndHookInput, SessionStartHookInput as SDKSessionStartHookInput, StopHookInput as SDKStopHookInput, SubagentStartHookInput as SDKSubagentStartHookInput, SubagentStopHookInput as SDKSubagentStopHookInput, UserPromptSubmitHookInput as SDKUserPromptSubmitHookInput } from "@anthropic-ai/claude-agent-sdk/entrypoints/agentSdkTypes.js";
-import type { AgentInput, AskUserQuestionInput, BashInput, ExitPlanModeInput, FileEditInput, FileReadInput, FileWriteInput, GlobInput, GrepInput, KillShellInput, NotebookEditInput, TaskOutputInput, TodoWriteInput, WebFetchInput, WebSearchInput } from "@anthropic-ai/claude-agent-sdk/sdk-tools.js";
+export type { BaseHookInput as SDKBaseHookInput, HookEvent as SDKHookEvent, HookInput as SDKHookInput, NotificationHookInput as SDKNotificationHookInput, PermissionMode as SDKPermissionMode, PermissionRequestHookInput as SDKPermissionRequestHookInput, PermissionUpdate as SDKPermissionUpdate, PostToolUseFailureHookInput as SDKPostToolUseFailureHookInput, PostToolUseHookInput as SDKPostToolUseHookInput, PreCompactHookInput as SDKPreCompactHookInput, PreToolUseHookInput as SDKPreToolUseHookInput, SessionEndHookInput as SDKSessionEndHookInput, SessionStartHookInput as SDKSessionStartHookInput, SetupHookInput as SDKSetupHookInput, StopHookInput as SDKStopHookInput, SubagentStartHookInput as SDKSubagentStartHookInput, SubagentStopHookInput as SDKSubagentStopHookInput, UserPromptSubmitHookInput as SDKUserPromptSubmitHookInput, } from "@anthropic-ai/claude-agent-sdk";
+import type { BaseHookInput as SDKBaseHookInput, NotificationHookInput as SDKNotificationHookInput, PermissionMode as SDKPermissionMode, PermissionRequestHookInput as SDKPermissionRequestHookInput, PermissionUpdate as SDKPermissionUpdate, PostToolUseFailureHookInput as SDKPostToolUseFailureHookInput, PostToolUseHookInput as SDKPostToolUseHookInput, PreCompactHookInput as SDKPreCompactHookInput, PreToolUseHookInput as SDKPreToolUseHookInput, SessionEndHookInput as SDKSessionEndHookInput, SessionStartHookInput as SDKSessionStartHookInput, SetupHookInput as SDKSetupHookInput, StopHookInput as SDKStopHookInput, SubagentStartHookInput as SDKSubagentStartHookInput, SubagentStopHookInput as SDKSubagentStopHookInput, UserPromptSubmitHookInput as SDKUserPromptSubmitHookInput } from "@anthropic-ai/claude-agent-sdk";
+import type { AgentInput, AskUserQuestionInput, BashInput, ExitPlanModeInput, FileEditInput, FileReadInput, FileWriteInput, GlobInput, GrepInput, TaskStopInput as KillShellInput, NotebookEditInput, TaskOutputInput, TodoWriteInput, WebFetchInput, WebSearchInput } from "@anthropic-ai/claude-agent-sdk/sdk-tools.js";
 /**
  * Permission mode for controlling how tool executions are handled.
  * @see https://code.claude.com/docs/en/hooks#permission-modes
@@ -364,6 +364,39 @@ export interface PermissionRequestInput extends SDKPermissionRequestHookInput {
      */
     tool_use_id: string;
 }
+/**
+ * Trigger type for Setup hooks.
+ */
+export type SetupTrigger = "init" | "maintenance";
+/**
+ * Input for Setup hooks.
+ *
+ * Fires during initialization or maintenance, allowing you to:
+ * - Configure initial session state
+ * - Perform setup tasks before the session starts
+ * - Add context for maintenance operations
+ *
+ * This hook uses `trigger` for matcher matching.
+ * @example
+ * ```typescript
+ * // Log setup events
+ * setupHook({}, async (input: SetupInput) => {
+ *   console.log(`Setup triggered by: ${input.trigger}`);
+ *   return setupOutput({});
+ * });
+ *
+ * // Only handle init triggers
+ * setupHook({ matcher: 'init' }, async (input: SetupInput) => {
+ *   return setupOutput({
+ *     hookSpecificOutput: {
+ *       additionalContext: 'Initial setup complete'
+ *     }
+ *   });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#setup
+ */
+export type SetupInput = SDKSetupHookInput;
 /**
  * Discriminated union of all hook input types.
  *
@@ -388,7 +421,7 @@ export interface PermissionRequestInput extends SDKPermissionRequestHookInput {
  * ```
  * @see https://code.claude.com/docs/en/hooks
  */
-export type HookInput = PreToolUseInput | PostToolUseInput | PostToolUseFailureInput | NotificationInput | UserPromptSubmitInput | SessionStartInput | SessionEndInput | StopInput | SubagentStartInput | SubagentStopInput | PreCompactInput | PermissionRequestInput;
+export type HookInput = PreToolUseInput | PostToolUseInput | PostToolUseFailureInput | NotificationInput | UserPromptSubmitInput | SessionStartInput | SessionEndInput | StopInput | SubagentStartInput | SubagentStopInput | PreCompactInput | PermissionRequestInput | SetupInput;
 /**
  * Hook event name literal union.
  *
@@ -406,7 +439,7 @@ export type HookEventName = HookInput["hook_event_name"];
  * }
  * ```
  */
-export declare const HOOK_EVENT_NAMES: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "Notification", "UserPromptSubmit", "SessionStart", "SessionEnd", "Stop", "SubagentStart", "SubagentStop", "PreCompact", "PermissionRequest"];
+export declare const HOOK_EVENT_NAMES: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "Notification", "UserPromptSubmit", "SessionStart", "SessionEnd", "Stop", "SubagentStart", "SubagentStop", "PreCompact", "PermissionRequest", "Setup"];
 export type { SDKPermissionUpdate as PermissionUpdate };
 /**
  * Re-export all tool input types from the official Claude Agent SDK.
@@ -414,6 +447,11 @@ export type { SDKPermissionUpdate as PermissionUpdate };
  * @see {@link https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk | @anthropic-ai/claude-agent-sdk}
  */
 export type * from "@anthropic-ai/claude-agent-sdk/sdk-tools.js";
+/**
+ * Backward compatibility alias for TaskStopInput (renamed in SDK 0.2.x).
+ * @deprecated Use TaskStopInput instead
+ */
+export type { KillShellInput };
 /**
  * A single edit entry within a MultiEdit operation.
  */

package/types/inputs.d.ts

@@ -1,601 +0,0 @@
-/**
- * Input types for Claude Code hooks using wire format (snake_case).
- *
- * These types match the JSON format that Claude Code sends via stdin. Property names
- * use snake_case to match the wire protocol directly without transformation overhead.
- * Each hook input type includes comprehensive JSDoc documentation explaining when
- * the hook fires and how to use it.
- * @see https://code.claude.com/docs/en/hooks
- * @module
- */
-import type { PermissionUpdate } from '@anthropic-ai/claude-agent-sdk/entrypoints/agentSdkTypes.js';
-/**
- * Permission mode for controlling how tool executions are handled.
- * @see https://code.claude.com/docs/en/hooks#permission-modes
- */
-export type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'delegate' | 'dontAsk';
-/**
- * Source that triggered a session start event.
- *
- * - `'startup'` - New session started from scratch
- * - `'resume'` - Resuming a previous session
- * - `'clear'` - Session cleared and restarted
- * - `'compact'` - Session restarted after context compaction
- */
-export type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact';
-/**
- * Trigger type for pre-compact events.
- *
- * - `'manual'` - User explicitly requested compaction
- * - `'auto'` - Automatic compaction due to context length
- */
-export type PreCompactTrigger = 'manual' | 'auto';
-/**
- * Reason for session end events.
- *
- * - `'clear'` - Session cleared by user
- * - `'logout'` - User logged out
- * - `'prompt_input_exit'` - User exited at prompt input
- * - `'other'` - Other reasons
- */
-export type SessionEndReason = 'clear' | 'logout' | 'prompt_input_exit' | 'other';
-/**
- * Common fields present in all hook inputs.
- *
- * Every hook receives these base fields providing session context.
- * Hook-specific inputs extend this base with additional fields.
- * @example
- * ```typescript
- * // All hook inputs include these fields
- * const handleAnyHook = (input: BaseHookInput) => {
- *   console.log(`Session: ${input.session_id}`);
- *   console.log(`Working directory: ${input.cwd}`);
- *   console.log(`Transcript: ${input.transcript_path}`);
- * };
- * ```
- * @see https://code.claude.com/docs/en/hooks#hook-input-structure
- */
-export interface BaseHookInput {
-  /**
-   * Unique identifier for the current Claude Code session.
-   * Persists across conversation turns within the same session.
-   */
-  session_id: string;
-  /**
-   * Absolute path to the session transcript file.
-   * Contains the full conversation history in JSONL format.
-   */
-  transcript_path: string;
-  /**
-   * Current working directory for the Claude Code session.
-   * All file operations are relative to this directory.
-   */
-  cwd: string;
-  /**
-   * Current permission mode for tool execution.
-   * May be undefined if using default mode.
-   */
-  permission_mode?: PermissionMode;
-}
-/**
- * Input for PreToolUse hooks.
- *
- * Fires before any tool is executed, allowing you to:
- * - Inspect and validate tool inputs
- * - Allow, deny, or modify the tool execution
- * - Add custom permission logic
- *
- * This hook uses `tool_name` for matcher matching.
- * @example
- * ```typescript
- * // Block dangerous Bash commands
- * preToolUseHook({ matcher: 'Bash' }, async (input: PreToolUseInput) => {
- *   const command = input.tool_input.command as string;
- *   if (command.includes('rm -rf')) {
- *     return preToolUseOutput({
- *       deny: 'Destructive commands are not allowed'
- *     });
- *   }
- *   return preToolUseOutput({ allow: true });
- * });
- * ```
- * @see https://code.claude.com/docs/en/hooks#pretooluse
- */
-export interface PreToolUseInput extends BaseHookInput {
-  /** Discriminator for hook event type. */
-  hook_event_name: 'PreToolUse';
-  /**
-   * Name of the tool being invoked.
-   * Examples: 'Bash', 'Read', 'Edit', 'Write', 'Glob', 'Grep'
-   */
-  tool_name: string;
-  /**
-   * Input parameters being passed to the tool.
-   * Structure varies by tool type.
-   */
-  tool_input: unknown;
-  /**
-   * Unique identifier for this specific tool invocation.
-   * Use this to correlate with PostToolUse events.
-   */
-  tool_use_id: string;
-}
-/**
- * Input for PostToolUse hooks.
- *
- * Fires after a tool executes successfully, allowing you to:
- * - Inspect tool results
- * - Add additional context to the conversation
- * - Modify MCP tool output
- *
- * This hook uses `tool_name` for matcher matching.
- * @example
- * ```typescript
- * // Add context after file reads
- * postToolUseHook({ matcher: 'Read' }, async (input: PostToolUseInput) => {
- *   const filePath = input.tool_input.file_path as string;
- *   return postToolUseOutput({
- *     additionalContext: `File ${filePath} was read successfully`
- *   });
- * });
- * ```
- * @see https://code.claude.com/docs/en/hooks#posttooluse
- */
-export interface PostToolUseInput extends BaseHookInput {
-  /** Discriminator for hook event type. */
-  hook_event_name: 'PostToolUse';
-  /**
-   * Name of the tool that was invoked.
-   */
-  tool_name: string;
-  /**
-   * Input parameters that were passed to the tool.
-   */
-  tool_input: unknown;
-  /**
-   * Response returned by the tool.
-   * Structure varies by tool type.
-   */
-  tool_response: unknown;
-  /**
-   * Unique identifier for this tool invocation.
-   * Matches the tool_use_id from the corresponding PreToolUse event.
-   */
-  tool_use_id: string;
-}
-/**
- * Input for PostToolUseFailure hooks.
- *
- * Fires after a tool execution fails, allowing you to:
- * - Log or report tool failures
- * - Add context about the failure
- * - Take corrective action
- *
- * This hook uses `tool_name` for matcher matching.
- * @example
- * ```typescript
- * // Log tool failures
- * postToolUseFailureHook({ matcher: '.*' }, async (input: PostToolUseFailureInput) => {
- *   console.error(`Tool ${input.tool_name} failed: ${input.error}`);
- *   return postToolUseFailureOutput({
- *     additionalContext: 'Please try an alternative approach'
- *   });
- * });
- * ```
- * @see https://code.claude.com/docs/en/hooks#posttoolusefailure
- */
-export interface PostToolUseFailureInput extends BaseHookInput {
-  /** Discriminator for hook event type. */
-  hook_event_name: 'PostToolUseFailure';
-  /**
-   * Name of the tool that failed.
-   */
-  tool_name: string;
-  /**
-   * Input parameters that were passed to the tool.
-   */
-  tool_input: unknown;
-  /**
-   * Unique identifier for this tool invocation.
-   */
-  tool_use_id: string;
-  /**
-   * Error message describing why the tool failed.
-   */
-  error: string;
-  /**
-   * Whether this failure was caused by a user interrupt.
-   */
-  is_interrupt?: boolean;
-}
-/**
- * Input for Notification hooks.
- *
- * Fires when Claude Code sends a notification, allowing you to:
- * - Forward notifications to external systems
- * - Log important events
- * - Trigger custom alerting
- *
- * This hook uses `notification_type` for matcher matching.
- * @example
- * ```typescript
- * // Forward notifications to Slack
- * notificationHook({}, async (input: NotificationInput) => {
- *   await sendSlackMessage(input.title, input.message);
- *   return notificationOutput({});
- * });
- * ```
- * @see https://code.claude.com/docs/en/hooks#notification
- */
-export interface NotificationInput extends BaseHookInput {
-  /** Discriminator for hook event type. */
-  hook_event_name: 'Notification';
-  /**
-   * Main content of the notification.
-   */
-  message: string;
-  /**
-   * Optional title for the notification.
-   */
-  title?: string;
-  /**
-   * Type/category of the notification.
-   */
-  notification_type: string;
-}
-/**
- * Input for UserPromptSubmit hooks.
- *
- * Fires when a user submits a prompt, allowing you to:
- * - Add additional context or instructions
- * - Log user interactions
- * - Validate or transform prompts
- *
- * This hook does not support matchers; it fires on all prompt submissions.
- * @example
- * ```typescript
- * // Add project context to every prompt
- * userPromptSubmitHook({}, async (input: UserPromptSubmitInput) => {
- *   return userPromptSubmitOutput({
- *     additionalContext: await getProjectContext()
- *   });
- * });
- * ```
- * @see https://code.claude.com/docs/en/hooks#userpromptsubmit
- */
-export interface UserPromptSubmitInput extends BaseHookInput {
-  /** Discriminator for hook event type. */
-  hook_event_name: 'UserPromptSubmit';
-  /**
-   * The prompt text submitted by the user.
-   */
-  prompt: string;
-}
-/**
- * Input for SessionStart hooks.
- *
- * Fires when a Claude Code session starts or restarts, allowing you to:
- * - Initialize session state
- * - Inject context or instructions
- * - Set up logging or monitoring
- *
- * This hook uses `source` for matcher matching.
- * @example
- * ```typescript
- * // Initialize context for new sessions
- * sessionStartHook({ matcher: 'startup' }, async (input: SessionStartInput) => {
- *   return sessionStartOutput({
- *     additionalContext: JSON.stringify({
- *       project: 'my-project',
- *       initialized: true
- *     })
- *   });
- * });
- * ```
- * @see https://code.claude.com/docs/en/hooks#sessionstart
- */
-export interface SessionStartInput extends BaseHookInput {
-  /** Discriminator for hook event type. */
-  hook_event_name: 'SessionStart';
-  /**
-   * How the session was started.
-   *
-   * - `'startup'` - New session started from scratch
-   * - `'resume'` - Resuming a previous session
-   * - `'clear'` - Session cleared and restarted
-   * - `'compact'` - Session restarted after context compaction
-   */
-  source: SessionStartSource;
-}
-/**
- * Input for SessionEnd hooks.
- *
- * Fires when a Claude Code session ends, allowing you to:
- * - Clean up session resources
- * - Log session metrics
- * - Persist session state
- *
- * This hook uses `reason` for matcher matching.
- * @example
- * ```typescript
- * // Log session end
- * sessionEndHook({}, async (input: SessionEndInput) => {
- *   console.log(`Session ended: ${input.reason}`);
- *   return sessionEndOutput({});
- * });
- * ```
- * @see https://code.claude.com/docs/en/hooks#sessionend
- */
-export interface SessionEndInput extends BaseHookInput {
-  /** Discriminator for hook event type. */
-  hook_event_name: 'SessionEnd';
-  /**
-   * The reason the session ended.
-   *
-   * - `'clear'` - Session cleared by user
-   * - `'logout'` - User logged out
-   * - `'prompt_input_exit'` - User exited at prompt input
-   * - `'other'` - Other reasons
-   */
-  reason: SessionEndReason;
-}
-/**
- * Input for Stop hooks.
- *
- * Fires when Claude Code is about to stop, allowing you to:
- * - Block the stop and require additional action
- * - Confirm the user wants to stop
- * - Clean up resources before stopping
- *
- * This hook does not support matchers; it fires on all stop events.
- * @example
- * ```typescript
- * // Require confirmation before stopping with pending changes
- * stopHook({}, async (input: StopInput) => {
- *   const pendingChanges = await checkPendingChanges();
- *   if (pendingChanges.length > 0) {
- *     return stopOutput({
- *       decision: 'block',
- *       reason: 'There are uncommitted changes'
- *     });
- *   }
- *   return stopOutput({ decision: 'approve' });
- * });
- * ```
- * @see https://code.claude.com/docs/en/hooks#stop
- */
-export interface StopInput extends BaseHookInput {
-  /** Discriminator for hook event type. */
-  hook_event_name: 'Stop';
-  /**
-   * Whether a stop hook is currently active.
-   * Used to prevent recursive stop hook invocations.
-   */
-  stop_hook_active: boolean;
-}
-/**
- * Input for SubagentStart hooks.
- *
- * Fires when a subagent (Task tool) starts, allowing you to:
- * - Inject context for the subagent
- * - Log subagent invocations
- * - Configure subagent behavior
- *
- * This hook uses `agent_type` for matcher matching.
- * @example
- * ```typescript
- * // Add context for explore subagents
- * subagentStartHook({ matcher: 'explore' }, async (input: SubagentStartInput) => {
- *   return subagentStartOutput({
- *     additionalContext: 'Focus on finding patterns and conventions'
- *   });
- * });
- * ```
- * @see https://code.claude.com/docs/en/hooks#subagentstart
- */
-export interface SubagentStartInput extends BaseHookInput {
-  /** Discriminator for hook event type. */
-  hook_event_name: 'SubagentStart';
-  /**
-   * Unique identifier for the subagent instance.
-   */
-  agent_id: string;
-  /**
-   * Type of subagent being started.
-   * Examples: 'explore', 'codebase-analysis', custom agent types
-   */
-  agent_type: string;
-}
-/**
- * Input for SubagentStop hooks.
- *
- * Fires when a subagent completes or stops, allowing you to:
- * - Process subagent results
- * - Clean up subagent resources
- * - Log subagent completion
- * - Block subagent from stopping
- *
- * This hook uses `agent_type` for matcher matching.
- * @example
- * ```typescript
- * // Block explore subagent if task incomplete
- * subagentStopHook({ matcher: 'explore' }, async (input: SubagentStopInput) => {
- *   console.log(`Subagent ${input.agent_id} (${input.agent_type}) stopping`);
- *   return subagentStopOutput({
- *     decision: 'block',
- *     reason: 'Please verify all files were explored'
- *   });
- * });
- * ```
- * @see https://code.claude.com/docs/en/hooks#subagentstop
- */
-export interface SubagentStopInput extends BaseHookInput {
-  /** Discriminator for hook event type. */
-  hook_event_name: 'SubagentStop';
-  /**
-   * Whether a stop hook is currently active.
-   */
-  stop_hook_active: boolean;
-  /**
-   * Unique identifier for the subagent instance.
-   */
-  agent_id: string;
-  /**
-   * Type of subagent that is stopping.
-   * Examples: 'explore', 'codebase-analysis', custom agent types
-   */
-  agent_type: string;
-  /**
-   * Path to the subagent's transcript file.
-   */
-  agent_transcript_path: string;
-}
-/**
- * Input for PreCompact hooks.
- *
- * Fires before context compaction occurs, allowing you to:
- * - Preserve important information before compaction
- * - Log compaction events
- * - Modify custom instructions for the compacted context
- *
- * This hook uses `trigger` for matcher matching.
- * @example
- * ```typescript
- * // Log compaction events
- * preCompactHook({}, async (input: PreCompactInput) => {
- *   console.log(`Compacting (${input.trigger})`);
- *   return preCompactOutput({});
- * });
- * ```
- * @see https://code.claude.com/docs/en/hooks#precompact
- */
-export interface PreCompactInput extends BaseHookInput {
-  /** Discriminator for hook event type. */
-  hook_event_name: 'PreCompact';
-  /**
-   * What triggered the compaction.
-   *
-   * - `'manual'` - User explicitly requested compaction
-   * - `'auto'` - Automatic compaction due to context length
-   */
-  trigger: PreCompactTrigger;
-  /**
-   * Custom instructions to include in the compacted context.
-   * May be null if no custom instructions are set.
-   */
-  custom_instructions: string | null;
-}
-/**
- * Input for PermissionRequest hooks.
- *
- * Fires when a permission prompt would be shown, allowing you to:
- * - Auto-approve or deny tool executions
- * - Implement custom permission logic
- * - Modify tool inputs before approval
- *
- * This hook uses `tool_name` for matcher matching.
- * @example
- * ```typescript
- * // Auto-approve read operations in allowed directories
- * permissionRequestHook({ matcher: 'Read' }, async (input: PermissionRequestInput) => {
- *   const filePath = input.tool_input.file_path as string;
- *   if (filePath.startsWith('/allowed/')) {
- *     return permissionRequestOutput({
- *       allow: true
- *     });
- *   }
- *   return permissionRequestOutput({});  // Fall through to normal permission prompt
- * });
- * ```
- * @see https://code.claude.com/docs/en/hooks#permissionrequest
- */
-export interface PermissionRequestInput extends BaseHookInput {
-  /** Discriminator for hook event type. */
-  hook_event_name: 'PermissionRequest';
-  /**
-   * Name of the tool requesting permission.
-   */
-  tool_name: string;
-  /**
-   * Input parameters for the tool.
-   */
-  tool_input: unknown;
-  /**
-   * Unique identifier for this specific tool invocation.
-   */
-  tool_use_id: string;
-  /**
-   * Suggested permission updates that would prevent future prompts.
-   * Typically used for "always allow" functionality.
-   */
-  permission_suggestions?: PermissionUpdate[];
-}
-/**
- * Discriminated union of all hook input types.
- *
- * Use this type when handling multiple hook types in a single handler
- * or when the hook type is not known statically.
- * @example
- * ```typescript
- * // Handle any hook type with type narrowing
- * function handleHook(input: HookInput) {
- *   switch (input.hook_event_name) {
- *     case 'PreToolUse':
- *       // TypeScript knows input is PreToolUseInput here
- *       console.log(`Tool: ${input.tool_name}`);
- *       break;
- *     case 'SessionStart':
- *       // TypeScript knows input is SessionStartInput here
- *       console.log(`Source: ${input.source}`);
- *       break;
- *     // ... handle other hook types
- *   }
- * }
- * ```
- * @see https://code.claude.com/docs/en/hooks
- */
-export type HookInput =
-  | PreToolUseInput
-  | PostToolUseInput
-  | PostToolUseFailureInput
-  | NotificationInput
-  | UserPromptSubmitInput
-  | SessionStartInput
-  | SessionEndInput
-  | StopInput
-  | SubagentStartInput
-  | SubagentStopInput
-  | PreCompactInput
-  | PermissionRequestInput;
-/**
- * Hook event name literal union.
- *
- * All valid hook event names that can appear in the `hook_event_name` field.
- */
-export type HookEventName = HookInput['hook_event_name'];
-/**
- * All hook event names as a readonly array.
- *
- * Useful for iteration and validation.
- * @example
- * ```typescript
- * for (const eventName of HOOK_EVENT_NAMES) {
- *   console.log(`Supported hook: ${eventName}`);
- * }
- * ```
- */
-export declare const HOOK_EVENT_NAMES: readonly [
-  'PreToolUse',
-  'PostToolUse',
-  'PostToolUseFailure',
-  'Notification',
-  'UserPromptSubmit',
-  'SessionStart',
-  'SessionEnd',
-  'Stop',
-  'SubagentStart',
-  'SubagentStop',
-  'PreCompact',
-  'PermissionRequest'
-];
-export type { PermissionUpdate };

package/types/tool-inputs.d.ts

@@ -1,228 +0,0 @@
-/**
- * Type definitions for well-known Claude Code tool inputs.
- *
- * These types define the structure of `toolInput` for common Claude Code tools.
- * Use them with type guards from `tool-helpers.ts` for safe type narrowing,
- * or with typed hook factory overloads for automatic typing.
- * @example
- * ```typescript
- * import { isWriteTool, getFilePath } from '@goodfoot/claude-code-hooks';
- *
- * preToolUseHook({ matcher: 'Write|Edit|MultiEdit' }, (input) => {
- *   if (isWriteTool(input)) {
- *     // input.tool_input is now typed as WriteToolInput
- *     console.log(input.tool_input.file_path);
- *   }
- * });
- * ```
- * @see https://code.claude.com/docs/en/hooks
- * @module
- */
-/**
- * Input structure for the Write tool.
- *
- * The Write tool creates or overwrites files with the specified content.
- * @example
- * ```typescript
- * // Example tool input
- * {
- *   file_path: '/workspace/src/index.ts',
- *   content: 'export const hello = "world";'
- * }
- * ```
- */
-export interface WriteToolInput {
-  /** Absolute path to the file to write. */
-  file_path: string;
-  /** The content to write to the file. */
-  content: string;
-}
-/**
- * Input structure for the Edit tool.
- *
- * The Edit tool performs search-and-replace operations on files.
- * @example
- * ```typescript
- * // Example tool input
- * {
- *   file_path: '/workspace/src/index.ts',
- *   old_string: 'const x = 1;',
- *   new_string: 'const x = 2;',
- *   replace_all: false
- * }
- * ```
- */
-export interface EditToolInput {
-  /** Absolute path to the file to edit. */
-  file_path: string;
-  /** The text to search for (must be unique in the file unless replace_all is true). */
-  old_string: string;
-  /** The text to replace old_string with. */
-  new_string: string;
-  /** If true, replace all occurrences. If false, old_string must be unique. */
-  replace_all?: boolean;
-}
-/**
- * A single edit entry within a MultiEdit operation.
- */
-export interface MultiEditEntry {
-  /** The text to search for. */
-  old_string: string;
-  /** The text to replace old_string with. */
-  new_string: string;
-}
-/**
- * Input structure for the MultiEdit tool.
- *
- * The MultiEdit tool performs multiple search-and-replace operations on a single file.
- * All edits are applied atomically.
- * @example
- * ```typescript
- * // Example tool input
- * {
- *   file_path: '/workspace/src/index.ts',
- *   edits: [
- *     { old_string: 'const x = 1;', new_string: 'const x = 2;' },
- *     { old_string: 'const y = 1;', new_string: 'const y = 2;' }
- *   ]
- * }
- * ```
- */
-export interface MultiEditToolInput {
-  /** Absolute path to the file to edit. */
-  file_path: string;
-  /** Array of edit operations to apply. */
-  edits: MultiEditEntry[];
-}
-/**
- * Input structure for the Read tool.
- *
- * The Read tool reads file contents, optionally with offset and limit.
- * @example
- * ```typescript
- * // Example tool input
- * {
- *   file_path: '/workspace/src/index.ts',
- *   offset: 0,
- *   limit: 100
- * }
- * ```
- */
-export interface ReadToolInput {
-  /** Absolute path to the file to read. */
-  file_path: string;
-  /** Line offset to start reading from. */
-  offset?: number;
-  /** Maximum number of lines to read. */
-  limit?: number;
-}
-/**
- * Input structure for the Bash tool.
- *
- * The Bash tool executes shell commands.
- * @example
- * ```typescript
- * // Example tool input
- * {
- *   command: 'npm install',
- *   timeout: 60000,
- *   description: 'Install dependencies'
- * }
- * ```
- */
-export interface BashToolInput {
-  /** The command to execute. */
-  command: string;
-  /** Optional timeout in milliseconds. */
-  timeout?: number;
-  /** Optional description of what the command does. */
-  description?: string;
-}
-/**
- * Input structure for the Glob tool.
- *
- * The Glob tool finds files matching a glob pattern.
- * @example
- * ```typescript
- * // Example tool input
- * {
- *   pattern: '**\/*.ts',
- *   path: '/workspace/src'
- * }
- * ```
- */
-export interface GlobToolInput {
-  /** Glob pattern to match files against. */
-  pattern: string;
-  /** Directory to search in (defaults to cwd). */
-  path?: string;
-}
-/**
- * Input structure for the Grep tool.
- *
- * The Grep tool searches file contents using regex patterns.
- * @example
- * ```typescript
- * // Example tool input
- * {
- *   pattern: 'function\\s+\\w+',
- *   path: '/workspace/src',
- *   glob: '*.ts'
- * }
- * ```
- */
-export interface GrepToolInput {
-  /** Regular expression pattern to search for. */
-  pattern: string;
-  /** Directory to search in (defaults to cwd). */
-  path?: string;
-  /** Glob pattern to filter files. */
-  glob?: string;
-}
-/**
- * Union of all file-modifying tool inputs.
- *
- * Use this type when you need to handle Write, Edit, or MultiEdit generically.
- */
-export type FileModifyingToolInput = WriteToolInput | EditToolInput | MultiEditToolInput;
-/**
- * Tool names for file-modifying tools.
- *
- * Use this type when you need to reference the tool name in type guards.
- */
-export type FileModifyingToolName = 'Write' | 'Edit' | 'MultiEdit';
-/**
- * Union of all known tool inputs.
- *
- * This includes all tool inputs that have well-defined type structures.
- */
-export type KnownToolInput =
-  | WriteToolInput
-  | EditToolInput
-  | MultiEditToolInput
-  | ReadToolInput
-  | BashToolInput
-  | GlobToolInput
-  | GrepToolInput;
-/**
- * Tool names for all known tools with typed inputs.
- */
-export type KnownToolName = 'Write' | 'Edit' | 'MultiEdit' | 'Read' | 'Bash' | 'Glob' | 'Grep';
-/**
- * Type mapping from tool name to tool input type.
- *
- * Used by typed factory overloads to provide automatic typing.
- * @example
- * ```typescript
- * type WriteInput = ToolInputMap['Write']; // WriteToolInput
- * ```
- */
-export interface ToolInputMap {
-  Write: WriteToolInput;
-  Edit: EditToolInput;
-  MultiEdit: MultiEditToolInput;
-  Read: ReadToolInput;
-  Bash: BashToolInput;
-  Glob: GlobToolInput;
-  Grep: GrepToolInput;
-}