@goodfoot/agent-hooks 1.0.0

package/types/agents/claude-code/hooks.d.ts

@@ -0,0 +1,1182 @@
+/**
+ * Hook factory functions for Claude Code hooks.
+ *
+ * Provides typed factory functions for all 30 hook types that handle:
+ * - Input type narrowing based on hook event type
+ * - Output type enforcement via return types
+ * - Error wrapping with automatic logging
+ * - Logger context injection
+ *
+ * Each factory accepts a HookConfig with optional matcher and timeout settings,
+ * and returns a function that the runtime invokes when the hook file executes.
+ * @module
+ * @example
+ * ```typescript
+ * import { preToolUseHook, preToolUseOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * export default preToolUseHook({ matcher: 'Bash' }, async (input, { logger }) => {
+ *   logger.info('Processing Bash command');
+ *   return preToolUseOutput({ allow: true });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks
+ */
+import type { HookConfig, HookContext, HookFunction, UnexpectedErrorHandler, UnexpectedErrorPolicy } from "../../core/types.js";
+import { type AllowedUnexpectedErrorPolicy } from "./events.js";
+import type { ConfigChangeOutput, CwdChangedOutput, ElicitationOutput, ElicitationResultOutput, FileChangedOutput, InstructionsLoadedOutput, MessageDisplayOutput, NotificationOutput, PermissionDeniedOutput, PermissionRequestOutput, PostCompactOutput, PostToolBatchOutput, PostToolUseFailureOutput, PostToolUseOutput, PreCompactOutput, PreToolUseOutput, SessionEndOutput, SessionStartOutput, SetupOutput, SpecificHookOutput, StopFailureOutput, StopOutput, SubagentStartOutput, SubagentStopOutput, TaskCompletedOutput, TaskCreatedOutput, TeammateIdleOutput, UserPromptExpansionOutput, UserPromptSubmitOutput, WorktreeCreateOutput, WorktreeRemoveOutput } from "./outputs.js";
+import type { ConfigChangeInput, CwdChangedInput, ElicitationInput, ElicitationResultInput, FileChangedInput, HookEventName, InstructionsLoadedInput, KnownToolName, MessageDisplayInput, NotificationInput, PermissionDeniedInput, PermissionRequestInput, PostCompactInput, PostToolBatchInput, PostToolUseFailureInput, PostToolUseInput, PreCompactInput, PreToolUseInput, SessionEndInput, SessionStartInput, SetupInput, StopFailureInput, StopInput, SubagentStartInput, SubagentStopInput, TaskCompletedInput, TaskCreatedInput, TeammateIdleInput, ToolInputMap, UserPromptExpansionInput, UserPromptSubmitInput, WorktreeCreateInput, WorktreeRemoveInput } from "./types.js";
+/**
+ * The policy, phase, and diagnostic vocabulary is shared across agents and
+ * owned by the core; re-exported here so the Claude Code surface keeps its
+ * historical import site (`hooks.js`).
+ *
+ * `"error"` (default) preserves existing behavior: an unhandled exception
+ * anywhere in the runtime writes a stack trace to stderr and exits non-zero.
+ *
+ * `"continue"` is an opt-in fail-open policy for advisory hooks whose only
+ * purpose is to enrich context (e.g. UserPromptSubmit additionalContext).
+ * Under this policy, unexpected runtime failures are swallowed, the empty
+ * output (`{}`) is emitted if no response was already produced, and the
+ * process exits 0 instead of surfacing a failed-hook banner to the user.
+ * An explicit `stderr`/blocking response returned by the handler itself is
+ * unaffected: it always writes that message and exits with code 2 (BLOCK).
+ * Do not use "continue" for hooks that enforce permission, safety, or
+ * policy decisions — see {@link ADVISORY_EVENTS} and the per-event config
+ * narrowing ({@link HookConfigFor}), which reject it at factory-call time
+ * and at compile time for every excluded event.
+ */
+export type { HookConfig, HookContext, HookErrorPhase, HookFunction, UnexpectedErrorHandler, UnexpectedErrorPolicy, } from "../../core/types.js";
+/**
+ * Per-event hook configuration: the shared {@link HookConfig} with the
+ * fail-open policy narrowed by the advisory allow-list. On excluded events
+ * (`PreToolUse`, `PermissionRequest`, blocking `Stop`/`SubagentStop`,
+ * `WorktreeCreate`/`WorktreeRemove`) the `unexpectedError` field collapses
+ * to `"error"` only, so `unexpectedError: "continue"` fails the type check;
+ * the same rule is enforced at factory-call time by the runtime policy gate.
+ * @template TEventName - The event the factory binds.
+ */
+export type HookConfigFor<TEventName extends HookEventName> = Omit<HookConfig, "unexpectedError"> & {
+    unexpectedError?: AllowedUnexpectedErrorPolicy<TEventName>;
+};
+/**
+ * Typed-single-tool-matcher variant of {@link HookConfigFor}: narrows both
+ * the tool input (via `matcher: T`) and the allowed fail-open policy for the
+ * bound event. See {@link HookConfigFor}.
+ * @template T - The known tool name to match
+ * @template TEventName - The event the factory binds.
+ */
+export type TypedHookConfigFor<T extends KnownToolName, TEventName extends HookEventName> = Omit<TypedHookConfig<T>, "unexpectedError"> & {
+    unexpectedError?: AllowedUnexpectedErrorPolicy<TEventName>;
+};
+/**
+ * Configuration for hooks with a known single-tool matcher.
+ *
+ * When the matcher is a single known tool name, the handler receives
+ * automatically typed toolInput based on the tool type.
+ * @template T - The known tool name
+ * @example
+ * ```typescript
+ * // tool_input is automatically typed as FileWriteInput
+ * preToolUseHook({ matcher: 'Write' }, (input) => {
+ *   console.log(input.tool_input.file_path); // Typed!
+ *   console.log(input.tool_input.content);   // Typed!
+ * });
+ * ```
+ */
+export interface TypedHookConfig<T extends KnownToolName> {
+    /**
+     * The single tool name to match.
+     * When this is a known tool name, toolInput will be automatically typed.
+     */
+    matcher: T;
+    /**
+     * Handler execution timeout in milliseconds.
+     */
+    timeout?: number;
+    /**
+     * Opt-in fail-open policy for unexpected runtime failures. See
+     * {@link UnexpectedErrorPolicy}.
+     */
+    unexpectedError?: UnexpectedErrorPolicy;
+    /**
+     * Best-effort diagnostic callback for the "continue" policy. See
+     * {@link UnexpectedErrorHandler}.
+     */
+    onUnexpectedError?: UnexpectedErrorHandler;
+}
+/**
+ * PreToolUseHookInput with typed tool_input for a specific tool.
+ * @template T - The known tool name
+ */
+type _TypedPreToolUseHookInputBase<T extends KnownToolName> = Omit<PreToolUseInput, "tool_name" | "tool_input"> & {
+    tool_name: T;
+    tool_input: ToolInputMap[T];
+};
+export type TypedPreToolUseHookInput<T extends KnownToolName> = {
+    [K in keyof _TypedPreToolUseHookInputBase<T>]: _TypedPreToolUseHookInputBase<T>[K];
+} & {};
+/**
+ * PostToolUseHookInput with typed tool_input for a specific tool.
+ * @template T - The known tool name
+ */
+type _TypedPostToolUseHookInputBase<T extends KnownToolName> = Omit<PostToolUseInput, "tool_name" | "tool_input"> & {
+    tool_name: T;
+    tool_input: ToolInputMap[T];
+};
+export type TypedPostToolUseHookInput<T extends KnownToolName> = {
+    [K in keyof _TypedPostToolUseHookInputBase<T>]: _TypedPostToolUseHookInputBase<T>[K];
+} & {};
+/**
+ * PostToolUseFailureHookInput with typed tool_input for a specific tool.
+ * @template T - The known tool name
+ */
+type _TypedPostToolUseFailureHookInputBase<T extends KnownToolName> = Omit<PostToolUseFailureInput, "tool_name" | "tool_input"> & {
+    tool_name: T;
+    tool_input: ToolInputMap[T];
+};
+export type TypedPostToolUseFailureHookInput<T extends KnownToolName> = {
+    [K in keyof _TypedPostToolUseFailureHookInputBase<T>]: _TypedPostToolUseFailureHookInputBase<T>[K];
+} & {};
+/**
+ * PermissionRequestInput with typed tool_input for a specific tool.
+ * @template T - The known tool name
+ */
+type _TypedPermissionRequestInputBase<T extends KnownToolName> = Omit<PermissionRequestInput, "tool_name" | "tool_input"> & {
+    tool_name: T;
+    tool_input: ToolInputMap[T];
+};
+export type TypedPermissionRequestInput<T extends KnownToolName> = {
+    [K in keyof _TypedPermissionRequestInputBase<T>]: _TypedPermissionRequestInputBase<T>[K];
+} & {};
+/**
+ * Extended context for SessionStart hooks.
+ *
+ * SessionStart hooks have additional capabilities for persisting environment
+ * variables that will be available in all subsequent bash commands.
+ * @example
+ * ```typescript
+ * export default sessionStartHook({}, async (input, { logger, persistEnvVar }) => {
+ *   // Set environment variables for the session
+ *   persistEnvVar('NODE_ENV', 'development');
+ *   persistEnvVar('DEBUG', 'true');
+ *
+ *   return sessionStartOutput({});
+ * });
+ * ```
+ */
+export interface SessionStartContext extends HookContext {
+    /**
+     * Persists an environment variable for use in subsequent bash commands.
+     *
+     * This function writes a shell export statement to the `CLAUDE_ENV_FILE`,
+     * which Claude Code sources before running bash commands. This allows
+     * SessionStart hooks to configure the environment for the entire session.
+     * @param name - The environment variable name
+     * @param value - The environment variable value (will be shell-escaped)
+     * @example
+     * ```typescript
+     * persistEnvVar('NODE_ENV', 'production');
+     * persistEnvVar('API_KEY', 'secret-key');
+     * ```
+     */
+    persistEnvVar: (name: string, value: string) => void;
+    /**
+     * Persists multiple environment variables at once.
+     *
+     * This is a convenience wrapper around `persistEnvVar` for setting
+     * multiple variables in a single call.
+     * @param vars - Object mapping variable names to values
+     * @example
+     * ```typescript
+     * persistEnvVars({
+     *   NODE_ENV: 'production',
+     *   API_KEY: 'secret',
+     *   DEBUG: 'false'
+     * });
+     * ```
+     */
+    persistEnvVars: (vars: Record<string, string>) => void;
+}
+/**
+ * Handler function for a specific hook type.
+ *
+ * Receives the typed input and context, returns a specific output type.
+ * Can be async for operations that require awaiting.
+ * @template TInput - The input type for this hook
+ * @template TOutput - The specific output type for this hook
+ * @template TContext - The context type (defaults to HookContext)
+ */
+export type HookHandler<TInput, TOutput extends SpecificHookOutput, TContext extends HookContext = HookContext> = (input: TInput, context: TContext) => TOutput | null | Promise<TOutput | null>;
+/**
+ * Creates a PreToolUse hook handler.
+ *
+ * PreToolUse hooks fire before any tool is executed, allowing you to:
+ * - Inspect and validate tool inputs
+ * - Allow, deny, or modify the tool execution
+ * - Add custom permission logic
+ *
+ * **Matcher**: Matches against `tool_name` (e.g., 'Bash', 'Read', 'Write')
+ *
+ * **Typed Overload**: When the matcher is a single known tool name (Write, Edit,
+ * MultiEdit, Read, Bash, Glob, Grep), the handler receives automatically typed
+ * `toolInput` based on the tool type.
+ * @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 { preToolUseHook, preToolUseOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * // Typed overload: tool_input is automatically typed as BashInput
+ * export default preToolUseHook({ matcher: 'Bash' }, async (input, { logger }) => {
+ *   // input.tool_input.command is typed as string - no cast needed!
+ *   if (input.tool_input.command.includes('rm -rf')) {
+ *     logger.warn('Blocking destructive command', { command: input.tool_input.command });
+ *     return preToolUseOutput({
+ *       hookSpecificOutput: {
+ *         permissionDecision: 'deny',
+ *         permissionDecisionReason: 'Destructive commands are not allowed'
+ *       }
+ *     });
+ *   }
+ *
+ *   return preToolUseOutput({
+ *     hookSpecificOutput: { permissionDecision: 'allow' }
+ *   });
+ * });
+ * ```
+ * @example
+ * ```typescript
+ * // Typed overload: tool_input is automatically typed as FileWriteInput
+ * export default preToolUseHook({ matcher: 'Write' }, (input) => {
+ *   const { file_path, content } = input.tool_input; // Full autocomplete!
+ *   // ...
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#pretooluse
+ */
+export declare function preToolUseHook<T extends KnownToolName>(config: TypedHookConfigFor<T, "PreToolUse">, handler: HookHandler<TypedPreToolUseHookInput<T>, PreToolUseOutput>): HookFunction<TypedPreToolUseHookInput<T>, PreToolUseOutput>;
+export declare function preToolUseHook(config: HookConfigFor<"PreToolUse">, handler: HookHandler<PreToolUseInput, PreToolUseOutput>): HookFunction<PreToolUseInput, PreToolUseOutput>;
+/**
+ * Creates a PostToolUse hook handler.
+ *
+ * PostToolUse hooks fire after a tool executes successfully, allowing you to:
+ * - Inspect tool results
+ * - Add additional context to the conversation
+ * - Modify MCP tool output
+ *
+ * **Matcher**: Matches against `tool_name`
+ *
+ * **Typed Overload**: When the matcher is a single known tool name, the handler
+ * receives automatically typed `toolInput` based on the tool type.
+ * @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 { postToolUseHook, postToolUseOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * // Typed overload: tool_input is automatically typed as FileReadInput
+ * export default postToolUseHook({ matcher: 'Read' }, async (input, { logger }) => {
+ *   // input.tool_input.file_path is typed as string - no cast needed!
+ *   logger.info('File read completed', { filePath: input.tool_input.file_path });
+ *
+ *   return postToolUseOutput({
+ *     hookSpecificOutput: {
+ *       additionalContext: `File ${input.tool_input.file_path} was read successfully`
+ *     }
+ *   });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#posttooluse
+ */
+export declare function postToolUseHook<T extends KnownToolName>(config: TypedHookConfig<T>, handler: HookHandler<TypedPostToolUseHookInput<T>, PostToolUseOutput>): HookFunction<TypedPostToolUseHookInput<T>, PostToolUseOutput>;
+export declare function postToolUseHook(config: HookConfig, handler: HookHandler<PostToolUseInput, PostToolUseOutput>): HookFunction<PostToolUseInput, PostToolUseOutput>;
+/**
+ * Creates a PostToolUseFailure hook handler.
+ *
+ * PostToolUseFailure hooks fire after a tool execution fails, allowing you to:
+ * - Log or report tool failures
+ * - Add context about the failure
+ * - Take corrective action
+ *
+ * **Matcher**: Matches against `tool_name`
+ *
+ * **Typed Overload**: When the matcher is a single known tool name, the handler
+ * receives automatically typed `toolInput` based on the tool type.
+ * @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 { postToolUseFailureHook, postToolUseFailureOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * // Log tool failures and suggest alternatives
+ * export default postToolUseFailureHook({ matcher: 'Bash' }, async (input, { logger }) => {
+ *   // input.tool_input.command is typed as string
+ *   logger.error('Bash command failed', {
+ *     command: input.tool_input.command,
+ *     error: input.error
+ *   });
+ *
+ *   return postToolUseFailureOutput({
+ *     hookSpecificOutput: {
+ *       additionalContext: 'Please try an alternative approach'
+ *     }
+ *   });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#posttoolusefailure
+ */
+export declare function postToolUseFailureHook<T extends KnownToolName>(config: TypedHookConfig<T>, handler: HookHandler<TypedPostToolUseFailureHookInput<T>, PostToolUseFailureOutput>): HookFunction<TypedPostToolUseFailureHookInput<T>, PostToolUseFailureOutput>;
+export declare function postToolUseFailureHook(config: HookConfig, handler: HookHandler<PostToolUseFailureInput, PostToolUseFailureOutput>): HookFunction<PostToolUseFailureInput, PostToolUseFailureOutput>;
+/**
+ * Creates a PostToolBatch hook handler.
+ *
+ * PostToolBatch hooks fire exactly once after every tool call in a batch has
+ * resolved, before the next model request. Unlike PostToolUse — which fires per
+ * tool and may run concurrently for parallel tool calls — PostToolBatch receives
+ * the full batch via `input.tool_calls`, allowing you to:
+ * - Inspect or summarize all tool calls in a single turn together
+ * - Inject additional context once per batch instead of once per tool
+ *
+ * **Matcher**: No matcher support - fires once per batch
+ * @param config - Hook configuration with optional timeout (matcher is ignored)
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { postToolBatchHook, postToolBatchOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * export default postToolBatchHook({}, async (input, { logger }) => {
+ *   logger.info('Tool batch completed', { count: input.tool_calls.length });
+ *
+ *   return postToolBatchOutput({
+ *     hookSpecificOutput: {
+ *       additionalContext: `Reviewed ${input.tool_calls.length} tool calls`
+ *     }
+ *   });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#posttoolbatch
+ */
+export declare function postToolBatchHook(config: HookConfig, handler: HookHandler<PostToolBatchInput, PostToolBatchOutput>): HookFunction<PostToolBatchInput, PostToolBatchOutput>;
+/**
+ * Creates a Notification hook handler.
+ *
+ * Notification hooks fire when Claude Code sends a notification, allowing you to:
+ * - Forward notifications to external systems
+ * - Log important events
+ * - Trigger custom alerting
+ *
+ * **Matcher**: Matches against `notification_type`
+ * @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 { notificationHook, notificationOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * // Forward notifications to Slack
+ * export default notificationHook({}, async (input, { logger }) => {
+ *   logger.info('Notification received', {
+ *     type: input.notification_type,
+ *     title: input.title
+ *   });
+ *
+ *   await sendSlackMessage(input.title ?? 'Notification', input.message);
+ *
+ *   return notificationOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#notification
+ */
+export declare function notificationHook(config: HookConfig, handler: HookHandler<NotificationInput, NotificationOutput>): HookFunction<NotificationInput, NotificationOutput>;
+/**
+ * Creates a UserPromptSubmit hook handler.
+ *
+ * UserPromptSubmit hooks fire when a user submits a prompt, allowing you to:
+ * - Add additional context or instructions
+ * - Log user interactions
+ * - Validate or transform prompts
+ *
+ * **Matcher**: No matcher support - fires on all prompt submissions
+ * @param config - Hook configuration with optional timeout (matcher is ignored)
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { userPromptSubmitHook, userPromptSubmitOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * // Add project context to every prompt
+ * export default userPromptSubmitHook({}, async (input, { logger }) => {
+ *   logger.debug('User prompt submitted', { promptLength: input.prompt.length });
+ *
+ *   const projectContext = await getProjectContext();
+ *
+ *   return userPromptSubmitOutput({
+ *     additionalContext: projectContext
+ *   });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#userpromptsubmit
+ */
+export declare function userPromptSubmitHook(config: HookConfig, handler: HookHandler<UserPromptSubmitInput, UserPromptSubmitOutput>): HookFunction<UserPromptSubmitInput, UserPromptSubmitOutput>;
+/**
+ * Creates a UserPromptExpansion hook handler.
+ *
+ * UserPromptExpansion hooks fire when a user prompt is expanded from a slash
+ * command or MCP prompt, allowing you to:
+ * - Add context based on the command being invoked
+ * - Log slash command and MCP prompt usage
+ * - Observe prompt expansion events
+ *
+ * **Matcher**: No matcher support - fires on all prompt expansions
+ * @param config - Hook configuration with optional timeout (matcher is ignored)
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { userPromptExpansionHook, userPromptExpansionOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * // Add context when a slash command is invoked
+ * export default userPromptExpansionHook({}, async (input, { logger }) => {
+ *   logger.debug('Prompt expanded', { type: input.expansion_type, command: input.command_name });
+ *
+ *   return userPromptExpansionOutput({
+ *     hookSpecificOutput: {
+ *       additionalContext: `Command: ${input.command_name}`
+ *     }
+ *   });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#userpromptexpansion
+ */
+export declare function userPromptExpansionHook(config: HookConfig, handler: HookHandler<UserPromptExpansionInput, UserPromptExpansionOutput>): HookFunction<UserPromptExpansionInput, UserPromptExpansionOutput>;
+/**
+ * Creates a SessionStart hook handler.
+ *
+ * SessionStart hooks fire when a Claude Code session starts or restarts,
+ * allowing you to:
+ * - Initialize session state
+ * - Inject context or instructions
+ * - Persist environment variables for subsequent bash commands
+ * - Set up logging or monitoring
+ *
+ * **Matcher**: Matches against `source` ('startup', 'resume', 'clear', 'compact')
+ *
+ * **Context**: SessionStart hooks receive an extended context with `persistEnvVar`
+ * and `persistEnvVars` functions for setting environment variables.
+ * @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 { sessionStartHook, sessionStartOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * // Persist environment variables for the session
+ * export default sessionStartHook({ matcher: 'startup' }, async (input, { logger, persistEnvVar }) => {
+ *   logger.info('New session started', {
+ *     sessionId: input.session_id,
+ *     cwd: input.cwd
+ *   });
+ *
+ *   // Set environment variables for all subsequent bash commands
+ *   persistEnvVar('NODE_ENV', 'development');
+ *   persistEnvVar('DEBUG', 'true');
+ *
+ *   return sessionStartOutput({});
+ * });
+ * ```
+ * @example
+ * ```typescript
+ * // Set multiple environment variables at once
+ * export default sessionStartHook({}, async (input, { persistEnvVars }) => {
+ *   persistEnvVars({
+ *     NODE_ENV: 'production',
+ *     API_KEY: 'secret',
+ *     DEBUG: 'false'
+ *   });
+ *
+ *   return sessionStartOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#sessionstart
+ */
+export declare function sessionStartHook(config: HookConfig, handler: HookHandler<SessionStartInput, SessionStartOutput, SessionStartContext>): HookFunction<SessionStartInput, SessionStartOutput, SessionStartContext>;
+/**
+ * Creates a SessionEnd hook handler.
+ *
+ * SessionEnd hooks fire when a Claude Code session ends, allowing you to:
+ * - Clean up session resources
+ * - Log session metrics
+ * - Persist session state
+ *
+ * **Matcher**: Matches against `reason` (the exit reason string)
+ * @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 { sessionEndHook, sessionEndOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * // Log session end and clean up
+ * export default sessionEndHook({}, async (input, { logger }) => {
+ *   logger.info('Session ended', {
+ *     sessionId: input.session_id,
+ *     reason: input.reason
+ *   });
+ *
+ *   await cleanupSessionResources(input.session_id);
+ *
+ *   return sessionEndOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#sessionend
+ */
+export declare function sessionEndHook(config: HookConfig, handler: HookHandler<SessionEndInput, SessionEndOutput>): HookFunction<SessionEndInput, SessionEndOutput>;
+/**
+ * Creates a Stop hook handler.
+ *
+ * Stop hooks fire 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
+ *
+ * **Matcher**: No matcher support - fires on all stop events
+ * @param config - Hook configuration with optional timeout (matcher is ignored)
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { stopHook, stopOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * // Block stop if there are pending changes
+ * export default stopHook({}, async (input, { logger }) => {
+ *   const pendingChanges = await checkPendingChanges();
+ *
+ *   if (pendingChanges.length > 0) {
+ *     logger.warn('Blocking stop due to pending changes', {
+ *       count: pendingChanges.length
+ *     });
+ *
+ *     return stopOutput({
+ *       decision: 'block',
+ *       reason: `There are ${pendingChanges.length} uncommitted changes`,
+ *       systemMessage: 'Please commit or discard changes before stopping'
+ *     });
+ *   }
+ *
+ *   logger.info('Approving stop');
+ *   return stopOutput({ decision: 'approve' });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#stop
+ */
+export declare function stopHook(config: HookConfigFor<"Stop">, handler: HookHandler<StopInput, StopOutput>): HookFunction<StopInput, StopOutput>;
+/**
+ * Creates a StopFailure hook handler.
+ *
+ * StopFailure hooks fire when Claude Code encounters an error while stopping
+ * (e.g., API errors, authentication failures, rate limits), allowing you to:
+ * - Log stop failure events and error details
+ * - Alert on unexpected session termination errors
+ * - Observe what error caused the failure
+ *
+ * **Matcher**: No matcher support - fires on all stop failure events
+ * @param config - Hook configuration with optional timeout (matcher is ignored)
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { stopFailureHook, stopFailureOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * export default stopFailureHook({}, async (input, { logger }) => {
+ *   logger.error('Session stopped due to error', {
+ *     error: input.error,
+ *     details: input.error_details
+ *   });
+ *   return stopFailureOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#stopfailure
+ */
+export declare function stopFailureHook(config: HookConfig, handler: HookHandler<StopFailureInput, StopFailureOutput>): HookFunction<StopFailureInput, StopFailureOutput>;
+/**
+ * Creates a SubagentStart hook handler.
+ *
+ * SubagentStart hooks fire when a subagent (Agent tool) starts, allowing you to:
+ * - Inject context for the subagent
+ * - Log subagent invocations
+ * - Configure subagent behavior
+ *
+ * **Matcher**: Matches against `agent_type` (e.g., 'explore', 'codebase-analysis')
+ * @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 { subagentStartHook, subagentStartOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * // Add context for explore subagents
+ * export default subagentStartHook({ matcher: 'explore' }, async (input, { logger }) => {
+ *   logger.info('Explore subagent starting', {
+ *     agentId: input.agent_id,
+ *     agentType: input.agent_type
+ *   });
+ *
+ *   return subagentStartOutput({
+ *     additionalContext: 'Focus on finding patterns and conventions'
+ *   });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#subagentstart
+ */
+export declare function subagentStartHook(config: HookConfig, handler: HookHandler<SubagentStartInput, SubagentStartOutput>): HookFunction<SubagentStartInput, SubagentStartOutput>;
+/**
+ * Creates a SubagentStop hook handler.
+ *
+ * SubagentStop hooks fire when a subagent completes or stops, allowing you to:
+ * - Block the subagent from stopping
+ * - Process subagent results
+ * - Clean up subagent resources
+ * - Log subagent completion
+ *
+ * **Matcher**: Matches against `agent_type` (e.g., 'explore', 'codebase-analysis')
+ * @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 { subagentStopHook, subagentStopOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * // Block explore subagents if task incomplete
+ * export default subagentStopHook({ matcher: 'explore' }, async (input, { logger }) => {
+ *   logger.info('Subagent stopping', {
+ *     agentId: input.agent_id,
+ *     agentType: input.agent_type
+ *   });
+ *
+ *   // Block if transcript shows incomplete work
+ *   return subagentStopOutput({
+ *     decision: 'block',
+ *     reason: 'Please verify exploration is complete'
+ *   });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#subagentstop
+ */
+export declare function subagentStopHook(config: HookConfigFor<"SubagentStop">, handler: HookHandler<SubagentStopInput, SubagentStopOutput>): HookFunction<SubagentStopInput, SubagentStopOutput>;
+/**
+ * Creates a PreCompact hook handler.
+ *
+ * PreCompact hooks fire before context compaction occurs, allowing you to:
+ * - Preserve important information before compaction
+ * - Log compaction events
+ * - Modify custom instructions for the compacted context
+ *
+ * **Matcher**: Matches against `trigger` ('manual', 'auto')
+ * @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 { preCompactHook, preCompactOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * // Log compaction events and preserve context
+ * export default preCompactHook({}, async (input, { logger }) => {
+ *   logger.info('Context compaction triggered', {
+ *     trigger: input.trigger,
+ *     hasCustomInstructions: input.custom_instructions !== null
+ *   });
+ *
+ *   return preCompactOutput({
+ *     systemMessage: 'Remember: strict mode is enabled'
+ *   });
+ * });
+ * ```
+ * @example
+ * ```typescript
+ * // Only handle manual compaction
+ * export default preCompactHook({ matcher: 'manual' }, async (input, { logger }) => {
+ *   logger.info('Manual compaction requested');
+ *   return preCompactOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#precompact
+ */
+export declare function preCompactHook(config: HookConfig, handler: HookHandler<PreCompactInput, PreCompactOutput>): HookFunction<PreCompactInput, PreCompactOutput>;
+/**
+ * Creates a PostCompact hook handler.
+ *
+ * PostCompact hooks fire after context compaction completes, allowing you to:
+ * - Observe the compaction summary and details
+ * - Log compaction events
+ * - React to the new compacted state
+ *
+ * **Matcher**: Matches against `trigger` ('manual', 'auto')
+ * @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 { postCompactHook, postCompactOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * export default postCompactHook({}, async (input, { logger }) => {
+ *   logger.info('Context compaction completed', {
+ *     trigger: input.trigger,
+ *     summary: input.compact_summary
+ *   });
+ *   return postCompactOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#postcompact
+ */
+export declare function postCompactHook(config: HookConfig, handler: HookHandler<PostCompactInput, PostCompactOutput>): HookFunction<PostCompactInput, PostCompactOutput>;
+/**
+ * Creates a PermissionRequest hook handler.
+ *
+ * PermissionRequest hooks fire 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
+ *
+ * **Matcher**: Matches against `tool_name`
+ *
+ * **Typed Overload**: When the matcher is a single known tool name, the handler
+ * receives automatically typed `toolInput` based on the tool type.
+ * @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 { permissionRequestHook, permissionRequestOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * // Typed overload: tool_input is automatically typed as FileReadInput
+ * export default permissionRequestHook({ matcher: 'Read' }, async (input, { logger }) => {
+ *   // input.tool_input.file_path is typed as string - no cast needed!
+ *   if (input.tool_input.file_path.startsWith('/allowed/')) {
+ *     logger.info('Auto-approving read in allowed directory', { filePath: input.tool_input.file_path });
+ *     return permissionRequestOutput({
+ *       hookSpecificOutput: { decision: { behavior: 'allow' } }
+ *     });
+ *   }
+ *
+ *   // Fall through to normal permission prompt
+ *   return permissionRequestOutput({});
+ * });
+ * ```
+ * @example
+ * ```typescript
+ * // Typed overload: tool_input is automatically typed as BashInput
+ * export default permissionRequestHook({ matcher: 'Bash' }, async (input, { logger }) => {
+ *   // input.tool_input.command is typed as string - no cast needed!
+ *   if (input.tool_input.command.includes('sudo')) {
+ *     logger.warn('Denying sudo command', { command: input.tool_input.command });
+ *     return permissionRequestOutput({
+ *       hookSpecificOutput: {
+ *         decision: {
+ *           behavior: 'deny',
+ *           message: 'sudo commands are not allowed',
+ *           interrupt: true
+ *         }
+ *       }
+ *     });
+ *   }
+ *
+ *   return permissionRequestOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#permissionrequest
+ */
+export declare function permissionRequestHook<T extends KnownToolName>(config: TypedHookConfigFor<T, "PermissionRequest">, handler: HookHandler<TypedPermissionRequestInput<T>, PermissionRequestOutput>): HookFunction<TypedPermissionRequestInput<T>, PermissionRequestOutput>;
+export declare function permissionRequestHook(config: HookConfigFor<"PermissionRequest">, handler: HookHandler<PermissionRequestInput, PermissionRequestOutput>): HookFunction<PermissionRequestInput, PermissionRequestOutput>;
+/**
+ * Creates a PermissionDenied hook handler.
+ *
+ * PermissionDenied hooks fire when a permission request is denied (either by the
+ * user or by a PermissionRequest hook), allowing you to:
+ * - Log permission denials for auditing
+ * - React to denied tool executions
+ * - Optionally request a retry via the output
+ *
+ * **Matcher**: Matches against `tool_name`
+ * @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 { permissionDeniedHook, permissionDeniedOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * // Log all permission denials
+ * export default permissionDeniedHook({}, async (input, { logger }) => {
+ *   logger.warn('Permission denied', {
+ *     toolName: input.tool_name,
+ *     reason: input.reason
+ *   });
+ *   return permissionDeniedOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#permissiondenied
+ */
+export declare function permissionDeniedHook(config: HookConfig, handler: HookHandler<PermissionDeniedInput, PermissionDeniedOutput>): HookFunction<PermissionDeniedInput, PermissionDeniedOutput>;
+/**
+ * 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/agent-hooks/claude-code';
+ *
+ * // 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>;
+/**
+ * Creates a TeammateIdle hook handler.
+ *
+ * TeammateIdle hooks fire when a teammate in a team is about to go idle,
+ * allowing you to:
+ * - Assign work to idle teammates
+ * - Log team activity
+ * - Coordinate multi-agent workflows
+ *
+ * **Matcher**: No matcher support - fires on all teammate idle events
+ * @param config - Hook configuration with optional timeout (matcher is ignored)
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { teammateIdleHook, teammateIdleOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * // Log when teammates go idle
+ * export default teammateIdleHook({}, async (input, { logger }) => {
+ *   logger.info('Teammate going idle', {
+ *     teammateName: input.teammate_name,
+ *     teamName: input.team_name
+ *   });
+ *
+ *   return teammateIdleOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#teammateidle
+ */
+export declare function teammateIdleHook(config: HookConfig, handler: HookHandler<TeammateIdleInput, TeammateIdleOutput>): HookFunction<TeammateIdleInput, TeammateIdleOutput>;
+/**
+ * Creates a TaskCreated hook handler.
+ *
+ * TaskCreated hooks fire when a new task is created and assigned to a teammate,
+ * allowing you to:
+ * - Observe task creation events
+ * - Log task assignments for auditing
+ * - React to new work being assigned
+ *
+ * **Matcher**: No matcher support - fires on all task creation events
+ * @param config - Hook configuration with optional timeout (matcher is ignored)
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { taskCreatedHook, taskCreatedOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * // Log task creation
+ * export default taskCreatedHook({}, async (input, { logger }) => {
+ *   logger.info('Task created', {
+ *     taskId: input.task_id,
+ *     taskSubject: input.task_subject
+ *   });
+ *
+ *   return taskCreatedOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#taskcreated
+ */
+export declare function taskCreatedHook(config: HookConfig, handler: HookHandler<TaskCreatedInput, TaskCreatedOutput>): HookFunction<TaskCreatedInput, TaskCreatedOutput>;
+/**
+ * Creates a TaskCompleted hook handler.
+ *
+ * TaskCompleted hooks fire when a task is being marked as completed,
+ * allowing you to:
+ * - Verify task completion
+ * - Log task metrics
+ * - Trigger follow-up actions
+ *
+ * **Matcher**: No matcher support - fires on all task completion events
+ * @param config - Hook configuration with optional timeout (matcher is ignored)
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { taskCompletedHook, taskCompletedOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * // Log task completion
+ * export default taskCompletedHook({}, async (input, { logger }) => {
+ *   logger.info('Task completed', {
+ *     taskId: input.task_id,
+ *     taskSubject: input.task_subject
+ *   });
+ *
+ *   return taskCompletedOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#taskcompleted
+ */
+export declare function taskCompletedHook(config: HookConfig, handler: HookHandler<TaskCompletedInput, TaskCompletedOutput>): HookFunction<TaskCompletedInput, TaskCompletedOutput>;
+/**
+ * Creates an Elicitation hook handler.
+ *
+ * Elicitation hooks fire when an MCP server requests user input, allowing you to:
+ * - Accept, decline, or cancel elicitation requests programmatically
+ * - Provide structured form input or URL-based auth responses
+ * - Log or audit elicitation requests
+ *
+ * **Matcher**: No matcher support - fires on all elicitation events
+ * @param config - Hook configuration with optional timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { elicitationHook, elicitationOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * export default elicitationHook({}, async (input, { logger }) => {
+ *   logger.info('Elicitation request', { server: input.mcp_server_name });
+ *   return elicitationOutput({
+ *     hookSpecificOutput: { action: 'accept', content: { approved: true } }
+ *   });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#elicitation
+ */
+export declare function elicitationHook(config: HookConfig, handler: HookHandler<ElicitationInput, ElicitationOutput>): HookFunction<ElicitationInput, ElicitationOutput>;
+/**
+ * Creates an ElicitationResult hook handler.
+ *
+ * ElicitationResult hooks fire with the result of an MCP elicitation request,
+ * allowing you to:
+ * - Observe elicitation outcomes
+ * - Modify the result before it is returned to the MCP server
+ * - Log elicitation completions
+ *
+ * **Matcher**: No matcher support - fires on all elicitation result events
+ * @param config - Hook configuration with optional timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { elicitationResultHook, elicitationResultOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * export default elicitationResultHook({}, async (input, { logger }) => {
+ *   logger.info('Elicitation result', { action: input.action });
+ *   return elicitationResultOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#elicitationresult
+ */
+export declare function elicitationResultHook(config: HookConfig, handler: HookHandler<ElicitationResultInput, ElicitationResultOutput>): HookFunction<ElicitationResultInput, ElicitationResultOutput>;
+/**
+ * Creates a ConfigChange hook handler.
+ *
+ * ConfigChange hooks fire when Claude Code configuration changes, allowing you to:
+ * - React to settings file changes
+ * - Log or audit configuration changes
+ * - Apply custom logic when settings are updated
+ *
+ * **Matcher**: Matches against `source` ('user_settings', 'project_settings', etc.)
+ * @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 { configChangeHook, configChangeOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * export default configChangeHook({}, async (input, { logger }) => {
+ *   logger.info('Config changed', { source: input.source, file: input.file_path });
+ *   return configChangeOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#configchange
+ */
+export declare function configChangeHook(config: HookConfig, handler: HookHandler<ConfigChangeInput, ConfigChangeOutput>): HookFunction<ConfigChangeInput, ConfigChangeOutput>;
+/**
+ * Creates an InstructionsLoaded hook handler.
+ *
+ * InstructionsLoaded hooks fire when a CLAUDE.md or similar instructions file
+ * is loaded, allowing you to:
+ * - React to instructions being applied
+ * - Log which instruction files are active
+ * - Observe the instruction loading hierarchy
+ *
+ * **Matcher**: No matcher support - fires on all instruction load events
+ * @param config - Hook configuration with optional timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { instructionsLoadedHook, instructionsLoadedOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * export default instructionsLoadedHook({}, async (input, { logger }) => {
+ *   logger.info('Instructions loaded', { file: input.file_path, type: input.memory_type });
+ *   return instructionsLoadedOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#instructionsloaded
+ */
+export declare function instructionsLoadedHook(config: HookConfig, handler: HookHandler<InstructionsLoadedInput, InstructionsLoadedOutput>): HookFunction<InstructionsLoadedInput, InstructionsLoadedOutput>;
+/**
+ * Creates a WorktreeCreate hook handler.
+ *
+ * WorktreeCreate hooks fire when a git worktree is created, allowing you to:
+ * - Set up worktree-specific configuration
+ * - Log worktree creation events
+ * - Initialize worktree resources
+ *
+ * **Matcher**: No matcher support - fires on all worktree creation events
+ * @param config - Hook configuration with optional timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { worktreeCreateHook, worktreeCreateOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * export default worktreeCreateHook({}, async (input, { logger }) => {
+ *   const worktreePath = `${input.cwd}/.worktrees/${input.name}`;
+ *   logger.info('Worktree created', { name: input.name, worktreePath });
+ *   // WorktreeCreate is a command hook: the path is written to stdout as plain text.
+ *   return worktreeCreateOutput({ worktreePath });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#worktreecreate
+ */
+export declare function worktreeCreateHook(config: HookConfigFor<"WorktreeCreate">, handler: HookHandler<WorktreeCreateInput, WorktreeCreateOutput>): HookFunction<WorktreeCreateInput, WorktreeCreateOutput>;
+/**
+ * Creates a WorktreeRemove hook handler.
+ *
+ * WorktreeRemove hooks fire when a git worktree is removed, allowing you to:
+ * - Clean up worktree-specific resources
+ * - Log worktree removal events
+ *
+ * **Matcher**: No matcher support - fires on all worktree removal events
+ * @param config - Hook configuration with optional timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { worktreeRemoveHook, worktreeRemoveOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * export default worktreeRemoveHook({}, async (input, { logger }) => {
+ *   logger.info('Worktree removed', { path: input.worktree_path });
+ *   return worktreeRemoveOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#worktreeremove
+ */
+export declare function worktreeRemoveHook(config: HookConfigFor<"WorktreeRemove">, handler: HookHandler<WorktreeRemoveInput, WorktreeRemoveOutput>): HookFunction<WorktreeRemoveInput, WorktreeRemoveOutput>;
+/**
+ * Creates a CwdChanged hook handler.
+ *
+ * CwdChanged hooks fire when Claude Code's current working directory changes,
+ * allowing you to:
+ * - React to directory changes within a session
+ * - Update file watchers or environment state
+ * - Return `watchPaths` via `hookSpecificOutput` to register paths for FileChanged events
+ *
+ * **Matcher**: No matcher support - fires on all cwd change events
+ * @param config - Hook configuration with optional timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { cwdChangedHook, cwdChangedOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * export default cwdChangedHook({}, async (input, { logger }) => {
+ *   logger.info('Working directory changed', { from: input.old_cwd, to: input.new_cwd });
+ *   return cwdChangedOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#cwdchanged
+ */
+export declare function cwdChangedHook(config: HookConfig, handler: HookHandler<CwdChangedInput, CwdChangedOutput>): HookFunction<CwdChangedInput, CwdChangedOutput>;
+/**
+ * Creates a FileChanged hook handler.
+ *
+ * FileChanged hooks fire when a watched file changes on disk, allowing you to:
+ * - React to file system changes during a session
+ * - Invalidate caches or reload configuration
+ * - Return `watchPaths` via `hookSpecificOutput` to update the set of watched paths
+ *
+ * The input `event` field indicates the type of change:
+ * - `'change'` - File contents changed
+ * - `'add'` - File was created
+ * - `'unlink'` - File was deleted
+ *
+ * **Matcher**: No matcher support - fires on all file change events
+ * @param config - Hook configuration with optional timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { fileChangedHook, fileChangedOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * export default fileChangedHook({}, async (input, { logger }) => {
+ *   logger.info('File changed', { path: input.file_path, event: input.event });
+ *   return fileChangedOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#filechanged
+ */
+export declare function fileChangedHook(config: HookConfig, handler: HookHandler<FileChangedInput, FileChangedOutput>): HookFunction<FileChangedInput, FileChangedOutput>;
+/**
+ * Creates a MessageDisplay hook handler.
+ *
+ * MessageDisplay hooks fire with each batch of newly completed lines while an
+ * assistant message streams. Display-only: the stored message and what the model
+ * sees are untouched. Allows you to:
+ * - Replace the delta shown on screen with custom content via `displayContent`
+ * - Observe and log message streaming events
+ *
+ * The input carries `turn_id`, `message_id`, `index`, `final`, and `delta` fields.
+ * The `final` flag indicates the last flush of a message — its `delta` is empty
+ * when the message ends on a newline; treat `final` as the end-of-message signal.
+ *
+ * **Matcher**: No matcher support - fires on all message display events
+ * @param config - Hook configuration with optional timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { messageDisplayHook, messageDisplayOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * export default messageDisplayHook({}, async (input, { logger }) => {
+ *   if (input.final) {
+ *     logger.info('Message complete', { messageId: input.message_id });
+ *   }
+ *   return messageDisplayOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#messagedisplay
+ */
+export declare function messageDisplayHook(config: HookConfig, handler: HookHandler<MessageDisplayInput, MessageDisplayOutput>): HookFunction<MessageDisplayInput, MessageDisplayOutput>;