Quick Reference

// Main query API
query(_params: {prompt: string | AsyncIterable<SDKUserMessage>; options?: Options}): Query

// V2 Session API (unstable)
unstable_v2_createSession(_options: SDKSessionOptions): SDKSession
unstable_v2_resumeSession(_sessionId: string, _options: SDKSessionOptions): SDKSession
unstable_v2_prompt(_message: string, _options: SDKSessionOptions): Promise<SDKResultMessage>

// MCP
createSdkMcpServer(_options: {name: string; version?: string; tools?: Array<SdkMcpToolDefinition<any>>}): McpSdkServerConfigWithInstance
tool<Schema extends ZodRawShape>(_name: string, _description: string, _inputSchema: Schema, _handler: (args: z.infer<ZodObject<Schema>>, extra: unknown) => Promise<CallToolResult>): SdkMcpToolDefinition<Schema>

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 Options {
  // Model & execution
  model?: string
  cwd?: string
  maxTurns?: number
  maxBudgetUsd?: number
  maxThinkingTokens?: number
  abortController?: AbortController

  // Tools
  tools?: string[] | {type: 'preset'; preset: 'claude_code'}
  allowedTools?: string[]
  disallowedTools?: string[]

  // Permissions
  permissionMode?: 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk'
  canUseTool?: CanUseTool
  allowDangerouslySkipPermissions?: boolean

  // Environment
  additionalDirectories?: string[]
  env?: {[key: string]: string | undefined}
  sandbox?: SandboxSettings

  // Extensions
  agents?: Record<string, AgentDefinition>
  hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>
  mcpServers?: Record<string, McpServerConfig>

  // Session
  continue?: boolean
  resume?: string
}

type SDKMessage =
  | SDKAssistantMessage      // Assistant response
  | SDKUserMessage           // User input
  | SDKResultMessage         // Final result
  | SDKSystemMessage         // System info (init, status, hooks)
  | SDKToolProgressMessage   // Tool execution progress
  | SDKAuthStatusMessage     // Auth status
  | SDKPartialAssistantMessage  // Streaming events
  | SDKUserMessageReplay     // Message replay
  | SDKCompactBoundaryMessage   // History compaction marker
  | SDKStatusMessage         // Status updates
  | SDKHookResponseMessage   // Hook execution result

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 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>

// File tools
FileReadInput: {file_path: string; offset?: number; limit?: number}
FileEditInput: {file_path: string; old_string: string; new_string: string; replace_all?: boolean}
FileWriteInput: {file_path: string; content: string}

// Search tools
GlobInput: {pattern: string; path?: string}
GrepInput: {pattern: string; path?: string; glob?: string; output_mode?: string; /* ... */}

// Shell tools
BashInput: {command: string; timeout?: number; run_in_background?: boolean; /* ... */}
BashOutputInput: {bash_id: string; filter?: string}
KillShellInput: {shell_id: string}

// Web tools
WebFetchInput: {url: string; prompt: string}
WebSearchInput: {query: string; allowed_domains?: string[]; blocked_domains?: string[]}

// Agent tools
AgentInput: {description: string; prompt: string; subagent_type: string; model?: string; resume?: string}

// Other tools
TodoWriteInput: {todos: Array<{content: string; status: string; activeForm: string}>}
NotebookEditInput: {notebook_path: string; new_source: string; /* ... */}
AskUserQuestionInput: {questions: Array<{/* ... */}>}

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

type McpServerConfig =
  | {type?: 'stdio'; command: string; args?: string[]; env?: Record<string, string>}
  | {type: 'sse'; url: string; headers?: Record<string, string>}
  | {type: 'http'; url: string; headers?: Record<string, string>}
  | {type: 'sdk'; name: string; instance: McpServer}

interface SandboxSettings {
  enabled?: boolean
  autoAllowBashIfSandboxed?: boolean
  allowUnsandboxedCommands?: boolean
  network?: {
    allowUnixSockets?: string[]
    allowAllUnixSockets?: boolean
    allowLocalBinding?: boolean
    httpProxyPort?: number
    socksProxyPort?: number
  }
  ignoreViolations?: Record<string, string[]>
  enableWeakerNestedSandbox?: boolean
  excludedCommands?: string[]
  ripgrep?: {command: string; args?: string[]}
}