# Claude Code Agent SDK agent features

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

URL: https://docs.passion8.cc/en/docs/claude-code/sdk-agent-features
Language: en
Publisher: Passion8

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](https://docs.passion8.cc/en/docs/claude-code/sdk-runtime-patterns) for APIs and [production deployment](https://docs.passion8.cc/en/docs/claude-code/sdk-production) 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:

```text
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:

```typescript
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

- [How the agent loop works](https://code.claude.com/docs/en/agent-sdk/agent-loop.md)
- [Claude Code features in SDK](https://code.claude.com/docs/en/agent-sdk/claude-code-features.md)
- [Work with sessions](https://code.claude.com/docs/en/agent-sdk/sessions.md)
- [Agent Skills in SDK](https://code.claude.com/docs/en/agent-sdk/skills.md)
- [Subagents in SDK](https://code.claude.com/docs/en/agent-sdk/subagents.md)
- [Todo Lists](https://code.claude.com/docs/en/agent-sdk/todo-tracking.md)
- [File checkpointing](https://code.claude.com/docs/en/agent-sdk/file-checkpointing.md)
- [Hosting the Agent SDK](https://code.claude.com/docs/en/agent-sdk/hosting.md)