Claude Agent SDK - Structured Outputs & Error Prevention Guide

Package: @anthropic-ai/claude-agent-sdk@0.2.12
Breaking Changes: v0.1.45 - Structured outputs (Nov 2025), v0.1.0 - No default system prompt, settingSources required

---

What's New in v0.1.45+ (Nov 2025)

Major Features:

1. Structured Outputs (v0.1.45, Nov 14, 2025)

• - JSON schema validation - Guarantees responses match exact schemas
• outputFormat parameter - Define output structure with JSON schema or Zod
• Access validated results - Via INLINECODE1
• Beta header required: INLINECODE2
• Type safety - Full TypeScript inference with Zod schemas

Example:
CODEBLOCK0

Zod Compatibility (v0.1.71+): SDK supports both Zod v3.24.1+ and Zod v4.0.0+ as peer dependencies. Import remains import { z } from "zod" for either version.

2. Plugins System (v0.1.27)

• - plugins array - Load local plugin paths
• Custom plugin support - Extend agent capabilities

3. Hooks System (v0.1.0+)

All 12 Hook Events:

Hook	When Fired	Use Case
INLINECODE5	Before tool execution	Validate, modify, or block tool calls
INLINECODE6

After tool execution | Log results, trigger side effects |
| Notification | Agent notifications | Display status updates |
| UserPromptSubmit | User prompt received | Pre-process or validate input |
| SubagentStart | Subagent spawned | Track delegation, log context |
| SubagentStop | Subagent completed | Aggregate results, cleanup |
| PreCompact | Before context compaction | Save state before truncation |
| PermissionRequest | Permission needed | Custom approval workflows |
| Stop | Agent stopping | Cleanup, final logging |
| SessionStart | Session begins | Initialize state |
| SessionEnd | Session ends | Persist state, cleanup |
| Error | Error occurred | Custom error handling |

Hook Configuration:
CODEBLOCK1

4. Additional Options

• - fallbackModel - Automatic model fallback on failures
• maxThinkingTokens - Control extended thinking budget
• strictMcpConfig - Strict MCP configuration validation
• continue - Resume with new prompt (differs from resume)
• permissionMode: 'plan' - New permission mode for planning workflows

📚 Docs: https://platform.claude.com/docs/en/agent-sdk/structured-outputs

---

The Complete Claude Agent SDK Reference

Table of Contents

1. 1. Core Query API
2. Tool Integration
3. MCP Servers
4. Subagent Orchestration
5. Session Management
6. Permission Control
7. Sandbox Settings
8. File Checkpointing
9. Filesystem Settings
10. Query Object Methods
11. Message Types & Streaming
12. Error Handling
13. Known Issues

---

Core Query API

Key signature:
CODEBLOCK2

Critical Options:

• - outputFormat - Structured JSON schema validation (v0.1.45+)
• INLINECODE24 - Filesystem settings loading ('user'|'project'|'local')
• INLINECODE25 - Custom permission logic callback
• INLINECODE26 - Programmatic subagent definitions
• INLINECODE27 - MCP server configuration
• INLINECODE28 - 'default'|'acceptEdits'|'bypassPermissions'|'plan'
• INLINECODE29 - Enable beta features (e.g., 1M context window)
• INLINECODE30 - Sandbox settings for secure execution
• INLINECODE31 - Enable file state snapshots
• INLINECODE32 - System prompt (string or preset object)

Extended Context (1M Tokens)

Enable 1 million token context window:

CODEBLOCK3

System Prompt Configuration

Two forms of systemPrompt:

CODEBLOCK4

Use preset form when you want Claude Code's default behaviors plus custom additions.

---

Tool Integration (Built-in + Custom)

Tool Control:

• - allowedTools - Whitelist (takes precedence)
• INLINECODE34 - Blacklist
• INLINECODE35 - Custom permission callback (see Permission Control section)

Built-in Tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, Task, NotebookEdit, BashOutput, KillBash, ListMcpResources, ReadMcpResource, AskUserQuestion

AskUserQuestion Tool (v0.1.71+)

Enable user interaction during agent execution:

CODEBLOCK5

Use cases:

• - Clarify ambiguous requirements mid-task
• Get user approval before destructive operations
• Present options and get selection

Tools Configuration (v0.1.57+)

Three forms of tool configuration:

CODEBLOCK6

Note: allowedTools and disallowedTools still work but tools provides more flexibility.

---

MCP Servers (Model Context Protocol)

Server Types:

• - In-process - createSdkMcpServer() with tool() definitions
• External - stdio, HTTP, SSE transport

Tool Definition:
CODEBLOCK7

Handler Return:
CODEBLOCK8

External MCP Servers (stdio)

CODEBLOCK9

External MCP Servers (HTTP/SSE)

CODEBLOCK10

MCP Tool Naming Convention

Format: INLINECODE41

CRITICAL:

• - Server name and tool name MUST match configuration
• Use double underscores (__) as separators
• Include in allowedTools array

Examples: mcp__weather-service__get_weather, mcp__filesystem__read_file

---

Subagent Orchestration

AgentDefinition Type

CODEBLOCK11

Field Details:

• - description: When to use agent (used by main agent for delegation)
• prompt: System prompt (defines role, inherits main context)
• tools: Allowed tools (if omitted, inherits from main agent)
• model: Model override (haiku/sonnet/opus/inherit)
• skills: Skills to load for agent (v0.2.10+)
• maxTurns: Limit agent to N turns before returning control (v0.2.10+)

Usage:
CODEBLOCK12

⚠️ Subagent Cleanup Warning

Known Issue: Subagents don't stop when parent agent stops (Issue #132)

When a parent agent is stopped (via cancellation or error), spawned subagents continue running as orphaned processes. This can lead to:

• - Resource leaks
• Continued tool execution after parent stopped
• RAM out-of-memory in recursive scenarios (Claude Code Issue #4850)

Workaround: Implement cleanup in Stop hooks:

CODEBLOCK13

Enhancement Tracking: Issue #142 proposes auto-termination

---

Session Management

Options:

• - resume: sessionId - Continue previous session
• INLINECODE51 - Create new branch from session
• INLINECODE52 - Resume with new prompt (differs from resume)

Session Forking Pattern (Unique Capability):

CODEBLOCK14

Capture Session ID:
CODEBLOCK15

V2 Session APIs (Preview - v0.1.54+)

Simpler multi-turn conversation pattern:

CODEBLOCK16

Note: V2 APIs are in preview (unstable_ prefix). The .receive() method was renamed to .stream() in v0.1.72.

---

Permission Control

Permission Modes:
CODEBLOCK17

• - default - Standard permission checks
• INLINECODE58 - Auto-approve file edits
• INLINECODE59 - Skip ALL checks (use in CI/CD only)
• INLINECODE60 - Planning mode (v0.1.45+)

Custom Permission Logic

CODEBLOCK18

canUseTool Callback

CODEBLOCK19

Examples:

CODEBLOCK20

---

Sandbox Settings (Security-Critical)

Enable sandboxed execution for Bash commands:

CODEBLOCK21

SandboxSettings Type

CODEBLOCK22

Key Options:

• - enabled - Activate sandbox isolation
• INLINECODE62 - Skip permission prompts for safe bash commands
• INLINECODE63 - Commands that always require permission
• INLINECODE64 - Allow commands that can't be sandboxed (risky)
• INLINECODE65 - Route network through proxy for monitoring

Best Practice: Always use sandbox in production agents handling untrusted input.

---

File Checkpointing

Enable file state snapshots for rollback capability:

CODEBLOCK23

Use cases:

• - Undo failed refactoring attempts
• A/B test code changes
• Safe exploration of alternatives

---

Filesystem Settings

Setting Sources:
CODEBLOCK24

• - user - ~/.claude/settings.json (global)
• INLINECODE68 - .claude/settings.json (team-shared)
• INLINECODE70 - .claude/settings.local.json (gitignored overrides)

Default: NO settings loaded (settingSources: [])

Settings Priority

When multiple sources loaded, settings merge in this order (highest priority first):

1. 1. Programmatic options (passed to query()) - Always win
2. Local settings (.claude/settings.local.json)
3. Project settings (.claude/settings.json)
4. User settings (~/.claude/settings.json)

Example:

CODEBLOCK25

Best Practice: Use settingSources: ["project"] in CI/CD for consistent behavior.

---

Query Object Methods

The query() function returns a Query object with these methods:

CODEBLOCK26

Use cases:

• - Dynamic model switching based on task complexity
• Monitoring MCP server health
• Adjusting thinking budget for reasoning tasks

---

Message Types & Streaming

Message Types:

• - system - Session init/completion (includes session_id)
• INLINECODE82 - Agent responses
• INLINECODE83 - Tool execution requests
• INLINECODE84 - Tool execution results
• INLINECODE85 - Error messages
• INLINECODE86 - Final result (includes structured_output for v0.1.45+)

Streaming Pattern:

for await (const message of response) {
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id;  // Capture for resume/fork
  }
  if (message.type === 'result' && message.structured_output) {
    // Structured output available (v0.1.45+)
    const validated = schema.parse(message.structured_output);
  }
}

---

Error Handling

Error Codes:

Error Code	Cause	Solution
INLINECODE88	Claude Code not installed	Install: INLINECODE89
INLINECODE90

Invalid API key | Check ANTHROPICAPIKEY env var |
| RATE_LIMIT_EXCEEDED | Too many requests | Implement retry with backoff |
| CONTEXT_LENGTH_EXCEEDED | Prompt too long | Use session compaction, reduce context |
| PERMISSION_DENIED | Tool blocked | Check permissionMode, canUseTool |
| TOOL_EXECUTION_FAILED | Tool error | Check tool implementation |
| SESSION_NOT_FOUND | Invalid session ID | Verify session ID |
| MCP_SERVER_FAILED | Server error | Check server configuration |

---

Known Issues Prevention

This skill prevents 14 documented issues:

Issue #1: CLI Not Found Error

Error: "Claude Code CLI not installed" Source: SDK requires Claude Code CLI Why It Happens: CLI not installed globally Prevention: Install before using SDK: INLINECODE98

Issue #2: Authentication Failed

Error: "Invalid API key" Source: Missing or incorrect ANTHROPICAPIKEY Why It Happens: Environment variable not set Prevention: Always set INLINECODE100

Issue #3: Permission Denied Errors

Error: Tool execution blocked Source: permissionMode restrictions Why It Happens: Tool not allowed by permissions Prevention: Use allowedTools or custom canUseTool callback

Issue #4: Context Length Exceeded (Session-Breaking)

Error: "Prompt too long" Source: Input exceeds model context window (Issue #138) Why It Happens: Large codebase, long conversations

⚠️ Critical Behavior: Once a session hits context limit:

1. 1. All subsequent requests to that session return "Prompt too long"
2. INLINECODE105 command fails with same error
3. Session is permanently broken and must be abandoned

Prevention Strategies:

CODEBLOCK28

Note: SDK auto-compacts, but if limit is reached, session becomes unrecoverable

Issue #5: Tool Execution Timeout

Error: Tool doesn't respond Source: Long-running tool execution Why It Happens: Tool takes too long (>5 minutes default) Prevention: Implement timeout handling in tool implementations

Issue #6: Session Not Found

Error: "Invalid session ID" Source: Session expired or invalid Why It Happens: Session ID incorrect or too old Prevention: Capture session_id from system init message

Issue #7: MCP Server Connection Failed

Error: Server not responding Source: Server not running or misconfigured Why It Happens: Command/URL incorrect, server crashed Prevention: Test MCP server independently, verify command/URL

Issue #8: Subagent Definition Errors

Error: Invalid AgentDefinition Source: Missing required fields Why It Happens: description or prompt missing Prevention: Always include description and prompt fields

Issue #9: Settings File Not Found

Error: "Cannot read settings" Source: Settings file doesn't exist Why It Happens: settingSources includes non-existent file Prevention: Check file exists before including in sources

Issue #10: Tool Name Collision

Error: Duplicate tool name Source: Multiple tools with same name Why It Happens: Two MCP servers define same tool name Prevention: Use unique tool names, prefix with server name

Issue #11: Zod Schema Validation Error

Error: Invalid tool input Source: Input doesn't match Zod schema Why It Happens: Agent provided wrong data type Prevention: Use descriptive Zod schemas with INLINECODE115

Issue #12: Filesystem Permission Denied

Error: Cannot access path Source: Restricted filesystem access Why It Happens: Path outside workingDirectory or no permissions Prevention: Set correct workingDirectory, check file permissions

Issue #13: MCP Server Config Missing type Field

Error: "Claude Code process exited with code 1" (cryptic, no context) Source: GitHub Issue #131 Why It Happens: URL-based MCP servers require explicit type: "http" or type: "sse" field Prevention: Always specify transport type for URL-based MCP servers

CODEBLOCK29

Diagnostic Clue: If you see "process exited with code 1" with no other context, check your MCP server configuration for missing type fields.

Issue #14: MCP Tool Result with Unicode Line Separators

Error: JSON parse error, agent hangs Source: GitHub Issue #137 Why It Happens: Unicode U+2028 (line separator) and U+2029 (paragraph separator) are valid in JSON but break JavaScript parsing Prevention: Escape these characters in MCP tool results

CODEBLOCK30

When This Matters: External data sources (APIs, web scraping, user input) that may contain these characters

Related: MCP Python SDK Issue #1356

---

Official Documentation

• - Agent SDK Overview: https://platform.claude.com/docs/en/api/agent-sdk/overview
• TypeScript API: https://platform.claude.com/docs/en/api/agent-sdk/typescript
• Structured Outputs: https://platform.claude.com/docs/en/agent-sdk/structured-outputs
• GitHub (TypeScript): https://github.com/anthropics/claude-agent-sdk-typescript
• CHANGELOG: https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md

---

Token Efficiency:

• - Without skill: ~15,000 tokens (MCP setup, permission patterns, session APIs, sandbox config, hooks, structured outputs, error handling)
• With skill: ~4,500 tokens (comprehensive v0.2.12 coverage + error prevention + advanced patterns)
• Savings: ~70% (~10,500 tokens)

Errors prevented: 14 documented issues with exact solutions (including 2 community-sourced gotchas)
Key value: V2 Session APIs, Sandbox Settings, File Checkpointing, Query methods, AskUserQuestion tool, structured outputs (v0.1.45+), session forking, canUseTool patterns, complete hooks system (12 events), Zod v4 support, subagent cleanup patterns

---

Last verified: 2026-01-20 | Skill version: 3.1.0 | Changes: Added Issue #13 (MCP type field), Issue #14 (Unicode U+2028/U+2029), expanded Issue #4 (session-breaking), added subagent cleanup warning with Stop hook pattern