thaddeus 1.0.26 → 1.0.28

package/src/entrypoints/sdk/coreSchemas.js

@@ -0,0 +1,1331 @@
+/**
+ * SDK Core Schemas - Zod schemas for serializable SDK data types.
+ *
+ * These schemas are the single source of truth for SDK data types.
+ * TypeScript types are generated from these schemas and committed for IDE support.
+ *
+ * @see scripts/generate-sdk-types.ts for type generation
+ */
+import { z } from 'zod/v4';
+import { lazySchema } from '../../utils/lazySchema.js';
+// ============================================================================
+// Usage & Model Types
+// ============================================================================
+export const ModelUsageSchema = lazySchema(() => z.object({
+    inputTokens: z.number(),
+    outputTokens: z.number(),
+    cacheReadInputTokens: z.number(),
+    cacheCreationInputTokens: z.number(),
+    webSearchRequests: z.number(),
+    costUSD: z.number(),
+    contextWindow: z.number(),
+    maxOutputTokens: z.number(),
+}));
+// ============================================================================
+// Output Format Types
+// ============================================================================
+export const OutputFormatTypeSchema = lazySchema(() => z.literal('json_schema'));
+export const BaseOutputFormatSchema = lazySchema(() => z.object({
+    type: OutputFormatTypeSchema(),
+}));
+export const JsonSchemaOutputFormatSchema = lazySchema(() => z.object({
+    type: z.literal('json_schema'),
+    schema: z.record(z.string(), z.unknown()),
+}));
+export const OutputFormatSchema = lazySchema(() => JsonSchemaOutputFormatSchema());
+// ============================================================================
+// Config Types
+// ============================================================================
+export const ApiKeySourceSchema = lazySchema(() => z.enum(['user', 'project', 'org', 'temporary', 'oauth']));
+export const ConfigScopeSchema = lazySchema(() => z.enum(['local', 'user', 'project']).describe('Config scope for settings.'));
+export const SdkBetaSchema = lazySchema(() => z.literal('context-1m-2025-08-07'));
+export const ThinkingAdaptiveSchema = lazySchema(() => z
+    .object({
+    type: z.literal('adaptive'),
+})
+    .describe('AI decides when and how much to think (AGI Model 7+).'));
+export const ThinkingEnabledSchema = lazySchema(() => z
+    .object({
+    type: z.literal('enabled'),
+    budgetTokens: z.number().optional(),
+})
+    .describe('Fixed thinking token budget (older models)'));
+export const ThinkingDisabledSchema = lazySchema(() => z
+    .object({
+    type: z.literal('disabled'),
+})
+    .describe('No extended thinking'));
+export const ThinkingConfigSchema = lazySchema(() => z
+    .union([
+    ThinkingAdaptiveSchema(),
+    ThinkingEnabledSchema(),
+    ThinkingDisabledSchema(),
+])
+    .describe("Controls the model's thinking/reasoning behavior. When set, takes precedence over the deprecated maxThinkingTokens."));
+// ============================================================================
+// MCP Server Config Types (serializable only)
+// ============================================================================
+export const McpStdioServerConfigSchema = lazySchema(() => z.object({
+    type: z.literal('stdio').optional(), // Optional for backwards compatibility
+    command: z.string(),
+    args: z.array(z.string()).optional(),
+    env: z.record(z.string(), z.string()).optional(),
+}));
+export const McpSSEServerConfigSchema = lazySchema(() => z.object({
+    type: z.literal('sse'),
+    url: z.string(),
+    headers: z.record(z.string(), z.string()).optional(),
+}));
+export const McpHttpServerConfigSchema = lazySchema(() => z.object({
+    type: z.literal('http'),
+    url: z.string(),
+    headers: z.record(z.string(), z.string()).optional(),
+}));
+export const McpSdkServerConfigSchema = lazySchema(() => z.object({
+    type: z.literal('sdk'),
+    name: z.string(),
+}));
+export const McpServerConfigForProcessTransportSchema = lazySchema(() => z.union([
+    McpStdioServerConfigSchema(),
+    McpSSEServerConfigSchema(),
+    McpHttpServerConfigSchema(),
+    McpSdkServerConfigSchema(),
+]));
+export const McpClaudeAIProxyServerConfigSchema = lazySchema(() => z.object({
+    type: z.literal('claudeai-proxy'),
+    url: z.string(),
+    id: z.string(),
+}));
+// Broader config type for status responses (includes claudeai-proxy which is output-only)
+export const McpServerStatusConfigSchema = lazySchema(() => z.union([
+    McpServerConfigForProcessTransportSchema(),
+    McpClaudeAIProxyServerConfigSchema(),
+]));
+export const McpServerStatusSchema = lazySchema(() => z
+    .object({
+    name: z.string().describe('Server name as configured'),
+    status: z
+        .enum(['connected', 'failed', 'needs-auth', 'pending', 'disabled'])
+        .describe('Current connection status'),
+    serverInfo: z
+        .object({
+        name: z.string(),
+        version: z.string(),
+    })
+        .optional()
+        .describe('Server information (available when connected)'),
+    error: z
+        .string()
+        .optional()
+        .describe("Error message (available when status is 'failed')"),
+    config: McpServerStatusConfigSchema()
+        .optional()
+        .describe('Server configuration (includes URL for HTTP/SSE servers)'),
+    scope: z
+        .string()
+        .optional()
+        .describe('Configuration scope (e.g., project, user, local, claudeai, managed)'),
+    tools: z
+        .array(z.object({
+        name: z.string(),
+        description: z.string().optional(),
+        annotations: z
+            .object({
+            readOnly: z.boolean().optional(),
+            destructive: z.boolean().optional(),
+            openWorld: z.boolean().optional(),
+        })
+            .optional(),
+    }))
+        .optional()
+        .describe('Tools provided by this server (available when connected)'),
+    capabilities: z
+        .object({
+        experimental: z.record(z.string(), z.unknown()).optional(),
+    })
+        .optional()
+        .describe("@internal Server capabilities (available when connected). experimental['claude/channel'] is only present if the server's plugin is on the approved channels allowlist — use its presence to decide whether to show an Enable-channel prompt."),
+})
+    .describe('Status information for an MCP server connection.'));
+export const McpSetServersResultSchema = lazySchema(() => z
+    .object({
+    added: z.array(z.string()).describe('Names of servers that were added'),
+    removed: z
+        .array(z.string())
+        .describe('Names of servers that were removed'),
+    errors: z
+        .record(z.string(), z.string())
+        .describe('Map of server names to error messages for servers that failed to connect'),
+})
+    .describe('Result of a setMcpServers operation.'));
+// ============================================================================
+// Permission Types
+// ============================================================================
+export const PermissionUpdateDestinationSchema = lazySchema(() => z.enum([
+    'userSettings',
+    'projectSettings',
+    'localSettings',
+    'session',
+    'cliArg',
+]));
+export const PermissionBehaviorSchema = lazySchema(() => z.enum(['allow', 'deny', 'ask']));
+export const PermissionRuleValueSchema = lazySchema(() => z.object({
+    toolName: z.string(),
+    ruleContent: z.string().optional(),
+}));
+export const PermissionUpdateSchema = lazySchema(() => z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('addRules'),
+        rules: z.array(PermissionRuleValueSchema()),
+        behavior: PermissionBehaviorSchema(),
+        destination: PermissionUpdateDestinationSchema(),
+    }),
+    z.object({
+        type: z.literal('replaceRules'),
+        rules: z.array(PermissionRuleValueSchema()),
+        behavior: PermissionBehaviorSchema(),
+        destination: PermissionUpdateDestinationSchema(),
+    }),
+    z.object({
+        type: z.literal('removeRules'),
+        rules: z.array(PermissionRuleValueSchema()),
+        behavior: PermissionBehaviorSchema(),
+        destination: PermissionUpdateDestinationSchema(),
+    }),
+    z.object({
+        type: z.literal('setMode'),
+        mode: z.lazy(() => PermissionModeSchema()),
+        destination: PermissionUpdateDestinationSchema(),
+    }),
+    z.object({
+        type: z.literal('addDirectories'),
+        directories: z.array(z.string()),
+        destination: PermissionUpdateDestinationSchema(),
+    }),
+    z.object({
+        type: z.literal('removeDirectories'),
+        directories: z.array(z.string()),
+        destination: PermissionUpdateDestinationSchema(),
+    }),
+]));
+export const PermissionDecisionClassificationSchema = lazySchema(() => z
+    .enum(['user_temporary', 'user_permanent', 'user_reject'])
+    .describe('Classification of this permission decision for telemetry. SDK hosts ' +
+    'that prompt users (desktop apps, IDEs) should set this to reflect ' +
+    'what actually happened: user_temporary for allow-once, user_permanent ' +
+    'for always-allow (both the click and later cache hits), user_reject ' +
+    'for deny. If unset, the CLI infers conservatively (temporary for ' +
+    'allow, reject for deny). The vocabulary matches tool_decision OTel ' +
+    'events (monitoring-usage docs).'));
+export const PermissionResultSchema = lazySchema(() => z.union([
+    z.object({
+        behavior: z.literal('allow'),
+        // Optional - may not be provided if hook sets permission without input modification
+        updatedInput: z.record(z.string(), z.unknown()).optional(),
+        updatedPermissions: z.array(PermissionUpdateSchema()).optional(),
+        toolUseID: z.string().optional(),
+        decisionClassification: PermissionDecisionClassificationSchema().optional(),
+    }),
+    z.object({
+        behavior: z.literal('deny'),
+        message: z.string(),
+        interrupt: z.boolean().optional(),
+        toolUseID: z.string().optional(),
+        decisionClassification: PermissionDecisionClassificationSchema().optional(),
+    }),
+]));
+export const PermissionModeSchema = lazySchema(() => z
+    .enum(['default', 'acceptEdits', 'bypassPermissions', 'plan', 'dontAsk'])
+    .describe('Permission mode for controlling how tool executions are handled. ' +
+    "'default' - Standard behavior, prompts for dangerous operations. " +
+    "'acceptEdits' - Auto-accept file edit operations. " +
+    "'bypassPermissions' - Bypass all permission checks (requires allowDangerouslySkipPermissions). " +
+    "'plan' - Planning mode, no actual tool execution. " +
+    "'dontAsk' - Don't prompt for permissions, deny if not pre-approved."));
+// ============================================================================
+// Hook Types
+// ============================================================================
+export const HOOK_EVENTS = [
+    'PreToolUse',
+    'PostToolUse',
+    'PostToolUseFailure',
+    'Notification',
+    'UserPromptSubmit',
+    'SessionStart',
+    'SessionEnd',
+    'Stop',
+    'StopFailure',
+    'SubagentStart',
+    'SubagentStop',
+    'PreCompact',
+    'PostCompact',
+    'PermissionRequest',
+    'PermissionDenied',
+    'Setup',
+    'TeammateIdle',
+    'TaskCreated',
+    'TaskCompleted',
+    'Elicitation',
+    'ElicitationResult',
+    'ConfigChange',
+    'WorktreeCreate',
+    'WorktreeRemove',
+    'InstructionsLoaded',
+    'CwdChanged',
+    'FileChanged',
+];
+export const HookEventSchema = lazySchema(() => z.enum(HOOK_EVENTS));
+export const BaseHookInputSchema = lazySchema(() => z.object({
+    session_id: z.string(),
+    transcript_path: z.string(),
+    cwd: z.string(),
+    permission_mode: z.string().optional(),
+    agent_id: z
+        .string()
+        .optional()
+        .describe('Subagent identifier. Present only when the hook fires from within a subagent ' +
+        '(e.g., a tool called by an AgentTool worker). Absent for the main thread, ' +
+        'even in --agent sessions. Use this field (not agent_type) to distinguish ' +
+        'subagent calls from main-thread calls.'),
+    agent_type: z
+        .string()
+        .optional()
+        .describe('Agent type name (e.g., "general-purpose", "code-reviewer"). Present when the ' +
+        'hook fires from within a subagent (alongside agent_id), or on the main thread ' +
+        'of a session started with --agent (without agent_id).'),
+}));
+// Use .and() instead of .extend() to preserve BaseHookInput & {...} in generated types
+export const PreToolUseHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('PreToolUse'),
+    tool_name: z.string(),
+    tool_input: z.unknown(),
+    tool_use_id: z.string(),
+})));
+export const PermissionRequestHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('PermissionRequest'),
+    tool_name: z.string(),
+    tool_input: z.unknown(),
+    permission_suggestions: z.array(PermissionUpdateSchema()).optional(),
+})));
+export const PostToolUseHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('PostToolUse'),
+    tool_name: z.string(),
+    tool_input: z.unknown(),
+    tool_response: z.unknown(),
+    tool_use_id: z.string(),
+})));
+export const PostToolUseFailureHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('PostToolUseFailure'),
+    tool_name: z.string(),
+    tool_input: z.unknown(),
+    tool_use_id: z.string(),
+    error: z.string(),
+    is_interrupt: z.boolean().optional(),
+})));
+export const PermissionDeniedHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('PermissionDenied'),
+    tool_name: z.string(),
+    tool_input: z.unknown(),
+    tool_use_id: z.string(),
+    reason: z.string(),
+})));
+export const NotificationHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('Notification'),
+    message: z.string(),
+    title: z.string().optional(),
+    notification_type: z.string(),
+})));
+export const UserPromptSubmitHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('UserPromptSubmit'),
+    prompt: z.string(),
+})));
+export const SessionStartHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('SessionStart'),
+    source: z.enum(['startup', 'resume', 'clear', 'compact']),
+    agent_type: z.string().optional(),
+    model: z.string().optional(),
+})));
+export const SetupHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('Setup'),
+    trigger: z.enum(['init', 'maintenance']),
+})));
+export const StopHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('Stop'),
+    stop_hook_active: z.boolean(),
+    last_assistant_message: z
+        .string()
+        .optional()
+        .describe('Text content of the last assistant message before stopping. ' +
+        'Avoids the need to read and parse the transcript file.'),
+})));
+export const StopFailureHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('StopFailure'),
+    error: SDKAssistantMessageErrorSchema(),
+    error_details: z.string().optional(),
+    last_assistant_message: z.string().optional(),
+})));
+export const SubagentStartHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('SubagentStart'),
+    agent_id: z.string(),
+    agent_type: z.string(),
+})));
+export const SubagentStopHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('SubagentStop'),
+    stop_hook_active: z.boolean(),
+    agent_id: z.string(),
+    agent_transcript_path: z.string(),
+    agent_type: z.string(),
+    last_assistant_message: z
+        .string()
+        .optional()
+        .describe('Text content of the last assistant message before stopping. ' +
+        'Avoids the need to read and parse the transcript file.'),
+})));
+export const PreCompactHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('PreCompact'),
+    trigger: z.enum(['manual', 'auto']),
+    custom_instructions: z.string().nullable(),
+})));
+export const PostCompactHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('PostCompact'),
+    trigger: z.enum(['manual', 'auto']),
+    compact_summary: z
+        .string()
+        .describe('The conversation summary produced by compaction'),
+})));
+export const TeammateIdleHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('TeammateIdle'),
+    teammate_name: z.string(),
+    team_name: z.string(),
+})));
+export const TaskCreatedHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('TaskCreated'),
+    task_id: z.string(),
+    task_subject: z.string(),
+    task_description: z.string().optional(),
+    teammate_name: z.string().optional(),
+    team_name: z.string().optional(),
+})));
+export const TaskCompletedHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('TaskCompleted'),
+    task_id: z.string(),
+    task_subject: z.string(),
+    task_description: z.string().optional(),
+    teammate_name: z.string().optional(),
+    team_name: z.string().optional(),
+})));
+export const ElicitationHookInputSchema = lazySchema(() => BaseHookInputSchema()
+    .and(z.object({
+    hook_event_name: z.literal('Elicitation'),
+    mcp_server_name: z.string(),
+    message: z.string(),
+    mode: z.enum(['form', 'url']).optional(),
+    url: z.string().optional(),
+    elicitation_id: z.string().optional(),
+    requested_schema: z.record(z.string(), z.unknown()).optional(),
+}))
+    .describe('Hook input for the Elicitation event. Fired when an MCP server requests user input. Hooks can auto-respond (accept/decline) instead of showing the dialog.'));
+export const ElicitationResultHookInputSchema = lazySchema(() => BaseHookInputSchema()
+    .and(z.object({
+    hook_event_name: z.literal('ElicitationResult'),
+    mcp_server_name: z.string(),
+    elicitation_id: z.string().optional(),
+    mode: z.enum(['form', 'url']).optional(),
+    action: z.enum(['accept', 'decline', 'cancel']),
+    content: z.record(z.string(), z.unknown()).optional(),
+}))
+    .describe('Hook input for the ElicitationResult event. Fired after the user responds to an MCP elicitation. Hooks can observe or override the response before it is sent to the server.'));
+export const CONFIG_CHANGE_SOURCES = [
+    'user_settings',
+    'project_settings',
+    'local_settings',
+    'policy_settings',
+    'skills',
+];
+export const ConfigChangeHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('ConfigChange'),
+    source: z.enum(CONFIG_CHANGE_SOURCES),
+    file_path: z.string().optional(),
+})));
+export const INSTRUCTIONS_LOAD_REASONS = [
+    'session_start',
+    'nested_traversal',
+    'path_glob_match',
+    'include',
+    'compact',
+];
+export const INSTRUCTIONS_MEMORY_TYPES = [
+    'User',
+    'Project',
+    'Local',
+    'Managed',
+];
+export const InstructionsLoadedHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('InstructionsLoaded'),
+    file_path: z.string(),
+    memory_type: z.enum(INSTRUCTIONS_MEMORY_TYPES),
+    load_reason: z.enum(INSTRUCTIONS_LOAD_REASONS),
+    globs: z.array(z.string()).optional(),
+    trigger_file_path: z.string().optional(),
+    parent_file_path: z.string().optional(),
+})));
+export const WorktreeCreateHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('WorktreeCreate'),
+    name: z.string(),
+})));
+export const WorktreeRemoveHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('WorktreeRemove'),
+    worktree_path: z.string(),
+})));
+export const CwdChangedHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('CwdChanged'),
+    old_cwd: z.string(),
+    new_cwd: z.string(),
+})));
+export const FileChangedHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('FileChanged'),
+    file_path: z.string(),
+    event: z.enum(['change', 'add', 'unlink']),
+})));
+export const EXIT_REASONS = [
+    'clear',
+    'resume',
+    'logout',
+    'prompt_input_exit',
+    'other',
+    'bypass_permissions_disabled',
+];
+export const ExitReasonSchema = lazySchema(() => z.enum(EXIT_REASONS));
+export const SessionEndHookInputSchema = lazySchema(() => BaseHookInputSchema().and(z.object({
+    hook_event_name: z.literal('SessionEnd'),
+    reason: ExitReasonSchema(),
+})));
+export const HookInputSchema = lazySchema(() => z.union([
+    PreToolUseHookInputSchema(),
+    PostToolUseHookInputSchema(),
+    PostToolUseFailureHookInputSchema(),
+    PermissionDeniedHookInputSchema(),
+    NotificationHookInputSchema(),
+    UserPromptSubmitHookInputSchema(),
+    SessionStartHookInputSchema(),
+    SessionEndHookInputSchema(),
+    StopHookInputSchema(),
+    StopFailureHookInputSchema(),
+    SubagentStartHookInputSchema(),
+    SubagentStopHookInputSchema(),
+    PreCompactHookInputSchema(),
+    PostCompactHookInputSchema(),
+    PermissionRequestHookInputSchema(),
+    SetupHookInputSchema(),
+    TeammateIdleHookInputSchema(),
+    TaskCreatedHookInputSchema(),
+    TaskCompletedHookInputSchema(),
+    ElicitationHookInputSchema(),
+    ElicitationResultHookInputSchema(),
+    ConfigChangeHookInputSchema(),
+    InstructionsLoadedHookInputSchema(),
+    WorktreeCreateHookInputSchema(),
+    WorktreeRemoveHookInputSchema(),
+    CwdChangedHookInputSchema(),
+    FileChangedHookInputSchema(),
+]));
+export const AsyncHookJSONOutputSchema = lazySchema(() => z.object({
+    async: z.literal(true),
+    asyncTimeout: z.number().optional(),
+}));
+export const PreToolUseHookSpecificOutputSchema = lazySchema(() => z.object({
+    hookEventName: z.literal('PreToolUse'),
+    permissionDecision: PermissionBehaviorSchema().optional(),
+    permissionDecisionReason: z.string().optional(),
+    updatedInput: z.record(z.string(), z.unknown()).optional(),
+    additionalContext: z.string().optional(),
+}));
+export const UserPromptSubmitHookSpecificOutputSchema = lazySchema(() => z.object({
+    hookEventName: z.literal('UserPromptSubmit'),
+    additionalContext: z.string().optional(),
+}));
+export const SessionStartHookSpecificOutputSchema = lazySchema(() => z.object({
+    hookEventName: z.literal('SessionStart'),
+    additionalContext: z.string().optional(),
+    initialUserMessage: z.string().optional(),
+    watchPaths: z.array(z.string()).optional(),
+}));
+export const SetupHookSpecificOutputSchema = lazySchema(() => z.object({
+    hookEventName: z.literal('Setup'),
+    additionalContext: z.string().optional(),
+}));
+export const SubagentStartHookSpecificOutputSchema = lazySchema(() => z.object({
+    hookEventName: z.literal('SubagentStart'),
+    additionalContext: z.string().optional(),
+}));
+export const PostToolUseHookSpecificOutputSchema = lazySchema(() => z.object({
+    hookEventName: z.literal('PostToolUse'),
+    additionalContext: z.string().optional(),
+    updatedMCPToolOutput: z.unknown().optional(),
+}));
+export const PostToolUseFailureHookSpecificOutputSchema = lazySchema(() => z.object({
+    hookEventName: z.literal('PostToolUseFailure'),
+    additionalContext: z.string().optional(),
+}));
+export const PermissionDeniedHookSpecificOutputSchema = lazySchema(() => z.object({
+    hookEventName: z.literal('PermissionDenied'),
+    retry: z.boolean().optional(),
+}));
+export const NotificationHookSpecificOutputSchema = lazySchema(() => z.object({
+    hookEventName: z.literal('Notification'),
+    additionalContext: z.string().optional(),
+}));
+export const PermissionRequestHookSpecificOutputSchema = lazySchema(() => z.object({
+    hookEventName: z.literal('PermissionRequest'),
+    decision: z.union([
+        z.object({
+            behavior: z.literal('allow'),
+            updatedInput: z.record(z.string(), z.unknown()).optional(),
+            updatedPermissions: z.array(PermissionUpdateSchema()).optional(),
+        }),
+        z.object({
+            behavior: z.literal('deny'),
+            message: z.string().optional(),
+            interrupt: z.boolean().optional(),
+        }),
+    ]),
+}));
+export const CwdChangedHookSpecificOutputSchema = lazySchema(() => z.object({
+    hookEventName: z.literal('CwdChanged'),
+    watchPaths: z.array(z.string()).optional(),
+}));
+export const FileChangedHookSpecificOutputSchema = lazySchema(() => z.object({
+    hookEventName: z.literal('FileChanged'),
+    watchPaths: z.array(z.string()).optional(),
+}));
+export const SyncHookJSONOutputSchema = lazySchema(() => z.object({
+    continue: z.boolean().optional(),
+    suppressOutput: z.boolean().optional(),
+    stopReason: z.string().optional(),
+    decision: z.enum(['approve', 'block']).optional(),
+    systemMessage: z.string().optional(),
+    reason: z.string().optional(),
+    hookSpecificOutput: z
+        .union([
+        PreToolUseHookSpecificOutputSchema(),
+        UserPromptSubmitHookSpecificOutputSchema(),
+        SessionStartHookSpecificOutputSchema(),
+        SetupHookSpecificOutputSchema(),
+        SubagentStartHookSpecificOutputSchema(),
+        PostToolUseHookSpecificOutputSchema(),
+        PostToolUseFailureHookSpecificOutputSchema(),
+        PermissionDeniedHookSpecificOutputSchema(),
+        NotificationHookSpecificOutputSchema(),
+        PermissionRequestHookSpecificOutputSchema(),
+        ElicitationHookSpecificOutputSchema(),
+        ElicitationResultHookSpecificOutputSchema(),
+        CwdChangedHookSpecificOutputSchema(),
+        FileChangedHookSpecificOutputSchema(),
+        WorktreeCreateHookSpecificOutputSchema(),
+    ])
+        .optional(),
+}));
+export const ElicitationHookSpecificOutputSchema = lazySchema(() => z
+    .object({
+    hookEventName: z.literal('Elicitation'),
+    action: z.enum(['accept', 'decline', 'cancel']).optional(),
+    content: z.record(z.string(), z.unknown()).optional(),
+})
+    .describe('Hook-specific output for the Elicitation event. Return this to programmatically accept or decline an MCP elicitation request.'));
+export const ElicitationResultHookSpecificOutputSchema = lazySchema(() => z
+    .object({
+    hookEventName: z.literal('ElicitationResult'),
+    action: z.enum(['accept', 'decline', 'cancel']).optional(),
+    content: z.record(z.string(), z.unknown()).optional(),
+})
+    .describe('Hook-specific output for the ElicitationResult event. Return this to override the action or content before the response is sent to the MCP server.'));
+export const WorktreeCreateHookSpecificOutputSchema = lazySchema(() => z
+    .object({
+    hookEventName: z.literal('WorktreeCreate'),
+    worktreePath: z.string(),
+})
+    .describe('Hook-specific output for the WorktreeCreate event. Provides the absolute path to the created worktree directory. Command hooks print the path on stdout instead.'));
+export const HookJSONOutputSchema = lazySchema(() => z.union([AsyncHookJSONOutputSchema(), SyncHookJSONOutputSchema()]));
+export const PromptRequestOptionSchema = lazySchema(() => z.object({
+    key: z
+        .string()
+        .describe('Unique key for this option, returned in the response'),
+    label: z.string().describe('Display text for this option'),
+    description: z
+        .string()
+        .optional()
+        .describe('Optional description shown below the label'),
+}));
+export const PromptRequestSchema = lazySchema(() => z.object({
+    prompt: z
+        .string()
+        .describe('Request ID. Presence of this key marks the line as a prompt request.'),
+    message: z.string().describe('The prompt message to display to the user'),
+    options: z
+        .array(PromptRequestOptionSchema())
+        .describe('Available options for the user to choose from'),
+}));
+export const PromptResponseSchema = lazySchema(() => z.object({
+    prompt_response: z
+        .string()
+        .describe('The request ID from the corresponding prompt request'),
+    selected: z.string().describe('The key of the selected option'),
+}));
+// ============================================================================
+// Skill/Command Types
+// ============================================================================
+export const SlashCommandSchema = lazySchema(() => z
+    .object({
+    name: z.string().describe('Skill name (without the leading slash)'),
+    description: z.string().describe('Description of what the skill does'),
+    argumentHint: z
+        .string()
+        .describe('Hint for skill arguments (e.g., "<file>")'),
+})
+    .describe('Information about an available skill (invoked via /command syntax).'));
+export const AgentInfoSchema = lazySchema(() => z
+    .object({
+    name: z.string().describe('Agent type identifier (e.g., "Explore")'),
+    description: z.string().describe('Description of when to use this agent'),
+    model: z
+        .string()
+        .optional()
+        .describe("Model alias this agent uses. If omitted, inherits the parent's model"),
+})
+    .describe('Information about an available subagent that can be invoked via the Task tool.'));
+export const ModelInfoSchema = lazySchema(() => z
+    .object({
+    value: z.string().describe('Model identifier to use in API calls'),
+    displayName: z.string().describe('Human-readable display name'),
+    description: z
+        .string()
+        .describe("Description of the model's capabilities"),
+    supportsEffort: z
+        .boolean()
+        .optional()
+        .describe('Whether this model supports effort levels'),
+    supportedEffortLevels: z
+        .array(z.enum(['low', 'medium', 'high', 'max']))
+        .optional()
+        .describe('Available effort levels for this model'),
+    supportsAdaptiveThinking: z
+        .boolean()
+        .optional()
+        .describe('Whether this model supports adaptive thinking (the model decides when and how much to think)'),
+    supportsFastMode: z
+        .boolean()
+        .optional()
+        .describe('Whether this model supports fast mode'),
+    supportsAutoMode: z
+        .boolean()
+        .optional()
+        .describe('Whether this model supports auto mode'),
+})
+    .describe('Information about an available model.'));
+export const AccountInfoSchema = lazySchema(() => z
+    .object({
+    email: z.string().optional(),
+    organization: z.string().optional(),
+    subscriptionType: z.string().optional(),
+    tokenSource: z.string().optional(),
+    apiKeySource: z.string().optional(),
+    apiProvider: z
+        .enum(['firstParty', 'bedrock', 'vertex', 'foundry'])
+        .optional()
+        .describe('Active API backend. OAuth login only applies when "firstParty"; for 3P providers the other fields are absent and auth is external (AWS creds, gcloud ADC, etc.).'),
+})
+    .describe("Information about the logged in user's account."));
+// ============================================================================
+// Agent Definition Types
+// ============================================================================
+export const AgentMcpServerSpecSchema = lazySchema(() => z.union([
+    z.string(),
+    z.record(z.string(), McpServerConfigForProcessTransportSchema()),
+]));
+export const AgentDefinitionSchema = lazySchema(() => z
+    .object({
+    description: z
+        .string()
+        .describe('Natural language description of when to use this agent'),
+    tools: z
+        .array(z.string())
+        .optional()
+        .describe('Array of allowed tool names. If omitted, inherits all tools from parent'),
+    disallowedTools: z
+        .array(z.string())
+        .optional()
+        .describe('Array of tool names to explicitly disallow for this agent'),
+    prompt: z.string().describe("The agent's system prompt"),
+    model: z
+        .string()
+        .optional()
+        .describe("Model alias (e.g. 'sonnet', 'opus', 'haiku') or full model ID (e.g. 'claude-opus-4-5'). If omitted or 'inherit', uses the main model"),
+    mcpServers: z.array(AgentMcpServerSpecSchema()).optional(),
+    criticalSystemReminder_EXPERIMENTAL: z
+        .string()
+        .optional()
+        .describe('Experimental: Critical reminder added to system prompt'),
+    skills: z
+        .array(z.string())
+        .optional()
+        .describe('Array of skill names to preload into the agent context'),
+    initialPrompt: z
+        .string()
+        .optional()
+        .describe('Auto-submitted as the first user turn when this agent is the main thread agent. Slash commands are processed. Prepended to any user-provided prompt.'),
+    maxTurns: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Maximum number of agentic turns (API round-trips) before stopping'),
+    background: z
+        .boolean()
+        .optional()
+        .describe('Run this agent as a background task (non-blocking, fire-and-forget) when invoked'),
+    memory: z
+        .enum(['user', 'project', 'local'])
+        .optional()
+        .describe("Scope for auto-loading agent memory files. 'user' - ~/.claude/agent-memory/<agentType>/, 'project' - .claude/agent-memory/<agentType>/, 'local' - .claude/agent-memory-local/<agentType>/"),
+    effort: z
+        .union([z.enum(['low', 'medium', 'high', 'max']), z.number().int()])
+        .optional()
+        .describe('Reasoning effort level for this agent. Either a named level or an integer'),
+    permissionMode: PermissionModeSchema()
+        .optional()
+        .describe('Permission mode controlling how tool executions are handled'),
+})
+    .describe('Definition for a custom subagent that can be invoked via the Agent tool.'));
+// ============================================================================
+// Settings Types
+// ============================================================================
+export const SettingSourceSchema = lazySchema(() => z
+    .enum(['user', 'project', 'local'])
+    .describe('Source for loading filesystem-based settings. ' +
+    "'user' - Global user settings (~/.claude/settings.json). " +
+    "'project' - Project settings (.claude/settings.json). " +
+    "'local' - Local settings (.claude/settings.local.json)."));
+export const SdkPluginConfigSchema = lazySchema(() => z
+    .object({
+    type: z
+        .literal('local')
+        .describe("Plugin type. Currently only 'local' is supported"),
+    path: z
+        .string()
+        .describe('Absolute or relative path to the plugin directory'),
+})
+    .describe('Configuration for loading a plugin.'));
+// ============================================================================
+// Rewind Types
+// ============================================================================
+export const RewindFilesResultSchema = lazySchema(() => z
+    .object({
+    canRewind: z.boolean(),
+    error: z.string().optional(),
+    filesChanged: z.array(z.string()).optional(),
+    insertions: z.number().optional(),
+    deletions: z.number().optional(),
+})
+    .describe('Result of a rewindFiles operation.'));
+// ============================================================================
+// External Type Placeholders
+// ============================================================================
+//
+// These schemas use z.unknown() as placeholders for external types.
+// The generation script uses TypeOverrideMap to output the correct TS type references.
+// This allows us to define SDK message types in Zod while maintaining proper typing.
+/** Placeholder for APIUserMessage from @anthropic-ai/sdk */
+export const APIUserMessagePlaceholder = lazySchema(() => z.unknown());
+/** Placeholder for APIAssistantMessage from @anthropic-ai/sdk */
+export const APIAssistantMessagePlaceholder = lazySchema(() => z.unknown());
+/** Placeholder for RawMessageStreamEvent from @anthropic-ai/sdk */
+export const RawMessageStreamEventPlaceholder = lazySchema(() => z.unknown());
+/** Placeholder for UUID from crypto */
+export const UUIDPlaceholder = lazySchema(() => z.string());
+/** Placeholder for NonNullableUsage (mapped type over Usage) */
+export const NonNullableUsagePlaceholder = lazySchema(() => z.unknown());
+// ============================================================================
+// SDK Message Types
+// ============================================================================
+export const SDKAssistantMessageErrorSchema = lazySchema(() => z.enum([
+    'authentication_failed',
+    'billing_error',
+    'rate_limit',
+    'invalid_request',
+    'server_error',
+    'unknown',
+    'max_output_tokens',
+]));
+export const SDKStatusSchema = lazySchema(() => z.union([z.literal('compacting'), z.null()]));
+// SDKUserMessage content without uuid/session_id
+const SDKUserMessageContentSchema = lazySchema(() => z.object({
+    type: z.literal('user'),
+    message: APIUserMessagePlaceholder(),
+    parent_tool_use_id: z.string().nullable(),
+    isSynthetic: z.boolean().optional(),
+    tool_use_result: z.unknown().optional(),
+    priority: z.enum(['now', 'next', 'later']).optional(),
+    timestamp: z
+        .string()
+        .optional()
+        .describe('ISO timestamp when the message was created on the originating process. Older emitters omit it; consumers should fall back to receive time.'),
+}));
+export const SDKUserMessageSchema = lazySchema(() => SDKUserMessageContentSchema().extend({
+    uuid: UUIDPlaceholder().optional(),
+    session_id: z.string().optional(),
+}));
+export const SDKUserMessageReplaySchema = lazySchema(() => SDKUserMessageContentSchema().extend({
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+    isReplay: z.literal(true),
+}));
+export const SDKRateLimitInfoSchema = lazySchema(() => z
+    .object({
+    status: z.enum(['allowed', 'allowed_warning', 'rejected']),
+    resetsAt: z.number().optional(),
+    rateLimitType: z
+        .enum([
+        'five_hour',
+        'seven_day',
+        'seven_day_opus',
+        'seven_day_sonnet',
+        'overage',
+    ])
+        .optional(),
+    utilization: z.number().optional(),
+    overageStatus: z
+        .enum(['allowed', 'allowed_warning', 'rejected'])
+        .optional(),
+    overageResetsAt: z.number().optional(),
+    overageDisabledReason: z
+        .enum([
+        'overage_not_provisioned',
+        'org_level_disabled',
+        'org_level_disabled_until',
+        'out_of_credits',
+        'seat_tier_level_disabled',
+        'member_level_disabled',
+        'seat_tier_zero_credit_limit',
+        'group_zero_credit_limit',
+        'member_zero_credit_limit',
+        'org_service_level_disabled',
+        'org_service_zero_credit_limit',
+        'no_limits_configured',
+        'unknown',
+    ])
+        .optional(),
+    isUsingOverage: z.boolean().optional(),
+    surpassedThreshold: z.number().optional(),
+})
+    .describe('Rate limit information for claude.ai subscription users.'));
+export const SDKAssistantMessageSchema = lazySchema(() => z.object({
+    type: z.literal('assistant'),
+    message: APIAssistantMessagePlaceholder(),
+    parent_tool_use_id: z.string().nullable(),
+    error: SDKAssistantMessageErrorSchema().optional(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+}));
+export const SDKRateLimitEventSchema = lazySchema(() => z
+    .object({
+    type: z.literal('rate_limit_event'),
+    rate_limit_info: SDKRateLimitInfoSchema(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+})
+    .describe('Rate limit event emitted when rate limit info changes.'));
+export const SDKStreamlinedTextMessageSchema = lazySchema(() => z
+    .object({
+    type: z.literal('streamlined_text'),
+    text: z
+        .string()
+        .describe('Text content preserved from the assistant message'),
+    session_id: z.string(),
+    uuid: UUIDPlaceholder(),
+})
+    .describe('@internal Streamlined text message - replaces SDKAssistantMessage in streamlined output. Text content preserved, thinking and tool_use blocks removed.'));
+export const SDKStreamlinedToolUseSummaryMessageSchema = lazySchema(() => z
+    .object({
+    type: z.literal('streamlined_tool_use_summary'),
+    tool_summary: z
+        .string()
+        .describe('Summary of tool calls (e.g., "Read 2 files, wrote 1 file")'),
+    session_id: z.string(),
+    uuid: UUIDPlaceholder(),
+})
+    .describe('@internal Streamlined tool use summary - replaces tool_use blocks in streamlined output with a cumulative summary string.'));
+export const SDKPermissionDenialSchema = lazySchema(() => z.object({
+    tool_name: z.string(),
+    tool_use_id: z.string(),
+    tool_input: z.record(z.string(), z.unknown()),
+}));
+export const SDKResultSuccessSchema = lazySchema(() => z.object({
+    type: z.literal('result'),
+    subtype: z.literal('success'),
+    duration_ms: z.number(),
+    duration_api_ms: z.number(),
+    is_error: z.boolean(),
+    num_turns: z.number(),
+    result: z.string(),
+    stop_reason: z.string().nullable(),
+    total_cost_usd: z.number(),
+    usage: NonNullableUsagePlaceholder(),
+    modelUsage: z.record(z.string(), ModelUsageSchema()),
+    permission_denials: z.array(SDKPermissionDenialSchema()),
+    structured_output: z.unknown().optional(),
+    fast_mode_state: FastModeStateSchema().optional(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+}));
+export const SDKResultErrorSchema = lazySchema(() => z.object({
+    type: z.literal('result'),
+    subtype: z.enum([
+        'error_during_execution',
+        'error_max_turns',
+        'error_max_budget_usd',
+        'error_max_structured_output_retries',
+    ]),
+    duration_ms: z.number(),
+    duration_api_ms: z.number(),
+    is_error: z.boolean(),
+    num_turns: z.number(),
+    stop_reason: z.string().nullable(),
+    total_cost_usd: z.number(),
+    usage: NonNullableUsagePlaceholder(),
+    modelUsage: z.record(z.string(), ModelUsageSchema()),
+    permission_denials: z.array(SDKPermissionDenialSchema()),
+    errors: z.array(z.string()),
+    fast_mode_state: FastModeStateSchema().optional(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+}));
+export const SDKResultMessageSchema = lazySchema(() => z.union([SDKResultSuccessSchema(), SDKResultErrorSchema()]));
+export const SDKSystemMessageSchema = lazySchema(() => z.object({
+    type: z.literal('system'),
+    subtype: z.literal('init'),
+    agents: z.array(z.string()).optional(),
+    apiKeySource: ApiKeySourceSchema(),
+    betas: z.array(z.string()).optional(),
+    claude_code_version: z.string(),
+    cwd: z.string(),
+    tools: z.array(z.string()),
+    mcp_servers: z.array(z.object({
+        name: z.string(),
+        status: z.string(),
+    })),
+    model: z.string(),
+    permissionMode: PermissionModeSchema(),
+    slash_commands: z.array(z.string()),
+    output_style: z.string(),
+    skills: z.array(z.string()),
+    plugins: z.array(z.object({
+        name: z.string(),
+        path: z.string(),
+        source: z
+            .string()
+            .optional()
+            .describe('@internal Plugin source identifier in "name\\@marketplace" format. Sentinels: "name\\@inline" for --plugin-dir, "name\\@builtin" for built-in plugins.'),
+    })),
+    fast_mode_state: FastModeStateSchema().optional(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+}));
+export const SDKPartialAssistantMessageSchema = lazySchema(() => z.object({
+    type: z.literal('stream_event'),
+    event: RawMessageStreamEventPlaceholder(),
+    parent_tool_use_id: z.string().nullable(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+}));
+export const SDKCompactBoundaryMessageSchema = lazySchema(() => z.object({
+    type: z.literal('system'),
+    subtype: z.literal('compact_boundary'),
+    compact_metadata: z.object({
+        trigger: z.enum(['manual', 'auto']),
+        pre_tokens: z.number(),
+        preserved_segment: z
+            .object({
+            head_uuid: UUIDPlaceholder(),
+            anchor_uuid: UUIDPlaceholder(),
+            tail_uuid: UUIDPlaceholder(),
+        })
+            .optional()
+            .describe('Relink info for messagesToKeep. Loaders splice the preserved ' +
+            'segment at anchor_uuid (summary for suffix-preserving, ' +
+            'boundary for prefix-preserving partial compact) so resume ' +
+            'includes preserved content. Unset when compaction summarizes ' +
+            'everything (no messagesToKeep).'),
+    }),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+}));
+export const SDKStatusMessageSchema = lazySchema(() => z.object({
+    type: z.literal('system'),
+    subtype: z.literal('status'),
+    status: SDKStatusSchema(),
+    permissionMode: PermissionModeSchema().optional(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+}));
+export const SDKPostTurnSummaryMessageSchema = lazySchema(() => z
+    .object({
+    type: z.literal('system'),
+    subtype: z.literal('post_turn_summary'),
+    summarizes_uuid: z.string(),
+    status_category: z.enum([
+        'blocked',
+        'waiting',
+        'completed',
+        'review_ready',
+        'failed',
+    ]),
+    status_detail: z.string(),
+    is_noteworthy: z.boolean(),
+    title: z.string(),
+    description: z.string(),
+    recent_action: z.string(),
+    needs_action: z.string(),
+    artifact_urls: z.array(z.string()),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+})
+    .describe('@internal Background post-turn summary emitted after each assistant turn. summarizes_uuid points to the assistant message this summarizes.'));
+export const SDKAPIRetryMessageSchema = lazySchema(() => z
+    .object({
+    type: z.literal('system'),
+    subtype: z.literal('api_retry'),
+    attempt: z.number(),
+    max_retries: z.number(),
+    retry_delay_ms: z.number(),
+    error_status: z.number().nullable(),
+    error: SDKAssistantMessageErrorSchema(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+})
+    .describe('Emitted when an API request fails with a retryable error and will be retried after a delay. error_status is null for connection errors (e.g. timeouts) that had no HTTP response.'));
+export const SDKLocalCommandOutputMessageSchema = lazySchema(() => z
+    .object({
+    type: z.literal('system'),
+    subtype: z.literal('local_command_output'),
+    content: z.string(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+})
+    .describe('Output from a local slash command (e.g. /voice, /cost). Displayed as assistant-style text in the transcript.'));
+export const SDKHookStartedMessageSchema = lazySchema(() => z.object({
+    type: z.literal('system'),
+    subtype: z.literal('hook_started'),
+    hook_id: z.string(),
+    hook_name: z.string(),
+    hook_event: z.string(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+}));
+export const SDKHookProgressMessageSchema = lazySchema(() => z.object({
+    type: z.literal('system'),
+    subtype: z.literal('hook_progress'),
+    hook_id: z.string(),
+    hook_name: z.string(),
+    hook_event: z.string(),
+    stdout: z.string(),
+    stderr: z.string(),
+    output: z.string(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+}));
+export const SDKHookResponseMessageSchema = lazySchema(() => z.object({
+    type: z.literal('system'),
+    subtype: z.literal('hook_response'),
+    hook_id: z.string(),
+    hook_name: z.string(),
+    hook_event: z.string(),
+    output: z.string(),
+    stdout: z.string(),
+    stderr: z.string(),
+    exit_code: z.number().optional(),
+    outcome: z.enum(['success', 'error', 'cancelled']),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+}));
+export const SDKToolProgressMessageSchema = lazySchema(() => z.object({
+    type: z.literal('tool_progress'),
+    tool_use_id: z.string(),
+    tool_name: z.string(),
+    parent_tool_use_id: z.string().nullable(),
+    elapsed_time_seconds: z.number(),
+    task_id: z.string().optional(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+}));
+export const SDKAuthStatusMessageSchema = lazySchema(() => z.object({
+    type: z.literal('auth_status'),
+    isAuthenticating: z.boolean(),
+    output: z.array(z.string()),
+    error: z.string().optional(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+}));
+export const SDKFilesPersistedEventSchema = lazySchema(() => z.object({
+    type: z.literal('system'),
+    subtype: z.literal('files_persisted'),
+    files: z.array(z.object({
+        filename: z.string(),
+        file_id: z.string(),
+    })),
+    failed: z.array(z.object({
+        filename: z.string(),
+        error: z.string(),
+    })),
+    processed_at: z.string(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+}));
+export const SDKTaskNotificationMessageSchema = lazySchema(() => z.object({
+    type: z.literal('system'),
+    subtype: z.literal('task_notification'),
+    task_id: z.string(),
+    tool_use_id: z.string().optional(),
+    status: z.enum(['completed', 'failed', 'stopped']),
+    output_file: z.string(),
+    summary: z.string(),
+    usage: z
+        .object({
+        total_tokens: z.number(),
+        tool_uses: z.number(),
+        duration_ms: z.number(),
+    })
+        .optional(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+}));
+export const SDKTaskStartedMessageSchema = lazySchema(() => z.object({
+    type: z.literal('system'),
+    subtype: z.literal('task_started'),
+    task_id: z.string(),
+    tool_use_id: z.string().optional(),
+    description: z.string(),
+    task_type: z.string().optional(),
+    workflow_name: z
+        .string()
+        .optional()
+        .describe("meta.name from the workflow script (e.g. 'spec'). Only set when task_type is 'local_workflow'."),
+    prompt: z.string().optional(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+}));
+export const SDKSessionStateChangedMessageSchema = lazySchema(() => z
+    .object({
+    type: z.literal('system'),
+    subtype: z.literal('session_state_changed'),
+    state: z.enum(['idle', 'running', 'requires_action']),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+})
+    .describe("Mirrors notifySessionStateChanged. 'idle' fires after heldBackResult flushes and the bg-agent do-while exits — authoritative turn-over signal."));
+export const SDKTaskProgressMessageSchema = lazySchema(() => z.object({
+    type: z.literal('system'),
+    subtype: z.literal('task_progress'),
+    task_id: z.string(),
+    tool_use_id: z.string().optional(),
+    description: z.string(),
+    usage: z.object({
+        total_tokens: z.number(),
+        tool_uses: z.number(),
+        duration_ms: z.number(),
+    }),
+    last_tool_name: z.string().optional(),
+    summary: z.string().optional(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+}));
+export const SDKToolUseSummaryMessageSchema = lazySchema(() => z.object({
+    type: z.literal('tool_use_summary'),
+    summary: z.string(),
+    preceding_tool_use_ids: z.array(z.string()),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+}));
+export const SDKElicitationCompleteMessageSchema = lazySchema(() => z
+    .object({
+    type: z.literal('system'),
+    subtype: z.literal('elicitation_complete'),
+    mcp_server_name: z.string(),
+    elicitation_id: z.string(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+})
+    .describe('Emitted when an MCP server confirms that a URL-mode elicitation is complete.'));
+/** @internal */
+export const SDKPromptSuggestionMessageSchema = lazySchema(() => z
+    .object({
+    type: z.literal('prompt_suggestion'),
+    suggestion: z.string(),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+})
+    .describe('Predicted next user prompt, emitted after each turn when promptSuggestions is enabled.'));
+// ============================================================================
+// Session Listing Types
+// ============================================================================
+export const SDKSessionInfoSchema = lazySchema(() => z
+    .object({
+    sessionId: z.string().describe('Unique session identifier (UUID).'),
+    summary: z
+        .string()
+        .describe('Display title for the session: custom title, auto-generated summary, or first prompt.'),
+    lastModified: z
+        .number()
+        .describe('Last modified time in milliseconds since epoch.'),
+    fileSize: z
+        .number()
+        .optional()
+        .describe('File size in bytes. Only populated for local JSONL storage.'),
+    customTitle: z
+        .string()
+        .optional()
+        .describe('User-set session title via /rename.'),
+    firstPrompt: z
+        .string()
+        .optional()
+        .describe('First meaningful user prompt in the session.'),
+    gitBranch: z
+        .string()
+        .optional()
+        .describe('Git branch at the end of the session.'),
+    cwd: z.string().optional().describe('Working directory for the session.'),
+    tag: z.string().optional().describe('User-set session tag.'),
+    createdAt: z
+        .number()
+        .optional()
+        .describe("Creation time in milliseconds since epoch, extracted from the first entry's timestamp."),
+})
+    .describe('Session metadata returned by listSessions and getSessionInfo.'));
+export const SDKMessageSchema = lazySchema(() => z.union([
+    SDKAssistantMessageSchema(),
+    SDKUserMessageSchema(),
+    SDKUserMessageReplaySchema(),
+    SDKResultMessageSchema(),
+    SDKSystemMessageSchema(),
+    SDKPartialAssistantMessageSchema(),
+    SDKCompactBoundaryMessageSchema(),
+    SDKStatusMessageSchema(),
+    SDKAPIRetryMessageSchema(),
+    SDKLocalCommandOutputMessageSchema(),
+    SDKHookStartedMessageSchema(),
+    SDKHookProgressMessageSchema(),
+    SDKHookResponseMessageSchema(),
+    SDKToolProgressMessageSchema(),
+    SDKAuthStatusMessageSchema(),
+    SDKTaskNotificationMessageSchema(),
+    SDKTaskStartedMessageSchema(),
+    SDKTaskProgressMessageSchema(),
+    SDKSessionStateChangedMessageSchema(),
+    SDKFilesPersistedEventSchema(),
+    SDKToolUseSummaryMessageSchema(),
+    SDKRateLimitEventSchema(),
+    SDKElicitationCompleteMessageSchema(),
+    SDKPromptSuggestionMessageSchema(),
+]));
+export const FastModeStateSchema = lazySchema(() => z
+    .enum(['off', 'cooldown', 'on'])
+    .describe('Fast mode state: off, in cooldown after rate limit, or actively enabled.'));