Configure your agent changedagent-sdk/configuration
Nearest release: v2.1.280, published 12 hours after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 22 Sep 2026 03:07 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 22 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+38added
Lines−38removed
From line
58
where the diff opens
First seen
15 Sep 2026
this site's first read of the page
Recorded edits5to this page, all time
The whole hunk
from line 58, old and new numbered
/
from line 58
5858
5959Point `cwd` at one of your own projects and run the example. The summary of that project's open TODOs prints when the result message arrives.
6060
61`allowedTools` (TypeScript) or `allowed_tools` (Python) pre-approves the listed tools, so calls to them run without stopping for approval. Tools outside the list stay available. When Claude calls an unlisted tool, the permission mode decides whether the call runs. For more information, see [Allow and deny rules](/docs/en/agent-sdk/permissions#allow-and-deny-rules).
61`allowedTools` (TypeScript) or `allowed_tools` (Python) pre-approves the listed tools, so calls to them run without stopping for approval. Tools outside the list stay available. When Claude calls an unlisted tool, the permission mode decides whether the call runs. For more information, see [Allow and deny rules](/docs/en/agent-sdk/permissions.md#allow-and-deny-rules).
6262
6363## Load settings files
6464
from line 65
6565Settings files supply configuration beyond the options object. Two options control how they load:
6666
6767* **`settingSources` / `setting_sources`**: controls which filesystem sources load: user, project, and local. Settings files and CLAUDE.md files arrive through these sources.
68* **`settings`**: loads a settings file path or an inline JSON string in either language, and TypeScript also accepts a settings object. Whichever form you pass overrides user, project, and local filesystem settings; only managed policy settings rank higher. The references document the full precedence order under [Settings precedence](/docs/en/agent-sdk/typescript#settings-precedence) for TypeScript and [Settings precedence](/docs/en/agent-sdk/python#settings-precedence) for Python.
68* **`settings`**: loads a settings file path or an inline JSON string in either language, and TypeScript also accepts a settings object. Whichever form you pass overrides user, project, and local filesystem settings; only managed policy settings rank higher. The references document the full precedence order under [Settings precedence](/docs/en/agent-sdk/typescript.md#settings-precedence) for TypeScript and [Settings precedence](/docs/en/agent-sdk/python.md#settings-precedence) for Python.
6969
70Pass `[]` to disable user, project, and local settings. For more information, see [Use Claude Code features in the SDK](/docs/en/agent-sdk/claude-code-features).
70Pass `[]` to disable user, project, and local settings. For more information, see [Use Claude Code features in the SDK](/docs/en/agent-sdk/claude-code-features.md).
7171
7272## Choose a model
7373
74Unless the `model` option, your settings, or your environment selects a model, a new session starts on [Claude Code's default model](/docs/en/model-config#default-model-setting). For the order of those sources, see [Setting your model](/docs/en/model-config#setting-your-model). Set `model` to pin a specific model, or to pick a smaller one for faster, cheaper agents. The value takes a model alias or a full model name; aliases and the versions they resolve to are listed under [Model aliases](/docs/en/model-config#model-aliases).
74Unless the `model` option, your settings, or your environment selects a model, a new session starts on [Claude Code's default model](/docs/en/model-config.md#default-model-setting). For the order of those sources, see [Setting your model](/docs/en/model-config.md#setting-your-model). Set `model` to pin a specific model, or to pick a smaller one for faster, cheaper agents. The value takes a model alias or a full model name; aliases and the versions they resolve to are listed under [Model aliases](/docs/en/model-config.md#model-aliases).
7575
7676Set `fallbackModel` (TypeScript) or `fallback_model` (Python) to name a backup model. When the primary is overloaded or unavailable, the session switches to the backup. The primary is retried at the start of each user turn, so the session returns to it once the outage passes.
7777
78In either language, the option accepts a single model or a comma-separated list of backups. For the order and the chain cap, see [Fallback model chains](/docs/en/model-config#fallback-model-chains). In TypeScript, a fallback equal to `model` throws an error at startup.
78In either language, the option accepts a single model or a comma-separated list of backups. For the order and the chain cap, see [Fallback model chains](/docs/en/model-config.md#fallback-model-chains). In TypeScript, a fallback equal to `model` throws an error at startup.
7979
8080The examples below show a fallback list in TypeScript and a single fallback in Python:
8181
from line 95
9595
9696> [!NOTE]
9797>
98> The [Messages API](https://platform.claude.com/docs/en/api/messages) request parameters `temperature`, `top_p`, and `max_tokens` have no fields on the options object in either language. Set the [effort level](/docs/en/agent-sdk/agent-loop#effort-level) or a [spend cap](#limit-turns-and-spend) instead, or call the Messages API when you need those parameters directly.
98> The [Messages API](https://platform.claude.com/docs/en/api/messages) request parameters `temperature`, `top_p`, and `max_tokens` have no fields on the options object in either language. Set the [effort level](/docs/en/agent-sdk/agent-loop.md#effort-level) or a [spend cap](#limit-turns-and-spend) instead, or call the Messages API when you need those parameters directly.
9999
100100## Set environment variables
101101
from line 120
120120)
121121```
122122
123The variables you pass can also configure Claude Code itself. For the variables the Claude Code process reads, see [Environment variables](/docs/en/env-vars). To tune API timeouts and stall detection this way, follow the Handle slow or stalled API responses section in the [TypeScript reference](/docs/en/agent-sdk/typescript#handle-slow-or-stalled-api-responses) or the [Python reference](/docs/en/agent-sdk/python#handle-slow-or-stalled-api-responses).
123The variables you pass can also configure Claude Code itself. For the variables the Claude Code process reads, see [Environment variables](/docs/en/env-vars.md). To tune API timeouts and stall detection this way, follow the Handle slow or stalled API responses section in the [TypeScript reference](/docs/en/agent-sdk/typescript.md#handle-slow-or-stalled-api-responses) or the [Python reference](/docs/en/agent-sdk/python.md#handle-slow-or-stalled-api-responses).
124124
125125## Set the working directory
126126
from line 128
128128
129129Claude Code reads the working directory to determine:
130130
131* **Project settings and hooks**: which project's [settings and hooks load](/docs/en/agent-sdk/claude-code-features)
132* **Skills**: where [session skills are discovered](/docs/en/agent-sdk/skills)
133* **Session storage**: which project a [stored session belongs to](/docs/en/agent-sdk/session-storage)
131* **Project settings and hooks**: which project's [settings and hooks load](/docs/en/agent-sdk/claude-code-features.md)
132* **Skills**: where [session skills are discovered](/docs/en/agent-sdk/skills.md)
133* **Session storage**: which project a [stored session belongs to](/docs/en/agent-sdk/session-storage.md)
134134
135To let tools reach files outside the working directory, add paths with `additionalDirectories` (TypeScript) or `add_dirs` (Python). For the scope of that grant, see [Additional directories grant file access, not configuration](/docs/en/permissions#additional-directories-grant-file-access-not-configuration).
135To let tools reach files outside the working directory, add paths with `additionalDirectories` (TypeScript) or `add_dirs` (Python). For the scope of that grant, see [Additional directories grant file access, not configuration](/docs/en/permissions.md#additional-directories-grant-file-access-not-configuration).
136136
137137## Limit turns and spend
138138
from line 146
146146* **`maxTurns` / `max_turns`**: `0` runs the session without a turn limit, the same as leaving the option unset
147147* **`maxBudgetUsd` / `max_budget_usd`**: the CLI rejects `0` as an invalid amount at startup, and the session never runs
148148
149For more information about both caps, including subagent spend, see [Turns and budget](/docs/en/agent-sdk/agent-loop#turns-and-budget).
149For more information about both caps, including subagent spend, see [Turns and budget](/docs/en/agent-sdk/agent-loop.md#turns-and-budget).
150150
151151## Change configuration mid-session
152152
153When you start a session with [streaming input](/docs/en/agent-sdk/streaming-vs-single-mode), you can switch its model and permission mode while it runs. Where you call the setters differs by language:
153When you start a session with [streaming input](/docs/en/agent-sdk/streaming-vs-single-mode.md), you can switch its model and permission mode while it runs. Where you call the setters differs by language:
154154
155155* **TypeScript**: methods on the object `query()` returns
156156* **Python**: methods on [`ClaudeSDKClient`](/docs/en/agent-sdk/python#claudesdkclient), since `query()` returns a plain iterator without control methods
from line 157
157157
158158Both languages have the same setters:
159159
160* **`setModel()` / `set_model()`**: switches the model. Call it with no model to switch to [Claude Code's default model](/docs/en/model-config#default-model-setting) rather than the `model` you passed in options.
160* **`setModel()` / `set_model()`**: switches the model. Call it with no model to switch to [Claude Code's default model](/docs/en/model-config.md#default-model-setting) rather than the `model` you passed in options.
161161* **`setPermissionMode()` / `set_permission_mode()`**: switches the permission mode
162162
163163TypeScript also has `applyFlagSettings()` and `updateSettings()`:
from line 250
250250
251251> [!NOTE]
252252>
253> Each model has its own prompt cache, so after a mid-session switch the next request recomputes the full conversation uncached at the new model's rates. For more information, see [Switching models](/docs/en/prompt-caching#switching-models).
253> Each model has its own prompt cache, so after a mid-session switch the next request recomputes the full conversation uncached at the new model's rates. For more information, see [Switching models](/docs/en/prompt-caching.md#switching-models).
254254
255255## Configure specific features
256256
257The table below maps each option to the feature it configures. For options this page doesn't cover, see the [TypeScript](/docs/en/agent-sdk/typescript#options) and [Python](/docs/en/agent-sdk/python#claudeagentoptions) references. If you know your goal but not which option serves it, start from [Choose the right feature](/docs/en/agent-sdk/claude-code-features#choose-the-right-feature).
257The table below maps each option to the feature it configures. For options this page doesn't cover, see the [TypeScript](/docs/en/agent-sdk/typescript.md#options) and [Python](/docs/en/agent-sdk/python.md#claudeagentoptions) references. If you know your goal but not which option serves it, start from [Choose the right feature](/docs/en/agent-sdk/claude-code-features.md#choose-the-right-feature).
258258
259259| TypeScript | Python | Controls | Covered in |
260260| - | - | - | - |
261| `permissionMode` | `permission_mode` | What the agent can do without approval | [Configure permissions](/docs/en/agent-sdk/permissions) |
262| `allowedTools` | `allowed_tools` | Which tool calls are pre-approved | [Configure permissions](/docs/en/agent-sdk/permissions) |
263| `canUseTool` | `can_use_tool` | Your approval callback for tool calls | [Handle tool approval requests](/docs/en/agent-sdk/user-input#handle-tool-approval-requests) |
264| `systemPrompt` | `system_prompt` | The agent's instructions | [Modifying system prompts](/docs/en/agent-sdk/modifying-system-prompts) |
265| `settingSources` | `setting_sources` | Which filesystem settings load | [Use Claude Code features in the SDK](/docs/en/agent-sdk/claude-code-features) |
266| `mcpServers` | `mcp_servers` | External tool servers | [Connect to external tools with MCP](/docs/en/agent-sdk/mcp) |
267| `agents` | `agents` | Subagent definitions | [Subagents](/docs/en/agent-sdk/subagents) |
268| `hooks` | `hooks` | Callbacks at lifecycle points | [Hooks](/docs/en/agent-sdk/hooks) |
269| `skills` | `skills` | Which skills load | [Extend agents with skills](/docs/en/agent-sdk/skills) |
270| `plugins` | `plugins` | Which plugins load | [Plugins](/docs/en/agent-sdk/plugins) |
271| `outputFormat` | `output_format` | Structured output schemas | [Structured outputs](/docs/en/agent-sdk/structured-outputs) |
272| `resume` | `resume` | Continuing a stored session | [Sessions](/docs/en/agent-sdk/sessions) |
273| `forkSession` | `fork_session` | Branching a session | [Sessions](/docs/en/agent-sdk/sessions) |
274| `sessionStore` | `session_store` | External session persistence | [Session storage](/docs/en/agent-sdk/session-storage) |
275| `enableFileCheckpointing` | `enable_file_checkpointing` | Rewindable file edits | [File checkpointing](/docs/en/agent-sdk/file-checkpointing) |
276| `effort` | `effort` | How much work Claude puts into responses | [Effort level](/docs/en/agent-sdk/agent-loop#effort-level) |
277| `sandbox` | `sandbox` | Sandbox behavior for tool execution | [TypeScript](/docs/en/agent-sdk/typescript#sandbox-configuration) and [Python](/docs/en/agent-sdk/python#sandbox-configuration) references, with deployment context in [Secure deployment](/docs/en/agent-sdk/secure-deployment) |
261| `permissionMode` | `permission_mode` | What the agent can do without approval | [Configure permissions](/docs/en/agent-sdk/permissions.md) |
262| `allowedTools` | `allowed_tools` | Which tool calls are pre-approved | [Configure permissions](/docs/en/agent-sdk/permissions.md) |
263| `canUseTool` | `can_use_tool` | Your approval callback for tool calls | [Handle tool approval requests](/docs/en/agent-sdk/user-input.md#handle-tool-approval-requests) |
264| `systemPrompt` | `system_prompt` | The agent's instructions | [Modifying system prompts](/docs/en/agent-sdk/modifying-system-prompts.md) |
265| `settingSources` | `setting_sources` | Which filesystem settings load | [Use Claude Code features in the SDK](/docs/en/agent-sdk/claude-code-features.md) |
266| `mcpServers` | `mcp_servers` | External tool servers | [Connect to external tools with MCP](/docs/en/agent-sdk/mcp.md) |
267| `agents` | `agents` | Subagent definitions | [Subagents](/docs/en/agent-sdk/subagents.md) |
268| `hooks` | `hooks` | Callbacks at lifecycle points | [Hooks](/docs/en/agent-sdk/hooks.md) |
269| `skills` | `skills` | Which skills load | [Extend agents with skills](/docs/en/agent-sdk/skills.md) |
270| `plugins` | `plugins` | Which plugins load | [Plugins](/docs/en/agent-sdk/plugins.md) |
271| `outputFormat` | `output_format` | Structured output schemas | [Structured outputs](/docs/en/agent-sdk/structured-outputs.md) |
272| `resume` | `resume` | Continuing a stored session | [Sessions](/docs/en/agent-sdk/sessions.md) |
273| `forkSession` | `fork_session` | Branching a session | [Sessions](/docs/en/agent-sdk/sessions.md) |
274| `sessionStore` | `session_store` | External session persistence | [Session storage](/docs/en/agent-sdk/session-storage.md) |
275| `enableFileCheckpointing` | `enable_file_checkpointing` | Rewindable file edits | [File checkpointing](/docs/en/agent-sdk/file-checkpointing.md) |
276| `effort` | `effort` | How much work Claude puts into responses | [Effort level](/docs/en/agent-sdk/agent-loop.md#effort-level) |
277| `sandbox` | `sandbox` | Sandbox behavior for tool execution | [TypeScript](/docs/en/agent-sdk/typescript.md#sandbox-configuration) and [Python](/docs/en/agent-sdk/python.md#sandbox-configuration) references, with deployment context in [Secure deployment](/docs/en/agent-sdk/secure-deployment.md) |
278278
279279## Next steps
280280
281281To see configuration composed into working agents:
282282
283* **[Quickstart](/docs/en/agent-sdk/quickstart)**: build and run a first agent end to end
284* **[Examples](/docs/en/agent-sdk/examples)**: find a complete, runnable project or a guided Claude Cookbook recipe that matches what you want to build
285* **[Multi-tenant isolation](/docs/en/agent-sdk/hosting#multi-tenant-isolation)**: isolate each tenant's settings and memory with `settingSources` / `setting_sources`, `env`, and `cwd`
283* **[Quickstart](/docs/en/agent-sdk/quickstart.md)**: build and run a first agent end to end
284* **[Examples](/docs/en/agent-sdk/examples.md)**: find a complete, runnable project or a guided Claude Cookbook recipe that matches what you want to build
285* **[Multi-tenant isolation](/docs/en/agent-sdk/hosting.md#multi-tenant-isolation)**: isolate each tenant's settings and memory with `settingSources` / `setting_sources`, `env`, and `cwd`
286286
No line in this hunk matches that.