Claude Code

Agent SDK agent features

Agent loop, settingSources, Claude Code features, sessions, skills, subagents, task tracking, checkpoints and hosting limits.

The SDK reuses project rules, skills, hooks, MCP, subagents, task tracking and checkpoints. Understand what loads automatically, what stays on disk and what increases prefixes and costs.

See runtime patterns for APIs and production deployment for topology and isolation.

#Official pages covered

Official page	Coverage
Agent loop	Message, tool, context, result and hook lifecycle
Claude Code features in SDK	Loading settings, CLAUDE.md, skills, hooks and MCP
Sessions	Continue, resume, fork and cross-host recovery
Skills	Discovery and loading in SDK
Subagents	Programmatic definitions, inheritance and tool limits
Todo tracking	Task tools and live progress UI
File checkpointing	File rollback capabilities and boundaries
Hosting	Subprocesses, local state, resources and limitations

#Agent loop

An SDK task roughly follows this loop:

user prompt
  -> system/init
  -> assistant thinks and emits tool calls
  -> SDK/CLI checks hooks and permissions
  -> tools execute
  -> tool results enter conversation
  -> repeat until success, max turns, max budget, or error

Message/stage	Host responsibility
system/init	Record session ID, model, commands, tools and permission mode
Assistant text	Stream to the UI
Tool use	Show reads, edits, commands or MCP activity
Tool result	Record summaries; collapse sensitive content
Successful result	Save output, usage and cost
Error result	Show cause and preserve recovery information

Common result subtypes:

Subtype	Meaning
success	Completed normally
error_max_turns	maxTurns reached
error_max_budget_usd	Budget reached
error_during_execution	API, tool, cancellation or runtime failure
error_max_structured_output_retries	Repeated schema validation failure

#Context sources

Source	Loaded when	Cache impact
System prompt	Every request	Stable content is reusable
CLAUDE.md / rules	Startup and on demand	Larger content increases initial writes
Tool definitions	Every request or deferred search	Upfront MCP schemas enlarge prefixes
Conversation history	Grows each turn	Long sessions need compaction or branches
Skill descriptions	Startup	Usually small; full content loads on invocation
Hooks	After configuration loads	Hook results may append context

#settingSources

Source	Loaded content
project	Project CLAUDE.md, rules, skills, hooks and settings
user	User CLAUDE.md, rules, skills and settings
`local`	`CLAUDE.local.md`、`.claude/settings.local.json`

settingSources does not control:

Input	Behavior	Disable/isolate with
Endpoint-managed policy	Loaded from device policy	Remove device policy
Server-managed settings	Organization-managed when eligible	Administrator control only
~/.claude.json	May still be read	CLAUDE_CONFIG_DIR
Auto memory	Injected into system prompt at startup	CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
claude.ai MCP connectors	May load with subscription login	strictMcpConfig or disable connector

Do not load user environments by default in multitenant services or CI:

options: {
  settingSources: [],
  env: {
    ...process.env,
    CLAUDE_CONFIG_DIR: "/srv/claude-config/job-123",
    CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1"
  }
}

#Sessions

Scenario	Usage
One-shot task	Omit session and let query() create one
Continue latest in directory	continue: true / continue_conversation=True
Resume a specific session	Save ID and pass resume
Explore alternatives	Fork the session
Avoid persistence	TypeScript persistSession: false

An ID alone cannot restore across hosts. Plan workspace, CLAUDE.md, checkpoints, tool caches and artifacts separately.

#Skills

Load project/user skills or supply them through plugins.

Design area	Recommendation
description	Explain when to use the skill for automatic selection
allowed-tools	Limit the skill's tool scope
Project skills	Version with the repository
User skills	Personal workflows
Plugin skills	Team distribution
SDK isolation	Empty settingSources to avoid automatic loading

Descriptions enter initial context even when full skill content does not. Large inventories still affect prefixes.

#Subagents

Programmatic definitions often suit SDK products better than agent files.

Field	Purpose
description	Helps select the subagent
prompt	Subagent role and task boundaries
tools	Limit available tools
disallowedTools	Remove inherited tools
model	Select a subagent model
skills	Preload named skills
mcpServers	Subagent-specific MCP
maxTurns	Bound task rounds
background	Run without blocking the main thread

Inheritance boundaries:

Subagent receives	Does not receive
Its own system prompt	Full parent conversation
Project CLAUDE.md	Parent tool results
Specified/inherited tools	Parent system prompt
Selected skills	Unloaded skill content

Suggested tool sets:

Use case	Tools
Read-only analysis	Read, Grep, Glob
Tests	Bash, Read, Grep
Code changes	Read, Edit, Write, Grep, Glob
Full autonomy	Carefully inherit tools inside a sandbox

#Todos and Task tools

Current versions favor Task tools over legacy TodoWrite.

Legacy TodoWrite	Task tools
Rewrite the entire array	TaskCreate adds an item
Track status fields	TaskUpdate changes individual fields
Render the array directly	Accumulate events or read snapshots
Simple lists	Owners, dependencies, metadata and parallel work

Listen to TaskCreate, TaskUpdate and TaskList results for progress UIs rather than parsing only assistant prose.

#File checkpointing

Checkpoints provide recovery points around agent file edits.

Tracked action	Description
Write	New files or overwrites
Edit	Partial changes to existing files
NotebookEdit	Jupyter cell edits
Same-session restore	Return to that session's checkpoint

Limitations:

Limitation	Description
Bash changes	Shell-created/deleted files are not checkpointed
Directory operations	Create/move/delete may not fully roll back
Remote files	Network resources are not tracked
Cross-session	Checkpoints belong to their originating session

Create a checkpoint before risky bulk edits or migrations.

#Hosting limitations

Limitation	Mitigation
No top-level wall-clock timeout	maxTurns, process watchdog and queue timeout
Growing session memory	Compact, split tasks and recycle processes
Parallel subagents hit limits	Batch work and bound fanout
No total subagent timeout	maxTurns and a stall watchdog
Extensive local state	Plan config directory, workspace and SessionStore

#Cache effects

Capability	Cache effect
CLAUDE.md through settingSources	Stable content can favor one-hour TTL
Many skills	Descriptions increase prefixes
Upfront MCP tools	Schema changes cause misses
Subagents	Independent contexts and prefixes
Task tools	State enters history; compact long tasks
Checkpoints	Primarily local state; rollback explanations enter conversation

#Official references

PreviousAgent SDK API reference NextAgent SDK capability matrix

Support

Need help?

For setup, billing, or model issues, email us. Check the status page for uptime.

Support Email[email protected]Service Statusstatus.passion8.cc

WeChat / QQ support is available at the bottom right.