[DOCS] Clarification needed on Agent SDK System Prompt defaults and "Minimum Viable Configuration"

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://platform.claude.com/docs/en/agent-sdk/migration-guide - https://platform.claude.com/docs/en/agent-sdk/typescript - https://platform.claude.com/docs/en/agent-sdk/quickstart

Section/Topic

The default behavior of systemPrompt and the relationship between an "empty prompt" and the agent's ability to execute a tool loop.

Current Documentation

• Migration Guide: "The SDK no longer uses Claude Code's system prompt by default. [...] AFTER (v0.1.0) - Uses empty system prompt by default."
• TypeScript Reference: systemPrompt default: undefined (empty prompt).
• Overview/Quickstart: "Build AI agents that autonomously read files, run commands... build a bug-fixing agent in minutes."

What's Wrong or Missing?

There is a logical gap between the "empty system prompt" default and the "agentic" nature of the SDK:

1. Ambiguity of "Empty": Does "empty" mean the API call is sent with a null system parameter (meaning Claude acts as a generic assistant), or is there a hidden "base agentic loop" instruction that is always present?
2. Minimum Viable Config: If a user initializes a query with a string prompt but leaves options undefined, the docs suggest they get an empty system prompt and an empty allowedTools list. In this state, the agent cannot actually perform the "autonomous" tasks mentioned in the Quickstart because it has neither the instructions to use tools nor the permission to execute them.
3. Contradictory Tool Defaults: The TS reference says allowedTools defaults to "All tools" in the description table, but the logic of the PermissionMode documentation suggests that without explicit configuration, nothing is auto-approved.

Suggested Improvement

Add a "Core Concepts" or "SDK Defaults" section that explicitly defines the Minimum Viable Configuration required to achieve an autonomous loop.

Suggested Text:

### Understanding the Default State By default, the Claude Agent SDK initializes with an empty system prompt. This means Claude will behave as a standard conversational assistant unless you: 1. Specify a Preset: Use systemPrompt: { type: "preset", preset: "claude_code" } to give Claude the reasoning capabilities required to use the built-in toolset (Read, Edit, Bash, etc.). 2. Provide Allowed Tools: Even if Claude knows how to use a tool via a prompt, you must explicitly list tool names in allowedTools or set a permissionMode (like acceptEdits) for the agent to execute them without a canUseTool callback. Note: A query with no options provided will result in a standard one-turn text response, as the model will have no instructions or permissions to enter a tool-use loop.

Impact

High - Prevents users from using a feature

Additional Context

• Related Docs: SDK Migration Guide
• Comparison: Most agentic frameworks (like LangGraph or AutoGPT) distinguish between the "Model" and the "Executor." The Claude Agent SDK documentation blurs these lines by stating the SDK is "agentic by default" while simultaneously stating the prompt that drives that agency (the Claude Code system prompt) is "off by default."