@goodfoot/agent-hooks 1.0.0

package/dist/agents/claude-code/hooks.js

@@ -0,0 +1,1000 @@
+/**
+ * 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 { defineHook } from "../../core/define-hook.js";
+import { persistEnvVar, persistEnvVars } from "../../core/env.js";
+import { logger } from "../../core/logger.js";
+import { ADVISORY_EVENTS } from "./events.js";
+// ============================================================================
+// Generic Factory
+// ============================================================================
+/**
+ * The runtime policy gate injected into every Claude Code factory: rejects
+ * `unexpectedError: "continue"` at factory-call time for any event not on
+ * the advisory allow-list ({@link ADVISORY_EVENTS}). Every other policy
+ * value (including undefined, meaning the default `"error"`) is accepted
+ * for every event. {@link defineHook} fails closed — throws instead of
+ * creating the hook — when this gate returns false.
+ */
+const advisoryPolicyGate = (eventName, policy) => policy !== "continue" || ADVISORY_EVENTS.includes(eventName);
+/**
+ * Builds the handler context for a SessionStart hook: the extended context
+ * carries the env-persistence utilities alongside the logger. Bound at
+ * factory time via {@link defineHook}'s `createContext` seam.
+ */
+function createSessionStartContext() {
+    return { logger, persistEnvVar, persistEnvVars };
+}
+/**
+ * Creates a hook function for a specific hook type on the shared core.
+ *
+ * This is the internal implementation used by all typed factories. It binds
+ * the event name, injects the advisory allow-list policy gate, and attaches
+ * the SessionStart-specific context factory where applicable.
+ * @param hookEventName - The hook event name
+ * @param config - Hook configuration
+ * @param handler - The handler function to wrap
+ * @returns A wrapped hook function carrying its metadata for the driver
+ * @internal
+ */
+function createHookFunction(hookEventName, config, handler) {
+    const isSessionStart = hookEventName === "SessionStart";
+    return defineHook(hookEventName, isSessionStart ? { ...config, createContext: createSessionStartContext } : config, handler, advisoryPolicyGate);
+}
+/** @inheritdoc */
+export function preToolUseHook(config, handler) {
+    return createHookFunction("PreToolUse", config, handler);
+}
+/** @inheritdoc */
+export function postToolUseHook(config, handler) {
+    return createHookFunction("PostToolUse", config, handler);
+}
+/** @inheritdoc */
+export function postToolUseFailureHook(config, handler) {
+    return createHookFunction("PostToolUseFailure", config, handler);
+}
+// ============================================================================
+// PostToolBatch Hook Factory
+// ============================================================================
+/**
+ * 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 function postToolBatchHook(config, handler) {
+    return createHookFunction("PostToolBatch", config, handler);
+}
+// ============================================================================
+// Notification Hook Factory
+// ============================================================================
+/**
+ * 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 function notificationHook(config, handler) {
+    return createHookFunction("Notification", config, handler);
+}
+// ============================================================================
+// UserPromptSubmit Hook Factory
+// ============================================================================
+/**
+ * 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 function userPromptSubmitHook(config, handler) {
+    return createHookFunction("UserPromptSubmit", config, handler);
+}
+// ============================================================================
+// UserPromptExpansion Hook Factory
+// ============================================================================
+/**
+ * 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 function userPromptExpansionHook(config, handler) {
+    return createHookFunction("UserPromptExpansion", config, handler);
+}
+// ============================================================================
+// SessionStart Hook Factory
+// ============================================================================
+/**
+ * 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 function sessionStartHook(config, handler) {
+    return createHookFunction("SessionStart", config, handler);
+}
+// ============================================================================
+// SessionEnd Hook Factory
+// ============================================================================
+/**
+ * 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 function sessionEndHook(config, handler) {
+    return createHookFunction("SessionEnd", config, handler);
+}
+// ============================================================================
+// Stop Hook Factory
+// ============================================================================
+/**
+ * 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 function stopHook(config, handler) {
+    return createHookFunction("Stop", config, handler);
+}
+// ============================================================================
+// StopFailure Hook Factory
+// ============================================================================
+/**
+ * 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 function stopFailureHook(config, handler) {
+    return createHookFunction("StopFailure", config, handler);
+}
+// ============================================================================
+// SubagentStart Hook Factory
+// ============================================================================
+/**
+ * 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 function subagentStartHook(config, handler) {
+    return createHookFunction("SubagentStart", config, handler);
+}
+// ============================================================================
+// SubagentStop Hook Factory
+// ============================================================================
+/**
+ * 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 function subagentStopHook(config, handler) {
+    return createHookFunction("SubagentStop", config, handler);
+}
+// ============================================================================
+// PreCompact Hook Factory
+// ============================================================================
+/**
+ * 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 function preCompactHook(config, handler) {
+    return createHookFunction("PreCompact", config, handler);
+}
+// ============================================================================
+// PostCompact Hook Factory
+// ============================================================================
+/**
+ * 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 function postCompactHook(config, handler) {
+    return createHookFunction("PostCompact", config, handler);
+}
+/** @inheritdoc */
+export function permissionRequestHook(config, handler) {
+    return createHookFunction("PermissionRequest", config, handler);
+}
+// ============================================================================
+// PermissionDenied Hook Factory
+// ============================================================================
+/**
+ * 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 function permissionDeniedHook(config, handler) {
+    return createHookFunction("PermissionDenied", 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/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 function setupHook(config, handler) {
+    return createHookFunction("Setup", config, handler);
+}
+// ============================================================================
+// TeammateIdle Hook Factory
+// ============================================================================
+/**
+ * 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 function teammateIdleHook(config, handler) {
+    return createHookFunction("TeammateIdle", config, handler);
+}
+// ============================================================================
+// TaskCreated Hook Factory
+// ============================================================================
+/**
+ * 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 function taskCreatedHook(config, handler) {
+    return createHookFunction("TaskCreated", config, handler);
+}
+// ============================================================================
+// TaskCompleted Hook Factory
+// ============================================================================
+/**
+ * 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 function taskCompletedHook(config, handler) {
+    return createHookFunction("TaskCompleted", config, handler);
+}
+// ============================================================================
+// Elicitation Hook Factory
+// ============================================================================
+/**
+ * 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 function elicitationHook(config, handler) {
+    return createHookFunction("Elicitation", config, handler);
+}
+// ============================================================================
+// ElicitationResult Hook Factory
+// ============================================================================
+/**
+ * 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 function elicitationResultHook(config, handler) {
+    return createHookFunction("ElicitationResult", config, handler);
+}
+// ============================================================================
+// ConfigChange Hook Factory
+// ============================================================================
+/**
+ * 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 function configChangeHook(config, handler) {
+    return createHookFunction("ConfigChange", config, handler);
+}
+// ============================================================================
+// InstructionsLoaded Hook Factory
+// ============================================================================
+/**
+ * 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 function instructionsLoadedHook(config, handler) {
+    return createHookFunction("InstructionsLoaded", config, handler);
+}
+// ============================================================================
+// WorktreeCreate Hook Factory
+// ============================================================================
+/**
+ * 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 function worktreeCreateHook(config, handler) {
+    return createHookFunction("WorktreeCreate", config, handler);
+}
+// ============================================================================
+// WorktreeRemove Hook Factory
+// ============================================================================
+/**
+ * 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 function worktreeRemoveHook(config, handler) {
+    return createHookFunction("WorktreeRemove", config, handler);
+}
+// ============================================================================
+// CwdChanged Hook Factory
+// ============================================================================
+/**
+ * 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 function cwdChangedHook(config, handler) {
+    return createHookFunction("CwdChanged", config, handler);
+}
+// ============================================================================
+// FileChanged Hook Factory
+// ============================================================================
+/**
+ * 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 function fileChangedHook(config, handler) {
+    return createHookFunction("FileChanged", config, handler);
+}
+// ============================================================================
+// MessageDisplay Hook Factory
+// ============================================================================
+/**
+ * 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 function messageDisplayHook(config, handler) {
+    return createHookFunction("MessageDisplay", config, handler);
+}