@goodfoot/agent-hooks 1.0.0

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

@@ -0,0 +1,1160 @@
+/**
+ * Output types and builders for Claude Code hooks.
+ *
+ * Provides type-safe output builder functions for all 30 hook types. Each builder
+ * accepts options that match the wire format expected by Claude Code, with types
+ * derived from the Claude Agent SDK's `SyncHookJSONOutput` type.
+ * @see https://code.claude.com/docs/en/hooks
+ * @module
+ */
+import type { CwdChangedHookSpecificOutput as SDKCwdChangedHookSpecificOutput, ElicitationHookSpecificOutput as SDKElicitationHookSpecificOutput, ElicitationResultHookSpecificOutput as SDKElicitationResultHookSpecificOutput, FileChangedHookSpecificOutput as SDKFileChangedHookSpecificOutput, MessageDisplayHookSpecificOutput as SDKMessageDisplayHookSpecificOutput, NotificationHookSpecificOutput as SDKNotificationHookSpecificOutput, PermissionDeniedHookSpecificOutput as SDKPermissionDeniedHookSpecificOutput, PermissionRequestHookSpecificOutput as SDKPermissionRequestHookSpecificOutput, PostToolBatchHookSpecificOutput as SDKPostToolBatchHookSpecificOutput, PostToolUseFailureHookSpecificOutput as SDKPostToolUseFailureHookSpecificOutput, PostToolUseHookSpecificOutput as SDKPostToolUseHookSpecificOutput, PreToolUseHookSpecificOutput as SDKPreToolUseHookSpecificOutput, SessionStartHookSpecificOutput as SDKSessionStartHookSpecificOutput, SetupHookSpecificOutput as SDKSetupHookSpecificOutput, SubagentStartHookSpecificOutput as SDKSubagentStartHookSpecificOutput, SyncHookJSONOutput as SDKSyncHookJSONOutput, UserPromptExpansionHookSpecificOutput as SDKUserPromptExpansionHookSpecificOutput, UserPromptSubmitHookSpecificOutput as SDKUserPromptSubmitHookSpecificOutput, WorktreeCreateHookSpecificOutput as SDKWorktreeCreateHookSpecificOutput } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * Exit codes used by Claude Code hooks.
+ *
+ * | Exit Code | Name | When Used | Claude Code Behavior |
+ * |-----------|------|-----------|---------------------|
+ * | 0 | Success | Handler returns normally | Continue, parse stdout as JSON |
+ * | 1 | Error | Invalid input, non-blocking error | Non-blocking, stderr to user only |
+ * | 2 | Block | Handler throws OR `stopReason` set | Blocking, stderr shown to Claude |
+ */
+export declare const EXIT_CODES: {
+    /** Handler completed successfully. Claude Code parses stdout as JSON. */
+    readonly SUCCESS: 0;
+    /** Non-blocking error occurred (e.g., invalid input). stderr shown to user only. */
+    readonly ERROR: 1;
+    /** Handler threw exception OR blocking action requested. stderr shown to Claude. */
+    readonly BLOCK: 2;
+};
+/**
+ * Exit code type.
+ */
+export type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];
+/**
+ * Re-export the SDK's SyncHookJSONOutput type.
+ */
+/**
+ * Re-export SDK hook-specific output types (includes hookEventName discriminator).
+ */
+export type { SDKCwdChangedHookSpecificOutput, SDKElicitationHookSpecificOutput, SDKElicitationResultHookSpecificOutput, SDKFileChangedHookSpecificOutput, SDKMessageDisplayHookSpecificOutput, SDKNotificationHookSpecificOutput, SDKPermissionDeniedHookSpecificOutput, SDKPermissionRequestHookSpecificOutput, SDKPostToolUseFailureHookSpecificOutput, SDKPostToolUseHookSpecificOutput, SDKPreToolUseHookSpecificOutput, SDKSessionStartHookSpecificOutput, SDKSetupHookSpecificOutput, SDKSubagentStartHookSpecificOutput, SDKSyncHookJSONOutput, SDKUserPromptSubmitHookSpecificOutput, };
+/**
+ * PreToolUse hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type PreToolUseHookSpecificOutput = Omit<SDKPreToolUseHookSpecificOutput, "hookEventName">;
+/**
+ * PostToolUse hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type PostToolUseHookSpecificOutput = Omit<SDKPostToolUseHookSpecificOutput, "hookEventName">;
+/**
+ * PostToolUseFailure hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type PostToolUseFailureHookSpecificOutput = Omit<SDKPostToolUseFailureHookSpecificOutput, "hookEventName">;
+/**
+ * PostToolBatch hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type PostToolBatchHookSpecificOutput = Omit<SDKPostToolBatchHookSpecificOutput, "hookEventName">;
+/**
+ * UserPromptExpansion hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type UserPromptExpansionHookSpecificOutput = Omit<SDKUserPromptExpansionHookSpecificOutput, "hookEventName">;
+/**
+ * UserPromptSubmit hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type UserPromptSubmitHookSpecificOutput = Omit<SDKUserPromptSubmitHookSpecificOutput, "hookEventName">;
+/**
+ * SessionStart hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type SessionStartHookSpecificOutput = Omit<SDKSessionStartHookSpecificOutput, "hookEventName">;
+/**
+ * SubagentStart hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type SubagentStartHookSpecificOutput = Omit<SDKSubagentStartHookSpecificOutput, "hookEventName">;
+/**
+ * PermissionRequest hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type PermissionRequestHookSpecificOutput = Omit<SDKPermissionRequestHookSpecificOutput, "hookEventName">;
+/**
+ * Setup hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type SetupHookSpecificOutput = Omit<SDKSetupHookSpecificOutput, "hookEventName">;
+/**
+ * Elicitation hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type ElicitationHookSpecificOutput = Omit<SDKElicitationHookSpecificOutput, "hookEventName">;
+/**
+ * ElicitationResult hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type ElicitationResultHookSpecificOutput = Omit<SDKElicitationResultHookSpecificOutput, "hookEventName">;
+/**
+ * PermissionDenied hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type PermissionDeniedHookSpecificOutput = Omit<SDKPermissionDeniedHookSpecificOutput, "hookEventName">;
+/**
+ * Allow decision for permission requests.
+ * Derived from SDK's PermissionRequestHookSpecificOutput.
+ */
+export type PermissionRequestAllowDecision = Extract<SDKPermissionRequestHookSpecificOutput["decision"], {
+    behavior: "allow";
+}>;
+/**
+ * Deny decision for permission requests.
+ * Derived from SDK's PermissionRequestHookSpecificOutput.
+ */
+export type PermissionRequestDenyDecision = Extract<SDKPermissionRequestHookSpecificOutput["decision"], {
+    behavior: "deny";
+}>;
+/**
+ * Permission request decision - either allow or deny.
+ * Derived from SDK's PermissionRequestHookSpecificOutput.
+ */
+export type PermissionRequestDecision = SDKPermissionRequestHookSpecificOutput["decision"];
+/**
+ * Notification hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type NotificationHookSpecificOutput = Omit<SDKNotificationHookSpecificOutput, "hookEventName">;
+/**
+ * CwdChanged hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type CwdChangedHookSpecificOutput = Omit<SDKCwdChangedHookSpecificOutput, "hookEventName">;
+/**
+ * FileChanged hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type FileChangedHookSpecificOutput = Omit<SDKFileChangedHookSpecificOutput, "hookEventName">;
+/**
+ * MessageDisplay hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type MessageDisplayHookSpecificOutput = Omit<SDKMessageDisplayHookSpecificOutput, "hookEventName">;
+/**
+ * Full hook-specific output with hookEventName discriminator.
+ */
+export type HookSpecificOutput = SDKPreToolUseHookSpecificOutput | SDKPostToolUseHookSpecificOutput | SDKPostToolUseFailureHookSpecificOutput | SDKPostToolBatchHookSpecificOutput | SDKUserPromptExpansionHookSpecificOutput | SDKUserPromptSubmitHookSpecificOutput | SDKSessionStartHookSpecificOutput | SDKSetupHookSpecificOutput | SDKSubagentStartHookSpecificOutput | SDKPermissionRequestHookSpecificOutput | SDKPermissionDeniedHookSpecificOutput | SDKNotificationHookSpecificOutput | SDKElicitationHookSpecificOutput | SDKElicitationResultHookSpecificOutput | SDKCwdChangedHookSpecificOutput | SDKFileChangedHookSpecificOutput | SDKMessageDisplayHookSpecificOutput;
+/**
+ * The JSON output format expected by Claude Code (sync hooks only).
+ * Extends SDK's SyncHookJSONOutput to include Notification hook support.
+ */
+export interface SyncHookJSONOutput {
+    /** If true, continue processing even after errors. */
+    continue?: boolean;
+    /** If true, suppress the hook's output from being displayed. */
+    suppressOutput?: boolean;
+    /** Reason for stopping the session (when blocking). */
+    stopReason?: string;
+    /** Decision for Stop/SubagentStop hooks: 'approve' allows stop, 'block' prevents it. */
+    decision?: "approve" | "block";
+    /** System message to inject into Claude's context. */
+    systemMessage?: string;
+    /** Reason shown to Claude when blocking. */
+    reason?: string;
+    /** Hook-specific output based on the hook type. */
+    hookSpecificOutput?: HookSpecificOutput;
+}
+/**
+ * The result of a hook handler, ready for the runtime to process.
+ * Exit code is always SUCCESS (0) - blocking behavior is communicated via stdout fields.
+ */
+export interface HookOutput {
+    /** JSON-serializable output to write to stdout. */
+    stdout: SyncHookJSONOutput;
+    /** Optional message to write to stderr. When present, the runtime exits with code 2 (BLOCK). */
+    stderr?: string;
+    /**
+     * Plain-text payload written verbatim to stdout instead of `JSON.stringify(stdout)`.
+     * When present, the runtime emits this string and ignores `stdout`. See
+     * {@link BaseSpecificOutput.rawStdout}.
+     */
+    rawStdout?: string;
+}
+/**
+ * Common options available to all output builders.
+ * These map directly to the wire format fields.
+ */
+export interface CommonOptions {
+    /** If true, continue processing even after errors. */
+    continue?: boolean;
+    /** If true, suppress the hook's output from being displayed. */
+    suppressOutput?: boolean;
+    /** System message to inject into Claude's context. */
+    systemMessage?: string;
+    /** Reason for stopping/blocking (sets exit code to BLOCK). */
+    stopReason?: string;
+}
+/**
+ * Options for exit-code-based hooks (TeammateIdle, TaskCompleted).
+ *
+ * These hooks use exit codes only, not JSON decision control.
+ * When `stderr` is provided, the runtime writes it to stderr and exits with code 2 (BLOCK).
+ * No stdout is written on this path: Claude Code's hook-result parser treats any stdout
+ * that parses as valid JSON as a success outcome regardless of exit code, so blocking
+ * only takes effect when stdout carries no JSON at all.
+ * When absent, the hook exits with code 0 (SUCCESS).
+ */
+export interface ExitCodeOptions {
+    /** Message to write to stderr. When present, exits with code 2 (BLOCK). */
+    stderr?: string;
+}
+/**
+ * Base structure for all specific outputs.
+ */
+interface BaseSpecificOutput<T extends string> {
+    readonly _type: T;
+    stdout: SyncHookJSONOutput;
+    stderr?: string;
+    /**
+     * Plain-text payload written verbatim to stdout instead of `JSON.stringify(stdout)`.
+     *
+     * Used by command hooks whose wire protocol is a bare string rather than JSON —
+     * notably `WorktreeCreate`/`WorktreeRemove`, where Claude Code reads stdout as the
+     * worktree path and `chdir`s into it. When present, the runtime emits this string
+     * and ignores `stdout`.
+     */
+    rawStdout?: string;
+}
+/**
+ *
+ */
+export type PreToolUseOutput = BaseSpecificOutput<"PreToolUse">;
+/**
+ *
+ */
+export type PostToolUseOutput = BaseSpecificOutput<"PostToolUse">;
+/**
+ *
+ */
+export type PostToolUseFailureOutput = BaseSpecificOutput<"PostToolUseFailure">;
+/**
+ *
+ */
+export type PostToolBatchOutput = BaseSpecificOutput<"PostToolBatch">;
+/**
+ *
+ */
+export type NotificationOutput = BaseSpecificOutput<"Notification">;
+/**
+ *
+ */
+export type UserPromptExpansionOutput = BaseSpecificOutput<"UserPromptExpansion">;
+/**
+ *
+ */
+export type UserPromptSubmitOutput = BaseSpecificOutput<"UserPromptSubmit">;
+/**
+ *
+ */
+export type SessionStartOutput = BaseSpecificOutput<"SessionStart">;
+/**
+ *
+ */
+export type SessionEndOutput = BaseSpecificOutput<"SessionEnd">;
+/**
+ *
+ */
+export type StopOutput = BaseSpecificOutput<"Stop">;
+/**
+ *
+ */
+export type StopFailureOutput = BaseSpecificOutput<"StopFailure">;
+/**
+ *
+ */
+export type SubagentStartOutput = BaseSpecificOutput<"SubagentStart">;
+/**
+ *
+ */
+export type SubagentStopOutput = BaseSpecificOutput<"SubagentStop">;
+/**
+ *
+ */
+export type PreCompactOutput = BaseSpecificOutput<"PreCompact">;
+/**
+ *
+ */
+export type PostCompactOutput = BaseSpecificOutput<"PostCompact">;
+/**
+ *
+ */
+export type PermissionRequestOutput = BaseSpecificOutput<"PermissionRequest">;
+/**
+ *
+ */
+export type PermissionDeniedOutput = BaseSpecificOutput<"PermissionDenied">;
+/**
+ *
+ */
+export type SetupOutput = BaseSpecificOutput<"Setup">;
+/**
+ *
+ */
+export type TeammateIdleOutput = BaseSpecificOutput<"TeammateIdle">;
+/**
+ *
+ */
+export type TaskCreatedOutput = BaseSpecificOutput<"TaskCreated">;
+/**
+ *
+ */
+export type TaskCompletedOutput = BaseSpecificOutput<"TaskCompleted">;
+/**
+ *
+ */
+export type ElicitationOutput = BaseSpecificOutput<"Elicitation">;
+/**
+ *
+ */
+export type ElicitationResultOutput = BaseSpecificOutput<"ElicitationResult">;
+/**
+ *
+ */
+export type ConfigChangeOutput = BaseSpecificOutput<"ConfigChange">;
+/**
+ *
+ */
+export type InstructionsLoadedOutput = BaseSpecificOutput<"InstructionsLoaded">;
+/**
+ *
+ */
+export type WorktreeCreateOutput = BaseSpecificOutput<"WorktreeCreate">;
+/**
+ *
+ */
+export type WorktreeRemoveOutput = BaseSpecificOutput<"WorktreeRemove">;
+/**
+ *
+ */
+export type CwdChangedOutput = BaseSpecificOutput<"CwdChanged">;
+/**
+ *
+ */
+export type FileChangedOutput = BaseSpecificOutput<"FileChanged">;
+/**
+ *
+ */
+export type MessageDisplayOutput = BaseSpecificOutput<"MessageDisplay">;
+/**
+ * Union of all specific output types.
+ */
+export type SpecificHookOutput = PreToolUseOutput | PostToolUseOutput | PostToolUseFailureOutput | PostToolBatchOutput | NotificationOutput | UserPromptExpansionOutput | UserPromptSubmitOutput | SessionStartOutput | SessionEndOutput | StopOutput | StopFailureOutput | SubagentStartOutput | SubagentStopOutput | PreCompactOutput | PostCompactOutput | PermissionRequestOutput | PermissionDeniedOutput | SetupOutput | TeammateIdleOutput | TaskCreatedOutput | TaskCompletedOutput | ElicitationOutput | ElicitationResultOutput | ConfigChangeOutput | InstructionsLoadedOutput | WorktreeCreateOutput | WorktreeRemoveOutput | CwdChangedOutput | FileChangedOutput | MessageDisplayOutput;
+/**
+ * Options for decision-based hooks (Stop, SubagentStop).
+ */
+interface DecisionOptions extends CommonOptions {
+    /** Decision: 'approve' allows the action, 'block' prevents it. */
+    decision?: "approve" | "block";
+    /** Reason for the decision (shown to Claude when blocking). */
+    reason?: string;
+}
+/**
+ * Options for the PreToolUse output builder.
+ * Uses wire format: hookSpecificOutput with permissionDecision.
+ */
+export type PreToolUseOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: PreToolUseHookSpecificOutput;
+};
+/**
+ * Creates an output for PreToolUse hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A PreToolUseOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Allow tool execution
+ * preToolUseOutput({
+ *   hookSpecificOutput: { permissionDecision: 'allow' }
+ * });
+ *
+ * // Deny with reason
+ * preToolUseOutput({
+ *   hookSpecificOutput: {
+ *     permissionDecision: 'deny',
+ *     permissionDecisionReason: 'Dangerous command detected'
+ *   }
+ * });
+ *
+ * // Allow with modified input
+ * preToolUseOutput({
+ *   hookSpecificOutput: {
+ *     permissionDecision: 'allow',
+ *     updatedInput: { command: 'ls -la' }
+ *   }
+ * });
+ * ```
+ */
+export declare const preToolUseOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: PreToolUseHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "PreToolUse";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the PostToolUse output builder.
+ */
+export type PostToolUseOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: PostToolUseHookSpecificOutput;
+};
+/**
+ * Creates an output for PostToolUse hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A PostToolUseOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Add context after a file read
+ * postToolUseOutput({
+ *   hookSpecificOutput: {
+ *     additionalContext: 'File contains sensitive data'
+ *   }
+ * });
+ * ```
+ */
+export declare const postToolUseOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: PostToolUseHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "PostToolUse";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the PostToolUseFailure output builder.
+ */
+export type PostToolUseFailureOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: PostToolUseFailureHookSpecificOutput;
+};
+/**
+ * Creates an output for PostToolUseFailure hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A PostToolUseFailureOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * postToolUseFailureOutput({
+ *   hookSpecificOutput: {
+ *     additionalContext: 'Try using a different approach'
+ *   }
+ * });
+ * ```
+ */
+export declare const postToolUseFailureOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: PostToolUseFailureHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "PostToolUseFailure";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the PostToolBatch output builder.
+ */
+export type PostToolBatchOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: PostToolBatchHookSpecificOutput;
+};
+/**
+ * Creates an output for PostToolBatch hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A PostToolBatchOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * postToolBatchOutput({
+ *   hookSpecificOutput: {
+ *     additionalContext: 'All edits in the batch were applied successfully'
+ *   }
+ * });
+ * ```
+ */
+export declare const postToolBatchOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: PostToolBatchHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "PostToolBatch";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the UserPromptExpansion output builder.
+ */
+export type UserPromptExpansionOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: UserPromptExpansionHookSpecificOutput;
+};
+/**
+ * Creates an output for UserPromptExpansion hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A UserPromptExpansionOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * userPromptExpansionOutput({
+ *   hookSpecificOutput: {
+ *     additionalContext: 'Slash command expanded with additional context'
+ *   }
+ * });
+ * ```
+ */
+export declare const userPromptExpansionOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: UserPromptExpansionHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "UserPromptExpansion";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the UserPromptSubmit output builder.
+ */
+export type UserPromptSubmitOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: UserPromptSubmitHookSpecificOutput;
+};
+/**
+ * Creates an output for UserPromptSubmit hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A UserPromptSubmitOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * userPromptSubmitOutput({
+ *   hookSpecificOutput: {
+ *     additionalContext: 'This project uses TypeScript strict mode'
+ *   }
+ * });
+ * ```
+ */
+export declare const userPromptSubmitOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: UserPromptSubmitHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "UserPromptSubmit";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the SessionStart output builder.
+ */
+export type SessionStartOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: SessionStartHookSpecificOutput;
+};
+/**
+ * Creates an output for SessionStart hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A SessionStartOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * sessionStartOutput({
+ *   hookSpecificOutput: {
+ *     additionalContext: JSON.stringify({ project: 'my-project' })
+ *   }
+ * });
+ * ```
+ */
+export declare const sessionStartOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: SessionStartHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "SessionStart";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the SessionEnd output builder.
+ * SessionEnd hooks only support common options.
+ */
+export type SessionEndOptions = CommonOptions;
+/**
+ * Creates an output for SessionEnd hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A SessionEndOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * sessionEndOutput({});
+ * ```
+ */
+export declare const sessionEndOutput: (options?: CommonOptions) => {
+    readonly _type: "SessionEnd";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the Stop output builder.
+ */
+export interface StopOptions extends CommonOptions {
+    /** Decision: 'approve' allows stop, 'block' prevents it. */
+    decision?: "approve" | "block";
+    /** Reason for the decision (shown to Claude when blocking). */
+    reason?: string;
+}
+/**
+ * Creates an output for Stop hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A StopOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Allow the stop
+ * stopOutput({ decision: 'approve' });
+ *
+ * // Block with reason
+ * stopOutput({
+ *   decision: 'block',
+ *   reason: 'There are uncommitted changes'
+ * });
+ * ```
+ */
+export declare const stopOutput: (options?: DecisionOptions) => {
+    readonly _type: "Stop";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the StopFailure output builder.
+ * StopFailure hooks only support common options.
+ */
+export type StopFailureOptions = CommonOptions;
+/**
+ * Creates an output for StopFailure hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A StopFailureOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * stopFailureOutput({});
+ * ```
+ */
+export declare const stopFailureOutput: (options?: CommonOptions) => {
+    readonly _type: "StopFailure";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the SubagentStart output builder.
+ */
+export type SubagentStartOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: SubagentStartHookSpecificOutput;
+};
+/**
+ * Creates an output for SubagentStart hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A SubagentStartOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * subagentStartOutput({
+ *   hookSpecificOutput: {
+ *     additionalContext: 'Focus on finding patterns'
+ *   }
+ * });
+ * ```
+ */
+export declare const subagentStartOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: SubagentStartHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "SubagentStart";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the SubagentStop output builder.
+ */
+export interface SubagentStopOptions extends CommonOptions {
+    /** Decision: 'approve' allows stop, 'block' prevents it. */
+    decision?: "approve" | "block";
+    /** Reason for the decision (shown to subagent when blocking). */
+    reason?: string;
+}
+/**
+ * Creates an output for SubagentStop hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A SubagentStopOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Block with reason
+ * subagentStopOutput({
+ *   decision: 'block',
+ *   reason: 'Task not complete'
+ * });
+ * ```
+ */
+export declare const subagentStopOutput: (options?: DecisionOptions) => {
+    readonly _type: "SubagentStop";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the Notification output builder.
+ */
+export type NotificationOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: NotificationHookSpecificOutput;
+};
+/**
+ * Creates an output for Notification hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A NotificationOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Add context about the notification
+ * notificationOutput({
+ *   hookSpecificOutput: {
+ *     additionalContext: 'Notification forwarded to Slack #alerts channel'
+ *   }
+ * });
+ *
+ * // Suppress the notification
+ * notificationOutput({ suppressOutput: true });
+ * ```
+ */
+export declare const notificationOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: NotificationHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "Notification";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the PreCompact output builder.
+ * PreCompact hooks only support common options.
+ */
+export type PreCompactOptions = CommonOptions;
+/**
+ * Creates an output for PreCompact hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A PreCompactOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * preCompactOutput({
+ *   systemMessage: 'Remember: strict mode is enabled'
+ * });
+ * ```
+ */
+export declare const preCompactOutput: (options?: CommonOptions) => {
+    readonly _type: "PreCompact";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the PostCompact output builder.
+ * PostCompact hooks only support common options.
+ */
+export type PostCompactOptions = CommonOptions;
+/**
+ * Creates an output for PostCompact hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A PostCompactOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * postCompactOutput({});
+ * ```
+ */
+export declare const postCompactOutput: (options?: CommonOptions) => {
+    readonly _type: "PostCompact";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the PermissionRequest output builder.
+ */
+export type PermissionRequestOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: PermissionRequestHookSpecificOutput;
+};
+/**
+ * Creates an output for PermissionRequest hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A PermissionRequestOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Auto-approve
+ * permissionRequestOutput({
+ *   hookSpecificOutput: {
+ *     decision: { behavior: 'allow' }
+ *   }
+ * });
+ *
+ * // Auto-approve with modified input
+ * permissionRequestOutput({
+ *   hookSpecificOutput: {
+ *     decision: {
+ *       behavior: 'allow',
+ *       updatedInput: { file_path: '/safe/path' }
+ *     }
+ *   }
+ * });
+ *
+ * // Auto-deny
+ * permissionRequestOutput({
+ *   hookSpecificOutput: {
+ *     decision: {
+ *       behavior: 'deny',
+ *       message: 'Not allowed',
+ *       interrupt: true
+ *     }
+ *   }
+ * });
+ *
+ * // Fall through to normal prompt
+ * permissionRequestOutput({});
+ * ```
+ */
+export declare const permissionRequestOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: PermissionRequestHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "PermissionRequest";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the PermissionDenied output builder.
+ */
+export type PermissionDeniedOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: PermissionDeniedHookSpecificOutput;
+};
+/**
+ * Creates an output for PermissionDenied hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A PermissionDeniedOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Log and allow retry
+ * permissionDeniedOutput({
+ *   hookSpecificOutput: { retry: true }
+ * });
+ *
+ * // Log without retry
+ * permissionDeniedOutput({});
+ * ```
+ */
+export declare const permissionDeniedOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: PermissionDeniedHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "PermissionDenied";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the Setup output builder.
+ */
+export type SetupOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: SetupHookSpecificOutput;
+};
+/**
+ * Creates an output for Setup hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A SetupOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Add context during setup
+ * setupOutput({
+ *   hookSpecificOutput: {
+ *     additionalContext: 'Project initialized with custom settings'
+ *   }
+ * });
+ *
+ * // Simple passthrough
+ * setupOutput({});
+ * ```
+ */
+export declare const setupOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: SetupHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "Setup";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the TeammateIdle output builder.
+ * TeammateIdle hooks use exit codes only, not JSON decision control.
+ */
+export type TeammateIdleOptions = ExitCodeOptions;
+/**
+ * Creates an output for TeammateIdle hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A TeammateIdleOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Allow teammate to go idle
+ * teammateIdleOutput({});
+ *
+ * // Block with feedback
+ * teammateIdleOutput({ stderr: 'Continue working: unfinished tasks remain.' });
+ * ```
+ */
+export declare const teammateIdleOutput: ({ stderr }?: ExitCodeOptions) => {
+    readonly _type: "TeammateIdle";
+    stdout: SyncHookJSONOutput;
+    stderr?: string;
+};
+/**
+ * Options for the TaskCreated output builder.
+ * TaskCreated hooks use exit codes only, not JSON decision control.
+ */
+export type TaskCreatedOptions = ExitCodeOptions;
+/**
+ * Creates an output for TaskCreated hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A TaskCreatedOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Allow task creation
+ * taskCreatedOutput({});
+ *
+ * // Block with feedback
+ * taskCreatedOutput({ stderr: 'Cannot create task: missing required fields.' });
+ * ```
+ */
+export declare const taskCreatedOutput: ({ stderr }?: ExitCodeOptions) => {
+    readonly _type: "TaskCreated";
+    stdout: SyncHookJSONOutput;
+    stderr?: string;
+};
+/**
+ * Options for the TaskCompleted output builder.
+ * TaskCompleted hooks use exit codes only, not JSON decision control.
+ */
+export type TaskCompletedOptions = ExitCodeOptions;
+/**
+ * Creates an output for TaskCompleted hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A TaskCompletedOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Allow task completion
+ * taskCompletedOutput({});
+ *
+ * // Block with feedback
+ * taskCompletedOutput({ stderr: 'Cannot complete: tests are failing.' });
+ * ```
+ */
+export declare const taskCompletedOutput: ({ stderr }?: ExitCodeOptions) => {
+    readonly _type: "TaskCompleted";
+    stdout: SyncHookJSONOutput;
+    stderr?: string;
+};
+/**
+ * Options for the Elicitation output builder.
+ */
+export type ElicitationOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: ElicitationHookSpecificOutput;
+};
+/**
+ * Creates an output for Elicitation hooks.
+ * @param options - Configuration options for the hook output
+ * @returns An ElicitationOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Accept the elicitation
+ * elicitationOutput({
+ *   hookSpecificOutput: { action: 'accept', content: { username: 'alice' } }
+ * });
+ *
+ * // Decline the elicitation
+ * elicitationOutput({
+ *   hookSpecificOutput: { action: 'decline' }
+ * });
+ * ```
+ */
+export declare const elicitationOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: ElicitationHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "Elicitation";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the ElicitationResult output builder.
+ */
+export type ElicitationResultOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: ElicitationResultHookSpecificOutput;
+};
+/**
+ * Creates an output for ElicitationResult hooks.
+ * @param options - Configuration options for the hook output
+ * @returns An ElicitationResultOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * elicitationResultOutput({});
+ * ```
+ */
+export declare const elicitationResultOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: ElicitationResultHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "ElicitationResult";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the ConfigChange output builder.
+ * ConfigChange hooks only support common options.
+ */
+export type ConfigChangeOptions = CommonOptions;
+/**
+ * Creates an output for ConfigChange hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A ConfigChangeOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * configChangeOutput({});
+ * ```
+ */
+export declare const configChangeOutput: (options?: CommonOptions) => {
+    readonly _type: "ConfigChange";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the InstructionsLoaded output builder.
+ * InstructionsLoaded hooks only support common options.
+ */
+export type InstructionsLoadedOptions = CommonOptions;
+/**
+ * Creates an output for InstructionsLoaded hooks.
+ * @param options - Configuration options for the hook output
+ * @returns An InstructionsLoadedOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * instructionsLoadedOutput({});
+ * ```
+ */
+export declare const instructionsLoadedOutput: (options?: CommonOptions) => {
+    readonly _type: "InstructionsLoaded";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the WorktreeCreate output builder.
+ *
+ * `worktreePath` is required: WorktreeCreate is a command hook whose protocol is the
+ * **bare absolute path on stdout**. The path type is derived from the SDK's
+ * `WorktreeCreateHookSpecificOutput`.
+ */
+export type WorktreeCreateOptions = CommonOptions & Pick<SDKWorktreeCreateHookSpecificOutput, "worktreePath">;
+/**
+ * Creates an output for WorktreeCreate hooks.
+ *
+ * The runtime writes `worktreePath` to stdout as plain text (not JSON) so Claude Code
+ * can `chdir` into the created worktree.
+ * @param options - Configuration options for the hook output
+ * @returns A WorktreeCreateOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * worktreeCreateOutput({ worktreePath: '/abs/path/to/worktree' });
+ * ```
+ */
+export declare const worktreeCreateOutput: (options: CommonOptions & {
+    worktreePath: string;
+}) => {
+    readonly _type: "WorktreeCreate";
+    stdout: SyncHookJSONOutput;
+    rawStdout: string;
+};
+/**
+ * Options for the WorktreeRemove output builder.
+ *
+ * `worktreePath` is optional: when provided it is written to stdout as plain text
+ * (matching the WorktreeCreate command-hook protocol); when omitted the builder falls
+ * back to the JSON passthrough.
+ */
+export type WorktreeRemoveOptions = CommonOptions & {
+    worktreePath?: string;
+};
+/**
+ * Creates an output for WorktreeRemove hooks.
+ *
+ * When `worktreePath` is supplied, the runtime writes it to stdout as plain text (not
+ * JSON), matching the worktree command-hook protocol.
+ * @param options - Configuration options for the hook output
+ * @returns A WorktreeRemoveOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Plain-text path protocol
+ * worktreeRemoveOutput({ worktreePath: '/abs/path/to/worktree' });
+ *
+ * // No path payload
+ * worktreeRemoveOutput({});
+ * ```
+ */
+export declare const worktreeRemoveOutput: (options?: WorktreeRemoveOptions) => {
+    readonly _type: "WorktreeRemove";
+    stdout: SyncHookJSONOutput;
+    rawStdout?: string;
+};
+/**
+ * Options for the CwdChanged output builder.
+ */
+export type CwdChangedOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: CwdChangedHookSpecificOutput;
+};
+/**
+ * Creates an output for CwdChanged hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A CwdChangedOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Return additional paths to watch after the cwd change
+ * cwdChangedOutput({
+ *   hookSpecificOutput: {
+ *     watchPaths: ['/new/path/to/watch']
+ *   }
+ * });
+ *
+ * // Simple passthrough
+ * cwdChangedOutput({});
+ * ```
+ */
+export declare const cwdChangedOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: CwdChangedHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "CwdChanged";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the FileChanged output builder.
+ */
+export type FileChangedOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: FileChangedHookSpecificOutput;
+};
+/**
+ * Creates an output for FileChanged hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A FileChangedOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Update the set of watched paths
+ * fileChangedOutput({
+ *   hookSpecificOutput: {
+ *     watchPaths: ['/path/to/watch', '/another/path']
+ *   }
+ * });
+ *
+ * // Simple passthrough
+ * fileChangedOutput({});
+ * ```
+ */
+export declare const fileChangedOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: FileChangedHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "FileChanged";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the MessageDisplay output builder.
+ */
+export type MessageDisplayOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: MessageDisplayHookSpecificOutput;
+};
+/**
+ * Creates an output for MessageDisplay hooks.
+ *
+ * MessageDisplay is display-only: the `displayContent` field replaces the delta on
+ * screen without changing the stored message or what the model sees. Omit
+ * `displayContent` (or set it to the original delta) to leave the display unchanged.
+ * @param options - Configuration options for the hook output
+ * @returns A MessageDisplayOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Replace the delta shown on screen
+ * messageDisplayOutput({
+ *   hookSpecificOutput: { displayContent: "[redacted]" }
+ * });
+ *
+ * // Passthrough (no display modification)
+ * messageDisplayOutput({});
+ * ```
+ */
+export declare const messageDisplayOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: MessageDisplayHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "MessageDisplay";
+    stdout: SyncHookJSONOutput;
+};