FJjhdZddlZddlZddlmZmZddlmZmZddl m Z m Z ddl m Z ddlmZe rdd lmZdd lmZmZmZmZmZmZmZmZGd d Zy) z3Claude SDK Client for interacting with Claude Code.N) AsyncIterable AsyncIterator)asdictreplace) TYPE_CHECKINGAny) Transport)CLIConnectionError)MaterializedResume)ClaudeAgentOptionsContextUsageResponse HookEvent HookMatcherMcpStatusResponseMessagePermissionMode ResultMessagec eZdZdZ d'dedzdedzfdZdeee e fdee e ee e fffdZ d(d e eee e fzdzddfd Zd e eee e fzdzd eee e fddfd Zdeefd Z d)d e eee e fzde ddfdZd*dZdeddfdZd(de dzddfdZde ddfdZde ddfdZde deddfdZde ddfdZdefdZde fdZ!dee e fdzfdZ"deefd Z#d*d!Z$d+d"Z%d#e d$e d%e defd&Z&y),ClaudeSDKClienta Client for bidirectional, interactive conversations with Claude Code. This client provides full control over the conversation flow with support for streaming, interrupts, and dynamic message sending. For simple one-shot queries, consider using the query() function instead. Key features: - **Bidirectional**: Send and receive messages at any time - **Stateful**: Maintains conversation context across messages - **Interactive**: Send follow-ups based on responses - **Control flow**: Support for interrupts and session management When to use ClaudeSDKClient: - Building chat interfaces or conversational UIs - Interactive debugging or exploration sessions - Multi-turn conversations with context - When you need to react to Claude's responses - Real-time applications with user input - When you need interrupt capabilities When to use query() instead: - Simple one-off questions - Batch processing of prompts - Fire-and-forget automation scripts - When all inputs are known upfront - Stateless operations See examples/streaming_mode.py for full examples of ClaudeSDKClient in different scenarios. Caveat: As of v0.0.20, you cannot use a ClaudeSDKClient instance across different async runtime contexts (e.g., different trio nurseries or asyncio task groups). The client internally maintains a persistent anyio task group for reading messages that remains active from connect() until disconnect(). This means you must complete all operations with the client within the same async context where it was connected. Ideally, this limitation should not exist. Noptions transportcb| t}||_||_d|_d|_d|_y)zInitialize Claude SDK client.N)r r_custom_transport _transport_query _materialized)selfrrs a/Users/ahmed/devFolder/claude-voice/.venv/lib/python3.12/site-packages/claude_agent_sdk/client.py__init__zClaudeSDKClient.__init__Cs6 ?(*G !*,0"& 8<hooksreturnc2i}|jD]\}}g||<|D]r}t|dr |jndt|dr |jngd}t|dr|j|j|d<||j |t|S)z4Convert HookMatcher format to internal Query format.matcherNr")r%r"timeout)itemshasattrr%r"r&append)rr"internal_hookseventmatchersr%internal_matchers r!_convert_hooks_to_internal_formatz1ClaudeSDKClient._convert_hooks_to_internal_formatQs;=${{}OE8$&N5 !#3:'92MwSW.5gw.GW]]R4 7I.7??3N29//$Y/u%,,-=>$ -r!promptcKddlm}ddlm}dtt t tffd}t|tr|n|}||j|j||jd{nd|_ |j||d{y7'7#t$r|jd{7wxYww)z2Connect to Claude with a prompt or message stream.r )materialize_resume_session)validate_session_store_optionsr#c KywNr5r!r _empty_streamz.ClaudeSDKClient.connect.._empty_streamls  sN)_internal.session_resumer1"_internal.session_store_validationr2rdictstrr isinstancerrrr_connect_inner BaseException disconnect)rr/r1r2r6 actual_prompts rconnectzClaudeSDKClient.connectcs IV ]4S>%B #-V]"C  't||4%%--T\\: : :  %%fm< < < ; =  //# # #  sHA7C 9B!: C B%B#B% C #B%%C CC  C r?c Kddlm}ddlm}m}ddlm}|jjrTt|tr td|jjr tdt|jd}n |j}|j|||j}|jr|j|_n||| |_|j j#d{i}|jj$r~t|jj$t&rZ|jj$j)D]3\} } t| t&s| j+d d k(s,| d || <5t-t.j0j+d d} t3| dz d} d} |jj4}t|t&r7|j+d dk(r#|j+d}t|t6r|} d}|jj8ri|jj8j)D cic]6\} }| t;|j)Dcic] \}}| || c}}8}}}} }||j d|jj|jj<r%|j?|jj<nd|| || |jj@ |_!|jjD|jBdtFdtddffd }|jBjI||jjD|j|jjJ||jjL|jBjOd{|jBjQd{t|trDdd|dddd}|j jStUjV|dzd{y|Ft|tXr5|jBj[|jBj]|yyy7cc}}wcc}}}} w777cw)Nr )Query)apply_materialized_optionsbuild_mirror_batcher)SubprocessCLITransportzmcan_use_tool callback requires streaming mode. Please provide prompt as an AsyncIterable instead of a string.zccan_use_tool callback cannot be used with permission_prompt_tool_name. Please use one or the other.stdio)permission_prompt_tool_name)r/rtypesdkinstance CLAUDE_CODE_STREAM_CLOSE_TIMEOUT60000g@@gN@presetexclude_dynamic_sectionsT) ris_streaming_mode can_use_toolr"sdk_mcp_serversinitialize_timeoutagentsrNskillskeyerrorr#c2Kj||ywr4)report_mirror_error)rUrVqs r_on_mirror_errorz8ClaudeSDKClient._connect_inner.._on_mirror_errors%%c51s)store materializedenvon_error flush_modeuserrolecontentdefaultrHmessageparent_tool_use_id session_id )/_internal.queryrBr7rCrD"_internal.transport.subprocess_clirErrPr;r: ValueErrorrGrrrrr@ mcp_serversr9r'getintosenvironmax system_promptboolrSrr"r.rTr session_storerset_transcript_mirror_batcherr]session_store_flushstart initializewritejsondumpsr spawn_task stream_input)rr/r?rBrCrDrErrQnameconfiginitialize_timeout_msrRrNspeds agents_dict agent_defkvrZrfrYs @rr<zClaudeSDKClient._connect_inners +  O << $ $&#& U ||77 3 dllPGllG    )0$:L:LMG  ! !"44DO4$DOoo%%''' << # # 4<<3K3KT(R $ 8 8 > > @ ffd+ 60Be0K,2:,>OD)!A !$ JJNN=w G! !!6!?F15 \\ ' ' b$ BFF6Nh$>&&34C#t$+.(9= <<  (,||':':'@'@'B'BOD)y(9(?(?(AS(A1Q]q!t(ASS'B  oo"22||!!889K9KL+1%=<<&&    << % % 1 A 2C 2 2 2 KK 5 5$,,44!%!3!3 ((-#||??  kk!!!kk$$&&& fc "$*v>&*' G //'' 7(;d(BC C C  Jv}$E KK " "4;;#;#;F#C D%F [ (:TJ "& Ds}C4S7R08A:S3SC"S*%R9  R3R3R9 %ES,S-!SSAS!S"AS3R9 9 SSScK|js tdddlm}|jj 23d{}||}||76yw)z!Receive all messages from Claude.$Not connected. Call connect() first.r ) parse_messageN)rr _internal.message_parserrreceive_messages)rrdatarfs rrz ClaudeSDKClient.receive_messagessQ{{$%KL L;++668 $#D)G"  8s,8AAAA AAAArhcK|jr |js tdt|trDdd|dd|d}|jj t j|dzd{y|23d{}d|vr||d<|jj t j|dzd{L7S7I7 6yw)z Send a new request in streaming mode. Args: prompt: Either a string message or an async iterable of message dictionaries session_id: Session identifier for the conversation rr`raNrerirh)rrr r;r:rzr{r|)rr/rhrfmsgs rqueryzClaudeSDKClient.querys{{$//$%KL L fc "$*v>&*( G //'' 7(;d(BC C C$ Dcs*(2C %oo++DJJsOd,BCCC D DD $sHA2C4C5C<CC C>CC C C CCcK|js td|jjd{y7w)z7Send interrupt signal (only works with streaming mode).rN)rr interruptrs rrzClaudeSDKClient.interrupt9s/{{$%KL Lkk##%%%s 5?=?modecK|js td|jj|d{y7w)aChange permission mode during conversation (only works with streaming mode). Args: mode: The permission mode to set. Valid options: - 'default': CLI prompts for dangerous tools - 'acceptEdits': Auto-accept file edits - 'plan': Plan-only mode (no tool execution) - 'bypassPermissions': Allow all tools (use with caution) - 'dontAsk': Deny anything not pre-approved by allow rules - 'auto': A model classifier approves or denies each tool call Example: ```python async with ClaudeSDKClient() as client: # Start with default permissions await client.query("Help me analyze this codebase") # Review mode done, switch to auto-accept edits await client.set_permission_mode('acceptEdits') await client.query("Now implement the fix we discussed") ``` rN)rr set_permission_mode)rrs rrz#ClaudeSDKClient.set_permission_mode?s3.{{$%KL Lkk--d3336A>AmodelcK|js td|jj|d{y7w)aChange the AI model during conversation (only works with streaming mode). Args: model: The model to use, or None to use default. Examples: - 'claude-sonnet-4-5' - 'claude-opus-4-1-20250805' - 'claude-opus-4-20250514' Example: ```python async with ClaudeSDKClient() as client: # Start with default model await client.query("Help me understand this problem") # Switch to a different model for implementation await client.set_model('claude-sonnet-4-5') await client.query("Now implement the solution") ``` rN)rr set_model)rrs rrzClaudeSDKClient.set_modelZs3({{$%KL Lkk##E***ruser_message_idcK|js td|jj|d{y7w)alRewind tracked files to their state at a specific user message. Requires: - `enable_file_checkpointing=True` to track file changes - `extra_args={"replay-user-messages": None}` to receive UserMessage objects with `uuid` in the response stream Args: user_message_id: UUID of the user message to rewind to. This should be the `uuid` field from a `UserMessage` received during the conversation. Example: ```python options = ClaudeAgentOptions( enable_file_checkpointing=True, extra_args={"replay-user-messages": None}, ) async with ClaudeSDKClient(options) as client: await client.query("Make some changes to my files") async for msg in client.receive_response(): if isinstance(msg, UserMessage) and msg.uuid: checkpoint_id = msg.uuid # Save this for later # Later, rewind to that point await client.rewind_files(checkpoint_id) ``` rN)rr rewind_files)rrs rrzClaudeSDKClient.rewind_filesrs38{{$%KL Lkk&&777r server_namecK|js td|jj|d{y7w)aReconnect a disconnected or failed MCP server (only works with streaming mode). Use this to retry connecting to an MCP server that failed to connect or was disconnected. Raises an exception if the reconnection fails. Args: server_name: The name of the MCP server to reconnect Example: ```python async with ClaudeSDKClient(options) as client: status = await client.get_mcp_status() for server in status.get("mcpServers", []): if server["status"] == "failed": await client.reconnect_mcp_server(server["name"]) ``` rN)rr reconnect_mcp_server)rrs rrz$ClaudeSDKClient.reconnect_mcp_servers3${{$%KL Lkk..{;;;renabledcK|js td|jj||d{y7w)aVEnable or disable an MCP server (only works with streaming mode). Disabling a server disconnects it and removes its tools from the available tool set. Enabling a server reconnects it and makes its tools available again. Raises an exception on failure. Args: server_name: The name of the MCP server to toggle enabled: True to enable the server, False to disable it Example: ```python async with ClaudeSDKClient(options) as client: # Temporarily disable a server await client.toggle_mcp_server("my-server", enabled=False) await client.query("Do something without my-server tools") # Re-enable it later await client.toggle_mcp_server("my-server", enabled=True) ``` rN)rr toggle_mcp_server)rrrs rrz!ClaudeSDKClient.toggle_mcp_servers5,{{$%KL Lkk++KAAAs7A?Atask_idcK|js td|jj|d{y7w)aStop a running task (only works with streaming mode). After this resolves, a `task_notification` system message with status `'stopped'` will be emitted by the CLI in the message stream. Args: task_id: The task ID from `task_notification` events. Example: ```python async with ClaudeSDKClient() as client: await client.query("Start a long-running task") # Listen for task_notification to get task_id, then: await client.stop_task("task-abc123") # A task_notification with status 'stopped' will follow ``` rN)rr stop_task)rrs rrzClaudeSDKClient.stop_tasks3&{{$%KL Lkk##G,,,rcK|js td|jjd{}|S7w)aGet current MCP server connection status (only works with streaming mode). Queries the Claude Code CLI for the live connection status of all configured MCP servers. Returns: McpStatusResponse dictionary with an 'mcpServers' key containing a list of McpServerStatus entries. Each entry includes: - 'name': Server name (str) - 'status': Connection status ('connected', 'pending', 'failed', 'needs-auth', 'disabled') - 'serverInfo': MCP server name/version (when connected) - 'error': Error message (when status is 'failed') - 'config': Server configuration (stdio/sse/http/sdk/claudeai-proxy) - 'scope': Configuration scope (e.g., project, user, local) - 'tools': List of tools provided by the server (when connected) Example: ```python async with ClaudeSDKClient(options) as client: status = await client.get_mcp_status() for server in status["mcpServers"]: print(f"{server['name']}: {server['status']}") if server["status"] == "failed": print(f" Error: {server.get('error')}") ``` rN)rr get_mcp_statusrresults rrzClaudeSDKClient.get_mcp_statuss;8{{$%KL L*.++*D*D*F$F %G5A>AcK|js td|jjd{}|S7w)a3Get a breakdown of current context window usage by category. Returns the same data shown by the `/context` command in the CLI, including token counts per category, total usage, and detailed breakdowns of MCP tools, memory files, and agents. Returns: ContextUsageResponse dictionary with keys including: - 'categories': List of categories with name, tokens, color - 'totalTokens': Total tokens in context - 'maxTokens': Effective context limit - 'percentage': Percent of context used (0-100) - 'model': Model the usage is calculated for - 'mcpTools': Per-tool token breakdown for MCP servers - 'memoryFiles': Per-file token breakdown for CLAUDE.md files - 'agents': Per-agent token breakdown Example: ```python async with ClaudeSDKClient() as client: await client.query("Read this file") async for _ in client.receive_response(): pass usage = await client.get_context_usage() print(f"Using {usage['percentage']:.1f}% of context") for cat in usage['categories']: print(f" {cat['name']}: {cat['tokens']} tokens") ``` rN)rr get_context_usagers rrz!ClaudeSDKClient.get_context_usages;>{{$%KL L-1[[-J-J-L'L (MrcfK|js tdt|jddSw)aGet server initialization info including available commands and output styles. Returns initialization information from the Claude Code server including: - Available commands (slash commands, system commands, etc.) - Current and available output styles - Server capabilities Returns: Dictionary with server info, or None if not in streaming mode Example: ```python async with ClaudeSDKClient() as client: info = await client.get_server_info() if info: print(f"Commands available: {len(info.get('commands', []))}") print(f"Output style: {info.get('output_style', 'default')}") ``` r_initialization_resultN)rr getattrrs rget_server_infozClaudeSDKClient.get_server_infos/({{$%KL Lt{{$zClaudeSDKClient.disconnect`s} ;;++##% % % KK , , .DK    )$$,,. . .!%D  * & /s"*BBABBBBcBK|jd{|S7w)zSEnter async context - automatically connects with empty stream for interactive use.N)r@rs r __aenter__zClaudeSDKClient.__aenter__kslln  s exc_typeexc_valexc_tbc@K|jd{y7w)z(Exit async context - always disconnects.NF)r>)rrrrs r __aexit__zClaudeSDKClient.__aexit__psoo s )NNr4)rd)r#N)r#r)'__name__ __module__ __qualname____doc__r r r r9rlistrr:rr.rr@r<rrrrrrrrrrrtrrrrrrrrr>rrr5r!rrrs4&T.2&* =#d* =t# =)T+%667 c4S#X'' (&DH.M$sCx.99D@. .`zEmDcN33d:zE%T#s(^4zE  zEx  g(> NWDM$sCx.99DGJD D<& 4n446+S4Z+4+08#8$8@'R & c34r!r)rr{rpcollections.abcrr dataclassesrrtypingrrr _errorsr r7r typesr rrrrrrrrr5r!rrs>9 8'%'<   Y Y r!