Claude Code SDK vs Claude Agent SDK: the rename, and whether you need either

The Claude Code SDK was renamed to the Claude Agent SDK, with two breaking changes that make migrated code behave differently. What actually changed, why claude -p is the third option nobody frames as one, and the CI security gap in a non-interactive run that has not trusted the folder.

If you are searching for the Claude Code SDK: it was renamed. It is now the Claude Agent SDK, the packages changed, and two breaking changes mean a straight find-and-replace leaves your agent behaving differently than before.

The rename reflects a real repositioning: it is a library for building agents, not a coding-specific tool. But the more useful question is the one underneath, which almost nobody frames properly, so start there.

There are four things, not two

The docs have a table for this and it is worth internalizing before you install anything:

• Agent SDK: a library that runs the agent loop in your own process. Python and TypeScript only.
• Claude Code CLI: the terminal interface, for interactive work and one-off tasks.
• Client SDK: direct Anthropic API access, where you implement the tool loop yourself.
• Managed Agents: a hosted REST API where Anthropic runs the agent and the sandbox. A separate product.

The gap most people fall into is reaching for the Agent SDK when they wanted the third option below.

claude -p is the third option

For any language that is not Python or TypeScript, the documented answer is to run the CLI as a subprocess with -p and --output-format json. That is not a workaround, it is the recommended path, and it is also a perfectly good answer in Python and TypeScript for anything that does not need callbacks.

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

You get structured output, a session ID you can resume, and cost figures:

claude -p "Summarize this project" --output-format json | jq -r '.result'

And you can constrain the shape of the answer, which is the feature that removes most of the reason to write a wrapper:

claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

Reach for the actual SDK when you need what a subprocess cannot give you: a canUseTool callback that decides permissions in your own code, native message objects, streaming with real callbacks rather than parsing newline-delimited JSON, or hooks written in your host language instead of as shell commands.

The two breaking changes that matter

The system prompt is no longer Claude Code's by default. Version 0.1.0 switched to a minimal system prompt. If your agent got noticeably worse at coding tasks after migrating, this is why. Ask for the preset explicitly:

const result = query({
  prompt: "Hello",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" }
  }
});

settingSources has a history that will mislead you. The default was briefly changed in v0.1.0 to load nothing from the filesystem, then reverted. Current behavior: omitting it loads user, project, and local settings, matching the CLI, including ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, CLAUDE.md, and custom commands. Any blog post written during that window tells you the opposite.

For CI, deployed apps, test environments, and anything multi-tenant, you want isolation, and you have to ask for it:

setting_sources=[]

Python SDK 0.1.59 and earlier treated an empty list the same as omitting the option, so check your version before relying on it. And be aware that settings precedence still applies to whatever does load.

The CI gap worth knowing about

This one is a genuine security finding rather than a preference, and it applies to claude -p rather than the SDK packages.

Without --bare, a -p session runs the hooks in a project's .claude/settings.json and connects the servers in its .mcp.json, even in a folder you have never trusted. There is no workspace trust dialog in -p mode and no per-server approval prompt. If your CI checks out a pull request from a fork and runs Claude Code over it, repository content decides what executes.

--bare is the fix, and the docs call it the recommended mode for scripted and SDK calls, with a note that it will become the default for -p in a future release. It skips auto-discovery of hooks, skills, custom commands, subagents, plugins, MCP servers, auto memory, and CLAUDE.md:

claude --bare -p "Summarize README.md" --allowedTools "Read"

Two consequences to plan for. Bare mode never reads OAuth credentials or the system keychain, so set ANTHROPIC_API_KEY or supply an apiKeyHelper; Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry still read their own provider credentials. And you now pass context explicitly: --append-system-prompt, --settings, --mcp-config, --agents, --plugin-dir.

This is the same principle as everything else in the security model: the repository is input, not authority. -p is the one place that principle is not enforced by default.

Non-interactive behavior that surprises people

• The starting permission mode for -p is Manual on every plan, not auto mode. Pass --permission-mode auto if you want the classifier, or dontAsk for a locked-down run that denies anything outside your allow rules.
• --permission-prompts none is for scheduled jobs with nobody to answer. Anything that would prompt is denied, Claude is told not to retry it, and the run continues instead of hanging.
• Background Bash tasks are killed about five seconds after the final result. A dev server started mid-run does not survive.
• Background subagents keep the process open until they finish, capped at ten minutes of continuous idle waiting, tunable with CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS. Set it to 0 to wait indefinitely.
• SIGTERM exits with code 143 and leaves the in-progress turn unfinished with no result recorded. Send SIGINT, or call the SDK's interrupt(), if you want the turn to end cleanly.
• Piped stdin is capped at 10MB. Above that, write to a file and reference the path.

Two constraints if you are shipping a product

Easy to miss, and both are stated plainly in the docs.

You cannot offer claude.ai login or rate limits to your users. Unless previously approved, Anthropic does not allow third-party developers to do that for products built on the Agent SDK. Use API key authentication. If your business model assumed customers would bring their own Claude subscription, check this before building around it.

You cannot call it Claude Code. "Claude Code" and "Claude Code Agent" are not permitted product names, and neither is Claude Code-branded ASCII art or visuals that mimic it. "Claude Agent", "Claude" inside a menu already labeled Agents, or "YourName Powered by Claude" are allowed.

How to pick

• A script, a CI step, a linter, a one-off: claude -p with --bare, --output-format json, and an explicit --permission-mode. No dependency, works from any language.
• A product with its own permission UI, streaming, or in-process hooks: the Agent SDK, in Python or TypeScript.
• You want the agent loop but not the sandbox or session infrastructure: Managed Agents.
• You want the model and will write your own loop: the Client SDK. Worth being honest that this is more work than it looks, because the context management is a large part of what makes the agent loop work at all.

The migration itself is twenty minutes. The part that costs a day is the system prompt default, because nothing errors, the agent just gets quietly worse, and you will look everywhere else first.