Type Alias Options

Options for the query function. Contains callbacks and other non-serializable fields.

type Options = {
    abortController?: AbortController;
    additionalDirectories?: string[];
    agent?: string;
    agentProgressSummaries?: boolean;
    agents?: Record<string, AgentDefinition>;
    allowDangerouslySkipPermissions?: boolean;
    allowedTools?: string[];
    betas?: SdkBeta[];
    canUseTool?: CanUseTool;
    continue?: boolean;
    cwd?: string;
    debug?: boolean;
    debugFile?: string;
    disallowedTools?: string[];
    effort?: EffortLevel;
    enableFileCheckpointing?: boolean;
    env?: { [envVar: string]: string | undefined };
    executable?: "bun" | "deno" | "node";
    executableArgs?: string[];
    extraArgs?: Record<string, string | null>;
    fallbackModel?: string;
    forkSession?: boolean;
    hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
    includeHookEvents?: boolean;
    includePartialMessages?: boolean;
    maxBudgetUsd?: number;
    maxThinkingTokens?: number;
    maxTurns?: number;
    mcpServers?: Record<string, McpServerConfig>;
    model?: string;
    onElicitation?: OnElicitation;
    outputFormat?: OutputFormat;
    pathToClaudeCodeExecutable?: string;
    permissionMode?: PermissionMode;
    permissionPromptToolName?: string;
    persistSession?: boolean;
    plugins?: SdkPluginConfig[];
    promptSuggestions?: boolean;
    resume?: string;
    resumeSessionAt?: string;
    sandbox?: SandboxSettings;
    sessionId?: string;
    settings?: string | Settings;
    settingSources?: SettingSource[];
    spawnClaudeCodeProcess?: (options: SpawnOptions) => SpawnedProcess;
    stderr?: (data: string) => void;
    strictMcpConfig?: boolean;
    systemPrompt?:
        | string
        | { append?: string; preset: "claude_code"; type: "preset" };
    taskBudget?: { total: number };
    thinking?: ThinkingConfig;
    toolConfig?: ToolConfig;
    tools?: string[] | { preset: "claude_code"; type: "preset" };
}

Claude SDK

`Optional`abortController

abortController?: AbortController

Controller for cancelling the query. When aborted, the query will stop and clean up resources.

`Optional`additionalDirectories

additionalDirectories?: string[]

Additional directories Claude can access beyond the current working directory. Paths should be absolute.

`Optional`agent

agent?: string

Agent name for the main thread. When specified, the agent's system prompt, tool restrictions, and model will be applied to the main conversation. The agent must be defined either in the agents option or in settings.

This is equivalent to the --agent CLI flag.

Example

agent: 'code-reviewer',
agents: {
  'code-reviewer': {
    description: 'Reviews code for best practices',
    prompt: 'You are a code reviewer...'
  }
}

`Optional`agentProgressSummaries

agentProgressSummaries?: boolean

Enable periodic AI-generated progress summaries for running subagents. When true, the subagent's conversation is forked every ~30s to produce a short present-tense description (e.g. "Analyzing authentication module"), emitted on task_progress events via the summary field. The fork reuses the subagent's model and prompt cache, so cost is typically minimal.

Applies to both foreground and background subagents. Defaults to false.

`Optional`agents

agents?: Record<string, AgentDefinition>

Programmatically define custom subagents that can be invoked via the Agent tool. Keys are agent names, values are agent definitions.

Example

agents: {
  'test-runner': {
    description: 'Runs tests and reports results',
    prompt: 'You are a test runner...',
    tools: ['Read', 'Grep', 'Glob', 'Bash']
  }
}

`Optional`allowDangerouslySkipPermissions

allowDangerouslySkipPermissions?: boolean

Must be set to true when using permissionMode: 'bypassPermissions'. This is a safety measure to ensure intentional bypassing of permissions.

`Optional`allowedTools

allowedTools?: string[]

List of tool names that are auto-allowed without prompting for permission. These tools will execute automatically without asking the user for approval. To restrict which tools are available, use the tools option instead.

`Optional`betas

betas?: SdkBeta[]

Enable beta features. Currently supported:

'context-1m-2025-08-07' - Enable 1M token context window (Sonnet 4/4.5 only)

See

https://docs.anthropic.com/en/api/beta-headers

`Optional`canUseTool

canUseTool?: CanUseTool

Custom permission handler for controlling tool usage. Called before each tool execution to determine if it should be allowed, denied, or prompt the user.

`Optional`continue

continue?: boolean

Continue the most recent conversation in the current directory instead of starting a new one. Mutually exclusive with resume.

`Optional`cwd

cwd?: string

Current working directory for the session. Defaults to process.cwd().

`Optional`debug

debug?: boolean

Enable debug mode for the Claude Code process. When true, enables verbose debug logging (equivalent to --debug CLI flag). Debug logs are written to a file (see debugFile option) or to stderr.

You can also capture debug output via the stderr callback.

`Optional`debugFile

debugFile?: string

Write debug logs to a specific file path. Implicitly enables debug mode. Equivalent to --debug-file <path> CLI flag.

`Optional`disallowedTools

disallowedTools?: string[]

List of tool names that are disallowed. These tools will be removed from the model's context and cannot be used, even if they would otherwise be allowed.

`Optional`effort

effort?: EffortLevel

Controls how much effort Claude puts into its response. Works with adaptive thinking to guide thinking depth.

'low' — Minimal thinking, fastest responses
'medium' — Moderate thinking
'high' — Deep reasoning (default)
'max' — Maximum effort (Opus 4.6 only)

See

https://docs.anthropic.com/en/docs/build-with-claude/effort

`Optional`enableFileCheckpointing

enableFileCheckpointing?: boolean

Enable file checkpointing to track file changes during the session. When enabled, files can be rewound to their state at any user message using Query.rewindFiles().

File checkpointing creates backups of files before they are modified, allowing you to restore them to previous states.

`Optional`env

env?: { [envVar: string]: string | undefined }

Environment variables to pass to the Claude Code process. Defaults to process.env.

SDK consumers can identify their app/library to include in the User-Agent header by setting:

CLAUDE_AGENT_SDK_CLIENT_APP - Your app/library identifier (e.g., "my-app/1.0.0", "my-library/2.1")

Example

env: { CLAUDE_AGENT_SDK_CLIENT_APP: 'my-app/1.0.0' }

`Optional`executable

executable?: "bun" | "deno" | "node"

JavaScript runtime to use for executing Claude Code. Auto-detected if not specified.

`Optional`executableArgs

executableArgs?: string[]

Additional arguments to pass to the JavaScript runtime executable.

`Optional`extraArgs

extraArgs?: Record<string, string | null>

Additional CLI arguments to pass to Claude Code. Keys are argument names (without --), values are argument values. Use null for boolean flags.

`Optional`fallbackModel

fallbackModel?: string

Fallback model to use if the primary model fails or is unavailable.

`Optional`forkSession

forkSession?: boolean

When true, resumed sessions will fork to a new session ID rather than continuing the previous session. Use with resume.

`Optional`hooks

hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>

Hook callbacks for responding to various events during execution. Hooks can modify behavior, add context, or implement custom logic.

Example

hooks: {
  PreToolUse: [{
    hooks: [async (input) => ({ continue: true })]
  }]
}

`Optional`includeHookEvents

includeHookEvents?: boolean

Include hook lifecycle events in the output stream. When true, hook_started, hook_progress, and hook_response system messages will be emitted for all hook event types (PreToolUse, PostToolUse, Stop, etc.). SessionStart and Setup hook events are always emitted regardless of this setting.

Default

false

`Optional`includePartialMessages

includePartialMessages?: boolean

Include partial/streaming message events in the output. When true, SDKPartialAssistantMessage events will be emitted during streaming.

`Optional`maxBudgetUsd

maxBudgetUsd?: number

Maximum budget in USD for the query. The query will stop if this budget is exceeded, returning an error_max_budget_usd result.

`Optional`maxThinkingTokens

maxThinkingTokens?: number

Maximum number of tokens the model can use for its thinking/reasoning process. Helps control cost and latency for complex tasks.

Deprecated

Use thinking instead. On Opus 4.6, this is treated as on/off (0 = disabled, any other value = adaptive). For explicit control, use thinking: { type: 'adaptive' } or thinking: { type: 'enabled', budgetTokens: N }.

`Optional`maxTurns

maxTurns?: number

Maximum number of conversation turns before the query stops. A turn consists of a user message and assistant response.

`Optional`mcpServers

mcpServers?: Record<string, McpServerConfig>

MCP (Model Context Protocol) server configurations. Keys are server names, values are server configurations.

Example

mcpServers: {
  'my-server': {
    command: 'node',
    args: ['./my-mcp-server.js']
  }
}

`Optional`model

model?: string

Claude model to use. Defaults to the CLI default model. Examples: 'claude-sonnet-4-6', 'claude-opus-4-6'

`Optional`onElicitation

onElicitation?: OnElicitation

Callback for handling MCP elicitation requests. Called when an MCP server requests user input (form fields, URL auth, etc.) and no hook handles the request first.

If not provided, elicitation requests that aren't handled by hooks will be declined automatically.

Example

onElicitation: async (request) => {
  if (request.mode === 'url') {
    // Handle URL-based auth
    return { action: 'accept' }
  }
  // Provide form values
  return { action: 'accept', content: { name: 'Test' } }
}

`Optional`outputFormat

outputFormat?: OutputFormat

Output format configuration for structured responses. When specified, the agent will return structured data matching the schema.

Example

outputFormat: {
  type: 'json_schema',
  schema: { type: 'object', properties: { result: { type: 'string' } } }
}

`Optional`pathToClaudeCodeExecutable

pathToClaudeCodeExecutable?: string

Path to the Claude Code executable. Uses the built-in executable if not specified.

`Optional`permissionMode

permissionMode?: PermissionMode

Permission mode for the session.

'default' - Standard permission behavior, prompts for dangerous operations
'acceptEdits' - Auto-accept file edit operations
'bypassPermissions' - Bypass all permission checks (requires allowDangerouslySkipPermissions)
'plan' - Planning mode, no execution of tools
'dontAsk' - Don't prompt for permissions, deny if not pre-approved

`Optional`permissionPromptToolName

permissionPromptToolName?: string

MCP tool name to use for permission prompts. When set, permission requests will be routed through this MCP tool instead of the default handler.

`Optional`persistSession

persistSession?: boolean

When false, disables session persistence to disk. Sessions will not be saved to ~/.claude/projects/ and cannot be resumed later. Useful for ephemeral or automated workflows where session history is not needed.

Default

true

`Optional`plugins

plugins?: SdkPluginConfig[]

Load plugins for this session. Plugins provide custom commands, agents, skills, and hooks that extend Claude Code's capabilities.

Currently only local plugins are supported via the 'local' type.

Example

plugins: [
  { type: 'local', path: './my-plugin' },
  { type: 'local', path: '/absolute/path/to/plugin' }
]

`Optional`promptSuggestions

promptSuggestions?: boolean

Enable prompt suggestions. When true, the agent emits a prompt_suggestion message after each turn with a predicted next user prompt.

Delivery semantics:

At most one prompt_suggestion per turn; arrives after the result message.
Consumers must keep iterating the stream after result to receive it.
Suppressed on the first turn, after API errors, in plan mode, and by the CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false env var.
Suggestions piggyback on the parent's prompt cache, making them nearly free.

`Optional`resume

resume?: string

Session ID to resume. Loads the conversation history from the specified session.

`Optional`resumeSessionAt

resumeSessionAt?: string

When resuming, only resume messages up to and including the message with this UUID. Use with resume. This allows you to resume from a specific point in the conversation. The message ID should be from SDKAssistantMessage.uuid.

`Optional`sandbox

sandbox?: SandboxSettings

Sandbox settings for command execution isolation.

When enabled, commands are executed in a sandboxed environment that restricts filesystem and network access. This provides an additional security layer.

Important: Filesystem and network restrictions are configured via permission rules, not via these sandbox settings:

Filesystem access: Use Read and Edit permission rules
Network access: Use WebFetch permission rules

These sandbox settings control sandbox behavior (enabled, auto-allow, etc.), while the actual access restrictions come from your permission configuration.

Dependency check: When enabled: true is passed via this option, failIfUnavailable defaults to true — if sandbox dependencies are missing (e.g. bubblewrap on Linux) or the platform is unsupported, query() will emit an error result and exit rather than silently running commands unsandboxed. Set failIfUnavailable: false to allow graceful degradation.

Example: Enable sandboxing with auto-allow

sandbox: {
  enabled: true,
  autoAllowBashIfSandboxed: true
}

Example: Configure network options (not restrictions)

sandbox: {
  enabled: true,
  network: {
    allowLocalBinding: true,
    allowUnixSockets: ['/var/run/docker.sock']
  }
}

See

https://docs.anthropic.com/en/docs/claude-code/settings#sandbox-settings

`Optional`sessionId

sessionId?: string

Use a specific session ID for the conversation instead of an auto-generated one. Must be a valid UUID. Cannot be used with continue or resume unless forkSession is also set (to specify a custom ID for the forked session).

`Optional`settings

settings?: string | Settings

Additional settings to apply. Accepts either a path to a settings JSON file or a settings object. These are loaded into the "flag settings" layer, which has the highest priority among user-controlled settings.

Equivalent to the --settings CLI flag.

Example: Inline settings object

settings: { model: 'claude-sonnet-4-6', permissions: { allow: ['Bash(*)'] } }

Example: Path to settings file

settings: '/path/to/settings.json'

`Optional`settingSources

settingSources?: SettingSource[]

Control which filesystem settings to load.

'user' - Global user settings (~/.claude/settings.json)
'project' - Project settings (.claude/settings.json)
'local' - Local settings (.claude/settings.local.json)

When omitted or empty, no filesystem settings are loaded (SDK isolation mode). Must include 'project' to load CLAUDE.md files.

`Optional`spawnClaudeCodeProcess

spawnClaudeCodeProcess?: (options: SpawnOptions) => SpawnedProcess

Custom function to spawn the Claude Code process. Use this to run Claude Code in VMs, containers, or remote environments.

When provided, this function is called instead of the default local spawn. The default behavior checks if the executable exists before spawning.

Example

spawnClaudeCodeProcess: (options) => {
  // Custom spawn logic for VM execution
  // options contains: command, args, cwd, env, signal
  return myVMProcess; // Must satisfy SpawnedProcess interface
}

`Optional`stderr

stderr?: (data: string) => void

Callback for stderr output from the Claude Code process. Useful for debugging and logging.

`Optional`strictMcpConfig

strictMcpConfig?: boolean

Enforce strict validation of MCP server configurations. When true, invalid configurations will cause errors instead of warnings.

`Optional`systemPrompt

systemPrompt?:
| string
| { append?: string; preset: "claude_code"; type: "preset" }

System prompt configuration.

string - Use a custom system prompt
{ type: 'preset', preset: 'claude_code' } - Use Claude Code's default system prompt
{ type: 'preset', preset: 'claude_code', append: '...' } - Use default prompt with appended instructions

Example: Custom prompt

systemPrompt: 'You are a helpful coding assistant.'

Example: Default with additions

systemPrompt: {
  type: 'preset',
  preset: 'claude_code',
  append: 'Always explain your reasoning.'
}

`Optional` `Alpha`taskBudget

taskBudget?: { total: number }

API-side task budget in tokens. When set, the model is made aware of its remaining token budget so it can pace tool use and wrap up before the limit. Sent as output_config.task_budget with the task-budgets-2026-03-13 beta header.

`Optional`thinking

thinking?: ThinkingConfig

Controls Claude's thinking/reasoning behavior.

{ type: 'adaptive' } — Claude decides when and how much to think (Opus 4.6+). This is the default for models that support it.
{ type: 'enabled', budgetTokens: number } — Fixed thinking token budget (older models)
{ type: 'disabled' } — No extended thinking

When set, takes precedence over the deprecated maxThinkingTokens.

See

https://docs.anthropic.com/en/docs/build-with-claude/adaptive-thinking

`Optional`toolConfig

toolConfig?: ToolConfig

Per-tool configuration for built-in tools.

Example

toolConfig: {
  askUserQuestion: { previewFormat: 'html' }
}

`Optional`tools

tools?: string[] | { preset: "claude_code"; type: "preset" }

Specify the base set of available built-in tools.

string[] - Array of specific tool names (e.g., ['Bash', 'Read', 'Edit'])
[] (empty array) - Disable all built-in tools
{ type: 'preset'; preset: 'claude_code' } - Use all default Claude Code tools

Type Alias Options

Index

Claude SDK

Claude SDK

OptionalabortController

OptionaladditionalDirectories

Optionalagent

Example

OptionalagentProgressSummaries

Optionalagents

Example

OptionalallowDangerouslySkipPermissions

OptionalallowedTools

Optionalbetas

See

OptionalcanUseTool

Optionalcontinue

Optionalcwd

Optionaldebug

OptionaldebugFile

OptionaldisallowedTools

Optionaleffort

See

OptionalenableFileCheckpointing

Optionalenv

Example

Optionalexecutable

OptionalexecutableArgs

OptionalextraArgs

OptionalfallbackModel

OptionalforkSession

Optionalhooks

Example

OptionalincludeHookEvents

Default

OptionalincludePartialMessages

OptionalmaxBudgetUsd

OptionalmaxThinkingTokens

Deprecated

OptionalmaxTurns

OptionalmcpServers

Example

Optionalmodel

OptionalonElicitation

Example

OptionaloutputFormat

Example

OptionalpathToClaudeCodeExecutable

OptionalpermissionMode

OptionalpermissionPromptToolName

OptionalpersistSession

Default

Optionalplugins

Example

OptionalpromptSuggestions

Optionalresume

OptionalresumeSessionAt

Optionalsandbox

Example: Enable sandboxing with auto-allow

Example: Configure network options (not restrictions)

See

OptionalsessionId

Optionalsettings

Example: Inline settings object

Example: Path to settings file

OptionalsettingSources

OptionalspawnClaudeCodeProcess

Example

Optionalstderr

OptionalstrictMcpConfig

OptionalsystemPrompt

Example: Custom prompt

Example: Default with additions

Optional AlphataskBudget

Optionalthinking

See

OptionaltoolConfig

Example

Optionaltools

Settings

`Optional`abortController

`Optional`additionalDirectories

`Optional`agent

`Optional`agentProgressSummaries

`Optional`agents

`Optional`allowDangerouslySkipPermissions

`Optional`allowedTools

`Optional`betas

`Optional`canUseTool

`Optional`continue

`Optional`cwd

`Optional`debug

`Optional`debugFile

`Optional`disallowedTools

`Optional`effort

`Optional`enableFileCheckpointing

`Optional`env

`Optional`executable

`Optional`executableArgs

`Optional`extraArgs

`Optional`fallbackModel

`Optional`forkSession

`Optional`hooks

`Optional`includeHookEvents

`Optional`includePartialMessages

`Optional`maxBudgetUsd

`Optional`maxThinkingTokens

`Optional`maxTurns

`Optional`mcpServers

`Optional`model

`Optional`onElicitation

`Optional`outputFormat

`Optional`pathToClaudeCodeExecutable

`Optional`permissionMode

`Optional`permissionPromptToolName

`Optional`persistSession

`Optional`plugins

`Optional`promptSuggestions

`Optional`resume

`Optional`resumeSessionAt

`Optional`sandbox

`Optional`sessionId

`Optional`settings

`Optional`settingSources

`Optional`spawnClaudeCodeProcess

`Optional`stderr

`Optional`strictMcpConfig

`Optional`systemPrompt

`Optional` `Alpha`taskBudget

`Optional`thinking

`Optional`toolConfig

`Optional`tools