467| `rewind_files(user_message_id)` | Restore files to their state at the specified user message. Requires `enable_file_checkpointing=True`. See [File checkpointing](/docs/en/agent-sdk/file-checkpointing) |467| `rewind_files(user_message_id)` | Restore files to their state at the specified user message. Requires `enable_file_checkpointing=True`. See [File checkpointing](/docs/en/agent-sdk/file-checkpointing) |
468| `get_mcp_status()` | Get the status of all configured MCP servers. Returns [`McpStatusResponse`](#mcpstatusresponse) |468| `get_mcp_status()` | Get the status of all configured MCP servers. Returns [`McpStatusResponse`](#mcpstatusresponse) |
469| `reconnect_mcp_server(server_name)` | Retry connecting to an MCP server that failed or was disconnected |469| `reconnect_mcp_server(server_name)` | Retry connecting to an MCP server that failed or was disconnected |
470| `toggle_mcp_server(server_name, enabled)` | Enable or disable an MCP server mid-session. Disabling removes its tools |470| `toggle_mcp_server(server_name, enabled)` | Enable or disable an MCP server mid-session. Disabling a stdio, SSE, or HTTP server removes its tools |
471| `stop_task(task_id)` | Stop a running background task. A [`TaskNotificationMessage`](#tasknotificationmessage) with status `"stopped"` follows in the message stream |471| `stop_task(task_id)` | Stop a running background task. A [`TaskNotificationMessage`](#tasknotificationmessage) with status `"stopped"` follows in the message stream |
472| `get_server_info()` | Get the server's initialization info, including available commands and output styles |472| `get_server_info()` | Get the server's initialization info, including available commands and output styles |
473| `disconnect()` | Disconnect from Claude |473| `disconnect()` | Disconnect from Claude |
536 536
537#### Example - Streaming input with ClaudeSDKClient537#### Example - Streaming input with ClaudeSDKClient
538 538
539`query()` also accepts an async iterable of user message dicts, so you can assemble the prompt at send time or include content blocks such as images. Claude Code starts responding to the first yielded message as soon as it arrives, without waiting for the iterable to finish, and `receive_response()` stops at the `ResultMessage` that ends that response. Put everything Claude should read before answering into one message, as this generator does, and pair each `query()` call with its own `receive_response()` loop.
540
539```python theme={null}541```python theme={null}
540import asyncio542import asyncio
541from claude_agent_sdk import ClaudeSDKClient543from claude_agent_sdk import ClaudeSDKClient
542 544
543 545
544async def message_stream():546async def message_stream():
545 """Generate messages dynamically."""547 """Assemble the prompt at send time and yield it as one user message."""
546 yield {548 readings = {"Temperature": "25°C", "Humidity": "60%"}
547 "type": "user",549 data = ", ".join(f"{name}: {value}" for name, value in readings.items())
548 "message": {"role": "user", "content": "Analyze the following data:"},
549 }
550 await asyncio.sleep(0.5)
551 yield {
552 "type": "user",
553 "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"},
554 }
555 await asyncio.sleep(0.5)
556 yield {550 yield {
557 "type": "user",551 "type": "user",
558 "message": {"role": "user", "content": "What patterns do you see?"},552 "message": {
553 "role": "user",
554 "content": f"Analyze the following sensor data and describe any patterns you see: {data}",
555 },
559 }556 }
560 557
561 558
2454 2451
2455Documentation of input/output schemas for all built-in Claude Code tools. While the Python SDK doesn't export these as types, they represent the structure of tool inputs and outputs in messages.2452Documentation of input/output schemas for all built-in Claude Code tools. While the Python SDK doesn't export these as types, they represent the structure of tool inputs and outputs in messages.
2456 2453
2454Each output shown is the value you read from [`UserMessage.tool_use_result`](#usermessage) for that tool. Key names appear exactly as Claude Code emits them. A key annotated `| None` with a "present when" or "optional" comment is omitted when it doesn't apply.
2455
2457### Agent2456### Agent
2458 2457
2459**Tool name:** `Agent`. The previous name `Task` is still accepted as an alias, and the `tools` list in the init [`SystemMessage`](#systemmessage) reports this tool as `Task` for backward compatibility.2458**Tool name:** `Agent`. The previous name `Task` is still accepted as an alias, and the `tools` list in the init [`SystemMessage`](#systemmessage) reports this tool as `Task` for backward compatibility.
2621 2620
2622**Tool name:** `Bash`2621**Tool name:** `Bash`
2623 2622
2624For what sets the foreground ceiling, see [Timeout and output limits](/docs/en/tools-reference#timeout-and-output-limits). For the background time limit, see [Background commands](/docs/en/tools-reference#background-commands).2623For what sets the foreground ceiling, see [Timeout and output limits](/docs/en/tools-reference#timeout-and-output-limits). For the background time limit, see [Time limit for background commands](/docs/en/tools-reference#time-limit-for-background-commands).
2625 2624
2626**Input:**2625**Input:**
2627 2626
2694 2693
2695```python theme={null}2694```python theme={null}
2696{2695{
2697 "message": str, # Confirmation message2696 "filePath": str, # The file that was edited
2698 "replacements": int, # Number of replacements made2697 "oldString": str, # The text that was replaced
2699 "file_path": str, # File path that was edited2698 "newString": str, # The text that replaced it
2699 "originalFile": str | None, # File contents before the edit
2700 "structuredPatch": [ # Diff hunks for the change
2701 {
2702 "oldStart": int,
2703 "oldLines": int,
2704 "newStart": int,
2705 "newLines": int,
2706 "lines": list[str],
2707 }
2708 ],
2709 "userModified": bool, # Whether the user changed the proposed edit before accepting it
2710 "replaceAll": bool, # Whether all occurrences were replaced
2711 "gitDiff": { # Optional git diff summary for the file
2712 "filename": str,
2713 "status": "modified" | "added",
2714 "additions": int,
2715 "deletions": int,
2716 "changes": int,
2717 "patch": str,
2718 "repository": str | None, # GitHub owner/repo when available
2719 } | None,
2700}2720}
2701```2721```
2702 2722
2714}2734}
2715```2735```
2716 2736
2717**Output (Text files):**2737The output takes one of the following shapes depending on what Claude read. Check the `type` key to tell them apart.
2738
2739**Output (type: `"text"`):**
2718 2740
2719```python theme={null}2741```python theme={null}
2720{2742{
2721 "content": str, # File contents with line numbers2743 "type": "text",
2722 "total_lines": int, # Total number of lines in file2744 "file": {
2723 "lines_returned": int, # Lines actually returned2745 "filePath": str, # The file that was read
2746 "content": str, # The returned content
2747 "numLines": int, # Number of lines in the returned content
2748 "startLine": int, # Line number the content starts at
2749 "totalLines": int, # Total number of lines in the file
2750 "truncatedByTokenCap": bool | None, # Present and True when a whole-file read exceeded the token cap and content is the first page
2751 },
2724}2752}
2725```2753```
2726 2754
2727**Output (Images):**2755**Output (type: `"image"`):**
2728 2756
2729```python theme={null}2757```python theme={null}
2730{2758{
2731 "image": str, # Base64 encoded image data2759 "type": "image",
2732 "mime_type": str, # Image MIME type2760 "file": {
2733 "file_size": int, # File size in bytes2761 "base64": str, # Base64-encoded image data
2762 "type": "image/jpeg" | "image/png" | "image/gif" | "image/webp", # Image MIME type
2763 "originalSize": int, # Original file size in bytes
2764 "dimensions": { # Optional sizing info for coordinate mapping
2765 "originalWidth": int | None, # Optional; original width in pixels
2766 "originalHeight": int | None, # Optional; original height in pixels
2767 "displayWidth": int | None, # Optional; width after resizing
2768 "displayHeight": int | None, # Optional; height after resizing
2769 } | None,
2770 },
2771}
2772```
2773
2774**Output (type: `"notebook"`):**
2775
2776```python theme={null}
2777{
2778 "type": "notebook",
2779 "file": {
2780 "filePath": str, # The notebook that was read
2781 "cells": list, # Notebook cells
2782 },
2783}
2784```
2785
2786**Output (type: `"pdf"`):**
2787
2788```python theme={null}
2789{
2790 "type": "pdf",
2791 "file": {
2792 "filePath": str, # The PDF that was read
2793 "base64": str, # Base64-encoded PDF data
2794 "originalSize": int, # File size in bytes
2795 },
2796}
2797```
2798
2799**Output (type: `"parts"`):**
2800
2801```python theme={null}
2802{
2803 "type": "parts",
2804 "file": {
2805 "filePath": str, # The PDF that was read
2806 "originalSize": int, # File size in bytes
2807 "count": int, # Number of pages extracted as images
2808 "outputDir": str, # Directory containing the extracted page images
2809 },
2810 "firstPage": int | None, # Optional document page number of the first extracted page
2811}
2812```
2813
2814**Output (type: `"file_unchanged"`):**
2815
2816```python theme={null}
2817{
2818 "type": "file_unchanged", # The file is unchanged since Claude last read it in this session, so the content isn't repeated
2819 "file": {
2820 "filePath": str,
2821 },
2822 "source": "seeded" | None, # Present when the earlier copy came from a CLAUDE.md or memory file loaded at startup rather than a Read call
2734}2823}
2735```2824```
2736 2825
2751 2840
2752```python theme={null}2841```python theme={null}
2753{2842{
2754 "message": str, # Success message2843 "type": "create" | "update", # Whether the write created a new file or overwrote an existing one
2755 "bytes_written": int, # Number of bytes written2844 "filePath": str, # The file that was written
2756 "file_path": str, # File path that was written2845 "content": str, # The content that was written
2846 "structuredPatch": [ # Diff hunks; empty for a new file, when nothing changed, or when Claude Code skipped the diff
2847 {
2848 "oldStart": int,
2849 "oldLines": int,
2850 "newStart": int,
2851 "newLines": int,
2852 "lines": list[str],
2853 }
2854 ],
2855 "originalFile": str | None, # Previous content; None for a new file or when the previous content was too large to include
2856 "gitDiff": { # Optional git diff summary for the file
2857 "filename": str,
2858 "status": "modified" | "added",
2859 "additions": int,
2860 "deletions": int,
2861 "changes": int,
2862 "patch": str,
2863 "repository": str | None, # GitHub owner/repo when available
2864 } | None,
2865 "userModified": bool | None, # Optional; whether the user edited the proposed content before accepting it
2757}2866}
2758```2867```
2759 2868
2774 2883
2775```python theme={null}2884```python theme={null}
2776{2885{
2777 "matches": list[str], # Array of matching file paths2886 "durationMs": int, # Time taken to run the search, in milliseconds
2778 "count": int, # Number of matches found2887 "numFiles": int, # Number of paths returned, after any truncation
2779 "search_path": str, # Search directory used2888 "filenames": list[str], # Matching file paths
2889 "truncated": bool, # Whether the results were truncated at the 100-file limit
2890 "totalMatches": int | None, # Optional total number of matching files before truncation; a lower bound when countIsComplete is False
2891 "countIsComplete": bool | None, # Optional; whether totalMatches is exact
2780}2892}
2781```2893```
2782 2894
2895`totalMatches` and `countIsComplete` require Claude Code v2.1.191 or later.
2896
2783### Grep2897### Grep
2784 2898
2785**Tool name:** `Grep`2899**Tool name:** `Grep`
2798 "-B": int | None, # Lines to show before each match2912 "-B": int | None, # Lines to show before each match
2799 "-A": int | None, # Lines to show after each match2913 "-A": int | None, # Lines to show after each match
2800 "-C": int | None, # Lines to show before and after2914 "-C": int | None, # Lines to show before and after
2915 "context": int | None, # Lines to show before and after; -C is an alias
2916 "-o": bool | None, # Print only the matched parts of each line
2801 "head_limit": int | None, # Limit output to first N lines/entries2917 "head_limit": int | None, # Limit output to first N lines/entries
2918 "offset": int | None, # Skip first N lines/entries before applying head_limit
2802 "multiline": bool | None, # Enable multiline mode2919 "multiline": bool | None, # Enable multiline mode
2803}2920}
2804```2921```
2805 2922
2806**Output (content mode):**2923**Output:**
2807 2924
2808```python theme={null}2925```python theme={null}
2809{2926{
2810 "matches": [2927 "mode": "content" | "files_with_matches" | "count" | None, # The output mode that was used
2811 {2928 "numFiles": int, # Number of files in the result; always 0 in content mode
2812 "file": str,2929 "filenames": list[str], # Matching files in files_with_matches mode; empty in the other modes
2813 "line_number": int | None,2930 "content": str | None, # Matching lines in content mode, or per-file counts in count mode
2814 "line": str,2931 "numLines": int | None, # Number of lines in content, present in content mode
2815 "before_context": list[str] | None,2932 "numMatches": int | None, # Total match count, present in count mode
2816 "after_context": list[str] | None,2933 "totalFiles": int | None, # Optional total before head_limit and offset, in files_with_matches mode
2817 }2934 "totalLines": int | None, # Optional total before head_limit and offset, in content mode
2818 ],2935 "appliedLimit": int | None, # Present when head_limit truncated the result
2819 "total_matches": int,2936 "appliedOffset": int | None, # Present when an offset was applied
2820}2937}
2821```2938```
2822 2939
2823**Output (files\_with\_matches mode):**2940Grep returns this dict shape in each output mode. Which optional keys are present depends on `output_mode`.
2824 2941
2825```python theme={null}2942`totalFiles` requires Claude Code v2.1.208 or later. `totalLines` requires Claude Code v2.1.210 or later.
2826{
2827 "files": list[str], # Files containing matches
2828 "count": int, # Number of files with matches
2829}
2830```
2831 2943
2832### NotebookEdit2944### NotebookEdit
2833 2945
2849 2961
2850```python theme={null}2962```python theme={null}
2851{2963{
2852 "message": str, # Success message2964 "new_source": str, # The source written to the cell
2853 "edit_type": "replaced" | "inserted" | "deleted", # Type of edit performed2965 "old_source": str | None, # Previous cell source, present for replace and delete
2854 "cell_id": str | None, # Cell ID that was affected2966 "cell_id": str | None, # ID of the edited cell, when available
2855 "total_cells": int, # Total cells in notebook after edit2967 "cell_type": "code" | "markdown", # The cell type
2968 "language": str, # The notebook's programming language
2969 "edit_mode": str, # The edit mode that was used
2970 "error": str | None, # Error message when the operation failed
2971 "notebook_path": str, # The notebook file
2972 "original_file": str, # Notebook content before the edit
2973 "updated_file": str, # Notebook content after the edit
2856}2974}
2857```2975```
2858 2976
2944 3062
2945```python theme={null}3063```python theme={null}
2946{3064{
2947 "message": str, # Success message3065 "oldTodos": [ # The todo list before the update
2948 "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},3066 {
3067 "content": str,
3068 "status": "pending" | "in_progress" | "completed",
3069 "activeForm": str,
3070 }
3071 ],
3072 "newTodos": [ # The todo list after the update
3073 {
3074 "content": str,
3075 "status": "pending" | "in_progress" | "completed",
3076 "activeForm": str,
3077 }
3078 ],
2949}3079}
2950```3080```
2951 3081
3103 3233
3104```python theme={null}3234```python theme={null}
3105{3235{
3106 "message": str, # Confirmation message3236 "plan": str | None, # The plan that was presented to the user
3107 "approved": bool | None, # Whether user approved the plan3237 "isAgent": bool, # True when a subagent called the tool
3238 "filePath": str | None, # Present when the plan was saved to a file
3239 "hasTaskTool": bool | None, # Optional; whether the Agent tool is available in the current context
3240 "planWasEdited": bool | None, # Present and True when the user edited the plan before approving
3241 "awaitingLeaderApproval": bool | None, # Present and True when a teammate sent the plan to the team lead for approval
3242 "requestId": str | None, # Optional ID of that approval request
3108}3243}
3109```3244```
3110 3245
3120}3255}
3121```3256```
3122 3257
3258The result is a list rather than a dict, so `tool_use_result` holds a `list` for this tool.
3259
3123**Output:**3260**Output:**
3124 3261
3125```python theme={null}3262```python theme={null}
3126{3263[ # One entry per resource
3127 "resources": [
3128 {3264 {
3129 "uri": str,3265 "uri": str, # Resource URI
3130 "name": str,3266 "name": str, # Resource name
3131 "description": str | None,3267 "mimeType": str | None, # Optional MIME type
3132 "mimeType": str | None,3268 "description": str | None, # Optional description
3133 "server": str,3269 "server": str, # Server that provides this resource
3134 }3270 }
3135 ],3271]
3136 "total": int,
3137}
3138```3272```
3139 3273
3140### ReadMcpResource3274### ReadMcpResource
3155```python theme={null}3289```python theme={null}
3156{3290{
3157 "contents": [3291 "contents": [
3158 {"uri": str, "mimeType": str | None, "text": str | None, "blob": str | None}3292 {
3293 "uri": str, # Resource URI
3294 "mimeType": str | None, # Optional MIME type
3295 "text": str | None, # Text content, or a note about the binary content
3296 "blobSavedTo": str | None, # Present when Claude Code saved binary content to disk; path of the saved file
3297 }
3159 ],3298 ],
3160 "server": str,3299 "error": str | None, # Present when the server couldn't read the resource
3161}3300}
3162```3301```
3163 3302
