Type Reference

interface Query extends AsyncGenerator<SDKMessage, void> {
  interrupt(): Promise<void>;
  setPermissionMode(mode: PermissionMode): Promise<void>;
  setModel(model?: string): Promise<void>;
  setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;
  supportedCommands(): Promise<SlashCommand[]>;
  supportedModels(): Promise<ModelInfo[]>;
  mcpServerStatus(): Promise<McpServerStatus[]>;
  accountInfo(): Promise<AccountInfo>;
  streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;
}

interface SDKSession {
  send(message: string | SDKUserMessage): Promise<void>;
  receive(): AsyncGenerator<SDKMessage, void>;
  close(): void;
  [Symbol.asyncDispose](): Promise<void>;
}

interface SDKSessionOptions {
  model: string;
  pathToClaudeCodeExecutable?: string;
  executable?: 'node' | 'bun' | 'deno';
  executableArgs?: string[];
}

type SDKMessage =
  | SDKAssistantMessage
  | SDKUserMessage
  | SDKUserMessageReplay
  | SDKResultMessage
  | SDKSystemMessage
  | SDKPartialAssistantMessage
  | SDKCompactBoundaryMessage
  | SDKStatusMessage
  | SDKHookResponseMessage
  | SDKToolProgressMessage
  | SDKAuthStatusMessage;

interface SDKAssistantMessage {
  type: 'assistant';
  message: APIAssistantMessage;
  parent_tool_use_id: string | null;
  error?: 'authentication_failed' | 'billing_error' | 'rate_limit' | 'invalid_request' | 'server_error' | 'unknown';
  uuid: UUID;
  session_id: string;
}

interface SDKUserMessage {
  type: 'user';
  message: APIUserMessage;
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  tool_use_result?: unknown;
  uuid?: UUID;
  session_id: string;
}

interface SDKResultMessageSuccess {
  type: 'result';
  subtype: 'success';
  duration_ms: number;
  duration_api_ms: number;
  is_error: boolean;
  num_turns: number;
  result: string;
  total_cost_usd: number;
  usage: NonNullableUsage;
  modelUsage: {[modelName: string]: ModelUsage};
  permission_denials: SDKPermissionDenial[];
  structured_output?: unknown;
  uuid: UUID;
  session_id: string;
}

interface SDKResultMessageError {
  type: 'result';
  subtype: 'error_during_execution' | 'error_max_turns' | 'error_max_budget_usd' | 'error_max_structured_output_retries';
  duration_ms: number;
  duration_api_ms: number;
  is_error: boolean;
  num_turns: number;
  total_cost_usd: number;
  usage: NonNullableUsage;
  modelUsage: {[modelName: string]: ModelUsage};
  permission_denials: SDKPermissionDenial[];
  errors: string[];
  uuid: UUID;
  session_id: string;
}

type SDKResultMessage = SDKResultMessageSuccess | SDKResultMessageError;

interface SDKSystemMessage {
  type: 'system';
  subtype: 'init';
  agents?: string[];
  apiKeySource: ApiKeySource;
  betas?: string[];
  claude_code_version: string;
  cwd: string;
  tools: string[];
  mcp_servers: {name: string; status: string}[];
  model: string;
  permissionMode: PermissionMode;
  slash_commands: string[];
  output_style: string;
  skills: string[];
  plugins: {name: string; path: string}[];
  uuid: UUID;
  session_id: string;
}

interface SDKToolProgressMessage {
  type: 'tool_progress';
  tool_use_id: string;
  tool_name: string;
  parent_tool_use_id: string | null;
  elapsed_time_seconds: number;
  uuid: UUID;
  session_id: string;
}

interface SDKAuthStatusMessage {
  type: 'auth_status';
  isAuthenticating: boolean;
  output: string[];
  error?: string;
  uuid: UUID;
  session_id: string;
}

interface SDKPartialAssistantMessage {
  type: 'stream_event';
  event: RawMessageStreamEvent;
  parent_tool_use_id: string | null;
  uuid: UUID;
  session_id: string;
}

interface SDKUserMessageReplay {
  type: 'user';
  message: APIUserMessage;
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  tool_use_result?: unknown;
  uuid: UUID;
  session_id: string;
  isReplay: true;
}

interface SDKCompactBoundaryMessage {
  type: 'system';
  subtype: 'compact_boundary';
  compact_metadata: {trigger: 'manual' | 'auto'; pre_tokens: number};
  uuid: UUID;
  session_id: string;
}

interface SDKStatusMessage {
  type: 'system';
  subtype: 'status';
  status: 'compacting' | null;
  uuid: UUID;
  session_id: string;
}

interface SDKHookResponseMessage {
  type: 'system';
  subtype: 'hook_response';
  hook_name: string;
  hook_event: string;
  stdout: string;
  stderr: string;
  exit_code?: number;
  uuid: UUID;
  session_id: string;
}

interface Options {
  abortController?: AbortController;
  additionalDirectories?: string[];
  agents?: Record<string, AgentDefinition>;
  allowedTools?: string[];
  disallowedTools?: string[];
  tools?: string[] | {type: 'preset'; preset: 'claude_code'};
  model?: string;
  fallbackModel?: string;
  cwd?: string;
  env?: {[envVar: string]: string | undefined};
  executable?: 'bun' | 'deno' | 'node';
  executableArgs?: string[];
  pathToClaudeCodeExecutable?: string;
  extraArgs?: Record<string, string | null>;
  permissionMode?: PermissionMode;
  allowDangerouslySkipPermissions?: boolean;
  canUseTool?: CanUseTool;
  permissionPromptToolName?: string;
  maxTurns?: number;
  maxBudgetUsd?: number;
  maxThinkingTokens?: number;
  hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
  mcpServers?: Record<string, McpServerConfig>;
  strictMcpConfig?: boolean;
  systemPrompt?: string | {type: 'preset'; preset: 'claude_code'; append?: string};
  outputFormat?: OutputFormat;
  includePartialMessages?: boolean;
  continue?: boolean;
  resume?: string;
  resumeSessionAt?: string;
  forkSession?: boolean;
  settingSources?: SettingSource[];
  plugins?: SdkPluginConfig[];
  sandbox?: SandboxSettings;
  betas?: SdkBeta[];
  stderr?: (data: string) => void;
}

type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk';

type CanUseTool = (
  toolName: string,
  input: Record<string, unknown>,
  options: {
    signal: AbortSignal;
    suggestions?: PermissionUpdate[];
    blockedPath?: string;
    decisionReason?: string;
    toolUseID: string;
    agentID?: string;
  }
) => Promise<PermissionResult>;

type PermissionResult =
  | {behavior: 'allow'; updatedInput: Record<string, unknown>; updatedPermissions?: PermissionUpdate[]; toolUseID?: string}
  | {behavior: 'deny'; message: string; interrupt?: boolean; toolUseID?: string};

type PermissionUpdate =
  | {type: 'addRules'; rules: PermissionRuleValue[]; behavior: PermissionBehavior; destination: PermissionUpdateDestination}
  | {type: 'replaceRules'; rules: PermissionRuleValue[]; behavior: PermissionBehavior; destination: PermissionUpdateDestination}
  | {type: 'removeRules'; rules: PermissionRuleValue[]; behavior: PermissionBehavior; destination: PermissionUpdateDestination}
  | {type: 'setMode'; mode: PermissionMode; destination: PermissionUpdateDestination}
  | {type: 'addDirectories'; directories: string[]; destination: PermissionUpdateDestination}
  | {type: 'removeDirectories'; directories: string[]; destination: PermissionUpdateDestination};

interface PermissionRuleValue {
  toolName: string;
  ruleContent?: string;
}

type PermissionBehavior = 'allow' | 'deny' | 'ask';
type PermissionUpdateDestination = 'userSettings' | 'projectSettings' | 'localSettings' | 'session' | 'cliArg';

interface SDKPermissionDenial {
  tool_name: string;
  tool_use_id: string;
  tool_input: Record<string, unknown>;
}

type HookEvent = 'PreToolUse' | 'PostToolUse' | 'PostToolUseFailure' | 'PermissionRequest'
  | 'UserPromptSubmit' | 'SessionStart' | 'SessionEnd' | 'Stop'
  | 'SubagentStart' | 'SubagentStop' | 'PreCompact' | 'Notification';

type HookCallback = (
  input: HookInput,
  toolUseID: string | undefined,
  options: {signal: AbortSignal}
) => Promise<HookJSONOutput>;

interface HookCallbackMatcher {
  matcher?: string;
  hooks: HookCallback[];
  timeout?: number;
}

interface BaseHookInput {
  session_id: string;
  transcript_path: string;
  cwd: string;
  permission_mode?: string;
}

interface PreToolUseHookInput extends BaseHookInput {
  hook_event_name: 'PreToolUse';
  tool_name: string;
  tool_input: unknown;
  tool_use_id: string;
}

interface PostToolUseHookInput extends BaseHookInput {
  hook_event_name: 'PostToolUse';
  tool_name: string;
  tool_input: unknown;
  tool_response: unknown;
  tool_use_id: string;
}

interface PostToolUseFailureHookInput extends BaseHookInput {
  hook_event_name: 'PostToolUseFailure';
  tool_name: string;
  tool_input: unknown;
  tool_use_id: string;
  error: string;
  is_interrupt?: boolean;
}

interface PermissionRequestHookInput extends BaseHookInput {
  hook_event_name: 'PermissionRequest';
  tool_name: string;
  tool_input: unknown;
  permission_suggestions?: PermissionUpdate[];
}

interface UserPromptSubmitHookInput extends BaseHookInput {
  hook_event_name: 'UserPromptSubmit';
  prompt: string;
}

interface SessionStartHookInput extends BaseHookInput {
  hook_event_name: 'SessionStart';
  source: 'startup' | 'resume' | 'clear' | 'compact';
}

interface SessionEndHookInput extends BaseHookInput {
  hook_event_name: 'SessionEnd';
  reason: ExitReason;
}

interface SubagentStartHookInput extends BaseHookInput {
  hook_event_name: 'SubagentStart';
  agent_id: string;
  agent_type: string;
}

interface SubagentStopHookInput extends BaseHookInput {
  hook_event_name: 'SubagentStop';
  stop_hook_active: boolean;
  agent_id: string;
  agent_transcript_path: string;
}

type HookInput = PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput
  | PermissionRequestHookInput | UserPromptSubmitHookInput | SessionStartHookInput
  | SessionEndHookInput | SubagentStartHookInput | SubagentStopHookInput
  | NotificationHookInput | StopHookInput | PreCompactHookInput;

interface SyncHookJSONOutput {
  continue?: boolean;
  suppressOutput?: boolean;
  stopReason?: string;
  decision?: 'approve' | 'block';
  systemMessage?: string;
  reason?: string;
  hookSpecificOutput?:
    | {hookEventName: 'PreToolUse'; permissionDecision?: 'allow' | 'deny' | 'ask'; permissionDecisionReason?: string; updatedInput?: Record<string, unknown>}
    | {hookEventName: 'UserPromptSubmit'; additionalContext?: string}
    | {hookEventName: 'SessionStart'; additionalContext?: string}
    | {hookEventName: 'SubagentStart'; additionalContext?: string}
    | {hookEventName: 'PostToolUse'; additionalContext?: string; updatedMCPToolOutput?: unknown}
    | {hookEventName: 'PostToolUseFailure'; additionalContext?: string}
    | {hookEventName: 'PermissionRequest'; decision: {behavior: 'allow'; updatedInput?: Record<string, unknown>; updatedPermissions?: PermissionUpdate[]} | {behavior: 'deny'; message?: string; interrupt?: boolean}};
}

interface AsyncHookJSONOutput {
  async: true;
  asyncTimeout?: number;
}

type HookJSONOutput = SyncHookJSONOutput | AsyncHookJSONOutput;

const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "Notification", "UserPromptSubmit", "SessionStart", "SessionEnd", "Stop", "SubagentStart", "SubagentStop", "PreCompact", "PermissionRequest"];
const EXIT_REASONS: string[];
type ExitReason = typeof EXIT_REASONS[number];

interface AgentDefinition {
  description: string;
  tools?: string[];
  disallowedTools?: string[];
  prompt: string;
  model?: 'sonnet' | 'opus' | 'haiku' | 'inherit';
  criticalSystemReminder_EXPERIMENTAL?: string;
}

type McpServerConfig =
  | McpStdioServerConfig
  | McpSSEServerConfig
  | McpHttpServerConfig
  | McpSdkServerConfigWithInstance;

interface McpStdioServerConfig {
  type?: 'stdio';
  command: string;
  args?: string[];
  env?: Record<string, string>;
}

interface McpSSEServerConfig {
  type: 'sse';
  url: string;
  headers?: Record<string, string>;
}

interface McpHttpServerConfig {
  type: 'http';
  url: string;
  headers?: Record<string, string>;
}

interface McpSdkServerConfigWithInstance {
  type: 'sdk';
  name: string;
  instance: McpServer;
}

interface McpServerStatus {
  name: string;
  status: 'connected' | 'failed' | 'needs-auth' | 'pending';
  serverInfo?: {name: string; version: string};
}

interface SandboxSettings {
  enabled?: boolean;
  autoAllowBashIfSandboxed?: boolean;
  allowUnsandboxedCommands?: boolean;
  network?: SandboxNetworkConfig;
  ignoreViolations?: Record<string, string[]>;
  enableWeakerNestedSandbox?: boolean;
  excludedCommands?: string[];
  ripgrep?: {command: string; args?: string[]};
}

interface SandboxNetworkConfig {
  allowUnixSockets?: string[];
  allowAllUnixSockets?: boolean;
  allowLocalBinding?: boolean;
  httpProxyPort?: number;
  socksProxyPort?: number;
}

type ToolInputSchemas = AgentInput | BashInput | BashOutputInput | FileReadInput
  | FileEditInput | FileWriteInput | GlobInput | GrepInput | WebFetchInput
  | WebSearchInput | TodoWriteInput | NotebookEditInput | McpInput
  | ListMcpResourcesInput | ReadMcpResourceInput | KillShellInput
  | ExitPlanModeInput | AskUserQuestionInput;

interface FileReadInput {
  file_path: string;
  offset?: number;
  limit?: number;
}

interface FileEditInput {
  file_path: string;
  old_string: string;
  new_string: string;
  replace_all?: boolean;
}

interface FileWriteInput {
  file_path: string;
  content: string;
}

interface GlobInput {
  pattern: string;
  path?: string;
}

interface GrepInput {
  pattern: string;
  path?: string;
  glob?: string;
  output_mode?: 'content' | 'files_with_matches' | 'count';
  '-B'?: number;
  '-A'?: number;
  '-C'?: number;
  '-n'?: boolean;
  '-i'?: boolean;
  type?: string;
  head_limit?: number;
  offset?: number;
  multiline?: boolean;
}

interface BashInput {
  command: string;
  timeout?: number;
  description?: string;
  run_in_background?: boolean;
  dangerouslyDisableSandbox?: boolean;
}

interface BashOutputInput {
  bash_id: string;
  filter?: string;
}

interface KillShellInput {
  shell_id: string;
}

interface WebFetchInput {
  url: string;
  prompt: string;
}

interface WebSearchInput {
  query: string;
  allowed_domains?: string[];
  blocked_domains?: string[];
}

interface AgentInput {
  description: string;
  prompt: string;
  subagent_type: string;
  model?: 'sonnet' | 'opus' | 'haiku';
  resume?: string;
}

interface NotebookEditInput {
  notebook_path: string;
  cell_id?: string;
  new_source: string;
  cell_type?: 'code' | 'markdown';
  edit_mode?: 'replace' | 'insert' | 'delete';
}

interface TodoWriteInput {
  todos: Array<{content: string; status: 'pending' | 'in_progress' | 'completed'; activeForm: string}>;
}

interface ListMcpResourcesInput {
  server?: string;
}

interface ReadMcpResourceInput {
  server: string;
  uri: string;
}

interface McpInput {
  [k: string]: unknown;
}

interface ExitPlanModeInput {
  [k: string]: unknown;
}

interface AskUserQuestionInput {
  questions: Array<{
    question: string;
    header: string;
    options: Array<{label: string; description: string}>;
    multiSelect: boolean;
  }>;
  answers?: {[k: string]: string};
}

interface ModelUsage {
  inputTokens: number;
  outputTokens: number;
  cacheReadInputTokens: number;
  cacheCreationInputTokens: number;
  webSearchRequests: number;
  costUSD: number;
  contextWindow: number;
}

interface AccountInfo {
  email?: string;
  organization?: string;
  subscriptionType?: string;
  tokenSource?: string;
  apiKeySource?: string;
}

interface ModelInfo {
  value: string;
  displayName: string;
  description: string;
}

interface SlashCommand {
  name: string;
  description: string;
  argumentHint: string;
}

interface OutputFormat {
  type: 'json_schema';
  schema: Record<string, unknown>;
}

interface SdkPluginConfig {
  type: 'local';
  path: string;
}

type NonNullableUsage = {[K in keyof Usage]: NonNullable<Usage[K]>};
type ApiKeySource = 'user' | 'project' | 'org' | 'temporary';
type ConfigScope = 'local' | 'user' | 'project';
type SdkBeta = 'context-1m-2025-08-07';
type SettingSource = 'user' | 'project' | 'local';
type UUID = string;

class AbortError extends Error {}