Skill: veeramanikandanr48/claude-agent-sdk (version 0.1.0)

--- name: claude-agent-sdk description: | Build autonomous AI agents with Claude Agent SDK. Structured outputs guarantee JSON schema validation, with plugins system and hooks for event-driven workflows. Prevents 14 documented errors. Use when: building coding agents, SRE systems, security auditors, or troubleshooting CLI not found, structured output validation, session forking errors, MCP config issues, subagent cleanup. user-invocable: true --- # 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 `message.structured_output` - **Beta header required**: `structured-outputs-2025-11-13` - **Type safety** - Full TypeScript inference with Zod schemas **Example:** ```typescript import { query } from "@anthropic-ai/claude-agent-sdk"; import { z } from "zod"; import { zodToJsonSchema } from "zod-to-json-schema"; const schema = z.object({ summary: z.string(), sentiment: z.enum(['positive', 'neutral', 'negative']), confidence: z.number().min(0).max(1) }); const response = query({ prompt: "Analyze this code review feedback", options: { model: "claude-sonnet-4-5", outputFormat: { type: "json_schema", json_schema: { name: "AnalysisResult", strict: true, schema: zodToJsonSchema(schema) } } } }); for await (const message of response) { if (message.type === 'result' && message.structured_output) { // Guaranteed to match schema const validated = schema.parse(message.structured_output); console.log(`Sentiment: ${validated.sentiment}`); } } ``` **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 | |------|------------|----------| | `PreToolUse` | Before tool execution | Validate, modify, or block tool calls | | `PostToolUse` | 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:** ```typescript const response = query({ prompt: "...", options: { hooks: { PreToolUse: async (input) => { console.log(`Tool: ${input.toolName}`); return { allow: true }; // or { allow: false, message: "..." } }, PostToolUse: async (input) => { await logToolUsage(input.toolName, input.result); } } } }); ``` ### 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. [Core Query API](#core-query-api) 2. [Tool Integration](#tool-integration-built-in--custom) 3. [MCP Servers](#mcp-servers-model-context-protocol) 4. [Subagent Orchestration](#subagent-orchestration) 5. [Session Management](#session-management) 6. [Permission Control](#permission-control) 7. [Sandbox Settings](#sandbox-settings-security-critical) 8. [File Checkpointing](#file-checkpointing) 9. [Filesystem Settings](#filesystem-settings) 10. [Query Object Methods](#query-object-methods) 11. [Message Types & Streaming](#message-types--streaming) 12. [Error Handling](#error-handling) 13. [Known Issues](#known-issues-prevention) --- ## Core Query API **Key signature:** ```typescript query(prompt: string | AsyncIterable<SDKUserMessage>, options?: Options) -> AsyncGenerator<SDKMessage> ``` **Critical Options:** - `outputFormat` - Structured JSON schema validation (v0.1.45+) - `settingSources` - Filesystem settings loading ('user'|'project'|'local') - `canUseTool` - Custom permission logic callback - `agents` - Programmatic subagent definitions - `mcpServers` - MCP server configuration - `permissionMode` - 'default'|'acceptEdits'|'bypassPermissions'|'plan' - `betas` - Enable beta features (e.g., 1M context window) - `sandbox` - Sandbox settings for secure execution - `enableFileCheckpointing` - Enable file state snapshots - `systemPrompt` - System prompt (string or preset object) ### Extended Context (1M Tokens) Enable 1 million token context window: ```typescript const response = query({ prompt: "Analyze this large codebase", options: { betas: ['context-1m-2025-08-07'], // Enable 1M context model: "claude-sonnet-4-5" } }); ``` ### System Prompt Configuration Two forms of systemPrompt: ```typescript // 1. Simple string systemPrompt: "You are a helpful coding assistant." // 2. Preset with optional append (preserves Claude Code defaults) systemPrompt: { type: 'preset', preset: 'claude_code', append: "\n\nAdditional context: Focus on security." } ``` **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) - `disallowedTools` - Blacklist - `canUseTool` - 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: ```typescript const response = query({ prompt: "Review and refactor the codebase", options: { allowedTools: ["Read", "Write", "Edit", "AskUserQuestion"] } }); // Agent can now ask clarifying questions // Questions appear in message stream as tool_call with name "AskUserQuestion" ``` **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:** ```typescript // 1. Exact allowlist (string array) tools: ["Read", "Write", "Grep"] // 2. Disable all tools (empty array) tools: [] // 3. Preset with defaults (object form) tools: { type: 'preset', preset: 'claude_code' } ``` **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:** ```typescript tool(name: string, description: string, zodSchema, handler) ``` **Handler Return:** ```typescript { content: [{ type: "text", text: "..." }], isError?: boolean } ``` ### External MCP Servers (stdio) ```typescript const response = query({ prompt: "List files and analyze Git history", options: { mcpServers: { // Filesystem server "filesystem": { command: "npx", args: ["@modelcontextprotocol/server-filesystem"], env: { ALLOWED_PATHS: "/Users/developer/projects:/tmp" } }, // Git operations server "git": { command: "npx", args: ["@modelcontextprotocol/server-git"], env: { GIT_REPO_PATH: [REDACTED_SECRET] } } }, allowedTools: [ "mcp__filesystem__list_files", "mcp__filesystem__read_file", "mcp__git__log", "mcp__git__diff" ] } }); ``` ### External MCP Servers (HTTP/SSE) ```typescript const response = query({ prompt: "Analyze data from remote service", options: { mcpServers: { "remote-service": { url: "https://api.example.com/mcp", headers: { "Authorization": "Bearer your-token-here", "Content-Type": "application/json" } } }, allowedTools: ["mcp__remote-service__analyze"] } }); ``` ### MCP Tool Naming Convention **Format**: `mcp__<server-name>__<tool-name>` **CRITICAL:** - Server name and tool name MUST match configuration - Use double underscores (`__`) as separators - Include in `allowedTools` array **Examples:** [REDACTED_SECRET], `mcp__filesystem__read_file` --- ## Subagent Orchestration ### AgentDefinition Type ```typescript type AgentDefinition = { description: string; // When to use this agent prompt: string; // System prompt for agent tools?: string[]; // Allowed tools (optional) model?: 'sonnet' | 'opus' | 'haiku' | 'inherit'; // Model (optional) skills?: string[]; // Skills to load (v0.2.10+) maxTurns?: number; // Maximum turns before stopping (v0.2.10+) } ``` **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:** ```typescript agents: { "security-checker": { description: "Security audits and vulnerability scanning", prompt: "You check security. Scan for secrets, verify OWASP compliance.", tools: ["Read", "Grep", "Bash"], model: "sonnet", skills: ["security-best-practices"], // Load specific skills maxTurns: 10 // Limit to 10 turns } } ``` ### ⚠️ Subagent Cleanup Warning **Known Issue**: Subagents don't stop when parent agent stops ([Issue #132](https://github.com/anthropics/claude-agent-sdk-typescript/issues/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](https://github.com/anthropics/claude-code/issues/4850)) **Workaround**: Implement cleanup in Stop hooks: ```typescript const response = query({ prompt: "Deploy to production", options: { agents: { "deployer": { description: "Handle deployments", prompt: "Deploy the application", tools: ["Bash"] } }, hooks: { Stop: async (input) => { // Manual cleanup of spawned processes console.log("Parent stopped - cleaning up subagents"); // Implement process tracking and termination } } } }); ``` **Enhancement Tracking**: [Issue #142](https://github.com/anthropics/claude-agent-sdk-typescript/issues/142) proposes auto-termination --- ## Session Management **Options:** - `resume: sessionId` - Continue previous session - `forkSession: true` - Create new branch from session - `continue: prompt` - Resume with new prompt (differs from `resume`) **Session Forking Pattern (Unique Capability):** ```typescript // Explore alternative without modifying original const forked = query({ prompt: "Try GraphQL instead of REST", options: { resume: sessionId, forkSession: true // Creates new branch, original session unchanged } }); ``` **Capture Session ID:** ```typescript for await (const message of response) { if (message.type === 'system' && message.subtype === 'init') { sessionId = message.session_id; // Save for later resume/fork } } ``` ### V2 Session APIs (Preview - v0.1.54+) **Simpler multi-turn conversation pattern:** ```typescript import { unstable_v2_createSession, unstable_v2_resumeSession, unstable_v2_prompt } from "@anthropic-ai/claude-agent-sdk"; // Create a new session const session = await unstable_v2_createSession({ model: "claude-sonnet-4-5", workingDirectory: process.cwd(), allowedTools: ["Read", "Grep", "Glob"] }); // Send prompts and stream responses const stream = unstable_v2_prompt(session, "Analyze the codebase structure"); for await (const message of stream) { console.log(message); } // Continue conversation in same session const stream2 = unstable_v2_prompt(session, "Now suggest improvements"); for await (const message of stream2) { console.log(message); } // Resume a previous session const resumedSession = await unstable_v2_resumeSession(session.sessionId); ``` **Note:** V2 APIs are in preview (`unstable_` prefix). The `.receive()` method was renamed to `.stream()` in v0.1.72. --- ## Permission Control **Permission Modes:** ```typescript type PermissionMode = "default" | "acceptEdits" | "bypassPermissions" | "plan"; ``` - `default` - Standard permission checks - `acceptEdits` - Auto-approve file edits - `bypassPermissions` - Skip ALL checks (use in CI/CD only) - `plan` - Planning mode (v0.1.45+) ### Custom Permission Logic ```typescript const response = query({ prompt: "Deploy application to production", options: { permissionMode: "default", canUseTool: async (toolName, input) => { // Allow read-only operations if (['Read', 'Grep', 'Glob'].includes(toolName)) { return { behavior: "allow" }; } // Deny destructive bash commands if (toolName === 'Bash') { const dangerous = ['rm -rf', 'dd if=', 'mkfs', '> /dev/']; if (dangerous.some(pattern => input.command.includes(pattern))) { return { behavior: "deny", message: "Destructive command blocked for safety" }; } } // Require confirmation for deployments if (input.command?.includes('deploy') || input.command?.includes('kubectl apply')) { return { behavior: "ask", message: "Confirm deployment to production?" }; } // Allow by default return { behavior: "allow" }; } } }); ``` ### canUseTool Callback ```typescript type CanUseToolCallback = ( toolName: string, input: any ) => Promise<PermissionDecision>; type PermissionDecision = | { behavior: "allow" } | { behavior: "deny"; message?: string } | { behavior: "ask"; message?: string }; ``` **Examples:** ```typescript // Block all file writes canUseTool: async (toolName, input) => { if (toolName === 'Write' || toolName === 'Edit') { return { behavior: "deny", message: "No file modifications allowed" }; } return { behavior: "allow" }; } // Require confirmation for specific files canUseTool: async (toolName, input) => { const sensitivePaths = ['/etc/', '/root/', '.env', 'credentials.json']; if ((toolName === 'Write' || toolName === 'Edit') && sensitivePaths.some(path => input.file_path?.includes(path))) { return { behavior: "ask", message: `Modify sensitive file ${input.file_path}?` }; } return { behavior: "allow" }; } // Log all tool usage canUseTool: async (toolName, input) => { console.log(`Tool requested: ${toolName}`, input); await logToDatabase(toolName, input); return { behavior: "allow" }; } ``` --- ## Sandbox Settings (Security-Critical) **Enable sandboxed execution for Bash commands:** ```typescript const response = query({ prompt: "Run system diagnostics", options: { sandbox: { enabled: true, autoAllowBashIfSandboxed: true, // Auto-approve bash in sandbox excludedCommands: ["rm", "dd", "mkfs"], // Never auto-approve these allowUnsandboxedCommands: false // Deny unsandboxable commands } } }); ``` ### SandboxSettings Type ```typescript type SandboxSettings = { enabled: boolean; autoAllowBashIfSandboxed?: boolean; // Default: false excludedCommands?: string[]; allowUnsandboxedCommands?: boolean; // Default: false network?: NetworkSandboxSettings; ignoreViolations?: SandboxIgnoreViolations; }; type NetworkSandboxSettings = { enabled: boolean; proxyUrl?: string; // HTTP proxy for network requests }; ``` **Key Options:** - `enabled` - Activate sandbox isolation - `autoAllowBashIfSandboxed` - Skip permission prompts for safe bash commands - `excludedCommands` - Commands that always require permission - `allowUnsandboxedCommands` - Allow commands that can't be sandboxed (risky) - `network.proxyUrl` - 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:** ```typescript const response = query({ prompt: "Refactor the authentication module", options: { enableFileCheckpointing: true // Enable file snapshots } }); // Later: rewind file changes to a specific point for await (const message of response) { if (message.type === 'user' && message.uuid) { // Can rewind to this point later const userMessageUuid = message.uuid; // To rewind (call on Query object) await response.rewindFiles(userMessageUuid); } } ``` **Use cases:** - Undo failed refactoring attempts - A/B test code changes - Safe exploration of alternatives --- ## Filesystem Settings **Setting Sources:** ```typescript type SettingSource = 'user' | 'project' | 'local'; ``` - `user` - `~/.claude/settings.json` (global) - `project` - `.claude/settings.json` (team-shared) - `local` - `.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. **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:** ```typescript // .claude/settings.json { "allowedTools": ["Read", "Write", "Edit"] } // .claude/settings.local.json { "allowedTools": ["Read"] // Overrides project settings } // Programmatic const response = query({ options: { settingSources: ["project", "local"], allowedTools: ["Read", "Grep"] // ← This wins } }); // Actual allowedTools: ["Read", "Grep"] ``` **Best Practice:** Use `settingSources: ["project"]` in CI/CD for consistent behavior. --- ## Query Object Methods The `query()` function returns a `Query` object with these methods: ```typescript const q = query({ prompt: "..." }); // Async iteration (primary usage) for await (const message of q) { ... } // Runtime model control await q.setModel("claude-opus-4-5"); // Change model mid-session await q.setMaxThinkingTokens(4096); // Set thinking budget // Introspection const models = await q.supportedModels(); // List available models const commands = await q.supportedCommands(); // List available commands const account = await q.accountInfo(); // Get account details // MCP status const status = await q.mcpServerStatus(); // Check MCP server status // Returns: { [serverName]: { status: 'connected' | 'failed', error?: string } } // File operations (requires enableFileCheckpointing) await q.rewindFiles(userMessageUuid); // Rewind to checkpoint ``` **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`) - `assistant` - Agent responses - `tool_call` - Tool execution requests - `tool_result` - Tool execution results - `error` - Error messages - `result` - Final result (includes `structured_output` for v0.1.45+) **Streaming Pattern:** ```typescript 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 | |------------|-------|----------| | `CLI_NOT_FOUND` | Claude Code not installed | Install: `npm install -g @anthropic-ai/claude-code` | | `AUTHENTICATION_FAILED` | Invalid API key | Check ANTHROPIC_API_KEY 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: `npm install -g @anthropic-ai/claude-code` ### Issue #2: Authentication Failed **Error**: `"Invalid API key"` **Source**: Missing or incorrect ANTHROPIC_API_KEY **Why It Happens**: Environment variable not set **Prevention**: Always set `export ANTHROPIC_API_KEY="sk-ant-..."` ### 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](https://github.com/anthropics/claude-agent-sdk-typescript/issues/138)) **Why It Happens**: Large codebase, long conversations **⚠️ Critical Behavior**: Once a session hits context limit: 1. All subsequent requests to that session return "Prompt too long" 2. `/compact` command fails with same error 3. **Session is permanently broken and must be abandoned** **Prevention Strategies**: ```typescript // 1. Proactive session forking (create checkpoints before hitting limit) const checkpoint = query({ prompt: "Checkpoint current state", options: { resume: sessionId, forkSession: true // Create branch before hitting limit } }); // 2. Monitor time and rotate sessions proactively const MAX_SESSION_TIME = 80 * 60 * 1000; // 80 minutes (before 90-min crash) let sessionStartTime = Date.now(); function shouldRotateSession() { return Date.now() - sessionStartTime > MAX_SESSION_TIME; } // 3. Start new sessions before hitting context limits if (shouldRotateSession()) { const summary = await getSummary(currentSession); const newSession = query({ prompt: `Continue with context: ${summary}` }); sessionStartTime = Date.now(); } ``` **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 `.describe()` ### 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](https://github.com/anthropics/claude-agent-sdk-typescript/issues/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 ```typescript // ❌ Wrong - missing type field (causes cryptic exit code 1) mcpServers: { "my-server": { url: "https://api.example.com/mcp" } } // ✅ Correct - type field required for URL-based servers mcpServers: { "my-server": { url: "https://api.example.com/mcp", type: "http" // or "sse" for Server-Sent Events } } ``` **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](https://github.com/anthropics/claude-agent-sdk-typescript/issues/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 ```typescript // MCP tool handler - sanitize external data tool("fetch_content", "Fetch text content", {}, async (args) => { const content = await fetchExternalData(); // ✅ Sanitize Unicode line/paragraph separators const sanitized = content .replace(/\u2028/g, '\\u2028') .replace(/\u2029/g, '\\u2029'); return { content: [{ type: "text", text: sanitized }] }; }); ``` **When This Matters**: External data sources (APIs, web scraping, user input) that may contain these characters **Related**: [MCP Python SDK Issue #1356](https://github.com/modelcontextprotocol/python-sdk/issues/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


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: suspicious | SkillSpector: suspicious (CRITICAL)