After migrating from claude-code-sdk to the Claude Agent SDK, which defaults changed, and how do you restore Claude Code's behaviour?
answer
- more than an import rename
- Python options class renamed
- system prompt no longer the default
- preset named claude_code
- settings default changed, then reverted
basics
~20 sSince Agent SDK v0.1.0 the packages and Python's ClaudeCodeOptions are renamed, and query() uses a minimal system prompt instead of Claude Code's; request the claude_code preset to restore it. Filesystem settings still load by default.
solid answer
~40 sThe rename to the Claude Agent SDK shipped breaking changes in v0.1.0. The packages moved (`@anthropic-ai/claude-code` to `@anthropic-ai/claude-agent-sdk`, `claude-code-sdk` to `claude-agent-sdk`, imports `claude_code_sdk` to `claude_agent_sdk`) and Python's `ClaudeCodeOptions` became `ClaudeAgentOptions`. The behavioural change is the **system prompt**: with no `systemPrompt` / `system_prompt`, the SDK now sends a minimal prompt that covers tool calling but leaves out the rest of Claude Code's prompt, including its security and safety instructions, whereas `claude -p` still uses the full one. To get the old behaviour, pass `{ type: "preset", preset: "claude_code" }`, optionally with `append`. The settings-sources default was briefly changed in v0.1.0 to load nothing and then reverted, so omitting `settingSources` still loads user, project and local settings and no action is needed.
code
python · 20 linesimport asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(
system_prompt={
"type": "preset",
"preset": "claude_code",
"append": "Summarise pull requests as release-note bullets.",
},
allowed_tools=["Read", "Grep", "Glob"],
)
async def main():
async for message in query(prompt="Summarise the changes on this branch", options=options):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())go deeper
Recall the new package names, the Python rename from ClaudeCodeOptions to ClaudeAgentOptions, and that the claude_code preset brings back Claude Code's system prompt.
Explain why an unset system prompt now yields a minimal prompt, how append extends the preset, and why CLAUDE.md loading depends on setting sources rather than the prompt.
Diagnose a migrated agent that answers generically or less carefully, and audit whether it is inheriting developer settings that the short-lived v0.1.0 change made people assume were gone.
Decide per agent whether Claude Code's prompt, a custom prompt or the minimal default is the right baseline, and who owns the safety guidance the minimal default no longer carries.
## Why the migration is more than a rename The **Claude Code SDK** became the **Claude Agent SDK**, and the docs moved into their own Agent SDK section. The guide flags **v0.1.0** of the new SDK as the release that introduced breaking changes "to improve isolation and explicit configuration". A team that only swaps the import can end up with an agent that runs but behaves differently, because one default changed underneath it. ## What changed | Aspect | Before (Claude Code SDK) | After (Claude Agent SDK) | |---|---|---| | TypeScript package | `@anthropic-ai/claude-code` | `@anthropic-ai/claude-agent-sdk` | | Python package and import | `claude-code-sdk`, `claude_code_sdk` | `claude-agent-sdk`, `claude_agent_sdk` | | Python options type | `ClaudeCodeOptions` | `ClaudeAgentOptions` | | System prompt when unset | Claude Code's system prompt | A **minimal** prompt | | Filesystem settings when `settingSources` is unset | All sources | All sources (briefly none in v0.1.0, then reverted) | The mechanical steps are the ones you expect: 1. Uninstall the old package and install the new one (`npm install @anthropic-ai/claude-agent-sdk`, `pip install claude-agent-sdk`). 2. Rewrite imports; in TypeScript `query`, `tool` and `createSdkMcpServer` keep their names. 3. In Python, rename `ClaudeCodeOptions` to `ClaudeAgentOptions`; the fields such as `model` and `permission_mode` carry over. 4. Update the version range in `package.json` or `requirements.txt` / `pyproject.toml`. 5. Review the breaking changes below before shipping. ## The system prompt is no longer Claude Code's This is the change that silently alters behaviour. With no system prompt option, the SDK uses a **minimal default** that supports tool calling and omits the rest of the `claude_code` preset, **including its security and safety instructions**. That differs from `claude -p`, which uses Claude Code's prompt by default, so an agent ported from a CLI script loses its coding-agent guidance without any error. You have three choices: - **The preset:** `systemPrompt: { type: "preset", preset: "claude_code" }` (Python: `system_prompt={"type": "preset", "preset": "claude_code"}`) restores Claude Code's prompt. Add `append` to extend it with your own instructions without discarding it. - **A custom string:** replaces the prompt entirely. Write your own safety guidance, and say what system reminders are, because the preset's explanation of them goes away with it. - **Nothing:** a thin tool-calling loop where the user prompt carries all behaviour. `CLAUDE.md` is a separate path. The SDK reads it according to the setting sources and injects it into the conversation as project context, not into the system prompt, so it applies with any of the three choices. Choosing the preset does **not** make `CLAUDE.md` load, and dropping the preset does not stop it. ## The settings-sources default that did not change The v0.1.0 release briefly changed the default to load **no** filesystem settings, then reverted it. Today, omitting `settingSources` loads user, project and local settings, matching the CLI: `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md` files and custom commands. The migration guide says no action is needed. Teams that remember the short-lived change sometimes assume their migrated agent is isolated when it is not. To isolate deliberately, pass `settingSources: []` (Python `setting_sources=[]`). Python SDK 0.1.59 and earlier treated an empty list the same as omitting it, so upgrade before relying on it. ## What the migration leaves alone - **`claude -p` is untouched.** The CLI still uses Claude Code's system prompt, so a CLI script and its SDK port can diverge on the same prompt. - **Filesystem configuration still loads.** `CLAUDE.md`, skills, hooks and settings-file permission rules arrive through the setting sources, as before. - **Option meanings are stable.** Fields such as `model` and `permission_mode` keep their meaning; in Python only the type name changed. - **Isolation stays opt-in.** An agent that must not see developer configuration has to say so with an explicit `settingSources` value. ## Checking a migrated agent - Compare one run before and after on the same prompt; a terse, generic answer style usually means the preset is missing. - Grep for `ClaudeCodeOptions` and `claude_code_sdk` left in helper modules and tests. - Decide explicitly whether the agent should inherit developer settings; the default says yes. - Keep `append` short and specific so it adds to the preset rather than contradicting it.
- Why can an agent ported from a claude -p script behave less carefully after the move to the SDK?`claude -p` uses Claude Code's system prompt by default; the SDK's minimal default omits the rest of that prompt, including its security and safety instructions. Unless you pass the `claude_code` preset or write your own guidance into a custom prompt, the ported agent runs with less built-in direction.
- Does dropping the claude_code preset stop CLAUDE.md loading in an SDK agent?No. `CLAUDE.md` loading is controlled by setting sources, not the preset. The SDK injects it into the conversation as project context whatever system prompt you choose; to stop it, leave `project` (and `user`) out of `settingSources`.
- Changing the import path is all a migration to the Agent SDK needs.
- The SDK still applies Claude Code's system prompt when none is set.
- Selecting the claude_code preset is what makes CLAUDE.md load.
- Since the rename, omitting settingSources loads no filesystem settings.
- The minimal default prompt keeps Claude Code's safety instructions.
Assumes Claude Agent SDK v0.1.0 or later, the rename's breaking release, checked against the Claude Code 2.1.286 docs.