{
  "schemaVersion": "1.0",
  "item": {
    "slug": "claude-agent-sdk",
    "name": "Claude Agent Sdk",
    "source": "tencent",
    "type": "skill",
    "category": "效率提升",
    "sourceUrl": "https://clawhub.ai/Veeramanikandanr48/claude-agent-sdk",
    "canonicalUrl": "https://clawhub.ai/Veeramanikandanr48/claude-agent-sdk",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/claude-agent-sdk",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=claude-agent-sdk",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      ".claude-plugin/plugin.json",
      "README.md",
      "SKILL.md",
      "references/mcp-servers-guide.md",
      "references/permissions-guide.md",
      "references/query-api-reference.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-23T16:43:11.935Z",
      "expiresAt": "2026-04-30T16:43:11.935Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard",
        "contentDisposition": "attachment; filename=\"4claw-imageboard-1.0.1.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/claude-agent-sdk"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/claude-agent-sdk",
    "agentPageUrl": "https://openagent3.xyz/skills/claude-agent-sdk/agent",
    "manifestUrl": "https://openagent3.xyz/skills/claude-agent-sdk/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/claude-agent-sdk/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Claude Agent SDK - Structured Outputs & Error Prevention Guide",
        "body": "Package: @anthropic-ai/claude-agent-sdk@0.2.12\nBreaking Changes: v0.1.45 - Structured outputs (Nov 2025), v0.1.0 - No default system prompt, settingSources required"
      },
      {
        "title": "What's New in v0.1.45+ (Nov 2025)",
        "body": "Major Features:"
      },
      {
        "title": "1. Structured Outputs (v0.1.45, Nov 14, 2025)",
        "body": "JSON schema validation - Guarantees responses match exact schemas\noutputFormat parameter - Define output structure with JSON schema or Zod\nAccess validated results - Via message.structured_output\nBeta header required: structured-outputs-2025-11-13\nType safety - Full TypeScript inference with Zod schemas\n\nExample:\n\nimport { query } from \"@anthropic-ai/claude-agent-sdk\";\nimport { z } from \"zod\";\nimport { zodToJsonSchema } from \"zod-to-json-schema\";\n\nconst schema = z.object({\n  summary: z.string(),\n  sentiment: z.enum(['positive', 'neutral', 'negative']),\n  confidence: z.number().min(0).max(1)\n});\n\nconst response = query({\n  prompt: \"Analyze this code review feedback\",\n  options: {\n    model: \"claude-sonnet-4-5\",\n    outputFormat: {\n      type: \"json_schema\",\n      json_schema: {\n        name: \"AnalysisResult\",\n        strict: true,\n        schema: zodToJsonSchema(schema)\n      }\n    }\n  }\n});\n\nfor await (const message of response) {\n  if (message.type === 'result' && message.structured_output) {\n    // Guaranteed to match schema\n    const validated = schema.parse(message.structured_output);\n    console.log(`Sentiment: ${validated.sentiment}`);\n  }\n}\n\nZod 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."
      },
      {
        "title": "2. Plugins System (v0.1.27)",
        "body": "plugins array - Load local plugin paths\nCustom plugin support - Extend agent capabilities"
      },
      {
        "title": "3. Hooks System (v0.1.0+)",
        "body": "All 12 Hook Events:\n\nHookWhen FiredUse CasePreToolUseBefore tool executionValidate, modify, or block tool callsPostToolUseAfter tool executionLog results, trigger side effectsNotificationAgent notificationsDisplay status updatesUserPromptSubmitUser prompt receivedPre-process or validate inputSubagentStartSubagent spawnedTrack delegation, log contextSubagentStopSubagent completedAggregate results, cleanupPreCompactBefore context compactionSave state before truncationPermissionRequestPermission neededCustom approval workflowsStopAgent stoppingCleanup, final loggingSessionStartSession beginsInitialize stateSessionEndSession endsPersist state, cleanupErrorError occurredCustom error handling\n\nHook Configuration:\n\nconst response = query({\n  prompt: \"...\",\n  options: {\n    hooks: {\n      PreToolUse: async (input) => {\n        console.log(`Tool: ${input.toolName}`);\n        return { allow: true };  // or { allow: false, message: \"...\" }\n      },\n      PostToolUse: async (input) => {\n        await logToolUsage(input.toolName, input.result);\n      }\n    }\n  }\n});"
      },
      {
        "title": "4. Additional Options",
        "body": "fallbackModel - Automatic model fallback on failures\nmaxThinkingTokens - Control extended thinking budget\nstrictMcpConfig - Strict MCP configuration validation\ncontinue - Resume with new prompt (differs from resume)\npermissionMode: 'plan' - New permission mode for planning workflows\n\n📚 Docs: https://platform.claude.com/docs/en/agent-sdk/structured-outputs"
      },
      {
        "title": "Table of Contents",
        "body": "Core Query API\nTool Integration\nMCP Servers\nSubagent Orchestration\nSession Management\nPermission Control\nSandbox Settings\nFile Checkpointing\nFilesystem Settings\nQuery Object Methods\nMessage Types & Streaming\nError Handling\nKnown Issues"
      },
      {
        "title": "Core Query API",
        "body": "Key signature:\n\nquery(prompt: string | AsyncIterable<SDKUserMessage>, options?: Options)\n  -> AsyncGenerator<SDKMessage>\n\nCritical Options:\n\noutputFormat - Structured JSON schema validation (v0.1.45+)\nsettingSources - Filesystem settings loading ('user'|'project'|'local')\ncanUseTool - Custom permission logic callback\nagents - Programmatic subagent definitions\nmcpServers - MCP server configuration\npermissionMode - 'default'|'acceptEdits'|'bypassPermissions'|'plan'\nbetas - Enable beta features (e.g., 1M context window)\nsandbox - Sandbox settings for secure execution\nenableFileCheckpointing - Enable file state snapshots\nsystemPrompt - System prompt (string or preset object)"
      },
      {
        "title": "Extended Context (1M Tokens)",
        "body": "Enable 1 million token context window:\n\nconst response = query({\n  prompt: \"Analyze this large codebase\",\n  options: {\n    betas: ['context-1m-2025-08-07'],  // Enable 1M context\n    model: \"claude-sonnet-4-5\"\n  }\n});"
      },
      {
        "title": "System Prompt Configuration",
        "body": "Two forms of systemPrompt:\n\n// 1. Simple string\nsystemPrompt: \"You are a helpful coding assistant.\"\n\n// 2. Preset with optional append (preserves Claude Code defaults)\nsystemPrompt: {\n  type: 'preset',\n  preset: 'claude_code',\n  append: \"\\n\\nAdditional context: Focus on security.\"\n}\n\nUse preset form when you want Claude Code's default behaviors plus custom additions."
      },
      {
        "title": "Tool Integration (Built-in + Custom)",
        "body": "Tool Control:\n\nallowedTools - Whitelist (takes precedence)\ndisallowedTools - Blacklist\ncanUseTool - Custom permission callback (see Permission Control section)\n\nBuilt-in Tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, Task, NotebookEdit, BashOutput, KillBash, ListMcpResources, ReadMcpResource, AskUserQuestion"
      },
      {
        "title": "AskUserQuestion Tool (v0.1.71+)",
        "body": "Enable user interaction during agent execution:\n\nconst response = query({\n  prompt: \"Review and refactor the codebase\",\n  options: {\n    allowedTools: [\"Read\", \"Write\", \"Edit\", \"AskUserQuestion\"]\n  }\n});\n\n// Agent can now ask clarifying questions\n// Questions appear in message stream as tool_call with name \"AskUserQuestion\"\n\nUse cases:\n\nClarify ambiguous requirements mid-task\nGet user approval before destructive operations\nPresent options and get selection"
      },
      {
        "title": "Tools Configuration (v0.1.57+)",
        "body": "Three forms of tool configuration:\n\n// 1. Exact allowlist (string array)\ntools: [\"Read\", \"Write\", \"Grep\"]\n\n// 2. Disable all tools (empty array)\ntools: []\n\n// 3. Preset with defaults (object form)\ntools: { type: 'preset', preset: 'claude_code' }\n\nNote: allowedTools and disallowedTools still work but tools provides more flexibility."
      },
      {
        "title": "MCP Servers (Model Context Protocol)",
        "body": "Server Types:\n\nIn-process - createSdkMcpServer() with tool() definitions\nExternal - stdio, HTTP, SSE transport\n\nTool Definition:\n\ntool(name: string, description: string, zodSchema, handler)\n\nHandler Return:\n\n{ content: [{ type: \"text\", text: \"...\" }], isError?: boolean }"
      },
      {
        "title": "External MCP Servers (stdio)",
        "body": "const response = query({\n  prompt: \"List files and analyze Git history\",\n  options: {\n    mcpServers: {\n      // Filesystem server\n      \"filesystem\": {\n        command: \"npx\",\n        args: [\"@modelcontextprotocol/server-filesystem\"],\n        env: {\n          ALLOWED_PATHS: \"/Users/developer/projects:/tmp\"\n        }\n      },\n      // Git operations server\n      \"git\": {\n        command: \"npx\",\n        args: [\"@modelcontextprotocol/server-git\"],\n        env: {\n          GIT_REPO_PATH: \"/Users/developer/projects/my-repo\"\n        }\n      }\n    },\n    allowedTools: [\n      \"mcp__filesystem__list_files\",\n      \"mcp__filesystem__read_file\",\n      \"mcp__git__log\",\n      \"mcp__git__diff\"\n    ]\n  }\n});"
      },
      {
        "title": "External MCP Servers (HTTP/SSE)",
        "body": "const response = query({\n  prompt: \"Analyze data from remote service\",\n  options: {\n    mcpServers: {\n      \"remote-service\": {\n        url: \"https://api.example.com/mcp\",\n        headers: {\n          \"Authorization\": \"Bearer your-token-here\",\n          \"Content-Type\": \"application/json\"\n        }\n      }\n    },\n    allowedTools: [\"mcp__remote-service__analyze\"]\n  }\n});"
      },
      {
        "title": "MCP Tool Naming Convention",
        "body": "Format: mcp__<server-name>__<tool-name>\n\nCRITICAL:\n\nServer name and tool name MUST match configuration\nUse double underscores (__) as separators\nInclude in allowedTools array\n\nExamples: mcp__weather-service__get_weather, mcp__filesystem__read_file"
      },
      {
        "title": "AgentDefinition Type",
        "body": "type AgentDefinition = {\n  description: string;        // When to use this agent\n  prompt: string;             // System prompt for agent\n  tools?: string[];           // Allowed tools (optional)\n  model?: 'sonnet' | 'opus' | 'haiku' | 'inherit';  // Model (optional)\n  skills?: string[];          // Skills to load (v0.2.10+)\n  maxTurns?: number;          // Maximum turns before stopping (v0.2.10+)\n}\n\nField Details:\n\ndescription: When to use agent (used by main agent for delegation)\nprompt: System prompt (defines role, inherits main context)\ntools: Allowed tools (if omitted, inherits from main agent)\nmodel: Model override (haiku/sonnet/opus/inherit)\nskills: Skills to load for agent (v0.2.10+)\nmaxTurns: Limit agent to N turns before returning control (v0.2.10+)\n\nUsage:\n\nagents: {\n  \"security-checker\": {\n    description: \"Security audits and vulnerability scanning\",\n    prompt: \"You check security. Scan for secrets, verify OWASP compliance.\",\n    tools: [\"Read\", \"Grep\", \"Bash\"],\n    model: \"sonnet\",\n    skills: [\"security-best-practices\"],  // Load specific skills\n    maxTurns: 10  // Limit to 10 turns\n  }\n}"
      },
      {
        "title": "⚠️ Subagent Cleanup Warning",
        "body": "Known Issue: Subagents don't stop when parent agent stops (Issue #132)\n\nWhen a parent agent is stopped (via cancellation or error), spawned subagents continue running as orphaned processes. This can lead to:\n\nResource leaks\nContinued tool execution after parent stopped\nRAM out-of-memory in recursive scenarios (Claude Code Issue #4850)\n\nWorkaround: Implement cleanup in Stop hooks:\n\nconst response = query({\n  prompt: \"Deploy to production\",\n  options: {\n    agents: {\n      \"deployer\": {\n        description: \"Handle deployments\",\n        prompt: \"Deploy the application\",\n        tools: [\"Bash\"]\n      }\n    },\n    hooks: {\n      Stop: async (input) => {\n        // Manual cleanup of spawned processes\n        console.log(\"Parent stopped - cleaning up subagents\");\n        // Implement process tracking and termination\n      }\n    }\n  }\n});\n\nEnhancement Tracking: Issue #142 proposes auto-termination"
      },
      {
        "title": "Session Management",
        "body": "Options:\n\nresume: sessionId - Continue previous session\nforkSession: true - Create new branch from session\ncontinue: prompt - Resume with new prompt (differs from resume)\n\nSession Forking Pattern (Unique Capability):\n\n// Explore alternative without modifying original\nconst forked = query({\n  prompt: \"Try GraphQL instead of REST\",\n  options: {\n    resume: sessionId,\n    forkSession: true  // Creates new branch, original session unchanged\n  }\n});\n\nCapture Session ID:\n\nfor await (const message of response) {\n  if (message.type === 'system' && message.subtype === 'init') {\n    sessionId = message.session_id;  // Save for later resume/fork\n  }\n}"
      },
      {
        "title": "V2 Session APIs (Preview - v0.1.54+)",
        "body": "Simpler multi-turn conversation pattern:\n\nimport {\n  unstable_v2_createSession,\n  unstable_v2_resumeSession,\n  unstable_v2_prompt\n} from \"@anthropic-ai/claude-agent-sdk\";\n\n// Create a new session\nconst session = await unstable_v2_createSession({\n  model: \"claude-sonnet-4-5\",\n  workingDirectory: process.cwd(),\n  allowedTools: [\"Read\", \"Grep\", \"Glob\"]\n});\n\n// Send prompts and stream responses\nconst stream = unstable_v2_prompt(session, \"Analyze the codebase structure\");\nfor await (const message of stream) {\n  console.log(message);\n}\n\n// Continue conversation in same session\nconst stream2 = unstable_v2_prompt(session, \"Now suggest improvements\");\nfor await (const message of stream2) {\n  console.log(message);\n}\n\n// Resume a previous session\nconst resumedSession = await unstable_v2_resumeSession(session.sessionId);\n\nNote: V2 APIs are in preview (unstable_ prefix). The .receive() method was renamed to .stream() in v0.1.72."
      },
      {
        "title": "Permission Control",
        "body": "Permission Modes:\n\ntype PermissionMode = \"default\" | \"acceptEdits\" | \"bypassPermissions\" | \"plan\";\n\ndefault - Standard permission checks\nacceptEdits - Auto-approve file edits\nbypassPermissions - Skip ALL checks (use in CI/CD only)\nplan - Planning mode (v0.1.45+)"
      },
      {
        "title": "Custom Permission Logic",
        "body": "const response = query({\n  prompt: \"Deploy application to production\",\n  options: {\n    permissionMode: \"default\",\n    canUseTool: async (toolName, input) => {\n      // Allow read-only operations\n      if (['Read', 'Grep', 'Glob'].includes(toolName)) {\n        return { behavior: \"allow\" };\n      }\n\n      // Deny destructive bash commands\n      if (toolName === 'Bash') {\n        const dangerous = ['rm -rf', 'dd if=', 'mkfs', '> /dev/'];\n        if (dangerous.some(pattern => input.command.includes(pattern))) {\n          return {\n            behavior: \"deny\",\n            message: \"Destructive command blocked for safety\"\n          };\n        }\n      }\n\n      // Require confirmation for deployments\n      if (input.command?.includes('deploy') || input.command?.includes('kubectl apply')) {\n        return {\n          behavior: \"ask\",\n          message: \"Confirm deployment to production?\"\n        };\n      }\n\n      // Allow by default\n      return { behavior: \"allow\" };\n    }\n  }\n});"
      },
      {
        "title": "canUseTool Callback",
        "body": "type CanUseToolCallback = (\n  toolName: string,\n  input: any\n) => Promise<PermissionDecision>;\n\ntype PermissionDecision =\n  | { behavior: \"allow\" }\n  | { behavior: \"deny\"; message?: string }\n  | { behavior: \"ask\"; message?: string };\n\nExamples:\n\n// Block all file writes\ncanUseTool: async (toolName, input) => {\n  if (toolName === 'Write' || toolName === 'Edit') {\n    return { behavior: \"deny\", message: \"No file modifications allowed\" };\n  }\n  return { behavior: \"allow\" };\n}\n\n// Require confirmation for specific files\ncanUseTool: async (toolName, input) => {\n  const sensitivePaths = ['/etc/', '/root/', '.env', 'credentials.json'];\n  if ((toolName === 'Write' || toolName === 'Edit') &&\n      sensitivePaths.some(path => input.file_path?.includes(path))) {\n    return {\n      behavior: \"ask\",\n      message: `Modify sensitive file ${input.file_path}?`\n    };\n  }\n  return { behavior: \"allow\" };\n}\n\n// Log all tool usage\ncanUseTool: async (toolName, input) => {\n  console.log(`Tool requested: ${toolName}`, input);\n  await logToDatabase(toolName, input);\n  return { behavior: \"allow\" };\n}"
      },
      {
        "title": "Sandbox Settings (Security-Critical)",
        "body": "Enable sandboxed execution for Bash commands:\n\nconst response = query({\n  prompt: \"Run system diagnostics\",\n  options: {\n    sandbox: {\n      enabled: true,\n      autoAllowBashIfSandboxed: true,  // Auto-approve bash in sandbox\n      excludedCommands: [\"rm\", \"dd\", \"mkfs\"],  // Never auto-approve these\n      allowUnsandboxedCommands: false  // Deny unsandboxable commands\n    }\n  }\n});"
      },
      {
        "title": "SandboxSettings Type",
        "body": "type SandboxSettings = {\n  enabled: boolean;\n  autoAllowBashIfSandboxed?: boolean;  // Default: false\n  excludedCommands?: string[];\n  allowUnsandboxedCommands?: boolean;  // Default: false\n  network?: NetworkSandboxSettings;\n  ignoreViolations?: SandboxIgnoreViolations;\n};\n\ntype NetworkSandboxSettings = {\n  enabled: boolean;\n  proxyUrl?: string;  // HTTP proxy for network requests\n};\n\nKey Options:\n\nenabled - Activate sandbox isolation\nautoAllowBashIfSandboxed - Skip permission prompts for safe bash commands\nexcludedCommands - Commands that always require permission\nallowUnsandboxedCommands - Allow commands that can't be sandboxed (risky)\nnetwork.proxyUrl - Route network through proxy for monitoring\n\nBest Practice: Always use sandbox in production agents handling untrusted input."
      },
      {
        "title": "File Checkpointing",
        "body": "Enable file state snapshots for rollback capability:\n\nconst response = query({\n  prompt: \"Refactor the authentication module\",\n  options: {\n    enableFileCheckpointing: true  // Enable file snapshots\n  }\n});\n\n// Later: rewind file changes to a specific point\nfor await (const message of response) {\n  if (message.type === 'user' && message.uuid) {\n    // Can rewind to this point later\n    const userMessageUuid = message.uuid;\n\n    // To rewind (call on Query object)\n    await response.rewindFiles(userMessageUuid);\n  }\n}\n\nUse cases:\n\nUndo failed refactoring attempts\nA/B test code changes\nSafe exploration of alternatives"
      },
      {
        "title": "Filesystem Settings",
        "body": "Setting Sources:\n\ntype SettingSource = 'user' | 'project' | 'local';\n\nuser - ~/.claude/settings.json (global)\nproject - .claude/settings.json (team-shared)\nlocal - .claude/settings.local.json (gitignored overrides)\n\nDefault: NO settings loaded (settingSources: [])"
      },
      {
        "title": "Settings Priority",
        "body": "When multiple sources loaded, settings merge in this order (highest priority first):\n\nProgrammatic options (passed to query()) - Always win\nLocal settings (.claude/settings.local.json)\nProject settings (.claude/settings.json)\nUser settings (~/.claude/settings.json)\n\nExample:\n\n// .claude/settings.json\n{\n  \"allowedTools\": [\"Read\", \"Write\", \"Edit\"]\n}\n\n// .claude/settings.local.json\n{\n  \"allowedTools\": [\"Read\"]  // Overrides project settings\n}\n\n// Programmatic\nconst response = query({\n  options: {\n    settingSources: [\"project\", \"local\"],\n    allowedTools: [\"Read\", \"Grep\"]  // ← This wins\n  }\n});\n\n// Actual allowedTools: [\"Read\", \"Grep\"]\n\nBest Practice: Use settingSources: [\"project\"] in CI/CD for consistent behavior."
      },
      {
        "title": "Query Object Methods",
        "body": "The query() function returns a Query object with these methods:\n\nconst q = query({ prompt: \"...\" });\n\n// Async iteration (primary usage)\nfor await (const message of q) { ... }\n\n// Runtime model control\nawait q.setModel(\"claude-opus-4-5\");           // Change model mid-session\nawait q.setMaxThinkingTokens(4096);            // Set thinking budget\n\n// Introspection\nconst models = await q.supportedModels();     // List available models\nconst commands = await q.supportedCommands(); // List available commands\nconst account = await q.accountInfo();        // Get account details\n\n// MCP status\nconst status = await q.mcpServerStatus();     // Check MCP server status\n// Returns: { [serverName]: { status: 'connected' | 'failed', error?: string } }\n\n// File operations (requires enableFileCheckpointing)\nawait q.rewindFiles(userMessageUuid);         // Rewind to checkpoint\n\nUse cases:\n\nDynamic model switching based on task complexity\nMonitoring MCP server health\nAdjusting thinking budget for reasoning tasks"
      },
      {
        "title": "Message Types & Streaming",
        "body": "Message Types:\n\nsystem - Session init/completion (includes session_id)\nassistant - Agent responses\ntool_call - Tool execution requests\ntool_result - Tool execution results\nerror - Error messages\nresult - Final result (includes structured_output for v0.1.45+)\n\nStreaming Pattern:\n\nfor await (const message of response) {\n  if (message.type === 'system' && message.subtype === 'init') {\n    sessionId = message.session_id;  // Capture for resume/fork\n  }\n  if (message.type === 'result' && message.structured_output) {\n    // Structured output available (v0.1.45+)\n    const validated = schema.parse(message.structured_output);\n  }\n}"
      },
      {
        "title": "Error Handling",
        "body": "Error Codes:\n\nError CodeCauseSolutionCLI_NOT_FOUNDClaude Code not installedInstall: npm install -g @anthropic-ai/claude-codeAUTHENTICATION_FAILEDInvalid API keyCheck ANTHROPIC_API_KEY env varRATE_LIMIT_EXCEEDEDToo many requestsImplement retry with backoffCONTEXT_LENGTH_EXCEEDEDPrompt too longUse session compaction, reduce contextPERMISSION_DENIEDTool blockedCheck permissionMode, canUseToolTOOL_EXECUTION_FAILEDTool errorCheck tool implementationSESSION_NOT_FOUNDInvalid session IDVerify session IDMCP_SERVER_FAILEDServer errorCheck server configuration"
      },
      {
        "title": "Known Issues Prevention",
        "body": "This skill prevents 14 documented issues:"
      },
      {
        "title": "Issue #1: CLI Not Found Error",
        "body": "Error: \"Claude Code CLI not installed\"\nSource: SDK requires Claude Code CLI\nWhy It Happens: CLI not installed globally\nPrevention: Install before using SDK: npm install -g @anthropic-ai/claude-code"
      },
      {
        "title": "Issue #2: Authentication Failed",
        "body": "Error: \"Invalid API key\"\nSource: Missing or incorrect ANTHROPIC_API_KEY\nWhy It Happens: Environment variable not set\nPrevention: Always set export ANTHROPIC_API_KEY=\"sk-ant-...\""
      },
      {
        "title": "Issue #3: Permission Denied Errors",
        "body": "Error: Tool execution blocked\nSource: permissionMode restrictions\nWhy It Happens: Tool not allowed by permissions\nPrevention: Use allowedTools or custom canUseTool callback"
      },
      {
        "title": "Issue #4: Context Length Exceeded (Session-Breaking)",
        "body": "Error: \"Prompt too long\"\nSource: Input exceeds model context window (Issue #138)\nWhy It Happens: Large codebase, long conversations\n\n⚠️ Critical Behavior: Once a session hits context limit:\n\nAll subsequent requests to that session return \"Prompt too long\"\n/compact command fails with same error\nSession is permanently broken and must be abandoned\n\nPrevention Strategies:\n\n// 1. Proactive session forking (create checkpoints before hitting limit)\nconst checkpoint = query({\n  prompt: \"Checkpoint current state\",\n  options: {\n    resume: sessionId,\n    forkSession: true  // Create branch before hitting limit\n  }\n});\n\n// 2. Monitor time and rotate sessions proactively\nconst MAX_SESSION_TIME = 80 * 60 * 1000;  // 80 minutes (before 90-min crash)\nlet sessionStartTime = Date.now();\n\nfunction shouldRotateSession() {\n  return Date.now() - sessionStartTime > MAX_SESSION_TIME;\n}\n\n// 3. Start new sessions before hitting context limits\nif (shouldRotateSession()) {\n  const summary = await getSummary(currentSession);\n  const newSession = query({\n    prompt: `Continue with context: ${summary}`\n  });\n  sessionStartTime = Date.now();\n}\n\nNote: SDK auto-compacts, but if limit is reached, session becomes unrecoverable"
      },
      {
        "title": "Issue #5: Tool Execution Timeout",
        "body": "Error: Tool doesn't respond\nSource: Long-running tool execution\nWhy It Happens: Tool takes too long (>5 minutes default)\nPrevention: Implement timeout handling in tool implementations"
      },
      {
        "title": "Issue #6: Session Not Found",
        "body": "Error: \"Invalid session ID\"\nSource: Session expired or invalid\nWhy It Happens: Session ID incorrect or too old\nPrevention: Capture session_id from system init message"
      },
      {
        "title": "Issue #7: MCP Server Connection Failed",
        "body": "Error: Server not responding\nSource: Server not running or misconfigured\nWhy It Happens: Command/URL incorrect, server crashed\nPrevention: Test MCP server independently, verify command/URL"
      },
      {
        "title": "Issue #8: Subagent Definition Errors",
        "body": "Error: Invalid AgentDefinition\nSource: Missing required fields\nWhy It Happens: description or prompt missing\nPrevention: Always include description and prompt fields"
      },
      {
        "title": "Issue #9: Settings File Not Found",
        "body": "Error: \"Cannot read settings\"\nSource: Settings file doesn't exist\nWhy It Happens: settingSources includes non-existent file\nPrevention: Check file exists before including in sources"
      },
      {
        "title": "Issue #10: Tool Name Collision",
        "body": "Error: Duplicate tool name\nSource: Multiple tools with same name\nWhy It Happens: Two MCP servers define same tool name\nPrevention: Use unique tool names, prefix with server name"
      },
      {
        "title": "Issue #11: Zod Schema Validation Error",
        "body": "Error: Invalid tool input\nSource: Input doesn't match Zod schema\nWhy It Happens: Agent provided wrong data type\nPrevention: Use descriptive Zod schemas with .describe()"
      },
      {
        "title": "Issue #12: Filesystem Permission Denied",
        "body": "Error: Cannot access path\nSource: Restricted filesystem access\nWhy It Happens: Path outside workingDirectory or no permissions\nPrevention: Set correct workingDirectory, check file permissions"
      },
      {
        "title": "Issue #13: MCP Server Config Missing type Field",
        "body": "Error: \"Claude Code process exited with code 1\" (cryptic, no context)\nSource: GitHub Issue #131\nWhy It Happens: URL-based MCP servers require explicit type: \"http\" or type: \"sse\" field\nPrevention: Always specify transport type for URL-based MCP servers\n\n// ❌ Wrong - missing type field (causes cryptic exit code 1)\nmcpServers: {\n  \"my-server\": {\n    url: \"https://api.example.com/mcp\"\n  }\n}\n\n// ✅ Correct - type field required for URL-based servers\nmcpServers: {\n  \"my-server\": {\n    url: \"https://api.example.com/mcp\",\n    type: \"http\"  // or \"sse\" for Server-Sent Events\n  }\n}\n\nDiagnostic Clue: If you see \"process exited with code 1\" with no other context, check your MCP server configuration for missing type fields."
      },
      {
        "title": "Issue #14: MCP Tool Result with Unicode Line Separators",
        "body": "Error: JSON parse error, agent hangs\nSource: GitHub Issue #137\nWhy It Happens: Unicode U+2028 (line separator) and U+2029 (paragraph separator) are valid in JSON but break JavaScript parsing\nPrevention: Escape these characters in MCP tool results\n\n// MCP tool handler - sanitize external data\ntool(\"fetch_content\", \"Fetch text content\", {}, async (args) => {\n  const content = await fetchExternalData();\n\n  // ✅ Sanitize Unicode line/paragraph separators\n  const sanitized = content\n    .replace(/\\u2028/g, '\\\\u2028')\n    .replace(/\\u2029/g, '\\\\u2029');\n\n  return {\n    content: [{ type: \"text\", text: sanitized }]\n  };\n});\n\nWhen This Matters: External data sources (APIs, web scraping, user input) that may contain these characters\n\nRelated: MCP Python SDK Issue #1356"
      },
      {
        "title": "Official Documentation",
        "body": "Agent SDK Overview: https://platform.claude.com/docs/en/api/agent-sdk/overview\nTypeScript API: https://platform.claude.com/docs/en/api/agent-sdk/typescript\nStructured Outputs: https://platform.claude.com/docs/en/agent-sdk/structured-outputs\nGitHub (TypeScript): https://github.com/anthropics/claude-agent-sdk-typescript\nCHANGELOG: https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md\n\nToken Efficiency:\n\nWithout skill: ~15,000 tokens (MCP setup, permission patterns, session APIs, sandbox config, hooks, structured outputs, error handling)\nWith skill: ~4,500 tokens (comprehensive v0.2.12 coverage + error prevention + advanced patterns)\nSavings: ~70% (~10,500 tokens)\n\nErrors prevented: 14 documented issues with exact solutions (including 2 community-sourced gotchas)\nKey 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\n\nLast 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"
      }
    ],
    "body": "Claude Agent SDK - Structured Outputs & Error Prevention Guide\n\nPackage: @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\n\nWhat's New in v0.1.45+ (Nov 2025)\n\nMajor Features:\n\n1. Structured Outputs (v0.1.45, Nov 14, 2025)\nJSON schema validation - Guarantees responses match exact schemas\noutputFormat parameter - Define output structure with JSON schema or Zod\nAccess validated results - Via message.structured_output\nBeta header required: structured-outputs-2025-11-13\nType safety - Full TypeScript inference with Zod schemas\n\nExample:\n\nimport { query } from \"@anthropic-ai/claude-agent-sdk\";\nimport { z } from \"zod\";\nimport { zodToJsonSchema } from \"zod-to-json-schema\";\n\nconst schema = z.object({\n  summary: z.string(),\n  sentiment: z.enum(['positive', 'neutral', 'negative']),\n  confidence: z.number().min(0).max(1)\n});\n\nconst response = query({\n  prompt: \"Analyze this code review feedback\",\n  options: {\n    model: \"claude-sonnet-4-5\",\n    outputFormat: {\n      type: \"json_schema\",\n      json_schema: {\n        name: \"AnalysisResult\",\n        strict: true,\n        schema: zodToJsonSchema(schema)\n      }\n    }\n  }\n});\n\nfor await (const message of response) {\n  if (message.type === 'result' && message.structured_output) {\n    // Guaranteed to match schema\n    const validated = schema.parse(message.structured_output);\n    console.log(`Sentiment: ${validated.sentiment}`);\n  }\n}\n\n\nZod 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.\n\n2. Plugins System (v0.1.27)\nplugins array - Load local plugin paths\nCustom plugin support - Extend agent capabilities\n3. Hooks System (v0.1.0+)\n\nAll 12 Hook Events:\n\nHook\tWhen Fired\tUse Case\nPreToolUse\tBefore tool execution\tValidate, modify, or block tool calls\nPostToolUse\tAfter tool execution\tLog results, trigger side effects\nNotification\tAgent notifications\tDisplay status updates\nUserPromptSubmit\tUser prompt received\tPre-process or validate input\nSubagentStart\tSubagent spawned\tTrack delegation, log context\nSubagentStop\tSubagent completed\tAggregate results, cleanup\nPreCompact\tBefore context compaction\tSave state before truncation\nPermissionRequest\tPermission needed\tCustom approval workflows\nStop\tAgent stopping\tCleanup, final logging\nSessionStart\tSession begins\tInitialize state\nSessionEnd\tSession ends\tPersist state, cleanup\nError\tError occurred\tCustom error handling\n\nHook Configuration:\n\nconst response = query({\n  prompt: \"...\",\n  options: {\n    hooks: {\n      PreToolUse: async (input) => {\n        console.log(`Tool: ${input.toolName}`);\n        return { allow: true };  // or { allow: false, message: \"...\" }\n      },\n      PostToolUse: async (input) => {\n        await logToolUsage(input.toolName, input.result);\n      }\n    }\n  }\n});\n\n4. Additional Options\nfallbackModel - Automatic model fallback on failures\nmaxThinkingTokens - Control extended thinking budget\nstrictMcpConfig - Strict MCP configuration validation\ncontinue - Resume with new prompt (differs from resume)\npermissionMode: 'plan' - New permission mode for planning workflows\n\n📚 Docs: https://platform.claude.com/docs/en/agent-sdk/structured-outputs\n\nThe Complete Claude Agent SDK Reference\nTable of Contents\nCore Query API\nTool Integration\nMCP Servers\nSubagent Orchestration\nSession Management\nPermission Control\nSandbox Settings\nFile Checkpointing\nFilesystem Settings\nQuery Object Methods\nMessage Types & Streaming\nError Handling\nKnown Issues\nCore Query API\n\nKey signature:\n\nquery(prompt: string | AsyncIterable<SDKUserMessage>, options?: Options)\n  -> AsyncGenerator<SDKMessage>\n\n\nCritical Options:\n\noutputFormat - Structured JSON schema validation (v0.1.45+)\nsettingSources - Filesystem settings loading ('user'|'project'|'local')\ncanUseTool - Custom permission logic callback\nagents - Programmatic subagent definitions\nmcpServers - MCP server configuration\npermissionMode - 'default'|'acceptEdits'|'bypassPermissions'|'plan'\nbetas - Enable beta features (e.g., 1M context window)\nsandbox - Sandbox settings for secure execution\nenableFileCheckpointing - Enable file state snapshots\nsystemPrompt - System prompt (string or preset object)\nExtended Context (1M Tokens)\n\nEnable 1 million token context window:\n\nconst response = query({\n  prompt: \"Analyze this large codebase\",\n  options: {\n    betas: ['context-1m-2025-08-07'],  // Enable 1M context\n    model: \"claude-sonnet-4-5\"\n  }\n});\n\nSystem Prompt Configuration\n\nTwo forms of systemPrompt:\n\n// 1. Simple string\nsystemPrompt: \"You are a helpful coding assistant.\"\n\n// 2. Preset with optional append (preserves Claude Code defaults)\nsystemPrompt: {\n  type: 'preset',\n  preset: 'claude_code',\n  append: \"\\n\\nAdditional context: Focus on security.\"\n}\n\n\nUse preset form when you want Claude Code's default behaviors plus custom additions.\n\nTool Integration (Built-in + Custom)\n\nTool Control:\n\nallowedTools - Whitelist (takes precedence)\ndisallowedTools - Blacklist\ncanUseTool - Custom permission callback (see Permission Control section)\n\nBuilt-in Tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, Task, NotebookEdit, BashOutput, KillBash, ListMcpResources, ReadMcpResource, AskUserQuestion\n\nAskUserQuestion Tool (v0.1.71+)\n\nEnable user interaction during agent execution:\n\nconst response = query({\n  prompt: \"Review and refactor the codebase\",\n  options: {\n    allowedTools: [\"Read\", \"Write\", \"Edit\", \"AskUserQuestion\"]\n  }\n});\n\n// Agent can now ask clarifying questions\n// Questions appear in message stream as tool_call with name \"AskUserQuestion\"\n\n\nUse cases:\n\nClarify ambiguous requirements mid-task\nGet user approval before destructive operations\nPresent options and get selection\nTools Configuration (v0.1.57+)\n\nThree forms of tool configuration:\n\n// 1. Exact allowlist (string array)\ntools: [\"Read\", \"Write\", \"Grep\"]\n\n// 2. Disable all tools (empty array)\ntools: []\n\n// 3. Preset with defaults (object form)\ntools: { type: 'preset', preset: 'claude_code' }\n\n\nNote: allowedTools and disallowedTools still work but tools provides more flexibility.\n\nMCP Servers (Model Context Protocol)\n\nServer Types:\n\nIn-process - createSdkMcpServer() with tool() definitions\nExternal - stdio, HTTP, SSE transport\n\nTool Definition:\n\ntool(name: string, description: string, zodSchema, handler)\n\n\nHandler Return:\n\n{ content: [{ type: \"text\", text: \"...\" }], isError?: boolean }\n\nExternal MCP Servers (stdio)\nconst response = query({\n  prompt: \"List files and analyze Git history\",\n  options: {\n    mcpServers: {\n      // Filesystem server\n      \"filesystem\": {\n        command: \"npx\",\n        args: [\"@modelcontextprotocol/server-filesystem\"],\n        env: {\n          ALLOWED_PATHS: \"/Users/developer/projects:/tmp\"\n        }\n      },\n      // Git operations server\n      \"git\": {\n        command: \"npx\",\n        args: [\"@modelcontextprotocol/server-git\"],\n        env: {\n          GIT_REPO_PATH: \"/Users/developer/projects/my-repo\"\n        }\n      }\n    },\n    allowedTools: [\n      \"mcp__filesystem__list_files\",\n      \"mcp__filesystem__read_file\",\n      \"mcp__git__log\",\n      \"mcp__git__diff\"\n    ]\n  }\n});\n\nExternal MCP Servers (HTTP/SSE)\nconst response = query({\n  prompt: \"Analyze data from remote service\",\n  options: {\n    mcpServers: {\n      \"remote-service\": {\n        url: \"https://api.example.com/mcp\",\n        headers: {\n          \"Authorization\": \"Bearer your-token-here\",\n          \"Content-Type\": \"application/json\"\n        }\n      }\n    },\n    allowedTools: [\"mcp__remote-service__analyze\"]\n  }\n});\n\nMCP Tool Naming Convention\n\nFormat: mcp__<server-name>__<tool-name>\n\nCRITICAL:\n\nServer name and tool name MUST match configuration\nUse double underscores (__) as separators\nInclude in allowedTools array\n\nExamples: mcp__weather-service__get_weather, mcp__filesystem__read_file\n\nSubagent Orchestration\nAgentDefinition Type\ntype AgentDefinition = {\n  description: string;        // When to use this agent\n  prompt: string;             // System prompt for agent\n  tools?: string[];           // Allowed tools (optional)\n  model?: 'sonnet' | 'opus' | 'haiku' | 'inherit';  // Model (optional)\n  skills?: string[];          // Skills to load (v0.2.10+)\n  maxTurns?: number;          // Maximum turns before stopping (v0.2.10+)\n}\n\n\nField Details:\n\ndescription: When to use agent (used by main agent for delegation)\nprompt: System prompt (defines role, inherits main context)\ntools: Allowed tools (if omitted, inherits from main agent)\nmodel: Model override (haiku/sonnet/opus/inherit)\nskills: Skills to load for agent (v0.2.10+)\nmaxTurns: Limit agent to N turns before returning control (v0.2.10+)\n\nUsage:\n\nagents: {\n  \"security-checker\": {\n    description: \"Security audits and vulnerability scanning\",\n    prompt: \"You check security. Scan for secrets, verify OWASP compliance.\",\n    tools: [\"Read\", \"Grep\", \"Bash\"],\n    model: \"sonnet\",\n    skills: [\"security-best-practices\"],  // Load specific skills\n    maxTurns: 10  // Limit to 10 turns\n  }\n}\n\n⚠️ Subagent Cleanup Warning\n\nKnown Issue: Subagents don't stop when parent agent stops (Issue #132)\n\nWhen a parent agent is stopped (via cancellation or error), spawned subagents continue running as orphaned processes. This can lead to:\n\nResource leaks\nContinued tool execution after parent stopped\nRAM out-of-memory in recursive scenarios (Claude Code Issue #4850)\n\nWorkaround: Implement cleanup in Stop hooks:\n\nconst response = query({\n  prompt: \"Deploy to production\",\n  options: {\n    agents: {\n      \"deployer\": {\n        description: \"Handle deployments\",\n        prompt: \"Deploy the application\",\n        tools: [\"Bash\"]\n      }\n    },\n    hooks: {\n      Stop: async (input) => {\n        // Manual cleanup of spawned processes\n        console.log(\"Parent stopped - cleaning up subagents\");\n        // Implement process tracking and termination\n      }\n    }\n  }\n});\n\n\nEnhancement Tracking: Issue #142 proposes auto-termination\n\nSession Management\n\nOptions:\n\nresume: sessionId - Continue previous session\nforkSession: true - Create new branch from session\ncontinue: prompt - Resume with new prompt (differs from resume)\n\nSession Forking Pattern (Unique Capability):\n\n// Explore alternative without modifying original\nconst forked = query({\n  prompt: \"Try GraphQL instead of REST\",\n  options: {\n    resume: sessionId,\n    forkSession: true  // Creates new branch, original session unchanged\n  }\n});\n\n\nCapture Session ID:\n\nfor await (const message of response) {\n  if (message.type === 'system' && message.subtype === 'init') {\n    sessionId = message.session_id;  // Save for later resume/fork\n  }\n}\n\nV2 Session APIs (Preview - v0.1.54+)\n\nSimpler multi-turn conversation pattern:\n\nimport {\n  unstable_v2_createSession,\n  unstable_v2_resumeSession,\n  unstable_v2_prompt\n} from \"@anthropic-ai/claude-agent-sdk\";\n\n// Create a new session\nconst session = await unstable_v2_createSession({\n  model: \"claude-sonnet-4-5\",\n  workingDirectory: process.cwd(),\n  allowedTools: [\"Read\", \"Grep\", \"Glob\"]\n});\n\n// Send prompts and stream responses\nconst stream = unstable_v2_prompt(session, \"Analyze the codebase structure\");\nfor await (const message of stream) {\n  console.log(message);\n}\n\n// Continue conversation in same session\nconst stream2 = unstable_v2_prompt(session, \"Now suggest improvements\");\nfor await (const message of stream2) {\n  console.log(message);\n}\n\n// Resume a previous session\nconst resumedSession = await unstable_v2_resumeSession(session.sessionId);\n\n\nNote: V2 APIs are in preview (unstable_ prefix). The .receive() method was renamed to .stream() in v0.1.72.\n\nPermission Control\n\nPermission Modes:\n\ntype PermissionMode = \"default\" | \"acceptEdits\" | \"bypassPermissions\" | \"plan\";\n\ndefault - Standard permission checks\nacceptEdits - Auto-approve file edits\nbypassPermissions - Skip ALL checks (use in CI/CD only)\nplan - Planning mode (v0.1.45+)\nCustom Permission Logic\nconst response = query({\n  prompt: \"Deploy application to production\",\n  options: {\n    permissionMode: \"default\",\n    canUseTool: async (toolName, input) => {\n      // Allow read-only operations\n      if (['Read', 'Grep', 'Glob'].includes(toolName)) {\n        return { behavior: \"allow\" };\n      }\n\n      // Deny destructive bash commands\n      if (toolName === 'Bash') {\n        const dangerous = ['rm -rf', 'dd if=', 'mkfs', '> /dev/'];\n        if (dangerous.some(pattern => input.command.includes(pattern))) {\n          return {\n            behavior: \"deny\",\n            message: \"Destructive command blocked for safety\"\n          };\n        }\n      }\n\n      // Require confirmation for deployments\n      if (input.command?.includes('deploy') || input.command?.includes('kubectl apply')) {\n        return {\n          behavior: \"ask\",\n          message: \"Confirm deployment to production?\"\n        };\n      }\n\n      // Allow by default\n      return { behavior: \"allow\" };\n    }\n  }\n});\n\ncanUseTool Callback\ntype CanUseToolCallback = (\n  toolName: string,\n  input: any\n) => Promise<PermissionDecision>;\n\ntype PermissionDecision =\n  | { behavior: \"allow\" }\n  | { behavior: \"deny\"; message?: string }\n  | { behavior: \"ask\"; message?: string };\n\n\nExamples:\n\n// Block all file writes\ncanUseTool: async (toolName, input) => {\n  if (toolName === 'Write' || toolName === 'Edit') {\n    return { behavior: \"deny\", message: \"No file modifications allowed\" };\n  }\n  return { behavior: \"allow\" };\n}\n\n// Require confirmation for specific files\ncanUseTool: async (toolName, input) => {\n  const sensitivePaths = ['/etc/', '/root/', '.env', 'credentials.json'];\n  if ((toolName === 'Write' || toolName === 'Edit') &&\n      sensitivePaths.some(path => input.file_path?.includes(path))) {\n    return {\n      behavior: \"ask\",\n      message: `Modify sensitive file ${input.file_path}?`\n    };\n  }\n  return { behavior: \"allow\" };\n}\n\n// Log all tool usage\ncanUseTool: async (toolName, input) => {\n  console.log(`Tool requested: ${toolName}`, input);\n  await logToDatabase(toolName, input);\n  return { behavior: \"allow\" };\n}\n\nSandbox Settings (Security-Critical)\n\nEnable sandboxed execution for Bash commands:\n\nconst response = query({\n  prompt: \"Run system diagnostics\",\n  options: {\n    sandbox: {\n      enabled: true,\n      autoAllowBashIfSandboxed: true,  // Auto-approve bash in sandbox\n      excludedCommands: [\"rm\", \"dd\", \"mkfs\"],  // Never auto-approve these\n      allowUnsandboxedCommands: false  // Deny unsandboxable commands\n    }\n  }\n});\n\nSandboxSettings Type\ntype SandboxSettings = {\n  enabled: boolean;\n  autoAllowBashIfSandboxed?: boolean;  // Default: false\n  excludedCommands?: string[];\n  allowUnsandboxedCommands?: boolean;  // Default: false\n  network?: NetworkSandboxSettings;\n  ignoreViolations?: SandboxIgnoreViolations;\n};\n\ntype NetworkSandboxSettings = {\n  enabled: boolean;\n  proxyUrl?: string;  // HTTP proxy for network requests\n};\n\n\nKey Options:\n\nenabled - Activate sandbox isolation\nautoAllowBashIfSandboxed - Skip permission prompts for safe bash commands\nexcludedCommands - Commands that always require permission\nallowUnsandboxedCommands - Allow commands that can't be sandboxed (risky)\nnetwork.proxyUrl - Route network through proxy for monitoring\n\nBest Practice: Always use sandbox in production agents handling untrusted input.\n\nFile Checkpointing\n\nEnable file state snapshots for rollback capability:\n\nconst response = query({\n  prompt: \"Refactor the authentication module\",\n  options: {\n    enableFileCheckpointing: true  // Enable file snapshots\n  }\n});\n\n// Later: rewind file changes to a specific point\nfor await (const message of response) {\n  if (message.type === 'user' && message.uuid) {\n    // Can rewind to this point later\n    const userMessageUuid = message.uuid;\n\n    // To rewind (call on Query object)\n    await response.rewindFiles(userMessageUuid);\n  }\n}\n\n\nUse cases:\n\nUndo failed refactoring attempts\nA/B test code changes\nSafe exploration of alternatives\nFilesystem Settings\n\nSetting Sources:\n\ntype SettingSource = 'user' | 'project' | 'local';\n\nuser - ~/.claude/settings.json (global)\nproject - .claude/settings.json (team-shared)\nlocal - .claude/settings.local.json (gitignored overrides)\n\nDefault: NO settings loaded (settingSources: [])\n\nSettings Priority\n\nWhen multiple sources loaded, settings merge in this order (highest priority first):\n\nProgrammatic options (passed to query()) - Always win\nLocal settings (.claude/settings.local.json)\nProject settings (.claude/settings.json)\nUser settings (~/.claude/settings.json)\n\nExample:\n\n// .claude/settings.json\n{\n  \"allowedTools\": [\"Read\", \"Write\", \"Edit\"]\n}\n\n// .claude/settings.local.json\n{\n  \"allowedTools\": [\"Read\"]  // Overrides project settings\n}\n\n// Programmatic\nconst response = query({\n  options: {\n    settingSources: [\"project\", \"local\"],\n    allowedTools: [\"Read\", \"Grep\"]  // ← This wins\n  }\n});\n\n// Actual allowedTools: [\"Read\", \"Grep\"]\n\n\nBest Practice: Use settingSources: [\"project\"] in CI/CD for consistent behavior.\n\nQuery Object Methods\n\nThe query() function returns a Query object with these methods:\n\nconst q = query({ prompt: \"...\" });\n\n// Async iteration (primary usage)\nfor await (const message of q) { ... }\n\n// Runtime model control\nawait q.setModel(\"claude-opus-4-5\");           // Change model mid-session\nawait q.setMaxThinkingTokens(4096);            // Set thinking budget\n\n// Introspection\nconst models = await q.supportedModels();     // List available models\nconst commands = await q.supportedCommands(); // List available commands\nconst account = await q.accountInfo();        // Get account details\n\n// MCP status\nconst status = await q.mcpServerStatus();     // Check MCP server status\n// Returns: { [serverName]: { status: 'connected' | 'failed', error?: string } }\n\n// File operations (requires enableFileCheckpointing)\nawait q.rewindFiles(userMessageUuid);         // Rewind to checkpoint\n\n\nUse cases:\n\nDynamic model switching based on task complexity\nMonitoring MCP server health\nAdjusting thinking budget for reasoning tasks\nMessage Types & Streaming\n\nMessage Types:\n\nsystem - Session init/completion (includes session_id)\nassistant - Agent responses\ntool_call - Tool execution requests\ntool_result - Tool execution results\nerror - Error messages\nresult - Final result (includes structured_output for v0.1.45+)\n\nStreaming Pattern:\n\nfor await (const message of response) {\n  if (message.type === 'system' && message.subtype === 'init') {\n    sessionId = message.session_id;  // Capture for resume/fork\n  }\n  if (message.type === 'result' && message.structured_output) {\n    // Structured output available (v0.1.45+)\n    const validated = schema.parse(message.structured_output);\n  }\n}\n\nError Handling\n\nError Codes:\n\nError Code\tCause\tSolution\nCLI_NOT_FOUND\tClaude Code not installed\tInstall: npm install -g @anthropic-ai/claude-code\nAUTHENTICATION_FAILED\tInvalid API key\tCheck ANTHROPIC_API_KEY env var\nRATE_LIMIT_EXCEEDED\tToo many requests\tImplement retry with backoff\nCONTEXT_LENGTH_EXCEEDED\tPrompt too long\tUse session compaction, reduce context\nPERMISSION_DENIED\tTool blocked\tCheck permissionMode, canUseTool\nTOOL_EXECUTION_FAILED\tTool error\tCheck tool implementation\nSESSION_NOT_FOUND\tInvalid session ID\tVerify session ID\nMCP_SERVER_FAILED\tServer error\tCheck server configuration\nKnown Issues Prevention\n\nThis skill prevents 14 documented issues:\n\nIssue #1: CLI Not Found Error\n\nError: \"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\n\nIssue #2: Authentication Failed\n\nError: \"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-...\"\n\nIssue #3: Permission Denied Errors\n\nError: Tool execution blocked Source: permissionMode restrictions Why It Happens: Tool not allowed by permissions Prevention: Use allowedTools or custom canUseTool callback\n\nIssue #4: Context Length Exceeded (Session-Breaking)\n\nError: \"Prompt too long\" Source: Input exceeds model context window (Issue #138) Why It Happens: Large codebase, long conversations\n\n⚠️ Critical Behavior: Once a session hits context limit:\n\nAll subsequent requests to that session return \"Prompt too long\"\n/compact command fails with same error\nSession is permanently broken and must be abandoned\n\nPrevention Strategies:\n\n// 1. Proactive session forking (create checkpoints before hitting limit)\nconst checkpoint = query({\n  prompt: \"Checkpoint current state\",\n  options: {\n    resume: sessionId,\n    forkSession: true  // Create branch before hitting limit\n  }\n});\n\n// 2. Monitor time and rotate sessions proactively\nconst MAX_SESSION_TIME = 80 * 60 * 1000;  // 80 minutes (before 90-min crash)\nlet sessionStartTime = Date.now();\n\nfunction shouldRotateSession() {\n  return Date.now() - sessionStartTime > MAX_SESSION_TIME;\n}\n\n// 3. Start new sessions before hitting context limits\nif (shouldRotateSession()) {\n  const summary = await getSummary(currentSession);\n  const newSession = query({\n    prompt: `Continue with context: ${summary}`\n  });\n  sessionStartTime = Date.now();\n}\n\n\nNote: SDK auto-compacts, but if limit is reached, session becomes unrecoverable\n\nIssue #5: Tool Execution Timeout\n\nError: 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\n\nIssue #6: Session Not Found\n\nError: \"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\n\nIssue #7: MCP Server Connection Failed\n\nError: 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\n\nIssue #8: Subagent Definition Errors\n\nError: Invalid AgentDefinition Source: Missing required fields Why It Happens: description or prompt missing Prevention: Always include description and prompt fields\n\nIssue #9: Settings File Not Found\n\nError: \"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\n\nIssue #10: Tool Name Collision\n\nError: 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\n\nIssue #11: Zod Schema Validation Error\n\nError: 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()\n\nIssue #12: Filesystem Permission Denied\n\nError: Cannot access path Source: Restricted filesystem access Why It Happens: Path outside workingDirectory or no permissions Prevention: Set correct workingDirectory, check file permissions\n\nIssue #13: MCP Server Config Missing type Field\n\nError: \"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\n\n// ❌ Wrong - missing type field (causes cryptic exit code 1)\nmcpServers: {\n  \"my-server\": {\n    url: \"https://api.example.com/mcp\"\n  }\n}\n\n// ✅ Correct - type field required for URL-based servers\nmcpServers: {\n  \"my-server\": {\n    url: \"https://api.example.com/mcp\",\n    type: \"http\"  // or \"sse\" for Server-Sent Events\n  }\n}\n\n\nDiagnostic Clue: If you see \"process exited with code 1\" with no other context, check your MCP server configuration for missing type fields.\n\nIssue #14: MCP Tool Result with Unicode Line Separators\n\nError: 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\n\n// MCP tool handler - sanitize external data\ntool(\"fetch_content\", \"Fetch text content\", {}, async (args) => {\n  const content = await fetchExternalData();\n\n  // ✅ Sanitize Unicode line/paragraph separators\n  const sanitized = content\n    .replace(/\\u2028/g, '\\\\u2028')\n    .replace(/\\u2029/g, '\\\\u2029');\n\n  return {\n    content: [{ type: \"text\", text: sanitized }]\n  };\n});\n\n\nWhen This Matters: External data sources (APIs, web scraping, user input) that may contain these characters\n\nRelated: MCP Python SDK Issue #1356\n\nOfficial Documentation\nAgent SDK Overview: https://platform.claude.com/docs/en/api/agent-sdk/overview\nTypeScript API: https://platform.claude.com/docs/en/api/agent-sdk/typescript\nStructured Outputs: https://platform.claude.com/docs/en/agent-sdk/structured-outputs\nGitHub (TypeScript): https://github.com/anthropics/claude-agent-sdk-typescript\nCHANGELOG: https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md\n\nToken Efficiency:\n\nWithout skill: ~15,000 tokens (MCP setup, permission patterns, session APIs, sandbox config, hooks, structured outputs, error handling)\nWith skill: ~4,500 tokens (comprehensive v0.2.12 coverage + error prevention + advanced patterns)\nSavings: ~70% (~10,500 tokens)\n\nErrors 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\n\nLast 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"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/Veeramanikandanr48/claude-agent-sdk",
    "publisherUrl": "https://clawhub.ai/Veeramanikandanr48/claude-agent-sdk",
    "owner": "Veeramanikandanr48",
    "version": "0.1.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/claude-agent-sdk",
    "downloadUrl": "https://openagent3.xyz/downloads/claude-agent-sdk",
    "agentUrl": "https://openagent3.xyz/skills/claude-agent-sdk/agent",
    "manifestUrl": "https://openagent3.xyz/skills/claude-agent-sdk/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/claude-agent-sdk/agent.md"
  }
}