Example

The example below resolves settings for a project directory and prints the source that controls the cleanup period. On a machine where no settings file sets cleanupPeriodDays, both printed lines show undefined for the value, which is the expected output rather than an error.

import { resolveSettings } from "@anthropic-ai/claude-agent-sdk";

const { effective, provenance } = await resolveSettings({
  cwd: "/path/to/project",
  settingSources: ["user", "project", "local"],
});

console.log(`Cleanup period: ${effective.cleanupPeriodDays} days`);
console.log(`Set by: ${provenance.cleanupPeriodDays?.source}`);

Types

Options

Configuration object for the query() function.

Property	Type	Default	Description
abortController	AbortController	new AbortController()	Controller for cancelling operations
additionalDirectories	string[]	[]	Additional directories Claude can access. The SDK passes each entry to Claude Code as --add-dir, so with the project setting source Claude Code also loads the directory's skills, commands, and subagents
agent	string	undefined	Agent name for the main thread. The agent must be defined in the agents option or in settings
agents	Record<string, [AgentDefinition](#agentdefinition)>	undefined	Programmatically define subagents
agentProgressSummaries	boolean	false	When true, generate one-line progress summaries for subagents and forward them on task_progress events via the summary field. Applies to foreground and background subagents
allowDangerouslySkipPermissions	boolean	false	Enable bypassing permissions. Required when using permissionMode: 'bypassPermissions'
allowedTools	string[]	[]	Tools to auto-approve without prompting. This does not restrict Claude to only these tools. If you name one of the task-tracking tools here, Claude Code also opts the session in. Other unlisted tools fall through to permissionMode and canUseTool. Use disallowedTools to block tools. See Permissions
betas	SdkBeta[]	[]	Enable beta features
canUseTool	CanUseTool	undefined	Custom permission function, invoked only when the permission flow falls through to a prompt. Not invoked for calls auto-approved by allowedTools, allow rules, or permissionMode. An allow rule doesn't pre-approve the actions no mode auto-approves. See CanUseTool for details
continue	boolean	false	Continue the most recent conversation
cwd	string	process.cwd()	Current working directory
debug	boolean	false	Enable debug mode for the Claude Code process
debugFile	string	undefined	Write debug logs to a specific file path. Implicitly enables debug mode
disallowedTools	string[]	[]	Tools to deny. A bare name such as "Bash" removes the tool from Claude's context. A scoped rule such as "Bash(rm *)" leaves the tool available and denies matching calls in every permission mode, including bypassPermissions, for the command as written. See Permissions
effort	'low' | 'medium' | 'high' | 'xhigh' | 'max'	Model default	Controls how much effort Claude puts into its response. Works with adaptive thinking to guide thinking depth. See adjust the effort level
enableFileCheckpointing	boolean	false	Enable file change tracking for rewinding. See File checkpointing
env	Record<string, string | undefined>	process.env	Environment variables. When set, this replaces the subprocess environment instead of merging with process.env, so pass \{ ...process.env, YOUR_VAR: 'value' \} to keep inherited variables like PATH. See Handle slow or stalled API responses for an example of this pattern, and Environment variables for variables the underlying CLI reads. Set CLAUDE_AGENT_SDK_CLIENT_APP to identify your app in the User-Agent header
executable	'bun' | 'deno' | 'node'	Auto-detected	JavaScript runtime to use
executableArgs	string[]	[]	Arguments to pass to the executable
extraArgs	Record<string, string | null>	\{\}	Additional arguments
fallbackModel	string	undefined	Model to use if primary fails
forkSession	boolean	false	When resuming with resume, fork to a new session ID instead of continuing the original session
forwardSubagentText	boolean	false	Forward subagent text and thinking blocks as assistant and user messages with parent_tool_use_id set, so consumers can render a nested transcript. Without this option, Claude Code emits subagent tool_use and tool_result blocks but not text or thinking. Messages from subagents at every nesting depth are forwarded on Claude Code v2.1.219 and later; before v2.1.219, only messages from depth-1 subagents appeared
hooks	Partial<Record<HookEvent, HookCallbackMatcher[]>>	\{\}	Hook callbacks for events
includeHookEvents	boolean	false	Include hook lifecycle events in the message stream as SDKHookStartedMessage, SDKHookProgressMessage, and SDKHookResponseMessage. Lifecycle events for SessionStart and Setup hooks are always included and don't need this option. Some hook events, such as Notification, SessionEnd, PreCompact, and PostCompact, never produce an SDKHookStartedMessage, even with this option. For those events, Claude Code still emits an SDKHookProgressMessage while a command hook that runs for more than a second produces output, and emits an SDKHookResponseMessage only when a hook that runs in the background finishes
includePartialMessages	boolean	false	Include partial message events
loadTimeoutMs	number	60000	Alpha. Timeout in milliseconds for each sessionStore.load() and sessionStore.listSubkeys() call during resume materialization. If the adapter doesn't settle within this window, the query fails instead of hanging. Ignored when sessionStore is not set
managedSettings	Settings	undefined	Policy-tier settings your host process supplies to the spawned session. On machines with admin-deployed managed settings, Claude Code ignores these unless the admin's highest-priority managed source sets parentSettingsBehavior: 'merge', and never merges them while a policyHelper supplies managed settings. Merged values pass through a restrictive-only filter; Restrict parent settings covers what the filter admits and the allowManaged*Only locks. A host that sets CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST has three keys read straight from this payload instead: its model configuration on Claude Code v2.1.222 or later, modelPricing when no managed source sets it on v2.1.246 or later, and its ENABLE_TOOL_SEARCH env entry on v2.1.247 or later
maxBudgetUsd	number	undefined	Stop the query when the client-side cost estimate reaches this USD value. Compared against the same estimate as total_cost_usd; see Track cost and usage for accuracy caveats
maxThinkingTokens	number	undefined	Deprecated: Use thinking instead. Maximum tokens for thinking process
maxTurns	number	undefined	Maximum agentic turns (tool-use round trips)
mcpServers	Record<string, [McpServerConfig](#mcpserverconfig)>	\{\}	MCP server configurations
model	string	Default from CLI	Claude model alias or full model name. See accepted values and provider-specific IDs
onElicitation	(request: ElicitationRequest, options: \{ signal: AbortSignal \}) => Promise<ElicitationResult>	undefined	Callback for handling MCP elicitation requests. Called when an MCP server requests user input and no hook handles it first. When not provided, unhandled elicitation requests are declined automatically
outputFormat	\{ type: 'json_schema', schema: JSONSchema \}	undefined	Define output format for agent results. See Structured outputs for details
outputStyle	string	undefined	Not an Options field. Set outputStyle in the inline settings object or a settings file instead. See Activate an output style
pathToClaudeCodeExecutable	string	Auto-resolved from bundled native binary	Path to Claude Code executable. Only needed if optional dependencies were skipped during install or your platform isn't in the supported set
permissionMode	PermissionMode	'default'	Permission mode for the session
permissionPromptToolName	string	undefined	MCP tool name for permission prompts
permissionPrompts	'host' | 'none'	'host'	Who answers permission prompts: 'host' routes them to your canUseTool callback or the permissionPromptToolName tool, and 'none' denies the calls that would have prompted. Requires Claude Code v2.1.259 or later
persistSession	boolean	true	When false, disables session persistence to disk. Sessions cannot be resumed later
planModeInstructions	string	undefined	Custom workflow instructions for plan mode. When permissionMode is 'plan', this string replaces the default plan-mode workflow body. The CLI still wraps it with the read-only enforcement preamble and the ExitPlanMode protocol footer
plugins	SdkPluginConfig[]	[]	Load custom plugins from local paths. See Plugins for details
promptSuggestions	boolean	false	Enable prompt suggestions. After a turn, Claude Code emits a prompt_suggestion message carrying a predicted next user prompt. Claude Code generates no suggestion for some turns, such as while your account is close to or at its usage limit. See When Claude Code skips suggestions
resume	string	undefined	Session ID to resume
resumeDropsTurn	string	undefined	With resumeSessionAt: the prompt UUID of the turn the truncating resume intends to discard. Claude Code refuses the resume when the discarded range contains anything not attributable to that turn, such as absorbed queued messages or task notifications, and names the --resume-drops-turn flag in the rejection message. Only the Agent SDK and print-mode resumes read the pair. Requires Claude Code v2.1.223 or later
resumeSessionAt	string	undefined	Resume session at a specific message UUID
sandbox	SandboxSettings	undefined	Configure sandbox behavior programmatically. See Sandbox settings for details
sessionId	string	Auto-generated	Use a specific UUID for the session instead of auto-generating one
sessionStore	SessionStore	undefined	Mirror session transcripts to an external backend so another host can resume them. See Persist sessions to external storage
sessionStoreFlush	'batched' | 'eager'	'batched'	Alpha. Flush mode for sessionStore. Ignored when sessionStore is not set
settings	string | Settings	undefined	Inline settings object or path to a settings file. Populates the flag-settings layer in the precedence order. Change at runtime with applyFlagSettings()
settingSources	SettingSource[]	CLI defaults (all sources)	Control which filesystem settings to load. Pass [] to disable user, project, and local settings. Endpoint-managed policy loads regardless; server-managed settings are fetched when the session authenticates with an organization credential on an eligible configuration. See Use Claude Code features
skills	string[] | 'all'	undefined	Skills available to the session. Pass 'all' to enable every discovered skill, or a list of skill names. Pass exact names only. On Agent SDK v0.3.221 or later, the SDK rejects malformed and wildcard-form names with an error before starting the Claude Code process. When set, the SDK adds the Skill tool to allowedTools automatically. If you also pass tools, include 'Skill' in that list. See Skills
spawnClaudeCodeProcess	(options: SpawnOptions) => SpawnedProcess	undefined	Custom function to spawn the Claude Code process. Use to run Claude Code in VMs, containers, or remote environments
stderr	(data: string) => void	undefined	Callback for stderr output
strictMcpConfig	boolean	false	Use only the servers passed in mcpServers and ignore project .mcp.json, user settings, plugin-provided MCP servers, and claude.ai connectors
systemPrompt	string | string[] | \{ type: 'custom'; prompt: string | string[]; snapshot?: boolean \} | \{ type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean \}	undefined (minimal prompt)	System prompt configuration. Pass a string for a custom prompt, or \{ type: 'preset', preset: 'claude_code' \} to use Claude Code's system prompt. Pass an array of strings with the exported SYSTEM_PROMPT_DYNAMIC_BOUNDARY constant between the static and per-request parts to cache the static part of a custom prompt. When using the preset object form, add append to extend it with additional instructions, and set excludeDynamicSections: true to move per-session context into the first user message for better prompt-cache reuse across machines. Set snapshot: false to rebuild the prompt on every request instead of reusing the prompt the session recorded on its first request. To set snapshot on a custom prompt, pass the \{ type: 'custom', prompt \} form. The \{ type: 'custom' \} form and the snapshot field require TypeScript Agent SDK v0.3.257 or later
taskBudget	\{ total: number \}	undefined	Alpha. API-side task budget in tokens. When set, the model is told its remaining token budget so it can pace tool use and wrap up before the limit
thinking	ThinkingConfig	\{ type: 'adaptive' \} for supported models	Controls Claude's thinking/reasoning behavior. See ThinkingConfig for options
title	string	undefined	Display title for the session. When resuming via resume or continue, the resumed session's persisted title takes precedence; use renameSession() to retitle an existing session
toolAliases	Record<string, string>	undefined	Map built-in tool names to MCP tool names so Claude calls your MCP implementation in place of the built-in. For example, \{ Bash: 'mcp__workspace__bash' \}
toolConfig	ToolConfig	undefined	Configuration for built-in tool behavior. See ToolConfig for details
tools	string[] | \{ type: 'preset'; preset: 'claude_code' \}	undefined	Tool configuration. Pass an array of tool names or use the preset to get Claude Code's default tools