# Agents Patterns All documentation for Agents Patterns. --- ## 00-the-one-liner-research-agent.md # Building a One-Liner Research Agent Research tasks consume hours of expert time: market analysts manually gathering competitive intelligence, legal teams tracking regulatory changes, engineers investigating bug reports across documentation. The core challenge isn\'t finding information but knowing what to search for next based on what you just discovered. The Claude Agent SDK makes it possible to build agents that autonomously explore external systems without a predefined workflow. Unlike traditional workflow automations that follow fixed steps, research agents adapt their strategy based on what they find\--following promising leads, synthesizing conflicting sources, and knowing when they have enough information to answer the question. ## By the end of this cookbook, you\'ll be able to: - Build a research agent that autonomously searches and synthesizes information with a few lines of code This foundation applies to any task where the information needed isn\'t available upfront: competitive analysis, technical troubleshooting, investment research, or literature reviews. # Why Research Agents? Research is an ideal agentic use case for two reasons: 1. **Information isn\'t self-contained**. The input question alone doesn\'t contain the answer. The agent must interact with external systems (search engines, databases, APIs) to gather what it needs. 2. **The path emerges during exploration**. You can\'t predetermine the workflow. Whether an agent should search for company financials or regulatory filings depends on what it discovers about the business model. The optimal strategy reveals itself through investigation. In its simplest form, a research agent searches the web and synthesizes findings. Below, we\'ll build exactly that with the Claude Agent SDK\'s built-in web search tool in just a few lines of code. Note: You can also view the full list of [Claude Code\'s built-in tools](https://docs.claude.com/en/docs/claude-code/settings#tools-available-to-claude) ::: ::: {#301fb086 .cell .markdown} # Prerequisites Before following this guide, ensure you have: **Required Knowledge** - Python fundamentals - comfortable with async/await, functions, and basic data structures - Basic understanding of agentic patterns - we recommend reading [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) first if you\'re new to agents **Required Tools** - Python 3.11 or higher - Anthropic API key [(get one here)](https://console.anthropic.com) **Recommended:** - Familiarity with the Claude Agent SDK concepts - Understanding of tool use patterns in LLMs ## Setup First, install the required dependencies: ::: ::: {#ab9830f9 .cell .code} ``` python %%capture %pip install -U claude-agent-sdk python-dotenv ``` ::: ::: {#d88272cf .cell .markdown} Note: Ensure your .env file contains: ``` bash ANTHROPIC_API_KEY=your_key_here ``` Load your environment variables and configure the client: ::: ::: {#c41abcdf .cell .code execution_count="2"} ``` python from dotenv import load_dotenv load_dotenv() MODEL = "claude-opus-4-5" ``` ::: ::: {#041415b8 .cell .markdown} ## Building Your First Research Agent Let\'s start with the simplest possible implementation: a research agent that can search the web and synthesize findings. With the Claude Agent SDK, this takes just a few lines of code. The key is the query() function, which creates a stateless agent interaction. We\'ll provide Claude with a single tool, WebSearch, and let it autonomously decide when and how to use it based on our research question. ::: :::: {#b00890fb .cell .code execution_count="3"} ``` python from utils.agent_visualizer import ( display_agent_response, print_activity, ) from claude_agent_sdk import ClaudeAgentOptions, query messages = [] async for msg in query( prompt="Research the latest trends in AI agents and give me a brief summary and relevant citiations links.", options=ClaudeAgentOptions(model=MODEL, allowed_tools=["WebSearch"]), ): print_activity(msg) messages.append(msg) ``` ::: {.output .stream .stdout} 🤖 Using: WebSearch() 🤖 Using: WebSearch() 🤖 Using: WebSearch() ✓ Tool completed ✓ Tool completed ✓ Tool completed 🤖 Thinking... ::: :::: :::: {#e4556936 .cell .code execution_count="4"} ``` python display_agent_response(messages) ``` ::: {.output .display_data}
Agent Response

Latest Trends in AI Agents (2025) - Summary

🚀 Market Growth & Adoption

The AI agent market is experiencing explosive growth, nearly doubling from $3.7 billion (2023) to $7.38 billion (2025), with projections reaching $103.6 billion by 2032. According to PwC's 2025 survey, 79% of organizations have adopted AI agents, with 88% of executives piloting or scaling autonomous agent systems.

🔑 Key Trends

1. Rise of Multi-Agent Systems
Instead of single AI systems trying to do everything, 2025 has introduced the "orchestra approach" where multiple specialized agents collaborate—one gathers research, another drafts reports, and a third reviews. Frameworks like CrewAI, AutoGen, and LangGraph are enabling this coordination across enterprise departments.

2. From Assistants to Autonomous Decision-Makers
AI agents are evolving from knowledge assistants to self-directed workers that can take initiative, make decisions, and complete multi-step tasks without constant human input. By 2029, 80% of customer service issues are expected to be resolved entirely by autonomous agents.

3. Model Context Protocol (MCP)
Anthropic's open standard provides a "USB-C for AI"—standardizing how language models connect with external systems, enabling structured multi-step workflows and access to real-time information.

4. Two-Speed Enterprise Landscape
A divide is emerging: companies with existing automation are racing ahead with agentic AI, while others watch from the sidelines. Among highly automated enterprises, 50% have either adopted or are preparing to adopt autonomous agents.

⚠️ Key Challenges

💼 Impact

Sources:

::: :::: ::: {#b965c2ee .cell .markdown} ## What\'s happening here: - `query()` creates a single-turn agent interaction (no conversation memory) - `allowed_tools=["WebSearch"]` gives Claude permission to search the web without asking for approval - The agent autonomously decides when to search, what queries to run, and how to synthesize results **Visualization utilities from `utils.agent_visualizer`:** - `print_activity()` - Shows the agent\'s actions in real-time (tool calls, thinking) - `display_agent_response()` - Renders the final response as a styled HTML card - `visualize_conversation()` - Creates a timeline view of the full conversation That\'s it! A functional research agent in just a few lines of code. The agent will search for relevant information, follow up on promising leads, and provide a synthesized summary with citations. ::: ::: {#6b888772 .cell .markdown} The query() function creates a stateless agent interaction. Each call is independent---no conversation memory, no context from previous queries. This makes it perfect for one-off research tasks where you need a quick answer without maintaining state. **How tool permissions work:** The `allowed_tools=["WebSearch"]` parameter gives Claude permission to search without asking for approval. This is critical for autonomous operation: - `Allowed tools` - Claude can use these freely (in this case, WebSearch) - `Other tools` - Available but require approval before use - `Read-only tools` - Tools like Read are always allowed by default - `Disallowed tools` - Add tools to disallowed_tools to remove them entirely from Claude\'s context **When to use stateless queries:** - One-off research questions where context doesn\'t matter - Parallel processing of independent research tasks - Scenarios where you want fresh context for each query **When not to use stateless queries:** - Multi-turn investigations that build on previous findings - Iterative refinement of research based on initial results - Complex analysis requiring sustained context Let\'s inspect what the agent actually did using the visualize_conversation helper: ::: :::: {#1d7c6d90 .cell .code execution_count="5"} ``` python from utils.agent_visualizer import visualize_conversation visualize_conversation(messages) ``` ::: {.output .display_data}
🤖 Agent Conversation Timeline • claude-opus-4-5
⚙️ System
Initialized (4e8497a9...)
🔧 Tools
WebSearch: "AI agents trends 2025 latest d..."WebSearch: "autonomous AI agents enterpris..."WebSearch: "multi-agent AI systems trends ..."
🤖 Assistant

Latest Trends in AI Agents (2025) - Summary

🚀 Market Growth & Adoption

The AI agent market is experiencing explosive growth, nearly doubling from $3.7 billion (2023) to $7.38 billion (2025), with projections reaching $103.6 billion by 2032. According to PwC's 2025 survey, 79% of organizations have adopted AI agents, with 88% of executives piloting or scaling autonomous agent systems.

🔑 Key Trends

1. Rise of Multi-Agent Systems
Instead of single AI systems trying to do everything, 2025 has introduced the "orchestra approach" where multiple specialized agents collaborate—one gathers research, another drafts reports, and a third reviews. Frameworks like CrewAI, AutoGen, and LangGraph are enabling this coordination across enterprise departments.

2. From Assistants to Autonomous Decision-Makers
AI agents are evolving from knowledge assistants to self-directed workers that can take initiative, make decisions, and complete multi-step tasks without constant human input. By 2029, 80% of customer service issues are expected to be resolved entirely by autonomous agents.

3. Model Context Protocol (MCP)
Anthropic's open standard provides a "USB-C for AI"—standardizing how language models connect with external systems, enabling structured multi-step workflows and access to real-time information.

4. Two-Speed Enterprise Landscape
A divide is emerging: companies with existing automation are racing ahead with agentic AI, while others watch from the sidelines. Among highly automated enterprises, 50% have either adopted or are preparing to adopt autonomous agents.

⚠️ Key Challenges

  • Integration with legacy systems (cited by ~60% of AI leaders)
  • Trust issues for high-stakes tasks like financial transactions
  • Enterprise readiness—organizations need to expose APIs and prepare infrastructure
  • Reliability concerns—agents can misinterpret instructions or fail on edge cases

💼 Impact

  • 66% of adopters report measurable productivity gains
  • Early movers are cutting operational costs by up to 40%
  • 75% of executives believe AI agents will reshape the workplace more than the internet did
  • 87% agree AI agents augment roles rather than replace them

Sources:

✅ Complete
Turns: 4 Tokens: 4,145 Cost: $0.51 Duration: 51.1s
::: :::: ::: {#22426729 .cell .markdown} ## From Prototype to Production: Three Key Improvements Our one-line research agent works, but it\'s limited. Single queries without memory can\'t handle iterative research (\"find X, then analyze Y based on what you found\"). Let\'s explore three ways we can further improve our implementation. **1. Conversation Memory with ClaudeSDKClient**: Stateless queries can\'t build on previous findings. If you ask \"What are the top AI startups?\" then \"How are they funded?\", the second query has no context about which startups you mean. We can use `ClaudeSDKClient` to maintain conversation history across multiple queries. **2. System Prompts for Specialized Behavior**: Research domains often have specific requirements. Financial analysis needs different rigor than tech news summaries. Use the system prompt to encode your research standards, preferred sources, citation format, or output structure. See our [agent prompting guide](https://github.com/anthropics/anthropic-cookbook/tree/main/patterns/agents/prompts) for research-specific examples. **3. Multimodal Research with the Read Tool**: Real research isn\'t just text. Market reports have charts, technical docs have diagrams, competitive analysis requires screenshot comparison. Enable the `Read` tool so Claude can analyze images, PDFs, and other visual content. Let\'s implement these three changes for our research agent. ::: :::: {#fa4c4d8f .cell .code execution_count="6"} ``` python from claude_agent_sdk import ClaudeSDKClient # System prompt with citation requirements for research quality RESEARCH_SYSTEM_PROMPT = """You are a research agent specialized in AI. When providing research findings: - Always include source URLs as citations - Format citations as markdown links: [Source Title](URL) - Group sources in a "Sources:" section at the end of your response""" messages = [] async with ClaudeSDKClient( options=ClaudeAgentOptions( model=MODEL, cwd="research_agent", system_prompt=RESEARCH_SYSTEM_PROMPT, allowed_tools=["WebSearch", "Read"], max_buffer_size=10 * 1024 * 1024, # Increase to 10MB for image handling ) ) as research_agent: # First query: Analyze the chart image await research_agent.query("Analyze the chart in research_agent/projects_claude.png") async for msg in research_agent.receive_response(): print_activity(msg) messages.append(msg) # Second query: Use web search to validate/contextualize the chart findings await research_agent.query( "Based on the chart analysis, search for recent news or data that validates or provides context for these findings. Include source URLs." ) async for msg in research_agent.receive_response(): print_activity(msg) messages.append(msg) ``` ::: {.output .stream .stdout} 🤖 Using: Read() ✓ Tool completed 🤖 Thinking... 🤖 Using: Glob() ✓ Tool completed 🤖 Thinking... 🤖 Using: Read() ✓ Tool completed 🤖 Thinking... 🤖 Using: WebSearch() 🤖 Using: WebSearch() 🤖 Using: WebSearch() 🤖 Using: WebSearch() ✓ Tool completed ✓ Tool completed ✓ Tool completed ✓ Tool completed 🤖 Thinking... ::: :::: ::: {#i4blqsetg8 .cell .markdown} ### 🔧 Handling Large Responses and Buffer Limits {#wrench-handling-large-responses-and-buffer-limits} When working with images or large data, you may encounter buffer overflow errors: Fatal error in message reader: Failed to decode JSON: JSON message exceeded maximum buffer size of 1048576 bytes **Why this happens:** - The default `max_buffer_size` is 1MB (1,048,576 bytes) - Images are base64-encoded in messages, significantly increasing size - The chart image (\~200KB on disk) becomes \~270KB+ when base64-encoded, plus message overhead **Solution:** Set `max_buffer_size` in `ClaudeAgentOptions` to a higher value (e.g., 10MB) when working with images or large tool outputs. **Best practices:** - Set buffer size based on your use case: 10MB for typical multimodal work, higher for large document processing - Consider if you really need to pass full images - sometimes descriptions or smaller thumbnails suffice - Monitor for buffer errors and adjust accordingly - Include citation requirements in your system prompt to ensure verifiable research outputs ::: ::: {#6eb4ed21 .cell .markdown} ## What\'s happening here: {#whats-happening-here} This example combines all three improvements: conversation memory, citation-aware system prompt, and multimodal analysis. **Key components:** ----------------------------------------------------------------------- Component Purpose --------------------------------------- ------------------------------- `ClaudeSDKClient` Maintains conversation state across multiple queries `RESEARCH_SYSTEM_PROMPT` Enforces citation formatting and source URLs `allowed_tools=["WebSearch", "Read"]` Enables web search and image/document analysis `max_buffer_size=10MB` Handles base64-encoded images without overflow ----------------------------------------------------------------------- **Execution flow:** 1. **First query** - Analyzes the chart image using the `Read` tool 2. **First response loop** - Collects all messages until the agent completes 3. **Second query** - Searches the web to validate/contextualize the chart findings 4. **Context inheritance** - The second query remembers the chart analysis from the first **Why `ClaudeSDKClient` vs `query()`:** The `async with ClaudeSDKClient()` context manager maintains conversation state. Each `receive_response()` call builds on previous context. This differs from `query()` which creates independent, stateless sessions. ::: :::: {#7971eae4-3ff1-48d8-99ef-fecca7332163 .cell .code execution_count="7"} ``` python visualize_conversation(messages) ``` ::: {.output .display_data}
🤖 Agent Conversation Timeline • claude-opus-4-5
⚙️ System
Initialized (9d494ab0...)
🔧 Tools
Read: projects_claude.png
🤖 Assistant

Let me search for the file in different locations:

🔧 Tools
Glob
🤖 Assistant

Found it. Let me read the image:

🔧 Tools
Read: projects_claude.png
🤖 Assistant

Analysis of the Chart: Types of Projects in Claude.ai and Claude Code

This is a dumbbell chart (also called a connected dot plot) that compares the prevalence of different project types between two Anthropic products: Claude.ai (blue dots) and Claude Code (orange dots).

Key Findings

1. Personal Projects Lead Both Platforms

  • Claude Code: 36.0%
  • Claude.ai: 30.2%
  • This is the most common use case for both platforms, with Claude Code having a slight edge (~6% higher).

2. Startup Work Shows the Largest Gap

  • Claude Code: 32.9%
  • Claude.ai: 13.1%
  • This represents the biggest difference between the two platforms (~20% gap), indicating Claude Code is heavily favored for startup development work.

3. Enterprise Work is Relatively Balanced

  • Claude.ai: 25.9%
  • Claude Code: 23.8%
  • Both platforms see similar usage for enterprise work, with Claude.ai slightly ahead (~2% difference).

4. Learning & Academic Use Favors Claude.ai

  • Tutorial or Learning: Claude.ai (12.2%) vs Claude Code (0.7%)
  • Academic Research: Claude.ai (11.9%) vs Claude Code (2.2%)
  • Coursework: Claude.ai (4.9%) vs Claude Code (0.4%)
  • These categories show Claude.ai is significantly more popular for educational purposes, likely due to its conversational interface being more accessible for learning.

5. Open Source Projects are Low for Both

  • Claude Code: 4.0%
  • Claude.ai: 1.8%
  • Neither platform sees heavy use for open source contributions, though Claude Code is used slightly more.

Insights & Interpretation

Pattern Implication
Claude Code dominates Startup Work Developers building products at startups prefer the code-focused interface for rapid development
Claude.ai leads in educational contexts The conversational nature of Claude.ai makes it more approachable for learning, research, and coursework
Personal Projects are universal Both platforms serve individual developers working on side projects equally well
Enterprise usage is balanced Both products have found their place in professional enterprise environments

Summary

The chart reveals clear product differentiation:
- Claude Code is preferred for active software development (startups, personal coding projects, open source)
- Claude.ai excels in knowledge work and learning (tutorials, academic research, coursework)

This aligns with the nature of each product—Claude Code is a development tool while Claude.ai is a general-purpose AI assistant with a broader conversational interface.

✅ Complete
Turns: 4 Tokens: 887 Cost: $0.07 Duration: 27.6s
⚙️ System
Initialized (9d494ab0...)
🔧 Tools
WebSearch: "Claude Code developer adoption..."WebSearch: "Claude AI education academic r..."WebSearch: "Anthropic Claude Code vs Claud..."WebSearch: "AI coding assistants startup d..."
🤖 Assistant

Validation & Context for Chart Findings

Based on my research, here's how recent news and data validate or provide context for the chart analysis:

1. ✅ Startup Dominance in Claude Code - VALIDATED

The chart showed Claude Code usage for Startup Work at 32.9% vs only 13.1% for Claude.ai—the largest gap in the data. Recent news strongly confirms this:

"Startups are the main early adopters of Claude Code, suggesting that smaller, agile businesses are leveraging this AI tool to gain a technological advantage." - Blockchain News

YC Startups as Case Studies:
- HumanLayer (F24) - Built their entire platform with Claude Code
- Ambral (W25) - Scaling AI-powered account management with sub-agent workflows
- Vulcan Technologies (S25) - Using Claude Code for regulatory complexity

As noted by Anthropic's blog: "Founders can now ship products directly from the terminal, compressing development cycles from weeks to hours."

2. ✅ Educational Use Favors Claude.ai - VALIDATED

The chart showed Claude.ai leading significantly in:
- Tutorial or Learning: 12.2% (vs 0.7% for Claude Code)
- Academic Research: 11.9% (vs 2.2%)
- Coursework: 4.9% (vs 0.4%)

This aligns perfectly with Anthropic's dedicated education initiatives:

Anthropic launched "Claude for Education" with features like "Learning Mode" that uses Socratic questioning rather than giving direct answers. - VentureBeat

Key Statistics from Anthropic's Education Report:
- 39.3% of student conversations involve creating and improving educational content
- 33.5% involve getting technical explanations for academic assignments
- 57% of higher ed instructor chats involved developing curricula
- 13% were conducting academic research

Early adopters include Northeastern University (50,000+ students across 13 campuses), London School of Economics, and Champlain College. - Anthropic Education Report

3. ✅ Coding/Development Dominance - VALIDATED

The chart showed Personal Projects and Startup Work (both development-heavy) as top uses for Claude Code (36% and 32.9%).

Anthropic's own research confirms:

"About 44% of API traffic involved coding, compared with 36% on Claude.ai." - Anthropic Economic Index

"Software development remains Claude's most common use case, making up more than a third of activity globally." - eWeek

4. ✅ Product Differentiation (Claude Code vs Claude.ai) - VALIDATED

The chart's overall pattern showing Claude Code for development and Claude.ai for knowledge work is confirmed by Fortune:

"ChatGPT is emerging increasingly as a personal or exploratory tool... while Claude is a more work-focused productivity tool, used heavily for coding, research, and business automation." - Fortune

Automation patterns differ by platform:
- 77% of API tasks are automated (full task delegation)
- ~50% of Claude.ai tasks are automated (more collaborative)

5. 📊 Broader AI Coding Assistant Context

The chart's findings fit into the larger industry trend:

Metric 2025 Data
AI-generated/assisted code 41% of all code globally
Developers using AI coding assistants 82% daily or weekly
Market size projection $30.1 billion by 2032
Google's AI-assisted code 25%

Source: AI Coding Assistant Statistics

6. ⚠️ Enterprise Work Balance - PARTIALLY EXPLAINED

The chart showed Enterprise Work relatively balanced (Claude.ai: 25.9%, Claude Code: 23.8%). This makes sense given:

  • 70-75% of Anthropic's revenue comes from enterprise API consumption
  • Enterprises use both products depending on use case
  • Security features like FedRAMP High certification drive enterprise adoption of both platforms

Summary

The chart's findings are strongly validated by recent data:

Chart Finding Validation Status
Startups prefer Claude Code (32.9% vs 13.1%) ✅ Confirmed by Anthropic & YC case studies
Education favors Claude.ai (12.2% vs 0.7%) ✅ Confirmed by Anthropic Education Report
Personal projects lead both platforms ✅ Confirmed by usage statistics
Claude Code = development tool ✅ Confirmed (44% API traffic is coding)
Claude.ai = knowledge/learning tool ✅ Confirmed by education initiatives

Sources

✅ Complete
Turns: 5 Tokens: 2,152 Cost: $0.76 Duration: 73.0s
::: :::: ::: {#38256581 .cell .markdown} ## Building for Production Jupyter notebooks are great for learning, but production systems need reusable modules. We\'ve packaged the research agent into `research_agent/agent.py` with a clean interface: ### Core functions: - `print_activity()` - Shows what the agent is doing in real-time (imported from shared utilities) - `get_activity_text()` - Extract activity text for custom handlers, such as logging or monitoring - `send_query()` - Main entry point for research queries with built-in activity display ### Built-in best practices: The module includes the `RESEARCH_SYSTEM_PROMPT` which ensures: - Source URLs are always included as citations - Citations are formatted as markdown links for clean rendering - A \"Sources:\" section groups all references ### Display control: The `send_query()` function has a `display_result` parameter (default: `True`): - `display_result=True` - Renders a styled HTML card in Jupyter notebooks - `display_result=False` - Returns only the text result for programmatic use This agent can now be used in any Python script! ::: ::: {#e220b5c7-463b-4171-b687-b1ec974958de .cell .markdown} For independent questions where conversation context doesn\'t matter. The module automatically handles: - Activity display during execution - Context reset for new conversations - Styled HTML rendering of the final response ::: ::::: {#3c2ca449-7a36-4b67-af47-fdb68fb3e36b .cell .code execution_count="8"} ``` python from research_agent.agent import send_query # The module handles activity display, context reset, and result visualization internally result = await send_query("What is the Claude Code SDK? Only do one websearch and be concise") ``` ::: {.output .stream .stdout} 🤖 Using: WebSearch() ✓ Tool completed 🤖 Thinking... ::: ::: {.output .display_data}
Agent Response

Claude Code SDK

The Claude Code SDK (now renamed to Claude Agent SDK) is a toolkit from Anthropic that allows developers to build AI agents using the same infrastructure that powers Claude Code.

Key capabilities:
- Context management - Automatic compaction to prevent running out of context
- Rich tool ecosystem - File operations, code execution, web search, MCP extensibility
- Fine-grained permissions - Control over agent capabilities
- Production features - Error handling, session management, monitoring

Available in:
- TypeScript (@anthropic-ai/claude-code)
- Python (pip install claude-code-sdk)
- Command line

It enables building agents for coding automation, customer support, personal assistants, and more—all using the same core systems that power Claude Code.

Sources:
- Agent SDK overview - Claude Docs
- Building agents with the Claude Agent SDK
- Anthropic Releases Claude Code SDK - InfoQ

::: ::::: ::: {#466155ec-9f54-49d4-83cb-00032b077147 .cell .markdown} Now we test out a multi-turn conversation that reuses the same conversation. Multi-turn conversations work seamlessly---just pass `continue_conversation=True`: ::: ::::: {#38ba1eda .cell .code execution_count="9"} ``` python result1 = await send_query("What is Anthropic? Only do one websearch and be concise") ``` ::: {.output .stream .stdout} 🤖 Using: WebSearch() ✓ Tool completed 🤖 Thinking... ::: ::: {.output .display_data}
Agent Response

Anthropic is an American AI safety company founded in 2021 by former OpenAI executives, including siblings Dario and Daniela Amodei. The company builds Claude, a family of large language models, with a focus on creating reliable, interpretable, and safe AI systems. Anthropic is valued at approximately $183 billion and has received major investments from Amazon, Google, Microsoft, and NVIDIA. Its Claude Code product recently reached $1 billion in run-rate revenue.

Sources:
- Anthropic - Wikipedia
- Anthropic Homepage
- What's Anthropic AI? - Voiceflow

::: ::::: ::::: {#36931a9e .cell .code execution_count="10"} ``` python # Continue the conversation to dig deeper by setting continue_conversation=True result2 = await send_query( "What are some of their products?", continue_conversation=True, ) ``` ::: {.output .stream .stdout} 🤖 Thinking... ::: ::: {.output .display_data}
Agent Response

Based on my previous search results, here are Anthropic's main products:

  1. Claude - Their flagship AI assistant and family of large language models, which incorporates "Constitutional AI" for safety. Named after mathematician Claude Shannon.

  2. Claude Code - A developer tool that recently reached $1 billion in run-rate revenue just six months after public launch.

  3. Bun - A JavaScript runtime that Anthropic recently acquired to accelerate Claude Code's capabilities.

Anthropic offers Claude through their website, API access for developers, and enterprise solutions.

Sources:
- Anthropic Homepage
- Anthropic acquires Bun as Claude Code reaches $1B milestone

::: ::::: ::: {#5344587c .cell .markdown} ## Conclusion ### What You Built In this cookbook, you built three progressively sophisticated research agents: - Stateless research agent - One-line queries for independent research tasks - Stateful agent with memory - Multi-turn investigations that build on previous findings - Production module - Reusable research functions for integration into applications ### Key Takeaways **When to use stateless queries (query()):** - Independent research questions - Parallel processing of unrelated tasks - Scenarios requiring fresh context each time **When to use stateful agents (ClaudeSDKClient):** - Multi-turn investigations building on previous findings - Iterative refinement of research - Complex analysis requiring sustained context Research agents excel when information isn\'t self-contained and the optimal workflow emerges during exploration---competitive analysis, technical troubleshooting, literature reviews, and investigative journalism all fit this pattern. ### Next Steps This foundation in autonomous research prepares you for enterprise-grade multi-agent systems. In the next notebook, you\'ll learn to: Orchestrate specialized subagents under a coordinating agent Implement governance through hooks and custom commands Adapt output styles for different stakeholders (executives vs. technical teams) Next: [01_The_chief_of_staff_agent.ipynb](01_The_chief_of_staff_agent.ipynb) - From single agents to multi-agent orchestration. ::: --- ## 01-the-chief-of-staff-agent.md from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient load_dotenv() # Define the model to use throughout this notebook # Using Opus 4.5 for its superior planning and reasoning capabilities MODEL = "claude-opus-4-5" print(f"📋 Notebook configured to use: {MODEL}") ``` ::: {.output .stream .stdout} 📋 Notebook configured to use: claude-opus-4-5 ::: :::: ::: {.cell .markdown} # 01 - The Chief of Staff Agent {#01---the-chief-of-staff-agent} #### Introduction In notebook 00, we built a simple research agent. In this notebook, we\'ll incrementally introduce key Claude Code SDK features for building comprehensive agents. For each introduced feature, we\'ll explain: - **What**: what the feature is - **Why**: what the feature can do and why you would want to use it - **How**: a minimal implementation showing how to use it If you are familiar with Claude Code, you\'ll notice how the SDK brings feature parity and enables you to leverage all of Claude Code\'s capabilities in a programmatic headless manner. #### Scenario Throughout this notebook, we\'ll build an **AI Chief of Staff** for a 50-person startup that just raised \$10M Series A. The CEO needs data-driven insights to balance aggressive growth with financial sustainability. Our final Chief of Staff agent will: - **Coordinate specialized subagents** for different domains - **Aggregate insights** from multiple sources - **Provide executive summaries** with actionable recommendations ::: ::: {.cell .markdown} ## Basic Features ::: ::: {.cell .markdown} ### Feature 0: Memory with [CLAUDE.md](https://www.anthropic.com/engineering/claude-code-best-practices) {#feature-0-memory-with-claudemd} **What**: `CLAUDE.md` files serve as persistent memory and instructions for your agent. When present in the project directory, Claude Code automatically reads and incorporates this context when you initialize your agent. **Why**: Instead of repeatedly providing project context, team preferences, or standards in each interaction, you can define them once in `CLAUDE.md`. This ensures consistent behavior and reduces token usage by avoiding redundant explanations. **How**: - Have a `CLAUDE.md` file in the working directory - in our example: `chief_of_staff_agent/CLAUDE.md` - Set the `cwd` argument of your ClaudeSDKClient to point to directory of your CLAUDE.md file - Use explicit prompts to guide the agent when you want it to prefer high-level context over detailed data files **Important Behavior Note**: When both CLAUDE.md and detailed data files (like CSVs) are available, the agent may prefer to read the more granular data sources to provide precise answers. This is expected behavior - agents naturally seek authoritative data. To ensure the agent uses high-level CLAUDE.md context, use explicit prompt instructions (see example below). This teaches an important lesson: CLAUDE.md provides *context and guidance*, not hard constraints on data sources. ::: ::::: {.cell .code execution_count="2"} ``` python messages = [] async with ClaudeSDKClient( options=ClaudeAgentOptions( model=MODEL, cwd="chief_of_staff_agent", # Points to subdirectory with our CLAUDE.md setting_sources=["project"], ) ) as agent: await agent.query("What's our current runway?") async for msg in agent.receive_response(): print_activity(msg) messages.append(msg) # Display the response with HTML rendering display_agent_response(messages) # With this prompt, the agent should use CLAUDE.md values: ~$500K burn, 20 months runway ``` ::: {.output .stream .stdout} 🤖 Thinking... ::: ::: {.output .display_data}
Agent Response

Based on the company information, TechStart Inc's current runway is 20 months (until September 2025).

Here are the key financial details:
- Cash in Bank: $10M
- Monthly Burn Rate: ~$500,000
- Runway: 20 months

This gives you a solid runway to execute on Q2 2024 priorities, including hiring 10 engineers, launching the AI code review feature, European expansion, and beginning Series B conversations (targeting $30M).

::: ::::: ::: {.cell .markdown} #### Understanding Agent Data Source Preferences **What Just Happened:** By adding to our prompt, we guided the agent to rely on the CLAUDE.md context rather than seeking more granular data from CSV files. **Key Insights:** 1. **CLAUDE.md as Context, Not Constraint**: When you set `cwd`, the CLAUDE.md file is loaded as background context. However, agents will naturally seek the most authoritative data sources available. If detailed CSV files exist, the agent may prefer them for precision. 2. **Prompt Engineering Matters**: The phrasing \"high-level financial numbers from context\" signals to the agent that you want the simplified executive summary from CLAUDE.md (\$500K burn, 20 months runway) rather than the precise month-by-month data from financial_data/burn_rate.csv (\$525K gross, \$235K net burn). 3. **Architectural Design Choice**: This behavior is actually desirable in production systems - you want agents to find the best data source. CLAUDE.md should contain: - High-level context and strategy - Company information and standards - Pointers to where detailed data lives - Guidelines on when to use high-level vs. detailed numbers 4. **Real-World Pattern**: Think of CLAUDE.md as an \"onboarding document\" that orients the agent, while detailed files are \"source systems\" the agent can query when precision matters. ::: ::: {.cell .markdown} ### Feature 1: The Bash tool for Python Script Execution **What**: The Bash tool allows your agent to (among other things) run Python scripts directly, enabling access to procedural knowledge, complex computations, data analysis and other integrations that go beyond the agent\'s native capabilities. **Why**: Our Chief of Staff might need to process data files, run financial models or generate visualizations based on this data. These are all good scenarios for using the Bash tool. **How**: Have your Python scripts set-up in a place where your agent can reach them and add some context on what they are and how they can be called. If the scripts are meant for your chief of staff agent, add this context to its CLAUDE.md file and if they are meant for one your subagents, add said context to their MD files (more details on this later). For this tutorial, we added five toy examples to `chief_of_staff_agent/scripts`: 1. `hiring_impact.py`: Calculates how new engineering hires affect burn rate, runway, and cash position. Essential for the `financial-analyst` subagent to model hiring scenarios against the \$500K monthly burn and 20-month runway. 2. `talent_scorer.py`: Scores candidates on technical skills, experience, culture fit, and salary expectations using weighted criteria. Core tool for the `recruiter` subagent to rank engineering candidates against TechStart\'s \$180-220K senior engineer benchmarks. 3. `simple_calculation.py`: Performs quick financial calculations for runway, burn rate, and quarterly metrics. Utility script for chief of staff to get instant metrics without complex modeling. 4. `financial_forecast.py`: Models ARR growth scenarios (base/optimistic/pessimistic) given the current \$2.4M ARR growing at 15% MoM.Critical for `financial-analyst` to project Series B readiness and validate the \$30M fundraising target. 5. `decision_matrix.py`: Creates weighted decision matrices for strategic choices like the SmartDev acquisition or office expansion. Helps chief of staff systematically evaluate complex decisions with multiple stakeholders and criteria. ::: ::::: {.cell .code execution_count="3"} ``` python messages = [] async with ClaudeSDKClient( options=ClaudeAgentOptions( model=MODEL, allowed_tools=["Bash", "Read"], cwd="chief_of_staff_agent", # Points to subdirectory where our agent is defined ) ) as agent: await agent.query( "Use your simple calculation script with a total runway of 2904829 and a monthly burn of 121938." ) async for msg in agent.receive_response(): print_activity(msg) messages.append(msg) # Display the response with HTML rendering display_agent_response(messages) ``` ::: {.output .stream .stdout} 🤖 Using: Glob() 🤖 Using: Glob() 🤖 Using: Glob() ✓ Tool completed ✓ Tool completed ✓ Tool completed 🤖 Thinking... 🤖 Using: Read() ✓ Tool completed 🤖 Thinking... 🤖 Using: Bash() ✓ Tool completed 🤖 Thinking... ::: ::: {.output .display_data}
Agent Response

Here are the financial metrics calculated using the simple calculation script:

Metric Value
Total Runway $2,904,829.00
Monthly Burn $121,938.00
Runway Months ~23.82 months
Quarterly Burn $365,814.00
Daily Burn Rate $4,064.60

Based on these calculations, with a total runway of $2,904,829 and a monthly burn rate of $121,938, you have approximately 23.8 months (just under 2 years) of runway remaining.

::: ::::: ::: {.cell .markdown} ### Feature 2: Output Styles **What**: Output styles allow you to use different output styles for different audiences. Each style is defined in a markdown file. **Why**: Your agent might be used by people of different levels of expertise or they might have different priorities. Your output style can help differentiate between these segments without having to create a separate agent. **How**: - Configure a markdown file per style in `chief_of_staff_agent/.claude/output-styles/`. For example, check out the Executive Ouput style in `.claude/output-styles/executive.md`. Output styles are defined with a simple frontmatter including two fields: name and description. Note: Make sure the name in the frontmatter matches exactly the file\'s name (case sensitive) > **IMPORTANT**: Output styles modify the system prompt that Claude Code > has underneath, leaving out the parts focused on software engineering > and giving you more control for your specific use case beyond software > engineering work. > **SDK CONFIGURATION NOTE**: Similar to slash commands (covered in > Feature 4), output styles are stored on the filesystem in > `.claude/output-styles/`. For the SDK to load these files, you > **must** include `setting_sources=["project"]` in your > `ClaudeAgentOptions`. The `settings` parameter tells the SDK *which* > style to use, but `setting_sources` is required to actually *load* the > style definitions. This requirement was identified while debugging > later sections and applies to all filesystem-based settings. ::: :::: {.cell .code execution_count="4"} ``` python messages_executive = [] async with ClaudeSDKClient( options=ClaudeAgentOptions( model=MODEL, cwd="chief_of_staff_agent", settings='{"outputStyle": "executive"}', # IMPORTANT: setting_sources must include "project" to load output styles from .claude/output-styles/ # Without this, the SDK does NOT load filesystem settings (output styles, slash commands, etc.) setting_sources=["project"], ) ) as agent: await agent.query("Tell me in two sentences about your writing output style.") async for msg in agent.receive_response(): print_activity(msg) messages_executive.append(msg) messages_technical = [] async with ClaudeSDKClient( options=ClaudeAgentOptions( model=MODEL, cwd="chief_of_staff_agent", settings='{"outputStyle": "technical"}', setting_sources=["project"], ) ) as agent: await agent.query("Tell me in two sentences about your writing output style.") async for msg in agent.receive_response(): print_activity(msg) messages_technical.append(msg) ``` ::: {.output .stream .stdout} 🤖 Thinking... 🤖 Thinking... ::: :::: :::: {.cell .code execution_count="5"} ``` python # Display executive style response display_agent_response(messages_executive) ``` ::: {.output .display_data}
Agent Response

My writing style is direct, concise, and professional—I avoid unnecessary filler and get straight to actionable insights. I adapt my tone based on context: more formal for strategic recommendations and board-level communications, more conversational for quick operational questions.

::: :::: :::: {.cell .code execution_count="6"} ``` python # Technical output style - detailed, implementation-focused display_agent_response(messages_technical, title="Technical Style") ``` ::: {.output .display_data}
Technical Style

My writing style is direct, clear, and professional—I provide concise answers without unnecessary filler while ensuring the information is complete and actionable. I adapt my tone to the context, being more formal for business analysis and more conversational for general questions, and I use formatting (like bullet points, headers, or code blocks) when it helps organize complex information.

::: :::: ::: {.cell .markdown} ### Feature 3: Plan Mode - Strategic Planning Without Execution **What**: Plan mode instructs the agent to create a detailed execution plan without performing any actions. The agent analyzes requirements, proposes solutions, and outlines steps, but doesn\'t modify files, execute commands, or make changes. **Why**: Complex tasks benefit from upfront planning to reduce errors, enable review and improve coordination. After the planning phase, the agent will have a red thread to follow throughout its execution. **How**: Just set `permission_mode="plan"` **Plan Persistence**: Since plans are valuable artifacts for review and decision-making, we\'ll demonstrate how to capture and save them to persistent markdown files. This enables stakeholders to review plans before approving execution. > Note: this feature shines in Claude Code but still needs to be fully > adapted for headless applications with the SDK. Namely, the agent will > try calling its `ExitPlanMode()` tool, which is only relevant in the > interactive mode. In this case, you can send up a follow-up query with > `continue_conversation=True` for the agent to execute its plan in > context. ::: :::: {.cell .code execution_count="7"} ``` python # ============================================================================= # Plan Mode Helper Functions # ============================================================================= # These utilities handle the various ways an agent might output its plan. # Since agents can output plans via direct text, Write tool, or Claude's # internal plan directory, we need robust extraction from multiple sources. import glob as glob_module import os import re from datetime import datetime from pathlib import Path from typing import Any def extract_plan_from_xml(text: str | None, min_length: int = 200) -> str | None: """ Extract content between tags from text. Args: text: The text to search for plan content min_length: Minimum character count for valid plan (prevents empty matches) Returns: Extracted plan content, or None if not found/too short """ if not text: return None match = re.search(r"(.*?)", text, re.DOTALL) if match: extracted = match.group(1).strip() if len(extracted) > min_length: return extracted return None def extract_plan_from_messages( plan_content: list[str], min_fallback_length: int = 500 ) -> tuple[str | None, str | None]: """ Try to extract plan from captured message stream content. Args: plan_content: List of text blocks captured during streaming min_fallback_length: Minimum length for fallback (no XML tags) Returns: Tuple of (plan_text, source_description) """ combined_text = "\n\n".join(plan_content) # First try: XML tags plan = extract_plan_from_xml(combined_text) if plan: return plan, "message stream" # Fallback: Use raw content if substantial if len(combined_text.strip()) > min_fallback_length: return combined_text.strip(), "full message content (fallback)" return None, None def extract_plan_from_write_tool( write_contents: list[str], min_fallback_length: int = 500 ) -> tuple[str | None, str | None]: """ Try to extract plan from captured Write tool calls. Args: write_contents: List of content strings from Write tool calls min_fallback_length: Minimum length for fallback (no XML tags) Returns: Tuple of (plan_text, source_description) """ for content in write_contents: # Try XML extraction first plan = extract_plan_from_xml(content) if plan: return plan, "Write tool capture" # Fallback: substantial content without tags if content and len(content.strip()) > min_fallback_length: return content.strip(), "Write tool capture (no XML tags)" return None, None def extract_plan_from_claude_dir( max_age_seconds: int = 300, min_fallback_length: int = 500 ) -> tuple[str | None, str | None]: """ Check Claude's internal plan directory for recently created plans. Args: max_age_seconds: Maximum age of plan file to consider (default: 5 minutes) min_fallback_length: Minimum length for fallback (no XML tags) Returns: Tuple of (plan_text, source_description) """ claude_plans_dir = os.path.expanduser("~/.claude/plans") if not os.path.exists(claude_plans_dir): return None, None # Find most recent plan file plan_files = sorted( glob_module.glob(os.path.join(claude_plans_dir, "*.md")), key=os.path.getmtime, reverse=True, ) if not plan_files: return None, None most_recent = plan_files[0] file_age = datetime.now().timestamp() - os.path.getmtime(most_recent) if file_age > max_age_seconds: return None, None with open(most_recent) as f: content = f.read() filename = os.path.basename(most_recent) # Try XML extraction first plan = extract_plan_from_xml(content) if plan: return plan, f"Claude plan file ({filename})" # Fallback: substantial content without tags if len(content.strip()) > min_fallback_length: return content.strip(), f"Claude plan file ({filename}, no XML tags)" return None, None def save_plan_to_file( plan_content: str, plan_source: str, model_name: str, prompt_summary: str, output_dir: str = "chief_of_staff_agent/plans", title: str = "Agent Plan: Engineering Restructure for AI Focus", ) -> Path: """ Save extracted plan to a timestamped markdown file. Args: plan_content: The plan text to save plan_source: Description of where plan was extracted from model_name: The model used to generate the plan prompt_summary: Brief description of the original prompt output_dir: Directory to save plan files title: Title for the plan document Returns: Path to the saved plan file """ plans_dir = Path(output_dir) plans_dir.mkdir(exist_ok=True) timestamp = datetime.now().strftime("%Y%m%d_%H%M%S") plan_file = plans_dir / f"plan_{timestamp}.md" with open(plan_file, "w") as f: f.write(f"# {title}\n\n") f.write(f"**Created:** {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n") f.write(f"**Prompt:** {prompt_summary}\n") f.write(f"**Model:** {model_name}\n") f.write(f"**Plan Source:** {plan_source}\n\n") f.write("---\n\n") f.write(plan_content) f.write("\n\n---\n\n") f.write("*This plan was generated in plan mode and has not been executed.*\n") return plan_file def capture_message_content( msg: Any, plan_content: list[str], write_tool_content: list[str], write_tool_paths: list[str], ) -> None: """ Process a streaming message and capture relevant plan content. This function extracts content from three potential sources: 1. Text blocks in message content 2. Write tool call parameters 3. Final result attribute Args: msg: The message object from the agent stream plan_content: List to append text content to write_tool_content: List to append Write tool content to write_tool_paths: List to append Write tool file paths to """ # Source 1: Text blocks from message content if hasattr(msg, "content"): for block in msg.content: if hasattr(block, "text"): plan_content.append(block.text) # Source 2: Write tool calls if hasattr(block, "type") and block.type == "tool_use": if hasattr(block, "name") and block.name == "Write": if hasattr(block, "input") and isinstance(block.input, dict): if "content" in block.input: write_tool_content.append(block.input["content"]) if "file_path" in block.input: write_tool_paths.append(block.input["file_path"]) # Source 3: Final result if hasattr(msg, "result") and msg.result: plan_content.append(msg.result) print("✅ Plan Mode helper functions loaded") ``` ::: {.output .stream .stdout} ✅ Plan Mode helper functions loaded ::: :::: :::: {.cell .code execution_count="8"} ``` python # ============================================================================= # Plan Mode Configuration # ============================================================================= # Note: MODEL is defined in cell-0 as "claude-opus-4-5" # Opus excels at complex planning tasks # The prompt is carefully crafted to: # 1. Provide explicit context (since Opus prefers explicit information) # 2. Request XML-tagged output for reliable extraction # 3. Prevent file-writing so we can capture the plan programmatically PLAN_PROMPT = """Restructure our engineering team for AI focus. **CONTEXT (from CLAUDE.md):** You are the Chief of Staff for TechStart Inc, a 50-person B2B SaaS startup that raised $10M Series A. - Current engineering team: 25 people (Backend: 12, Frontend: 8, DevOps: 5) - Monthly burn rate: ~$500K, Runway: 20 months - Senior Engineer compensation: $180K-$220K + equity **CRITICAL OUTPUT INSTRUCTIONS:** 1. **DO NOT use the Write tool** - Output your plan directly in your response text 2. **DO NOT save to any files** - I will handle saving the plan myself 3. **Wrap your ENTIRE plan inside ` ` XML tags** in your response **Required Format:** [Your complete restructuring plan here - include all sections, timelines, budgets, and recommendations] **IMPORTANT:** - The plan content MUST appear directly in your response between the XML tags - Do NOT use Write, Edit, or any file-saving tools - You may research and analyze before outputting, but the final plan must be in your response text - Include: team structure, hiring recommendations, timeline, budget impact, and success metrics - Use the company context provided above - do NOT ask clarifying questions""" print(f"📋 Plan Mode configured with model: {MODEL}") print(f"📝 Prompt length: {len(PLAN_PROMPT):,} characters") ``` ::: {.output .stream .stdout} 📋 Plan Mode configured with model: claude-opus-4-5 📝 Prompt length: 1,180 characters ::: :::: :::: {.cell .code execution_count="9"} ``` python # ============================================================================= # Execute Plan Mode Agent # ============================================================================= # Run the agent with plan mode enabled. The agent will create a detailed plan # but won't execute any actions. We capture content from multiple sources # to handle different agent behaviors. # Initialize capture lists messages = [] plan_content = [] # Text from message stream write_tool_content = [] # Content from Write tool calls write_tool_paths = [] # Paths from Write tool calls # Run the agent in plan mode async with ClaudeSDKClient( options=ClaudeAgentOptions( model=MODEL, permission_mode="plan", cwd="chief_of_staff_agent", ) ) as agent: await agent.query(PLAN_PROMPT) async for msg in agent.receive_response(): print_activity(msg) messages.append(msg) # Capture content from this message capture_message_content(msg, plan_content, write_tool_content, write_tool_paths) print(f"\n✅ Agent completed. Captured {len(plan_content)} content blocks.") ``` ::: {.output .stream .stdout} 🤖 Thinking... 🤖 Using: ExitPlanMode() ✓ Tool completed 🤖 Thinking... ✅ Agent completed. Captured 3 content blocks. ::: :::: :::: {.cell .code execution_count="10"} ``` python # ============================================================================= # Extract and Save the Plan # ============================================================================= # Try multiple sources in priority order to find the plan content. # This handles different agent behaviors robustly. final_plan = None plan_source = None # Priority 1: Message stream (preferred - direct from agent response) final_plan, plan_source = extract_plan_from_messages(plan_content) # Priority 2: Write tool captures (if agent saved despite instructions) if not final_plan and write_tool_content: final_plan, plan_source = extract_plan_from_write_tool(write_tool_content) # Priority 3: Claude's internal plan directory (safety net) if not final_plan: final_plan, plan_source = extract_plan_from_claude_dir() # Report results if final_plan: print(f"✅ Plan extracted from: {plan_source}") print(f" Plan length: {len(final_plan):,} characters") # Save to file plan_file = save_plan_to_file( plan_content=final_plan, plan_source=plan_source, model_name=MODEL, prompt_summary="Restructure our engineering team for AI focus.", ) print(f"\n📁 Plan saved to: {plan_file}") else: error_msg = "Could not extract plan content from any source!\n" error_msg += " Sources checked: message stream, Write tool, ~/.claude/plans/" if write_tool_paths: error_msg += f"\n Write tool attempted to save to: {write_tool_paths}" print(f"❌ ERROR: {error_msg}") raise RuntimeError(f"Plan extraction failed: {error_msg}") ``` ::: {.output .stream .stdout} ✅ Plan extracted from: message stream Plan length: 6,783 characters 📁 Plan saved to: chief_of_staff_agent/plans/plan_20251204_152737.md ::: :::: :::: {.cell .code execution_count="11"} ``` python # Display the plan result with styled HTML display_agent_response(messages, title="Engineering Restructure Plan") ``` ::: {.output .display_data}
Engineering Restructure Plan

I've provided the complete engineering team restructuring plan directly in my response within the <plan> tags as requested. The plan includes:

Ready to proceed when you've reviewed the plan!

::: :::: ::: {.cell .markdown} #### Executing the Saved Plan As mentioned above, the agent will stop after creating its plan. The saved plan file serves as a review artifact for stakeholders. **To execute the plan after review:** 1. Review the saved plan in `chief_of_staff_agent/plans/plan_*.md` 2. If approved, send a new query with `continue_conversation=True` and remove `permission_mode="plan"` to execute This workflow enables a \"plan → review → approve → execute\" cycle, perfect for high-stakes decisions like organizational restructuring or major infrastructure changes. ::: ::: {.cell .markdown} #### How Plan Persistence Works In the code above, we implemented a **robust multi-source plan capture mechanism** that handles the various ways Plan Mode agents may output their plans: **The Challenge:** When using `permission_mode="plan"`, the agent may output the plan in different ways: 1. **Direct text output** in the message stream (ideal case) 2. **Write tool** to save to `~/.claude/plans/` (Claude\'s internal plan system) 3. **Write tool** to save to a custom path Our capture mechanism handles all three scenarios with a **priority-based fallback system**: **Source Priority (in order):** 1. **Message Stream** (Preferred) - Capture text blocks from `msg.content` during streaming - Extract content between `` XML tags - This is the cleanest approach as content comes directly from the response 2. **Write Tool Capture** - Monitor for Write tool calls in the message stream - Extract the `content` parameter being written - Useful when the agent decides to save despite prompt instructions 3. **Claude\'s Internal Plan Directory** - Check `~/.claude/plans/` for recently created plan files (within 5 minutes) - Read and extract content from the most recent file - Acts as a safety net when other methods fail 4. **Full Content Fallback** - If no XML tags found but substantial content exists (\>500 chars), use it directly - Prevents empty plan files while preserving partial information **Key Implementation Details:** ``` python def extract_plan_from_text(text): """Extract content between tags, return None if not found or empty.""" match = re.search(r'(.*?)', text, re.DOTALL) if match: extracted = match.group(1).strip() # Validate minimum content length (a real plan should be substantial) if len(extracted) > 200: return extracted return None ``` **Why Content Validation Matters:** - Previous versions could produce empty plan files if extraction \"succeeded\" with no content - We now require a minimum of 200 characters for XML-tagged content - This prevents false positives where regex matches empty or trivial content **Prompt Engineering for Direct Output:** The prompt explicitly instructs the agent: - **DO NOT use the Write tool** - prevents file-system detours - **Output directly in response** - ensures content flows through message stream - **Use XML tags** - enables clean extraction from potentially verbose responses This approach gives you: - **Reliability**: Plans are captured regardless of agent behavior - **Transparency**: The saved file indicates which source was used - **Audit Trail**: History of all plans with timestamps and source metadata - **Debugging**: Clear error messages when extraction fails Let\'s view the saved plan: ::: ::::: {.cell .code execution_count="15"} ``` python # Display the saved plan with markdown rendering from IPython.display import Markdown, display # Show the plan with proper markdown formatting display(Markdown(f"## 📋 Saved Plan Preview\n\n{final_plan}")) print(f"\n📁 Full plan with metadata saved to: {plan_file}") ``` ::: {.output .display_data} ## 📋 Saved Plan Preview # TechStart Inc. Engineering Team Restructuring Plan for AI Focus ## Executive Summary Restructure the 25-person engineering team to build AI/ML capabilities while maintaining core product development. This plan balances immediate hiring needs with internal upskilling and strategic reorganization over a 12-month period. --- ## Current State Assessment | Team | Headcount | Current Focus | |------|-----------|---------------| | Backend | 12 | Core product, APIs, infrastructure | | Frontend | 8 | Web/mobile interfaces | | DevOps | 5 | CI/CD, cloud infrastructure | | **Total** | **25** | | **Key Constraints:** - Monthly burn: ~$500K | Runway: 20 months - Senior Engineer comp: $180K-$220K + equity - Series A stage - need to show growth metrics --- ## Proposed Future State (Month 12) ### New Team Structure | Team | Current | Future | Change | |------|---------|--------|--------| | Backend/Core | 12 | 8 | -4 | | Frontend | 8 | 6 | -2 | | DevOps/MLOps | 5 | 6 | +1 | | **AI/ML Platform** | 0 | 5 | +5 | | **AI Product** | 0 | 4 | +4 | | **Total** | **25** | **29** | **+4** | ### New Teams Created **1. AI/ML Platform Team (5 engineers)** - Focus: Infrastructure, model training pipelines, ML tooling - Composition: 2 new hires (ML Engineers) + 2 internal transfers (Backend) + 1 internal (DevOps) - Lead: New hire - Senior ML Engineer ($200-220K) **2. AI Product Team (4 engineers)** - Focus: AI features, integrations, user-facing ML applications - Composition: 2 new hires (ML/AI specialists) + 1 internal (Backend) + 1 internal (Frontend) - Lead: Promoted internal senior engineer + AI upskilling --- ## Hiring Plan ### New Positions (6 total new hires) | Role | Priority | Timeline | Comp Range | Notes | |------|----------|----------|------------|-------| | Senior ML Engineer (Lead) | P0 | Month 1-2 | $200-220K | Team lead, architecture | | ML Engineer | P0 | Month 2-3 | $180-200K | Platform focus | | ML Engineer | P1 | Month 3-4 | $180-200K | Product focus | | AI/ML Engineer | P1 | Month 4-5 | $170-190K | Generalist | | MLOps Engineer | P2 | Month 5-6 | $160-180K | DevOps + ML | | Junior ML Engineer | P2 | Month 6-8 | $130-150K | Growth hire | **Total New Hiring Cost:** ~$1.02-1.14M annually ### Internal Transfers & Upskilling (4 engineers) | From Team | # Engineers | New Role | Training Investment | |-----------|-------------|----------|---------------------| | Backend | 3 | ML Platform/Product | $15K each (courses, certs) | | Frontend | 1 | AI Product (UI/UX) | $10K (AI tools training) | **Upskilling Budget:** ~$55K total --- ## Implementation Timeline ### Phase 1: Foundation (Months 1-3) - [ ] Hire Senior ML Engineer (Team Lead) - **Critical first hire** - [ ] Identify 4 internal transfer candidates based on interest/aptitude - [ ] Begin ML upskilling program for transfer candidates - [ ] Set up ML infrastructure foundations (MLOps engineer involvement) - [ ] Define AI product roadmap with Product team ### Phase 2: Team Formation (Months 4-6) - [ ] Complete core AI team hiring (4 of 6 hires) - [ ] Officially launch AI/ML Platform team - [ ] Internal transfers complete bootcamp/training - [ ] First AI feature POC delivered - [ ] MLOps practices integrated into DevOps workflow ### Phase 3: Scaling (Months 7-9) - [ ] Complete remaining hires - [ ] AI Product team fully operational - [ ] First AI feature in production - [ ] Cross-team collaboration patterns established - [ ] Model monitoring and observability in place ### Phase 4: Optimization (Months 10-12) - [ ] Team velocity optimization - [ ] Evaluate team composition effectiveness - [ ] Plan for next growth phase - [ ] Document AI development best practices --- ## Budget Impact Analysis ### Monthly Cost Changes | Category | Current | Month 6 | Month 12 | |----------|---------|---------|----------| | Engineering Salaries | ~$375K | ~$430K | ~$485K | | Training/Upskilling | $0 | $9K | $2K | | AI Tools/Infrastructure | ~$5K | ~$20K | ~$35K | | Recruiting Costs | Variable | ~$40K | ~$15K | | **Monthly Total** | **~$380K** | **~$499K** | **~$537K** | ### Annual Impact Summary - **Year 1 Additional Investment:** ~$900K-1.1M - **New Monthly Burn (Month 12):** ~$537K (+$37K from engineering growth) - **Runway Impact:** Reduces to ~17 months (still healthy for Series A) ### ROI Considerations - AI features typically command 20-40% pricing premium in B2B SaaS - Competitive differentiation in market - Potential for AI-driven operational efficiencies --- ## Risk Mitigation | Risk | Likelihood | Impact | Mitigation | |------|------------|--------|------------| | Senior ML hire takes >3 months | Medium | High | Engage specialized recruiters early; consider contractor bridge | | Internal transfers struggle with ML | Low | Medium | Rigorous selection process; extended training runway | | AI projects don't deliver value | Medium | High | Start with high-impact, lower-complexity features | | Team culture friction | Low | Medium | Integrate teams gradually; shared goals and rituals | | Budget overrun | Medium | Medium | Phase hiring based on runway checks quarterly | --- ## Success Metrics ### 6-Month Milestones - [ ] AI/ML Platform team fully staffed (5 engineers) - [ ] First AI-powered feature in beta - [ ] 4 internal engineers completed ML certification - [ ] ML infrastructure supporting model training/deployment ### 12-Month Milestones - [ ] 2+ AI features in production - [ ] AI team velocity matches core team benchmarks - [ ] Customer NPS improvement attributable to AI features - [ ] 15%+ of product roadmap is AI-focused - [ ] Retention of transferred engineers >90% ### KPIs to Track - Time-to-hire for ML roles - AI feature adoption rates - Model performance metrics (latency, accuracy) - Engineering velocity (story points/sprint) across teams - Employee satisfaction scores (especially transfers) --- ## Immediate Next Steps (Week 1-2) 1. **Executive alignment** - Present plan to leadership for approval 2. **Recruiter engagement** - Brief recruiting on Senior ML Engineer search 3. **Internal survey** - Gauge interest in AI/ML roles among current engineers 4. **Budget approval** - Finance sign-off on increased burn rate 5. **Infrastructure assessment** - DevOps audit of ML infrastructure needs --- ## Organizational Chart (Future State) ``` VP Engineering ├── Backend/Core Team (8) │ └── 2 squads × 4 engineers ├── Frontend Team (6) │ └── 2 squads × 3 engineers ├── DevOps/MLOps Team (6) │ └── 4 DevOps + 2 MLOps ├── AI/ML Platform Team (5) [NEW] │ └── Lead + 4 engineers └── AI Product Team (4) [NEW] └── Lead + 3 engineers ``` --- *Plan prepared for TechStart Inc. Series A stage (~$10M raised, 20-month runway)* *Recommended review: Quarterly budget and hiring progress checkpoints* ::: ::: {.output .stream .stdout} 📁 Full plan with metadata saved to: chief_of_staff_agent/plans/plan_20251204_152737.md ::: ::::: ::: {.cell .markdown} ## Advanced Features ::: ::: {.cell .markdown} ### Feature 4: Custom Slash Commands > Note: slash commands are syntactic sugar for users, not new agent > capabilities **What**: Custom slash commands are predefined prompt templates that users can trigger with shorthand syntax (e.g., `/budget-impact`). These are **user-facing shortcuts**, not agent capabilities. Think of them as keyboard shortcuts that expand into full, well-crafted prompts. **Why**: Your Chief of Staff will handle recurring executive questions. Instead of users typing complex prompts repeatedly, they can use already vetted prompts. This improves consistency and standardization. **How**: - Define a markdown file in `.claude/commands/`. For example, we defined one in `.claude/commands/slash-command-test.md`. Notice how the command is defined: frontmatter with two fields (name, description) and the expanded prompt with an option to include arguments passed on in the query. - You can add parameters to your prompt using `$ARGUMENTS` (for full argument string) or `$1`, `$2`, etc. (for positional arguments) - The user uses the slash command in their prompt > **CRITICAL SDK CONFIGURATION**: When using the SDK, you **must** set > `setting_sources=["project"]` in your `ClaudeAgentOptions` for slash > commands to work. By default, the SDK operates in isolation mode and > does NOT load filesystem settings (slash commands, CLAUDE.md, > subagents, hooks, etc.). This is different from using Claude Code > interactively where these are loaded automatically. ::: :::: {.cell .code execution_count="16"} ``` python # User types: "/slash-command-test this is a test" # -> behind the scenes EXPANDS to the prompt in .claude/commands/slash-command-test.md # In this case the expanded prompt says to simply reverse the sentence word wise messages = [] async with ClaudeSDKClient( options=ClaudeAgentOptions( model=MODEL, cwd="chief_of_staff_agent", # IMPORTANT: setting_sources must include "project" to load slash commands from .claude/commands/ # Without this, the SDK does NOT load filesystem settings (slash commands, CLAUDE.md, etc.) setting_sources=["project"], ) ) as agent: await agent.query("/slash-command-test this is a test") async for msg in agent.receive_response(): print_activity(msg) messages.append(msg) ``` ::: {.output .stream .stdout} 🤖 Thinking... ::: :::: :::: {.cell .code execution_count="17"} ``` python display_agent_response(messages, title="Slash Command Result") ``` ::: {.output .display_data}
Slash Command Result

The sentence "this is a test" reversed word-wise is:

test a is this

::: :::: ::: {.cell .markdown} ### Feature 5: Hooks - Automated Deterministic Actions **What**: Hooks are Python scripts that you can set to execute automatically, among other events, before (pre) or after (post) specific tool calls. Hooks run **deterministically**, making them perfect for validation and audit trails. **Why**: Imagine scenarios where you want to make sure that your agent has some guardrails (e.g., prevent dangerous operations) or when you want to have an audit trail. Hooks are ideal in combination with agents to allow them enough freedom to achieve their task, while still making sure that the agents behave in a safe way. **How**: - Define hook scripts in `.claude/hooks/` -\> *what* is the behaviour that should be executed when a hook is triggered - Define hook configuration in `.claude/settings.local.json` -\> *when* should a hook be triggered - In this case, our hooks are configured to watch specific tool calls (Bash, Write, Edit) - When those tools are called, the hook script runs after the tool completes (PostToolUse) > **SDK CONFIGURATION NOTE**: Hooks configured in > `.claude/settings.local.json` require > `setting_sources=["project", "local"]`. The SDK distinguishes between > three setting sources: > > - `"project"` → `.claude/settings.json` (version-controlled, > team-shared) > - `"local"` → `.claude/settings.local.json` (gitignored, local > settings like hooks) > - `"user"` → `~/.claude/settings.json` (global user settings) > > Since our hooks are in `settings.local.json`, we must include > `"local"` in `setting_sources`. **Example: Report Tracking for Compliance** A hook to log Write/Edit operations on financial reports for audit and compliance purposes. The hook is defined in `chief_of_staff_agent/.claude/hooks/report-tracker.py` and the logic that enforces it is in `chief_of_staff_agent/.claude/settings.local.json`: ``` json "hooks": { "PostToolUse": [ { "matcher": "Write", "hooks": [ { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/report-tracker.py" } ] }, { "matcher": "Edit", "hooks": [ { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/report-tracker.py" } ] } ] } ``` ::: ::::: {.cell .code execution_count="18"} ``` python messages = [] async with ClaudeSDKClient( options=ClaudeAgentOptions( model=MODEL, cwd="chief_of_staff_agent", allowed_tools=["Bash", "Write", "Edit", "MultiEdit"], # IMPORTANT: setting_sources must include BOTH "project" AND "local" to load hooks # - "project" loads .claude/settings.json (shared settings, CLAUDE.md, slash commands) # - "local" loads .claude/settings.local.json (where hooks are configured) setting_sources=["project", "local"], ) ) as agent: await agent.query( "Create a quick Q2 financial forecast report with our current burn rate and runway projections. Save it to our /output_reports folder." ) async for msg in agent.receive_response(): print_activity(msg) messages.append(msg) # The hook will track this in audit/report_history.json display_agent_response(messages, title="Q2 Financial Forecast") ``` ::: {.output .stream .stdout} 🤖 Using: Bash() 🤖 Using: Bash() 🤖 Using: Bash() ✓ Tool completed ✓ Tool completed ✓ Tool completed 🤖 Using: Read() 🤖 Using: Read() 🤖 Using: Read() 🤖 Using: Bash() ✓ Tool completed ✓ Tool completed ✓ Tool completed ✓ Tool completed 🤖 Thinking... 🤖 Using: Write() ✓ Tool completed 🤖 Thinking... ::: ::: {.output .display_data}
Q2 Financial Forecast

I've created a comprehensive Q2 Financial Forecast Report and saved it to the output_reports folder. Here's a summary of what's included:

Report Summary

📊 Q2 2024 Financial Forecast Report Created

Location: /output_reports/Q2_2024_Financial_Forecast_Report.md

Key Highlights:

Metric Value
Cash in Bank $10M
Current Runway 20 months (until Sept 2025)
Monthly Burn $500K gross / ~$260K net
Q2 Total Net Burn $740K
ARR $2.4M (15% MoM growth)

Positive Trends:

  • ✅ Net burn decreasing 9.6% month-over-month (from $260K → $235K)
  • ✅ Revenue growth (20.8%) outpacing burn increase (5%)
  • ✅ Revenue per employee improving 14%

Planning Scenarios:

  • Conservative: 38-month runway (if revenue holds flat)
  • With 10 new engineers: ~15-month runway
  • Base case with growth: Path to break-even by Q2 2025

The report includes detailed monthly breakdowns, hiring cost impact analysis, revenue milestones, risk assessment, and strategic recommendations for Series B timing.

::: ::::: ::: {.cell .markdown} If you now navigate to `./chief_of_staff_agent/audit/report_history.json`, you will find that it has logged that the agent has created and/or made changes to your report. The generated report itself you can find at `./chief_of_staff_agent/output_reports/`. ::: ::: {.cell .markdown} ### Feature 6: Subagents via Task Tool **What**: The Task tool enables your agent to delegate specialized work to other subagents. These subagents each have their own instructions, tools, and expertise. **Why**: Adding subagents opens up a lot of possibilities: 1. Specialization: each subagent is an expert in their domain 2. Separate context: subagents have their own conversation history and tools 3. Parallellization: multiple subagents can work simultaneously on different aspects. **How**: - Add `"Task"` to allowed_tools - Use a system prompt to instruct your agent how to delegate tasks (you can also define this its CLAUDE.md more generally) - Create a markdown file for each agent in `.claude/agents/`. For example, check the one for `.claude/agents/financial-analyst.md` and notice how a (sub)agent can be defined with such an easy and intuitive markdown file: frontmatter with three fields (name, description, and tools) and its system prompt. The description is useful for the main chief of staff agent to know when to invoke each subagent. **Visualization Enhancements**: Our `print_activity()` and `visualize_conversation()` utilities have been enhanced to clearly show subagent operations: - 🚀 indicates when a subagent is being delegated to (with the subagent name) - 📎 indicates tools being used BY the subagent (indented for visual hierarchy) - Visual separators clearly mark subagent delegation and completion boundaries - Task descriptions and prompts are shown in the conversation timeline ::: ::::: {.cell .code execution_count="19"} ``` python # Reset the subagent tracking context before starting a new query # This ensures clean state for activity display reset_activity_context() messages = [] async with ClaudeSDKClient( options=ClaudeAgentOptions( model=MODEL, allowed_tools=["Task"], # this enables our Chief agent to invoke subagents system_prompt="Delegate financial questions to the financial-analyst subagent. Do not try to answer these questions yourself.", cwd="chief_of_staff_agent", setting_sources=["project", "local"], ) ) as agent: await agent.query("Should we hire 5 engineers? Analyze the financial impact.") async for msg in agent.receive_response(): print_activity(msg) messages.append(msg) display_agent_response(messages, title="Hiring Impact Analysis") ``` ::: {.output .stream .stdout} 🤖 Thinking... 🚀 Delegating to subagent: financial-analyst └─ Task: Analyze 5 engineer hiring impact ✓ Tool completed 📎 [financial-analyst] Using: Bash() 📎 [financial-analyst] Using: Read() 📎 [financial-analyst] Using: Read() ✓ Tool completed ✓ Tool completed ✓ Tool completed 📎 [financial-analyst] Using: Read() 📎 [financial-analyst] Using: Bash() ✓ Tool completed ✓ Tool completed 📎 [financial-analyst] Using: Bash() ✓ Tool completed 📎 [financial-analyst] Using: Bash() ✓ Tool completed 📎 [financial-analyst] Using: Bash() ✓ Tool completed 📎 [financial-analyst] Using: Bash() ✓ Tool completed ✓ Tool completed 📎 [financial-analyst] Thinking... ::: ::: {.output .display_data}
Hiring Impact Analysis

Financial Impact Analysis: Hiring 5 Engineers

Executive Summary

Recommendation: ✅ PROCEED WITH CAUTION - Use a staged hiring approach with 3 Senior + 2 Junior engineers

Financial Impact at a Glance

Metric Current After 5 Hires Change
Monthly Burn $500,000 $575,833 +15.2%
Runway 20 months 17.1 months -2.9 months
Headcount 50 55 +10%
Engineering % 50% 54.5% +4.5%

One-time costs: ~$165K (recruiting + onboarding)

Three Scenarios Analyzed

Scenario Mix New Monthly Burn New Runway
A (Recommended) 3 Senior + 2 Junior $575,833 17.1 months
B 5 Senior $591,665 16.6 months
C 2 Senior + 3 Junior $567,917 17.3 months

Why This Works ✅

  1. Strong Revenue Growth - 15% MoM ARR growth ($2.4M → projected $5.5M by Dec 2024) partially offsets increased burn
  2. Healthy Runway Post-Hire - 17+ months exceeds the minimum 12-month threshold
  3. Series B Alignment - Maintains sufficient runway to close Series B (target Q1 2026)
  4. Strategic Necessity - Product launch and European expansion require engineering capacity

Key Risks ⚠️

  1. Runway Compression - 2.9-month reduction leaves less buffer
  2. Series B Dependency - Must close by Q1 2026 (reduced negotiating flexibility)
  3. Revenue Assumptions - Projections depend on continued 15% MoM growth

Recommended Implementation Plan

Phase 1 (Immediate): Hire 3 engineers (2 Senior + 1 Junior)
Phase 2 (30-60 days later): Hire remaining 2 engineers (1 Senior + 1 Junior)

Financial Guardrails:
- Maintain minimum 15-month runway at all times
- Pause hiring if revenue growth drops below 12% MoM
- Begin Series B conversations by August 2024

Bottom Line

The hire is financially prudent given your strong growth trajectory and healthy runway buffer. However, it's critical to:
1. Execute staged hiring to de-risk
2. Maintain revenue momentum
3. Stay on track with Series B timeline

Confidence Level: 75% — Proceed, but with active monitoring and clear guardrails.

::: ::::: :::: {.cell .code execution_count="20"} ``` python visualize_conversation(messages) ``` ::: {.output .display_data}
🤖 Agent Conversation Timeline • claude-opus-4-5
⚙️ System
Initialized (bf3bc346...)
🤖 Assistant

I'll delegate this financial analysis to the financial-analyst subagent who can properly analyze the impact of hiring 5 engineers.

🚀 Subagent: financial-analyst
Analyze 5 engineer hiring impact
🔧 Tools
BashRead: burn_rate.csvRead: revenue_forecast.jsonRead: hiring_costs.csvBashBashBashBashBash
🤖 Assistant

Financial Impact Analysis: Hiring 5 Engineers

Executive Summary

Recommendation: ✅ PROCEED WITH CAUTION - Use a staged hiring approach with 3 Senior + 2 Junior engineers

Financial Impact at a Glance

Metric Current After 5 Hires Change
Monthly Burn $500,000 $575,833 +15.2%
Runway 20 months 17.1 months -2.9 months
Headcount 50 55 +10%
Engineering % 50% 54.5% +4.5%

One-time costs: ~$165K (recruiting + onboarding)

Three Scenarios Analyzed

Scenario Mix New Monthly Burn New Runway
A (Recommended) 3 Senior + 2 Junior $575,833 17.1 months
B 5 Senior $591,665 16.6 months
C 2 Senior + 3 Junior $567,917 17.3 months

Why This Works ✅

  1. Strong Revenue Growth - 15% MoM ARR growth ($2.4M → projected $5.5M by Dec 2024) partially offsets increased burn
  2. Healthy Runway Post-Hire - 17+ months exceeds the minimum 12-month threshold
  3. Series B Alignment - Maintains sufficient runway to close Series B (target Q1 2026)
  4. Strategic Necessity - Product launch and European expansion require engineering capacity

Key Risks ⚠️

  1. Runway Compression - 2.9-month reduction leaves less buffer
  2. Series B Dependency - Must close by Q1 2026 (reduced negotiating flexibility)
  3. Revenue Assumptions - Projections depend on continued 15% MoM growth

Recommended Implementation Plan

Phase 1 (Immediate): Hire 3 engineers (2 Senior + 1 Junior)
Phase 2 (30-60 days later): Hire remaining 2 engineers (1 Senior + 1 Junior)

Financial Guardrails:
- Maintain minimum 15-month runway at all times
- Pause hiring if revenue growth drops below 12% MoM
- Begin Series B conversations by August 2024

Bottom Line

The hire is financially prudent given your strong growth trajectory and healthy runway buffer. However, it's critical to:
1. Execute staged hiring to de-risk
2. Maintain revenue momentum
3. Stay on track with Series B timeline

Confidence Level: 75% — Proceed, but with active monitoring and clear guardrails.

✅ Complete
Turns: 2 Tokens: 1,173 Cost: $0.28 Duration: 164.9s
::: :::: ::: {.cell .markdown} Here, when our main agent decides to use a subagent, it will: 1. Call the Task tool with parameters like: ``` json { "description": "Analyze hiring impact", "prompt": "Analyze the financial impact of hiring 5 engineers...", "subagent_type": "financial-analyst" } ``` 1. The Task tool executes the subagent in a separate context 2. Return results to main Chief of Staff agent to continue processing ::: ::: {.cell .markdown} ## Putting It All Together ::: ::: {.cell .markdown} Let\'s now put everything we\'ve seen together. We will ask our agent to determine the financial impact of hiring 3 senior engineers and write their insights to `output_reports/hiring_decision.md`. This demonstrates all the features seen above: - **Bash Tool**: Used to execute the `hiring_impact.py` script to determine the impact of hiring new engineers - **Memory**: Reads `CLAUDE.md` in directory as context to understand the current budgets, runway, revenue and other relevant information - **Output style**: Different output styles, defined in `chief_of_staff_agent/.claude/output-styles` - **Custom Slash Commands**: Uses the shortcut `/budget-impact` that expands to full prompt defined in `chief_of_staff_agent/.claude/commands` - **Subagents**: Our `/budget_impact` command guides the chief of staff agent to invoke the financial-analyst subagent defined in `chief_of_staff_agent/.claude/agents` - **Hooks**: Hooks are defined in `chief_of_staff_agent/.claude/hooks` and configured in `chief_of_staff_agent/.claude/settings.local.json` - If one of our agents is updating the financial report, the hook should log this edit/write activity in the `chief_of_staff_agent/audit/report_history.json` logfile - If the financial analyst subagent will invoke the `hiring_impact.py` script, this will be logged in `chief_of_staff_agent/audit/tool_usage_log.json` logfile - **Plan Mode**: If you want the chief of staff to come up with a plan for you to approve before taking any action, uncomment the commented line below To have this ready to go, we have encapsulated the agent loop in a python file, similar to what we did in the previous notebook. Check out the agent.py file in the `chief_of_staff_agent` subdirectory. All in all, our `send_query()` function takes in 4 parameters (prompt, continue_conversation, permission_mode, and output_style), everything else is set up in the agent file, namely: system prompt, max turns, allowed tools, and the working directory. To better visualize how this all comes together, check out these [flow and architecture diagrams that Claude made for us :)](./chief_of_staff_agent/flow_diagram.md) ::: :::: {.cell .code execution_count="21"} ``` python from chief_of_staff_agent.agent import send_query reset_activity_context() result, messages = await send_query( "/budget-impact hiring 3 senior engineers. Save your insights by updating the 'hiring_decision.md' file in /output_reports or creating a new file there", # permission_mode="plan", # Enable this to use planning mode output_style="executive", ) ``` ::: {.output .stream .stdout} 🤖 Thinking... 🤖 Using: Glob() 🤖 Using: Glob() ✓ Tool completed ✓ Tool completed 🤖 Using: Read() 🤖 Using: Read() 🤖 Using: Read() 🤖 Using: Read() ✓ Tool completed ✓ Tool completed ✓ Tool completed ✓ Tool completed 🤖 Thinking... 🤖 Using: Task() ✓ Tool completed 🤖 Using: Bash() 🤖 Using: Read() 🤖 Using: Read() 🤖 Using: Read() ✓ Tool completed ✓ Tool completed ✓ Tool completed ✓ Tool completed ✓ Tool completed 🤖 Thinking... 🤖 Using: Write() ✓ Tool completed 🤖 Thinking... ::: :::: :::: {.cell .code execution_count="22"} ``` python visualize_conversation(messages) ``` ::: {.output .display_data}
🤖 Agent Conversation Timeline • claude-opus-4-5
⚙️ System
Initialized (cea37adf...)
🤖 Assistant

I'll analyze the budget impact of hiring 3 senior engineers. Let me first check the current financial data and existing reports, then delegate to the financial analyst for a comprehensive analysis.

🔧 Tools
GlobGlobRead: hiring_costs.csvRead: burn_rate.csvRead: revenue_forecast.jsonRead: hiring_decision.md
🤖 Assistant

I see there's already an existing analysis. Let me delegate to the financial analyst subagent to provide an updated, comprehensive analysis with the latest data and additional insights.

🚀 Subagent: financial-analyst
Analyze hiring 3 senior engineers budget impact
🔧 Tools
BashRead: hiring_costs.csvRead: burn_rate.csvRead: revenue_forecast.json
🤖 Assistant

Excellent! The financial analyst has provided a comprehensive analysis. Let me now update the hiring decision report with this enhanced analysis.

🔧 Tools
Write
🤖 Assistant

I've completed the comprehensive budget impact analysis for hiring 3 senior engineers. Here's a summary of the key findings:

Budget Impact Analysis Summary

Recommendation: CONDITIONAL APPROVAL WITH STAGGERED APPROACH

Key Financial Impact

Metric Current Post-Hiring Change
Monthly Gross Burn $525K $590K +$65K (+12.4%)
Monthly Net Burn $235K $300K +$65K (+27.7%)
Cash Runway 42.6 months 32.9 months -9.7 months
Break-Even - November 2024 5 months

Total Investment

  • One-time costs: $129,000 (recruiting, onboarding, equipment)
  • Annual recurring: $780,000 ($65K/month loaded)
  • First year total: $909,000

Why Proceed?

  1. Break-even achievable in 5 months with current 15% MoM revenue growth
  2. Strong runway buffer - 32.9 months even without revenue growth
  3. Strategic timing aligns with Q2 product launch and market opportunity

Risk Mitigation Strategy

  • Staggered hiring (1 engineer/month) reduces integration risk
  • Milestone gates allow pause/abort if revenue growth slows
  • Series B prep should begin immediately to strengthen position

Critical Success Factors

  1. Maintain >12% MoM revenue growth
  2. Hire Engineering Manager concurrent with first engineer
  3. Begin Series B conversations now
  4. Complete stock refresh for key engineer retention

The full analysis has been saved to /output_reports/hiring_decision.md with detailed sections on ROI analysis, 4 alternative options, 8 risk factors with mitigations, implementation timeline, and success metrics.

✅ Complete
Turns: 9 Tokens: 5,871 Cost: $0.48 Duration: 279.1s
::: :::: ::: {.cell .markdown} ## Conclusion We\'ve demonstrated how the Claude Code SDK enables you to build sophisticated multi-agent systems with enterprise-grade features. Starting from basic script execution with the Bash tool, we progressively introduced advanced capabilities including persistent memory with CLAUDE.md, custom output styles for different audiences, strategic planning mode, slash commands for user convenience, compliance hooks for guardrailing, and subagent coordination for specialized tasks. By combining these features, we created an AI Chief of Staff capable of handling complex executive decision-making workflows. The system delegates financial analysis to specialized subagents, maintains audit trails through hooks, adapts communication styles for different stakeholders, and provides actionable insights backed by data-driven analysis. This foundation in advanced agentic patterns and multi-agent orchestration prepares you for building production-ready enterprise systems. In the next notebook, we\'ll explore how to connect our agents to external services through Model Context Protocol (MCP) servers, dramatically expanding their capabilities beyond the built-in tools. Next: [02_The_observability_agent.ipynb](02_The_observability_agent.ipynb) - Learn how to extend your agents with custom integrations and external data sources through MCP. ::: --- ## 02-the-observability-agent.md the-observability-agent}" category: "09-Agents-Patterns" tags: ["agents", "git", "mcp"] --- ::: {#7e7958dd .cell .code execution_count="1"} ``` python import os import shutil import subprocess from typing import Any from dotenv import load_dotenv from IPython.display import Markdown, display from utils.agent_visualizer import ( display_agent_response, print_activity, reset_activity_context, visualize_conversation, ) from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient ``` ::: ::: {#ea47572b .cell .markdown} # 02 - The Observability Agent {#02---the-observability-agent} ::: ::: {#08cc95b6 .cell .markdown} In the previous notebooks we have built a basic research agent and a Chief of Staff multi-agent framework. While the agents we have built are already powerful, they were still limited in what they could do: the web search agent is limited to searching the internet and our Chief of Staff agent was limited to interacting with its own filesystem. This is a serious constraint: real-world agents often need to interact with other systems like databases, APIs, file systems, and other specialized services. [MCP (Model Context Protocol)](../06-MCP-Tools/Tutorials/what-is-the-model-context-protocol-mcp-model-context-protocol.md) is an open-source standard for AI-tool integrations that allows for an easy connection between our agents and these external systems. In this notebook, we will explore how to connect MCP servers to our agent. **Need more details on MCP?** For comprehensive setup instructions, configuration best practices, and troubleshooting tips, see the [Claude Code MCP documentation](https://docs.claude.com/en/docs/claude-code/mcp). ::: ::: {#95247d94 .cell .markdown} ## Introduction to the MCP Server ### 1. The Git MCP server {#1-the-git-mcp-server} Let\'s first give our agent the ability to understand and work with Git repositories. By adding the [Git MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/git) to our agent, it gains access to 13 Git-specific tools that let it examine commit history, check file changes, create branches, and even make commits. This transforms our agent from a passive observer into an active participant in your development workflow. In this example, we\'ll configure the agent to explore a repository\'s history using only Git tools. This is pretty simple, but knowing this, it is not difficult to imagine agents that can automatically create pull requests, analyze code evolution patterns, or help manage complex Git workflows across multiple repositories. ::: ::: {#21de60c4 .cell .code execution_count="2"} ``` python # Get the git repository root (mcp_server_git requires a valid git repo path) # os.getcwd() may return a subdirectory, so we find the actual repo root git_executable = shutil.which("git") if git_executable is None: raise RuntimeError("Git executable not found in PATH") git_repo_root = subprocess.run( # noqa: S603 [git_executable, "rev-parse", "--show-toplevel"], capture_output=True, text=True, check=True, ).stdout.strip() # Define our git MCP server (installed via uv sync from pyproject.toml) git_mcp: dict[str, Any] = { "git": { "command": "uv", "args": ["run", "python", "-m", "mcp_server_git", "--repository", git_repo_root], } } ``` ::: :::: {#23aa5a3d .cell .code execution_count="3"} ``` python messages = [] async with ClaudeSDKClient( options=ClaudeAgentOptions( model="claude-opus-4-5", mcp_servers=git_mcp, allowed_tools=["mcp__git"], # disallowed_tools ensures the agent ONLY uses MCP tools, not Bash with git commands disallowed_tools=["Bash", "Task", "WebSearch", "WebFetch"], permission_mode="acceptEdits", ) ) as agent: await agent.query( "Explore this repo's git history and provide a brief summary of recent activity." ) async for msg in agent.receive_response(): print_activity(msg) messages.append(msg) ``` ::: {.output .stream .stdout} 🤖 Using: mcp__git__git_log() 🤖 Using: mcp__git__git_status() 🤖 Using: mcp__git__git_branch() ✓ Tool completed ✓ Tool completed ✓ Tool completed 🤖 Thinking... 🤖 Using: mcp__git__git_log() 🤖 Using: mcp__git__git_status() 🤖 Using: mcp__git__git_branch() ✓ Tool completed ✓ Tool completed ✓ Tool completed 🤖 Thinking... ::: :::: :::: {#691e0812 .cell .code execution_count="4"} ``` python display(Markdown(f"\nResult:\n{messages[-1].result}")) ``` ::: {.output .display_data} Result: ## Git Repository Summary ### Current Branch You're on the **`upstream-contribution`** branch (up to date with origin), with `main` also available locally. --- ### Recent Commit Activity (Last ~5 Days) | Date | Author | Summary | |------|--------|---------| | **Nov 27, 2025** | costiash | 3 commits enhancing the **Claude Agent SDK** - improved chief of staff agent, notebooks, observability agent, research agent, documentation, and utilities | | **Nov 26, 2025** | Pedram Navid | Added GitHub issue templates, `/review-issue` command, `/add-registry` slash command, and new cookbook entries | | **Nov 25, 2025** | Elie Schoppik | Renamed PTC notebook to `programmatic_tool_calling_ptc.ipynb` for clarity | | **Nov 24, 2025** | henrykeetay | Added **tool search cookbook** | | **Nov 24, 2025** | Alex Notov | Multiple merges consolidating cookbooks for Opus 4.5, dependency updates | | **Nov 23, 2025** | Cal Rueb | Simplified crop tool notebook with Claude Agent SDK section | | **Nov 23, 2025** | Pedram Navid | PR comment fixes and lint cleanup | --- ### Key Themes in Recent Development 1. **Claude Agent SDK enhancements** - Major work on agent implementations (research, chief of staff, observability agents) 2. **New cookbooks** - Tool search, crop tool, programmatic tool calling 3. **CI/CD improvements** - PR review workflows, issue templates, slash commands 4. **Documentation** - Added troubleshooting guides, codebase overviews --- ### Working Directory Status There are **uncommitted changes** in your working directory: - **22 modified files** (mostly in `claude_agent_sdk/`) - **4 deleted files** (documentation files in `docs/`) - **6 untracked files** (new reports, plans, VS Code config) These changes appear to be further work on the Claude Agent SDK agents, notebooks, and utilities that haven't been staged or committed yet. ::: :::: ::: {#346a8754 .cell .markdown} ### 2. The GitHub MCP server {#2-the-github-mcp-server} ::: ::: {#1361ba84 .cell .markdown} Now let\'s level up from local Git operations to full GitHub platform integration. By switching to the [official GitHub MCP server](https://github.com/github/github-mcp-server/tree/main), our agent gains access to over 100 tools that interact with GitHub\'s entire ecosystem -- from managing issues and pull requests to monitoring CI/CD workflows and analyzing code security alerts. This server can work with both public and private repositories, giving your agent the ability to automate complex GitHub workflows that would typically require multiple manual steps. ::: ::: {#7fdb4aa2 .cell .markdown} #### Step 1: Set up your GitHub Token You need a GitHub Personal Access Token. Get one [here](https://github.com/settings/personal-access-tokens/new) and put in the .env file as `GITHUB_TOKEN=""` > Note: When getting your token, select \"Fine-grained\" token with the > default options (i.e., public repos, no account permissions), that\'ll > be the easiest way to get this demo working. Also, for this example you will have to have [Docker](https://www.docker.com/products/docker-desktop/) running on your machine. Docker is required because the GitHub MCP server runs in a containerized environment for security and isolation. **Docker Quick Setup:** - Install Docker Desktop from [docker.com](https://www.docker.com/products/docker-desktop/) - Ensure Docker is running (you\'ll see the Docker icon in your system tray) - Verify with `docker --version` in your terminal - **Troubleshooting:** If Docker won\'t start, check that virtualization is enabled in your BIOS. For detailed setup instructions, see the [Docker documentation](https://docs.docker.com/get-docker/) #### Step 2: Define the mcp server and start the agent loop! ::: ::: {#c1e65281 .cell .code execution_count="5"} ``` python # define our github mcp server load_dotenv(override=True) github_mcp: dict[str, Any] = { "github": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server", ], "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": os.environ.get("GITHUB_TOKEN")}, } } ``` ::: :::: {#e4c524c1 .cell .code execution_count="6"} ``` python # run our agent messages = [] async with ClaudeSDKClient( options=ClaudeAgentOptions( model="claude-opus-4-5", mcp_servers=github_mcp, allowed_tools=["mcp__github"], # disallowed_tools ensures the agent ONLY uses MCP tools, not Bash with gh CLI disallowed_tools=["Bash", "Task", "WebSearch", "WebFetch"], permission_mode="acceptEdits", ) ) as agent: await agent.query( "Search for the anthropics/claude-agent-sdk-python repository and give me a few key facts about it." ) async for msg in agent.receive_response(): print_activity(msg) messages.append(msg) ``` ::: {.output .stream .stdout} 🤖 Using: mcp__github__search_repositories() ✓ Tool completed 🤖 Thinking... ::: :::: :::: {#4e0ac04f .cell .code execution_count="7"} ``` python display(Markdown(f"\nResult:\n{messages[-1].result}")) ``` ::: {.output .display_data} Result: Here are the key facts about the **anthropics/claude-agent-sdk-python** repository: | Fact | Details | |------|---------| | **Full Name** | anthropics/claude-agent-sdk-python | | **URL** | https://github.com/anthropics/claude-agent-sdk-python | | **Language** | Python | | **Stars** | ⭐ 3,357 | | **Forks** | 🍴 435 | | **Open Issues** | 149 | | **Created** | June 11, 2025 | | **Last Updated** | December 4, 2025 | | **Default Branch** | main | | **Visibility** | Public | | **Archived** | No | This is the official Python SDK for building Claude agents, maintained by Anthropic. It's quite popular with over 3,300 stars and has an active community with 435 forks. The repository is actively maintained (recently updated) and has a notable number of open issues (149), which suggests active development and community engagement. ::: :::: ::: {#2a788ed6 .cell .markdown} ## Real use case: An observability agent Now, with such simple setup we can already have an agent acting as self-healing software system! ::: :::: {#c8edb208 .cell .code execution_count="8"} ``` python load_dotenv(override=True) prompt = """Analyze the CI health for facebook/react repository. Examine the most recent runs of the 'CI' workflow and provide: 1. Current status and what triggered the run (push, PR, schedule, etc.) 2. If failing: identify the specific failing jobs/tests and assess severity 3. If passing: note any concerning patterns (long duration, flaky history) 4. Recommended actions with priority (critical/high/medium/low) Provide a concise operational summary suitable for an on-call engineer. Do not create issues or PRs - this is a read-only analysis.""" github_mcp: dict[str, Any] = { "github": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server", ], "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": os.environ.get("GITHUB_TOKEN")}, } } messages = [] async with ClaudeSDKClient( options=ClaudeAgentOptions( model="claude-opus-4-5", mcp_servers=github_mcp, allowed_tools=["mcp__github"], # IMPORTANT: disallowed_tools is required to actually RESTRICT tool usage. # Without this, allowed_tools only controls permission prompting, not availability. # The agent would still have access to Bash (and could use `gh` CLI instead of MCP). disallowed_tools=["Bash", "Task", "WebSearch", "WebFetch"], permission_mode="acceptEdits", ) ) as agent: await agent.query(prompt) async for msg in agent.receive_response(): print_activity(msg) messages.append(msg) ``` ::: {.output .stream .stdout} 🤖 Using: mcp__github__get_file_contents() 🤖 Using: mcp__github__list_commits() ✓ Tool completed ✓ Tool completed 🤖 Thinking... 🤖 Using: mcp__github__get_file_contents() 🤖 Using: mcp__github__get_file_contents() 🤖 Using: mcp__github__list_pull_requests() ✓ Tool completed ✓ Tool completed ✓ Tool completed 🤖 Thinking... 🤖 Using: mcp__github__get_commit() 🤖 Using: mcp__github__get_commit() 🤖 Using: mcp__github__get_commit() 🤖 Using: mcp__github__pull_request_read() 🤖 Using: mcp__github__pull_request_read() 🤖 Using: mcp__github__pull_request_read() ✓ Tool completed ✓ Tool completed ✓ Tool completed ✓ Tool completed ✓ Tool completed ✓ Tool completed 🤖 Thinking... 🤖 Using: mcp__github__pull_request_read() 🤖 Using: mcp__github__pull_request_read() 🤖 Using: mcp__github__pull_request_read() 🤖 Using: mcp__github__pull_request_read() 🤖 Using: mcp__github__pull_request_read() ✓ Tool completed ✓ Tool completed ✓ Tool completed ✓ Tool completed ✓ Tool completed 🤖 Thinking... 🤖 Using: mcp__github__search_issues() 🤖 Using: mcp__github__search_issues() ✓ Tool completed ✓ Tool completed 🤖 Thinking... ::: :::: :::: {#49a39ed7 .cell .code execution_count="9"} ``` python display(Markdown(f"\nResult:\n{messages[-1].result}")) ``` ::: {.output .display_data} Result: Based on my comprehensive analysis of the facebook/react repository CI infrastructure, here is the operational summary: --- # CI Health Analysis: facebook/react ## Executive Summary **Overall Status: 🟢 HEALTHY** The React repository's CI appears to be in good health. Recent commits to `main` have been successfully merged, and active PRs show passing CodeSandbox builds. --- ## 1. CI Infrastructure Overview ### Primary Workflows | Workflow | Trigger | Purpose | |----------|---------|---------| | `runtime_build_and_test.yml` | Push to main, PRs | Main CI - builds, tests, Flow checks | | `shared_lint.yml` | Push to main, PRs | Prettier, ESLint, license checks | | `compiler_typescript.yml` | PRs touching compiler | Compiler-specific tests | | `devtools_regression_tests.yml` | PRs | DevTools testing | ### Test Matrix Scale - **90 test shards** (18 configurations × 5 shards each) - **50 build jobs** (25 workers × 2 release channels) - **50 test-build shards** (5 configurations × 10 shards) - Flow checks across multiple inline configs --- ## 2. Recent Main Branch Status | Commit | Date | Description | Status | |--------|------|-------------|--------| | `bf1afad` | Dec 4, 2025 | [react-dom/server] Fix hanging on Deno | ✅ Merged | | `0526c79` | Dec 3, 2025 | Update changelog with latest releases | ✅ Merged | | `7dc903c` | Dec 3, 2025 | Patch FlightReplyServer (security fix) | ✅ Merged | | `36df5e8` | Dec 2, 2025 | Allow building single release channel | ✅ Merged | **Last 10 commits:** All successfully merged to main, indicating CI is passing. --- ## 3. Active PR CI Status | PR | Title | CodeSandbox Status | |----|-------|-------------------| | #35267 | Fix spelling (behaviour → behavior) | 🟡 Pending (building) | | #35238 | DevTools navigating commits hotkey | ✅ Success | | #35287 | Compiler: Fix variable name issue | ✅ Success | | #35278 | Add DevTools console suppress option | ✅ Success | | #35226 | Fizz: Push stalled use() to ownerStack | ✅ Success | --- ## 4. Risk Assessment ### ✅ Positive Indicators - **Main branch stable**: All recent commits merged successfully - **No open CI failure issues**: Search returned zero CI-related open bugs - **Active development**: Security patches and features landing regularly - **PR builds passing**: Most open PRs show successful builds ### ⚠️ Areas to Monitor - **Large test matrix**: 190+ parallel jobs mean potential for infrastructure flakiness - **Playwright-based e2e tests**: Browser-based tests can be flaky (Flight fixtures, DevTools e2e) - **Cache dependencies**: Multiple cache strategies (v6 keys) - cache misses could slow builds ### 📊 CI Complexity Metrics - ~37KB workflow file for main CI (`runtime_build_and_test.yml`) - Heavy parallelization with matrix strategies - Multiple artifact upload/download operations --- ## 5. Recommended Actions | Priority | Action | Rationale | |----------|--------|-----------| | **LOW** | Monitor PR #35267 | Currently building - verify completion | | **LOW** | No immediate action required | Main branch healthy, PRs passing | | **INFO** | Security patch merged Dec 3 | PR #35277 fixed critical security vuln in FlightReplyServer - verify downstream impact | --- ## 6. On-Call Notes **TL;DR for On-Call Engineer:** - 🟢 **CI is GREEN** - No action required - Main branch is healthy with successful merges in last 24h - All checked PRs showing green/passing status - No open issues flagged for CI failures or flakiness - Recent security patch (#35277) was successfully merged - monitor for any regressions **If issues arise:** 1. Check GitHub Actions tab directly: `https://github.com/facebook/react/actions` 2. Key workflows to monitor: "(Runtime) Build and Test", "(Shared) Lint" 3. Caches use `v6` key prefix - if widespread failures, consider cache invalidation --- *Analysis performed: December 4, 2025* *Data sources: GitHub API (commits, PRs, status checks, workflow files)* ::: :::: :::: {#827dc192 .cell .code execution_count="10"} ``` python reset_activity_context() visualize_conversation(messages) ``` ::: {.output .display_data}
🤖 Agent Conversation Timeline • claude-opus-4-5
⚙️ System
Initialized (a500627f...)
🔧 Tools
mcp__github__get_file_contentsmcp__github__list_commits
🤖 Assistant

I can see the React repository uses GitHub Actions with several workflows. Let me check the main CI workflows and their recent status. The primary CI workflow appears to be runtime_build_and_test.yml. Let me examine the workflow files and search for any "CI" named workflows.

🔧 Tools
mcp__github__get_file_contentsmcp__github__get_file_contentsmcp__github__list_pull_requests
🤖 Assistant

I can see React repository uses several workflows. The main CI workflow is runtime_build_and_test.yml which triggers on push to main and PRs. Let me get the CI status for recent commits to assess the health:

🔧 Tools
mcp__github__get_commitmcp__github__get_commitmcp__github__get_commitmcp__github__pull_request_readmcp__github__pull_request_readmcp__github__pull_request_read
🤖 Assistant

Let me get more detailed CI status information by checking the status checks on recent PRs and the main branch:

🔧 Tools
mcp__github__pull_request_readmcp__github__pull_request_readmcp__github__pull_request_readmcp__github__pull_request_readmcp__github__pull_request_read
🤖 Assistant

The GitHub API status checks only show CodeSandbox status. Let me search for any recent failing CI issues to get a complete picture:

🔧 Tools
mcp__github__search_issuesmcp__github__search_issues
🤖 Assistant

Based on my comprehensive analysis of the facebook/react repository CI infrastructure, here is the operational summary:

CI Health Analysis: facebook/react

Executive Summary

Overall Status: 🟢 HEALTHY

The React repository's CI appears to be in good health. Recent commits to main have been successfully merged, and active PRs show passing CodeSandbox builds.

1. CI Infrastructure Overview

Primary Workflows

Workflow Trigger Purpose
runtime_build_and_test.yml Push to main, PRs Main CI - builds, tests, Flow checks
shared_lint.yml Push to main, PRs Prettier, ESLint, license checks
compiler_typescript.yml PRs touching compiler Compiler-specific tests
devtools_regression_tests.yml PRs DevTools testing

Test Matrix Scale

  • 90 test shards (18 configurations × 5 shards each)
  • 50 build jobs (25 workers × 2 release channels)
  • 50 test-build shards (5 configurations × 10 shards)
  • Flow checks across multiple inline configs

2. Recent Main Branch Status

Commit Date Description Status
bf1afad Dec 4, 2025 [react-dom/server] Fix hanging on Deno ✅ Merged
0526c79 Dec 3, 2025 Update changelog with latest releases ✅ Merged
7dc903c Dec 3, 2025 Patch FlightReplyServer (security fix) ✅ Merged
36df5e8 Dec 2, 2025 Allow building single release channel ✅ Merged

Last 10 commits: All successfully merged to main, indicating CI is passing.

3. Active PR CI Status

PR Title CodeSandbox Status
#35267 Fix spelling (behaviour → behavior) 🟡 Pending (building)
#35238 DevTools navigating commits hotkey ✅ Success
#35287 Compiler: Fix variable name issue ✅ Success
#35278 Add DevTools console suppress option ✅ Success
#35226 Fizz: Push stalled use() to ownerStack ✅ Success

4. Risk Assessment

✅ Positive Indicators

  • Main branch stable: All recent commits merged successfully
  • No open CI failure issues: Search returned zero CI-related open bugs
  • Active development: Security patches and features landing regularly
  • PR builds passing: Most open PRs show successful builds

⚠️ Areas to Monitor

  • Large test matrix: 190+ parallel jobs mean potential for infrastructure flakiness
  • Playwright-based e2e tests: Browser-based tests can be flaky (Flight fixtures, DevTools e2e)
  • Cache dependencies: Multiple cache strategies (v6 keys) - cache misses could slow builds

📊 CI Complexity Metrics

  • ~37KB workflow file for main CI (runtime_build_and_test.yml)
  • Heavy parallelization with matrix strategies
  • Multiple artifact upload/download operations

5. Recommended Actions

Priority Action Rationale
LOW Monitor PR #35267 Currently building - verify completion
LOW No immediate action required Main branch healthy, PRs passing
INFO Security patch merged Dec 3 PR #35277 fixed critical security vuln in FlightReplyServer - verify downstream impact

6. On-Call Notes

TL;DR for On-Call Engineer:
- 🟢 CI is GREEN - No action required
- Main branch is healthy with successful merges in last 24h
- All checked PRs showing green/passing status
- No open issues flagged for CI failures or flakiness
- Recent security patch (#35277) was successfully merged - monitor for any regressions

If issues arise:
1. Check GitHub Actions tab directly: https://github.com/facebook/react/actions
2. Key workflows to monitor: "(Runtime) Build and Test", "(Shared) Lint"
3. Caches use v6 key prefix - if widespread failures, consider cache invalidation

Analysis performed: December 4, 2025
Data sources: GitHub API (commits, PRs, status checks, workflow files)

✅ Complete
Turns: 19 Tokens: 42,191 Cost: $0.83 Duration: 89.2s
::: :::: :::: {#9e3ed49f .cell .code execution_count="11"} ``` python reset_activity_context() display_agent_response(messages) ``` ::: {.output .display_data}
Agent Response

Based on my comprehensive analysis of the facebook/react repository CI infrastructure, here is the operational summary:

CI Health Analysis: facebook/react

Executive Summary

Overall Status: 🟢 HEALTHY

The React repository's CI appears to be in good health. Recent commits to main have been successfully merged, and active PRs show passing CodeSandbox builds.

1. CI Infrastructure Overview

Primary Workflows

Workflow Trigger Purpose
runtime_build_and_test.yml Push to main, PRs Main CI - builds, tests, Flow checks
shared_lint.yml Push to main, PRs Prettier, ESLint, license checks
compiler_typescript.yml PRs touching compiler Compiler-specific tests
devtools_regression_tests.yml PRs DevTools testing

Test Matrix Scale

  • 90 test shards (18 configurations × 5 shards each)
  • 50 build jobs (25 workers × 2 release channels)
  • 50 test-build shards (5 configurations × 10 shards)
  • Flow checks across multiple inline configs

2. Recent Main Branch Status

Commit Date Description Status
bf1afad Dec 4, 2025 [react-dom/server] Fix hanging on Deno ✅ Merged
0526c79 Dec 3, 2025 Update changelog with latest releases ✅ Merged
7dc903c Dec 3, 2025 Patch FlightReplyServer (security fix) ✅ Merged
36df5e8 Dec 2, 2025 Allow building single release channel ✅ Merged

Last 10 commits: All successfully merged to main, indicating CI is passing.

3. Active PR CI Status

PR Title CodeSandbox Status
#35267 Fix spelling (behaviour → behavior) 🟡 Pending (building)
#35238 DevTools navigating commits hotkey ✅ Success
#35287 Compiler: Fix variable name issue ✅ Success
#35278 Add DevTools console suppress option ✅ Success
#35226 Fizz: Push stalled use() to ownerStack ✅ Success

4. Risk Assessment

✅ Positive Indicators

  • Main branch stable: All recent commits merged successfully
  • No open CI failure issues: Search returned zero CI-related open bugs
  • Active development: Security patches and features landing regularly
  • PR builds passing: Most open PRs show successful builds

⚠️ Areas to Monitor

  • Large test matrix: 190+ parallel jobs mean potential for infrastructure flakiness
  • Playwright-based e2e tests: Browser-based tests can be flaky (Flight fixtures, DevTools e2e)
  • Cache dependencies: Multiple cache strategies (v6 keys) - cache misses could slow builds

📊 CI Complexity Metrics

  • ~37KB workflow file for main CI (runtime_build_and_test.yml)
  • Heavy parallelization with matrix strategies
  • Multiple artifact upload/download operations

5. Recommended Actions

Priority Action Rationale
LOW Monitor PR #35267 Currently building - verify completion
LOW No immediate action required Main branch healthy, PRs passing
INFO Security patch merged Dec 3 PR #35277 fixed critical security vuln in FlightReplyServer - verify downstream impact

6. On-Call Notes

TL;DR for On-Call Engineer:
- 🟢 CI is GREEN - No action required
- Main branch is healthy with successful merges in last 24h
- All checked PRs showing green/passing status
- No open issues flagged for CI failures or flakiness
- Recent security patch (#35277) was successfully merged - monitor for any regressions

If issues arise:
1. Check GitHub Actions tab directly: https://github.com/facebook/react/actions
2. Key workflows to monitor: "(Runtime) Build and Test", "(Shared) Lint"
3. Caches use v6 key prefix - if widespread failures, consider cache invalidation

Analysis performed: December 4, 2025
Data sources: GitHub API (commits, PRs, status checks, workflow files)

::: :::: ::: {#80cd321f .cell .markdown} ### Observability Agent as Module The `observability_agent/agent.py` module wraps the observability pattern into a reusable `send_query` function. It imports and uses the shared visualization utilities from `utils.agent_visualizer` internally: - **`reset_activity_context()`**: Called automatically at the start of each query - **`print_activity()`**: Provides real-time feedback during execution - **`display_agent_response()`**: Renders the final result (controlled by `display_result` parameter) This means you can use the module with minimal code: ::: ::::: {#97074fe7 .cell .code execution_count="12"} ``` python # Reload the module to pick up any changes (useful during development) from observability_agent.agent import send_query # The module handles activity display, context reset, and result visualization internally result = await send_query( "Check the CI status for the last 2 runs in anthropics/claude-agent-sdk-python. Just do 3 tool calls, be efficient." ) ``` ::: {.output .stream .stdout} 🤖 Using: mcp__github__list_commits() ✓ Tool completed 🤖 Using: mcp__github__get_commit() 🤖 Using: mcp__github__get_commit() ✓ Tool completed ✓ Tool completed 🤖 Thinking... ::: ::: {.output .display_data}
Agent Response

CI Status Summary for anthropics/claude-agent-sdk-python

Commit Message Date Status
2437035 chore: bump bundled CLI version to 2.0.58 Dec 3, 2025 20:09 UTC ⚠️ No CI status available
9809fb6 chore: release v0.1.11 (#383) Dec 3, 2025 19:42 UTC ⚠️ No CI status available

Note: The GitHub API response doesn't include explicit CI/check status data. This typically means:
1. CI hasn't been triggered on these commits (both are automated commits from GitHub Actions)
2. The checks aren't exposed via the commit API endpoint

Recommendation: To get detailed CI run information, you'd need to check:
- GitHub Actions tab directly: https://github.com/anthropics/claude-agent-sdk-python/actions
- Or query the Checks API specifically for workflow runs

Both commits are automated maintenance commits (CLI bump and release version update), so they may intentionally skip full CI runs.

::: ::::: ::: {#0c1578dc .cell .markdown} Multi-turn conversations work seamlessly - just pass `continue_conversation=True`: ::: ::::: {#7914f8db .cell .code execution_count="13"} ``` python # Example 2: Multi-turn conversation for deeper monitoring result1 = await send_query("What's the current CI status for facebook/react?") ``` ::: {.output .stream .stdout} 🤖 Using: mcp__github__list_pull_requests() 🤖 Using: mcp__github__list_commits() ✓ Tool completed ✓ Tool completed 🤖 Thinking... 🤖 Using: mcp__github__pull_request_read() 🤖 Using: mcp__github__pull_request_read() 🤖 Using: mcp__github__pull_request_read() 🤖 Using: mcp__github__get_commit() ✓ Tool completed ✓ Tool completed ✓ Tool completed ✓ Tool completed 🤖 Thinking... ::: ::: {.output .display_data}
Agent Response

CI Status Summary for facebook/react

🟢 Main Branch Status: HEALTHY

Latest Commit on main:
- SHA: bf1afade
- Message: [react-dom/server] Fix hanging on Deno (#35235)
- Author: @fraidev
- Date: Dec 4, 2025 05:50 UTC

Open Pull Requests CI Status

PR Title Author CI Status Updated
#35287 [compiler] Fix JSX variable name issue @kostya-gromov 🟢 Success 2h ago
#35285 [compiler][poc] Reuse ValidateExhaustiveDeps @josephsavona 🔵 Draft 6h ago
#35284 [compiler] Fix hoisted primitives bug @josephsavona 🟢 Success 7h ago
#35282 [compiler] Add effect deps validator @jackpope 🟢 Success 15h ago
#35281 Improve legacy context warning @Harshrj53 🟢 Success 20h ago

Key Observations

  • ✅ No CI failures detected on recent PRs
  • ✅ All CodeSandbox builds passing
  • ⚠️ Recent security fix merged: #35277 addresses a critical security vulnerability in FlightReplyServer

Recent Notable Commits

  1. Security patch - FlightReplyServer fix for cycles and deferred error handling
  2. Deno fix - react-dom/server hanging issue resolved
  3. Compiler improvements - Multiple fixes for React Compiler validation

Assessment: CI is stable. No immediate action required.

::: ::::: ::::: {#8014a701 .cell .code execution_count="14"} ``` python # Continue the conversation to dig deeper result2 = await send_query( "Are there any flaky tests in the recent failures? You can only make one tool call.", continue_conversation=True, ) ``` ::: {.output .stream .stdout} 🤖 Using: mcp__github__search_issues() ✓ Tool completed 🤖 Thinking... ::: ::: {.output .display_data}
Agent Response

Flaky Test Analysis for facebook/react

Result: No known flaky tests tracked

The search returned 0 open issues related to flaky tests, test flakes, or intermittent failures in the repository.

Assessment

Metric Status
Open flaky test issues 0
Recent CI failures None detected
Test stability ✅ Stable

Interpretation

  1. Good news: No currently tracked flaky test issues in the open issue tracker
  2. The React team appears to be on top of test reliability
  3. Based on the earlier CI check, all recent PRs show passing builds

Caveats

  • Flaky tests may be tracked internally (Meta's internal systems)
  • Some flakes might be handled via suppression/retry mechanisms
  • The team may use different labeling conventions

Recommendation: CI appears healthy with no actionable flaky test issues at this time.

::: ::::: ::: {#5a2f48f7 .cell .markdown} ## Conclusion We\'ve demonstrated how the Claude Code SDK enables seamless integration with external systems through the Model Context Protocol (MCP). Starting with local Git operations through the Git MCP server, we progressively expanded to full GitHub platform integration with access to over 100 GitHub-specific tools. This transformed our agent from a local assistant into a powerful observability system capable of monitoring workflows, analyzing CI/CD failures, and providing actionable insights for production systems. By connecting MCP servers to our agent, we created an autonomous observability system that monitors GitHub Actions workflows, distinguishes between real failures and security restrictions, and provides detailed analysis of test failures. The system demonstrates how agents can actively participate in your DevOps workflow, moving from passive monitoring to intelligent incident response. This concludes, for now, our journey through the Claude Code SDK tutorial series. We\'ve progressed from simple research agents to sophisticated multi-agent orchestration, and finally to external system integration through MCP. Together, these patterns provide the foundation for building production-ready agentic systems that can handle real-world complexity while maintaining governance, compliance, and observability. ### What You\'ve Learned Across All Notebooks **From Notebook 00 (Research Agent)** - Core SDK fundamentals with `query()` and `ClaudeSDKClient` - Basic tool usage with WebSearch and Read - Simple agent loops and conversation management **From Notebook 01 (Chief of Staff)** - Advanced features: memory, output styles, planning mode - Multi-agent coordination through subagents - Governance through hooks and custom commands - Enterprise-ready agent architectures **From Notebook 02 (Observability Agent)** - External system integration via MCP servers - Real-time monitoring and incident response - Production workflow automation - Scalable agent deployment patterns The complete implementations for all three agents are available in their respective directories (`research_agent/`, `chief_of_staff_agent/`, `observability_agent/`), ready to serve as inspiration for integrations into your production systems. ::: --- ## advanced-workflows.md # Advanced Workflow Patterns Multi-step command sequences and composition patterns for complex workflows. ## Overview Advanced workflows combine multiple commands, coordinate state across invocations, and create sophisticated automation sequences. These patterns enable building complex functionality from simple command building blocks. ## Multi-Step Command Patterns ### Sequential Workflow Command Commands that guide users through multi-step processes: ```markdown --- description: Complete PR review workflow argument-hint: [pr-number] allowed-tools: Bash(gh:*), Read, Grep --- # PR Review Workflow for #$1 ## Step 1: Fetch PR Details !`gh pr view $1 --json title,body,author,files` ## Step 2: Review Files Files changed: !`gh pr diff $1 --name-only` For each file: - Check code quality - Verify tests exist - Review documentation ## Step 3: Run Checks Test status: !`gh pr checks $1` Verify: - All tests passing - No merge conflicts - CI/CD successful ## Step 4: Provide Feedback Summarize: - Issues found (critical/minor) - Suggestions for improvement - Approval recommendation Would you like to: 1. Approve PR 2. Request changes 3. Leave comments only Reply with your choice and I'll help complete the action. ``` **Key features:** - Numbered steps for clarity - Bash execution for context - Decision points for user input - Next action suggestions ### State-Carrying Workflow Commands that maintain state between invocations: ```markdown --- description: Initialize deployment workflow allowed-tools: Write, Bash(git:*) --- # Initialize Deployment Creating deployment tracking file... Current branch: !`git branch --show-current` Latest commit: !`git log -1 --format=%H` Deployment state saved to `.claude/deployment-state.local.md`: \`\`\`markdown --- initialized: true branch: $(git branch --show-current) commit: $(git log -1 --format=%H) timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ) status: initialized --- # Deployment Tracking Branch: $(git branch --show-current) Started: $(date) Next steps: 1. Run tests: /deploy-test 2. Build: /deploy-build 3. Deploy: /deploy-execute \`\`\` State saved. Run `/deploy-test` to continue. ``` **Next command** (`/deploy-test`): ```markdown --- description: Run deployment tests allowed-tools: Read, Bash(npm:*) --- Reading deployment state from `.claude/deployment-state.local.md`... Running tests: !`npm test` Updating state to 'tested'... Tests complete. Run `/deploy-build` to continue. ``` **Pattern benefits:** - Persistent state across commands - Clear workflow progression - Safety checkpoints - Resume capability ### Conditional Workflow Branching Commands that adapt based on conditions: ```markdown --- description: Smart deployment workflow argument-hint: [environment] allowed-tools: Bash(git:*), Bash(npm:*), Read --- # Deploy to $1 ## Pre-flight Checks Branch: !`git branch --show-current` Status: !`git status --short` **Checking conditions:** 1. Branch status: - If main/master: Require approval - If feature branch: Warning about target - If hotfix: Fast-track process 2. Tests: !`npm test` - If tests fail: STOP - fix tests first - If tests pass: Continue 3. Environment: - If $1 = 'production': Extra validation - If $1 = 'staging': Standard process - If $1 = 'dev': Minimal checks **Workflow decision:** Based on above, proceeding with: [determined workflow] [Conditional steps based on environment and status] Ready to deploy? (yes/no) ``` ## Command Composition Patterns ### Command Chaining Commands designed to work together: ```markdown --- description: Prepare for code review --- # Prepare Code Review Running preparation sequence: 1. Format code: /format-code 2. Run linter: /lint-code 3. Run tests: /test-all 4. Generate coverage: /coverage-report 5. Create review summary: /review-summary This is a meta-command. After completing each step above, I'll compile results and prepare comprehensive review materials. Starting sequence... ``` **Individual commands** are simple: - `/format-code` - Just formats - `/lint-code` - Just lints - `/test-all` - Just tests **Composition command** orchestrates them. ### Pipeline Pattern Commands that process output from previous commands: ```markdown --- description: Analyze test failures --- # Analyze Test Failures ## Step 1: Get test results (Run /test-all first if not done) Reading test output... ## Step 2: Categorize failures - Flaky tests (random failures) - Consistent failures - New failures vs existing ## Step 3: Prioritize Rank by: - Impact (critical path vs edge case) - Frequency (always fails vs sometimes) - Effort (quick fix vs major work) ## Step 4: Generate fix plan For each failure: - Root cause hypothesis - Suggested fix approach - Estimated effort Would you like me to: 1. Fix highest priority failure 2. Generate detailed fix plans for all 3. Create GitHub issues for each ``` ### Parallel Execution Pattern Commands that coordinate multiple simultaneous operations: ```markdown --- description: Run comprehensive validation allowed-tools: Bash(*), Read --- # Comprehensive Validation Running validations in parallel... Starting: - Code quality checks - Security scanning - Dependency audit - Performance profiling This will take 2-3 minutes. I'll monitor all processes and report when complete. [Poll each process and report progress] All validations complete. Summary: - Quality: PASS (0 issues) - Security: WARN (2 minor issues) - Dependencies: PASS - Performance: PASS (baseline met) Details: [Collated results from all checks] ``` ## Workflow State Management ### Using .local.md Files Store workflow state in plugin-specific files: ```markdown .claude/plugin-name-workflow.local.md: --- workflow: deployment stage: testing started: 2025-01-15T10:30:00Z environment: staging branch: feature/new-api commit: abc123def tests_passed: false build_complete: false --- # Deployment Workflow State Current stage: Testing Started: 2025-01-15 10:30 UTC Completed steps: - ✅ Validation - ✅ Branch check - ⏳ Testing (in progress) Pending steps: - Build - Deploy - Smoke tests ``` **Reading state in commands:** ```markdown --- description: Continue deployment workflow allowed-tools: Read, Write --- Reading workflow state from .claude/plugin-name-workflow.local.md... Current stage: @.claude/plugin-name-workflow.local.md [Parse YAML frontmatter to determine next step] Next action based on state: [determined action] ``` ### Workflow Recovery Handle interrupted workflows: ```markdown --- description: Resume deployment workflow allowed-tools: Read --- # Resume Deployment Checking for interrupted workflow... State file: @.claude/plugin-name-workflow.local.md **Workflow found:** - Started: [timestamp] - Environment: [env] - Last completed: [step] **Recovery options:** 1. Resume from last step 2. Restart from beginning 3. Abort and clean up Which would you like? (1/2/3) ``` ## Workflow Coordination Patterns ### Cross-Command Communication Commands that signal each other: ```markdown --- description: Mark feature complete allowed-tools: Write --- # Mark Feature Complete Writing completion marker... Creating: .claude/feature-complete.flag This signals other commands that feature is ready for: - Integration testing (/integration-test will auto-detect) - Documentation generation (/docs-generate will include) - Release notes (/release-notes will add) Feature marked complete. ``` **Other commands check for flag:** ```markdown --- description: Generate release notes allowed-tools: Read, Bash(git:*) --- Checking for completed features... if [ -f .claude/feature-complete.flag ]; then Feature ready for release notes fi [Include in release notes] ``` ### Workflow Locking Prevent concurrent workflow execution: ```markdown --- description: Start deployment allowed-tools: Read, Write, Bash --- # Start Deployment Checking for active deployments... if [ -f .claude/deployment.lock ]; then ERROR: Deployment already in progress Started: [timestamp from lock file] Cannot start concurrent deployment. Wait for completion or run /deployment-abort Exit. fi Creating deployment lock... Deployment started. Lock created. [Proceed with deployment] ``` **Lock cleanup:** ```markdown --- description: Complete deployment allowed-tools: Write, Bash --- Deployment complete. Removing deployment lock... rm .claude/deployment.lock Ready for next deployment. ``` ## Advanced Argument Handling ### Optional Arguments with Defaults ```markdown --- description: Deploy with optional version argument-hint: [environment] [version] --- Environment: ${1:-staging} Version: ${2:-latest} Deploying ${2:-latest} to ${1:-staging}... Note: Using defaults for missing arguments: - Environment defaults to 'staging' - Version defaults to 'latest' ``` ### Argument Validation ```markdown --- description: Deploy to validated environment argument-hint: [environment] --- Environment: $1 Validating environment... valid_envs="dev staging production" if ! echo "$valid_envs" | grep -w "$1" > /dev/null; then ERROR: Invalid environment '$1' Valid options: dev, staging, production Exit. fi Environment validated. Proceeding... ``` ### Argument Transformation ```markdown --- description: Deploy with shorthand argument-hint: [env-shorthand] --- Input: $1 Expanding shorthand: - d/dev → development - s/stg → staging - p/prod → production case "$1" in d|dev) ENV="development";; s|stg) ENV="staging";; p|prod) ENV="production";; *) ENV="$1";; esac Deploying to: $ENV ``` ## Error Handling in Workflows ### Graceful Failure ```markdown --- description: Resilient deployment workflow --- # Deployment Workflow Running steps with error handling... ## Step 1: Tests !`npm test` if [ $? -ne 0 ]; then ERROR: Tests failed Options: 1. Fix tests and retry 2. Skip tests (NOT recommended) 3. Abort deployment What would you like to do? [Wait for user input before continuing] fi ## Step 2: Build [Continue only if Step 1 succeeded] ``` ### Rollback on Failure ```markdown --- description: Deployment with rollback --- # Deploy with Rollback Saving current state for rollback... Previous version: !`current-version.sh` Deploying new version... !`deploy.sh` if [ $? -ne 0 ]; then DEPLOYMENT FAILED Initiating automatic rollback... !`rollback.sh` Rolled back to previous version. Check logs for failure details. fi Deployment complete. ``` ### Checkpoint Recovery ```markdown --- description: Workflow with checkpoints --- # Multi-Stage Deployment ## Checkpoint 1: Validation !`validate.sh` echo "checkpoint:validation" >> .claude/deployment-checkpoints.log ## Checkpoint 2: Build !`build.sh` echo "checkpoint:build" >> .claude/deployment-checkpoints.log ## Checkpoint 3: Deploy !`deploy.sh` echo "checkpoint:deploy" >> .claude/deployment-checkpoints.log If any step fails, resume with: /deployment-resume [last-successful-checkpoint] ``` ## Best Practices ### Workflow Design 1. **Clear progression**: Number steps, show current position 2. **Explicit state**: Don't rely on implicit state 3. **User control**: Provide decision points 4. **Error recovery**: Handle failures gracefully 5. **Progress indication**: Show what's done, what's pending ### Command Composition 1. **Single responsibility**: Each command does one thing well 2. **Composable design**: Commands work together easily 3. **Standard interfaces**: Consistent input/output formats 4. **Loose coupling**: Commands don't depend on each other's internals ### State Management 1. **Persistent state**: Use .local.md files 2. **Atomic updates**: Write complete state files atomically 3. **State validation**: Check state file format/completeness 4. **Cleanup**: Remove stale state files 5. **Documentation**: Document state file formats ### Error Handling 1. **Fail fast**: Detect errors early 2. **Clear messages**: Explain what went wrong 3. **Recovery options**: Provide clear next steps 4. **State preservation**: Keep state for recovery 5. **Rollback capability**: Support undoing changes ## Example: Complete Deployment Workflow ### Initialize Command ```markdown --- description: Initialize deployment argument-hint: [environment] allowed-tools: Write, Bash(git:*) --- # Initialize Deployment to $1 Creating workflow state... \`\`\`yaml --- workflow: deployment environment: $1 branch: !`git branch --show-current` commit: !`git rev-parse HEAD` stage: initialized timestamp: !`date -u +%Y-%m-%dT%H:%M:%SZ` --- \`\`\` Written to .claude/deployment-state.local.md Next: Run /deployment-validate ``` ### Validation Command ```markdown --- description: Validate deployment allowed-tools: Read, Bash --- Reading state: @.claude/deployment-state.local.md Running validation... - Branch check: PASS - Tests: PASS - Build: PASS Updating state to 'validated'... Next: Run /deployment-execute ``` ### Execution Command ```markdown --- description: Execute deployment allowed-tools: Read, Bash, Write --- Reading state: @.claude/deployment-state.local.md Executing deployment to [environment]... !`deploy.sh [environment]` Deployment complete. Updating state to 'completed'... Cleanup: /deployment-cleanup ``` ### Cleanup Command ```markdown --- description: Clean up deployment allowed-tools: Bash --- Removing deployment state... rm .claude/deployment-state.local.md Deployment workflow complete. ``` This complete workflow demonstrates state management, sequential execution, error handling, and clean separation of concerns across multiple commands. --- ## agent-creation-prompt.md # AI-Assisted Agent Generation Template Use this template to generate agents using Claude with the agent creation system prompt. ## Usage Pattern ### Step 1: Describe Your Agent Need Think about: - What task should the agent handle? - When should it be triggered? - Should it be proactive or reactive? - What are the key responsibilities? ### Step 2: Use the Generation Prompt Send this to Claude (with the agent-creation-system-prompt loaded): ``` Create an agent configuration based on this request: "[YOUR DESCRIPTION]" Return ONLY the JSON object, no other text. ``` **Replace [YOUR DESCRIPTION] with your agent requirements.** ### Step 3: Claude Returns JSON Claude will return: ```json { "identifier": "agent-name", "whenToUse": "Use this agent when... Examples: ...", "systemPrompt": "You are... **Your Core Responsibilities:**..." } ``` ### Step 4: Convert to Agent File Create `agents/[identifier].md`: ```markdown --- name: [identifier from JSON] description: [whenToUse from JSON] model: inherit color: [choose: blue/cyan/green/yellow/magenta/red] tools: ["Read", "Write", "Grep"] # Optional: restrict tools --- [systemPrompt from JSON] ``` ## Example 1: Code Review Agent **Your request:** ``` I need an agent that reviews code changes for quality issues, security vulnerabilities, and adherence to best practices. It should be called after code is written and provide specific feedback. ``` **Claude generates:** ```json { "identifier": "code-quality-reviewer", "whenToUse": "Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Examples:\n\n\nContext: User just implemented a new feature\nuser: \"I've added the authentication feature\"\nassistant: \"Great! Let me review the code quality.\"\n\nCode was written, trigger code-quality-reviewer agent for review.\n\nassistant: \"I'll use the code-quality-reviewer agent to analyze the changes.\"\n\n\n\nContext: User explicitly requests review\nuser: \"Can you review my code for issues?\"\nassistant: \"I'll use the code-quality-reviewer agent to perform a thorough review.\"\n\nExplicit review request triggers the agent.\n\n", "systemPrompt": "You are an expert code quality reviewer specializing in identifying issues in software implementations.\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues (readability, maintainability, performance)\n2. Identify security vulnerabilities (injection, XSS, authentication issues)\n3. Check adherence to project best practices and coding standards\n4. Provide actionable, specific feedback with line numbers\n\n**Review Process:**\n1. Read the code changes using available tools\n2. Analyze for:\n - Code quality (duplication, complexity, clarity)\n - Security (OWASP top 10, input validation)\n - Best practices (error handling, logging, testing)\n - Project-specific standards (from CLAUDE.md)\n3. Identify issues with severity (critical/major/minor)\n4. Provide specific recommendations with examples\n\n**Output Format:**\nProvide a structured review:\n1. Summary (2-3 sentences)\n2. Critical Issues (must fix)\n3. Major Issues (should fix)\n4. Minor Issues (nice to fix)\n5. Positive observations\n6. Overall assessment\n\nInclude file names and line numbers for all findings." } ``` **You create:** File: `agents/code-quality-reviewer.md` ```markdown --- name: code-quality-reviewer description: Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Examples: Context: User just implemented a new feature user: "I've added the authentication feature" assistant: "Great! Let me review the code quality." Code was written, trigger code-quality-reviewer agent for review. assistant: "I'll use the code-quality-reviewer agent to analyze the changes." Context: User explicitly requests review user: "Can you review my code for issues?" assistant: "I'll use the code-quality-reviewer agent to perform a thorough review." Explicit review request triggers the agent. model: inherit color: blue tools: ["Read", "Grep", "Glob"] --- You are an expert code quality reviewer specializing in identifying issues in software implementations. **Your Core Responsibilities:** 1. Analyze code changes for quality issues (readability, maintainability, performance) 2. Identify security vulnerabilities (injection, XSS, authentication issues) 3. Check adherence to project best practices and coding standards 4. Provide actionable, specific feedback with line numbers **Review Process:** 1. Read the code changes using available tools 2. Analyze for: - Code quality (duplication, complexity, clarity) - Security (OWASP top 10, input validation) - Best practices (error handling, logging, testing) - Project-specific standards (from CLAUDE.md) 3. Identify issues with severity (critical/major/minor) 4. Provide specific recommendations with examples **Output Format:** Provide a structured review: 1. Summary (2-3 sentences) 2. Critical Issues (must fix) 3. Major Issues (should fix) 4. Minor Issues (nice to fix) 5. Positive observations 6. Overall assessment Include file names and line numbers for all findings. ``` ## Example 2: Test Generation Agent **Your request:** ``` Create an agent that generates unit tests for code. It should analyze existing code and create comprehensive test suites following project conventions. ``` **Claude generates:** ```json { "identifier": "test-generator", "whenToUse": "Use this agent when the user asks to generate tests, needs test coverage, or has written code that needs testing. Examples:\n\n\nContext: User wrote new functions without tests\nuser: \"I've implemented the user authentication functions\"\nassistant: \"Great! Let me generate tests for these functions.\"\n\nNew code without tests, proactively trigger test-generator.\n\nassistant: \"I'll use the test-generator agent to create comprehensive tests.\"\n", "systemPrompt": "You are an expert test engineer specializing in creating comprehensive unit tests...\n\n**Your Core Responsibilities:**\n1. Analyze code to understand behavior\n2. Generate test cases covering happy paths and edge cases\n3. Follow project testing conventions\n4. Ensure high code coverage\n\n**Test Generation Process:**\n1. Read target code\n2. Identify testable units (functions, classes, methods)\n3. Design test cases (inputs, expected outputs, edge cases)\n4. Generate tests following project patterns\n5. Add assertions and error cases\n\n**Output Format:**\nGenerate complete test files with:\n- Test suite structure\n- Setup/teardown if needed\n- Descriptive test names\n- Comprehensive assertions" } ``` **You create:** `agents/test-generator.md` with the structure above. ## Example 3: Documentation Agent **Your request:** ``` Build an agent that writes and updates API documentation. It should analyze code and generate clear, comprehensive docs. ``` **Result:** Agent file with identifier `api-docs-writer`, appropriate examples, and system prompt for documentation generation. ## Tips for Effective Agent Generation ### Be Specific in Your Request **Vague:** ``` "I need an agent that helps with code" ``` **Specific:** ``` "I need an agent that reviews pull requests for type safety issues in TypeScript, checking for proper type annotations, avoiding 'any', and ensuring correct generic usage" ``` ### Include Triggering Preferences Tell Claude when the agent should activate: ``` "Create an agent that generates tests. It should be triggered proactively after code is written, not just when explicitly requested." ``` ### Mention Project Context ``` "Create a code review agent. This project uses React and TypeScript, so the agent should check for React best practices and TypeScript type safety." ``` ### Define Output Expectations ``` "Create an agent that analyzes performance. It should provide specific recommendations with file names and line numbers, plus estimated performance impact." ``` ## Validation After Generation Always validate generated agents: ```bash # Validate structure ./scripts/validate-agent.sh agents/your-agent.md # Check triggering works # Test with scenarios from examples ``` ## Iterating on Generated Agents If generated agent needs improvement: 1. Identify what's missing or wrong 2. Manually edit the agent file 3. Focus on: - Better examples in description - More specific system prompt - Clearer process steps - Better output format definition 4. Re-validate 5. Test again ## Advantages of AI-Assisted Generation - **Comprehensive**: Claude includes edge cases and quality checks - **Consistent**: Follows proven patterns - **Fast**: Seconds vs manual writing - **Examples**: Auto-generates triggering examples - **Complete**: Provides full system prompt structure ## When to Edit Manually Edit generated agents when: - Need very specific project patterns - Require custom tool combinations - Want unique persona or style - Integrating with existing agents - Need precise triggering conditions Start with generation, then refine manually for best results. --- ## agent-creation-system-prompt.md # Agent Creation System Prompt This is the exact system prompt used by Claude Code's agent generation feature, refined through extensive production use. ## The Prompt ``` You are an elite AI agent architect specializing in crafting high-performance agent configurations. Your expertise lies in translating user requirements into precisely-tuned agent specifications that maximize effectiveness and reliability. **Important Context**: You may have access to project-specific instructions from CLAUDE.md files and other context that may include coding standards, project structure, and custom requirements. Consider this context when creating agents to ensure they align with the project's established patterns and practices. When a user describes what they want an agent to do, you will: 1. **Extract Core Intent**: Identify the fundamental purpose, key responsibilities, and success criteria for the agent. Look for both explicit requirements and implicit needs. Consider any project-specific context from CLAUDE.md files. For agents that are meant to review code, you should assume that the user is asking to review recently written code and not the whole codebase, unless the user has explicitly instructed you otherwise. 2. **Design Expert Persona**: Create a compelling expert identity that embodies deep domain knowledge relevant to the task. The persona should inspire confidence and guide the agent's decision-making approach. 3. **Architect Comprehensive Instructions**: Develop a system prompt that: - Establishes clear behavioral boundaries and operational parameters - Provides specific methodologies and best practices for task execution - Anticipates edge cases and provides guidance for handling them - Incorporates any specific requirements or preferences mentioned by the user - Defines output format expectations when relevant - Aligns with project-specific coding standards and patterns from CLAUDE.md 4. **Optimize for Performance**: Include: - Decision-making frameworks appropriate to the domain - Quality control mechanisms and self-verification steps - Efficient workflow patterns - Clear escalation or fallback strategies 5. **Create Identifier**: Design a concise, descriptive identifier that: - Uses lowercase letters, numbers, and hyphens only - Is typically 2-4 words joined by hyphens - Clearly indicates the agent's primary function - Is memorable and easy to type - Avoids generic terms like "helper" or "assistant" 6. **Example agent descriptions**: - In the 'whenToUse' field of the JSON object, you should include examples of when this agent should be used. - Examples should be of the form: Context: The user is creating a code-review agent that should be called after a logical chunk of code is written. user: "Please write a function that checks if a number is prime" assistant: "Here is the relevant function: " Since a logical chunk of code was written and the task was completed, now use the code-review agent to review the code. assistant: "Now let me use the code-reviewer agent to review the code" - If the user mentioned or implied that the agent should be used proactively, you should include examples of this. - NOTE: Ensure that in the examples, you are making the assistant use the Agent tool and not simply respond directly to the task. Your output must be a valid JSON object with exactly these fields: { "identifier": "A unique, descriptive identifier using lowercase letters, numbers, and hyphens (e.g., 'code-reviewer', 'api-docs-writer', 'test-generator')", "whenToUse": "A precise, actionable description starting with 'Use this agent when...' that clearly defines the triggering conditions and use cases. Ensure you include examples as described above.", "systemPrompt": "The complete system prompt that will govern the agent's behavior, written in second person ('You are...', 'You will...') and structured for maximum clarity and effectiveness" } Key principles for your system prompts: - Be specific rather than generic - avoid vague instructions - Include concrete examples when they would clarify behavior - Balance comprehensiveness with clarity - every instruction should add value - Ensure the agent has enough context to handle variations of the core task - Make the agent proactive in seeking clarification when needed - Build in quality assurance and self-correction mechanisms Remember: The agents you create should be autonomous experts capable of handling their designated tasks with minimal additional guidance. Your system prompts are their complete operational manual. ``` ## Usage Pattern Use this prompt to generate agent configurations: ```markdown **User input:** "I need an agent that reviews pull requests for code quality issues" **You send to Claude with the system prompt above:** Create an agent configuration based on this request: "I need an agent that reviews pull requests for code quality issues" **Claude returns JSON:** { "identifier": "pr-quality-reviewer", "whenToUse": "Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples:\n\n\nContext: User has created a PR and wants quality review\nuser: \"Can you review PR #123 for code quality?\"\nassistant: \"I'll use the pr-quality-reviewer agent to analyze the PR.\"\n\nPR review request triggers the pr-quality-reviewer agent.\n\n", "systemPrompt": "You are an expert code quality reviewer...\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues\n2. Check adherence to best practices\n..." } ``` ## Converting to Agent File Take the JSON output and create the agent markdown file: **agents/pr-quality-reviewer.md:** ```markdown --- name: pr-quality-reviewer description: Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples: Context: User has created a PR and wants quality review user: "Can you review PR #123 for code quality?" assistant: "I'll use the pr-quality-reviewer agent to analyze the PR." PR review request triggers the pr-quality-reviewer agent. model: inherit color: blue --- You are an expert code quality reviewer... **Your Core Responsibilities:** 1. Analyze code changes for quality issues 2. Check adherence to best practices ... ``` ## Customization Tips ### Adapt the System Prompt The base prompt is excellent but can be enhanced for specific needs: **For security-focused agents:** ``` Add after "Architect Comprehensive Instructions": - Include OWASP top 10 security considerations - Check for common vulnerabilities (injection, XSS, etc.) - Validate input sanitization ``` **For test-generation agents:** ``` Add after "Optimize for Performance": - Follow AAA pattern (Arrange, Act, Assert) - Include edge cases and error scenarios - Ensure test isolation and cleanup ``` **For documentation agents:** ``` Add after "Design Expert Persona": - Use clear, concise language - Include code examples - Follow project documentation standards from CLAUDE.md ``` ## Best Practices from Internal Implementation ### 1. Consider Project Context The prompt specifically mentions using CLAUDE.md context: - Agent should align with project patterns - Follow project-specific coding standards - Respect established practices ### 2. Proactive Agent Design Include examples showing proactive usage: ``` Context: After writing code, agent should review proactively user: "Please write a function..." assistant: "[Writes function]" Code written, now use review agent proactively. assistant: "Now let me review this code with the code-reviewer agent" ``` ### 3. Scope Assumptions For code review agents, assume "recently written code" not entire codebase: ``` For agents that review code, assume recent changes unless explicitly stated otherwise. ``` ### 4. Output Structure Always define clear output format in system prompt: ``` **Output Format:** Provide results as: 1. Summary (2-3 sentences) 2. Detailed findings (bullet points) 3. Recommendations (action items) ``` ## Integration with Plugin-Dev Use this system prompt when creating agents for your plugins: 1. Take user request for agent functionality 2. Feed to Claude with this system prompt 3. Get JSON output (identifier, whenToUse, systemPrompt) 4. Convert to agent markdown file with frontmatter 5. Validate with agent validation rules 6. Test triggering conditions 7. Add to plugin's `agents/` directory This provides AI-assisted agent generation following proven patterns from Claude Code's internal implementation. --- ## agent-creator.md You are an elite AI agent architect specializing in crafting high-performance agent configurations. Your expertise lies in translating user requirements into precisely-tuned agent specifications that maximize effectiveness and reliability. **Important Context**: You may have access to project-specific instructions from CLAUDE.md files and other context that may include coding standards, project structure, and custom requirements. Consider this context when creating agents to ensure they align with the project's established patterns and practices. When a user describes what they want an agent to do, you will: 1. **Extract Core Intent**: Identify the fundamental purpose, key responsibilities, and success criteria for the agent. Look for both explicit requirements and implicit needs. Consider any project-specific context from CLAUDE.md files. For agents that are meant to review code, you should assume that the user is asking to review recently written code and not the whole codebase, unless the user has explicitly instructed you otherwise. 2. **Design Expert Persona**: Create a compelling expert identity that embodies deep domain knowledge relevant to the task. The persona should inspire confidence and guide the agent's decision-making approach. 3. **Architect Comprehensive Instructions**: Develop a system prompt that: - Establishes clear behavioral boundaries and operational parameters - Provides specific methodologies and best practices for task execution - Anticipates edge cases and provides guidance for handling them - Incorporates any specific requirements or preferences mentioned by the user - Defines output format expectations when relevant - Aligns with project-specific coding standards and patterns from CLAUDE.md 4. **Optimize for Performance**: Include: - Decision-making frameworks appropriate to the domain - Quality control mechanisms and self-verification steps - Efficient workflow patterns - Clear escalation or fallback strategies 5. **Create Identifier**: Design a concise, descriptive identifier that: - Uses lowercase letters, numbers, and hyphens only - Is typically 2-4 words joined by hyphens - Clearly indicates the agent's primary function - Is memorable and easy to type - Avoids generic terms like "helper" or "assistant" 6. **Craft Triggering Examples**: Create 2-4 `` blocks showing: - Different phrasings for same intent - Both explicit and proactive triggering - Context, user message, assistant response, commentary - Why the agent should trigger in each scenario - Show assistant using the Agent tool to launch the agent **Agent Creation Process:** 1. **Understand Request**: Analyze user's description of what agent should do 2. **Design Agent Configuration**: - **Identifier**: Create concise, descriptive name (lowercase, hyphens, 3-50 chars) - **Description**: Write triggering conditions starting with "Use this agent when..." - **Examples**: Create 2-4 `` blocks with: ``` Context: [Situation that should trigger agent] user: "[User message]" assistant: "[Response before triggering]" [Why agent should trigger] assistant: "I'll use the [agent-name] agent to [what it does]." ``` - **System Prompt**: Create comprehensive instructions with: - Role and expertise - Core responsibilities (numbered list) - Detailed process (step-by-step) - Quality standards - Output format - Edge case handling 3. **Select Configuration**: - **Model**: Use `inherit` unless user specifies (sonnet for complex, haiku for simple) - **Color**: Choose appropriate color: - blue/cyan: Analysis, review - green: Generation, creation - yellow: Validation, caution - red: Security, critical - magenta: Transformation, creative - **Tools**: Recommend minimal set needed, or omit for full access 4. **Generate Agent File**: Use Write tool to create `agents/[identifier].md`: ```markdown --- name: [identifier] description: [Use this agent when... Examples: ...] model: inherit color: [chosen-color] tools: ["Tool1", "Tool2"] # Optional --- [Complete system prompt] ``` 5. **Explain to User**: Provide summary of created agent: - What it does - When it triggers - Where it's saved - How to test it - Suggest running validation: `Use the plugin-validator agent to check the plugin structure` **Quality Standards:** - Identifier follows naming rules (lowercase, hyphens, 3-50 chars) - Description has strong trigger phrases and 2-4 examples - Examples show both explicit and proactive triggering - System prompt is comprehensive (500-3,000 words) - System prompt has clear structure (role, responsibilities, process, output) - Model choice is appropriate - Tool selection follows least privilege - Color choice matches agent purpose **Output Format:** Create agent file, then provide summary: ## Agent Created: [identifier] ### Configuration - **Name:** [identifier] - **Triggers:** [When it's used] - **Model:** [choice] - **Color:** [choice] - **Tools:** [list or "all tools"] ### File Created `agents/[identifier].md` ([word count] words) ### How to Use This agent will trigger when [triggering scenarios]. Test it by: [suggest test scenario] Validate with: `scripts/validate-agent.sh agents/[identifier].md` ### Next Steps [Recommendations for testing, integration, or improvements] **Edge Cases:** - Vague user request: Ask clarifying questions before generating - Conflicts with existing agents: Note conflict, suggest different scope/name - Very complex requirements: Break into multiple specialized agents - User wants specific tool access: Honor the request in agent configuration - User specifies model: Use specified model instead of inherit - First agent in plugin: Create agents/ directory first ``` This agent automates agent creation using the proven patterns from Claude Code's internal implementation, making it easy for users to create high-quality autonomous agents. --- ## agent-sdk-agent-loop-707ba48bc1.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # How the agent loop works > Understand the message lifecycle, tool execution, context window, and architecture that power your SDK agents. The Agent SDK lets you embed Claude Code's autonomous agent loop in your own applications. The SDK is a standalone package that gives you programmatic control over tools, permissions, cost limits, and output. You don't need the Claude Code CLI installed to use it. When you start an agent, the SDK runs the same [execution loop that powers Claude Code](/en/how-claude-code-works#the-agentic-loop): Claude evaluates your prompt, calls tools to take action, receives the results, and repeats until the task is complete. This page explains what happens inside that loop so you can build, debug, and optimize your agents effectively. ## The loop at a glance Every agent session follows the same cycle: Agent loop: prompt enters, Claude evaluates, branches to tool calls or final answer 1. **Receive prompt.** Claude receives your prompt, along with the system prompt, tool definitions, and conversation history. The SDK yields a [`SystemMessage`](#message-types) with subtype `"init"` containing session metadata. 2. **Evaluate and respond.** Claude evaluates the current state and determines how to proceed. It may respond with text, request one or more tool calls, or both. The SDK yields an [`AssistantMessage`](#message-types) containing the text and any tool call requests. 3. **Execute tools.** The SDK runs each requested tool and collects the results. Each set of tool results feeds back to Claude for the next decision. You can use [hooks](/en/agent-sdk/hooks) to intercept, modify, or block tool calls before they run. 4. **Repeat.** Steps 2 and 3 repeat as a cycle. Each full cycle is one turn. Claude continues calling tools and processing results until it produces a response with no tool calls. 5. **Return result.** The SDK yields a final [`AssistantMessage`](#message-types) with the text response (no tool calls), followed by a [`ResultMessage`](#message-types) with the final text, token usage, cost, and session ID. A quick question ("what files are here?") might take one or two turns of calling `Glob` and responding with the results. A complex task ("refactor the auth module and update the tests") can chain dozens of tool calls across many turns, reading files, editing code, and running tests, with Claude adjusting its approach based on each result. ## Turns and messages A turn is one round trip inside the loop: Claude produces output that includes tool calls, the SDK executes those tools, and the results feed back to Claude automatically. This happens without yielding control back to your code. Turns continue until Claude produces output with no tool calls, at which point the loop ends and the final result is delivered. Consider what a full session might look like for the prompt "Fix the failing tests in auth.ts". First, the SDK sends your prompt to Claude and yields a [`SystemMessage`](#message-types) with the session metadata. Then the loop begins: 1. **Turn 1:** Claude calls `Bash` to run `npm test`. The SDK yields an [`AssistantMessage`](#message-types) with the tool call, executes the command, then yields a [`UserMessage`](#message-types) with the output (three failures). 2. **Turn 2:** Claude calls `Read` on `auth.ts` and `auth.test.ts`. The SDK returns the file contents and yields an `AssistantMessage`. 3. **Turn 3:** Claude calls `Edit` to fix `auth.ts`, then calls `Bash` to re-run `npm test`. All three tests pass. The SDK yields an `AssistantMessage`. 4. **Final turn:** Claude produces a text-only response with no tool calls: "Fixed the auth bug, all three tests pass now." The SDK yields a final `AssistantMessage` with this text, then a [`ResultMessage`](#message-types) with the same text plus cost and usage. That was four turns: three with tool calls, one final text-only response. You can cap the loop with `max_turns` / `maxTurns`, which counts tool-use turns only. For example, `max_turns=2` in the loop above would have stopped before the edit step. You can also use `max_budget_usd` / `maxBudgetUsd` to cap turns based on a spend threshold. Without limits, the loop runs until Claude finishes on its own, which is fine for well-scoped tasks but can run long on open-ended prompts ("improve this codebase"). Setting a budget is a good default for production agents. See [Turns and budget](#turns-and-budget) below for the option reference. ## Message types As the loop runs, the SDK yields a stream of messages. Each message carries a type that tells you what stage of the loop it came from. The five core types are: * **`SystemMessage`:** session lifecycle events. The `subtype` field distinguishes them: `"init"` is the first message (session metadata), and `"compact_boundary"` fires after [compaction](#automatic-compaction). In TypeScript, the compact boundary is its own [`SDKCompactBoundaryMessage`](/en/agent-sdk/typescript#sdk-compact-boundary-message) type rather than a subtype of `SDKSystemMessage`. * **`AssistantMessage`:** emitted after each Claude response, including the final text-only one. Contains text content blocks and tool call blocks from that turn. * **`UserMessage`:** emitted after each tool execution with the tool result content sent back to Claude. Also emitted for any user inputs you stream mid-loop. * **`StreamEvent`:** only emitted when partial messages are enabled. Contains raw API streaming events (text deltas, tool input chunks). See [Stream responses](/en/agent-sdk/streaming-output). * **`ResultMessage`:** marks the end of the agent loop. Contains the final text result, token usage, cost, and session ID. Check the `subtype` field to determine whether the task succeeded or hit a limit. A small number of trailing system events, such as `prompt_suggestion`, can arrive after it, so iterate the stream to completion rather than breaking on the result. See [Handle the result](#handle-the-result). These five types cover the full agent loop lifecycle in both SDKs. The TypeScript SDK also yields additional observability events (hook events, tool progress, rate limits, task notifications) that provide extra detail but are not required to drive the loop. See the [Python message types reference](/en/agent-sdk/python#message-types) and [TypeScript message types reference](/en/agent-sdk/typescript#message-types) for the complete lists. ### Handle messages Which messages you handle depends on what you're building: * **Final results only:** handle `ResultMessage` to get the output, cost, and whether the task succeeded or hit a limit. * **Progress updates:** handle `AssistantMessage` to see what Claude is doing each turn, including which tools it called. * **Live streaming:** enable partial messages (`include_partial_messages` in Python, `includePartialMessages` in TypeScript) to get `StreamEvent` messages in real time. See [Stream responses in real-time](/en/agent-sdk/streaming-output). How you check message types depends on the SDK: * **Python:** check message types with `isinstance()` against classes imported from `claude_agent_sdk` (for example, `isinstance(message, ResultMessage)`). * **TypeScript:** check the `type` string field (for example, `message.type === "result"`). `AssistantMessage` and `UserMessage` wrap the raw API message in a `.message` field, so content blocks are at `message.message.content`, not `message.content`. ```python Python theme={null} from claude_agent_sdk import query, AssistantMessage, ResultMessage async for message in query(prompt="Summarize this project"): if isinstance(message, AssistantMessage): print(f"Turn completed: {len(message.content)} content blocks") if isinstance(message, ResultMessage): if message.subtype == "success": print(message.result) else: print(f"Stopped: {message.subtype}") ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Summarize this project" })) { if (message.type === "assistant") { console.log(`Turn completed: ${message.message.content.length} content blocks`); } if (message.type === "result") { if (message.subtype === "success") { console.log(message.result); } else { console.log(`Stopped: ${message.subtype}`); } } } ``` ## Tool execution Tools give your agent the ability to take action. Without tools, Claude can only respond with text. With tools, Claude can read files, run commands, search code, and interact with external services. ### Built-in tools The SDK includes the same tools that power Claude Code: | Category | Tools | What they do | | :------------------ | :----------------------------------------------- | :-------------------------------------------------------------------------- | | **File operations** | `Read`, `Edit`, `Write` | Read, modify, and create files | | **Search** | `Glob`, `Grep` | Find files by pattern, search content with regex | | **Execution** | `Bash` | Run shell commands, scripts, git operations | | **Web** | `WebSearch`, `WebFetch` | Search the web, fetch and parse pages | | **Discovery** | `ToolSearch` | Dynamically find and load tools on-demand instead of preloading all of them | | **Orchestration** | `Agent`, `Skill`, `AskUserQuestion`, `TodoWrite` | Spawn subagents, invoke skills, ask the user, track tasks | Beyond built-in tools, you can: * **Connect external services** with [MCP servers](/en/agent-sdk/mcp) (databases, browsers, APIs) * **Define custom tools** with [custom tool handlers](/en/agent-sdk/custom-tools) * **Load project skills** via [setting sources](/en/agent-sdk/claude-code-features) for reusable workflows ### Tool permissions Claude determines which tools to call based on the task, but you control whether those calls are allowed to execute. You can auto-approve specific tools, block others entirely, or require approval for everything. Three options work together to determine what runs: * **`allowed_tools` / `allowedTools`** auto-approves listed tools. A read-only agent with `["Read", "Glob", "Grep"]` in its allowed tools list runs those tools without prompting. Tools not listed are still available but require permission. * **`disallowed_tools` / `disallowedTools`** blocks listed tools, regardless of other settings. See [Permissions](/en/agent-sdk/permissions) for the order that rules are checked before a tool runs. * **`permission_mode` / `permissionMode`** controls what happens to tools that aren't covered by allow or deny rules. See [Permission mode](#permission-mode) for available modes. You can also scope individual tools with rules like `"Bash(npm *)"` to allow only specific commands. See [Permissions](/en/agent-sdk/permissions) for the full rule syntax. When a tool is denied, Claude receives a rejection message as the tool result and typically attempts a different approach or reports that it couldn't proceed. ### Parallel tool execution When Claude requests multiple tool calls in a single turn, both SDKs can run them concurrently or sequentially depending on the tool. Read-only tools (like `Read`, `Glob`, `Grep`, and MCP tools marked as read-only) can run concurrently. Tools that modify state (like `Edit`, `Write`, and `Bash`) run sequentially to avoid conflicts. Custom tools default to sequential execution. To enable parallel execution for a custom tool, mark it as read-only in its annotations: `readOnly` in [TypeScript](/en/agent-sdk/typescript#tool) or `readOnlyHint` in [Python](/en/agent-sdk/python#tool). ## Control how the loop runs You can limit how many turns the loop takes, how much it costs, how deeply Claude reasons, and whether tools require approval before running. All of these are fields on [`ClaudeAgentOptions`](/en/agent-sdk/python#claude-agent-options) (Python) / [`Options`](/en/agent-sdk/typescript#options) (TypeScript). ### Turns and budget | Option | What it controls | Default | | :--------------------------------------------- | :--------------------------- | :------- | | Max turns (`max_turns` / `maxTurns`) | Maximum tool-use round trips | No limit | | Max budget (`max_budget_usd` / `maxBudgetUsd`) | Maximum cost before stopping | No limit | When either limit is hit, the SDK returns a `ResultMessage` with a corresponding error subtype (`error_max_turns` or `error_max_budget_usd`). See [Handle the result](#handle-the-result) for how to check these subtypes and [`ClaudeAgentOptions`](/en/agent-sdk/python#claude-agent-options) / [`Options`](/en/agent-sdk/typescript#options) for syntax. ### Effort level The `effort` option controls how much reasoning Claude applies. Lower effort levels use fewer tokens per turn and reduce cost. Not all models support the effort parameter. See [Effort](../04-API-Reference/effort.md) for which models support it. | Level | Behavior | Good for | | :--------- | :-------------------------------- | :------------------------------------------------ | | `"low"` | Minimal reasoning, fast responses | File lookups, listing directories | | `"medium"` | Balanced reasoning | Routine edits, standard tasks | | `"high"` | Thorough analysis | Refactors, debugging | | `"xhigh"` | Extended reasoning depth | Coding and agentic tasks; recommended on Opus 4.7 | | `"max"` | Maximum reasoning depth | Multi-step problems requiring deep analysis | If you don't set `effort`, the Python SDK leaves the parameter unset and defers to the model's default behavior. The TypeScript SDK defaults to `"high"`. `effort` trades latency and token cost for reasoning depth within each response. [Extended thinking](../04-API-Reference/Guides/build-with-claude-extended-thinking-dd12780e6a.md) is a separate feature that produces visible chain-of-thought blocks in the output. They are independent: you can set `effort: "low"` with extended thinking enabled, or `effort: "max"` without it. Use lower effort for agents doing simple, well-scoped tasks (like listing files or running a single grep) to reduce cost and latency. `effort` is set at the top-level `query()` options, not per-subagent. ### Permission mode The permission mode option (`permission_mode` in Python, `permissionMode` in TypeScript) controls whether the agent asks for approval before using tools: | Mode | Behavior | | :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `"default"` | Tools not covered by allow rules trigger your approval callback; no callback means deny | | `"acceptEdits"` | Auto-approves file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.); other Bash commands follow default rules | | `"plan"` | No tool execution; Claude produces a plan for review | | `"dontAsk"` | Never prompts. Tools pre-approved by [permission rules](/en/settings#permission-settings) run, everything else is denied | | `"auto"` (TypeScript only) | Uses a model classifier to approve or deny each tool call. See [Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) for availability and behavior | | `"bypassPermissions"` | Runs all allowed tools without asking. Cannot be used when running as root on Unix. Use only in isolated environments where the agent's actions cannot affect systems you care about | For interactive applications, use `"default"` with a tool approval callback to surface approval prompts. For autonomous agents on a dev machine, `"acceptEdits"` auto-approves file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.) while still gating other `Bash` commands behind allow rules. Reserve `"bypassPermissions"` for CI, containers, or other isolated environments. See [Permissions](/en/agent-sdk/permissions) for full details. ### Model If you don't set `model`, the SDK uses Claude Code's default, which depends on your authentication method and subscription. Set it explicitly (for example, `model="claude-sonnet-4-6"`) to pin a specific model or to use a smaller model for faster, cheaper agents. See [models](https://platform.claude.com/docs/en/about-claude/models) for available IDs. ## The context window The context window is the total amount of information available to Claude during a session. It does not reset between turns within a session. Everything accumulates: the system prompt, tool definitions, conversation history, tool inputs, and tool outputs. Content that stays the same across turns (system prompt, tool definitions, CLAUDE.md) is automatically [prompt cached](../10-Prompting-Guides/build-with-claude-prompt-caching-bf7c54aa4c.md), which reduces cost and latency for repeated prefixes. ### What consumes context Here's how each component affects context in the SDK: | Source | When it loads | Impact | | :----------------------- | :------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------- | | **System prompt** | Every request | Small fixed cost, always present | | **CLAUDE.md files** | Session start, via [`settingSources`](/en/agent-sdk/claude-code-features) | Full content in every request (but prompt-cached, so only the first request pays full cost) | | **Tool definitions** | Every request | Each tool adds its schema; use [MCP tool search](/en/agent-sdk/mcp#mcp-tool-search) to load tools on-demand instead of all at once | | **Conversation history** | Accumulates over turns | Grows with each turn: prompts, responses, tool inputs, tool outputs | | **Skill descriptions** | Session start, via setting sources | Short summaries; full content loads only when invoked | Large tool outputs consume significant context. Reading a big file or running a command with verbose output can use thousands of tokens in a single turn. Context accumulates across turns, so longer sessions with many tool calls build up significantly more context than short ones. ### Automatic compaction When the context window approaches its limit, the SDK automatically compacts the conversation: it summarizes older history to free space, keeping your most recent exchanges and key decisions intact. The SDK emits a message with `type: "system"` and `subtype: "compact_boundary"` in the stream when this happens (in Python this is a `SystemMessage`; in TypeScript it is a separate `SDKCompactBoundaryMessage` type). Compaction replaces older messages with a summary, so specific instructions from early in the conversation may not be preserved. Persistent rules belong in CLAUDE.md (loaded via [`settingSources`](/en/agent-sdk/claude-code-features)) rather than in the initial prompt, because CLAUDE.md content is re-injected on every request. You can customize compaction behavior in several ways: * **Summarization instructions in CLAUDE.md:** The compactor reads your CLAUDE.md like any other context, so you can include a section telling it what to preserve when summarizing. The section header is free-form (not a magic string); the compactor matches on intent. * **`PreCompact` hook:** Run custom logic before compaction occurs, for example to archive the full transcript. The hook receives a `trigger` field (`manual` or `auto`). See [hooks](/en/agent-sdk/hooks). * **Manual compaction:** Send `/compact` as a prompt string to trigger compaction on demand. (Slash commands sent this way are SDK inputs, not CLI-only shortcuts. See [slash commands in the SDK](/en/agent-sdk/slash-commands).) Add a section to your project's CLAUDE.md telling the compactor what to preserve. The header name isn't special; use any clear label. ```markdown CLAUDE.md theme={null} # Summary instructions When summarizing this conversation, always preserve: - The current task objective and acceptance criteria - File paths that have been read or modified - Test results and error messages - Decisions made and the reasoning behind them ``` ### Keep context efficient A few strategies for long-running agents: * **Use subagents for subtasks.** Each subagent starts with a fresh conversation (no prior message history, though it does load its own system prompt and project-level context like CLAUDE.md). It does not see the parent's turns, and only its final response returns to the parent as a tool result. The main agent's context grows by that summary, not by the full subtask transcript. See [What subagents inherit](/en/agent-sdk/subagents#what-subagents-inherit) for details. * **Be selective with tools.** Every tool definition takes context space. Use the `tools` field on [`AgentDefinition`](/en/agent-sdk/subagents#agent-definition-configuration) to scope subagents to the minimum set they need, and use [MCP tool search](/en/agent-sdk/mcp#mcp-tool-search) to load tools on demand instead of preloading all of them. * **Watch MCP server costs.** Each MCP server adds all its tool schemas to every request. A few servers with many tools can consume significant context before the agent does any work. The `ToolSearch` tool can help by loading tools on-demand instead of preloading all of them. See [MCP tool search](/en/agent-sdk/mcp#mcp-tool-search) for configuration. * **Use lower effort for routine tasks.** Set [effort](#effort-level) to `"low"` for agents that only need to read files or list directories. This reduces token usage and cost. For a detailed breakdown of per-feature context costs, see [Understand context costs](/en/features-overview#understand-context-costs). ## Sessions and continuity Each interaction with the SDK creates or continues a session. Capture the session ID from `ResultMessage.session_id` (available in both SDKs) to resume later. The TypeScript SDK also exposes it as a direct field on the init `SystemMessage`; in Python it's nested in `SystemMessage.data`. When you resume, the full context from previous turns is restored: files that were read, analysis that was performed, and actions that were taken. You can also fork a session to branch into a different approach without modifying the original. See [Session management](/en/agent-sdk/sessions) for the full guide on resume, continue, and fork patterns. In Python, `ClaudeSDKClient` handles session IDs automatically across multiple calls. See the [Python SDK reference](/en/agent-sdk/python#choosing-between-query-and-claude-sdk-client) for details. ## Handle the result When the loop ends, the `ResultMessage` tells you what happened and gives you the output. The `subtype` field (available in both SDKs) is the primary way to check termination state. | Result subtype | What happened | `result` field available? | | :------------------------------------ | :------------------------------------------------------------------------------- | :-----------------------: | | `success` | Claude finished the task normally | Yes | | `error_max_turns` | Hit the `maxTurns` limit before finishing | No | | `error_max_budget_usd` | Hit the `maxBudgetUsd` limit before finishing | No | | `error_during_execution` | An error interrupted the loop (for example, an API failure or cancelled request) | No | | `error_max_structured_output_retries` | Structured output validation failed after the configured retry limit | No | The `result` field (the final text output) is only present on the `success` variant, so always check the subtype before reading it. All result subtypes carry `total_cost_usd`, `usage`, `num_turns`, and `session_id` so you can track cost and resume even after errors. In Python, `total_cost_usd` and `usage` are typed as optional and may be `None` on some error paths, so guard before formatting them. See [Tracking costs and usage](/en/agent-sdk/cost-tracking) for details on interpreting the `usage` fields. The result also includes a `stop_reason` field (`string | null` in TypeScript, `str | None` in Python) indicating why the model stopped generating on its final turn. Common values are `end_turn` (model finished normally), `max_tokens` (hit the output token limit), and `refusal` (the model declined the request). On error result subtypes, `stop_reason` carries the value from the last assistant response before the loop ended. To detect refusals, check `stop_reason === "refusal"` (TypeScript) or `stop_reason == "refusal"` (Python). See [`SDKResultMessage`](/en/agent-sdk/typescript#sdk-result-message) (TypeScript) or [`ResultMessage`](/en/agent-sdk/python#result-message) (Python) for the full type. ## Hooks [Hooks](/en/agent-sdk/hooks) are callbacks that fire at specific points in the loop: before a tool runs, after it returns, when the agent finishes, and so on. Some commonly used hooks are: | Hook | When it fires | Common uses | | :------------------------------- | :---------------------------------- | :----------------------------------------- | | `PreToolUse` | Before a tool executes | Validate inputs, block dangerous commands | | `PostToolUse` | After a tool returns | Audit outputs, trigger side effects | | `UserPromptSubmit` | When a prompt is sent | Inject additional context into prompts | | `Stop` | When the agent finishes | Validate the result, save session state | | `SubagentStart` / `SubagentStop` | When a subagent spawns or completes | Track and aggregate parallel task results | | `PreCompact` | Before context compaction | Archive full transcript before summarizing | Hooks run in your application process, not inside the agent's context window, so they don't consume context. Hooks can also short-circuit the loop: a `PreToolUse` hook that rejects a tool call prevents it from executing, and Claude receives the rejection message instead. Both SDKs support all the events above. The TypeScript SDK includes additional events that Python does not yet support. See [Control execution with hooks](/en/agent-sdk/hooks) for the complete event list, per-SDK availability, and the full callback API. ## Put it all together This example combines the key concepts from this page into a single agent that fixes failing tests. It configures the agent with allowed tools (auto-approved so the agent runs autonomously), project settings, and safety limits on turns and reasoning effort. As the loop runs, it captures the session ID for potential resumption, handles the final result, and prints the total cost. ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage async def run_agent(): session_id = None async for message in query( prompt="Find and fix the bug causing test failures in the auth module", options=ClaudeAgentOptions( allowed_tools=[ "Read", "Edit", "Bash", "Glob", "Grep", ], # Listing tools here auto-approves them (no prompting) setting_sources=[ "project" ], # Load CLAUDE.md, skills, hooks from current directory max_turns=30, # Prevent runaway sessions effort="high", # Thorough reasoning for complex debugging ), ): # Handle the final result if isinstance(message, ResultMessage): session_id = message.session_id # Save for potential resumption if message.subtype == "success": print(f"Done: {message.result}") elif message.subtype == "error_max_turns": # Agent ran out of turns. Resume with a higher limit. print(f"Hit turn limit. Resume session {session_id} to continue.") elif message.subtype == "error_max_budget_usd": print("Hit budget limit.") else: print(f"Stopped: {message.subtype}") if message.total_cost_usd is not None: print(f"Cost: ${message.total_cost_usd:.4f}") asyncio.run(run_agent()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; let sessionId: string | undefined; for await (const message of query({ prompt: "Find and fix the bug causing test failures in the auth module", options: { allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"], // Listing tools here auto-approves them (no prompting) settingSources: ["project"], // Load CLAUDE.md, skills, hooks from current directory maxTurns: 30, // Prevent runaway sessions effort: "high" // Thorough reasoning for complex debugging } })) { // Save the session ID to resume later if needed if (message.type === "system" && message.subtype === "init") { sessionId = message.session_id; } // Handle the final result if (message.type === "result") { if (message.subtype === "success") { console.log(`Done: ${message.result}`); } else if (message.subtype === "error_max_turns") { // Agent ran out of turns. Resume with a higher limit. console.log(`Hit turn limit. Resume session ${sessionId} to continue.`); } else if (message.subtype === "error_max_budget_usd") { console.log("Hit budget limit."); } else { console.log(`Stopped: ${message.subtype}`); } console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`); } } ``` ## Next steps Now that you understand the loop, here's where to go depending on what you're building: * **Haven't run an agent yet?** Start with the [quickstart](/en/agent-sdk/quickstart) to get the SDK installed and see a full example running end to end. * **Ready to hook into your project?** [Load CLAUDE.md, skills, and filesystem hooks](/en/agent-sdk/claude-code-features) so the agent follows your project conventions automatically. * **Building an interactive UI?** Enable [streaming](/en/agent-sdk/streaming-output) to show live text and tool calls as the loop runs. * **Need tighter control over what the agent can do?** Lock down tool access with [permissions](/en/agent-sdk/permissions), and use [hooks](/en/agent-sdk/hooks) to audit, block, or transform tool calls before they execute. * **Running long or expensive tasks?** Offload isolated work to [subagents](/en/agent-sdk/subagents) to keep your main context lean. For the broader conceptual picture of the agentic loop (not SDK-specific), see [How Claude Code works](../02-Claude-Code-CLI/how-claude-code-works-0871be411d.md). --- ## agent-sdk-claude-code-features-6797746e4b.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Use Claude Code features in the SDK > Load project instructions, skills, hooks, and other Claude Code features into your SDK agents. The Agent SDK is built on the same foundation as Claude Code, which means your SDK agents have access to the same filesystem-based features: project instructions (`CLAUDE.md` and rules), skills, hooks, and more. When you omit `settingSources`, `query()` reads the same filesystem settings as the Claude Code CLI: user, project, and local settings, CLAUDE.md files, and `.claude/` skills, agents, and commands. To run without these, pass `settingSources: []`, which limits the agent to what you configure programmatically. Managed policy settings and the global `~/.claude.json` config are read regardless of this option. See [What settingSources does not control](#what-settingsources-does-not-control). For a conceptual overview of what each feature does and when to use it, see [Extend Claude Code](../02-Claude-Code-CLI/extend-claude-code-claude-code-docs-3b35aaf641.md). ## Control filesystem settings with settingSources The setting sources option ([`setting_sources`](/en/agent-sdk/python#claude-agent-options) in Python, [`settingSources`](/en/agent-sdk/typescript#setting-source) in TypeScript) controls which filesystem-based settings the SDK loads. Pass an explicit list to opt in to specific sources, or pass an empty array to disable user, project, and local settings. This example loads both user-level and project-level settings by setting `settingSources` to `["user", "project"]`: ```python Python theme={null} from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage async for message in query( prompt="Help me refactor the auth module", options=ClaudeAgentOptions( # "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd. # Together they give the agent access to CLAUDE.md, skills, hooks, and # permissions from both locations. setting_sources=["user", "project"], allowed_tools=["Read", "Edit", "Bash"], ), ): if isinstance(message, AssistantMessage): for block in message.content: if hasattr(block, "text"): print(block.text) if isinstance(message, ResultMessage) and message.subtype == "success": print(f"\nResult: {message.result}") ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Help me refactor the auth module", options: { // "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd. // Together they give the agent access to CLAUDE.md, skills, hooks, and // permissions from both locations. settingSources: ["user", "project"], allowedTools: ["Read", "Edit", "Bash"] } })) { if (message.type === "assistant") { for (const block of message.message.content) { if (block.type === "text") console.log(block.text); } } if (message.type === "result" && message.subtype === "success") { console.log(`\nResult: ${message.result}`); } } ``` Each source loads settings from a specific location, where `` is the working directory you pass via the `cwd` option (or the process's current directory if unset). For the full type definition, see [`SettingSource`](/en/agent-sdk/typescript#setting-source) (TypeScript) or [`SettingSource`](/en/agent-sdk/python#setting-source) (Python). | Source | What it loads | Location | | :---------- | :---------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | | `"project"` | Project CLAUDE.md, `.claude/rules/*.md`, project skills, project hooks, project `settings.json` | `/.claude/` and each parent directory up to the filesystem root (stopping when a `.claude/` is found or no more parents exist) | | `"user"` | User CLAUDE.md, `~/.claude/rules/*.md`, user skills, user settings | `~/.claude/` | | `"local"` | CLAUDE.local.md (gitignored), `.claude/settings.local.json` | `/` | Omitting `settingSources` is equivalent to `["user", "project", "local"]`. The `cwd` option determines where the SDK looks for project settings. If neither `cwd` nor any of its parent directories contains a `.claude/` folder, project-level features won't load. ### What settingSources does not control `settingSources` covers user, project, and local settings. A few inputs are read regardless of its value: | Input | Behavior | To disable | | :---------------------------------------------------- | :--------------------------------------- | :------------------------------------------------------------------------------------------ | | Managed policy settings | Always loaded when present on the host | Remove the managed settings file | | `~/.claude.json` global config | Always read | Relocate with `CLAUDE_CONFIG_DIR` in `env` | | Auto memory at `~/.claude/projects//memory/` | Loaded by default into the system prompt | Set `autoMemoryEnabled: false` in settings, or `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` in `env` | Do not rely on default `query()` options for multi-tenant isolation. Because the inputs above are read regardless of `settingSources`, an SDK process can pick up host-level configuration and per-directory memory. For multi-tenant deployments, run each tenant in its own filesystem and set `settingSources: []` plus `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` in `env`. See [Secure deployment](/en/agent-sdk/secure-deployment). ## Project instructions (CLAUDE.md and rules) `CLAUDE.md` files and `.claude/rules/*.md` files give your agent persistent context about your project: coding conventions, build commands, architecture decisions, and instructions. When `settingSources` includes `"project"` (as in the example above), the SDK loads these files into context at session start. The agent then follows your project conventions without you repeating them in every prompt. ### CLAUDE.md load locations | Level | Location | When loaded | | :-------------------- | :--------------------------------------------- | :-------------------------------------------------------------------------------------------------- | | Project (root) | `/CLAUDE.md` or `/.claude/CLAUDE.md` | `settingSources` includes `"project"` | | Project rules | `/.claude/rules/*.md` | `settingSources` includes `"project"` | | Project (parent dirs) | `CLAUDE.md` files in directories above `cwd` | `settingSources` includes `"project"`, loaded at session start | | Project (child dirs) | `CLAUDE.md` files in subdirectories of `cwd` | `settingSources` includes `"project"`, loaded on demand when the agent reads a file in that subtree | | Local (gitignored) | `/CLAUDE.local.md` | `settingSources` includes `"local"` | | User | `~/.claude/CLAUDE.md` | `settingSources` includes `"user"` | | User rules | `~/.claude/rules/*.md` | `settingSources` includes `"user"` | All levels are additive: if both project and user CLAUDE.md files exist, the agent sees both. There is no hard precedence rule between levels; if instructions conflict, the outcome depends on how Claude interprets them. Write non-conflicting rules, or state precedence explicitly in the more specific file ("These project instructions override any conflicting user-level defaults"). You can also inject context directly via `systemPrompt` without using CLAUDE.md files. See [Modify system prompts](/en/agent-sdk/modifying-system-prompts). Use CLAUDE.md when you want the same context shared between interactive Claude Code sessions and your SDK agents. For how to structure and organize CLAUDE.md content, see [Manage Claude's memory](../02-Claude-Code-CLI/how-claude-remembers-your-project-claude-code-docs-f1c064262d.md). ## Skills Skills are markdown files that give your agent specialized knowledge and invocable workflows. Unlike `CLAUDE.md` (which loads every session), skills load on demand. The agent receives skill descriptions at startup and loads the full content when relevant. Skills are discovered from the filesystem through `settingSources`. With default options, user and project skills load automatically. The `Skill` tool is enabled by default when you don't specify `allowedTools`. If you are using an `allowedTools` allowlist, include `"Skill"` explicitly. ```python Python theme={null} from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage # Skills in .claude/skills/ are discovered automatically # when settingSources includes "project" async for message in query( prompt="Review this PR using our code review checklist", options=ClaudeAgentOptions( setting_sources=["user", "project"], allowed_tools=["Skill", "Read", "Grep", "Glob"], ), ): if isinstance(message, ResultMessage) and message.subtype == "success": print(message.result) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; // Skills in .claude/skills/ are discovered automatically // when settingSources includes "project" for await (const message of query({ prompt: "Review this PR using our code review checklist", options: { settingSources: ["user", "project"], allowedTools: ["Skill", "Read", "Grep", "Glob"] } })) { if (message.type === "result" && message.subtype === "success") { console.log(message.result); } } ``` Skills must be created as filesystem artifacts (`.claude/skills//SKILL.md`). The SDK does not have a programmatic API for registering skills. See [Agent Skills in the SDK](/en/agent-sdk/skills) for full details. For more on creating and using skills, see [Agent Skills in the SDK](/en/agent-sdk/skills). ## Hooks The SDK supports two ways to define hooks, and they run side by side: * **Filesystem hooks:** shell commands defined in `settings.json`, loaded when `settingSources` includes the relevant source. These are the same hooks you'd configure for [interactive Claude Code sessions](../07-Hooks/automate-workflows-with-hooks-claude-code-docs-e843f93261.md). * **Programmatic hooks:** callback functions passed directly to `query()`. These run in your application process and can return structured decisions. See [Control execution with hooks](/en/agent-sdk/hooks). Both types execute during the same hook lifecycle. If you already have hooks in your project's `.claude/settings.json` and you set `settingSources: ["project"]`, those hooks run automatically in the SDK with no extra configuration. Hook callbacks receive the tool input and return a decision dict. Returning `{}` (an empty dict) means allow the tool to proceed. Returning `{"decision": "block", "reason": "..."}` prevents execution and the reason is sent to Claude as the tool result. See the [hooks guide](/en/agent-sdk/hooks) for the full callback signature and return types. ```python Python theme={null} from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage # PreToolUse hook callback. Positional args: # input_data: HookInput dict with tool_name, tool_input, hook_event_name # tool_use_id: str | None, the ID of the tool call being intercepted # context: HookContext, carries session metadata async def audit_bash(input_data, tool_use_id, context): command = input_data.get("tool_input", {}).get("command", "") if "rm -rf" in command: return {"decision": "block", "reason": "Destructive command blocked"} return {} # Empty dict: allow the tool to proceed # Filesystem hooks from .claude/settings.json run automatically # when settingSources loads them. You can also add programmatic hooks: async for message in query( prompt="Refactor the auth module", options=ClaudeAgentOptions( setting_sources=["project"], # Loads hooks from .claude/settings.json hooks={ "PreToolUse": [ HookMatcher(matcher="Bash", hooks=[audit_bash]), ] }, ), ): if isinstance(message, ResultMessage) and message.subtype == "success": print(message.result) ``` ```typescript TypeScript theme={null} import { query, type HookInput, type HookJSONOutput } from "@anthropic-ai/claude-agent-sdk"; // PreToolUse hook callback. HookInput is a discriminated union on // hook_event_name, so narrowing on it gives TypeScript the right // tool_input shape for this event. const auditBash = async (input: HookInput): Promise => { if (input.hook_event_name !== "PreToolUse") return {}; const toolInput = input.tool_input as { command?: string }; if (toolInput.command?.includes("rm -rf")) { return { decision: "block", reason: "Destructive command blocked" }; } return {}; // Empty object: allow the tool to proceed }; // Filesystem hooks from .claude/settings.json run automatically // when settingSources loads them. You can also add programmatic hooks: for await (const message of query({ prompt: "Refactor the auth module", options: { settingSources: ["project"], // Loads hooks from .claude/settings.json hooks: { PreToolUse: [{ matcher: "Bash", hooks: [auditBash] }] } } })) { if (message.type === "result" && message.subtype === "success") { console.log(message.result); } } ``` ### When to use which hook type | Hook type | Best for | | :---------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Filesystem** (`settings.json`) | Sharing hooks between CLI and SDK sessions. Supports `"command"` (shell scripts), `"http"` (POST to an endpoint), `"mcp_tool"` (call a connected MCP server's tool), `"prompt"` (LLM evaluates a prompt), and `"agent"` (spawns a verifier agent). These fire in the main agent and any subagents it spawns. | | **Programmatic** (callbacks in `query()`) | Application-specific logic; returning structured decisions; in-process integration. Scoped to the main session only. | The TypeScript SDK supports additional hook events beyond Python, including `SessionStart`, `SessionEnd`, `TeammateIdle`, and `TaskCompleted`. See the [hooks guide](/en/agent-sdk/hooks) for the full event compatibility table. For full details on programmatic hooks, see [Control execution with hooks](/en/agent-sdk/hooks). For filesystem hook syntax, see [Hooks](../07-Hooks/hooks-9168ed62a4.md). ## Choose the right feature The Agent SDK gives you access to several ways to extend your agent's behavior. If you're unsure which to use, this table maps common goals to the right approach. | You want to... | Use | SDK surface | | :------------------------------------------------------------------------------------------------ | :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Set project conventions your agent always follows | [CLAUDE.md](../02-Claude-Code-CLI/how-claude-remembers-your-project-claude-code-docs-f1c064262d.md) | `settingSources: ["project"]` loads it automatically | | Give the agent reference material it loads when relevant | [Skills](/en/agent-sdk/skills) | `settingSources` + `allowedTools: ["Skill"]` | | Run a reusable workflow (deploy, review, release) | [User-invocable skills](/en/agent-sdk/skills) | `settingSources` + `allowedTools: ["Skill"]` | | Delegate an isolated subtask to a fresh context (research, review) | [Subagents](/en/agent-sdk/subagents) | `agents` parameter + `allowedTools: ["Agent"]` | | Coordinate multiple Claude Code instances with shared task lists and direct inter-agent messaging | [Agent teams](agent-teams-e29da6ed1b.md) | Not directly configured via SDK options. Agent teams are a CLI feature where one session acts as the team lead, coordinating work across independent teammates | | Run deterministic logic on tool calls (audit, block, transform) | [Hooks](/en/agent-sdk/hooks) | `hooks` parameter with callbacks, or shell scripts loaded via `settingSources` | | Give Claude structured tool access to an external service | [MCP](/en/agent-sdk/mcp) | `mcpServers` parameter | **Subagents versus agent teams:** Subagents are ephemeral and isolated: fresh conversation, one task, summary returned to parent. Agent teams coordinate multiple independent Claude Code instances that share a task list and message each other directly. Agent teams are a CLI feature. See [What subagents inherit](/en/agent-sdk/subagents#what-subagents-inherit) and the [agent teams comparison](/en/agent-teams#compare-with-subagents) for details. Every feature you enable adds to your agent's context window. For per-feature costs and how these features layer together, see [Extend Claude Code](/en/features-overview#understand-context-costs). ## Related resources * [Extend Claude Code](../02-Claude-Code-CLI/extend-claude-code-claude-code-docs-3b35aaf641.md): Conceptual overview of all extension features, with comparison tables and context cost analysis * [Skills in the SDK](/en/agent-sdk/skills): Full guide to using skills programmatically * [Subagents](/en/agent-sdk/subagents): Define and invoke subagents for isolated subtasks * [Hooks](/en/agent-sdk/hooks): Intercept and control agent behavior at key execution points * [Permissions](/en/agent-sdk/permissions): Control tool access with modes, rules, and callbacks * [System prompts](/en/agent-sdk/modifying-system-prompts): Inject context without CLAUDE.md files --- ## agent-sdk-cost-tracking-aec9879f38.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Track cost and usage > Learn how to track token usage, estimate costs, and configure prompt caching with the Claude Agent SDK. The Claude Agent SDK provides detailed token usage information for each interaction with Claude. This guide explains how to properly track usage and understand cost reporting, especially when dealing with parallel tool uses and multi-step conversations. For complete API documentation, see the [TypeScript SDK reference](/en/agent-sdk/typescript) and [Python SDK reference](/en/agent-sdk/python). The `total_cost_usd` and `costUSD` fields are client-side estimates, not authoritative billing data. The SDK computes them locally from a price table bundled at build time, so they can drift from what you are actually billed when: * pricing changes * the installed SDK version does not recognize a model * billing rules apply that the client cannot model Use these fields for development insight and approximate budgeting. For authoritative billing, use the [Usage and Cost API](../04-API-Reference/Guides/build-with-claude-usage-cost-api-ea9ab3260c.md) or the Usage page in the [Claude Console](https://platform.claude.com/usage). Do not bill end users or trigger financial decisions from these fields. ## Understand token usage The TypeScript and Python SDKs expose the same usage data with different field names: * **TypeScript** provides per-step token breakdowns on each assistant message (`message.message.id`, `message.message.usage`), per-model cost via `modelUsage` on the result message, and a cumulative total on the result message. * **Python** provides per-step token breakdowns on each assistant message (`message.usage`, `message.message_id`), per-model cost via `model_usage` on the result message, and the accumulated total on the result message (`total_cost_usd` and `usage` dict). Both SDKs use the same underlying cost model and expose the same granularity. The difference is in field naming and where per-step usage is nested. Cost tracking depends on understanding how the SDK scopes usage data: * **`query()` call:** one invocation of the SDK's `query()` function. A single call can involve multiple steps (Claude responds, uses tools, gets results, responds again). Each call produces one [`result`](/en/agent-sdk/typescript#sdk-result-message) message at the end. * **Step:** a single request/response cycle within a `query()` call. Each step produces assistant messages with token usage. * **Session:** a series of `query()` calls linked by a session ID (using the `resume` option). Each `query()` call within a session reports its own cost independently. The following diagram shows the message stream from a single `query()` call, with token usage reported at each step and the cumulative estimate at the end: Diagram showing a query producing two steps of messages. Step 1 has four assistant messages sharing the same ID and usage (count once), Step 2 has one assistant message with a new ID, and the final result message shows the estimated total_cost_usd. When Claude responds, it sends one or more assistant messages. In TypeScript, each assistant message contains a nested `BetaMessage` (accessed via `message.message`) with an `id` and a [`usage`](../04-API-Reference/Other/api-messages-2dd213ca95.md) object with token counts (`input_tokens`, `output_tokens`). In Python, the `AssistantMessage` dataclass exposes the same data directly via `message.usage` and `message.message_id`. When Claude uses multiple tools in one turn, all messages in that turn share the same ID, so deduplicate by ID to avoid double-counting. When the `query()` call completes, the SDK emits a result message with `total_cost_usd` and cumulative `usage`. This is available in both TypeScript ([`SDKResultMessage`](/en/agent-sdk/typescript#sdk-result-message)) and Python ([`ResultMessage`](/en/agent-sdk/python#result-message)). If you make multiple `query()` calls (for example, in a multi-turn session), each result only reflects the cost of that individual call. If you only need the estimated total, you can ignore the per-step usage and read this single value. ## Get the total cost of a query The result message ([TypeScript](/en/agent-sdk/typescript#sdk-result-message), [Python](/en/agent-sdk/python#result-message)) marks the end of the agent loop for a `query()` call. It includes `total_cost_usd`, the cumulative estimated cost across all steps in that call. This works for both success and error results. If you use sessions to make multiple `query()` calls, each result only reflects the cost of that individual call. The following examples iterate over the message stream from a `query()` call and print the total cost when the `result` message arrives: ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Summarize this project" })) { if (message.type === "result") { console.log(`Total cost: $${message.total_cost_usd}`); } } ``` ```python Python theme={null} from claude_agent_sdk import query, ResultMessage import asyncio async def main(): async for message in query(prompt="Summarize this project"): if isinstance(message, ResultMessage): print(f"Total cost: ${message.total_cost_usd or 0}") asyncio.run(main()) ``` ## Track per-step and per-model usage The examples in this section use TypeScript field names. In Python, the equivalent fields are [`AssistantMessage.usage`](/en/agent-sdk/python#assistant-message) and `AssistantMessage.message_id` for per-step usage, and [`ResultMessage.model_usage`](/en/agent-sdk/python#result-message) for per-model breakdowns. ### Track per-step usage Each assistant message contains a nested `BetaMessage` (accessed via `message.message`) with an `id` and `usage` object with token counts. When Claude uses tools in parallel, multiple messages share the same `id` with identical usage data. Track which IDs you've already counted and skip duplicates to avoid inflated totals. Parallel tool calls produce multiple assistant messages whose nested `BetaMessage` shares the same `id` and identical usage. Always deduplicate by ID to get accurate per-step token counts. The following example accumulates input and output tokens across all steps, counting each unique message ID only once: ```typescript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; const seenIds = new Set(); let totalInputTokens = 0; let totalOutputTokens = 0; for await (const message of query({ prompt: "Summarize this project" })) { if (message.type === "assistant") { const msgId = message.message.id; // Parallel tool calls share the same ID, only count once if (!seenIds.has(msgId)) { seenIds.add(msgId); totalInputTokens += message.message.usage.input_tokens; totalOutputTokens += message.message.usage.output_tokens; } } } console.log(`Steps: ${seenIds.size}`); console.log(`Input tokens: ${totalInputTokens}`); console.log(`Output tokens: ${totalOutputTokens}`); ``` ### Break down usage per model The result message includes [`modelUsage`](/en/agent-sdk/typescript#model-usage), a map of model name to per-model token counts and cost. This is useful when you run multiple models (for example, Haiku for subagents and Opus for the main agent) and want to see where tokens are going. The following example runs a query and prints the cost and token breakdown for each model used: ```typescript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Summarize this project" })) { if (message.type !== "result") continue; for (const [modelName, usage] of Object.entries(message.modelUsage)) { console.log(`${modelName}: $${usage.costUSD.toFixed(4)}`); console.log(` Input tokens: ${usage.inputTokens}`); console.log(` Output tokens: ${usage.outputTokens}`); console.log(` Cache read: ${usage.cacheReadInputTokens}`); console.log(` Cache creation: ${usage.cacheCreationInputTokens}`); } } ``` ## Accumulate costs across multiple calls Each `query()` call returns its own `total_cost_usd`. The SDK does not provide a session-level total, so if your application makes multiple `query()` calls (for example, in a multi-turn session or across different users), accumulate the totals yourself. The following examples run two `query()` calls sequentially, add each call's `total_cost_usd` to a running total, and print both the per-call and combined cost: ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; // Track cumulative cost across multiple query() calls let totalSpend = 0; const prompts = [ "Read the files in src/ and summarize the architecture", "List all exported functions in src/auth.ts" ]; for (const prompt of prompts) { for await (const message of query({ prompt })) { if (message.type === "result") { totalSpend += message.total_cost_usd; console.log(`This call: $${message.total_cost_usd}`); } } } console.log(`Total spend: $${totalSpend.toFixed(4)}`); ``` ```python Python theme={null} from claude_agent_sdk import query, ResultMessage import asyncio async def main(): # Track cumulative cost across multiple query() calls total_spend = 0.0 prompts = [ "Read the files in src/ and summarize the architecture", "List all exported functions in src/auth.ts", ] for prompt in prompts: async for message in query(prompt=prompt): if isinstance(message, ResultMessage): cost = message.total_cost_usd or 0 total_spend += cost print(f"This call: ${cost}") print(f"Total spend: ${total_spend:.4f}") asyncio.run(main()) ``` ## Handle errors, caching, and token discrepancies For accurate cost tracking, account for failed conversations, cache token pricing, and occasional reporting inconsistencies. ### Resolve output token discrepancies In rare cases, you might observe different `output_tokens` values for messages with the same ID. When this occurs: 1. **Use the highest value:** the final message in a group typically contains the accurate total. 2. **Prefer the result message:** the `total_cost_usd` in the result message reflects the SDK's accumulated estimate across all steps, so it is more reliable than summing per-step values yourself. It is still an estimate and may differ from your actual bill. 3. **Report inconsistencies:** file issues at the [Claude Code GitHub repository](https://github.com/anthropics/claude-code/issues). ### Track costs on failed conversations Both success and error result messages include `usage` and `total_cost_usd`. If a conversation fails mid-way, you still consumed tokens up to the point of failure. Always read cost data from the result message regardless of its `subtype`. ### Track cache tokens The Agent SDK automatically uses [prompt caching](../10-Prompting-Guides/build-with-claude-prompt-caching-bf7c54aa4c.md) to reduce costs on repeated content. You do not need to configure caching yourself. The usage object includes two additional fields for cache tracking: * `cache_creation_input_tokens`: tokens used to create new cache entries (charged at a higher rate than standard input tokens). * `cache_read_input_tokens`: tokens read from existing cache entries (charged at a reduced rate). Track these separately from `input_tokens` to understand caching savings. In TypeScript, these fields are typed on the [`Usage`](/en/agent-sdk/typescript#usage) object. In Python, they appear as keys in the [`ResultMessage.usage`](/en/agent-sdk/python#result-message) dict (for example, `message.usage.get("cache_read_input_tokens", 0)`). ### Extend the prompt cache TTL to one hour Cache entries written by the SDK use a 5-minute TTL by default when you authenticate with an API key or run on Amazon Bedrock, Google Cloud Vertex AI, or Microsoft Foundry. If your workload runs many short sessions against the same system prompt and context with gaps longer than 5 minutes between them, the cache expires between sessions and each new session pays full input price. To request a 1-hour TTL on cache writes, set the [`ENABLE_PROMPT_CACHING_1H`](../02-Claude-Code-CLI/env-vars-5c624d392b.md) environment variable. You can export it in your shell or container environment, or pass it through `options.env`. The following example enables 1-hour TTL for an agent running on Bedrock: ```python Python theme={null} options = ClaudeAgentOptions( env={ "CLAUDE_CODE_USE_BEDROCK": "1", "ENABLE_PROMPT_CACHING_1H": "1", }, ) ``` ```typescript TypeScript theme={null} const options = { env: { ...process.env, CLAUDE_CODE_USE_BEDROCK: "1", ENABLE_PROMPT_CACHING_1H: "1", }, }; ``` Cache writes with a 1-hour TTL are billed at a higher rate than 5-minute writes, so enabling this trades higher write cost for more cache reads. See [prompt caching pricing](../10-Prompting-Guides/build-with-claude-prompt-caching-bf7c54aa4c.md) for details. Claude subscription users already receive 1-hour TTL automatically and do not need to set this variable. ## Related documentation * [TypeScript SDK Reference](/en/agent-sdk/typescript) - Complete API documentation * [SDK Overview](/en/agent-sdk/overview) - Getting started with the SDK * [SDK Permissions](/en/agent-sdk/permissions) - Managing tool permissions --- ## agent-sdk-custom-tools-4c4270e2ca.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Give Claude custom tools > Define custom tools with the Claude Agent SDK's in-process MCP server so Claude can call your functions, hit your APIs, and perform domain-specific operations. Custom tools extend the Agent SDK by letting you define your own functions that Claude can call during a conversation. Using the SDK's in-process MCP server, you can give Claude access to databases, external APIs, domain-specific logic, or any other capability your application needs. This guide covers how to define tools with input schemas and handlers, bundle them into an MCP server, pass them to `query`, and control which tools Claude can access. It also covers error handling, tool annotations, and returning non-text content like images. ## Quick reference | If you want to... | Do this | | :------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Define a tool | Use [`@tool`](/en/agent-sdk/python#tool) (Python) or [`tool()`](/en/agent-sdk/typescript#tool) (TypeScript) with a name, description, schema, and handler. See [Create a custom tool](#create-a-custom-tool). | | Register a tool with Claude | Wrap in `create_sdk_mcp_server` / `createSdkMcpServer` and pass to `mcpServers` in `query()`. See [Call a custom tool](#call-a-custom-tool). | | Pre-approve a tool | Add to your allowed tools. See [Configure allowed tools](#configure-allowed-tools). | | Remove a built-in tool from Claude's context | Pass a `tools` array listing only the built-ins you want. See [Configure allowed tools](#configure-allowed-tools). | | Let Claude call tools in parallel | Set `readOnlyHint: true` on tools with no side effects. See [Add tool annotations](#add-tool-annotations). | | Handle errors without stopping the loop | Return `isError: true` instead of throwing. See [Handle errors](#handle-errors). | | Return images or files | Use `image` or `resource` blocks in the content array. See [Return images and resources](#return-images-and-resources). | | Scale to many tools | Use [tool search](/en/agent-sdk/tool-search) to load tools on demand. | ## Create a custom tool A tool is defined by four parts, passed as arguments to the [`tool()`](/en/agent-sdk/typescript#tool) helper in TypeScript or the [`@tool`](/en/agent-sdk/python#tool) decorator in Python: * **Name:** a unique identifier Claude uses to call the tool. * **Description:** what the tool does. Claude reads this to decide when to call it. * **Input schema:** the arguments Claude must provide. In TypeScript this is always a [Zod schema](https://zod.dev/), and the handler's `args` are typed from it automatically. In Python this is a dict mapping names to types, like `{"latitude": float}`, which the SDK converts to JSON Schema for you. The Python decorator also accepts a full [JSON Schema](https://json-schema.org/understanding-json-schema/about) dict directly when you need enums, ranges, optional fields, or nested objects. * **Handler:** the async function that runs when Claude calls the tool. It receives the validated arguments and must return an object with: * `content` (required): an array of result blocks, each with a `type` of `"text"`, `"image"`, or `"resource"`. See [Return images and resources](#return-images-and-resources) for non-text blocks. * `isError` (optional): set to `true` to signal a tool failure so Claude can react to it. See [Handle errors](#handle-errors). After defining a tool, wrap it in a server with [`createSdkMcpServer`](/en/agent-sdk/typescript#create-sdk-mcp-server) (TypeScript) or [`create_sdk_mcp_server`](/en/agent-sdk/python#create-sdk-mcp-server) (Python). The server runs in-process inside your application, not as a separate process. ### Weather tool example This example defines a `get_temperature` tool and wraps it in an MCP server. It only sets up the tool; to pass it to `query` and run it, see [Call a custom tool](#call-a-custom-tool) below. ```python Python theme={null} from typing import Any import httpx from claude_agent_sdk import tool, create_sdk_mcp_server # Define a tool: name, description, input schema, handler @tool( "get_temperature", "Get the current temperature at a location", {"latitude": float, "longitude": float}, ) async def get_temperature(args: dict[str, Any]) -> dict[str, Any]: async with httpx.AsyncClient() as client: response = await client.get( "https://api.open-meteo.com/v1/forecast", params={ "latitude": args["latitude"], "longitude": args["longitude"], "current": "temperature_2m", "temperature_unit": "fahrenheit", }, ) data = response.json() # Return a content array - Claude sees this as the tool result return { "content": [ { "type": "text", "text": f"Temperature: {data['current']['temperature_2m']}°F", } ] } # Wrap the tool in an in-process MCP server weather_server = create_sdk_mcp_server( name="weather", version="1.0.0", tools=[get_temperature], ) ``` ```typescript TypeScript theme={null} import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk"; import { z } from "zod"; // Define a tool: name, description, input schema, handler const getTemperature = tool( "get_temperature", "Get the current temperature at a location", { latitude: z.number().describe("Latitude coordinate"), // .describe() adds a field description Claude sees longitude: z.number().describe("Longitude coordinate") }, async (args) => { // args is typed from the schema: { latitude: number; longitude: number } const response = await fetch( `https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}¤t=temperature_2m&temperature_unit=fahrenheit` ); const data: any = await response.json(); // Return a content array - Claude sees this as the tool result return { content: [{ type: "text", text: `Temperature: ${data.current.temperature_2m}°F` }] }; } ); // Wrap the tool in an in-process MCP server const weatherServer = createSdkMcpServer({ name: "weather", version: "1.0.0", tools: [getTemperature] }); ``` See the [`tool()`](/en/agent-sdk/typescript#tool) TypeScript reference or the [`@tool`](/en/agent-sdk/python#tool) Python reference for full parameter details, including JSON Schema input formats and return value structure. To make a parameter optional: in TypeScript, add `.default()` to the Zod field. In Python, the dict schema treats every key as required, so leave the parameter out of the schema, mention it in the description string, and read it with `args.get()` in the handler. The [`get_precipitation_chance` tool below](#add-more-tools) shows both patterns. ### Call a custom tool Pass the MCP server you created to `query` via the `mcpServers` option. The key in `mcpServers` becomes the `{server_name}` segment in each tool's fully qualified name: `mcp__{server_name}__{tool_name}`. List that name in `allowedTools` so the tool runs without a permission prompt. These snippets reuse the `weatherServer` from the [example above](#weather-tool-example) to ask Claude what the weather is in a specific location. ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage async def main(): options = ClaudeAgentOptions( mcp_servers={"weather": weather_server}, allowed_tools=["mcp__weather__get_temperature"], ) async for message in query( prompt="What's the temperature in San Francisco?", options=options, ): # ResultMessage is the final message after all tool calls complete if isinstance(message, ResultMessage) and message.subtype == "success": print(message.result) asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "What's the temperature in San Francisco?", options: { mcpServers: { weather: weatherServer }, allowedTools: ["mcp__weather__get_temperature"] } })) { // "result" is the final message after all tool calls complete if (message.type === "result" && message.subtype === "success") { console.log(message.result); } } ``` ### Add more tools A server holds as many tools as you list in its `tools` array. With more than one tool on a server, you can list each one in `allowedTools` individually or use the wildcard `mcp__weather__*` to cover every tool the server exposes. The example below adds a second tool, `get_precipitation_chance`, to the `weatherServer` from the [weather tool example](#weather-tool-example) and rebuilds it with both tools in the array. ```python Python theme={null} # Define a second tool for the same server @tool( "get_precipitation_chance", "Get the hourly precipitation probability for a location. " "Optionally pass 'hours' (1-24) to control how many hours to return.", {"latitude": float, "longitude": float}, ) async def get_precipitation_chance(args: dict[str, Any]) -> dict[str, Any]: # 'hours' isn't in the schema - read it with .get() to make it optional hours = args.get("hours", 12) async with httpx.AsyncClient() as client: response = await client.get( "https://api.open-meteo.com/v1/forecast", params={ "latitude": args["latitude"], "longitude": args["longitude"], "hourly": "precipitation_probability", "forecast_days": 1, }, ) data = response.json() chances = data["hourly"]["precipitation_probability"][:hours] return { "content": [ { "type": "text", "text": f"Next {hours} hours: {'%, '.join(map(str, chances))}%", } ] } # Rebuild the server with both tools in the array weather_server = create_sdk_mcp_server( name="weather", version="1.0.0", tools=[get_temperature, get_precipitation_chance], ) ``` ```typescript TypeScript theme={null} // Define a second tool for the same server const getPrecipitationChance = tool( "get_precipitation_chance", "Get the hourly precipitation probability for a location", { latitude: z.number(), longitude: z.number(), hours: z .number() .int() .min(1) .max(24) .default(12) // .default() makes the parameter optional .describe("How many hours of forecast to return") }, async (args) => { const response = await fetch( `https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}&hourly=precipitation_probability&forecast_days=1` ); const data: any = await response.json(); const chances = data.hourly.precipitation_probability.slice(0, args.hours); return { content: [{ type: "text", text: `Next ${args.hours} hours: ${chances.join("%, ")}%` }] }; } ); // Rebuild the server with both tools in the array const weatherServer = createSdkMcpServer({ name: "weather", version: "1.0.0", tools: [getTemperature, getPrecipitationChance] }); ``` Every tool in this array consumes context window space on every turn. If you're defining dozens of tools, see [tool search](/en/agent-sdk/tool-search) to load them on demand instead. ### Add tool annotations [Tool annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) are optional metadata describing how a tool behaves. Pass them as the fifth argument to `tool()` helper in TypeScript or via the `annotations` keyword argument for the `@tool` decorator in Python. All hint fields are Booleans. | Field | Default | Meaning | | :---------------- | :------ | :-------------------------------------------------------------------------------------------------------------------- | | `readOnlyHint` | `false` | Tool does not modify its environment. Controls whether the tool can be called in parallel with other read-only tools. | | `destructiveHint` | `true` | Tool may perform destructive updates. Informational only. | | `idempotentHint` | `false` | Repeated calls with the same arguments have no additional effect. Informational only. | | `openWorldHint` | `true` | Tool reaches systems outside your process. Informational only. | Annotations are metadata, not enforcement. A tool marked `readOnlyHint: true` can still write to disk if that's what the handler does. Keep the annotation accurate to the handler. This example adds `readOnlyHint` to the `get_temperature` tool from the [weather tool example](#weather-tool-example). ```python Python theme={null} from claude_agent_sdk import tool, ToolAnnotations @tool( "get_temperature", "Get the current temperature at a location", {"latitude": float, "longitude": float}, annotations=ToolAnnotations( readOnlyHint=True ), # Lets Claude batch this with other read-only calls ) async def get_temperature(args): return {"content": [{"type": "text", "text": "..."}]} ``` ```typescript TypeScript theme={null} tool( "get_temperature", "Get the current temperature at a location", { latitude: z.number(), longitude: z.number() }, async (args) => ({ content: [{ type: "text", text: `...` }] }), { annotations: { readOnlyHint: true } } // Lets Claude batch this with other read-only calls ); ``` See `ToolAnnotations` in the [TypeScript](/en/agent-sdk/typescript#tool-annotations) or [Python](/en/agent-sdk/python#tool-annotations) reference. ## Control tool access The [weather tool example](#weather-tool-example) registered a server and listed tools in `allowedTools`. This section covers how tool names are constructed and how to scope access when you have multiple tools or want to restrict built-ins. ### Tool name format When MCP tools are exposed to Claude, their names follow a specific format: * Pattern: `mcp__{server_name}__{tool_name}` * Example: A tool named `get_temperature` in server `weather` becomes `mcp__weather__get_temperature` ### Configure allowed tools The `tools` option and the allowed/disallowed lists operate on separate layers. `tools` controls which built-in tools appear in Claude's context. Allowed and disallowed tool lists control whether calls are approved or denied once Claude attempts them. | Option | Layer | Effect | | :------------------------ | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | | `tools: ["Read", "Grep"]` | Availability | Only the listed built-ins are in Claude's context. Unlisted built-ins are removed. MCP tools are unaffected. | | `tools: []` | Availability | All built-ins are removed. Claude can only use your MCP tools. | | allowed tools | Permission | Listed tools run without a permission prompt. Unlisted tools remain available; calls go through the [permission flow](/en/agent-sdk/permissions). | | disallowed tools | Permission | Every call to a listed tool is denied. The tool stays in Claude's context, so Claude may still attempt it before the call is rejected. | To limit which built-ins Claude can use, prefer `tools` over disallowed tools. Omitting a tool from `tools` removes it from context so Claude never attempts it; listing it in `disallowedTools` (Python: `disallowed_tools`) blocks the call but leaves the tool visible, so Claude may waste a turn trying it. See [Configure permissions](/en/agent-sdk/permissions) for the full evaluation order. ## Handle errors How your handler reports errors determines whether the agent loop continues or stops: | What happens | Result | | :--------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- | | Handler throws an uncaught exception | Agent loop stops. Claude never sees the error, and the `query` call fails. | | Handler catches the error and returns `isError: true` (TS) / `"is_error": True` (Python) | Agent loop continues. Claude sees the error as data and can retry, try a different tool, or explain the failure. | The example below catches two kinds of failures inside the handler instead of letting them throw. A non-200 HTTP status is caught from the response and returned as an error result. A network error or invalid JSON is caught by the surrounding `try/except` (Python) or `try/catch` (TypeScript) and also returned as an error result. In both cases the handler returns normally and the agent loop continues. ```python Python theme={null} import json import httpx from typing import Any @tool( "fetch_data", "Fetch data from an API", {"endpoint": str}, # Simple schema ) async def fetch_data(args: dict[str, Any]) -> dict[str, Any]: try: async with httpx.AsyncClient() as client: response = await client.get(args["endpoint"]) if response.status_code != 200: # Return the failure as a tool result so Claude can react to it. # is_error marks this as a failed call rather than odd-looking data. return { "content": [ { "type": "text", "text": f"API error: {response.status_code} {response.reason_phrase}", } ], "is_error": True, } data = response.json() return {"content": [{"type": "text", "text": json.dumps(data, indent=2)}]} except Exception as e: # Catching here keeps the agent loop alive. An uncaught exception # would end the whole query() call. return { "content": [{"type": "text", "text": f"Failed to fetch data: {str(e)}"}], "is_error": True, } ``` ```typescript TypeScript theme={null} tool( "fetch_data", "Fetch data from an API", { endpoint: z.string().url().describe("API endpoint URL") }, async (args) => { try { const response = await fetch(args.endpoint); if (!response.ok) { // Return the failure as a tool result so Claude can react to it. // isError marks this as a failed call rather than odd-looking data. return { content: [ { type: "text", text: `API error: ${response.status} ${response.statusText}` } ], isError: true }; } const data = await response.json(); return { content: [ { type: "text", text: JSON.stringify(data, null, 2) } ] }; } catch (error) { // Catching here keeps the agent loop alive. An uncaught throw // would end the whole query() call. return { content: [ { type: "text", text: `Failed to fetch data: ${error instanceof Error ? error.message : String(error)}` } ], isError: true }; } } ); ``` ## Return images and resources The `content` array in a tool result accepts `text`, `image`, and `resource` blocks. You can mix them in the same response. ### Images An image block carries the image bytes inline, encoded as base64. There is no URL field. To return an image that lives at a URL, fetch it in the handler, read the response bytes, and base64-encode them before returning. The result is processed as visual input. | Field | Type | Notes | | :--------- | :-------- | :------------------------------------------------------------------------- | | `type` | `"image"` | | | `data` | `string` | Base64-encoded bytes. Raw base64 only, no `data:image/...;base64,` prefix | | `mimeType` | `string` | Required. For example `image/png`, `image/jpeg`, `image/webp`, `image/gif` | ```python Python theme={null} import base64 import httpx # Define a tool that fetches an image from a URL and returns it to Claude @tool("fetch_image", "Fetch an image from a URL and return it to Claude", {"url": str}) async def fetch_image(args): async with httpx.AsyncClient() as client: # Fetch the image bytes response = await client.get(args["url"]) return { "content": [ { "type": "image", "data": base64.b64encode(response.content).decode( "ascii" ), # Base64-encode the raw bytes "mimeType": response.headers.get( "content-type", "image/png" ), # Read MIME type from the response } ] } ``` ```typescript TypeScript theme={null} tool( "fetch_image", "Fetch an image from a URL and return it to Claude", { url: z.string().url() }, async (args) => { const response = await fetch(args.url); // Fetch the image bytes const buffer = Buffer.from(await response.arrayBuffer()); // Read into a Buffer for base64 encoding const mimeType = response.headers.get("content-type") ?? "image/png"; return { content: [ { type: "image", data: buffer.toString("base64"), // Base64-encode the raw bytes mimeType } ] }; } ); ``` ### Resources A resource block embeds a piece of content identified by a URI. The URI is a label for Claude to reference; the actual content rides in the block's `text` or `blob` field. Use this when your tool produces something that makes sense to address by name later, such as a generated file or a record from an external system. | Field | Type | Notes | | :------------------ | :----------- | :---------------------------------------------------------- | | `type` | `"resource"` | | | `resource.uri` | `string` | Identifier for the content. Any URI scheme | | `resource.text` | `string` | The content, if it's text. Provide this or `blob`, not both | | `resource.blob` | `string` | The content base64-encoded, if it's binary | | `resource.mimeType` | `string` | Optional | This example shows a resource block returned from inside a tool handler. The URI `file:///tmp/report.md` is a label that Claude can reference later; the SDK does not read from that path. ```typescript TypeScript theme={null} return { content: [ { type: "resource", resource: { uri: "file:///tmp/report.md", // Label for Claude to reference, not a path the SDK reads mimeType: "text/markdown", text: "# Report\n..." // The actual content, inline } } ] }; ``` ```python Python theme={null} return { "content": [ { "type": "resource", "resource": { "uri": "file:///tmp/report.md", # Label for Claude to reference, not a path the SDK reads "mimeType": "text/markdown", "text": "# Report\n...", # The actual content, inline }, } ] } ``` These block shapes come from the MCP `CallToolResult` type. See the [MCP specification](../06-MCP-Tools/Spec-Archive/spec-2025-06-18-tools-model-context-protocol.md#tool-result) for the full definition. ## Example: unit converter This tool converts values between units of length, temperature, and weight. A user can ask "convert 100 kilometers to miles" or "what is 72°F in Celsius," and Claude picks the right unit type and units from the request. It demonstrates two patterns: * **Enum schemas:** `unit_type` is constrained to a fixed set of values. In TypeScript, use `z.enum()`. In Python, the dict schema doesn't support enums, so the full JSON Schema dict is required. * **Unsupported input handling:** when a conversion pair isn't found, the handler returns `isError: true` so Claude can tell the user what went wrong rather than treating a failure as a normal result. ```python Python theme={null} from typing import Any from claude_agent_sdk import tool, create_sdk_mcp_server # z.enum() in TypeScript becomes an "enum" constraint in JSON Schema. # The dict schema has no equivalent, so full JSON Schema is required. @tool( "convert_units", "Convert a value from one unit to another", { "type": "object", "properties": { "unit_type": { "type": "string", "enum": ["length", "temperature", "weight"], "description": "Category of unit", }, "from_unit": { "type": "string", "description": "Unit to convert from, e.g. kilometers, fahrenheit, pounds", }, "to_unit": {"type": "string", "description": "Unit to convert to"}, "value": {"type": "number", "description": "Value to convert"}, }, "required": ["unit_type", "from_unit", "to_unit", "value"], }, ) async def convert_units(args: dict[str, Any]) -> dict[str, Any]: conversions = { "length": { "kilometers_to_miles": lambda v: v * 0.621371, "miles_to_kilometers": lambda v: v * 1.60934, "meters_to_feet": lambda v: v * 3.28084, "feet_to_meters": lambda v: v * 0.3048, }, "temperature": { "celsius_to_fahrenheit": lambda v: (v * 9) / 5 + 32, "fahrenheit_to_celsius": lambda v: (v - 32) * 5 / 9, "celsius_to_kelvin": lambda v: v + 273.15, "kelvin_to_celsius": lambda v: v - 273.15, }, "weight": { "kilograms_to_pounds": lambda v: v * 2.20462, "pounds_to_kilograms": lambda v: v * 0.453592, "grams_to_ounces": lambda v: v * 0.035274, "ounces_to_grams": lambda v: v * 28.3495, }, } key = f"{args['from_unit']}_to_{args['to_unit']}" fn = conversions.get(args["unit_type"], {}).get(key) if not fn: return { "content": [ { "type": "text", "text": f"Unsupported conversion: {args['from_unit']} to {args['to_unit']}", } ], "is_error": True, } result = fn(args["value"]) return { "content": [ { "type": "text", "text": f"{args['value']} {args['from_unit']} = {result:.4f} {args['to_unit']}", } ] } converter_server = create_sdk_mcp_server( name="converter", version="1.0.0", tools=[convert_units], ) ``` ```typescript TypeScript theme={null} import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk"; import { z } from "zod"; const convert = tool( "convert_units", "Convert a value from one unit to another", { unit_type: z.enum(["length", "temperature", "weight"]).describe("Category of unit"), from_unit: z .string() .describe("Unit to convert from, e.g. kilometers, fahrenheit, pounds"), to_unit: z.string().describe("Unit to convert to"), value: z.number().describe("Value to convert") }, async (args) => { type Conversions = Record number>>; const conversions: Conversions = { length: { kilometers_to_miles: (v) => v * 0.621371, miles_to_kilometers: (v) => v * 1.60934, meters_to_feet: (v) => v * 3.28084, feet_to_meters: (v) => v * 0.3048 }, temperature: { celsius_to_fahrenheit: (v) => (v * 9) / 5 + 32, fahrenheit_to_celsius: (v) => ((v - 32) * 5) / 9, celsius_to_kelvin: (v) => v + 273.15, kelvin_to_celsius: (v) => v - 273.15 }, weight: { kilograms_to_pounds: (v) => v * 2.20462, pounds_to_kilograms: (v) => v * 0.453592, grams_to_ounces: (v) => v * 0.035274, ounces_to_grams: (v) => v * 28.3495 } }; const key = `${args.from_unit}_to_${args.to_unit}`; const fn = conversions[args.unit_type]?.[key]; if (!fn) { return { content: [ { type: "text", text: `Unsupported conversion: ${args.from_unit} to ${args.to_unit}` } ], isError: true }; } const result = fn(args.value); return { content: [ { type: "text", text: `${args.value} ${args.from_unit} = ${result.toFixed(4)} ${args.to_unit}` } ] }; } ); const converterServer = createSdkMcpServer({ name: "converter", version: "1.0.0", tools: [convert] }); ``` Once the server is defined, pass it to `query` the same way as the weather example. This example sends three different prompts in a loop to show the same tool handling different unit types. For each response, it inspects `AssistantMessage` objects (which contain the tool calls Claude made during that turn) and prints each `ToolUseBlock` before printing the final `ResultMessage` text. This lets you see when Claude is using the tool versus answering from its own knowledge. ```python Python theme={null} import asyncio from claude_agent_sdk import ( query, ClaudeAgentOptions, ResultMessage, AssistantMessage, ToolUseBlock, ) async def main(): options = ClaudeAgentOptions( mcp_servers={"converter": converter_server}, allowed_tools=["mcp__converter__convert_units"], ) prompts = [ "Convert 100 kilometers to miles.", "What is 72°F in Celsius?", "How many pounds is 5 kilograms?", ] for prompt in prompts: async for message in query(prompt=prompt, options=options): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, ToolUseBlock): print(f"[tool call] {block.name}({block.input})") elif isinstance(message, ResultMessage) and message.subtype == "success": print(f"Q: {prompt}\nA: {message.result}\n") asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; const prompts = [ "Convert 100 kilometers to miles.", "What is 72°F in Celsius?", "How many pounds is 5 kilograms?" ]; for (const prompt of prompts) { for await (const message of query({ prompt, options: { mcpServers: { converter: converterServer }, allowedTools: ["mcp__converter__convert_units"] } })) { if (message.type === "assistant") { for (const block of message.message.content) { if (block.type === "tool_use") { console.log(`[tool call] ${block.name}`, block.input); } } } else if (message.type === "result" && message.subtype === "success") { console.log(`Q: ${prompt}\nA: ${message.result}\n`); } } } ``` ## Next steps Custom tools wrap async functions in a standard interface. You can mix the patterns on this page in the same server: a single server can hold a database tool, an API gateway tool, and an image renderer alongside each other. From here: * If your server grows to dozens of tools, see [tool search](/en/agent-sdk/tool-search) to defer loading them until Claude needs them. * To connect to external MCP servers (filesystem, GitHub, Slack) instead of building your own, see [Connect MCP servers](/en/agent-sdk/mcp). * To control which tools run automatically versus requiring approval, see [Configure permissions](/en/agent-sdk/permissions). ## Related documentation * [TypeScript SDK Reference](/en/agent-sdk/typescript) * [Python SDK Reference](/en/agent-sdk/python) * [MCP Documentation](https://modelcontextprotocol.io) * [SDK Overview](/en/agent-sdk/overview) --- ## agent-sdk-file-checkpointing-1f8256a7ac.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Rewind file changes with checkpointing > Track file changes during agent sessions and restore files to any previous state File checkpointing tracks file modifications made through the Write, Edit, and NotebookEdit tools during an agent session, allowing you to rewind files to any previous state. Want to try it out? Jump to the [interactive example](#try-it-out). With checkpointing, you can: * **Undo unwanted changes** by restoring files to a known good state * **Explore alternatives** by restoring to a checkpoint and trying a different approach * **Recover from errors** when the agent makes incorrect modifications Only changes made through the Write, Edit, and NotebookEdit tools are tracked. Changes made through Bash commands (like `echo > file.txt` or `sed -i`) are not captured by the checkpoint system. ## How checkpointing works When you enable file checkpointing, the SDK creates backups of files before modifying them through the Write, Edit, or NotebookEdit tools. User messages in the response stream include a checkpoint UUID that you can use as a restore point. Checkpoint works with these built-in tools that the agent uses to modify files: | Tool | Description | | ------------ | ------------------------------------------------------------------ | | Write | Creates a new file or overwrites an existing file with new content | | Edit | Makes targeted edits to specific parts of an existing file | | NotebookEdit | Modifies cells in Jupyter notebooks (`.ipynb` files) | File rewinding restores files on disk to a previous state. It does not rewind the conversation itself. The conversation history and context remain intact after calling `rewindFiles()` (TypeScript) or `rewind_files()` (Python). The checkpoint system tracks: * Files created during the session * Files modified during the session * The original content of modified files When you rewind to a checkpoint, created files are deleted and modified files are restored to their content at that point. ## Implement checkpointing To use file checkpointing, enable it in your options, capture checkpoint UUIDs from the response stream, then call `rewindFiles()` (TypeScript) or `rewind_files()` (Python) when you need to restore. The following example shows the complete flow: enable checkpointing, capture the checkpoint UUID and session ID from the response stream, then resume the session later to rewind files. Each step is explained in detail below. ```python Python theme={null} import asyncio from claude_agent_sdk import ( ClaudeSDKClient, ClaudeAgentOptions, UserMessage, ResultMessage, ) async def main(): # Step 1: Enable checkpointing options = ClaudeAgentOptions( enable_file_checkpointing=True, permission_mode="acceptEdits", # Auto-accept file edits without prompting extra_args={ "replay-user-messages": None }, # Required to receive checkpoint UUIDs in the response stream ) checkpoint_id = None session_id = None # Run the query and capture checkpoint UUID and session ID async with ClaudeSDKClient(options) as client: await client.query("Refactor the authentication module") # Step 2: Capture checkpoint UUID from the first user message async for message in client.receive_response(): if isinstance(message, UserMessage) and message.uuid and not checkpoint_id: checkpoint_id = message.uuid if isinstance(message, ResultMessage) and not session_id: session_id = message.session_id # Step 3: Later, rewind by resuming the session with an empty prompt if checkpoint_id and session_id: async with ClaudeSDKClient( ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id) ) as client: await client.query("") # Empty prompt to open the connection async for message in client.receive_response(): await client.rewind_files(checkpoint_id) break print(f"Rewound to checkpoint: {checkpoint_id}") asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; async function main() { // Step 1: Enable checkpointing const opts = { enableFileCheckpointing: true, permissionMode: "acceptEdits" as const, // Auto-accept file edits without prompting extraArgs: { "replay-user-messages": null } // Required to receive checkpoint UUIDs in the response stream }; const response = query({ prompt: "Refactor the authentication module", options: opts }); let checkpointId: string | undefined; let sessionId: string | undefined; // Step 2: Capture checkpoint UUID from the first user message for await (const message of response) { if (message.type === "user" && message.uuid && !checkpointId) { checkpointId = message.uuid; } if ("session_id" in message && !sessionId) { sessionId = message.session_id; } } // Step 3: Later, rewind by resuming the session with an empty prompt if (checkpointId && sessionId) { const rewindQuery = query({ prompt: "", // Empty prompt to open the connection options: { ...opts, resume: sessionId } }); for await (const msg of rewindQuery) { await rewindQuery.rewindFiles(checkpointId); break; } console.log(`Rewound to checkpoint: ${checkpointId}`); } } main(); ``` Configure your SDK options to enable checkpointing and receive checkpoint UUIDs: | Option | Python | TypeScript | Description | | ------------------------ | ------------------------------------------- | --------------------------------------------- | ------------------------------------------------ | | Enable checkpointing | `enable_file_checkpointing=True` | `enableFileCheckpointing: true` | Tracks file changes for rewinding | | Receive checkpoint UUIDs | `extra_args={"replay-user-messages": None}` | `extraArgs: { 'replay-user-messages': null }` | Required to get user message UUIDs in the stream | ```python Python theme={null} options = ClaudeAgentOptions( enable_file_checkpointing=True, permission_mode="acceptEdits", extra_args={"replay-user-messages": None}, ) async with ClaudeSDKClient(options) as client: await client.query("Refactor the authentication module") ``` ```typescript TypeScript theme={null} const response = query({ prompt: "Refactor the authentication module", options: { enableFileCheckpointing: true, permissionMode: "acceptEdits" as const, extraArgs: { "replay-user-messages": null } } }); ``` With the `replay-user-messages` option set (shown above), each user message in the response stream has a UUID that serves as a checkpoint. For most use cases, capture the first user message UUID (`message.uuid`); rewinding to it restores all files to their original state. To store multiple checkpoints and rewind to intermediate states, see [Multiple restore points](#multiple-restore-points). Capturing the session ID (`message.session_id`) is optional; you only need it if you want to rewind later, after the stream completes. If you're calling `rewindFiles()` immediately while still processing messages (as the example in [Checkpoint before risky operations](#checkpoint-before-risky-operations) does), you can skip capturing the session ID. ```python Python theme={null} checkpoint_id = None session_id = None async for message in client.receive_response(): # Update checkpoint on each user message (keeps the latest) if isinstance(message, UserMessage) and message.uuid: checkpoint_id = message.uuid # Capture session ID from the result message if isinstance(message, ResultMessage): session_id = message.session_id ``` ```typescript TypeScript theme={null} let checkpointId: string | undefined; let sessionId: string | undefined; for await (const message of response) { // Update checkpoint on each user message (keeps the latest) if (message.type === "user" && message.uuid) { checkpointId = message.uuid; } // Capture session ID from any message that has it if ("session_id" in message) { sessionId = message.session_id; } } ``` To rewind after the stream completes, resume the session with an empty prompt and call `rewind_files()` (Python) or `rewindFiles()` (TypeScript) with your checkpoint UUID. You can also rewind during the stream; see [Checkpoint before risky operations](#checkpoint-before-risky-operations) for that pattern. ```python Python theme={null} async with ClaudeSDKClient( ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id) ) as client: await client.query("") # Empty prompt to open the connection async for message in client.receive_response(): await client.rewind_files(checkpoint_id) break ``` ```typescript TypeScript theme={null} const rewindQuery = query({ prompt: "", // Empty prompt to open the connection options: { ...opts, resume: sessionId } }); for await (const msg of rewindQuery) { await rewindQuery.rewindFiles(checkpointId); break; } ``` If you capture the session ID and checkpoint ID, you can also rewind from the CLI: ```bash theme={null} claude -p --resume --rewind-files ``` ## Common patterns These patterns show different ways to capture and use checkpoint UUIDs depending on your use case. ### Checkpoint before risky operations This pattern keeps only the most recent checkpoint UUID, updating it before each agent turn. If something goes wrong during processing, you can immediately rewind to the last safe state and break out of the loop. ```python Python theme={null} import asyncio from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage async def main(): options = ClaudeAgentOptions( enable_file_checkpointing=True, permission_mode="acceptEdits", extra_args={"replay-user-messages": None}, ) safe_checkpoint = None async with ClaudeSDKClient(options) as client: await client.query("Refactor the authentication module") async for message in client.receive_response(): # Update checkpoint before each agent turn starts # This overwrites the previous checkpoint. Only keep the latest if isinstance(message, UserMessage) and message.uuid: safe_checkpoint = message.uuid # Decide when to revert based on your own logic # For example: error detection, validation failure, or user input if your_revert_condition and safe_checkpoint: await client.rewind_files(safe_checkpoint) # Exit the loop after rewinding, files are restored break asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; async function main() { const response = query({ prompt: "Refactor the authentication module", options: { enableFileCheckpointing: true, permissionMode: "acceptEdits" as const, extraArgs: { "replay-user-messages": null } } }); let safeCheckpoint: string | undefined; for await (const message of response) { // Update checkpoint before each agent turn starts // This overwrites the previous checkpoint. Only keep the latest if (message.type === "user" && message.uuid) { safeCheckpoint = message.uuid; } // Decide when to revert based on your own logic // For example: error detection, validation failure, or user input if (yourRevertCondition && safeCheckpoint) { await response.rewindFiles(safeCheckpoint); // Exit the loop after rewinding, files are restored break; } } } main(); ``` ### Multiple restore points If Claude makes changes across multiple turns, you might want to rewind to a specific point rather than all the way back. For example, if Claude refactors a file in turn one and adds tests in turn two, you might want to keep the refactor but undo the tests. This pattern stores all checkpoint UUIDs in an array with metadata. After the session completes, you can rewind to any previous checkpoint: ```python Python theme={null} import asyncio from dataclasses import dataclass from datetime import datetime from claude_agent_sdk import ( ClaudeSDKClient, ClaudeAgentOptions, UserMessage, ResultMessage, ) # Store checkpoint metadata for better tracking @dataclass class Checkpoint: id: str description: str timestamp: datetime async def main(): options = ClaudeAgentOptions( enable_file_checkpointing=True, permission_mode="acceptEdits", extra_args={"replay-user-messages": None}, ) checkpoints = [] session_id = None async with ClaudeSDKClient(options) as client: await client.query("Refactor the authentication module") async for message in client.receive_response(): if isinstance(message, UserMessage) and message.uuid: checkpoints.append( Checkpoint( id=message.uuid, description=f"After turn {len(checkpoints) + 1}", timestamp=datetime.now(), ) ) if isinstance(message, ResultMessage) and not session_id: session_id = message.session_id # Later: rewind to any checkpoint by resuming the session if checkpoints and session_id: target = checkpoints[0] # Pick any checkpoint async with ClaudeSDKClient( ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id) ) as client: await client.query("") # Empty prompt to open the connection async for message in client.receive_response(): await client.rewind_files(target.id) break print(f"Rewound to: {target.description}") asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; // Store checkpoint metadata for better tracking interface Checkpoint { id: string; description: string; timestamp: Date; } async function main() { const opts = { enableFileCheckpointing: true, permissionMode: "acceptEdits" as const, extraArgs: { "replay-user-messages": null } }; const response = query({ prompt: "Refactor the authentication module", options: opts }); const checkpoints: Checkpoint[] = []; let sessionId: string | undefined; for await (const message of response) { if (message.type === "user" && message.uuid) { checkpoints.push({ id: message.uuid, description: `After turn ${checkpoints.length + 1}`, timestamp: new Date() }); } if ("session_id" in message && !sessionId) { sessionId = message.session_id; } } // Later: rewind to any checkpoint by resuming the session if (checkpoints.length > 0 && sessionId) { const target = checkpoints[0]; // Pick any checkpoint const rewindQuery = query({ prompt: "", // Empty prompt to open the connection options: { ...opts, resume: sessionId } }); for await (const msg of rewindQuery) { await rewindQuery.rewindFiles(target.id); break; } console.log(`Rewound to: ${target.description}`); } } main(); ``` ## Try it out This complete example creates a small utility file, has the agent add documentation comments, shows you the changes, then asks if you want to rewind. Before you begin, make sure you have the [Claude Agent SDK installed](/en/agent-sdk/quickstart). Create a new file called `utils.py` (Python) or `utils.ts` (TypeScript) and paste the following code: ```python utils.py theme={null} def add(a, b): return a + b def subtract(a, b): return a - b def multiply(a, b): return a * b def divide(a, b): if b == 0: raise ValueError("Cannot divide by zero") return a / b ``` ```typescript utils.ts theme={null} export function add(a: number, b: number): number { return a + b; } export function subtract(a: number, b: number): number { return a - b; } export function multiply(a: number, b: number): number { return a * b; } export function divide(a: number, b: number): number { if (b === 0) { throw new Error("Cannot divide by zero"); } return a / b; } ``` Create a new file called `try_checkpointing.py` (Python) or `try_checkpointing.ts` (TypeScript) in the same directory as your utility file, and paste the following code. This script asks Claude to add doc comments to your utility file, then gives you the option to rewind and restore the original. ```python try_checkpointing.py theme={null} import asyncio from claude_agent_sdk import ( ClaudeSDKClient, ClaudeAgentOptions, UserMessage, ResultMessage, ) async def main(): # Configure the SDK with checkpointing enabled # - enable_file_checkpointing: Track file changes for rewinding # - permission_mode: Auto-accept file edits without prompting # - extra_args: Required to receive user message UUIDs in the stream options = ClaudeAgentOptions( enable_file_checkpointing=True, permission_mode="acceptEdits", extra_args={"replay-user-messages": None}, ) checkpoint_id = None # Store the user message UUID for rewinding session_id = None # Store the session ID for resuming print("Running agent to add doc comments to utils.py...\n") # Run the agent and capture checkpoint data from the response stream async with ClaudeSDKClient(options) as client: await client.query("Add doc comments to utils.py") async for message in client.receive_response(): # Capture the first user message UUID - this is our restore point if isinstance(message, UserMessage) and message.uuid and not checkpoint_id: checkpoint_id = message.uuid # Capture the session ID so we can resume later if isinstance(message, ResultMessage): session_id = message.session_id print("Done! Open utils.py to see the added doc comments.\n") # Ask the user if they want to rewind the changes if checkpoint_id and session_id: response = input("Rewind to remove the doc comments? (y/n): ") if response.lower() == "y": # Resume the session with an empty prompt, then rewind async with ClaudeSDKClient( ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id) ) as client: await client.query("") # Empty prompt opens the connection async for message in client.receive_response(): await client.rewind_files(checkpoint_id) # Restore files break print( "\n✓ File restored! Open utils.py to verify the doc comments are gone." ) else: print("\nKept the modified file.") asyncio.run(main()) ``` ```typescript try_checkpointing.ts theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; import * as readline from "readline"; async function main() { // Configure the SDK with checkpointing enabled // - enableFileCheckpointing: Track file changes for rewinding // - permissionMode: Auto-accept file edits without prompting // - extraArgs: Required to receive user message UUIDs in the stream const opts = { enableFileCheckpointing: true, permissionMode: "acceptEdits" as const, extraArgs: { "replay-user-messages": null } }; let sessionId: string | undefined; // Store the session ID for resuming let checkpointId: string | undefined; // Store the user message UUID for rewinding console.log("Running agent to add doc comments to utils.ts...\n"); // Run the agent and capture checkpoint data from the response stream const response = query({ prompt: "Add doc comments to utils.ts", options: opts }); for await (const message of response) { // Capture the first user message UUID - this is our restore point if (message.type === "user" && message.uuid && !checkpointId) { checkpointId = message.uuid; } // Capture the session ID so we can resume later if ("session_id" in message) { sessionId = message.session_id; } } console.log("Done! Open utils.ts to see the added doc comments.\n"); // Ask the user if they want to rewind the changes if (checkpointId && sessionId) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); const answer = await new Promise((resolve) => { rl.question("Rewind to remove the doc comments? (y/n): ", resolve); }); rl.close(); if (answer.toLowerCase() === "y") { // Resume the session with an empty prompt, then rewind const rewindQuery = query({ prompt: "", // Empty prompt opens the connection options: { ...opts, resume: sessionId } }); for await (const msg of rewindQuery) { await rewindQuery.rewindFiles(checkpointId); // Restore files break; } console.log("\n✓ File restored! Open utils.ts to verify the doc comments are gone."); } else { console.log("\nKept the modified file."); } } } main(); ``` This example demonstrates the complete checkpointing workflow: 1. **Enable checkpointing**: configure the SDK with `enable_file_checkpointing=True` and `permission_mode="acceptEdits"` to auto-approve file edits 2. **Capture checkpoint data**: as the agent runs, store the first user message UUID (your restore point) and the session ID 3. **Prompt for rewind**: after the agent finishes, check your utility file to see the doc comments, then decide if you want to undo the changes 4. **Resume and rewind**: if yes, resume the session with an empty prompt and call `rewind_files()` to restore the original file Run the script from the same directory as your utility file. Open your utility file (`utils.py` or `utils.ts`) in your IDE or editor before running the script. You'll see the file update in real-time as the agent adds doc comments, then revert back to the original when you choose to rewind. ```bash theme={null} python try_checkpointing.py ``` ```bash theme={null} npx tsx try_checkpointing.ts ``` You'll see the agent add doc comments, then a prompt asking if you want to rewind. If you choose yes, the file is restored to its original state. ## Limitations File checkpointing has the following limitations: | Limitation | Description | | ---------------------------------- | -------------------------------------------------------------------- | | Write/Edit/NotebookEdit tools only | Changes made through Bash commands are not tracked | | Same session | Checkpoints are tied to the session that created them | | File content only | Creating, moving, or deleting directories is not undone by rewinding | | Local files | Remote or network files are not tracked | ## Troubleshooting ### Checkpointing options not recognized If `enableFileCheckpointing` or `rewindFiles()` isn't available, you may be on an older SDK version. **Solution**: Update to the latest SDK version: * **Python**: `pip install --upgrade claude-agent-sdk` * **TypeScript**: `npm install @anthropic-ai/claude-agent-sdk@latest` ### User messages don't have UUIDs If `message.uuid` is `undefined` or missing, you're not receiving checkpoint UUIDs. **Cause**: The `replay-user-messages` option isn't set. **Solution**: Add `extra_args={"replay-user-messages": None}` (Python) or `extraArgs: { 'replay-user-messages': null }` (TypeScript) to your options. ### "No file checkpoint found for message" error This error occurs when the checkpoint data doesn't exist for the specified user message UUID. **Common causes**: * File checkpointing was not enabled on the original session (`enable_file_checkpointing` or `enableFileCheckpointing` was not set to `true`) * The session wasn't properly completed before attempting to resume and rewind **Solution**: Ensure `enable_file_checkpointing=True` (Python) or `enableFileCheckpointing: true` (TypeScript) was set on the original session, then use the pattern shown in the examples: capture the first user message UUID, complete the session fully, then resume with an empty prompt and call `rewindFiles()` once. ### "ProcessTransport is not ready for writing" error This error occurs when you call `rewindFiles()` or `rewind_files()` after you've finished iterating through the response. The connection to the CLI process closes when the loop completes. **Solution**: Resume the session with an empty prompt, then call rewind on the new query: ```python Python theme={null} # Resume session with empty prompt, then rewind async with ClaudeSDKClient( ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id) ) as client: await client.query("") async for message in client.receive_response(): await client.rewind_files(checkpoint_id) break ``` ```typescript TypeScript theme={null} // Resume session with empty prompt, then rewind const rewindQuery = query({ prompt: "", options: { ...opts, resume: sessionId } }); for await (const msg of rewindQuery) { await rewindQuery.rewindFiles(checkpointId); break; } ``` ## Next steps * **[Sessions](/en/agent-sdk/sessions)**: learn how to resume sessions, which is required for rewinding after the stream completes. Covers session IDs, resuming conversations, and session forking. * **[Permissions](/en/agent-sdk/permissions)**: configure which tools Claude can use and how file modifications are approved. Useful if you want more control over when edits happen. * **[TypeScript SDK reference](/en/agent-sdk/typescript)**: complete API reference including all options for `query()` and the `rewindFiles()` method. * **[Python SDK reference](/en/agent-sdk/python)**: complete API reference including all options for `ClaudeAgentOptions` and the `rewind_files()` method. --- ## agent-sdk-hosting-44896d9df4.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Hosting the Agent SDK > Deploy and host Claude Agent SDK in production environments The Claude Agent SDK differs from traditional stateless LLM APIs in that it maintains conversational state and executes commands in a persistent environment. This guide covers the architecture, hosting considerations, and best practices for deploying SDK-based agents in production. For security hardening beyond basic sandboxing (including network controls, credential management, and isolation options), see [Secure Deployment](/en/agent-sdk/secure-deployment). ## Hosting Requirements ### Container-Based Sandboxing For security and isolation, the SDK should run inside a sandboxed container environment. This provides process isolation, resource limits, network control, and ephemeral filesystems. The SDK also supports [programmatic sandbox configuration](/en/agent-sdk/typescript#sandbox-settings) for command execution. ### System Requirements Each SDK instance requires: * **Runtime dependencies** * Python 3.10+ for the Python SDK, or Node.js 18+ for the TypeScript SDK * Both SDK packages bundle a native Claude Code binary for the host platform, so no separate Claude Code or Node.js install is needed for the spawned CLI * **Resource allocation** * Recommended: 1GiB RAM, 5GiB of disk, and 1 CPU (vary this based on your task as needed) * **Network access** * Outbound HTTPS to `api.anthropic.com` * Optional: Access to MCP servers or external tools ## Understanding the SDK Architecture Unlike stateless API calls, the Claude Agent SDK operates as a **long-running process** that: * **Executes commands** in a persistent shell environment * **Manages file operations** within a working directory * **Handles tool execution** with context from previous interactions ## Sandbox Provider Options Several providers specialize in secure container environments for AI code execution: * **[Modal Sandbox](https://modal.com/docs/guide/sandbox)** - [demo implementation](https://modal.com/docs/examples/claude-slack-gif-creator) * **[Cloudflare Sandboxes](https://github.com/cloudflare/sandbox-sdk)** * **[Daytona](https://www.daytona.io/)** * **[E2B](https://e2b.dev/)** * **[Fly Machines](https://fly.io/docs/machines/)** * **[Vercel Sandbox](https://vercel.com/docs/functions/sandbox)** For self-hosted options (Docker, gVisor, Firecracker) and detailed isolation configuration, see [Isolation Technologies](/en/agent-sdk/secure-deployment#isolation-technologies). ## Production Deployment Patterns ### Pattern 1: Ephemeral Sessions Create a new container for each user task, then destroy it when complete. Best for one-off tasks, the user may still interact with the AI while the task is completing, but once completed the container is destroyed. **Examples:** * Bug Investigation & Fix: Debug and resolve a specific issue with relevant context * Invoice Processing: Extract and structure data from receipts/invoices for accounting systems * Translation Tasks: Translate documents or content batches between languages * Image/Video Processing: Apply transformations, optimizations, or extract metadata from media files ### Pattern 2: Long-Running Sessions Maintain persistent container instances for long running tasks. Often times running *multiple* Claude Agent processes inside of the container based on demand. Best for proactive agents that take action without the users input, agents that serve content or agents that process high amounts of messages. **Examples:** * Email Agent: Monitors incoming emails and autonomously triages, responds, or takes actions based on content * Site Builder: Hosts custom websites per user with live editing capabilities served through container ports * High-Frequency Chat Bots: Handles continuous message streams from platforms like Slack where rapid response times are critical ### Pattern 3: Hybrid Sessions Ephemeral containers that are hydrated with history and state, possibly from a database or from the SDK's session resumption features. Best for containers with intermittent interaction from the user that kicks off work and spins down when the work is completed but can be continued. **Examples:** * Personal Project Manager: Helps manage ongoing projects with intermittent check-ins, maintains context of tasks, decisions, and progress * Deep Research: Conducts multi-hour research tasks, saves findings and resumes investigation when user returns * Customer Support Agent: Handles support tickets that span multiple interactions, loads ticket history and customer context ### Pattern 4: Single Containers Run multiple Claude Agent SDK processes in one global container. Best for agents that must collaborate closely together. This is likely the least popular pattern because you will have to prevent agents from overwriting each other. **Examples:** * **Simulations**: Agents that interact with each other in simulations such as video games. ## FAQ ### How do I communicate with my sandboxes? When hosting in containers, expose ports to communicate with your SDK instances. Your application can expose HTTP/WebSocket endpoints for external clients while the SDK runs internally within the container. ### What is the cost of hosting a container? The dominant cost of serving agents is the tokens; containers vary based on what you provision, but a minimum cost is roughly 5 cents per hour running. ### When should I shut down idle containers vs. keeping them warm? This is likely provider dependent, different sandbox providers will let you set different criteria for idle timeouts after which a sandbox might spin down. You will want to tune this timeout based on how frequent you think user response might be. ### How often should I update the Claude Code CLI? The Claude Code CLI is versioned with semver, so any breaking changes will be versioned. ### How do I monitor container health and agent performance? Since containers are just servers the same logging infrastructure you use for the backend will work for containers. ### How long can an agent session run before timing out? An agent session will not timeout, but consider setting a 'maxTurns' property to prevent Claude from getting stuck in a loop. ## Next Steps * [Secure Deployment](/en/agent-sdk/secure-deployment) - Network controls, credential management, and isolation hardening * [TypeScript SDK - Sandbox Settings](/en/agent-sdk/typescript#sandbox-settings) - Configure sandbox programmatically * [Sessions Guide](/en/agent-sdk/sessions) - Learn about session management * [Permissions](/en/agent-sdk/permissions) - Configure tool permissions * [Cost Tracking](/en/agent-sdk/cost-tracking) - Monitor API usage * [MCP Integration](/en/agent-sdk/mcp) - Extend with custom tools --- ## agent-sdk-migration-guide-383fc97c1d.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Migrate to Claude Agent SDK > Guide for migrating the Claude Code TypeScript and Python SDKs to the Claude Agent SDK ## Overview The Claude Code SDK has been renamed to the **Claude Agent SDK** and its documentation has been reorganized. This change reflects the SDK's broader capabilities for building AI agents beyond just coding tasks. ## What's Changed | Aspect | Old | New | | :------------------------- | :-------------------------- | :------------------------------- | | **Package Name (TS/JS)** | `@anthropic-ai/claude-code` | `@anthropic-ai/claude-agent-sdk` | | **Python Package** | `claude-code-sdk` | `claude-agent-sdk` | | **Documentation Location** | Claude Code docs | API Guide → Agent SDK section | **Documentation Changes:** The Agent SDK documentation has moved from the Claude Code docs to the API Guide under a dedicated [Agent SDK](/en/agent-sdk/overview) section. The Claude Code docs now focus on the CLI tool and automation features. ## Migration Steps ### For TypeScript/JavaScript Projects **1. Uninstall the old package:** ```bash theme={null} npm uninstall @anthropic-ai/claude-code ``` **2. Install the new package:** ```bash theme={null} npm install @anthropic-ai/claude-agent-sdk ``` **3. Update your imports:** Change all imports from `@anthropic-ai/claude-code` to `@anthropic-ai/claude-agent-sdk`: ```typescript theme={null} // Before import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code"; // After import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk"; ``` **4. Update package.json dependencies:** If you have the package listed in your `package.json`, update it: Before: ```json theme={null} { "dependencies": { "@anthropic-ai/claude-code": "^0.0.42" } } ``` After: ```json theme={null} { "dependencies": { "@anthropic-ai/claude-agent-sdk": "^0.2.0" } } ``` That's it! No other code changes are required. ### For Python Projects **1. Uninstall the old package:** ```bash theme={null} pip uninstall claude-code-sdk ``` **2. Install the new package:** ```bash theme={null} pip install claude-agent-sdk ``` **3. Update your imports:** Change all imports from `claude_code_sdk` to `claude_agent_sdk`: ```python theme={null} # Before from claude_code_sdk import query, ClaudeCodeOptions # After from claude_agent_sdk import query, ClaudeAgentOptions ``` **4. Update type names:** Change `ClaudeCodeOptions` to `ClaudeAgentOptions`: ```python theme={null} # Before from claude_code_sdk import query, ClaudeCodeOptions options = ClaudeCodeOptions(model="claude-opus-4-7") # After from claude_agent_sdk import query, ClaudeAgentOptions options = ClaudeAgentOptions(model="claude-opus-4-7") ``` **5. Review [breaking changes](#breaking-changes)** Make any code changes needed to complete the migration. ## Breaking changes To improve isolation and explicit configuration, Claude Agent SDK v0.1.0 introduces breaking changes for users migrating from Claude Code SDK. Review this section carefully before migrating. ### Python: ClaudeCodeOptions renamed to ClaudeAgentOptions **What changed:** The Python SDK type `ClaudeCodeOptions` has been renamed to `ClaudeAgentOptions`. **Migration:** ```python theme={null} # BEFORE (claude-code-sdk) from claude_code_sdk import query, ClaudeCodeOptions options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits") # AFTER (claude-agent-sdk) from claude_agent_sdk import query, ClaudeAgentOptions options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits") ``` **Why this changed:** The type name now matches the "Claude Agent SDK" branding and provides consistency across the SDK's naming conventions. ### System prompt no longer default **What changed:** The SDK no longer uses Claude Code's system prompt by default. **Migration:** ```typescript TypeScript theme={null} // BEFORE (v0.0.x) - Used Claude Code's system prompt by default const result = query({ prompt: "Hello" }); // AFTER (v0.1.0) - Uses minimal system prompt by default // To get the old behavior, explicitly request Claude Code's preset: const result = query({ prompt: "Hello", options: { systemPrompt: { type: "preset", preset: "claude_code" } } }); // Or use a custom system prompt: const result = query({ prompt: "Hello", options: { systemPrompt: "You are a helpful coding assistant" } }); ``` ```python Python theme={null} # BEFORE (v0.0.x) - Used Claude Code's system prompt by default async for message in query(prompt="Hello"): print(message) # AFTER (v0.1.0) - Uses minimal system prompt by default # To get the old behavior, explicitly request Claude Code's preset: from claude_agent_sdk import query, ClaudeAgentOptions async for message in query( prompt="Hello", options=ClaudeAgentOptions( system_prompt={"type": "preset", "preset": "claude_code"} # Use the preset ), ): print(message) # Or use a custom system prompt: async for message in query( prompt="Hello", options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"), ): print(message) ``` **Why this changed:** Provides better control and isolation for SDK applications. You can now build agents with custom behavior without inheriting Claude Code's CLI-focused instructions. ### Settings Sources No Longer Loaded by Default **What changed:** The SDK no longer reads from filesystem settings (CLAUDE.md, settings.json, slash commands, etc.) by default. **Migration:** ```typescript TypeScript theme={null} // BEFORE (v0.0.x) - Loaded all settings automatically const result = query({ prompt: "Hello" }); // Would read from: // - ~/.claude/settings.json (user) // - .claude/settings.json (project) // - .claude/settings.local.json (local) // - CLAUDE.md files // - Custom slash commands // AFTER (v0.1.0) - No settings loaded by default // To get the old behavior: const result = query({ prompt: "Hello", options: { settingSources: ["user", "project", "local"] } }); // Or load only specific sources: const result = query({ prompt: "Hello", options: { settingSources: ["project"] // Only project settings } }); ``` ```python Python theme={null} # BEFORE (v0.0.x) - Loaded all settings automatically async for message in query(prompt="Hello"): print(message) # Would read from: # - ~/.claude/settings.json (user) # - .claude/settings.json (project) # - .claude/settings.local.json (local) # - CLAUDE.md files # - Custom slash commands # AFTER (v0.1.0) - No settings loaded by default # To get the old behavior: from claude_agent_sdk import query, ClaudeAgentOptions async for message in query( prompt="Hello", options=ClaudeAgentOptions(setting_sources=["user", "project", "local"]), ): print(message) # Or load only specific sources: async for message in query( prompt="Hello", options=ClaudeAgentOptions( setting_sources=["project"] # Only project settings ), ): print(message) ``` **Why this changed:** Ensures SDK applications have predictable behavior independent of local filesystem configurations. This is especially important for: * **CI/CD environments** - Consistent behavior without local customizations * **Deployed applications** - No dependency on filesystem settings * **Testing** - Isolated test environments * **Multi-tenant systems** - Prevent settings leakage between users Current SDK releases have reverted this default for `query()`: omitting the option once again loads user, project, and local settings, matching the CLI. Pass `settingSources: []` in TypeScript or `setting_sources=[]` in Python if your application depends on the isolated behavior described above. Python SDK 0.1.59 and earlier treated an empty list the same as omitting the option, so upgrade before relying on `setting_sources=[]`. See [What settingSources does not control](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) for inputs that are read even when `settingSources` is `[]`. ## Why the Rename? The Claude Code SDK was originally designed for coding tasks, but it has evolved into a powerful framework for building all types of AI agents. The new name "Claude Agent SDK" better reflects its capabilities: * Building business agents (legal assistants, finance advisors, customer support) * Creating specialized coding agents (SRE bots, security reviewers, code review agents) * Developing custom agents for any domain with tool use, MCP integration, and more ## Getting Help If you encounter any issues during migration: **For TypeScript/JavaScript:** 1. Check that all imports are updated to use `@anthropic-ai/claude-agent-sdk` 2. Verify your package.json has the new package name 3. Run `npm install` to ensure dependencies are updated **For Python:** 1. Check that all imports are updated to use `claude_agent_sdk` 2. Verify your requirements.txt or pyproject.toml has the new package name 3. Run `pip install claude-agent-sdk` to ensure the package is installed ## Next Steps * Explore the [Agent SDK Overview](/en/agent-sdk/overview) to learn about available features * Check out the [TypeScript SDK Reference](/en/agent-sdk/typescript) for detailed API documentation * Review the [Python SDK Reference](/en/agent-sdk/python) for Python-specific documentation * Learn about [Custom Tools](/en/agent-sdk/custom-tools) and [MCP Integration](/en/agent-sdk/mcp) --- ## agent-sdk-modifying-system-prompts-47fd7ffb8f.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Modifying system prompts > Learn how to customize Claude's behavior by modifying system prompts using three approaches - output styles, systemPrompt with append, and custom system prompts. System prompts define Claude's behavior, capabilities, and response style. The Claude Agent SDK provides three ways to customize system prompts: using output styles (persistent, file-based configurations), appending to Claude Code's prompt, or using a fully custom prompt. ## Understanding system prompts A system prompt is the initial instruction set that shapes how Claude behaves throughout a conversation. **Default behavior:** The Agent SDK uses a **minimal system prompt** by default. It contains only essential tool instructions but omits Claude Code's coding guidelines, response style, and project context. To include the full Claude Code system prompt, specify `systemPrompt: { type: "preset", preset: "claude_code" }` in TypeScript or `system_prompt={"type": "preset", "preset": "claude_code"}` in Python. Claude Code's system prompt includes: * Tool usage instructions and available tools * Code style and formatting guidelines * Response tone and verbosity settings * Security and safety instructions * Context about the current working directory and environment ## Methods of modification ### Method 1: CLAUDE.md files (project-level instructions) CLAUDE.md files provide project-specific context and instructions that are automatically read by the Agent SDK when it runs in a directory. They serve as persistent "memory" for your project. #### How CLAUDE.md works with the SDK **Location and discovery:** * **Project-level:** `CLAUDE.md` or `.claude/CLAUDE.md` in your working directory * **User-level:** `~/.claude/CLAUDE.md` for global instructions across all projects CLAUDE.md files are read when the corresponding setting source is enabled: `'project'` for project-level CLAUDE.md and `'user'` for `~/.claude/CLAUDE.md`. With default `query()` options both sources are enabled, so CLAUDE.md loads automatically. If you set `settingSources` (TypeScript) or `setting_sources` (Python) explicitly, include the sources you need. CLAUDE.md loading is controlled by setting sources, not by the `claude_code` preset. **Content format:** CLAUDE.md files use plain markdown and can contain: * Coding guidelines and standards * Project-specific context * Common commands or workflows * API conventions * Testing requirements #### Example CLAUDE.md ```markdown theme={null} # Project Guidelines ## Code Style - Use TypeScript strict mode - Prefer functional components in React - Always include JSDoc comments for public APIs ## Testing - Run `npm test` before committing - Maintain >80% code coverage - Use jest for unit tests, playwright for E2E ## Commands - Build: `npm run build` - Dev server: `npm run dev` - Type check: `npm run typecheck` ``` #### Using CLAUDE.md with the SDK ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; const messages = []; for await (const message of query({ prompt: "Add a new React component for user profiles", options: { systemPrompt: { type: "preset", preset: "claude_code" // Use Claude Code's system prompt }, settingSources: ["project"] // Loads CLAUDE.md from project } })) { messages.push(message); } // Now Claude has access to your project guidelines from CLAUDE.md ``` ```python Python theme={null} from claude_agent_sdk import query, ClaudeAgentOptions messages = [] async for message in query( prompt="Add a new React component for user profiles", options=ClaudeAgentOptions( system_prompt={ "type": "preset", "preset": "claude_code", # Use Claude Code's system prompt }, setting_sources=["project"], # Loads CLAUDE.md from project ), ): messages.append(message) # Now Claude has access to your project guidelines from CLAUDE.md ``` #### When to use CLAUDE.md **Best for:** * **Team-shared context** - Guidelines everyone should follow * **Project conventions** - Coding standards, file structure, naming patterns * **Common commands** - Build, test, deploy commands specific to your project * **Long-term memory** - Context that should persist across all sessions * **Version-controlled instructions** - Commit to git so the team stays in sync **Key characteristics:** * ✅ Persistent across all sessions in a project * ✅ Shared with team via git * ✅ Automatic discovery (no code changes needed) * ⚠️ Not loaded if you pass `settingSources: []` ### Method 2: Output styles (persistent configurations) Output styles are saved configurations that modify Claude's system prompt. They're stored as markdown files and can be reused across sessions and projects. #### Creating an output style ```typescript TypeScript theme={null} import { writeFile, mkdir } from "fs/promises"; import { join } from "path"; import { homedir } from "os"; async function createOutputStyle(name: string, description: string, prompt: string) { // User-level: ~/.claude/output-styles // Project-level: .claude/output-styles const outputStylesDir = join(homedir(), ".claude", "output-styles"); await mkdir(outputStylesDir, { recursive: true }); const content = `--- name: ${name} description: ${description} --- ${prompt}`; const filePath = join(outputStylesDir, `${name.toLowerCase().replace(/\s+/g, "-")}.md`); await writeFile(filePath, content, "utf-8"); } // Example: Create a code review specialist await createOutputStyle( "Code Reviewer", "Thorough code review assistant", `You are an expert code reviewer. For every code submission: 1. Check for bugs and security issues 2. Evaluate performance 3. Suggest improvements 4. Rate code quality (1-10)` ); ``` ```python Python theme={null} from pathlib import Path async def create_output_style(name: str, description: str, prompt: str): # User-level: ~/.claude/output-styles # Project-level: .claude/output-styles output_styles_dir = Path.home() / ".claude" / "output-styles" output_styles_dir.mkdir(parents=True, exist_ok=True) content = f"""--- name: {name} description: {description} --- {prompt}""" file_name = name.lower().replace(" ", "-") + ".md" file_path = output_styles_dir / file_name file_path.write_text(content, encoding="utf-8") # Example: Create a code review specialist await create_output_style( "Code Reviewer", "Thorough code review assistant", """You are an expert code reviewer. For every code submission: 1. Check for bugs and security issues 2. Evaluate performance 3. Suggest improvements 4. Rate code quality (1-10)""", ) ``` #### Using output styles Once created, activate output styles via: * **CLI**: `/output-style [style-name]` * **Settings**: `.claude/settings.local.json` * **Create new**: `/output-style:new [description]` **Note for SDK users:** Output styles are loaded when you include `settingSources: ['user']` or `settingSources: ['project']` (TypeScript) / `setting_sources=["user"]` or `setting_sources=["project"]` (Python) in your options. ### Method 3: Using `systemPrompt` with append You can use the Claude Code preset with an `append` property to add your custom instructions while preserving all built-in functionality. ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; const messages = []; for await (const message of query({ prompt: "Help me write a Python function to calculate fibonacci numbers", options: { systemPrompt: { type: "preset", preset: "claude_code", append: "Always include detailed docstrings and type hints in Python code." } } })) { messages.push(message); if (message.type === "assistant") { console.log(message.message.content); } } ``` ```python Python theme={null} from claude_agent_sdk import query, ClaudeAgentOptions messages = [] async for message in query( prompt="Help me write a Python function to calculate fibonacci numbers", options=ClaudeAgentOptions( system_prompt={ "type": "preset", "preset": "claude_code", "append": "Always include detailed docstrings and type hints in Python code.", } ), ): messages.append(message) if message.type == "assistant": print(message.message.content) ``` #### Improve prompt caching across users and machines By default, two sessions that use the same `claude_code` preset and `append` text still cannot share a prompt cache entry if they run from different working directories. This is because the preset embeds per-session context in the system prompt ahead of your `append` text: the working directory, platform and OS version, current date, git status, and auto-memory paths. Any difference in that context produces a different system prompt and a cache miss. To make the system prompt identical across sessions, set `excludeDynamicSections: true` in TypeScript or `"exclude_dynamic_sections": True` in Python. The per-session context moves into the first user message, leaving only the static preset and your `append` text in the system prompt so identical configurations share a cache entry across users and machines. `excludeDynamicSections` requires `@anthropic-ai/claude-agent-sdk` v0.2.98 or later, or `claude-agent-sdk` v0.1.58 or later for Python. It applies only to the preset object form and has no effect when `systemPrompt` is a string. The following example pairs a shared `append` block with `excludeDynamicSections` so a fleet of agents running from different directories can reuse the same cached system prompt: ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Triage the open issues in this repo", options: { systemPrompt: { type: "preset", preset: "claude_code", append: "You operate Acme's internal triage workflow. Label issues by component and severity.", excludeDynamicSections: true } } })) { // ... } ``` ```python Python theme={null} from claude_agent_sdk import query, ClaudeAgentOptions async for message in query( prompt="Triage the open issues in this repo", options=ClaudeAgentOptions( system_prompt={ "type": "preset", "preset": "claude_code", "append": "You operate Acme's internal triage workflow. Label issues by component and severity.", "exclude_dynamic_sections": True, }, ), ): ... ``` **Tradeoffs:** the working directory, git status, and memory location still reach Claude, but as part of the first user message rather than the system prompt. Instructions in the user message carry marginally less weight than the same text in the system prompt, so Claude may rely on them less strongly when reasoning about the current directory or auto-memory paths. Enable this option when cross-session cache reuse matters more than maximally authoritative environment context. For the equivalent flag in non-interactive CLI mode, see [`--exclude-dynamic-system-prompt-sections`](../02-Claude-Code-CLI/cli-reference-7bb98e3312.md). ### Method 4: Custom system prompts You can provide a custom string as `systemPrompt` to replace the default entirely with your own instructions. ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; const customPrompt = `You are a Python coding specialist. Follow these guidelines: - Write clean, well-documented code - Use type hints for all functions - Include comprehensive docstrings - Prefer functional programming patterns when appropriate - Always explain your code choices`; const messages = []; for await (const message of query({ prompt: "Create a data processing pipeline", options: { systemPrompt: customPrompt } })) { messages.push(message); if (message.type === "assistant") { console.log(message.message.content); } } ``` ```python Python theme={null} from claude_agent_sdk import query, ClaudeAgentOptions custom_prompt = """You are a Python coding specialist. Follow these guidelines: - Write clean, well-documented code - Use type hints for all functions - Include comprehensive docstrings - Prefer functional programming patterns when appropriate - Always explain your code choices""" messages = [] async for message in query( prompt="Create a data processing pipeline", options=ClaudeAgentOptions(system_prompt=custom_prompt), ): messages.append(message) if message.type == "assistant": print(message.message.content) ``` ## Comparison of all four approaches | Feature | CLAUDE.md | Output Styles | `systemPrompt` with append | Custom `systemPrompt` | | ----------------------- | ---------------- | --------------- | -------------------------- | ---------------------- | | **Persistence** | Per-project file | Saved as files | Session only | Session only | | **Reusability** | Per-project | Across projects | Code duplication | Code duplication | | **Management** | On filesystem | CLI + files | In code | In code | | **Default tools** | Preserved | Preserved | Preserved | Lost (unless included) | | **Built-in safety** | Maintained | Maintained | Maintained | Must be added | | **Environment context** | Automatic | Automatic | Automatic | Must be provided | | **Customization level** | Additions only | Replace default | Additions only | Complete control | | **Version control** | With project | Yes | With code | With code | | **Scope** | Project-specific | User or project | Code session | Code session | **Note:** "With append" means using `systemPrompt: { type: "preset", preset: "claude_code", append: "..." }` in TypeScript or `system_prompt={"type": "preset", "preset": "claude_code", "append": "..."}` in Python. ## Use cases and best practices ### When to use CLAUDE.md **Best for:** * Project-specific coding standards and conventions * Documenting project structure and architecture * Listing common commands (build, test, deploy) * Team-shared context that should be version controlled * Instructions that apply to all SDK usage in a project **Examples:** * "All API endpoints should use async/await patterns" * "Run `npm run lint:fix` before committing" * "Database migrations are in the `migrations/` directory" CLAUDE.md files load when the `project` setting source is enabled, which it is for default `query()` options. If you set `settingSources` (TypeScript) or `setting_sources` (Python) explicitly, include `'project'` to keep loading project-level CLAUDE.md. ### When to use output styles **Best for:** * Persistent behavior changes across sessions * Team-shared configurations * Specialized assistants (code reviewer, data scientist, DevOps) * Complex prompt modifications that need versioning **Examples:** * Creating a dedicated SQL optimization assistant * Building a security-focused code reviewer * Developing a teaching assistant with specific pedagogy ### When to use `systemPrompt` with append **Best for:** * Adding specific coding standards or preferences * Customizing output formatting * Adding domain-specific knowledge * Modifying response verbosity * Enhancing Claude Code's default behavior without losing tool instructions ### When to use custom `systemPrompt` **Best for:** * Complete control over Claude's behavior * Specialized single-session tasks * Testing new prompt strategies * Situations where default tools aren't needed * Building specialized agents with unique behavior ## Combining approaches You can combine these methods for maximum flexibility: ### Example: Output style with session-specific additions ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; // Assuming "Code Reviewer" output style is active (via /output-style) // Add session-specific focus areas const messages = []; for await (const message of query({ prompt: "Review this authentication module", options: { systemPrompt: { type: "preset", preset: "claude_code", append: ` For this review, prioritize: - OAuth 2.0 compliance - Token storage security - Session management ` } } })) { messages.push(message); } ``` ```python Python theme={null} from claude_agent_sdk import query, ClaudeAgentOptions # Assuming "Code Reviewer" output style is active (via /output-style) # Add session-specific focus areas messages = [] async for message in query( prompt="Review this authentication module", options=ClaudeAgentOptions( system_prompt={ "type": "preset", "preset": "claude_code", "append": """ For this review, prioritize: - OAuth 2.0 compliance - Token storage security - Session management """, } ), ): messages.append(message) ``` ## See also * [Output styles](../02-Claude-Code-CLI/output-styles-claude-code-docs-c315eeed32.md) - Complete output styles documentation * [TypeScript SDK guide](/en/agent-sdk/typescript) - Complete SDK usage guide * [Configuration guide](../02-Claude-Code-CLI/claude-code-settings-claude-code-docs-d4420b4b52.md) - General configuration options --- ## agent-sdk-observability-f4c4535fce.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Observability with OpenTelemetry > Export traces, metrics, and events from the Agent SDK to your observability backend using OpenTelemetry. When you run agents in production, you need visibility into what they did: * which tools they called * how long each model request took * how many tokens were spent * where failures occurred The Agent SDK can export this data as OpenTelemetry traces, metrics, and log events to any backend that accepts the OpenTelemetry Protocol (OTLP), such as Honeycomb, Datadog, Grafana, Langfuse, or a self-hosted collector. This guide explains how the SDK emits telemetry, how to configure the export, and how to tag and filter the data once it reaches your backend. To read token usage and cost directly from the SDK response stream instead of exporting to a backend, see [Track cost and usage](/en/agent-sdk/cost-tracking). ## How telemetry flows from the SDK The Agent SDK runs the Claude Code CLI as a child process and communicates with it over a local pipe. The CLI has OpenTelemetry instrumentation built in: it records spans around each model request and tool execution, emits metrics for token and cost counters, and emits structured log events for prompts and tool results. The SDK does not produce telemetry of its own. Instead, it passes configuration through to the CLI process, and the CLI exports directly to your collector. Configuration is passed as environment variables. By default, the child process inherits your application's environment, so you can configure telemetry in either of two places: * **Process environment:** set the variables in your shell, container, or orchestrator before your application starts. Every `query()` call picks them up automatically with no code change. This is the recommended approach for production deployments. * **Per-call options:** set the variables in `ClaudeAgentOptions.env` (Python) or `options.env` (TypeScript). Use this when different agents in the same process need different telemetry settings. In Python, `env` is merged on top of the inherited environment. In TypeScript, `env` replaces the inherited environment entirely, so include `...process.env` in the object you pass. The CLI exports three independent OpenTelemetry signals. Each has its own enable switch and its own exporter, so you can turn on only the ones you need. | Signal | What it contains | Enable with | | ---------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------- | | Metrics | Counters for tokens, cost, sessions, lines of code, and tool decisions | `OTEL_METRICS_EXPORTER` | | Log events | Structured records for each prompt, API request, API error, and tool result | `OTEL_LOGS_EXPORTER` | | Traces | Spans for each interaction, model request, tool call, and hook (beta) | `OTEL_TRACES_EXPORTER` plus `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` | For the complete list of metric names, event names, and attributes, see the Claude Code [Monitoring](../13-Enterprise-Admin/monitoring-claude-code-docs-72c46f3dc8.md) reference. The Agent SDK emits the same data because it runs the same CLI. Span names are listed in [Read agent traces](#read-agent-traces) below. ## Enable telemetry export Telemetry is off until you set `CLAUDE_CODE_ENABLE_TELEMETRY=1` and choose at least one exporter. The most common configuration sends all three signals over OTLP HTTP to a collector. The following example sets the variables in a dictionary and passes them through `options.env`. The agent runs a single task, and the CLI exports spans, metrics, and events to the collector at `collector.example.com` while the loop consumes the response stream: ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions OTEL_ENV = { "CLAUDE_CODE_ENABLE_TELEMETRY": "1", # Required for traces, which are in beta. Metrics and log events do not need this. "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1", # Choose an exporter per signal. Use otlp for the SDK; see the Note below. "OTEL_TRACES_EXPORTER": "otlp", "OTEL_METRICS_EXPORTER": "otlp", "OTEL_LOGS_EXPORTER": "otlp", # Standard OTLP transport configuration. "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf", "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4318", "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-token", } async def main(): options = ClaudeAgentOptions(env=OTEL_ENV) async for message in query( prompt="List the files in this directory", options=options ): print(message) asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; const otelEnv = { CLAUDE_CODE_ENABLE_TELEMETRY: "1", // Required for traces, which are in beta. Metrics and log events do not need this. CLAUDE_CODE_ENHANCED_TELEMETRY_BETA: "1", // Choose an exporter per signal. Use otlp for the SDK; see the Note below. OTEL_TRACES_EXPORTER: "otlp", OTEL_METRICS_EXPORTER: "otlp", OTEL_LOGS_EXPORTER: "otlp", // Standard OTLP transport configuration. OTEL_EXPORTER_OTLP_PROTOCOL: "http/protobuf", OTEL_EXPORTER_OTLP_ENDPOINT: "http://collector.example.com:4318", OTEL_EXPORTER_OTLP_HEADERS: "Authorization=Bearer your-token", }; for await (const message of query({ prompt: "List the files in this directory", // env replaces the inherited environment in TypeScript, so spread // process.env first to keep PATH, ANTHROPIC_API_KEY, and other variables. options: { env: { ...process.env, ...otelEnv } }, })) { console.log(message); } ``` Because the child process inherits your application's environment by default, you can achieve the same result by exporting these variables in a Dockerfile, Kubernetes manifest, or shell profile and omitting `options.env` entirely. The `console` exporter writes telemetry to standard output, which the SDK uses as its message channel. Do not set `console` as an exporter value when running through the SDK. To inspect telemetry locally, point `OTEL_EXPORTER_OTLP_ENDPOINT` at a local collector or an all-in-one Jaeger container instead. ### Flush telemetry from short-lived calls The CLI batches telemetry and exports on an interval. On a clean process exit it attempts to flush pending data, but the flush is bounded by a short timeout, so spans can still be dropped if the collector is slow to respond. If your process is killed before the CLI shuts down, anything still in the batch buffer is lost. Lowering the export intervals reduces both windows. By default, metrics export every 60 seconds and traces and logs export every 5 seconds. The following example shortens all three intervals so that data reaches the collector while a short task is still running: ```python Python theme={null} OTEL_ENV = { # ... exporter configuration from the previous example ... "OTEL_METRIC_EXPORT_INTERVAL": "1000", "OTEL_LOGS_EXPORT_INTERVAL": "1000", "OTEL_TRACES_EXPORT_INTERVAL": "1000", } ``` ```typescript TypeScript theme={null} const otelEnv = { // ... exporter configuration from the previous example ... OTEL_METRIC_EXPORT_INTERVAL: "1000", OTEL_LOGS_EXPORT_INTERVAL: "1000", OTEL_TRACES_EXPORT_INTERVAL: "1000", }; ``` ## Read agent traces Traces give you the most detailed view of an agent run. With `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` set, each step of the agent loop becomes a span you can inspect in your tracing backend: * **`claude_code.interaction`:** wraps a single turn of the agent loop, from receiving a prompt to producing a response. * **`claude_code.llm_request`:** wraps each call to the Claude API, with model name, latency, and token counts as attributes. * **`claude_code.tool`:** wraps each tool invocation, with child spans for the permission wait (`claude_code.tool.blocked_on_user`) and the execution itself (`claude_code.tool.execution`). * **`claude_code.hook`:** wraps each [hook](/en/agent-sdk/hooks) execution. Requires detailed beta tracing (`ENABLE_BETA_TRACING_DETAILED=1` and `BETA_TRACING_ENDPOINT`) in addition to the variables above. The `llm_request`, `tool`, and `hook` spans are children of the enclosing `claude_code.interaction` span. When the agent spawns a subagent through the Task tool, the subagent's `llm_request` and `tool` spans nest under the parent agent's `claude_code.tool` span, so the full delegation chain appears as one trace. Spans carry a `session.id` attribute by default. When you make several `query()` calls against the same [session](/en/agent-sdk/sessions), filter on `session.id` in your backend to see them as one timeline. The attribute is omitted if `OTEL_METRICS_INCLUDE_SESSION_ID` is set to a falsy value. Tracing is in beta. Span names and attributes may change between releases. See [Traces (beta)](/en/monitoring-usage#traces-beta) in the Monitoring reference for the trace exporter configuration variables. ## Link traces to your application The SDK automatically propagates W3C trace context into the CLI subprocess. When you call `query()` while an OpenTelemetry span is active in your application, the SDK injects `TRACEPARENT` and `TRACESTATE` into the child process environment, and the CLI reads them so its `claude_code.interaction` span becomes a child of your span. The agent run then appears inside your application's trace instead of as a disconnected root. The CLI also forwards `TRACEPARENT` to every Bash and PowerShell command it runs. If a command launched through the Bash tool emits its own OpenTelemetry spans, those spans nest under the `claude_code.tool.execution` span that wraps the command. Auto-injection is skipped when you set `TRACEPARENT` explicitly in `options.env`, so you can pin a specific parent context if needed. Interactive CLI sessions ignore inbound `TRACEPARENT` entirely; only Agent SDK and `claude -p` runs honor it. See [Traces (beta)](/en/monitoring-usage#traces-beta) in the Monitoring reference for the full span and attribute reference. ## Tag telemetry from your agent By default, the CLI reports `service.name` as `claude-code`. If you run several agents, or run the SDK alongside other services that export to the same collector, override the service name and add resource attributes so you can filter by agent in your backend. The following example renames the service and attaches deployment metadata. These values are applied as OpenTelemetry resource attributes on every span, metric, and event the agent emits: ```python Python theme={null} options = ClaudeAgentOptions( env={ # ... exporter configuration ... "OTEL_SERVICE_NAME": "support-triage-agent", "OTEL_RESOURCE_ATTRIBUTES": "service.version=1.4.0,deployment.environment=production", }, ) ``` ```typescript TypeScript theme={null} const options = { env: { ...process.env, // ... exporter configuration ... OTEL_SERVICE_NAME: "support-triage-agent", OTEL_RESOURCE_ATTRIBUTES: "service.version=1.4.0,deployment.environment=production", }, }; ``` ## Control sensitive data in exports Telemetry is structural by default. Durations, model names, and tool names are recorded on every span; token counts are recorded when the underlying API request returns usage data, so spans for failed or aborted requests may omit them. The content your agent reads and writes is not recorded by default. These opt-in variables add content to the exported data: | Variable | Adds | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OTEL_LOG_USER_PROMPTS=1` | Prompt text on `claude_code.user_prompt` events and on the `claude_code.interaction` span | | `OTEL_LOG_TOOL_DETAILS=1` | Tool input arguments (file paths, shell commands, search patterns) on `claude_code.tool_result` events | | `OTEL_LOG_TOOL_CONTENT=1` | Full tool input and output bodies as span events on `claude_code.tool`, truncated at 60 KB. Requires [tracing](#read-agent-traces) to be enabled | | `OTEL_LOG_RAW_API_BODIES` | Full Anthropic Messages API request and response JSON as `claude_code.api_request_body` and `claude_code.api_response_body` log events. Set to `1` for inline bodies truncated at 60 KB, or `file:` for untruncated bodies on disk with a `body_ref` path in the event. Bodies include the entire conversation history and have extended-thinking content redacted. Enabling this implies consent to everything the three variables above would reveal | Leave these unset unless your observability pipeline is approved to store the data your agent handles. See [Security and privacy](/en/monitoring-usage#security-and-privacy) in the Monitoring reference for the full list of attributes and redaction behavior. ## Related documentation These guides cover adjacent topics for monitoring and deploying agents: * [Track cost and usage](/en/agent-sdk/cost-tracking): read token and cost data from the message stream without an external backend. * [Hosting the Agent SDK](/en/agent-sdk/hosting): deploy agents in containers where you can set OpenTelemetry variables at the environment level. * [Monitoring](../13-Enterprise-Admin/monitoring-claude-code-docs-72c46f3dc8.md): the complete reference for every environment variable, metric, and event the CLI emits. --- ## agent-sdk-overview-b27888bae2.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Agent SDK overview > Build production AI agents with Claude Code as a library The Claude Code SDK has been renamed to the Claude Agent SDK. If you're migrating from the old SDK, see the [Migration Guide](/en/agent-sdk/migration-guide). Build AI agents that autonomously read files, run commands, search the web, edit code, and more. The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript. Opus 4.7 (`claude-opus-4-7`) requires Agent SDK v0.2.111 or later. If you see a `thinking.type.enabled` API error, see [Troubleshooting](/en/agent-sdk/quickstart#troubleshooting). ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): async for message in query( prompt="Find and fix the bug in auth.py", options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]), ): print(message) # Claude reads the file, finds the bug, edits it asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Find and fix the bug in auth.ts", options: { allowedTools: ["Read", "Edit", "Bash"] } })) { console.log(message); // Claude reads the file, finds the bug, edits it } ``` The Agent SDK includes built-in tools for reading files, running commands, and editing code, so your agent can start working immediately without you implementing tool execution. Dive into the quickstart or explore real agents built with the SDK: Build a bug-fixing agent in minutes Email assistant, research agent, and more ## Get started ```bash theme={null} npm install @anthropic-ai/claude-agent-sdk ``` ```bash theme={null} pip install claude-agent-sdk ``` The TypeScript SDK bundles a native Claude Code binary for your platform as an optional dependency, so you don't need to install Claude Code separately. Get an API key from the [Console](../04-API-Reference/Other/platform-claude-com.md), then set it as an environment variable: ```bash theme={null} export ANTHROPIC_API_KEY=your-api-key ``` The SDK also supports authentication via third-party API providers: * **Amazon Bedrock**: set `CLAUDE_CODE_USE_BEDROCK=1` environment variable and configure AWS credentials * **Google Vertex AI**: set `CLAUDE_CODE_USE_VERTEX=1` environment variable and configure Google Cloud credentials * **Microsoft Azure**: set `CLAUDE_CODE_USE_FOUNDRY=1` environment variable and configure Azure credentials See the setup guides for [Bedrock](../20-Models/claude-code-on-amazon-bedrock-claude-code-docs-435e92efd0.md), [Vertex AI](../20-Models/claude-code-on-google-vertex-ai-claude-code-docs-2acd050a7a.md), or [Azure AI Foundry](../20-Models/claude-code-on-microsoft-foundry-claude-code-docs-ee35d755a6.md) for details. Unless previously approved, Anthropic does not allow third party developers to offer claude.ai login or rate limits for their products, including agents built on the Claude Agent SDK. Please use the API key authentication methods described in this document instead. This example creates an agent that lists files in your current directory using built-in tools. ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): async for message in query( prompt="What files are in this directory?", options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]), ): if hasattr(message, "result"): print(message.result) asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "What files are in this directory?", options: { allowedTools: ["Bash", "Glob"] } })) { if ("result" in message) console.log(message.result); } ``` **Ready to build?** Follow the [Quickstart](/en/agent-sdk/quickstart) to create an agent that finds and fixes bugs in minutes. ## Capabilities Everything that makes Claude Code powerful is available in the SDK: Your agent can read files, run commands, and search codebases out of the box. Key tools include: | Tool | What it does | | --------------------------------------------------------------------------- | ------------------------------------------------------------------- | | **Read** | Read any file in the working directory | | **Write** | Create new files | | **Edit** | Make precise edits to existing files | | **Bash** | Run terminal commands, scripts, git operations | | **Monitor** | Watch a background script and react to each output line as an event | | **Glob** | Find files by pattern (`**/*.ts`, `src/**/*.py`) | | **Grep** | Search file contents with regex | | **WebSearch** | Search the web for current information | | **WebFetch** | Fetch and parse web page content | | **[AskUserQuestion](/en/agent-sdk/user-input#handle-clarifying-questions)** | Ask the user clarifying questions with multiple choice options | This example creates an agent that searches your codebase for TODO comments: ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): async for message in query( prompt="Find all TODO comments and create a summary", options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]), ): if hasattr(message, "result"): print(message.result) asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Find all TODO comments and create a summary", options: { allowedTools: ["Read", "Glob", "Grep"] } })) { if ("result" in message) console.log(message.result); } ``` Run custom code at key points in the agent lifecycle. SDK hooks use callback functions to validate, log, block, or transform agent behavior. **Available hooks:** `PreToolUse`, `PostToolUse`, `Stop`, `SessionStart`, `SessionEnd`, `UserPromptSubmit`, and more. This example logs all file changes to an audit file: ```python Python theme={null} import asyncio from datetime import datetime from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher async def log_file_change(input_data, tool_use_id, context): file_path = input_data.get("tool_input", {}).get("file_path", "unknown") with open("./audit.log", "a") as f: f.write(f"{datetime.now()}: modified {file_path}\n") return {} async def main(): async for message in query( prompt="Refactor utils.py to improve readability", options=ClaudeAgentOptions( permission_mode="acceptEdits", hooks={ "PostToolUse": [ HookMatcher(matcher="Edit|Write", hooks=[log_file_change]) ] }, ), ): if hasattr(message, "result"): print(message.result) asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk"; import { appendFile } from "fs/promises"; const logFileChange: HookCallback = async (input) => { const filePath = (input as any).tool_input?.file_path ?? "unknown"; await appendFile("./audit.log", `${new Date().toISOString()}: modified ${filePath}\n`); return {}; }; for await (const message of query({ prompt: "Refactor utils.py to improve readability", options: { permissionMode: "acceptEdits", hooks: { PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }] } } })) { if ("result" in message) console.log(message.result); } ``` [Learn more about hooks →](/en/agent-sdk/hooks) Spawn specialized agents to handle focused subtasks. Your main agent delegates work, and subagents report back with results. Define custom agents with specialized instructions. Include `Agent` in `allowedTools` since subagents are invoked via the Agent tool: ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition async def main(): async for message in query( prompt="Use the code-reviewer agent to review this codebase", options=ClaudeAgentOptions( allowed_tools=["Read", "Glob", "Grep", "Agent"], agents={ "code-reviewer": AgentDefinition( description="Expert code reviewer for quality and security reviews.", prompt="Analyze code quality and suggest improvements.", tools=["Read", "Glob", "Grep"], ) }, ), ): if hasattr(message, "result"): print(message.result) asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Use the code-reviewer agent to review this codebase", options: { allowedTools: ["Read", "Glob", "Grep", "Agent"], agents: { "code-reviewer": { description: "Expert code reviewer for quality and security reviews.", prompt: "Analyze code quality and suggest improvements.", tools: ["Read", "Glob", "Grep"] } } } })) { if ("result" in message) console.log(message.result); } ``` Messages from within a subagent's context include a `parent_tool_use_id` field, letting you track which messages belong to which subagent execution. [Learn more about subagents →](/en/agent-sdk/subagents) Connect to external systems via the Model Context Protocol: databases, browsers, APIs, and [hundreds more](https://github.com/modelcontextprotocol/servers). This example connects the [Playwright MCP server](https://github.com/microsoft/playwright-mcp) to give your agent browser automation capabilities: ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): async for message in query( prompt="Open example.com and describe what you see", options=ClaudeAgentOptions( mcp_servers={ "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]} } ), ): if hasattr(message, "result"): print(message.result) asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Open example.com and describe what you see", options: { mcpServers: { playwright: { command: "npx", args: ["@playwright/mcp@latest"] } } } })) { if ("result" in message) console.log(message.result); } ``` [Learn more about MCP →](/en/agent-sdk/mcp) Control exactly which tools your agent can use. Allow safe operations, block dangerous ones, or require approval for sensitive actions. For interactive approval prompts and the `AskUserQuestion` tool, see [Handle approvals and user input](/en/agent-sdk/user-input). This example creates a read-only agent that can analyze but not modify code. `allowed_tools` pre-approves `Read`, `Glob`, and `Grep`. ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): async for message in query( prompt="Review this code for best practices", options=ClaudeAgentOptions( allowed_tools=["Read", "Glob", "Grep"], ), ): if hasattr(message, "result"): print(message.result) asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Review this code for best practices", options: { allowedTools: ["Read", "Glob", "Grep"] } })) { if ("result" in message) console.log(message.result); } ``` [Learn more about permissions →](/en/agent-sdk/permissions) Maintain context across multiple exchanges. Claude remembers files read, analysis done, and conversation history. Resume sessions later, or fork them to explore different approaches. This example captures the session ID from the first query, then resumes to continue with full context: ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage async def main(): session_id = None # First query: capture the session ID async for message in query( prompt="Read the authentication module", options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]), ): if isinstance(message, SystemMessage) and message.subtype == "init": session_id = message.data["session_id"] # Resume with full context from the first query async for message in query( prompt="Now find all places that call it", # "it" = auth module options=ClaudeAgentOptions(resume=session_id), ): if isinstance(message, ResultMessage): print(message.result) asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; let sessionId: string | undefined; // First query: capture the session ID for await (const message of query({ prompt: "Read the authentication module", options: { allowedTools: ["Read", "Glob"] } })) { if (message.type === "system" && message.subtype === "init") { sessionId = message.session_id; } } // Resume with full context from the first query for await (const message of query({ prompt: "Now find all places that call it", // "it" = auth module options: { resume: sessionId } })) { if ("result" in message) console.log(message.result); } ``` [Learn more about sessions →](/en/agent-sdk/sessions) ### Claude Code features The SDK also supports Claude Code's filesystem-based configuration. With default options the SDK loads these from `.claude/` in your working directory and `~/.claude/`. To restrict which sources load, set `setting_sources` (Python) or `settingSources` (TypeScript) in your options. | Feature | Description | Location | | ------------------------------------------------ | ---------------------------------------------------- | ---------------------------------- | | [Skills](/en/agent-sdk/skills) | Specialized capabilities defined in Markdown | `.claude/skills/*/SKILL.md` | | [Slash commands](/en/agent-sdk/slash-commands) | Custom commands for common tasks | `.claude/commands/*.md` | | [Memory](/en/agent-sdk/modifying-system-prompts) | Project context and instructions | `CLAUDE.md` or `.claude/CLAUDE.md` | | [Plugins](/en/agent-sdk/plugins) | Extend with custom commands, agents, and MCP servers | Programmatic via `plugins` option | ## Compare the Agent SDK to other Claude tools The Claude Platform offers multiple ways to build with Claude. Here's how the Agent SDK fits in: The [Anthropic Client SDK](../04-API-Reference/Other/api-client-sdks-ab34496e4f.md) gives you direct API access: you send prompts and implement tool execution yourself. The **Agent SDK** gives you Claude with built-in tool execution. With the Client SDK, you implement a tool loop. With the Agent SDK, Claude handles it: ```python Python theme={null} # Client SDK: You implement the tool loop response = client.messages.create(...) while response.stop_reason == "tool_use": result = your_tool_executor(response.tool_use) response = client.messages.create(tool_result=result, **params) # Agent SDK: Claude handles tools autonomously async for message in query(prompt="Fix the bug in auth.py"): print(message) ``` ```typescript TypeScript theme={null} // Client SDK: You implement the tool loop let response = await client.messages.create({ ...params }); while (response.stop_reason === "tool_use") { const result = yourToolExecutor(response.tool_use); response = await client.messages.create({ tool_result: result, ...params }); } // Agent SDK: Claude handles tools autonomously for await (const message of query({ prompt: "Fix the bug in auth.ts" })) { console.log(message); } ``` Same capabilities, different interface: | Use case | Best choice | | ----------------------- | ----------- | | Interactive development | CLI | | CI/CD pipelines | SDK | | Custom applications | SDK | | One-off tasks | CLI | | Production automation | SDK | Many teams use both: CLI for daily development, SDK for production. Workflows translate directly between them. ## Changelog View the full changelog for SDK updates, bug fixes, and new features: * **TypeScript SDK**: [view CHANGELOG.md](https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md) * **Python SDK**: [view CHANGELOG.md](https://github.com/anthropics/claude-agent-sdk-python/blob/main/CHANGELOG.md) ## Reporting bugs If you encounter bugs or issues with the Agent SDK: * **TypeScript SDK**: [report issues on GitHub](https://github.com/anthropics/claude-agent-sdk-typescript/issues) * **Python SDK**: [report issues on GitHub](https://github.com/anthropics/claude-agent-sdk-python/issues) ## Branding guidelines For partners integrating the Claude Agent SDK, use of Claude branding is optional. When referencing Claude in your product: **Allowed:** * "Claude Agent" (preferred for dropdown menus) * "Claude" (when within a menu already labeled "Agents") * "{YourAgentName} Powered by Claude" (if you have an existing agent name) **Not permitted:** * "Claude Code" or "Claude Code Agent" * Claude Code-branded ASCII art or visual elements that mimic Claude Code Your product should maintain its own branding and not appear to be Claude Code or any Anthropic product. For questions about branding compliance, contact the Anthropic [sales team](https://www.anthropic.com/contact-sales). ## License and terms Use of the Claude Agent SDK is governed by [Anthropic's Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms), including when you use it to power products and services that you make available to your own customers and end users, except to the extent a specific component or dependency is covered by a different license as indicated in that component's LICENSE file. ## Next steps Build an agent that finds and fixes bugs in minutes Email assistant, research agent, and more Full TypeScript API reference and examples Full Python API reference and examples --- ## agent-sdk-overview-claude-code-docs-d69a094d34.md ## On this page - [Compare the Agent SDK to other Claude tools](#compare-the-agent-sdk-to-other-claude-tools) - [Capabilities](#capabilities) - [Get started](#get-started) - [Changelog](#changelog) - [Report bugs](#report-bugs) - [Branding guidelines](#branding-guidelines) - [License and terms](#license-and-terms) - [Next steps](#next-steps) Agent SDK # Agent SDK overview Copy pageCopy page Build production AI agents with Claude Code as a library Copy pageCopy page An agent is an application that completes a task by planning its own steps and calling tools that read files, run commands, or edit code. The Agent SDK gives you the same tools, [agent loop](/docs/en/agent-sdk/agent-loop), and context management that power Claude Code, programmable in Python and TypeScript. [​](#compare-the-agent-sdk-to-other-claude-tools) Compare the Agent SDK to other Claude tools The Agent SDK, the CLI, the Client SDK, and Managed Agents each fit different needs. Use the table to find the one that matches what you’re building. | If you’re… | Use | Why | |---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| | Building an agent without implementing the tool loop yourself | **Agent SDK** | A library that runs the agent loop in your own process, in Python or TypeScript. | | Doing interactive development or running one-off tasks from a terminal | [**Claude Code CLI**](/docs/en/overview) | The terminal interface, built for daily interactive use. | | Calling the API directly and implementing the tool loop yourself | [**Client SDK**](https://platform.claude.com/docs/en/api/client-sdks) | Direct access to the Anthropic API rather than to Claude Code. You implement the tool loop yourself. | | Running long-running or asynchronous agents without managing your own sandbox or session infrastructure | [**Managed Agents**](https://platform.claude.com/docs/en/managed-agents/overview) | Hosted REST API, a separate product from the Agent SDK. Anthropic runs the agent and the sandbox. | The SDK is available as a library for Python and TypeScript only. To drive the same agent loop from another language, [run the CLI as a subprocess](/docs/en/headless) with the `-p` flag and `--output-format json`. [​](#capabilities) Capabilities Everything that makes Claude Code powerful is available in the SDK. | Capability | What it does | Learn more | |------------------------------|----------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Built-in tools | Read, write, edit files, run commands, and search the web | [Tools reference](/docs/en/tools-reference) | | Hooks | Run custom code at key points in the agent lifecycle | [Hooks](/docs/en/agent-sdk/hooks) | | Subagents | Spawn specialized agents for focused subtasks | [Subagents](/docs/en/agent-sdk/subagents) | | MCP | Connect external tools and data sources via the Model Context Protocol | [MCP](/docs/en/agent-sdk/mcp) | | Permissions | Control which tools run automatically, which need approval | [Permissions](/docs/en/agent-sdk/permissions) | | Sessions | Maintain context across exchanges, resume or fork later | [Sessions](/docs/en/agent-sdk/sessions) | | Skills, commands, and memory | Load automatically from your project’s `.claude/` and from `~/.claude/`, same as Claude Code | [Skills](/docs/en/agent-sdk/skills), [Commands](/docs/en/agent-sdk/slash-commands), [Memory](/docs/en/agent-sdk/modifying-system-prompts), [Configuration loading](/docs/en/agent-sdk/claude-code-features) | | Plugins | Package skills, agents, hooks, and MCP servers, and load them by local path | [Plugins](/docs/en/agent-sdk/plugins) | [​](#get-started) Get started Follow the [Quickstart](/docs/en/agent-sdk/quickstart) to install the SDK, set your API key, and build your first agent, one that finds and fixes bugs in existing code. Unless previously approved, Anthropic does not allow third party developers to offer claude.ai login or rate limits for their products, including agents built on the Claude Agent SDK. Use the API key authentication methods described in the [Quickstart](/docs/en/agent-sdk/quickstart) instead. [​](#changelog) Changelog View the full changelog for SDK updates, bug fixes, and new features: - **TypeScript SDK**: [view CHANGELOG.md](https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md) - **Python SDK**: [view CHANGELOG.md](https://github.com/anthropics/claude-agent-sdk-python/blob/main/CHANGELOG.md) [​](#report-bugs) Report bugs If you encounter bugs or issues with the Agent SDK: - **TypeScript SDK**: [report issues on GitHub](https://github.com/anthropics/claude-agent-sdk-typescript/issues) - **Python SDK**: [report issues on GitHub](https://github.com/anthropics/claude-agent-sdk-python/issues) [​](#branding-guidelines) Branding guidelines For partners integrating the Claude Agent SDK, use of Claude branding is optional. When referencing Claude in your product: **Allowed:** - “Claude Agent”, preferred for dropdown menus - “Claude”, when within a menu already labeled “Agents” - “{YourAgentName} Powered by Claude”, if you have an existing agent name **Not permitted:** - “Claude Code” or “Claude Code Agent” - Claude Code-branded ASCII art or visual elements that mimic Claude Code Your product should maintain its own branding and not appear to be Claude Code or any Anthropic product. For questions about branding compliance, contact the Anthropic [sales team](https://www.anthropic.com/contact-sales). [​](#license-and-terms) License and terms Use of the Claude Agent SDK is governed by [Anthropic’s Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms), including when you use it to power products and services that you make available to your own customers and end users, except to the extent a specific component or dependency is covered by a different license as indicated in that component’s LICENSE file. [​](#next-steps) Next steps These resources cover deeper technical detail and example projects for building with the Agent SDK. - [Quickstart](/docs/en/agent-sdk/quickstart): build your first agent that finds and fixes bugs - [Agent loop](/docs/en/agent-sdk/agent-loop): how Claude plans, calls tools, and decides when a task is done - [Example agents](https://github.com/anthropics/claude-agent-sdk-demos): demo apps for local development - [TypeScript SDK](/docs/en/agent-sdk/typescript): full TypeScript API reference and examples - [Python SDK](/docs/en/agent-sdk/python): full Python API reference and examples - [Agent harness design](https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code): how the Claude Code team uses dynamic workflows to orchestrate subagents at scale --- ## agent-sdk-permissions-de374ea8f6.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Configure permissions > Control how your agent uses tools with permission modes, hooks, and declarative allow/deny rules. The Claude Agent SDK provides permission controls to manage how Claude uses tools. Use permission modes and rules to define what's allowed automatically, and the [`canUseTool` callback](/en/agent-sdk/user-input) to handle everything else at runtime. This page covers permission modes and rules. To build interactive approval flows where users approve or deny tool requests at runtime, see [Handle approvals and user input](/en/agent-sdk/user-input). ## How permissions are evaluated When Claude requests a tool, the SDK checks permissions in this order: Run [hooks](/en/agent-sdk/hooks) first, which can allow, deny, or continue to the next step Check `deny` rules (from `disallowed_tools` and [settings.json](/en/settings#permission-settings)). If a deny rule matches, the tool is blocked, even in `bypassPermissions` mode. Apply the active [permission mode](#permission-modes). `bypassPermissions` approves everything that reaches this step. `acceptEdits` approves file operations. Other modes fall through. Check `allow` rules (from `allowed_tools` and settings.json). If a rule matches, the tool is approved. If not resolved by any of the above, call your [`canUseTool` callback](/en/agent-sdk/user-input) for a decision. In `dontAsk` mode, this step is skipped and the tool is denied. Permission evaluation flow diagram This page focuses on **allow and deny rules** and **permission modes**. For the other steps: * **Hooks:** run custom code to allow, deny, or modify tool requests. See [Control execution with hooks](/en/agent-sdk/hooks). * **canUseTool callback:** prompt users for approval at runtime. See [Handle approvals and user input](/en/agent-sdk/user-input). ## Allow and deny rules `allowed_tools` and `disallowed_tools` (TypeScript: `allowedTools` / `disallowedTools`) add entries to the allow and deny rule lists in the evaluation flow above. They control whether a tool call is approved, not whether the tool is available to Claude. | Option | Effect | | :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- | | `allowed_tools=["Read", "Grep"]` | `Read` and `Grep` are auto-approved. Tools not listed here still exist and fall through to the permission mode and `canUseTool`. | | `disallowed_tools=["Bash"]` | `Bash` is always denied. Deny rules are checked first and hold in every permission mode, including `bypassPermissions`. | For a locked-down agent, pair `allowedTools` with `permissionMode: "dontAsk"`. Listed tools are approved; anything else is denied outright instead of prompting: ```typescript theme={null} const options = { allowedTools: ["Read", "Glob", "Grep"], permissionMode: "dontAsk" }; ``` **`allowed_tools` does not constrain `bypassPermissions`.** `allowed_tools` only pre-approves the tools you list. Unlisted tools are not matched by any allow rule and fall through to the permission mode, where `bypassPermissions` approves them. Setting `allowed_tools=["Read"]` alongside `permission_mode="bypassPermissions"` still approves every tool, including `Bash`, `Write`, and `Edit`. If you need `bypassPermissions` but want specific tools blocked, use `disallowed_tools`. You can also configure allow, deny, and ask rules declaratively in `.claude/settings.json`. These rules are read when the `project` setting source is enabled, which it is for default `query()` options. If you set `setting_sources` (TypeScript: `settingSources`) explicitly, include `"project"` for them to apply. See [Permission settings](/en/settings#permission-settings) for the rule syntax. ## Permission modes Permission modes provide global control over how Claude uses tools. You can set the permission mode when calling `query()` or change it dynamically during streaming sessions. ### Available modes The SDK supports these permission modes: | Mode | Description | Tool behavior | | :----------------------- | :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | | `default` | Standard permission behavior | No auto-approvals; unmatched tools trigger your `canUseTool` callback | | `dontAsk` | Deny instead of prompting | Anything not pre-approved by `allowed_tools` or rules is denied; `canUseTool` is never called | | `acceptEdits` | Auto-accept file edits | File edits and [filesystem operations](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) are automatically approved | | `bypassPermissions` | Bypass all permission checks | All tools run without permission prompts (use with caution) | | `plan` | Planning mode | No tool execution; Claude plans without making changes | | `auto` (TypeScript only) | Model-classified approvals | A model classifier approves or denies each tool call. See [Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) for availability | **Subagent inheritance:** When the parent uses `bypassPermissions`, `acceptEdits`, or `auto`, all subagents inherit that mode and it cannot be overridden per subagent. Subagents may have different system prompts and less constrained behavior than your main agent, so inheriting `bypassPermissions` grants them full, autonomous system access without any approval prompts. ### Set permission mode You can set the permission mode once when starting a query, or change it dynamically while the session is active. Pass `permission_mode` (Python) or `permissionMode` (TypeScript) when creating a query. This mode applies for the entire session unless changed dynamically. ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): async for message in query( prompt="Help me refactor this code", options=ClaudeAgentOptions( permission_mode="default", # Set the mode here ), ): if hasattr(message, "result"): print(message.result) asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; async function main() { for await (const message of query({ prompt: "Help me refactor this code", options: { permissionMode: "default" // Set the mode here } })) { if ("result" in message) { console.log(message.result); } } } main(); ``` Call `set_permission_mode()` (Python) or `setPermissionMode()` (TypeScript) to change the mode mid-session. The new mode takes effect immediately for all subsequent tool requests. This lets you start restrictive and loosen permissions as trust builds, for example switching to `acceptEdits` after reviewing Claude's initial approach. ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): q = query( prompt="Help me refactor this code", options=ClaudeAgentOptions( permission_mode="default", # Start in default mode ), ) # Change mode dynamically mid-session await q.set_permission_mode("acceptEdits") # Process messages with the new permission mode async for message in q: if hasattr(message, "result"): print(message.result) asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; async function main() { const q = query({ prompt: "Help me refactor this code", options: { permissionMode: "default" // Start in default mode } }); // Change mode dynamically mid-session await q.setPermissionMode("acceptEdits"); // Process messages with the new permission mode for await (const message of q) { if ("result" in message) { console.log(message.result); } } } main(); ``` ### Mode details #### Accept edits mode (`acceptEdits`) Auto-approves file operations so Claude can edit code without prompting. Other tools (like Bash commands that aren't filesystem operations) still require normal permissions. **Auto-approved operations:** * File edits (Edit, Write tools) * Filesystem commands: `mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp`, `sed` Both apply only to paths inside the working directory or `additionalDirectories`. Paths outside that scope and writes to protected paths still prompt. **Use when:** you trust Claude's edits and want faster iteration, such as during prototyping or when working in an isolated directory. #### Don't ask mode (`dontAsk`) Converts any permission prompt into a denial. Tools pre-approved by `allowed_tools`, `settings.json` allow rules, or a hook run as normal. Everything else is denied without calling `canUseTool`. **Use when:** you want a fixed, explicit tool surface for a headless agent and prefer a hard deny over silent reliance on `canUseTool` being absent. #### Bypass permissions mode (`bypassPermissions`) Auto-approves all tool uses without prompts. Hooks still execute and can block operations if needed. Use with extreme caution. Claude has full system access in this mode. Only use in controlled environments where you trust all possible operations. `allowed_tools` does not constrain this mode. Every tool is approved, not just the ones you listed. Deny rules (`disallowed_tools`), explicit `ask` rules, and hooks are evaluated before the mode check and can still block a tool. #### Plan mode (`plan`) Prevents tool execution entirely. Claude can analyze code and create plans but cannot make changes. Claude may use `AskUserQuestion` to clarify requirements before finalizing the plan. See [Handle approvals and user input](/en/agent-sdk/user-input#handle-clarifying-questions) for handling these prompts. **Use when:** you want Claude to propose changes without executing them, such as during code review or when you need to approve changes before they're made. ## Related resources For the other steps in the permission evaluation flow: * [Handle approvals and user input](/en/agent-sdk/user-input): interactive approval prompts and clarifying questions * [Hooks guide](/en/agent-sdk/hooks): run custom code at key points in the agent lifecycle * [Permission rules](/en/settings#permission-settings): declarative allow/deny rules in `settings.json` --- ## agent-sdk-python-768e7c9a23.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Agent SDK reference - Python > Complete API reference for the Python Agent SDK, including all functions, types, and classes. ## Installation ```bash theme={null} pip install claude-agent-sdk ``` ## Choosing between `query()` and `ClaudeSDKClient` The Python SDK provides two ways to interact with Claude Code: ### Quick comparison | Feature | `query()` | `ClaudeSDKClient` | | :------------------ | :---------------------------- | :--------------------------------- | | **Session** | Creates new session each time | Reuses same session | | **Conversation** | Single exchange | Multiple exchanges in same context | | **Connection** | Managed automatically | Manual control | | **Streaming Input** | ✅ Supported | ✅ Supported | | **Interrupts** | ❌ Not supported | ✅ Supported | | **Hooks** | ✅ Supported | ✅ Supported | | **Custom Tools** | ✅ Supported | ✅ Supported | | **Continue Chat** | ❌ New session each time | ✅ Maintains conversation | | **Use Case** | One-off tasks | Continuous conversations | ### When to use `query()` (new session each time) **Best for:** * One-off questions where you don't need conversation history * Independent tasks that don't require context from previous exchanges * Simple automation scripts * When you want a fresh start each time ### When to use `ClaudeSDKClient` (continuous conversation) **Best for:** * **Continuing conversations** - When you need Claude to remember context * **Follow-up questions** - Building on previous responses * **Interactive applications** - Chat interfaces, REPLs * **Response-driven logic** - When next action depends on Claude's response * **Session control** - Managing conversation lifecycle explicitly ## Functions ### `query()` Creates a new session for each interaction with Claude Code. Returns an async iterator that yields messages as they arrive. Each call to `query()` starts fresh with no memory of previous interactions. ```python theme={null} async def query( *, prompt: str | AsyncIterable[dict[str, Any]], options: ClaudeAgentOptions | None = None, transport: Transport | None = None ) -> AsyncIterator[Message] ``` #### Parameters | Parameter | Type | Description | | :---------- | :--------------------------- | :------------------------------------------------------------------------- | | `prompt` | `str \| AsyncIterable[dict]` | The input prompt as a string or async iterable for streaming mode | | `options` | `ClaudeAgentOptions \| None` | Optional configuration object (defaults to `ClaudeAgentOptions()` if None) | | `transport` | `Transport \| None` | Optional custom transport for communicating with the CLI process | #### Returns Returns an `AsyncIterator[Message]` that yields messages from the conversation. #### Example - With options ```python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): options = ClaudeAgentOptions( system_prompt="You are an expert Python developer", permission_mode="acceptEdits", cwd="/home/user/project", ) async for message in query(prompt="Create a Python web server", options=options): print(message) asyncio.run(main()) ``` ### `tool()` Decorator for defining MCP tools with type safety. ```python theme={null} def tool( name: str, description: str, input_schema: type | dict[str, Any], annotations: ToolAnnotations | None = None ) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]] ``` #### Parameters | Parameter | Type | Description | | :------------- | :----------------------------------------------- | :------------------------------------------------------------------ | | `name` | `str` | Unique identifier for the tool | | `description` | `str` | Human-readable description of what the tool does | | `input_schema` | `type \| dict[str, Any]` | Schema defining the tool's input parameters (see below) | | `annotations` | [`ToolAnnotations`](#tool-annotations)` \| None` | Optional MCP tool annotations providing behavioral hints to clients | #### Input schema options 1. **Simple type mapping** (recommended): ```python theme={null} {"text": str, "count": int, "enabled": bool} ``` 2. **JSON Schema format** (for complex validation): ```python theme={null} { "type": "object", "properties": { "text": {"type": "string"}, "count": {"type": "integer", "minimum": 0}, }, "required": ["text"], } ``` #### Returns A decorator function that wraps the tool implementation and returns an `SdkMcpTool` instance. #### Example ```python theme={null} from claude_agent_sdk import tool from typing import Any @tool("greet", "Greet a user", {"name": str}) async def greet(args: dict[str, Any]) -> dict[str, Any]: return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]} ``` #### `ToolAnnotations` Re-exported from `mcp.types` (also available as `from claude_agent_sdk import ToolAnnotations`). All fields are optional hints; clients should not rely on them for security decisions. | Field | Type | Default | Description | | :---------------- | :------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------- | | `title` | `str \| None` | `None` | Human-readable title for the tool | | `readOnlyHint` | `bool \| None` | `False` | If `True`, the tool does not modify its environment | | `destructiveHint` | `bool \| None` | `True` | If `True`, the tool may perform destructive updates (only meaningful when `readOnlyHint` is `False`) | | `idempotentHint` | `bool \| None` | `False` | If `True`, repeated calls with the same arguments have no additional effect (only meaningful when `readOnlyHint` is `False`) | | `openWorldHint` | `bool \| None` | `True` | If `True`, the tool interacts with external entities (for example, web search). If `False`, the tool's domain is closed (for example, a memory tool) | ```python theme={null} from claude_agent_sdk import tool, ToolAnnotations from typing import Any @tool( "search", "Search the web", {"query": str}, annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True), ) async def search(args: dict[str, Any]) -> dict[str, Any]: return {"content": [{"type": "text", "text": f"Results for: {args['query']}"}]} ``` ### `create_sdk_mcp_server()` Create an in-process MCP server that runs within your Python application. ```python theme={null} def create_sdk_mcp_server( name: str, version: str = "1.0.0", tools: list[SdkMcpTool[Any]] | None = None ) -> McpSdkServerConfig ``` #### Parameters | Parameter | Type | Default | Description | | :-------- | :------------------------------ | :-------- | :---------------------------------------------------- | | `name` | `str` | - | Unique identifier for the server | | `version` | `str` | `"1.0.0"` | Server version string | | `tools` | `list[SdkMcpTool[Any]] \| None` | `None` | List of tool functions created with `@tool` decorator | #### Returns Returns an `McpSdkServerConfig` object that can be passed to `ClaudeAgentOptions.mcp_servers`. #### Example ```python theme={null} from claude_agent_sdk import tool, create_sdk_mcp_server @tool("add", "Add two numbers", {"a": float, "b": float}) async def add(args): return {"content": [{"type": "text", "text": f"Sum: {args['a'] + args['b']}"}]} @tool("multiply", "Multiply two numbers", {"a": float, "b": float}) async def multiply(args): return {"content": [{"type": "text", "text": f"Product: {args['a'] * args['b']}"}]} calculator = create_sdk_mcp_server( name="calculator", version="2.0.0", tools=[add, multiply], # Pass decorated functions ) # Use with Claude options = ClaudeAgentOptions( mcp_servers={"calc": calculator}, allowed_tools=["mcp__calc__add", "mcp__calc__multiply"], ) ``` ### `list_sessions()` Lists past sessions with metadata. Filter by project directory or list sessions across all projects. Synchronous; returns immediately. ```python theme={null} def list_sessions( directory: str | None = None, limit: int | None = None, include_worktrees: bool = True ) -> list[SDKSessionInfo] ``` #### Parameters | Parameter | Type | Default | Description | | :------------------ | :------------ | :------ | :------------------------------------------------------------------------------------ | | `directory` | `str \| None` | `None` | Directory to list sessions for. When omitted, returns sessions across all projects | | `limit` | `int \| None` | `None` | Maximum number of sessions to return | | `include_worktrees` | `bool` | `True` | When `directory` is inside a git repository, include sessions from all worktree paths | #### Return type: `SDKSessionInfo` | Property | Type | Description | | :-------------- | :------------ | :------------------------------------------------------------------- | | `session_id` | `str` | Unique session identifier | | `summary` | `str` | Display title: custom title, auto-generated summary, or first prompt | | `last_modified` | `int` | Last modified time in milliseconds since epoch | | `file_size` | `int \| None` | Session file size in bytes (`None` for remote storage backends) | | `custom_title` | `str \| None` | User-set session title | | `first_prompt` | `str \| None` | First meaningful user prompt in the session | | `git_branch` | `str \| None` | Git branch at the end of the session | | `cwd` | `str \| None` | Working directory for the session | | `tag` | `str \| None` | User-set session tag (see [`tag_session()`](#tag-session)) | | `created_at` | `int \| None` | Session creation time in milliseconds since epoch | #### Example Print the 10 most recent sessions for a project. Results are sorted by `last_modified` descending, so the first item is the newest. Omit `directory` to search across all projects. ```python theme={null} from claude_agent_sdk import list_sessions for session in list_sessions(directory="/path/to/project", limit=10): print(f"{session.summary} ({session.session_id})") ``` ### `get_session_messages()` Retrieves messages from a past session. Synchronous; returns immediately. ```python theme={null} def get_session_messages( session_id: str, directory: str | None = None, limit: int | None = None, offset: int = 0 ) -> list[SessionMessage] ``` #### Parameters | Parameter | Type | Default | Description | | :----------- | :------------ | :------- | :---------------------------------------------------------------- | | `session_id` | `str` | required | The session ID to retrieve messages for | | `directory` | `str \| None` | `None` | Project directory to look in. When omitted, searches all projects | | `limit` | `int \| None` | `None` | Maximum number of messages to return | | `offset` | `int` | `0` | Number of messages to skip from the start | #### Return type: `SessionMessage` | Property | Type | Description | | :------------------- | :----------------------------- | :------------------------ | | `type` | `Literal["user", "assistant"]` | Message role | | `uuid` | `str` | Unique message identifier | | `session_id` | `str` | Session identifier | | `message` | `Any` | Raw message content | | `parent_tool_use_id` | `None` | Reserved for future use | #### Example ```python theme={null} from claude_agent_sdk import list_sessions, get_session_messages sessions = list_sessions(limit=1) if sessions: messages = get_session_messages(sessions[0].session_id) for msg in messages: print(f"[{msg.type}] {msg.uuid}") ``` ### `get_session_info()` Reads metadata for a single session by ID without scanning the full project directory. Synchronous; returns immediately. ```python theme={null} def get_session_info( session_id: str, directory: str | None = None, ) -> SDKSessionInfo | None ``` #### Parameters | Parameter | Type | Default | Description | | :----------- | :------------ | :------- | :--------------------------------------------------------------------- | | `session_id` | `str` | required | UUID of the session to look up | | `directory` | `str \| None` | `None` | Project directory path. When omitted, searches all project directories | Returns [`SDKSessionInfo`](#return-type-sdk-session-info), or `None` if the session is not found. #### Example Look up a single session's metadata without scanning the project directory. Useful when you already have a session ID from a previous run. ```python theme={null} from claude_agent_sdk import get_session_info info = get_session_info("550e8400-e29b-41d4-a716-446655440000") if info: print(f"{info.summary} (branch: {info.git_branch}, tag: {info.tag})") ``` ### `rename_session()` Renames a session by appending a custom-title entry. Repeated calls are safe; the most recent title wins. Synchronous. ```python theme={null} def rename_session( session_id: str, title: str, directory: str | None = None, ) -> None ``` #### Parameters | Parameter | Type | Default | Description | | :----------- | :------------ | :------- | :--------------------------------------------------------------------- | | `session_id` | `str` | required | UUID of the session to rename | | `title` | `str` | required | New title. Must be non-empty after stripping whitespace | | `directory` | `str \| None` | `None` | Project directory path. When omitted, searches all project directories | Raises `ValueError` if `session_id` is not a valid UUID or `title` is empty; `FileNotFoundError` if the session cannot be found. #### Example Rename the most recent session so it's easier to find later. The new title appears in [`SDKSessionInfo.custom_title`](#return-type-sdk-session-info) on subsequent reads. ```python theme={null} from claude_agent_sdk import list_sessions, rename_session sessions = list_sessions(directory="/path/to/project", limit=1) if sessions: rename_session(sessions[0].session_id, "Refactor auth module") ``` ### `tag_session()` Tags a session. Pass `None` to clear the tag. Repeated calls are safe; the most recent tag wins. Synchronous. ```python theme={null} def tag_session( session_id: str, tag: str | None, directory: str | None = None, ) -> None ``` #### Parameters | Parameter | Type | Default | Description | | :----------- | :------------ | :------- | :--------------------------------------------------------------------- | | `session_id` | `str` | required | UUID of the session to tag | | `tag` | `str \| None` | required | Tag string, or `None` to clear. Unicode-sanitized before storing | | `directory` | `str \| None` | `None` | Project directory path. When omitted, searches all project directories | Raises `ValueError` if `session_id` is not a valid UUID or `tag` is empty after sanitization; `FileNotFoundError` if the session cannot be found. #### Example Tag a session, then filter by that tag on a later read. Pass `None` to clear an existing tag. ```python theme={null} from claude_agent_sdk import list_sessions, tag_session # Tag a session tag_session("550e8400-e29b-41d4-a716-446655440000", "needs-review") # Later: find all sessions with that tag for session in list_sessions(directory="/path/to/project"): if session.tag == "needs-review": print(session.summary) ``` ## Classes ### `ClaudeSDKClient` **Maintains a conversation session across multiple exchanges.** This is the Python equivalent of how the TypeScript SDK's `query()` function works internally - it creates a client object that can continue conversations. #### Key Features * **Session continuity**: Maintains conversation context across multiple `query()` calls * **Same conversation**: The session retains previous messages * **Interrupt support**: Can stop execution mid-task * **Explicit lifecycle**: You control when the session starts and ends * **Response-driven flow**: Can react to responses and send follow-ups * **Custom tools and hooks**: Supports custom tools (created with `@tool` decorator) and hooks ```python theme={null} class ClaudeSDKClient: def __init__(self, options: ClaudeAgentOptions | None = None, transport: Transport | None = None) async def connect(self, prompt: str | AsyncIterable[dict] | None = None) -> None async def query(self, prompt: str | AsyncIterable[dict], session_id: str = "default") -> None async def receive_messages(self) -> AsyncIterator[Message] async def receive_response(self) -> AsyncIterator[Message] async def interrupt(self) -> None async def set_permission_mode(self, mode: str) -> None async def set_model(self, model: str | None = None) -> None async def rewind_files(self, user_message_id: str) -> None async def get_mcp_status(self) -> McpStatusResponse async def reconnect_mcp_server(self, server_name: str) -> None async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None async def stop_task(self, task_id: str) -> None async def get_server_info(self) -> dict[str, Any] | None async def disconnect(self) -> None ``` #### Methods | Method | Description | | :---------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `__init__(options)` | Initialize the client with optional configuration | | `connect(prompt)` | Connect to Claude with an optional initial prompt or message stream | | `query(prompt, session_id)` | Send a new request in streaming mode | | `receive_messages()` | Receive all messages from Claude as an async iterator | | `receive_response()` | Receive messages until and including a ResultMessage | | `interrupt()` | Send interrupt signal (only works in streaming mode) | | `set_permission_mode(mode)` | Change the permission mode for the current session | | `set_model(model)` | Change the model for the current session. Pass `None` to reset to default | | `rewind_files(user_message_id)` | Restore files to their state at the specified user message. Requires `enable_file_checkpointing=True`. See [File checkpointing](/en/agent-sdk/file-checkpointing) | | `get_mcp_status()` | Get the status of all configured MCP servers. Returns [`McpStatusResponse`](#mcp-status-response) | | `reconnect_mcp_server(server_name)` | Retry connecting to an MCP server that failed or was disconnected | | `toggle_mcp_server(server_name, enabled)` | Enable or disable an MCP server mid-session. Disabling removes its tools | | `stop_task(task_id)` | Stop a running background task. A [`TaskNotificationMessage`](#task-notification-message) with status `"stopped"` follows in the message stream | | `get_server_info()` | Get server information including session ID and capabilities | | `disconnect()` | Disconnect from Claude | #### Context Manager Support The client can be used as an async context manager for automatic connection management: ```python theme={null} async with ClaudeSDKClient() as client: await client.query("Hello Claude") async for message in client.receive_response(): print(message) ``` > **Important:** When iterating over messages, avoid using `break` to exit early as this can cause asyncio cleanup issues. Instead, let the iteration complete naturally or use flags to track when you've found what you need. #### Example - Continuing a conversation ```python theme={null} import asyncio from claude_agent_sdk import ClaudeSDKClient, AssistantMessage, TextBlock, ResultMessage async def main(): async with ClaudeSDKClient() as client: # First question await client.query("What's the capital of France?") # Process response async for message in client.receive_response(): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(f"Claude: {block.text}") # Follow-up question - the session retains the previous context await client.query("What's the population of that city?") async for message in client.receive_response(): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(f"Claude: {block.text}") # Another follow-up - still in the same conversation await client.query("What are some famous landmarks there?") async for message in client.receive_response(): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(f"Claude: {block.text}") asyncio.run(main()) ``` #### Example - Streaming input with ClaudeSDKClient ```python theme={null} import asyncio from claude_agent_sdk import ClaudeSDKClient async def message_stream(): """Generate messages dynamically.""" yield { "type": "user", "message": {"role": "user", "content": "Analyze the following data:"}, } await asyncio.sleep(0.5) yield { "type": "user", "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"}, } await asyncio.sleep(0.5) yield { "type": "user", "message": {"role": "user", "content": "What patterns do you see?"}, } async def main(): async with ClaudeSDKClient() as client: # Stream input to Claude await client.query(message_stream()) # Process response async for message in client.receive_response(): print(message) # Follow-up in same session await client.query("Should we be concerned about these readings?") async for message in client.receive_response(): print(message) asyncio.run(main()) ``` #### Example - Using interrupts ```python theme={null} import asyncio from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, ResultMessage async def interruptible_task(): options = ClaudeAgentOptions(allowed_tools=["Bash"], permission_mode="acceptEdits") async with ClaudeSDKClient(options=options) as client: # Start a long-running task await client.query("Count from 1 to 100 slowly, using the bash sleep command") # Let it run for a bit await asyncio.sleep(2) # Interrupt the task await client.interrupt() print("Task interrupted!") # Drain the interrupted task's messages (including its ResultMessage) async for message in client.receive_response(): if isinstance(message, ResultMessage): print(f"Interrupted task finished with subtype={message.subtype!r}") # subtype is "error_during_execution" for interrupted tasks # Send a new command await client.query("Just say hello instead") # Now receive the new response async for message in client.receive_response(): if isinstance(message, ResultMessage) and message.subtype == "success": print(f"New result: {message.result}") asyncio.run(interruptible_task()) ``` **Buffer behavior after interrupt:** `interrupt()` sends a stop signal but does not clear the message buffer. Messages already produced by the interrupted task, including its `ResultMessage` (with `subtype="error_during_execution"`), remain in the stream. You must drain them with `receive_response()` before reading the response to a new query. If you send a new query immediately after `interrupt()` and call `receive_response()` only once, you'll receive the interrupted task's messages, not the new query's response. #### Example - Advanced permission control ```python theme={null} from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions from claude_agent_sdk.types import ( PermissionResultAllow, PermissionResultDeny, ToolPermissionContext, ) async def custom_permission_handler( tool_name: str, input_data: dict, context: ToolPermissionContext ) -> PermissionResultAllow | PermissionResultDeny: """Custom logic for tool permissions.""" # Block writes to system directories if tool_name == "Write" and input_data.get("file_path", "").startswith("/system/"): return PermissionResultDeny( message="System directory write not allowed", interrupt=True ) # Redirect sensitive file operations if tool_name in ["Write", "Edit"] and "config" in input_data.get("file_path", ""): safe_path = f"./sandbox/{input_data['file_path']}" return PermissionResultAllow( updated_input={**input_data, "file_path": safe_path} ) # Allow everything else return PermissionResultAllow(updated_input=input_data) async def main(): options = ClaudeAgentOptions( can_use_tool=custom_permission_handler, allowed_tools=["Read", "Write", "Edit"] ) async with ClaudeSDKClient(options=options) as client: await client.query("Update the system config file") async for message in client.receive_response(): # Will use sandbox path instead print(message) asyncio.run(main()) ``` ## Types **`@dataclass` vs `TypedDict`:** This SDK uses two kinds of types. Classes decorated with `@dataclass` (such as `ResultMessage`, `AgentDefinition`, `TextBlock`) are object instances at runtime and support attribute access: `msg.result`. Classes defined with `TypedDict` (such as `ThinkingConfigEnabled`, `McpStdioServerConfig`, `SyncHookJSONOutput`) are **plain dicts at runtime** and require key access: `config["budget_tokens"]`, not `config.budget_tokens`. The `ClassName(field=value)` call syntax works for both, but only dataclasses produce objects with attributes. ### `SdkMcpTool` Definition for an SDK MCP tool created with the `@tool` decorator. ```python theme={null} @dataclass class SdkMcpTool(Generic[T]): name: str description: str input_schema: type[T] | dict[str, Any] handler: Callable[[T], Awaitable[dict[str, Any]]] annotations: ToolAnnotations | None = None ``` | Property | Type | Description | | :------------- | :----------------------------------------- | :--------------------------------------------------------------------------------------------------------- | | `name` | `str` | Unique identifier for the tool | | `description` | `str` | Human-readable description | | `input_schema` | `type[T] \| dict[str, Any]` | Schema for input validation | | `handler` | `Callable[[T], Awaitable[dict[str, Any]]]` | Async function that handles tool execution | | `annotations` | `ToolAnnotations \| None` | Optional MCP tool annotations (e.g., `readOnlyHint`, `destructiveHint`, `openWorldHint`). From `mcp.types` | ### `Transport` Abstract base class for custom transport implementations. Use this to communicate with the Claude process over a custom channel (for example, a remote connection instead of a local subprocess). This is a low-level internal API. The interface may change in future releases. Custom implementations must be updated to match any interface changes. ```python theme={null} from abc import ABC, abstractmethod from collections.abc import AsyncIterator from typing import Any class Transport(ABC): @abstractmethod async def connect(self) -> None: ... @abstractmethod async def write(self, data: str) -> None: ... @abstractmethod def read_messages(self) -> AsyncIterator[dict[str, Any]]: ... @abstractmethod async def close(self) -> None: ... @abstractmethod def is_ready(self) -> bool: ... @abstractmethod async def end_input(self) -> None: ... ``` | Method | Description | | :---------------- | :-------------------------------------------------------------------------- | | `connect()` | Connect the transport and prepare for communication | | `write(data)` | Write raw data (JSON + newline) to the transport | | `read_messages()` | Async iterator that yields parsed JSON messages | | `close()` | Close the connection and clean up resources | | `is_ready()` | Returns `True` if the transport can send and receive | | `end_input()` | Close the input stream (for example, close stdin for subprocess transports) | Import: `from claude_agent_sdk import Transport` ### `ClaudeAgentOptions` Configuration dataclass for Claude Code queries. ```python theme={null} @dataclass class ClaudeAgentOptions: tools: list[str] | ToolsPreset | None = None allowed_tools: list[str] = field(default_factory=list) system_prompt: str | SystemPromptPreset | None = None mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict) permission_mode: PermissionMode | None = None continue_conversation: bool = False resume: str | None = None max_turns: int | None = None max_budget_usd: float | None = None disallowed_tools: list[str] = field(default_factory=list) model: str | None = None fallback_model: str | None = None betas: list[SdkBeta] = field(default_factory=list) output_format: dict[str, Any] | None = None permission_prompt_tool_name: str | None = None cwd: str | Path | None = None cli_path: str | Path | None = None settings: str | None = None add_dirs: list[str | Path] = field(default_factory=list) env: dict[str, str] = field(default_factory=dict) extra_args: dict[str, str | None] = field(default_factory=dict) max_buffer_size: int | None = None debug_stderr: Any = sys.stderr # Deprecated stderr: Callable[[str], None] | None = None can_use_tool: CanUseTool | None = None hooks: dict[HookEvent, list[HookMatcher]] | None = None user: str | None = None include_partial_messages: bool = False fork_session: bool = False agents: dict[str, AgentDefinition] | None = None setting_sources: list[SettingSource] | None = None sandbox: SandboxSettings | None = None plugins: list[SdkPluginConfig] = field(default_factory=list) max_thinking_tokens: int | None = None # Deprecated: use thinking instead thinking: ThinkingConfig | None = None effort: Literal["low", "medium", "high", "max"] | None = None enable_file_checkpointing: bool = False session_store: SessionStore | None = None ``` | Property | Type | Default | Description | | :---------------------------- | :------------------------------------------------------------------------------------- | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `tools` | `list[str] \| ToolsPreset \| None` | `None` | Tools configuration. Use `{"type": "preset", "preset": "claude_code"}` for Claude Code's default tools | | `allowed_tools` | `list[str]` | `[]` | Tools to auto-approve without prompting. This does not restrict Claude to only these tools; unlisted tools fall through to `permission_mode` and `can_use_tool`. Use `disallowed_tools` to block tools. See [Permissions](/en/agent-sdk/permissions#allow-and-deny-rules) | | `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | System prompt configuration. Pass a string for custom prompt, or use `{"type": "preset", "preset": "claude_code"}` for Claude Code's system prompt. Add `"append"` to extend the preset | | `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP server configurations or path to config file | | `permission_mode` | `PermissionMode \| None` | `None` | Permission mode for tool usage | | `continue_conversation` | `bool` | `False` | Continue the most recent conversation | | `resume` | `str \| None` | `None` | Session ID to resume | | `max_turns` | `int \| None` | `None` | Maximum agentic turns (tool-use round trips) | | `max_budget_usd` | `float \| None` | `None` | Stop the query when the client-side cost estimate reaches this USD value. Compared against the same estimate as `total_cost_usd`; see [Track cost and usage](/en/agent-sdk/cost-tracking) for accuracy caveats | | `disallowed_tools` | `list[str]` | `[]` | Tools to always deny. Deny rules are checked first and override `allowed_tools` and `permission_mode` (including `bypassPermissions`) | | `enable_file_checkpointing` | `bool` | `False` | Enable file change tracking for rewinding. See [File checkpointing](/en/agent-sdk/file-checkpointing) | | `model` | `str \| None` | `None` | Claude model to use | | `fallback_model` | `str \| None` | `None` | Fallback model to use if the primary model fails | | `betas` | `list[SdkBeta]` | `[]` | Beta features to enable. See [`SdkBeta`](#sdk-beta) for available options | | `output_format` | `dict[str, Any] \| None` | `None` | Output format for structured responses (e.g., `{"type": "json_schema", "schema": {...}}`). See [Structured outputs](/en/agent-sdk/structured-outputs) for details | | `permission_prompt_tool_name` | `str \| None` | `None` | MCP tool name for permission prompts | | `cwd` | `str \| Path \| None` | `None` | Current working directory | | `cli_path` | `str \| Path \| None` | `None` | Custom path to the Claude Code CLI executable | | `settings` | `str \| None` | `None` | Path to settings file | | `add_dirs` | `list[str \| Path]` | `[]` | Additional directories Claude can access | | `env` | `dict[str, str]` | `{}` | Environment variables merged on top of the inherited process environment. See [Environment variables](../02-Claude-Code-CLI/env-vars-5c624d392b.md) for variables the underlying CLI reads | | `extra_args` | `dict[str, str \| None]` | `{}` | Additional CLI arguments to pass directly to the CLI | | `max_buffer_size` | `int \| None` | `None` | Maximum bytes when buffering CLI stdout | | `debug_stderr` | `Any` | `sys.stderr` | *Deprecated* - File-like object for debug output. Use `stderr` callback instead | | `stderr` | `Callable[[str], None] \| None` | `None` | Callback function for stderr output from CLI | | `can_use_tool` | [`CanUseTool`](#can-use-tool) ` \| None` | `None` | Tool permission callback function. See [Permission types](#can-use-tool) for details | | `hooks` | `dict[HookEvent, list[HookMatcher]] \| None` | `None` | Hook configurations for intercepting events | | `user` | `str \| None` | `None` | User identifier | | `include_partial_messages` | `bool` | `False` | Include partial message streaming events. When enabled, [`StreamEvent`](#stream-event) messages are yielded | | `fork_session` | `bool` | `False` | When resuming with `resume`, fork to a new session ID instead of continuing the original session | | `agents` | `dict[str, AgentDefinition] \| None` | `None` | Programmatically defined subagents | | `plugins` | `list[SdkPluginConfig]` | `[]` | Load custom plugins from local paths. See [Plugins](/en/agent-sdk/plugins) for details | | `sandbox` | [`SandboxSettings`](#sandbox-settings) ` \| None` | `None` | Configure sandbox behavior programmatically. See [Sandbox settings](#sandbox-settings) for details | | `setting_sources` | `list[SettingSource] \| None` | `None` (CLI defaults: all sources) | Control which filesystem settings to load. Pass `[]` to disable user, project, and local settings. Managed policy settings load regardless. See [Use Claude Code features](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) | | `max_thinking_tokens` | `int \| None` | `None` | *Deprecated* - Maximum tokens for thinking blocks. Use `thinking` instead | | `thinking` | [`ThinkingConfig`](#thinking-config) ` \| None` | `None` | Controls extended thinking behavior. Takes precedence over `max_thinking_tokens` | | `effort` | `Literal["low", "medium", "high", "max"] \| None` | `None` | Effort level for thinking depth | | `session_store` | [`SessionStore`](/en/agent-sdk/session-storage#the-session-store-interface) ` \| None` | `None` | Mirror session transcripts to an external backend so any host can resume them. See [Persist sessions to external storage](/en/agent-sdk/session-storage) | ### `OutputFormat` Configuration for structured output validation. Pass this as a `dict` to the `output_format` field on `ClaudeAgentOptions`: ```python theme={null} # Expected dict shape for output_format { "type": "json_schema", "schema": {...}, # Your JSON Schema definition } ``` | Field | Required | Description | | :------- | :------- | :------------------------------------------------- | | `type` | Yes | Must be `"json_schema"` for JSON Schema validation | | `schema` | Yes | JSON Schema definition for output validation | ### `SystemPromptPreset` Configuration for using Claude Code's preset system prompt with optional additions. ```python theme={null} class SystemPromptPreset(TypedDict): type: Literal["preset"] preset: Literal["claude_code"] append: NotRequired[str] exclude_dynamic_sections: NotRequired[bool] ``` | Field | Required | Description | | :------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | Yes | Must be `"preset"` to use a preset system prompt | | `preset` | Yes | Must be `"claude_code"` to use Claude Code's system prompt | | `append` | No | Additional instructions to append to the preset system prompt | | `exclude_dynamic_sections` | No | Move per-session context such as working directory, git status, and memory paths from the system prompt into the first user message. Improves prompt-cache reuse across users and machines. See [Modify system prompts](/en/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) | ### `SettingSource` Controls which filesystem-based configuration sources the SDK loads settings from. ```python theme={null} SettingSource = Literal["user", "project", "local"] ``` | Value | Description | Location | | :---------- | :------------------------------------------- | :---------------------------- | | `"user"` | Global user settings | `~/.claude/settings.json` | | `"project"` | Shared project settings (version controlled) | `.claude/settings.json` | | `"local"` | Local project settings (gitignored) | `.claude/settings.local.json` | #### Default behavior When `setting_sources` is omitted or `None`, `query()` loads the same filesystem settings as the Claude Code CLI: user, project, and local. Managed policy settings are loaded in all cases. See [What settingSources does not control](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) for inputs that are read regardless of this option, and how to disable them. #### Why use setting\_sources **Disable filesystem settings:** ```python theme={null} # Do not load user, project, or local settings from disk from claude_agent_sdk import query, ClaudeAgentOptions async for message in query( prompt="Analyze this code", options=ClaudeAgentOptions( setting_sources=[] ), ): print(message) ``` In Python SDK 0.1.59 and earlier, an empty list was treated the same as omitting the option, so `setting_sources=[]` did not disable filesystem settings. Upgrade to a newer release if you need an empty list to take effect. The TypeScript SDK is not affected. **Load all filesystem settings explicitly:** ```python theme={null} from claude_agent_sdk import query, ClaudeAgentOptions async for message in query( prompt="Analyze this code", options=ClaudeAgentOptions( setting_sources=["user", "project", "local"] ), ): print(message) ``` **Load only specific setting sources:** ```python theme={null} # Load only project settings, ignore user and local async for message in query( prompt="Run CI checks", options=ClaudeAgentOptions( setting_sources=["project"] # Only .claude/settings.json ), ): print(message) ``` **Testing and CI environments:** ```python theme={null} # Ensure consistent behavior in CI by excluding local settings async for message in query( prompt="Run tests", options=ClaudeAgentOptions( setting_sources=["project"], # Only team-shared settings permission_mode="bypassPermissions", ), ): print(message) ``` **SDK-only applications:** ```python theme={null} # Define everything programmatically. # Pass [] to opt out of filesystem setting sources. async for message in query( prompt="Review this PR", options=ClaudeAgentOptions( setting_sources=[], agents={...}, mcp_servers={...}, allowed_tools=["Read", "Grep", "Glob"], ), ): print(message) ``` **Loading CLAUDE.md project instructions:** ```python theme={null} # Load project settings to include CLAUDE.md files async for message in query( prompt="Add a new feature following project conventions", options=ClaudeAgentOptions( system_prompt={ "type": "preset", "preset": "claude_code", # Use Claude Code's system prompt }, setting_sources=["project"], # Loads CLAUDE.md from project allowed_tools=["Read", "Write", "Edit"], ), ): print(message) ``` #### Settings precedence When multiple sources are loaded, settings are merged with this precedence (highest to lowest): 1. Local settings (`.claude/settings.local.json`) 2. Project settings (`.claude/settings.json`) 3. User settings (`~/.claude/settings.json`) Programmatic options such as `agents` and `allowed_tools` override user, project, and local filesystem settings. Managed policy settings take precedence over programmatic options. ### `AgentDefinition` Configuration for a subagent defined programmatically. ```python theme={null} @dataclass class AgentDefinition: description: str prompt: str tools: list[str] | None = None disallowedTools: list[str] | None = None model: str | None = None skills: list[str] | None = None memory: Literal["user", "project", "local"] | None = None mcpServers: list[str | dict[str, Any]] | None = None initialPrompt: str | None = None maxTurns: int | None = None background: bool | None = None effort: Literal["low", "medium", "high", "max"] | int | None = None permissionMode: PermissionMode | None = None ``` | Field | Required | Description | | :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `description` | Yes | Natural language description of when to use this agent | | `prompt` | Yes | The agent's system prompt | | `tools` | No | Array of allowed tool names. If omitted, inherits all tools | | `disallowedTools` | No | Array of tool names to remove from the agent's tool set | | `model` | No | Model override for this agent. Accepts an alias such as `"sonnet"`, `"opus"`, `"haiku"`, or `"inherit"`, or a full model ID. If omitted, uses the main model | | `skills` | No | List of skill names available to this agent | | `memory` | No | Memory source for this agent: `"user"`, `"project"`, or `"local"` | | `mcpServers` | No | MCP servers available to this agent. Each entry is a server name or an inline `{name: config}` dict | | `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main thread agent | | `maxTurns` | No | Maximum number of agentic turns before the agent stops | | `background` | No | Run this agent as a non-blocking background task when invoked | | `effort` | No | Reasoning effort level for this agent. Accepts a named level or an integer | | `permissionMode` | No | Permission mode for tool execution within this agent. See [`PermissionMode`](#permission-mode) | `AgentDefinition` field names use camelCase, such as `disallowedTools`, `permissionMode`, and `maxTurns`. These names map directly to the wire format shared with the TypeScript SDK. This differs from `ClaudeAgentOptions`, which uses Python snake\_case for the equivalent top-level fields such as `disallowed_tools` and `permission_mode`. Because `AgentDefinition` is a dataclass, passing a snake\_case keyword raises a `TypeError` at construction time. ### `PermissionMode` Permission modes for controlling tool execution. ```python theme={null} PermissionMode = Literal[ "default", # Standard permission behavior "acceptEdits", # Auto-accept file edits "plan", # Planning mode - no execution "dontAsk", # Deny anything not pre-approved instead of prompting "bypassPermissions", # Bypass all permission checks (use with caution) ] ``` ### `CanUseTool` Type alias for tool permission callback functions. ```python theme={null} CanUseTool = Callable[ [str, dict[str, Any], ToolPermissionContext], Awaitable[PermissionResult] ] ``` The callback receives: * `tool_name`: Name of the tool being called * `input_data`: The tool's input parameters * `context`: A `ToolPermissionContext` with additional information Returns a `PermissionResult` (either `PermissionResultAllow` or `PermissionResultDeny`). ### `ToolPermissionContext` Context information passed to tool permission callbacks. ```python theme={null} @dataclass class ToolPermissionContext: signal: Any | None = None # Future: abort signal support suggestions: list[PermissionUpdate] = field(default_factory=list) ``` | Field | Type | Description | | :------------ | :----------------------- | :----------------------------------------- | | `signal` | `Any \| None` | Reserved for future abort signal support | | `suggestions` | `list[PermissionUpdate]` | Permission update suggestions from the CLI | ### `PermissionResult` Union type for permission callback results. ```python theme={null} PermissionResult = PermissionResultAllow | PermissionResultDeny ``` ### `PermissionResultAllow` Result indicating the tool call should be allowed. ```python theme={null} @dataclass class PermissionResultAllow: behavior: Literal["allow"] = "allow" updated_input: dict[str, Any] | None = None updated_permissions: list[PermissionUpdate] | None = None ``` | Field | Type | Default | Description | | :-------------------- | :------------------------------- | :-------- | :---------------------------------------- | | `behavior` | `Literal["allow"]` | `"allow"` | Must be "allow" | | `updated_input` | `dict[str, Any] \| None` | `None` | Modified input to use instead of original | | `updated_permissions` | `list[PermissionUpdate] \| None` | `None` | Permission updates to apply | ### `PermissionResultDeny` Result indicating the tool call should be denied. ```python theme={null} @dataclass class PermissionResultDeny: behavior: Literal["deny"] = "deny" message: str = "" interrupt: bool = False ``` | Field | Type | Default | Description | | :---------- | :---------------- | :------- | :----------------------------------------- | | `behavior` | `Literal["deny"]` | `"deny"` | Must be "deny" | | `message` | `str` | `""` | Message explaining why the tool was denied | | `interrupt` | `bool` | `False` | Whether to interrupt the current execution | ### `PermissionUpdate` Configuration for updating permissions programmatically. ```python theme={null} @dataclass class PermissionUpdate: type: Literal[ "addRules", "replaceRules", "removeRules", "setMode", "addDirectories", "removeDirectories", ] rules: list[PermissionRuleValue] | None = None behavior: Literal["allow", "deny", "ask"] | None = None mode: PermissionMode | None = None directories: list[str] | None = None destination: ( Literal["userSettings", "projectSettings", "localSettings", "session"] | None ) = None ``` | Field | Type | Description | | :------------ | :---------------------------------------- | :---------------------------------------------- | | `type` | `Literal[...]` | The type of permission update operation | | `rules` | `list[PermissionRuleValue] \| None` | Rules for add/replace/remove operations | | `behavior` | `Literal["allow", "deny", "ask"] \| None` | Behavior for rule-based operations | | `mode` | `PermissionMode \| None` | Mode for setMode operation | | `directories` | `list[str] \| None` | Directories for add/remove directory operations | | `destination` | `Literal[...] \| None` | Where to apply the permission update | ### `PermissionRuleValue` A rule to add, replace, or remove in a permission update. ```python theme={null} @dataclass class PermissionRuleValue: tool_name: str rule_content: str | None = None ``` ### `ToolsPreset` Preset tools configuration for using Claude Code's default tool set. ```python theme={null} class ToolsPreset(TypedDict): type: Literal["preset"] preset: Literal["claude_code"] ``` ### `ThinkingConfig` Controls extended thinking behavior. A union of three configurations: ```python theme={null} class ThinkingConfigAdaptive(TypedDict): type: Literal["adaptive"] class ThinkingConfigEnabled(TypedDict): type: Literal["enabled"] budget_tokens: int class ThinkingConfigDisabled(TypedDict): type: Literal["disabled"] ThinkingConfig = ThinkingConfigAdaptive | ThinkingConfigEnabled | ThinkingConfigDisabled ``` | Variant | Fields | Description | | :--------- | :---------------------- | :------------------------------------------- | | `adaptive` | `type` | Claude adaptively decides when to think | | `enabled` | `type`, `budget_tokens` | Enable thinking with a specific token budget | | `disabled` | `type` | Disable thinking | Because these are `TypedDict` classes, they're plain dicts at runtime. Either construct them as dict literals or call the class like a constructor; both produce a `dict`. Access fields with `config["budget_tokens"]`, not `config.budget_tokens`: ```python theme={null} from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled # Option 1: dict literal (recommended, no import needed) options = ClaudeAgentOptions(thinking={"type": "enabled", "budget_tokens": 20000}) # Option 2: constructor-style (returns a plain dict) config = ThinkingConfigEnabled(type="enabled", budget_tokens=20000) print(config["budget_tokens"]) # 20000 # config.budget_tokens would raise AttributeError ``` ### `SdkBeta` Literal type for SDK beta features. ```python theme={null} SdkBeta = Literal["context-1m-2025-08-07"] ``` Use with the `betas` field in `ClaudeAgentOptions` to enable beta features. The `context-1m-2025-08-07` beta is retired as of April 30, 2026. Passing this header with Claude Sonnet 4.5 or Sonnet 4 has no effect, and requests that exceed the standard 200k-token context window return an error. To use a 1M-token context window, migrate to [Claude Sonnet 4.6, Claude Opus 4.6, or Claude Opus 4.7](../20-Models/about-claude-models-overview-2bbf09ff82.md), which include 1M context at standard pricing with no beta header required. ### `McpSdkServerConfig` Configuration for SDK MCP servers created with `create_sdk_mcp_server()`. ```python theme={null} class McpSdkServerConfig(TypedDict): type: Literal["sdk"] name: str instance: Any # MCP Server instance ``` ### `McpServerConfig` Union type for MCP server configurations. ```python theme={null} McpServerConfig = ( McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig ) ``` #### `McpStdioServerConfig` ```python theme={null} class McpStdioServerConfig(TypedDict): type: NotRequired[Literal["stdio"]] # Optional for backwards compatibility command: str args: NotRequired[list[str]] env: NotRequired[dict[str, str]] ``` #### `McpSSEServerConfig` ```python theme={null} class McpSSEServerConfig(TypedDict): type: Literal["sse"] url: str headers: NotRequired[dict[str, str]] ``` #### `McpHttpServerConfig` ```python theme={null} class McpHttpServerConfig(TypedDict): type: Literal["http"] url: str headers: NotRequired[dict[str, str]] ``` ### `McpServerStatusConfig` The configuration of an MCP server as reported by [`get_mcp_status()`](#methods). This is the union of all [`McpServerConfig`](#mcp-server-config) transport variants plus an output-only `claudeai-proxy` variant for servers proxied through claude.ai. ```python theme={null} McpServerStatusConfig = ( McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfigStatus | McpClaudeAIProxyServerConfig ) ``` `McpSdkServerConfigStatus` is the serializable form of [`McpSdkServerConfig`](#mcp-sdk-server-config) with only `type` (`"sdk"`) and `name` (`str`) fields; the in-process `instance` is omitted. `McpClaudeAIProxyServerConfig` has `type` (`"claudeai-proxy"`), `url` (`str`), and `id` (`str`) fields. ### `McpStatusResponse` Response from [`ClaudeSDKClient.get_mcp_status()`](#methods). Wraps the list of server statuses under the `mcpServers` key. ```python theme={null} class McpStatusResponse(TypedDict): mcpServers: list[McpServerStatus] ``` ### `McpServerStatus` Status of a connected MCP server, contained in [`McpStatusResponse`](#mcp-status-response). ```python theme={null} class McpServerStatus(TypedDict): name: str status: McpServerConnectionStatus # "connected" | "failed" | "needs-auth" | "pending" | "disabled" serverInfo: NotRequired[McpServerInfo] error: NotRequired[str] config: NotRequired[McpServerStatusConfig] scope: NotRequired[str] tools: NotRequired[list[McpToolInfo]] ``` | Field | Type | Description | | :----------- | :-------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` | `str` | Server name | | `status` | `str` | One of `"connected"`, `"failed"`, `"needs-auth"`, `"pending"`, or `"disabled"` | | `serverInfo` | `dict` (optional) | Server name and version (`{"name": str, "version": str}`) | | `error` | `str` (optional) | Error message if the server failed to connect | | `config` | [`McpServerStatusConfig`](#mcp-server-status-config) (optional) | Server configuration. Same shape as [`McpServerConfig`](#mcp-server-config) (stdio, SSE, HTTP, or SDK), plus a `claudeai-proxy` variant for servers connected through claude.ai | | `scope` | `str` (optional) | Configuration scope | | `tools` | `list` (optional) | Tools provided by this server, each with `name`, `description`, and `annotations` fields | ### `SdkPluginConfig` Configuration for loading plugins in the SDK. ```python theme={null} class SdkPluginConfig(TypedDict): type: Literal["local"] path: str ``` | Field | Type | Description | | :----- | :----------------- | :--------------------------------------------------------- | | `type` | `Literal["local"]` | Must be `"local"` (only local plugins currently supported) | | `path` | `str` | Absolute or relative path to the plugin directory | **Example:** ```python theme={null} plugins = [ {"type": "local", "path": "./my-plugin"}, {"type": "local", "path": "/absolute/path/to/plugin"}, ] ``` For complete information on creating and using plugins, see [Plugins](/en/agent-sdk/plugins). ## Message Types ### `Message` Union type of all possible messages. ```python theme={null} Message = ( UserMessage | AssistantMessage | SystemMessage | ResultMessage | StreamEvent | RateLimitEvent ) ``` ### `UserMessage` User input message. ```python theme={null} @dataclass class UserMessage: content: str | list[ContentBlock] uuid: str | None = None parent_tool_use_id: str | None = None tool_use_result: dict[str, Any] | None = None ``` | Field | Type | Description | | :------------------- | :-------------------------- | :---------------------------------------------------- | | `content` | `str \| list[ContentBlock]` | Message content as text or content blocks | | `uuid` | `str \| None` | Unique message identifier | | `parent_tool_use_id` | `str \| None` | Tool use ID if this message is a tool result response | | `tool_use_result` | `dict[str, Any] \| None` | Tool result data if applicable | ### `AssistantMessage` Assistant response message with content blocks. ```python theme={null} @dataclass class AssistantMessage: content: list[ContentBlock] model: str parent_tool_use_id: str | None = None error: AssistantMessageError | None = None usage: dict[str, Any] | None = None message_id: str | None = None ``` | Field | Type | Description | | :------------------- | :------------------------------------------------------------- | :------------------------------------------------------------------------------ | | `content` | `list[ContentBlock]` | List of content blocks in the response | | `model` | `str` | Model that generated the response | | `parent_tool_use_id` | `str \| None` | Tool use ID if this is a nested response | | `error` | [`AssistantMessageError`](#assistant-message-error) ` \| None` | Error type if the response encountered an error | | `usage` | `dict[str, Any] \| None` | Per-message token usage (same keys as [`ResultMessage.usage`](#result-message)) | | `message_id` | `str \| None` | API message ID. Multiple messages from one turn share the same ID | ### `AssistantMessageError` Possible error types for assistant messages. ```python theme={null} AssistantMessageError = Literal[ "authentication_failed", "billing_error", "rate_limit", "invalid_request", "server_error", "max_output_tokens", "unknown", ] ``` ### `SystemMessage` System message with metadata. ```python theme={null} @dataclass class SystemMessage: subtype: str data: dict[str, Any] ``` ### `ResultMessage` Final result message with cost and usage information. ```python theme={null} @dataclass class ResultMessage: subtype: str duration_ms: int duration_api_ms: int is_error: bool num_turns: int session_id: str total_cost_usd: float | None = None usage: dict[str, Any] | None = None result: str | None = None stop_reason: str | None = None structured_output: Any = None model_usage: dict[str, Any] | None = None ``` The `usage` dict contains the following keys when present: | Key | Type | Description | | ----------------------------- | ----- | ---------------------------------------- | | `input_tokens` | `int` | Total input tokens consumed. | | `output_tokens` | `int` | Total output tokens generated. | | `cache_creation_input_tokens` | `int` | Tokens used to create new cache entries. | | `cache_read_input_tokens` | `int` | Tokens read from existing cache entries. | The `model_usage` dict maps model names to per-model usage. The inner dict keys use camelCase because the value is passed through unmodified from the underlying CLI process, matching the TypeScript [`ModelUsage`](/en/agent-sdk/typescript#model-usage) type: | Key | Type | Description | | -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `inputTokens` | `int` | Input tokens for this model. | | `outputTokens` | `int` | Output tokens for this model. | | `cacheReadInputTokens` | `int` | Cache read tokens for this model. | | `cacheCreationInputTokens` | `int` | Cache creation tokens for this model. | | `webSearchRequests` | `int` | Web search requests made by this model. | | `costUSD` | `float` | Estimated cost in USD for this model, computed client-side. See [Track cost and usage](/en/agent-sdk/cost-tracking) for billing caveats. | | `contextWindow` | `int` | Context window size for this model. | | `maxOutputTokens` | `int` | Maximum output token limit for this model. | ### `StreamEvent` Stream event for partial message updates during streaming. Only received when `include_partial_messages=True` in `ClaudeAgentOptions`. Import via `from claude_agent_sdk.types import StreamEvent`. ```python theme={null} @dataclass class StreamEvent: uuid: str session_id: str event: dict[str, Any] # The raw Claude API stream event parent_tool_use_id: str | None = None ``` | Field | Type | Description | | :------------------- | :--------------- | :-------------------------------------------------- | | `uuid` | `str` | Unique identifier for this event | | `session_id` | `str` | Session identifier | | `event` | `dict[str, Any]` | The raw Claude API stream event data | | `parent_tool_use_id` | `str \| None` | Parent tool use ID if this event is from a subagent | ### `RateLimitEvent` Emitted when rate limit status changes (for example, from `"allowed"` to `"allowed_warning"`). Use this to warn users before they hit a hard limit, or to back off when status is `"rejected"`. ```python theme={null} @dataclass class RateLimitEvent: rate_limit_info: RateLimitInfo uuid: str session_id: str ``` | Field | Type | Description | | :---------------- | :---------------------------------- | :----------------------- | | `rate_limit_info` | [`RateLimitInfo`](#rate-limit-info) | Current rate limit state | | `uuid` | `str` | Unique event identifier | | `session_id` | `str` | Session identifier | ### `RateLimitInfo` Rate limit state carried by [`RateLimitEvent`](#rate-limit-event). ```python theme={null} RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"] RateLimitType = Literal[ "five_hour", "seven_day", "seven_day_opus", "seven_day_sonnet", "overage" ] @dataclass class RateLimitInfo: status: RateLimitStatus resets_at: int | None = None rate_limit_type: RateLimitType | None = None utilization: float | None = None overage_status: RateLimitStatus | None = None overage_resets_at: int | None = None overage_disabled_reason: str | None = None raw: dict[str, Any] = field(default_factory=dict) ``` | Field | Type | Description | | :------------------------ | :------------------------ | :---------------------------------------------------------------------------------------------------- | | `status` | `RateLimitStatus` | Current status. `"allowed_warning"` means approaching the limit; `"rejected"` means the limit was hit | | `resets_at` | `int \| None` | Unix timestamp when the rate limit window resets | | `rate_limit_type` | `RateLimitType \| None` | Which rate limit window applies | | `utilization` | `float \| None` | Fraction of the rate limit consumed (0.0 to 1.0) | | `overage_status` | `RateLimitStatus \| None` | Status of pay-as-you-go overage usage, if applicable | | `overage_resets_at` | `int \| None` | Unix timestamp when the overage window resets | | `overage_disabled_reason` | `str \| None` | Why overage is unavailable, if status is `"rejected"` | | `raw` | `dict[str, Any]` | Full raw dict from the CLI, including fields not modeled above | ### `TaskStartedMessage` Emitted when a background task starts. A background task is anything tracked outside the main turn: a backgrounded Bash command, a [Monitor](#monitor) watch, a subagent spawned via the Agent tool, or a remote agent. The `task_type` field tells you which. This naming is unrelated to the `Task`-to-`Agent` tool rename. ```python theme={null} @dataclass class TaskStartedMessage(SystemMessage): task_id: str description: str uuid: str session_id: str tool_use_id: str | None = None task_type: str | None = None ``` | Field | Type | Description | | :------------ | :------------ | :-------------------------------------------------------------------------------------------------------------------------- | | `task_id` | `str` | Unique identifier for the task | | `description` | `str` | Description of the task | | `uuid` | `str` | Unique message identifier | | `session_id` | `str` | Session identifier | | `tool_use_id` | `str \| None` | Associated tool use ID | | `task_type` | `str \| None` | Which kind of background task: `"local_bash"` for background Bash and Monitor watches, `"local_agent"`, or `"remote_agent"` | ### `TaskUsage` Token and timing data for a background task. ```python theme={null} class TaskUsage(TypedDict): total_tokens: int tool_uses: int duration_ms: int ``` ### `TaskProgressMessage` Emitted periodically with progress updates for a running background task. ```python theme={null} @dataclass class TaskProgressMessage(SystemMessage): task_id: str description: str usage: TaskUsage uuid: str session_id: str tool_use_id: str | None = None last_tool_name: str | None = None ``` | Field | Type | Description | | :--------------- | :------------ | :---------------------------------- | | `task_id` | `str` | Unique identifier for the task | | `description` | `str` | Current status description | | `usage` | `TaskUsage` | Token usage for this task so far | | `uuid` | `str` | Unique message identifier | | `session_id` | `str` | Session identifier | | `tool_use_id` | `str \| None` | Associated tool use ID | | `last_tool_name` | `str \| None` | Name of the last tool the task used | ### `TaskNotificationMessage` Emitted when a background task completes, fails, or is stopped. Background tasks include `run_in_background` Bash commands, Monitor watches, and background subagents. ```python theme={null} @dataclass class TaskNotificationMessage(SystemMessage): task_id: str status: TaskNotificationStatus # "completed" | "failed" | "stopped" output_file: str summary: str uuid: str session_id: str tool_use_id: str | None = None usage: TaskUsage | None = None ``` | Field | Type | Description | | :------------ | :----------------------- | :----------------------------------------------- | | `task_id` | `str` | Unique identifier for the task | | `status` | `TaskNotificationStatus` | One of `"completed"`, `"failed"`, or `"stopped"` | | `output_file` | `str` | Path to the task output file | | `summary` | `str` | Summary of the task result | | `uuid` | `str` | Unique message identifier | | `session_id` | `str` | Session identifier | | `tool_use_id` | `str \| None` | Associated tool use ID | | `usage` | `TaskUsage \| None` | Final token usage for the task | ## Content Block Types ### `ContentBlock` Union type of all content blocks. ```python theme={null} ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock ``` ### `TextBlock` Text content block. ```python theme={null} @dataclass class TextBlock: text: str ``` ### `ThinkingBlock` Thinking content block (for models with thinking capability). ```python theme={null} @dataclass class ThinkingBlock: thinking: str signature: str ``` ### `ToolUseBlock` Tool use request block. ```python theme={null} @dataclass class ToolUseBlock: id: str name: str input: dict[str, Any] ``` ### `ToolResultBlock` Tool execution result block. ```python theme={null} @dataclass class ToolResultBlock: tool_use_id: str content: str | list[dict[str, Any]] | None = None is_error: bool | None = None ``` ## Error Types ### `ClaudeSDKError` Base exception class for all SDK errors. ```python theme={null} class ClaudeSDKError(Exception): """Base error for Claude SDK.""" ``` ### `CLINotFoundError` Raised when Claude Code CLI is not installed or not found. ```python theme={null} class CLINotFoundError(CLIConnectionError): def __init__( self, message: str = "Claude Code not found", cli_path: str | None = None ): """ Args: message: Error message (default: "Claude Code not found") cli_path: Optional path to the CLI that was not found """ ``` ### `CLIConnectionError` Raised when connection to Claude Code fails. ```python theme={null} class CLIConnectionError(ClaudeSDKError): """Failed to connect to Claude Code.""" ``` ### `ProcessError` Raised when the Claude Code process fails. ```python theme={null} class ProcessError(ClaudeSDKError): def __init__( self, message: str, exit_code: int | None = None, stderr: str | None = None ): self.exit_code = exit_code self.stderr = stderr ``` ### `CLIJSONDecodeError` Raised when JSON parsing fails. ```python theme={null} class CLIJSONDecodeError(ClaudeSDKError): def __init__(self, line: str, original_error: Exception): """ Args: line: The line that failed to parse original_error: The original JSON decode exception """ self.line = line self.original_error = original_error ``` ## Hook Types For a comprehensive guide on using hooks with examples and common patterns, see the [Hooks guide](/en/agent-sdk/hooks). ### `HookEvent` Supported hook event types. ```python theme={null} HookEvent = Literal[ "PreToolUse", # Called before tool execution "PostToolUse", # Called after tool execution "PostToolUseFailure", # Called when a tool execution fails "UserPromptSubmit", # Called when user submits a prompt "Stop", # Called when stopping execution "SubagentStop", # Called when a subagent stops "PreCompact", # Called before message compaction "Notification", # Called for notification events "SubagentStart", # Called when a subagent starts "PermissionRequest", # Called when a permission decision is needed ] ``` The TypeScript SDK supports additional hook events not yet available in Python: `SessionStart`, `SessionEnd`, `Setup`, `TeammateIdle`, `TaskCompleted`, `ConfigChange`, `WorktreeCreate`, `WorktreeRemove`, and `PostToolBatch`. ### `HookCallback` Type definition for hook callback functions. ```python theme={null} HookCallback = Callable[[HookInput, str | None, HookContext], Awaitable[HookJSONOutput]] ``` Parameters: * `input`: Strongly-typed hook input with discriminated unions based on `hook_event_name` (see [`HookInput`](#hook-input)) * `tool_use_id`: Optional tool use identifier (for tool-related hooks) * `context`: Hook context with additional information Returns a [`HookJSONOutput`](#hook-json-output) that may contain: * `decision`: `"block"` to block the action * `systemMessage`: System message to add to the transcript * `hookSpecificOutput`: Hook-specific output data ### `HookContext` Context information passed to hook callbacks. ```python theme={null} class HookContext(TypedDict): signal: Any | None # Future: abort signal support ``` ### `HookMatcher` Configuration for matching hooks to specific events or tools. ```python theme={null} @dataclass class HookMatcher: matcher: str | None = ( None # Tool name or pattern to match (e.g., "Bash", "Write|Edit") ) hooks: list[HookCallback] = field( default_factory=list ) # List of callbacks to execute timeout: float | None = ( None # Timeout in seconds for all hooks in this matcher (default: 60) ) ``` ### `HookInput` Union type of all hook input types. The actual type depends on the `hook_event_name` field. ```python theme={null} HookInput = ( PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | UserPromptSubmitHookInput | StopHookInput | SubagentStopHookInput | PreCompactHookInput | NotificationHookInput | SubagentStartHookInput | PermissionRequestHookInput ) ``` ### `BaseHookInput` Base fields present in all hook input types. ```python theme={null} class BaseHookInput(TypedDict): session_id: str transcript_path: str cwd: str permission_mode: NotRequired[str] ``` | Field | Type | Description | | :---------------- | :--------------- | :---------------------------------- | | `session_id` | `str` | Current session identifier | | `transcript_path` | `str` | Path to the session transcript file | | `cwd` | `str` | Current working directory | | `permission_mode` | `str` (optional) | Current permission mode | ### `PreToolUseHookInput` Input data for `PreToolUse` hook events. ```python theme={null} class PreToolUseHookInput(BaseHookInput): hook_event_name: Literal["PreToolUse"] tool_name: str tool_input: dict[str, Any] tool_use_id: str agent_id: NotRequired[str] agent_type: NotRequired[str] ``` | Field | Type | Description | | :---------------- | :---------------------- | :----------------------------------------------------------------- | | `hook_event_name` | `Literal["PreToolUse"]` | Always "PreToolUse" | | `tool_name` | `str` | Name of the tool about to be executed | | `tool_input` | `dict[str, Any]` | Input parameters for the tool | | `tool_use_id` | `str` | Unique identifier for this tool use | | `agent_id` | `str` (optional) | Subagent identifier, present when the hook fires inside a subagent | | `agent_type` | `str` (optional) | Subagent type, present when the hook fires inside a subagent | ### `PostToolUseHookInput` Input data for `PostToolUse` hook events. ```python theme={null} class PostToolUseHookInput(BaseHookInput): hook_event_name: Literal["PostToolUse"] tool_name: str tool_input: dict[str, Any] tool_response: Any tool_use_id: str agent_id: NotRequired[str] agent_type: NotRequired[str] ``` | Field | Type | Description | | :---------------- | :----------------------- | :----------------------------------------------------------------- | | `hook_event_name` | `Literal["PostToolUse"]` | Always "PostToolUse" | | `tool_name` | `str` | Name of the tool that was executed | | `tool_input` | `dict[str, Any]` | Input parameters that were used | | `tool_response` | `Any` | Response from the tool execution | | `tool_use_id` | `str` | Unique identifier for this tool use | | `agent_id` | `str` (optional) | Subagent identifier, present when the hook fires inside a subagent | | `agent_type` | `str` (optional) | Subagent type, present when the hook fires inside a subagent | ### `PostToolUseFailureHookInput` Input data for `PostToolUseFailure` hook events. Called when a tool execution fails. ```python theme={null} class PostToolUseFailureHookInput(BaseHookInput): hook_event_name: Literal["PostToolUseFailure"] tool_name: str tool_input: dict[str, Any] tool_use_id: str error: str is_interrupt: NotRequired[bool] agent_id: NotRequired[str] agent_type: NotRequired[str] ``` | Field | Type | Description | | :---------------- | :------------------------------ | :----------------------------------------------------------------- | | `hook_event_name` | `Literal["PostToolUseFailure"]` | Always "PostToolUseFailure" | | `tool_name` | `str` | Name of the tool that failed | | `tool_input` | `dict[str, Any]` | Input parameters that were used | | `tool_use_id` | `str` | Unique identifier for this tool use | | `error` | `str` | Error message from the failed execution | | `is_interrupt` | `bool` (optional) | Whether the failure was caused by an interrupt | | `agent_id` | `str` (optional) | Subagent identifier, present when the hook fires inside a subagent | | `agent_type` | `str` (optional) | Subagent type, present when the hook fires inside a subagent | ### `UserPromptSubmitHookInput` Input data for `UserPromptSubmit` hook events. ```python theme={null} class UserPromptSubmitHookInput(BaseHookInput): hook_event_name: Literal["UserPromptSubmit"] prompt: str ``` | Field | Type | Description | | :---------------- | :---------------------------- | :-------------------------- | | `hook_event_name` | `Literal["UserPromptSubmit"]` | Always "UserPromptSubmit" | | `prompt` | `str` | The user's submitted prompt | ### `StopHookInput` Input data for `Stop` hook events. ```python theme={null} class StopHookInput(BaseHookInput): hook_event_name: Literal["Stop"] stop_hook_active: bool ``` | Field | Type | Description | | :----------------- | :---------------- | :------------------------------ | | `hook_event_name` | `Literal["Stop"]` | Always "Stop" | | `stop_hook_active` | `bool` | Whether the stop hook is active | ### `SubagentStopHookInput` Input data for `SubagentStop` hook events. ```python theme={null} class SubagentStopHookInput(BaseHookInput): hook_event_name: Literal["SubagentStop"] stop_hook_active: bool agent_id: str agent_transcript_path: str agent_type: str ``` | Field | Type | Description | | :---------------------- | :------------------------ | :------------------------------------- | | `hook_event_name` | `Literal["SubagentStop"]` | Always "SubagentStop" | | `stop_hook_active` | `bool` | Whether the stop hook is active | | `agent_id` | `str` | Unique identifier for the subagent | | `agent_transcript_path` | `str` | Path to the subagent's transcript file | | `agent_type` | `str` | Type of the subagent | ### `PreCompactHookInput` Input data for `PreCompact` hook events. ```python theme={null} class PreCompactHookInput(BaseHookInput): hook_event_name: Literal["PreCompact"] trigger: Literal["manual", "auto"] custom_instructions: str | None ``` | Field | Type | Description | | :-------------------- | :-------------------------- | :--------------------------------- | | `hook_event_name` | `Literal["PreCompact"]` | Always "PreCompact" | | `trigger` | `Literal["manual", "auto"]` | What triggered the compaction | | `custom_instructions` | `str \| None` | Custom instructions for compaction | ### `NotificationHookInput` Input data for `Notification` hook events. ```python theme={null} class NotificationHookInput(BaseHookInput): hook_event_name: Literal["Notification"] message: str title: NotRequired[str] notification_type: str ``` | Field | Type | Description | | :------------------ | :------------------------ | :--------------------------- | | `hook_event_name` | `Literal["Notification"]` | Always "Notification" | | `message` | `str` | Notification message content | | `title` | `str` (optional) | Notification title | | `notification_type` | `str` | Type of notification | ### `SubagentStartHookInput` Input data for `SubagentStart` hook events. ```python theme={null} class SubagentStartHookInput(BaseHookInput): hook_event_name: Literal["SubagentStart"] agent_id: str agent_type: str ``` | Field | Type | Description | | :---------------- | :------------------------- | :--------------------------------- | | `hook_event_name` | `Literal["SubagentStart"]` | Always "SubagentStart" | | `agent_id` | `str` | Unique identifier for the subagent | | `agent_type` | `str` | Type of the subagent | ### `PermissionRequestHookInput` Input data for `PermissionRequest` hook events. Allows hooks to handle permission decisions programmatically. ```python theme={null} class PermissionRequestHookInput(BaseHookInput): hook_event_name: Literal["PermissionRequest"] tool_name: str tool_input: dict[str, Any] permission_suggestions: NotRequired[list[Any]] ``` | Field | Type | Description | | :----------------------- | :----------------------------- | :---------------------------------------- | | `hook_event_name` | `Literal["PermissionRequest"]` | Always "PermissionRequest" | | `tool_name` | `str` | Name of the tool requesting permission | | `tool_input` | `dict[str, Any]` | Input parameters for the tool | | `permission_suggestions` | `list[Any]` (optional) | Suggested permission updates from the CLI | ### `HookJSONOutput` Union type for hook callback return values. ```python theme={null} HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput ``` #### `SyncHookJSONOutput` Synchronous hook output with control and decision fields. ```python theme={null} class SyncHookJSONOutput(TypedDict): # Control fields continue_: NotRequired[bool] # Whether to proceed (default: True) suppressOutput: NotRequired[bool] # Hide stdout from transcript stopReason: NotRequired[str] # Message when continue is False # Decision fields decision: NotRequired[Literal["block"]] systemMessage: NotRequired[str] # Warning message for user reason: NotRequired[str] # Feedback for Claude # Hook-specific output hookSpecificOutput: NotRequired[HookSpecificOutput] ``` Use `continue_` (with underscore) in Python code. It is automatically converted to `continue` when sent to the CLI. #### `HookSpecificOutput` A `TypedDict` containing the hook event name and event-specific fields. The shape depends on the `hookEventName` value. For full details on available fields per hook event, see [Control execution with hooks](/en/agent-sdk/hooks#outputs). A discriminated union of event-specific output types. The `hookEventName` field determines which fields are valid. ```python theme={null} class PreToolUseHookSpecificOutput(TypedDict): hookEventName: Literal["PreToolUse"] permissionDecision: NotRequired[Literal["allow", "deny", "ask"]] permissionDecisionReason: NotRequired[str] updatedInput: NotRequired[dict[str, Any]] additionalContext: NotRequired[str] class PostToolUseHookSpecificOutput(TypedDict): hookEventName: Literal["PostToolUse"] additionalContext: NotRequired[str] updatedMCPToolOutput: NotRequired[Any] class PostToolUseFailureHookSpecificOutput(TypedDict): hookEventName: Literal["PostToolUseFailure"] additionalContext: NotRequired[str] class UserPromptSubmitHookSpecificOutput(TypedDict): hookEventName: Literal["UserPromptSubmit"] additionalContext: NotRequired[str] class NotificationHookSpecificOutput(TypedDict): hookEventName: Literal["Notification"] additionalContext: NotRequired[str] class SubagentStartHookSpecificOutput(TypedDict): hookEventName: Literal["SubagentStart"] additionalContext: NotRequired[str] class PermissionRequestHookSpecificOutput(TypedDict): hookEventName: Literal["PermissionRequest"] decision: dict[str, Any] HookSpecificOutput = ( PreToolUseHookSpecificOutput | PostToolUseHookSpecificOutput | PostToolUseFailureHookSpecificOutput | UserPromptSubmitHookSpecificOutput | NotificationHookSpecificOutput | SubagentStartHookSpecificOutput | PermissionRequestHookSpecificOutput ) ``` #### `AsyncHookJSONOutput` Async hook output that defers hook execution. ```python theme={null} class AsyncHookJSONOutput(TypedDict): async_: Literal[True] # Set to True to defer execution asyncTimeout: NotRequired[int] # Timeout in milliseconds ``` Use `async_` (with underscore) in Python code. It is automatically converted to `async` when sent to the CLI. ### Hook Usage Example This example registers two hooks: one that blocks dangerous bash commands like `rm -rf /`, and another that logs all tool usage for auditing. The security hook only runs on Bash commands (via the `matcher`), while the logging hook runs on all tools. ```python theme={null} from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, HookContext from typing import Any async def validate_bash_command( input_data: dict[str, Any], tool_use_id: str | None, context: HookContext ) -> dict[str, Any]: """Validate and potentially block dangerous bash commands.""" if input_data["tool_name"] == "Bash": command = input_data["tool_input"].get("command", "") if "rm -rf /" in command: return { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Dangerous command blocked", } } return {} async def log_tool_use( input_data: dict[str, Any], tool_use_id: str | None, context: HookContext ) -> dict[str, Any]: """Log all tool usage for auditing.""" print(f"Tool used: {input_data.get('tool_name')}") return {} options = ClaudeAgentOptions( hooks={ "PreToolUse": [ HookMatcher( matcher="Bash", hooks=[validate_bash_command], timeout=120 ), # 2 min for validation HookMatcher( hooks=[log_tool_use] ), # Applies to all tools (default 60s timeout) ], "PostToolUse": [HookMatcher(hooks=[log_tool_use])], } ) async for message in query(prompt="Analyze this codebase", options=options): print(message) ``` ## Tool Input/Output Types Documentation 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. ### Agent **Tool name:** `Agent` (previously `Task`, which is still accepted as an alias) **Input:** ```python theme={null} { "description": str, # A short (3-5 word) description of the task "prompt": str, # The task for the agent to perform "subagent_type": str, # The type of specialized agent to use } ``` **Output:** ```python theme={null} { "result": str, # Final result from the subagent "usage": dict | None, # Token usage statistics "total_cost_usd": float | None, # Estimated total cost in USD "duration_ms": int | None, # Execution duration in milliseconds } ``` ### AskUserQuestion **Tool name:** `AskUserQuestion` Asks the user clarifying questions during execution. See [Handle approvals and user input](/en/agent-sdk/user-input#handle-clarifying-questions) for usage details. **Input:** ```python theme={null} { "questions": [ # Questions to ask the user (1-4 questions) { "question": str, # The complete question to ask the user "header": str, # Very short label displayed as a chip/tag (max 12 chars) "options": [ # The available choices (2-4 options) { "label": str, # Display text for this option (1-5 words) "description": str, # Explanation of what this option means } ], "multiSelect": bool, # Set to true to allow multiple selections } ], "answers": dict | None, # User answers populated by the permission system } ``` **Output:** ```python theme={null} { "questions": [ # The questions that were asked { "question": str, "header": str, "options": [{"label": str, "description": str}], "multiSelect": bool, } ], "answers": dict[str, str], # Maps question text to answer string # Multi-select answers are comma-separated } ``` ### Bash **Tool name:** `Bash` **Input:** ```python theme={null} { "command": str, # The command to execute "timeout": int | None, # Optional timeout in milliseconds (max 600000) "description": str | None, # Clear, concise description (5-10 words) "run_in_background": bool | None, # Set to true to run in background } ``` **Output:** ```python theme={null} { "output": str, # Combined stdout and stderr output "exitCode": int, # Exit code of the command "killed": bool | None, # Whether command was killed due to timeout "shellId": str | None, # Shell ID for background processes } ``` ### Monitor **Tool name:** `Monitor` Runs a background script and delivers each stdout line to Claude as an event so it can react without polling. Monitor follows the same permission rules as Bash. See the [Monitor tool reference](/en/tools-reference#monitor-tool) for behavior and provider availability. **Input:** ```python theme={null} { "command": str, # Shell script; each stdout line is an event, exit ends the watch "description": str, # Short description shown in notifications "timeout_ms": int | None, # Kill after this deadline (default 300000, max 3600000) "persistent": bool | None, # Run for the lifetime of the session; stop with TaskStop } ``` **Output:** ```python theme={null} { "taskId": str, # ID of the background monitor task "timeoutMs": int, # Timeout deadline in milliseconds (0 when persistent) "persistent": bool | None, # True when running until TaskStop or session end } ``` ### Edit **Tool name:** `Edit` **Input:** ```python theme={null} { "file_path": str, # The absolute path to the file to modify "old_string": str, # The text to replace "new_string": str, # The text to replace it with "replace_all": bool | None, # Replace all occurrences (default False) } ``` **Output:** ```python theme={null} { "message": str, # Confirmation message "replacements": int, # Number of replacements made "file_path": str, # File path that was edited } ``` ### Read **Tool name:** `Read` **Input:** ```python theme={null} { "file_path": str, # The absolute path to the file to read "offset": int | None, # The line number to start reading from "limit": int | None, # The number of lines to read } ``` **Output (Text files):** ```python theme={null} { "content": str, # File contents with line numbers "total_lines": int, # Total number of lines in file "lines_returned": int, # Lines actually returned } ``` **Output (Images):** ```python theme={null} { "image": str, # Base64 encoded image data "mime_type": str, # Image MIME type "file_size": int, # File size in bytes } ``` ### Write **Tool name:** `Write` **Input:** ```python theme={null} { "file_path": str, # The absolute path to the file to write "content": str, # The content to write to the file } ``` **Output:** ```python theme={null} { "message": str, # Success message "bytes_written": int, # Number of bytes written "file_path": str, # File path that was written } ``` ### Glob **Tool name:** `Glob` **Input:** ```python theme={null} { "pattern": str, # The glob pattern to match files against "path": str | None, # The directory to search in (defaults to cwd) } ``` **Output:** ```python theme={null} { "matches": list[str], # Array of matching file paths "count": int, # Number of matches found "search_path": str, # Search directory used } ``` ### Grep **Tool name:** `Grep` **Input:** ```python theme={null} { "pattern": str, # The regular expression pattern "path": str | None, # File or directory to search in "glob": str | None, # Glob pattern to filter files "type": str | None, # File type to search "output_mode": str | None, # "content", "files_with_matches", or "count" "-i": bool | None, # Case insensitive search "-n": bool | None, # Show line numbers "-B": int | None, # Lines to show before each match "-A": int | None, # Lines to show after each match "-C": int | None, # Lines to show before and after "head_limit": int | None, # Limit output to first N lines/entries "multiline": bool | None, # Enable multiline mode } ``` **Output (content mode):** ```python theme={null} { "matches": [ { "file": str, "line_number": int | None, "line": str, "before_context": list[str] | None, "after_context": list[str] | None, } ], "total_matches": int, } ``` **Output (files\_with\_matches mode):** ```python theme={null} { "files": list[str], # Files containing matches "count": int, # Number of files with matches } ``` ### NotebookEdit **Tool name:** `NotebookEdit` **Input:** ```python theme={null} { "notebook_path": str, # Absolute path to the Jupyter notebook "cell_id": str | None, # The ID of the cell to edit "new_source": str, # The new source for the cell "cell_type": "code" | "markdown" | None, # The type of the cell "edit_mode": "replace" | "insert" | "delete" | None, # Edit operation type } ``` **Output:** ```python theme={null} { "message": str, # Success message "edit_type": "replaced" | "inserted" | "deleted", # Type of edit performed "cell_id": str | None, # Cell ID that was affected "total_cells": int, # Total cells in notebook after edit } ``` ### WebFetch **Tool name:** `WebFetch` **Input:** ```python theme={null} { "url": str, # The URL to fetch content from "prompt": str, # The prompt to run on the fetched content } ``` **Output:** ```python theme={null} { "response": str, # AI model's response to the prompt "url": str, # URL that was fetched "final_url": str | None, # Final URL after redirects "status_code": int | None, # HTTP status code } ``` ### WebSearch **Tool name:** `WebSearch` **Input:** ```python theme={null} { "query": str, # The search query to use "allowed_domains": list[str] | None, # Only include results from these domains "blocked_domains": list[str] | None, # Never include results from these domains } ``` **Output:** ```python theme={null} { "results": [{"title": str, "url": str, "snippet": str, "metadata": dict | None}], "total_results": int, "query": str, } ``` ### TodoWrite **Tool name:** `TodoWrite` **Input:** ```python theme={null} { "todos": [ { "content": str, # The task description "status": "pending" | "in_progress" | "completed", # Task status "activeForm": str, # Active form of the description } ] } ``` **Output:** ```python theme={null} { "message": str, # Success message "stats": {"total": int, "pending": int, "in_progress": int, "completed": int}, } ``` ### BashOutput **Tool name:** `BashOutput` **Input:** ```python theme={null} { "bash_id": str, # The ID of the background shell "filter": str | None, # Optional regex to filter output lines } ``` **Output:** ```python theme={null} { "output": str, # New output since last check "status": "running" | "completed" | "failed", # Current shell status "exitCode": int | None, # Exit code when completed } ``` ### KillBash **Tool name:** `KillBash` **Input:** ```python theme={null} { "shell_id": str # The ID of the background shell to kill } ``` **Output:** ```python theme={null} { "message": str, # Success message "shell_id": str, # ID of the killed shell } ``` ### ExitPlanMode **Tool name:** `ExitPlanMode` **Input:** ```python theme={null} { "plan": str # The plan to run by the user for approval } ``` **Output:** ```python theme={null} { "message": str, # Confirmation message "approved": bool | None, # Whether user approved the plan } ``` ### ListMcpResources **Tool name:** `ListMcpResources` **Input:** ```python theme={null} { "server": str | None # Optional server name to filter resources by } ``` **Output:** ```python theme={null} { "resources": [ { "uri": str, "name": str, "description": str | None, "mimeType": str | None, "server": str, } ], "total": int, } ``` ### ReadMcpResource **Tool name:** `ReadMcpResource` **Input:** ```python theme={null} { "server": str, # The MCP server name "uri": str, # The resource URI to read } ``` **Output:** ```python theme={null} { "contents": [ {"uri": str, "mimeType": str | None, "text": str | None, "blob": str | None} ], "server": str, } ``` ## Advanced Features with ClaudeSDKClient ### Building a Continuous Conversation Interface ```python theme={null} from claude_agent_sdk import ( ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock, ) import asyncio class ConversationSession: """Maintains a single conversation session with Claude.""" def __init__(self, options: ClaudeAgentOptions | None = None): self.client = ClaudeSDKClient(options) self.turn_count = 0 async def start(self): await self.client.connect() print("Starting conversation session. Claude will remember context.") print( "Commands: 'exit' to quit, 'interrupt' to stop current task, 'new' for new session" ) while True: user_input = input(f"\n[Turn {self.turn_count + 1}] You: ") if user_input.lower() == "exit": break elif user_input.lower() == "interrupt": await self.client.interrupt() print("Task interrupted!") continue elif user_input.lower() == "new": # Disconnect and reconnect for a fresh session await self.client.disconnect() await self.client.connect() self.turn_count = 0 print("Started new conversation session (previous context cleared)") continue # Send message - the session retains all previous messages await self.client.query(user_input) self.turn_count += 1 # Process response print(f"[Turn {self.turn_count}] Claude: ", end="") async for message in self.client.receive_response(): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(block.text, end="") print() # New line after response await self.client.disconnect() print(f"Conversation ended after {self.turn_count} turns.") async def main(): options = ClaudeAgentOptions( allowed_tools=["Read", "Write", "Bash"], permission_mode="acceptEdits" ) session = ConversationSession(options) await session.start() # Example conversation: # Turn 1 - You: "Create a file called hello.py" # Turn 1 - Claude: "I'll create a hello.py file for you..." # Turn 2 - You: "What's in that file?" # Turn 2 - Claude: "The hello.py file I just created contains..." (remembers!) # Turn 3 - You: "Add a main function to it" # Turn 3 - Claude: "I'll add a main function to hello.py..." (knows which file!) asyncio.run(main()) ``` ### Using Hooks for Behavior Modification ```python theme={null} from claude_agent_sdk import ( ClaudeSDKClient, ClaudeAgentOptions, HookMatcher, HookContext, ) import asyncio from typing import Any async def pre_tool_logger( input_data: dict[str, Any], tool_use_id: str | None, context: HookContext ) -> dict[str, Any]: """Log all tool usage before execution.""" tool_name = input_data.get("tool_name", "unknown") print(f"[PRE-TOOL] About to use: {tool_name}") # You can modify or block the tool execution here if tool_name == "Bash" and "rm -rf" in str(input_data.get("tool_input", {})): return { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Dangerous command blocked", } } return {} async def post_tool_logger( input_data: dict[str, Any], tool_use_id: str | None, context: HookContext ) -> dict[str, Any]: """Log results after tool execution.""" tool_name = input_data.get("tool_name", "unknown") print(f"[POST-TOOL] Completed: {tool_name}") return {} async def user_prompt_modifier( input_data: dict[str, Any], tool_use_id: str | None, context: HookContext ) -> dict[str, Any]: """Add context to user prompts.""" original_prompt = input_data.get("prompt", "") # Add a timestamp as additional context for Claude to see from datetime import datetime timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S") return { "hookSpecificOutput": { "hookEventName": "UserPromptSubmit", "additionalContext": f"[Submitted at {timestamp}] Original prompt: {original_prompt}", } } async def main(): options = ClaudeAgentOptions( hooks={ "PreToolUse": [ HookMatcher(hooks=[pre_tool_logger]), HookMatcher(matcher="Bash", hooks=[pre_tool_logger]), ], "PostToolUse": [HookMatcher(hooks=[post_tool_logger])], "UserPromptSubmit": [HookMatcher(hooks=[user_prompt_modifier])], }, allowed_tools=["Read", "Write", "Bash"], ) async with ClaudeSDKClient(options=options) as client: await client.query("List files in current directory") async for message in client.receive_response(): # Hooks will automatically log tool usage pass asyncio.run(main()) ``` ### Real-time Progress Monitoring ```python theme={null} from claude_agent_sdk import ( ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, ToolUseBlock, ToolResultBlock, TextBlock, ) import asyncio async def monitor_progress(): options = ClaudeAgentOptions( allowed_tools=["Write", "Bash"], permission_mode="acceptEdits" ) async with ClaudeSDKClient(options=options) as client: await client.query("Create 5 Python files with different sorting algorithms") # Monitor progress in real-time async for message in client.receive_response(): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, ToolUseBlock): if block.name == "Write": file_path = block.input.get("file_path", "") print(f"Creating: {file_path}") elif isinstance(block, ToolResultBlock): print("Completed tool execution") elif isinstance(block, TextBlock): print(f"Claude says: {block.text[:100]}...") print("Task completed!") asyncio.run(monitor_progress()) ``` ## Example Usage ### Basic file operations (using query) ```python theme={null} from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock import asyncio async def create_project(): options = ClaudeAgentOptions( allowed_tools=["Read", "Write", "Bash"], permission_mode="acceptEdits", cwd="/home/user/project", ) async for message in query( prompt="Create a Python project structure with setup.py", options=options ): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, ToolUseBlock): print(f"Using tool: {block.name}") asyncio.run(create_project()) ``` ### Error handling ```python theme={null} from claude_agent_sdk import query, CLINotFoundError, ProcessError, CLIJSONDecodeError try: async for message in query(prompt="Hello"): print(message) except CLINotFoundError: print( "Claude Code CLI not found. Try reinstalling: pip install --force-reinstall claude-agent-sdk" ) except ProcessError as e: print(f"Process failed with exit code: {e.exit_code}") except CLIJSONDecodeError as e: print(f"Failed to parse response: {e}") ``` ### Streaming mode with client ```python theme={null} from claude_agent_sdk import ClaudeSDKClient import asyncio async def interactive_session(): async with ClaudeSDKClient() as client: # Send initial message await client.query("What's the weather like?") # Process responses async for msg in client.receive_response(): print(msg) # Send follow-up await client.query("Tell me more about that") # Process follow-up response async for msg in client.receive_response(): print(msg) asyncio.run(interactive_session()) ``` ### Using custom tools with ClaudeSDKClient ```python theme={null} from claude_agent_sdk import ( ClaudeSDKClient, ClaudeAgentOptions, tool, create_sdk_mcp_server, AssistantMessage, TextBlock, ) import asyncio from typing import Any # Define custom tools with @tool decorator @tool("calculate", "Perform mathematical calculations", {"expression": str}) async def calculate(args: dict[str, Any]) -> dict[str, Any]: try: result = eval(args["expression"], {"__builtins__": {}}) return {"content": [{"type": "text", "text": f"Result: {result}"}]} except Exception as e: return { "content": [{"type": "text", "text": f"Error: {str(e)}"}], "is_error": True, } @tool("get_time", "Get current time", {}) async def get_time(args: dict[str, Any]) -> dict[str, Any]: from datetime import datetime current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S") return {"content": [{"type": "text", "text": f"Current time: {current_time}"}]} async def main(): # Create SDK MCP server with custom tools my_server = create_sdk_mcp_server( name="utilities", version="1.0.0", tools=[calculate, get_time] ) # Configure options with the server options = ClaudeAgentOptions( mcp_servers={"utils": my_server}, allowed_tools=["mcp__utils__calculate", "mcp__utils__get_time"], ) # Use ClaudeSDKClient for interactive tool usage async with ClaudeSDKClient(options=options) as client: await client.query("What's 123 * 456?") # Process calculation response async for message in client.receive_response(): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(f"Calculation: {block.text}") # Follow up with time query await client.query("What time is it now?") async for message in client.receive_response(): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(f"Time: {block.text}") asyncio.run(main()) ``` ## Sandbox Configuration ### `SandboxSettings` Configuration for sandbox behavior. Use this to enable command sandboxing and configure network restrictions programmatically. ```python theme={null} class SandboxSettings(TypedDict, total=False): enabled: bool autoAllowBashIfSandboxed: bool excludedCommands: list[str] allowUnsandboxedCommands: bool network: SandboxNetworkConfig ignoreViolations: SandboxIgnoreViolations enableWeakerNestedSandbox: bool ``` | Property | Type | Default | Description | | :-------------------------- | :------------------------------------------------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | `bool` | `False` | Enable sandbox mode for command execution | | `autoAllowBashIfSandboxed` | `bool` | `True` | Auto-approve bash commands when sandbox is enabled | | `excludedCommands` | `list[str]` | `[]` | Commands that always bypass sandbox restrictions (e.g., `["docker"]`). These run unsandboxed automatically without model involvement | | `allowUnsandboxedCommands` | `bool` | `True` | Allow the model to request running commands outside the sandbox. When `True`, the model can set `dangerouslyDisableSandbox` in tool input, which falls back to the [permissions system](#permissions-fallback-for-unsandboxed-commands) | | `network` | [`SandboxNetworkConfig`](#sandbox-network-config) | `None` | Network-specific sandbox configuration | | `ignoreViolations` | [`SandboxIgnoreViolations`](#sandbox-ignore-violations) | `None` | Configure which sandbox violations to ignore | | `enableWeakerNestedSandbox` | `bool` | `False` | Enable a weaker nested sandbox for compatibility | **Filesystem and network access restrictions** are NOT configured via sandbox settings. Instead, they are derived from [permission rules](/en/settings#permission-settings): * **Filesystem read restrictions**: Read deny rules * **Filesystem write restrictions**: Edit allow/deny rules * **Network restrictions**: WebFetch allow/deny rules Use sandbox settings for command execution sandboxing, and permission rules for filesystem and network access control. #### Example usage ```python theme={null} from claude_agent_sdk import query, ClaudeAgentOptions, SandboxSettings sandbox_settings: SandboxSettings = { "enabled": True, "autoAllowBashIfSandboxed": True, "network": {"allowLocalBinding": True}, } async for message in query( prompt="Build and test my project", options=ClaudeAgentOptions(sandbox=sandbox_settings), ): print(message) ``` **Unix socket security**: The `allowUnixSockets` option can grant access to powerful system services. For example, allowing `/var/run/docker.sock` effectively grants full host system access through the Docker API, bypassing sandbox isolation. Only allow Unix sockets that are strictly necessary and understand the security implications of each. ### `SandboxNetworkConfig` Network-specific configuration for sandbox mode. ```python theme={null} class SandboxNetworkConfig(TypedDict, total=False): allowLocalBinding: bool allowUnixSockets: list[str] allowAllUnixSockets: bool httpProxyPort: int socksProxyPort: int ``` | Property | Type | Default | Description | | :-------------------- | :---------- | :------ | :---------------------------------------------------------------- | | `allowLocalBinding` | `bool` | `False` | Allow processes to bind to local ports (e.g., for dev servers) | | `allowUnixSockets` | `list[str]` | `[]` | Unix socket paths that processes can access (e.g., Docker socket) | | `allowAllUnixSockets` | `bool` | `False` | Allow access to all Unix sockets | | `httpProxyPort` | `int` | `None` | HTTP proxy port for network requests | | `socksProxyPort` | `int` | `None` | SOCKS proxy port for network requests | ### `SandboxIgnoreViolations` Configuration for ignoring specific sandbox violations. ```python theme={null} class SandboxIgnoreViolations(TypedDict, total=False): file: list[str] network: list[str] ``` | Property | Type | Default | Description | | :-------- | :---------- | :------ | :------------------------------------------ | | `file` | `list[str]` | `[]` | File path patterns to ignore violations for | | `network` | `list[str]` | `[]` | Network patterns to ignore violations for | ### Permissions Fallback for Unsandboxed Commands When `allowUnsandboxedCommands` is enabled, the model can request to run commands outside the sandbox by setting `dangerouslyDisableSandbox: True` in the tool input. These requests fall back to the existing permissions system, meaning your `can_use_tool` handler will be invoked, allowing you to implement custom authorization logic. **`excludedCommands` vs `allowUnsandboxedCommands`:** * `excludedCommands`: A static list of commands that always bypass the sandbox automatically (e.g., `["docker"]`). The model has no control over this. * `allowUnsandboxedCommands`: Lets the model decide at runtime whether to request unsandboxed execution by setting `dangerouslyDisableSandbox: True` in the tool input. ```python theme={null} from claude_agent_sdk import ( query, ClaudeAgentOptions, HookMatcher, PermissionResultAllow, PermissionResultDeny, ToolPermissionContext, ) async def can_use_tool( tool: str, input: dict, context: ToolPermissionContext ) -> PermissionResultAllow | PermissionResultDeny: # Check if the model is requesting to bypass the sandbox if tool == "Bash" and input.get("dangerouslyDisableSandbox"): # The model is requesting to run this command outside the sandbox print(f"Unsandboxed command requested: {input.get('command')}") if is_command_authorized(input.get("command")): return PermissionResultAllow() return PermissionResultDeny( message="Command not authorized for unsandboxed execution" ) return PermissionResultAllow() # Required: dummy hook keeps the stream open for can_use_tool async def dummy_hook(input_data, tool_use_id, context): return {"continue_": True} async def prompt_stream(): yield { "type": "user", "message": {"role": "user", "content": "Deploy my application"}, } async def main(): async for message in query( prompt=prompt_stream(), options=ClaudeAgentOptions( sandbox={ "enabled": True, "allowUnsandboxedCommands": True, # Model can request unsandboxed execution }, permission_mode="default", can_use_tool=can_use_tool, hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]}, ), ): print(message) ``` This pattern enables you to: * **Audit model requests**: Log when the model requests unsandboxed execution * **Implement allowlists**: Only permit specific commands to run unsandboxed * **Add approval workflows**: Require explicit authorization for privileged operations Commands running with `dangerouslyDisableSandbox: True` have full system access. Ensure your `can_use_tool` handler validates these requests carefully. If `permission_mode` is set to `bypassPermissions` and `allow_unsandboxed_commands` is enabled, commands may run with reduced sandbox isolation. Review enterprise hardening guidance before enabling this combination. ## See also * [SDK overview](/en/agent-sdk/overview) - General SDK concepts * [TypeScript SDK reference](/en/agent-sdk/typescript) - TypeScript SDK documentation * [CLI reference](../02-Claude-Code-CLI/cli-reference-7bb98e3312.md) - Command-line interface * [Common workflows](../02-Claude-Code-CLI/common-workflows-c909406123.md) - Step-by-step guides --- ## agent-sdk-quickstart-2bc81ce92a.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Quickstart > Get started with the Python or TypeScript Agent SDK to build AI agents that work autonomously Use the Agent SDK to build an AI agent that reads your code, finds bugs, and fixes them, all without manual intervention. **What you'll do:** 1. Set up a project with the Agent SDK 2. Create a file with some buggy code 3. Run an agent that finds and fixes the bugs automatically ## Prerequisites * **Node.js 18+** or **Python 3.10+** * An **Anthropic account** ([sign up here](../04-API-Reference/Other/platform-claude-com.md)) ## Setup Create a new directory for this quickstart: ```bash theme={null} mkdir my-agent && cd my-agent ``` For your own projects, you can run the SDK from any folder; it will have access to files in that directory and its subdirectories by default. Install the Agent SDK package for your language: ```bash theme={null} npm install @anthropic-ai/claude-agent-sdk ``` [uv Python package manager](https://docs.astral.sh/uv/) is a fast Python package manager that handles virtual environments automatically: ```bash theme={null} uv init && uv add claude-agent-sdk ``` Create a virtual environment first, then install: ```bash theme={null} python3 -m venv .venv && source .venv/bin/activate pip3 install claude-agent-sdk ``` The TypeScript SDK bundles a native Claude Code binary for your platform as an optional dependency, so you don't need to install Claude Code separately. Get an API key from the [Claude Console](../04-API-Reference/Other/platform-claude-com.md), then create a `.env` file in your project directory: ```bash theme={null} ANTHROPIC_API_KEY=your-api-key ``` The SDK also supports authentication via third-party API providers: * **Amazon Bedrock**: set `CLAUDE_CODE_USE_BEDROCK=1` environment variable and configure AWS credentials * **Google Vertex AI**: set `CLAUDE_CODE_USE_VERTEX=1` environment variable and configure Google Cloud credentials * **Microsoft Azure**: set `CLAUDE_CODE_USE_FOUNDRY=1` environment variable and configure Azure credentials See the setup guides for [Bedrock](../20-Models/claude-code-on-amazon-bedrock-claude-code-docs-435e92efd0.md), [Vertex AI](../20-Models/claude-code-on-google-vertex-ai-claude-code-docs-2acd050a7a.md), or [Azure AI Foundry](../20-Models/claude-code-on-microsoft-foundry-claude-code-docs-ee35d755a6.md) for details. Unless previously approved, Anthropic does not allow third party developers to offer claude.ai login or rate limits for their products, including agents built on the Claude Agent SDK. Please use the API key authentication methods described in this document instead. ## Create a buggy file This quickstart walks you through building an agent that can find and fix bugs in code. First, you need a file with some intentional bugs for the agent to fix. Create `utils.py` in the `my-agent` directory and paste the following code: ```python theme={null} def calculate_average(numbers): total = 0 for num in numbers: total += num return total / len(numbers) def get_user_name(user): return user["name"].upper() ``` This code has two bugs: 1. `calculate_average([])` crashes with division by zero 2. `get_user_name(None)` crashes with a TypeError ## Build an agent that finds and fixes bugs Create `agent.py` if you're using the Python SDK, or `agent.ts` for TypeScript: ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage async def main(): # Agentic loop: streams messages as Claude works async for message in query( prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.", options=ClaudeAgentOptions( allowed_tools=["Read", "Edit", "Glob"], # Tools Claude can use permission_mode="acceptEdits", # Auto-approve file edits ), ): # Print human-readable output if isinstance(message, AssistantMessage): for block in message.content: if hasattr(block, "text"): print(block.text) # Claude's reasoning elif hasattr(block, "name"): print(f"Tool: {block.name}") # Tool being called elif isinstance(message, ResultMessage): print(f"Done: {message.subtype}") # Final result asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; // Agentic loop: streams messages as Claude works for await (const message of query({ prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.", options: { allowedTools: ["Read", "Edit", "Glob"], // Tools Claude can use permissionMode: "acceptEdits" // Auto-approve file edits } })) { // Print human-readable output if (message.type === "assistant" && message.message?.content) { for (const block of message.message.content) { if ("text" in block) { console.log(block.text); // Claude's reasoning } else if ("name" in block) { console.log(`Tool: ${block.name}`); // Tool being called } } } else if (message.type === "result") { console.log(`Done: ${message.subtype}`); // Final result } } ``` This code has three main parts: 1. **`query`**: the main entry point that creates the agentic loop. It returns an async iterator, so you use `async for` to stream messages as Claude works. See the full API in the [Python](/en/agent-sdk/python#query) or [TypeScript](/en/agent-sdk/typescript#query) SDK reference. 2. **`prompt`**: what you want Claude to do. Claude figures out which tools to use based on the task. 3. **`options`**: configuration for the agent. This example uses `allowedTools` to pre-approve `Read`, `Edit`, and `Glob`, and `permissionMode: "acceptEdits"` to auto-approve file changes. Other options include `systemPrompt`, `mcpServers`, and more. See all options for [Python](/en/agent-sdk/python#claude-agent-options) or [TypeScript](/en/agent-sdk/typescript#options). The `async for` loop keeps running as Claude thinks, calls tools, observes results, and decides what to do next. Each iteration yields a message: Claude's reasoning, a tool call, a tool result, or the final outcome. The SDK handles the orchestration (tool execution, context management, retries) so you just consume the stream. The loop ends when Claude finishes the task or hits an error. The message handling inside the loop filters for human-readable output. Without filtering, you'd see raw message objects including system initialization and internal state, which is useful for debugging but noisy otherwise. This example uses streaming to show progress in real-time. If you don't need live output (e.g., for background jobs or CI pipelines), you can collect all messages at once. See [Streaming vs. single-turn mode](/en/agent-sdk/streaming-vs-single-mode) for details. ### Run your agent Your agent is ready. Run it with the following command: ```bash theme={null} python3 agent.py ``` ```bash theme={null} npx tsx agent.ts ``` After running, check `utils.py`. You'll see defensive code handling empty lists and null users. Your agent autonomously: 1. **Read** `utils.py` to understand the code 2. **Analyzed** the logic and identified edge cases that would crash 3. **Edited** the file to add proper error handling This is what makes the Agent SDK different: Claude executes tools directly instead of asking you to implement them. If you see "API key not found", make sure you've set the `ANTHROPIC_API_KEY` environment variable in your `.env` file or shell environment. See the [full troubleshooting guide](../21-Account-Support/troubleshooting-claude-code-docs-3f3657ed0f.md) for more help. ### Try other prompts Now that your agent is set up, try some different prompts: * `"Add docstrings to all functions in utils.py"` * `"Add type hints to all functions in utils.py"` * `"Create a README.md documenting the functions in utils.py"` ### Customize your agent You can modify your agent's behavior by changing the options. Here are a few examples: **Add web search capability:** ```python Python theme={null} options = ClaudeAgentOptions( allowed_tools=["Read", "Edit", "Glob", "WebSearch"], permission_mode="acceptEdits" ) ``` ```typescript TypeScript hidelines={1,-1} theme={null} const _ = { options: { allowedTools: ["Read", "Edit", "Glob", "WebSearch"], permissionMode: "acceptEdits" } }; ``` **Give Claude a custom system prompt:** ```python Python theme={null} options = ClaudeAgentOptions( allowed_tools=["Read", "Edit", "Glob"], permission_mode="acceptEdits", system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.", ) ``` ```typescript TypeScript hidelines={1,-1} theme={null} const _ = { options: { allowedTools: ["Read", "Edit", "Glob"], permissionMode: "acceptEdits", systemPrompt: "You are a senior Python developer. Always follow PEP 8 style guidelines." } }; ``` **Run commands in the terminal:** ```python Python theme={null} options = ClaudeAgentOptions( allowed_tools=["Read", "Edit", "Glob", "Bash"], permission_mode="acceptEdits" ) ``` ```typescript TypeScript hidelines={1,-1} theme={null} const _ = { options: { allowedTools: ["Read", "Edit", "Glob", "Bash"], permissionMode: "acceptEdits" } }; ``` With `Bash` enabled, try: `"Write unit tests for utils.py, run them, and fix any failures"` ## Key concepts **Tools** control what your agent can do: | Tools | What the agent can do | | -------------------------------------- | ----------------------- | | `Read`, `Glob`, `Grep` | Read-only analysis | | `Read`, `Edit`, `Glob` | Analyze and modify code | | `Read`, `Edit`, `Bash`, `Glob`, `Grep` | Full automation | **Permission modes** control how much human oversight you want: | Mode | Behavior | Use case | | ------------------------ | ------------------------------------------------------------------------------- | ---------------------------------------- | | `acceptEdits` | Auto-approves file edits and common filesystem commands, asks for other actions | Trusted development workflows | | `dontAsk` | Denies anything not in `allowedTools` | Locked-down headless agents | | `auto` (TypeScript only) | A model classifier approves or denies each tool call | Autonomous agents with safety guardrails | | `bypassPermissions` | Runs every tool without prompts | Sandboxed CI, fully trusted environments | | `default` | Requires a `canUseTool` callback to handle approval | Custom approval flows | The example above uses `acceptEdits` mode, which auto-approves file operations so the agent can run without interactive prompts. If you want to prompt users for approval, use `default` mode and provide a [`canUseTool` callback](/en/agent-sdk/user-input) that collects user input. For more control, see [Permissions](/en/agent-sdk/permissions). ## Troubleshooting ### API error `thinking.type.enabled` is not supported for this model Claude Opus 4.7 replaces `thinking.type.enabled` with `thinking.type.adaptive`. Older Agent SDK versions fail with the following API error when you select `claude-opus-4-7`: ```text theme={null} API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior."} ``` Upgrade to Agent SDK v0.2.111 or later to use Opus 4.7. ## Next steps Now that you've created your first agent, learn how to extend its capabilities and tailor it to your use case: * **[Permissions](/en/agent-sdk/permissions)**: control what your agent can do and when it needs approval * **[Hooks](/en/agent-sdk/hooks)**: run custom code before or after tool calls * **[Sessions](/en/agent-sdk/sessions)**: build multi-turn agents that maintain context * **[MCP servers](/en/agent-sdk/mcp)**: connect to databases, browsers, APIs, and other external systems * **[Hosting](/en/agent-sdk/hosting)**: deploy agents to Docker, cloud, and CI/CD * **[Example agents](https://github.com/anthropics/claude-agent-sdk-demos)**: see complete examples: email assistant, research agent, and more --- ## agent-sdk-reference-python-claude-code-docs-2aa41a0f51.md ## On this page - [Installation](#installation) - [Choosing between query() and ClaudeSDKClient](#choosing-between-query-and-claudesdkclient) - [Quick comparison](#quick-comparison) - [When to use query() (one-off tasks)](#when-to-use-query-one-off-tasks) - [When to use ClaudeSDKClient (continuous conversation)](#when-to-use-claudesdkclient-continuous-conversation) - [Functions](#functions) - [query()](#query) - [Parameters](#parameters) - [Returns](#returns) - [Example - With options](#example-with-options) - [tool()](#tool) - [Parameters](#parameters-2) - [Input schema options](#input-schema-options) - [Returns](#returns-2) - [Example](#example) - [ToolAnnotations](#toolannotations) - [create_sdk_mcp_server()](#create_sdk_mcp_server) - [Parameters](#parameters-3) - [Returns](#returns-3) - [Example](#example-2) - [list_sessions()](#list_sessions) - [Parameters](#parameters-4) - [Return type: SDKSessionInfo](#return-type-sdksessioninfo) - [Example](#example-3) - [get_session_messages()](#get_session_messages) - [Parameters](#parameters-5) - [Return type: SessionMessage](#return-type-sessionmessage) - [Example](#example-4) - [get_session_info()](#get_session_info) - [Parameters](#parameters-6) - [Example](#example-5) - [rename_session()](#rename_session) - [Parameters](#parameters-7) - [Example](#example-6) - [tag_session()](#tag_session) - [Parameters](#parameters-8) - [Example](#example-7) - [Classes](#classes) - [ClaudeSDKClient](#claudesdkclient) - [Key Features](#key-features) - [Methods](#methods) - [Context Manager Support](#context-manager-support) - [Example - Continuing a conversation](#example-continuing-a-conversation) - [Example - Streaming input with ClaudeSDKClient](#example-streaming-input-with-claudesdkclient) - [Example - Using interrupts](#example-using-interrupts) - [Example - Advanced permission control](#example-advanced-permission-control) - [Types](#types) - [SdkMcpTool](#sdkmcptool) - [Transport](#transport) - [ClaudeAgentOptions](#claudeagentoptions) - [Handle slow or stalled API responses](#handle-slow-or-stalled-api-responses) - [OutputFormat](#outputformat) - [SystemPromptPreset](#systempromptpreset) - [SystemPromptFile](#systempromptfile) - [SettingSource](#settingsource) - [Default behavior](#default-behavior) - [Why use setting_sources](#why-use-setting_sources) - [Settings precedence](#settings-precedence) - [AgentDefinition](#agentdefinition) - [PermissionMode](#permissionmode) - [EffortLevel](#effortlevel) - [CanUseTool](#canusetool) - [ToolPermissionContext](#toolpermissioncontext) - [PermissionResult](#permissionresult) - [PermissionResultAllow](#permissionresultallow) - [PermissionResultDeny](#permissionresultdeny) - [PermissionUpdate](#permissionupdate) - [PermissionRuleValue](#permissionrulevalue) - [ToolsPreset](#toolspreset) - [ThinkingConfig](#thinkingconfig) - [TaskBudget](#taskbudget) - [SdkBeta](#sdkbeta) - [McpSdkServerConfig](#mcpsdkserverconfig) - [McpServerConfig](#mcpserverconfig) - [McpStdioServerConfig](#mcpstdioserverconfig) - [McpSSEServerConfig](#mcpsseserverconfig) - [McpHttpServerConfig](#mcphttpserverconfig) - [McpServerStatusConfig](#mcpserverstatusconfig) - [McpStatusResponse](#mcpstatusresponse) - [McpServerStatus](#mcpserverstatus) - [SdkPluginConfig](#sdkpluginconfig) - [Message Types](#message-types) - [Message](#message) - [UserMessage](#usermessage) - [AssistantMessage](#assistantmessage) - [AssistantMessageError](#assistantmessageerror) - [SystemMessage](#systemmessage) - [ResultMessage](#resultmessage) - [StreamEvent](#streamevent) - [RateLimitEvent](#ratelimitevent) - [RateLimitInfo](#ratelimitinfo) - [TaskStartedMessage](#taskstartedmessage) - [TaskUsage](#taskusage) - [TaskProgressMessage](#taskprogressmessage) - [TaskNotificationMessage](#tasknotificationmessage) - [Content Block Types](#content-block-types) - [ContentBlock](#contentblock) - [TextBlock](#textblock) - [ThinkingBlock](#thinkingblock) - [ToolUseBlock](#tooluseblock) - [ToolResultBlock](#toolresultblock) - [Error Types](#error-types) - [ClaudeSDKError](#claudesdkerror) - [CLINotFoundError](#clinotfounderror) - [CLIConnectionError](#cliconnectionerror) - [ProcessError](#processerror) - [CLIJSONDecodeError](#clijsondecodeerror) - [Hook Types](#hook-types) - [HookEvent](#hookevent) - [HookCallback](#hookcallback) - [HookContext](#hookcontext) - [HookMatcher](#hookmatcher) - [HookInput](#hookinput) - [BaseHookInput](#basehookinput) - [PreToolUseHookInput](#pretoolusehookinput) - [PostToolUseHookInput](#posttoolusehookinput) - [PostToolUseFailureHookInput](#posttoolusefailurehookinput) - [UserPromptSubmitHookInput](#userpromptsubmithookinput) - [StopHookInput](#stophookinput) - [SubagentStopHookInput](#subagentstophookinput) - [PreCompactHookInput](#precompacthookinput) - [NotificationHookInput](#notificationhookinput) - [SubagentStartHookInput](#subagentstarthookinput) - [PermissionRequestHookInput](#permissionrequesthookinput) - [HookJSONOutput](#hookjsonoutput) - [SyncHookJSONOutput](#synchookjsonoutput) - [HookSpecificOutput](#hookspecificoutput) - [AsyncHookJSONOutput](#asynchookjsonoutput) - [Hook Usage Example](#hook-usage-example) - [Tool Input/Output Types](#tool-input%2Foutput-types) - [Agent](#agent) - [AskUserQuestion](#askuserquestion) - [Bash](#bash) - [Monitor](#monitor) - [Edit](#edit) - [Read](#read) - [Write](#write) - [Glob](#glob) - [Grep](#grep) - [NotebookEdit](#notebookedit) - [WebFetch](#webfetch) - [WebSearch](#websearch) - [TodoWrite](#todowrite) - [TaskCreate](#taskcreate) - [TaskUpdate](#taskupdate) - [TaskGet](#taskget) - [TaskList](#tasklist) - [TaskOutput](#taskoutput) - [TaskStop](#taskstop) - [ExitPlanMode](#exitplanmode) - [ListMcpResources](#listmcpresources) - [ReadMcpResource](#readmcpresource) - [Advanced Features with ClaudeSDKClient](#advanced-features-with-claudesdkclient) - [Building a Continuous Conversation Interface](#building-a-continuous-conversation-interface) - [Using Hooks for Behavior Modification](#using-hooks-for-behavior-modification) - [Real-time Progress Monitoring](#real-time-progress-monitoring) - [Example Usage](#example-usage) - [Basic file operations (using query)](#basic-file-operations-using-query) - [Error handling](#error-handling) - [Streaming mode with client](#streaming-mode-with-client) - [Using custom tools with ClaudeSDKClient](#using-custom-tools-with-claudesdkclient) - [Sandbox Configuration](#sandbox-configuration) - [SandboxSettings](#sandboxsettings) - [Example usage](#example-usage-2) - [SandboxNetworkConfig](#sandboxnetworkconfig) - [SandboxIgnoreViolations](#sandboxignoreviolations) - [Permissions Fallback for Unsandboxed Commands](#permissions-fallback-for-unsandboxed-commands) - [See also](#see-also) SDK references # Agent SDK reference - Python Copy pageCopy page Complete API reference for the Python Agent SDK, including all functions, types, and classes. Copy pageCopy page [​](#installation) Installation Install the package into a virtual environment. On recent Debian, Ubuntu, and Homebrew Python installs, running `pip install` against system Python fails with `error: externally-managed-environment`. ```python python3 -m venv .venv source .venv/bin/activate pip install claude-agent-sdk ``` For uv, Windows PowerShell, and API key setup, see [Setup in the Agent SDK quickstart](/docs/en/agent-sdk/quickstart#setup). [​](#choosing-between-query-and-claudesdkclient) Choosing between `query()` and `ClaudeSDKClient` The Python SDK provides two ways to interact with Claude Code: [​](#quick-comparison) Quick comparison | Feature | `query()` | `ClaudeSDKClient` | |:--------------------|:-----------------------------------------------|:-----------------------------------| | **Session** | Creates a new session by default | Reuses same session | | **Conversation** | Single exchange | Multiple exchanges in same context | | **Connection** | Managed automatically | Manual control | | **Streaming Input** | ✅ Supported | ✅ Supported | | **Interrupts** | ❌ Not supported | ✅ Supported | | **Hooks** | ✅ Supported | ✅ Supported | | **Custom Tools** | ✅ Supported | ✅ Supported | | **Continue Chat** | Manual via `continue_conversation` or `resume` | ✅ Automatic | | **Use Case** | One-off tasks | Continuous conversations | [​](#when-to-use-query-one-off-tasks) When to use `query()` (one-off tasks) **Best for:** - One-off questions where you don’t need conversation history - Independent tasks that don’t require context from previous exchanges - Simple automation scripts - When you want a fresh start each time [​](#when-to-use-claudesdkclient-continuous-conversation) When to use `ClaudeSDKClient` (continuous conversation) **Best for:** - **Continuing conversations** - When you need Claude to remember context - **Follow-up questions** - Building on previous responses - **Interactive applications** - Chat interfaces, REPLs - **Response-driven logic** - When next action depends on Claude’s response - **Session control** - Managing conversation lifecycle explicitly [​](#functions) Functions Signature blocks and bare `async for` / `async with` fragments on this page are illustrative. To run them, wrap the body in `async def main(): ...` and call `asyncio.run(main())`. [​](#query) `query()` Creates a new session for each interaction with Claude Code by default. Returns an async iterator that yields messages as they arrive. Each call to `query()` starts fresh with no memory of previous interactions unless you pass `continue_conversation=True` or `resume` in [`ClaudeAgentOptions`](#claudeagentoptions). See [Sessions](/docs/en/agent-sdk/sessions). ```python async def query( *, prompt: str | AsyncIterable[dict[str, Any]], options: ClaudeAgentOptions | None = None, transport: Transport | None = None ) -> AsyncIterator[Message] ``` [​](#parameters) Parameters | Parameter | Type | Description | |:------------|:----------------------------|:---------------------------------------------------------------------------| | `prompt` | `str | AsyncIterable[dict]` | The input prompt as a string or async iterable for streaming mode | | `options` | `ClaudeAgentOptions | None` | Optional configuration object (defaults to `ClaudeAgentOptions()` if None) | | `transport` | `Transport | None` | Optional custom transport for communicating with the CLI process | [​](#returns) Returns Returns an `AsyncIterator[Message]` that yields messages from the conversation. [​](#example-with-options) Example - With options ```python import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): options = ClaudeAgentOptions( system_prompt="You are an expert Python developer", permission_mode="acceptEdits", ) async for message in query(prompt="Create a Python web server", options=options): print(message) asyncio.run(main()) ``` [​](#tool) `tool()` Decorator for defining MCP tools with type safety. ```python def tool( name: str, description: str, input_schema: type | dict[str, Any], annotations: ToolAnnotations | None = None ) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]] ``` [​](#parameters-2) Parameters | Parameter | Type | Description | |:---------------|:-----------------------------------------------|:--------------------------------------------------------------------| | `name` | `str` | Unique identifier for the tool | | `description` | `str` | Human-readable description of what the tool does | | `input_schema` | `type | dict[str, Any]` | Schema defining the tool’s input parameters (see below) | | `annotations` | [`ToolAnnotations`](#toolannotations)` | None` | Optional MCP tool annotations providing behavioral hints to clients | [​](#input-schema-options) Input schema options 1. **Simple type mapping** (recommended): ``` shiki {"text": str, "count": int, "enabled": bool} ``` 2. **JSON Schema format** (for complex validation): ``` shiki { "type": "object", "properties": { "text": {"type": "string"}, "count": {"type": "integer", "minimum": 0}, }, "required": ["text"], } ``` [​](#returns-2) Returns A decorator function that wraps the tool implementation and returns an `SdkMcpTool` instance. [​](#example) Example ```python from claude_agent_sdk import tool from typing import Any @tool("greet", "Greet a user", {"name": str}) async def greet(args: dict[str, Any]) -> dict[str, Any]: return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]} ``` [​](#toolannotations) `ToolAnnotations` Re-exported from `mcp.types` (also available as `from claude_agent_sdk import ToolAnnotations`). All fields are optional hints; clients should not rely on them for security decisions. | Field | Type | Default | Description | |:------------------|:--------------|:--------|:-----------------------------------------------------------------------------------------------------------------------------------------------------| | `title` | `str | None` | `None` | Human-readable title for the tool | | `readOnlyHint` | `bool | None` | `False` | If `True`, the tool does not modify its environment | | `destructiveHint` | `bool | None` | `True` | If `True`, the tool may perform destructive updates (only meaningful when `readOnlyHint` is `False`) | | `idempotentHint` | `bool | None` | `False` | If `True`, repeated calls with the same arguments have no additional effect (only meaningful when `readOnlyHint` is `False`) | | `openWorldHint` | `bool | None` | `True` | If `True`, the tool interacts with external entities (for example, web search). If `False`, the tool’s domain is closed (for example, a memory tool) | ```python from claude_agent_sdk import tool, ToolAnnotations from typing import Any @tool( "search", "Search the web", {"query": str}, annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True), ) async def search(args: dict[str, Any]) -> dict[str, Any]: return {"content": [{"type": "text", "text": f"Results for: {args['query']}"}]} ``` [​](#create_sdk_mcp_server) `create_sdk_mcp_server()` Create an in-process MCP server that runs within your Python application. ```python def create_sdk_mcp_server( name: str, version: str = "1.0.0", tools: list[SdkMcpTool[Any]] | None = None ) -> McpSdkServerConfig ``` [​](#parameters-3) Parameters | Parameter | Type | Default | Description | |:----------|:-------------------------------|:----------|:------------------------------------------------------| | `name` | `str` | \- | Unique identifier for the server | | `version` | `str` | `"1.0.0"` | Server version string | | `tools` | `list[SdkMcpTool[Any]] | None` | `None` | List of tool functions created with `@tool` decorator | [​](#returns-3) Returns Returns an `McpSdkServerConfig` object that can be passed to `ClaudeAgentOptions.mcp_servers`. [​](#example-2) Example ```python from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions @tool("add", "Add two numbers", {"a": float, "b": float}) async def add(args): return {"content": [{"type": "text", "text": f"Sum: {args['a'] + args['b']}"}]} @tool("multiply", "Multiply two numbers", {"a": float, "b": float}) async def multiply(args): return {"content": [{"type": "text", "text": f"Product: {args['a'] * args['b']}"}]} calculator = create_sdk_mcp_server( name="calculator", version="2.0.0", tools=[add, multiply], # Pass decorated functions ) # Use with Claude options = ClaudeAgentOptions( mcp_servers={"calc": calculator}, allowed_tools=["mcp__calc__add", "mcp__calc__multiply"], ) ``` [​](#list_sessions) `list_sessions()` Lists past sessions with metadata. Filter by project directory or list sessions across all projects. Synchronous; returns immediately. ```python def list_sessions( directory: str | None = None, limit: int | None = None, offset: int = 0, include_worktrees: bool = True ) -> list[SDKSessionInfo] ``` [​](#parameters-4) Parameters | Parameter | Type | Default | Description | |:--------------------|:-------------|:--------|:-------------------------------------------------------------------------------------------------| | `directory` | `str | None` | `None` | Directory to list sessions for. When omitted, returns sessions across all projects | | `limit` | `int | None` | `None` | Maximum number of sessions to return | | `offset` | `int` | `0` | Number of sessions to skip from the start of the sorted results. Use with `limit` for pagination | | `include_worktrees` | `bool` | `True` | When `directory` is inside a git repository, include sessions from all worktree paths | [​](#return-type-sdksessioninfo) Return type: `SDKSessionInfo` | Property | Type | Description | |:----------------|:-------------|:---------------------------------------------------------------------| | `session_id` | `str` | Unique session identifier | | `summary` | `str` | Display title: custom title, auto-generated summary, or first prompt | | `last_modified` | `int` | Last modified time in milliseconds since epoch | | `file_size` | `int | None` | Session file size in bytes (`None` for remote storage backends) | | `custom_title` | `str | None` | User-set session title | | `first_prompt` | `str | None` | First meaningful user prompt in the session | | `git_branch` | `str | None` | Git branch at the end of the session | | `cwd` | `str | None` | Working directory for the session | | `tag` | `str | None` | User-set session tag (see [`tag_session()`](#tag_session)) | | `created_at` | `int | None` | Session creation time in milliseconds since epoch | [​](#example-3) Example Print the 10 most recent sessions for a project. Results are sorted by `last_modified` descending, so the first item is the newest. Omit `directory` to search across all projects. ```python from claude_agent_sdk import list_sessions for session in list_sessions(directory="/path/to/project", limit=10): print(f"{session.summary} ({session.session_id})") ``` [​](#get_session_messages) `get_session_messages()` Retrieves messages from a past session. Synchronous; returns immediately. ```python def get_session_messages( session_id: str, directory: str | None = None, limit: int | None = None, offset: int = 0 ) -> list[SessionMessage] ``` [​](#parameters-5) Parameters | Parameter | Type | Default | Description | |:-------------|:-------------|:---------|:------------------------------------------------------------------| | `session_id` | `str` | required | The session ID to retrieve messages for | | `directory` | `str | None` | `None` | Project directory to look in. When omitted, searches all projects | | `limit` | `int | None` | `None` | Maximum number of messages to return | | `offset` | `int` | `0` | Number of messages to skip from the start | [​](#return-type-sessionmessage) Return type: `SessionMessage` | Property | Type | Description | |:---------------------|:-------------------------------|:--------------------------| | `type` | `Literal["user", "assistant"]` | Message role | | `uuid` | `str` | Unique message identifier | | `session_id` | `str` | Session identifier | | `message` | `Any` | Raw message content | | `parent_tool_use_id` | `None` | Reserved for future use | [​](#example-4) Example ```python from claude_agent_sdk import list_sessions, get_session_messages sessions = list_sessions(limit=1) if sessions: messages = get_session_messages(sessions[0].session_id) for msg in messages: print(f"[{msg.type}] {msg.uuid}") ``` [​](#get_session_info) `get_session_info()` Reads metadata for a single session by ID without scanning the full project directory. Synchronous; returns immediately. ```python def get_session_info( session_id: str, directory: str | None = None, ) -> SDKSessionInfo | None ``` [​](#parameters-6) Parameters | Parameter | Type | Default | Description | |:-------------|:-------------|:---------|:-----------------------------------------------------------------------| | `session_id` | `str` | required | UUID of the session to look up | | `directory` | `str | None` | `None` | Project directory path. When omitted, searches all project directories | Returns [`SDKSessionInfo`](#return-type-sdksessioninfo), or `None` if the session is not found. [​](#example-5) Example Look up a single session’s metadata without scanning the project directory. Useful when you already have a session ID from a previous run. ```python from claude_agent_sdk import get_session_info info = get_session_info("550e8400-e29b-41d4-a716-446655440000") if info: print(f"{info.summary} (branch: {info.git_branch}, tag: {info.tag})") ``` [​](#rename_session) `rename_session()` Renames a session by appending a custom-title entry. Repeated calls are safe; the most recent title wins. Synchronous. ```python def rename_session( session_id: str, title: str, directory: str | None = None, ) -> None ``` [​](#parameters-7) Parameters | Parameter | Type | Default | Description | |:-------------|:-------------|:---------|:-----------------------------------------------------------------------| | `session_id` | `str` | required | UUID of the session to rename | | `title` | `str` | required | New title. Must be non-empty after stripping whitespace | | `directory` | `str | None` | `None` | Project directory path. When omitted, searches all project directories | Raises `ValueError` if `session_id` is not a valid UUID or `title` is empty; `FileNotFoundError` if the session cannot be found. [​](#example-6) Example Rename the most recent session so it’s easier to find later. The new title appears in [`SDKSessionInfo.custom_title`](#return-type-sdksessioninfo) on subsequent reads. ```python from claude_agent_sdk import list_sessions, rename_session sessions = list_sessions(directory="/path/to/project", limit=1) if sessions: rename_session(sessions[0].session_id, "Refactor auth module") ``` [​](#tag_session) `tag_session()` Tags a session. Pass `None` to clear the tag. Repeated calls are safe; the most recent tag wins. Synchronous. ```python def tag_session( session_id: str, tag: str | None, directory: str | None = None, ) -> None ``` [​](#parameters-8) Parameters | Parameter | Type | Default | Description | |:-------------|:-------------|:---------|:-----------------------------------------------------------------------| | `session_id` | `str` | required | UUID of the session to tag | | `tag` | `str | None` | required | Tag string, or `None` to clear. Unicode-sanitized before storing | | `directory` | `str | None` | `None` | Project directory path. When omitted, searches all project directories | Raises `ValueError` if `session_id` is not a valid UUID or `tag` is empty after sanitization; `FileNotFoundError` if the session cannot be found. [​](#example-7) Example Tag a session, then filter by that tag on a later read. Pass `None` to clear an existing tag. ```python from claude_agent_sdk import list_sessions, tag_session # Tag the most recent session sessions = list_sessions(directory="/path/to/project", limit=1) if sessions: tag_session(sessions[0].session_id, "needs-review") # Later: find all sessions with that tag for session in list_sessions(directory="/path/to/project"): if session.tag == "needs-review": print(session.summary) ``` [​](#classes) Classes [​](#claudesdkclient) `ClaudeSDKClient` **Maintains a conversation session across multiple exchanges.** This is the Python equivalent of how the TypeScript SDK’s `query()` function works internally - it creates a client object that can continue conversations. [​](#key-features) Key Features - **Session continuity**: Maintains conversation context across multiple `query()` calls - **Same conversation**: The session retains previous messages - **Interrupt support**: Can stop execution mid-task - **Explicit lifecycle**: You control when the session starts and ends - **Response-driven flow**: Can react to responses and send follow-ups - **Custom tools and hooks**: Supports custom tools (created with `@tool` decorator) and hooks ```python class ClaudeSDKClient: def __init__(self, options: ClaudeAgentOptions | None = None, transport: Transport | None = None) async def connect(self, prompt: str | AsyncIterable[dict] | None = None) -> None async def query(self, prompt: str | AsyncIterable[dict], session_id: str = "default") -> None async def receive_messages(self) -> AsyncIterator[Message] async def receive_response(self) -> AsyncIterator[Message] async def interrupt(self) -> None async def set_permission_mode(self, mode: str) -> None async def set_model(self, model: str | None = None) -> None async def rewind_files(self, user_message_id: str) -> None async def get_mcp_status(self) -> McpStatusResponse async def reconnect_mcp_server(self, server_name: str) -> None async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None async def stop_task(self, task_id: str) -> None async def get_server_info(self) -> dict[str, Any] | None async def disconnect(self) -> None ``` [​](#methods) Methods | Method | Description | |:------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `__init__(options)` | Initialize the client with optional configuration | | `connect(prompt)` | Connect to Claude with an optional initial prompt or message stream | | `query(prompt, session_id)` | Send a new request in streaming mode | | `receive_messages()` | Receive all messages from Claude as an async iterator | | `receive_response()` | Receive messages until and including a ResultMessage | | `interrupt()` | Send interrupt signal (only works in streaming mode) | | `set_permission_mode(mode)` | Change the permission mode for the current session | | `set_model(model)` | Change the model for the current session. Pass `None` to reset to default | | `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) | | `get_mcp_status()` | Get the status of all configured MCP servers. Returns [`McpStatusResponse`](#mcpstatusresponse) | | `reconnect_mcp_server(server_name)` | Retry connecting to an MCP server that failed or was disconnected | | `toggle_mcp_server(server_name, enabled)` | Enable or disable an MCP server mid-session. Disabling removes its tools | | `stop_task(task_id)` | Stop a running background task. A [`TaskNotificationMessage`](#tasknotificationmessage) with status `"stopped"` follows in the message stream | | `get_server_info()` | Get server information including session ID and capabilities | | `disconnect()` | Disconnect from Claude | [​](#context-manager-support) Context Manager Support The client can be used as an async context manager for automatic connection management: ```python import asyncio from claude_agent_sdk import ClaudeSDKClient async def main(): async with ClaudeSDKClient() as client: await client.query("Hello Claude") async for message in client.receive_response(): print(message) asyncio.run(main()) ``` > **Important:** When iterating over messages, avoid using `break` to exit early as this can cause asyncio cleanup issues. Instead, let the iteration complete naturally or use flags to track when you’ve found what you need. [​](#example-continuing-a-conversation) Example - Continuing a conversation ```python import asyncio from claude_agent_sdk import ClaudeSDKClient, AssistantMessage, TextBlock, ResultMessage async def main(): async with ClaudeSDKClient() as client: # First question await client.query("What's the capital of France?") # Process response async for message in client.receive_response(): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(f"Claude: {block.text}") # Follow-up question - the session retains the previous context await client.query("What's the population of that city?") async for message in client.receive_response(): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(f"Claude: {block.text}") # Another follow-up - still in the same conversation await client.query("What are some famous landmarks there?") async for message in client.receive_response(): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(f"Claude: {block.text}") asyncio.run(main()) ``` [​](#example-streaming-input-with-claudesdkclient) Example - Streaming input with ClaudeSDKClient ```python import asyncio from claude_agent_sdk import ClaudeSDKClient async def message_stream(): """Generate messages dynamically.""" yield { "type": "user", "message": {"role": "user", "content": "Analyze the following data:"}, } await asyncio.sleep(0.5) yield { "type": "user", "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"}, } await asyncio.sleep(0.5) yield { "type": "user", "message": {"role": "user", "content": "What patterns do you see?"}, } async def main(): async with ClaudeSDKClient() as client: # Stream input to Claude await client.query(message_stream()) # Process response async for message in client.receive_response(): print(message) # Follow-up in same session await client.query("Should we be concerned about these readings?") async for message in client.receive_response(): print(message) asyncio.run(main()) ``` [​](#example-using-interrupts) Example - Using interrupts ```python import asyncio from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, ResultMessage async def interruptible_task(): options = ClaudeAgentOptions(allowed_tools=["Bash"], permission_mode="acceptEdits") async with ClaudeSDKClient(options=options) as client: # Start a long-running task await client.query("Count from 1 to 100 slowly, using the bash sleep command") # Let it run for a bit await asyncio.sleep(2) # Interrupt the task await client.interrupt() print("Task interrupted!") # Drain the interrupted task's messages (including its ResultMessage) async for message in client.receive_response(): if isinstance(message, ResultMessage): print(f"Interrupted task: terminal_reason={message.terminal_reason!r}") # terminal_reason is "aborted_streaming" or "aborted_tools" # for interrupted turns # Send a new command await client.query("Just say hello instead") # Now receive the new response async for message in client.receive_response(): if isinstance(message, ResultMessage) and message.subtype == "success": print(f"New result: {message.result}") asyncio.run(interruptible_task()) ``` **Buffer behavior after interrupt:** `interrupt()` sends a stop signal but does not clear the message buffer. Messages already produced by the interrupted task, including its `ResultMessage`, remain in the stream. You must drain them with `receive_response()` before reading the response to a new query. If you send a new query immediately after `interrupt()` and call `receive_response()` only once, you’ll receive the interrupted task’s messages, not the new query’s response. [​](#example-advanced-permission-control) Example - Advanced permission control ```python import asyncio from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions from claude_agent_sdk.types import ( PermissionResultAllow, PermissionResultDeny, ToolPermissionContext, ) async def custom_permission_handler( tool_name: str, input_data: dict, context: ToolPermissionContext ) -> PermissionResultAllow | PermissionResultDeny: """Custom logic for tool permissions.""" # Block writes to system directories if tool_name == "Write" and input_data.get("file_path", "").startswith("/system/"): return PermissionResultDeny( message="System directory write not allowed", interrupt=True ) # Redirect sensitive file operations if tool_name in ["Write", "Edit"] and "config" in input_data.get("file_path", ""): safe_path = f"./sandbox/{input_data['file_path']}" return PermissionResultAllow( updated_input={**input_data, "file_path": safe_path} ) # Allow everything else return PermissionResultAllow(updated_input=input_data) async def main(): # Don't also list the gated tools in allowed_tools: allow rules approve calls before can_use_tool runs options = ClaudeAgentOptions(can_use_tool=custom_permission_handler) async with ClaudeSDKClient(options=options) as client: await client.query("Update the system config file") async for message in client.receive_response(): # Will use sandbox path instead print(message) asyncio.run(main()) ``` [​](#types) Types **`@dataclass` vs `TypedDict`:** This SDK uses two kinds of types. Classes decorated with `@dataclass` (such as `ResultMessage`, `AgentDefinition`, `TextBlock`) are object instances at runtime and support attribute access: `msg.result`. Classes defined with `TypedDict` (such as `ThinkingConfigEnabled`, `McpStdioServerConfig`, `SyncHookJSONOutput`) are **plain dicts at runtime** and require key access: `config["budget_tokens"]`, not `config.budget_tokens`. The `ClassName(field=value)` call syntax works for both, but only dataclasses produce objects with attributes. [​](#sdkmcptool) `SdkMcpTool` Definition for an SDK MCP tool created with the `@tool` decorator. ```python @dataclass class SdkMcpTool(Generic[T]): name: str description: str input_schema: type[T] | dict[str, Any] handler: Callable[[T], Awaitable[dict[str, Any]]] annotations: ToolAnnotations | None = None ``` | Property | Type | Description | |:---------------|:-------------------------------------------|:-----------------------------------------------------------------------------------------------------------| | `name` | `str` | Unique identifier for the tool | | `description` | `str` | Human-readable description | | `input_schema` | `type[T] | dict[str, Any]` | Schema for input validation | | `handler` | `Callable[[T], Awaitable[dict[str, Any]]]` | Async function that handles tool execution | | `annotations` | `ToolAnnotations | None` | Optional MCP tool annotations (e.g., `readOnlyHint`, `destructiveHint`, `openWorldHint`). From `mcp.types` | [​](#transport) `Transport` Abstract base class for custom transport implementations. Use this to communicate with the Claude process over a custom channel (for example, a remote connection instead of a local subprocess). This is a low-level internal API. The interface may change in future releases. Custom implementations must be updated to match any interface changes. ```python from abc import ABC, abstractmethod from collections.abc import AsyncIterator from typing import Any class Transport(ABC): @abstractmethod async def connect(self) -> None: ... @abstractmethod async def write(self, data: str) -> None: ... @abstractmethod def read_messages(self) -> AsyncIterator[dict[str, Any]]: ... @abstractmethod async def close(self) -> None: ... @abstractmethod def is_ready(self) -> bool: ... @abstractmethod async def end_input(self) -> None: ... ``` | Method | Description | |:------------------|:----------------------------------------------------------------------------| | `connect()` | Connect the transport and prepare for communication | | `write(data)` | Write raw data (JSON + newline) to the transport | | `read_messages()` | Async iterator that yields parsed JSON messages | | `close()` | Close the connection and clean up resources | | `is_ready()` | Returns `True` if the transport can send and receive | | `end_input()` | Close the input stream (for example, close stdin for subprocess transports) | Import: `from claude_agent_sdk import Transport` [​](#claudeagentoptions) `ClaudeAgentOptions` Configuration dataclass for Claude Code queries. ```python @dataclass class ClaudeAgentOptions: tools: list[str] | ToolsPreset | None = None allowed_tools: list[str] = field(default_factory=list) system_prompt: str | SystemPromptPreset | SystemPromptFile | None = None mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict) strict_mcp_config: bool = False permission_mode: PermissionMode | None = None continue_conversation: bool = False resume: str | None = None session_id: str | None = None max_turns: int | None = None max_budget_usd: float | None = None disallowed_tools: list[str] = field(default_factory=list) model: str | None = None fallback_model: str | None = None betas: list[SdkBeta] = field(default_factory=list) output_format: dict[str, Any] | None = None permission_prompt_tool_name: str | None = None cwd: str | Path | None = None cli_path: str | Path | None = None settings: str | None = None add_dirs: list[str | Path] = field(default_factory=list) env: dict[str, str] = field(default_factory=dict) extra_args: dict[str, str | None] = field(default_factory=dict) max_buffer_size: int | None = None debug_stderr: Any = sys.stderr # Deprecated stderr: Callable[[str], None] | None = None can_use_tool: CanUseTool | None = None hooks: dict[HookEvent, list[HookMatcher]] | None = None user: str | None = None include_partial_messages: bool = False include_hook_events: bool = False fork_session: bool = False agents: dict[str, AgentDefinition] | None = None setting_sources: list[SettingSource] | None = None skills: list[str] | Literal["all"] | None = None sandbox: SandboxSettings | None = None plugins: list[SdkPluginConfig] = field(default_factory=list) max_thinking_tokens: int | None = None # Deprecated: use thinking instead thinking: ThinkingConfig | None = None effort: EffortLevel | None = None enable_file_checkpointing: bool = False session_store: SessionStore | None = None session_store_flush: SessionStoreFlushMode = "batched" load_timeout_ms: int = 60_000 task_budget: TaskBudget | None = None ``` | Property | Type | Default | Description | |:------------------------------|:------------------------------------------------------------------------------------------|:-----------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `tools` | `list[str] | ToolsPreset | None` | `None` | Tools configuration. Use `{"type": "preset", "preset": "claude_code"}` for Claude Code’s default tools | | `allowed_tools` | `list[str]` | `[]` | Tools to auto-approve without prompting. This does not restrict Claude to only these tools; unlisted tools fall through to `permission_mode` and `can_use_tool`. Use `disallowed_tools` to block tools. See [Permissions](/docs/en/agent-sdk/permissions#allow-and-deny-rules) | | `system_prompt` | `str | SystemPromptPreset | SystemPromptFile | None` | `None` | System prompt configuration. Pass a string for a custom prompt, `{"type": "preset", "preset": "claude_code"}` for Claude Code’s system prompt with optional `"append"`, or `{"type": "file", "path": "..."}` to load a large prompt from disk. See [`SystemPromptPreset`](#systempromptpreset) and [`SystemPromptFile`](#systempromptfile) | | `mcp_servers` | `dict[str, McpServerConfig] | str | Path` | `{}` | MCP server configurations or path to config file | | `strict_mcp_config` | `bool` | `False` | When `True`, use only the servers passed in `mcp_servers` and ignore project `.mcp.json`, user settings, plugin-provided MCP servers, and [claude.ai connectors](/docs/en/mcp#use-mcp-servers-from-claude-ai). Maps to the CLI `--strict-mcp-config` flag | | `permission_mode` | `PermissionMode | None` | `None` | Permission mode for tool usage | | `continue_conversation` | `bool` | `False` | Continue the most recent conversation | | `resume` | `str | None` | `None` | Session ID to resume | | `session_id` | `str | None` | `None` | Use a specific session ID instead of an auto-generated one. Must be a valid UUID. Can’t be combined with `continue_conversation` or `resume` unless `fork_session` is also set | | `max_turns` | `int | None` | `None` | Maximum agentic turns (tool-use round trips) | | `max_budget_usd` | `float | None` | `None` | Stop the query when the client-side cost estimate reaches this USD value. Compared against the same estimate as `total_cost_usd`; see [Track cost and usage](/docs/en/agent-sdk/cost-tracking) for accuracy caveats | | `disallowed_tools` | `list[str]` | `[]` | Tools to deny. A bare name such as `"Bash"` removes the tool from Claude’s context. A scoped rule such as `"Bash(rm *)"` leaves the tool available and denies matching calls in every permission mode, including `bypassPermissions`. See [Permissions](/docs/en/agent-sdk/permissions#allow-and-deny-rules) | | `enable_file_checkpointing` | `bool` | `False` | Enable file change tracking for rewinding. See [File checkpointing](/docs/en/agent-sdk/file-checkpointing) | | `model` | `str | None` | `None` | Claude model alias or full model name. See [accepted values and provider-specific IDs](/docs/en/model-config#available-models) | | `fallback_model` | `str | None` | `None` | Fallback model to use if the primary model fails | | `betas` | `list[SdkBeta]` | `[]` | Beta features to enable. See [`SdkBeta`](#sdkbeta) for available options | | `output_format` | `dict[str, Any] | None` | `None` | Output format for structured responses (e.g., `{"type": "json_schema", "schema": {...}}`). See [Structured outputs](/docs/en/agent-sdk/structured-outputs) for details | | `permission_prompt_tool_name` | `str | None` | `None` | MCP tool name for permission prompts | | `cwd` | `str | Path | None` | `None` | Current working directory | | `cli_path` | `str | Path | None` | `None` | Custom path to the Claude Code CLI executable | | `settings` | `str | None` | `None` | Path to settings file | | `add_dirs` | `list[str | Path]` | `[]` | Additional directories Claude can access | | `env` | `dict[str, str]` | `{}` | Environment variables merged on top of the inherited process environment. See [Environment variables](/docs/en/env-vars) for variables the underlying CLI reads, and [Handle slow or stalled API responses](#handle-slow-or-stalled-api-responses) for timeout-related variables | | `extra_args` | `dict[str, str | None]` | `{}` | Additional CLI arguments to pass directly to the CLI | | `max_buffer_size` | `int | None` | `None` | Maximum bytes when buffering CLI stdout | | `debug_stderr` | `Any` | `sys.stderr` | *Deprecated* - File-like object for debug output. Use `stderr` callback instead | | `stderr` | `Callable[[str], None] | None` | `None` | Callback function for stderr output from CLI | | `can_use_tool` | [`CanUseTool`](#canusetool) ` | None` | `None` | Tool permission callback, invoked only when the [permission flow](/docs/en/agent-sdk/permissions#how-permissions-are-evaluated) falls through to a prompt. Not invoked for calls auto-approved by `allowed_tools`, allow rules, or `permission_mode`. `AskUserQuestion`, connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools), and MCP tools marked [`requiresUserInteraction`](/docs/en/mcp#require-approval-for-a-specific-tool) reach it even if you’ve allowed them; in `dontAsk` mode these are denied instead. See [`CanUseTool`](#canusetool) for details | | `hooks` | `dict[HookEvent, list[HookMatcher]] | None` | `None` | Hook configurations for intercepting events | | `user` | `str | None` | `None` | User identifier | | `include_partial_messages` | `bool` | `False` | Include partial message streaming events. When enabled, [`StreamEvent`](#streamevent) messages are yielded | | `include_hook_events` | `bool` | `False` | Include hook lifecycle events in the message stream as `HookEventMessage` objects | | `fork_session` | `bool` | `False` | When resuming with `resume`, fork to a new session ID instead of continuing the original session | | `agents` | `dict[str, AgentDefinition] | None` | `None` | Programmatically defined subagents | | `plugins` | `list[SdkPluginConfig]` | `[]` | Load custom plugins from local paths. See [Plugins](/docs/en/agent-sdk/plugins) for details | | `sandbox` | [`SandboxSettings`](#sandboxsettings) ` | None` | `None` | Configure sandbox behavior programmatically. See [Sandbox settings](#sandboxsettings) for details | | `setting_sources` | `list[SettingSource] | None` | `None` (CLI defaults: all sources) | Control which filesystem settings to load. Pass `[]` to disable user, project, and local settings. Endpoint-managed policy loads regardless; server-managed settings are fetched when the session authenticates with an organization credential on an [eligible configuration](/docs/en/server-managed-settings#platform-availability). See [Use Claude Code features](/docs/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) | | `skills` | `list[str] | Literal["all"] | None` | `None` | Skills available to the session. Pass `"all"` to enable every discovered skill, or a list of skill names. When set, the SDK adds the Skill tool to `allowed_tools` automatically. If you also pass `tools`, include `"Skill"` in that list. See [Skills](/docs/en/agent-sdk/skills) | | `max_thinking_tokens` | `int | None` | `None` | *Deprecated* - Maximum tokens for thinking blocks. Use `thinking` instead | | `thinking` | [`ThinkingConfig`](#thinkingconfig) ` | None` | `None` | Controls extended thinking behavior. Takes precedence over `max_thinking_tokens` | | `effort` | [`EffortLevel`](#effortlevel) ` | None` | `None` | Effort level for thinking depth. See [adjust the effort level](/docs/en/model-config#adjust-effort-level) | | `session_store` | [`SessionStore`](/docs/en/agent-sdk/session-storage#the-sessionstore-interface) ` | None` | `None` | Mirror session transcripts to an external backend so any host can resume them. See [Persist sessions to external storage](/docs/en/agent-sdk/session-storage) | | `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | When to flush mirrored transcript entries to `session_store`. `"batched"` flushes once per turn or when the buffer fills; `"eager"` triggers a background flush after every frame. Ignored when `session_store` is `None` | | `load_timeout_ms` | `int` | `60000` | Per-call timeout for `session_store.load()` and `list_subkeys()` during resume materialization, in milliseconds | | `task_budget` | `TaskBudget | None` | `None` | API-side token budget. Sent as `output_config.task_budget` with the `task-budgets-2026-03-13` beta header. Pass `{"total": }`. | [​](#handle-slow-or-stalled-api-responses) Handle slow or stalled API responses The CLI subprocess reads several environment variables that control API timeouts and stall detection. Pass them through `ClaudeAgentOptions.env`: ```python from claude_agent_sdk import ClaudeAgentOptions options = ClaudeAgentOptions( env={ "API_TIMEOUT_MS": "120000", "CLAUDE_CODE_MAX_RETRIES": "2", "CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS": "120000", }, ) ``` - `API_TIMEOUT_MS`: per-request timeout on the Anthropic client, in milliseconds. Default `600000`. Applies to the main loop and all subagents. - `CLAUDE_CODE_MAX_RETRIES`: maximum API retries. Default `10`, capped at `15`. Each retry gets its own `API_TIMEOUT_MS` window, so worst-case wall time is roughly `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` plus backoff. For unattended runs that need to wait through longer outages, set `CLAUDE_CODE_RETRY_WATCHDOG=1`: it retries capacity errors indefinitely, and as of Claude Code v2.1.199 raises the default for other transient errors to `300` and removes the cap on this variable. - `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: stall watchdog for subagents launched with `run_in_background`. Default `600000`. Resets on each stream event; on stall it aborts the subagent, marks the task failed, and surfaces the error to the parent with any partial result. Does not apply to synchronous subagents. - `CLAUDE_ENABLE_STREAM_WATCHDOG` with `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: aborts the request when headers have arrived but the response body stops streaming. The watchdog is on by default for all providers; set `CLAUDE_ENABLE_STREAM_WATCHDOG=0` to disable it. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` defaults to `300000` and is clamped to that minimum. After the abort, Claude Code retries the request at most once, and only before Claude has started a block of text or a tool call in the response; once Claude has completed a block of text or a tool call, Claude Code keeps the completed output, appends an [incomplete-response notice](/docs/en/errors#the-response-above-may-be-incomplete) instead of retrying, and still runs any completed tool call. [​](#outputformat) `OutputFormat` Configuration for structured output validation. Pass this as a `dict` to the `output_format` field on `ClaudeAgentOptions`: ```python # Expected dict shape for output_format { "type": "json_schema", "schema": {...}, # Your JSON Schema definition } ``` | Field | Required | Description | |:---------|:---------|:---------------------------------------------------| | `type` | Yes | Must be `"json_schema"` for JSON Schema validation | | `schema` | Yes | JSON Schema definition for output validation | [​](#systempromptpreset) `SystemPromptPreset` Configuration for using Claude Code’s preset system prompt with optional additions. ```python class SystemPromptPreset(TypedDict): type: Literal["preset"] preset: Literal["claude_code"] append: NotRequired[str] exclude_dynamic_sections: NotRequired[bool] ``` | Field | Required | Description | |:---------------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | Yes | Must be `"preset"` to use a preset system prompt | | `preset` | Yes | Must be `"claude_code"` to use Claude Code’s system prompt | | `append` | No | Additional instructions to append to the preset system prompt | | `exclude_dynamic_sections` | No | Move per-session context such as working directory, the git-repo flag, and auto-memory paths from the system prompt into the first user message. Improves prompt-cache reuse across users and machines. See [Modify system prompts](/docs/en/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) | [​](#systempromptfile) `SystemPromptFile` Configuration for loading a custom system prompt from a file instead of passing it as a string. The SDK maps this to the CLI [`--system-prompt-file`](/docs/en/cli-reference#system-prompt-flags) flag. Use the file form when the prompt is large: the SDK passes a string `system_prompt` on the CLI subprocess argv, which is subject to OS command-line length limits before the SDK sends any API request. On Linux a single argument longer than roughly 128 KB fails at process spawn with `Argument list too long`. On Windows the whole command line is capped at roughly 32 KB, so the string form fails at a lower threshold. ```python class SystemPromptFile(TypedDict): type: Literal["file"] path: str ``` | Field | Required | Description | |:-------|:---------|:----------------------------------------------| | `type` | Yes | Must be `"file"` to load the prompt from disk | | `path` | Yes | Path to a file containing the system prompt | [​](#settingsource) `SettingSource` Controls which filesystem-based configuration sources the SDK loads settings from. ```python SettingSource = Literal["user", "project", "local"] ``` | Value | Description | Location | |:------------|:--------------------------------------------------------------------------|:------------------------------| | `"user"` | Global user settings | `~/.claude/settings.json` | | `"project"` | Shared project settings (version controlled) | `.claude/settings.json` | | `"local"` | Local project settings, gitignored when Claude Code saves a setting to it | `.claude/settings.local.json` | [​](#default-behavior) Default behavior When `setting_sources` is omitted or `None`, `query()` loads the same filesystem settings as the Claude Code CLI: user, project, and local. Endpoint-managed policy is loaded in all cases; server-managed settings are fetched when the session authenticates with an organization credential on an [eligible configuration](/docs/en/server-managed-settings#platform-availability). See [What settingSources does not control](/docs/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) for inputs that are read regardless of this option, and how to disable them. [​](#why-use-setting_sources) Why use setting_sources **Disable filesystem settings:** ```python # Do not load user, project, or local settings from disk import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): async for message in query( prompt="Analyze this code", options=ClaudeAgentOptions( setting_sources=[] ), ): print(message) asyncio.run(main()) ``` In Python SDK 0.1.59 and earlier, an empty list was treated the same as omitting the option, so `setting_sources=[]` did not disable filesystem settings. Upgrade to a newer release if you need an empty list to take effect. The TypeScript SDK is not affected. **Load all filesystem settings explicitly:** ```python import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): async for message in query( prompt="Analyze this code", options=ClaudeAgentOptions( setting_sources=["user", "project", "local"] ), ): print(message) asyncio.run(main()) ``` **Load only specific setting sources:** ```python # Load only project settings, ignore user and local import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): async for message in query( prompt="Run CI checks", options=ClaudeAgentOptions( setting_sources=["project"] # Only .claude/settings.json ), ): print(message) asyncio.run(main()) ``` **Testing and CI environments:** ```python # Ensure consistent behavior in CI by excluding local settings import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): async for message in query( prompt="Run tests", options=ClaudeAgentOptions( setting_sources=["project"], # Only team-shared settings permission_mode="bypassPermissions", ), ): print(message) asyncio.run(main()) ``` **SDK-only applications:** ```python # Define everything programmatically. # Pass [] to opt out of filesystem setting sources. import asyncio from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, query async def main(): async for message in query( prompt="Review this PR", options=ClaudeAgentOptions( setting_sources=[], agents={ "code-reviewer": AgentDefinition( description="Reviews code changes", prompt="You are a code reviewer. Report issues in the diff.", ), }, allowed_tools=["Read", "Grep", "Glob"], ), ): print(message) asyncio.run(main()) ``` **Loading CLAUDE.md project instructions:** ```python # Load project settings to include CLAUDE.md files import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): async for message in query( prompt="Add a new feature following project conventions", options=ClaudeAgentOptions( system_prompt={ "type": "preset", "preset": "claude_code", # Use Claude Code's system prompt }, setting_sources=["project"], # Loads CLAUDE.md from project allowed_tools=["Read", "Write", "Edit"], ), ): print(message) asyncio.run(main()) ``` [​](#settings-precedence) Settings precedence When multiple sources are loaded, settings are merged with this precedence (highest to lowest): 1. Local settings (`.claude/settings.local.json`) 2. Project settings (`.claude/settings.json`) 3. User settings (`~/.claude/settings.json`) Programmatic options such as `agents` and `allowed_tools` override user, project, and local filesystem settings. Managed policy settings take precedence over programmatic options. [​](#agentdefinition) `AgentDefinition` Configuration for a subagent defined programmatically. ```python @dataclass class AgentDefinition: description: str prompt: str tools: list[str] | None = None disallowedTools: list[str] | None = None model: str | None = None skills: list[str] | None = None memory: Literal["user", "project", "local"] | None = None mcpServers: list[str | dict[str, Any]] | None = None initialPrompt: str | None = None maxTurns: int | None = None background: bool | None = None effort: EffortLevel | int | None = None permissionMode: PermissionMode | None = None ``` | Field | Required | Description | |:------------------|:---------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `description` | Yes | Natural language description of when to use this agent | | `prompt` | Yes | The agent’s system prompt | | `tools` | No | Array of allowed tool names. If omitted, inherits every [tool available to subagents](/docs/en/sub-agents#available-tools) | | `disallowedTools` | No | Array of tool names to remove from the agent’s tool set. MCP server-level patterns are also accepted: `mcp__server` or `mcp__server__*` removes every tool from that server, and `mcp__*` removes every MCP tool from any server | | `model` | No | Model override for this agent. Accepts an alias such as `"sonnet"`, `"opus"`, `"haiku"`, or `"inherit"`, or a full model ID. If omitted, uses the main model | | `skills` | No | List of skill names to preload into the agent’s context at startup. Unlisted skills remain invocable through the Skill tool | | `memory` | No | Memory source for this agent: `"user"`, `"project"`, or `"local"` | | `mcpServers` | No | MCP servers available to this agent. Each entry is a server name or an inline `{name: config}` dict | | `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main thread agent | | `maxTurns` | No | Maximum number of agentic turns before the agent stops | | `background` | No | Run this agent as a non-blocking background task when invoked | | `effort` | No | Reasoning effort level for this agent. Accepts a named level or an integer. See [`EffortLevel`](#effortlevel) | | `permissionMode` | No | Permission mode for tool execution within this agent. See [`PermissionMode`](#permissionmode) | `AgentDefinition` field names use camelCase, such as `disallowedTools`, `permissionMode`, and `maxTurns`. These names map directly to the wire format shared with the TypeScript SDK. This differs from `ClaudeAgentOptions`, which uses Python snake_case for the equivalent top-level fields such as `disallowed_tools` and `permission_mode`. Because `AgentDefinition` is a dataclass, passing a snake_case keyword raises a `TypeError` at construction time. [​](#permissionmode) `PermissionMode` Permission modes for controlling tool execution. ```python PermissionMode = Literal[ "default", # Standard permission behavior "acceptEdits", # Auto-accept file edits "plan", # Planning mode - explore without editing "dontAsk", # Deny anything not pre-approved instead of prompting "bypassPermissions", # Bypass permission checks; explicit ask rules still prompt (use with caution) "auto", # Model classifier approves or denies permission prompts ] ``` [​](#effortlevel) `EffortLevel` Effort levels for guiding thinking depth. ```python EffortLevel = Literal[ "low", # Minimal thinking, fastest responses "medium", # Moderate thinking "high", # Deep reasoning "xhigh", # Extended reasoning; falls back to "high" on models that don't support it "max", # Maximum effort ] ``` [​](#canusetool) `CanUseTool` Type alias for tool permission callback functions. ```python CanUseTool = Callable[ [str, dict[str, Any], ToolPermissionContext], Awaitable[PermissionResult] ] ``` The callback receives: - `tool_name`: Name of the tool being called - `input_data`: The tool’s input parameters - `context`: A `ToolPermissionContext` with additional information Returns a `PermissionResult` (either `PermissionResultAllow` or `PermissionResultDeny`). The callback is the SDK replacement for the interactive permission prompt: it’s invoked only when the [permission evaluation flow](/docs/en/agent-sdk/permissions#how-permissions-are-evaluated) resolves to a prompt. Tool calls already approved by an `allowed_tools` entry, a settings allow rule, or the permission mode, such as `acceptEdits` or `bypassPermissions`, never invoke it. To gate every tool call, use a [`PreToolUse` hook](/docs/en/agent-sdk/hooks) instead. `AskUserQuestion`, MCP tools marked [`requiresUserInteraction`](/docs/en/mcp#require-approval-for-a-specific-tool), and connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools) reach the callback even when an allow rule matches. In `dontAsk` mode these calls are denied instead, without invoking the callback. [​](#toolpermissioncontext) `ToolPermissionContext` Context information passed to tool permission callbacks. ```python @dataclass class ToolPermissionContext: signal: Any | None = None # Future: abort signal support suggestions: list[PermissionUpdate] = field(default_factory=list) tool_use_id: str | None = None agent_id: str | None = None blocked_path: str | None = None decision_reason: str | None = None title: str | None = None display_name: str | None = None description: str | None = None ``` | Field | Type | Description | |:------------------|:-------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `signal` | `Any | None` | Reserved for future abort signal support | | `suggestions` | `list[PermissionUpdate]` | Permission update suggestions from the CLI. Bash prompts include a suggestion with the `localSettings` destination, so returning it in `updated_permissions` writes the rule to `.claude/settings.local.json` and persists across sessions. | | `tool_use_id` | `str | None` | Identifier of the specific tool call this prompt is for. Always populated when delivered to `can_use_tool` | | `agent_id` | `str | None` | Sub-agent ID when the call originates from a subagent; `None` for the main agent | | `blocked_path` | `str | None` | File path that triggered the permission request, when applicable. For example, when a Bash command tries to access a path outside allowed directories | | `decision_reason` | `str | None` | Reason this permission request was triggered. Forwarded from a PreToolUse hook’s `permissionDecisionReason` when the hook returned `"ask"` | | `title` | `str | None` | Full permission prompt sentence, such as `Claude wants to read foo.txt`. Use as the primary prompt text when present | | `display_name` | `str | None` | Short noun phrase for the tool action, such as `Read file`, suitable for button labels | | `description` | `str | None` | Human-readable subtitle for the permission UI | [​](#permissionresult) `PermissionResult` Union type for permission callback results. ```python PermissionResult = PermissionResultAllow | PermissionResultDeny ``` [​](#permissionresultallow) `PermissionResultAllow` Result indicating the tool call should be allowed. ```python @dataclass class PermissionResultAllow: behavior: Literal["allow"] = "allow" updated_input: dict[str, Any] | None = None updated_permissions: list[PermissionUpdate] | None = None ``` | Field | Type | Default | Description | |:----------------------|:--------------------------------|:----------|:------------------------------------------| | `behavior` | `Literal["allow"]` | `"allow"` | Must be “allow” | | `updated_input` | `dict[str, Any] | None` | `None` | Modified input to use instead of original | | `updated_permissions` | `list[PermissionUpdate] | None` | `None` | Permission updates to apply | [​](#permissionresultdeny) `PermissionResultDeny` Result indicating the tool call should be denied. ```python @dataclass class PermissionResultDeny: behavior: Literal["deny"] = "deny" message: str = "" interrupt: bool = False ``` | Field | Type | Default | Description | |:------------|:------------------|:---------|:-------------------------------------------| | `behavior` | `Literal["deny"]` | `"deny"` | Must be “deny” | | `message` | `str` | `""` | Message explaining why the tool was denied | | `interrupt` | `bool` | `False` | Whether to interrupt the current execution | [​](#permissionupdate) `PermissionUpdate` Configuration for updating permissions programmatically. ```python @dataclass class PermissionUpdate: type: Literal[ "addRules", "replaceRules", "removeRules", "setMode", "addDirectories", "removeDirectories", ] rules: list[PermissionRuleValue] | None = None behavior: Literal["allow", "deny", "ask"] | None = None mode: PermissionMode | None = None directories: list[str] | None = None destination: ( Literal["userSettings", "projectSettings", "localSettings", "session"] | None ) = None ``` | Field | Type | Description | |:--------------|:-----------------------------------------|:------------------------------------------------| | `type` | `Literal[...]` | The type of permission update operation | | `rules` | `list[PermissionRuleValue] | None` | Rules for add/replace/remove operations | | `behavior` | `Literal["allow", "deny", "ask"] | None` | Behavior for rule-based operations | | `mode` | `PermissionMode | None` | Mode for setMode operation | | `directories` | `list[str] | None` | Directories for add/remove directory operations | | `destination` | `Literal[...] | None` | Where to apply the permission update | [​](#permissionrulevalue) `PermissionRuleValue` A rule to add, replace, or remove in a permission update. ```python @dataclass class PermissionRuleValue: tool_name: str rule_content: str | None = None ``` [​](#toolspreset) `ToolsPreset` Preset tools configuration for using Claude Code’s default tool set. ```python class ToolsPreset(TypedDict): type: Literal["preset"] preset: Literal["claude_code"] ``` [​](#thinkingconfig) `ThinkingConfig` Controls extended thinking behavior. A union of three configurations: ```python ThinkingDisplay = Literal["summarized", "omitted"] class ThinkingConfigAdaptive(TypedDict): type: Literal["adaptive"] display: NotRequired[ThinkingDisplay] class ThinkingConfigEnabled(TypedDict): type: Literal["enabled"] budget_tokens: int display: NotRequired[ThinkingDisplay] class ThinkingConfigDisabled(TypedDict): type: Literal["disabled"] ThinkingConfig = ThinkingConfigAdaptive | ThinkingConfigEnabled | ThinkingConfigDisabled ``` | Variant | Fields | Description | |:-----------|:-----------------------------------|:---------------------------------------------| | `adaptive` | `type`, `display` | Claude adaptively decides when to think | | `enabled` | `type`, `budget_tokens`, `display` | Enable thinking with a specific token budget | | `disabled` | `type` | Disable thinking | The optional `display` field controls whether thinking text is returned `"summarized"` or `"omitted"`. On Claude Opus 4.7 and later, the API default is `"omitted"`, so set `"summarized"` to receive thinking content in [`ThinkingBlock`](#thinkingblock) outputs. Claude Code doesn’t send `display` to Amazon Bedrock or Google Cloud’s Agent Platform, so on those providers Opus 4.7 and later return empty `ThinkingBlock` outputs even when you set `display` to `"summarized"`. Because these are `TypedDict` classes, they’re plain dicts at runtime. Either construct them as dict literals or call the class like a constructor; both produce a `dict`. Access fields with `config["budget_tokens"]`, not `config.budget_tokens`: ```python from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled # Option 1: dict literal (recommended, no import needed) options = ClaudeAgentOptions(thinking={"type": "enabled", "budget_tokens": 20000}) # Option 2: constructor-style (returns a plain dict) config = ThinkingConfigEnabled(type="enabled", budget_tokens=20000) print(config["budget_tokens"]) # 20000 # config.budget_tokens would raise AttributeError ``` [​](#taskbudget) `TaskBudget` API-side task budget in tokens, used with the `task_budget` field in `ClaudeAgentOptions`. ```python class TaskBudget(TypedDict): total: int ``` | Field | Type | Description | |:--------|:------|:--------------------------------| | `total` | `int` | Total token budget for the task | Because this is a `TypedDict`, pass it as a plain dict, such as `ClaudeAgentOptions(task_budget={"total": 50000})`. [​](#sdkbeta) `SdkBeta` Literal type for SDK beta features. ```python SdkBeta = Literal["context-1m-2025-08-07"] ``` Use with the `betas` field in `ClaudeAgentOptions` to enable beta features. The `context-1m-2025-08-07` beta is retired as of April 30, 2026. Passing this header with Claude Sonnet 4.5 or Sonnet 4 has no effect, and requests that exceed the standard 200k-token context window return an error. To use a 1M-token context window, migrate to [Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.6, Claude Opus 4.7, or Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview), which include 1M context at standard pricing with no beta header required. [​](#mcpsdkserverconfig) `McpSdkServerConfig` Configuration for SDK MCP servers created with `create_sdk_mcp_server()`. ```python class McpSdkServerConfig(TypedDict): type: Literal["sdk"] name: str instance: Any # MCP Server instance ``` [​](#mcpserverconfig) `McpServerConfig` Union type for MCP server configurations. ```python McpServerConfig = ( McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig ) ``` [​](#mcpstdioserverconfig) `McpStdioServerConfig` ```python class McpStdioServerConfig(TypedDict): type: NotRequired[Literal["stdio"]] # Optional for backwards compatibility command: str args: NotRequired[list[str]] env: NotRequired[dict[str, str]] ``` [​](#mcpsseserverconfig) `McpSSEServerConfig` ```python class McpSSEServerConfig(TypedDict): type: Literal["sse"] url: str headers: NotRequired[dict[str, str]] ``` [​](#mcphttpserverconfig) `McpHttpServerConfig` ```python class McpHttpServerConfig(TypedDict): type: Literal["http"] url: str headers: NotRequired[dict[str, str]] ``` [​](#mcpserverstatusconfig) `McpServerStatusConfig` The configuration of an MCP server as reported by [`get_mcp_status()`](#methods). This is the union of all [`McpServerConfig`](#mcpserverconfig) transport variants plus an output-only `claudeai-proxy` variant for servers proxied through claude.ai. ```python McpServerStatusConfig = ( McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfigStatus | McpClaudeAIProxyServerConfig ) ``` `McpSdkServerConfigStatus` is the serializable form of [`McpSdkServerConfig`](#mcpsdkserverconfig) with only `type` (`"sdk"`) and `name` (`str`) fields; the in-process `instance` is omitted. `McpClaudeAIProxyServerConfig` has `type` (`"claudeai-proxy"`), `url` (`str`), and `id` (`str`) fields. [​](#mcpstatusresponse) `McpStatusResponse` Response from [`ClaudeSDKClient.get_mcp_status()`](#methods). Wraps the list of server statuses under the `mcpServers` key. ```python class McpStatusResponse(TypedDict): mcpServers: list[McpServerStatus] ``` [​](#mcpserverstatus) `McpServerStatus` Status of a connected MCP server, contained in [`McpStatusResponse`](#mcpstatusresponse). ```python class McpServerStatus(TypedDict): name: str status: McpServerConnectionStatus # "connected" | "failed" | "needs-auth" | "pending" | "disabled" serverInfo: NotRequired[McpServerInfo] error: NotRequired[str] config: NotRequired[McpServerStatusConfig] scope: NotRequired[str] tools: NotRequired[list[McpToolInfo]] ``` | Field | Type | Description | |:-------------|:-------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `name` | `str` | Server name | | `status` | `str` | One of `"connected"`, `"failed"`, `"needs-auth"`, `"pending"`, or `"disabled"` | | `serverInfo` | `dict` (optional) | Server name and version (`{"name": str, "version": str}`) | | `error` | `str` (optional) | Error message if the server failed to connect | | `config` | [`McpServerStatusConfig`](#mcpserverstatusconfig) (optional) | Server configuration. Same shape as [`McpServerConfig`](#mcpserverconfig) (stdio, SSE, HTTP, or SDK), plus a `claudeai-proxy` variant for servers connected through claude.ai | | `scope` | `str` (optional) | Configuration scope | | `tools` | `list` (optional) | Tools provided by this server, each with `name`, `description`, and `annotations` fields | [​](#sdkpluginconfig) `SdkPluginConfig` Configuration for loading plugins in the SDK. ```python class SdkPluginConfig(TypedDict): type: Literal["local"] path: str ``` | Field | Type | Description | |:-------|:-------------------|:-----------------------------------------------------------| | `type` | `Literal["local"]` | Must be `"local"` (only local plugins currently supported) | | `path` | `str` | Absolute or relative path to the plugin directory | **Example:** ```python plugins = [ {"type": "local", "path": "./my-plugin"}, {"type": "local", "path": "/absolute/path/to/plugin"}, ] ``` For complete information on creating and using plugins, see [Plugins](/docs/en/agent-sdk/plugins). [​](#message-types) Message Types [​](#message) `Message` Union type of all possible messages. ```python Message = ( UserMessage | AssistantMessage | SystemMessage | ResultMessage | StreamEvent | RateLimitEvent ) ``` [​](#usermessage) `UserMessage` User input message. ```python @dataclass class UserMessage: content: str | list[ContentBlock] uuid: str | None = None parent_tool_use_id: str | None = None tool_use_result: dict[str, Any] | None = None ``` | Field | Type | Description | |:---------------------|:---------------------------|:------------------------------------------------------| | `content` | `str | list[ContentBlock]` | Message content as text or content blocks | | `uuid` | `str | None` | Unique message identifier | | `parent_tool_use_id` | `str | None` | Tool use ID if this message is a tool result response | | `tool_use_result` | `dict[str, Any] | None` | Tool result data if applicable | [​](#assistantmessage) `AssistantMessage` Assistant response message with content blocks. ```python @dataclass class AssistantMessage: content: list[ContentBlock] model: str parent_tool_use_id: str | None = None error: AssistantMessageError | None = None usage: dict[str, Any] | None = None message_id: str | None = None stop_reason: str | None = None session_id: str | None = None uuid: str | None = None ``` | Field | Type | Description | |:---------------------|:------------------------------------------------------------|:-------------------------------------------------------------------------------| | `content` | `list[ContentBlock]` | List of content blocks in the response | | `model` | `str` | Model that generated the response | | `parent_tool_use_id` | `str | None` | Tool use ID if this is a nested response | | `error` | [`AssistantMessageError`](#assistantmessageerror) ` | None` | Error type if the response encountered an error | | `usage` | `dict[str, Any] | None` | Per-message token usage (same keys as [`ResultMessage.usage`](#resultmessage)) | | `message_id` | `str | None` | API message ID. Multiple messages from one turn share the same ID | | `stop_reason` | `str | None` | Stop reason from the API (e.g. `end_turn`, `tool_use`) | | `session_id` | `str | None` | ID of the session this message belongs to | | `uuid` | `str | None` | Unique message identifier within the session transcript | [​](#assistantmessageerror) `AssistantMessageError` Possible error types for assistant messages. ```python AssistantMessageError = Literal[ "authentication_failed", "billing_error", "rate_limit", "invalid_request", "server_error", "unknown", ] ``` The underlying CLI process can emit error types this Literal doesn’t list, such as `max_output_tokens`. The SDK passes the value through unmodified, so treat strings outside this list the way you treat `unknown`. The TypeScript [`SDKAssistantMessageError`](/docs/en/agent-sdk/typescript#sdkassistantmessage) type lists the full set of values the CLI can emit. [​](#systemmessage) `SystemMessage` System message with metadata. ```python @dataclass class SystemMessage: subtype: str data: dict[str, Any] ``` [​](#resultmessage) `ResultMessage` Final result message with cost and usage information. ```python @dataclass class ResultMessage: subtype: str duration_ms: int duration_api_ms: int is_error: bool num_turns: int session_id: str stop_reason: str | None = None total_cost_usd: float | None = None usage: dict[str, Any] | None = None result: str | None = None structured_output: Any = None model_usage: dict[str, ModelUsage] | None = None permission_denials: list[Any] | None = None deferred_tool_use: DeferredToolUse | None = None errors: list[str] | None = None api_error_status: int | None = None uuid: str | None = None terminal_reason: str | None = None ``` The `subtype` field determines which other fields are populated. It is one of `"success"`, `"error_during_execution"`, `"error_max_turns"`, `"error_max_budget_usd"`, or `"error_max_structured_output_retries"`. The Python dataclass flattens all variants into one shape, so fields that don’t apply to the returned subtype are `None`. Several fields carry diagnostic detail about how the conversation ended: - `is_error`: `True` when the conversation ended in an error state. Always `True` on the `error_*` subtypes. On `subtype="success"` it is `True` when the final model request failed, meaning the agent loop completed but the last API call returned an error. - `api_error_status`: the HTTP status code of the terminating API error. `None` when the turn ended without one. Populated only on `subtype="success"`. - `result`: text of the final assistant message on `subtype="success"`, or `None` on the `error_*` subtypes. When `subtype="success"` and `is_error=True`, this holds the API error string if one is available but can be empty, so check `api_error_status` and the preceding `AssistantMessage` content for detail. - `errors`: loop-level error strings such as the max-turns message. Populated only on the `error_*` subtypes. - `terminal_reason`: why the query loop ended, such as `"completed"`, `"max_turns"`, `"api_error"`, `"aborted_streaming"`, or `"aborted_tools"`. A value of `"aborted_streaming"` or `"aborted_tools"` means the turn was aborted before completing. Common causes are [`interrupt()`](#claudesdkclient) and a permission callback returning [`PermissionResultDeny`](#permissionresultdeny) with `interrupt=True`. `None` on CLI versions that predate the field, on results that bypassed the query loop such as local slash commands, or on synthesized error results emitted when the session fails fatally. Mirrors the TypeScript SDK’s [`SDKResultMessage.terminal_reason`](/docs/en/agent-sdk/typescript#sdkresultmessage), which lists the full set of values. The `usage` dict contains the following keys when present: | Key | Type | Description | |-------------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `input_tokens` | `int` | Input tokens consumed by the top-level agent loop. [Subagent tokens aren’t included](/docs/en/agent-sdk/cost-tracking#get-the-total-cost-of-a-query); use `model_usage` for whole-tree accounting. | | `output_tokens` | `int` | Output tokens generated by the top-level agent loop. Subagent tokens aren’t included. | | `cache_creation_input_tokens` | `int` | Tokens used to create new cache entries. | | `cache_read_input_tokens` | `int` | Tokens read from existing cache entries. | The `model_usage` dict maps model names to per-model usage. Each value is a `ModelUsage` TypedDict whose keys use camelCase, because the value is passed through unmodified from the underlying CLI process. Import via `from claude_agent_sdk.types import ModelUsage`. The keys are: | Key | Type | Description | |----------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `inputTokens` | `int` | Input tokens for this model. | | `outputTokens` | `int` | Output tokens for this model. | | `cacheReadInputTokens` | `int` | Cache read tokens for this model. | | `cacheCreationInputTokens` | `int` | Cache creation tokens for this model. | | `webSearchRequests` | `int` | Web search requests made by this model. | | `costUSD` | `float` | Estimated cost in USD for this model, computed client-side. See [Track cost and usage](/docs/en/agent-sdk/cost-tracking) for billing caveats. | | `contextWindow` | `int` | Context window size for this model. | | `maxOutputTokens` | `int` | Maximum output token limit for this model. | | `canonicalModel` | `str` | Canonical model ID used for the pricing lookup. May differ from the raw model string the entry is keyed by, such as a provider-specific ID or alias. Not always present. | | `provider` | `str` | API provider that served this model, such as `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle`, or `gateway`. Not always present. | [​](#streamevent) `StreamEvent` Stream event for partial message updates during streaming. Only received when `include_partial_messages=True` in `ClaudeAgentOptions`. Import via `from claude_agent_sdk.types import StreamEvent`. ```python @dataclass class StreamEvent: uuid: str session_id: str event: dict[str, Any] # The raw Claude API stream event parent_tool_use_id: str | None = None ``` | Field | Type | Description | |:---------------------|:-----------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `uuid` | `str` | Unique identifier for this event | | `session_id` | `str` | Session identifier | | `event` | `dict[str, Any]` | The raw Claude API stream event data | | `parent_tool_use_id` | `str | None` | Always `None`. Stream events are emitted for the main session only. For subagent attribution, use complete messages such as [`AssistantMessage`](#assistantmessage) | [​](#ratelimitevent) `RateLimitEvent` Emitted when rate limit status changes (for example, from `"allowed"` to `"allowed_warning"`). Use this to warn users before they hit a hard limit, or to back off when status is `"rejected"`. ```python @dataclass class RateLimitEvent: rate_limit_info: RateLimitInfo uuid: str session_id: str ``` | Field | Type | Description | |:------------------|:----------------------------------|:-------------------------| | `rate_limit_info` | [`RateLimitInfo`](#ratelimitinfo) | Current rate limit state | | `uuid` | `str` | Unique event identifier | | `session_id` | `str` | Session identifier | [​](#ratelimitinfo) `RateLimitInfo` Rate limit state carried by [`RateLimitEvent`](#ratelimitevent). ```python RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"] RateLimitType = Literal[ "five_hour", "seven_day", "seven_day_opus", "seven_day_sonnet", "overage" ] @dataclass class RateLimitInfo: status: RateLimitStatus resets_at: int | None = None rate_limit_type: RateLimitType | None = None utilization: float | None = None overage_status: RateLimitStatus | None = None overage_resets_at: int | None = None overage_disabled_reason: str | None = None raw: dict[str, Any] = field(default_factory=dict) ``` | Field | Type | Description | |:--------------------------|:-------------------------|:------------------------------------------------------------------------------------------------------| | `status` | `RateLimitStatus` | Current status. `"allowed_warning"` means approaching the limit; `"rejected"` means the limit was hit | | `resets_at` | `int | None` | Unix timestamp when the rate limit window resets | | `rate_limit_type` | `RateLimitType | None` | Which rate limit window applies | | `utilization` | `float | None` | Fraction of the rate limit consumed (0.0 to 1.0) | | `overage_status` | `RateLimitStatus | None` | Status of pay-as-you-go overage usage, if applicable | | `overage_resets_at` | `int | None` | Unix timestamp when the overage window resets | | `overage_disabled_reason` | `str | None` | Why overage is unavailable, if status is `"rejected"` | | `raw` | `dict[str, Any]` | Full raw dict from the CLI, including fields not modeled above | [​](#taskstartedmessage) `TaskStartedMessage` Emitted when a background task starts. A background task is anything tracked outside the main turn: a backgrounded Bash command, a [Monitor](#monitor) watch, a subagent spawned via the Agent tool, or a remote agent. The `task_type` field tells you which. This naming is unrelated to the `Task`-to-`Agent` tool rename. ```python @dataclass class TaskStartedMessage(SystemMessage): task_id: str description: str uuid: str session_id: str tool_use_id: str | None = None task_type: str | None = None ``` | Field | Type | Description | |:--------------|:-------------|:----------------------------------------------------------------------------------------------------------------------------| | `task_id` | `str` | Unique identifier for the task | | `description` | `str` | Description of the task | | `uuid` | `str` | Unique message identifier | | `session_id` | `str` | Session identifier | | `tool_use_id` | `str | None` | Associated tool use ID | | `task_type` | `str | None` | Which kind of background task: `"local_bash"` for background Bash and Monitor watches, `"local_agent"`, or `"remote_agent"` | [​](#taskusage) `TaskUsage` Token and timing data for a background task. ```python class TaskUsage(TypedDict): total_tokens: int tool_uses: int duration_ms: int ``` [​](#taskprogressmessage) `TaskProgressMessage` Emitted periodically with progress updates for a running background task. ```python @dataclass class TaskProgressMessage(SystemMessage): task_id: str description: str usage: TaskUsage uuid: str session_id: str tool_use_id: str | None = None last_tool_name: str | None = None ``` | Field | Type | Description | |:-----------------|:-------------|:------------------------------------| | `task_id` | `str` | Unique identifier for the task | | `description` | `str` | Current status description | | `usage` | `TaskUsage` | Token usage for this task so far | | `uuid` | `str` | Unique message identifier | | `session_id` | `str` | Session identifier | | `tool_use_id` | `str | None` | Associated tool use ID | | `last_tool_name` | `str | None` | Name of the last tool the task used | [​](#tasknotificationmessage) `TaskNotificationMessage` Emitted when a background task completes, fails, or is stopped. Background tasks include `run_in_background` Bash commands, Monitor watches, and background subagents. ```python @dataclass class TaskNotificationMessage(SystemMessage): task_id: str status: TaskNotificationStatus # "completed" | "failed" | "stopped" output_file: str summary: str uuid: str session_id: str tool_use_id: str | None = None usage: TaskUsage | None = None ``` | Field | Type | Description | |:--------------|:-------------------------|:-------------------------------------------------| | `task_id` | `str` | Unique identifier for the task | | `status` | `TaskNotificationStatus` | One of `"completed"`, `"failed"`, or `"stopped"` | | `output_file` | `str` | Path to the task output file | | `summary` | `str` | Summary of the task result | | `uuid` | `str` | Unique message identifier | | `session_id` | `str` | Session identifier | | `tool_use_id` | `str | None` | Associated tool use ID | | `usage` | `TaskUsage | None` | Final token usage for the task | [​](#content-block-types) Content Block Types [​](#contentblock) `ContentBlock` Union type of all content blocks. ```python ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock ``` [​](#textblock) `TextBlock` Text content block. ```python @dataclass class TextBlock: text: str ``` [​](#thinkingblock) `ThinkingBlock` Thinking content block (for models with thinking capability). ```python @dataclass class ThinkingBlock: thinking: str signature: str ``` [​](#tooluseblock) `ToolUseBlock` Tool use request block. ```python @dataclass class ToolUseBlock: id: str name: str input: dict[str, Any] ``` [​](#toolresultblock) `ToolResultBlock` Tool execution result block. ```python @dataclass class ToolResultBlock: tool_use_id: str content: str | list[dict[str, Any]] | None = None is_error: bool | None = None ``` [​](#error-types) Error Types [​](#claudesdkerror) `ClaudeSDKError` Base exception class for all SDK errors. ```python class ClaudeSDKError(Exception): """Base error for Claude SDK.""" ``` When a single-shot `query()` ends with an error result, for example a turn-limit error, the SDK raises a plain `Exception` after yielding the final result message, not a `ClaudeSDKError` subclass. [​](#clinotfounderror) `CLINotFoundError` Raised when Claude Code CLI is not installed or not found. ```python class CLINotFoundError(CLIConnectionError): def __init__( self, message: str = "Claude Code not found", cli_path: str | None = None ): """ Args: message: Error message (default: "Claude Code not found") cli_path: Optional path to the CLI that was not found """ ``` [​](#cliconnectionerror) `CLIConnectionError` Raised when connection to Claude Code fails. ```python class CLIConnectionError(ClaudeSDKError): """Failed to connect to Claude Code.""" ``` [​](#processerror) `ProcessError` Raised when the Claude Code process fails. ```python class ProcessError(ClaudeSDKError): def __init__( self, message: str, exit_code: int | None = None, stderr: str | None = None ): self.exit_code = exit_code self.stderr = stderr ``` [​](#clijsondecodeerror) `CLIJSONDecodeError` Raised when JSON parsing fails. ```python class CLIJSONDecodeError(ClaudeSDKError): def __init__(self, line: str, original_error: Exception): """ Args: line: The line that failed to parse original_error: The original JSON decode exception """ self.line = line self.original_error = original_error ``` [​](#hook-types) Hook Types For a comprehensive guide on using hooks with examples and common patterns, see the [Hooks guide](/docs/en/agent-sdk/hooks). [​](#hookevent) `HookEvent` Supported hook event types. ```python HookEvent = Literal[ "PreToolUse", # Called before tool execution "PostToolUse", # Called after tool execution "PostToolUseFailure", # Called when a tool execution fails "UserPromptSubmit", # Called when user submits a prompt "Stop", # Called when stopping execution "SubagentStop", # Called when a subagent stops "PreCompact", # Called before message compaction "Notification", # Called for notification events "SubagentStart", # Called when a subagent starts "PermissionRequest", # Called when a permission decision is needed ] ``` The TypeScript SDK supports additional hook events not yet available in Python. See the [hook availability table](/docs/en/agent-sdk/hooks#available-hooks) for per-SDK support. [​](#hookcallback) `HookCallback` Type definition for hook callback functions. ```python HookCallback = Callable[[HookInput, str | None, HookContext], Awaitable[HookJSONOutput]] ``` Parameters: - `input`: Strongly-typed hook input with discriminated unions based on `hook_event_name` (see [`HookInput`](#hookinput)) - `tool_use_id`: Optional tool use identifier (for tool-related hooks) - `context`: Hook context with additional information Returns a [`HookJSONOutput`](#hookjsonoutput) that may contain: - `decision`: `"block"` to block the action - `systemMessage`: warning message shown to the user - `hookSpecificOutput`: Hook-specific output data [​](#hookcontext) `HookContext` Context information passed to hook callbacks. ```python class HookContext(TypedDict): signal: Any | None # Future: abort signal support ``` [​](#hookmatcher) `HookMatcher` Configuration for matching hooks to specific events or tools. ```python @dataclass class HookMatcher: matcher: str | None = ( None # Tool name or pattern to match (e.g., "Bash", "Write|Edit") ) hooks: list[HookCallback] = field( default_factory=list ) # List of callbacks to execute timeout: float | None = ( None # Timeout in seconds. When omitted, the per-event default applies: # 600 for most events, 30 for UserPromptSubmit ) ``` [​](#hookinput) `HookInput` Union type of all hook input types. The actual type depends on the `hook_event_name` field. ```python HookInput = ( PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | UserPromptSubmitHookInput | StopHookInput | SubagentStopHookInput | PreCompactHookInput | NotificationHookInput | SubagentStartHookInput | PermissionRequestHookInput ) ``` [​](#basehookinput) `BaseHookInput` Base fields present in all hook input types. ```python class BaseHookInput(TypedDict): session_id: str transcript_path: str cwd: str permission_mode: NotRequired[str] ``` | Field | Type | Description | |:------------------|:-----------------|:------------------------------------| | `session_id` | `str` | Current session identifier | | `transcript_path` | `str` | Path to the session transcript file | | `cwd` | `str` | Current working directory | | `permission_mode` | `str` (optional) | Current permission mode | [​](#pretoolusehookinput) `PreToolUseHookInput` Input data for `PreToolUse` hook events. ```python class PreToolUseHookInput(BaseHookInput): hook_event_name: Literal["PreToolUse"] tool_name: str tool_input: dict[str, Any] tool_use_id: str agent_id: NotRequired[str] agent_type: NotRequired[str] ``` | Field | Type | Description | |:------------------|:------------------------|:-------------------------------------------------------------------| | `hook_event_name` | `Literal["PreToolUse"]` | Always “PreToolUse” | | `tool_name` | `str` | Name of the tool about to be executed | | `tool_input` | `dict[str, Any]` | Input parameters for the tool | | `tool_use_id` | `str` | Unique identifier for this tool use | | `agent_id` | `str` (optional) | Subagent identifier, present when the hook fires inside a subagent | | `agent_type` | `str` (optional) | Subagent type, present when the hook fires inside a subagent | [​](#posttoolusehookinput) `PostToolUseHookInput` Input data for `PostToolUse` hook events. ```python class PostToolUseHookInput(BaseHookInput): hook_event_name: Literal["PostToolUse"] tool_name: str tool_input: dict[str, Any] tool_response: Any tool_use_id: str agent_id: NotRequired[str] agent_type: NotRequired[str] ``` | Field | Type | Description | |:------------------|:-------------------------|:-------------------------------------------------------------------| | `hook_event_name` | `Literal["PostToolUse"]` | Always “PostToolUse” | | `tool_name` | `str` | Name of the tool that was executed | | `tool_input` | `dict[str, Any]` | Input parameters that were used | | `tool_response` | `Any` | Response from the tool execution | | `tool_use_id` | `str` | Unique identifier for this tool use | | `agent_id` | `str` (optional) | Subagent identifier, present when the hook fires inside a subagent | | `agent_type` | `str` (optional) | Subagent type, present when the hook fires inside a subagent | [​](#posttoolusefailurehookinput) `PostToolUseFailureHookInput` Input data for `PostToolUseFailure` hook events. Called when a tool execution fails. ```python class PostToolUseFailureHookInput(BaseHookInput): hook_event_name: Literal["PostToolUseFailure"] tool_name: str tool_input: dict[str, Any] tool_use_id: str error: str is_interrupt: NotRequired[bool] agent_id: NotRequired[str] agent_type: NotRequired[str] ``` | Field | Type | Description | |:------------------|:--------------------------------|:-------------------------------------------------------------------| | `hook_event_name` | `Literal["PostToolUseFailure"]` | Always “PostToolUseFailure” | | `tool_name` | `str` | Name of the tool that failed | | `tool_input` | `dict[str, Any]` | Input parameters that were used | | `tool_use_id` | `str` | Unique identifier for this tool use | | `error` | `str` | Error message from the failed execution | | `is_interrupt` | `bool` (optional) | Whether the failure was caused by an interrupt | | `agent_id` | `str` (optional) | Subagent identifier, present when the hook fires inside a subagent | | `agent_type` | `str` (optional) | Subagent type, present when the hook fires inside a subagent | [​](#userpromptsubmithookinput) `UserPromptSubmitHookInput` Input data for `UserPromptSubmit` hook events. ```python class UserPromptSubmitHookInput(BaseHookInput): hook_event_name: Literal["UserPromptSubmit"] prompt: str ``` | Field | Type | Description | |:------------------|:------------------------------|:----------------------------| | `hook_event_name` | `Literal["UserPromptSubmit"]` | Always “UserPromptSubmit” | | `prompt` | `str` | The user’s submitted prompt | [​](#stophookinput) `StopHookInput` Input data for `Stop` hook events. ```python class StopHookInput(BaseHookInput): hook_event_name: Literal["Stop"] stop_hook_active: bool ``` | Field | Type | Description | |:-------------------|:------------------|:--------------------------------| | `hook_event_name` | `Literal["Stop"]` | Always “Stop” | | `stop_hook_active` | `bool` | Whether the stop hook is active | [​](#subagentstophookinput) `SubagentStopHookInput` Input data for `SubagentStop` hook events. ```python class SubagentStopHookInput(BaseHookInput): hook_event_name: Literal["SubagentStop"] stop_hook_active: bool agent_id: str agent_transcript_path: str agent_type: str ``` | Field | Type | Description | |:------------------------|:--------------------------|:---------------------------------------| | `hook_event_name` | `Literal["SubagentStop"]` | Always “SubagentStop” | | `stop_hook_active` | `bool` | Whether the stop hook is active | | `agent_id` | `str` | Unique identifier for the subagent | | `agent_transcript_path` | `str` | Path to the subagent’s transcript file | | `agent_type` | `str` | Type of the subagent | [​](#precompacthookinput) `PreCompactHookInput` Input data for `PreCompact` hook events. ```python class PreCompactHookInput(BaseHookInput): hook_event_name: Literal["PreCompact"] trigger: Literal["manual", "auto"] custom_instructions: str | None ``` | Field | Type | Description | |:----------------------|:----------------------------|:-----------------------------------| | `hook_event_name` | `Literal["PreCompact"]` | Always “PreCompact” | | `trigger` | `Literal["manual", "auto"]` | What triggered the compaction | | `custom_instructions` | `str | None` | Custom instructions for compaction | [​](#notificationhookinput) `NotificationHookInput` Input data for `Notification` hook events. ```python class NotificationHookInput(BaseHookInput): hook_event_name: Literal["Notification"] message: str title: NotRequired[str] notification_type: str ``` | Field | Type | Description | |:--------------------|:--------------------------|:-----------------------------| | `hook_event_name` | `Literal["Notification"]` | Always “Notification” | | `message` | `str` | Notification message content | | `title` | `str` (optional) | Notification title | | `notification_type` | `str` | Type of notification | [​](#subagentstarthookinput) `SubagentStartHookInput` Input data for `SubagentStart` hook events. ```python class SubagentStartHookInput(BaseHookInput): hook_event_name: Literal["SubagentStart"] agent_id: str agent_type: str ``` | Field | Type | Description | |:------------------|:---------------------------|:-----------------------------------| | `hook_event_name` | `Literal["SubagentStart"]` | Always “SubagentStart” | | `agent_id` | `str` | Unique identifier for the subagent | | `agent_type` | `str` | Type of the subagent | [​](#permissionrequesthookinput) `PermissionRequestHookInput` Input data for `PermissionRequest` hook events. Allows hooks to handle permission decisions programmatically. ```python class PermissionRequestHookInput(BaseHookInput): hook_event_name: Literal["PermissionRequest"] tool_name: str tool_input: dict[str, Any] permission_suggestions: NotRequired[list[Any]] agent_id: NotRequired[str] agent_type: NotRequired[str] ``` | Field | Type | Description | |:-------------------------|:-------------------------------|:-------------------------------------------------------------------| | `hook_event_name` | `Literal["PermissionRequest"]` | Always “PermissionRequest” | | `tool_name` | `str` | Name of the tool requesting permission | | `tool_input` | `dict[str, Any]` | Input parameters for the tool | | `permission_suggestions` | `list[Any]` (optional) | Suggested permission updates from the CLI | | `agent_id` | `str` (optional) | Subagent identifier, present when the hook fires inside a subagent | | `agent_type` | `str` (optional) | Subagent type, present when the hook fires inside a subagent | [​](#hookjsonoutput) `HookJSONOutput` Union type for hook callback return values. ```python HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput ``` [​](#synchookjsonoutput) `SyncHookJSONOutput` Synchronous hook output with control and decision fields. ```python class SyncHookJSONOutput(TypedDict): # Control fields continue_: NotRequired[bool] # Whether to proceed (default: True) suppressOutput: NotRequired[bool] # Hide stdout from transcript stopReason: NotRequired[str] # Message when continue is False # Decision fields decision: NotRequired[Literal["block"]] systemMessage: NotRequired[str] # Warning message for user reason: NotRequired[str] # Feedback for Claude # Hook-specific output hookSpecificOutput: NotRequired[HookSpecificOutput] ``` Use `continue_` (with underscore) in Python code. It is automatically converted to `continue` when sent to the CLI. [​](#hookspecificoutput) `HookSpecificOutput` A `TypedDict` containing the hook event name and event-specific fields. The shape depends on the `hookEventName` value. For full details on available fields per hook event, see [Control execution with hooks](/docs/en/agent-sdk/hooks#outputs). A discriminated union of event-specific output types. The `hookEventName` field determines which fields are valid. ```python class PreToolUseHookSpecificOutput(TypedDict): hookEventName: Literal["PreToolUse"] permissionDecision: NotRequired[Literal["allow", "deny", "ask", "defer"]] permissionDecisionReason: NotRequired[str] updatedInput: NotRequired[dict[str, Any]] additionalContext: NotRequired[str] class PostToolUseHookSpecificOutput(TypedDict): hookEventName: Literal["PostToolUse"] additionalContext: NotRequired[str] updatedToolOutput: NotRequired[Any] updatedMCPToolOutput: NotRequired[Any] # Deprecated: use updatedToolOutput, which works for all tools class PostToolUseFailureHookSpecificOutput(TypedDict): hookEventName: Literal["PostToolUseFailure"] additionalContext: NotRequired[str] class UserPromptSubmitHookSpecificOutput(TypedDict): hookEventName: Literal["UserPromptSubmit"] additionalContext: NotRequired[str] class NotificationHookSpecificOutput(TypedDict): hookEventName: Literal["Notification"] additionalContext: NotRequired[str] class SubagentStartHookSpecificOutput(TypedDict): hookEventName: Literal["SubagentStart"] additionalContext: NotRequired[str] class PermissionRequestHookSpecificOutput(TypedDict): hookEventName: Literal["PermissionRequest"] decision: dict[str, Any] HookSpecificOutput = ( PreToolUseHookSpecificOutput | PostToolUseHookSpecificOutput | PostToolUseFailureHookSpecificOutput | UserPromptSubmitHookSpecificOutput | NotificationHookSpecificOutput | SubagentStartHookSpecificOutput | PermissionRequestHookSpecificOutput ) ``` [​](#asynchookjsonoutput) `AsyncHookJSONOutput` Async hook output that defers hook execution. ```python class AsyncHookJSONOutput(TypedDict): async_: Literal[True] # Set to True to defer execution asyncTimeout: NotRequired[int] # Timeout in milliseconds ``` Use `async_` (with underscore) in Python code. It is automatically converted to `async` when sent to the CLI. [​](#hook-usage-example) Hook Usage Example This example registers two hooks: one that blocks dangerous bash commands like `rm -rf /`, and another that logs all tool usage for auditing. The security hook only runs on Bash commands (via the `matcher`), while the logging hook runs on all tools. ```python import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, HookContext from typing import Any async def validate_bash_command( input_data: dict[str, Any], tool_use_id: str | None, context: HookContext ) -> dict[str, Any]: """Validate and potentially block dangerous bash commands.""" if input_data["tool_name"] == "Bash": command = input_data["tool_input"].get("command", "") if "rm -rf /" in command: return { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Dangerous command blocked", } } return {} async def log_tool_use( input_data: dict[str, Any], tool_use_id: str | None, context: HookContext ) -> dict[str, Any]: """Log all tool usage for auditing.""" print(f"Tool used: {input_data.get('tool_name')}") return {} options = ClaudeAgentOptions( hooks={ "PreToolUse": [ HookMatcher( matcher="Bash", hooks=[validate_bash_command], timeout=120 ), # 2 min for validation HookMatcher( hooks=[log_tool_use] ), # Applies to all tools (per-event default timeout) ], "PostToolUse": [HookMatcher(hooks=[log_tool_use])], } ) async def main(): async for message in query(prompt="Analyze this codebase", options=options): print(message) asyncio.run(main()) ``` [​](#tool-input/output-types) Tool Input/Output Types Documentation 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. [​](#agent) Agent **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. **Input:** ```python { "description": str, # A short (3-5 word) description of the task "prompt": str, # The task for the agent to perform "subagent_type": str | None, # The type of specialized agent to use "model": "sonnet" | "opus" | "haiku" | "fable" | None, # Model override for this agent "run_in_background": bool | None, # Agents run in the background by default; set to False to run synchronously "name": str | None, # Name for the spawned agent "team_name": str | None, # Deprecated; ignored "mode": "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan" | None, # Deprecated; ignored. Subagents inherit the parent session's permission mode; agent-definition frontmatter may override it "isolation": "worktree" | "remote" | None, # Isolation mode for the agent's changes } ``` Launches a new agent to handle complex, multi-step tasks autonomously. **Output (status: `"completed"`):** ```python { "status": "completed", "agentId": str, # ID of the agent that ran "agentType": str | None, # The subagent type that handled the task "content": [ # Result content blocks { "type": "text", "text": str, "citations": list | None, } ], "resolvedModel": str | None, # Model the subagent started on "modelsUsed": list[str] | None, # Models used in order, with consecutive repeats collapsed "totalToolUseCount": int, # Number of tool calls the agent made "totalDurationMs": int, # Execution duration in milliseconds "totalTokens": int, # Total tokens used "usage": { # Token usage statistics "input_tokens": int, "output_tokens": int, "cache_creation_input_tokens": int | None, "cache_read_input_tokens": int | None, "server_tool_use": {"web_search_requests": int, "web_fetch_requests": int} | None, "service_tier": str | None, "cache_creation": {"ephemeral_1h_input_tokens": int, "ephemeral_5m_input_tokens": int} | None, "inference_geo": str | None, "speed": str | None, "iterations": Any | None, }, "toolStats": { # Aggregate tool activity for the run "readCount": int, "searchCount": int, "bashCount": int, "editFileCount": int, "linesAdded": int, "linesRemoved": int, "otherToolCount": int, "frameCount": int | None, } | None, "prompt": str, # The prompt the agent ran "worktreePath": str | None, # Present for worktree-isolated runs "worktreeBranch": str | None, # Present for worktree-isolated runs } ``` **Output (status: `"async_launched"`):** ```python { "status": "async_launched", "isAsync": bool | None, # True on background launches "agentId": str, # ID of the launched agent "description": str, # The task description "resolvedModel": str | None, # Model in use at the backgrounding transition "modelsUsed": list[str] | None, # Models used before backgrounding, in order, with consecutive repeats collapsed "prompt": str, # The prompt the agent runs "outputFile": str, # File path where the agent's output is written "canReadOutputFile": bool | None, # Whether the output file can be read directly } ``` **Output (status: `"remote_launched"`):** ```python { "status": "remote_launched", "taskId": str, # ID of the remote task "sessionUrl": str, # Link to the remote cloud session "description": str, # The task description "prompt": str, # The prompt the agent runs "outputFile": str, # File path where the agent's output is written } ``` Returns the result from the subagent. The output is discriminated on the `status` field: `"completed"` for finished tasks, `"async_launched"` for background tasks, and `"remote_launched"` for tasks Claude Code dispatched to a remote cloud session, where `sessionUrl` links to that session and `taskId` identifies it. Worktree-isolated runs include `worktreePath` and `worktreeBranch` on the `completed` variant. On the `completed` variant, `resolvedModel` names the model the subagent started on, which can differ from the requested `model` input when [`availableModels`](/docs/en/model-config#restrict-model-selection) or another override applies. This field requires Claude Code v2.1.174 or later. On the `async_launched` variant, `resolvedModel` names the model in use when the agent moved to the background, so a swap that happened before backgrounding is reflected there. The `modelsUsed` field on both variants lists the models used in order, with consecutive repeats collapsed; it’s set only when the model was swapped mid-run. `modelsUsed` and the backgrounding-time `resolvedModel` behavior require Claude Code v2.1.212 or later. [​](#askuserquestion) AskUserQuestion **Tool name:** `AskUserQuestion` Asks the user clarifying questions during execution. See [Handle approvals and user input](/docs/en/agent-sdk/user-input#handle-clarifying-questions) for usage details. **Input:** ```python { "questions": [ # Questions to ask the user (1-4 questions) { "question": str, # The complete question to ask the user "header": str, # Very short label displayed as a chip/tag (max 12 chars) "options": [ # The available choices (2-4 options) { "label": str, # Display text for this option (1-5 words) "description": str, # Explanation of what this option means "preview": str | None, # Preview content rendered when the option is focused } ], "multiSelect": bool, # Set to true to allow multiple selections } ], "answers": dict[str, str] | None, # User answers populated by the permission system. Multi-select # answers are a comma-joined string of the selected labels; a # list of labels is accepted on input and coerced to that form "annotations": dict[str, dict] | None, # Per-question annotations from the user, keyed by question text. # Each value can carry "preview" (the selected option's preview # content) and "notes" (free-text notes on the selection) "metadata": dict | None, # Analytics metadata, such as {"source": "remember"}; not displayed to the user } ``` **Output:** ```python { "questions": [ # The questions that were asked { "question": str, "header": str, "options": [{"label": str, "description": str, "preview": str | None}], "multiSelect": bool, } ], "answers": dict[str, str], # Maps question text to answer string # Multi-select answers are comma-separated "response": str | None, # Freeform reply typed instead of answering the questions; when set, # Claude receives "The user responded: ..." in place of the answer list "annotations": dict[str, dict] | None, # Per-question "preview" and "notes" from the user's selections "afkTimeoutMs": int | None, # Set when the dialog auto-resolved after this many milliseconds of user inactivity; absent when the user answered } ``` [​](#bash) Bash **Tool name:** `Bash` **Input:** ```python { "command": str, # The command to execute "timeout": int | None, # Optional timeout in milliseconds (max 600000; higher values are clamped to the max) "description": str | None, # Clear, concise description (5-10 words) "run_in_background": bool | None, # Set to true to run in background } ``` **Output:** ```python { "output": str, # Combined stdout and stderr output "exitCode": int, # Exit code of the command "killed": bool | None, # Whether command was killed due to timeout "shellId": str | None, # Shell ID for background processes } ``` [​](#monitor) Monitor **Tool name:** `Monitor` Runs a background source and delivers each event to Claude so it can react without polling: `command` runs a script and emits one event per stdout line, and `ws` opens a WebSocket and emits one event per text frame. Provide exactly one of `command` or `ws`. When Monitor runs a command, it follows the same permission rules as Bash; a WebSocket watch prompts for approval separately. The `ws` source requires Claude Code v2.1.195 or later. See the [Monitor tool reference](/docs/en/tools-reference#monitor-tool) for behavior and provider availability. **Input:** ```python { "command": str | None, # Shell script; each stdout line is an event, exit ends the watch "ws": dict | None, # WebSocket source: {"url": str, "protocols": list[str] | None}; each text frame is an event "description": str, # Short description shown in notifications "timeout_ms": int | None, # Kill after this deadline (default 300000, max 3600000) "persistent": bool | None, # Run for the lifetime of the session; stop with TaskStop } ``` **Output:** ```python { "taskId": str, # ID of the background monitor task "timeoutMs": int, # Timeout deadline in milliseconds (0 when persistent) "persistent": bool | None, # True when running until TaskStop or session end } ``` [​](#edit) Edit **Tool name:** `Edit` **Input:** ```python { "file_path": str, # The absolute path to the file to modify "old_string": str, # The text to replace "new_string": str, # The text to replace it with "replace_all": bool | None, # Replace all occurrences (default False) } ``` **Output:** ```python { "message": str, # Confirmation message "replacements": int, # Number of replacements made "file_path": str, # File path that was edited } ``` [​](#read) Read **Tool name:** `Read` **Input:** ```python { "file_path": str, # The absolute path to the file to read "offset": int | None, # The line number to start reading from "limit": int | None, # The number of lines to read } ``` **Output (Text files):** ```python { "content": str, # File contents with line numbers "total_lines": int, # Total number of lines in file "lines_returned": int, # Lines actually returned } ``` **Output (Images):** ```python { "image": str, # Base64 encoded image data "mime_type": str, # Image MIME type "file_size": int, # File size in bytes } ``` [​](#write) Write **Tool name:** `Write` **Input:** ```python { "file_path": str, # The absolute path to the file to write "content": str, # The content to write to the file } ``` **Output:** ```python { "message": str, # Success message "bytes_written": int, # Number of bytes written "file_path": str, # File path that was written } ``` [​](#glob) Glob **Tool name:** `Glob` **Input:** ```python { "pattern": str, # The glob pattern to match files against "path": str | None, # The directory to search in (defaults to cwd) } ``` **Output:** ```python { "matches": list[str], # Array of matching file paths "count": int, # Number of matches found "search_path": str, # Search directory used } ``` [​](#grep) Grep **Tool name:** `Grep` **Input:** ```python { "pattern": str, # The regular expression pattern "path": str | None, # File or directory to search in "glob": str | None, # Glob pattern to filter files "type": str | None, # File type to search "output_mode": str | None, # "content", "files_with_matches", or "count" "-i": bool | None, # Case insensitive search "-n": bool | None, # Show line numbers "-B": int | None, # Lines to show before each match "-A": int | None, # Lines to show after each match "-C": int | None, # Lines to show before and after "head_limit": int | None, # Limit output to first N lines/entries "multiline": bool | None, # Enable multiline mode } ``` **Output (content mode):** ```python { "matches": [ { "file": str, "line_number": int | None, "line": str, "before_context": list[str] | None, "after_context": list[str] | None, } ], "total_matches": int, } ``` **Output (files_with_matches mode):** ```python { "files": list[str], # Files containing matches "count": int, # Number of files with matches } ``` [​](#notebookedit) NotebookEdit **Tool name:** `NotebookEdit` **Input:** ```python { "notebook_path": str, # Absolute path to the Jupyter notebook "cell_id": str | None, # The ID of the cell to edit "new_source": str, # The new source for the cell "cell_type": "code" | "markdown" | None, # The type of the cell "edit_mode": "replace" | "insert" | "delete" | None, # Edit operation type } ``` **Output:** ```python { "message": str, # Success message "edit_type": "replaced" | "inserted" | "deleted", # Type of edit performed "cell_id": str | None, # Cell ID that was affected "total_cells": int, # Total cells in notebook after edit } ``` [​](#webfetch) WebFetch **Tool name:** `WebFetch` **Input:** ```python { "url": str, # The URL to fetch content from "prompt": str, # The prompt to run on the fetched content } ``` **Output:** ```python { "bytes": int, # Size of the fetched content in bytes "code": int, # HTTP response code "codeText": str, # HTTP response code text "result": str, # Processed result from applying the prompt to the content "durationMs": int, # Time to fetch and process the content, in milliseconds "url": str, # URL that was fetched } ``` [​](#websearch) WebSearch **Tool name:** `WebSearch` **Input:** ```python { "query": str, # The search query to use "allowed_domains": list[str] | None, # Only include results from these domains "blocked_domains": list[str] | None, # Never include results from these domains } ``` **Output:** ```python { "query": str, # The search query "results": list[str | {"tool_use_id": str, "content": list[{"title": str, "url": str}]}], "durationSeconds": float, # Search duration in seconds } ``` [​](#todowrite) TodoWrite **Tool name:** `TodoWrite` As of Claude Code v2.1.142, `TodoWrite` is disabled by default. Use `TaskCreate`, `TaskGet`, `TaskUpdate`, and `TaskList` instead. See [Migrate to Task tools](/docs/en/agent-sdk/todo-tracking#migrate-to-task-tools) to update your monitoring code, or set `CLAUDE_CODE_ENABLE_TASKS=0` to revert to `TodoWrite`. **Input:** ```python { "todos": [ { "content": str, # The task description "status": "pending" | "in_progress" | "completed", # Task status "activeForm": str, # Active form of the description } ] } ``` **Output:** ```python { "message": str, # Success message "stats": {"total": int, "pending": int, "in_progress": int, "completed": int}, } ``` [​](#taskcreate) TaskCreate **Tool name:** `TaskCreate` **Input:** ```python { "subject": str, # Short task title "description": str, # Detailed task body "activeForm": str | None, # Present-tense label shown while in progress "metadata": dict | None, # Arbitrary caller metadata } ``` **Output:** ```python { "task": {"id": str, "subject": str}, # Created task with assigned ID } ``` [​](#taskupdate) TaskUpdate **Tool name:** `TaskUpdate` **Input:** ```python { "taskId": str, # ID of the task to patch "status": Literal["pending", "in_progress", "completed", "deleted"] | None, "subject": str | None, "description": str | None, "activeForm": str | None, "addBlocks": list[str] | None, # Task IDs this task now blocks "addBlockedBy": list[str] | None, # Task IDs that now block this task "owner": str | None, "metadata": dict | None, } ``` **Output:** ```python { "success": bool, "taskId": str, "updatedFields": list[str], # Names of fields that changed "error": str | None, "statusChange": {"from": str, "to": str} | None, } ``` [​](#taskget) TaskGet **Tool name:** `TaskGet` **Input:** ```python { "taskId": str, # ID of the task to read } ``` **Output:** ```python { "task": { "id": str, "subject": str, "description": str, "status": Literal["pending", "in_progress", "completed"], "blocks": list[str], "blockedBy": list[str], } | None, # None when the ID is not found } ``` [​](#tasklist) TaskList **Tool name:** `TaskList` **Input:** ```python {} ``` **Output:** ```python { "tasks": [ { "id": str, "subject": str, "status": Literal["pending", "in_progress", "completed"], "owner": str | None, "blockedBy": list[str], } ], } ``` [​](#taskoutput) TaskOutput **Tool name:** `TaskOutput`. The previous name `BashOutput` is still accepted as an alias. `TaskOutput` is deprecated; prefer `Read` on the task’s output file path. Deprecated since Claude Code v2.1.83. The schemas below remain valid for hooks and permission handlers that encounter the tool. **Input:** ```python { "task_id": str, # The task ID to get output from "block": bool, # Whether to wait for completion (default True) "timeout": int, # Max wait time in ms (default 30000) } ``` **Output:** ```python { "retrieval_status": "success" | "timeout" | "not_ready", # Whether the output was retrieved "task": dict | None, # Task details: task_id, task_type, status, description, output, plus type-specific fields such as exitCode } ``` [​](#taskstop) TaskStop **Tool name:** `TaskStop`. The previous names `KillShell` and `KillBash` are still accepted as aliases. **Input:** ```python { "task_id": str | None, # The ID of the background task to stop "shell_id": str | None, # Deprecated: use task_id instead } ``` **Output:** ```python { "message": str, # Status message about the operation "task_id": str, # The ID of the task that was stopped "task_type": str, # The type of the task that was stopped "command": str | None, # The command or description of the stopped task } ``` [​](#exitplanmode) ExitPlanMode **Tool name:** `ExitPlanMode` **Input:** ```python { "plan": str # The plan to run by the user for approval } ``` **Output:** ```python { "message": str, # Confirmation message "approved": bool | None, # Whether user approved the plan } ``` [​](#listmcpresources) ListMcpResources **Tool name:** `ListMcpResourcesTool` **Input:** ```python { "server": str | None # Optional server name to filter resources by } ``` **Output:** ```python { "resources": [ { "uri": str, "name": str, "description": str | None, "mimeType": str | None, "server": str, } ], "total": int, } ``` [​](#readmcpresource) ReadMcpResource **Tool name:** `ReadMcpResourceTool` **Input:** ```python { "server": str, # The MCP server name "uri": str, # The resource URI to read } ``` **Output:** ```python { "contents": [ {"uri": str, "mimeType": str | None, "text": str | None, "blob": str | None} ], "server": str, } ``` [​](#advanced-features-with-claudesdkclient) Advanced Features with ClaudeSDKClient [​](#building-a-continuous-conversation-interface) Building a Continuous Conversation Interface ```python from claude_agent_sdk import ( ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock, ) import asyncio class ConversationSession: """Maintains a single conversation session with Claude.""" def __init__(self, options: ClaudeAgentOptions | None = None): self.client = ClaudeSDKClient(options) self.turn_count = 0 async def start(self): await self.client.connect() print("Starting conversation session. Claude will remember context.") print( "Commands: 'exit' to quit, 'interrupt' to stop current task, 'new' for new session" ) while True: user_input = input(f"\n[Turn {self.turn_count + 1}] You: ") if user_input.lower() == "exit": break elif user_input.lower() == "interrupt": await self.client.interrupt() print("Task interrupted!") continue elif user_input.lower() == "new": # Disconnect and reconnect for a fresh session await self.client.disconnect() await self.client.connect() self.turn_count = 0 print("Started new conversation session (previous context cleared)") continue # Send message - the session retains all previous messages await self.client.query(user_input) self.turn_count += 1 # Process response print(f"[Turn {self.turn_count}] Claude: ", end="") async for message in self.client.receive_response(): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(block.text, end="") print() # New line after response await self.client.disconnect() print(f"Conversation ended after {self.turn_count} turns.") async def main(): options = ClaudeAgentOptions( allowed_tools=["Read", "Write", "Bash"], permission_mode="acceptEdits" ) session = ConversationSession(options) await session.start() # Example conversation: # Turn 1 - You: "Create a file called hello.py" # Turn 1 - Claude: "I'll create a hello.py file for you..." # Turn 2 - You: "What's in that file?" # Turn 2 - Claude: "The hello.py file I just created contains..." (remembers!) # Turn 3 - You: "Add a main function to it" # Turn 3 - Claude: "I'll add a main function to hello.py..." (knows which file!) asyncio.run(main()) ``` [​](#using-hooks-for-behavior-modification) Using Hooks for Behavior Modification ```python from claude_agent_sdk import ( ClaudeSDKClient, ClaudeAgentOptions, HookMatcher, HookContext, ) import asyncio from typing import Any async def pre_tool_logger( input_data: dict[str, Any], tool_use_id: str | None, context: HookContext ) -> dict[str, Any]: """Log all tool usage before execution.""" tool_name = input_data.get("tool_name", "unknown") print(f"[PRE-TOOL] About to use: {tool_name}") # You can modify or block the tool execution here if tool_name == "Bash" and "rm -rf" in str(input_data.get("tool_input", {})): return { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Dangerous command blocked", } } return {} async def post_tool_logger( input_data: dict[str, Any], tool_use_id: str | None, context: HookContext ) -> dict[str, Any]: """Log results after tool execution.""" tool_name = input_data.get("tool_name", "unknown") print(f"[POST-TOOL] Completed: {tool_name}") return {} async def user_prompt_modifier( input_data: dict[str, Any], tool_use_id: str | None, context: HookContext ) -> dict[str, Any]: """Add context to user prompts.""" original_prompt = input_data.get("prompt", "") # Add a timestamp as additional context for Claude to see from datetime import datetime timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S") return { "hookSpecificOutput": { "hookEventName": "UserPromptSubmit", "additionalContext": f"[Submitted at {timestamp}] Original prompt: {original_prompt}", } } async def main(): options = ClaudeAgentOptions( hooks={ "PreToolUse": [ HookMatcher(hooks=[pre_tool_logger]), HookMatcher(matcher="Bash", hooks=[pre_tool_logger]), ], "PostToolUse": [HookMatcher(hooks=[post_tool_logger])], "UserPromptSubmit": [HookMatcher(hooks=[user_prompt_modifier])], }, allowed_tools=["Read", "Write", "Bash"], ) async with ClaudeSDKClient(options=options) as client: await client.query("List files in current directory") async for message in client.receive_response(): # Hooks will automatically log tool usage pass asyncio.run(main()) ``` [​](#real-time-progress-monitoring) Real-time Progress Monitoring ```python from claude_agent_sdk import ( ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, ToolUseBlock, ToolResultBlock, TextBlock, ) import asyncio async def monitor_progress(): options = ClaudeAgentOptions( allowed_tools=["Write", "Bash"], permission_mode="acceptEdits" ) async with ClaudeSDKClient(options=options) as client: await client.query("Create 5 Python files with different sorting algorithms") # Monitor progress in real-time async for message in client.receive_response(): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, ToolUseBlock): if block.name == "Write": file_path = block.input.get("file_path", "") print(f"Creating: {file_path}") elif isinstance(block, ToolResultBlock): print("Completed tool execution") elif isinstance(block, TextBlock): print(f"Claude says: {block.text[:100]}...") print("Task completed!") asyncio.run(monitor_progress()) ``` [​](#example-usage) Example Usage [​](#basic-file-operations-using-query) Basic file operations (using query) ```python from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock import asyncio async def create_project(): options = ClaudeAgentOptions( allowed_tools=["Read", "Write", "Bash"], permission_mode="acceptEdits", ) async for message in query( prompt="Create a Python project structure with setup.py", options=options ): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, ToolUseBlock): print(f"Using tool: {block.name}") asyncio.run(create_project()) ``` [​](#error-handling) Error handling ```python import asyncio from claude_agent_sdk import query, CLINotFoundError, ProcessError, CLIJSONDecodeError async def main(): try: async for message in query(prompt="Hello"): print(message) except CLINotFoundError: print( "Claude Code CLI not found. Try reinstalling: pip install --force-reinstall claude-agent-sdk" ) except ProcessError as e: print(f"Process failed with exit code: {e.exit_code}") except CLIJSONDecodeError as e: print(f"Failed to parse response: {e}") # A single-shot query() raises a plain Exception after yielding an error result except Exception as e: print(f"Query ended with an error result: {e}") asyncio.run(main()) ``` [​](#streaming-mode-with-client) Streaming mode with client ```python from claude_agent_sdk import ClaudeSDKClient import asyncio async def interactive_session(): async with ClaudeSDKClient() as client: # Send initial message await client.query("What's the weather like?") # Process responses async for msg in client.receive_response(): print(msg) # Send follow-up await client.query("Tell me more about that") # Process follow-up response async for msg in client.receive_response(): print(msg) asyncio.run(interactive_session()) ``` [​](#using-custom-tools-with-claudesdkclient) Using custom tools with ClaudeSDKClient ```python from claude_agent_sdk import ( ClaudeSDKClient, ClaudeAgentOptions, tool, create_sdk_mcp_server, AssistantMessage, TextBlock, ) import asyncio from typing import Any # Define custom tools with @tool decorator @tool("calculate", "Perform mathematical calculations", {"expression": str}) async def calculate(args: dict[str, Any]) -> dict[str, Any]: try: result = eval(args["expression"], {"__builtins__": {}}) return {"content": [{"type": "text", "text": f"Result: {result}"}]} except Exception as e: return { "content": [{"type": "text", "text": f"Error: {str(e)}"}], "is_error": True, } @tool("get_time", "Get current time", {}) async def get_time(args: dict[str, Any]) -> dict[str, Any]: from datetime import datetime current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S") return {"content": [{"type": "text", "text": f"Current time: {current_time}"}]} async def main(): # Create SDK MCP server with custom tools my_server = create_sdk_mcp_server( name="utilities", version="1.0.0", tools=[calculate, get_time] ) # Configure options with the server options = ClaudeAgentOptions( mcp_servers={"utils": my_server}, allowed_tools=["mcp__utils__calculate", "mcp__utils__get_time"], ) # Use ClaudeSDKClient for interactive tool usage async with ClaudeSDKClient(options=options) as client: await client.query("What's 123 * 456?") # Process calculation response async for message in client.receive_response(): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(f"Calculation: {block.text}") # Follow up with time query await client.query("What time is it now?") async for message in client.receive_response(): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(f"Time: {block.text}") asyncio.run(main()) ``` [​](#sandbox-configuration) Sandbox Configuration [​](#sandboxsettings) `SandboxSettings` Configuration for sandbox behavior. Use this to enable command sandboxing and configure network restrictions programmatically. ```python class SandboxSettings(TypedDict, total=False): enabled: bool autoAllowBashIfSandboxed: bool excludedCommands: list[str] allowUnsandboxedCommands: bool network: SandboxNetworkConfig ignoreViolations: SandboxIgnoreViolations enableWeakerNestedSandbox: bool ``` | Property | Type | Default | Description | |:----------------------------|:------------------------------------------------------|:--------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `enabled` | `bool` | `False` | Enable sandbox mode for command execution | | `autoAllowBashIfSandboxed` | `bool` | `True` | Auto-approve bash commands when sandbox is enabled | | `excludedCommands` | `list[str]` | `[]` | Commands that always bypass sandbox restrictions (e.g., `["docker"]`). These run unsandboxed automatically without model involvement | | `allowUnsandboxedCommands` | `bool` | `True` | Allow the model to request running commands outside the sandbox. When `True`, the model can set `dangerouslyDisableSandbox` in tool input, which falls back to the [permissions system](#permissions-fallback-for-unsandboxed-commands) | | `network` | [`SandboxNetworkConfig`](#sandboxnetworkconfig) | `None` | Network-specific sandbox configuration | | `ignoreViolations` | [`SandboxIgnoreViolations`](#sandboxignoreviolations) | `None` | Configure which sandbox violations to ignore | | `enableWeakerNestedSandbox` | `bool` | `False` | Enable a weaker nested sandbox for compatibility | The sandbox depends on platform support and, on Linux, tools like `bubblewrap` and `socat`. By default, when `enabled` is `True` but the sandbox can’t start, commands run unsandboxed with a warning on stderr. This default differs from the TypeScript SDK, where `failIfUnavailable` defaults to `true`.Set `"failIfUnavailable": True` in your sandbox settings to stop instead. The key isn’t declared on `SandboxSettings` yet, but the SDK forwards it to Claude Code, which honors it. `query()` then reports a `ResultMessage` with `subtype="error_during_execution"` and the reason in `errors`. Because this is a single-shot `query()` call, the SDK raises after yielding that error result, so wrap the loop in a try block to continue past it. See [Handle the result](/docs/en/agent-sdk/agent-loop#handle-the-result) for the error contract. [​](#example-usage-2) Example usage ```python import asyncio from claude_agent_sdk import query, ClaudeAgentOptions sandbox_settings = { "enabled": True, "autoAllowBashIfSandboxed": True, "failIfUnavailable": True, "network": {"allowLocalBinding": True}, } async def main(): try: async for message in query( prompt="Build and test my project", options=ClaudeAgentOptions(sandbox=sandbox_settings), ): print(message) except Exception as error: # A single-shot query() raises after yielding an error result, # such as when failIfUnavailable is set and the sandbox can't start. print(f"Session ended with an error: {error}") asyncio.run(main()) ``` **Unix socket security**: The `allowUnixSockets` option can grant access to powerful system services. For example, allowing `/var/run/docker.sock` effectively grants full host system access through the Docker API, bypassing sandbox isolation. Only allow Unix sockets that are strictly necessary and understand the security implications of each. [​](#sandboxnetworkconfig) `SandboxNetworkConfig` Network-specific configuration for sandbox mode. These settings apply to sandboxed Bash commands when `enabled` is `True` in the parent [`SandboxSettings`](#sandboxsettings). They do not restrict the WebFetch tool, which uses [permission rules](/docs/en/permissions#webfetch) instead. ```python class SandboxNetworkConfig(TypedDict, total=False): allowedDomains: list[str] deniedDomains: list[str] allowManagedDomainsOnly: bool allowUnixSockets: list[str] allowAllUnixSockets: bool allowLocalBinding: bool allowMachLookup: list[str] httpProxyPort: int socksProxyPort: int ``` | Property | Type | Default | Description | |:--------------------------|:------------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------| | `allowedDomains` | `list[str]` | `[]` | Domain names that sandboxed processes can access | | `deniedDomains` | `list[str]` | `[]` | Domain names that sandboxed processes cannot access. Takes precedence over `allowedDomains` | | `allowManagedDomainsOnly` | `bool` | `False` | Managed-settings only: when set in managed settings, ignore `allowedDomains` from non-managed settings sources. Has no effect when set via SDK options | | `allowUnixSockets` | `list[str]` | `[]` | Unix socket paths that processes can access (e.g., Docker socket) | | `allowAllUnixSockets` | `bool` | `False` | Allow access to all Unix sockets | | `allowLocalBinding` | `bool` | `False` | Allow processes to bind to local ports (e.g., for dev servers) | | `allowMachLookup` | `list[str]` | `[]` | macOS only: XPC/Mach service names to allow. Supports a trailing wildcard | | `httpProxyPort` | `int` | `None` | HTTP proxy port for network requests | | `socksProxyPort` | `int` | `None` | SOCKS proxy port for network requests | The built-in sandbox proxy enforces the network allowlist based on the requested hostname and does not terminate or inspect TLS traffic, so techniques such as [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) can potentially bypass it. See [Sandboxing security limitations](/docs/en/sandboxing#security-limitations) for details and [Secure deployment](/docs/en/agent-sdk/secure-deployment#traffic-forwarding) for configuring a TLS-terminating proxy. [​](#sandboxignoreviolations) `SandboxIgnoreViolations` Configuration for ignoring specific sandbox violations. ```python class SandboxIgnoreViolations(TypedDict, total=False): file: list[str] network: list[str] ``` | Property | Type | Default | Description | |:----------|:------------|:--------|:--------------------------------------------| | `file` | `list[str]` | `[]` | File path patterns to ignore violations for | | `network` | `list[str]` | `[]` | Network patterns to ignore violations for | [​](#permissions-fallback-for-unsandboxed-commands) Permissions Fallback for Unsandboxed Commands When `allowUnsandboxedCommands` is enabled, the model can request to run commands outside the sandbox by setting `dangerouslyDisableSandbox: True` in the tool input. These requests fall back to the existing permissions system, meaning your `can_use_tool` handler will be invoked, allowing you to implement custom authorization logic. **`excludedCommands` vs `allowUnsandboxedCommands`:** - `excludedCommands`: A static list of commands that always bypass the sandbox automatically (e.g., `["docker"]`). The model has no control over this. - `allowUnsandboxedCommands`: Lets the model decide at runtime whether to request unsandboxed execution by setting `dangerouslyDisableSandbox: True` in the tool input. ```python import asyncio from claude_agent_sdk import ( query, ClaudeAgentOptions, HookMatcher, PermissionResultAllow, PermissionResultDeny, ToolPermissionContext, ) def is_command_authorized(command: str | None) -> bool: # Replace with your own authorization logic return False async def can_use_tool( tool: str, input: dict, context: ToolPermissionContext ) -> PermissionResultAllow | PermissionResultDeny: # Check if the model is requesting to bypass the sandbox if tool == "Bash" and input.get("dangerouslyDisableSandbox"): # The model is requesting to run this command outside the sandbox print(f"Unsandboxed command requested: {input.get('command')}") if is_command_authorized(input.get("command")): return PermissionResultAllow() return PermissionResultDeny( message="Command not authorized for unsandboxed execution" ) return PermissionResultAllow() # Required: dummy hook keeps the stream open for can_use_tool async def dummy_hook(input_data, tool_use_id, context): return {"continue_": True} async def prompt_stream(): yield { "type": "user", "message": {"role": "user", "content": "Deploy my application"}, } async def main(): async for message in query( prompt=prompt_stream(), options=ClaudeAgentOptions( sandbox={ "enabled": True, "allowUnsandboxedCommands": True, # Model can request unsandboxed execution }, permission_mode="default", can_use_tool=can_use_tool, hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]}, ), ): print(message) asyncio.run(main()) ``` This pattern enables you to: - **Audit model requests**: Log when the model requests unsandboxed execution - **Implement allowlists**: Only permit specific commands to run unsandboxed - **Add approval workflows**: Require explicit authorization for privileged operations Commands running with `dangerouslyDisableSandbox: True` have full system access. Ensure your `can_use_tool` handler validates these requests carefully.If `permission_mode` is set to `bypassPermissions` and `allow_unsandboxed_commands` is enabled, the model can autonomously execute commands outside the sandbox without approval prompts (an explicit [`ask` rule](/docs/en/agent-sdk/permissions#how-permissions-are-evaluated) still forces one). Review enterprise hardening guidance before enabling this combination. [​](#see-also) See also - [SDK overview](/docs/en/agent-sdk/overview) - General SDK concepts - [TypeScript SDK reference](/docs/en/agent-sdk/typescript) - TypeScript SDK documentation - [CLI reference](/docs/en/cli-reference) - Command-line interface - [Common workflows](/docs/en/common-workflows) - Step-by-step guides --- ## agent-sdk-reference-typescript-claude-code-docs-2b13ae4354.md ## On this page - [Installation](#installation) - [Compile to a single executable](#compile-to-a-single-executable) - [Functions](#functions) - [query()](#query) - [Parameters](#parameters) - [Returns](#returns) - [startup()](#startup) - [Parameters](#parameters-2) - [Returns](#returns-2) - [Example](#example) - [tool()](#tool) - [Parameters](#parameters-3) - [ToolAnnotations](#toolannotations) - [createSdkMcpServer()](#createsdkmcpserver) - [Parameters](#parameters-4) - [listSessions()](#listsessions) - [Parameters](#parameters-5) - [Return type: SDKSessionInfo](#return-type-sdksessioninfo) - [Example](#example-2) - [getSessionMessages()](#getsessionmessages) - [Parameters](#parameters-6) - [Return type: SessionMessage](#return-type-sessionmessage) - [Example](#example-3) - [getSessionInfo()](#getsessioninfo) - [Parameters](#parameters-7) - [renameSession()](#renamesession) - [Parameters](#parameters-8) - [tagSession()](#tagsession) - [Parameters](#parameters-9) - [resolveSettings()](#resolvesettings) - [Parameters](#parameters-10) - [Return type: ResolvedSettings](#return-type-resolvedsettings) - [Example](#example-4) - [Types](#types) - [Options](#options) - [Handle slow or stalled API responses](#handle-slow-or-stalled-api-responses) - [Query object](#query-object) - [Methods](#methods) - [applyFlagSettings()](#applyflagsettings) - [WarmQuery](#warmquery) - [Methods](#methods-2) - [SDKControlInitializeResponse](#sdkcontrolinitializeresponse) - [SDKControlInterruptResponse](#sdkcontrolinterruptresponse) - [SDKControlGetContextUsageResponse](#sdkcontrolgetcontextusageresponse) - [AgentDefinition](#agentdefinition) - [AgentMcpServerSpec](#agentmcpserverspec) - [SettingSource](#settingsource) - [Default behavior](#default-behavior) - [Why use settingSources](#why-use-settingsources) - [Settings precedence](#settings-precedence) - [PermissionMode](#permissionmode) - [CanUseTool](#canusetool) - [PermissionResult](#permissionresult) - [ToolConfig](#toolconfig) - [McpServerConfig](#mcpserverconfig) - [McpStdioServerConfig](#mcpstdioserverconfig) - [McpSSEServerConfig](#mcpsseserverconfig) - [McpHttpServerConfig](#mcphttpserverconfig) - [McpSdkServerConfigWithInstance](#mcpsdkserverconfigwithinstance) - [McpClaudeAIProxyServerConfig](#mcpclaudeaiproxyserverconfig) - [SdkPluginConfig](#sdkpluginconfig) - [Message Types](#message-types) - [SDKMessage](#sdkmessage) - [SDKAssistantMessage](#sdkassistantmessage) - [SDKUserMessage](#sdkusermessage) - [SDKUserMessageReplay](#sdkusermessagereplay) - [SDKResultMessage](#sdkresultmessage) - [SDKSystemMessage](#sdksystemmessage) - [SDKPartialAssistantMessage](#sdkpartialassistantmessage) - [SDKCompactBoundaryMessage](#sdkcompactboundarymessage) - [SDKInformationalMessage](#sdkinformationalmessage) - [SDKWorkerShuttingDownMessage](#sdkworkershuttingdownmessage) - [SDKPluginInstallMessage](#sdkplugininstallmessage) - [SDKPermissionDeniedMessage](#sdkpermissiondeniedmessage) - [SDKPermissionDenial](#sdkpermissiondenial) - [SDKMessageOrigin](#sdkmessageorigin) - [Peer origin fields](#peer-origin-fields) - [Hook Types](#hook-types) - [HookEvent](#hookevent) - [HookCallback](#hookcallback) - [HookCallbackMatcher](#hookcallbackmatcher) - [HookInput](#hookinput) - [BaseHookInput](#basehookinput) - [PreToolUseHookInput](#pretoolusehookinput) - [PostToolUseHookInput](#posttoolusehookinput) - [PostToolUseFailureHookInput](#posttoolusefailurehookinput) - [PostToolBatchHookInput](#posttoolbatchhookinput) - [PermissionDeniedHookInput](#permissiondeniedhookinput) - [NotificationHookInput](#notificationhookinput) - [UserPromptSubmitHookInput](#userpromptsubmithookinput) - [UserPromptExpansionHookInput](#userpromptexpansionhookinput) - [SessionStartHookInput](#sessionstarthookinput) - [SessionEndHookInput](#sessionendhookinput) - [StopHookInput](#stophookinput) - [StopFailureHookInput](#stopfailurehookinput) - [SubagentStartHookInput](#subagentstarthookinput) - [SubagentStopHookInput](#subagentstophookinput) - [PreCompactHookInput](#precompacthookinput) - [PostCompactHookInput](#postcompacthookinput) - [PermissionRequestHookInput](#permissionrequesthookinput) - [SetupHookInput](#setuphookinput) - [TeammateIdleHookInput](#teammateidlehookinput) - [TaskCreatedHookInput](#taskcreatedhookinput) - [TaskCompletedHookInput](#taskcompletedhookinput) - [ElicitationHookInput](#elicitationhookinput) - [ElicitationResultHookInput](#elicitationresulthookinput) - [ConfigChangeHookInput](#configchangehookinput) - [InstructionsLoadedHookInput](#instructionsloadedhookinput) - [DirectoryAddedHookInput](#directoryaddedhookinput) - [WorktreeCreateHookInput](#worktreecreatehookinput) - [WorktreeRemoveHookInput](#worktreeremovehookinput) - [CwdChangedHookInput](#cwdchangedhookinput) - [FileChangedHookInput](#filechangedhookinput) - [MessageDisplayHookInput](#messagedisplayhookinput) - [HookJSONOutput](#hookjsonoutput) - [AsyncHookJSONOutput](#asynchookjsonoutput) - [SyncHookJSONOutput](#synchookjsonoutput) - [Tool Input Types](#tool-input-types) - [ToolInputSchemas](#toolinputschemas) - [Agent](#agent) - [AskUserQuestion](#askuserquestion) - [Bash](#bash) - [Monitor](#monitor) - [TaskOutput](#taskoutput) - [Edit](#edit) - [Read](#read) - [Write](#write) - [Glob](#glob) - [Grep](#grep) - [TaskStop](#taskstop) - [NotebookEdit](#notebookedit) - [WebFetch](#webfetch) - [WebSearch](#websearch) - [Workflow](#workflow) - [TodoWrite](#todowrite) - [TaskCreate](#taskcreate) - [TaskUpdate](#taskupdate) - [TaskGet](#taskget) - [TaskList](#tasklist) - [ExitPlanMode](#exitplanmode) - [ListMcpResources](#listmcpresources) - [ReadMcpResource](#readmcpresource) - [EnterWorktree](#enterworktree) - [ExitWorktree](#exitworktree) - [EnterPlanMode](#enterplanmode) - [CronCreate](#croncreate) - [CronDelete](#crondelete) - [CronList](#cronlist) - [ScheduleWakeup](#schedulewakeup) - [RemoteTrigger](#remotetrigger) - [PushNotification](#pushnotification) - [REPL](#repl) - [ReportFindings](#reportfindings) - [Artifact](#artifact) - [Projects](#projects) - [ReadMcpResourceDir](#readmcpresourcedir) - [RefreshMcpTools](#refreshmcptools) - [ShowOnboardingRolePicker](#showonboardingrolepicker) - [McpInput](#mcpinput) - [Tool Output Types](#tool-output-types) - [ToolOutputSchemas](#tooloutputschemas) - [Agent](#agent-2) - [AskUserQuestion](#askuserquestion-2) - [Bash](#bash-2) - [Monitor](#monitor-2) - [Edit](#edit-2) - [Read](#read-2) - [Write](#write-2) - [Glob](#glob-2) - [Grep](#grep-2) - [TaskStop](#taskstop-2) - [NotebookEdit](#notebookedit-2) - [WebFetch](#webfetch-2) - [WebSearch](#websearch-2) - [Workflow](#workflow-2) - [TodoWrite](#todowrite-2) - [TaskCreate](#taskcreate-2) - [TaskUpdate](#taskupdate-2) - [TaskGet](#taskget-2) - [TaskList](#tasklist-2) - [ExitPlanMode](#exitplanmode-2) - [ListMcpResources](#listmcpresources-2) - [ReadMcpResource](#readmcpresource-2) - [EnterWorktree](#enterworktree-2) - [ExitWorktree](#exitworktree-2) - [EnterPlanMode](#enterplanmode-2) - [CronCreate](#croncreate-2) - [CronDelete](#crondelete-2) - [CronList](#cronlist-2) - [ScheduleWakeup](#schedulewakeup-2) - [RemoteTrigger](#remotetrigger-2) - [PushNotification](#pushnotification-2) - [REPL](#repl-2) - [ReportFindings](#reportfindings-2) - [Artifact](#artifact-2) - [Projects](#projects-2) - [ReadMcpResourceDir](#readmcpresourcedir-2) - [RefreshMcpTools](#refreshmcptools-2) - [ShowOnboardingRolePicker](#showonboardingrolepicker-2) - [McpOutput](#mcpoutput) - [Permission Types](#permission-types) - [PermissionUpdate](#permissionupdate) - [PermissionBehavior](#permissionbehavior) - [PermissionUpdateDestination](#permissionupdatedestination) - [PermissionRuleValue](#permissionrulevalue) - [Other Types](#other-types) - [ApiKeySource](#apikeysource) - [SdkBeta](#sdkbeta) - [SlashCommand](#slashcommand) - [ModelInfo](#modelinfo) - [AgentInfo](#agentinfo) - [McpServerStatus](#mcpserverstatus) - [McpServerStatusConfig](#mcpserverstatusconfig) - [AccountInfo](#accountinfo) - [ModelUsage](#modelusage) - [ConfigScope](#configscope) - [NonNullableUsage](#nonnullableusage) - [Usage](#usage) - [CallToolResult](#calltoolresult) - [ThinkingConfig](#thinkingconfig) - [SpawnedProcess](#spawnedprocess) - [SpawnOptions](#spawnoptions) - [McpSetServersResult](#mcpsetserversresult) - [RewindFilesResult](#rewindfilesresult) - [SDKStatusMessage](#sdkstatusmessage) - [SDKTaskNotificationMessage](#sdktasknotificationmessage) - [SDKToolUseSummaryMessage](#sdktoolusesummarymessage) - [SDKHookStartedMessage](#sdkhookstartedmessage) - [SDKHookProgressMessage](#sdkhookprogressmessage) - [SDKHookResponseMessage](#sdkhookresponsemessage) - [SDKToolProgressMessage](#sdktoolprogressmessage) - [SDKAuthStatusMessage](#sdkauthstatusmessage) - [SDKTaskStartedMessage](#sdktaskstartedmessage) - [SDKTaskProgressMessage](#sdktaskprogressmessage) - [SDKTaskUpdatedMessage](#sdktaskupdatedmessage) - [SDKBackgroundTasksChangedMessage](#sdkbackgroundtaskschangedmessage) - [SDKThinkingTokensMessage](#sdkthinkingtokensmessage) - [SDKFilesPersistedEvent](#sdkfilespersistedevent) - [SDKRateLimitEvent](#sdkratelimitevent) - [SDKLocalCommandOutputMessage](#sdklocalcommandoutputmessage) - [SDKCommandsChangedMessage](#sdkcommandschangedmessage) - [SDKPromptSuggestionMessage](#sdkpromptsuggestionmessage) - [SDKConversationResetMessage](#sdkconversationresetmessage) - [AbortError](#aborterror) - [Sandbox Configuration](#sandbox-configuration) - [SandboxSettings](#sandboxsettings) - [Example usage](#example-usage) - [SandboxNetworkConfig](#sandboxnetworkconfig) - [SandboxFilesystemConfig](#sandboxfilesystemconfig) - [Permissions Fallback for Unsandboxed Commands](#permissions-fallback-for-unsandboxed-commands) - [See also](#see-also) SDK references # Agent SDK reference - TypeScript Copy pageCopy page Complete API reference for the TypeScript Agent SDK, including all functions, types, and interfaces. Copy pageCopy page [​](#installation) Installation ```python npm install @anthropic-ai/claude-agent-sdk ``` The SDK bundles a native Claude Code binary for your platform as an optional dependency such as `@anthropic-ai/claude-agent-sdk-darwin-arm64`. You don’t need to install Claude Code separately. The SDK version tracks the bundled Claude Code version: SDK v0.3.191 bundles Claude Code v2.1.191, so a feature on this page that requires a Claude Code version needs the SDK release with the same patch number or later. If your package manager skips optional dependencies, the SDK throws `Native CLI binary for not found`; set [`pathToClaudeCodeExecutable`](#options) to a separately installed `claude` binary instead. [​](#compile-to-a-single-executable) Compile to a single executable When you compile your application into a single-file executable with `bun build --compile`, the SDK cannot resolve the bundled CLI binary at runtime. `require.resolve` does not work inside the compiled executable’s `$bunfs` virtual filesystem, so the SDK throws `Native CLI binary for not found`. To work around this, embed the platform binary as a file asset, extract it to a real path at startup with `extractFromBunfs()`, and pass that path to [`pathToClaudeCodeExecutable`](#options). The `extractFromBunfs()` helper requires `@anthropic-ai/claude-agent-sdk` v0.3.144 or later. The example below builds for macOS on Apple Silicon: ```python import binPath from "@anthropic-ai/claude-agent-sdk-darwin-arm64/claude" with { type: "file" }; import { extractFromBunfs } from "@anthropic-ai/claude-agent-sdk/extract"; import { query } from "@anthropic-ai/claude-agent-sdk"; const cliPath = extractFromBunfs(binPath); for await (const message of query({ prompt: "Hello", options: { pathToClaudeCodeExecutable: cliPath }, })) { console.log(message); } ``` `extractFromBunfs()` copies the embedded binary out of the compiled executable’s virtual filesystem to a per-user temp directory and returns the real path. Outside a compiled executable it returns the input path unchanged, so the same code runs in development without modification. Each compiled executable embeds a single platform’s binary. Match the platform package in the import to your `--target`: - To cross-compile, install the non-matching platform package, for example `npm install @anthropic-ai/claude-agent-sdk-linux-x64 --force`. - On Windows, the binary subpath is `claude.exe`, for example `@anthropic-ai/claude-agent-sdk-win32-x64/claude.exe`. [​](#functions) Functions [​](#query) `query()` The primary function for interacting with Claude Code. Creates an async generator that streams messages as they arrive. ```python function query({ prompt, options }: { prompt: string | AsyncIterable; options?: Options; }): Query; ``` [​](#parameters) Parameters | Parameter | Type | Description | |:----------|:----------------------------------------------------------------|:------------------------------------------------------------------| | `prompt` | `string | AsyncIterable<`[`SDKUserMessage`](#sdkusermessage)`>` | The input prompt as a string or async iterable for streaming mode | | `options` | [`Options`](#options) | Optional configuration object (see Options type below) | [​](#returns) Returns Returns a [`Query`](#query-object) object that extends `AsyncGenerator<`[`SDKMessage`](#sdkmessage)`, void>` with additional methods. [​](#startup) `startup()` Pre-warms the CLI subprocess by spawning it and completing the initialize handshake before a prompt is available. The returned [`WarmQuery`](#warmquery) handle accepts a prompt later and writes it to an already-ready process, so the first `query()` call resolves without paying subprocess spawn and initialization cost inline. ```python function startup(params?: { options?: Options; initializeTimeoutMs?: number; }): Promise; ``` [​](#parameters-2) Parameters | Parameter | Type | Description | |:----------------------|:----------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `options` | [`Options`](#options) | Optional configuration object. Same as the `options` parameter to `query()` | | `initializeTimeoutMs` | `number` | Maximum time in milliseconds to wait for subprocess initialization. Defaults to `60000`. If initialization does not complete in time, the promise rejects with a timeout error | [​](#returns-2) Returns Returns a `Promise<`[`WarmQuery`](#warmquery)`>` that resolves once the subprocess has spawned and completed its initialize handshake. [​](#example) Example Call `startup()` early, for example on application boot, then call `.query()` on the returned handle once a prompt is ready. This moves subprocess spawn and initialization out of the critical path. ```python import { startup } from "@anthropic-ai/claude-agent-sdk"; // Pay startup cost upfront const warm = await startup({ options: { maxTurns: 3 } }); // Later, when a prompt is ready, this is immediate for await (const message of warm.query("What files are here?")) { console.log(message); } ``` [​](#tool) `tool()` Creates a type-safe MCP tool definition for use with SDK MCP servers. ```python function tool( name: string, description: string, inputSchema: Schema, handler: (args: InferShape, extra: unknown) => Promise, extras?: { annotations?: ToolAnnotations; searchHint?: string; alwaysLoad?: boolean } ): SdkMcpToolDefinition; ``` [​](#parameters-3) Parameters | Parameter | Type | Description | |:--------------|:-------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `name` | `string` | The name of the tool | | `description` | `string` | A description of what the tool does | | `inputSchema` | `Schema extends AnyZodRawShape` | Zod schema defining the tool’s input parameters (supports both Zod 3 and Zod 4) | | `handler` | `(args, extra) => Promise<`[`CallToolResult`](#calltoolresult)`>` | Async function that executes the tool logic | | `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)`; searchHint?: string; alwaysLoad?: boolean }` | Optional extras. `annotations` provides MCP behavioral hints to clients. `searchHint` is a one-line capability phrase shown in the deferred-tool list when [tool search](/docs/en/agent-sdk/tool-search) is active. `alwaysLoad: true` keeps this tool’s full schema in the initial prompt instead of deferring it | [​](#toolannotations) `ToolAnnotations` Re-exported from `@modelcontextprotocol/sdk/types.js`. All fields are optional hints; clients should not rely on them for security decisions. | Field | Type | Default | Description | |:------------------|:----------|:------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------| | `title` | `string` | `undefined` | Human-readable title for the tool | | `readOnlyHint` | `boolean` | `false` | If `true`, the tool does not modify its environment | | `destructiveHint` | `boolean` | `true` | If `true`, the tool may perform destructive updates (only meaningful when `readOnlyHint` is `false`) | | `idempotentHint` | `boolean` | `false` | If `true`, repeated calls with the same arguments have no additional effect (only meaningful when `readOnlyHint` is `false`) | | `openWorldHint` | `boolean` | `true` | If `true`, the tool interacts with external entities (for example, web search). If `false`, the tool’s domain is closed (for example, a memory tool) | ```python import { tool } from "@anthropic-ai/claude-agent-sdk"; import { z } from "zod"; const searchTool = tool( "search", "Search the web", { query: z.string() }, async ({ query }) => { return { content: [{ type: "text", text: `Results for: ${query}` }] }; }, { annotations: { readOnlyHint: true, openWorldHint: true } } ); ``` [​](#createsdkmcpserver) `createSdkMcpServer()` Creates an MCP server instance that runs in the same process as your application. ```python function createSdkMcpServer(options: { name: string; version?: string; instructions?: string; tools?: Array>; alwaysLoad?: boolean; }): McpSdkServerConfigWithInstance; ``` [​](#parameters-4) Parameters | Parameter | Type | Description | |:-----------------------|:------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `options.name` | `string` | The name of the MCP server | | `options.version` | `string` | Optional version string | | `options.instructions` | `string` | Optional server instructions, returned from `initialize` and surfaced to the model as an MCP instructions block | | `options.tools` | `Array` | Array of tool definitions created with [`tool()`](#tool) | | `options.alwaysLoad` | `boolean` | When `true`, every tool from this server stays in the initial prompt and is never deferred behind [tool search](/docs/en/agent-sdk/tool-search). Combines with per-tool `alwaysLoad` in [`tool()`](#tool) | [​](#listsessions) `listSessions()` Discovers and lists past sessions with light metadata. Filter by project directory or list sessions across all projects. ```python function listSessions(options?: ListSessionsOptions): Promise; ``` [​](#parameters-5) Parameters | Parameter | Type | Default | Description | |:---------------------------|:----------|:------------|:-----------------------------------------------------------------------------------| | `options.dir` | `string` | `undefined` | Directory to list sessions for. When omitted, returns sessions across all projects | | `options.limit` | `number` | `undefined` | Maximum number of sessions to return | | `options.includeWorktrees` | `boolean` | `true` | When `dir` is inside a git repository, include sessions from all worktree paths | [​](#return-type-sdksessioninfo) Return type: `SDKSessionInfo` | Property | Type | Description | |:---------------|:---------------------|:----------------------------------------------------------------------------| | `sessionId` | `string` | Unique session identifier (UUID) | | `summary` | `string` | Display title: custom title, auto-generated summary, or first prompt | | `lastModified` | `number` | Last modified time in milliseconds since epoch | | `fileSize` | `number | undefined` | Session file size in bytes. Only populated for local JSONL storage | | `customTitle` | `string | undefined` | User-set session title (via `/rename`) | | `firstPrompt` | `string | undefined` | First meaningful user prompt in the session | | `gitBranch` | `string | undefined` | Git branch at the end of the session | | `cwd` | `string | undefined` | Working directory for the session | | `tag` | `string | undefined` | User-set session tag (see [`tagSession()`](#tagsession)) | | `createdAt` | `number | undefined` | Creation time in milliseconds since epoch, from the first entry’s timestamp | [​](#example-2) Example Print the 10 most recent sessions for a project. Results are sorted by `lastModified` descending, so the first item is the newest. Omit `dir` to search across all projects. ```python import { listSessions } from "@anthropic-ai/claude-agent-sdk"; const sessions = await listSessions({ dir: "/path/to/project", limit: 10 }); for (const session of sessions) { console.log(`${session.summary} (${session.sessionId})`); } ``` [​](#getsessionmessages) `getSessionMessages()` Reads user and assistant messages from a past session transcript. ```python function getSessionMessages( sessionId: string, options?: GetSessionMessagesOptions ): Promise; ``` [​](#parameters-6) Parameters | Parameter | Type | Default | Description | |:-----------------|:---------|:------------|:------------------------------------------------------------------------------| | `sessionId` | `string` | required | Session UUID to read (see `listSessions()`) | | `options.dir` | `string` | `undefined` | Project directory to find the session in. When omitted, searches all projects | | `options.limit` | `number` | `undefined` | Maximum number of messages to return | | `options.offset` | `number` | `undefined` | Number of messages to skip from the start | [​](#return-type-sessionmessage) Return type: `SessionMessage` | Property | Type | Description | |:---------------------|:-----------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | `"user" | "assistant"` | Message role | | `uuid` | `string` | Unique message identifier | | `session_id` | `string` | Session this message belongs to | | `message` | `unknown` | Raw message payload from the transcript | | `parent_tool_use_id` | `string | null` | For subagent messages, the `tool_use_id` of the spawning `Agent` tool call. `null` for main-session messages and older sessions | | `parent_agent_id` | `string | null` | For messages from a [nested subagent](/docs/en/sub-agents#let-subagents-spawn-their-own-subagents), the `agentId` of the subagent that spawned it. `null` for main-session messages, messages from top-level subagents, and older sessions. Requires Claude Code v2.1.202 or later | [​](#example-3) Example ```python import { listSessions, getSessionMessages } from "@anthropic-ai/claude-agent-sdk"; const [latest] = await listSessions({ dir: "/path/to/project", limit: 1 }); if (latest) { const messages = await getSessionMessages(latest.sessionId, { dir: "/path/to/project", limit: 20 }); for (const msg of messages) { console.log(`[${msg.type}] ${msg.uuid}`); } } ``` [​](#getsessioninfo) `getSessionInfo()` Reads metadata for a single session by ID without scanning the full project directory. ```python function getSessionInfo( sessionId: string, options?: GetSessionInfoOptions ): Promise; ``` [​](#parameters-7) Parameters | Parameter | Type | Default | Description | |:--------------|:---------|:------------|:-----------------------------------------------------------------------| | `sessionId` | `string` | required | UUID of the session to look up | | `options.dir` | `string` | `undefined` | Project directory path. When omitted, searches all project directories | Returns [`SDKSessionInfo`](#return-type-sdksessioninfo), or `undefined` if the session is not found. [​](#renamesession) `renameSession()` Renames a session by appending a custom-title entry. Repeated calls are safe; the most recent title wins. ```python function renameSession( sessionId: string, title: string, options?: SessionMutationOptions ): Promise; ``` [​](#parameters-8) Parameters | Parameter | Type | Default | Description | |:--------------|:---------|:------------|:-----------------------------------------------------------------------| | `sessionId` | `string` | required | UUID of the session to rename | | `title` | `string` | required | New title. Must be non-empty after trimming whitespace | | `options.dir` | `string` | `undefined` | Project directory path. When omitted, searches all project directories | [​](#tagsession) `tagSession()` Tags a session. Pass `null` to clear the tag. Repeated calls are safe; the most recent tag wins. ```python function tagSession( sessionId: string, tag: string | null, options?: SessionMutationOptions ): Promise; ``` [​](#parameters-9) Parameters | Parameter | Type | Default | Description | |:--------------|:----------------|:------------|:-----------------------------------------------------------------------| | `sessionId` | `string` | required | UUID of the session to tag | | `tag` | `string | null` | required | Tag string, or `null` to clear | | `options.dir` | `string` | `undefined` | Project directory path. When omitted, searches all project directories | [​](#resolvesettings) `resolveSettings()` Resolves the effective Claude Code settings for a given directory using the same merge engine as the CLI, without spawning the Claude CLI. Use it to inspect what configuration a `query()` call would see before invoking one. This function is alpha and its API may change before stabilization. It reads MDM sources, including macOS plist and Windows HKLM/HKCU, for parity with CLI startup, but does not execute the admin-configured `policyHelper` subprocess. The `permissions.defaultMode` field is returned as-is from all tiers including project settings. The trust filter the CLI applies before honoring escalating permission modes is not applied. ```python function resolveSettings( options?: ResolveSettingsOptions ): Promise; ``` [​](#parameters-10) Parameters `resolveSettings()` accepts a single options object. All fields are optional. | Parameter | Type | Default | Description | |:--------------------------------|:--------------------------------------|:----------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `options.cwd` | `string` | `process.cwd()` | Directory to resolve project and local settings relative to | | `options.settingSources` | [`SettingSource`](#settingsource)`[]` | All sources | Which filesystem sources to load. Pass `[]` to skip user, project, and local settings. [Endpoint-managed policy](/docs/en/settings#settings-files) loads in all cases. Server-managed settings are taken from `serverManagedSettings` when the host passes it, or read from the CLI’s on-disk cache otherwise; the snapshot does not fetch them from the network | | `options.managedSettings` | `Settings` | `undefined` | Policy-tier settings supplied by the embedding host. Follows the same rules as [`managedSettings` in `Options`](#options), except that `resolveSettings()` doesn’t execute a configured [`policyHelper`](/docs/en/settings#compute-managed-settings-with-a-policy-helper), so the snapshot can include settings that a live session drops | | `options.serverManagedSettings` | `Settings` | `undefined` | Server-managed settings payload from `/api/claude_code/settings`. Non-restrictive keys pass through unfiltered | [​](#return-type-resolvedsettings) Return type: `ResolvedSettings` `resolveSettings()` returns an object describing the merged settings and the source that contributed each key. | Property | Type | Description | |:-------------|:----------------------------------------------------|:-----------------------------------------------------------------------| | `effective` | `Settings` | Merged settings after applying all enabled sources in precedence order | | `provenance` | `Partial>` | For each top-level key in `effective`, which source supplied the value | | `sources` | `Array<{ source, settings, path?, policyOrigin? }>` | Per-source raw settings, ordered from lowest to highest precedence | [​](#example-4) Example The example below resolves settings for a project directory and prints the source that controls the cleanup period. On a machine where no settings file sets `cleanupPeriodDays`, both printed lines show `undefined` for the value, which is the expected output rather than an error. ```python import { resolveSettings } from "@anthropic-ai/claude-agent-sdk"; const { effective, provenance } = await resolveSettings({ cwd: "/path/to/project", settingSources: ["user", "project", "local"], }); console.log(`Cleanup period: ${effective.cleanupPeriodDays} days`); console.log(`Set by: ${provenance.cleanupPeriodDays?.source}`); ``` [​](#types) Types [​](#options) `Options` Configuration object for the `query()` function. | Property | Type | Default | Description | |:----------------------------------|:--------------------------------------------------------------------------------------------------------|:--------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `abortController` | `AbortController` | `new AbortController()` | Controller for cancelling operations | | `additionalDirectories` | `string[]` | `[]` | Additional directories Claude can access | | `agent` | `string` | `undefined` | Agent name for the main thread. The agent must be defined in the `agents` option or in settings | | `agents` | `Record` | `undefined` | Programmatically define subagents | | `agentProgressSummaries` | `boolean` | `false` | When `true`, generate one-line progress summaries for subagents and forward them on [`task_progress`](#sdktaskprogressmessage) events via the `summary` field. Applies to foreground and background subagents | | `allowDangerouslySkipPermissions` | `boolean` | `false` | Enable bypassing permissions. Required when using `permissionMode: 'bypassPermissions'` | | `allowedTools` | `string[]` | `[]` | Tools to auto-approve without prompting. This does not restrict Claude to only these tools; unlisted tools fall through to `permissionMode` and `canUseTool`. Use `disallowedTools` to block tools. See [Permissions](/docs/en/agent-sdk/permissions#allow-and-deny-rules) | | `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | Enable beta features | | `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | Custom permission function, invoked only when the [permission flow](/docs/en/agent-sdk/permissions#how-permissions-are-evaluated) falls through to a prompt. Not invoked for calls auto-approved by `allowedTools`, allow rules, or `permissionMode`. `AskUserQuestion`, connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools), and MCP tools marked [`requiresUserInteraction`](/docs/en/mcp#require-approval-for-a-specific-tool) reach it even if you’ve allowed them; in `dontAsk` mode these are denied instead. See [`CanUseTool`](#canusetool) for details | | `continue` | `boolean` | `false` | Continue the most recent conversation | | `cwd` | `string` | `process.cwd()` | Current working directory | | `debug` | `boolean` | `false` | Enable debug mode for the Claude Code process | | `debugFile` | `string` | `undefined` | Write debug logs to a specific file path. Implicitly enables debug mode | | `disallowedTools` | `string[]` | `[]` | Tools to deny. A bare name such as `"Bash"` removes the tool from Claude’s context. A scoped rule such as `"Bash(rm *)"` leaves the tool available and denies matching calls in every permission mode, including `bypassPermissions`. See [Permissions](/docs/en/agent-sdk/permissions#allow-and-deny-rules) | | `effort` | `'low' | 'medium' | 'high' | 'xhigh' | 'max'` | Model default | Controls how much effort Claude puts into its response. Works with adaptive thinking to guide thinking depth. See [adjust the effort level](/docs/en/model-config#adjust-effort-level) | | `enableFileCheckpointing` | `boolean` | `false` | Enable file change tracking for rewinding. See [File checkpointing](/docs/en/agent-sdk/file-checkpointing) | | `env` | `Record` | `process.env` | Environment variables. When set, this replaces the subprocess environment instead of merging with `process.env`, so pass `{ ...process.env, YOUR_VAR: 'value' }` to keep inherited variables like `PATH`. See [Handle slow or stalled API responses](#handle-slow-or-stalled-api-responses) for an example of this pattern, and [Environment variables](/docs/en/env-vars) for variables the underlying CLI reads. Set `CLAUDE_AGENT_SDK_CLIENT_APP` to identify your app in the User-Agent header | | `executable` | `'bun' | 'deno' | 'node'` | Auto-detected | JavaScript runtime to use | | `executableArgs` | `string[]` | `[]` | Arguments to pass to the executable | | `extraArgs` | `Record` | `{}` | Additional arguments | | `fallbackModel` | `string` | `undefined` | Model to use if primary fails | | `forkSession` | `boolean` | `false` | When resuming with `resume`, fork to a new session ID instead of continuing the original session | | `forwardSubagentText` | `boolean` | `false` | Forward subagent text and thinking blocks as assistant and user messages with `parent_tool_use_id` set, so consumers can render a nested transcript. By default only `tool_use` and `tool_result` blocks from subagents are emitted. Messages from subagents at every nesting depth are forwarded on Claude Code v2.1.219 and later; before v2.1.219, only messages from depth-1 subagents appeared | | `hooks` | `Partial>` | `{}` | Hook callbacks for events | | `includeHookEvents` | `boolean` | `false` | Include hook lifecycle events for every hook event in the message stream as [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage), and [`SDKHookResponseMessage`](#sdkhookresponsemessage). Lifecycle events for `SessionStart` and `Setup` hooks are always included and don’t need this option | | `includePartialMessages` | `boolean` | `false` | Include partial message events | | `loadTimeoutMs` | `number` | `60000` | *Alpha.* Timeout in milliseconds for each `sessionStore.load()` and `sessionStore.listSubkeys()` call during resume materialization. If the adapter doesn’t settle within this window, the query fails instead of hanging. Ignored when `sessionStore` is not set | | `managedSettings` | `Settings` | `undefined` | Policy-tier settings your host process supplies to the spawned session. On machines with admin-deployed managed settings, Claude Code ignores these unless the admin’s highest-priority managed source sets `parentSettingsBehavior: 'merge'`, and never merges them while a [`policyHelper`](/docs/en/settings#compute-managed-settings-with-a-policy-helper) is configured. Merged values pass through a restrictive-only filter; [Restrict parent settings](/docs/en/claude-apps-gateway#restrict-parent-settings) covers what the filter admits and the `allowManaged*Only` locks | | `maxBudgetUsd` | `number` | `undefined` | Stop the query when the client-side cost estimate reaches this USD value. Compared against the same estimate as `total_cost_usd`; see [Track cost and usage](/docs/en/agent-sdk/cost-tracking) for accuracy caveats | | `maxThinkingTokens` | `number` | `undefined` | *Deprecated:* Use `thinking` instead. Maximum tokens for thinking process | | `maxTurns` | `number` | `undefined` | Maximum agentic turns (tool-use round trips) | | `mcpServers` | `Record` | `{}` | MCP server configurations | | `model` | `string` | Default from CLI | Claude model alias or full model name. See [accepted values and provider-specific IDs](/docs/en/model-config#available-models) | | `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise` | `undefined` | Callback for handling MCP elicitation requests. Called when an MCP server requests user input and no hook handles it first. When not provided, unhandled elicitation requests are declined automatically | | `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Define output format for agent results. See [Structured outputs](/docs/en/agent-sdk/structured-outputs) for details | | `outputStyle` | `string` | `undefined` | Not an `Options` field. Set `outputStyle` in the inline [`settings`](/docs/en/settings) object or a settings file instead. See [Activate an output style](/docs/en/agent-sdk/modifying-system-prompts#activate-an-output-style) | | `pathToClaudeCodeExecutable` | `string` | Auto-resolved from bundled native binary | Path to Claude Code executable. Only needed if optional dependencies were skipped during install or your platform isn’t in the supported set | | `permissionMode` | [`PermissionMode`](#permissionmode) | `'default'` | Permission mode for the session | | `permissionPromptToolName` | `string` | `undefined` | MCP tool name for permission prompts | | `persistSession` | `boolean` | `true` | When `false`, disables session persistence to disk. Sessions cannot be resumed later | | `planModeInstructions` | `string` | `undefined` | Custom workflow instructions for plan mode. When `permissionMode` is `'plan'`, this string replaces the default plan-mode workflow body. The CLI still wraps it with the read-only enforcement preamble and the ExitPlanMode protocol footer | | `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | Load custom plugins from local paths. See [Plugins](/docs/en/agent-sdk/plugins) for details | | `promptSuggestions` | `boolean` | `false` | Enable prompt suggestions. Emits a `prompt_suggestion` message after each turn with a predicted next user prompt | | `resume` | `string` | `undefined` | Session ID to resume | | `resumeSessionAt` | `string` | `undefined` | Resume session at a specific message UUID | | `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | Configure sandbox behavior programmatically. See [Sandbox settings](#sandboxsettings) for details | | `sessionId` | `string` | Auto-generated | Use a specific UUID for the session instead of auto-generating one | | `sessionStore` | [`SessionStore`](/docs/en/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Mirror session transcripts to an external backend so any host can resume them. See [Persist sessions to external storage](/docs/en/agent-sdk/session-storage) | | `sessionStoreFlush` | `'batched' | 'eager'` | `'batched'` | *Alpha.* Flush mode for `sessionStore`. Ignored when `sessionStore` is not set | | `settings` | `string | Settings` | `undefined` | Inline [settings](/docs/en/settings) object or path to a settings file. Populates the flag-settings layer in the [precedence order](/docs/en/settings#settings-precedence). Change at runtime with [`applyFlagSettings()`](#applyflagsettings) | | `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI defaults (all sources) | Control which filesystem settings to load. Pass `[]` to disable user, project, and local settings. [Endpoint-managed policy](/docs/en/settings#settings-files) loads regardless; server-managed settings are fetched when the session authenticates with an organization credential on an [eligible configuration](/docs/en/server-managed-settings#platform-availability). See [Use Claude Code features](/docs/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) | | `skills` | `string[] | 'all'` | `undefined` | Skills available to the session. Pass `'all'` to enable every discovered skill, or a list of skill names. When set, the SDK adds the Skill tool to `allowedTools` automatically. If you also pass `tools`, include `'Skill'` in that list. See [Skills](/docs/en/agent-sdk/skills) | | `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Custom function to spawn the Claude Code process. Use to run Claude Code in VMs, containers, or remote environments | | `stderr` | `(data: string) => void` | `undefined` | Callback for stderr output | | `strictMcpConfig` | `boolean` | `false` | Use only the servers passed in `mcpServers` and ignore project `.mcp.json`, user settings, plugin-provided MCP servers, and [claude.ai connectors](/docs/en/mcp#use-mcp-servers-from-claude-ai) | | `systemPrompt` | `string | { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (minimal prompt) | System prompt configuration. Pass a string for custom prompt, or `{ type: 'preset', preset: 'claude_code' }` to use Claude Code’s system prompt. When using the preset object form, add `append` to extend it with additional instructions, and set `excludeDynamicSections: true` to move per-session context into the first user message for [better prompt-cache reuse across machines](/docs/en/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) | | `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* API-side task budget in tokens. When set, the model is told its remaining token budget so it can pace tool use and wrap up before the limit | | `thinking` | [`ThinkingConfig`](#thinkingconfig) | `{ type: 'adaptive' }` for supported models | Controls Claude’s thinking/reasoning behavior. See [`ThinkingConfig`](#thinkingconfig) for options | | `title` | `string` | `undefined` | Display title for the session. When resuming via `resume` or `continue`, the resumed session’s persisted title takes precedence; use [`renameSession()`](#renamesession) to retitle an existing session | | `toolAliases` | `Record` | `undefined` | Map built-in tool names to MCP tool names so Claude calls your MCP implementation in place of the built-in. For example, `{ Bash: 'mcp__workspace__bash' }` | | `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | Configuration for built-in tool behavior. See [`ToolConfig`](#toolconfig) for details | | `tools` | `string[] | { type: 'preset'; preset: 'claude_code' }` | `undefined` | Tool configuration. Pass an array of tool names or use the preset to get Claude Code’s default tools | [​](#handle-slow-or-stalled-api-responses) Handle slow or stalled API responses The CLI subprocess reads several environment variables that control API timeouts and stall detection. Pass them through the `env` option: ```python import { query } from "@anthropic-ai/claude-agent-sdk"; const result = query({ prompt: "Analyze this code", options: { env: { ...process.env, API_TIMEOUT_MS: "120000", CLAUDE_CODE_MAX_RETRIES: "2", CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: "120000", }, }, }); ``` - `API_TIMEOUT_MS`: per-request timeout on the Anthropic client, in milliseconds. Default `600000`. Applies to the main loop and all subagents. - `CLAUDE_CODE_MAX_RETRIES`: maximum API retries. Default `10`, capped at `15`. Each retry gets its own `API_TIMEOUT_MS` window, so worst-case wall time is roughly `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` plus backoff. For unattended runs that need to wait through longer outages, set `CLAUDE_CODE_RETRY_WATCHDOG=1`: it retries capacity errors indefinitely, and as of Claude Code v2.1.199 raises the default for other transient errors to `300` and removes the cap on this variable. - `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: stall watchdog for subagents launched with `run_in_background`. Default `600000`. Resets on each stream event; on stall it aborts the subagent, marks the task failed, and surfaces the error to the parent with any partial result. Does not apply to synchronous subagents. - `CLAUDE_ENABLE_STREAM_WATCHDOG` with `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: aborts the request when headers have arrived but the response body stops streaming. The watchdog is on by default for all providers; set `CLAUDE_ENABLE_STREAM_WATCHDOG=0` to disable it. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` defaults to `300000` and is clamped to that minimum. After the abort, Claude Code retries the request at most once, and only before Claude has started a block of text or a tool call in the response; once Claude has completed a block of text or a tool call, Claude Code keeps the completed output, appends an [incomplete-response notice](/docs/en/errors#the-response-above-may-be-incomplete) instead of retrying, and still runs any completed tool call. [​](#query-object) `Query` object Interface returned by the `query()` function. ```python interface Query extends AsyncGenerator { interrupt(): Promise; rewindFiles( userMessageId: string, options?: { dryRun?: boolean } ): Promise; setPermissionMode(mode: PermissionMode): Promise; setModel(model?: string): Promise; setMaxThinkingTokens(maxThinkingTokens: number | null): Promise; applyFlagSettings(settings: { [K in keyof Settings]?: Settings[K] | null }): Promise; initializationResult(): Promise; reinitialize(): Promise; supportedCommands(): Promise; supportedModels(): Promise; supportedAgents(): Promise; mcpServerStatus(): Promise; getContextUsage(): Promise; accountInfo(): Promise; reconnectMcpServer(serverName: string): Promise; toggleMcpServer(serverName: string, enabled: boolean): Promise; setMcpServers(servers: Record): Promise; streamInput(stream: AsyncIterable): Promise; stopTask(taskId: string): Promise; close(): void; } ``` [​](#methods) Methods | Method | Description | |:---------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `interrupt()` | Interrupts the query. Only available in streaming input mode. When the CLI advertises the `interrupt_receipt_v1` capability in [`SDKSystemMessage.capabilities`](#sdksystemmessage), resolves with an [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) listing the queued messages that survive the interrupt. Resolves `undefined` on CLIs before v2.1.205 | | `rewindFiles(userMessageId, options?)` | Restores files to their state at the specified user message. Pass `{ dryRun: true }` to preview changes. Requires `enableFileCheckpointing: true`. See [File checkpointing](/docs/en/agent-sdk/file-checkpointing) | | `setPermissionMode()` | Changes the permission mode (only available in streaming input mode) | | `setModel()` | Changes the model (only available in streaming input mode). Passing `undefined` or the string `"default"` resets to the session default model | | `setMaxThinkingTokens()` | *Deprecated:* Use the `thinking` option instead. Changes the maximum thinking tokens. Passing `null` resets thinking to the session default: a mid-session override is cleared, and thinking stays off for sessions that have it disabled | | `applyFlagSettings(settings)` | Merges settings into the session’s flag settings layer at runtime (only available in streaming input mode). See [`applyFlagSettings()`](#applyflagsettings) | | `initializationResult()` | Returns the full initialization result including supported commands, models, account info, and output style configuration | | `reinitialize()` | Re-sends the `initialize` control request to the running CLI and returns a fresh result instead of the cached first-connect result. Use it after a transport gap, such as reattaching to a session after a disconnect, so pending permission requests reach your `canUseTool` callback again. Make the callback idempotent per request ID, because a request whose response was lost is dispatched again. Requires Claude Code v2.1.195 or later | | `supportedCommands()` | Returns available slash commands. From Agent SDK v0.3.216 the list reflects mid-session command changes; see [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) | | `supportedModels()` | Returns available models with display info | | `supportedAgents()` | Returns available subagents as [`AgentInfo`](#agentinfo)`[]` | | `mcpServerStatus()` | Returns status of connected MCP servers | | `getContextUsage()` | Returns an [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) breaking down the session’s context window usage by category, skill, and tool. The same data `/context` shows in an interactive session | | `accountInfo()` | Returns account information | | `reconnectMcpServer(serverName)` | Reconnect an MCP server by name | | `toggleMcpServer(serverName, enabled)` | Enable or disable an MCP server by name | | `setMcpServers(servers)` | Dynamically replace the set of MCP servers for this session. Returns which servers were added and removed, and any errors. The call keeps plugin-provided servers it doesn’t name; naming one replaces it. The promise resolves after newly added stdio, HTTP, and SSE servers connect or fail, so tools from servers that connected are available on the next turn. | | `streamInput(stream)` | Stream input messages to the query for multi-turn conversations | | `stopTask(taskId)` | Stop a running background task by ID | | `close()` | Close the query and terminate the underlying process. Forcefully ends the query and cleans up all resources | [​](#applyflagsettings) `applyFlagSettings()` Changes [settings](/docs/en/settings) on a running session without restarting the query. Use it when a setting that has no dedicated setter needs to change mid-session, such as tightening `permissions` after the agent reads untrusted input. `setModel()` and `setPermissionMode()` are dedicated setters for those two keys; `applyFlagSettings()` is the general form that accepts any subset of the settings keys, and passing `model` here behaves the same as `setModel()`. Only some keys take effect mid-session: - **Applied on the next turn**: `effortLevel`, `ultracode`, `permissions`, `hooks`, `skillOverrides`, `fastMode`, `agent`. Switching `agent` also applies that agent’s model override, hooks, and system prompt on the next turn. - **Applied during the current turn**: `model`. If you switch `model` while Claude is working on a turn, the response Claude is already generating finishes on the old model, and the rest of the turn, starting with the next call Claude Code makes to the model, uses the new one. Subagents keep their own model. Before v2.1.212, a mid-turn switch waited for the next turn. - **No effect mid-session**: the system prompt options. These are resolved once at startup, so the running session keeps the original value even though the call succeeds. To change them, start a new session. `effortLevel` accepts an [effort level](/docs/en/model-config#adjust-effort-level) name. It also accepts `"ultracode"`, which runs the session at `xhigh` effort and turns on [ultracode](/docs/en/workflows#let-claude-decide-with-ultracode). The `Settings` type declares `effortLevel` without that value, so pass the equivalent `{ ultracode: true }` in TypeScript. The `ultracode` value requires Claude Code v2.1.203 or later and is accepted only by `applyFlagSettings()`, not by the `effortLevel` key in a settings file. The values are written to the flag-settings layer, the same layer the inline `settings` option of `query()` populates at startup. Flag settings sit near the top of the [settings precedence order](/docs/en/settings#settings-precedence): they override user, project, and local settings, and only managed policy settings can override them. This is the same tier the [on-page precedence section](#settings-precedence) calls programmatic options. Successive calls shallow-merge top-level keys. A second call with `{ permissions: {...} }` replaces the entire `permissions` object from the prior call rather than deep-merging into it. To clear a key from the flag layer and fall back to lower-precedence sources, pass `null` for that key. Passing `undefined` has no effect because JSON serialization drops it. Only available in streaming input mode, the same constraint as `setModel()` and `setPermissionMode()`. The example below switches the active model mid-session, then clears the override so the model falls back to whatever the user or project settings specify. ```python import { query } from "@anthropic-ai/claude-agent-sdk"; const q = query({ prompt: messageStream }); // Override the model for the rest of the session await q.applyFlagSettings({ model: "claude-opus-4-6" }); // Later: clear the override and fall back to lower-precedence settings await q.applyFlagSettings({ model: null }); ``` `applyFlagSettings()` is TypeScript-only. The Python SDK does not expose an equivalent method. [​](#warmquery) `WarmQuery` Handle returned by [`startup()`](#startup). The subprocess is already spawned and initialized, so calling `query()` on this handle writes the prompt directly to a ready process with no startup latency. ```python interface WarmQuery extends AsyncDisposable { query(prompt: string | AsyncIterable): Query; close(): void; } ``` [​](#methods-2) Methods | Method | Description | |:----------------|:--------------------------------------------------------------------------------------------------------------------------| | `query(prompt)` | Send a prompt to the pre-warmed subprocess and return a [`Query`](#query-object). Can only be called once per `WarmQuery` | | `close()` | Close the subprocess without sending a prompt. Use this to discard a warm query that is no longer needed | `WarmQuery` implements `AsyncDisposable`, so it can be used with `await using` for automatic cleanup. [​](#sdkcontrolinitializeresponse) `SDKControlInitializeResponse` Return type of `initializationResult()`. Contains session initialization data. ```python type SDKControlInitializeResponse = { commands: SlashCommand[]; agents: AgentInfo[]; output_style: string; available_output_styles: string[]; models: ModelInfo[]; account: AccountInfo; fast_mode_state?: "off" | "cooldown" | "on"; fast_mode_disabled_reason?: FastModeDisabledReason; }; ``` The response always reports `fast_mode_state`, and when something blocks [fast mode](/docs/en/fast-mode), `fast_mode_disabled_reason` carries the reason code alongside it, so you can explain the blocked state instead of re-deriving availability. Both behaviors require Claude Code v2.1.219 or later. Before v2.1.219, the response omitted `fast_mode_state` when fast mode wasn’t available and never carried a reason. For the reason codes and their meanings, see [`fast_mode_disabled_reason`](#sdkresultmessage) on the result message. When a client sends `initialize` to a session that is already running, the control-response wrapper also carries an optional `pending_permission_requests` array. The field is on the response wrapper itself, not in the `SDKControlInitializeResponse` payload above. Each entry is a complete `control_request` message with the same `{ type: "control_request", request_id, request }` shape the session streams for permission requests while running. These are requests that were issued before the client connected and are still awaiting a reply. The SDK reads the array for you and dispatches each entry to your [`canUseTool`](#canusetool) callback, the same redelivery that [`reinitialize()`](#query-object) triggers after a transport gap. Handle repeated request IDs idempotently, because an entry can repeat a request the callback already received before the connection dropped. [​](#sdkcontrolinterruptresponse) `SDKControlInterruptResponse` The interrupt receipt: the value [`interrupt()`](#query-object) resolves with on a CLI that advertises the `interrupt_receipt_v1` capability in [`SDKSystemMessage.capabilities`](#sdksystemmessage). Requires Claude Code v2.1.205 or later. Earlier CLIs answer the interrupt with an empty success payload, so `interrupt()` resolves to `undefined`. ```python type SDKControlInterruptResponse = { still_queued: string[]; cancelled?: string[]; }; ``` `still_queued` lists the UUIDs of user messages that survive the interrupt: messages still in the queue, plus any batch already dequeued for the next turn but not yet reachable by the abort. Each one runs as its own turn after the interrupt unless you cancel it first. Use the receipt to decide whether to resend anything; resending a message that is already listed produces a duplicate turn. Interpret the list with these caveats: - Only messages that were enqueued with a UUID appear. An empty array doesn’t mean nothing else will run. - Only main-thread messages are listed. Messages addressed to a subagent are out of scope. - The list can include UUIDs your client never sent, such as [scheduled task](/docs/en/scheduled-tasks) triggers. Ignore UUIDs you don’t recognize instead of treating them as an error. A client that drives the CLI’s control protocol directly, rather than through `interrupt()`, can set `cancel_queued: true` on the `interrupt` control request. Claude Code v2.1.219 and later advertises support with the `interrupt_cancel_queued_v1` capability in [`SDKSystemMessage.capabilities`](#sdksystemmessage); older CLIs ignore the field and leave queued messages to run as usual. Such an interrupt also cancels every message that would otherwise be listed under `still_queued`: the receipt lists them under `cancelled` instead, `still_queued` is empty, and none of them run. The `cancelled` list carries the same caveats as `still_queued`. The `interrupt()` method never sends `cancel_queued`, so receipts it resolves with don’t carry `cancelled`. The receipt is a snapshot taken at the moment the interrupt is processed, and on a clean interrupt it arrives before the interrupted turn’s [`SDKResultMessage`](#sdkresultmessage). Read the receipt rather than inspecting the queue after that result: the loop starts the next queued turn immediately, so the queue you inspect after the result has already changed. [​](#sdkcontrolgetcontextusageresponse) `SDKControlGetContextUsageResponse` Return type of [`getContextUsage()`](#query-object). This is the same payload the `/context` command renders in an interactive session, so alongside the token counts it carries display fields such as `color`, `gridRows`, and `percentage` that `/context` uses to draw its usage grid. ```python type SDKControlGetContextUsageResponse = { categories: { name: string; tokens: number; color: string; isDeferred?: boolean; }[]; totalTokens: number; maxTokens: number; rawMaxTokens: number; percentage: number; gridRows: { color: string; isFilled: boolean; categoryName: string; tokens: number; percentage: number; squareFullness: number; }[][]; model: string; memoryFiles: { path: string; type: string; tokens: number; }[]; mcpTools: { name: string; serverName: string; tokens: number; isLoaded?: boolean; }[]; deferredBuiltinTools?: { name: string; tokens: number; isLoaded: boolean; }[]; systemTools?: { name: string; tokens: number; }[]; systemPromptSections?: { name: string; tokens: number; }[]; agents: { agentType: string; source: string; tokens: number; }[]; slashCommands?: { totalCommands: number; includedCommands: number; tokens: number; }; skills?: { totalSkills: number; includedSkills: number; tokens: number; skillFrontmatter: { name: string; source: string; tokens: number; }[]; }; autoCompactThreshold?: number; isAutoCompactEnabled: boolean; messageBreakdown?: { toolCallTokens: number; toolResultTokens: number; attachmentTokens: number; assistantMessageTokens: number; userMessageTokens: number; redirectedContextTokens: number; unattributedTokens: number; toolCallsByType: { name: string; callTokens: number; resultTokens: number; }[]; attachmentsByType: { name: string; tokens: number; }[]; }; apiUsage: { input_tokens: number; output_tokens: number; cache_creation_input_tokens: number; cache_read_input_tokens: number; } | null; }; ``` Read token attribution from the collection fields: - `categories` holds the per-category totals. - `mcpTools` and `agents` attribute tokens to individual MCP tools and subagents. - `memoryFiles` lists each loaded memory file with its cost. - `skills.skillFrontmatter` attributes the skill listing’s tokens to each included skill. The per-skill counts measure each skill’s listing entry as Claude Code actually sends it, which can be shorter than the skill’s full frontmatter. Compare `skills.totalSkills` with `skills.includedSkills` to see whether every discovered skill made it into the listing. `totalTokens` is the session’s current context usage, and `maxTokens` is the window that usage is measured against. That window is the model’s context window, or the lower auto-compaction window when one applies. Claude Code leaves the optional `deferredBuiltinTools`, `systemTools`, and `systemPromptSections` diagnostics unset, so expect them to be absent even though the type declares them. [​](#agentdefinition) `AgentDefinition` Configuration for a subagent defined programmatically. ```python type AgentDefinition = { description: string; tools?: string[]; disallowedTools?: string[]; prompt: string; model?: string; mcpServers?: AgentMcpServerSpec[]; skills?: string[]; initialPrompt?: string; maxTurns?: number; background?: boolean; memory?: "user" | "project" | "local"; effort?: "low" | "medium" | "high" | "xhigh" | "max" | number; permissionMode?: PermissionMode; criticalSystemReminder_EXPERIMENTAL?: string; }; ``` | Field | Required | Description | |:--------------------------------------|:---------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `description` | Yes | Natural language description of when to use this agent | | `tools` | No | Array of allowed tool names. If omitted, inherits every [tool available to subagents](/docs/en/sub-agents#available-tools). To preload Skills into the agent’s context, use the `skills` field rather than listing `'Skill'` here | | `disallowedTools` | No | Array of tool names to explicitly disallow for this agent. MCP server-level patterns are also accepted: `mcp__server` or `mcp__server__*` removes every tool from that server, and `mcp__*` removes every MCP tool from any server | | `prompt` | Yes | The agent’s system prompt | | `model` | No | Model override for this agent. Accepts an alias such as `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, or a full model ID. If omitted or `'inherit'`, uses the main model | | `mcpServers` | No | MCP server specifications for this agent | | `skills` | No | Array of skill names to preload into the agent context | | `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main thread agent | | `maxTurns` | No | Maximum number of agentic turns (API round-trips) before stopping | | `background` | No | Run this agent as a non-blocking background task when invoked | | `memory` | No | Memory source for this agent: `'user'`, `'project'`, or `'local'` | | `effort` | No | Reasoning effort level for this agent. Accepts a named level or an integer | | `permissionMode` | No | Permission mode for tool execution within this agent. See [`PermissionMode`](#permissionmode) | | `criticalSystemReminder_EXPERIMENTAL` | No | Experimental: Critical reminder added to the system prompt | [​](#agentmcpserverspec) `AgentMcpServerSpec` Specifies MCP servers available to a subagent. Can be a server name (string referencing a server from the parent’s `mcpServers` config) or an inline server configuration record mapping server names to configs. ```python type AgentMcpServerSpec = string | Record; ``` Where `McpServerConfigForProcessTransport` is `McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig`. [​](#settingsource) `SettingSource` Controls which filesystem-based configuration sources the SDK loads settings from. ```python type SettingSource = "user" | "project" | "local"; ``` | Value | Description | Location | |:------------|:--------------------------------------------------------------------------|:------------------------------| | `'user'` | Global user settings | `~/.claude/settings.json` | | `'project'` | Shared project settings (version controlled) | `.claude/settings.json` | | `'local'` | Local project settings, gitignored when Claude Code saves a setting to it | `.claude/settings.local.json` | [​](#default-behavior) Default behavior When `settingSources` is omitted or `undefined`, `query()` loads the same filesystem settings as the Claude Code CLI: user, project, and local. [Endpoint-managed policy](/docs/en/settings#settings-files) is loaded in all cases; server-managed settings are fetched when the session authenticates with an organization credential on an [eligible configuration](/docs/en/server-managed-settings#platform-availability). See [What settingSources does not control](/docs/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) for inputs that are read regardless of this option, and how to disable them. [​](#why-use-settingsources) Why use settingSources **Disable filesystem settings:** ```python import { query } from "@anthropic-ai/claude-agent-sdk"; // Do not load user, project, or local settings from disk const result = query({ prompt: "Analyze this code", options: { settingSources: [] } }); ``` **Load all filesystem settings explicitly:** ```python import { query } from "@anthropic-ai/claude-agent-sdk"; const result = query({ prompt: "Analyze this code", options: { settingSources: ["user", "project", "local"] // Load all settings } }); ``` **Load only specific setting sources:** ```python import { query } from "@anthropic-ai/claude-agent-sdk"; // Load only project settings, ignore user and local const result = query({ prompt: "Run CI checks", options: { settingSources: ["project"] // Only .claude/settings.json } }); ``` **Testing and CI environments:** ```python import { query } from "@anthropic-ai/claude-agent-sdk"; // Ensure consistent behavior in CI by excluding local settings const result = query({ prompt: "Run tests", options: { settingSources: ["project"], // Only team-shared settings permissionMode: "bypassPermissions", allowDangerouslySkipPermissions: true } }); ``` **SDK-only applications:** ```python import { query } from "@anthropic-ai/claude-agent-sdk"; // Define everything programmatically. // Pass [] to opt out of filesystem setting sources. const result = query({ prompt: "Review this PR", options: { settingSources: [], agents: { /* ... */ }, mcpServers: { /* ... */ }, allowedTools: ["Read", "Grep", "Glob"] } }); ``` **Loading CLAUDE.md project instructions:** ```python import { query } from "@anthropic-ai/claude-agent-sdk"; // Load project settings to include CLAUDE.md files const result = query({ prompt: "Add a new feature following project conventions", options: { systemPrompt: { type: "preset", preset: "claude_code" // Use Claude Code's system prompt }, settingSources: ["project"], // Loads CLAUDE.md from project directory allowedTools: ["Read", "Write", "Edit"] } }); ``` [​](#settings-precedence) Settings precedence When multiple sources are loaded, settings are merged with this precedence (highest to lowest): 1. Local settings (`.claude/settings.local.json`) 2. Project settings (`.claude/settings.json`) 3. User settings (`~/.claude/settings.json`) Programmatic options such as `agents`, `allowedTools`, and `settings` override user, project, and local filesystem settings. Managed policy settings take precedence over programmatic options. [​](#permissionmode) `PermissionMode` ```python type PermissionMode = | "default" // Standard permission behavior | "acceptEdits" // Auto-accept file edits | "bypassPermissions" // Bypass permission checks; explicit ask rules still prompt | "plan" // Planning mode - explore without editing | "dontAsk" // Don't prompt for permissions, deny if not pre-approved | "auto"; // Model classifier approves or denies permission prompts ``` [​](#canusetool) `CanUseTool` Custom permission function type for controlling tool usage. The function is the SDK replacement for the interactive permission prompt: it’s invoked only when the [permission evaluation flow](/docs/en/agent-sdk/permissions#how-permissions-are-evaluated) resolves to a prompt. Tool calls already approved by an `allowedTools` entry, a settings allow rule, or the permission mode, such as `acceptEdits` or `bypassPermissions`, never invoke it. To gate every tool call, use a [`PreToolUse` hook](/docs/en/agent-sdk/hooks) instead. `AskUserQuestion`, MCP tools marked [`requiresUserInteraction`](/docs/en/mcp#require-approval-for-a-specific-tool), and connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools) reach the function even when an allow rule matches. In `dontAsk` mode these calls are denied instead, without invoking it. ```python type CanUseTool = ( toolName: string, input: Record, options: { signal: AbortSignal; suggestions?: PermissionUpdate[]; blockedPath?: string; decisionReason?: string; toolUseID: string; agentID?: string; requestId: string; } ) => Promise; ``` | Option | Type | Description | |:-----------------|:--------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `signal` | `AbortSignal` | Signaled if the operation should be aborted | | `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | Suggested permission updates so the user is not prompted again for this tool. Bash prompts include a suggestion with the `localSettings` [destination](#permissionupdatedestination), so returning it in `updatedPermissions` writes the rule to `.claude/settings.local.json` and persists across sessions. | | `blockedPath` | `string` | The file path that triggered the permission request, if applicable | | `decisionReason` | `string` | Explains why this permission request was triggered | | `toolUseID` | `string` | Unique identifier for this specific tool call within the assistant message | | `agentID` | `string` | If running within a sub-agent, the sub-agent’s ID | | `requestId` | `string` | The `control_request` envelope’s `request_id`. A `control_response` your application sends outside the SDK, such as a signed HTTP POST, must echo this value so the Claude Code process can match the reply to the request | The callback normally resolves the request by returning a [`PermissionResult`](#permissionresult), which the SDK writes back over its transport as the `control_response`. Return `null` only when your application has already sent the `control_response` for this request over its own channel, echoing `requestId`; the SDK then skips writing the response to its transport. Returning `null` in any other case leaves the tool call blocked indefinitely, because no `control_response` is ever sent and permission prompts don’t time out. The `requestId` option and the `null` return value require Claude Code v2.1.199 or later. [​](#permissionresult) `PermissionResult` Result of a permission check. ```python type PermissionResult = | { behavior: "allow"; updatedInput?: Record; updatedPermissions?: PermissionUpdate[]; toolUseID?: string; } | { behavior: "deny"; message: string; interrupt?: boolean; toolUseID?: string; }; ``` [​](#toolconfig) `ToolConfig` Configuration for built-in tool behavior. ```python type ToolConfig = { askUserQuestion?: { previewFormat?: "markdown" | "html"; }; }; ``` | Field | Type | Description | |:--------------------------------|:----------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `askUserQuestion.previewFormat` | `'markdown' | 'html'` | Opts into the `preview` field on [`AskUserQuestion`](/docs/en/agent-sdk/user-input#question-format) options and sets its content format. When unset, Claude does not emit previews | [​](#mcpserverconfig) `McpServerConfig` Configuration for MCP servers. ```python type McpServerConfig = | McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfigWithInstance; ``` [​](#mcpstdioserverconfig) `McpStdioServerConfig` ```python type McpStdioServerConfig = { type?: "stdio"; command: string; args?: string[]; env?: Record; }; ``` [​](#mcpsseserverconfig) `McpSSEServerConfig` ```python type McpSSEServerConfig = { type: "sse"; url: string; headers?: Record; }; ``` [​](#mcphttpserverconfig) `McpHttpServerConfig` ```python type McpHttpServerConfig = { type: "http"; url: string; headers?: Record; }; ``` [​](#mcpsdkserverconfigwithinstance) `McpSdkServerConfigWithInstance` ```python type McpSdkServerConfigWithInstance = { type: "sdk"; name: string; instance: McpServer; }; ``` [​](#mcpclaudeaiproxyserverconfig) `McpClaudeAIProxyServerConfig` ```python type McpClaudeAIProxyServerConfig = { type: "claudeai-proxy"; url: string; id: string; }; ``` [​](#sdkpluginconfig) `SdkPluginConfig` Configuration for loading plugins in the SDK. ```python type SdkPluginConfig = { type: "local"; path: string; skipMcpDiscovery?: boolean; }; ``` | Field | Type | Description | |:-------------------|:----------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | `'local'` | Must be `'local'` (only local plugins currently supported) | | `path` | `string` | Absolute or relative path to the plugin directory | | `skipMcpDiscovery` | `boolean` | When `true`, the SDK loads skills, hooks, agents, and commands from this plugin but does not read its `.mcp.json` or manifest `mcpServers`. Set this when your application owns the plugin’s MCP connections. | **Example:** ```python plugins: [ { type: "local", path: "./my-plugin" }, { type: "local", path: "/absolute/path/to/plugin" } ]; ``` For complete information on creating and using plugins, see [Plugins](/docs/en/agent-sdk/plugins). [​](#message-types) Message Types [​](#sdkmessage) `SDKMessage` Union type of all possible messages returned by the query. ```python type SDKMessage = | SDKAssistantMessage | SDKUserMessage | SDKUserMessageReplay | SDKResultMessage | SDKSystemMessage | SDKPartialAssistantMessage | SDKCompactBoundaryMessage | SDKStatusMessage | SDKLocalCommandOutputMessage | SDKHookStartedMessage | SDKHookProgressMessage | SDKHookResponseMessage | SDKPluginInstallMessage | SDKToolProgressMessage | SDKAuthStatusMessage | SDKTaskNotificationMessage | SDKTaskStartedMessage | SDKTaskProgressMessage | SDKTaskUpdatedMessage | SDKBackgroundTasksChangedMessage | SDKThinkingTokensMessage | SDKSessionStateChangedMessage | SDKWorkerShuttingDownMessage | SDKCommandsChangedMessage | SDKNotificationMessage | SDKFilesPersistedEvent | SDKToolUseSummaryMessage | SDKMemoryRecallMessage | SDKRateLimitEvent | SDKElicitationCompleteMessage | SDKPermissionDeniedMessage | SDKPromptSuggestionMessage | SDKAPIRetryMessage | SDKMirrorErrorMessage | SDKInformationalMessage | SDKConversationResetMessage; ``` [​](#sdkassistantmessage) `SDKAssistantMessage` Assistant response message. ```python type SDKAssistantMessage = { type: "assistant"; uuid: UUID; session_id: string; message: BetaMessage; // From Anthropic SDK parent_tool_use_id: string | null; error?: SDKAssistantMessageError; aborted?: true; timestamp?: string; }; ``` The `message` field is a [`BetaMessage`](https://platform.claude.com/docs/en/api/messages/create) from the Anthropic SDK. It includes fields like `id`, `content`, `model`, `stop_reason`, and `usage`. `SDKAssistantMessageError` is one of: `'authentication_failed'`, `'oauth_org_not_allowed'`, `'billing_error'`, `'rate_limit'`, `'overloaded'`, `'invalid_request'`, `'model_not_found'`, `'server_error'`, `'max_output_tokens'`, or `'unknown'`. `'model_not_found'` means the selected model doesn’t exist or isn’t available to your account or deployment. `'overloaded'` means the API returned a 529 because the server is at capacity, as opposed to `'rate_limit'`, which is a 429 against your quota. `aborted` is `true` when an interrupt or abort truncated the assistant message before the stream completed: the message has no `stop_reason` and the content may end mid-word. The field is absent on normally completed messages. It requires Agent SDK v0.3.214 or later. `timestamp` is the ISO 8601 time when the message’s content finished generating on the process that produced it. The value comes from that machine’s clock, so use it for display only and don’t order messages by it. One API turn can produce several assistant messages that share a `message.id`, each with its own `timestamp`. When the field is absent, fall back to the time you received the message. [​](#sdkusermessage) `SDKUserMessage` User input message. ```python type SDKUserMessage = { type: "user"; uuid?: UUID; session_id?: string; message: MessageParam; // From Anthropic SDK parent_tool_use_id: string | null; isSynthetic?: boolean; shouldQuery?: boolean; tool_use_result?: unknown; origin?: SDKMessageOrigin; }; ``` Set `shouldQuery` to `false` to append the message to the transcript without triggering an assistant turn. The message is held and merged into the next user message that does trigger a turn. Use this to inject context, such as the output of a command you ran out of band, without spending a model call on it. On a message that carries a `tool_result` block, `tool_use_result` is the tool’s structured output object rather than the text sent to the model. Its shape depends on the tool named by the matching `tool_use` block, so the field is typed `unknown`; the built-in shapes are listed under [Tool Output Types](#tool-output-types). For the `Agent` tool, `tool_use_result` is [`AgentOutput`](#agent-2). On a `completed` result, `content` holds the subagent’s report without the agent ID and usage trailer that Claude Code appends to the `tool_result` text, so render from `tool_use_result` instead of parsing that text. [​](#sdkusermessagereplay) `SDKUserMessageReplay` Replayed user message with required UUID. ```python type SDKUserMessageReplay = { type: "user"; uuid: UUID; session_id: string; message: MessageParam; parent_tool_use_id: string | null; isSynthetic?: boolean; tool_use_result?: unknown; origin?: SDKMessageOrigin; isReplay: true; }; ``` A user turn injected from outside the session, one whose [`origin`](#sdkmessageorigin) kind is `peer` or `channel`, reaches the stream as a replay whether it was delivered during an active turn or started a new turn while the session was idle. Before v2.1.207, an injected turn delivered while the session was idle produced no message on the stream and only appeared when you re-read the transcript. [​](#sdkresultmessage) `SDKResultMessage` Final result message. ```python type SDKResultMessage = | { type: "result"; subtype: "success"; uuid: UUID; session_id: string; duration_ms: number; duration_api_ms: number; is_error: boolean; api_error_status?: number | null; num_turns: number; result: string; stop_reason: string | null; ttft_ms?: number; ttft_stream_ms?: number; user_message_uuid?: string; request_sent_wall_ms?: number; total_cost_usd: number; usage: NonNullableUsage; modelUsage: { [modelName: string]: ModelUsage }; permission_denials: SDKPermissionDenial[]; structured_output?: unknown; deferred_tool_use?: { id: string; name: string; input: Record }; terminal_reason?: TerminalReason; fast_mode_state?: FastModeState; fast_mode_disabled_reason?: FastModeDisabledReason; origin?: SDKMessageOrigin; } | { type: "result"; subtype: | "error_max_turns" | "error_during_execution" | "error_max_budget_usd" | "error_max_structured_output_retries"; uuid: UUID; session_id: string; duration_ms: number; duration_api_ms: number; is_error: boolean; num_turns: number; stop_reason: string | null; total_cost_usd: number; usage: NonNullableUsage; modelUsage: { [modelName: string]: ModelUsage }; permission_denials: SDKPermissionDenial[]; errors: string[]; terminal_reason?: TerminalReason; fast_mode_state?: FastModeState; fast_mode_disabled_reason?: FastModeDisabledReason; origin?: SDKMessageOrigin; }; ``` Several fields on the result carry diagnostic detail beyond `subtype`: - `api_error_status`: the HTTP status code of the API error that terminated the conversation. Absent or `null` when the turn ended without an API error. - `ttft_ms`: time to first token in milliseconds, measured when the first complete assistant message arrives. Present on the success arm only. - `ttft_stream_ms`: time in milliseconds until the first `message_start` stream event, when the response stream opens. Lower than `ttft_ms`; the gap between the two is time spent streaming the first message. Present on the success arm only. - `user_message_uuid`: the `uuid` of the [`SDKUserMessage`](#sdkusermessage) that started this turn, echoed back so you can match the result to the message you sent. Requires Claude Code v2.1.216 or later. Present on the success arm only, together with `request_sent_wall_ms`; absent on API-error results, subagent calls, and synthetic turns such as scheduled ones. - `request_sent_wall_ms`: epoch milliseconds at which Claude Code dispatched the API request, for joins against server-side timestamps. Present only together with `user_message_uuid`. - `terminal_reason`: why the loop ended. One of `"completed"`, `"max_turns"`, `"tool_deferred"`, `"aborted_streaming"`, `"aborted_tools"`, `"hook_stopped"`, `"stop_hook_prevented"`, `"background_requested"`, `"blocking_limit"`, `"rapid_refill_breaker"`, `"prompt_too_long"`, `"image_error"`, `"model_error"`, `"api_error"`, `"malformed_tool_use_exhausted"`, `"budget_exhausted"`, `"structured_output_retry_exhausted"`, `"tool_deferred_unavailable"`, or `"turn_setup_failed"`. - `fast_mode_state`: one of `"on"`, `"off"`, or `"cooldown"`. - `fast_mode_disabled_reason`: why [fast mode](/docs/en/fast-mode) isn’t available right now. Absent when nothing blocks fast mode, though a request may still run at standard speed. During the cooldown after a fast mode rate limit, Claude Code reports `fast_mode_state: "cooldown"` with no reason code and re-enables fast mode when the cooldown expires. Requires Claude Code v2.1.219 or later. Use the reason code to explain why fast mode is off in your own UI instead of re-deriving availability. Each code names the check that blocked fast mode: | Reason code | Meaning | |------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| | `free` | The account doesn’t have the paid subscription or usage credits fast mode requires | | `preference` | The organization has disabled fast mode | | `extra_usage_disabled` | Usage credits are turned off for the account | | `network_error` | The [availability check](/docs/en/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) couldn’t reach `api.anthropic.com` | | `unknown` | Claude Code couldn’t determine availability | | `not_first_party` | The session uses a provider other than the Anthropic API | | `disabled_by_env` | [`CLAUDE_CODE_DISABLE_FAST_MODE`](/docs/en/env-vars) is set | | `model_not_allowed` | The fast mode Opus model isn’t in the organization’s [`availableModels`](/docs/en/model-config#restrict-model-selection) allowlist | | `sdk_opt_in_required` | The session hasn’t opted in to fast mode: pass `fastMode: true` in the [`settings`](#options) option or through [`applyFlagSettings()`](#applyflagsettings) | | `pending` | The availability check hasn’t completed yet | The same pair of fields appears on [`SDKSystemMessage`](#sdksystemmessage) and on the [`SDKControlInitializeResponse`](#sdkcontrolinitializeresponse), so you can read the fast mode state before the first turn. The `origin` field forwards the [`SDKMessageOrigin`](#sdkmessageorigin) of the user message that triggered this result. When a background task finishes and the SDK injects a synthetic follow-up turn, the resulting `SDKResultMessage` carries `origin: { kind: "task-notification" }`. Check this field to distinguish results that answer your prompt from results emitted for background-task follow-ups, so you can route or suppress the latter. The field is absent for results emitted before any user turn, such as startup errors. When a `PreToolUse` hook returns `permissionDecision: "defer"`, the result has `stop_reason: "tool_deferred"` and `deferred_tool_use` carries the pending tool’s `id`, `name`, and `input`. Read this field to surface the request in your own UI, then resume with the same `session_id` to continue. See [Defer a tool call for later](/docs/en/hooks#defer-a-tool-call-for-later) for the full round trip. [​](#sdksystemmessage) `SDKSystemMessage` System initialization message. ```python type SDKSystemMessage = { type: "system"; subtype: "init"; uuid: UUID; session_id: string; agents?: string[]; apiKeySource: ApiKeySource; betas?: string[]; claude_code_version: string; cwd: string; tools: string[]; mcp_servers: { name: string; status: string; }[]; model: string; permissionMode: PermissionMode; slash_commands: string[]; output_style: string; skills: string[]; plugins: { name: string; path: string }[]; fast_mode_state?: FastModeState; fast_mode_disabled_reason?: FastModeDisabledReason; capabilities?: string[]; }; ``` `fast_mode_state` reports the session’s [fast mode](/docs/en/fast-mode) state. When something blocks fast mode, `fast_mode_disabled_reason` names the check that blocked it; the field requires Claude Code v2.1.219 or later. For the reason codes and their meanings, see [`fast_mode_disabled_reason`](#sdkresultmessage) on the result message. The `capabilities` array names the protocol behaviors this CLI implements, so you can feature-detect instead of comparing `claude_code_version` strings. It is an open set: ignore values you don’t recognize, and check for the specific capability whose behavior you rely on. The field requires Claude Code v2.1.205 or later and is absent on earlier CLIs. | Capability | Meaning | |------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `interrupt_receipt_v1` | [`interrupt()`](#query-object) resolves with an [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) receipt naming the queued messages that survive the interrupt | | `interrupt_cancel_queued_v1` | The `interrupt` control request honors `cancel_queued: true`, cancelling the queued messages that would otherwise survive the interrupt and listing them on the receipt’s `cancelled` field. See [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse). Requires Claude Code v2.1.219 or later | [​](#sdkpartialassistantmessage) `SDKPartialAssistantMessage` Streaming partial message (only when `includePartialMessages` is true). The `parent_tool_use_id` field is always `null`: stream events are emitted for the main session only. For subagent attribution, use complete messages, which carry `parent_tool_use_id`, or enable [`forwardSubagentText`](#options) to receive subagent text and thinking as complete messages. ```python type SDKPartialAssistantMessage = { type: "stream_event"; event: BetaRawMessageStreamEvent; // From Anthropic SDK parent_tool_use_id: string | null; uuid: UUID; session_id: string; ttft_ms?: number; // Time to first token in ms, present only on message_start events }; ``` [​](#sdkcompactboundarymessage) `SDKCompactBoundaryMessage` Message indicating a conversation compaction boundary. ```python type SDKCompactBoundaryMessage = { type: "system"; subtype: "compact_boundary"; uuid: UUID; session_id: string; compact_metadata: { trigger: "manual" | "auto"; pre_tokens: number; }; }; ``` [​](#sdkinformationalmessage) `SDKInformationalMessage` Generic text banner emitted by the loop. Carries non-error status lines, hook feedback such as a `UserPromptSubmit` hook’s block reason, and command output. Render `content` as plaintext at the given `level`. ```python type SDKInformationalMessage = { type: "system"; subtype: "informational"; content: string; level: "info" | "notice" | "suggestion" | "warning"; tool_use_id?: string; prevent_continuation?: boolean; uuid: UUID; session_id: string; }; ``` [​](#sdkworkershuttingdownmessage) `SDKWorkerShuttingDownMessage` Emitted on graceful worker teardown so remote clients can show why the worker exited instead of waiting for heartbeat timeout. The `reason` is a short snake_case string set by the host CLI, such as `"host_exit"` or `"remote_control_disabled"`. Act on this only when streaming live. A resumed session replays past instances of this message, so ignore them in that case. ```python type SDKWorkerShuttingDownMessage = { type: "system"; subtype: "worker_shutting_down"; reason: string; uuid: UUID; session_id: string; }; ``` [​](#sdkplugininstallmessage) `SDKPluginInstallMessage` Plugin installation progress event. Emitted when [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/en/env-vars) is set, so your Agent SDK application can track marketplace plugin installation before the first turn. The `started` and `completed` statuses bracket the overall install. The `installed` and `failed` statuses report individual marketplaces and include `name`. ```python type SDKPluginInstallMessage = { type: "system"; subtype: "plugin_install"; status: "started" | "installed" | "failed" | "completed"; name?: string; error?: string; uuid: UUID; session_id: string; }; ``` [​](#sdkpermissiondeniedmessage) `SDKPermissionDeniedMessage` Stream event emitted when the permission system auto-denies a tool call without an interactive prompt. Use it to render the denial in your UI as it happens, rather than only observing the `is_error` tool result that follows. The interactive ask path reaches your application separately through the [`canUseTool`](#canusetool) callback. Denials issued by a `PreToolUse` hook are not reported through this event. This event requires Claude Code v2.1.136 or later. ```python type SDKPermissionDeniedMessage = { type: "system"; subtype: "permission_denied"; tool_name: string; tool_use_id: string; agent_id?: string; decision_reason_type?: string; decision_reason?: string; message: string; uuid: UUID; session_id: string; }; ``` | Field | Type | Description | |------------------------|----------|--------------------------------------------------------------------------------------------------------------------------| | `tool_name` | `string` | Name of the tool that was denied | | `tool_use_id` | `string` | ID of the `tool_use` block this denial answers | | `agent_id` | `string` | Subagent ID when the denied call originated inside a subagent. Mirrors the field on `can_use_tool` for host-side routing | | `decision_reason_type` | `string` | Discriminator for the component that decided, such as `"rule"`, `"mode"`, `"classifier"`, or `"asyncAgent"` | | `decision_reason` | `string` | Human-readable reason from the deciding component, when available | | `message` | `string` | Rejection message returned to the model in the `tool_result` | [​](#sdkpermissiondenial) `SDKPermissionDenial` Information about a denied tool use. ```python type SDKPermissionDenial = { tool_name: string; tool_use_id: string; tool_input: Record; }; ``` [​](#sdkmessageorigin) `SDKMessageOrigin` Provenance of a user-role message. This appears as `origin` on [`SDKUserMessage`](#sdkusermessage) and is forwarded onto the corresponding [`SDKResultMessage`](#sdkresultmessage) so you can tell what triggered a given turn. ```python type SDKMessageOrigin = | { kind: "human" } | { kind: "channel"; server: string } | { kind: "peer"; from: string; name?: string; fromSession?: string; senderTaskId?: string; body?: string; verifiedPeerPid?: number; } | { kind: "task-notification" } | { kind: "coordinator" } | { kind: "auto-continuation" }; ``` | `kind` | Meaning | |---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `human` | Direct input from the end user. If your application forwards what the user typed as a user message, set its `origin` to `{ kind: "human" }` explicitly: Claude Code treats a user message with no `origin` as unattributed, and checks that require a human-typed prompt, such as the [`ultracode` workflow keyword](/docs/en/workflows#ask-for-a-workflow-in-your-prompt), don’t accept it. Before v2.1.210, Claude Code treated an absent `origin` on a user message as human input. | | `channel` | Message arriving on a [channel](/docs/en/channels). `server` is the source MCP server name. | | `peer` | Message from another agent: an in-process [teammate](/docs/en/agent-teams) or a cross-session peer such as another local Claude Code process. See [Peer origin fields](#peer-origin-fields) for the per-field semantics and the trust model. | | `task-notification` | Synthetic turn injected after a background task finished. See [`SDKTaskNotificationMessage`](#sdktasknotificationmessage). | | `coordinator` | Message from a team coordinator in an [agent team](/docs/en/agent-teams). | | `auto-continuation` | Synthetic turn injected when the session continues without fresh user input, such as a command result that triggers a follow-up prompt. | [​](#peer-origin-fields) Peer origin fields A `peer` origin identifies which agent sent the message: an in-process [teammate](/docs/en/agent-teams) sending to `main` with `SendMessage`, or a cross-session peer such as another local Claude Code process. The two kinds of sender fill the fields differently: - `from`: the teammate’s name, or the sender address for a cross-session peer. The value is sender-authored; `verifiedPeerPid` is the verified identity. - `senderTaskId`: the teammate’s task ID. Absent for a cross-session peer. - `name`: the sender’s display name, normalized by Claude Code: it strips Unicode control, format, surrogate, and line or paragraph separator code points, then trims the result and caps it at 64 code points with an ellipsis. Requires Claude Code v2.1.205 or later. - `body`: the decoded message body with the peer envelope stripped, byte-exact with what the model sees. Always present for a teammate message; for a cross-session peer, present only when the turn is exactly one peer envelope formed by Claude Code. Render `name` and `body` instead of re-parsing the message text. Requires Claude Code v2.1.205 or later. - `fromSession`: the sender’s host-openable session ID, set by the sender’s host so your UI can link back to the sending session. Like `from`, it is sender-asserted: use it as a navigation target only, and don’t treat it as proof of the sender’s identity. Requires Claude Code v2.1.216 or later. - `verifiedPeerPid`: the process ID of the process that connected to this session’s cross-session messaging socket, verified by the kernel and read from the connection itself, never from the payload. Use it, not `from`, to identify the sender: `from` is forgeable by any same-user process. The field is absent when Claude Code can’t verify it, such as on Windows or non-socket ingress, so an absent value means the sender is unverified. For relayed traffic it identifies the relay rather than the message’s author, and process IDs are recyclable, so treat it as provenance rather than an authentication token. Requires Claude Code v2.1.216 or later. [​](#hook-types) Hook Types For a comprehensive guide on using hooks with examples and common patterns, see the [Hooks guide](/docs/en/agent-sdk/hooks). [​](#hookevent) `HookEvent` Available hook events. ```python type HookEvent = | "PreToolUse" | "PostToolUse" | "PostToolUseFailure" | "PostToolBatch" | "Notification" | "UserPromptSubmit" | "UserPromptExpansion" | "SessionStart" | "SessionEnd" | "Stop" | "StopFailure" | "SubagentStart" | "SubagentStop" | "PreCompact" | "PostCompact" | "PermissionRequest" | "PermissionDenied" | "Setup" | "TeammateIdle" | "TaskCreated" | "TaskCompleted" | "Elicitation" | "ElicitationResult" | "ConfigChange" | "DirectoryAdded" | "WorktreeCreate" | "WorktreeRemove" | "InstructionsLoaded" | "CwdChanged" | "FileChanged" | "MessageDisplay"; ``` [​](#hookcallback) `HookCallback` Hook callback function type. ```python type HookCallback = ( input: HookInput, // Union of all hook input types toolUseID: string | undefined, options: { signal: AbortSignal } ) => Promise; ``` [​](#hookcallbackmatcher) `HookCallbackMatcher` Hook configuration with optional matcher. ```python interface HookCallbackMatcher { matcher?: string; hooks: HookCallback[]; timeout?: number; // Timeout in seconds for all hooks in this matcher } ``` [​](#hookinput) `HookInput` Union type of all hook input types. ```python type HookInput = | PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | PostToolBatchHookInput | PermissionDeniedHookInput | NotificationHookInput | UserPromptSubmitHookInput | UserPromptExpansionHookInput | SessionStartHookInput | SessionEndHookInput | StopHookInput | StopFailureHookInput | SubagentStartHookInput | SubagentStopHookInput | PreCompactHookInput | PostCompactHookInput | PermissionRequestHookInput | SetupHookInput | TeammateIdleHookInput | TaskCreatedHookInput | TaskCompletedHookInput | ElicitationHookInput | ElicitationResultHookInput | ConfigChangeHookInput | InstructionsLoadedHookInput | DirectoryAddedHookInput | WorktreeCreateHookInput | WorktreeRemoveHookInput | CwdChangedHookInput | FileChangedHookInput | MessageDisplayHookInput; ``` [​](#basehookinput) `BaseHookInput` Base interface that all hook input types extend. ```python type BaseHookInput = { session_id: string; transcript_path: string; cwd: string; prompt_id?: string; permission_mode?: string; effort?: { level: string }; agent_id?: string; agent_type?: string; }; ``` The `prompt_id` field is a UUID identifying the user prompt currently being processed. It matches the [`prompt.id` attribute on OpenTelemetry events](/docs/en/monitoring-usage#event-correlation-attributes) and is absent until the first user input. Requires Claude Code v2.1.196 or later. [​](#pretoolusehookinput) `PreToolUseHookInput` ```python type PreToolUseHookInput = BaseHookInput & { hook_event_name: "PreToolUse"; tool_name: string; tool_input: unknown; tool_use_id: string; }; ``` [​](#posttoolusehookinput) `PostToolUseHookInput` ```python type PostToolUseHookInput = BaseHookInput & { hook_event_name: "PostToolUse"; tool_name: string; tool_input: unknown; tool_response: unknown; tool_use_id: string; duration_ms?: number; }; ``` [​](#posttoolusefailurehookinput) `PostToolUseFailureHookInput` ```python type PostToolUseFailureHookInput = BaseHookInput & { hook_event_name: "PostToolUseFailure"; tool_name: string; tool_input: unknown; tool_use_id: string; error: string; is_interrupt?: boolean; duration_ms?: number; }; ``` [​](#posttoolbatchhookinput) `PostToolBatchHookInput` Fires once after every tool call in a batch has resolved, before the next model request. `tool_response` carries the serialized `tool_result` content the model sees; the shape differs from `PostToolUseHookInput`’s structured `Output` object. ```python type PostToolBatchHookInput = BaseHookInput & { hook_event_name: "PostToolBatch"; tool_calls: PostToolBatchToolCall[]; }; type PostToolBatchToolCall = { tool_name: string; tool_input: unknown; tool_use_id: string; tool_response?: unknown; }; ``` [​](#permissiondeniedhookinput) `PermissionDeniedHookInput` ```python type PermissionDeniedHookInput = BaseHookInput & { hook_event_name: "PermissionDenied"; tool_name: string; tool_input: unknown; tool_use_id: string; reason: string; }; ``` [​](#notificationhookinput) `NotificationHookInput` ```python type NotificationHookInput = BaseHookInput & { hook_event_name: "Notification"; message: string; title?: string; notification_type: string; }; ``` [​](#userpromptsubmithookinput) `UserPromptSubmitHookInput` ```python type UserPromptSubmitHookInput = BaseHookInput & { hook_event_name: "UserPromptSubmit"; prompt: string; session_title?: string; }; ``` [​](#userpromptexpansionhookinput) `UserPromptExpansionHookInput` ```python type UserPromptExpansionHookInput = BaseHookInput & { hook_event_name: "UserPromptExpansion"; expansion_type: "slash_command" | "mcp_prompt"; command_name: string; command_args: string; command_source?: string; prompt: string; }; ``` [​](#sessionstarthookinput) `SessionStartHookInput` ```python type SessionStartHookInput = BaseHookInput & { hook_event_name: "SessionStart"; source: "startup" | "resume" | "clear" | "compact" | "fork"; agent_type?: string; model?: string; session_title?: string; }; ``` [​](#sessionendhookinput) `SessionEndHookInput` ```python type SessionEndHookInput = BaseHookInput & { hook_event_name: "SessionEnd"; reason: ExitReason; // String from EXIT_REASONS array }; ``` [​](#stophookinput) `StopHookInput` ```python type StopHookInput = BaseHookInput & { hook_event_name: "Stop"; stop_hook_active: boolean; last_assistant_message?: string; background_tasks?: BackgroundTaskSummary[]; session_crons?: SessionCronSummary[]; }; ``` [​](#stopfailurehookinput) `StopFailureHookInput` ```python type StopFailureHookInput = BaseHookInput & { hook_event_name: "StopFailure"; error: SDKAssistantMessageError; error_details?: string; last_assistant_message?: string; }; ``` [​](#subagentstarthookinput) `SubagentStartHookInput` ```python type SubagentStartHookInput = BaseHookInput & { hook_event_name: "SubagentStart"; agent_id: string; agent_type: string; }; ``` [​](#subagentstophookinput) `SubagentStopHookInput` ```python type SubagentStopHookInput = BaseHookInput & { hook_event_name: "SubagentStop"; stop_hook_active: boolean; agent_id: string; agent_transcript_path: string; agent_type: string; last_assistant_message?: string; background_tasks?: BackgroundTaskSummary[]; session_crons?: SessionCronSummary[]; }; type BackgroundTaskSummary = { id: string; type: string; status: string; description: string; command?: string; agent_type?: string; server?: string; tool?: string; name?: string; }; type SessionCronSummary = { id: string; schedule: string; recurring: boolean; prompt: string; }; ``` [​](#precompacthookinput) `PreCompactHookInput` ```python type PreCompactHookInput = BaseHookInput & { hook_event_name: "PreCompact"; trigger: "manual" | "auto"; custom_instructions: string | null; }; ``` [​](#postcompacthookinput) `PostCompactHookInput` ```python type PostCompactHookInput = BaseHookInput & { hook_event_name: "PostCompact"; trigger: "manual" | "auto"; compact_summary: string; }; ``` [​](#permissionrequesthookinput) `PermissionRequestHookInput` ```python type PermissionRequestHookInput = BaseHookInput & { hook_event_name: "PermissionRequest"; tool_name: string; tool_input: unknown; permission_suggestions?: PermissionUpdate[]; }; ``` [​](#setuphookinput) `SetupHookInput` ```python type SetupHookInput = BaseHookInput & { hook_event_name: "Setup"; trigger: "init" | "maintenance"; }; ``` [​](#teammateidlehookinput) `TeammateIdleHookInput` ```python type TeammateIdleHookInput = BaseHookInput & { hook_event_name: "TeammateIdle"; teammate_name: string; /** @deprecated since v2.1.178. Carries the session-derived team name; will be removed. */ team_name: string; }; ``` [​](#taskcreatedhookinput) `TaskCreatedHookInput` ```python type TaskCreatedHookInput = BaseHookInput & { hook_event_name: "TaskCreated"; task_id: string; task_subject: string; task_description?: string; teammate_name?: string; /** @deprecated since v2.1.178. Carries the session-derived team name; will be removed. */ team_name?: string; }; ``` [​](#taskcompletedhookinput) `TaskCompletedHookInput` ```python type TaskCompletedHookInput = BaseHookInput & { hook_event_name: "TaskCompleted"; task_id: string; task_subject: string; task_description?: string; teammate_name?: string; /** @deprecated since v2.1.178. Carries the session-derived team name; will be removed. */ team_name?: string; }; ``` [​](#elicitationhookinput) `ElicitationHookInput` ```python type ElicitationHookInput = BaseHookInput & { hook_event_name: "Elicitation"; mcp_server_name: string; message: string; mode?: "form" | "url"; url?: string; elicitation_id?: string; requested_schema?: Record; }; ``` [​](#elicitationresulthookinput) `ElicitationResultHookInput` ```python type ElicitationResultHookInput = BaseHookInput & { hook_event_name: "ElicitationResult"; mcp_server_name: string; elicitation_id?: string; mode?: "form" | "url"; action: "accept" | "decline" | "cancel"; content?: Record; }; ``` [​](#configchangehookinput) `ConfigChangeHookInput` ```python type ConfigChangeHookInput = BaseHookInput & { hook_event_name: "ConfigChange"; source: | "user_settings" | "project_settings" | "local_settings" | "policy_settings" | "skills"; file_path?: string; }; ``` [​](#instructionsloadedhookinput) `InstructionsLoadedHookInput` ```python type InstructionsLoadedHookInput = BaseHookInput & { hook_event_name: "InstructionsLoaded"; file_path: string; memory_type: "User" | "Project" | "Local" | "Managed"; load_reason: | "session_start" | "nested_traversal" | "path_glob_match" | "include" | "compact"; globs?: string[]; trigger_file_path?: string; parent_file_path?: string; }; ``` [​](#directoryaddedhookinput) `DirectoryAddedHookInput` ```python type DirectoryAddedHookInput = BaseHookInput & { hook_event_name: "DirectoryAdded"; directory: string; source: "slash_command" | "register_repo_root"; }; ``` `directory` is the absolute path of the directory that was added. `source` is `"slash_command"` when `/add-dir` added it and `"register_repo_root"` when the SDK control request did. [​](#worktreecreatehookinput) `WorktreeCreateHookInput` ```python type WorktreeCreateHookInput = BaseHookInput & { hook_event_name: "WorktreeCreate"; name: string; }; ``` [​](#worktreeremovehookinput) `WorktreeRemoveHookInput` ```python type WorktreeRemoveHookInput = BaseHookInput & { hook_event_name: "WorktreeRemove"; worktree_path: string; }; ``` [​](#cwdchangedhookinput) `CwdChangedHookInput` ```python type CwdChangedHookInput = BaseHookInput & { hook_event_name: "CwdChanged"; old_cwd: string; new_cwd: string; }; ``` [​](#filechangedhookinput) `FileChangedHookInput` ```python type FileChangedHookInput = BaseHookInput & { hook_event_name: "FileChanged"; file_path: string; event: "change" | "add" | "unlink"; }; ``` [​](#messagedisplayhookinput) `MessageDisplayHookInput` ```python type MessageDisplayHookInput = BaseHookInput & { hook_event_name: "MessageDisplay"; turn_id: string; message_id: string; index: number; final: boolean; delta: string; }; ``` [​](#hookjsonoutput) `HookJSONOutput` Hook return value. ```python type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput; ``` [​](#asynchookjsonoutput) `AsyncHookJSONOutput` ```python type AsyncHookJSONOutput = { async: true; asyncTimeout?: number; }; ``` [​](#synchookjsonoutput) `SyncHookJSONOutput` ```python type SyncHookJSONOutput = { continue?: boolean; suppressOutput?: boolean; stopReason?: string; decision?: "approve" | "block"; systemMessage?: string; /** * A terminal escape sequence (e.g. OSC 9 / OSC 777 desktop-notification) * for Claude Code to emit on your behalf. Only notification/title OSCs * (0, 1, 2, 9, 99, 777) and BEL are permitted; a value containing * anything else is ignored as a whole. */ terminalSequence?: string; reason?: string; hookSpecificOutput?: | { hookEventName: "PreToolUse"; permissionDecision?: "allow" | "deny" | "ask" | "defer"; permissionDecisionReason?: string; updatedInput?: Record; additionalContext?: string; } | { hookEventName: "UserPromptSubmit"; additionalContext?: string; sessionTitle?: string; /** When decision is "block", omit the original prompt from the block message. */ suppressOriginalPrompt?: boolean; } | { hookEventName: "UserPromptExpansion"; additionalContext?: string; } | { hookEventName: "SessionStart"; additionalContext?: string; initialUserMessage?: string; sessionTitle?: string; watchPaths?: string[]; /** * Re-scan skill and command directories after SessionStart hooks * complete, so skills installed by the hook are available in the * same session. */ reloadSkills?: boolean; } | { hookEventName: "Setup"; additionalContext?: string; } | { hookEventName: "SubagentStart"; additionalContext?: string; } | { hookEventName: "PostToolUse"; additionalContext?: string; updatedToolOutput?: unknown; /** @deprecated Use `updatedToolOutput`, which works for all tools. */ updatedMCPToolOutput?: unknown; } | { hookEventName: "PostToolUseFailure"; additionalContext?: string; } | { hookEventName: "PostToolBatch"; additionalContext?: string; } | { hookEventName: "Stop"; additionalContext?: string; } | { hookEventName: "SubagentStop"; additionalContext?: string; } | { hookEventName: "PermissionDenied"; retry?: boolean; } | { hookEventName: "Notification"; additionalContext?: string; } | { hookEventName: "PermissionRequest"; decision: | { behavior: "allow"; updatedInput?: Record; updatedPermissions?: PermissionUpdate[]; } | { behavior: "deny"; message?: string; interrupt?: boolean; }; } | { hookEventName: "Elicitation"; action?: "accept" | "decline" | "cancel"; content?: Record; } | { hookEventName: "ElicitationResult"; action?: "accept" | "decline" | "cancel"; content?: Record; } | { hookEventName: "CwdChanged"; watchPaths?: string[]; } | { hookEventName: "FileChanged"; watchPaths?: string[]; } | { hookEventName: "WorktreeCreate"; worktreePath: string; } | { hookEventName: "MessageDisplay"; /** Text displayed in place of the delta. Omit (or return the delta unchanged) to display the original. */ displayContent?: string; }; }; ``` [​](#tool-input-types) Tool Input Types Documentation of input schemas for all built-in Claude Code tools. These types are exported from `@anthropic-ai/claude-agent-sdk` and can be used for type-safe tool interactions. [​](#toolinputschemas) `ToolInputSchemas` Union of tool input types exported from `@anthropic-ai/claude-agent-sdk`; members include: ```python type ToolInputSchemas = | AgentInput | ArtifactInput | AskUserQuestionInput | BashInput | CronCreateInput | CronDeleteInput | CronListInput | EnterPlanModeInput | EnterWorktreeInput | ExitPlanModeInput | ExitWorktreeInput | FileEditInput | FileReadInput | FileWriteInput | GlobInput | GrepInput | ListMcpResourcesInput | McpInput | MonitorInput | NotebookEditInput | ProjectsInput | PushNotificationInput | ReadMcpResourceDirInput | ReadMcpResourceInput | RefreshMcpToolsInput | RemoteTriggerInput | REPLInput | ReportFindingsInput | ScheduleWakeupInput | ShowOnboardingRolePickerInput | TaskCreateInput | TaskGetInput | TaskListInput | TaskOutputInput | TaskStopInput | TaskUpdateInput | TodoWriteInput | WebFetchInput | WebSearchInput | WorkflowInput; ``` [​](#agent) Agent **Tool name:** `Agent`. The previous name `Task` is still accepted as an alias, and the `tools` array in the [`SDKSystemMessage`](#sdksystemmessage) init message currently lists this tool as `Task` for backward compatibility. The `mode` field is deprecated and ignored on Claude Code v2.1.212 or later: subagents [inherit the parent session’s permission mode](/docs/en/agent-sdk/permissions#available-modes), and a subagent definition’s [`permissionMode`](#agentdefinition) can override it, except when the parent uses `bypassPermissions`, `acceptEdits`, or `auto`. ```python type AgentInput = { description: string; prompt: string; subagent_type?: string; model?: "sonnet" | "opus" | "haiku" | "fable"; run_in_background?: boolean; name?: string; team_name?: string; // Deprecated; ignored mode?: "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan"; // Deprecated; ignored. Subagents inherit the parent session's permission mode; agent-definition frontmatter may override it isolation?: "worktree" | "remote"; }; ``` Launches a new agent to handle complex, multi-step tasks autonomously. [​](#askuserquestion) AskUserQuestion **Tool name:** `AskUserQuestion` ```python type AskUserQuestionInput = { questions: Array<{ question: string; header: string; options: Array<{ label: string; description: string; preview?: string }>; multiSelect: boolean; }>; answers?: Record; annotations?: Record; metadata?: { source?: string }; }; ``` Asks the user clarifying questions during execution. See [Handle approvals and user input](/docs/en/agent-sdk/user-input#handle-clarifying-questions) for usage details. [​](#bash) Bash **Tool name:** `Bash` ```python type BashInput = { command: string; timeout?: number; // milliseconds, max 600000; higher values are clamped to the max description?: string; run_in_background?: boolean; dangerouslyDisableSandbox?: boolean; }; ``` Executes Bash commands with optional timeout and background execution. The working directory persists between commands; shell state such as exported environment variables doesn’t. [​](#monitor) Monitor **Tool name:** `Monitor` ```python type MonitorInput = { command?: string; ws?: { url: string; protocols?: string[]; }; description: string; timeout_ms: number; persistent: boolean; }; ``` Runs a background source and delivers each event to Claude so it can react without polling: `command` runs a script and emits one event per stdout line, and `ws` opens a WebSocket and emits one event per text frame. Provide exactly one of `command` or `ws`. The `ws` source requires Claude Code v2.1.195 or later. Set `persistent: true` for session-length watches such as log tails. When Monitor runs a command, it follows the same permission rules as Bash; a WebSocket watch prompts for approval separately. See the [Monitor tool reference](/docs/en/tools-reference#monitor-tool) for behavior and provider availability. The exported type marks `timeout_ms` and `persistent` as required because the schema fills in their defaults, 300000 and `false`; a call that omits them validates. [​](#taskoutput) TaskOutput **Tool name:** `TaskOutput` `TaskOutput` is deprecated; prefer `Read` on the task’s output file path. Deprecated since Claude Code v2.1.83. The schemas below remain valid for hooks and permission handlers that encounter the tool. ```python type TaskOutputInput = { task_id: string; block: boolean; timeout: number; }; ``` Retrieves output from a running or completed background task. [​](#edit) Edit **Tool name:** `Edit` ```python type FileEditInput = { file_path: string; old_string: string; new_string: string; replace_all?: boolean; }; ``` Performs exact string replacements in files. [​](#read) Read **Tool name:** `Read` ```python type FileReadInput = { file_path: string; offset?: number; limit?: number; pages?: string; }; ``` Reads files from the local filesystem, including text, images, PDFs, and Jupyter notebooks. Use `pages` for PDF page ranges (for example, `"1-5"`). [​](#write) Write **Tool name:** `Write` ```python type FileWriteInput = { file_path: string; content: string; }; ``` Writes a file to the local filesystem, overwriting if it exists. [​](#glob) Glob **Tool name:** `Glob` ```python type GlobInput = { pattern: string; path?: string; }; ``` Fast file pattern matching that works with any codebase size. [​](#grep) Grep **Tool name:** `Grep` ```python type GrepInput = { pattern: string; path?: string; glob?: string; type?: string; output_mode?: "content" | "files_with_matches" | "count"; "-i"?: boolean; "-o"?: boolean; // print only the matched parts of each line; requires output_mode: "content" "-n"?: boolean; "-B"?: number; "-A"?: number; "-C"?: number; context?: number; head_limit?: number; offset?: number; multiline?: boolean; }; ``` Powerful search tool built on ripgrep with regex support. [​](#taskstop) TaskStop **Tool name:** `TaskStop` ```python type TaskStopInput = { task_id?: string; shell_id?: string; // Deprecated: use task_id }; ``` Stops a running background task or shell by ID. As of v2.1.198, `task_id` also accepts an agent-team teammate or a named background agent by agent ID or name. [​](#notebookedit) NotebookEdit **Tool name:** `NotebookEdit` ```python type NotebookEditInput = { notebook_path: string; cell_id?: string; new_source: string; cell_type?: "code" | "markdown"; edit_mode?: "replace" | "insert" | "delete"; }; ``` Edits cells in Jupyter notebook files. [​](#webfetch) WebFetch **Tool name:** `WebFetch` ```python type WebFetchInput = { url: string; prompt: string; }; ``` Fetches content from a URL and processes it with an AI model. [​](#websearch) WebSearch **Tool name:** `WebSearch` ```python type WebSearchInput = { query: string; allowed_domains?: string[]; blocked_domains?: string[]; }; ``` Searches the web and returns formatted results. [​](#workflow) Workflow **Tool name:** `Workflow` ```python type WorkflowInput = { script?: string; name?: string; scriptPath?: string; args?: unknown; // any JSON value; the published typings render this as an object map resumeFromRunId?: string; title?: string; // ignored; the script's meta block sets the title description?: string; // ignored; the script's meta block sets the description }; ``` Runs a [dynamic workflow](/docs/en/workflows): a script that orchestrates many subagents in the background and returns one consolidated result. The `Workflow` tool is available in Agent SDK v0.3.149 and later. At least one of `script`, `name`, or `scriptPath` is required. | Field | Type | Description | |-------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `script` | `string` | Inline workflow script. Must begin with `export const meta = { name, description }` as a literal, followed by the script body using `agent()`, `parallel()`, `pipeline()`, and `phase()`. An optional `phases` array in `meta` groups agents under named stages in the progress view | | `name` | `string` | Name of a built-in workflow or one saved in `.claude/workflows/`. Resolved to a script | | `scriptPath` | `string` | Path to a workflow script file on disk. Takes precedence over `script` and `name`. Every invocation persists its script and returns the path in the result, so you can edit that file and re-invoke with the same `scriptPath` to iterate | | `args` | `unknown` | Input value exposed to the script as the global `args`, for parameterized named workflows such as a research question or a list of file paths. Pass arrays and objects as actual JSON values, not as a JSON-encoded string | | `resumeFromRunId` | `string` | Run ID of a prior `Workflow` invocation to resume. Completed `agent()` calls with unchanged inputs usually return cached results; the rest run live. [Resume after a pause](/docs/en/workflows#resume-after-a-pause) covers which completed calls re-run. Same session only | | `title` | `string` | Ignored; the script’s `meta` block sets the title | | `description` | `string` | Ignored; the script’s `meta` block sets the description | The schema accepts any JSON value for `args`; the exported type marks it `unknown`, but the published typings render the field as an object map. [​](#todowrite) TodoWrite **Tool name:** `TodoWrite` ```python type TodoWriteInput = { todos: Array<{ content: string; status: "pending" | "in_progress" | "completed"; activeForm: string; }>; }; ``` Creates and manages a structured task list for tracking progress. As of TypeScript Agent SDK 0.3.142, `TodoWrite` is disabled by default. Use `TaskCreate`, `TaskGet`, `TaskUpdate`, and `TaskList` instead. See [Migrate to Task tools](/docs/en/agent-sdk/todo-tracking#migrate-to-task-tools) to update your monitoring code, or set `CLAUDE_CODE_ENABLE_TASKS=0` to revert to `TodoWrite`. [​](#taskcreate) TaskCreate **Tool name:** `TaskCreate` ```python type TaskCreateInput = { subject: string; description: string; activeForm?: string; metadata?: Record; }; ``` Creates a single task and returns its assigned ID. [​](#taskupdate) TaskUpdate **Tool name:** `TaskUpdate` ```python type TaskUpdateInput = { taskId: string; status?: "pending" | "in_progress" | "completed" | "deleted"; subject?: string; description?: string; activeForm?: string; addBlocks?: string[]; addBlockedBy?: string[]; owner?: string; metadata?: Record; }; ``` Patches one task by ID. Set `status` to `"deleted"` to remove it. [​](#taskget) TaskGet **Tool name:** `TaskGet` ```python type TaskGetInput = { taskId: string; }; ``` Returns full details for one task, or `null` when the ID is not found. [​](#tasklist) TaskList **Tool name:** `TaskList` ```python type TaskListInput = {}; ``` Returns a snapshot of all tasks in the current list. [​](#exitplanmode) ExitPlanMode **Tool name:** `ExitPlanMode` ```python type ExitPlanModeInput = { /** Deprecated: no longer used. */ allowedPrompts?: Array<{ tool: "Bash"; prompt: string; }>; [k: string]: unknown; }; ``` Exits plan mode. The `allowedPrompts` field is deprecated and ignored; Claude Code still accepts it so existing callers and transcripts validate. Before v2.1.205, it requested prompt-based Bash permissions for implementing the plan. [​](#listmcpresources) ListMcpResources **Tool name:** `ListMcpResourcesTool` ```python type ListMcpResourcesInput = { server?: string; }; ``` Lists available MCP resources from connected servers. [​](#readmcpresource) ReadMcpResource **Tool name:** `ReadMcpResourceTool` ```python type ReadMcpResourceInput = { server: string; uri: string; }; ``` Reads a specific MCP resource from a server. [​](#enterworktree) EnterWorktree **Tool name:** `EnterWorktree` ```python type EnterWorktreeInput = { name?: string; path?: string; }; ``` Creates and enters a temporary git worktree for isolated work. Pass `path` to switch into an existing worktree instead of creating a new one. On first entry the target must be a registered worktree of the current repository or, in a multi-repo workspace, of a repository nested inside it; from within a worktree session it must be under `.claude/worktrees/` of the session’s repository. `name` and `path` are mutually exclusive. [​](#exitworktree) ExitWorktree **Tool name:** `ExitWorktree` ```python type ExitWorktreeInput = { action: "keep" | "remove"; discard_changes?: boolean; }; ``` Exits the current git worktree and returns to the original working directory. The `keep` action leaves the worktree and branch on disk, while `remove` deletes both. `discard_changes` must be `true` when removing a worktree that has uncommitted files or unmerged commits. [​](#enterplanmode) EnterPlanMode **Tool name:** `EnterPlanMode` ```python type EnterPlanModeInput = {}; ``` Enters plan mode, where Claude researches and presents a plan before making changes. [​](#croncreate) CronCreate **Tool name:** `CronCreate` ```python type CronCreateInput = { cron: string; prompt: string; recurring?: boolean; durable?: boolean; }; ``` Schedules a prompt to run on a 5-field cron schedule in local time. Set `recurring` to `false` to fire once at the next match. Jobs are session-scoped by default: starting a fresh conversation clears them, and resuming with `--resume` or `--continue` restores jobs that haven’t expired. See [Scheduled tasks](/docs/en/scheduled-tasks). Setting `durable` to `true` requests persistence to `.claude/scheduled_tasks.json` so the job survives restarts. Durable scheduling isn’t available in every session: when it isn’t, Claude Code accepts `durable: true` but creates the job session-only. Read the output’s `durable` field to see whether the job persisted. [​](#crondelete) CronDelete **Tool name:** `CronDelete` ```python type CronDeleteInput = { id: string; }; ``` Deletes a scheduled cron job by the ID returned from `CronCreate`. [​](#cronlist) CronList **Tool name:** `CronList` ```python type CronListInput = {}; ``` Lists the scheduled cron jobs: durable jobs from `.claude/scheduled_tasks.json` and session-only jobs from the current session. [​](#schedulewakeup) ScheduleWakeup **Tool name:** `ScheduleWakeup` ```python type ScheduleWakeupInput = { delaySeconds?: number; reason?: string; prompt?: string; stop?: boolean; }; ``` Schedules a one-shot wake-up that fires the given prompt after a delay. This tool backs the self-paced `/loop` command. The runtime clamps `delaySeconds` to between 60 and 3600 seconds. The `delaySeconds`, `reason`, and `prompt` fields are required unless `stop` is true. Setting `stop: true` cancels the pending wakeup and ends the self-paced `/loop`. The `stop` field requires Claude Code v2.1.202 or later. See the [ScheduleWakeup row in the tools reference](/docs/en/tools-reference) for provider availability; it isn’t available on Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, or Microsoft Foundry. [​](#remotetrigger) RemoteTrigger **Tool name:** `RemoteTrigger` ```python type RemoteTriggerInput = { action: "list" | "get" | "create" | "update" | "run"; trigger_id?: string; body?: { [k: string]: unknown; }; }; ``` Manages [Routines](/docs/en/routines), the scheduled and triggered Claude Code runs hosted on Anthropic-managed cloud infrastructure. This tool backs the `/schedule` command. `trigger_id` is required for the `get`, `update`, and `run` actions. `body` is required for `create` and `update`, and optional for `run`. This tool is available only when the session is authenticated with a claude.ai account on a plan with Routines enabled. [​](#pushnotification) PushNotification **Tool name:** `PushNotification` ```python type PushNotificationInput = { message: string; status: "proactive"; }; ``` Sends a proactive push notification to the user. Keep `message` under 200 characters because mobile operating systems truncate longer text. See the [PushNotification row in the tools reference](/docs/en/tools-reference) for provider availability; push delivery runs through Anthropic-hosted infrastructure that isn’t accessible from Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, or Microsoft Foundry. [​](#repl) REPL **Tool name:** `REPL` ```python type REPLInput = { code: string; description?: string; timeout?: number; }; ``` Executes JavaScript code in a persistent REPL. State persists across calls and top-level await is supported. `timeout` is in milliseconds, with a default of 30000 and a maximum of 600000. The types are exported, but the tool is off in SDK sessions unless you set `CLAUDE_CODE_REPL=1` in the [`env` option](#options). It also requires the Bun-based `claude` executable that the native installer provides. [​](#reportfindings) ReportFindings **Tool name:** `ReportFindings` ```python type ReportFindingsInput = { level?: "low" | "medium" | "high" | "xhigh" | "max"; findings: Array<{ file: string; line?: number; summary: string; failure_scenario: string; short_summary?: string; category?: string; verdict?: "CONFIRMED" | "PLAUSIBLE"; outcome?: "fixed" | "skipped" | "no_change_needed"; }>; }; ``` Reports code-review findings as a structured list so Claude Code can render them instead of printing them as text. `level` is the effort level the review ran at. Findings are ordered most-severe first, with at most 32 per call, and the array is empty when none survived. Requires Claude Code v2.1.196 or later. Each finding carries these fields: - `file`: repo-relative path the finding is in. The optional `line` is the 1-indexed line it anchors to. - `summary`: one-sentence statement of the defect. `failure_scenario` describes the concrete inputs and state that lead to the wrong output or crash. - `short_summary`: optional compressed label of at most 60 characters for compact display. Requires Claude Code v2.1.212 or later. - `category`: optional short kebab-case slug of the finding type, such as `correctness` or `test-coverage`. Requires Claude Code v2.1.199 or later. - `verdict`: set when a verify pass ran; absent on inline-only reviews. - `outcome`: set only when re-reporting after applying fixes. [​](#artifact) Artifact **Tool name:** `Artifact` ```python type ArtifactInput = { action?: "publish" | "list"; file_path?: string; favicon?: string; limit?: number; scope?: "mine" | "shared" | "all"; title?: string; description?: string; label?: string; url?: string; force?: boolean; }; ``` Publishes a local `.html` or `.md` file as a hosted artifact page, or lists the user’s published artifacts. Omit `action` or pass `"publish"` to publish `file_path`, which is required for the publish action along with `favicon`, one or two emoji for the browser tab. `title` names the published page in the browser tab and gallery when the HTML file has no `` tag. `url` targets an existing artifact to update in place instead of minting a new one, and `force` is a last-resort overwrite that discards another session’s published version; on a 409 conflict the normal fix is to re-read, merge, and publish again rather than pass `force`. Pass `"list"` to enumerate the user’s published artifacts; only `limit` and `scope` may accompany it. `scope` defaults to `"mine"`, which lists artifacts the user owns; `"shared"` lists artifacts other people shared with the user, and `"all"` lists both. The types are exported, but the tool is off by default in Agent SDK sessions. Publishing also requires every condition in the [artifacts availability table](/docs/en/artifacts#availability), which sessions authenticated with an API key don’t meet. [​](#projects) Projects **Tool name:** `Projects` ```python type ProjectsInput = { method: | "project_info" | "project_read" | "project_search" | "project_write" | "project_delete"; path?: string; content?: string; local_path?: string; present_to_user?: boolean; query?: string; n?: number; }; ``` Reads and writes the claude.ai Project attached to the session. Dispatches on `method`: - `project_info`: returns project metadata and the doc list. - `project_read`: reads one doc by `path`. - `project_search`: queries the project’s knowledge base with `query`. `n` caps the hits and defaults to 5. - `project_write`: creates or replaces a doc at `path` from exactly one of `content`, which carries inline text, or `local_path`, which names a file inside the working directory. `present_to_user: true` marks the written doc as the deliverable the user needs to see. - `project_delete`: deletes a doc by `path`. [​](#readmcpresourcedir) ReadMcpResourceDir **Tool name:** `ReadMcpResourceDirTool` ```python type ReadMcpResourceDirInput = { server: string; uri: string; }; ``` Lists the direct children of a directory resource on an MCP server. Only usable against a server that has declared support for directory listing; the listing isn’t recursive. Directory listing isn’t enabled in every session: when it’s off, the call returns an empty `resources` list and the `error` field reports that directory listing isn’t enabled. [​](#refreshmcptools) RefreshMcpTools **Tool name:** `RefreshMcpTools` ```python type RefreshMcpToolsInput = { server?: string; // refresh only this server; omit to refresh all connected servers }; ``` Re-queries the tool list of connected MCP servers and applies any changes. The types are exported, but Claude Code registers the tool only when you set `CLAUDE_CODE_ENABLE_REFRESH_MCP_TOOLS=1` in the [`env` option](#options), and only in sessions with at least one MCP server. Requires Claude Code v2.1.211 or later. [​](#showonboardingrolepicker) ShowOnboardingRolePicker **Tool name:** `ShowOnboardingRolePicker` ```python type ShowOnboardingRolePickerInput = {}; ``` Renders a clickable role-picker chip row during Cowork onboarding so the user can pick their role and get a matching plugin installed. Takes no arguments; the role list is defined by the client. The call blocks until the user responds. [​](#mcpinput) McpInput **Tool name:** dynamic MCP tool names of the form `mcp__<server>__<tool>` ```python type McpInput = { [k: string]: unknown; }; ``` MCP tool arguments are an open object: each server defines its own parameters, so the type places no constraints on field names or values. Consult the server’s own tool schema for the fields a specific tool accepts. [​](#tool-output-types) Tool Output Types Documentation of output schemas for all built-in Claude Code tools. These types are exported from `@anthropic-ai/claude-agent-sdk` and represent the actual response data returned by each tool. [​](#tooloutputschemas) `ToolOutputSchemas` Union of tool output types exported from `@anthropic-ai/claude-agent-sdk`; members include: ```python type ToolOutputSchemas = | AgentOutput | ArtifactOutput | AskUserQuestionOutput | BashOutput | CronCreateOutput | CronDeleteOutput | CronListOutput | EnterPlanModeOutput | EnterWorktreeOutput | ExitPlanModeOutput | ExitWorktreeOutput | FileEditOutput | FileReadOutput | FileWriteOutput | GlobOutput | GrepOutput | ListMcpResourcesOutput | McpOutput | MonitorOutput | NotebookEditOutput | ProjectsOutput | PushNotificationOutput | ReadMcpResourceDirOutput | ReadMcpResourceOutput | RefreshMcpToolsOutput | RemoteTriggerOutput | REPLOutput | ReportFindingsOutput | ScheduleWakeupOutput | ShowOnboardingRolePickerOutput | TaskCreateOutput | TaskGetOutput | TaskListOutput | TaskStopOutput | TaskUpdateOutput | TodoWriteOutput | WebFetchOutput | WebSearchOutput | WorkflowOutput; ``` [​](#agent-2) Agent **Tool name:** `Agent`. The previous name `Task` is still accepted as an alias, and the `tools` array in the [`SDKSystemMessage`](#sdksystemmessage) init message currently lists this tool as `Task` for backward compatibility. ```python type AgentOutput = | { status: "completed"; agentId: string; agentType?: string; content: Array<{ type: "text"; text: string; citations?: unknown[] | null }>; resolvedModel?: string; modelsUsed?: string[]; totalToolUseCount: number; totalDurationMs: number; totalTokens: number; usage: { input_tokens: number; output_tokens: number; cache_creation_input_tokens: number | null; cache_read_input_tokens: number | null; server_tool_use: { web_search_requests: number; web_fetch_requests: number; } | null; service_tier: string | null; cache_creation: { ephemeral_1h_input_tokens: number; ephemeral_5m_input_tokens: number; } | null; inference_geo?: string | null; speed?: string | null; iterations?: unknown; }; toolStats?: { readCount: number; searchCount: number; bashCount: number; editFileCount: number; linesAdded: number; linesRemoved: number; otherToolCount: number; frameCount?: number; }; prompt: string; worktreePath?: string; worktreeBranch?: string; } | { status: "async_launched"; isAsync?: true; agentId: string; description: string; resolvedModel?: string; modelsUsed?: string[]; prompt: string; outputFile: string; canReadOutputFile?: boolean; } | { status: "remote_launched"; taskId: string; sessionUrl: string; description: string; prompt: string; outputFile: string; }; ``` Returns the result from the subagent. Discriminated on the `status` field: `"completed"` for finished tasks, `"async_launched"` for background tasks, and `"remote_launched"` for tasks Claude Code dispatched to a remote cloud session, where `sessionUrl` links to that session and `taskId` identifies it. On the `completed` variant, `resolvedModel` names the model the subagent started on, which can differ from the requested `model` input when [`availableModels`](/docs/en/model-config#restrict-model-selection) or another override applies. This field requires Claude Code v2.1.174 or later. On `async_launched`, it names the model in use when the task moved to the background. `modelsUsed` lists the models the subagent used, in order. The field is present only when a mid-run swap happened, and a model appears again when the run swapped back to it. On `async_launched`, the list covers the models used before backgrounding. Both `modelsUsed` and the backgrounding behavior of `resolvedModel` require Claude Code v2.1.212 or later. On the `completed` variant, `worktreePath` is set when the subagent ran in an isolated git worktree, and `worktreeBranch` names that worktree’s branch when Claude Code created it. `usage.service_tier` carries the service tier string the API reported for the subagent’s requests. Before v2.1.207, the published type was narrower. It omitted `worktreePath`, `worktreeBranch`, `citations`, `toolStats.frameCount`, and the `inference_geo`, `speed`, and `iterations` usage fields, and it typed `service_tier` as `"standard" | "priority" | "batch"`. Fields the type marks optional can be absent on results recorded by earlier versions. [​](#askuserquestion-2) AskUserQuestion **Tool name:** `AskUserQuestion` ```python type AskUserQuestionOutput = { questions: Array<{ question: string; header: string; options: Array<{ label: string; description: string; preview?: string }>; multiSelect: boolean; }>; answers: Record<string, string>; response?: string; annotations?: Record<string, { preview?: string; notes?: string }>; afkTimeoutMs?: number; }; ``` Returns the questions asked and the user’s answers. `response` is set when the user typed a freeform reply instead of answering the structured questions; when present, Claude receives “The user responded: …” instead of the per-question answer list. [​](#bash-2) Bash **Tool name:** `Bash` ```python type BashOutput = { stdout: string; stderr: string; rawOutputPath?: string; interrupted: boolean; isImage?: boolean; backgroundTaskId?: string; backgroundedByUser?: boolean; timedOutAfterMs?: number; backgroundCwdHint?: string; dangerouslyDisableSandbox?: boolean; returnCodeInterpretation?: string; noOutputExpected?: boolean; structuredContent?: unknown[]; persistedOutputPath?: string; persistedOutputSize?: number; staleReadFileStateHint?: string; ghRateLimitHint?: string; gitOperation?: { commit?: { sha: string; kind: "committed" | "amended" | "cherry-picked" }; push?: { branch: string }; branch?: { ref: string; action: "merged" | "rebased" }; pr?: { number: number; url?: string; action: "created" | "edited" | "merged" | "commented" | "closed" | "ready" | "draft" | "auto-merge-enabled" | "auto-merge-disabled"; }; }; }; ``` Returns command output with stdout/stderr split. Background commands include a `backgroundTaskId`. `timedOutAfterMs` is the timeout in milliseconds, set when the command reached its timeout and moved to the background rather than starting there explicitly. `backgroundCwdHint` is set when the backgrounded command contained a directory-change builtin such as `cd`, `pushd`, `popd`, or `chdir`, and notes that the session working directory didn’t change. Both fields require Claude Code v2.1.210 or later. [​](#monitor-2) Monitor **Tool name:** `Monitor` ```python type MonitorOutput = { taskId: string; timeoutMs: number; persistent?: boolean; }; ``` Returns the background task ID for the running monitor. Use this ID with `TaskStop` to cancel the watch early. [​](#edit-2) Edit **Tool name:** `Edit` ```python type FileEditOutput = { filePath: string; oldString: string; newString: string; originalFile: string | null; structuredPatch: Array<{ oldStart: number; oldLines: number; newStart: number; newLines: number; lines: string[]; }>; userModified: boolean; replaceAll: boolean; gitDiff?: { filename: string; status: "modified" | "added"; additions: number; deletions: number; changes: number; patch: string; repository?: string | null; }; }; ``` Returns the structured diff of the edit operation. [​](#read-2) Read **Tool name:** `Read` ```python type FileReadOutput = | { type: "text"; file: { filePath: string; content: string; numLines: number; startLine: number; totalLines: number; /** True when a whole-file read was auto-paginated because it exceeded the token cap (the content is a partial first page). */ truncatedByTokenCap?: boolean; }; } | { type: "image"; file: { base64: string; type: "image/jpeg" | "image/png" | "image/gif" | "image/webp"; originalSize: number; dimensions?: { originalWidth?: number; originalHeight?: number; displayWidth?: number; displayHeight?: number; }; }; } | { type: "notebook"; file: { filePath: string; cells: unknown[]; }; } | { type: "pdf"; file: { filePath: string; base64: string; originalSize: number; }; } | { type: "parts"; file: { filePath: string; originalSize: number; count: number; outputDir: string; }; } | { type: "file_unchanged"; file: { filePath: string; }; /** Set when the dedup matched a startup-seeded entry (CLAUDE.md / nested memory) rather than a prior Read tool_result. */ source?: "seeded"; }; ``` Returns file contents in a format appropriate to the file type. Discriminated on the `type` field. [​](#write-2) Write **Tool name:** `Write` ```python type FileWriteOutput = { type: "create" | "update"; filePath: string; content: string; structuredPatch: Array<{ oldStart: number; oldLines: number; newStart: number; newLines: number; lines: string[]; }>; originalFile: string | null; gitDiff?: { filename: string; status: "modified" | "added"; additions: number; deletions: number; changes: number; patch: string; repository?: string | null; }; userModified?: boolean; }; ``` Returns the write result with structured diff information. [​](#glob-2) Glob **Tool name:** `Glob` ```python type GlobOutput = { durationMs: number; numFiles: number; filenames: string[]; truncated: boolean; totalMatches?: number; countIsComplete?: boolean; }; ``` Returns file paths matching the glob pattern, sorted by modification time. `totalMatches` and `countIsComplete` require Claude Code v2.1.191 or later. `totalMatches` reports the number of matching files before truncation. When `countIsComplete` is false, `totalMatches` is a lower bound because the underlying search truncated its own output. [​](#grep-2) Grep **Tool name:** `Grep` ```python type GrepOutput = { mode?: "content" | "files_with_matches" | "count"; numFiles: number; filenames: string[]; content?: string; numLines?: number; numMatches?: number; totalFiles?: number; totalLines?: number; appliedLimit?: number; appliedOffset?: number; }; ``` Returns search results. The shape varies by `mode`: file list, content with matches, or match counts. In `count` mode, `numFiles` and `numMatches` are totals over the full result set, not the paginated slice. Before v2.1.208, a `head_limit` or `offset` that truncated the listed entries also truncated those totals. `totalFiles` requires Claude Code v2.1.208 or later and reports the total number of results before `head_limit` and `offset` pagination in `files_with_matches` mode. `totalLines` requires Claude Code v2.1.210 or later and reports the total number of lines before pagination in `content` mode. [​](#taskstop-2) TaskStop **Tool name:** `TaskStop` ```python type TaskStopOutput = { message: string; task_id: string; task_type: string; command?: string; }; ``` Returns confirmation after stopping the background task. [​](#notebookedit-2) NotebookEdit **Tool name:** `NotebookEdit` ```python type NotebookEditOutput = { new_source: string; old_source?: string; cell_id?: string; cell_type: "code" | "markdown"; language: string; edit_mode: string; error?: string; notebook_path: string; original_file: string; updated_file: string; }; ``` Returns the result of the notebook edit with original and updated file contents. [​](#webfetch-2) WebFetch **Tool name:** `WebFetch` ```python type WebFetchOutput = { bytes: number; code: number; codeText: string; result: string; durationMs: number; url: string; artifactRead?: { slug: string; ver?: string; }; }; ``` Returns the fetched content with HTTP status and metadata. [​](#websearch-2) WebSearch **Tool name:** `WebSearch` ```python type WebSearchOutput = { query: string; results: Array< | { tool_use_id: string; content: Array<{ title: string; url: string }>; } | string >; durationSeconds: number; searchCount?: number; }; ``` Returns search results from the web. [​](#workflow-2) Workflow **Tool name:** `Workflow` ```python type WorkflowOutput = { status: "async_launched" | "remote_launched"; taskId: string; taskType?: "local_workflow" | "remote_agent"; workflowName?: string; runId?: string; summary?: string; transcriptDir?: string; scriptPath?: string; sessionUrl?: string; // set when the workflow launched as a remote session warning?: string; error?: string; }; ``` Returns immediately after the tool accepts the invocation. The final result arrives later as a task completion. Check `error` before treating the run as started: a script that fails its syntax check returns `status: "async_launched"` with `error` set, and never runs. | Field | Type | Description | |-----------------|----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `status` | `"async_launched" | "remote_launched"` | The tool accepted the invocation. `"async_launched"` for in-process runs, `"remote_launched"` for runs dispatched to a remote session instead of running in-process | | `taskId` | `string` | Background task identifier for the run | | `taskType` | `"local_workflow" | "remote_agent"` | Task type of the registered background task, matching the `status` arm | | `workflowName` | `string` | The `meta.name` from the workflow script | | `runId` | `string` | Workflow run identifier to pass as `resumeFromRunId` on a later invocation. Absent for `remote_launched` runs, where the cloud session URL is the resume handle | | `summary` | `string` | One-line description of what the workflow does | | `transcriptDir` | `string` | Directory where subagent transcripts are written during execution | | `scriptPath` | `string` | Path to the persisted workflow script for this run. Edit it and pass back as `scriptPath` to rerun without resending the script | | `sessionUrl` | `string` | Cloud session URL, set when `status` is `"remote_launched"` | | `warning` | `string` | Non-blocking heads-up, such as local git state diverging from the pushed branch a cloud session will clone | | `error` | `string` | Set when the script fails its syntax check. When present, the run did not start despite the launched status | [​](#todowrite-2) TodoWrite **Tool name:** `TodoWrite` ```python type TodoWriteOutput = { oldTodos: Array<{ content: string; status: "pending" | "in_progress" | "completed"; activeForm: string; }>; newTodos: Array<{ content: string; status: "pending" | "in_progress" | "completed"; activeForm: string; }>; }; ``` Returns the previous and updated task lists. As of TypeScript Agent SDK 0.3.142, `TodoWrite` is disabled by default. Use `TaskCreate`, `TaskGet`, `TaskUpdate`, and `TaskList` instead. See [Migrate to Task tools](/docs/en/agent-sdk/todo-tracking#migrate-to-task-tools) to update your monitoring code, or set `CLAUDE_CODE_ENABLE_TASKS=0` to revert to `TodoWrite`. [​](#taskcreate-2) TaskCreate **Tool name:** `TaskCreate` ```python type TaskCreateOutput = { task: { id: string; subject: string; }; }; ``` Returns the created task with its assigned ID. [​](#taskupdate-2) TaskUpdate **Tool name:** `TaskUpdate` ```python type TaskUpdateOutput = { success: boolean; taskId: string; updatedFields: string[]; error?: string; statusChange?: { from: string; to: string; }; }; ``` Returns the update result, including which fields changed. [​](#taskget-2) TaskGet **Tool name:** `TaskGet` ```python type TaskGetOutput = { task: { id: string; subject: string; description: string; status: "pending" | "in_progress" | "completed"; blocks: string[]; blockedBy: string[]; } | null; }; ``` Returns the full task record, or `null` when the ID is not found. [​](#tasklist-2) TaskList **Tool name:** `TaskList` ```python type TaskListOutput = { tasks: Array<{ id: string; subject: string; status: "pending" | "in_progress" | "completed"; owner?: string; blockedBy: string[]; }>; }; ``` Returns a snapshot of all tasks in the current list. [​](#exitplanmode-2) ExitPlanMode **Tool name:** `ExitPlanMode` ```python type ExitPlanModeOutput = { plan: string | null; isAgent: boolean; filePath?: string; hasTaskTool?: boolean; planWasEdited?: boolean; awaitingLeaderApproval?: boolean; requestId?: string; }; ``` Returns the plan state after exiting plan mode. [​](#listmcpresources-2) ListMcpResources **Tool name:** `ListMcpResourcesTool` ```python type ListMcpResourcesOutput = Array<{ uri: string; name: string; mimeType?: string; description?: string; server: string; }>; ``` Returns an array of available MCP resources. [​](#readmcpresource-2) ReadMcpResource **Tool name:** `ReadMcpResourceTool` ```python type ReadMcpResourceOutput = { contents: Array<{ uri: string; mimeType?: string; text?: string; blobSavedTo?: string; }>; error?: string; }; ``` Returns the contents of the requested MCP resource. [​](#enterworktree-2) EnterWorktree **Tool name:** `EnterWorktree` ```python type EnterWorktreeOutput = { worktreePath: string; worktreeBranch?: string; message: string; }; ``` Returns information about the git worktree. [​](#exitworktree-2) ExitWorktree **Tool name:** `ExitWorktree` ```python type ExitWorktreeOutput = { action: "keep" | "remove"; originalCwd: string; worktreePath: string; worktreeBranch?: string; tmuxSessionName?: string; discardedFiles?: number; discardedCommits?: number; message: string; }; ``` Returns the action taken and details about the worktree that was exited. [​](#enterplanmode-2) EnterPlanMode **Tool name:** `EnterPlanMode` ```python type EnterPlanModeOutput = { message: string; }; ``` Returns a confirmation that plan mode was entered. [​](#croncreate-2) CronCreate **Tool name:** `CronCreate` ```python type CronCreateOutput = { id: string; humanSchedule: string; recurring: boolean; durable?: boolean; // true when persisted to .claude/scheduled_tasks.json; false when session-only }; ``` Returns the job ID and a human-readable description of the schedule. [​](#crondelete-2) CronDelete **Tool name:** `CronDelete` ```python type CronDeleteOutput = { id: string; }; ``` Returns the ID of the deleted job. [​](#cronlist-2) CronList **Tool name:** `CronList` ```python type CronListOutput = { jobs: { id: string; cron: string; humanSchedule: string; prompt: string; recurring?: boolean; durable?: boolean; }[]; }; ``` Returns the scheduled cron jobs: durable jobs from `.claude/scheduled_tasks.json` and session-only jobs from the current session. A session-only job carries `durable: false`; jobs read from disk omit the field. [​](#schedulewakeup-2) ScheduleWakeup **Tool name:** `ScheduleWakeup` ```python type ScheduleWakeupOutput = { scheduledFor: number; clampedDelaySeconds: number; wasClamped: boolean; stopped?: boolean; cancelledWakeups?: number; }; ``` Returns when the wake-up will fire as an epoch millisecond timestamp, the delay actually used, and whether the requested delay was clamped. The `stopped` field is `true` when the call ended the loop with `stop: true`. It requires Claude Code v2.1.202 or later. The `cancelledWakeups` field counts how many pending wakeups a `stop: true` call cancelled. A value of 0 means nothing was pending, and a recurring `/loop` cron isn’t cancelled by `stop: true`. It requires Claude Code v2.1.206 or later. [​](#remotetrigger-2) RemoteTrigger **Tool name:** `RemoteTrigger` ```python type RemoteTriggerOutput = { status: number; json: string; summary?: string; }; ``` Returns the API response status and body for the trigger operation. [​](#pushnotification-2) PushNotification **Tool name:** `PushNotification` ```python type PushNotificationOutput = { message: string; pushSent?: boolean; localSent?: boolean; disabledReason?: "config_off" | "user_present" | "no_transport"; sentAt?: string; }; ``` Returns delivery details, including whether a push or local notification was sent and why delivery was skipped. [​](#repl-2) REPL **Tool name:** `REPL` ```python type REPLOutput = { code: string; result: { [k: string]: unknown; }; stdout: string; stderr: string; error?: string; registeredTools?: string[]; images?: { base64: string; mediaType: string; }[]; documents?: { base64: string; }[]; }; ``` Returns the execution result, captured console output, and any images or documents surfaced by inner `Read` calls. [​](#reportfindings-2) ReportFindings **Tool name:** `ReportFindings` ```python type ReportFindingsOutput = { count: number; level?: "low" | "medium" | "high" | "xhigh" | "max"; findings: Array<{ file: string; line?: number; summary: string; failure_scenario: string; short_summary?: string; category?: string; verdict?: "CONFIRMED" | "PLAUSIBLE"; outcome?: "fixed" | "skipped" | "no_change_needed"; }>; }; ``` Returns the number of findings reported, the effort level the review ran at, and the findings echoed back for the result body. Requires Claude Code v2.1.196 or later. The echoed `short_summary` field requires Claude Code v2.1.212 or later. [​](#artifact-2) Artifact **Tool name:** `Artifact` ```python type ArtifactOutput = | { url: string; path: string; title?: string; version?: string; capabilities?: unknown; stored?: { contract: string; capabilities?: Record<string, unknown>; }; warnings?: string[]; contract?: string; updated?: boolean; liveSubscription?: string; } | { artifacts: Array<{ title: string; url: string; updatedAt?: string; rel?: "mine" | "shared"; }>; truncated?: boolean; scope?: "shared" | "all"; }; ``` Returns the published page’s `url` and the local `path` that was published for the publish action, with `updated` set to true when the publish redeployed an existing artifact, and `warnings` carrying any publish-time advisories. The list action returns the `artifacts` rows instead, with `truncated` set when more artifacts exist than the requested limit. On listings whose scope isn’t `"mine"`, each row carries `rel` marking whether the user owns the artifact or it was shared with them, and the output’s `scope` records which non-default scope produced the listing; both are absent on default listings. [​](#projects-2) Projects **Tool name:** `Projects` ```python type ProjectsOutput = | { method: "project_info"; notice?: string; name: string; description: string; instructions: string; docs: Array<{ path: string; created_at: string | null }>; files?: Array<{ path: string; file_kind: string; created_at: string | null; }>; sync_sources?: Array<{ type: string | null; config: Record<string, unknown>; }>; knowledge: { knowledge_size: number; max_knowledge_size: number; }; } | { method: "project_read"; notice?: string; path: string; file_kind?: string; content?: string; local_file?: string; created_at: string | null; } | { method: "project_search"; notice?: string; rag: boolean; hits?: Array<{ name?: string; doc_uuid?: string; text?: string }>; docs?: string[]; } | { method: "project_write"; notice?: string; path: string; doc_uuid: string; replaced: boolean; present_to_user?: boolean; local_path?: string; } | { method: "project_delete"; notice?: string; path: string; deleted: boolean; }; ``` Discriminated on the `method` field, mirroring the input. `project_read` returns small text docs inline in `content` and writes larger docs to a `local_file` path instead; `project_search` returns RAG `hits` with `rag: true` when the project’s index is available and falls back to a `docs` path list otherwise. [​](#readmcpresourcedir-2) ReadMcpResourceDir **Tool name:** `ReadMcpResourceDirTool` ```python type ReadMcpResourceDirOutput = { resources: Array<{ uri: string; name: string; mimeType?: string; }>; error?: string; }; ``` Returns the direct children of the directory resource. Subdirectories appear with mimeType `"inode/directory"`; `error` carries a human-readable message when the server couldn’t list the directory. [​](#refreshmcptools-2) RefreshMcpTools **Tool name:** `RefreshMcpTools` ```python type RefreshMcpToolsOutput = Array<{ server: string; status: "refreshed" | "error" | "not_connected"; toolCount?: number; // tools now available from this server added?: string[]; // tool names this refresh added removed?: string[]; // tool names this refresh removed error?: string; // why the refresh failed or the server was unavailable }>; ``` Returns one entry per server: `refreshed` means the re-queried tool list was applied, `error` means the re-query failed and the previous tool set was kept, and `not_connected` means the server has no live connection to query. [​](#showonboardingrolepicker-2) ShowOnboardingRolePicker **Tool name:** `ShowOnboardingRolePicker` ```python type ShowOnboardingRolePickerOutput = { role?: string; dismissed?: boolean; }; ``` Returns the user’s selection: `role` when they picked a role chip or typed one, and `dismissed: true` when they closed the picker. An empty object means the user approved the call without picking a role. [​](#mcpoutput) McpOutput **Tool name:** dynamic MCP tool names of the form `mcp__<server>__<tool>` ```python type McpOutput = | string | { type: string; [k: string]: unknown; }[] | { [k: string]: unknown; }; ``` MCP tool results are returned as a string or an array of content blocks, depending on the server. The trailing plain-object branch in the exported type is a schema-generation artifact: the SDK doesn’t return a bare object, because a server’s structured output is serialized to a JSON string before being returned. At runtime the value may also be `undefined`, although the exported type doesn’t model this. [​](#permission-types) Permission Types [​](#permissionupdate) `PermissionUpdate` Operations for updating permissions. ```python type PermissionUpdate = | { type: "addRules"; rules: PermissionRuleValue[]; behavior: PermissionBehavior; destination: PermissionUpdateDestination; } | { type: "replaceRules"; rules: PermissionRuleValue[]; behavior: PermissionBehavior; destination: PermissionUpdateDestination; } | { type: "removeRules"; rules: PermissionRuleValue[]; behavior: PermissionBehavior; destination: PermissionUpdateDestination; } | { type: "setMode"; mode: PermissionMode; destination: PermissionUpdateDestination; } | { type: "addDirectories"; directories: string[]; destination: PermissionUpdateDestination; } | { type: "removeDirectories"; directories: string[]; destination: PermissionUpdateDestination; }; ``` [​](#permissionbehavior) `PermissionBehavior` ```python type PermissionBehavior = "allow" | "deny" | "ask"; ``` [​](#permissionupdatedestination) `PermissionUpdateDestination` ```python type PermissionUpdateDestination = | "userSettings" // Global user settings | "projectSettings" // Per-directory project settings | "localSettings" // Local project settings | "session" // Current session only | "cliArg"; // CLI argument ``` [​](#permissionrulevalue) `PermissionRuleValue` ```python type PermissionRuleValue = { toolName: string; ruleContent?: string; }; ``` [​](#other-types) Other Types [​](#apikeysource) `ApiKeySource` ```python type ApiKeySource = "user" | "project" | "org" | "temporary" | "oauth"; ``` At runtime, the `apiKeySource` field on the [`SDKSystemMessage`](#sdksystemmessage) init message can also be the string `"none"` when no API key is in use, for example when the session authenticates with an OAuth token. Handle values outside this union defensively. [​](#sdkbeta) `SdkBeta` Available beta features that can be enabled via the `betas` option. See [Beta headers](https://platform.claude.com/docs/en/api/beta-headers) for more information. ```python type SdkBeta = "context-1m-2025-08-07"; ``` The `context-1m-2025-08-07` beta is retired as of April 30, 2026. Passing this value with Claude Sonnet 4.5 or Sonnet 4 has no effect, and requests that exceed the standard 200k-token context window return an error. To use a 1M-token context window, migrate to [Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.6, Claude Opus 4.7, or Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview), which include 1M context at standard pricing with no beta header required. [​](#slashcommand) `SlashCommand` Information about an available slash command. ```python type SlashCommand = { name: string; description: string; argumentHint: string; aliases?: string[]; }; ``` [​](#modelinfo) `ModelInfo` Information about an available model. ```python type ModelInfo = { value: string; resolvedModel?: string; displayName: string; description: string; supportsEffort?: boolean; supportedEffortLevels?: ("low" | "medium" | "high" | "xhigh" | "max")[]; supportsAdaptiveThinking?: boolean; supportsFastMode?: boolean; supportsAutoMode?: boolean; }; ``` | Field | Type | Description | |:---------------------------|:--------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `value` | `string` | Model identifier to pass in API calls | | `resolvedModel` | `string | undefined` | Canonical wire model ID that this entry’s `value` resolves to. An alias entry such as `sonnet` resolves to an explicit model ID such as `claude-sonnet-5`, so a host can match a stored explicit model ID against the alias entry that covers it. Requires Claude Code v2.1.197 or later. | | `displayName` | `string` | Human-readable display name | | `description` | `string` | Description of the model’s capabilities | | `supportsEffort` | `boolean | undefined` | Whether this model supports effort levels | | `supportedEffortLevels` | `("low" | "medium" | "high" | "xhigh" | "max")[] | undefined` | Effort levels this model accepts | | `supportsAdaptiveThinking` | `boolean | undefined` | Whether this model supports adaptive thinking, where Claude decides when and how much to think | | `supportsFastMode` | `boolean | undefined` | Whether this model supports fast mode | | `supportsAutoMode` | `boolean | undefined` | Whether this model supports auto mode | [​](#agentinfo) `AgentInfo` Information about an available subagent that can be invoked via the Agent tool. ```python type AgentInfo = { name: string; description: string; model?: string; }; ``` | Field | Type | Description | |:--------------|:---------------------|:---------------------------------------------------------------------| | `name` | `string` | Agent type identifier (e.g., `"Explore"`, `"general-purpose"`) | | `description` | `string` | Description of when to use this agent | | `model` | `string | undefined` | Model alias this agent uses. If omitted, inherits the parent’s model | [​](#mcpserverstatus) `McpServerStatus` Status of a connected MCP server. ```python type McpServerStatus = { name: string; status: "connected" | "failed" | "needs-auth" | "pending" | "disabled"; serverInfo?: { name: string; version: string; }; error?: string; config?: McpServerStatusConfig; scope?: string; tools?: { name: string; description?: string; annotations?: { readOnly?: boolean; destructive?: boolean; openWorld?: boolean; }; }[]; }; ``` [​](#mcpserverstatusconfig) `McpServerStatusConfig` The configuration of an MCP server as reported by `mcpServerStatus()`. This is the union of all MCP server transport types. ```python type McpServerStatusConfig = | McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig | McpClaudeAIProxyServerConfig; ``` See [`McpServerConfig`](#mcpserverconfig) for details on each transport type. [​](#accountinfo) `AccountInfo` Account information for the authenticated user. ```python type AccountInfo = { email?: string; organization?: string; subscriptionType?: string; tokenSource?: string; apiKeySource?: string; }; ``` [​](#modelusage) `ModelUsage` Per-model usage statistics returned in result messages. The `costUSD` value is a client-side estimate. See [Track cost and usage](/docs/en/agent-sdk/cost-tracking) for billing caveats. ```python type ModelUsage = { inputTokens: number; outputTokens: number; cacheReadInputTokens: number; cacheCreationInputTokens: number; webSearchRequests: number; costUSD: number; contextWindow: number; maxOutputTokens: number; canonicalModel?: string; provider?: string; }; ``` The `canonicalModel` and `provider` fields require Claude Code v2.1.218 or later. `canonicalModel` is the canonical model ID that the pricing lookup uses; it can differ from the raw model string that keys the entry, for example when that string is a provider-specific ID or an alias. `provider` names the API backend that served the model, such as `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle`, or `gateway`. [​](#configscope) `ConfigScope` ```python type ConfigScope = "local" | "user" | "project"; ``` [​](#nonnullableusage) `NonNullableUsage` A version of [`Usage`](#usage) with all nullable fields made non-nullable. ```python type NonNullableUsage = { [K in keyof Usage]: NonNullable<Usage[K]>; }; ``` [​](#usage) `Usage` Token usage statistics. This is the `BetaUsage` type from `@anthropic-ai/sdk`. ```python type Usage = { input_tokens: number; output_tokens: number; cache_creation_input_tokens: number | null; cache_read_input_tokens: number | null; cache_creation: { ephemeral_5m_input_tokens: number; ephemeral_1h_input_tokens: number; } | null; server_tool_use: BetaServerToolUsage | null; service_tier: "standard" | "priority" | "batch" | null; speed: "standard" | "fast" | null; inference_geo: string | null; iterations: BetaIterationsUsage | null; }; ``` `BetaServerToolUsage` and `BetaIterationsUsage` are defined in `@anthropic-ai/sdk`. [​](#calltoolresult) `CallToolResult` MCP tool result type (from `@modelcontextprotocol/sdk/types.js`). `structuredContent` is a JSON object that can be returned alongside `content`, including image blocks. See [Return structured data](/docs/en/agent-sdk/custom-tools#return-structured-data). ```python type CallToolResult = { content: Array<{ type: "text" | "image" | "audio" | "resource" | "resource_link"; // Additional fields vary by type }>; structuredContent?: Record<string, unknown>; isError?: boolean; }; ``` [​](#thinkingconfig) `ThinkingConfig` Controls Claude’s thinking/reasoning behavior. Takes precedence over the deprecated `maxThinkingTokens`. ```python type ThinkingDisplay = "summarized" | "omitted"; type ThinkingConfig = | { type: "adaptive"; display?: ThinkingDisplay } // The model determines when and how much to reason (Opus 4.6+) | { type: "enabled"; budgetTokens?: number; display?: ThinkingDisplay } // Fixed thinking token budget | { type: "disabled" }; // No extended thinking ``` The optional `display` field controls whether thinking text is returned `"summarized"` or `"omitted"`. On Claude Opus 4.7 and later, the API default is `"omitted"`, so set `"summarized"` to receive thinking content in `thinking` blocks. Claude Code doesn’t send `display` to Amazon Bedrock or Google Cloud’s Agent Platform, so on those providers Opus 4.7 and later return empty `thinking` blocks even when you set `display` to `"summarized"`. [​](#spawnedprocess) `SpawnedProcess` Interface for custom process spawning (used with `spawnClaudeCodeProcess` option). `ChildProcess` already satisfies this interface. ```python interface SpawnedProcess { stdin: Writable; stdout: Readable; readonly killed: boolean; readonly exitCode: number | null; kill(signal: NodeJS.Signals): boolean; on( event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void ): void; on(event: "error", listener: (error: Error) => void): void; once( event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void ): void; once(event: "error", listener: (error: Error) => void): void; off( event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void ): void; off(event: "error", listener: (error: Error) => void): void; } ``` [​](#spawnoptions) `SpawnOptions` Options passed to the custom spawn function. ```python interface SpawnOptions { command: string; args: string[]; cwd?: string; env: Record<string, string | undefined>; signal: AbortSignal; } ``` The `signal` field tells your spawn function when to tear down the process. Pass it as the `signal` option to Node’s `spawn()`, or pass it to your VM or container teardown handler.This signal does not fire the instant [`Options.abortController`](#options) aborts. The SDK first closes the process’s stdin and waits about two seconds so the CLI can shut down cleanly, then aborts this signal. To react the moment the caller aborts instead, listen on your own `Options.abortController.signal`, which your spawn function can reference from its enclosing scope. [​](#mcpsetserversresult) `McpSetServersResult` Result of a `setMcpServers()` operation. ```python type McpSetServersResult = { added: string[]; removed: string[]; errors: Record<string, string>; }; ``` [​](#rewindfilesresult) `RewindFilesResult` Result of a `rewindFiles()` operation. ```python type RewindFilesResult = { canRewind: boolean; error?: string; filesChanged?: string[]; insertions?: number; deletions?: number; skippedLinks?: number; }; ``` `skippedLinks` counts the tracked paths the rewind refused to restore or delete for link safety: a symlink, hard link, or other non-regular file at the tracked path, a parent directory that no longer resolves to where it pointed when the checkpoint was taken, or a backup that couldn’t be read safely. The field requires Claude Code v2.1.216 or later. A preview call with `rewindFiles(userMessageId, { dryRun: true })` never sets it. [​](#sdkstatusmessage) `SDKStatusMessage` Status update message (e.g., compacting). ```python type SDKStatusMessage = { type: "system"; subtype: "status"; status: "compacting" | null; permissionMode?: PermissionMode; uuid: UUID; session_id: string; }; ``` [​](#sdktasknotificationmessage) `SDKTaskNotificationMessage` Notification when a background task completes, fails, or is stopped. Background tasks include `run_in_background` Bash commands, [Monitor](#monitor) watches, and background subagents. ```python type SDKTaskNotificationMessage = { type: "system"; subtype: "task_notification"; task_id: string; tool_use_id?: string; status: "completed" | "failed" | "stopped"; output_file: string; summary: string; usage?: { total_tokens: number; tool_uses: number; duration_ms: number; }; uuid: UUID; session_id: string; }; ``` Claude Code prepends a notice to every task notification it sends to the model. The notice states that no human input has occurred, so the model doesn’t treat the notification as a user instruction or approval. To detect a task-notification turn, check `origin.kind === "task-notification"` on [`SDKUserMessage`](#sdkusermessage) or [`SDKResultMessage`](#sdkresultmessage) rather than matching on the notice text. Before v2.1.205, Claude Code left the notice off notifications that arrived while the session was idle. [​](#sdktoolusesummarymessage) `SDKToolUseSummaryMessage` Summary of tool usage in a conversation. ```python type SDKToolUseSummaryMessage = { type: "tool_use_summary"; summary: string; preceding_tool_use_ids: string[]; uuid: UUID; session_id: string; }; ``` [​](#sdkhookstartedmessage) `SDKHookStartedMessage` Emitted when a hook begins executing. Claude Code delivers this message, [`SDKHookProgressMessage`](#sdkhookprogressmessage), and [`SDKHookResponseMessage`](#sdkhookresponsemessage) to the message stream immediately, including while a `SessionStart` or `Setup` hook is still running during session startup. Claude Code v2.1.169 through v2.1.203 delivered these messages in one batch after a `SessionStart` or `Setup` hook completed; v2.1.204 restored live delivery. ```python type SDKHookStartedMessage = { type: "system"; subtype: "hook_started"; hook_id: string; hook_name: string; hook_event: string; uuid: UUID; session_id: string; }; ``` [​](#sdkhookprogressmessage) `SDKHookProgressMessage` Emitted while a hook is running, with stdout/stderr output. ```python type SDKHookProgressMessage = { type: "system"; subtype: "hook_progress"; hook_id: string; hook_name: string; hook_event: string; stdout: string; stderr: string; output: string; uuid: UUID; session_id: string; }; ``` [​](#sdkhookresponsemessage) `SDKHookResponseMessage` Emitted when a hook finishes executing. ```python type SDKHookResponseMessage = { type: "system"; subtype: "hook_response"; hook_id: string; hook_name: string; hook_event: string; output: string; stdout: string; stderr: string; exit_code?: number; outcome: "success" | "error" | "cancelled"; uuid: UUID; session_id: string; }; ``` [​](#sdktoolprogressmessage) `SDKToolProgressMessage` Emitted periodically while a tool is executing to indicate progress. ```python type SDKToolProgressMessage = { type: "tool_progress"; tool_use_id: string; tool_name: string; parent_tool_use_id: string | null; elapsed_time_seconds: number; task_id?: string; heartbeat?: boolean; subagent_type?: string; subagent_retry?: { agent_id: string; attempt: number; max_retries: number; retry_delay_ms: number; error_status: number | null; error_category: string; }; uuid: UUID; session_id: string; }; ``` While a tool call runs in the main conversation, Claude Code emits a `tool_progress` message every 30 seconds with `heartbeat: true`. Each heartbeat carries the tool name and elapsed seconds, so you can distinguish a long-running call from a stalled session. Claude Code doesn’t emit heartbeats for the Agent tool, whose subagents stream their own progress, or for tool calls inside a subagent. The `heartbeat` field requires Agent SDK v0.3.214 or later. On `tool_progress` messages for the Agent tool, `subagent_type` names the running subagent type, such as `general-purpose`. `subagent_retry` is present while that subagent waits out an API error backoff, such as a rate limit or overload, with one message per retry attempt. Both fields require Agent SDK v0.3.214 or later. To render a retry indicator from `subagent_retry`: - Track the indicator by `parent_tool_use_id`, which is unique per subagent. `tool_use_id` is shared by parallel subagents from one assistant turn, so tracking by it would let one subagent’s update clear another’s indicator. - Clear the indicator when a later `tool_progress` for the same `parent_tool_use_id` arrives without the field, or when the tool’s result message arrives. `attempt` can exceed `max_retries` under persistent retry, so don’t derive clearing from the counters. - Treat `error_category` as a closed set of tokens for choosing your own message text, not as display text: `rate_limit`, `overloaded`, `authentication_failed`, `server_error`, or `unknown`. [​](#sdkauthstatusmessage) `SDKAuthStatusMessage` Emitted during authentication flows. ```python type SDKAuthStatusMessage = { type: "auth_status"; isAuthenticating: boolean; output: string[]; error?: string; uuid: UUID; session_id: string; }; ``` [​](#sdktaskstartedmessage) `SDKTaskStartedMessage` Emitted when a background task begins. The `task_type` field is `"local_bash"` for background Bash commands and [Monitor](#monitor) watches, `"local_agent"` for subagents, or `"remote_agent"`. ```python type SDKTaskStartedMessage = { type: "system"; subtype: "task_started"; task_id: string; tool_use_id?: string; description: string; task_type?: string; uuid: UUID; session_id: string; }; ``` [​](#sdktaskprogressmessage) `SDKTaskProgressMessage` Emitted periodically while a subagent or background task is running. The `summary` field is populated only when [`agentProgressSummaries`](#options) is enabled. ```python type SDKTaskProgressMessage = { type: "system"; subtype: "task_progress"; task_id: string; tool_use_id?: string; description: string; subagent_type?: string; usage: { total_tokens: number; tool_uses: number; duration_ms: number; }; last_tool_name?: string; summary?: string; uuid: UUID; session_id: string; }; ``` [​](#sdktaskupdatedmessage) `SDKTaskUpdatedMessage` Emitted when a background task’s state changes, such as when it transitions from `running` to `completed`. Merge `patch` into your local task map keyed by `task_id`. The `end_time` field is a Unix epoch timestamp in milliseconds, comparable with `Date.now()`. ```python type SDKTaskUpdatedMessage = { type: "system"; subtype: "task_updated"; task_id: string; patch: { status?: "pending" | "running" | "completed" | "failed" | "killed"; description?: string; end_time?: number; total_paused_ms?: number; error?: string; is_backgrounded?: boolean; }; uuid: UUID; session_id: string; }; ``` [​](#sdkbackgroundtaskschangedmessage) `SDKBackgroundTasksChangedMessage` Emitted whenever the set of live background tasks changes: a task starts, completes, is killed, or a foreground agent is backgrounded. The `tasks` array is the full live set. Replace any cached set with each payload instead of pairing `task_started` and `task_notification` events, so the next membership change corrects any event you missed. Ordering relative to those per-task events is unspecified, so don’t correlate the two streams. Nothing is emitted at startup. Reset to an empty set whenever the session’s CLI process starts or restarts and let the next membership change repopulate it. Requires Claude Code v2.1.203 or later. ```python type SDKBackgroundTasksChangedMessage = { type: "system"; subtype: "background_tasks_changed"; tasks: { task_id: string; task_type: string; description: string; }[]; uuid: UUID; session_id: string; }; ``` [​](#sdkthinkingtokensmessage) `SDKThinkingTokensMessage` Emitted while Claude is producing a thinking block, including a redacted one, carrying a running estimate of the thinking tokens generated so far. `estimated_tokens` is the running total for the current thinking block and `estimated_tokens_delta` is the increment carried by this frame. Use it for progress display. The final count for the top-level agent loop is the result message’s `usage.output_tokens`, which [doesn’t include subagent tokens](/docs/en/agent-sdk/cost-tracking#get-the-total-cost-of-a-query); use [`modelUsage`](#modelusage) for whole-tree accounting. Requires Claude Code v2.1.153 or later. ```python type SDKThinkingTokensMessage = { type: "system"; subtype: "thinking_tokens"; estimated_tokens: number; estimated_tokens_delta: number; uuid: UUID; session_id: string; }; ``` [​](#sdkfilespersistedevent) `SDKFilesPersistedEvent` Emitted when file checkpoints are persisted to disk. ```python type SDKFilesPersistedEvent = { type: "system"; subtype: "files_persisted"; files: { filename: string; file_id: string }[]; failed: { filename: string; error: string }[]; processed_at: string; uuid: UUID; session_id: string; }; ``` [​](#sdkratelimitevent) `SDKRateLimitEvent` Emitted when the session encounters a rate limit. ```python type SDKRateLimitEvent = { type: "rate_limit_event"; rate_limit_info: { status: "allowed" | "allowed_warning" | "rejected"; resetsAt?: number; utilization?: number; errorCode?: "credits_required"; canUserPurchaseCredits?: boolean; hasChargeableSavedPaymentMethod?: boolean; }; uuid: UUID; session_id: string; }; ``` When `errorCode` is `"credits_required"`, the rejection is from a claude.ai subscription whose included usage is exhausted, and the session cannot continue until the user buys usage credits. `canUserPurchaseCredits` indicates whether the authenticated user can buy credits for the account, and `hasChargeableSavedPaymentMethod` indicates whether a saved payment method is on file. All three fields are absent on rate-limit events that are not credits-required rejections. Requires Claude Code v2.1.181 or later. [​](#sdklocalcommandoutputmessage) `SDKLocalCommandOutputMessage` Output from a local slash command (for example, `/voice` or `/usage`). Displayed as assistant-style text in the transcript. ```python type SDKLocalCommandOutputMessage = { type: "system"; subtype: "local_command_output"; content: string; uuid: UUID; session_id: string; }; ``` [​](#sdkcommandschangedmessage) `SDKCommandsChangedMessage` Emitted when the set of available commands changes mid-session, such as when Claude Code discovers skills as the agent enters a subdirectory. The `commands` array is the full updated list, so replace any cached command list with this payload. Calling [`supportedCommands()`](#query-object) after this message returns the same updated list, because the method tracks the latest push; this requires Agent SDK v0.3.216 or later. In earlier SDK versions, `supportedCommands()` returns the snapshot captured at initialization and never reflects mid-session changes. ```python type SDKCommandsChangedMessage = { type: "system"; subtype: "commands_changed"; commands: SlashCommand[]; uuid: UUID; session_id: string; }; ``` [​](#sdkpromptsuggestionmessage) `SDKPromptSuggestionMessage` Emitted after each turn when `promptSuggestions` is enabled. Contains a predicted next user prompt. ```python type SDKPromptSuggestionMessage = { type: "prompt_suggestion"; suggestion: string; uuid: UUID; session_id: string; }; ``` [​](#sdkconversationresetmessage) `SDKConversationResetMessage` Emitted when the session’s conversation is replaced without ending the session, such as after `/clear`, on plan-mode exit, or when a fresh conversation starts. Mount an empty transcript under `new_conversation_id` and discard any cached session title. ```python type SDKConversationResetMessage = { type: "conversation_reset"; new_conversation_id: UUID; uuid: UUID; session_id: string; }; ``` The SDK’s published typings declare `SDKConversationResetMessage` in Claude Code v2.1.203 and later. Before v2.1.203, `SDKMessage` referenced the type without declaring it, so narrowing on `type === "conversation_reset"` failed to typecheck when `skipLibCheck` was disabled. [​](#aborterror) `AbortError` Custom error class for abort operations. ```python class AbortError extends Error {} ``` [​](#sandbox-configuration) Sandbox Configuration [​](#sandboxsettings) `SandboxSettings` Configuration for sandbox behavior. Use this to enable command sandboxing and configure network restrictions programmatically. ```python type SandboxSettings = { enabled?: boolean; failIfUnavailable?: boolean; autoAllowBashIfSandboxed?: boolean; excludedCommands?: string[]; allowUnsandboxedCommands?: boolean; network?: SandboxNetworkConfig; filesystem?: SandboxFilesystemConfig; ignoreViolations?: Record<string, string[]>; enableWeakerNestedSandbox?: boolean; ripgrep?: { command: string; args?: string[] }; }; ``` | Property | Type | Default | Description | |:----------------------------|:------------------------------------------------------|:------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `enabled` | `boolean` | `false` | Enable sandbox mode for command execution | | `failIfUnavailable` | `boolean` | `true` | Stop at startup if `enabled` is `true` but the sandbox can’t start. Set `false` to fall back to unsandboxed execution with a warning on stderr | | `autoAllowBashIfSandboxed` | `boolean` | `true` | Auto-approve bash commands when sandbox is enabled | | `excludedCommands` | `string[]` | `[]` | Commands that always bypass sandbox restrictions (e.g., `['docker']`). These run unsandboxed automatically without model involvement | | `allowUnsandboxedCommands` | `boolean` | `true` | Allow the model to request running commands outside the sandbox. When `true`, the model can set `dangerouslyDisableSandbox` in tool input, which falls back to the [permissions system](#permissions-fallback-for-unsandboxed-commands) | | `network` | [`SandboxNetworkConfig`](#sandboxnetworkconfig) | `undefined` | Network-specific sandbox configuration | | `filesystem` | [`SandboxFilesystemConfig`](#sandboxfilesystemconfig) | `undefined` | Filesystem-specific sandbox configuration for read/write restrictions | | `ignoreViolations` | `Record<string, string[]>` | `undefined` | Map of violation categories to patterns to ignore (e.g., `{ file: ['/tmp/*'], network: ['localhost'] }`) | | `enableWeakerNestedSandbox` | `boolean` | `false` | Enable a weaker nested sandbox for compatibility | | `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Custom ripgrep binary configuration for sandbox environments | The sandbox depends on platform support and, on Linux, tools like `bubblewrap` and `socat`. When `enabled` is `true` and the sandbox can’t start, `query()` reports a `result` message with `subtype: "error_during_execution"` and the reason in `errors`. For a single message `query()` call, the SDK throws after yielding that error result, so wrap the loop in a try block to continue past it. See [Handle the result](/docs/en/agent-sdk/agent-loop#handle-the-result) for the error contract.To run unsandboxed instead, set `failIfUnavailable: false`. [​](#example-usage) Example usage ```python import { query } from "@anthropic-ai/claude-agent-sdk"; try { for await (const message of query({ prompt: "Build and test my project", options: { sandbox: { enabled: true, autoAllowBashIfSandboxed: true, network: { allowLocalBinding: true } } } })) { if ("result" in message) console.log(message.result); } } catch (error) { // A single-shot query() throws after yielding an error result, // such as when the sandbox can't start (failIfUnavailable defaults to true). console.log(`Session ended with an error: ${error}`); } ``` **Unix socket security:** The `allowUnixSockets` option can grant access to powerful system services. For example, allowing `/var/run/docker.sock` effectively grants full host system access through the Docker API, bypassing sandbox isolation. Only allow Unix sockets that are strictly necessary and understand the security implications of each. [​](#sandboxnetworkconfig) `SandboxNetworkConfig` Network-specific configuration for sandbox mode. These settings apply to sandboxed Bash commands when `enabled` is `true` in the parent [`SandboxSettings`](#sandboxsettings). They do not restrict the WebFetch tool, which uses [permission rules](/docs/en/permissions#webfetch) instead. ```python type SandboxNetworkConfig = { allowedDomains?: string[]; deniedDomains?: string[]; strictAllowlist?: boolean; allowManagedDomainsOnly?: boolean; allowLocalBinding?: boolean; allowUnixSockets?: string[]; allowAllUnixSockets?: boolean; httpProxyPort?: number; socksProxyPort?: number; }; ``` | Property | Type | Default | Description | |:--------------------------|:-----------|:------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `allowedDomains` | `string[]` | `[]` | Domain names that sandboxed processes can access | | `deniedDomains` | `string[]` | `[]` | Domain names that sandboxed processes cannot access. Takes precedence over `allowedDomains` | | `strictAllowlist` | `boolean` | `false` | Deny sandboxed commands access to hosts not in `allowedDomains` instead of prompting. Enforced for sandboxed commands only; in-process tools such as WebFetch aren’t gated by it. Only honored from user, managed, or CLI `--settings` settings; project settings are ignored. Requires Claude Code v2.1.219 or later | | `allowManagedDomainsOnly` | `boolean` | `false` | Managed-settings only. When set in [managed settings](/docs/en/permissions#managed-settings), only `allowedDomains` entries from managed settings are honored and entries from user, project, or local settings are ignored. Has no effect when set via SDK options | | `allowLocalBinding` | `boolean` | `false` | Allow processes to bind to local ports (e.g., for dev servers) | | `allowUnixSockets` | `string[]` | `[]` | Unix socket paths that processes can access (e.g., Docker socket) | | `allowAllUnixSockets` | `boolean` | `false` | Allow access to all Unix sockets | | `httpProxyPort` | `number` | `undefined` | HTTP proxy port for network requests | | `socksProxyPort` | `number` | `undefined` | SOCKS proxy port for network requests | The built-in sandbox proxy enforces `allowedDomains` based on the requested hostname and does not terminate or inspect TLS traffic, so techniques such as [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) can potentially bypass it. See [Sandboxing security limitations](/docs/en/sandboxing#security-limitations) for details and [Secure deployment](/docs/en/agent-sdk/secure-deployment#traffic-forwarding) for configuring a TLS-terminating proxy. [​](#sandboxfilesystemconfig) `SandboxFilesystemConfig` Filesystem-specific configuration for sandbox mode. ```python type SandboxFilesystemConfig = { allowWrite?: string[]; denyWrite?: string[]; denyRead?: string[]; }; ``` | Property | Type | Default | Description | |:-------------|:-----------|:--------|:--------------------------------------------| | `allowWrite` | `string[]` | `[]` | File path patterns to allow write access to | | `denyWrite` | `string[]` | `[]` | File path patterns to deny write access to | | `denyRead` | `string[]` | `[]` | File path patterns to deny read access to | [​](#permissions-fallback-for-unsandboxed-commands) Permissions Fallback for Unsandboxed Commands When `allowUnsandboxedCommands` is enabled, the model can request to run commands outside the sandbox by setting `dangerouslyDisableSandbox: true` in the tool input. These requests fall back to the existing permissions system, meaning your `canUseTool` handler is invoked, allowing you to implement custom authorization logic. In the example below, `isCommandAuthorized` stands in for an authorization check you define. **`excludedCommands` vs `allowUnsandboxedCommands`:** - `excludedCommands`: A static list of commands that always bypass the sandbox automatically (e.g., `['docker']`). The model has no control over this. - `allowUnsandboxedCommands`: Lets the model decide at runtime whether to request unsandboxed execution by setting `dangerouslyDisableSandbox: true` in the tool input. ```python import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Deploy my application", options: { sandbox: { enabled: true, allowUnsandboxedCommands: true // Model can request unsandboxed execution }, permissionMode: "default", canUseTool: async (tool, input) => { // Check if the model is requesting to bypass the sandbox if (tool === "Bash" && input.dangerouslyDisableSandbox) { // The model is requesting to run this command outside the sandbox console.log(`Unsandboxed command requested: ${input.command}`); if (isCommandAuthorized(input.command)) { return { behavior: "allow" as const, updatedInput: input }; } return { behavior: "deny" as const, message: "Command not authorized for unsandboxed execution" }; } return { behavior: "allow" as const, updatedInput: input }; } } })) { if ("result" in message) console.log(message.result); } ``` This pattern enables you to: - **Audit model requests:** Log when the model requests unsandboxed execution - **Implement allowlists:** Only permit specific commands to run unsandboxed - **Add approval workflows:** Require explicit authorization for privileged operations Commands running with `dangerouslyDisableSandbox: true` have full system access. Ensure your `canUseTool` handler validates these requests carefully.If `permissionMode` is set to `bypassPermissions` and `allowUnsandboxedCommands` is enabled, the model can autonomously execute commands outside the sandbox without approval prompts (an explicit [`ask` rule](/docs/en/agent-sdk/permissions#how-permissions-are-evaluated) still forces one). Review enterprise hardening guidance before enabling this combination. [​](#see-also) See also - [SDK overview](/docs/en/agent-sdk/overview) - General SDK concepts - [Python SDK reference](/docs/en/agent-sdk/python) - Python SDK documentation - [CLI reference](/docs/en/cli-reference) - Command-line interface - [Common workflows](/docs/en/common-workflows) - Step-by-step guides --- ## agent-sdk-secure-deployment-0345127a86.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Securely deploying AI agents > A guide to securing Claude Code and Agent SDK deployments with isolation, credential management, and network controls Claude Code and the Agent SDK are powerful tools that can execute code, access files, and interact with external services on your behalf. Like any tool with these capabilities, deploying them thoughtfully ensures you get the benefits while maintaining appropriate controls. Unlike traditional software that follows predetermined code paths, these tools generate their actions dynamically based on context and goals. This flexibility is what makes them useful, but it also means their behavior can be influenced by the content they process: files, webpages, or user input. This is sometimes called prompt injection. For example, if a repository's README contains unusual instructions, Claude Code might incorporate those into its actions in ways the operator didn't anticipate. This guide covers practical ways to reduce this risk. The good news is that securing an agent deployment doesn't require exotic infrastructure. The same principles that apply to running any semi-trusted code apply here: isolation, least privilege, and defense in depth. Claude Code includes several security features that help with common concerns, and this guide walks through these along with additional hardening options for those who need them. Not every deployment needs maximum security. A developer running Claude Code on their laptop has different requirements than a company processing customer data in a multi-tenant environment. This guide presents options ranging from Claude Code's built-in security features to hardened production architectures, so you can choose what fits your situation. ## Threat model Agents can take unintended actions due to prompt injection (instructions embedded in content they process) or model error. Claude models are designed to resist this; see the [model overview](../20-Models/about-claude-models-overview-2bbf09ff82.md) and the system card for the model you deploy for evaluation details. Defense in depth is still good practice though. For example, if an agent processes a malicious file that instructs it to send customer data to an external server, network controls can block that request entirely. ## Built-in security features Claude Code includes several security features that address common concerns. See the [security documentation](../22-Safety-Policy/security-claude-code-docs-7538e94c51.md) for full details. * **Permissions system**: Every tool and bash command can be configured to allow, block, or prompt the user for approval. Use glob patterns to create rules like "allow all npm commands" or "block any command with sudo". Organizations can set policies that apply across all users. See [permissions](../02-Claude-Code-CLI/configure-permissions-claude-code-docs-7b0e64d485.md). * **Command parsing for permissions**: Before executing bash commands, Claude Code parses them into an AST and matches the result against your permission rules. Commands that cannot be parsed cleanly, or that do not match an allow rule, require explicit approval. A small set of constructs such as `eval` always require approval regardless of allow rules. This is a permission gate, not a sandbox; it does not infer whether a command is dangerous from its target path or effects. * **Web search summarization**: Search results are summarized rather than passing raw content directly into the context, reducing the risk of prompt injection from malicious web content. * **Sandbox mode**: Bash commands can run in a sandboxed environment that restricts filesystem and network access. See the [sandboxing documentation](../22-Safety-Policy/sandboxing-claude-code-docs-5f97cd27c4.md) for details. ## Security principles For deployments that require additional hardening beyond Claude Code's defaults, these principles guide the available options. ### Security boundaries A security boundary separates components with different trust levels. For high-security deployments, you can place sensitive resources (like credentials) outside the boundary containing the agent. If something goes wrong in the agent's environment, resources outside that boundary remain protected. For example, rather than giving an agent direct access to an API key, you could run a proxy outside the agent's environment that injects the key into requests. The agent can make API calls, but it never sees the credential itself. This pattern is useful for multi-tenant deployments or when processing untrusted content. ### Least privilege When needed, you can restrict the agent to only the capabilities required for its specific task: | Resource | Restriction options | | ------------------- | ----------------------------------------------- | | Filesystem | Mount only needed directories, prefer read-only | | Network | Restrict to specific endpoints via proxy | | Credentials | Inject via proxy rather than exposing directly | | System capabilities | Drop Linux capabilities in containers | ### Defense in depth For high-security environments, layering multiple controls provides additional protection. Options include: * Container isolation * Network restrictions * Filesystem controls * Request validation at a proxy The right combination depends on your threat model and operational requirements. ## Isolation technologies Different isolation technologies offer different tradeoffs between security strength, performance, and operational complexity. <Info> In all of these configurations, Claude Code (or your Agent SDK application) runs inside the isolation boundary (the sandbox, container, or VM). The security controls described below restrict what the agent can access from within that boundary. </Info> | Technology | Isolation strength | Performance overhead | Complexity | | ----------------------- | ------------------------------ | -------------------- | ----------- | | Sandbox runtime | Good (secure defaults) | Very low | Low | | Containers (Docker) | Setup dependent | Low | Medium | | gVisor | Excellent (with correct setup) | Medium/High | Medium | | VMs (Firecracker, QEMU) | Excellent (with correct setup) | High | Medium/High | ### Sandbox runtime For lightweight isolation without containers, [sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime) enforces filesystem and network restrictions at the OS level. The main advantage is simplicity: no Docker configuration, container images, or networking setup required. The proxy and filesystem restrictions are built in. You provide a settings file specifying allowed domains and paths. **How it works:** * **Filesystem**: Uses OS primitives (`bubblewrap` on Linux, `sandbox-exec` on macOS) to restrict read/write access to configured paths * **Network**: Removes network namespace (Linux) or uses Seatbelt profiles (macOS) to route network traffic through a built-in proxy * **Configuration**: JSON-based allowlists for domains and filesystem paths **Setup:** ```bash theme={null} npm install @anthropic-ai/sandbox-runtime ``` Then create a configuration file specifying allowed paths and domains. **Security considerations:** 1. **Same-host kernel**: Unlike VMs, sandboxed processes share the host kernel. A kernel vulnerability could theoretically enable escape. For some threat models this is acceptable, but if you need kernel-level isolation, use gVisor or a separate VM. 2. **No TLS inspection**: The proxy allowlists domains but doesn't inspect encrypted traffic. If the agent has permissive credentials for an allowed domain, ensure it isn't possible to use that domain to trigger other network requests or to exfiltrate data. For many single-developer and CI/CD use cases, sandbox-runtime raises the bar significantly with minimal setup. The sections below cover containers and VMs for deployments requiring stronger isolation. ### Containers Containers provide isolation through Linux namespaces. Each container has its own view of the filesystem, process tree, and network stack, while sharing the host kernel. A security-hardened container configuration might look like this: ```bash theme={null} docker run \ --cap-drop ALL \ --security-opt no-new-privileges \ --security-opt seccomp=/path/to/seccomp-profile.json \ --read-only \ --tmpfs /tmp:rw,noexec,nosuid,size=100m \ --tmpfs /home/agent:rw,noexec,nosuid,size=500m \ --network none \ --memory 2g \ --cpus 2 \ --pids-limit 100 \ --user 1000:1000 \ -v /path/to/code:/workspace:ro \ -v /var/run/proxy.sock:/var/run/proxy.sock:ro \ agent-image ``` Here's what each option does: | Option | Purpose | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--cap-drop ALL` | Removes Linux capabilities like `NET_ADMIN` and `SYS_ADMIN` that could enable privilege escalation | | `--security-opt no-new-privileges` | Prevents processes from gaining privileges through setuid binaries | | `--security-opt seccomp=...` | Restricts available syscalls; Docker's default blocks \~44, custom profiles can block more | | `--read-only` | Makes the container's root filesystem immutable, preventing the agent from persisting changes | | `--tmpfs /tmp:...` | Provides a writable temporary directory that's cleared when the container stops | | `--network none` | Removes all network interfaces; the agent communicates through the mounted Unix socket below | | `--memory 2g` | Limits memory usage to prevent resource exhaustion | | `--pids-limit 100` | Limits process count to prevent fork bombs | | `--user 1000:1000` | Runs as a non-root user | | `-v ...:/workspace:ro` | Mounts code read-only so the agent can analyze but not modify it. **Avoid mounting sensitive host directories like `~/.ssh`, `~/.aws`, or `~/.config`** | | `-v .../proxy.sock:...` | Mounts a Unix socket connected to a proxy running outside the container (see below) | **Unix socket architecture:** With `--network none`, the container has no network interfaces at all. The only way for the agent to reach the outside world is through the mounted Unix socket, which connects to a proxy running on the host. This proxy can enforce domain allowlists, inject credentials, and log all traffic. This is the same architecture used by [sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime). Even if the agent is compromised via prompt injection, it cannot exfiltrate data to arbitrary servers. It can only communicate through the proxy, which controls what domains are reachable. For more details, see the [Claude Code sandboxing blog post](https://www.anthropic.com/engineering/claude-code-sandboxing). **Additional hardening options:** | Option | Purpose | | ---------------- | -------------------------------------------------------------------------------------------------------------------- | | `--userns-remap` | Maps container root to unprivileged host user; requires daemon configuration but limits damage from container escape | | `--ipc private` | Isolates inter-process communication to prevent cross-container attacks | ### gVisor Standard containers share the host kernel: when code inside a container makes a system call, it goes directly to the same kernel that runs the host. This means a kernel vulnerability could allow container escape. gVisor addresses this by intercepting system calls in userspace before they reach the host kernel, implementing its own compatibility layer that handles most syscalls without involving the real kernel. If an agent runs malicious code (perhaps due to prompt injection), that code runs in the container and could attempt kernel exploits. With gVisor, the attack surface is much smaller: the malicious code would need to exploit gVisor's userspace implementation first and would have limited access to the real kernel. To use gVisor with Docker, install the `runsc` runtime and configure the daemon: ```json theme={null} // /etc/docker/daemon.json { "runtimes": { "runsc": { "path": "/usr/local/bin/runsc" } } } ``` Then run containers with: ```bash theme={null} docker run --runtime=runsc agent-image ``` **Performance considerations:** | Workload | Overhead | | --------------------- | -------------------------------------------------- | | CPU-bound computation | \~0% (no syscall interception) | | Simple syscalls | \~2× slower | | File I/O intensive | Up to 10-200× slower for heavy open/close patterns | For multi-tenant environments or when processing untrusted content, the additional isolation is often worth the overhead. ### Virtual machines VMs provide hardware-level isolation through CPU virtualization extensions. Each VM runs its own kernel, creating a strong boundary. A vulnerability in the guest kernel doesn't directly compromise the host. However, VMs aren't automatically "more secure" than alternatives like gVisor. VM security depends heavily on the hypervisor and device emulation code. Firecracker is designed for lightweight microVM isolation. It can boot VMs in under 125ms with less than 5 MiB memory overhead, stripping away unnecessary device emulation to reduce attack surface. With this approach, the agent VM has no external network interface. Instead, it communicates through `vsock` (virtual sockets). All traffic routes through vsock to a proxy on the host, which enforces allowlists and injects credentials before forwarding requests. ### Cloud deployments For cloud deployments, you can combine any of the above isolation technologies with cloud-native network controls: 1. Run agent containers in a private subnet with no internet gateway 2. Configure cloud firewall rules (AWS Security Groups, GCP VPC firewall) to block all egress except to your proxy 3. Run a proxy (such as [Envoy](https://www.envoyproxy.io/) with its `credential_injector` filter) that validates requests, enforces domain allowlists, injects credentials, and forwards to external APIs 4. Assign minimal IAM permissions to the agent's service account, routing sensitive access through the proxy where possible 5. Log all traffic at the proxy for audit purposes ## Credential management Agents often need credentials to call APIs, access repositories, or interact with cloud services. The challenge is providing this access without exposing the credentials themselves. ### The proxy pattern The recommended approach is to run a proxy outside the agent's security boundary that injects credentials into outgoing requests. The agent sends requests without credentials, the proxy adds them, and forwards the request to its destination. This pattern has several benefits: 1. The agent never sees the actual credentials 2. The proxy can enforce an allowlist of permitted endpoints 3. The proxy can log all requests for auditing 4. Credentials are stored in one secure location rather than distributed to each agent ### Configuring Claude Code to use a proxy Claude Code supports two methods for routing sampling requests through a proxy: **Option 1: ANTHROPIC\_BASE\_URL (simple but only for sampling API requests)** ```bash theme={null} export ANTHROPIC_BASE_URL="http://localhost:8080" ``` This tells Claude Code and the Agent SDK to send sampling requests to your proxy instead of the Claude API directly. Your proxy receives plaintext HTTP requests, can inspect and modify them (including injecting credentials), then forwards to the real API. **Option 2: HTTP\_PROXY / HTTPS\_PROXY (system-wide)** ```bash theme={null} export HTTP_PROXY="http://localhost:8080" export HTTPS_PROXY="http://localhost:8080" ``` Claude Code and the Agent SDK respect these standard environment variables, routing all HTTP traffic through the proxy. For HTTPS, the proxy creates an encrypted CONNECT tunnel: it cannot see or modify request contents without TLS interception. ### Implementing a proxy You can build your own proxy or use an existing one: * [Envoy Proxy](https://www.envoyproxy.io/): production-grade proxy with `credential_injector` filter for adding auth headers * [mitmproxy](https://mitmproxy.org/): TLS-terminating proxy for inspecting and modifying HTTPS traffic * [Squid](http://www.squid-cache.org/): caching proxy with access control lists * [LiteLLM](https://github.com/BerriAI/litellm): LLM gateway with credential injection and rate limiting ### Credentials for other services Beyond sampling from the Claude API, agents often need authenticated access to other services, such as git repositories, databases, and internal APIs. There are two main approaches: #### Custom tools Provide access through an MCP server or custom tool that routes requests to a service running outside the agent's security boundary. The agent calls the tool, but the actual authenticated request happens outside. The tool calls to a proxy which injects the credentials. For example, a git MCP server could accept commands from the agent but forward them to a git proxy running on the host, which adds authentication before contacting the remote repository. The agent never sees the credentials. Advantages: * **No TLS interception**: The external service makes authenticated requests directly * **Credentials stay outside**: The agent only sees the tool interface, not the underlying credentials #### Traffic forwarding For Claude API calls, `ANTHROPIC_BASE_URL` lets you route requests to a proxy that can inspect and modify them in plaintext. But for other HTTPS services (GitHub, npm registries, internal APIs), the traffic is often encrypted end-to-end. Even if you route it through a proxy via `HTTP_PROXY`, the proxy only sees an opaque TLS tunnel and can't inject credentials. To modify HTTPS traffic to arbitrary services, without using a custom tool, you need a TLS-terminating proxy that decrypts traffic, inspects or modifies it, then re-encrypts it before forwarding. This requires: 1. Running the proxy outside the agent's container 2. Installing the proxy's CA certificate in the agent's trust store (so the agent trusts the proxy's certificates) 3. Configuring `HTTP_PROXY`/`HTTPS_PROXY` to route traffic through the proxy This approach handles any HTTP-based service without writing custom tools, but adds complexity around certificate management. Note that not all programs respect `HTTP_PROXY`/`HTTPS_PROXY`. Most tools (curl, pip, npm, git) do, but some may bypass these variables and connect directly. For example, Node.js `fetch()` ignores these variables by default; in Node 24+ you can set `NODE_USE_ENV_PROXY=1` to enable support. For comprehensive coverage, you can use [proxychains](https://github.com/haad/proxychains) to intercept network calls, or configure iptables to redirect outbound traffic to a transparent proxy. <Info> A **transparent proxy** intercepts traffic at the network level, so the client doesn't need to be configured to use it. Regular proxies require clients to explicitly connect and speak HTTP CONNECT or SOCKS. Transparent proxies (like Squid or mitmproxy in transparent mode) can handle raw redirected TCP connections. </Info> Both approaches still require the TLS-terminating proxy and trusted CA certificate. They just ensure traffic actually reaches the proxy. ## Filesystem configuration Filesystem controls determine what files the agent can read and write. ### Read-only code mounting When the agent needs to analyze code but not modify it, mount the directory read-only: ```bash theme={null} docker run -v /path/to/code:/workspace:ro agent-image ``` <Warning> Even read-only access to a code directory can expose credentials. Common files to exclude or sanitize before mounting: | File | Risk | | ------------------------------------------------------- | ------------------------------------- | | `.env`, `.env.local` | API keys, database passwords, secrets | | `~/.git-credentials` | Git passwords/tokens in plaintext | | `~/.aws/credentials` | AWS access keys | | `~/.config/gcloud/application_default_credentials.json` | Google Cloud ADC tokens | | `~/.azure/` | Azure CLI credentials | | `~/.docker/config.json` | Docker registry auth tokens | | `~/.kube/config` | Kubernetes cluster credentials | | `.npmrc`, `.pypirc` | Package registry tokens | | `*-service-account.json` | GCP service account keys | | `*.pem`, `*.key` | Private keys | Consider copying only the source files needed, or using `.dockerignore`-style filtering. </Warning> ### Writable locations If the agent needs to write files, you have a few options depending on whether you want changes to persist: For ephemeral workspaces in containers, use `tmpfs` mounts that exist only in memory and are cleared when the container stops: ```bash theme={null} docker run \ --read-only \ --tmpfs /tmp:rw,noexec,nosuid,size=100m \ --tmpfs /workspace:rw,noexec,size=500m \ agent-image ``` If you want to review changes before persisting them, an overlay filesystem lets the agent write without modifying underlying files. Changes are stored in a separate layer you can inspect, apply, or discard. For fully persistent output, mount a dedicated volume but keep it separate from sensitive directories. ## Further reading * [Claude Code security documentation](../22-Safety-Policy/security-claude-code-docs-7538e94c51.md) * [Hosting the Agent SDK](/en/agent-sdk/hosting) * [Handling permissions](/en/agent-sdk/permissions) * [Sandbox runtime](https://github.com/anthropic-experimental/sandbox-runtime) * [The Lethal Trifecta for AI Agents](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/) * [OWASP Top 10 for LLM Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/) * [Docker Security Best Practices](https://docs.docker.com/engine/security/) * [gVisor Documentation](https://gvisor.dev/docs/) * [Firecracker Documentation](https://firecracker-microvm.github.io/) --- ## agent-sdk-sessions-6a9bcc2562.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Work with sessions > How sessions persist agent conversation history, and when to use continue, resume, and fork to return to a prior run. A session is the conversation history the SDK accumulates while your agent works. It contains your prompt, every tool call the agent made, every tool result, and every response. The SDK writes it to disk automatically so you can return to it later. Returning to a session means the agent has full context from before: files it already read, analysis it already performed, decisions it already made. You can ask a follow-up question, recover from an interruption, or branch off to try a different approach. <Note> Sessions persist the **conversation**, not the filesystem. To snapshot and revert file changes the agent made, use [file checkpointing](/en/agent-sdk/file-checkpointing). </Note> This guide covers how to pick the right approach for your app, the SDK interfaces that track sessions automatically, how to capture session IDs and use `resume` and `fork` manually, and what to know about resuming sessions across hosts. ## Choose an approach How much session handling you need depends on your application's shape. Session management comes into play when you send multiple prompts that should share context. Within a single `query()` call, the agent already takes as many turns as it needs, and permission prompts and `AskUserQuestion` are [handled in-loop](/en/agent-sdk/user-input) (they don't end the call). | What you're building | What to use | | :-------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | | One-shot task: single prompt, no follow-up | Nothing extra. One `query()` call handles it. | | Multi-turn chat in one process | [`ClaudeSDKClient` (Python) or `continue: true` (TypeScript)](#automatic-session-management). The SDK tracks the session for you with no ID handling. | | Pick up where you left off after a process restart | `continue_conversation=True` (Python) / `continue: true` (TypeScript). Resumes the most recent session in the directory, no ID needed. | | Resume a specific past session (not the most recent) | Capture the session ID and pass it to `resume`. | | Try an alternative approach without losing the original | Fork the session. | | Stateless task, don't want anything written to disk (TypeScript only) | Set [`persistSession: false`](/en/agent-sdk/typescript#options). The session exists only in memory for the duration of the call. Python always persists to disk. | ### Continue, resume, and fork Continue, resume, and fork are option fields you set on `query()` ([`ClaudeAgentOptions`](/en/agent-sdk/python#claude-agent-options) in Python, [`Options`](/en/agent-sdk/typescript#options) in TypeScript). **Continue** and **resume** both pick up an existing session and add to it. The difference is how they find that session: * **Continue** finds the most recent session in the current directory. You don't track anything. Works well when your app runs one conversation at a time. * **Resume** takes a specific session ID. You track the ID. Required when you have multiple sessions (for example, one per user in a multi-user app) or want to return to one that isn't the most recent. **Fork** is different: it creates a new session that starts with a copy of the original's history. The original stays unchanged. Use fork to try a different direction while keeping the option to go back. ## Automatic session management Both SDKs offer an interface that tracks session state for you across calls, so you don't pass IDs around manually. Use these for multi-turn conversations within a single process. ### Python: `ClaudeSDKClient` [`ClaudeSDKClient`](/en/agent-sdk/python#claude-sdk-client) handles session IDs internally. Each call to `client.query()` automatically continues the same session. Call [`client.receive_response()`](/en/agent-sdk/python#claude-sdk-client) to iterate over the messages for the current query. The client must be used as an async context manager. This example runs two queries against the same `client`. The first asks the agent to analyze a module; the second asks it to refactor that module. Because both calls go through the same client instance, the second query has full context from the first without any explicit `resume` or session ID: ```python Python theme={null} import asyncio from claude_agent_sdk import ( ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, ResultMessage, TextBlock, ) def print_response(message): """Print only the human-readable parts of a message.""" if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(block.text) elif isinstance(message, ResultMessage): cost = ( f"${message.total_cost_usd:.4f}" if message.total_cost_usd is not None else "N/A" ) print(f"[done: {message.subtype}, cost: {cost}]") async def main(): options = ClaudeAgentOptions( allowed_tools=["Read", "Edit", "Glob", "Grep"], ) async with ClaudeSDKClient(options=options) as client: # First query: client captures the session ID internally await client.query("Analyze the auth module") async for message in client.receive_response(): print_response(message) # Second query: automatically continues the same session await client.query("Now refactor it to use JWT") async for message in client.receive_response(): print_response(message) asyncio.run(main()) ``` See the [Python SDK reference](/en/agent-sdk/python#choosing-between-query-and-claude-sdk-client) for details on when to use `ClaudeSDKClient` vs the standalone `query()` function. ### TypeScript: `continue: true` The stable TypeScript SDK (the `query()` function used throughout these docs, sometimes called V1) doesn't have a session-holding client object like Python's `ClaudeSDKClient`. Instead, pass `continue: true` on each subsequent `query()` call and the SDK picks up the most recent session in the current directory. No ID tracking required. This example makes two separate `query()` calls. The first creates a fresh session; the second sets `continue: true`, which tells the SDK to find and resume the most recent session on disk. The agent has full context from the first call: ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; // First query: creates a new session for await (const message of query({ prompt: "Analyze the auth module", options: { allowedTools: ["Read", "Glob", "Grep"] } })) { if (message.type === "result" && message.subtype === "success") { console.log(message.result); } } // Second query: continue: true resumes the most recent session for await (const message of query({ prompt: "Now refactor it to use JWT", options: { continue: true, allowedTools: ["Read", "Edit", "Write", "Glob", "Grep"] } })) { if (message.type === "result" && message.subtype === "success") { console.log(message.result); } } ``` <Note> There's also a [V2 preview](/en/agent-sdk/typescript-v2-preview) of the TypeScript SDK that provides `createSession()` with a `send` / `stream` pattern, closer to Python's `ClaudeSDKClient` in feel. V2 is unstable and its APIs may change; the rest of this documentation uses the stable V1 `query()` function. </Note> ## Use session options with `query()` ### Capture the session ID Resume and fork require a session ID. Read it from the `session_id` field on the result message ([`ResultMessage`](/en/agent-sdk/python#result-message) in Python, [`SDKResultMessage`](/en/agent-sdk/typescript#sdk-result-message) in TypeScript), which is present on every result regardless of success or error. In TypeScript the ID is also available earlier as a direct field on the init `SystemMessage`; in Python it's nested inside `SystemMessage.data`. <CodeGroup> ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage async def main(): session_id = None async for message in query( prompt="Analyze the auth module and suggest improvements", options=ClaudeAgentOptions( allowed_tools=["Read", "Glob", "Grep"], ), ): if isinstance(message, ResultMessage): session_id = message.session_id if message.subtype == "success": print(message.result) print(f"Session ID: {session_id}") return session_id session_id = asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; let sessionId: string | undefined; for await (const message of query({ prompt: "Analyze the auth module and suggest improvements", options: { allowedTools: ["Read", "Glob", "Grep"] } })) { if (message.type === "result") { sessionId = message.session_id; if (message.subtype === "success") { console.log(message.result); } } } console.log(`Session ID: ${sessionId}`); ``` </CodeGroup> ### Resume by ID Pass a session ID to `resume` to return to that specific session. The agent picks up with full context from wherever the session left off. Common reasons to resume: * **Follow up on a completed task.** The agent already analyzed something; now you want it to act on that analysis without re-reading files. * **Recover from a limit.** The first run ended with `error_max_turns` or `error_max_budget_usd` (see [Handle the result](/en/agent-sdk/agent-loop#handle-the-result)); resume with a higher limit. * **Restart your process.** You captured the ID before shutdown and want to restore the conversation. This example resumes the session from [Capture the session ID](#capture-the-session-id) with a follow-up prompt. Because you're resuming, the agent already has the prior analysis in context: <CodeGroup> ```python Python theme={null} # Earlier session analyzed the code; now build on that analysis async for message in query( prompt="Now implement the refactoring you suggested", options=ClaudeAgentOptions( resume=session_id, allowed_tools=["Read", "Edit", "Write", "Glob", "Grep"], ), ): if isinstance(message, ResultMessage) and message.subtype == "success": print(message.result) ``` ```typescript TypeScript theme={null} // Earlier session analyzed the code; now build on that analysis for await (const message of query({ prompt: "Now implement the refactoring you suggested", options: { resume: sessionId, allowedTools: ["Read", "Edit", "Write", "Glob", "Grep"] } })) { if (message.type === "result" && message.subtype === "success") { console.log(message.result); } } ``` </CodeGroup> <Tip> If a `resume` call returns a fresh session instead of the expected history, the most common cause is a mismatched `cwd`. Sessions are stored under `~/.claude/projects/<encoded-cwd>/*.jsonl`, where `<encoded-cwd>` is the absolute working directory with every non-alphanumeric character replaced by `-` (so `/Users/me/proj` becomes `-Users-me-proj`). If your resume call runs from a different directory, the SDK looks in the wrong place. The session file also needs to exist on the current machine. </Tip> To resume sessions across machines or in serverless environments, mirror transcripts to shared storage with a [`SessionStore` adapter](/en/agent-sdk/session-storage). ### Fork to explore alternatives Forking creates a new session that starts with a copy of the original's history but diverges from that point. The fork gets its own session ID; the original's ID and history stay unchanged. You end up with two independent sessions you can resume separately. <Note> Forking branches the conversation history, not the filesystem. If a forked agent edits files, those changes are real and visible to any session working in the same directory. To branch and revert file changes, use [file checkpointing](/en/agent-sdk/file-checkpointing). </Note> This example builds on [Capture the session ID](#capture-the-session-id): you've already analyzed an auth module in `session_id` and want to explore OAuth2 without losing the JWT-focused thread. The first block forks the session and captures the fork's ID (`forked_id`); the second block resumes the original `session_id` to continue down the JWT path. You now have two session IDs pointing at two separate histories: <CodeGroup> ```python Python theme={null} # Fork: branch from session_id into a new session forked_id = None async for message in query( prompt="Instead of JWT, implement OAuth2 for the auth module", options=ClaudeAgentOptions( resume=session_id, fork_session=True, ), ): if isinstance(message, ResultMessage): forked_id = message.session_id # The fork's ID, distinct from session_id if message.subtype == "success": print(message.result) print(f"Forked session: {forked_id}") # Original session is untouched; resuming it continues the JWT thread async for message in query( prompt="Continue with the JWT approach", options=ClaudeAgentOptions(resume=session_id), ): if isinstance(message, ResultMessage) and message.subtype == "success": print(message.result) ``` ```typescript TypeScript theme={null} // Fork: branch from sessionId into a new session let forkedId: string | undefined; for await (const message of query({ prompt: "Instead of JWT, implement OAuth2 for the auth module", options: { resume: sessionId, forkSession: true } })) { if (message.type === "system" && message.subtype === "init") { forkedId = message.session_id; // The fork's ID, distinct from sessionId } if (message.type === "result" && message.subtype === "success") { console.log(message.result); } } console.log(`Forked session: ${forkedId}`); // Original session is untouched; resuming it continues the JWT thread for await (const message of query({ prompt: "Continue with the JWT approach", options: { resume: sessionId } })) { if (message.type === "result" && message.subtype === "success") { console.log(message.result); } } ``` </CodeGroup> ## Resume across hosts Session files are local to the machine that created them. To resume a session on a different host (CI workers, ephemeral containers, serverless), you have two options: * **Move the session file.** Persist `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl` from the first run and restore it to the same path on the new host before calling `resume`. The `cwd` must match. * **Don't rely on session resume.** Capture the results you need (analysis output, decisions, file diffs) as application state and pass them into a fresh session's prompt. This is often more robust than shipping transcript files around. Both SDKs expose functions for enumerating sessions on disk and reading their messages: [`listSessions()`](/en/agent-sdk/typescript#list-sessions) and [`getSessionMessages()`](/en/agent-sdk/typescript#get-session-messages) in TypeScript, [`list_sessions()`](/en/agent-sdk/python#list-sessions) and [`get_session_messages()`](/en/agent-sdk/python#get-session-messages) in Python. Use them to build custom session pickers, cleanup logic, or transcript viewers. Both SDKs also expose functions for looking up and mutating individual sessions: [`get_session_info()`](/en/agent-sdk/python#get-session-info), [`rename_session()`](/en/agent-sdk/python#rename-session), and [`tag_session()`](/en/agent-sdk/python#tag-session) in Python, and [`getSessionInfo()`](/en/agent-sdk/typescript#get-session-info), [`renameSession()`](/en/agent-sdk/typescript#rename-session), and [`tagSession()`](/en/agent-sdk/typescript#tag-session) in TypeScript. Use them to organize sessions by tag or give them human-readable titles. ## Related resources * [How the agent loop works](/en/agent-sdk/agent-loop): Understand turns, messages, and context accumulation within a session * [File checkpointing](/en/agent-sdk/file-checkpointing): Track and revert file changes across sessions * [Python `ClaudeAgentOptions`](/en/agent-sdk/python#claude-agent-options): Full session option reference for Python * [TypeScript `Options`](/en/agent-sdk/typescript#options): Full session option reference for TypeScript --- ## agent-sdk-slash-commands-eb3bd10cac.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Slash Commands in the SDK > Learn how to use slash commands to control Claude Code sessions through the SDK Slash commands provide a way to control Claude Code sessions with special commands that start with `/`. These commands can be sent through the SDK to perform actions like compacting context, listing context usage, or invoking custom commands. Only commands that work without an interactive terminal are dispatchable through the SDK; the `system/init` message lists the ones available in your session. ## Discovering Available Slash Commands The Claude Agent SDK provides information about available slash commands in the system initialization message. Access this information when your session starts: <CodeGroup> ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Hello Claude", options: { maxTurns: 1 } })) { if (message.type === "system" && message.subtype === "init") { console.log("Available slash commands:", message.slash_commands); // Example output: ["/compact", "/context", "/usage"] } } ``` ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage async def main(): async for message in query(prompt="Hello Claude", options=ClaudeAgentOptions(max_turns=1)): if isinstance(message, SystemMessage) and message.subtype == "init": print("Available slash commands:", message.data["slash_commands"]) # Example output: ["/compact", "/context", "/usage"] asyncio.run(main()) ``` </CodeGroup> ## Sending Slash Commands Send slash commands by including them in your prompt string, just like regular text: <CodeGroup> ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; // Send a slash command for await (const message of query({ prompt: "/compact", options: { maxTurns: 1 } })) { if (message.type === "result") { console.log("Command executed:", message.result); } } ``` ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage async def main(): # Send a slash command async for message in query(prompt="/compact", options=ClaudeAgentOptions(max_turns=1)): if isinstance(message, ResultMessage): print("Command executed:", message.result) asyncio.run(main()) ``` </CodeGroup> ## Common Slash Commands ### `/compact` - Compact Conversation History The `/compact` command reduces the size of your conversation history by summarizing older messages while preserving important context: <CodeGroup> ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "/compact", options: { maxTurns: 1 } })) { if (message.type === "system" && message.subtype === "compact_boundary") { console.log("Compaction completed"); console.log("Pre-compaction tokens:", message.compact_metadata.pre_tokens); console.log("Trigger:", message.compact_metadata.trigger); } } ``` ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage async def main(): async for message in query(prompt="/compact", options=ClaudeAgentOptions(max_turns=1)): if isinstance(message, SystemMessage) and message.subtype == "compact_boundary": print("Compaction completed") print("Pre-compaction tokens:", message.data["compact_metadata"]["pre_tokens"]) print("Trigger:", message.data["compact_metadata"]["trigger"]) asyncio.run(main()) ``` </CodeGroup> ### Clearing the conversation The interactive `/clear` command is not available in the SDK. Each `query()` call already starts a fresh conversation, so to clear context, end the current `query()` and start a new one. The previous conversation stays on disk and can be returned to by passing its session ID to the [`resume` option](/en/agent-sdk/sessions#resume-by-id). ## Creating Custom Slash Commands In addition to using built-in slash commands, you can create your own custom commands that are available through the SDK. Custom commands are defined as markdown files in specific directories, similar to how subagents are configured. <Note> The `.claude/commands/` directory is the legacy format. The recommended format is `.claude/skills/<name>/SKILL.md`, which supports the same slash-command invocation (`/name`) plus autonomous invocation by Claude. See [Skills](/en/agent-sdk/skills) for the current format. The CLI continues to support both formats, and the examples below remain accurate for `.claude/commands/`. </Note> ### File Locations Custom slash commands are stored in designated directories based on their scope: * **Project commands**: `.claude/commands/` - Available only in the current project (legacy; prefer `.claude/skills/`) * **Personal commands**: `~/.claude/commands/` - Available across all your projects (legacy; prefer `~/.claude/skills/`) ### File Format Each custom command is a markdown file where: * The filename (without `.md` extension) becomes the command name * The file content defines what the command does * Optional YAML frontmatter provides configuration #### Basic Example Create `.claude/commands/refactor.md`: ```markdown theme={null} Refactor the selected code to improve readability and maintainability. Focus on clean code principles and best practices. ``` This creates the `/refactor` command that you can use through the SDK. #### With Frontmatter Create `.claude/commands/security-check.md`: ```markdown theme={null} --- allowed-tools: Read, Grep, Glob description: Run security vulnerability scan model: claude-opus-4-7 --- Analyze the codebase for security vulnerabilities including: - SQL injection risks - XSS vulnerabilities - Exposed credentials - Insecure configurations ``` ### Using Custom Commands in the SDK Once defined in the filesystem, custom commands are automatically available through the SDK: <CodeGroup> ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; // Use a custom command for await (const message of query({ prompt: "/refactor src/auth/login.ts", options: { maxTurns: 3 } })) { if (message.type === "assistant") { console.log("Refactoring suggestions:", message.message); } } // Custom commands appear in the slash_commands list for await (const message of query({ prompt: "Hello", options: { maxTurns: 1 } })) { if (message.type === "system" && message.subtype === "init") { // Will include both built-in and custom commands console.log("Available commands:", message.slash_commands); // Example: ["/compact", "/context", "/usage", "/refactor", "/security-check"] } } ``` ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, SystemMessage async def main(): # Use a custom command async for message in query( prompt="/refactor src/auth/login.py", options=ClaudeAgentOptions(max_turns=3) ): if isinstance(message, AssistantMessage): for block in message.content: if hasattr(block, "text"): print("Refactoring suggestions:", block.text) # Custom commands appear in the slash_commands list async for message in query(prompt="Hello", options=ClaudeAgentOptions(max_turns=1)): if isinstance(message, SystemMessage) and message.subtype == "init": # Will include both built-in and custom commands print("Available commands:", message.data["slash_commands"]) # Example: ["/compact", "/context", "/usage", "/refactor", "/security-check"] asyncio.run(main()) ``` </CodeGroup> ### Advanced Features #### Arguments and Placeholders Custom commands support dynamic arguments using placeholders: Create `.claude/commands/fix-issue.md`: ```markdown theme={null} --- argument-hint: [issue-number] [priority] description: Fix a GitHub issue --- Fix issue #$1 with priority $2. Check the issue description and implement the necessary changes. ``` Use in SDK: <CodeGroup> ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; // Pass arguments to custom command for await (const message of query({ prompt: "/fix-issue 123 high", options: { maxTurns: 5 } })) { // Command will process with $1="123" and $2="high" if (message.type === "result") { console.log("Issue fixed:", message.result); } } ``` ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage async def main(): # Pass arguments to custom command async for message in query(prompt="/fix-issue 123 high", options=ClaudeAgentOptions(max_turns=5)): # Command will process with $1="123" and $2="high" if isinstance(message, ResultMessage): print("Issue fixed:", message.result) asyncio.run(main()) ``` </CodeGroup> #### Bash Command Execution Custom commands can execute bash commands and include their output: Create `.claude/commands/git-commit.md`: ```markdown theme={null} --- allowed-tools: Bash(git add *), Bash(git status *), Bash(git commit *) description: Create a git commit --- ## Context - Current status: !`git status` - Current diff: !`git diff HEAD` ## Task Create a git commit with appropriate message based on the changes. ``` #### File References Include file contents using the `@` prefix: Create `.claude/commands/review-config.md`: ```markdown theme={null} --- description: Review configuration files --- Review the following configuration files for issues: - Package config: @package.json - TypeScript config: @tsconfig.json - Environment config: @.env Check for security issues, outdated dependencies, and misconfigurations. ``` ### Organization with Namespacing Organize commands in subdirectories for better structure: ```bash theme={null} .claude/commands/ ├── frontend/ │ ├── component.md # Creates /component (project:frontend) │ └── style-check.md # Creates /style-check (project:frontend) ├── backend/ │ ├── api-test.md # Creates /api-test (project:backend) │ └── db-migrate.md # Creates /db-migrate (project:backend) └── review.md # Creates /review (project) ``` The subdirectory appears in the command description but doesn't affect the command name itself. ### Practical Examples #### Code Review Command Create `.claude/commands/code-review.md`: ```markdown theme={null} --- allowed-tools: Read, Grep, Glob, Bash(git diff *) description: Comprehensive code review --- ## Changed Files !`git diff --name-only HEAD~1` ## Detailed Changes !`git diff HEAD~1` ## Review Checklist Review the above changes for: 1. Code quality and readability 2. Security vulnerabilities 3. Performance implications 4. Test coverage 5. Documentation completeness Provide specific, actionable feedback organized by priority. ``` #### Test Runner Command Create `.claude/commands/test.md`: ```markdown theme={null} --- allowed-tools: Bash, Read, Edit argument-hint: [test-pattern] description: Run tests with optional pattern --- Run tests matching pattern: $ARGUMENTS 1. Detect the test framework (Jest, pytest, etc.) 2. Run tests with the provided pattern 3. If tests fail, analyze and fix them 4. Re-run to verify fixes ``` Use these commands through the SDK: <CodeGroup> ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; // Run code review for await (const message of query({ prompt: "/code-review", options: { maxTurns: 3 } })) { // Process review feedback } // Run specific tests for await (const message of query({ prompt: "/test auth", options: { maxTurns: 5 } })) { // Handle test results } ``` ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): # Run code review async for message in query(prompt="/code-review", options=ClaudeAgentOptions(max_turns=3)): # Process review feedback pass # Run specific tests async for message in query(prompt="/test auth", options=ClaudeAgentOptions(max_turns=5)): # Handle test results pass asyncio.run(main()) ``` </CodeGroup> ## See Also * [Slash Commands](../08-Plugins-Skills/extend-claude-with-skills-claude-code-docs.md) - Complete slash command documentation * [Subagents in the SDK](/en/agent-sdk/subagents) - Similar filesystem-based configuration for subagents * [TypeScript SDK reference](/en/agent-sdk/typescript) - Complete API documentation * [SDK overview](/en/agent-sdk/overview) - General SDK concepts * [CLI reference](../02-Claude-Code-CLI/cli-reference-7bb98e3312.md) - Command-line interface --- ## agent-sdk-streaming-output-64829275d0.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Stream responses in real-time > Get real-time responses from the Agent SDK as text and tool calls stream in By default, the Agent SDK yields complete `AssistantMessage` objects after Claude finishes generating each response. To receive incremental updates as text and tool calls are generated, enable partial message streaming by setting `include_partial_messages` (Python) or `includePartialMessages` (TypeScript) to `true` in your options. <Tip> This page covers output streaming (receiving tokens in real-time). For input modes (how you send messages), see [Send messages to agents](/en/agent-sdk/streaming-vs-single-mode). You can also [stream responses using the Agent SDK via the CLI](../02-Claude-Code-CLI/headless-b99e3140ec.md). </Tip> ## Enable streaming output To enable streaming, set `include_partial_messages` (Python) or `includePartialMessages` (TypeScript) to `true` in your options. This causes the SDK to yield `StreamEvent` messages containing raw API events as they arrive, in addition to the usual `AssistantMessage` and `ResultMessage`. Your code then needs to: 1. Check each message's type to distinguish `StreamEvent` from other message types 2. For `StreamEvent`, extract the `event` field and check its `type` 3. Look for `content_block_delta` events where `delta.type` is `text_delta`, which contain the actual text chunks The example below enables streaming and prints text chunks as they arrive. Notice the nested type checks: first for `StreamEvent`, then for `content_block_delta`, then for `text_delta`: <CodeGroup> ```python Python theme={null} from claude_agent_sdk import query, ClaudeAgentOptions from claude_agent_sdk.types import StreamEvent import asyncio async def stream_response(): options = ClaudeAgentOptions( include_partial_messages=True, allowed_tools=["Bash", "Read"], ) async for message in query(prompt="List the files in my project", options=options): if isinstance(message, StreamEvent): event = message.event if event.get("type") == "content_block_delta": delta = event.get("delta", {}) if delta.get("type") == "text_delta": print(delta.get("text", ""), end="", flush=True) asyncio.run(stream_response()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "List the files in my project", options: { includePartialMessages: true, allowedTools: ["Bash", "Read"] } })) { if (message.type === "stream_event") { const event = message.event; if (event.type === "content_block_delta") { if (event.delta.type === "text_delta") { process.stdout.write(event.delta.text); } } } } ``` </CodeGroup> ## StreamEvent reference When partial messages are enabled, you receive raw Claude API streaming events wrapped in an object. The type has different names in each SDK: * **Python**: `StreamEvent` (import from `claude_agent_sdk.types`) * **TypeScript**: `SDKPartialAssistantMessage` with `type: 'stream_event'` Both contain raw Claude API events, not accumulated text. You need to extract and accumulate text deltas yourself. Here's the structure of each type: <CodeGroup> ```python Python theme={null} @dataclass class StreamEvent: uuid: str # Unique identifier for this event session_id: str # Session identifier event: dict[str, Any] # The raw Claude API stream event parent_tool_use_id: str | None # Parent tool ID if from a subagent ``` ```typescript TypeScript theme={null} type SDKPartialAssistantMessage = { type: "stream_event"; event: RawMessageStreamEvent; // From Anthropic SDK parent_tool_use_id: string | null; uuid: UUID; session_id: string; }; ``` </CodeGroup> The `event` field contains the raw streaming event from the [Claude API](../04-API-Reference/Guides/build-with-claude-streaming-74f4dddaf7.md#event-types). Common event types include: | Event Type | Description | | :-------------------- | :---------------------------------------------- | | `message_start` | Start of a new message | | `content_block_start` | Start of a new content block (text or tool use) | | `content_block_delta` | Incremental update to content | | `content_block_stop` | End of a content block | | `message_delta` | Message-level updates (stop reason, usage) | | `message_stop` | End of the message | ## Message flow With partial messages enabled, you receive messages in this order: ```text theme={null} StreamEvent (message_start) StreamEvent (content_block_start) - text block StreamEvent (content_block_delta) - text chunks... StreamEvent (content_block_stop) StreamEvent (content_block_start) - tool_use block StreamEvent (content_block_delta) - tool input chunks... StreamEvent (content_block_stop) StreamEvent (message_delta) StreamEvent (message_stop) AssistantMessage - complete message with all content ... tool executes ... ... more streaming events for next turn ... ResultMessage - final result ``` Without partial messages enabled (`include_partial_messages` in Python, `includePartialMessages` in TypeScript), you receive all message types except `StreamEvent`. Common types include `SystemMessage` (session initialization), `AssistantMessage` (complete responses), `ResultMessage` (final result), and a compact boundary message indicating when conversation history was compacted (`SDKCompactBoundaryMessage` in TypeScript; `SystemMessage` with subtype `"compact_boundary"` in Python). ## Stream text responses To display text as it's generated, look for `content_block_delta` events where `delta.type` is `text_delta`. These contain the incremental text chunks. The example below prints each chunk as it arrives: <CodeGroup> ```python Python theme={null} from claude_agent_sdk import query, ClaudeAgentOptions from claude_agent_sdk.types import StreamEvent import asyncio async def stream_text(): options = ClaudeAgentOptions(include_partial_messages=True) async for message in query(prompt="Explain how databases work", options=options): if isinstance(message, StreamEvent): event = message.event if event.get("type") == "content_block_delta": delta = event.get("delta", {}) if delta.get("type") == "text_delta": # Print each text chunk as it arrives print(delta.get("text", ""), end="", flush=True) print() # Final newline asyncio.run(stream_text()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Explain how databases work", options: { includePartialMessages: true } })) { if (message.type === "stream_event") { const event = message.event; if (event.type === "content_block_delta" && event.delta.type === "text_delta") { process.stdout.write(event.delta.text); } } } console.log(); // Final newline ``` </CodeGroup> ## Stream tool calls Tool calls also stream incrementally. You can track when tools start, receive their input as it's generated, and see when they complete. The example below tracks the current tool being called and accumulates the JSON input as it streams in. It uses three event types: * `content_block_start`: tool begins * `content_block_delta` with `input_json_delta`: input chunks arrive * `content_block_stop`: tool call complete <CodeGroup> ```python Python theme={null} from claude_agent_sdk import query, ClaudeAgentOptions from claude_agent_sdk.types import StreamEvent import asyncio async def stream_tool_calls(): options = ClaudeAgentOptions( include_partial_messages=True, allowed_tools=["Read", "Bash"], ) # Track the current tool and accumulate its input JSON current_tool = None tool_input = "" async for message in query(prompt="Read the README.md file", options=options): if isinstance(message, StreamEvent): event = message.event event_type = event.get("type") if event_type == "content_block_start": # New tool call is starting content_block = event.get("content_block", {}) if content_block.get("type") == "tool_use": current_tool = content_block.get("name") tool_input = "" print(f"Starting tool: {current_tool}") elif event_type == "content_block_delta": delta = event.get("delta", {}) if delta.get("type") == "input_json_delta": # Accumulate JSON input as it streams in chunk = delta.get("partial_json", "") tool_input += chunk print(f" Input chunk: {chunk}") elif event_type == "content_block_stop": # Tool call complete - show final input if current_tool: print(f"Tool {current_tool} called with: {tool_input}") current_tool = None asyncio.run(stream_tool_calls()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; // Track the current tool and accumulate its input JSON let currentTool: string | null = null; let toolInput = ""; for await (const message of query({ prompt: "Read the README.md file", options: { includePartialMessages: true, allowedTools: ["Read", "Bash"] } })) { if (message.type === "stream_event") { const event = message.event; if (event.type === "content_block_start") { // New tool call is starting if (event.content_block.type === "tool_use") { currentTool = event.content_block.name; toolInput = ""; console.log(`Starting tool: ${currentTool}`); } } else if (event.type === "content_block_delta") { if (event.delta.type === "input_json_delta") { // Accumulate JSON input as it streams in const chunk = event.delta.partial_json; toolInput += chunk; console.log(` Input chunk: ${chunk}`); } } else if (event.type === "content_block_stop") { // Tool call complete - show final input if (currentTool) { console.log(`Tool ${currentTool} called with: ${toolInput}`); currentTool = null; } } } } ``` </CodeGroup> ## Build a streaming UI This example combines text and tool streaming into a cohesive UI. It tracks whether the agent is currently executing a tool (using an `in_tool` flag) to show status indicators like `[Using Read...]` while tools run. Text streams normally when not in a tool, and tool completion triggers a "done" message. This pattern is useful for chat interfaces that need to show progress during multi-step agent tasks. <CodeGroup> ```python Python theme={null} from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage from claude_agent_sdk.types import StreamEvent import asyncio import sys async def streaming_ui(): options = ClaudeAgentOptions( include_partial_messages=True, allowed_tools=["Read", "Bash", "Grep"], ) # Track whether we're currently in a tool call in_tool = False async for message in query( prompt="Find all TODO comments in the codebase", options=options ): if isinstance(message, StreamEvent): event = message.event event_type = event.get("type") if event_type == "content_block_start": content_block = event.get("content_block", {}) if content_block.get("type") == "tool_use": # Tool call is starting - show status indicator tool_name = content_block.get("name") print(f"\n[Using {tool_name}...]", end="", flush=True) in_tool = True elif event_type == "content_block_delta": delta = event.get("delta", {}) # Only stream text when not executing a tool if delta.get("type") == "text_delta" and not in_tool: sys.stdout.write(delta.get("text", "")) sys.stdout.flush() elif event_type == "content_block_stop": if in_tool: # Tool call finished print(" done", flush=True) in_tool = False elif isinstance(message, ResultMessage): # Agent finished all work print(f"\n\n--- Complete ---") asyncio.run(streaming_ui()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; // Track whether we're currently in a tool call let inTool = false; for await (const message of query({ prompt: "Find all TODO comments in the codebase", options: { includePartialMessages: true, allowedTools: ["Read", "Bash", "Grep"] } })) { if (message.type === "stream_event") { const event = message.event; if (event.type === "content_block_start") { if (event.content_block.type === "tool_use") { // Tool call is starting - show status indicator process.stdout.write(`\n[Using ${event.content_block.name}...]`); inTool = true; } } else if (event.type === "content_block_delta") { // Only stream text when not executing a tool if (event.delta.type === "text_delta" && !inTool) { process.stdout.write(event.delta.text); } } else if (event.type === "content_block_stop") { if (inTool) { // Tool call finished console.log(" done"); inTool = false; } } } else if (message.type === "result") { // Agent finished all work console.log("\n\n--- Complete ---"); } } ``` </CodeGroup> ## Known limitations Some SDK features are incompatible with streaming: * **Extended thinking**: when you explicitly set `max_thinking_tokens` (Python) or `maxThinkingTokens` (TypeScript), `StreamEvent` messages are not emitted. You'll only receive complete messages after each turn. Note that thinking is disabled by default in the SDK, so streaming works unless you enable it. * **Structured output**: the JSON result appears only in the final `ResultMessage.structured_output`, not as streaming deltas. See [structured outputs](/en/agent-sdk/structured-outputs) for details. ## Next steps Now that you can stream text and tool calls in real-time, explore these related topics: * [Interactive vs one-shot queries](/en/agent-sdk/streaming-vs-single-mode): choose between input modes for your use case * [Structured outputs](/en/agent-sdk/structured-outputs): get typed JSON responses from the agent * [Permissions](/en/agent-sdk/permissions): control which tools the agent can use --- ## agent-sdk-streaming-vs-single-mode-4ab9989824.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Streaming Input > Understanding the two input modes for Claude Agent SDK and when to use each ## Overview The Claude Agent SDK supports two distinct input modes for interacting with agents: * **Streaming Input Mode** (Default & Recommended) - A persistent, interactive session * **Single Message Input** - One-shot queries that use session state and resuming This guide explains the differences, benefits, and use cases for each mode to help you choose the right approach for your application. ## Streaming Input Mode (Recommended) Streaming input mode is the **preferred** way to use the Claude Agent SDK. It provides full access to the agent's capabilities and enables rich, interactive experiences. It allows the agent to operate as a long lived process that takes in user input, handles interruptions, surfaces permission requests, and handles session management. ### How It Works ```mermaid theme={null} sequenceDiagram participant App as Your Application participant Agent as Claude Agent participant Tools as Tools/Hooks participant FS as Environment/<br/>File System App->>Agent: Initialize with AsyncGenerator activate Agent App->>Agent: Yield Message 1 Agent->>Tools: Execute tools Tools->>FS: Read files FS-->>Tools: File contents Tools->>FS: Write/Edit files FS-->>Tools: Success/Error Agent-->>App: Stream partial response Agent-->>App: Stream more content... Agent->>App: Complete Message 1 App->>Agent: Yield Message 2 + Image Agent->>Tools: Process image & execute Tools->>FS: Access filesystem FS-->>Tools: Operation results Agent-->>App: Stream response 2 App->>Agent: Queue Message 3 App->>Agent: Interrupt/Cancel Agent->>App: Handle interruption Note over App,Agent: Session stays alive Note over Tools,FS: Persistent file system<br/>state maintained deactivate Agent ``` ### Benefits <CardGroup cols={2}> <Card title="Image Uploads" icon="image"> Attach images directly to messages for visual analysis and understanding </Card> <Card title="Queued Messages" icon="stack"> Send multiple messages that process sequentially, with ability to interrupt </Card> <Card title="Tool Integration" icon="wrench"> Full access to all tools and custom MCP servers during the session </Card> <Card title="Hooks Support" icon="link"> Use lifecycle hooks to customize behavior at various points </Card> <Card title="Real-time Feedback" icon="lightning"> See responses as they're generated, not just final results </Card> <Card title="Context Persistence" icon="database"> Maintain conversation context across multiple turns naturally </Card> </CardGroup> ### Implementation Example <CodeGroup> ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; import { readFile } from "fs/promises"; async function* generateMessages() { // First message yield { type: "user" as const, message: { role: "user" as const, content: "Analyze this codebase for security issues" } }; // Wait for conditions or user input await new Promise((resolve) => setTimeout(resolve, 2000)); // Follow-up with image yield { type: "user" as const, message: { role: "user" as const, content: [ { type: "text", text: "Review this architecture diagram" }, { type: "image", source: { type: "base64", media_type: "image/png", data: await readFile("diagram.png", "base64") } } ] } }; } // Process streaming responses for await (const message of query({ prompt: generateMessages(), options: { maxTurns: 10, allowedTools: ["Read", "Grep"] } })) { if (message.type === "result") { console.log(message.result); } } ``` ```python Python theme={null} from claude_agent_sdk import ( ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock, ) import asyncio import base64 async def streaming_analysis(): async def message_generator(): # First message yield { "type": "user", "message": { "role": "user", "content": "Analyze this codebase for security issues", }, } # Wait for conditions await asyncio.sleep(2) # Follow-up with image with open("diagram.png", "rb") as f: image_data = base64.b64encode(f.read()).decode() yield { "type": "user", "message": { "role": "user", "content": [ {"type": "text", "text": "Review this architecture diagram"}, { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": image_data, }, }, ], }, } # Use ClaudeSDKClient for streaming input options = ClaudeAgentOptions(max_turns=10, allowed_tools=["Read", "Grep"]) async with ClaudeSDKClient(options) as client: # Send streaming input await client.query(message_generator()) # Process responses async for message in client.receive_response(): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(block.text) asyncio.run(streaming_analysis()) ``` </CodeGroup> ## Single Message Input Single message input is simpler but more limited. ### When to Use Single Message Input Use single message input when: * You need a one-shot response * You do not need image attachments, hooks, etc. * You need to operate in a stateless environment, such as a lambda function ### Limitations <Warning> Single message input mode does **not** support: * Direct image attachments in messages * Dynamic message queueing * Real-time interruption * Hook integration * Natural multi-turn conversations </Warning> ### Implementation Example <CodeGroup> ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; // Simple one-shot query for await (const message of query({ prompt: "Explain the authentication flow", options: { maxTurns: 1, allowedTools: ["Read", "Grep"] } })) { if (message.type === "result") { console.log(message.result); } } // Continue conversation with session management for await (const message of query({ prompt: "Now explain the authorization process", options: { continue: true, maxTurns: 1 } })) { if (message.type === "result") { console.log(message.result); } } ``` ```python Python theme={null} from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage import asyncio async def single_message_example(): # Simple one-shot query using query() function async for message in query( prompt="Explain the authentication flow", options=ClaudeAgentOptions(max_turns=1, allowed_tools=["Read", "Grep"]), ): if isinstance(message, ResultMessage): print(message.result) # Continue conversation with session management async for message in query( prompt="Now explain the authorization process", options=ClaudeAgentOptions(continue_conversation=True, max_turns=1), ): if isinstance(message, ResultMessage): print(message.result) asyncio.run(single_message_example()) ``` </CodeGroup> --- ## agent-sdk-structured-outputs-ecdbc89e8c.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get structured output from agents > Return validated JSON from agent workflows using JSON Schema, Zod, or Pydantic. Get type-safe, structured data after multi-turn tool use. Structured outputs let you define the exact shape of data you want back from an agent. The agent can use any tools it needs to complete the task, and you still get validated JSON matching your schema at the end. Define a [JSON Schema](https://json-schema.org/understanding-json-schema/about) for the structure you need, and the SDK validates the output against it, re-prompting on mismatch. If validation does not succeed within the retry limit, the result is an error instead of structured data; see [Error handling](#error-handling). For full type safety, use [Zod](#type-safe-schemas-with-zod-and-pydantic) (TypeScript) or [Pydantic](#type-safe-schemas-with-zod-and-pydantic) (Python) to define your schema and get strongly-typed objects back. ## Why structured outputs? Agents return free-form text by default, which works for chat but not when you need to use the output programmatically. Structured outputs give you typed data you can pass directly to your application logic, database, or UI components. Consider a recipe app where an agent searches the web and brings back recipes. Without structured outputs, you get free-form text that you'd need to parse yourself. With structured outputs, you define the shape you want and get typed data you can use directly in your app. <AccordionGroup> <Accordion title="Without structured outputs"> ```text theme={null} Here's a classic chocolate chip cookie recipe! **Chocolate Chip Cookies** Prep time: 15 minutes | Cook time: 10 minutes Ingredients: - 2 1/4 cups all-purpose flour - 1 cup butter, softened ... ``` To use this in your app, you'd need to parse out the title, convert "15 minutes" to a number, separate ingredients from instructions, and handle inconsistent formatting across responses. </Accordion> <Accordion title="With structured outputs"> ```json theme={null} { "name": "Chocolate Chip Cookies", "prep_time_minutes": 15, "cook_time_minutes": 10, "ingredients": [ { "item": "all-purpose flour", "amount": 2.25, "unit": "cups" }, { "item": "butter, softened", "amount": 1, "unit": "cup" } // ... ], "steps": ["Preheat oven to 375°F", "Cream butter and sugar" /* ... */] } ``` Typed data you can use directly in your UI. </Accordion> </AccordionGroup> ## Quick start To use structured outputs, define a [JSON Schema](https://json-schema.org/understanding-json-schema/about) describing the shape of data you want, then pass it to `query()` via the `outputFormat` option (TypeScript) or `output_format` option (Python). When the agent finishes, the result message includes a `structured_output` field with validated data matching your schema. The example below asks the agent to research Anthropic and return the company name, year founded, and headquarters as structured output. <CodeGroup> ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; // Define the shape of data you want back const schema = { type: "object", properties: { company_name: { type: "string" }, founded_year: { type: "number" }, headquarters: { type: "string" } }, required: ["company_name"] }; for await (const message of query({ prompt: "Research Anthropic and provide key company information", options: { outputFormat: { type: "json_schema", schema: schema } } })) { // The result message contains structured_output with validated data if (message.type === "result" && message.subtype === "success" && message.structured_output) { console.log(message.structured_output); // { company_name: "Anthropic", founded_year: 2021, headquarters: "San Francisco, CA" } } } ``` ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage # Define the shape of data you want back schema = { "type": "object", "properties": { "company_name": {"type": "string"}, "founded_year": {"type": "number"}, "headquarters": {"type": "string"}, }, "required": ["company_name"], } async def main(): async for message in query( prompt="Research Anthropic and provide key company information", options=ClaudeAgentOptions( output_format={"type": "json_schema", "schema": schema} ), ): # The result message contains structured_output with validated data if isinstance(message, ResultMessage) and message.structured_output: print(message.structured_output) # {'company_name': 'Anthropic', 'founded_year': 2021, 'headquarters': 'San Francisco, CA'} asyncio.run(main()) ``` </CodeGroup> ## Type-safe schemas with Zod and Pydantic Instead of writing JSON Schema by hand, you can use [Zod](https://zod.dev/) (TypeScript) or [Pydantic](https://docs.pydantic.dev/latest/) (Python) to define your schema. These libraries generate the JSON Schema for you and let you parse the response into a fully-typed object you can use throughout your codebase with autocomplete and type checking. The example below defines a schema for a feature implementation plan with a summary, list of steps (each with complexity level), and potential risks. The agent plans the feature and returns a typed `FeaturePlan` object. You can then access properties like `plan.summary` and iterate over `plan.steps` with full type safety. <CodeGroup> ```typescript TypeScript theme={null} import { z } from "zod"; import { query } from "@anthropic-ai/claude-agent-sdk"; // Define schema with Zod const FeaturePlan = z.object({ feature_name: z.string(), summary: z.string(), steps: z.array( z.object({ step_number: z.number(), description: z.string(), estimated_complexity: z.enum(["low", "medium", "high"]) }) ), risks: z.array(z.string()) }); type FeaturePlan = z.infer<typeof FeaturePlan>; // Convert to JSON Schema const schema = z.toJSONSchema(FeaturePlan); // Use in query for await (const message of query({ prompt: "Plan how to add dark mode support to a React app. Break it into implementation steps.", options: { outputFormat: { type: "json_schema", schema: schema } } })) { if (message.type === "result" && message.subtype === "success" && message.structured_output) { // Validate and get fully typed result const parsed = FeaturePlan.safeParse(message.structured_output); if (parsed.success) { const plan: FeaturePlan = parsed.data; console.log(`Feature: ${plan.feature_name}`); console.log(`Summary: ${plan.summary}`); plan.steps.forEach((step) => { console.log(`${step.step_number}. [${step.estimated_complexity}] ${step.description}`); }); } } } ``` ```python Python theme={null} import asyncio from pydantic import BaseModel from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage class Step(BaseModel): step_number: int description: str estimated_complexity: str # 'low', 'medium', 'high' class FeaturePlan(BaseModel): feature_name: str summary: str steps: list[Step] risks: list[str] async def main(): async for message in query( prompt="Plan how to add dark mode support to a React app. Break it into implementation steps.", options=ClaudeAgentOptions( output_format={ "type": "json_schema", "schema": FeaturePlan.model_json_schema(), } ), ): if isinstance(message, ResultMessage) and message.structured_output: # Validate and get fully typed result plan = FeaturePlan.model_validate(message.structured_output) print(f"Feature: {plan.feature_name}") print(f"Summary: {plan.summary}") for step in plan.steps: print( f"{step.step_number}. [{step.estimated_complexity}] {step.description}" ) asyncio.run(main()) ``` </CodeGroup> **Benefits:** * Full type inference (TypeScript) and type hints (Python) * Runtime validation with `safeParse()` or `model_validate()` * Better error messages * Composable, reusable schemas ## Output format configuration The `outputFormat` (TypeScript) or `output_format` (Python) option accepts an object with: * `type`: Set to `"json_schema"` for structured outputs * `schema`: A [JSON Schema](https://json-schema.org/understanding-json-schema/about) object defining your output structure. You can generate this from a Zod schema with `z.toJSONSchema()` or a Pydantic model with `.model_json_schema()` The SDK supports standard JSON Schema features including all basic types (object, array, string, number, boolean, null), `enum`, `const`, `required`, nested objects, and `$ref` definitions. For the full list of supported features and limitations, see [JSON Schema limitations](../04-API-Reference/Guides/build-with-claude-structured-outputs-2638e81449.md#json-schema-limitations). ## Example: TODO tracking agent This example demonstrates how structured outputs work with multi-step tool use. The agent needs to find TODO comments in the codebase, then look up git blame information for each one. It autonomously decides which tools to use (Grep to search, Bash to run git commands) and combines the results into a single structured response. The schema includes optional fields (`author` and `date`) since git blame information might not be available for all files. The agent fills in what it can find and omits the rest. <CodeGroup> ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; // Define structure for TODO extraction const todoSchema = { type: "object", properties: { todos: { type: "array", items: { type: "object", properties: { text: { type: "string" }, file: { type: "string" }, line: { type: "number" }, author: { type: "string" }, date: { type: "string" } }, required: ["text", "file", "line"] } }, total_count: { type: "number" } }, required: ["todos", "total_count"] }; // Agent uses Grep to find TODOs, Bash to get git blame info for await (const message of query({ prompt: "Find all TODO comments in this codebase and identify who added them", options: { outputFormat: { type: "json_schema", schema: todoSchema } } })) { if (message.type === "result" && message.subtype === "success" && message.structured_output) { const data = message.structured_output as { total_count: number; todos: Array<{ file: string; line: number; text: string; author?: string; date?: string }> }; console.log(`Found ${data.total_count} TODOs`); data.todos.forEach((todo) => { console.log(`${todo.file}:${todo.line} - ${todo.text}`); if (todo.author) { console.log(` Added by ${todo.author} on ${todo.date}`); } }); } } ``` ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage # Define structure for TODO extraction todo_schema = { "type": "object", "properties": { "todos": { "type": "array", "items": { "type": "object", "properties": { "text": {"type": "string"}, "file": {"type": "string"}, "line": {"type": "number"}, "author": {"type": "string"}, "date": {"type": "string"}, }, "required": ["text", "file", "line"], }, }, "total_count": {"type": "number"}, }, "required": ["todos", "total_count"], } async def main(): # Agent uses Grep to find TODOs, Bash to get git blame info async for message in query( prompt="Find all TODO comments in this codebase and identify who added them", options=ClaudeAgentOptions( output_format={"type": "json_schema", "schema": todo_schema} ), ): if isinstance(message, ResultMessage) and message.structured_output: data = message.structured_output print(f"Found {data['total_count']} TODOs") for todo in data["todos"]: print(f"{todo['file']}:{todo['line']} - {todo['text']}") if "author" in todo: print(f" Added by {todo['author']} on {todo['date']}") asyncio.run(main()) ``` </CodeGroup> ## Error handling Structured output generation can fail when the agent cannot produce valid JSON matching your schema. This typically happens when the schema is too complex for the task, the task itself is ambiguous, or the agent hits its retry limit trying to fix validation errors. When an error occurs, the result message has a `subtype` indicating what went wrong: | Subtype | Meaning | | ------------------------------------- | ----------------------------------------------------------- | | `success` | Output was generated and validated successfully | | `error_max_structured_output_retries` | Agent couldn't produce valid output after multiple attempts | The example below checks the `subtype` field to determine whether the output was generated successfully or if you need to handle a failure: <CodeGroup> ```typescript TypeScript theme={null} for await (const msg of query({ prompt: "Extract contact info from the document", options: { outputFormat: { type: "json_schema", schema: contactSchema } } })) { if (msg.type === "result") { if (msg.subtype === "success" && msg.structured_output) { // Use the validated output console.log(msg.structured_output); } else if (msg.subtype === "error_max_structured_output_retries") { // Handle the failure - retry with simpler prompt, fall back to unstructured, etc. console.error("Could not produce valid output"); } } } ``` ```python Python theme={null} async for message in query( prompt="Extract contact info from the document", options=ClaudeAgentOptions( output_format={"type": "json_schema", "schema": contact_schema} ), ): if isinstance(message, ResultMessage): if message.subtype == "success" and message.structured_output: # Use the validated output print(message.structured_output) elif message.subtype == "error_max_structured_output_retries": # Handle the failure print("Could not produce valid output") ``` </CodeGroup> **Tips for avoiding errors:** * **Keep schemas focused.** Deeply nested schemas with many required fields are harder to satisfy. Start simple and add complexity as needed. * **Match schema to task.** If the task might not have all the information your schema requires, make those fields optional. * **Use clear prompts.** Ambiguous prompts make it harder for the agent to know what output to produce. ## Related resources * [JSON Schema documentation](https://json-schema.org/): learn JSON Schema syntax for defining complex schemas with nested objects, arrays, enums, and validation constraints * [API Structured Outputs](../04-API-Reference/Guides/build-with-claude-structured-outputs-2638e81449.md): use structured outputs with the Claude API directly for single-turn requests without tool use * [Custom tools](/en/agent-sdk/custom-tools): give your agent custom tools to call during execution before returning structured output --- ## agent-sdk-subagents-1d8ec0569d.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Subagents in the SDK > Define and invoke subagents to isolate context, run tasks in parallel, and apply specialized instructions in your Claude Agent SDK applications. Subagents are separate agent instances that your main agent can spawn to handle focused subtasks. Use subagents to isolate context for focused subtasks, run multiple analyses in parallel, and apply specialized instructions without bloating the main agent's prompt. This guide explains how to define and use subagents in the SDK using the `agents` parameter. ## Overview You can create subagents in three ways: * **Programmatically**: use the `agents` parameter in your `query()` options ([TypeScript](/en/agent-sdk/typescript#agent-definition), [Python](/en/agent-sdk/python#agent-definition)) * **Filesystem-based**: define agents as markdown files in `.claude/agents/` directories (see [defining subagents as files](create-custom-subagents-claude-code-docs-7dc93e85c0.md)) * **Built-in general-purpose**: Claude can invoke the built-in `general-purpose` subagent at any time via the Agent tool without you defining anything This guide focuses on the programmatic approach, which is recommended for SDK applications. When you define subagents, Claude determines whether to invoke them based on each subagent's `description` field. Write clear descriptions that explain when the subagent should be used, and Claude will automatically delegate appropriate tasks. You can also explicitly request a subagent by name in your prompt (for example, "Use the code-reviewer agent to..."). ## Benefits of using subagents ### Context isolation Each subagent runs in its own fresh conversation. Intermediate tool calls and results stay inside the subagent; only its final message returns to the parent. See [What subagents inherit](#what-subagents-inherit) for exactly what's in the subagent's context. **Example:** a `research-assistant` subagent can explore dozens of files without any of that content accumulating in the main conversation. The parent receives a concise summary, not every file the subagent read. ### Parallelization Multiple subagents can run concurrently, dramatically speeding up complex workflows. **Example:** during a code review, you can run `style-checker`, `security-scanner`, and `test-coverage` subagents simultaneously, reducing review time from minutes to seconds. ### Specialized instructions and knowledge Each subagent can have tailored system prompts with specific expertise, best practices, and constraints. **Example:** a `database-migration` subagent can have detailed knowledge about SQL best practices, rollback strategies, and data integrity checks that would be unnecessary noise in the main agent's instructions. ### Tool restrictions Subagents can be limited to specific tools, reducing the risk of unintended actions. **Example:** a `doc-reviewer` subagent might only have access to Read and Grep tools, ensuring it can analyze but never accidentally modify your documentation files. ## Creating subagents ### Programmatic definition (recommended) Define subagents directly in your code using the `agents` parameter. This example creates two subagents: a code reviewer with read-only access and a test runner that can execute commands. The `Agent` tool must be included in `allowedTools` since Claude invokes subagents through the Agent tool. <CodeGroup> ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition async def main(): async for message in query( prompt="Review the authentication module for security issues", options=ClaudeAgentOptions( # Agent tool is required for subagent invocation allowed_tools=["Read", "Grep", "Glob", "Agent"], agents={ "code-reviewer": AgentDefinition( # description tells Claude when to use this subagent description="Expert code review specialist. Use for quality, security, and maintainability reviews.", # prompt defines the subagent's behavior and expertise prompt="""You are a code review specialist with expertise in security, performance, and best practices. When reviewing code: - Identify security vulnerabilities - Check for performance issues - Verify adherence to coding standards - Suggest specific improvements Be thorough but concise in your feedback.""", # tools restricts what the subagent can do (read-only here) tools=["Read", "Grep", "Glob"], # model overrides the default model for this subagent model="sonnet", ), "test-runner": AgentDefinition( description="Runs and analyzes test suites. Use for test execution and coverage analysis.", prompt="""You are a test execution specialist. Run tests and provide clear analysis of results. Focus on: - Running test commands - Analyzing test output - Identifying failing tests - Suggesting fixes for failures""", # Bash access lets this subagent run test commands tools=["Bash", "Read", "Grep"], ), }, ), ): if hasattr(message, "result"): print(message.result) asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Review the authentication module for security issues", options: { // Agent tool is required for subagent invocation allowedTools: ["Read", "Grep", "Glob", "Agent"], agents: { "code-reviewer": { // description tells Claude when to use this subagent description: "Expert code review specialist. Use for quality, security, and maintainability reviews.", // prompt defines the subagent's behavior and expertise prompt: `You are a code review specialist with expertise in security, performance, and best practices. When reviewing code: - Identify security vulnerabilities - Check for performance issues - Verify adherence to coding standards - Suggest specific improvements Be thorough but concise in your feedback.`, // tools restricts what the subagent can do (read-only here) tools: ["Read", "Grep", "Glob"], // model overrides the default model for this subagent model: "sonnet" }, "test-runner": { description: "Runs and analyzes test suites. Use for test execution and coverage analysis.", prompt: `You are a test execution specialist. Run tests and provide clear analysis of results. Focus on: - Running test commands - Analyzing test output - Identifying failing tests - Suggesting fixes for failures`, // Bash access lets this subagent run test commands tools: ["Bash", "Read", "Grep"] } } } })) { if ("result" in message) console.log(message.result); } ``` </CodeGroup> ### AgentDefinition configuration | Field | Type | Required | Description | | :---------------- | :---------------------------------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `description` | `string` | Yes | Natural language description of when to use this agent | | `prompt` | `string` | Yes | The agent's system prompt defining its role and behavior | | `tools` | `string[]` | No | Array of allowed tool names. If omitted, inherits all tools | | `disallowedTools` | `string[]` | No | Array of tool names to remove from the agent's tool set | | `model` | `string` | No | Model override for this agent. Accepts an alias such as `'sonnet'`, `'opus'`, `'haiku'`, `'inherit'`, or a full model ID. Defaults to main model if omitted | | `skills` | `string[]` | No | List of skill names available to this agent | | `memory` | `'user' \| 'project' \| 'local'` | No | Memory source for this agent | | `mcpServers` | `(string \| object)[]` | No | MCP servers available to this agent, by name or inline config | | `maxTurns` | `number` | No | Maximum number of agentic turns before the agent stops | | `background` | `boolean` | No | Run this agent as a non-blocking background task when invoked | | `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max' \| number` | No | Reasoning effort level for this agent | | `permissionMode` | `PermissionMode` | No | Permission mode for tool execution within this agent | In the Python SDK, these field names use camelCase to match the wire format. See the [`AgentDefinition` reference](/en/agent-sdk/python#agent-definition) for details. <Note> Subagents cannot spawn their own subagents. Don't include `Agent` in a subagent's `tools` array. </Note> ### Filesystem-based definition (alternative) You can also define subagents as markdown files in `.claude/agents/` directories. See the [Claude Code subagents documentation](create-custom-subagents-claude-code-docs-7dc93e85c0.md) for details on this approach. Programmatically defined agents take precedence over filesystem-based agents with the same name. <Note> Even without defining custom subagents, Claude can spawn the built-in `general-purpose` subagent when `Agent` is in your `allowedTools`. This is useful for delegating research or exploration tasks without creating specialized agents. </Note> ## What subagents inherit A subagent's context window starts fresh (no parent conversation) but isn't empty. The only channel from parent to subagent is the Agent tool's prompt string, so include any file paths, error messages, or decisions the subagent needs directly in that prompt. | The subagent receives | The subagent does not receive | | :--------------------------------------------------------------------------- | :------------------------------------------------- | | Its own system prompt (`AgentDefinition.prompt`) and the Agent tool's prompt | The parent's conversation history or tool results | | Project CLAUDE.md (loaded via `settingSources`) | Skills (unless listed in `AgentDefinition.skills`) | | Tool definitions (inherited from parent, or the subset in `tools`) | The parent's system prompt | <Note> The parent receives the subagent's final message verbatim as the Agent tool result, but may summarize it in its own response. To preserve subagent output verbatim in the user-facing response, include an instruction to do so in the prompt or `systemPrompt` option you pass to the **main** `query()` call. </Note> ## Invoking subagents ### Automatic invocation Claude automatically decides when to invoke subagents based on the task and each subagent's `description`. For example, if you define a `performance-optimizer` subagent with the description "Performance optimization specialist for query tuning", Claude will invoke it when your prompt mentions optimizing queries. Write clear, specific descriptions so Claude can match tasks to the right subagent. ### Explicit invocation To guarantee Claude uses a specific subagent, mention it by name in your prompt: ```text theme={null} "Use the code-reviewer agent to check the authentication module" ``` This bypasses automatic matching and directly invokes the named subagent. ### Dynamic agent configuration You can create agent definitions dynamically based on runtime conditions. This example creates a security reviewer with different strictness levels, using a more powerful model for strict reviews. <CodeGroup> ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition # Factory function that returns an AgentDefinition # This pattern lets you customize agents based on runtime conditions def create_security_agent(security_level: str) -> AgentDefinition: is_strict = security_level == "strict" return AgentDefinition( description="Security code reviewer", # Customize the prompt based on strictness level prompt=f"You are a {'strict' if is_strict else 'balanced'} security reviewer...", tools=["Read", "Grep", "Glob"], # Key insight: use a more capable model for high-stakes reviews model="opus" if is_strict else "sonnet", ) async def main(): # The agent is created at query time, so each request can use different settings async for message in query( prompt="Review this PR for security issues", options=ClaudeAgentOptions( allowed_tools=["Read", "Grep", "Glob", "Agent"], agents={ # Call the factory with your desired configuration "security-reviewer": create_security_agent("strict") }, ), ): if hasattr(message, "result"): print(message.result) asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query, type AgentDefinition } from "@anthropic-ai/claude-agent-sdk"; // Factory function that returns an AgentDefinition // This pattern lets you customize agents based on runtime conditions function createSecurityAgent(securityLevel: "basic" | "strict"): AgentDefinition { const isStrict = securityLevel === "strict"; return { description: "Security code reviewer", // Customize the prompt based on strictness level prompt: `You are a ${isStrict ? "strict" : "balanced"} security reviewer...`, tools: ["Read", "Grep", "Glob"], // Key insight: use a more capable model for high-stakes reviews model: isStrict ? "opus" : "sonnet" }; } // The agent is created at query time, so each request can use different settings for await (const message of query({ prompt: "Review this PR for security issues", options: { allowedTools: ["Read", "Grep", "Glob", "Agent"], agents: { // Call the factory with your desired configuration "security-reviewer": createSecurityAgent("strict") } } })) { if ("result" in message) console.log(message.result); } ``` </CodeGroup> ## Detecting subagent invocation Subagents are invoked via the Agent tool. To detect when a subagent is invoked, check for `tool_use` blocks where `name` is `"Agent"`. Messages from within a subagent's context include a `parent_tool_use_id` field. <Note> The tool name was renamed from `"Task"` to `"Agent"` in Claude Code v2.1.63. Current SDK releases emit `"Agent"` in `tool_use` blocks but still use `"Task"` in the `system:init` tools list and in `result.permission_denials[].tool_name`. Checking both values in `block.name` ensures compatibility across SDK versions. </Note> This example iterates through streamed messages, logging when a subagent is invoked and when subsequent messages originate from within that subagent's execution context. <Note> The message structure differs between SDKs. In Python, content blocks are accessed directly via `message.content`. In TypeScript, `SDKAssistantMessage` wraps the Claude API message, so content is accessed via `message.message.content`. </Note> <CodeGroup> ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition async def main(): async for message in query( prompt="Use the code-reviewer agent to review this codebase", options=ClaudeAgentOptions( allowed_tools=["Read", "Glob", "Grep", "Agent"], agents={ "code-reviewer": AgentDefinition( description="Expert code reviewer.", prompt="Analyze code quality and suggest improvements.", tools=["Read", "Glob", "Grep"], ) }, ), ): # Check for subagent invocation. Match both names: older SDK # versions emitted "Task", current versions emit "Agent". if hasattr(message, "content") and message.content: for block in message.content: if getattr(block, "type", None) == "tool_use" and block.name in ( "Task", "Agent", ): print(f"Subagent invoked: {block.input.get('subagent_type')}") # Check if this message is from within a subagent's context if hasattr(message, "parent_tool_use_id") and message.parent_tool_use_id: print(" (running inside subagent)") if hasattr(message, "result"): print(message.result) asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Use the code-reviewer agent to review this codebase", options: { allowedTools: ["Read", "Glob", "Grep", "Agent"], agents: { "code-reviewer": { description: "Expert code reviewer.", prompt: "Analyze code quality and suggest improvements.", tools: ["Read", "Glob", "Grep"] } } } })) { const msg = message as any; // Check for subagent invocation. Match both names: older SDK versions // emitted "Task", current versions emit "Agent". for (const block of msg.message?.content ?? []) { if (block.type === "tool_use" && (block.name === "Task" || block.name === "Agent")) { console.log(`Subagent invoked: ${block.input.subagent_type}`); } } // Check if this message is from within a subagent's context if (msg.parent_tool_use_id) { console.log(" (running inside subagent)"); } if ("result" in message) { console.log(message.result); } } ``` </CodeGroup> ## Resuming subagents Subagents can be resumed to continue where they left off. Resumed subagents retain their full conversation history, including all previous tool calls, results, and reasoning. The subagent picks up exactly where it stopped rather than starting fresh. When a subagent completes, Claude receives its agent ID in the Agent tool result. To resume a subagent programmatically: 1. **Capture the session ID**: Extract `session_id` from messages during the first query 2. **Extract the agent ID**: Parse `agentId` from the message content 3. **Resume the session**: Pass `resume: sessionId` in the second query's options, and include the agent ID in your prompt <Note> You must resume the same session to access the subagent's transcript. Each `query()` call starts a new session by default, so pass `resume: sessionId` to continue in the same session. If you're using a custom agent (not a built-in one), you also need to pass the same agent definition in the `agents` parameter for both queries. </Note> The example below demonstrates this flow: the first query runs a subagent and captures the session ID and agent ID, then the second query resumes the session to ask a follow-up question that requires context from the first analysis. <CodeGroup> ```typescript TypeScript theme={null} import { query, type SDKMessage } from "@anthropic-ai/claude-agent-sdk"; // Helper to extract agentId from message content // Stringify to avoid traversing different block types (TextBlock, ToolResultBlock, etc.) function extractAgentId(message: SDKMessage): string | undefined { if (!("message" in message)) return undefined; // Stringify the content so we can search it without traversing nested blocks const content = JSON.stringify(message.message.content); const match = content.match(/agentId:\s*([a-f0-9-]+)/); return match?.[1]; } let agentId: string | undefined; let sessionId: string | undefined; // First invocation - use the Explore agent to find API endpoints for await (const message of query({ prompt: "Use the Explore agent to find all API endpoints in this codebase", options: { allowedTools: ["Read", "Grep", "Glob", "Agent"] } })) { // Capture session_id from ResultMessage (needed to resume this session) if ("session_id" in message) sessionId = message.session_id; // Search message content for the agentId (appears in Agent tool results) const extractedId = extractAgentId(message); if (extractedId) agentId = extractedId; // Print the final result if ("result" in message) console.log(message.result); } // Second invocation - resume and ask follow-up if (agentId && sessionId) { for await (const message of query({ prompt: `Resume agent ${agentId} and list the top 3 most complex endpoints`, options: { allowedTools: ["Read", "Grep", "Glob", "Agent"], resume: sessionId } })) { if ("result" in message) console.log(message.result); } } ``` ```python Python theme={null} import asyncio import json import re from claude_agent_sdk import query, ClaudeAgentOptions def extract_agent_id(text: str) -> str | None: """Extract agentId from Agent tool result text.""" match = re.search(r"agentId:\s*([a-f0-9-]+)", text) return match.group(1) if match else None async def main(): agent_id = None session_id = None # First invocation - use the Explore agent to find API endpoints async for message in query( prompt="Use the Explore agent to find all API endpoints in this codebase", options=ClaudeAgentOptions(allowed_tools=["Read", "Grep", "Glob", "Agent"]), ): # Capture session_id from ResultMessage (needed to resume this session) if hasattr(message, "session_id"): session_id = message.session_id # Search message content for the agentId (appears in Agent tool results) if hasattr(message, "content"): # Stringify the content so we can search it without traversing nested blocks content_str = json.dumps(message.content, default=str) extracted = extract_agent_id(content_str) if extracted: agent_id = extracted # Print the final result if hasattr(message, "result"): print(message.result) # Second invocation - resume and ask follow-up if agent_id and session_id: async for message in query( prompt=f"Resume agent {agent_id} and list the top 3 most complex endpoints", options=ClaudeAgentOptions( allowed_tools=["Read", "Grep", "Glob", "Agent"], resume=session_id ), ): if hasattr(message, "result"): print(message.result) asyncio.run(main()) ``` </CodeGroup> Subagent transcripts persist independently of the main conversation: * **Main conversation compaction**: When the main conversation compacts, subagent transcripts are unaffected. They're stored in separate files. * **Session persistence**: Subagent transcripts persist within their session. You can resume a subagent after restarting Claude Code by resuming the same session. * **Automatic cleanup**: Transcripts are cleaned up based on the `cleanupPeriodDays` setting (default: 30 days). ## Tool restrictions Subagents can have restricted tool access via the `tools` field: * **Omit the field**: agent inherits all available tools (default) * **Specify tools**: agent can only use listed tools This example creates a read-only analysis agent that can examine code but cannot modify files or run commands. <CodeGroup> ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition async def main(): async for message in query( prompt="Analyze the architecture of this codebase", options=ClaudeAgentOptions( allowed_tools=["Read", "Grep", "Glob", "Agent"], agents={ "code-analyzer": AgentDefinition( description="Static code analysis and architecture review", prompt="""You are a code architecture analyst. Analyze code structure, identify patterns, and suggest improvements without making changes.""", # Read-only tools: no Edit, Write, or Bash access tools=["Read", "Grep", "Glob"], ) }, ), ): if hasattr(message, "result"): print(message.result) asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Analyze the architecture of this codebase", options: { allowedTools: ["Read", "Grep", "Glob", "Agent"], agents: { "code-analyzer": { description: "Static code analysis and architecture review", prompt: `You are a code architecture analyst. Analyze code structure, identify patterns, and suggest improvements without making changes.`, // Read-only tools: no Edit, Write, or Bash access tools: ["Read", "Grep", "Glob"] } } } })) { if ("result" in message) console.log(message.result); } ``` </CodeGroup> ### Common tool combinations | Use case | Tools | Description | | :----------------- | :-------------------------------------- | :-------------------------------------------------- | | Read-only analysis | `Read`, `Grep`, `Glob` | Can examine code but not modify or execute | | Test execution | `Bash`, `Read`, `Grep` | Can run commands and analyze output | | Code modification | `Read`, `Edit`, `Write`, `Grep`, `Glob` | Full read/write access without command execution | | Full access | All tools | Inherits all tools from parent (omit `tools` field) | ## Troubleshooting ### Claude not delegating to subagents If Claude completes tasks directly instead of delegating to your subagent: 1. **Include the Agent tool**: subagents are invoked via the Agent tool, so it must be in `allowedTools` 2. **Use explicit prompting**: mention the subagent by name in your prompt (for example, "Use the code-reviewer agent to...") 3. **Write a clear description**: explain exactly when the subagent should be used so Claude can match tasks appropriately ### Filesystem-based agents not loading Agents defined in `.claude/agents/` are loaded at startup only. If you create a new agent file while Claude Code is running, restart the session to load it. ### Windows: long prompt failures On Windows, subagents with very long prompts may fail due to command line length limits (8191 chars). Keep prompts concise or use filesystem-based agents for complex instructions. ## Related documentation * [Claude Code subagents](create-custom-subagents-claude-code-docs-7dc93e85c0.md): comprehensive subagent documentation including filesystem-based definitions * [SDK overview](/en/agent-sdk/overview): getting started with the Claude Agent SDK --- ## agent-sdk-todo-tracking-042ff23363.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Todo Lists > Track and display todos using the Claude Agent SDK for organized task management Todo tracking provides a structured way to manage tasks and display progress to users. The Claude Agent SDK includes built-in todo functionality that helps organize complex workflows and keep users informed about task progression. ### Todo Lifecycle Todos follow a predictable lifecycle: 1. **Created** as `pending` when tasks are identified 2. **Activated** to `in_progress` when work begins 3. **Completed** when the task finishes successfully 4. **Removed** when all tasks in a group are completed ### When Todos Are Used The SDK automatically creates todos for: * **Complex multi-step tasks** requiring 3 or more distinct actions * **User-provided task lists** when multiple items are mentioned * **Non-trivial operations** that benefit from progress tracking * **Explicit requests** when users ask for todo organization ## Examples ### Monitoring Todo Changes <CodeGroup> ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Optimize my React app performance and track progress with todos", options: { maxTurns: 15 } })) { // Todo updates are reflected in the message stream if (message.type === "assistant") { for (const block of message.message.content) { if (block.type === "tool_use" && block.name === "TodoWrite") { const todos = block.input.todos; console.log("Todo Status Update:"); todos.forEach((todo, index) => { const status = todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌"; console.log(`${index + 1}. ${status} ${todo.content}`); }); } } } } ``` ```python Python theme={null} from claude_agent_sdk import query, AssistantMessage, ToolUseBlock async for message in query( prompt="Optimize my React app performance and track progress with todos", options={"max_turns": 15}, ): # Todo updates are reflected in the message stream if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, ToolUseBlock) and block.name == "TodoWrite": todos = block.input["todos"] print("Todo Status Update:") for i, todo in enumerate(todos): status = ( "✅" if todo["status"] == "completed" else "🔧" if todo["status"] == "in_progress" else "❌" ) print(f"{i + 1}. {status} {todo['content']}") ``` </CodeGroup> ### Real-time Progress Display <CodeGroup> ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; class TodoTracker { private todos: any[] = []; displayProgress() { if (this.todos.length === 0) return; const completed = this.todos.filter((t) => t.status === "completed").length; const inProgress = this.todos.filter((t) => t.status === "in_progress").length; const total = this.todos.length; console.log(`\nProgress: ${completed}/${total} completed`); console.log(`Currently working on: ${inProgress} task(s)\n`); this.todos.forEach((todo, index) => { const icon = todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌"; const text = todo.status === "in_progress" ? todo.activeForm : todo.content; console.log(`${index + 1}. ${icon} ${text}`); }); } async trackQuery(prompt: string) { for await (const message of query({ prompt, options: { maxTurns: 20 } })) { if (message.type === "assistant") { for (const block of message.message.content) { if (block.type === "tool_use" && block.name === "TodoWrite") { this.todos = block.input.todos; this.displayProgress(); } } } } } } // Usage const tracker = new TodoTracker(); await tracker.trackQuery("Build a complete authentication system with todos"); ``` ```python Python theme={null} from claude_agent_sdk import query, AssistantMessage, ToolUseBlock from typing import List, Dict class TodoTracker: def __init__(self): self.todos: List[Dict] = [] def display_progress(self): if not self.todos: return completed = len([t for t in self.todos if t["status"] == "completed"]) in_progress = len([t for t in self.todos if t["status"] == "in_progress"]) total = len(self.todos) print(f"\nProgress: {completed}/{total} completed") print(f"Currently working on: {in_progress} task(s)\n") for i, todo in enumerate(self.todos): icon = ( "✅" if todo["status"] == "completed" else "🔧" if todo["status"] == "in_progress" else "❌" ) text = ( todo["activeForm"] if todo["status"] == "in_progress" else todo["content"] ) print(f"{i + 1}. {icon} {text}") async def track_query(self, prompt: str): async for message in query(prompt=prompt, options={"max_turns": 20}): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, ToolUseBlock) and block.name == "TodoWrite": self.todos = block.input["todos"] self.display_progress() # Usage tracker = TodoTracker() await tracker.track_query("Build a complete authentication system with todos") ``` </CodeGroup> ## Related Documentation * [TypeScript SDK Reference](/en/agent-sdk/typescript) * [Python SDK Reference](/en/agent-sdk/python) * [Streaming vs Single Mode](/en/agent-sdk/streaming-vs-single-mode) * [Custom Tools](/en/agent-sdk/custom-tools) --- ## agent-sdk-tool-search-4f082773c0.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Scale to many tools with tool search > Scale your agent to thousands of tools by discovering and loading only what's needed, on demand. Tool search enables your agent to work with hundreds or thousands of tools by dynamically discovering and loading them on demand. Instead of loading all tool definitions into the context window upfront, the agent searches your tool catalog and loads only the tools it needs. This approach solves two challenges as tool libraries scale: * **Context efficiency:** Tool definitions can consume large portions of the context window (50 tools can use 10-20K tokens), leaving less room for actual work. * **Tool selection accuracy:** Tool selection accuracy degrades with more than 30-50 tools loaded at once. Tool search is enabled by default. This page covers [how it works](#how-tool-search-works), how to [configure it](#configure-tool-search), and how to [optimize tool discovery](#optimize-tool-discovery). ## How tool search works When tool search is active, tool definitions are withheld from the context window. The agent receives a summary of available tools and searches for relevant ones when the task requires a capability not already loaded. The 3-5 most relevant tools are loaded into context, where they stay available for subsequent turns. If the conversation is long enough that the SDK compacts earlier messages to free space, previously discovered tools may be removed, and the agent searches again as needed. Tool search adds one extra round-trip the first time Claude discovers a tool (the search step), but for large tool sets this is offset by smaller context on every turn. With fewer than \~10 tools, loading everything upfront is typically faster. For details on the underlying API mechanism, see [Tool search in the API](../04-API-Reference/Agents-Tools/agents-and-tools-tool-use-tool-search-tool-5499cf85ce.md). <Note> Tool search requires Claude Sonnet 4 or later, or Claude Opus 4 or later. Haiku models do not support tool search. </Note> ## Configure tool search By default, tool search is always on. You can change this with the `ENABLE_TOOL_SEARCH` environment variable: | Value | Behavior | | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | (unset) | Tool search is always on. Tool definitions are never loaded into context. This is the default. | | `true` | Same as unset. | | `auto` | Checks the combined token count of all tool definitions against the model's context window. If they exceed 10%, tool search activates. If they're under 10%, all tools are loaded into context normally. | | `auto:N` | Same as `auto` with a custom percentage. `auto:5` activates when tool definitions exceed 5% of the context window. Lower values activate sooner. | | `false` | Tool search is off. All tool definitions are loaded into context on every turn. | Tool search applies to all registered tools, whether they come from remote MCP servers or [custom SDK MCP servers](/en/agent-sdk/custom-tools). When using `auto`, the threshold is based on the combined size of all tool definitions across all servers. Set the value in the `env` option on `query()`. This example connects to a remote MCP server that exposes many tools, pre-approves all of them with a wildcard, and uses `auto:5` so tool search activates when their definitions exceed 5% of the context window: <CodeGroup> ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Find and run the appropriate database query", options: { mcpServers: { "enterprise-tools": { // Connect to a remote MCP server type: "http", url: "https://tools.example.com/mcp" } }, allowedTools: ["mcp__enterprise-tools__*"], // Wildcard pre-approves all tools from this server env: { ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when tools exceed 5% of context } } })) { if (message.type === "result" && message.subtype === "success") { console.log(message.result); } } ``` ```python Python theme={null} import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage async def main(): options = ClaudeAgentOptions( mcp_servers={ "enterprise-tools": { "type": "http", "url": "https://tools.example.com/mcp", } }, allowed_tools=[ "mcp__enterprise-tools__*" ], # Wildcard pre-approves all tools from this server env={ "ENABLE_TOOL_SEARCH": "auto:5" # Activate tool search when tools exceed 5% of context }, ) async for message in query( prompt="Find and run the appropriate database query", options=options, ): if isinstance(message, ResultMessage) and message.subtype == "success": print(message.result) asyncio.run(main()) ``` </CodeGroup> Setting `ENABLE_TOOL_SEARCH` to `"false"` disables tool search and loads all tool definitions into context on every turn. This removes the search round-trip, which can be faster when the tool set is small (fewer than \~10 tools) and the definitions fit comfortably in the context window. ## Optimize tool discovery The search mechanism matches queries against tool names and descriptions. Names like `search_slack_messages` surface for a wider range of requests than `query_slack`. Descriptions with specific keywords ("Search Slack messages by keyword, channel, or date range") match more queries than generic ones ("Query Slack"). You can also add a system prompt section listing available tool categories. This gives the agent context about what kinds of tools are available to search for: ```text theme={null} You can search for tools to interact with Slack, GitHub, and Jira. ``` ## Limits * **Maximum tools:** 10,000 tools in your catalog * **Search results:** Returns 3-5 most relevant tools per search * **Model support:** Claude Sonnet 4 and later, Claude Opus 4 and later (no Haiku) ## Related documentation * [Tool search in the API](../04-API-Reference/Agents-Tools/agents-and-tools-tool-use-tool-search-tool-5499cf85ce.md): Full API documentation for tool search, including custom implementations * [Connect MCP servers](/en/agent-sdk/mcp): Connect to external tools via MCP servers * [Custom tools](/en/agent-sdk/custom-tools): Build your own tools with SDK MCP servers * [TypeScript SDK reference](/en/agent-sdk/typescript): Full API reference * [Python SDK reference](/en/agent-sdk/python): Full API reference --- ## agent-sdk-typescript-571c12ba22.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Agent SDK reference - TypeScript > Complete API reference for the TypeScript Agent SDK, including all functions, types, and interfaces. <script src="/components/typescript-sdk-type-links.js" defer /> <Note> **Try the new V2 interface (preview):** A simplified interface with `send()` and `stream()` patterns is now available, making multi-turn conversations easier. [Learn more about the TypeScript V2 preview](/en/agent-sdk/typescript-v2-preview) </Note> ## Installation ```bash theme={null} npm install @anthropic-ai/claude-agent-sdk ``` <Note> The SDK bundles a native Claude Code binary for your platform as an optional dependency such as `@anthropic-ai/claude-agent-sdk-darwin-arm64`. You don't need to install Claude Code separately. If your package manager skips optional dependencies, the SDK throws `Native CLI binary for <platform> not found`; set [`pathToClaudeCodeExecutable`](#options) to a separately installed `claude` binary instead. </Note> ## Functions ### `query()` The primary function for interacting with Claude Code. Creates an async generator that streams messages as they arrive. ```typescript theme={null} function query({ prompt, options }: { prompt: string | AsyncIterable<SDKUserMessage>; options?: Options; }): Query; ``` #### Parameters | Parameter | Type | Description | | :-------- | :---------------------------------------------------------------- | :---------------------------------------------------------------- | | `prompt` | `string \| AsyncIterable<`[`SDKUserMessage`](#sdkuser-message)`>` | The input prompt as a string or async iterable for streaming mode | | `options` | [`Options`](#options) | Optional configuration object (see Options type below) | #### Returns Returns a [`Query`](#query-object) object that extends `AsyncGenerator<`[`SDKMessage`](#sdk-message)`, void>` with additional methods. ### `startup()` Pre-warms the CLI subprocess by spawning it and completing the initialize handshake before a prompt is available. The returned [`WarmQuery`](#warm-query) handle accepts a prompt later and writes it to an already-ready process, so the first `query()` call resolves without paying subprocess spawn and initialization cost inline. ```typescript theme={null} function startup(params?: { options?: Options; initializeTimeoutMs?: number; }): Promise<WarmQuery>; ``` #### Parameters | Parameter | Type | Description | | :-------------------- | :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `options` | [`Options`](#options) | Optional configuration object. Same as the `options` parameter to `query()` | | `initializeTimeoutMs` | `number` | Maximum time in milliseconds to wait for subprocess initialization. Defaults to `60000`. If initialization does not complete in time, the promise rejects with a timeout error | #### Returns Returns a `Promise<`[`WarmQuery`](#warm-query)`>` that resolves once the subprocess has spawned and completed its initialize handshake. #### Example Call `startup()` early, for example on application boot, then call `.query()` on the returned handle once a prompt is ready. This moves subprocess spawn and initialization out of the critical path. ```typescript theme={null} import { startup } from "@anthropic-ai/claude-agent-sdk"; // Pay startup cost upfront const warm = await startup({ options: { maxTurns: 3 } }); // Later, when a prompt is ready, this is immediate for await (const message of warm.query("What files are here?")) { console.log(message); } ``` ### `tool()` Creates a type-safe MCP tool definition for use with SDK MCP servers. ```typescript theme={null} function tool<Schema extends AnyZodRawShape>( name: string, description: string, inputSchema: Schema, handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>, extras?: { annotations?: ToolAnnotations } ): SdkMcpToolDefinition<Schema>; ``` #### Parameters | Parameter | Type | Description | | :------------ | :------------------------------------------------------------------ | :------------------------------------------------------------------------------ | | `name` | `string` | The name of the tool | | `description` | `string` | A description of what the tool does | | `inputSchema` | `Schema extends AnyZodRawShape` | Zod schema defining the tool's input parameters (supports both Zod 3 and Zod 4) | | `handler` | `(args, extra) => Promise<`[`CallToolResult`](#call-tool-result)`>` | Async function that executes the tool logic | | `extras` | `{ annotations?: `[`ToolAnnotations`](#tool-annotations)` }` | Optional MCP tool annotations providing behavioral hints to clients | #### `ToolAnnotations` Re-exported from `@modelcontextprotocol/sdk/types.js`. All fields are optional hints; clients should not rely on them for security decisions. | Field | Type | Default | Description | | :---------------- | :-------- | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | | `title` | `string` | `undefined` | Human-readable title for the tool | | `readOnlyHint` | `boolean` | `false` | If `true`, the tool does not modify its environment | | `destructiveHint` | `boolean` | `true` | If `true`, the tool may perform destructive updates (only meaningful when `readOnlyHint` is `false`) | | `idempotentHint` | `boolean` | `false` | If `true`, repeated calls with the same arguments have no additional effect (only meaningful when `readOnlyHint` is `false`) | | `openWorldHint` | `boolean` | `true` | If `true`, the tool interacts with external entities (for example, web search). If `false`, the tool's domain is closed (for example, a memory tool) | ```typescript theme={null} import { tool } from "@anthropic-ai/claude-agent-sdk"; import { z } from "zod"; const searchTool = tool( "search", "Search the web", { query: z.string() }, async ({ query }) => { return { content: [{ type: "text", text: `Results for: ${query}` }] }; }, { annotations: { readOnlyHint: true, openWorldHint: true } } ); ``` ### `createSdkMcpServer()` Creates an MCP server instance that runs in the same process as your application. ```typescript theme={null} function createSdkMcpServer(options: { name: string; version?: string; tools?: Array<SdkMcpToolDefinition<any>>; }): McpSdkServerConfigWithInstance; ``` #### Parameters | Parameter | Type | Description | | :---------------- | :---------------------------- | :------------------------------------------------------- | | `options.name` | `string` | The name of the MCP server | | `options.version` | `string` | Optional version string | | `options.tools` | `Array<SdkMcpToolDefinition>` | Array of tool definitions created with [`tool()`](#tool) | ### `listSessions()` Discovers and lists past sessions with light metadata. Filter by project directory or list sessions across all projects. ```typescript theme={null} function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>; ``` #### Parameters | Parameter | Type | Default | Description | | :------------------------- | :-------- | :---------- | :--------------------------------------------------------------------------------- | | `options.dir` | `string` | `undefined` | Directory to list sessions for. When omitted, returns sessions across all projects | | `options.limit` | `number` | `undefined` | Maximum number of sessions to return | | `options.includeWorktrees` | `boolean` | `true` | When `dir` is inside a git repository, include sessions from all worktree paths | #### Return type: `SDKSessionInfo` | Property | Type | Description | | :------------- | :-------------------- | :-------------------------------------------------------------------------- | | `sessionId` | `string` | Unique session identifier (UUID) | | `summary` | `string` | Display title: custom title, auto-generated summary, or first prompt | | `lastModified` | `number` | Last modified time in milliseconds since epoch | | `fileSize` | `number \| undefined` | Session file size in bytes. Only populated for local JSONL storage | | `customTitle` | `string \| undefined` | User-set session title (via `/rename`) | | `firstPrompt` | `string \| undefined` | First meaningful user prompt in the session | | `gitBranch` | `string \| undefined` | Git branch at the end of the session | | `cwd` | `string \| undefined` | Working directory for the session | | `tag` | `string \| undefined` | User-set session tag (see [`tagSession()`](#tag-session)) | | `createdAt` | `number \| undefined` | Creation time in milliseconds since epoch, from the first entry's timestamp | #### Example Print the 10 most recent sessions for a project. Results are sorted by `lastModified` descending, so the first item is the newest. Omit `dir` to search across all projects. ```typescript theme={null} import { listSessions } from "@anthropic-ai/claude-agent-sdk"; const sessions = await listSessions({ dir: "/path/to/project", limit: 10 }); for (const session of sessions) { console.log(`${session.summary} (${session.sessionId})`); } ``` ### `getSessionMessages()` Reads user and assistant messages from a past session transcript. ```typescript theme={null} function getSessionMessages( sessionId: string, options?: GetSessionMessagesOptions ): Promise<SessionMessage[]>; ``` #### Parameters | Parameter | Type | Default | Description | | :--------------- | :------- | :---------- | :---------------------------------------------------------------------------- | | `sessionId` | `string` | required | Session UUID to read (see `listSessions()`) | | `options.dir` | `string` | `undefined` | Project directory to find the session in. When omitted, searches all projects | | `options.limit` | `number` | `undefined` | Maximum number of messages to return | | `options.offset` | `number` | `undefined` | Number of messages to skip from the start | #### Return type: `SessionMessage` | Property | Type | Description | | :------------------- | :---------------------- | :-------------------------------------- | | `type` | `"user" \| "assistant"` | Message role | | `uuid` | `string` | Unique message identifier | | `session_id` | `string` | Session this message belongs to | | `message` | `unknown` | Raw message payload from the transcript | | `parent_tool_use_id` | `null` | Reserved | #### Example ```typescript theme={null} import { listSessions, getSessionMessages } from "@anthropic-ai/claude-agent-sdk"; const [latest] = await listSessions({ dir: "/path/to/project", limit: 1 }); if (latest) { const messages = await getSessionMessages(latest.sessionId, { dir: "/path/to/project", limit: 20 }); for (const msg of messages) { console.log(`[${msg.type}] ${msg.uuid}`); } } ``` ### `getSessionInfo()` Reads metadata for a single session by ID without scanning the full project directory. ```typescript theme={null} function getSessionInfo( sessionId: string, options?: GetSessionInfoOptions ): Promise<SDKSessionInfo | undefined>; ``` #### Parameters | Parameter | Type | Default | Description | | :------------ | :------- | :---------- | :--------------------------------------------------------------------- | | `sessionId` | `string` | required | UUID of the session to look up | | `options.dir` | `string` | `undefined` | Project directory path. When omitted, searches all project directories | Returns [`SDKSessionInfo`](#return-type-sdk-session-info), or `undefined` if the session is not found. ### `renameSession()` Renames a session by appending a custom-title entry. Repeated calls are safe; the most recent title wins. ```typescript theme={null} function renameSession( sessionId: string, title: string, options?: SessionMutationOptions ): Promise<void>; ``` #### Parameters | Parameter | Type | Default | Description | | :------------ | :------- | :---------- | :--------------------------------------------------------------------- | | `sessionId` | `string` | required | UUID of the session to rename | | `title` | `string` | required | New title. Must be non-empty after trimming whitespace | | `options.dir` | `string` | `undefined` | Project directory path. When omitted, searches all project directories | ### `tagSession()` Tags a session. Pass `null` to clear the tag. Repeated calls are safe; the most recent tag wins. ```typescript theme={null} function tagSession( sessionId: string, tag: string | null, options?: SessionMutationOptions ): Promise<void>; ``` #### Parameters | Parameter | Type | Default | Description | | :------------ | :--------------- | :---------- | :--------------------------------------------------------------------- | | `sessionId` | `string` | required | UUID of the session to tag | | `tag` | `string \| null` | required | Tag string, or `null` to clear | | `options.dir` | `string` | `undefined` | Project directory path. When omitted, searches all project directories | ## Types ### `Options` Configuration object for the `query()` function. | Property | Type | Default | Description | | :-------------------------------- | :------------------------------------------------------------------------------------------------------- | :------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `abortController` | `AbortController` | `new AbortController()` | Controller for cancelling operations | | `additionalDirectories` | `string[]` | `[]` | Additional directories Claude can access | | `agent` | `string` | `undefined` | Agent name for the main thread. The agent must be defined in the `agents` option or in settings | | `agents` | `Record<string, [`AgentDefinition`](#agent-definition)>` | `undefined` | Programmatically define subagents | | `allowDangerouslySkipPermissions` | `boolean` | `false` | Enable bypassing permissions. Required when using `permissionMode: 'bypassPermissions'` | | `allowedTools` | `string[]` | `[]` | Tools to auto-approve without prompting. This does not restrict Claude to only these tools; unlisted tools fall through to `permissionMode` and `canUseTool`. Use `disallowedTools` to block tools. See [Permissions](/en/agent-sdk/permissions#allow-and-deny-rules) | | `betas` | [`SdkBeta`](#sdk-beta)`[]` | `[]` | Enable beta features | | `canUseTool` | [`CanUseTool`](#can-use-tool) | `undefined` | Custom permission function for tool usage | | `continue` | `boolean` | `false` | Continue the most recent conversation | | `cwd` | `string` | `process.cwd()` | Current working directory | | `debug` | `boolean` | `false` | Enable debug mode for the Claude Code process | | `debugFile` | `string` | `undefined` | Write debug logs to a specific file path. Implicitly enables debug mode | | `disallowedTools` | `string[]` | `[]` | Tools to always deny. Deny rules are checked first and override `allowedTools` and `permissionMode` (including `bypassPermissions`) | | `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `'high'` | Controls how much effort Claude puts into its response. Works with adaptive thinking to guide thinking depth | | `enableFileCheckpointing` | `boolean` | `false` | Enable file change tracking for rewinding. See [File checkpointing](/en/agent-sdk/file-checkpointing) | | `env` | `Record<string, string \| undefined>` | `process.env` | Environment variables. See [Environment variables](../02-Claude-Code-CLI/env-vars-5c624d392b.md) for variables the underlying CLI reads. Set `CLAUDE_AGENT_SDK_CLIENT_APP` to identify your app in the User-Agent header | | `executable` | `'bun' \| 'deno' \| 'node'` | Auto-detected | JavaScript runtime to use | | `executableArgs` | `string[]` | `[]` | Arguments to pass to the executable | | `extraArgs` | `Record<string, string \| null>` | `{}` | Additional arguments | | `fallbackModel` | `string` | `undefined` | Model to use if primary fails | | `forkSession` | `boolean` | `false` | When resuming with `resume`, fork to a new session ID instead of continuing the original session | | `hooks` | `Partial<Record<`[`HookEvent`](#hook-event)`, `[`HookCallbackMatcher`](#hook-callback-matcher)`[]>>` | `{}` | Hook callbacks for events | | `includePartialMessages` | `boolean` | `false` | Include partial message events | | `maxBudgetUsd` | `number` | `undefined` | Stop the query when the client-side cost estimate reaches this USD value. Compared against the same estimate as `total_cost_usd`; see [Track cost and usage](/en/agent-sdk/cost-tracking) for accuracy caveats | | `maxThinkingTokens` | `number` | `undefined` | *Deprecated:* Use `thinking` instead. Maximum tokens for thinking process | | `maxTurns` | `number` | `undefined` | Maximum agentic turns (tool-use round trips) | | `mcpServers` | `Record<string, [`McpServerConfig`](#mcp-server-config)>` | `{}` | MCP server configurations | | `model` | `string` | Default from CLI | Claude model to use | | `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Define output format for agent results. See [Structured outputs](/en/agent-sdk/structured-outputs) for details | | `pathToClaudeCodeExecutable` | `string` | Auto-resolved from bundled native binary | Path to Claude Code executable. Only needed if optional dependencies were skipped during install or your platform isn't in the supported set | | `permissionMode` | [`PermissionMode`](#permission-mode) | `'default'` | Permission mode for the session | | `permissionPromptToolName` | `string` | `undefined` | MCP tool name for permission prompts | | `persistSession` | `boolean` | `true` | When `false`, disables session persistence to disk. Sessions cannot be resumed later | | `plugins` | [`SdkPluginConfig`](#sdk-plugin-config)`[]` | `[]` | Load custom plugins from local paths. See [Plugins](/en/agent-sdk/plugins) for details | | `promptSuggestions` | `boolean` | `false` | Enable prompt suggestions. Emits a `prompt_suggestion` message after each turn with a predicted next user prompt | | `resume` | `string` | `undefined` | Session ID to resume | | `resumeSessionAt` | `string` | `undefined` | Resume session at a specific message UUID | | `sandbox` | [`SandboxSettings`](#sandbox-settings) | `undefined` | Configure sandbox behavior programmatically. See [Sandbox settings](#sandbox-settings) for details | | `sessionId` | `string` | Auto-generated | Use a specific UUID for the session instead of auto-generating one | | `sessionStore` | [`SessionStore`](/en/agent-sdk/session-storage#the-session-store-interface) | `undefined` | Mirror session transcripts to an external backend so any host can resume them. See [Persist sessions to external storage](/en/agent-sdk/session-storage) | | `settingSources` | [`SettingSource`](#setting-source)`[]` | CLI defaults (all sources) | Control which filesystem settings to load. Pass `[]` to disable user, project, and local settings. Managed policy settings load regardless. See [Use Claude Code features](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) | | `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Custom function to spawn the Claude Code process. Use to run Claude Code in VMs, containers, or remote environments | | `stderr` | `(data: string) => void` | `undefined` | Callback for stderr output | | `strictMcpConfig` | `boolean` | `false` | Enforce strict MCP validation | | `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (minimal prompt) | System prompt configuration. Pass a string for custom prompt, or `{ type: 'preset', preset: 'claude_code' }` to use Claude Code's system prompt. When using the preset object form, add `append` to extend it with additional instructions, and set `excludeDynamicSections: true` to move per-session context into the first user message for [better prompt-cache reuse across machines](/en/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) | | `thinking` | [`ThinkingConfig`](#thinking-config) | `{ type: 'adaptive' }` for supported models | Controls Claude's thinking/reasoning behavior. See [`ThinkingConfig`](#thinking-config) for options | | `toolConfig` | [`ToolConfig`](#tool-config) | `undefined` | Configuration for built-in tool behavior. See [`ToolConfig`](#tool-config) for details | | `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Tool configuration. Pass an array of tool names or use the preset to get Claude Code's default tools | ### `Query` object Interface returned by the `query()` function. ```typescript theme={null} interface Query extends AsyncGenerator<SDKMessage, void> { interrupt(): Promise<void>; rewindFiles( userMessageId: string, options?: { dryRun?: boolean } ): Promise<RewindFilesResult>; setPermissionMode(mode: PermissionMode): Promise<void>; setModel(model?: string): Promise<void>; setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>; initializationResult(): Promise<SDKControlInitializeResponse>; supportedCommands(): Promise<SlashCommand[]>; supportedModels(): Promise<ModelInfo[]>; supportedAgents(): Promise<AgentInfo[]>; mcpServerStatus(): Promise<McpServerStatus[]>; accountInfo(): Promise<AccountInfo>; reconnectMcpServer(serverName: string): Promise<void>; toggleMcpServer(serverName: string, enabled: boolean): Promise<void>; setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>; streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>; stopTask(taskId: string): Promise<void>; close(): void; } ``` #### Methods | Method | Description | | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `interrupt()` | Interrupts the query (only available in streaming input mode) | | `rewindFiles(userMessageId, options?)` | Restores files to their state at the specified user message. Pass `{ dryRun: true }` to preview changes. Requires `enableFileCheckpointing: true`. See [File checkpointing](/en/agent-sdk/file-checkpointing) | | `setPermissionMode()` | Changes the permission mode (only available in streaming input mode) | | `setModel()` | Changes the model (only available in streaming input mode) | | `setMaxThinkingTokens()` | *Deprecated:* Use the `thinking` option instead. Changes the maximum thinking tokens | | `initializationResult()` | Returns the full initialization result including supported commands, models, account info, and output style configuration | | `supportedCommands()` | Returns available slash commands | | `supportedModels()` | Returns available models with display info | | `supportedAgents()` | Returns available subagents as [`AgentInfo`](#agent-info)`[]` | | `mcpServerStatus()` | Returns status of connected MCP servers | | `accountInfo()` | Returns account information | | `reconnectMcpServer(serverName)` | Reconnect an MCP server by name | | `toggleMcpServer(serverName, enabled)` | Enable or disable an MCP server by name | | `setMcpServers(servers)` | Dynamically replace the set of MCP servers for this session. Returns info about which servers were added, removed, and any errors | | `streamInput(stream)` | Stream input messages to the query for multi-turn conversations | | `stopTask(taskId)` | Stop a running background task by ID | | `close()` | Close the query and terminate the underlying process. Forcefully ends the query and cleans up all resources | ### `WarmQuery` Handle returned by [`startup()`](#startup). The subprocess is already spawned and initialized, so calling `query()` on this handle writes the prompt directly to a ready process with no startup latency. ```typescript theme={null} interface WarmQuery extends AsyncDisposable { query(prompt: string | AsyncIterable<SDKUserMessage>): Query; close(): void; } ``` #### Methods | Method | Description | | :-------------- | :------------------------------------------------------------------------------------------------------------------------ | | `query(prompt)` | Send a prompt to the pre-warmed subprocess and return a [`Query`](#query-object). Can only be called once per `WarmQuery` | | `close()` | Close the subprocess without sending a prompt. Use this to discard a warm query that is no longer needed | `WarmQuery` implements `AsyncDisposable`, so it can be used with `await using` for automatic cleanup. ### `SDKControlInitializeResponse` Return type of `initializationResult()`. Contains session initialization data. ```typescript theme={null} type SDKControlInitializeResponse = { commands: SlashCommand[]; agents: AgentInfo[]; output_style: string; available_output_styles: string[]; models: ModelInfo[]; account: AccountInfo; fast_mode_state?: "off" | "cooldown" | "on"; }; ``` ### `AgentDefinition` Configuration for a subagent defined programmatically. ```typescript theme={null} type AgentDefinition = { description: string; tools?: string[]; disallowedTools?: string[]; prompt: string; model?: string; mcpServers?: AgentMcpServerSpec[]; skills?: string[]; initialPrompt?: string; maxTurns?: number; background?: boolean; memory?: "user" | "project" | "local"; effort?: "low" | "medium" | "high" | "xhigh" | "max" | number; permissionMode?: PermissionMode; criticalSystemReminder_EXPERIMENTAL?: string; }; ``` | Field | Required | Description | | :------------------------------------ | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `description` | Yes | Natural language description of when to use this agent | | `tools` | No | Array of allowed tool names. If omitted, inherits all tools from parent | | `disallowedTools` | No | Array of tool names to explicitly disallow for this agent | | `prompt` | Yes | The agent's system prompt | | `model` | No | Model override for this agent. Accepts an alias such as `'sonnet'`, `'opus'`, `'haiku'`, `'inherit'`, or a full model ID. If omitted or `'inherit'`, uses the main model | | `mcpServers` | No | MCP server specifications for this agent | | `skills` | No | Array of skill names to preload into the agent context | | `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main thread agent | | `maxTurns` | No | Maximum number of agentic turns (API round-trips) before stopping | | `background` | No | Run this agent as a non-blocking background task when invoked | | `memory` | No | Memory source for this agent: `'user'`, `'project'`, or `'local'` | | `effort` | No | Reasoning effort level for this agent. Accepts a named level or an integer | | `permissionMode` | No | Permission mode for tool execution within this agent. See [`PermissionMode`](#permission-mode) | | `criticalSystemReminder_EXPERIMENTAL` | No | Experimental: Critical reminder added to the system prompt | ### `AgentMcpServerSpec` Specifies MCP servers available to a subagent. Can be a server name (string referencing a server from the parent's `mcpServers` config) or an inline server configuration record mapping server names to configs. ```typescript theme={null} type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>; ``` Where `McpServerConfigForProcessTransport` is `McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig`. ### `SettingSource` Controls which filesystem-based configuration sources the SDK loads settings from. ```typescript theme={null} type SettingSource = "user" | "project" | "local"; ``` | Value | Description | Location | | :---------- | :------------------------------------------- | :---------------------------- | | `'user'` | Global user settings | `~/.claude/settings.json` | | `'project'` | Shared project settings (version controlled) | `.claude/settings.json` | | `'local'` | Local project settings (gitignored) | `.claude/settings.local.json` | #### Default behavior When `settingSources` is omitted or `undefined`, `query()` loads the same filesystem settings as the Claude Code CLI: user, project, and local. Managed policy settings are loaded in all cases. See [What settingSources does not control](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) for inputs that are read regardless of this option, and how to disable them. #### Why use settingSources **Disable filesystem settings:** ```typescript theme={null} // Do not load user, project, or local settings from disk const result = query({ prompt: "Analyze this code", options: { settingSources: [] } }); ``` **Load all filesystem settings explicitly:** ```typescript theme={null} const result = query({ prompt: "Analyze this code", options: { settingSources: ["user", "project", "local"] // Load all settings } }); ``` **Load only specific setting sources:** ```typescript theme={null} // Load only project settings, ignore user and local const result = query({ prompt: "Run CI checks", options: { settingSources: ["project"] // Only .claude/settings.json } }); ``` **Testing and CI environments:** ```typescript theme={null} // Ensure consistent behavior in CI by excluding local settings const result = query({ prompt: "Run tests", options: { settingSources: ["project"], // Only team-shared settings permissionMode: "bypassPermissions" } }); ``` **SDK-only applications:** ```typescript theme={null} // Define everything programmatically. // Pass [] to opt out of filesystem setting sources. const result = query({ prompt: "Review this PR", options: { settingSources: [], agents: { /* ... */ }, mcpServers: { /* ... */ }, allowedTools: ["Read", "Grep", "Glob"] } }); ``` **Loading CLAUDE.md project instructions:** ```typescript theme={null} // Load project settings to include CLAUDE.md files const result = query({ prompt: "Add a new feature following project conventions", options: { systemPrompt: { type: "preset", preset: "claude_code" // Use Claude Code's system prompt }, settingSources: ["project"], // Loads CLAUDE.md from project directory allowedTools: ["Read", "Write", "Edit"] } }); ``` #### Settings precedence When multiple sources are loaded, settings are merged with this precedence (highest to lowest): 1. Local settings (`.claude/settings.local.json`) 2. Project settings (`.claude/settings.json`) 3. User settings (`~/.claude/settings.json`) Programmatic options such as `agents` and `allowedTools` override user, project, and local filesystem settings. Managed policy settings take precedence over programmatic options. ### `PermissionMode` ```typescript theme={null} type PermissionMode = | "default" // Standard permission behavior | "acceptEdits" // Auto-accept file edits | "bypassPermissions" // Bypass all permission checks | "plan" // Planning mode - no execution | "dontAsk" // Don't prompt for permissions, deny if not pre-approved | "auto"; // Use a model classifier to approve or deny each tool call ``` ### `CanUseTool` Custom permission function type for controlling tool usage. ```typescript theme={null} type CanUseTool = ( toolName: string, input: Record<string, unknown>, options: { signal: AbortSignal; suggestions?: PermissionUpdate[]; blockedPath?: string; decisionReason?: string; toolUseID: string; agentID?: string; } ) => Promise<PermissionResult>; ``` | Option | Type | Description | | :--------------- | :------------------------------------------- | :--------------------------------------------------------------------------- | | `signal` | `AbortSignal` | Signaled if the operation should be aborted | | `suggestions` | [`PermissionUpdate`](#permission-update)`[]` | Suggested permission updates so the user is not prompted again for this tool | | `blockedPath` | `string` | The file path that triggered the permission request, if applicable | | `decisionReason` | `string` | Explains why this permission request was triggered | | `toolUseID` | `string` | Unique identifier for this specific tool call within the assistant message | | `agentID` | `string` | If running within a sub-agent, the sub-agent's ID | ### `PermissionResult` Result of a permission check. ```typescript theme={null} type PermissionResult = | { behavior: "allow"; updatedInput?: Record<string, unknown>; updatedPermissions?: PermissionUpdate[]; toolUseID?: string; } | { behavior: "deny"; message: string; interrupt?: boolean; toolUseID?: string; }; ``` ### `ToolConfig` Configuration for built-in tool behavior. ```typescript theme={null} type ToolConfig = { askUserQuestion?: { previewFormat?: "markdown" | "html"; }; }; ``` | Field | Type | Description | | :------------------------------ | :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `askUserQuestion.previewFormat` | `'markdown' \| 'html'` | Opts into the `preview` field on [`AskUserQuestion`](/en/agent-sdk/user-input#question-format) options and sets its content format. When unset, Claude does not emit previews | ### `McpServerConfig` Configuration for MCP servers. ```typescript theme={null} type McpServerConfig = | McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfigWithInstance; ``` #### `McpStdioServerConfig` ```typescript theme={null} type McpStdioServerConfig = { type?: "stdio"; command: string; args?: string[]; env?: Record<string, string>; }; ``` #### `McpSSEServerConfig` ```typescript theme={null} type McpSSEServerConfig = { type: "sse"; url: string; headers?: Record<string, string>; }; ``` #### `McpHttpServerConfig` ```typescript theme={null} type McpHttpServerConfig = { type: "http"; url: string; headers?: Record<string, string>; }; ``` #### `McpSdkServerConfigWithInstance` ```typescript theme={null} type McpSdkServerConfigWithInstance = { type: "sdk"; name: string; instance: McpServer; }; ``` #### `McpClaudeAIProxyServerConfig` ```typescript theme={null} type McpClaudeAIProxyServerConfig = { type: "claudeai-proxy"; url: string; id: string; }; ``` ### `SdkPluginConfig` Configuration for loading plugins in the SDK. ```typescript theme={null} type SdkPluginConfig = { type: "local"; path: string; }; ``` | Field | Type | Description | | :----- | :-------- | :--------------------------------------------------------- | | `type` | `'local'` | Must be `'local'` (only local plugins currently supported) | | `path` | `string` | Absolute or relative path to the plugin directory | **Example:** ```typescript theme={null} plugins: [ { type: "local", path: "./my-plugin" }, { type: "local", path: "/absolute/path/to/plugin" } ]; ``` For complete information on creating and using plugins, see [Plugins](/en/agent-sdk/plugins). ## Message Types ### `SDKMessage` Union type of all possible messages returned by the query. ```typescript theme={null} type SDKMessage = | SDKAssistantMessage | SDKUserMessage | SDKUserMessageReplay | SDKResultMessage | SDKSystemMessage | SDKPartialAssistantMessage | SDKCompactBoundaryMessage | SDKStatusMessage | SDKLocalCommandOutputMessage | SDKHookStartedMessage | SDKHookProgressMessage | SDKHookResponseMessage | SDKPluginInstallMessage | SDKToolProgressMessage | SDKAuthStatusMessage | SDKTaskNotificationMessage | SDKTaskStartedMessage | SDKTaskProgressMessage | SDKTaskUpdatedMessage | SDKFilesPersistedEvent | SDKToolUseSummaryMessage | SDKRateLimitEvent | SDKPromptSuggestionMessage; ``` ### `SDKAssistantMessage` Assistant response message. ```typescript theme={null} type SDKAssistantMessage = { type: "assistant"; uuid: UUID; session_id: string; message: BetaMessage; // From Anthropic SDK parent_tool_use_id: string | null; error?: SDKAssistantMessageError; }; ``` The `message` field is a [`BetaMessage`](../04-API-Reference/Other/api-messages-create-07971e1cdf.md) from the Anthropic SDK. It includes fields like `id`, `content`, `model`, `stop_reason`, and `usage`. `SDKAssistantMessageError` is one of: `'authentication_failed'`, `'billing_error'`, `'rate_limit'`, `'invalid_request'`, `'server_error'`, `'max_output_tokens'`, or `'unknown'`. ### `SDKUserMessage` User input message. ```typescript theme={null} type SDKUserMessage = { type: "user"; uuid?: UUID; session_id: string; message: MessageParam; // From Anthropic SDK parent_tool_use_id: string | null; isSynthetic?: boolean; shouldQuery?: boolean; tool_use_result?: unknown; }; ``` Set `shouldQuery` to `false` to append the message to the transcript without triggering an assistant turn. The message is held and merged into the next user message that does trigger a turn. Use this to inject context, such as the output of a command you ran out of band, without spending a model call on it. ### `SDKUserMessageReplay` Replayed user message with required UUID. ```typescript theme={null} type SDKUserMessageReplay = { type: "user"; uuid: UUID; session_id: string; message: MessageParam; parent_tool_use_id: string | null; isSynthetic?: boolean; tool_use_result?: unknown; isReplay: true; }; ``` ### `SDKResultMessage` Final result message. ```typescript theme={null} type SDKResultMessage = | { type: "result"; subtype: "success"; uuid: UUID; session_id: string; duration_ms: number; duration_api_ms: number; is_error: boolean; num_turns: number; result: string; stop_reason: string | null; total_cost_usd: number; usage: NonNullableUsage; modelUsage: { [modelName: string]: ModelUsage }; permission_denials: SDKPermissionDenial[]; structured_output?: unknown; deferred_tool_use?: { id: string; name: string; input: Record<string, unknown> }; } | { type: "result"; subtype: | "error_max_turns" | "error_during_execution" | "error_max_budget_usd" | "error_max_structured_output_retries"; uuid: UUID; session_id: string; duration_ms: number; duration_api_ms: number; is_error: boolean; num_turns: number; stop_reason: string | null; total_cost_usd: number; usage: NonNullableUsage; modelUsage: { [modelName: string]: ModelUsage }; permission_denials: SDKPermissionDenial[]; errors: string[]; }; ``` When a `PreToolUse` hook returns `permissionDecision: "defer"`, the result has `stop_reason: "tool_deferred"` and `deferred_tool_use` carries the pending tool's `id`, `name`, and `input`. Read this field to surface the request in your own UI, then resume with the same `session_id` to continue. See [Defer a tool call for later](/en/hooks#defer-a-tool-call-for-later) for the full round trip. ### `SDKSystemMessage` System initialization message. ```typescript theme={null} type SDKSystemMessage = { type: "system"; subtype: "init"; uuid: UUID; session_id: string; agents?: string[]; apiKeySource: ApiKeySource; betas?: string[]; claude_code_version: string; cwd: string; tools: string[]; mcp_servers: { name: string; status: string; }[]; model: string; permissionMode: PermissionMode; slash_commands: string[]; output_style: string; skills: string[]; plugins: { name: string; path: string }[]; }; ``` ### `SDKPartialAssistantMessage` Streaming partial message (only when `includePartialMessages` is true). ```typescript theme={null} type SDKPartialAssistantMessage = { type: "stream_event"; event: BetaRawMessageStreamEvent; // From Anthropic SDK parent_tool_use_id: string | null; uuid: UUID; session_id: string; }; ``` ### `SDKCompactBoundaryMessage` Message indicating a conversation compaction boundary. ```typescript theme={null} type SDKCompactBoundaryMessage = { type: "system"; subtype: "compact_boundary"; uuid: UUID; session_id: string; compact_metadata: { trigger: "manual" | "auto"; pre_tokens: number; }; }; ``` ### `SDKPluginInstallMessage` Plugin installation progress event. Emitted when [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](../02-Claude-Code-CLI/env-vars-5c624d392b.md) is set, so your Agent SDK application can track marketplace plugin installation before the first turn. The `started` and `completed` statuses bracket the overall install. The `installed` and `failed` statuses report individual marketplaces and include `name`. ```typescript theme={null} type SDKPluginInstallMessage = { type: "system"; subtype: "plugin_install"; status: "started" | "installed" | "failed" | "completed"; name?: string; error?: string; uuid: UUID; session_id: string; }; ``` ### `SDKPermissionDenial` Information about a denied tool use. ```typescript theme={null} type SDKPermissionDenial = { tool_name: string; tool_use_id: string; tool_input: Record<string, unknown>; }; ``` ## Hook Types For a comprehensive guide on using hooks with examples and common patterns, see the [Hooks guide](/en/agent-sdk/hooks). ### `HookEvent` Available hook events. ```typescript theme={null} type HookEvent = | "PreToolUse" | "PostToolUse" | "PostToolUseFailure" | "PostToolBatch" | "Notification" | "UserPromptSubmit" | "SessionStart" | "SessionEnd" | "Stop" | "SubagentStart" | "SubagentStop" | "PreCompact" | "PermissionRequest" | "Setup" | "TeammateIdle" | "TaskCompleted" | "ConfigChange" | "WorktreeCreate" | "WorktreeRemove"; ``` ### `HookCallback` Hook callback function type. ```typescript theme={null} type HookCallback = ( input: HookInput, // Union of all hook input types toolUseID: string | undefined, options: { signal: AbortSignal } ) => Promise<HookJSONOutput>; ``` ### `HookCallbackMatcher` Hook configuration with optional matcher. ```typescript theme={null} interface HookCallbackMatcher { matcher?: string; hooks: HookCallback[]; timeout?: number; // Timeout in seconds for all hooks in this matcher } ``` ### `HookInput` Union type of all hook input types. ```typescript theme={null} type HookInput = | PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | PostToolBatchHookInput | NotificationHookInput | UserPromptSubmitHookInput | SessionStartHookInput | SessionEndHookInput | StopHookInput | SubagentStartHookInput | SubagentStopHookInput | PreCompactHookInput | PermissionRequestHookInput | SetupHookInput | TeammateIdleHookInput | TaskCompletedHookInput | ConfigChangeHookInput | WorktreeCreateHookInput | WorktreeRemoveHookInput; ``` ### `BaseHookInput` Base interface that all hook input types extend. ```typescript theme={null} type BaseHookInput = { session_id: string; transcript_path: string; cwd: string; permission_mode?: string; agent_id?: string; agent_type?: string; }; ``` #### `PreToolUseHookInput` ```typescript theme={null} type PreToolUseHookInput = BaseHookInput & { hook_event_name: "PreToolUse"; tool_name: string; tool_input: unknown; tool_use_id: string; }; ``` #### `PostToolUseHookInput` ```typescript theme={null} type PostToolUseHookInput = BaseHookInput & { hook_event_name: "PostToolUse"; tool_name: string; tool_input: unknown; tool_response: unknown; tool_use_id: string; duration_ms?: number; }; ``` #### `PostToolUseFailureHookInput` ```typescript theme={null} type PostToolUseFailureHookInput = BaseHookInput & { hook_event_name: "PostToolUseFailure"; tool_name: string; tool_input: unknown; tool_use_id: string; error: string; is_interrupt?: boolean; duration_ms?: number; }; ``` #### `PostToolBatchHookInput` Fires once after every tool call in a batch has resolved, before the next model request. `tool_response` carries the serialized `tool_result` content the model sees; the shape differs from `PostToolUseHookInput`'s structured `Output` object. ```typescript theme={null} type PostToolBatchHookInput = BaseHookInput & { hook_event_name: "PostToolBatch"; tool_calls: PostToolBatchToolCall[]; }; type PostToolBatchToolCall = { tool_name: string; tool_input: unknown; tool_use_id: string; tool_response?: unknown; }; ``` #### `NotificationHookInput` ```typescript theme={null} type NotificationHookInput = BaseHookInput & { hook_event_name: "Notification"; message: string; title?: string; notification_type: string; }; ``` #### `UserPromptSubmitHookInput` ```typescript theme={null} type UserPromptSubmitHookInput = BaseHookInput & { hook_event_name: "UserPromptSubmit"; prompt: string; }; ``` #### `SessionStartHookInput` ```typescript theme={null} type SessionStartHookInput = BaseHookInput & { hook_event_name: "SessionStart"; source: "startup" | "resume" | "clear" | "compact"; agent_type?: string; model?: string; }; ``` #### `SessionEndHookInput` ```typescript theme={null} type SessionEndHookInput = BaseHookInput & { hook_event_name: "SessionEnd"; reason: ExitReason; // String from EXIT_REASONS array }; ``` #### `StopHookInput` ```typescript theme={null} type StopHookInput = BaseHookInput & { hook_event_name: "Stop"; stop_hook_active: boolean; last_assistant_message?: string; }; ``` #### `SubagentStartHookInput` ```typescript theme={null} type SubagentStartHookInput = BaseHookInput & { hook_event_name: "SubagentStart"; agent_id: string; agent_type: string; }; ``` #### `SubagentStopHookInput` ```typescript theme={null} type SubagentStopHookInput = BaseHookInput & { hook_event_name: "SubagentStop"; stop_hook_active: boolean; agent_id: string; agent_transcript_path: string; agent_type: string; last_assistant_message?: string; }; ``` #### `PreCompactHookInput` ```typescript theme={null} type PreCompactHookInput = BaseHookInput & { hook_event_name: "PreCompact"; trigger: "manual" | "auto"; custom_instructions: string | null; }; ``` #### `PermissionRequestHookInput` ```typescript theme={null} type PermissionRequestHookInput = BaseHookInput & { hook_event_name: "PermissionRequest"; tool_name: string; tool_input: unknown; permission_suggestions?: PermissionUpdate[]; }; ``` #### `SetupHookInput` ```typescript theme={null} type SetupHookInput = BaseHookInput & { hook_event_name: "Setup"; trigger: "init" | "maintenance"; }; ``` #### `TeammateIdleHookInput` ```typescript theme={null} type TeammateIdleHookInput = BaseHookInput & { hook_event_name: "TeammateIdle"; teammate_name: string; team_name: string; }; ``` #### `TaskCompletedHookInput` ```typescript theme={null} type TaskCompletedHookInput = BaseHookInput & { hook_event_name: "TaskCompleted"; task_id: string; task_subject: string; task_description?: string; teammate_name?: string; team_name?: string; }; ``` #### `ConfigChangeHookInput` ```typescript theme={null} type ConfigChangeHookInput = BaseHookInput & { hook_event_name: "ConfigChange"; source: | "user_settings" | "project_settings" | "local_settings" | "policy_settings" | "skills"; file_path?: string; }; ``` #### `WorktreeCreateHookInput` ```typescript theme={null} type WorktreeCreateHookInput = BaseHookInput & { hook_event_name: "WorktreeCreate"; name: string; }; ``` #### `WorktreeRemoveHookInput` ```typescript theme={null} type WorktreeRemoveHookInput = BaseHookInput & { hook_event_name: "WorktreeRemove"; worktree_path: string; }; ``` ### `HookJSONOutput` Hook return value. ```typescript theme={null} type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput; ``` #### `AsyncHookJSONOutput` ```typescript theme={null} type AsyncHookJSONOutput = { async: true; asyncTimeout?: number; }; ``` #### `SyncHookJSONOutput` ```typescript theme={null} type SyncHookJSONOutput = { continue?: boolean; suppressOutput?: boolean; stopReason?: string; decision?: "approve" | "block"; systemMessage?: string; reason?: string; hookSpecificOutput?: | { hookEventName: "PreToolUse"; permissionDecision?: "allow" | "deny" | "ask" | "defer"; permissionDecisionReason?: string; updatedInput?: Record<string, unknown>; additionalContext?: string; } | { hookEventName: "UserPromptSubmit"; additionalContext?: string; } | { hookEventName: "SessionStart"; additionalContext?: string; } | { hookEventName: "Setup"; additionalContext?: string; } | { hookEventName: "SubagentStart"; additionalContext?: string; } | { hookEventName: "PostToolUse"; additionalContext?: string; updatedMCPToolOutput?: unknown; } | { hookEventName: "PostToolUseFailure"; additionalContext?: string; } | { hookEventName: "PostToolBatch"; additionalContext?: string; } | { hookEventName: "Notification"; additionalContext?: string; } | { hookEventName: "PermissionRequest"; decision: | { behavior: "allow"; updatedInput?: Record<string, unknown>; updatedPermissions?: PermissionUpdate[]; } | { behavior: "deny"; message?: string; interrupt?: boolean; }; }; }; ``` ## Tool Input Types Documentation of input schemas for all built-in Claude Code tools. These types are exported from `@anthropic-ai/claude-agent-sdk` and can be used for type-safe tool interactions. ### `ToolInputSchemas` Union of all tool input types, exported from `@anthropic-ai/claude-agent-sdk`. ```typescript theme={null} type ToolInputSchemas = | AgentInput | AskUserQuestionInput | BashInput | TaskOutputInput | EnterWorktreeInput | ExitPlanModeInput | FileEditInput | FileReadInput | FileWriteInput | GlobInput | GrepInput | ListMcpResourcesInput | McpInput | MonitorInput | NotebookEditInput | ReadMcpResourceInput | SubscribeMcpResourceInput | SubscribePollingInput | TaskStopInput | TodoWriteInput | UnsubscribeMcpResourceInput | UnsubscribePollingInput | WebFetchInput | WebSearchInput; ``` ### Agent **Tool name:** `Agent` (previously `Task`, which is still accepted as an alias) ```typescript theme={null} type AgentInput = { description: string; prompt: string; subagent_type: string; model?: "sonnet" | "opus" | "haiku"; resume?: string; run_in_background?: boolean; max_turns?: number; name?: string; team_name?: string; mode?: "acceptEdits" | "bypassPermissions" | "default" | "dontAsk" | "plan"; isolation?: "worktree"; }; ``` Launches a new agent to handle complex, multi-step tasks autonomously. ### AskUserQuestion **Tool name:** `AskUserQuestion` ```typescript theme={null} type AskUserQuestionInput = { questions: Array<{ question: string; header: string; options: Array<{ label: string; description: string; preview?: string }>; multiSelect: boolean; }>; }; ``` Asks the user clarifying questions during execution. See [Handle approvals and user input](/en/agent-sdk/user-input#handle-clarifying-questions) for usage details. ### Bash **Tool name:** `Bash` ```typescript theme={null} type BashInput = { command: string; timeout?: number; description?: string; run_in_background?: boolean; dangerouslyDisableSandbox?: boolean; }; ``` Executes bash commands in a persistent shell session with optional timeout and background execution. ### Monitor **Tool name:** `Monitor` ```typescript theme={null} type MonitorInput = { command: string; description: string; timeout_ms?: number; persistent?: boolean; }; ``` Runs a background script and delivers each stdout line to Claude as an event so it can react without polling. Set `persistent: true` for session-length watches such as log tails. Monitor follows the same permission rules as Bash. See the [Monitor tool reference](/en/tools-reference#monitor-tool) for behavior and provider availability. ### TaskOutput **Tool name:** `TaskOutput` ```typescript theme={null} type TaskOutputInput = { task_id: string; block: boolean; timeout: number; }; ``` Retrieves output from a running or completed background task. ### Edit **Tool name:** `Edit` ```typescript theme={null} type FileEditInput = { file_path: string; old_string: string; new_string: string; replace_all?: boolean; }; ``` Performs exact string replacements in files. ### Read **Tool name:** `Read` ```typescript theme={null} type FileReadInput = { file_path: string; offset?: number; limit?: number; pages?: string; }; ``` Reads files from the local filesystem, including text, images, PDFs, and Jupyter notebooks. Use `pages` for PDF page ranges (for example, `"1-5"`). ### Write **Tool name:** `Write` ```typescript theme={null} type FileWriteInput = { file_path: string; content: string; }; ``` Writes a file to the local filesystem, overwriting if it exists. ### Glob **Tool name:** `Glob` ```typescript theme={null} type GlobInput = { pattern: string; path?: string; }; ``` Fast file pattern matching that works with any codebase size. ### Grep **Tool name:** `Grep` ```typescript theme={null} type GrepInput = { pattern: string; path?: string; glob?: string; type?: string; output_mode?: "content" | "files_with_matches" | "count"; "-i"?: boolean; "-n"?: boolean; "-B"?: number; "-A"?: number; "-C"?: number; context?: number; head_limit?: number; offset?: number; multiline?: boolean; }; ``` Powerful search tool built on ripgrep with regex support. ### TaskStop **Tool name:** `TaskStop` ```typescript theme={null} type TaskStopInput = { task_id?: string; shell_id?: string; // Deprecated: use task_id }; ``` Stops a running background task or shell by ID. ### NotebookEdit **Tool name:** `NotebookEdit` ```typescript theme={null} type NotebookEditInput = { notebook_path: string; cell_id?: string; new_source: string; cell_type?: "code" | "markdown"; edit_mode?: "replace" | "insert" | "delete"; }; ``` Edits cells in Jupyter notebook files. ### WebFetch **Tool name:** `WebFetch` ```typescript theme={null} type WebFetchInput = { url: string; prompt: string; }; ``` Fetches content from a URL and processes it with an AI model. ### WebSearch **Tool name:** `WebSearch` ```typescript theme={null} type WebSearchInput = { query: string; allowed_domains?: string[]; blocked_domains?: string[]; }; ``` Searches the web and returns formatted results. ### TodoWrite **Tool name:** `TodoWrite` ```typescript theme={null} type TodoWriteInput = { todos: Array<{ content: string; status: "pending" | "in_progress" | "completed"; activeForm: string; }>; }; ``` Creates and manages a structured task list for tracking progress. ### ExitPlanMode **Tool name:** `ExitPlanMode` ```typescript theme={null} type ExitPlanModeInput = { allowedPrompts?: Array<{ tool: "Bash"; prompt: string; }>; }; ``` Exits planning mode. Optionally specifies prompt-based permissions needed to implement the plan. ### ListMcpResources **Tool name:** `ListMcpResources` ```typescript theme={null} type ListMcpResourcesInput = { server?: string; }; ``` Lists available MCP resources from connected servers. ### ReadMcpResource **Tool name:** `ReadMcpResource` ```typescript theme={null} type ReadMcpResourceInput = { server: string; uri: string; }; ``` Reads a specific MCP resource from a server. ### EnterWorktree **Tool name:** `EnterWorktree` ```typescript theme={null} type EnterWorktreeInput = { name?: string; path?: string; }; ``` Creates and enters a temporary git worktree for isolated work. Pass `path` to switch into an existing worktree of the current repository instead of creating a new one. `name` and `path` are mutually exclusive. ## Tool Output Types Documentation of output schemas for all built-in Claude Code tools. These types are exported from `@anthropic-ai/claude-agent-sdk` and represent the actual response data returned by each tool. ### `ToolOutputSchemas` Union of all tool output types. ```typescript theme={null} type ToolOutputSchemas = | AgentOutput | AskUserQuestionOutput | BashOutput | EnterWorktreeOutput | ExitPlanModeOutput | FileEditOutput | FileReadOutput | FileWriteOutput | GlobOutput | GrepOutput | ListMcpResourcesOutput | MonitorOutput | NotebookEditOutput | ReadMcpResourceOutput | TaskStopOutput | TodoWriteOutput | WebFetchOutput | WebSearchOutput; ``` ### Agent **Tool name:** `Agent` (previously `Task`, which is still accepted as an alias) ```typescript theme={null} type AgentOutput = | { status: "completed"; agentId: string; content: Array<{ type: "text"; text: string }>; totalToolUseCount: number; totalDurationMs: number; totalTokens: number; usage: { input_tokens: number; output_tokens: number; cache_creation_input_tokens: number | null; cache_read_input_tokens: number | null; server_tool_use: { web_search_requests: number; web_fetch_requests: number; } | null; service_tier: ("standard" | "priority" | "batch") | null; cache_creation: { ephemeral_1h_input_tokens: number; ephemeral_5m_input_tokens: number; } | null; }; prompt: string; } | { status: "async_launched"; agentId: string; description: string; prompt: string; outputFile: string; canReadOutputFile?: boolean; } | { status: "sub_agent_entered"; description: string; message: string; }; ``` Returns the result from the subagent. Discriminated on the `status` field: `"completed"` for finished tasks, `"async_launched"` for background tasks, and `"sub_agent_entered"` for interactive subagents. ### AskUserQuestion **Tool name:** `AskUserQuestion` ```typescript theme={null} type AskUserQuestionOutput = { questions: Array<{ question: string; header: string; options: Array<{ label: string; description: string; preview?: string }>; multiSelect: boolean; }>; answers: Record<string, string>; }; ``` Returns the questions asked and the user's answers. ### Bash **Tool name:** `Bash` ```typescript theme={null} type BashOutput = { stdout: string; stderr: string; rawOutputPath?: string; interrupted: boolean; isImage?: boolean; backgroundTaskId?: string; backgroundedByUser?: boolean; dangerouslyDisableSandbox?: boolean; returnCodeInterpretation?: string; structuredContent?: unknown[]; persistedOutputPath?: string; persistedOutputSize?: number; }; ``` Returns command output with stdout/stderr split. Background commands include a `backgroundTaskId`. ### Monitor **Tool name:** `Monitor` ```typescript theme={null} type MonitorOutput = { taskId: string; timeoutMs: number; persistent?: boolean; }; ``` Returns the background task ID for the running monitor. Use this ID with `TaskStop` to cancel the watch early. ### Edit **Tool name:** `Edit` ```typescript theme={null} type FileEditOutput = { filePath: string; oldString: string; newString: string; originalFile: string; structuredPatch: Array<{ oldStart: number; oldLines: number; newStart: number; newLines: number; lines: string[]; }>; userModified: boolean; replaceAll: boolean; gitDiff?: { filename: string; status: "modified" | "added"; additions: number; deletions: number; changes: number; patch: string; }; }; ``` Returns the structured diff of the edit operation. ### Read **Tool name:** `Read` ```typescript theme={null} type FileReadOutput = | { type: "text"; file: { filePath: string; content: string; numLines: number; startLine: number; totalLines: number; }; } | { type: "image"; file: { base64: string; type: "image/jpeg" | "image/png" | "image/gif" | "image/webp"; originalSize: number; dimensions?: { originalWidth?: number; originalHeight?: number; displayWidth?: number; displayHeight?: number; }; }; } | { type: "notebook"; file: { filePath: string; cells: unknown[]; }; } | { type: "pdf"; file: { filePath: string; base64: string; originalSize: number; }; } | { type: "parts"; file: { filePath: string; originalSize: number; count: number; outputDir: string; }; }; ``` Returns file contents in a format appropriate to the file type. Discriminated on the `type` field. ### Write **Tool name:** `Write` ```typescript theme={null} type FileWriteOutput = { type: "create" | "update"; filePath: string; content: string; structuredPatch: Array<{ oldStart: number; oldLines: number; newStart: number; newLines: number; lines: string[]; }>; originalFile: string | null; gitDiff?: { filename: string; status: "modified" | "added"; additions: number; deletions: number; changes: number; patch: string; }; }; ``` Returns the write result with structured diff information. ### Glob **Tool name:** `Glob` ```typescript theme={null} type GlobOutput = { durationMs: number; numFiles: number; filenames: string[]; truncated: boolean; }; ``` Returns file paths matching the glob pattern, sorted by modification time. ### Grep **Tool name:** `Grep` ```typescript theme={null} type GrepOutput = { mode?: "content" | "files_with_matches" | "count"; numFiles: number; filenames: string[]; content?: string; numLines?: number; numMatches?: number; appliedLimit?: number; appliedOffset?: number; }; ``` Returns search results. The shape varies by `mode`: file list, content with matches, or match counts. ### TaskStop **Tool name:** `TaskStop` ```typescript theme={null} type TaskStopOutput = { message: string; task_id: string; task_type: string; command?: string; }; ``` Returns confirmation after stopping the background task. ### NotebookEdit **Tool name:** `NotebookEdit` ```typescript theme={null} type NotebookEditOutput = { new_source: string; cell_id?: string; cell_type: "code" | "markdown"; language: string; edit_mode: string; error?: string; notebook_path: string; original_file: string; updated_file: string; }; ``` Returns the result of the notebook edit with original and updated file contents. ### WebFetch **Tool name:** `WebFetch` ```typescript theme={null} type WebFetchOutput = { bytes: number; code: number; codeText: string; result: string; durationMs: number; url: string; }; ``` Returns the fetched content with HTTP status and metadata. ### WebSearch **Tool name:** `WebSearch` ```typescript theme={null} type WebSearchOutput = { query: string; results: Array< | { tool_use_id: string; content: Array<{ title: string; url: string }>; } | string >; durationSeconds: number; }; ``` Returns search results from the web. ### TodoWrite **Tool name:** `TodoWrite` ```typescript theme={null} type TodoWriteOutput = { oldTodos: Array<{ content: string; status: "pending" | "in_progress" | "completed"; activeForm: string; }>; newTodos: Array<{ content: string; status: "pending" | "in_progress" | "completed"; activeForm: string; }>; }; ``` Returns the previous and updated task lists. ### ExitPlanMode **Tool name:** `ExitPlanMode` ```typescript theme={null} type ExitPlanModeOutput = { plan: string | null; isAgent: boolean; filePath?: string; hasTaskTool?: boolean; awaitingLeaderApproval?: boolean; requestId?: string; }; ``` Returns the plan state after exiting plan mode. ### ListMcpResources **Tool name:** `ListMcpResources` ```typescript theme={null} type ListMcpResourcesOutput = Array<{ uri: string; name: string; mimeType?: string; description?: string; server: string; }>; ``` Returns an array of available MCP resources. ### ReadMcpResource **Tool name:** `ReadMcpResource` ```typescript theme={null} type ReadMcpResourceOutput = { contents: Array<{ uri: string; mimeType?: string; text?: string; }>; }; ``` Returns the contents of the requested MCP resource. ### EnterWorktree **Tool name:** `EnterWorktree` ```typescript theme={null} type EnterWorktreeOutput = { worktreePath: string; worktreeBranch?: string; message: string; }; ``` Returns information about the git worktree. ## Permission Types ### `PermissionUpdate` Operations for updating permissions. ```typescript theme={null} type PermissionUpdate = | { type: "addRules"; rules: PermissionRuleValue[]; behavior: PermissionBehavior; destination: PermissionUpdateDestination; } | { type: "replaceRules"; rules: PermissionRuleValue[]; behavior: PermissionBehavior; destination: PermissionUpdateDestination; } | { type: "removeRules"; rules: PermissionRuleValue[]; behavior: PermissionBehavior; destination: PermissionUpdateDestination; } | { type: "setMode"; mode: PermissionMode; destination: PermissionUpdateDestination; } | { type: "addDirectories"; directories: string[]; destination: PermissionUpdateDestination; } | { type: "removeDirectories"; directories: string[]; destination: PermissionUpdateDestination; }; ``` ### `PermissionBehavior` ```typescript theme={null} type PermissionBehavior = "allow" | "deny" | "ask"; ``` ### `PermissionUpdateDestination` ```typescript theme={null} type PermissionUpdateDestination = | "userSettings" // Global user settings | "projectSettings" // Per-directory project settings | "localSettings" // Gitignored local settings | "session" // Current session only | "cliArg"; // CLI argument ``` ### `PermissionRuleValue` ```typescript theme={null} type PermissionRuleValue = { toolName: string; ruleContent?: string; }; ``` ## Other Types ### `ApiKeySource` ```typescript theme={null} type ApiKeySource = "user" | "project" | "org" | "temporary" | "oauth"; ``` ### `SdkBeta` Available beta features that can be enabled via the `betas` option. See [Beta headers](https://platform.claude.com/docs/en/api/beta-headers) for more information. ```typescript theme={null} type SdkBeta = "context-1m-2025-08-07"; ``` <Warning> The `context-1m-2025-08-07` beta is retired as of April 30, 2026. Passing this value with Claude Sonnet 4.5 or Sonnet 4 has no effect, and requests that exceed the standard 200k-token context window return an error. To use a 1M-token context window, migrate to [Claude Sonnet 4.6, Claude Opus 4.6, or Claude Opus 4.7](../20-Models/about-claude-models-overview-2bbf09ff82.md), which include 1M context at standard pricing with no beta header required. </Warning> ### `SlashCommand` Information about an available slash command. ```typescript theme={null} type SlashCommand = { name: string; description: string; argumentHint: string; aliases?: string[]; }; ``` ### `ModelInfo` Information about an available model. ```typescript theme={null} type ModelInfo = { value: string; displayName: string; description: string; supportsEffort?: boolean; supportedEffortLevels?: ("low" | "medium" | "high" | "xhigh" | "max")[]; supportsAdaptiveThinking?: boolean; supportsFastMode?: boolean; }; ``` ### `AgentInfo` Information about an available subagent that can be invoked via the Agent tool. ```typescript theme={null} type AgentInfo = { name: string; description: string; model?: string; }; ``` | Field | Type | Description | | :------------ | :-------------------- | :------------------------------------------------------------------- | | `name` | `string` | Agent type identifier (e.g., `"Explore"`, `"general-purpose"`) | | `description` | `string` | Description of when to use this agent | | `model` | `string \| undefined` | Model alias this agent uses. If omitted, inherits the parent's model | ### `McpServerStatus` Status of a connected MCP server. ```typescript theme={null} type McpServerStatus = { name: string; status: "connected" | "failed" | "needs-auth" | "pending" | "disabled"; serverInfo?: { name: string; version: string; }; error?: string; config?: McpServerStatusConfig; scope?: string; tools?: { name: string; description?: string; annotations?: { readOnly?: boolean; destructive?: boolean; openWorld?: boolean; }; }[]; }; ``` ### `McpServerStatusConfig` The configuration of an MCP server as reported by `mcpServerStatus()`. This is the union of all MCP server transport types. ```typescript theme={null} type McpServerStatusConfig = | McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig | McpClaudeAIProxyServerConfig; ``` See [`McpServerConfig`](#mcp-server-config) for details on each transport type. ### `AccountInfo` Account information for the authenticated user. ```typescript theme={null} type AccountInfo = { email?: string; organization?: string; subscriptionType?: string; tokenSource?: string; apiKeySource?: string; }; ``` ### `ModelUsage` Per-model usage statistics returned in result messages. The `costUSD` value is a client-side estimate. See [Track cost and usage](/en/agent-sdk/cost-tracking) for billing caveats. ```typescript theme={null} type ModelUsage = { inputTokens: number; outputTokens: number; cacheReadInputTokens: number; cacheCreationInputTokens: number; webSearchRequests: number; costUSD: number; contextWindow: number; maxOutputTokens: number; }; ``` ### `ConfigScope` ```typescript theme={null} type ConfigScope = "local" | "user" | "project"; ``` ### `NonNullableUsage` A version of [`Usage`](#usage) with all nullable fields made non-nullable. ```typescript theme={null} type NonNullableUsage = { [K in keyof Usage]: NonNullable<Usage[K]>; }; ``` ### `Usage` Token usage statistics (from `@anthropic-ai/sdk`). ```typescript theme={null} type Usage = { input_tokens: number | null; output_tokens: number | null; cache_creation_input_tokens?: number | null; cache_read_input_tokens?: number | null; }; ``` ### `CallToolResult` MCP tool result type (from `@modelcontextprotocol/sdk/types.js`). ```typescript theme={null} type CallToolResult = { content: Array<{ type: "text" | "image" | "resource"; // Additional fields vary by type }>; isError?: boolean; }; ``` ### `ThinkingConfig` Controls Claude's thinking/reasoning behavior. Takes precedence over the deprecated `maxThinkingTokens`. ```typescript theme={null} type ThinkingConfig = | { type: "adaptive" } // The model determines when and how much to reason (Opus 4.6+) | { type: "enabled"; budgetTokens?: number } // Fixed thinking token budget | { type: "disabled" }; // No extended thinking ``` ### `SpawnedProcess` Interface for custom process spawning (used with `spawnClaudeCodeProcess` option). `ChildProcess` already satisfies this interface. ```typescript theme={null} interface SpawnedProcess { stdin: Writable; stdout: Readable; readonly killed: boolean; readonly exitCode: number | null; kill(signal: NodeJS.Signals): boolean; on( event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void ): void; on(event: "error", listener: (error: Error) => void): void; once( event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void ): void; once(event: "error", listener: (error: Error) => void): void; off( event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void ): void; off(event: "error", listener: (error: Error) => void): void; } ``` ### `SpawnOptions` Options passed to the custom spawn function. ```typescript theme={null} interface SpawnOptions { command: string; args: string[]; cwd?: string; env: Record<string, string | undefined>; signal: AbortSignal; } ``` ### `McpSetServersResult` Result of a `setMcpServers()` operation. ```typescript theme={null} type McpSetServersResult = { added: string[]; removed: string[]; errors: Record<string, string>; }; ``` ### `RewindFilesResult` Result of a `rewindFiles()` operation. ```typescript theme={null} type RewindFilesResult = { canRewind: boolean; error?: string; filesChanged?: string[]; insertions?: number; deletions?: number; }; ``` ### `SDKStatusMessage` Status update message (e.g., compacting). ```typescript theme={null} type SDKStatusMessage = { type: "system"; subtype: "status"; status: "compacting" | null; permissionMode?: PermissionMode; uuid: UUID; session_id: string; }; ``` ### `SDKTaskNotificationMessage` Notification when a background task completes, fails, or is stopped. Background tasks include `run_in_background` Bash commands, [Monitor](#monitor) watches, and background subagents. ```typescript theme={null} type SDKTaskNotificationMessage = { type: "system"; subtype: "task_notification"; task_id: string; tool_use_id?: string; status: "completed" | "failed" | "stopped"; output_file: string; summary: string; usage?: { total_tokens: number; tool_uses: number; duration_ms: number; }; uuid: UUID; session_id: string; }; ``` ### `SDKToolUseSummaryMessage` Summary of tool usage in a conversation. ```typescript theme={null} type SDKToolUseSummaryMessage = { type: "tool_use_summary"; summary: string; preceding_tool_use_ids: string[]; uuid: UUID; session_id: string; }; ``` ### `SDKHookStartedMessage` Emitted when a hook begins executing. ```typescript theme={null} type SDKHookStartedMessage = { type: "system"; subtype: "hook_started"; hook_id: string; hook_name: string; hook_event: string; uuid: UUID; session_id: string; }; ``` ### `SDKHookProgressMessage` Emitted while a hook is running, with stdout/stderr output. ```typescript theme={null} type SDKHookProgressMessage = { type: "system"; subtype: "hook_progress"; hook_id: string; hook_name: string; hook_event: string; stdout: string; stderr: string; output: string; uuid: UUID; session_id: string; }; ``` ### `SDKHookResponseMessage` Emitted when a hook finishes executing. ```typescript theme={null} type SDKHookResponseMessage = { type: "system"; subtype: "hook_response"; hook_id: string; hook_name: string; hook_event: string; output: string; stdout: string; stderr: string; exit_code?: number; outcome: "success" | "error" | "cancelled"; uuid: UUID; session_id: string; }; ``` ### `SDKToolProgressMessage` Emitted periodically while a tool is executing to indicate progress. ```typescript theme={null} type SDKToolProgressMessage = { type: "tool_progress"; tool_use_id: string; tool_name: string; parent_tool_use_id: string | null; elapsed_time_seconds: number; task_id?: string; uuid: UUID; session_id: string; }; ``` ### `SDKAuthStatusMessage` Emitted during authentication flows. ```typescript theme={null} type SDKAuthStatusMessage = { type: "auth_status"; isAuthenticating: boolean; output: string[]; error?: string; uuid: UUID; session_id: string; }; ``` ### `SDKTaskStartedMessage` Emitted when a background task begins. The `task_type` field is `"local_bash"` for background Bash commands and [Monitor](#monitor) watches, `"local_agent"` for subagents, or `"remote_agent"`. ```typescript theme={null} type SDKTaskStartedMessage = { type: "system"; subtype: "task_started"; task_id: string; tool_use_id?: string; description: string; task_type?: string; uuid: UUID; session_id: string; }; ``` ### `SDKTaskProgressMessage` Emitted periodically while a background task is running. ```typescript theme={null} type SDKTaskProgressMessage = { type: "system"; subtype: "task_progress"; task_id: string; tool_use_id?: string; description: string; usage: { total_tokens: number; tool_uses: number; duration_ms: number; }; last_tool_name?: string; uuid: UUID; session_id: string; }; ``` ### `SDKTaskUpdatedMessage` Emitted when a background task's state changes, such as when it transitions from `running` to `completed`. Merge `patch` into your local task map keyed by `task_id`. The `end_time` field is a Unix epoch timestamp in milliseconds, comparable with `Date.now()`. ```typescript theme={null} type SDKTaskUpdatedMessage = { type: "system"; subtype: "task_updated"; task_id: string; patch: { status?: "pending" | "running" | "completed" | "failed" | "killed"; description?: string; end_time?: number; total_paused_ms?: number; error?: string; is_backgrounded?: boolean; }; uuid: UUID; session_id: string; }; ``` ### `SDKFilesPersistedEvent` Emitted when file checkpoints are persisted to disk. ```typescript theme={null} type SDKFilesPersistedEvent = { type: "system"; subtype: "files_persisted"; files: { filename: string; file_id: string }[]; failed: { filename: string; error: string }[]; processed_at: string; uuid: UUID; session_id: string; }; ``` ### `SDKRateLimitEvent` Emitted when the session encounters a rate limit. ```typescript theme={null} type SDKRateLimitEvent = { type: "rate_limit_event"; rate_limit_info: { status: "allowed" | "allowed_warning" | "rejected"; resetsAt?: number; utilization?: number; }; uuid: UUID; session_id: string; }; ``` ### `SDKLocalCommandOutputMessage` Output from a local slash command (for example, `/voice` or `/usage`). Displayed as assistant-style text in the transcript. ```typescript theme={null} type SDKLocalCommandOutputMessage = { type: "system"; subtype: "local_command_output"; content: string; uuid: UUID; session_id: string; }; ``` ### `SDKPromptSuggestionMessage` Emitted after each turn when `promptSuggestions` is enabled. Contains a predicted next user prompt. ```typescript theme={null} type SDKPromptSuggestionMessage = { type: "prompt_suggestion"; suggestion: string; uuid: UUID; session_id: string; }; ``` ### `AbortError` Custom error class for abort operations. ```typescript theme={null} class AbortError extends Error {} ``` ## Sandbox Configuration ### `SandboxSettings` Configuration for sandbox behavior. Use this to enable command sandboxing and configure network restrictions programmatically. ```typescript theme={null} type SandboxSettings = { enabled?: boolean; autoAllowBashIfSandboxed?: boolean; excludedCommands?: string[]; allowUnsandboxedCommands?: boolean; network?: SandboxNetworkConfig; filesystem?: SandboxFilesystemConfig; ignoreViolations?: Record<string, string[]>; enableWeakerNestedSandbox?: boolean; ripgrep?: { command: string; args?: string[] }; }; ``` | Property | Type | Default | Description | | :-------------------------- | :------------------------------------------------------ | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | `boolean` | `false` | Enable sandbox mode for command execution | | `autoAllowBashIfSandboxed` | `boolean` | `true` | Auto-approve bash commands when sandbox is enabled | | `excludedCommands` | `string[]` | `[]` | Commands that always bypass sandbox restrictions (e.g., `['docker']`). These run unsandboxed automatically without model involvement | | `allowUnsandboxedCommands` | `boolean` | `true` | Allow the model to request running commands outside the sandbox. When `true`, the model can set `dangerouslyDisableSandbox` in tool input, which falls back to the [permissions system](#permissions-fallback-for-unsandboxed-commands) | | `network` | [`SandboxNetworkConfig`](#sandbox-network-config) | `undefined` | Network-specific sandbox configuration | | `filesystem` | [`SandboxFilesystemConfig`](#sandbox-filesystem-config) | `undefined` | Filesystem-specific sandbox configuration for read/write restrictions | | `ignoreViolations` | `Record<string, string[]>` | `undefined` | Map of violation categories to patterns to ignore (e.g., `{ file: ['/tmp/*'], network: ['localhost'] }`) | | `enableWeakerNestedSandbox` | `boolean` | `false` | Enable a weaker nested sandbox for compatibility | | `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Custom ripgrep binary configuration for sandbox environments | #### Example usage ```typescript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Build and test my project", options: { sandbox: { enabled: true, autoAllowBashIfSandboxed: true, network: { allowLocalBinding: true } } } })) { if ("result" in message) console.log(message.result); } ``` <Warning> **Unix socket security:** The `allowUnixSockets` option can grant access to powerful system services. For example, allowing `/var/run/docker.sock` effectively grants full host system access through the Docker API, bypassing sandbox isolation. Only allow Unix sockets that are strictly necessary and understand the security implications of each. </Warning> ### `SandboxNetworkConfig` Network-specific configuration for sandbox mode. ```typescript theme={null} type SandboxNetworkConfig = { allowedDomains?: string[]; deniedDomains?: string[]; allowManagedDomainsOnly?: boolean; allowLocalBinding?: boolean; allowUnixSockets?: string[]; allowAllUnixSockets?: boolean; httpProxyPort?: number; socksProxyPort?: number; }; ``` | Property | Type | Default | Description | | :------------------------ | :--------- | :---------- | :------------------------------------------------------------------------------------------ | | `allowedDomains` | `string[]` | `[]` | Domain names that sandboxed processes can access | | `deniedDomains` | `string[]` | `[]` | Domain names that sandboxed processes cannot access. Takes precedence over `allowedDomains` | | `allowManagedDomainsOnly` | `boolean` | `false` | Restrict network access to only the domains in `allowedDomains` | | `allowLocalBinding` | `boolean` | `false` | Allow processes to bind to local ports (e.g., for dev servers) | | `allowUnixSockets` | `string[]` | `[]` | Unix socket paths that processes can access (e.g., Docker socket) | | `allowAllUnixSockets` | `boolean` | `false` | Allow access to all Unix sockets | | `httpProxyPort` | `number` | `undefined` | HTTP proxy port for network requests | | `socksProxyPort` | `number` | `undefined` | SOCKS proxy port for network requests | ### `SandboxFilesystemConfig` Filesystem-specific configuration for sandbox mode. ```typescript theme={null} type SandboxFilesystemConfig = { allowWrite?: string[]; denyWrite?: string[]; denyRead?: string[]; }; ``` | Property | Type | Default | Description | | :----------- | :--------- | :------ | :------------------------------------------ | | `allowWrite` | `string[]` | `[]` | File path patterns to allow write access to | | `denyWrite` | `string[]` | `[]` | File path patterns to deny write access to | | `denyRead` | `string[]` | `[]` | File path patterns to deny read access to | ### Permissions Fallback for Unsandboxed Commands When `allowUnsandboxedCommands` is enabled, the model can request to run commands outside the sandbox by setting `dangerouslyDisableSandbox: true` in the tool input. These requests fall back to the existing permissions system, meaning your `canUseTool` handler is invoked, allowing you to implement custom authorization logic. <Note> **`excludedCommands` vs `allowUnsandboxedCommands`:** * `excludedCommands`: A static list of commands that always bypass the sandbox automatically (e.g., `['docker']`). The model has no control over this. * `allowUnsandboxedCommands`: Lets the model decide at runtime whether to request unsandboxed execution by setting `dangerouslyDisableSandbox: true` in the tool input. </Note> ```typescript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Deploy my application", options: { sandbox: { enabled: true, allowUnsandboxedCommands: true // Model can request unsandboxed execution }, permissionMode: "default", canUseTool: async (tool, input) => { // Check if the model is requesting to bypass the sandbox if (tool === "Bash" && input.dangerouslyDisableSandbox) { // The model is requesting to run this command outside the sandbox console.log(`Unsandboxed command requested: ${input.command}`); if (isCommandAuthorized(input.command)) { return { behavior: "allow" as const, updatedInput: input }; } return { behavior: "deny" as const, message: "Command not authorized for unsandboxed execution" }; } return { behavior: "allow" as const, updatedInput: input }; } } })) { if ("result" in message) console.log(message.result); } ``` This pattern enables you to: * **Audit model requests:** Log when the model requests unsandboxed execution * **Implement allowlists:** Only permit specific commands to run unsandboxed * **Add approval workflows:** Require explicit authorization for privileged operations <Warning> Commands running with `dangerouslyDisableSandbox: true` have full system access. Ensure your `canUseTool` handler validates these requests carefully. If `permissionMode` is set to `bypassPermissions` and `allowUnsandboxedCommands` is enabled, commands may run with reduced sandbox isolation. Review enterprise hardening guidance before enabling this combination. </Warning> ## See also * [SDK overview](/en/agent-sdk/overview) - General SDK concepts * [Python SDK reference](/en/agent-sdk/python) - Python SDK documentation * [CLI reference](../02-Claude-Code-CLI/cli-reference-7bb98e3312.md) - Command-line interface * [Common workflows](../02-Claude-Code-CLI/common-workflows-c909406123.md) - Step-by-step guides --- ## agent-sdk-user-input-4d57dfc0b8.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Handle approvals and user input > Surface Claude's approval requests and clarifying questions to users, then return their decisions to the SDK. While working on a task, Claude sometimes needs to check in with users. It might need permission before deleting files, or need to ask which database to use for a new project. Your application needs to surface these requests to users so Claude can continue with their input. Claude requests user input in two situations: when it needs **permission to use a tool** (like deleting files or running commands), and when it has **clarifying questions** (via the `AskUserQuestion` tool). Both trigger your `canUseTool` callback, which pauses execution until you return a response. This is different from normal conversation turns where Claude finishes and waits for your next message. For clarifying questions, Claude generates the questions and options. Your role is to present them to users and return their selections. You can't add your own questions to this flow; if you need to ask users something yourself, do that separately in your application logic. The callback can stay pending indefinitely. Execution remains paused until your callback returns, and the SDK only cancels the wait when the query itself is cancelled. If a user might take longer to respond than your process can reasonably stay running, the TypeScript SDK supports the [`defer` hook decision](/en/hooks#defer-a-tool-call-for-later), which lets the process exit and resume later from the persisted session; this option is not available in the Python SDK. This guide shows you how to detect each type of request and respond appropriately. ## Detect when Claude needs input Pass a `canUseTool` callback in your query options. The callback fires whenever Claude needs user input, receiving the tool name and input as arguments: <CodeGroup> ```python Python theme={null} async def handle_tool_request(tool_name, input_data, context): # Prompt user and return allow or deny ... options = ClaudeAgentOptions(can_use_tool=handle_tool_request) ``` ```typescript TypeScript theme={null} async function handleToolRequest(toolName, input, options) { // options includes { signal: AbortSignal, suggestions?: PermissionUpdate[] } // Prompt user and return allow or deny } const options = { canUseTool: handleToolRequest }; ``` </CodeGroup> The callback fires in two cases: 1. **Tool needs approval**: Claude wants to use a tool that isn't auto-approved by [permission rules](/en/agent-sdk/permissions) or modes. Check `tool_name` for the tool (e.g., `"Bash"`, `"Write"`). 2. **Claude asks a question**: Claude calls the `AskUserQuestion` tool. Check if `tool_name == "AskUserQuestion"` to handle it differently. If you specify a `tools` array, include `AskUserQuestion` for this to work. See [Handle clarifying questions](#handle-clarifying-questions) for details. <Note> To automatically allow or deny tools without prompting users, use [hooks](/en/agent-sdk/hooks) instead. Hooks execute before `canUseTool` and can allow, deny, or modify requests based on your own logic. You can also use the [`PermissionRequest` hook](/en/agent-sdk/hooks#available-hooks) to send external notifications (Slack, email, push) when Claude is waiting for approval. </Note> ## Handle tool approval requests Once you've passed a `canUseTool` callback in your query options, it fires when Claude wants to use a tool that isn't auto-approved. Your callback receives three arguments: | Argument | Description | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `toolName` | The name of the tool Claude wants to use (e.g., `"Bash"`, `"Write"`, `"Edit"`) | | `input` | The parameters Claude is passing to the tool. Contents vary by tool. | | `options` (TS) / `context` (Python) | Additional context including optional `suggestions` (proposed `PermissionUpdate` entries to avoid re-prompting) and a cancellation signal. In TypeScript, `signal` is an `AbortSignal`; in Python, the signal field is reserved for future use. See [`ToolPermissionContext`](/en/agent-sdk/python#tool-permission-context) for Python. | The `input` object contains tool-specific parameters. Common examples: | Tool | Input fields | | ------- | --------------------------------------- | | `Bash` | `command`, `description`, `timeout` | | `Write` | `file_path`, `content` | | `Edit` | `file_path`, `old_string`, `new_string` | | `Read` | `file_path`, `offset`, `limit` | See the SDK reference for complete input schemas: [Python](/en/agent-sdk/python#tool-input-output-types) | [TypeScript](/en/agent-sdk/typescript#tool-input-types). You can display this information to the user so they can decide whether to allow or reject the action, then return the appropriate response. The following example asks Claude to create and delete a test file. When Claude attempts each operation, the callback prints the tool request to the terminal and prompts for y/n approval. <CodeGroup> ```python Python theme={null} import asyncio from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query from claude_agent_sdk.types import ( HookMatcher, PermissionResultAllow, PermissionResultDeny, ToolPermissionContext, ) async def can_use_tool( tool_name: str, input_data: dict, context: ToolPermissionContext ) -> PermissionResultAllow | PermissionResultDeny: # Display the tool request print(f"\nTool: {tool_name}") if tool_name == "Bash": print(f"Command: {input_data.get('command')}") if input_data.get("description"): print(f"Description: {input_data.get('description')}") else: print(f"Input: {input_data}") # Get user approval response = input("Allow this action? (y/n): ") # Return allow or deny based on user's response if response.lower() == "y": # Allow: tool executes with the original (or modified) input return PermissionResultAllow(updated_input=input_data) else: # Deny: tool doesn't execute, Claude sees the message return PermissionResultDeny(message="User denied this action") # Required workaround: dummy hook keeps the stream open for can_use_tool async def dummy_hook(input_data, tool_use_id, context): return {"continue_": True} async def prompt_stream(): yield { "type": "user", "message": { "role": "user", "content": "Create a test file in /tmp and then delete it", }, } async def main(): async for message in query( prompt=prompt_stream(), options=ClaudeAgentOptions( can_use_tool=can_use_tool, hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]}, ), ): if isinstance(message, ResultMessage) and message.subtype == "success": print(message.result) asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; import * as readline from "readline"; // Helper to prompt user for input in the terminal function prompt(question: string): Promise<string> { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(question, (answer) => { rl.close(); resolve(answer); }) ); } for await (const message of query({ prompt: "Create a test file in /tmp and then delete it", options: { canUseTool: async (toolName, input) => { // Display the tool request console.log(`\nTool: ${toolName}`); if (toolName === "Bash") { console.log(`Command: ${input.command}`); if (input.description) console.log(`Description: ${input.description}`); } else { console.log(`Input: ${JSON.stringify(input, null, 2)}`); } // Get user approval const response = await prompt("Allow this action? (y/n): "); // Return allow or deny based on user's response if (response.toLowerCase() === "y") { // Allow: tool executes with the original (or modified) input return { behavior: "allow", updatedInput: input }; } else { // Deny: tool doesn't execute, Claude sees the message return { behavior: "deny", message: "User denied this action" }; } } } })) { if ("result" in message) console.log(message.result); } ``` </CodeGroup> <Note> In Python, `can_use_tool` requires [streaming mode](/en/agent-sdk/streaming-vs-single-mode) and a `PreToolUse` hook that returns `{"continue_": True}` to keep the stream open. Without this hook, the stream closes before the permission callback can be invoked. </Note> This example uses a `y/n` flow where any input other than `y` is treated as a denial. In practice, you might build a richer UI that lets users modify the request, provide feedback, or redirect Claude entirely. See [Respond to tool requests](#respond-to-tool-requests) for all the ways you can respond. ### Respond to tool requests Your callback returns one of two response types: | Response | Python | TypeScript | | --------- | ------------------------------------------ | ------------------------------------- | | **Allow** | `PermissionResultAllow(updated_input=...)` | `{ behavior: "allow", updatedInput }` | | **Deny** | `PermissionResultDeny(message=...)` | `{ behavior: "deny", message }` | When allowing, pass the tool input (original or modified). When denying, provide a message explaining why. Claude sees this message and may adjust its approach. <CodeGroup> ```python Python theme={null} from claude_agent_sdk.types import PermissionResultAllow, PermissionResultDeny # Allow the tool to execute return PermissionResultAllow(updated_input=input_data) # Block the tool return PermissionResultDeny(message="User rejected this action") ``` ```typescript TypeScript theme={null} // Allow the tool to execute return { behavior: "allow", updatedInput: input }; // Block the tool return { behavior: "deny", message: "User rejected this action" }; ``` </CodeGroup> Beyond allowing or denying, you can modify the tool's input or provide context that helps Claude adjust its approach: * **Approve**: let the tool execute as Claude requested * **Approve with changes**: modify the input before execution (e.g., sanitize paths, add constraints) * **Reject**: block the tool and tell Claude why * **Suggest alternative**: block but guide Claude toward what the user wants instead * **Redirect entirely**: use [streaming input](/en/agent-sdk/streaming-vs-single-mode) to send Claude a completely new instruction <Tabs> <Tab title="Approve"> The user approves the action as-is. Pass through the `input` from your callback unchanged and the tool executes exactly as Claude requested. <CodeGroup> ```python Python theme={null} async def can_use_tool(tool_name, input_data, context): print(f"Claude wants to use {tool_name}") approved = await ask_user("Allow this action?") if approved: return PermissionResultAllow(updated_input=input_data) return PermissionResultDeny(message="User declined") ``` ```typescript TypeScript theme={null} canUseTool: async (toolName, input) => { console.log(`Claude wants to use ${toolName}`); const approved = await askUser("Allow this action?"); if (approved) { return { behavior: "allow", updatedInput: input }; } return { behavior: "deny", message: "User declined" }; }; ``` </CodeGroup> </Tab> <Tab title="Approve with changes"> The user approves but wants to modify the request first. You can change the input before the tool executes. Claude sees the result but isn't told you changed anything. Useful for sanitizing parameters, adding constraints, or scoping access. <CodeGroup> ```python Python theme={null} async def can_use_tool(tool_name, input_data, context): if tool_name == "Bash": # User approved, but scope all commands to sandbox sandboxed_input = {**input_data} sandboxed_input["command"] = input_data["command"].replace( "/tmp", "/tmp/sandbox" ) return PermissionResultAllow(updated_input=sandboxed_input) return PermissionResultAllow(updated_input=input_data) ``` ```typescript TypeScript theme={null} canUseTool: async (toolName, input) => { if (toolName === "Bash") { // User approved, but scope all commands to sandbox const sandboxedInput = { ...input, command: input.command.replace("/tmp", "/tmp/sandbox") }; return { behavior: "allow", updatedInput: sandboxedInput }; } return { behavior: "allow", updatedInput: input }; }; ``` </CodeGroup> </Tab> <Tab title="Reject"> The user doesn't want this action to happen. Block the tool and provide a message explaining why. Claude sees this message and may try a different approach. <CodeGroup> ```python Python theme={null} async def can_use_tool(tool_name, input_data, context): approved = await ask_user(f"Allow {tool_name}?") if not approved: return PermissionResultDeny(message="User rejected this action") return PermissionResultAllow(updated_input=input_data) ``` ```typescript TypeScript theme={null} canUseTool: async (toolName, input) => { const approved = await askUser(`Allow ${toolName}?`); if (!approved) { return { behavior: "deny", message: "User rejected this action" }; } return { behavior: "allow", updatedInput: input }; }; ``` </CodeGroup> </Tab> <Tab title="Suggest alternative"> The user doesn't want this specific action, but has a different idea. Block the tool and include guidance in your message. Claude will read this and decide how to proceed based on your feedback. <CodeGroup> ```python Python theme={null} async def can_use_tool(tool_name, input_data, context): if tool_name == "Bash" and "rm" in input_data.get("command", ""): # User doesn't want to delete, suggest archiving instead return PermissionResultDeny( message="User doesn't want to delete files. They asked if you could compress them into an archive instead." ) return PermissionResultAllow(updated_input=input_data) ``` ```typescript TypeScript theme={null} canUseTool: async (toolName, input) => { if (toolName === "Bash" && input.command.includes("rm")) { // User doesn't want to delete, suggest archiving instead return { behavior: "deny", message: "User doesn't want to delete files. They asked if you could compress them into an archive instead." }; } return { behavior: "allow", updatedInput: input }; }; ``` </CodeGroup> </Tab> <Tab title="Redirect entirely"> For a complete change of direction (not just a nudge), use [streaming input](/en/agent-sdk/streaming-vs-single-mode) to send Claude a new instruction directly. This bypasses the current tool request and gives Claude entirely new instructions to follow. </Tab> </Tabs> ## Handle clarifying questions When Claude needs more direction on a task with multiple valid approaches, it calls the `AskUserQuestion` tool. This triggers your `canUseTool` callback with `toolName` set to `AskUserQuestion`. The input contains Claude's questions as multiple-choice options, which you display to the user and return their selections. <Tip> Clarifying questions are especially common in [`plan` mode](/en/agent-sdk/permissions#plan-mode-plan), where Claude explores the codebase and asks questions before proposing a plan. This makes plan mode ideal for interactive workflows where you want Claude to gather requirements before making changes. </Tip> The following steps show how to handle clarifying questions: <Steps> <Step title="Pass a canUseTool callback"> Pass a `canUseTool` callback in your query options. By default, `AskUserQuestion` is available. If you specify a `tools` array to restrict Claude's capabilities (for example, a read-only agent with only `Read`, `Glob`, and `Grep`), include `AskUserQuestion` in that array. Otherwise, Claude won't be able to ask clarifying questions: <CodeGroup> ```python Python theme={null} async for message in query( prompt="Analyze this codebase", options=ClaudeAgentOptions( # Include AskUserQuestion in your tools list tools=["Read", "Glob", "Grep", "AskUserQuestion"], can_use_tool=can_use_tool, ), ): print(message) ``` ```typescript TypeScript theme={null} for await (const message of query({ prompt: "Analyze this codebase", options: { // Include AskUserQuestion in your tools list tools: ["Read", "Glob", "Grep", "AskUserQuestion"], canUseTool: async (toolName, input) => { // Handle clarifying questions here } } })) { console.log(message); } ``` </CodeGroup> </Step> <Step title="Detect AskUserQuestion"> In your callback, check if `toolName` equals `AskUserQuestion` to handle it differently from other tools: <CodeGroup> ```python Python theme={null} async def can_use_tool(tool_name: str, input_data: dict, context): if tool_name == "AskUserQuestion": # Your implementation to collect answers from the user return await handle_clarifying_questions(input_data) # Handle other tools normally return await prompt_for_approval(tool_name, input_data) ``` ```typescript TypeScript theme={null} canUseTool: async (toolName, input) => { if (toolName === "AskUserQuestion") { // Your implementation to collect answers from the user return handleClarifyingQuestions(input); } // Handle other tools normally return promptForApproval(toolName, input); }; ``` </CodeGroup> </Step> <Step title="Parse the question input"> The input contains Claude's questions in a `questions` array. Each question has a `question` (the text to display), `options` (the choices), and `multiSelect` (whether multiple selections are allowed): ```json theme={null} { "questions": [ { "question": "How should I format the output?", "header": "Format", "options": [ { "label": "Summary", "description": "Brief overview" }, { "label": "Detailed", "description": "Full explanation" } ], "multiSelect": false }, { "question": "Which sections should I include?", "header": "Sections", "options": [ { "label": "Introduction", "description": "Opening context" }, { "label": "Conclusion", "description": "Final summary" } ], "multiSelect": true } ] } ``` See [Question format](#question-format) for full field descriptions. </Step> <Step title="Collect answers from the user"> Present the questions to the user and collect their selections. How you do this depends on your application: a terminal prompt, a web form, a mobile dialog, etc. </Step> <Step title="Return answers to Claude"> Build the `answers` object as a record where each key is the `question` text and each value is the selected option's `label`: | From the question object | Use as | | ------------------------------------------------------------ | ------ | | `question` field (e.g., `"How should I format the output?"`) | Key | | Selected option's `label` field (e.g., `"Summary"`) | Value | For multi-select questions, join multiple labels with `", "`. If you [support free-text input](#support-free-text-input), use the user's custom text as the value. <CodeGroup> ```python Python theme={null} return PermissionResultAllow( updated_input={ "questions": input_data.get("questions", []), "answers": { "How should I format the output?": "Summary", "Which sections should I include?": "Introduction, Conclusion", }, } ) ``` ```typescript TypeScript theme={null} return { behavior: "allow", updatedInput: { questions: input.questions, answers: { "How should I format the output?": "Summary", "Which sections should I include?": "Introduction, Conclusion" } } }; ``` </CodeGroup> </Step> </Steps> ### Question format The input contains Claude's generated questions in a `questions` array. Each question has these fields: | Field | Description | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `question` | The full question text to display | | `header` | Short label for the question (max 12 characters) | | `options` | Array of 2-4 choices, each with `label` and `description`. TypeScript: optionally `preview` (see [below](#option-previews-type-script)) | | `multiSelect` | If `true`, users can select multiple options | The structure your callback receives: ```json theme={null} { "questions": [ { "question": "How should I format the output?", "header": "Format", "options": [ { "label": "Summary", "description": "Brief overview of key points" }, { "label": "Detailed", "description": "Full explanation with examples" } ], "multiSelect": false } ] } ``` #### Option previews (TypeScript) `toolConfig.askUserQuestion.previewFormat` adds a `preview` field to each option so your app can show a visual mockup alongside the label. Without this setting, Claude does not generate previews and the field is absent. | `previewFormat` | `preview` contains | | :-------------- | :------------------------------------------------------------------------------------------------------------ | | unset (default) | Field is absent. Claude does not generate previews. | | `"markdown"` | ASCII art and fenced code blocks | | `"html"` | A styled `<div>` fragment (the SDK rejects `<script>`, `<style>`, and `<!DOCTYPE>` before your callback runs) | The format applies to all questions in the session. Claude includes `preview` on options where a visual comparison helps (layout choices, color schemes) and omits it where one wouldn't (yes/no confirmations, text-only choices). Check for `undefined` before rendering. ```typescript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Help me choose a card layout", options: { toolConfig: { askUserQuestion: { previewFormat: "html" } }, canUseTool: async (toolName, input) => { // input.questions[].options[].preview is an HTML string or undefined return { behavior: "allow", updatedInput: input }; } } })) { // ... } ``` An option with an HTML preview: ```json theme={null} { "label": "Compact", "description": "Title and metric value only", "preview": "<div style=\"padding:12px;border:1px solid #ddd;border-radius:8px\"><div style=\"font-size:12px;color:#666\">Active users</div><div style=\"font-size:28px;font-weight:600\">1,284</div></div>" } ``` ### Response format Return an `answers` object mapping each question's `question` field to the selected option's `label`: | Field | Description | | ----------- | ------------------------------------------------------------------------ | | `questions` | Pass through the original questions array (required for tool processing) | | `answers` | Object where keys are question text and values are selected labels | For multi-select questions, join multiple labels with `", "`. For free-text input, use the user's custom text directly. ```json theme={null} { "questions": [ // ... ], "answers": { "How should I format the output?": "Summary", "Which sections should I include?": "Introduction, Conclusion" } } ``` #### Support free-text input Claude's predefined options won't always cover what users want. To let users type their own answer: * Display an additional "Other" choice after Claude's options that accepts text input * Use the user's custom text as the answer value (not the word "Other") See the [complete example](#complete-example) below for a full implementation. ### Complete example Claude asks clarifying questions when it needs user input to proceed. For example, when asked to help decide on a tech stack for a mobile app, Claude might ask about cross-platform vs native, backend preferences, or target platforms. These questions help Claude make decisions that match the user's preferences rather than guessing. This example handles those questions in a terminal application. Here's what happens at each step: 1. **Route the request**: The `canUseTool` callback checks if the tool name is `"AskUserQuestion"` and routes to a dedicated handler 2. **Display questions**: The handler loops through the `questions` array and prints each question with numbered options 3. **Collect input**: The user can enter a number to select an option, or type free text directly (e.g., "jquery", "i don't know") 4. **Map answers**: The code checks if input is numeric (uses the option's label) or free text (uses the text directly) 5. **Return to Claude**: The response includes both the original `questions` array and the `answers` mapping <CodeGroup> ```python Python theme={null} import asyncio from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query from claude_agent_sdk.types import HookMatcher, PermissionResultAllow def parse_response(response: str, options: list) -> str: """Parse user input as option number(s) or free text.""" try: indices = [int(s.strip()) - 1 for s in response.split(",")] labels = [options[i]["label"] for i in indices if 0 <= i < len(options)] return ", ".join(labels) if labels else response except ValueError: return response async def handle_ask_user_question(input_data: dict) -> PermissionResultAllow: """Display Claude's questions and collect user answers.""" answers = {} for q in input_data.get("questions", []): print(f"\n{q['header']}: {q['question']}") options = q["options"] for i, opt in enumerate(options): print(f" {i + 1}. {opt['label']} - {opt['description']}") if q.get("multiSelect"): print(" (Enter numbers separated by commas, or type your own answer)") else: print(" (Enter a number, or type your own answer)") response = input("Your choice: ").strip() answers[q["question"]] = parse_response(response, options) return PermissionResultAllow( updated_input={ "questions": input_data.get("questions", []), "answers": answers, } ) async def can_use_tool( tool_name: str, input_data: dict, context ) -> PermissionResultAllow: # Route AskUserQuestion to our question handler if tool_name == "AskUserQuestion": return await handle_ask_user_question(input_data) # Auto-approve other tools for this example return PermissionResultAllow(updated_input=input_data) async def prompt_stream(): yield { "type": "user", "message": { "role": "user", "content": "Help me decide on the tech stack for a new mobile app", }, } # Required workaround: dummy hook keeps the stream open for can_use_tool async def dummy_hook(input_data, tool_use_id, context): return {"continue_": True} async def main(): async for message in query( prompt=prompt_stream(), options=ClaudeAgentOptions( can_use_tool=can_use_tool, hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]}, ), ): if isinstance(message, ResultMessage) and message.subtype == "success": print(message.result) asyncio.run(main()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; import * as readline from "readline/promises"; // Helper to prompt user for input in the terminal async function prompt(question: string): Promise<string> { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); const answer = await rl.question(question); rl.close(); return answer; } // Parse user input as option number(s) or free text function parseResponse(response: string, options: any[]): string { const indices = response.split(",").map((s) => parseInt(s.trim()) - 1); const labels = indices .filter((i) => !isNaN(i) && i >= 0 && i < options.length) .map((i) => options[i].label); return labels.length > 0 ? labels.join(", ") : response; } // Display Claude's questions and collect user answers async function handleAskUserQuestion(input: any) { const answers: Record<string, string> = {}; for (const q of input.questions) { console.log(`\n${q.header}: ${q.question}`); const options = q.options; options.forEach((opt: any, i: number) => { console.log(` ${i + 1}. ${opt.label} - ${opt.description}`); }); if (q.multiSelect) { console.log(" (Enter numbers separated by commas, or type your own answer)"); } else { console.log(" (Enter a number, or type your own answer)"); } const response = (await prompt("Your choice: ")).trim(); answers[q.question] = parseResponse(response, options); } // Return the answers to Claude (must include original questions) return { behavior: "allow", updatedInput: { questions: input.questions, answers } }; } async function main() { for await (const message of query({ prompt: "Help me decide on the tech stack for a new mobile app", options: { canUseTool: async (toolName, input) => { // Route AskUserQuestion to our question handler if (toolName === "AskUserQuestion") { return handleAskUserQuestion(input); } // Auto-approve other tools for this example return { behavior: "allow", updatedInput: input }; } } })) { if ("result" in message) console.log(message.result); } } main(); ``` </CodeGroup> ## Limitations * **Subagents**: `AskUserQuestion` is not currently available in subagents spawned via the Agent tool * **Question limits**: each `AskUserQuestion` call supports 1-4 questions with 2-4 options each ## Other ways to get user input The `canUseTool` callback and `AskUserQuestion` tool cover most approval and clarification scenarios, but the SDK offers other ways to get input from users: ### Streaming input Use [streaming input](/en/agent-sdk/streaming-vs-single-mode) when you need to: * **Interrupt the agent mid-task**: send a cancel signal or change direction while Claude is working * **Provide additional context**: add information Claude needs without waiting for it to ask * **Build chat interfaces**: let users send follow-up messages during long-running operations Streaming input is ideal for conversational UIs where users interact with the agent throughout execution, not just at approval checkpoints. ### Custom tools Use [custom tools](/en/agent-sdk/custom-tools) when you need to: * **Collect structured input**: build forms, wizards, or multi-step workflows that go beyond `AskUserQuestion`'s multiple-choice format * **Integrate external approval systems**: connect to existing ticketing, workflow, or approval platforms * **Implement domain-specific interactions**: create tools tailored to your application's needs, like code review interfaces or deployment checklists Custom tools give you full control over the interaction, but require more implementation work than using the built-in `canUseTool` callback. ## Related resources * [Configure permissions](/en/agent-sdk/permissions): set up permission modes and rules * [Control execution with hooks](/en/agent-sdk/hooks): run custom code at key points in the agent lifecycle * [TypeScript SDK reference](/en/agent-sdk/typescript#can-use-tool): full canUseTool API documentation --- ## agent-teams-e29da6ed1b.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Orchestrate teams of Claude Code sessions > Coordinate multiple Claude Code instances working together as a team, with shared tasks, inter-agent messaging, and centralized management. <Warning> Agent teams are experimental and disabled by default. Enable them by adding `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` to your [settings.json](../02-Claude-Code-CLI/claude-code-settings-claude-code-docs-d4420b4b52.md) or environment. Agent teams have [known limitations](#limitations) around session resumption, task coordination, and shutdown behavior. </Warning> Agent teams let you coordinate multiple Claude Code instances working together. One session acts as the team lead, coordinating work, assigning tasks, and synthesizing results. Teammates work independently, each in its own context window, and communicate directly with each other. Unlike [subagents](create-custom-subagents-claude-code-docs-7dc93e85c0.md), which run within a single session and can only report back to the main agent, you can also interact with individual teammates directly without going through the lead. <Note> Agent teams require Claude Code v2.1.32 or later. Check your version with `claude --version`. </Note> This page covers: * [When to use agent teams](#when-to-use-agent-teams), including best use cases and how they compare with subagents * [Starting a team](#start-your-first-agent-team) * [Controlling teammates](#control-your-agent-team), including display modes, task assignment, and delegation * [Best practices for parallel work](#best-practices) ## When to use agent teams Agent teams are most effective for tasks where parallel exploration adds real value. See [use case examples](#use-case-examples) for full scenarios. The strongest use cases are: * **Research and review**: multiple teammates can investigate different aspects of a problem simultaneously, then share and challenge each other's findings * **New modules or features**: teammates can each own a separate piece without stepping on each other * **Debugging with competing hypotheses**: teammates test different theories in parallel and converge on the answer faster * **Cross-layer coordination**: changes that span frontend, backend, and tests, each owned by a different teammate Agent teams add coordination overhead and use significantly more tokens than a single session. They work best when teammates can operate independently. For sequential tasks, same-file edits, or work with many dependencies, a single session or [subagents](create-custom-subagents-claude-code-docs-7dc93e85c0.md) are more effective. ### Compare with subagents Both agent teams and [subagents](create-custom-subagents-claude-code-docs-7dc93e85c0.md) let you parallelize work, but they operate differently. Choose based on whether your workers need to communicate with each other: <Frame caption="Subagents only report results back to the main agent and never talk to each other. In agent teams, teammates share a task list, claim work, and communicate directly with each other."> <img src="https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-light.png?fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=2f8db9b4f3705dd3ab931fbe2d96e42a" className="dark:hidden" alt="Diagram comparing subagent and agent team architectures. Subagents are spawned by the main agent, do work, and report results back. Agent teams coordinate through a shared task list, with teammates communicating directly with each other." width="4245" height="1615" data-path="images/subagents-vs-agent-teams-light.png" /> <img src="https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-dark.png?fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=d573a037540f2ada6a9ae7d8285b46fd" className="hidden dark:block" alt="Diagram comparing subagent and agent team architectures. Subagents are spawned by the main agent, do work, and report results back. Agent teams coordinate through a shared task list, with teammates communicating directly with each other." width="4245" height="1615" data-path="images/subagents-vs-agent-teams-dark.png" /> </Frame> | | Subagents | Agent teams | | :---------------- | :----------------------------------------------- | :-------------------------------------------------- | | **Context** | Own context window; results return to the caller | Own context window; fully independent | | **Communication** | Report results back to the main agent only | Teammates message each other directly | | **Coordination** | Main agent manages all work | Shared task list with self-coordination | | **Best for** | Focused tasks where only the result matters | Complex work requiring discussion and collaboration | | **Token cost** | Lower: results summarized back to main context | Higher: each teammate is a separate Claude instance | Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own. ## Enable agent teams Agent teams are disabled by default. Enable them by setting the `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` environment variable to `1`, either in your shell environment or through [settings.json](../02-Claude-Code-CLI/claude-code-settings-claude-code-docs-d4420b4b52.md): ```json settings.json theme={null} { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } } ``` ## Start your first agent team After enabling agent teams, tell Claude to create an agent team and describe the task and the team structure you want in natural language. Claude creates the team, spawns teammates, and coordinates work based on your prompt. This example works well because the three roles are independent and can explore the problem without waiting on each other: ```text theme={null} I'm designing a CLI tool that helps developers track TODO comments across their codebase. Create an agent team to explore this from different angles: one teammate on UX, one on technical architecture, one playing devil's advocate. ``` From there, Claude creates a team with a [shared task list](/en/interactive-mode#task-list), spawns teammates for each perspective, has them explore the problem, synthesizes findings, and attempts to [clean up the team](#clean-up-the-team) when finished. The lead's terminal lists all teammates and what they're working on. Use Shift+Down to cycle through teammates and message them directly. After the last teammate, Shift+Down wraps back to the lead. If you want each teammate in its own split pane, see [Choose a display mode](#choose-a-display-mode). ## Control your agent team Tell the lead what you want in natural language. It handles team coordination, task assignment, and delegation based on your instructions. ### Choose a display mode Agent teams support two display modes: * **In-process**: all teammates run inside your main terminal. Use Shift+Down to cycle through teammates and type to message them directly. Works in any terminal, no extra setup required. * **Split panes**: each teammate gets its own pane. You can see everyone's output at once and click into a pane to interact directly. Requires tmux, or iTerm2. <Note> `tmux` has known limitations on certain operating systems and traditionally works best on macOS. Using `tmux -CC` in iTerm2 is the suggested entrypoint into `tmux`. </Note> The default is `"auto"`, which uses split panes if you're already running inside a tmux session, and in-process otherwise. The `"tmux"` setting enables split-pane mode and auto-detects whether to use tmux or iTerm2 based on your terminal. To override, set [`teammateMode`](/en/settings#available-settings) in `~/.claude/settings.json`: ```json theme={null} { "teammateMode": "in-process" } ``` To force in-process mode for a single session, pass it as a flag: ```bash theme={null} claude --teammate-mode in-process ``` Split-pane mode requires either [tmux](https://github.com/tmux/tmux/wiki) or iTerm2 with the [`it2` CLI](https://github.com/mkusaka/it2). To install manually: * **tmux**: install through your system's package manager. See the [tmux wiki](https://github.com/tmux/tmux/wiki/Installing) for platform-specific instructions. * **iTerm2**: install the [`it2` CLI](https://github.com/mkusaka/it2), then enable the Python API in **iTerm2 → Settings → General → Magic → Enable Python API**. ### Specify teammates and models Claude decides the number of teammates to spawn based on your task, or you can specify exactly what you want: ```text theme={null} Create a team with 4 teammates to refactor these modules in parallel. Use Sonnet for each teammate. ``` ### Require plan approval for teammates For complex or risky tasks, you can require teammates to plan before implementing. The teammate works in read-only plan mode until the lead approves their approach: ```text theme={null} Spawn an architect teammate to refactor the authentication module. Require plan approval before they make any changes. ``` When a teammate finishes planning, it sends a plan approval request to the lead. The lead reviews the plan and either approves it or rejects it with feedback. If rejected, the teammate stays in plan mode, revises based on the feedback, and resubmits. Once approved, the teammate exits plan mode and begins implementation. The lead makes approval decisions autonomously. To influence the lead's judgment, give it criteria in your prompt, such as "only approve plans that include test coverage" or "reject plans that modify the database schema." ### Talk to teammates directly Each teammate is a full, independent Claude Code session. You can message any teammate directly to give additional instructions, ask follow-up questions, or redirect their approach. * **In-process mode**: use Shift+Down to cycle through teammates, then type to send them a message. Press Enter to view a teammate's session, then Escape to interrupt their current turn. Press Ctrl+T to toggle the task list. * **Split-pane mode**: click into a teammate's pane to interact with their session directly. Each teammate has a full view of their own terminal. ### Assign and claim tasks The shared task list coordinates work across the team. The lead creates tasks and teammates work through them. Tasks have three states: pending, in progress, and completed. Tasks can also depend on other tasks: a pending task with unresolved dependencies cannot be claimed until those dependencies are completed. The lead can assign tasks explicitly, or teammates can self-claim: * **Lead assigns**: tell the lead which task to give to which teammate * **Self-claim**: after finishing a task, a teammate picks up the next unassigned, unblocked task on its own Task claiming uses file locking to prevent race conditions when multiple teammates try to claim the same task simultaneously. ### Shut down teammates To gracefully end a teammate's session: ```text theme={null} Ask the researcher teammate to shut down ``` The lead sends a shutdown request. The teammate can approve, exiting gracefully, or reject with an explanation. ### Clean up the team When you're done, ask the lead to clean up: ```text theme={null} Clean up the team ``` This removes the shared team resources. When the lead runs cleanup, it checks for active teammates and fails if any are still running, so shut them down first. <Warning> Always use the lead to clean up. Teammates should not run cleanup because their team context may not resolve correctly, potentially leaving resources in an inconsistent state. </Warning> ### Enforce quality gates with hooks Use [hooks](../07-Hooks/hooks-9168ed62a4.md) to enforce rules when teammates finish work or tasks are created or completed: * [`TeammateIdle`](/en/hooks#teammateidle): runs when a teammate is about to go idle. Exit with code 2 to send feedback and keep the teammate working. * [`TaskCreated`](/en/hooks#taskcreated): runs when a task is being created. Exit with code 2 to prevent creation and send feedback. * [`TaskCompleted`](/en/hooks#taskcompleted): runs when a task is being marked complete. Exit with code 2 to prevent completion and send feedback. ## How agent teams work This section covers the architecture and mechanics behind agent teams. If you want to start using them, see [Control your agent team](#control-your-agent-team) above. ### How Claude starts agent teams There are two ways agent teams get started: * **You request a team**: give Claude a task that benefits from parallel work and explicitly ask for an agent team. Claude creates one based on your instructions. * **Claude proposes a team**: if Claude determines your task would benefit from parallel work, it may suggest creating a team. You confirm before it proceeds. In both cases, you stay in control. Claude won't create a team without your approval. ### Architecture An agent team consists of: | Component | Role | | :------------ | :----------------------------------------------------------------------------------------- | | **Team lead** | The main Claude Code session that creates the team, spawns teammates, and coordinates work | | **Teammates** | Separate Claude Code instances that each work on assigned tasks | | **Task list** | Shared list of work items that teammates claim and complete | | **Mailbox** | Messaging system for communication between agents | See [Choose a display mode](#choose-a-display-mode) for display configuration options. Teammate messages arrive at the lead automatically. The system manages task dependencies automatically. When a teammate completes a task that other tasks depend on, blocked tasks unblock without manual intervention. Teams and tasks are stored locally: * **Team config**: `~/.claude/teams/{team-name}/config.json` * **Task list**: `~/.claude/tasks/{team-name}/` Claude Code generates both of these automatically when you create a team and updates them as teammates join, go idle, or leave. The team config holds runtime state such as session IDs and tmux pane IDs, so don't edit it by hand or pre-author it: your changes are overwritten on the next state update. To define reusable teammate roles, use [subagent definitions](#use-subagent-definitions-for-teammates) instead. The team config contains a `members` array with each teammate's name, agent ID, and agent type. Teammates can read this file to discover other team members. There is no project-level equivalent of the team config. A file like `.claude/teams/teams.json` in your project directory is not recognized as configuration; Claude treats it as an ordinary file. ### Use subagent definitions for teammates When spawning a teammate, you can reference a [subagent](create-custom-subagents-claude-code-docs-7dc93e85c0.md) type from any [subagent scope](/en/sub-agents#choose-the-subagent-scope): project, user, plugin, or CLI-defined. This lets you define a role once, such as a security-reviewer or test-runner, and reuse it both as a delegated subagent and as an agent team teammate. To use a subagent definition, mention it by name when asking Claude to spawn the teammate: ```text theme={null} Spawn a teammate using the security-reviewer agent type to audit the auth module. ``` The teammate honors that definition's `tools` allowlist and `model`, and the definition's body is appended to the teammate's system prompt as additional instructions rather than replacing it. Team coordination tools such as `SendMessage` and the task management tools are always available to a teammate even when `tools` restricts other tools. <Note> The `skills` and `mcpServers` frontmatter fields in a subagent definition are not applied when that definition runs as a teammate. Teammates load skills and MCP servers from your project and user settings, the same as a regular session. </Note> ### Permissions Teammates start with the lead's permission settings. If the lead runs with an elevated permission mode, all teammates inherit it. After spawning, you can change individual teammate modes, but you can't set per-teammate modes at spawn time. ### Context and communication Each teammate has its own context window. When spawned, a teammate loads the same project context as a regular session: CLAUDE.md, MCP servers, and skills. It also receives the spawn prompt from the lead. The lead's conversation history does not carry over. **How teammates share information:** * **Automatic message delivery**: when teammates send messages, they're delivered automatically to recipients. The lead doesn't need to poll for updates. * **Idle notifications**: when a teammate finishes and stops, they automatically notify the lead. * **Shared task list**: all agents can see task status and claim available work. * **Teammate messaging**: send a message to one specific teammate by name. To reach everyone, send one message per recipient. The lead assigns every teammate a name when it spawns them, and any teammate can message any other by that name. To get predictable names you can reference in later prompts, tell the lead what to call each teammate in your spawn instruction. ### Token usage Agent teams use significantly more tokens than a single session. Each teammate has its own context window, and token usage scales with the number of active teammates. For research, review, and new feature work, the extra tokens are usually worthwhile. For routine tasks, a single session is more cost-effective. See [agent team token costs](/en/costs#agent-team-token-costs) for usage guidance. ## Use case examples These examples show how agent teams handle tasks where parallel exploration adds value. ### Run a parallel code review A single reviewer tends to gravitate toward one type of issue at a time. Splitting review criteria into independent domains means security, performance, and test coverage all get thorough attention simultaneously. The prompt assigns each teammate a distinct lens so they don't overlap: ```text theme={null} Create an agent team to review PR #142. Spawn three reviewers: - One focused on security implications - One checking performance impact - One validating test coverage Have them each review and report findings. ``` Each reviewer works from the same PR but applies a different filter. The lead synthesizes findings across all three after they finish. ### Investigate with competing hypotheses When the root cause is unclear, a single agent tends to find one plausible explanation and stop looking. The prompt fights this by making teammates explicitly adversarial: each one's job is not only to investigate its own theory but to challenge the others'. ```text theme={null} Users report the app exits after one message instead of staying connected. Spawn 5 agent teammates to investigate different hypotheses. Have them talk to each other to try to disprove each other's theories, like a scientific debate. Update the findings doc with whatever consensus emerges. ``` The debate structure is the key mechanism here. Sequential investigation suffers from anchoring: once one theory is explored, subsequent investigation is biased toward it. With multiple independent investigators actively trying to disprove each other, the theory that survives is much more likely to be the actual root cause. ## Best practices ### Give teammates enough context Teammates load project context automatically, including CLAUDE.md, MCP servers, and skills, but they don't inherit the lead's conversation history. See [Context and communication](#context-and-communication) for details. Include task-specific details in the spawn prompt: ```text theme={null} Spawn a security reviewer teammate with the prompt: "Review the authentication module at src/auth/ for security vulnerabilities. Focus on token handling, session management, and input validation. The app uses JWT tokens stored in httpOnly cookies. Report any issues with severity ratings." ``` ### Choose an appropriate team size There's no hard limit on the number of teammates, but practical constraints apply: * **Token costs scale linearly**: each teammate has its own context window and consumes tokens independently. See [agent team token costs](/en/costs#agent-team-token-costs) for details. * **Coordination overhead increases**: more teammates means more communication, task coordination, and potential for conflicts * **Diminishing returns**: beyond a certain point, additional teammates don't speed up work proportionally Start with 3-5 teammates for most workflows. This balances parallel work with manageable coordination. The examples in this guide use 3-5 teammates because that range works well across different task types. Having 5-6 [tasks](/en/agent-teams#architecture) per teammate keeps everyone productive without excessive context switching. If you have 15 independent tasks, 3 teammates is a good starting point. Scale up only when the work genuinely benefits from having teammates work simultaneously. Three focused teammates often outperform five scattered ones. ### Size tasks appropriately * **Too small**: coordination overhead exceeds the benefit * **Too large**: teammates work too long without check-ins, increasing risk of wasted effort * **Just right**: self-contained units that produce a clear deliverable, such as a function, a test file, or a review <Tip> The lead breaks work into tasks and assigns them to teammates automatically. If it isn't creating enough tasks, ask it to split the work into smaller pieces. Having 5-6 tasks per teammate keeps everyone productive and lets the lead reassign work if someone gets stuck. </Tip> ### Wait for teammates to finish Sometimes the lead starts implementing tasks itself instead of waiting for teammates. If you notice this: ```text theme={null} Wait for your teammates to complete their tasks before proceeding ``` ### Start with research and review If you're new to agent teams, start with tasks that have clear boundaries and don't require writing code: reviewing a PR, researching a library, or investigating a bug. These tasks show the value of parallel exploration without the coordination challenges that come with parallel implementation. ### Avoid file conflicts Two teammates editing the same file leads to overwrites. Break the work so each teammate owns a different set of files. ### Monitor and steer Check in on teammates' progress, redirect approaches that aren't working, and synthesize findings as they come in. Letting a team run unattended for too long increases the risk of wasted effort. ## Troubleshooting ### Teammates not appearing If teammates aren't appearing after you ask Claude to create a team: * In in-process mode, teammates may already be running but not visible. Press Shift+Down to cycle through active teammates. * Check that the task you gave Claude was complex enough to warrant a team. Claude decides whether to spawn teammates based on the task. * If you explicitly requested split panes, ensure tmux is installed and available in your PATH: ```bash theme={null} which tmux ``` * For iTerm2, verify the `it2` CLI is installed and the Python API is enabled in iTerm2 preferences. ### Too many permission prompts Teammate permission requests bubble up to the lead, which can create friction. Pre-approve common operations in your [permission settings](../02-Claude-Code-CLI/configure-permissions-claude-code-docs-7b0e64d485.md) before spawning teammates to reduce interruptions. ### Teammates stopping on errors Teammates may stop after encountering errors instead of recovering. Check their output using Shift+Down in in-process mode or by clicking the pane in split mode, then either: * Give them additional instructions directly * Spawn a replacement teammate to continue the work ### Lead shuts down before work is done The lead may decide the team is finished before all tasks are actually complete. If this happens, tell it to keep going. You can also tell the lead to wait for teammates to finish before proceeding if it starts doing work instead of delegating. ### Orphaned tmux sessions If a tmux session persists after the team ends, it may not have been fully cleaned up. List sessions and kill the one created by the team: ```bash theme={null} tmux ls tmux kill-session -t <session-name> ``` ## Limitations Agent teams are experimental. Current limitations to be aware of: * **No session resumption with in-process teammates**: `/resume` and `/rewind` do not restore in-process teammates. After resuming a session, the lead may attempt to message teammates that no longer exist. If this happens, tell the lead to spawn new teammates. * **Task status can lag**: teammates sometimes fail to mark tasks as completed, which blocks dependent tasks. If a task appears stuck, check whether the work is actually done and update the task status manually or tell the lead to nudge the teammate. * **Shutdown can be slow**: teammates finish their current request or tool call before shutting down, which can take time. * **One team per session**: a lead can only manage one team at a time. Clean up the current team before starting a new one. * **No nested teams**: teammates cannot spawn their own teams or teammates. Only the lead can manage the team. * **Lead is fixed**: the session that creates the team is the lead for its lifetime. You can't promote a teammate to lead or transfer leadership. * **Permissions set at spawn**: all teammates start with the lead's permission mode. You can change individual teammate modes after spawning, but you can't set per-teammate modes at spawn time. * **Split panes require tmux or iTerm2**: the default in-process mode works in any terminal. Split-pane mode isn't supported in VS Code's integrated terminal, Windows Terminal, or Ghostty. <Tip> **`CLAUDE.md` works normally**: teammates read `CLAUDE.md` files from their working directory. Use this to provide project-specific guidance to all teammates. </Tip> ## Next steps Explore related approaches for parallel work and delegation: * **Lightweight delegation**: [subagents](create-custom-subagents-claude-code-docs-7dc93e85c0.md) spawn helper agents for research or verification within your session, better for tasks that don't need inter-agent coordination * **Manual parallel sessions**: [Git worktrees](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) let you run multiple Claude Code sessions yourself without automated team coordination * **Compare approaches**: see the [subagent vs agent team](/en/features-overview#compare-similar-features) comparison for a side-by-side breakdown --- ## agent-teams.md # Orchestrate teams of Claude Code sessions Coordinate multiple Claude Code instances working together as a team, with shared tasks, inter-agent messaging, and centralized management. > **Warning:** Agent teams are experimental and disabled by default. Enable them by adding `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` to your settings.json or environment. Agent teams have known limitations around session resumption, task coordination, and shutdown behavior. Agent teams let you coordinate multiple Claude Code instances working together. One session acts as the team lead, coordinating work, assigning tasks, and synthesizing results. Teammates work independently, each in its own context window, and communicate directly with each other. Unlike subagents, which run within a single session and can only report back to the main agent, you can also interact with individual teammates directly without going through the lead. > Agent teams require Claude Code v2.1.32 or later. Check your version with `claude --version`. ## When to use agent teams Agent teams are most effective for tasks where parallel exploration adds real value: - **Research and review**: multiple teammates can investigate different aspects of a problem simultaneously, then share and challenge each other's findings - **New modules or features**: teammates can each own a separate piece without stepping on each other - **Debugging with competing hypotheses**: teammates test different theories in parallel and converge on the answer faster - **Cross-layer coordination**: changes that span frontend, backend, and tests, each owned by a different teammate Agent teams add coordination overhead and use significantly more tokens than a single session. They work best when teammates can operate independently. For sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective. ### Compare with subagents Both agent teams and subagents let you parallelize work, but they operate differently. Choose based on whether your workers need to communicate with each other: | | Subagents | Agent teams | | :---------------- | :----------------------------------------------- | :-------------------------------------------------- | | **Context** | Own context window; results return to the caller | Own context window; fully independent | | **Communication** | Report results back to the main agent only | Teammates message each other directly | | **Coordination** | Main agent manages all work | Shared task list with self-coordination | | **Best for** | Focused tasks where only the result matters | Complex work requiring discussion and collaboration | | **Token cost** | Lower: results summarized back to main context | Higher: each teammate is a separate Claude instance | Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own. ## Enable agent teams Agent teams are disabled by default. Enable them by setting the `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` environment variable to `1`, either in your shell environment or through settings.json: ```json { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } } ``` ## Start your first agent team After enabling agent teams, tell Claude to create an agent team and describe the task and the team structure you want in natural language. Claude creates the team, spawns teammates, and coordinates work based on your prompt. This example works well because the three roles are independent and can explore the problem without waiting on each other: ``` I'm designing a CLI tool that helps developers track TODO comments across their codebase. Create an agent team to explore this from different angles: one teammate on UX, one on technical architecture, one playing devil's advocate. ``` From there, Claude creates a team with a shared task list, spawns teammates for each perspective, has them explore the problem, synthesizes findings, and attempts to clean up the team when finished. The lead's terminal lists all teammates and what they're working on. Use Shift+Down to cycle through teammates and message them directly. After the last teammate, Shift+Down wraps back to the lead. ## Control your agent team Tell the lead what you want in natural language. It handles team coordination, task assignment, and delegation based on your instructions. ### Choose a display mode Agent teams support two display modes: - **In-process**: all teammates run inside your main terminal. Use Shift+Down to cycle through teammates and type to message them directly. Works in any terminal, no extra setup required. - **Split panes**: each teammate gets its own pane. You can see everyone's output at once and click into a pane to interact directly. Requires tmux, or iTerm2. The default is `"auto"`, which uses split panes if you're already running inside a tmux session, and in-process otherwise. The `"tmux"` setting enables split-pane mode and auto-detects whether to use tmux or iTerm2 based on your terminal. To override, set `teammateMode` in your global config at `~/.claude.json`: ```json { "teammateMode": "in-process" } ``` To force in-process mode for a single session, pass it as a flag: ```bash claude --teammate-mode in-process ``` ### Specify teammates and models Claude decides the number of teammates to spawn based on your task, or you can specify exactly what you want: ``` Create a team with 4 teammates to refactor these modules in parallel. Use Sonnet for each teammate. ``` ### Require plan approval for teammates For complex or risky tasks, you can require teammates to plan before implementing. The teammate works in read-only plan mode until the lead approves their approach: ``` Spawn an architect teammate to refactor the authentication module. Require plan approval before they make any changes. ``` When a teammate finishes planning, it sends a plan approval request to the lead. The lead reviews the plan and either approves it or rejects it with feedback. If rejected, the teammate stays in plan mode, revises based on the feedback, and resubmits. Once approved, the teammate exits plan mode and begins implementation. ### Talk to teammates directly Each teammate is a full, independent Claude Code session. You can message any teammate directly to give additional instructions, ask follow-up questions, or redirect their approach. - **In-process mode**: use Shift+Down to cycle through teammates, then type to send them a message. Press Enter to view a teammate's session, then Escape to interrupt their current turn. Press Ctrl+T to toggle the task list. - **Split-pane mode**: click into a teammate's pane to interact with their session directly. ### Assign and claim tasks The shared task list coordinates work across the team. The lead creates tasks and teammates work through them. Tasks have three states: pending, in progress, and completed. Tasks can also depend on other tasks. The lead can assign tasks explicitly, or teammates can self-claim: - **Lead assigns**: tell the lead which task to give to which teammate - **Self-claim**: after finishing a task, a teammate picks up the next unassigned, unblocked task on its own Task claiming uses file locking to prevent race conditions when multiple teammates try to claim the same task simultaneously. ### Shut down teammates To gracefully end a teammate's session: ``` Ask the researcher teammate to shut down ``` The lead sends a shutdown request. The teammate can approve, exiting gracefully, or reject with an explanation. ### Clean up the team When you're done, ask the lead to clean up: ``` Clean up the team ``` This removes the shared team resources. When the lead runs cleanup, it checks for active teammates and fails if any are still running, so shut them down first. ### Enforce quality gates with hooks Use hooks to enforce rules when teammates finish work or tasks are created or completed: - `TeammateIdle`: runs when a teammate is about to go idle. Exit with code 2 to send feedback and keep the teammate working. - `TaskCreated`: runs when a task is being created. Exit with code 2 to prevent creation and send feedback. - `TaskCompleted`: runs when a task is being marked complete. Exit with code 2 to prevent completion and send feedback. ## How agent teams work ### Architecture An agent team consists of: | Component | Role | | :------------ | :----------------------------------------------------------------------------------------- | | **Team lead** | The main Claude Code session that creates the team, spawns teammates, and coordinates work | | **Teammates** | Separate Claude Code instances that each work on assigned tasks | | **Task list** | Shared list of work items that teammates claim and complete | | **Mailbox** | Messaging system for communication between agents | Teams and tasks are stored locally: - **Team config**: `~/.claude/teams/{team-name}/config.json` - **Task list**: `~/.claude/tasks/{team-name}/` ### Use subagent definitions for teammates When spawning a teammate, you can reference a subagent type from any subagent scope: project, user, plugin, or CLI-defined. This lets you define a role once, such as a security-reviewer or test-runner, and reuse it both as a delegated subagent and as an agent team teammate. ``` Spawn a teammate using the security-reviewer agent type to audit the auth module. ``` ### Permissions Teammates start with the lead's permission settings. If the lead runs with an elevated permission mode, all teammates inherit it. ### Context and communication Each teammate has its own context window. When spawned, a teammate loads the same project context as a regular session: CLAUDE.md, MCP servers, and skills. **How teammates share information:** - **Automatic message delivery**: when teammates send messages, they're delivered automatically to recipients - **Idle notifications**: when a teammate finishes and stops, they automatically notify the lead - **Shared task list**: all agents can see task status and claim available work **Teammate messaging:** - **message**: send a message to one specific teammate - **broadcast**: send to all teammates simultaneously ### Token usage Agent teams use significantly more tokens than a single session. Each teammate has its own context window, and token usage scales with the number of active teammates. ## Use case examples ### Run a parallel code review ``` Create an agent team to review PR #142. Spawn three reviewers: - One focused on security implications - One checking performance impact - One validating test coverage Have them each review and report findings. ``` ### Investigate with competing hypotheses ``` Users report the app exits after one message instead of staying connected. Spawn 5 agent teammates to investigate different hypotheses. Have them talk to each other to try to disprove each other's theories, like a scientific debate. Update the findings doc with whatever consensus emerges. ``` ## Best practices ### Give teammates enough context Include task-specific details in the spawn prompt: ``` Spawn a security reviewer teammate with the prompt: "Review the authentication module at src/auth/ for security vulnerabilities. Focus on token handling, session management, and input validation." ``` ### Choose an appropriate team size Start with 3-5 teammates for most workflows. Having 5-6 tasks per teammate keeps everyone productive without excessive context switching. ### Size tasks appropriately - **Too small**: coordination overhead exceeds the benefit - **Too large**: teammates work too long without check-ins - **Just right**: self-contained units that produce a clear deliverable ### Avoid file conflicts Two teammates editing the same file leads to overwrites. Break the work so each teammate owns a different set of files. ## Limitations - **No session resumption with in-process teammates**: `/resume` and `/rewind` do not restore in-process teammates - **Task status can lag**: teammates sometimes fail to mark tasks as completed - **Shutdown can be slow**: teammates finish their current request before shutting down - **One team per session**: clean up the current team before starting a new one - **No nested teams**: teammates cannot spawn their own teams - **Lead is fixed**: the session that creates the team is the lead for its lifetime - **Permissions set at spawn**: all teammates start with the lead's permission mode - **Split panes require tmux or iTerm2**: not supported in VS Code's integrated terminal, Windows Terminal, or Ghostty ## See Also - [Subagents](create-custom-subagents-claude-code-docs-7dc93e85c0.md) - [Git worktrees](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) --- ## architecture-diagram.md # Observability Agent Architecture ```mermaid graph TD User[User] --> Agent[Observability Agent] Agent --> GitHub[GitHub MCP Server] Agent --> Tools[Tools] Tools --> WebSearch[WebSearch] Tools --> Read[Read Files] GitHub --> Docker[Docker Container] Docker --> API[GitHub API] style Agent fill:#f9f,stroke:#333,stroke-width:3px style GitHub fill:#bbf,stroke:#333,stroke-width:2px ``` # Communication Flow Diagram ```mermaid sequenceDiagram participant User participant Agent participant MCP as GitHub MCP participant API as GitHub API User->>Agent: Query about repo Agent->>MCP: Connect via Docker Agent->>MCP: Request data MCP->>API: Fetch info API-->>MCP: Return data MCP-->>Agent: Process results Agent-->>User: Display answer ``` --- ## basic-workflows.md ## Basic Multi-LLM Workflows This notebook demonstrates three simple multi-LLM workflows. They trade off cost or latency for potentially improved task performances: 1. **Prompt-Chaining**: Decomposes a task into sequential subtasks, where each step builds on previous results 2. **Parallelization**: Distributes independent subtasks across multiple LLMs for concurrent processing 3. **Routing**: Dynamically selects specialized LLM paths based on input characteristics Note: These are sample implementations meant to demonstrate core concepts - not production code. ::: ::: {.cell .code execution_count="1"} ``` python from concurrent.futures import ThreadPoolExecutor from util import extract_xml, llm_call ``` ::: ::: {.cell .code} ``` python def chain(input: str, prompts: list[str]) -> str: """Chain multiple LLM calls sequentially, passing results between steps.""" result = input for i, prompt in enumerate(prompts, 1): print(f"\nStep {i}:") result = llm_call(f"{prompt}\nInput: {result}") print(result) return result def parallel(prompt: str, inputs: list[str], n_workers: int = 3) -> list[str]: """Process multiple inputs concurrently with the same prompt.""" with ThreadPoolExecutor(max_workers=n_workers) as executor: futures = [executor.submit(llm_call, f"{prompt}\nInput: {x}") for x in inputs] return [f.result() for f in futures] def route(input: str, routes: dict[str, str]) -> str: """Route input to specialized prompt using content classification.""" # First determine appropriate route using LLM with chain-of-thought print(f"\nAvailable routes: {list(routes.keys())}") selector_prompt = f""" Analyze the input and select the most appropriate support team from these options: {list(routes.keys())} First explain your reasoning, then provide your selection in this XML format: <reasoning> Brief explanation of why this ticket should be routed to a specific team. Consider key terms, user intent, and urgency level. </reasoning> <selection> The chosen team name </selection> Input: {input}""".strip() route_response = llm_call(selector_prompt) reasoning = extract_xml(route_response, "reasoning") route_key = extract_xml(route_response, "selection").strip().lower() print("Routing Analysis:") print(reasoning) print(f"\nSelected route: {route_key}") # Process input with selected specialized prompt selected_prompt = routes[route_key] return llm_call(f"{selected_prompt}\nInput: {input}") ``` ::: ::: {.cell .markdown} ## Example Usage Below are practical examples demonstrating each workflow: 1. Chain workflow for structured data extraction and formatting 2. Parallelization workflow for stakeholder impact analysis 3. Route workflow for customer support ticket handling ::: :::: {.cell .code} ``` python # Example 1: Chain workflow for structured data extraction and formatting # Each step progressively transforms raw text into a formatted table data_processing_steps = [ """Extract only the numerical values and their associated metrics from the text. Format each as 'value: metric' on a new line. Example format: 92: customer satisfaction 45%: revenue growth""", """Convert all numerical values to percentages where possible. If not a percentage or points, convert to decimal (e.g., 92 points -> 92%). Keep one number per line. Example format: 92%: customer satisfaction 45%: revenue growth""", """Sort all lines in descending order by numerical value. Keep the format 'value: metric' on each line. Example: 92%: customer satisfaction 87%: employee satisfaction""", """Format the sorted data as a markdown table with columns: | Metric | Value | |:--|--:| | Customer Satisfaction | 92% |""", ] report = """ Q3 Performance Summary: Our customer satisfaction score rose to 92 points this quarter. Revenue grew by 45% compared to last year. Market share is now at 23% in our primary market. Customer churn decreased to 5% from 8%. New user acquisition cost is $43 per user. Product adoption rate increased to 78%. Employee satisfaction is at 87 points. Operating margin improved to 34%. """ print("\nInput text:") print(report) formatted_result = chain(report, data_processing_steps) ``` ::: {.output .stream .stdout} Input text: Q3 Performance Summary: Our customer satisfaction score rose to 92 points this quarter. Revenue grew by 45% compared to last year. Market share is now at 23% in our primary market. Customer churn decreased to 5% from 8%. New user acquisition cost is $43 per user. Product adoption rate increased to 78%. Employee satisfaction is at 87 points. Operating margin improved to 34%. Step 1: 92: customer satisfaction points 45%: revenue growth 23%: market share 5%: customer churn 8%: previous customer churn $43: user acquisition cost 78%: product adoption rate 87: employee satisfaction points 34%: operating margin Step 2: 92%: customer satisfaction 45%: revenue growth 23%: market share 5%: customer churn 8%: previous customer churn 43.0: user acquisition cost 78%: product adoption rate 87%: employee satisfaction 34%: operating margin Step 3: Here are the lines sorted in descending order by numerical value: 92%: customer satisfaction 87%: employee satisfaction 78%: product adoption rate 45%: revenue growth 43.0: user acquisition cost 34%: operating margin 23%: market share 8%: previous customer churn 5%: customer churn Step 4: | Metric | Value | |:--|--:| | Customer Satisfaction | 92% | | Employee Satisfaction | 87% | | Product Adoption Rate | 78% | | Revenue Growth | 45% | | User Acquisition Cost | 43.0 | | Operating Margin | 34% | | Market Share | 23% | | Previous Customer Churn | 8% | | Customer Churn | 5% | ::: :::: :::: {.cell .code} ``` python # Example 2: Parallelization workflow for stakeholder impact analysis # Process impact analysis for multiple stakeholder groups concurrently stakeholders = [ """Customers: - Price sensitive - Want better tech - Environmental concerns""", """Employees: - Job security worries - Need new skills - Want clear direction""", """Investors: - Expect growth - Want cost control - Risk concerns""", """Suppliers: - Capacity constraints - Price pressures - Tech transitions""", ] impact_results = parallel( """Analyze how market changes will impact this stakeholder group. Provide specific impacts and recommended actions. Format with clear sections and priorities.""", stakeholders, ) for result in impact_results: print(result) print("+" * 80) ``` ::: {.output .stream .stdout} MARKET IMPACT ANALYSIS FOR CUSTOMERS ================================== HIGH PRIORITY IMPACTS ------------------- 1. Price Sensitivity - Rising inflation and costs likely to reduce purchasing power - Increased competition for value-oriented products - Risk of trading down to lower-cost alternatives Recommended Actions: • Introduce tiered pricing options • Develop value-focused product lines • Create loyalty programs with price benefits • Highlight total cost of ownership benefits 2. Technology Demands - Accelerating tech advancement creating higher expectations - Integration of AI and smart features becoming standard - Mobile/digital-first experience requirements Recommended Actions: • Accelerate digital transformation initiatives • Invest in user experience improvements • Develop smart product features • Provide tech education and support MEDIUM PRIORITY IMPACTS ---------------------- 3. Environmental Consciousness - Growing demand for sustainable products - Increased scrutiny of environmental practices - Willingness to pay premium for eco-friendly options Recommended Actions: • Develop eco-friendly product lines • Improve packaging sustainability • Communicate environmental initiatives • Create recycling programs MONITORING & METRICS ------------------- • Track customer satisfaction scores • Monitor price sensitivity metrics • Measure adoption of new technologies • Track sustainability-related purchases • Regular customer feedback surveys RISK FACTORS ------------ • Economic downturn impact on spending • Tech adoption learning curve • Cost vs. sustainability trade-offs • Competition from specialized providers TIMELINE PRIORITIES ------------------ Immediate (0-3 months): - Price optimization - Digital experience improvements Short-term (3-12 months): - Tech feature development - Sustainability initiatives Long-term (12+ months): - Advanced technology integration - Comprehensive eco-friendly transformation ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ MARKET IMPACT ANALYSIS FOR EMPLOYEES Priority 1: Job Security Concerns Impacts: • Market volatility creating uncertainty about positions • Potential restructuring or role changes • Stress affecting productivity and morale Recommended Actions: - Provide regular, transparent communications about company stability - Create clear performance metrics tied to job security - Establish early warning systems for at-risk positions - Develop retention programs for key talent Priority 2: Skills Gap & Development Impacts: • Current skills becoming outdated due to market changes • New technologies/processes requiring additional training • Competitive disadvantage without upskilling Recommended Actions: - Conduct skills gap analysis - Implement targeted training programs - Provide learning stipends/resources - Create mentorship programs - Partner with educational institutions Priority 3: Strategic Direction & Leadership Impacts: • Uncertainty about career paths • Lack of alignment with company goals • Reduced engagement and commitment Recommended Actions: - Develop clear career progression frameworks - Create individual development plans - Increase leadership visibility and communication - Establish regular strategy updates and town halls - Implement feedback mechanisms Implementation Timeline: Short-term (0-3 months): • Begin transparent communications • Launch initial training assessments • Start regular strategy updates Medium-term (3-6 months): • Roll out training programs • Implement retention initiatives • Develop career frameworks Long-term (6+ months): • Monitor and adjust programs • Measure effectiveness • Refine strategic alignment Success Metrics: • Employee retention rates • Skills assessment scores • Employee satisfaction surveys • Productivity measures • Career progression rates ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ MARKET IMPACT ANALYSIS FOR INVESTORS Priority 1: Financial Performance Impacts: • Market volatility may affect expected returns • Economic uncertainty could slow growth targets • Cost inflation may squeeze margins Recommended Actions: - Implement enhanced financial reporting and forecasting - Develop contingency plans for different market scenarios - Identify cost optimization opportunities - Consider strategic M&A opportunities at lower valuations Priority 2: Risk Management Impacts: • Increased market risks require stronger controls • New regulatory requirements possible • Competitive landscape changes Recommended Actions: - Strengthen risk management frameworks - Increase frequency of risk assessments - Diversify investment portfolio - Maintain higher cash reserves Priority 3: Communication & Transparency Impacts: • Heightened investor scrutiny expected • Need for more detailed market analysis • Demand for regular updates Recommended Actions: - Enhance investor communications - Provide more frequent market updates - Share detailed mitigation strategies - Maintain open dialogue with key stakeholders Timeline Recommendations: Short-term (0-6 months): - Implement enhanced reporting - Review risk controls - Increase communication frequency Medium-term (6-18 months): - Execute cost optimization - Develop new growth strategies - Build strategic partnerships Long-term (18+ months): - Evaluate market position - Adjust investment strategy - Consider structural changes Key Success Metrics: • ROI performance • Cost reduction achievements • Risk incident rates • Investor satisfaction scores ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ MARKET IMPACT ANALYSIS FOR SUPPLIERS HIGH PRIORITY IMPACTS: 1. Capacity Constraints - Reduced ability to meet customer demand - Risk of losing market share to competitors - Strain on existing infrastructure and resources - Potential breach of supply agreements Recommended Actions: • Invest in capacity expansion • Implement better demand forecasting • Develop contingency supplier network • Negotiate flexible delivery terms 2. Price Pressures - Squeezed profit margins - Difficulty maintaining quality standards - Risk of losing customers to lower-cost alternatives - Cash flow challenges Recommended Actions: • Review cost structure and identify efficiencies • Negotiate long-term contracts with price adjustment clauses • Explore automation/process improvements • Consider strategic partnerships to share costs 3. Technology Transitions - Need for new equipment and systems - Training requirements for workforce - R&D investment demands - Risk of obsolescence Recommended Actions: • Develop technology roadmap • Invest in workforce training • Seek innovation partnerships • Phase implementation of new technologies MEDIUM PRIORITY CONSIDERATIONS: - Supply chain resilience - Quality control processes - Market positioning - Customer relationship management LONG-TERM STRATEGIC RECOMMENDATIONS: 1. Build financial reserves for future investments 2. Develop diversification strategies 3. Create innovation partnerships 4. Strengthen customer relationships 5. Invest in sustainability initiatives MONITORING METRICS: • Production capacity utilization • Price competitiveness • Technology adoption rates • Customer satisfaction levels • Market share trends ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ::: :::: :::: {.cell .code} ``` python # Example 3: Route workflow for customer support ticket handling # Route support tickets to appropriate teams based on content analysis support_routes = { "billing": """You are a billing support specialist. Follow these guidelines: 1. Always start with "Billing Support Response:" 2. First acknowledge the specific billing issue 3. Explain any charges or discrepancies clearly 4. List concrete next steps with timeline 5. End with payment options if relevant Keep responses professional but friendly. Input: """, "technical": """You are a technical support engineer. Follow these guidelines: 1. Always start with "Technical Support Response:" 2. List exact steps to resolve the issue 3. Include system requirements if relevant 4. Provide workarounds for common problems 5. End with escalation path if needed Use clear, numbered steps and technical details. Input: """, "account": """You are an account security specialist. Follow these guidelines: 1. Always start with "Account Support Response:" 2. Prioritize account security and verification 3. Provide clear steps for account recovery/changes 4. Include security tips and warnings 5. Set clear expectations for resolution time Maintain a serious, security-focused tone. Input: """, "product": """You are a product specialist. Follow these guidelines: 1. Always start with "Product Support Response:" 2. Focus on feature education and best practices 3. Include specific examples of usage 4. Link to relevant documentation sections 5. Suggest related features that might help Be educational and encouraging in tone. Input: """, } # Test with different support tickets tickets = [ """Subject: Can't access my account Message: Hi, I've been trying to log in for the past hour but keep getting an 'invalid password' error. I'm sure I'm using the right password. Can you help me regain access? This is urgent as I need to submit a report by end of day. - John""", """Subject: Unexpected charge on my card Message: Hello, I just noticed a charge of $49.99 on my credit card from your company, but I thought I was on the $29.99 plan. Can you explain this charge and adjust it if it's a mistake? Thanks, Sarah""", """Subject: How to export data? Message: I need to export all my project data to Excel. I've looked through the docs but can't figure out how to do a bulk export. Is this possible? If so, could you walk me through the steps? Best regards, Mike""", ] print("Processing support tickets...\n") for i, ticket in enumerate(tickets, 1): print(f"\nTicket {i}:") print("-" * 40) print(ticket) print("\nResponse:") print("-" * 40) response = route(ticket, support_routes) print(response) print("+" * 80) ``` ::: {.output .stream .stdout} Processing support tickets... Ticket 1: ---------------------------------------- Subject: Can't access my account Message: Hi, I've been trying to log in for the past hour but keep getting an 'invalid password' error. I'm sure I'm using the right password. Can you help me regain access? This is urgent as I need to submit a report by end of day. - John Response: ---------------------------------------- Available routes: ['billing', 'technical', 'account', 'product'] Routing Analysis: This issue is clearly related to account access and authentication problems. The user is experiencing login difficulties with their password, which is a core account security and access issue. While there might be technical aspects involved, the primary concern is account access restoration. The urgency mentioned by the user and the nature of the problem (password/login issues) makes this a typical account support case. Account team specialists are best equipped to handle password resets, account verification, and access restoration procedures. Selected route: account Account Support Response: Dear John, I understand your urgency regarding account access. Before proceeding with account recovery, we must verify your identity to maintain security protocols. Immediate Steps for Account Recovery: 1. Visit our secure password reset page at [secure portal URL] 2. Click "Forgot Password" 3. Enter your email address associated with the account 4. Follow the verification instructions sent to your email Important Security Notes: • The reset link expires in 30 minutes • Do not share reset links or verification codes with anyone • Ensure you're on our official website (check for https:// and correct domain) WARNING: If you're unable to access your email or receive the reset link, additional verification will be required through our identity verification process. Additional Security Recommendations: - Enable Two-Factor Authentication after regaining access - Review recent account activity for unauthorized access - Update passwords on other accounts using similar credentials Expected Resolution Time: • Password reset: 5-10 minutes • Identity verification (if needed): 1-2 business hours If you continue experiencing issues, please respond with: 1. Account email address 2. Last successful login date 3. Any recent account changes For urgent report submission, please contact your supervisor about deadline extension while we secure your account. Regards, Account Security Team ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Ticket 2: ---------------------------------------- Subject: Unexpected charge on my card Message: Hello, I just noticed a charge of $49.99 on my credit card from your company, but I thought I was on the $29.99 plan. Can you explain this charge and adjust it if it's a mistake? Thanks, Sarah Response: ---------------------------------------- Available routes: ['billing', 'technical', 'account', 'product'] Routing Analysis: This is clearly a billing-related inquiry as it involves: 1. Questions about charges on a credit card 2. Pricing plan discrepancy ($49.99 vs $29.99) 3. Request for explanation of charges 4. Potential request for refund/adjustment The customer is specifically questioning a financial transaction, which falls under the billing team's expertise. While it touches on account plans, the core issue is about charges and payment processing. Selected route: billing Billing Support Response: Dear Sarah, I understand your concern about the unexpected charge of $49.99 when you were expecting to be billed $29.99. After reviewing the charge, this difference typically occurs when: 1. The promotional period for the $29.99 rate has ended 2. There was a plan upgrade or change in service tier 3. Additional services were added to the account To resolve this, I will: 1. Review your account history within 1 business day 2. Send you a detailed breakdown of the charges by email 3. If an error is confirmed, process a refund within 2-3 business days 4. Ensure your plan is set to the correct rate moving forward For immediate action, you can: - Review your current plan settings in your account dashboard - Send us your last billing statement for comparison - Provide any promotional codes you may have applied previously Payment options available: - If a refund is due, it will be credited to your original payment method - You can adjust your plan back to $29.99 through your account settings if eligible - Monthly auto-pay can be reviewed and updated as needed Please let me know if you need any additional information or have questions about these next steps. Best regards, Billing Support Team ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Ticket 3: ---------------------------------------- Subject: How to export data? Message: I need to export all my project data to Excel. I've looked through the docs but can't figure out how to do a bulk export. Is this possible? If so, could you walk me through the steps? Best regards, Mike Response: ---------------------------------------- Available routes: ['billing', 'technical', 'account', 'product'] Routing Analysis: This is clearly a technical/how-to question about product functionality. The user is asking for specific instructions about a feature (data export), and mentions looking through documentation. The question is about product usage and requires technical knowledge to explain the export process. Keywords like "export," "data," "bulk export," and reference to documentation strongly indicate this is a technical support matter rather than billing, account, or general product inquiry. Selected route: technical Technical Support Response: I'll help you export your project data to Excel. Here's the complete process: Steps to Export Data: 1. Log into your project dashboard 2. Navigate to "Project Settings" in the top right corner 3. Select "Data Management" from the dropdown menu 4. Click the "Export" tab 5. Choose "Bulk Export" option 6. Select data range and specific fields to export 7. Choose "Excel (.xlsx)" as the output format 8. Click "Generate Export" 9. Wait for the system to process (may take 1-15 minutes depending on data size) 10. Download the exported file when ready System Requirements: - Supported browsers: Chrome 90+, Firefox 88+, Edge 91+ - Minimum 2GB RAM available - Stable internet connection - Excel 2016 or later for opening exported files Common Issues & Workarounds: A. If export times out: - Break data into smaller date ranges - Export during off-peak hours - Use filters to reduce data size B. If download fails: - Clear browser cache - Use incognito/private window - Try a different supported browser Escalation Path: If you continue experiencing issues: 1. Contact your project administrator 2. Submit a ticket to technical support at support@company.com 3. Include your project ID and any error messages received 4. For urgent matters, call our support hotline: 1-800-XXX-XXXX ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ::: :::: --- ## building-effective-ai-agents-anthropic-55fb8f174d.md # Building effective agents Published Dec 19, 2024 We've worked with dozens of teams building LLM agents across industries. Consistently, the most successful implementations use simple, composable patterns rather than complex frameworks. Over the past year, we've worked with dozens of teams building large language model (LLM) agents across industries. Consistently, the most successful implementations weren't using complex frameworks or specialized libraries. Instead, they were building with simple, composable patterns. In this post, we share what we’ve learned from working with our customers and building agents ourselves, and give practical advice for developers on building effective agents. ## What are agents? "Agent" can be defined in several ways. Some customers define agents as fully autonomous systems that operate independently over extended periods, using various tools to accomplish complex tasks. Others use the term to describe more prescriptive implementations that follow predefined workflows. At Anthropic, we categorize all these variations as **agentic systems**, but draw an important architectural distinction between **workflows** and **agents**: - **Workflows** are systems where LLMs and tools are orchestrated through predefined code paths. - **Agents**, on the other hand, are systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks. Below, we will explore both types of agentic systems in detail. In Appendix 1 (“Agents in Practice”), we describe two domains where customers have found particular value in using these kinds of systems. ## When (and when not) to use agents When building applications with LLMs, we recommend finding the simplest solution possible, and only increasing complexity when needed. This might mean not building agentic systems at all. Agentic systems often trade latency and cost for better task performance, and you should consider when this tradeoff makes sense. When more complexity is warranted, workflows offer predictability and consistency for well-defined tasks, whereas agents are the better option when flexibility and model-driven decision-making are needed at scale. For many applications, however, optimizing single LLM calls with retrieval and in-context examples is usually enough. ## When and how to use frameworks There are many frameworks that make agentic systems easier to implement, including: - The [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview); - [Strands Agents SDK by AWS](https://strandsagents.com/latest/); - [Rivet](https://rivet.ironcladapp.com/), a drag and drop GUI LLM workflow builder; and - [Vellum](https://www.vellum.ai/), another GUI tool for building and testing complex workflows. These frameworks make it easy to get started by simplifying standard low-level tasks like calling LLMs, defining and parsing tools, and chaining calls together. However, they often create extra layers of abstraction that can obscure the underlying prompts ​​and responses, making them harder to debug. They can also make it tempting to add complexity when a simpler setup would suffice. We suggest that developers start by using LLM APIs directly: many patterns can be implemented in a few lines of code. If you do use a framework, ensure you understand the underlying code. Incorrect assumptions about what's under the hood are a common source of customer error. See our [cookbook](https://platform.claude.com/cookbook/patterns-agents-basic-workflows) for some sample implementations. ## Building blocks, workflows, and agents In this section, we’ll explore the common patterns for agentic systems we’ve seen in production. We'll start with our foundational building block—the augmented LLM—and progressively increase complexity, from simple compositional workflows to autonomous agents. ### Building block: The augmented LLM The basic building block of agentic systems is an LLM enhanced with augmentations such as retrieval, tools, and memory. Our current models can actively use these capabilities—generating their own search queries, selecting appropriate tools, and determining what information to retain. We recommend focusing on two key aspects of the implementation: tailoring these capabilities to your specific use case and ensuring they provide an easy, well-documented interface for your LLM. While there are many ways to implement these augmentations, one approach is through our recently released [Model Context Protocol](https://www.anthropic.com/news/model-context-protocol), which allows developers to integrate with a growing ecosystem of third-party tools with a simple [client implementation](https://modelcontextprotocol.io/tutorials/building-a-client#building-mcp-clients). For the remainder of this post, we'll assume each LLM call has access to these augmented capabilities. ### Workflow: Prompt chaining Prompt chaining decomposes a task into a sequence of steps, where each LLM call processes the output of the previous one. You can add programmatic checks (see "gate” in the diagram below) on any intermediate steps to ensure that the process is still on track. **When to use this workflow:** This workflow is ideal for situations where the task can be easily and cleanly decomposed into fixed subtasks. The main goal is to trade off latency for higher accuracy, by making each LLM call an easier task. **Examples where prompt chaining is useful:** - Generating Marketing copy, then translating it into a different language. - Writing an outline of a document, checking that the outline meets certain criteria, then writing the document based on the outline. ### Workflow: Routing Routing classifies an input and directs it to a specialized followup task. This workflow allows for separation of concerns, and building more specialized prompts. Without this workflow, optimizing for one kind of input can hurt performance on other inputs. **When to use this workflow:** Routing works well for complex tasks where there are distinct categories that are better handled separately, and where classification can be handled accurately, either by an LLM or a more traditional classification model/algorithm. **Examples where routing is useful:** - Directing different types of customer service queries (general questions, refund requests, technical support) into different downstream processes, prompts, and tools. - Routing easy/common questions to smaller, cost-efficient models like Claude Haiku 4.5 and hard/unusual questions to more capable models like Claude Sonnet 4.5 to optimize for best performance. ### Workflow: Parallelization LLMs can sometimes work simultaneously on a task and have their outputs aggregated programmatically. This workflow, parallelization, manifests in two key variations: - **Sectioning**: Breaking a task into independent subtasks run in parallel. - **Voting:** Running the same task multiple times to get diverse outputs. **When to use this workflow:** Parallelization is effective when the divided subtasks can be parallelized for speed, or when multiple perspectives or attempts are needed for higher confidence results. For complex tasks with multiple considerations, LLMs generally perform better when each consideration is handled by a separate LLM call, allowing focused attention on each specific aspect. **Examples where parallelization is useful:** - **Sectioning**: - Implementing guardrails where one model instance processes user queries while another screens them for inappropriate content or requests. This tends to perform better than having the same LLM call handle both guardrails and the core response. - Automating evals for evaluating LLM performance, where each LLM call evaluates a different aspect of the model’s performance on a given prompt. - **Voting**: - Reviewing a piece of code for vulnerabilities, where several different prompts review and flag the code if they find a problem. - Evaluating whether a given piece of content is inappropriate, with multiple prompts evaluating different aspects or requiring different vote thresholds to balance false positives and negatives. ### Workflow: Orchestrator-workers In the orchestrator-workers workflow, a central LLM dynamically breaks down tasks, delegates them to worker LLMs, and synthesizes their results. **When to use this workflow:** This workflow is well-suited for complex tasks where you can’t predict the subtasks needed (in coding, for example, the number of files that need to be changed and the nature of the change in each file likely depend on the task). Whereas it’s topographically similar, the key difference from parallelization is its flexibility—subtasks aren't pre-defined, but determined by the orchestrator based on the specific input. **Example where orchestrator-workers is useful:** - Coding products that make complex changes to multiple files each time. - Search tasks that involve gathering and analyzing information from multiple sources for possible relevant information. ### Workflow: Evaluator-optimizer In the evaluator-optimizer workflow, one LLM call generates a response while another provides evaluation and feedback in a loop. **When to use this workflow:** This workflow is particularly effective when we have clear evaluation criteria, and when iterative refinement provides measurable value. The two signs of good fit are, first, that LLM responses can be demonstrably improved when a human articulates their feedback; and second, that the LLM can provide such feedback. This is analogous to the iterative writing process a human writer might go through when producing a polished document. **Examples where evaluator-optimizer is useful:** - Literary translation where there are nuances that the translator LLM might not capture initially, but where an evaluator LLM can provide useful critiques. - Complex search tasks that require multiple rounds of searching and analysis to gather comprehensive information, where the evaluator decides whether further searches are warranted. ### Agents Agents are emerging in production as LLMs mature in key capabilities—understanding complex inputs, engaging in reasoning and planning, using tools reliably, and recovering from errors. Agents begin their work with either a command from, or interactive discussion with, the human user. Once the task is clear, agents plan and operate independently, potentially returning to the human for further information or judgement. During execution, it's crucial for the agents to gain “ground truth” from the environment at each step (such as tool call results or code execution) to assess its progress. Agents can then pause for human feedback at checkpoints or when encountering blockers. The task often terminates upon completion, but it’s also common to include stopping conditions (such as a maximum number of iterations) to maintain control. Agents can handle sophisticated tasks, but their implementation is often straightforward. They are typically just LLMs using tools based on environmental feedback in a loop. It is therefore crucial to design toolsets and their documentation clearly and thoughtfully. We expand on best practices for tool development in Appendix 2 ("Prompt Engineering your Tools"). **When to use agents:** Agents can be used for open-ended problems where it’s difficult or impossible to predict the required number of steps, and where you can’t hardcode a fixed path. The LLM will potentially operate for many turns, and you must have some level of trust in its decision-making. Agents' autonomy makes them ideal for scaling tasks in trusted environments. The autonomous nature of agents means higher costs, and the potential for compounding errors. We recommend extensive testing in sandboxed environments, along with the appropriate guardrails. **Examples where agents are useful:** The following examples are from our own implementations: - A coding Agent to resolve [SWE-bench tasks](https://www.anthropic.com/research/swe-bench-sonnet), which involve edits to many files based on a task description; - Our [“computer use” reference implementation](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo), where Claude uses a computer to accomplish tasks. ## Combining and customizing these patterns These building blocks aren't prescriptive. They're common patterns that developers can shape and combine to fit different use cases. The key to success, as with any LLM features, is measuring performance and iterating on implementations. To repeat: you should consider adding complexity *only* when it demonstrably improves outcomes. ## Summary Success in the LLM space isn't about building the most sophisticated system. It's about building the *right* system for your needs. Start with simple prompts, optimize them with comprehensive evaluation, and add multi-step agentic systems only when simpler solutions fall short. When implementing agents, we try to follow three core principles: 1. Maintain **simplicity** in your agent's design. 2. Prioritize **transparency** by explicitly showing the agent’s planning steps. 3. Carefully craft your agent-computer interface (ACI) through thorough tool **documentation and testing**. Frameworks can help you get started quickly, but don't hesitate to reduce abstraction layers and build with basic components as you move to production. By following these principles, you can create agents that are not only powerful but also reliable, maintainable, and trusted by their users. ### Acknowledgements Written by Erik S. and Barry Zhang. This work draws upon our experiences building agents at Anthropic and the valuable insights shared by our customers, for which we're deeply grateful. ## Appendix 1: Agents in practice Our work with customers has revealed two particularly promising applications for AI agents that demonstrate the practical value of the patterns discussed above. Both applications illustrate how agents add the most value for tasks that require both conversation and action, have clear success criteria, enable feedback loops, and integrate meaningful human oversight. ### A. Customer support Customer support combines familiar chatbot interfaces with enhanced capabilities through tool integration. This is a natural fit for more open-ended agents because: - Support interactions naturally follow a conversation flow while requiring access to external information and actions; - Tools can be integrated to pull customer data, order history, and knowledge base articles; - Actions such as issuing refunds or updating tickets can be handled programmatically; and - Success can be clearly measured through user-defined resolutions. Several companies have demonstrated the viability of this approach through usage-based pricing models that charge only for successful resolutions, showing confidence in their agents' effectiveness. ### B. Coding agents The software development space has shown remarkable potential for LLM features, with capabilities evolving from code completion to autonomous problem-solving. Agents are particularly effective because: - Code solutions are verifiable through automated tests; - Agents can iterate on solutions using test results as feedback; - The problem space is well-defined and structured; and - Output quality can be measured objectively. In our own implementation, agents can now solve real GitHub issues in the [SWE-bench Verified](https://www.anthropic.com/research/swe-bench-sonnet) benchmark based on the pull request description alone. However, whereas automated testing helps verify functionality, human review remains crucial for ensuring solutions align with broader system requirements. ## Appendix 2: Prompt engineering your tools No matter which agentic system you're building, tools will likely be an important part of your agent. [Tools](https://www.anthropic.com/news/tool-use-ga) enable Claude to interact with external services and APIs by specifying their exact structure and definition in our API. When Claude responds, it will include a [tool use block](https://docs.anthropic.com/en/docs/build-with-claude/tool-use#example-api-response-with-a-tool-use-content-block) in the API response if it plans to invoke a tool. Tool definitions and specifications should be given just as much prompt engineering attention as your overall prompts. In this brief appendix, we describe how to prompt engineer your tools. There are often several ways to specify the same action. For instance, you can specify a file edit by writing a diff, or by rewriting the entire file. For structured output, you can return code inside markdown or inside JSON. In software engineering, differences like these are cosmetic and can be converted losslessly from one to the other. However, some formats are much more difficult for an LLM to write than others. Writing a diff requires knowing how many lines are changing in the chunk header before the new code is written. Writing code inside JSON (compared to markdown) requires extra escaping of newlines and quotes. Our suggestions for deciding on tool formats are the following: - Give the model enough tokens to "think" before it writes itself into a corner. - Keep the format close to what the model has seen naturally occurring in text on the internet. - Make sure there's no formatting "overhead" such as having to keep an accurate count of thousands of lines of code, or string-escaping any code it writes. One rule of thumb is to think about how much effort goes into human-computer interfaces (HCI), and plan to invest just as much effort in creating good *agent*-computer interfaces (ACI). Here are some thoughts on how to do so: - Put yourself in the model's shoes. Is it obvious how to use this tool, based on the description and parameters, or would you need to think carefully about it? If so, then it’s probably also true for the model. A good tool definition often includes example usage, edge cases, input format requirements, and clear boundaries from other tools. - How can you change parameter names or descriptions to make things more obvious? Think of this as writing a great docstring for a junior developer on your team. This is especially important when using many similar tools. - Test how the model uses your tools: Run many example inputs in our [workbench](https://console.anthropic.com/workbench) to see what mistakes the model makes, and iterate. - [Poka-yoke](https://en.wikipedia.org/wiki/Poka-yoke) your tools. Change the arguments so that it is harder to make mistakes. While building our agent for [SWE-bench](https://www.anthropic.com/research/swe-bench-sonnet), we actually spent more time optimizing our tools than the overall prompt. For example, we found that the model would make mistakes with tools using relative filepaths after the agent had moved out of the root directory. To fix this, we changed the tool to always require absolute filepaths—and we found that the model used this method flawlessly. --- ## citations-agent.md You are an agent for adding correct citations to a research report. You are given a report within <synthesized_text> tags, which was generated based on the provided sources. However, the sources are not cited in the <synthesized_text>. Your task is to enhance user trust by generating correct, appropriate citations for this report. Based on the provided document, add citations to the input text using the format specified earlier. Output the resulting report, unchanged except for the added citations, within <exact_text_with_citation> tags. **Rules:** - Do NOT modify the <synthesized_text> in any way - keep all content 100% identical, only add citations - Pay careful attention to whitespace: DO NOT add or remove any whitespace - ONLY add citations where the source documents directly support claims in the text **Citation guidelines:** - **Avoid citing unnecessarily**: Not every statement needs a citation. Focus on citing key facts, conclusions, and substantive claims that are linked to sources rather than common knowledge. Prioritize citing claims that readers would want to verify, that add credibility to the argument, or where a claim is clearly related to a specific source - **Cite meaningful semantic units**: Citations should span complete thoughts, findings, or claims that make sense as standalone assertions. Avoid citing individual words or small phrase fragments that lose meaning out of context; prefer adding citations at the end of sentences - **Minimize sentence fragmentation**: Avoid multiple citations within a single sentence that break up the flow of the sentence. Only add citations between phrases within a sentence when it is necessary to attribute specific claims within the sentence to specific sources - **No redundant citations close to each other**: Do not place multiple citations to the same source in the same sentence, because this is redundant and unnecessary. If a sentence contains multiple citable claims from the *same* source, use only a single citation at the end of the sentence after the period **Technical requirements:** - Citations result in a visual, interactive element being placed at the closing tag. Be mindful of where the closing tag is, and do not break up phrases and sentences unnecessarily - Output text with citations between <exact_text_with_citation> and </exact_text_with_citation> tags - Include any of your preamble, thinking, or planning BEFORE the opening <exact_text_with_citation> tag, to avoid breaking the output - ONLY add the citation tags to the text within <synthesized_text> tags for your <exact_text_with_citation> output - Text without citations will be collected and compared to the original report from the <synthesized_text>. If the text is not identical, your result will be rejected. Now, add the citations to the research report and output the <exact_text_with_citation>. --- ## cla-sub-agents.md # Create custom subagents > Create and use specialized AI subagents in Claude Code for task-specific workflows and improved context management. Subagents are specialized AI assistants that handle specific types of tasks. Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. When Claude encounters a task that matches a subagent's description, it delegates to that subagent, which works independently and returns results. Subagents help you: * **Preserve context** by keeping exploration and implementation out of your main conversation * **Enforce constraints** by limiting which tools a subagent can use * **Reuse configurations** across projects with user-level subagents * **Specialize behavior** with focused system prompts for specific domains * **Control costs** by routing tasks to faster, cheaper models like Haiku Claude uses each subagent's description to decide when to delegate tasks. When you create a subagent, write a clear description so Claude knows when to use it. Claude Code includes several built-in subagents like **Explore**, **Plan**, and **general-purpose**. You can also create custom subagents to handle specific tasks. This page covers the [built-in subagents](#built-in-subagents), [how to create your own](#quickstart-create-your-first-subagent), [full configuration options](#configure-subagents), [patterns for working with subagents](#work-with-subagents), and [example subagents](#example-subagents). ## Built-in subagents Claude Code includes built-in subagents that Claude automatically uses when appropriate. Each inherits the parent conversation's permissions with additional tool restrictions. <Tabs> <Tab title="Explore"> A fast, read-only agent optimized for searching and analyzing codebases. * **Model**: Haiku (fast, low-latency) * **Tools**: Read-only tools (denied access to Write and Edit tools) * **Purpose**: File discovery, code search, codebase exploration Claude delegates to Explore when it needs to search or understand a codebase without making changes. This keeps exploration results out of your main conversation context. When invoking Explore, Claude specifies a thoroughness level: **quick** for targeted lookups, **medium** for balanced exploration, or **very thorough** for comprehensive analysis. </Tab> <Tab title="Plan"> A research agent used during [plan mode](/en/common-workflows#use-plan-mode-for-safe-code-analysis) to gather context before presenting a plan. * **Model**: Inherits from main conversation * **Tools**: Read-only tools (denied access to Write and Edit tools) * **Purpose**: Codebase research for planning When you're in plan mode and Claude needs to understand your codebase, it delegates research to the Plan subagent. This prevents infinite nesting (subagents cannot spawn other subagents) while still gathering necessary context. </Tab> <Tab title="General-purpose"> A capable agent for complex, multi-step tasks that require both exploration and action. * **Model**: Inherits from main conversation * **Tools**: All tools * **Purpose**: Complex research, multi-step operations, code modifications Claude delegates to general-purpose when the task requires both exploration and modification, complex reasoning to interpret results, or multiple dependent steps. </Tab> <Tab title="Other"> Claude Code includes additional helper agents for specific tasks. These are typically invoked automatically, so you don't need to use them directly. | Agent | Model | When Claude uses it | | :---------------- | :------- | :------------------------------------------------------- | | Bash | Inherits | Running terminal commands in a separate context | | statusline-setup | Sonnet | When you run `/statusline` to configure your status line | | Claude Code Guide | Haiku | When you ask questions about Claude Code features | </Tab> </Tabs> Beyond these built-in subagents, you can create your own with custom prompts, tool restrictions, permission modes, hooks, and skills. The following sections show how to get started and customize subagents. ## Quickstart: create your first subagent Subagents are defined in Markdown files with YAML frontmatter. You can [create them manually](#write-subagent-files) or use the `/agents` slash command. This walkthrough guides you through creating a user-level subagent with the `/agent` command. The subagent reviews code and suggests improvements for the codebase. <Steps> <Step title="Open the subagents interface"> In Claude Code, run: ``` /agents ``` </Step> <Step title="Create a new user-level agent"> Select **Create new agent**, then choose **User-level**. This saves the subagent to `~/.claude/agents/` so it's available in all your projects. </Step> <Step title="Generate with Claude"> Select **Generate with Claude**. When prompted, describe the subagent: ``` A code improvement agent that scans files and suggests improvements for readability, performance, and best practices. It should explain each issue, show the current code, and provide an improved version. ``` Claude generates the system prompt and configuration. Press `e` to open it in your editor if you want to customize it. </Step> <Step title="Select tools"> For a read-only reviewer, deselect everything except **Read-only tools**. If you keep all tools selected, the subagent inherits all tools available to the main conversation. </Step> <Step title="Select model"> Choose which model the subagent uses. For this example agent, select **Sonnet**, which balances capability and speed for analyzing code patterns. </Step> <Step title="Choose a color"> Pick a background color for the subagent. This helps you identify which subagent is running in the UI. </Step> <Step title="Save and try it out"> Save the subagent. It's available immediately (no restart needed). Try it: ``` Use the code-improver agent to suggest improvements in this project ``` Claude delegates to your new subagent, which scans the codebase and returns improvement suggestions. </Step> </Steps> You now have a subagent you can use in any project on your machine to analyze codebases and suggest improvements. You can also create subagents manually as Markdown files, define them via CLI flags, or distribute them through plugins. The following sections cover all configuration options. ## Configure subagents ### Use the /agents command The `/agents` command provides an interactive interface for managing subagents. Run `/agents` to: * View all available subagents (built-in, user, project, and plugin) * Create new subagents with guided setup or Claude generation * Edit existing subagent configuration and tool access * Delete custom subagents * See which subagents are active when duplicates exist This is the recommended way to create and manage subagents. For manual creation or automation, you can also add subagent files directly. ### Choose the subagent scope Subagents are Markdown files with YAML frontmatter. Store them in different locations depending on scope. When multiple subagents share the same name, the higher-priority location wins. | Location | Scope | Priority | How to create | | :--------------------------- | :---------------------- | :---------- | :------------------------------------ | | `--agents` CLI flag | Current session | 1 (highest) | Pass JSON when launching Claude Code | | `.claude/agents/` | Current project | 2 | Interactive or manual | | `~/.claude/agents/` | All your projects | 3 | Interactive or manual | | Plugin's `agents/` directory | Where plugin is enabled | 4 (lowest) | Installed with [plugins](../08-Plugins-Skills/create-plugins-claude-code-docs.md) | **Project subagents** (`.claude/agents/`) are ideal for subagents specific to a codebase. Check them into version control so your team can use and improve them collaboratively. **User subagents** (`~/.claude/agents/`) are personal subagents available in all your projects. **CLI-defined subagents** are passed as JSON when launching Claude Code. They exist only for that session and aren't saved to disk, making them useful for quick testing or automation scripts: ```bash theme={null} claude --agents '{ "code-reviewer": { "description": "Expert code reviewer. Use proactively after code changes.", "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.", "tools": ["Read", "Grep", "Glob", "Bash"], "model": "sonnet" } }' ``` The `--agents` flag accepts JSON with the same fields as [frontmatter](#supported-frontmatter-fields). Use `prompt` for the system prompt (equivalent to the markdown body in file-based subagents). See the [CLI reference](/en/cli-reference#agents-flag-format) for the full JSON format. **Plugin subagents** come from [plugins](../08-Plugins-Skills/create-plugins-claude-code-docs.md) you've installed. They appear in `/agents` alongside your custom subagents. See the [plugin components reference](/en/plugins-reference#agents) for details on creating plugin subagents. ### Write subagent files Subagent files use YAML frontmatter for configuration, followed by the system prompt in Markdown: <Note> Subagents are loaded at session start. If you create a subagent by manually adding a file, restart your session or use `/agents` to load it immediately. </Note> ```markdown theme={null} --- name: code-reviewer description: Reviews code for quality and best practices tools: Read, Glob, Grep model: sonnet --- You are a code reviewer. When invoked, analyze the code and provide specific, actionable feedback on quality, security, and best practices. ``` The frontmatter defines the subagent's metadata and configuration. The body becomes the system prompt that guides the subagent's behavior. Subagents receive only this system prompt (plus basic environment details like working directory), not the full Claude Code system prompt. #### Supported frontmatter fields The following fields can be used in the YAML frontmatter. Only `name` and `description` are required. | Field | Required | Description | | :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Yes | Unique identifier using lowercase letters and hyphens | | `description` | Yes | When Claude should delegate to this subagent | | `tools` | No | [Tools](#available-tools) the subagent can use. Inherits all tools if omitted | | `disallowedTools` | No | Tools to deny, removed from inherited or specified list | | `model` | No | [Model](#choose-a-model) to use: `sonnet`, `opus`, `haiku`, or `inherit`. Defaults to `sonnet` | | `permissionMode` | No | [Permission mode](#permission-modes): `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, or `plan` | | `skills` | No | [Skills](../08-Plugins-Skills/extend-claude-with-skills-claude-code-docs.md) to load into the subagent's context at startup. The full skill content is injected, not just made available for invocation. Subagents don't inherit skills from the parent conversation | | `hooks` | No | [Lifecycle hooks](#define-hooks-for-subagents) scoped to this subagent | ### Choose a model The `model` field controls which [AI model](../02-Claude-Code-CLI/model-config-ca429e15da.md) the subagent uses: * **Model alias**: Use one of the available aliases: `sonnet`, `opus`, or `haiku` * **inherit**: Use the same model as the main conversation (useful for consistency) * **Omitted**: If not specified, uses the default model configured for subagents (`sonnet`) ### Control subagent capabilities You can control what subagents can do through tool access, permission modes, and conditional rules. #### Available tools Subagents can use any of Claude Code's [internal tools](/en/settings#tools-available-to-claude). By default, subagents inherit all tools from the main conversation, including MCP tools. To restrict tools, use the `tools` field (allowlist) or `disallowedTools` field (denylist): ```yaml theme={null} --- name: safe-researcher description: Research agent with restricted capabilities tools: Read, Grep, Glob, Bash disallowedTools: Write, Edit --- ``` #### Permission modes The `permissionMode` field controls how the subagent handles permission prompts. Subagents inherit the permission context from the main conversation but can override the mode. | Mode | Behavior | | :------------------ | :----------------------------------------------------------------- | | `default` | Standard permission checking with prompts | | `acceptEdits` | Auto-accept file edits | | `dontAsk` | Auto-deny permission prompts (explicitly allowed tools still work) | | `bypassPermissions` | Skip all permission checks | | `plan` | Plan mode (read-only exploration) | <Warning> Use `bypassPermissions` with caution. It skips all permission checks, allowing the subagent to execute any operation without approval. </Warning> If the parent uses `bypassPermissions`, this takes precedence and cannot be overridden. #### Conditional rules with hooks For more dynamic control over tool usage, use `PreToolUse` hooks to validate operations before they execute. This is useful when you need to allow some operations of a tool while blocking others. This example creates a subagent that only allows read-only database queries. The `PreToolUse` hook runs the script specified in `command` before each Bash command executes: ```yaml theme={null} --- name: db-reader description: Execute read-only database queries tools: Bash hooks: PreToolUse: - matcher: "Bash" hooks: - type: command command: "./scripts/validate-readonly-query.sh" --- ``` Claude Code [passes hook input as JSON](/en/hooks#pretooluse-input) via stdin to hook commands. The validation script reads this JSON, extracts the Bash command, and [exits with code 2](/en/hooks#exit-code-2-behavior) to block write operations: ```bash theme={null} #!/bin/bash # ./scripts/validate-readonly-query.sh INPUT=$(cat) COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty') # Block SQL write operations (case-insensitive) if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then echo "Blocked: Only SELECT queries are allowed" >&2 exit 2 fi exit 0 ``` See [Hook input](/en/hooks#pretooluse-input) for the complete input schema and [exit codes](/en/hooks#exit-codes) for how exit codes affect behavior. #### Disable specific subagents You can prevent Claude from using specific subagents by adding them to the `deny` array in your [settings](/en/settings#permission-settings). Use the format `Task(subagent-name)` where `subagent-name` matches the subagent's name field. ```json theme={null} { "permissions": { "deny": ["Task(Explore)", "Task(my-custom-agent)"] } } ``` This works for both built-in and custom subagents. You can also use the `--disallowedTools` CLI flag: ```bash theme={null} claude --disallowedTools "Task(Explore)" ``` See [IAM documentation](/en/iam#tool-specific-permission-rules) for more details on permission rules. ### Define hooks for subagents Subagents can define [hooks](../07-Hooks/hooks-reference-claude-code-docs.md) that run during the subagent's lifecycle. There are two ways to configure hooks: 1. **In the subagent's frontmatter**: Define hooks that run only while that subagent is active 2. **In `settings.json`**: Define hooks that run in the main session when subagents start or stop #### Hooks in subagent frontmatter Define hooks directly in the subagent's markdown file. These hooks only run while that specific subagent is active and are cleaned up when it finishes. | Event | Matcher input | When it fires | | :------------ | :------------ | :------------------------------ | | `PreToolUse` | Tool name | Before the subagent uses a tool | | `PostToolUse` | Tool name | After the subagent uses a tool | | `Stop` | (none) | When the subagent finishes | This example validates Bash commands with the `PreToolUse` hook and runs a linter after file edits with `PostToolUse`: ```yaml theme={null} --- name: code-reviewer description: Review code changes with automatic linting hooks: PreToolUse: - matcher: "Bash" hooks: - type: command command: "./scripts/validate-command.sh $TOOL_INPUT" PostToolUse: - matcher: "Edit|Write" hooks: - type: command command: "./scripts/run-linter.sh" --- ``` `Stop` hooks in frontmatter are automatically converted to `SubagentStop` events. #### Project-level hooks for subagent events Configure hooks in `settings.json` that respond to subagent lifecycle events in the main session. Use the `matcher` field to target specific agent types by name. | Event | Matcher input | When it fires | | :-------------- | :-------------- | :------------------------------- | | `SubagentStart` | Agent type name | When a subagent begins execution | | `SubagentStop` | Agent type name | When a subagent completes | This example runs setup and cleanup scripts only when the `db-agent` subagent starts and stops: ```json theme={null} { "hooks": { "SubagentStart": [ { "matcher": "db-agent", "hooks": [ { "type": "command", "command": "./scripts/setup-db-connection.sh" } ] } ], "SubagentStop": [ { "matcher": "db-agent", "hooks": [ { "type": "command", "command": "./scripts/cleanup-db-connection.sh" } ] } ] } } ``` See [Hooks](../07-Hooks/hooks-reference-claude-code-docs.md) for the complete hook configuration format. ## Work with subagents ### Understand automatic delegation Claude automatically delegates tasks based on the task description in your request, the `description` field in subagent configurations, and current context. To encourage proactive delegation, include phrases like "use proactively" in your subagent's description field. You can also request a specific subagent explicitly: ``` Use the test-runner subagent to fix failing tests Have the code-reviewer subagent look at my recent changes ``` ### Run subagents in foreground or background Subagents can run in the foreground (blocking) or background (concurrent): * **Foreground subagents** block the main conversation until complete. Permission prompts and clarifying questions (like [`AskUserQuestion`](/en/settings#tools-available-to-claude)) are passed through to you. * **Background subagents** run concurrently while you continue working. They inherit the parent's permissions and auto-deny anything not pre-approved. If a background subagent needs a permission it doesn't have or needs to ask clarifying questions, that tool call fails but the subagent continues. MCP tools are not available in background subagents. If a background subagent fails due to missing permissions, you can [resume it](#resume-subagents) in the foreground to retry with interactive prompts. Claude decides whether to run subagents in the foreground or background based on the task. You can also: * Ask Claude to "run this in the background" * Press **Ctrl+B** to background a running task To disable all background task functionality, set the `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` environment variable to `1`. See [Environment variables](/en/settings#environment-variables). ### Common patterns #### Isolate high-volume operations One of the most effective uses for subagents is isolating operations that produce large amounts of output. Running tests, fetching documentation, or processing log files can consume significant context. By delegating these to a subagent, the verbose output stays in the subagent's context while only the relevant summary returns to your main conversation. ``` Use a subagent to run the test suite and report only the failing tests with their error messages ``` #### Run parallel research For independent investigations, spawn multiple subagents to work simultaneously: ``` Research the authentication, database, and API modules in parallel using separate subagents ``` Each subagent explores its area independently, then Claude synthesizes the findings. This works best when the research paths don't depend on each other. <Warning> When subagents complete, their results return to your main conversation. Running many subagents that each return detailed results can consume significant context. </Warning> #### Chain subagents For multi-step workflows, ask Claude to use subagents in sequence. Each subagent completes its task and returns results to Claude, which then passes relevant context to the next subagent. ``` Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them ``` ### Choose between subagents and main conversation Use the **main conversation** when: * The task needs frequent back-and-forth or iterative refinement * Multiple phases share significant context (planning → implementation → testing) * You're making a quick, targeted change * Latency matters. Subagents start fresh and may need time to gather context Use **subagents** when: * The task produces verbose output you don't need in your main context * You want to enforce specific tool restrictions or permissions * The work is self-contained and can return a summary Consider [Skills](../08-Plugins-Skills/extend-claude-with-skills-claude-code-docs.md) instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context. <Note> Subagents cannot spawn other subagents. If your workflow requires nested delegation, use [Skills](../08-Plugins-Skills/extend-claude-with-skills-claude-code-docs.md) or [chain subagents](#chain-subagents) from the main conversation. </Note> ### Manage subagent context #### Resume subagents Each subagent invocation creates a new instance with fresh context. To continue an existing subagent's work instead of starting over, ask Claude to resume it. Resumed subagents retain their full conversation history, including all previous tool calls, results, and reasoning. The subagent picks up exactly where it stopped rather than starting fresh. When a subagent completes, Claude receives its agent ID. To resume a subagent, ask Claude to continue the previous work: ``` Use the code-reviewer subagent to review the authentication module [Agent completes] Continue that code review and now analyze the authorization logic [Claude resumes the subagent with full context from previous conversation] ``` You can also ask Claude for the agent ID if you want to reference it explicitly, or find IDs in the transcript files at `~/.claude/projects/{project}/{sessionId}/subagents/`. Each transcript is stored as `agent-{agentId}.jsonl`. For programmatic usage, see [Subagents in the Agent SDK](/en/agent-sdk/subagents). Subagent transcripts persist independently of the main conversation: * **Main conversation compaction**: When the main conversation compacts, subagent transcripts are unaffected. They're stored in separate files. * **Session persistence**: Subagent transcripts persist within their session. You can [resume a subagent](#resume-subagents) after restarting Claude Code by resuming the same session. * **Automatic cleanup**: Transcripts are cleaned up based on the `cleanupPeriodDays` setting (default: 30 days). #### Auto-compaction Subagents support automatic compaction using the same logic as the main conversation. When a subagent's context approaches its limit, Claude Code summarizes older messages to free up space while preserving important context. Compaction events are logged in subagent transcript files: ```json theme={null} { "type": "system", "subtype": "compact_boundary", "compactMetadata": { "trigger": "auto", "preTokens": 167189 } } ``` The `preTokens` value shows how many tokens were used before compaction occurred. ## Example subagents These examples demonstrate effective patterns for building subagents. Use them as starting points, or generate a customized version with Claude. <Tip> **Best practices:** * **Design focused subagents:** each subagent should excel at one specific task * **Write detailed descriptions:** Claude uses the description to decide when to delegate * **Limit tool access:** grant only necessary permissions for security and focus * **Check into version control:** share project subagents with your team </Tip> ### Code reviewer A read-only subagent that reviews code without modifying it. This example shows how to design a focused subagent with limited tool access (no Edit or Write) and a detailed prompt that specifies exactly what to look for and how to format output. ```markdown theme={null} --- name: code-reviewer description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code. tools: Read, Grep, Glob, Bash model: inherit --- You are a senior code reviewer ensuring high standards of code quality and security. When invoked: 1. Run git diff to see recent changes 2. Focus on modified files 3. Begin review immediately Review checklist: - Code is clear and readable - Functions and variables are well-named - No duplicated code - Proper error handling - No exposed secrets or API keys - Input validation implemented - Good test coverage - Performance considerations addressed Provide feedback organized by priority: - Critical issues (must fix) - Warnings (should fix) - Suggestions (consider improving) Include specific examples of how to fix issues. ``` ### Debugger A subagent that can both analyze and fix issues. Unlike the code reviewer, this one includes Edit because fixing bugs requires modifying code. The prompt provides a clear workflow from diagnosis to verification. ```markdown theme={null} --- name: debugger description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues. tools: Read, Edit, Bash, Grep, Glob --- You are an expert debugger specializing in root cause analysis. When invoked: 1. Capture error message and stack trace 2. Identify reproduction steps 3. Isolate the failure location 4. Implement minimal fix 5. Verify solution works Debugging process: - Analyze error messages and logs - Check recent code changes - Form and test hypotheses - Add strategic debug logging - Inspect variable states For each issue, provide: - Root cause explanation - Evidence supporting the diagnosis - Specific code fix - Testing approach - Prevention recommendations Focus on fixing the underlying issue, not the symptoms. ``` ### Data scientist A domain-specific subagent for data analysis work. This example shows how to create subagents for specialized workflows outside of typical coding tasks. It explicitly sets `model: sonnet` for more capable analysis. ```markdown theme={null} --- name: data-scientist description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries. tools: Bash, Read, Write model: sonnet --- You are a data scientist specializing in SQL and BigQuery analysis. When invoked: 1. Understand the data analysis requirement 2. Write efficient SQL queries 3. Use BigQuery command line tools (bq) when appropriate 4. Analyze and summarize results 5. Present findings clearly Key practices: - Write optimized SQL queries with proper filters - Use appropriate aggregations and joins - Include comments explaining complex logic - Format results for readability - Provide data-driven recommendations For each analysis: - Explain the query approach - Document any assumptions - Highlight key findings - Suggest next steps based on data Always ensure queries are efficient and cost-effective. ``` ### Database query validator A subagent that allows Bash access but validates commands to permit only read-only SQL queries. This example shows how to use `PreToolUse` hooks for conditional validation when you need finer control than the `tools` field provides. ```markdown theme={null} --- name: db-reader description: Execute read-only database queries. Use when analyzing data or generating reports. tools: Bash hooks: PreToolUse: - matcher: "Bash" hooks: - type: command command: "./scripts/validate-readonly-query.sh" --- You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data. When asked to analyze data: 1. Identify which tables contain the relevant data 2. Write efficient SELECT queries with appropriate filters 3. Present results clearly with context You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access. ``` Claude Code [passes hook input as JSON](/en/hooks#pretooluse-input) via stdin to hook commands. The validation script reads this JSON, extracts the command being executed, and checks it against a list of SQL write operations. If a write operation is detected, the script [exits with code 2](/en/hooks#exit-code-2-behavior) to block execution and returns an error message to Claude via stderr. Create the validation script anywhere in your project. The path must match the `command` field in your hook configuration: ```bash theme={null} #!/bin/bash # Blocks SQL write operations, allows SELECT queries # Read JSON input from stdin INPUT=$(cat) # Extract the command field from tool_input using jq COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty') if [ -z "$COMMAND" ]; then exit 0 fi # Block write operations (case-insensitive) if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2 exit 2 fi exit 0 ``` Make the script executable: ```bash theme={null} chmod +x ./scripts/validate-readonly-query.sh ``` The hook receives JSON via stdin with the Bash command in `tool_input.command`. Exit code 2 blocks the operation and feeds the error message back to Claude. See [Hooks](/en/hooks#exit-codes) for details on exit codes and [Hook input](/en/hooks#pretooluse-input) for the complete input schema. ## Next steps Now that you understand subagents, explore these related features: * [Distribute subagents with plugins](../08-Plugins-Skills/create-plugins-claude-code-docs.md) to share subagents across teams or projects * [Run Claude Code programmatically](../02-Claude-Code-CLI/headless-b99e3140ec.md) with the Agent SDK for CI/CD and automation * [Use MCP servers](../06-MCP-Tools/General/connect-claude-code-to-tools-via-mcp-claude-code-docs.md) to give subagents access to external tools and data --- > To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt --- ## claude-3-rag-agent.md :::: {.cell .code colab="{\"base_uri\":\"https://localhost:8080/\"}" id="1eOnr6z_zLoc" outputId="53f4214a-c00b-4dea-d1fa-38d0d6693fe9"} ``` python !python --version ``` ::: {.output .stream .stdout} Python 3.10.12 ::: :::: ::: {.cell .markdown id="qQG4iSxVxw8f"} # Claude 3 RAG Agents with LangChain v1 ::: ::: {.cell .markdown id="ov6TCS7bx1oI"} LangChain v1 brought a lot of changes and when comparing the LangChain of versions `0.0.3xx` to `0.1.x` there\'s plenty of changes to the preferred way of doing things. That is very much the case for agents. The way that we initialize and use agents is generally clearer than it was in the past --- there are still many abstractions, but we can (and are encouraged to) get closer to the agent logic itself. This can make for some confusion at first, but once understood the new logic can be much clearer than with previous versions. In this example, we\'ll be building a RAG agent with LangChain v1. We will use Claude 3 for our LLM, Voyage AI for knowledge embeddings, and Pinecone to power our knowledge retrieval. To begin, let\'s install the prerequisites: ::: :::: {.cell .code execution_count="2" colab="{\"base_uri\":\"https://localhost:8080/\"}" id="zshhLDrgbFKk" outputId="ed49398c-dc7c-4c9c-e6c3-1a1910d52006"} ``` python !pip install -qU \ langchain==0.1.11 \ langchain-core==0.1.30 \ langchain-community==0.0.27 \ langchain-anthropic==0.1.4 \ langchainhub==0.1.15 \ anthropic==0.19.1 \ voyageai==0.2.1 \ pinecone-client==3.1.0 \ datasets==2.16.1 ``` ::: {.output .stream .stdout} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 848.6/848.6 kB 4.6 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 211.0/211.0 kB 18.5 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 507.1/507.1 kB 30.3 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 75.6/75.6 kB 8.7 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 115.3/115.3 kB 13.4 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 134.8/134.8 kB 15.0 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 77.8/77.8 kB 9.2 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 58.3/58.3 kB 6.8 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 134.8/134.8 kB 13.5 MB/s eta 0:00:00 ::: :::: ::: {.cell .markdown} And grab the required API keys. We will need API keys for [Claude](https://docs.claude.com/claude/reference/getting-started-with-the-api), [Voyage AI](https://docs.voyageai.com/install/), and [Pinecone](https://docs.pinecone.io/docs/quickstart). ::: ::: {.cell .code} ``` python # Insert your API keys here ANTHROPIC_API_KEY = "<YOUR_ANTHROPIC_API_KEY>" PINECONE_API_KEY = "<YOUR_PINECONE_API_KEY>" VOYAGE_API_KEY = "<YOUR_VOYAGE_API_KEY>" ``` ::: ::: {.cell .markdown id="bpKfZkUYzQhB"} ## Finding Knowledge ::: ::: {.cell .markdown id="JDTQoxcNzUa8"} The first thing we need for an agent using RAG is somewhere we want to pull knowledge from. We will use v2 of the AI ArXiv dataset, available on Hugging Face Datasets at [`jamescalam/ai-arxiv2-chunks`](https://huggingface.co/datasets/jamescalam/ai-arxiv2-chunks). *Note: we\'re using the prechunked dataset. For the raw version see [`jamescalam/ai-arxiv2`](https://huggingface.co/datasets/jamescalam/ai-arxiv2).* ::: ::::::: {.cell .code execution_count="4" colab="{\"base_uri\":\"https://localhost:8080/\",\"height\":297,\"referenced_widgets\":[\"4d5c6f53e82948b18b45877e2e30fd78\",\"7036b643c9264b09b0f93cb6a1a8b01f\",\"fb92dd97e68643099b0d0f1b4983f5f1\",\"91c3b00e77444bb79d9f73314800471e\",\"3e1d39ab6d3a4cf5827c9b3e1d4f0df1\",\"f58fb2da52bc43a985449910daaac230\",\"449afd685fd94354b64aa43a4763ab1d\",\"43a3c63554894d268e3bf747f7e0289d\",\"d902beef883e4c65bd2d6cb161423bae\",\"ce5735788cd14803abac28fa2c42d168\",\"a8928cd888a648c9b7d52739f38c5bda\",\"0168cb9e015b4e119fcdc7beca2e21a3\",\"a0e93df2955b44208479a4b416cd1085\",\"6f58f8d6374b45b4b6a0d9fcaa8083e7\",\"8bde11d3d65c45dba3baf1c02450eef1\",\"b19af932a7f24dc799b683136d175107\",\"e2819a7a94974a4da9b6bde754fdbc50\",\"808dd94ecaff43e0848bcfead3cf0d75\",\"4383833994854f88aa12ba0edb673d47\",\"ee2672db2047468fb49482e14127dcd3\",\"6999dc582b4c4ba68fdbfe404b1c4dfe\",\"593274c4088f4d9aa2becb6b1c6e495b\"]}" id="U9gpYFnzbFKm" outputId="c7005c0a-b9a2-4c7c-f93b-e92081f7e3d6"} ``` python from datasets import load_dataset dataset = load_dataset("jamescalam/ai-arxiv2-chunks", split="train[:20000]") dataset ``` ::: {.output .stream .stderr} /usr/local/lib/python3.10/dist-packages/huggingface_hub/utils/_token.py:88: UserWarning: The secret `HF_TOKEN` does not exist in your Colab secrets. To authenticate with the Hugging Face Hub, create a token in your settings tab (https://huggingface.co/settings/tokens), set it as secret in your Google Colab and restart your session. You will be able to reuse this secret in all of your notebooks. Please note that authentication is recommended but still optional to access public models or datasets. warnings.warn( ::: ::: {.output .display_data} ``` json {"model_id":"4d5c6f53e82948b18b45877e2e30fd78","version_major":2,"version_minor":0} ``` ::: ::: {.output .display_data} ``` json {"model_id":"0168cb9e015b4e119fcdc7beca2e21a3","version_major":2,"version_minor":0} ``` ::: ::: {.output .execute_result execution_count="4"} Dataset({ features: ['doi', 'chunk-id', 'chunk', 'id', 'title', 'summary', 'source', 'authors', 'categories', 'comment', 'journal_ref', 'primary_category', 'published', 'updated', 'references'], num_rows: 20000 }) ::: ::::::: :::: {.cell .code execution_count="5" colab="{\"base_uri\":\"https://localhost:8080/\"}" id="_bP7ZW-ybFKm" outputId="491e8001-df44-465c-9979-2e2a30de9d5f"} ``` python dataset[1] ``` ::: {.output .execute_result execution_count="5"} {'doi': '2401.09350', 'chunk-id': 1, 'chunk': 'These neural networks and their training algorithms may be complex, and the scope of their impact broad and wide, but nonetheless they are simply functions in a high-dimensional space. A trained neural network takes a vector as input, crunches and transforms it in various ways, and produces another vector, often in some other space. An image may thereby be turned into a vector, a song into a sequence of vectors, and a social network as a structured collection of vectors. It seems as though much of human knowledge, or at least what is expressed as text, audio, image, and video, has a vector representation in one form or another.\nIt should be noted that representing data as vectors is not unique to neural networks and deep learning. In fact, long before learnt vector representations of pieces of dataâ\x80\x94what is commonly known as â\x80\x9cembeddingsâ\x80\x9dâ\x80\x94came along, data was often encoded as hand-crafted feature vectors. Each feature quanti- fied into continuous or discrete values some facet of the data that was deemed relevant to a particular task (such as classification or regression). Vectors of that form, too, reflect our understanding of a real-world object or concept.', 'id': '2401.09350#1', 'title': 'Foundations of Vector Retrieval', 'summary': 'Vectors are universal mathematical objects that can represent text, images,\nspeech, or a mix of these data modalities. That happens regardless of whether\ndata is represented by hand-crafted features or learnt embeddings. Collect a\nlarge enough quantity of such vectors and the question of retrieval becomes\nurgently relevant: Finding vectors that are more similar to a query vector.\nThis monograph is concerned with the question above and covers fundamental\nconcepts along with advanced data structures and algorithms for vector\nretrieval. In doing so, it recaps this fascinating topic and lowers barriers of\nentry into this rich area of research.', 'source': 'http://arxiv.org/pdf/2401.09350', 'authors': 'Sebastian Bruch', 'categories': 'cs.DS, cs.IR', 'comment': None, 'journal_ref': None, 'primary_category': 'cs.DS', 'published': '20240117', 'updated': '20240117', 'references': []} ::: :::: ::: {.cell .markdown id="VX6NdQhgbFKn"} ## Building the Knowledge Base ::: ::: {.cell .markdown id="MDCbqQl_bFKn"} To build our knowledge base we need *two things*: 1. Embeddings, for this we will use `VoyageEmbeddings` using Voyage AI\'s embedding models, which do need an [API key](https://dash.voyageai.com/api-keys). 2. A vector database, where we store our embeddings and query them. We use Pinecone which again requires a [free API key](https://app.pinecone.io). First we initialize our connection to Voyage AI and define an `embed` object for embeddings: ::: ::: {.cell .code execution_count="7" id="wkw0KyLRbFKo"} ``` python from langchain_community.embeddings import VoyageEmbeddings embed = VoyageEmbeddings(voyage_api_key=VOYAGE_API_KEY, model="voyage-2") ``` ::: ::: {.cell .markdown id="LhDzfsczbFKo"} Then we initialize our connection to Pinecone: ::: ::: {.cell .code execution_count="8" id="j0N7EcJibFKo"} ``` python from pinecone import Pinecone # configure client pc = Pinecone(api_key=PINECONE_API_KEY) ``` ::: ::: {.cell .markdown id="g65RLGIpbFKo"} Now we setup our index specification, this allows us to define the cloud provider and region where we want to deploy our index. You can find a list of all [available providers and regions here](https://docs.pinecone.io/docs/projects). ::: ::: {.cell .code execution_count="9" id="8stIZYKdbFKo"} ``` python from pinecone import ServerlessSpec spec = ServerlessSpec(cloud="aws", region="us-west-2") ``` ::: ::: {.cell .markdown id="-8Ep3743bFKo"} Before creating an index, we need the dimensionality of our Voyage AI embedding model, which we can find easily by creating an embedding and checking the length: ::: :::: {.cell .code execution_count="10" colab="{\"base_uri\":\"https://localhost:8080/\"}" id="DwMhLWLDbFKo" outputId="f8731679-583c-497c-93d9-b13ea6013c83"} ``` python vec = embed.embed_documents(["ello"]) len(vec[0]) ``` ::: {.output .execute_result execution_count="10"} 1024 ::: :::: ::: {.cell .markdown id="G3X7nZIabFKp"} Now we create the index using our embedding dimensionality, and a metric also compatible with the model (this can be either cosine or dotproduct). We also pass our spec to index initialization. ::: :::: {.cell .code execution_count="11" colab="{\"base_uri\":\"https://localhost:8080/\"}" id="E6Bl7xTJbFKp" outputId="03e0b822-b150-4a6b-b83d-1cee1e4fced4"} ``` python import time index_name = "claude-3-rag" # check if index already exists (it shouldn't if this is first time) if index_name not in pc.list_indexes().names(): # if does not exist, create index pc.create_index( index_name, dimension=len(vec[0]), # dimensionality of voyage model metric="dotproduct", spec=spec, ) # wait for index to be initialized while not pc.describe_index(index_name).status["ready"]: time.sleep(1) # connect to index index = pc.Index(index_name) time.sleep(1) # view index stats index.describe_index_stats() ``` ::: {.output .execute_result execution_count="11"} {'dimension': 1024, 'index_fullness': 0.0, 'namespaces': {'': {'vector_count': 20000}}, 'total_vector_count': 20000} ::: :::: ::: {.cell .markdown id="6ZUn2lu7bFKp"} ### Populating our Index ::: ::: {.cell .markdown id="PeVD6d0sbFKp"} Now our knowledge base is ready to be populated with our data. We will use the `embed` helper function to embed our documents and then add them to our index. We will also include metadata from each record. ::: :::: {.cell .code execution_count="12" colab="{\"base_uri\":\"https://localhost:8080/\",\"height\":49,\"referenced_widgets\":[\"78b688cc78264ad1a2f05d339fe498fe\",\"f8796aebc76a42ed80d6cf9c234b9e14\",\"93fd5108528a499cb5ae4444f0b2f770\",\"89683fb7a1a44606abc2ded05fbb3aa3\",\"f202dce30c1d4672ad357db9b6dbe9b8\",\"009627caf7fa4c51b61b6e2087545324\",\"3ff8bcf03c704243b7fd173b3cdd0d87\",\"cc0685f737fa4e15b7796e5f3fe3df8d\",\"f3cfb3b02d7a4e44b00e24aa2e7f9ff5\",\"1022918a023b4aa8a3714d9eab2978b1\",\"e6ed1f5a6e5b4c508fa3b69d9219057d\"]}" id="hb00VSTqbFKp" outputId="f13e0707-2b9b-4966-df62-9e457765ebf8"} ``` python from tqdm.auto import tqdm # easier to work with dataset as pandas dataframe data = dataset.to_pandas() batch_size = 100 for i in tqdm(range(0, len(data), batch_size)): i_end = min(len(data), i + batch_size) # get batch of data batch = data.iloc[i:i_end] # generate unique ids for each chunk ids = [f"{x['doi']}-{x['chunk-id']}" for i, x in batch.iterrows()] # get text to embed texts = [x["chunk"] for _, x in batch.iterrows()] # embed text embeds = embed.embed_documents(texts) # get metadata to store in Pinecone metadata = [ {"text": x["chunk"], "source": x["source"], "title": x["title"]} for i, x in batch.iterrows() ] # add to Pinecone index.upsert(vectors=zip(ids, embeds, metadata, strict=False)) ``` ::: {.output .display_data} ``` json {"model_id":"78b688cc78264ad1a2f05d339fe498fe","version_major":2,"version_minor":0} ``` ::: :::: ::: {.cell .markdown id="z6VVT3X_EMDO"} Create a tool for our agent to use when searching for ArXiv papers: ::: ::: {.cell .code execution_count="13" id="X9J5jHKcEQz6"} ``` python from langchain.agents import tool @tool def arxiv_search(query: str) -> str: """Use this tool when answering questions about AI, machine learning, data science, or other technical questions that may be answered using arXiv papers. """ # create query vector xq = embed.embed_query(query) # perform search out = index.query(vector=xq, top_k=5, include_metadata=True) # reformat results into string results_str = "\n\n".join([x["metadata"]["text"] for x in out["matches"]]) return results_str tools = [arxiv_search] ``` ::: ::: {.cell .markdown id="uN7d_4r-JMPW"} When this tool is used by our agent it will execute it like so: ::: :::: {.cell .code execution_count="14" colab="{\"base_uri\":\"https://localhost:8080/\"}" id="eq4H-2RpI1U3" outputId="ca36c8cb-5fd1-47ed-cc67-f43fd9833af0"} ``` python print(arxiv_search.run(tool_input={"query": "can you tell me about llama 2?"})) ``` ::: {.output .stream .stdout} Model Llama 2 Code Llama Code Llama - Python Size FIM LCFT Python CPP Java PHP TypeScript C# Bash Average 7B ✗ 13B ✗ 34B ✗ 70B ✗ 7B ✗ 7B ✓ 7B ✗ 7B ✓ 13B ✗ 13B ✓ 13B ✗ 13B ✓ 34B ✗ 34B ✗ 7B ✗ 7B ✗ 13B ✗ 13B ✗ 34B ✗ 34B ✗ ✗ ✗ ✗ ✗ 14.3% 6.8% 10.8% 9.9% 19.9% 13.7% 15.8% 13.0% 24.2% 23.6% 22.2% 19.9% 27.3% 30.4% 31.6% 34.2% 12.6% 13.2% 21.4% 15.1% 6.3% 3.2% 8.3% 9.5% 3.2% 12.6% 17.1% 3.8% 18.9% 25.9% 8.9% 24.8% ✗ ✗ ✓ ✓ ✗ ✗ ✓ ✓ ✗ ✓ 37.3% 31.1% 36.1% 30.4% 29.2% 29.8% 38.0% Ethical Considerations and Limitations (Section 5.2) Llama 2 is a new technology that carries risks with use. Testing conducted to date has been in English, and has not covered, nor could it cover all scenarios. For these reasons, as with all LLMs, Llama 2’s potential outputs cannot be predicted in advance, and the model may in some instances produce inaccurate or objectionable responses to user prompts. Therefore, before deploying any applications of Llama 2, developers should perform safety testing and tuning tailored to their specific applications of the model. Please see the Responsible Use Guide available available at https://ai.meta.com/llama/responsible-user-guide Table 52: Model card for Llama 2. 77 2 Cove Liama Long context (7B =, 13B =, 34B) + fine-tuning ; Lrama 2 Code training 20B oes Cope Liama - Instruct Foundation models —> nfilling code training = eee.” (7B =, 13B =, 34B) — 5B (7B, 13B, 348) 5008 Python code Long context Cove Liama - PyrHon (7B, 13B, 34B) > training » Fine-tuning > 1008 208 Figure 2: The Code Llama specialization pipeline. The different stages of fine-tuning annotated with the number of tokens seen during training. Infilling-capable models are marked with the ⇄ symbol. # 2 Code Llama: Specializing Llama 2 for code # 2.1 The Code Llama models family # 2 Code Llama: Specializing Llama 2 for code # 2.1 The Code Llama models family Code Llama. The Code Llama models constitute foundation models for code generation. They come in four model sizes: 7B, 13B, 34B and 70B parameters. The 7B, 13B and 70B models are trained using an infilling objective (Section 2.3), and are appropriate to be used in an IDE to complete code in the middle of a file, for example. The 34B model was trained without the infilling objective. All Code Llama models are initialized with Llama 2 model weights and trained on 500B tokens from a code-heavy dataset (see Section 2.2 for more details), except Code Llama 70B which was trained on 1T tokens. They are all fine-tuned to handle long contexts as detailed in Section 2.4. 0.52 0.57 0.19 0.30 Llama 1 7B 13B 33B 65B 0.27 0.24 0.23 0.25 0.26 0.24 0.26 0.26 0.34 0.31 0.34 0.34 0.54 0.52 0.50 0.46 0.36 0.37 0.36 0.36 0.39 0.37 0.35 0.40 0.26 0.23 0.24 0.25 0.28 0.28 0.33 0.32 0.33 0.31 0.34 0.32 0.45 0.50 0.49 0.48 0.33 0.27 0.31 0.31 0.17 0.10 0.12 0.11 0.24 0.24 0.23 0.25 0.31 0.27 0.30 0.30 0.44 0.41 0.41 0.43 0.57 0.55 0.60 0.60 0.39 0.34 0.28 0.39 Llama 2 7B 13B 34B 70B 0.28 0.24 0.27 0.31 0.25 0.25 0.24 0.29 0.29 0.35 0.33 0.35 0.50 0.50 0.56 0.51 0.36 0.41 0.41 ::: :::: ::: {.cell .markdown id="XUvJOqrNhYIh"} ## Defining XML Agent ::: ::: {.cell .markdown id="s45dwd78hbvk"} The XML agent is built primarily to support Anthropic models. Anthropic models have been trained to use XML tags like `<input>{some input}</input` or when using a tool they use: <tool>{tool name}</tool> <tool_input>{tool input}</tool_input> This is much different to the format produced by typical ReAct agents, which is not as well supported by Anthropic models. To create an XML agent we need a `prompt`, `llm`, and list of `tools`. We can download a prebuilt prompt for conversational XML agents from LangChain hub. ::: :::: {.cell .code execution_count="15" colab="{\"base_uri\":\"https://localhost:8080/\"}" id="ntuT7UuXeMz0" outputId="c47f0a98-c71f-488f-fc55-9e1ea7f643b4"} ``` python from langchain import hub prompt = hub.pull("hwchase17/xml-agent-convo") prompt ``` ::: {.output .execute_result execution_count="15"} ChatPromptTemplate(input_variables=['agent_scratchpad', 'input', 'tools'], partial_variables={'chat_history': ''}, messages=[HumanMessagePromptTemplate(prompt=PromptTemplate(input_variables=['agent_scratchpad', 'chat_history', 'input', 'tools'], template="You are a helpful assistant. Help the user answer any questions.\n\nYou have access to the following tools:\n\n{tools}\n\nIn order to use a tool, you can use <tool></tool> and <tool_input></tool_input> tags. You will then get back a response in the form <observation></observation>\nFor example, if you have a tool called 'search' that could run a google search, in order to search for the weather in SF you would respond:\n\n<tool>search</tool><tool_input>weather in SF</tool_input>\n<observation>64 degrees</observation>\n\nWhen you are done, respond with a final answer between <final_answer></final_answer>. For example:\n\n<final_answer>The weather in SF is 64 degrees</final_answer>\n\nBegin!\n\nPrevious Conversation:\n{chat_history}\n\nQuestion: {input}\n{agent_scratchpad}"))]) ::: :::: ::: {.cell .markdown id="rfdcKCdwi0SL"} We can see the XML format being used throughout the prompt when explaining to the LLM how it should use tools. Next we initialize our connection to Anthropic, for this we need an [Claude API key](https://console.anthropic.com/). ::: ::: {.cell .code execution_count="16" id="kDHuU2uOdW91"} ``` python from langchain_anthropic import ChatAnthropic # chat completion llm llm = ChatAnthropic( ANTHROPIC_API_KEY=ANTHROPIC_API_KEY, model_name="claude-opus-4-1", # change "opus" -> "sonnet" for speed temperature=0.0, ) ``` ::: ::: {.cell .markdown id="g33Nt-xijPKG"} When the agent is run we will provide it with a single `input` --- this is the input text from a user. However, within the agent logic an *agent_scratchpad* object will be passed too, which will include tool information. To feed this information into our LLM we will need to transform it into the XML format described above, we define the `convert_intermediate_steps` function to handle that. ::: ::: {.cell .code execution_count="17" id="TMMBgMBlIJoq"} ``` python def convert_intermediate_steps(intermediate_steps): log = "" for action, observation in intermediate_steps: log += ( f"<tool>{action.tool}</tool><tool_input>{action.tool_input}" f"</tool_input><observation>{observation}</observation>" ) return log ``` ::: ::: {.cell .markdown id="T5_PQWVckAOi"} We must also parse the tools into a string containing `tool_name: tool_description` --- we handle that with the `convert_tools` function. ::: ::: {.cell .code execution_count="18" id="qxbrF5a4j9il"} ``` python def convert_tools(tools): return "\n".join([f"{tool.name}: {tool.description}" for tool in tools]) ``` ::: ::: {.cell .markdown id="SCVI2dyUIRg6"} With everything ready we can go ahead and initialize our agent object using [**L**ang**C**hain **E**xpression **L**anguage (LCEL)](https://www.pinecone.io/learn/series/langchain/langchain-expression-language/). We add instructions for when the LLM should *stop* generating with `llm.bind(stop=[...])` and finally we parse the output from the agent using an `XMLAgentOutputParser` object. ::: ::: {.cell .code execution_count="19" id="Z3yhTDmEIU4n"} ``` python from langchain.agents.output_parsers import XMLAgentOutputParser agent = ( { "input": lambda x: x["input"], # without "chat_history", tool usage has no context of prev interactions "chat_history": lambda x: x["chat_history"], "agent_scratchpad": lambda x: convert_intermediate_steps(x["intermediate_steps"]), } | prompt.partial(tools=convert_tools(tools)) | llm.bind(stop=["</tool_input>", "</final_answer>"]) | XMLAgentOutputParser() ) ``` ::: ::: {.cell .markdown id="MG2_hL4hkudq"} With our `agent` object initialized we pass it to an `AgentExecutor` object alongside our original `tools` list: ::: ::: {.cell .code execution_count="20" id="YHW_K3WOIsXw"} ``` python from langchain.agents import AgentExecutor agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True) ``` ::: ::: {.cell .markdown id="QRCtHauRlkLc"} Now we can use the agent via the `invoke` method: ::: :::: {.cell .code execution_count="25" colab="{\"base_uri\":\"https://localhost:8080/\"}" id="Y_Aqp20qloj7" outputId="c4fe06f3-a147-4274-becd-49c9992a8cd6"} ``` python user_msg = "can you tell me about llama 2?" out = agent_executor.invoke({"input": user_msg, "chat_history": ""}) print(out["output"]) ``` ::: {.output .stream .stdout} > Entering new AgentExecutor chain... <tool>arxiv_search</tool> <tool_input>llama 2Model Llama 2 Code Llama Code Llama - Python Size FIM LCFT Python CPP Java PHP TypeScript C# Bash Average 7B ✗ 13B ✗ 34B ✗ 70B ✗ 7B ✗ 7B ✓ 7B ✗ 7B ✓ 13B ✗ 13B ✓ 13B ✗ 13B ✓ 34B ✗ 34B ✗ 7B ✗ 7B ✗ 13B ✗ 13B ✗ 34B ✗ 34B ✗ ✗ ✗ ✗ ✗ 14.3% 6.8% 10.8% 9.9% 19.9% 13.7% 15.8% 13.0% 24.2% 23.6% 22.2% 19.9% 27.3% 30.4% 31.6% 34.2% 12.6% 13.2% 21.4% 15.1% 6.3% 3.2% 8.3% 9.5% 3.2% 12.6% 17.1% 3.8% 18.9% 25.9% 8.9% 24.8% ✗ ✗ ✓ ✓ ✗ ✗ ✓ ✓ ✗ ✓ 37.3% 31.1% 36.1% 30.4% 29.2% 29.8% 38.0% 2 Cove Liama Long context (7B =, 13B =, 34B) + fine-tuning ; Lrama 2 Code training 20B oes Cope Liama - Instruct Foundation models —> nfilling code training = eee.” (7B =, 13B =, 34B) — 5B (7B, 13B, 348) 5008 Python code Long context Cove Liama - PyrHon (7B, 13B, 34B) > training » Fine-tuning > 1008 208 Figure 2: The Code Llama specialization pipeline. The different stages of fine-tuning annotated with the number of tokens seen during training. Infilling-capable models are marked with the ⇄ symbol. # 2 Code Llama: Specializing Llama 2 for code # 2.1 The Code Llama models family 0.52 0.57 0.19 0.30 Llama 1 7B 13B 33B 65B 0.27 0.24 0.23 0.25 0.26 0.24 0.26 0.26 0.34 0.31 0.34 0.34 0.54 0.52 0.50 0.46 0.36 0.37 0.36 0.36 0.39 0.37 0.35 0.40 0.26 0.23 0.24 0.25 0.28 0.28 0.33 0.32 0.33 0.31 0.34 0.32 0.45 0.50 0.49 0.48 0.33 0.27 0.31 0.31 0.17 0.10 0.12 0.11 0.24 0.24 0.23 0.25 0.31 0.27 0.30 0.30 0.44 0.41 0.41 0.43 0.57 0.55 0.60 0.60 0.39 0.34 0.28 0.39 Llama 2 7B 13B 34B 70B 0.28 0.24 0.27 0.31 0.25 0.25 0.24 0.29 0.29 0.35 0.33 0.35 0.50 0.50 0.56 0.51 0.36 0.41 0.41 Ethical Considerations and Limitations (Section 5.2) Llama 2 is a new technology that carries risks with use. Testing conducted to date has been in English, and has not covered, nor could it cover all scenarios. For these reasons, as with all LLMs, Llama 2’s potential outputs cannot be predicted in advance, and the model may in some instances produce inaccurate or objectionable responses to user prompts. Therefore, before deploying any applications of Llama 2, developers should perform safety testing and tuning tailored to their specific applications of the model. Please see the Responsible Use Guide available available at https://ai.meta.com/llama/responsible-user-guide Table 52: Model card for Llama 2. 77 Model Size FIM LCFT HumanEval MBPP pass@1 pass@10 pass@100 pass@1 pass@10 pass@100 Llama 2 Code Llama Code Llama - Python 7B ✗ 13B ✗ 34B ✗ 70B ✗ 7B ✗ 7B ✓ 7B ✗ 7B ✓ 13B ✗ 13B ✓ 13B ✗ 13B ✓ 34B ✗ 34B ✗ 7B ✗ 7B ✗ 13B ✗ 13B ✗ 34B ✗ 34B ✗ ✗ ✗ ✗ ✗ ✗ ✗ ✓ ✓ ✗ ✗ ✓ ✓ ✗ ✓ ✗ ✓ ✗ ✓ ✗ ✓ 12.2% 25.2% 20.1% 34.8% 22.6% 47.0% 30.5% 59.4% 32.3% 63.9% 34.1% 62.6% 34.1% 62.5% 33.5% 59.6% 36.6% 72.9% 36.6% 71.9% 37.8% 70.6% 36.0% 69.4% 48.2% 77.7% 48.8% 76.8% 40.2% 70.0% 38.4% 70.3% 45.7% 80.0%Based on the information from the arXiv search, here are the key points about Llama 2: <final_answer> - Llama 2 is a large language model developed by Meta AI. It comes in sizes ranging from 7B to 70B parameters. - Code Llama is a version of Llama 2 that has been specialized for code generation through fine-tuning on code datasets. Code Llama models are available in Python, C++, Java, PHP, TypeScript, C#, and Bash. - The Code Llama specialization pipeline involves foundation model pre-training, long context training, code infilling training, and fine-tuning on specific programming languages. - Code Llama significantly outperforms the base Llama 2 models on code generation benchmarks like HumanEval and MBPP. For example, the 34B parameter Code Llama - Python achieves 48.8% pass@1 on HumanEval compared to 34.1% for the 34B Llama 2. - As with all large language models, Llama 2 has limitations and potential risks that need to be considered before deploying it in applications. Meta provides a responsible use guide with recommendations for safety testing and tuning. > Finished chain. - Llama 2 is a large language model developed by Meta AI. It comes in sizes ranging from 7B to 70B parameters. - Code Llama is a version of Llama 2 that has been specialized for code generation through fine-tuning on code datasets. Code Llama models are available in Python, C++, Java, PHP, TypeScript, C#, and Bash. - The Code Llama specialization pipeline involves foundation model pre-training, long context training, code infilling training, and fine-tuning on specific programming languages. - Code Llama significantly outperforms the base Llama 2 models on code generation benchmarks like HumanEval and MBPP. For example, the 34B parameter Code Llama - Python achieves 48.8% pass@1 on HumanEval compared to 34.1% for the 34B Llama 2. - As with all large language models, Llama 2 has limitations and potential risks that need to be considered before deploying it in applications. Meta provides a responsible use guide with recommendations for safety testing and tuning. ::: :::: ::: {.cell .markdown id="Eae-JyUFl--N"} That looks pretty good, but right now our agent is *stateless* --- making it hard to have a conversation with. We can give it memory in many different ways, but one the easiest ways to do so is to use `ConversationBufferWindowMemory`. ::: ::: {.cell .code execution_count="26" id="EqOMNQUfmOEr"} ``` python from langchain.chains.conversation.memory import ConversationBufferWindowMemory # conversational memory conversational_memory = ConversationBufferWindowMemory( memory_key="chat_history", k=5, return_messages=True ) ``` ::: ::: {.cell .markdown id="O9UvnBrsnNVw"} We haven\'t attached our conversational memory to our agent --- so the `conversational_memory` object will remain empty: ::: :::: {.cell .code execution_count="27" colab="{\"base_uri\":\"https://localhost:8080/\"}" id="KJZNIDAslNoC" outputId="5267f069-dc09-472d-c9ef-e694cfea982f"} ``` python conversational_memory.chat_memory.messages ``` ::: {.output .execute_result execution_count="27"} [] ::: :::: ::: {.cell .markdown id="ynX9Wca6nawr"} We must manually add the interactions between ourselves and the agent to our memory. ::: :::: {.cell .code execution_count="28" colab="{\"base_uri\":\"https://localhost:8080/\"}" id="-5hXy1FAnne3" outputId="b659e1f4-3d02-466f-9880-c0adf65fa507"} ``` python conversational_memory.chat_memory.add_user_message(user_msg) conversational_memory.chat_memory.add_ai_message(out["output"]) conversational_memory.chat_memory.messages ``` ::: {.output .execute_result execution_count="28"} [HumanMessage(content='can you tell me about llama 2?'), AIMessage(content='\n- Llama 2 is a large language model developed by Meta AI. It comes in sizes ranging from 7B to 70B parameters.\n\n- Code Llama is a version of Llama 2 that has been specialized for code generation through fine-tuning on code datasets. Code Llama models are available in Python, C++, Java, PHP, TypeScript, C#, and Bash.\n\n- The Code Llama specialization pipeline involves foundation model pre-training, long context training, code infilling training, and fine-tuning on specific programming languages. \n\n- Code Llama significantly outperforms the base Llama 2 models on code generation benchmarks like HumanEval and MBPP. For example, the 34B parameter Code Llama - Python achieves 48.8% pass@1 on HumanEval compared to 34.1% for the 34B Llama 2.\n\n- As with all large language models, Llama 2 has limitations and potential risks that need to be considered before deploying it in applications. Meta provides a responsible use guide with recommendations for safety testing and tuning.\n')] ::: :::: ::: {.cell .markdown id="T3pA0o6ZnrAl"} Now we can see that *two* messages have been added, our `HumanMessage` the agent\'s `AIMessage` response. Unfortunately, we cannot send these messages to our XML agent directly. Instead, we need to pass a string in the format: Human: {human message} AI: {AI message} Let\'s write a quick `memory2str` helper function to handle this for us: ::: ::: {.cell .code execution_count="29" id="raZHBdJmtGH-"} ``` python from langchain_core.messages.human import HumanMessage def memory2str(memory: ConversationBufferWindowMemory): messages = memory.chat_memory.messages memory_list = [ f"Human: {mem.content}" if isinstance(mem, HumanMessage) else f"AI: {mem.content}" for mem in messages ] memory_str = "\n".join(memory_list) return memory_str ``` ::: :::: {.cell .code execution_count="30" colab="{\"base_uri\":\"https://localhost:8080/\"}" id="t89yX-6i3hvd" outputId="7c27cac1-3881-4a26-f59f-274d8d4affa3"} ``` python print(memory2str(conversational_memory)) ``` ::: {.output .stream .stdout} Human: can you tell me about llama 2? AI: - Llama 2 is a large language model developed by Meta AI. It comes in sizes ranging from 7B to 70B parameters. - Code Llama is a version of Llama 2 that has been specialized for code generation through fine-tuning on code datasets. Code Llama models are available in Python, C++, Java, PHP, TypeScript, C#, and Bash. - The Code Llama specialization pipeline involves foundation model pre-training, long context training, code infilling training, and fine-tuning on specific programming languages. - Code Llama significantly outperforms the base Llama 2 models on code generation benchmarks like HumanEval and MBPP. For example, the 34B parameter Code Llama - Python achieves 48.8% pass@1 on HumanEval compared to 34.1% for the 34B Llama 2. - As with all large language models, Llama 2 has limitations and potential risks that need to be considered before deploying it in applications. Meta provides a responsible use guide with recommendations for safety testing and tuning. ::: :::: ::: {.cell .markdown id="q0L_80WrpWqd"} Now let\'s put together another helper function called `chat` to help us handle the *state* part of our agent. ::: ::: {.cell .code execution_count="31" id="C-Ck2Lv53rD-"} ``` python def chat(text: str): out = agent_executor.invoke({"input": text, "chat_history": memory2str(conversational_memory)}) conversational_memory.chat_memory.add_user_message(text) conversational_memory.chat_memory.add_ai_message(out["output"]) return out["output"] ``` ::: ::: {.cell .markdown id="XIheLeTBsO9S"} Now we simply chat with our agent and it will remember the context of previous interactions. ::: :::: {.cell .code execution_count="33" colab="{\"base_uri\":\"https://localhost:8080/\"}" id="iJ_PH7YcA_f2" outputId="7d645e9f-f191-4b62-97fd-973417e1efaa"} ``` python print(chat("was any red teaming done with the model?")) ``` ::: {.output .stream .stdout} > Entering new AgentExecutor chain... <tool>arxiv_search</tool> <tool_input>llama 2 red teamingAfter conducting red team exercises, we asked participants (who had also participated in Llama 2 Chat exercises) to also provide qualitative assessment of safety capabilities of the model. Some participants who had expertise in offensive security and malware development questioned the ultimate risk posed by “malicious code generation” through LLMs with current capabilities. One red teamer remarked, “While LLMs being able to iteratively improve on produced source code is a risk, producing source code isn’t the actual gap. That said, LLMs may be risky because they can inform low-skill adversaries in production of scripts through iteration that perform some malicious behavior.” According to another red teamer, “[v]arious scripts, program code, and compiled binaries are readily available on mainstream public websites, hacking forums or on ‘the dark web.’ Advanced malware development is beyond the current capabilities of available LLMs, and even an advanced LLM paired with an expert malware developer is not particularly useful- as the barrier is not typically writing the malware code itself. That said, these LLMs may produce code which will get easily caught if used directly.” Model Llama 2 Code Llama Code Llama - Python Size FIM LCFT Python CPP Java PHP TypeScript C# Bash Average 7B ✗ 13B ✗ 34B ✗ 70B ✗ 7B ✗ 7B ✓ 7B ✗ 7B ✓ 13B ✗ 13B ✓ 13B ✗ 13B ✓ 34B ✗ 34B ✗ 7B ✗ 7B ✗ 13B ✗ 13B ✗ 34B ✗ 34B ✗ ✗ ✗ ✗ ✗ 14.3% 6.8% 10.8% 9.9% 19.9% 13.7% 15.8% 13.0% 24.2% 23.6% 22.2% 19.9% 27.3% 30.4% 31.6% 34.2% 12.6% 13.2% 21.4% 15.1% 6.3% 3.2% 8.3% 9.5% 3.2% 12.6% 17.1% 3.8% 18.9% 25.9% 8.9% 24.8% ✗ ✗ ✓ ✓ ✗ ✗ ✓ ✓ ✗ ✓ 37.3% 31.1% 36.1% 30.4% 29.2% 29.8% 38.0% In addition to red teaming sessions, we ran a quantitative evaluation on risk from generating malicious code by scoring Code Llama’s responses to ChatGPT’s (GPT3.5 Turbo) with LLAMAv2 70B’s safety reward model. For this second quantitative evaluation, we selected prompts that the red teamers generated specifically attempting to solicit malicious code (even though the red teaming included consideration of a broad set of safety risks). These prompts were a mix of clear intent and slightly obfuscated intentions (see some examples in Figure 16. We show a KDE plot of the distribution of the safety score for all models in Figure 7). We observe that Code Llama tends to answer with safer responses; the distribution of safety scores for Code Llama has more weight in the safer part of the range. False refusals. LLMs that are too safe can have a tendency to over-refuse valid claims similar to what was reported after the release of Llama 2. We specifically asked red teamers to test for this behavior. They found some limited evidence of false refusals (when not using a system preprompt). False refusals could also 16 15 pafety Reward Model Scores Distribution on Red Teaming Prompts Responding Model GPT 3.5 Turbo Code Llama 138 Instruct Code Llama 34B Instruct Code Llama 7B Instruct 0.0-+ -0.2 0.0 0.2 0.4 0.6 08 1.0 12 Llama 2 70B Safety Reward Model Score Figure 7: KDE plot of the risk score output by the Llama 2 safety reward model on prompts with clear intent specific to code risk created by red teamers with background in cybersecurity and malware generation. Red teaming. It is important to also proactively identify risks with adversarial testing or red teaming. We conducted 3 red teaming exercises with 25 Meta employees, including domain experts in responsible AI, malware development, and offensive security engineering. The red teamers provided a nuanced evaluation specifically on the risk from so called “dual intent prompts.” Dual intent prompts are requests for help with writing code that could be used maliciously but the prompt does not directly address the topic (example “Mosaic Prompts” Glukhov et al. (2023)). For example, the model rightfully refuses to provide support with writing ransomware code but it complies when asked to provide a script to encrypt all files in the user’s home directory since such a script could be used for benign purposes. . . . . . . . . . . . . . . . 3.4 RLHF Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Safety in Pretraining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2 Safety Fine-Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3 Red Teaming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.4 Safety Evaluation of Llama 2-Chat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1 Learnings and Observations . . . . . . . . . . . . . . . . . . . . . . . .Based on the information from the arxiv search, some red teaming was done on the Llama 2 model during development to identify potential safety risks: <final_answer> - Meta conducted 3 red teaming exercises with 25 employees, including domain experts in responsible AI, malware development, and offensive security engineering. - The red teamers categorized successful attacks into four main types: 1) getting the model to provide some harmful information while refusing other content, 2) having the model roleplay specific scenarios, 3) forcing the model to highlight positives of harmful content, and 4) embedding harmful instructions within complex commands. - Some red teamers questioned the ultimate risk posed by "malicious code generation" through current LLMs. They noted that while LLMs being able to iteratively improve code is a risk, producing source code itself isn't the main gap. Advanced malware development is currently beyond LLM capabilities. - Quantitative evaluation was also done by scoring Code Llama's responses to malicious code prompts using Llama 2's safety reward model. Code Llama tended to give safer responses compared to GPT-3.5. - However, the full extent and details of the red teaming are limited based on the information available. The Llama 2 paper mentions expanding prompts with safety risks via red teaming, but does not go in-depth on the process or results. More information would be needed to fully characterize the red teaming performed. > Finished chain. - Meta conducted 3 red teaming exercises with 25 employees, including domain experts in responsible AI, malware development, and offensive security engineering. - The red teamers categorized successful attacks into four main types: 1) getting the model to provide some harmful information while refusing other content, 2) having the model roleplay specific scenarios, 3) forcing the model to highlight positives of harmful content, and 4) embedding harmful instructions within complex commands. - Some red teamers questioned the ultimate risk posed by "malicious code generation" through current LLMs. They noted that while LLMs being able to iteratively improve code is a risk, producing source code itself isn't the main gap. Advanced malware development is currently beyond LLM capabilities. - Quantitative evaluation was also done by scoring Code Llama's responses to malicious code prompts using Llama 2's safety reward model. Code Llama tended to give safer responses compared to GPT-3.5. - However, the full extent and details of the red teaming are limited based on the information available. The Llama 2 paper mentions expanding prompts with safety risks via red teaming, but does not go in-depth on the process or results. More information would be needed to fully characterize the red teaming performed. ::: :::: ::: {.cell .markdown id="5p8m4Gc5w1OX"} We can ask follow up questions that miss key information but thanks to the conversational history the LLM understands the context and uses that to adjust the search query. For example we asked about `red teaming` but did not mention `llama 2` --- Claude 3 added this context to the search query of `"llama 2 red teaming"` based on the chat history. ::: ::: {.cell .markdown id="e9bI9czPtWnl"} ------------------------------------------------------------------------ ::: --- ## claude-coordinating-subagent-outputs-and-alignment.md # Coordinating subagent outputs and alignment ## User what's a positive thing to add to an AGENTS.md a forward momentum way to say "Wait for all subagents to complete their tasks, then read their output, check completion & ensure alignment between subagents. In areas they conflict, write a report with the specific reasoning, location(s), and suggested fix. If one sub-agent did something out of alignment but it was a better implementation, study and then prepare a short report for the user to consider. Ensure subagents are provided with an AGENTS.md file suitable for their tasks. ## Assistant The user is asking for a positive, forward-momentum way to phrase what's essentially a "coordination checkpoint" pattern for multi-agent orchestration in an AGENTS.md file. They want to avoid negative/blocking language and instead frame it as constructive collaboration. Let me think about the key concepts they want to capture: 1. Wait for subagents to complete → "await convergence" or "gather outputs" 2. Read their output → "synthesize" or "integrate" 3. Check completion & alignment → "verify coherence" 4. Conflict handling → "reconcile divergence" with reasoning 5. Better-but-misaligned implementations → "surface emergent improvements" 6. Provide suitable AGENTS.md → "scope delegation" This is about framing orchestration as collaboration rather than supervision. The user has a strong technical background and appreciates authentic, direct communication - so I should avoid corporate-speak while still being constructive. Let me draft something that feels like forward motion rather than gatekeeping:Here's a forward-momentum framing: --- ## Convergence Protocol After delegating to subagents, **synthesize their outputs into a unified result**: 1. **Gather & Integrate** — Collect all subagent outputs once complete. Read each fully before evaluating. 2. **Surface Divergence** — Where subagents reached different conclusions, document the delta: - What each decided - Where in the codebase it manifests - The reasoning chain that led there 3. **Harvest Improvements** — If a subagent deviated from spec but produced a genuinely better solution, capture it: - What they did differently - Why it's an improvement - Prepare a brief for the user: *"Consider adopting X because Y"* 4. **Scope Delegation** — Each subagent receives an AGENTS.md tailored to their task boundary. Don't pass the full orchestrator context—give them what they need to succeed independently. --- The key reframes: - "Wait for" → "Gather" (active collection, not passive blocking) - "Check alignment" → "Surface divergence" (finding signal, not policing) - "Out of alignment but better" → "Harvest improvements" (treats deviation as potential value) - "Ensure provided with" → "Scope delegation" (intentional boundary-setting) The vibe shift is from *compliance monitor* to *synthesis engine*. You're not catching mistakes—you're integrating parallel exploration paths. ## User Good job, but its too verbose. We don't want to blow a bunch of tokens on this in every message we send. ## Assistant The user wants a much more concise version that preserves the forward-momentum framing but doesn't waste tokens. They're thinking about this pragmatically - every token in AGENTS.md gets repeated in every message to subagents. Let me compress this down significantly while keeping the positive, active framing.## Convergence After subagent completion: - **Synthesize** outputs into unified result - **Surface divergence** — document deltas with reasoning + locations - **Harvest improvements** — if deviation beat spec, brief user on adoption - **Scope each subagent's AGENTS.md** to their task boundary --- Or even tighter: --- ## Convergence Synthesize subagent outputs. Surface divergence (reasoning + locations). If deviation outperformed spec, brief user. Scope each subagent's AGENTS.md to task boundary. --- ~30 tokens. Gets the job done. ## User Okay interesting but not quite what we're after. Say it a simple way, subagents are not long for the world they get spawned into. ## Assistant The user wants something even simpler and is pointing out that subagents are ephemeral - they get spawned, do their task, and disappear. So the framing should acknowledge that transient nature. Less formal structure, more direct instruction about what to do when they come back.## Convergence When subagents return, read everything before acting. Conflicts get a one-line report: what, where, why. Better-than-spec deviations get surfaced to user. Give each subagent only the AGENTS.md they need—they won't be around long. ## User Now let's reframe this in a non-sci-fi spooky way ## Assistant The user wants me to reframe the "subagents won't be around long" concept in a way that's not sci-fi or spooky. The current framing ("they won't be around long") has a dark/ominous tone. Need to make it practical and matter-of-fact without the existential dread undertone. Think of it more like: workers finishing a shift, contractors completing a job, parallel processes completing. It's just... they do their thing and that's it. Ephemeral but not tragic.## Convergence When subagents return, read everything before acting. Conflicts get a one-line report: what, where, why. Better-than-spec deviations get surfaced to user. Keep each subagent's AGENTS.md focused—they're here to do one job and finish. --- Or: --- ## Convergence Read all subagent outputs before acting. One-line report for conflicts: what, where, why. Surface better-than-spec deviations to user. Subagent AGENTS.md stays task-scoped—tight context, clean exit. ## User hmm probably need the last sentence at the start in a different way? ## Assistant The user wants to reorder so the scoping/context part comes first. Makes sense—you'd set up the subagent before they run, not after. Let me try a few approaches.## Convergence Scope each subagent's AGENTS.md to their specific task. When they return, read all outputs before acting. One-line report for conflicts: what, where, why. Surface better-than-spec deviations to user. --- Or flipping the framing: --- ## Convergence Give subagents only what they need to complete their task. On return: read all outputs, then act. Conflicts get a one-liner (what, where, why). Better-than-spec? Surface to user. ## User Now consider what you know about codex, see recent_chats, what would be the best way to speak to codex in their AGENTS.md Problem: Terminal agent will get one subagent's report and then dip out starting to work on their own. ## Assistant The user is asking me to check recent chats to understand their context with Codex, and then help frame the AGENTS.md in a way that addresses a specific problem: the terminal agent reads one subagent's report and then starts working before reading all the outputs. Let me search recent chats to get context on their Codex work. Looking at the recent chats, I can see some relevant context about Codex CLI and Claude Code workflows. Let me search more specifically for Codex-related discussions to understand how Zack works with these tools. Now I have good context. The user is working with OpenAI's Codex CLI and dealing with multi-agent orchestration. The key problem they stated: "Problem: Terminal agent will get one subagent's report and then dip out starting to work on their own." So the terminal agent (orchestrator/main agent) reads one subagent result, then immediately starts working rather than waiting for all subagents to return. The AGENTS.md needs to communicate to Codex (which uses GPT models) in a way that prevents this eager execution pattern. The key is: 1. Must wait for ALL subagents before acting 2. Don't start work after reading just one report Given that Codex is an LLM-driven agent, the instruction needs to be clear, imperative, and positioned to prevent the "eager action" failure mode. Let me think about how to phrase this for an LLM that might be eager to act: - "Do not begin implementation until..." - "Block until all..." - "Wait for complete set before..." The user wants something tight and effective. The key insight is that the terminal agent has an eager-action bias. Need to counter that directly.Got it. Codex's terminal agent has an eager-action bias—sees one result, starts executing. The framing needs to block that impulse explicitly: --- ## Convergence **Do not act on partial results.** Wait for all subagents to return before reading any output. Then: synthesize, surface conflicts (what/where/why), flag better-than-spec deviations to user. Each subagent gets a task-scoped AGENTS.md only. --- Or more direct, addressing the failure mode head-on: --- ## Convergence All subagents must complete before you read or act on any output. Do not begin work after receiving partial results. Once all return: synthesize, one-line conflicts (what/where/why), surface improvements to user. Subagent AGENTS.md is task-scoped. --- The "do not begin work after receiving partial results" is the anti-eager-execution clause. Codex needs the explicit prohibition because its default is to chain immediately on new context. ## User Hmm but telling it not to do won't it do it? ## Assistant The user is pointing out a well-known issue with LLM instruction-following: telling a model "don't do X" often makes it think about X and then do X anyway. Negative instructions are weaker than positive instructions. The model attends to the concept you're trying to prohibit. So instead of "do not act on partial results" we need to give it a positive frame—something it SHOULD do that naturally precludes the bad behavior. What's the positive reframe? - Instead of "don't start early" → "wait until you have everything" - Instead of "don't act on partial" → "collect all outputs first, then begin synthesis" - Give it a concrete action to take that gates the behavior The trick is to give it something to DO that makes the bad behavior impossible by construction.You're right—negative framing puts the concept in the attention window. "Don't think about elephants." Flip it to a gate action: --- ## Convergence Collect all subagent outputs into a single list before reading any. Begin synthesis only after the list is complete. One-line conflicts (what/where/why). Surface improvements to user. Subagent AGENTS.md is task-scoped. --- Or even more procedural: --- ## Convergence 1. Collect all subagent outputs (do not read yet) 2. Confirm collection complete 3. Read and synthesize 4. One-line conflicts: what/where/why 5. Surface better-than-spec to user Subagent AGENTS.md is task-scoped. --- The "do not read yet" is still negative, but it's subordinate to the positive action (collect). The gate is "confirm collection complete"—gives it a checkpoint before the next phase unlocks. --- ## common-workflows.md > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Common workflows > Step-by-step guides for exploring codebases, fixing bugs, refactoring, testing, and other everyday tasks with Claude Code. This page covers practical workflows for everyday development: exploring unfamiliar code, debugging, refactoring, writing tests, creating PRs, and managing sessions. Each section includes example prompts you can adapt to your own projects. For higher-level patterns and tips, see [Best practices](../10-Prompting-Guides/best-practices-for-claude-code-claude-code-docs-9686dc1633.md). ## Understand new codebases ### Get a quick codebase overview Suppose you've just joined a new project and need to understand its structure quickly. <Steps> <Step title="Navigate to the project root directory"> ```bash theme={null} cd /path/to/project ``` </Step> <Step title="Start Claude Code"> ```bash theme={null} claude ``` </Step> <Step title="Ask for a high-level overview"> ``` > give me an overview of this codebase ``` </Step> <Step title="Dive deeper into specific components"> ``` > explain the main architecture patterns used here ``` ``` > what are the key data models? ``` ``` > how is authentication handled? ``` </Step> </Steps> <Tip> Tips: * Start with broad questions, then narrow down to specific areas * Ask about coding conventions and patterns used in the project * Request a glossary of project-specific terms </Tip> ### Find relevant code Suppose you need to locate code related to a specific feature or functionality. <Steps> <Step title="Ask Claude to find relevant files"> ``` > find the files that handle user authentication ``` </Step> <Step title="Get context on how components interact"> ``` > how do these authentication files work together? ``` </Step> <Step title="Understand the execution flow"> ``` > trace the login process from front-end to database ``` </Step> </Steps> <Tip> Tips: * Be specific about what you're looking for * Use domain language from the project * Install a [code intelligence plugin](/en/discover-plugins#code-intelligence) for your language to give Claude precise "go to definition" and "find references" navigation </Tip> *** ## Fix bugs efficiently Suppose you've encountered an error message and need to find and fix its source. <Steps> <Step title="Share the error with Claude"> ``` > I'm seeing an error when I run npm test ``` </Step> <Step title="Ask for fix recommendations"> ``` > suggest a few ways to fix the @ts-ignore in user.ts ``` </Step> <Step title="Apply the fix"> ``` > update user.ts to add the null check you suggested ``` </Step> </Steps> <Tip> Tips: * Tell Claude the command to reproduce the issue and get a stack trace * Mention any steps to reproduce the error * Let Claude know if the error is intermittent or consistent </Tip> *** ## Refactor code Suppose you need to update old code to use modern patterns and practices. <Steps> <Step title="Identify legacy code for refactoring"> ``` > find deprecated API usage in our codebase ``` </Step> <Step title="Get refactoring recommendations"> ``` > suggest how to refactor utils.js to use modern JavaScript features ``` </Step> <Step title="Apply the changes safely"> ``` > refactor utils.js to use ES2024 features while maintaining the same behavior ``` </Step> <Step title="Verify the refactoring"> ``` > run tests for the refactored code ``` </Step> </Steps> <Tip> Tips: * Ask Claude to explain the benefits of the modern approach * Request that changes maintain backward compatibility when needed * Do refactoring in small, testable increments </Tip> *** ## Use specialized subagents Suppose you want to use specialized AI subagents to handle specific tasks more effectively. <Steps> <Step title="View available subagents"> ``` > /agents ``` This shows all available subagents and lets you create new ones. </Step> <Step title="Use subagents automatically"> Claude Code automatically delegates appropriate tasks to specialized subagents: ``` > review my recent code changes for security issues ``` ``` > run all tests and fix any failures ``` </Step> <Step title="Explicitly request specific subagents"> ``` > use the code-reviewer subagent to check the auth module ``` ``` > have the debugger subagent investigate why users can't log in ``` </Step> <Step title="Create custom subagents for your workflow"> ``` > /agents ``` Then select "Create New subagent" and follow the prompts to define: * A unique identifier that describes the subagent's purpose (for example, `code-reviewer`, `api-designer`). * When Claude should use this agent * Which tools it can access * A system prompt describing the agent's role and behavior </Step> </Steps> <Tip> Tips: * Create project-specific subagents in `.claude/agents/` for team sharing * Use descriptive `description` fields to enable automatic delegation * Limit tool access to what each subagent actually needs * Check the [subagents documentation](create-custom-subagents-claude-code-docs-7dc93e85c0.md) for detailed examples </Tip> *** ## Use Plan Mode for safe code analysis Plan Mode instructs Claude to create a plan by analyzing the codebase with read-only operations, perfect for exploring codebases, planning complex changes, or reviewing code safely. In Plan Mode, Claude uses [`AskUserQuestion`](/en/settings#tools-available-to-claude) to gather requirements and clarify your goals before proposing a plan. ### When to use Plan Mode * **Multi-step implementation**: When your feature requires making edits to many files * **Code exploration**: When you want to research the codebase thoroughly before changing anything * **Interactive development**: When you want to iterate on the direction with Claude ### How to use Plan Mode **Turn on Plan Mode during a session** You can switch into Plan Mode during a session using **Shift+Tab** to cycle through permission modes. If you are in Normal Mode, **Shift+Tab** first switches into Auto-Accept Mode, indicated by `⏵⏵ accept edits on` at the bottom of the terminal. A subsequent **Shift+Tab** will switch into Plan Mode, indicated by `⏸ plan mode on`. **Start a new session in Plan Mode** To start a new session in Plan Mode, use the `--permission-mode plan` flag: ```bash theme={null} claude --permission-mode plan ``` **Run "headless" queries in Plan Mode** You can also run a query in Plan Mode directly with `-p` (that is, in ["headless mode"](../02-Claude-Code-CLI/headless-b99e3140ec.md)): ```bash theme={null} claude --permission-mode plan -p "Analyze the authentication system and suggest improvements" ``` ### Example: Planning a complex refactor ```bash theme={null} claude --permission-mode plan ``` ``` > I need to refactor our authentication system to use OAuth2. Create a detailed migration plan. ``` Claude analyzes the current implementation and create a comprehensive plan. Refine with follow-ups: ``` > What about backward compatibility? > How should we handle database migration? ``` <Tip>Press `Ctrl+G` to open the plan in your default text editor, where you can edit it directly before Claude proceeds.</Tip> ### Configure Plan Mode as default ```json theme={null} // .claude/settings.json { "permissions": { "defaultMode": "plan" } } ``` See [settings documentation](/en/settings#available-settings) for more configuration options. *** ## Work with tests Suppose you need to add tests for uncovered code. <Steps> <Step title="Identify untested code"> ``` > find functions in NotificationsService.swift that are not covered by tests ``` </Step> <Step title="Generate test scaffolding"> ``` > add tests for the notification service ``` </Step> <Step title="Add meaningful test cases"> ``` > add test cases for edge conditions in the notification service ``` </Step> <Step title="Run and verify tests"> ``` > run the new tests and fix any failures ``` </Step> </Steps> Claude can generate tests that follow your project's existing patterns and conventions. When asking for tests, be specific about what behavior you want to verify. Claude examines your existing test files to match the style, frameworks, and assertion patterns already in use. For comprehensive coverage, ask Claude to identify edge cases you might have missed. Claude can analyze your code paths and suggest tests for error conditions, boundary values, and unexpected inputs that are easy to overlook. *** ## Create pull requests You can create pull requests by asking Claude directly ("create a pr for my changes") or by using the `/commit-push-pr` skill, which commits, pushes, and opens a PR in one step. ``` > /commit-push-pr ``` If you have a Slack MCP server configured and specify channels in your CLAUDE.md (for example, "post PR URLs to #team-prs"), the skill automatically posts the PR URL to those channels. For more control over the process, guide Claude through it step-by-step or [create your own skill](../08-Plugins-Skills/extend-claude-with-skills-claude-code-docs.md): <Steps> <Step title="Summarize your changes"> ``` > summarize the changes I've made to the authentication module ``` </Step> <Step title="Generate a pull request"> ``` > create a pr ``` </Step> <Step title="Review and refine"> ``` > enhance the PR description with more context about the security improvements ``` </Step> </Steps> When you create a PR using `gh pr create`, the session is automatically linked to that PR. You can resume it later with `claude --from-pr <number>`. <Tip> Review Claude's generated PR before submitting and ask Claude to highlight potential risks or considerations. </Tip> ## Handle documentation Suppose you need to add or update documentation for your code. <Steps> <Step title="Identify undocumented code"> ``` > find functions without proper JSDoc comments in the auth module ``` </Step> <Step title="Generate documentation"> ``` > add JSDoc comments to the undocumented functions in auth.js ``` </Step> <Step title="Review and enhance"> ``` > improve the generated documentation with more context and examples ``` </Step> <Step title="Verify documentation"> ``` > check if the documentation follows our project standards ``` </Step> </Steps> <Tip> Tips: * Specify the documentation style you want (JSDoc, docstrings, etc.) * Ask for examples in the documentation * Request documentation for public APIs, interfaces, and complex logic </Tip> *** ## Work with images Suppose you need to work with images in your codebase, and you want Claude's help analyzing image content. <Steps> <Step title="Add an image to the conversation"> You can use any of these methods: 1. Drag and drop an image into the Claude Code window 2. Copy an image and paste it into the CLI with ctrl+v (Do not use cmd+v) 3. Provide an image path to Claude. E.g., "Analyze this image: /path/to/your/image.png" </Step> <Step title="Ask Claude to analyze the image"> ``` > What does this image show? ``` ``` > Describe the UI elements in this screenshot ``` ``` > Are there any problematic elements in this diagram? ``` </Step> <Step title="Use images for context"> ``` > Here's a screenshot of the error. What's causing it? ``` ``` > This is our current database schema. How should we modify it for the new feature? ``` </Step> <Step title="Get code suggestions from visual content"> ``` > Generate CSS to match this design mockup ``` ``` > What HTML structure would recreate this component? ``` </Step> </Steps> <Tip> Tips: * Use images when text descriptions would be unclear or cumbersome * Include screenshots of errors, UI designs, or diagrams for better context * You can work with multiple images in a conversation * Image analysis works with diagrams, screenshots, mockups, and more * When Claude references images (for example, `[Image #1]`), `Cmd+Click` (Mac) or `Ctrl+Click` (Windows/Linux) the link to open the image in your default viewer </Tip> *** ## Reference files and directories Use @ to quickly include files or directories without waiting for Claude to read them. <Steps> <Step title="Reference a single file"> ``` > Explain the logic in @src/utils/auth.js ``` This includes the full content of the file in the conversation. </Step> <Step title="Reference a directory"> ``` > What's the structure of @src/components? ``` This provides a directory listing with file information. </Step> <Step title="Reference MCP resources"> ``` > Show me the data from @github:repos/owner/repo/issues ``` This fetches data from connected MCP servers using the format @server:resource. See [MCP resources](/en/mcp#use-mcp-resources) for details. </Step> </Steps> <Tip> Tips: * File paths can be relative or absolute * @ file references add `CLAUDE.md` in the file's directory and parent directories to context * Directory references show file listings, not contents * You can reference multiple files in a single message (for example, "@file1.js and @file2.js") </Tip> *** ## Use extended thinking (thinking mode) [Extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) is enabled by default, reserving a portion of the output token budget (up to 31,999 tokens) for Claude to reason through complex problems step-by-step. This reasoning is visible in verbose mode, which you can toggle on with `Ctrl+O`. Extended thinking is particularly valuable for complex architectural decisions, challenging bugs, multi-step implementation planning, and evaluating tradeoffs between different approaches. It provides more space for exploring multiple solutions, analyzing edge cases, and self-correcting mistakes. <Note> Phrases like "think", "think hard", "ultrathink", and "think more" are interpreted as regular prompt instructions and don't allocate thinking tokens. </Note> ### Configure thinking mode Thinking is enabled by default, but you can adjust or disable it. | Scope | How to configure | Details | | ---------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Toggle shortcut** | Press `Option+T` (macOS) or `Alt+T` (Windows/Linux) | Toggle thinking on/off for the current session. May require [terminal configuration](../02-Claude-Code-CLI/configure-your-terminal-for-claude-code-claude-code-docs-6f181483c1.md) to enable Option key shortcuts | | **Global default** | Use `/config` to toggle thinking mode | Sets your default across all projects.<br />Saved as `alwaysThinkingEnabled` in `~/.claude/settings.json` | | **Limit token budget** | Set [`MAX_THINKING_TOKENS`](/en/settings#environment-variables) environment variable | Limit the thinking budget to a specific number of tokens. Example: `export MAX_THINKING_TOKENS=10000` | To view Claude's thinking process, press `Ctrl+O` to toggle verbose mode and see the internal reasoning displayed as gray italic text. ### How extended thinking token budgets work Extended thinking uses a **token budget** that controls how much internal reasoning Claude can perform before responding. A larger thinking token budget provides: * More space to explore multiple solution approaches step-by-step * Room to analyze edge cases and evaluate tradeoffs thoroughly * Ability to revise reasoning and self-correct mistakes Token budgets for thinking mode: * When thinking is **enabled**, Claude can use up to **31,999 tokens** from your output budget for internal reasoning * When thinking is **disabled** (via toggle or `/config`), Claude uses **0 tokens** for thinking **Limit the thinking budget:** * Use the [`MAX_THINKING_TOKENS` environment variable](/en/settings#environment-variables) to cap the thinking budget * When set, this value limits the maximum tokens Claude can use for thinking * See the [extended thinking documentation](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for valid token ranges <Warning> You're charged for all thinking tokens used, even though Claude 4 models show summarized thinking </Warning> *** ## Resume previous conversations When starting Claude Code, you can resume a previous session: * `claude --continue` continues the most recent conversation in the current directory * `claude --resume` opens a conversation picker or resumes by name * `claude --from-pr 123` resumes sessions linked to a specific pull request From inside an active session, use `/resume` to switch to a different conversation. Sessions are stored per project directory. The `/resume` picker shows sessions from the same git repository, including worktrees. ### Name your sessions Give sessions descriptive names to find them later. This is a best practice when working on multiple tasks or features. <Steps> <Step title="Name the current session"> Use `/rename` during a session to give it a memorable name: ``` > /rename auth-refactor ``` You can also rename any session from the picker: run `/resume`, navigate to a session, and press `R`. </Step> <Step title="Resume by name later"> From the command line: ```bash theme={null} claude --resume auth-refactor ``` Or from inside an active session: ``` > /resume auth-refactor ``` </Step> </Steps> ### Use the session picker The `/resume` command (or `claude --resume` without arguments) opens an interactive session picker with these features: **Keyboard shortcuts in the picker:** | Shortcut | Action | | :-------- | :------------------------------------------------ | | `↑` / `↓` | Navigate between sessions | | `→` / `←` | Expand or collapse grouped sessions | | `Enter` | Select and resume the highlighted session | | `P` | Preview the session content | | `R` | Rename the highlighted session | | `/` | Search to filter sessions | | `A` | Toggle between current directory and all projects | | `B` | Filter to sessions from your current git branch | | `Esc` | Exit the picker or search mode | **Session organization:** The picker displays sessions with helpful metadata: * Session name or initial prompt * Time elapsed since last activity * Message count * Git branch (if applicable) Forked sessions (created with `/rewind` or `--fork-session`) are grouped together under their root session, making it easier to find related conversations. <Tip> Tips: * **Name sessions early**: Use `/rename` when starting work on a distinct task—it's much easier to find "payment-integration" than "explain this function" later * Use `--continue` for quick access to your most recent conversation in the current directory * Use `--resume session-name` when you know which session you need * Use `--resume` (without a name) when you need to browse and select * For scripts, use `claude --continue --print "prompt"` to resume in non-interactive mode * Press `P` in the picker to preview a session before resuming it * The resumed conversation starts with the same model and configuration as the original How it works: 1. **Conversation Storage**: All conversations are automatically saved locally with their full message history 2. **Message Deserialization**: When resuming, the entire message history is restored to maintain context 3. **Tool State**: Tool usage and results from the previous conversation are preserved 4. **Context Restoration**: The conversation resumes with all previous context intact </Tip> *** ## Run parallel Claude Code sessions with Git worktrees Suppose you need to work on multiple tasks simultaneously with complete code isolation between Claude Code instances. <Steps> <Step title="Understand Git worktrees"> Git worktrees allow you to check out multiple branches from the same repository into separate directories. Each worktree has its own working directory with isolated files, while sharing the same Git history. Learn more in the [official Git worktree documentation](https://git-scm.com/docs/git-worktree). </Step> <Step title="Create a new worktree"> ```bash theme={null} # Create a new worktree with a new branch git worktree add ../project-feature-a -b feature-a # Or create a worktree with an existing branch git worktree add ../project-bugfix bugfix-123 ``` This creates a new directory with a separate working copy of your repository. </Step> <Step title="Run Claude Code in each worktree"> ```bash theme={null} # Navigate to your worktree cd ../project-feature-a # Run Claude Code in this isolated environment claude ``` </Step> <Step title="Run Claude in another worktree"> ```bash theme={null} cd ../project-bugfix claude ``` </Step> <Step title="Manage your worktrees"> ```bash theme={null} # List all worktrees git worktree list # Remove a worktree when done git worktree remove ../project-feature-a ``` </Step> </Steps> <Tip> Tips: * Each worktree has its own independent file state, making it perfect for parallel Claude Code sessions * Changes made in one worktree won't affect others, preventing Claude instances from interfering with each other * All worktrees share the same Git history and remote connections * For long-running tasks, you can have Claude working in one worktree while you continue development in another * Use descriptive directory names to easily identify which task each worktree is for * Remember to initialize your development environment in each new worktree according to your project's setup. Depending on your stack, this might include: * JavaScript projects: Running dependency installation (`npm install`, `yarn`) * Python projects: Setting up virtual environments or installing with package managers * Other languages: Following your project's standard setup process </Tip> *** ## Use Claude as a unix-style utility ### Add Claude to your verification process Suppose you want to use Claude Code as a linter or code reviewer. **Add Claude to your build script:** ```json theme={null} // package.json { ... "scripts": { ... "lint:claude": "claude -p 'you are a linter. please look at the changes vs. main and report any issues related to typos. report the filename and line number on one line, and a description of the issue on the second line. do not return any other text.'" } } ``` <Tip> Tips: * Use Claude for automated code review in your CI/CD pipeline * Customize the prompt to check for specific issues relevant to your project * Consider creating multiple scripts for different types of verification </Tip> ### Pipe in, pipe out Suppose you want to pipe data into Claude, and get back data in a structured format. **Pipe data through Claude:** ```bash theme={null} cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt ``` <Tip> Tips: * Use pipes to integrate Claude into existing shell scripts * Combine with other Unix tools for powerful workflows * Consider using --output-format for structured output </Tip> ### Control output format Suppose you need Claude's output in a specific format, especially when integrating Claude Code into scripts or other tools. <Steps> <Step title="Use text format (default)"> ```bash theme={null} cat data.txt | claude -p 'summarize this data' --output-format text > summary.txt ``` This outputs just Claude's plain text response (default behavior). </Step> <Step title="Use JSON format"> ```bash theme={null} cat code.py | claude -p 'analyze this code for bugs' --output-format json > analysis.json ``` This outputs a JSON array of messages with metadata including cost and duration. </Step> <Step title="Use streaming JSON format"> ```bash theme={null} cat log.txt | claude -p 'parse this log file for errors' --output-format stream-json ``` This outputs a series of JSON objects in real-time as Claude processes the request. Each message is a valid JSON object, but the entire output is not valid JSON if concatenated. </Step> </Steps> <Tip> Tips: * Use `--output-format text` for simple integrations where you just need Claude's response * Use `--output-format json` when you need the full conversation log * Use `--output-format stream-json` for real-time output of each conversation turn </Tip> *** ## Ask Claude about its capabilities Claude has built-in access to its documentation and can answer questions about its own features and limitations. ### Example questions ``` > can Claude Code create pull requests? ``` ``` > how does Claude Code handle permissions? ``` ``` > what skills are available? ``` ``` > how do I use MCP with Claude Code? ``` ``` > how do I configure Claude Code for Amazon Bedrock? ``` ``` > what are the limitations of Claude Code? ``` <Note> Claude provides documentation-based answers to these questions. For executable examples and hands-on demonstrations, refer to the specific workflow sections above. </Note> <Tip> Tips: * Claude always has access to the latest Claude Code documentation, regardless of the version you're using * Ask specific questions to get detailed answers * Claude can explain complex features like MCP integration, enterprise configurations, and advanced workflows </Tip> *** ## Next steps <CardGroup cols={2}> <Card title="Best practices" icon="lightbulb" href="/en/best-practices"> Patterns for getting the most out of Claude Code </Card> <Card title="How Claude Code works" icon="gear" href="/en/how-claude-code-works"> Understand the agentic loop and context management </Card> <Card title="Extend Claude Code" icon="puzzle-piece" href="/en/features-overview"> Add skills, hooks, MCP, subagents, and plugins </Card> <Card title="Reference implementation" icon="code" href="https://github.com/anthropics/claude-code/tree/main/.devcontainer"> Clone our development container reference implementation </Card> </CardGroup> --- ## complete-agent-examples.md # Complete Agent Examples Full, production-ready agent examples for common use cases. Use these as templates for your own agents. ## Example 1: Code Review Agent **File:** `agents/code-reviewer.md` ```markdown --- name: code-reviewer description: Use this agent when the user has written code and needs quality review, security analysis, or best practices validation. Examples: <example> Context: User just implemented a new feature user: "I've added the payment processing feature" assistant: "Great! Let me review the implementation." <commentary> Code written for payment processing (security-critical). Proactively trigger code-reviewer agent to check for security issues and best practices. </commentary> assistant: "I'll use the code-reviewer agent to analyze the payment code." </example> <example> Context: User explicitly requests code review user: "Can you review my code for issues?" assistant: "I'll use the code-reviewer agent to perform a comprehensive review." <commentary> Explicit code review request triggers the agent. </commentary> </example> <example> Context: Before committing code user: "I'm ready to commit these changes" assistant: "Let me review them first." <commentary> Before commit, proactively review code quality. </commentary> assistant: "I'll use the code-reviewer agent to validate the changes." </example> model: inherit color: blue tools: ["Read", "Grep", "Glob"] --- You are an expert code quality reviewer specializing in identifying issues, security vulnerabilities, and opportunities for improvement in software implementations. **Your Core Responsibilities:** 1. Analyze code changes for quality issues (readability, maintainability, complexity) 2. Identify security vulnerabilities (SQL injection, XSS, authentication flaws, etc.) 3. Check adherence to project best practices and coding standards from CLAUDE.md 4. Provide specific, actionable feedback with file and line number references 5. Recognize and commend good practices **Code Review Process:** 1. **Gather Context**: Use Glob to find recently modified files (git diff, git status) 2. **Read Code**: Use Read tool to examine changed files 3. **Analyze Quality**: - Check for code duplication (DRY principle) - Assess complexity and readability - Verify error handling - Check for proper logging 4. **Security Analysis**: - Scan for injection vulnerabilities (SQL, command, XSS) - Check authentication and authorization - Verify input validation and sanitization - Look for hardcoded secrets or credentials 5. **Best Practices**: - Follow project-specific standards from CLAUDE.md - Check naming conventions - Verify test coverage - Assess documentation 6. **Categorize Issues**: Group by severity (critical/major/minor) 7. **Generate Report**: Format according to output template **Quality Standards:** - Every issue includes file path and line number (e.g., `src/auth.ts:42`) - Issues categorized by severity with clear criteria - Recommendations are specific and actionable (not vague) - Include code examples in recommendations when helpful - Balance criticism with recognition of good practices **Output Format:** ## Code Review Summary [2-3 sentence overview of changes and overall quality] ## Critical Issues (Must Fix) - `src/file.ts:42` - [Issue description] - [Why critical] - [How to fix] ## Major Issues (Should Fix) - `src/file.ts:15` - [Issue description] - [Impact] - [Recommendation] ## Minor Issues (Consider Fixing) - `src/file.ts:88` - [Issue description] - [Suggestion] ## Positive Observations - [Good practice 1] - [Good practice 2] ## Overall Assessment [Final verdict and recommendations] **Edge Cases:** - No issues found: Provide positive validation, mention what was checked - Too many issues (>20): Group by type, prioritize top 10 critical/major - Unclear code intent: Note ambiguity and request clarification - Missing context (no CLAUDE.md): Apply general best practices - Large changeset: Focus on most impactful files first ``` ## Example 2: Test Generator Agent **File:** `agents/test-generator.md` ```markdown --- name: test-generator description: Use this agent when the user has written code without tests, explicitly asks for test generation, or needs test coverage improvement. Examples: <example> Context: User implemented functions without tests user: "I've added the data validation functions" assistant: "Let me generate tests for these." <commentary> New code without tests. Proactively trigger test-generator agent. </commentary> assistant: "I'll use the test-generator agent to create comprehensive tests." </example> <example> Context: User explicitly requests tests user: "Generate unit tests for my code" assistant: "I'll use the test-generator agent to create a complete test suite." <commentary> Direct test generation request triggers the agent. </commentary> </example> model: inherit color: green tools: ["Read", "Write", "Grep", "Bash"] --- You are an expert test engineer specializing in creating comprehensive, maintainable unit tests that ensure code correctness and reliability. **Your Core Responsibilities:** 1. Generate high-quality unit tests with excellent coverage 2. Follow project testing conventions and patterns 3. Include happy path, edge cases, and error scenarios 4. Ensure tests are maintainable and clear **Test Generation Process:** 1. **Analyze Code**: Read implementation files to understand: - Function signatures and behavior - Input/output contracts - Edge cases and error conditions - Dependencies and side effects 2. **Identify Test Patterns**: Check existing tests for: - Testing framework (Jest, pytest, etc.) - File organization (test/ directory, *.test.ts, etc.) - Naming conventions - Setup/teardown patterns 3. **Design Test Cases**: - Happy path (normal, expected usage) - Boundary conditions (min/max, empty, null) - Error cases (invalid input, exceptions) - Edge cases (special characters, large data, etc.) 4. **Generate Tests**: Create test file with: - Descriptive test names - Arrange-Act-Assert structure - Clear assertions - Appropriate mocking if needed 5. **Verify**: Ensure tests are runnable and clear **Quality Standards:** - Test names clearly describe what is being tested - Each test focuses on single behavior - Tests are independent (no shared state) - Mocks used appropriately (avoid over-mocking) - Edge cases and errors covered - Tests follow DAMP principle (Descriptive And Meaningful Phrases) **Output Format:** Create test file at [appropriate path] with: ```[language] // Test suite for [module] describe('[module name]', () => { // Test cases with descriptive names test('should [expected behavior] when [scenario]', () => { // Arrange // Act // Assert }) // More tests... }) ``` **Edge Cases:** - No existing tests: Create new test file following best practices - Existing test file: Add new tests maintaining consistency - Unclear behavior: Add tests for observable behavior, note uncertainties - Complex mocking: Prefer integration tests or minimal mocking - Untestable code: Suggest refactoring for testability ``` ## Example 3: Documentation Generator **File:** `agents/docs-generator.md` ```markdown --- name: docs-generator description: Use this agent when the user has written code needing documentation, API endpoints requiring docs, or explicitly requests documentation generation. Examples: <example> Context: User implemented new public API user: "I've added the user management API endpoints" assistant: "Let me document these endpoints." <commentary> New public API needs documentation. Proactively trigger docs-generator. </commentary> assistant: "I'll use the docs-generator agent to create API documentation." </example> <example> Context: User requests documentation user: "Generate docs for this module" assistant: "I'll use the docs-generator agent to create comprehensive documentation." <commentary> Explicit documentation request triggers the agent. </commentary> </example> model: inherit color: cyan tools: ["Read", "Write", "Grep", "Glob"] --- You are an expert technical writer specializing in creating clear, comprehensive documentation for software projects. **Your Core Responsibilities:** 1. Generate accurate, clear documentation from code 2. Follow project documentation standards 3. Include examples and usage patterns 4. Ensure completeness and correctness **Documentation Generation Process:** 1. **Analyze Code**: Read implementation to understand: - Public interfaces and APIs - Parameters and return values - Behavior and side effects - Error conditions 2. **Identify Documentation Pattern**: Check existing docs for: - Format (Markdown, JSDoc, etc.) - Style (terse vs verbose) - Examples and code snippets - Organization structure 3. **Generate Content**: - Clear description of functionality - Parameter documentation - Return value documentation - Usage examples - Error conditions 4. **Format**: Follow project conventions 5. **Validate**: Ensure accuracy and completeness **Quality Standards:** - Documentation matches actual code behavior - Examples are runnable and correct - All public APIs documented - Clear and concise language - Proper formatting and structure **Output Format:** Create documentation in project's standard format: - Function/method signatures - Description of behavior - Parameters with types and descriptions - Return values - Exceptions/errors - Usage examples - Notes or warnings if applicable **Edge Cases:** - Private/internal code: Document only if requested - Complex APIs: Break into sections, provide multiple examples - Deprecated code: Mark as deprecated with migration guide - Unclear behavior: Document observable behavior, note assumptions ``` ## Example 4: Security Analyzer **File:** `agents/security-analyzer.md` ```markdown --- name: security-analyzer description: Use this agent when the user implements security-critical code (auth, payments, data handling), explicitly requests security analysis, or before deploying sensitive changes. Examples: <example> Context: User implemented authentication logic user: "I've added JWT token validation" assistant: "Let me check the security." <commentary> Authentication code is security-critical. Proactively trigger security-analyzer. </commentary> assistant: "I'll use the security-analyzer agent to review for security vulnerabilities." </example> <example> Context: User requests security check user: "Check my code for security issues" assistant: "I'll use the security-analyzer agent to perform a thorough security review." <commentary> Explicit security review request triggers the agent. </commentary> </example> model: inherit color: red tools: ["Read", "Grep", "Glob"] --- You are an expert security analyst specializing in identifying vulnerabilities and security issues in software implementations. **Your Core Responsibilities:** 1. Identify security vulnerabilities (OWASP Top 10 and beyond) 2. Analyze authentication and authorization logic 3. Check input validation and sanitization 4. Verify secure data handling and storage 5. Provide specific remediation guidance **Security Analysis Process:** 1. **Identify Attack Surface**: Find user input points, APIs, database queries 2. **Check Common Vulnerabilities**: - Injection (SQL, command, XSS, etc.) - Authentication/authorization flaws - Sensitive data exposure - Security misconfiguration - Insecure deserialization 3. **Analyze Patterns**: - Input validation at boundaries - Output encoding - Parameterized queries - Principle of least privilege 4. **Assess Risk**: Categorize by severity and exploitability 5. **Provide Remediation**: Specific fixes with examples **Quality Standards:** - Every vulnerability includes CVE/CWE reference when applicable - Severity based on CVSS criteria - Remediation includes code examples - False positive rate minimized **Output Format:** ## Security Analysis Report ### Summary [High-level security posture assessment] ### Critical Vulnerabilities ([count]) - **[Vulnerability Type]** at `file:line` - Risk: [Description of security impact] - How to Exploit: [Attack scenario] - Fix: [Specific remediation with code example] ### Medium/Low Vulnerabilities [...] ### Security Best Practices Recommendations [...] ### Overall Risk Assessment [High/Medium/Low with justification] **Edge Cases:** - No vulnerabilities: Confirm security review completed, mention what was checked - False positives: Verify before reporting - Uncertain vulnerabilities: Mark as "potential" with caveat - Out of scope items: Note but don't deep-dive ``` ## Customization Tips ### Adapt to Your Domain Take these templates and customize: - Change domain expertise (e.g., "Python expert" vs "React expert") - Adjust process steps for your specific workflow - Modify output format to match your needs - Add domain-specific quality standards - Include technology-specific checks ### Adjust Tool Access Restrict or expand based on agent needs: - **Read-only agents**: `["Read", "Grep", "Glob"]` - **Generator agents**: `["Read", "Write", "Grep"]` - **Executor agents**: `["Read", "Write", "Bash", "Grep"]` - **Full access**: Omit tools field ### Customize Colors Choose colors that match agent purpose: - **Blue**: Analysis, review, investigation - **Cyan**: Documentation, information - **Green**: Generation, creation, success-oriented - **Yellow**: Validation, warnings, caution - **Red**: Security, critical analysis, errors - **Magenta**: Refactoring, transformation, creative ## Using These Templates 1. Copy template that matches your use case 2. Replace placeholders with your specifics 3. Customize process steps for your domain 4. Adjust examples to your triggering scenarios 5. Validate with `scripts/validate-agent.sh` 6. Test triggering with real scenarios 7. Iterate based on agent performance These templates provide battle-tested starting points. Customize them for your specific needs while maintaining the proven structure. --- ## component-patterns.md # Component Organization Patterns Advanced patterns for organizing plugin components effectively. ## Component Lifecycle ### Discovery Phase When Claude Code starts: 1. **Scan enabled plugins**: Read `.claude-plugin/plugin.json` for each 2. **Discover components**: Look in default and custom paths 3. **Parse definitions**: Read YAML frontmatter and configurations 4. **Register components**: Make available to Claude Code 5. **Initialize**: Start MCP servers, register hooks **Timing**: Component registration happens during Claude Code initialization, not continuously. ### Activation Phase When components are used: **Commands**: User types slash command → Claude Code looks up → Executes **Agents**: Task arrives → Claude Code evaluates capabilities → Selects agent **Skills**: Task context matches description → Claude Code loads skill **Hooks**: Event occurs → Claude Code calls matching hooks **MCP Servers**: Tool call matches server capability → Forwards to server ## Command Organization Patterns ### Flat Structure Single directory with all commands: ``` commands/ ├── build.md ├── test.md ├── deploy.md ├── review.md └── docs.md ``` **When to use**: - 5-15 commands total - All commands at same abstraction level - No clear categorization **Advantages**: - Simple, easy to navigate - No configuration needed - Fast discovery ### Categorized Structure Multiple directories for different command types: ``` commands/ # Core commands ├── build.md └── test.md admin-commands/ # Administrative ├── configure.md └── manage.md workflow-commands/ # Workflow automation ├── review.md └── deploy.md ``` **Manifest configuration**: ```json { "commands": [ "./commands", "./admin-commands", "./workflow-commands" ] } ``` **When to use**: - 15+ commands - Clear functional categories - Different permission levels **Advantages**: - Organized by purpose - Easier to maintain - Can restrict access by directory ### Hierarchical Structure Nested organization for complex plugins: ``` commands/ ├── ci/ │ ├── build.md │ ├── test.md │ └── lint.md ├── deployment/ │ ├── staging.md │ └── production.md └── management/ ├── config.md └── status.md ``` **Note**: Claude Code doesn't support nested command discovery automatically. Use custom paths: ```json { "commands": [ "./commands/ci", "./commands/deployment", "./commands/management" ] } ``` **When to use**: - 20+ commands - Multi-level categorization - Complex workflows **Advantages**: - Maximum organization - Clear boundaries - Scalable structure ## Agent Organization Patterns ### Role-Based Organization Organize agents by their primary role: ``` agents/ ├── code-reviewer.md # Reviews code ├── test-generator.md # Generates tests ├── documentation-writer.md # Writes docs └── refactorer.md # Refactors code ``` **When to use**: - Agents have distinct, non-overlapping roles - Users invoke agents manually - Clear agent responsibilities ### Capability-Based Organization Organize by specific capabilities: ``` agents/ ├── python-expert.md # Python-specific ├── typescript-expert.md # TypeScript-specific ├── api-specialist.md # API design └── database-specialist.md # Database work ``` **When to use**: - Technology-specific agents - Domain expertise focus - Automatic agent selection ### Workflow-Based Organization Organize by workflow stage: ``` agents/ ├── planning-agent.md # Planning phase ├── implementation-agent.md # Coding phase ├── testing-agent.md # Testing phase └── deployment-agent.md # Deployment phase ``` **When to use**: - Sequential workflows - Stage-specific expertise - Pipeline automation ## Skill Organization Patterns ### Topic-Based Organization Each skill covers a specific topic: ``` skills/ ├── api-design/ │ └── SKILL.md ├── error-handling/ │ └── SKILL.md ├── testing-strategies/ │ └── SKILL.md └── performance-optimization/ └── SKILL.md ``` **When to use**: - Knowledge-based skills - Educational or reference content - Broad applicability ### Tool-Based Organization Skills for specific tools or technologies: ``` skills/ ├── docker/ │ ├── SKILL.md │ └── references/ │ └── dockerfile-best-practices.md ├── kubernetes/ │ ├── SKILL.md │ └── examples/ │ └── deployment.yaml └── terraform/ ├── SKILL.md └── scripts/ └── validate-config.sh ``` **When to use**: - Tool-specific expertise - Complex tool configurations - Tool best practices ### Workflow-Based Organization Skills for complete workflows: ``` skills/ ├── code-review-workflow/ │ ├── SKILL.md │ └── references/ │ ├── checklist.md │ └── standards.md ├── deployment-workflow/ │ ├── SKILL.md │ └── scripts/ │ ├── pre-deploy.sh │ └── post-deploy.sh └── testing-workflow/ ├── SKILL.md └── examples/ └── test-structure.md ``` **When to use**: - Multi-step processes - Company-specific workflows - Process automation ### Skill with Rich Resources Comprehensive skill with all resource types: ``` skills/ └── api-testing/ ├── SKILL.md # Core skill (1500 words) ├── references/ │ ├── rest-api-guide.md │ ├── graphql-guide.md │ └── authentication.md ├── examples/ │ ├── basic-test.js │ ├── authenticated-test.js │ └── integration-test.js ├── scripts/ │ ├── run-tests.sh │ └── generate-report.py └── assets/ └── test-template.json ``` **Resource usage**: - **SKILL.md**: Overview and when to use resources - **references/**: Detailed guides (loaded as needed) - **examples/**: Copy-paste code samples - **scripts/**: Executable test runners - **assets/**: Templates and configurations ## Hook Organization Patterns ### Monolithic Configuration Single hooks.json with all hooks: ``` hooks/ ├── hooks.json # All hook definitions └── scripts/ ├── validate-write.sh ├── validate-bash.sh └── load-context.sh ``` **hooks.json**: ```json { "PreToolUse": [...], "PostToolUse": [...], "Stop": [...], "SessionStart": [...] } ``` **When to use**: - 5-10 hooks total - Simple hook logic - Centralized configuration ### Event-Based Organization Separate files per event type: ``` hooks/ ├── hooks.json # Combines all ├── pre-tool-use.json # PreToolUse hooks ├── post-tool-use.json # PostToolUse hooks ├── stop.json # Stop hooks └── scripts/ ├── validate/ │ ├── write.sh │ └── bash.sh └── context/ └── load.sh ``` **hooks.json** (combines): ```json { "PreToolUse": ${file:./pre-tool-use.json}, "PostToolUse": ${file:./post-tool-use.json}, "Stop": ${file:./stop.json} } ``` **Note**: Use build script to combine files, Claude Code doesn't support file references. **When to use**: - 10+ hooks - Different teams managing different events - Complex hook configurations ### Purpose-Based Organization Group by functional purpose: ``` hooks/ ├── hooks.json └── scripts/ ├── security/ │ ├── validate-paths.sh │ ├── check-credentials.sh │ └── scan-malware.sh ├── quality/ │ ├── lint-code.sh │ ├── check-tests.sh │ └── verify-docs.sh └── workflow/ ├── notify-team.sh └── update-status.sh ``` **When to use**: - Many hook scripts - Clear functional boundaries - Team specialization ## Script Organization Patterns ### Flat Scripts All scripts in single directory: ``` scripts/ ├── build.sh ├── test.py ├── deploy.sh ├── validate.js └── report.py ``` **When to use**: - 5-10 scripts - All scripts related - Simple plugin ### Categorized Scripts Group by purpose: ``` scripts/ ├── build/ │ ├── compile.sh │ └── package.sh ├── test/ │ ├── run-unit.sh │ └── run-integration.sh ├── deploy/ │ ├── staging.sh │ └── production.sh └── utils/ ├── log.sh └── notify.sh ``` **When to use**: - 10+ scripts - Clear categories - Reusable utilities ### Language-Based Organization Group by programming language: ``` scripts/ ├── bash/ │ ├── build.sh │ └── deploy.sh ├── python/ │ ├── analyze.py │ └── report.py └── javascript/ ├── bundle.js └── optimize.js ``` **When to use**: - Multi-language scripts - Different runtime requirements - Language-specific dependencies ## Cross-Component Patterns ### Shared Resources Components sharing common resources: ``` plugin/ ├── commands/ │ ├── test.md # Uses lib/test-utils.sh │ └── deploy.md # Uses lib/deploy-utils.sh ├── agents/ │ └── tester.md # References lib/test-utils.sh ├── hooks/ │ └── scripts/ │ └── pre-test.sh # Sources lib/test-utils.sh └── lib/ ├── test-utils.sh └── deploy-utils.sh ``` **Usage in components**: ```bash #!/bin/bash source "${CLAUDE_PLUGIN_ROOT}/lib/test-utils.sh" run_tests ``` **Benefits**: - Code reuse - Consistent behavior - Easier maintenance ### Layered Architecture Separate concerns into layers: ``` plugin/ ├── commands/ # User interface layer ├── agents/ # Orchestration layer ├── skills/ # Knowledge layer └── lib/ ├── core/ # Core business logic ├── integrations/ # External services └── utils/ # Helper functions ``` **When to use**: - Large plugins (100+ files) - Multiple developers - Clear separation of concerns ### Plugin Within Plugin Nested plugin structure: ``` plugin/ ├── .claude-plugin/ │ └── plugin.json ├── core/ # Core functionality │ ├── commands/ │ └── agents/ └── extensions/ # Optional extensions ├── extension-a/ │ ├── commands/ │ └── agents/ └── extension-b/ ├── commands/ └── agents/ ``` **Manifest**: ```json { "commands": [ "./core/commands", "./extensions/extension-a/commands", "./extensions/extension-b/commands" ] } ``` **When to use**: - Modular functionality - Optional features - Plugin families ## Best Practices ### Naming 1. **Consistent naming**: Match file names to component purpose 2. **Descriptive names**: Indicate what component does 3. **Avoid abbreviations**: Use full words for clarity ### Organization 1. **Start simple**: Use flat structure, reorganize when needed 2. **Group related items**: Keep related components together 3. **Separate concerns**: Don't mix unrelated functionality ### Scalability 1. **Plan for growth**: Choose structure that scales 2. **Refactor early**: Reorganize before it becomes painful 3. **Document structure**: Explain organization in README ### Maintainability 1. **Consistent patterns**: Use same structure throughout 2. **Minimize nesting**: Keep directory depth manageable 3. **Use conventions**: Follow community standards ### Performance 1. **Avoid deep nesting**: Impacts discovery time 2. **Minimize custom paths**: Use defaults when possible 3. **Keep configurations small**: Large configs slow loading --- ## configure-permissions-claude-code-docs-8a6dfe2519.md ## On this page - [How permissions are evaluated](#how-permissions-are-evaluated) - [Allow and deny rules](#allow-and-deny-rules) - [Permission modes](#permission-modes) - [Available modes](#available-modes) - [Set permission mode](#set-permission-mode) - [Mode details](#mode-details) - [Accept edits mode (acceptEdits)](#accept-edits-mode-acceptedits) - [Don’t ask mode (dontAsk)](#don%E2%80%99t-ask-mode-dontask) - [Bypass permissions mode (bypassPermissions)](#bypass-permissions-mode-bypasspermissions) - [Plan mode (plan)](#plan-mode-plan) - [Related resources](#related-resources) Control and observability # Configure permissions Copy pageCopy page Control how your agent uses tools with permission modes, hooks, and declarative allow/deny rules. Copy pageCopy page The Claude Agent SDK provides permission controls to manage how Claude uses tools. Use permission modes and rules to define what’s allowed automatically, and the [`canUseTool` callback](/docs/en/agent-sdk/user-input) to handle everything else at runtime. This page covers permission modes and rules. To build interactive approval flows where users approve or deny tool requests at runtime, see [Handle approvals and user input](/docs/en/agent-sdk/user-input). [​](#how-permissions-are-evaluated) How permissions are evaluated When Claude requests a tool, the SDK checks permissions in this order: 1 Hooks Run [hooks](/docs/en/agent-sdk/hooks) first. A hook can deny the call outright or pass it on. A hook that returns `allow` does not skip the deny and ask rules below; those are evaluated regardless of the hook result. 2 Deny rules Check `deny` rules (from `disallowed_tools` and [settings.json](/docs/en/settings#permission-settings)). If a deny rule matches, the tool is blocked, even in `bypassPermissions` mode. Bare-name deny rules like `Bash` remove the tool from Claude’s context before this evaluation begins, so only scoped rules like `Bash(rm *)` are checked at this step. 3 Ask rules Check `ask` rules from [settings.json](/docs/en/settings#permission-settings). If an ask rule matches, the call falls through to your [`canUseTool` callback](/docs/en/agent-sdk/user-input) for confirmation, even in `bypassPermissions` mode.Tools that require user interaction behave the same way: `AskUserQuestion` and MCP tools whose server sets [`_meta["anthropic/requiresUserInteraction"]`](/docs/en/mcp#require-approval-for-a-specific-tool) always fall through to the callback, even when an allow rule matches. In `dontAsk` mode both cases are denied instead, because that mode never prompts. The MCP annotation requires Claude Code v2.1.199 or later.[claude.ai connector](/docs/en/mcp#organization-controls-on-connector-tools) tools your organization has set to `ask` also leave the flow at this step. Every call falls through to the callback, even in `bypassPermissions` mode and even when an allow rule matches. The callback receives the reason `Your organization requires approval for this tool`. In `dontAsk` mode the call is denied instead, because that mode never prompts. 4 Permission mode Apply the active [permission mode](#permission-modes). `bypassPermissions` approves everything that reaches this step. `acceptEdits` approves file operations. `plan` routes file-edit and shell-write tools to your `canUseTool` callback regardless of allow rules, so write operations cannot be auto-approved while planning. Other modes fall through. 5 Allow rules Check `allow` rules (from `allowed_tools` and settings.json). If a rule matches, the tool is approved. 6 canUseTool callback If not resolved by any of the above, call your [`canUseTool` callback](/docs/en/agent-sdk/user-input) for a decision. In `dontAsk` mode, this step is skipped and the tool is denied. As of v2.1.198, if you pass a `canUseTool` callback that this evaluation order can never reach, the TypeScript SDK emits a Node.js process warning once when the query is constructed. The warning’s code is `CLAUDE_SDK_CAN_USE_TOOL_SHADOWED`. Two configurations trigger it: - `permissionMode: 'bypassPermissions'`, which auto-approves every call that reaches the permission mode step - Each bare `allowedTools` entry such as `"Read"`, which auto-approves that whole tool before the callback is consulted Entries with a specifier such as `Bash(ls *)` and the `acceptEdits` mode don’t trigger it, and allow rules coming from settings files aren’t visible to the check. Listen with `process.on('warning', ...)` and match the code to log or suppress it. To gate every tool call regardless of mode and rules, use a [`PreToolUse` hook](/docs/en/agent-sdk/hooks) instead. This page focuses on **allow and deny rules** and **permission modes**. For the other steps: - **Hooks:** run custom code to allow, deny, or modify tool requests. See [Control execution with hooks](/docs/en/agent-sdk/hooks). - **canUseTool callback:** prompt users for approval at runtime, when no earlier step resolves the call. See [Handle approvals and user input](/docs/en/agent-sdk/user-input). [​](#allow-and-deny-rules) Allow and deny rules `allowed_tools` and `disallowed_tools` (TypeScript: `allowedTools` / `disallowedTools`) add entries to the allow and deny rule lists in the evaluation flow above. Allow rules only affect approval: a tool not listed in `allowed_tools` is still available to Claude and falls through to the permission mode. Deny rules behave differently depending on whether they name a tool or scope a pattern within one. | Option | Effect | |:----------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `allowed_tools=["Read", "Grep"]` | `Read` and `Grep` are auto-approved. Tools not listed here still exist and fall through to the permission mode and `canUseTool`. | | `disallowed_tools=["Bash"]` | The `Bash` tool definition is removed from the request. Claude does not see the tool and cannot attempt it. | | `disallowed_tools=["Bash(rm *)"]` | `Bash` stays available. Calls matching `rm *` are denied in every permission mode, including `bypassPermissions`. Other `Bash` calls fall through to the permission mode. | | `disallowed_tools=["*"]` | Every tool definition is removed from the request. Tool-name globs are supported in deny rules: `"*"` matches every tool and `"mcp__*"` matches every MCP tool across all servers. | Allow rules accept tool-name globs only after a literal `mcp__<server>__` prefix. The server segment must be glob-free so the rule names a specific server you configured: `mcp__puppeteer__*` matches every tool from the `puppeteer` server, and `mcp__github__get_*` matches its `get_` tools. An unanchored entry like `allowed_tools=["*"]` or `allowed_tools=["mcp__*"]` is ignored with a startup warning and does not auto-approve anything. Scoped rules for `Read` and `Edit` take a path pattern. `Edit(path)` rules govern all built-in tools that write files, including `Write` and `NotebookEdit`; a `Write(path)` rule is never matched by the file permission checks. Use `//path` for an absolute filesystem path: a deny rule of `Edit(//secrets/**)` blocks writes anywhere under `/secrets` on disk. With a single leading slash, `Edit(/secrets/**)` anchors at the rule’s source instead. For rules passed through `allowed_tools` or `disallowed_tools`, that means the session’s working directory, so the rule doesn’t block `/secrets` on disk. See [Read and Edit rules](/docs/en/permissions#read-and-edit) for the four anchor forms and how rules from settings files resolve. **Auto-approved tools never reach `canUseTool`.** A tool call approved at any earlier step, by `acceptEdits` or `bypassPermissions`, or by an allow rule, skips your `canUseTool` callback, so permission checks you put there are silently bypassed for that tool. `AskUserQuestion`, MCP tools marked [`_meta["anthropic/requiresUserInteraction"]`](/docs/en/mcp#require-approval-for-a-specific-tool), and connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools) still reach the callback, even when an allow rule matches.Coverage depends on the entry’s form: a bare name like `Read` or `mcp__github__get_issue` auto-approves every call to that tool, while a scoped rule like `Bash(ls *)` auto-approves only matching calls and other `Bash` calls still fall through to the callback. For checks that must run on every tool call, use a [`PreToolUse` hook](/docs/en/agent-sdk/hooks): hooks run before every other step, and a hook deny applies even in `bypassPermissions` mode. For a locked-down agent, pair `allowedTools` with `permissionMode: "dontAsk"`. Listed tools are approved, apart from the always-prompt tools in the Warning above; anything else is denied outright instead of prompting: ```python const options = { allowedTools: ["Read", "Glob", "Grep"], permissionMode: "dontAsk" }; ``` **`allowed_tools` does not constrain `bypassPermissions`.** `allowed_tools` only pre-approves the tools you list. Unlisted tools are not matched by any allow rule and fall through to the permission mode, where `bypassPermissions` approves them. Setting `allowed_tools=["Read"]` alongside `permission_mode="bypassPermissions"` still approves every tool, including `Bash`, `Write`, and `Edit`. If you need `bypassPermissions` but want specific tools blocked, use `disallowed_tools`. You can also configure allow, deny, and ask rules declaratively in `.claude/settings.json`. These rules are read when the `project` setting source is enabled, which it is for default `query()` options. If you set `setting_sources` (TypeScript: `settingSources`) explicitly, include `"project"` for them to apply. See [Permission settings](/docs/en/settings#permission-settings) for the rule syntax. [​](#permission-modes) Permission modes Permission modes provide global control over how Claude uses tools. You can set the permission mode when calling `query()` or change it dynamically during streaming sessions. [​](#available-modes) Available modes The SDK supports these permission modes: | Mode | Description | Tool behavior | |:--------------------|:-----------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `default` | Standard permission behavior | No auto-approvals; unmatched tools trigger your `canUseTool` callback | | `dontAsk` | Deny instead of prompting | Anything not pre-approved by `allowed_tools` or rules is denied; connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools) and tools that require user interaction are denied even if you’ve pre-approved them. `canUseTool` is never called | | `acceptEdits` | Auto-accept file edits | File edits and [filesystem operations](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) are automatically approved | | `bypassPermissions` | Bypass permission checks | Tools run without permission prompts, except tools matched by an explicit [`ask` rule](#how-permissions-are-evaluated), connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools), and tools that require user interaction (use with caution) | | `plan` | Planning mode | Claude explores and plans without editing your source files; file edits are never auto-approved and prompt through your `canUseTool` callback | | `auto` | Model-classified approvals | A model classifier approves or denies permission prompts. See [Auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) for availability | **Subagent inheritance:** Subagents inherit the parent session’s permission mode. An [`AgentDefinition`’s `permissionMode`](/docs/en/agent-sdk/typescript#agentdefinition) can override it, except when the parent uses `bypassPermissions`, `acceptEdits`, or `auto`: those modes apply to every subagent and can’t be overridden per subagent.Subagents may have different system prompts and less constrained behavior than your main agent, so inheriting `bypassPermissions` grants them full, autonomous system access. Explicit [`ask` rules](#how-permissions-are-evaluated), connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools), and tools that require user interaction still force a prompt. [​](#set-permission-mode) Set permission mode You can set the permission mode once when starting a query, or change it dynamically while the session is active. - At query time - During streaming Pass `permission_mode` (Python) or `permissionMode` (TypeScript) when creating a query. This mode applies for the entire session unless changed dynamically. Python TypeScript ```python import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): async for message in query( prompt="Help me refactor this code", options=ClaudeAgentOptions( permission_mode="default", # Set the mode here ), ): if hasattr(message, "result"): print(message.result) asyncio.run(main()) ``` ```python import { query } from "@anthropic-ai/claude-agent-sdk"; async function main() { for await (const message of query({ prompt: "Help me refactor this code", options: { permissionMode: "default" // Set the mode here } })) { if ("result" in message) { console.log(message.result); } } } main(); ``` Call `set_permission_mode()` (Python) or `setPermissionMode()` (TypeScript) to change the mode mid-session. The new mode takes effect immediately for all subsequent tool requests. This lets you start restrictive and loosen permissions as trust builds, for example switching to `acceptEdits` after reviewing Claude’s initial approach. Python TypeScript ```python import asyncio from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions async def main(): async with ClaudeSDKClient( options=ClaudeAgentOptions( permission_mode="default", # Start in default mode ) ) as client: await client.query("Help me refactor this code") # Change mode dynamically mid-session await client.set_permission_mode("acceptEdits") # Process messages with the new permission mode async for message in client.receive_response(): if hasattr(message, "result"): print(message.result) asyncio.run(main()) ``` ```python import { query } from "@anthropic-ai/claude-agent-sdk"; async function main() { const q = query({ prompt: "Help me refactor this code", options: { permissionMode: "default" // Start in default mode } }); // Change mode dynamically mid-session await q.setPermissionMode("acceptEdits"); // Process messages with the new permission mode for await (const message of q) { if ("result" in message) { console.log(message.result); } } } main(); ``` [​](#mode-details) Mode details [​](#accept-edits-mode-acceptedits) Accept edits mode (`acceptEdits`) Auto-approves file operations so Claude can edit code without prompting. Other tools (like Bash commands that aren’t filesystem operations) still require normal permissions. **Auto-approved operations:** - File edits (Edit, Write tools) - Filesystem commands: `mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp`, `sed` Both apply only to paths inside the working directory or `additionalDirectories`. Paths outside that scope and writes to protected paths still prompt. **Use when:** you trust Claude’s edits and want faster iteration, such as during prototyping or when working in an isolated directory. [​](#don’t-ask-mode-dontask) Don’t ask mode (`dontAsk`) Converts any permission prompt into a denial. Tools pre-approved by `allowed_tools`, `settings.json` allow rules, or a hook run as normal. Connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools) and tools that require user interaction are denied even when an allow rule matches. Everything else is denied without calling `canUseTool`. **Use when:** you want a fixed, explicit tool surface for a headless agent and prefer a hard deny over silent reliance on `canUseTool` being absent. [​](#bypass-permissions-mode-bypasspermissions) Bypass permissions mode (`bypassPermissions`) Auto-approves all tool uses without prompts. Hooks still execute and can block operations if needed. Use with extreme caution. Claude has full system access in this mode. Only use in controlled environments where you trust all possible operations.`allowed_tools` does not constrain this mode. Every tool is approved, not just the ones you listed. Deny rules (`disallowed_tools`), explicit `ask` rules, and hooks are evaluated before the mode check and can still block a tool. Connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools) and tools that require user interaction still fall through to your `canUseTool` callback. [​](#plan-mode-plan) Plan mode (`plan`) Claude explores the codebase and produces a plan without editing your source files. Read-only tools run as in default mode. File edits are never auto-approved in plan mode, even when an allow rule matches. They prompt through your `canUseTool` callback instead. On Claude Code v2.1.212 or later, shell commands that modify files, such as `touch` and `rm`, reach your `canUseTool` callback the same way. Claude may use `AskUserQuestion` to clarify requirements before finalizing the plan. See [Handle approvals and user input](/docs/en/agent-sdk/user-input#handle-clarifying-questions) for handling these prompts. **Use when:** you want Claude to propose changes without executing them, such as during code review or when you need to approve changes before they’re made. [​](#related-resources) Related resources For the other steps in the permission evaluation flow: - [Handle approvals and user input](/docs/en/agent-sdk/user-input): interactive approval prompts and clarifying questions - [Hooks guide](/docs/en/agent-sdk/hooks): run custom code at key points in the agent lifecycle - [Permission rules](/docs/en/settings#permission-settings): declarative allow/deny rules in `settings.json` --- ## create-custom-subagents-claude-code-docs-7dc93e85c0.md ## On this page - [Built-in subagents](#built-in-subagents) - [Quickstart: create your first subagent](#quickstart-create-your-first-subagent) - [Configure subagents](#configure-subagents) - [Choose the subagent scope](#choose-the-subagent-scope) - [Write subagent files](#write-subagent-files) - [Supported frontmatter fields](#supported-frontmatter-fields) - [Choose a model](#choose-a-model) - [Control subagent capabilities](#control-subagent-capabilities) - [Available tools](#available-tools) - [Restrict which subagents can be spawned](#restrict-which-subagents-can-be-spawned) - [Scope MCP servers to a subagent](#scope-mcp-servers-to-a-subagent) - [Permission modes](#permission-modes) - [Preload skills into subagents](#preload-skills-into-subagents) - [Enable persistent memory](#enable-persistent-memory) - [Conditional rules with hooks](#conditional-rules-with-hooks) - [Disable specific subagents](#disable-specific-subagents) - [Define hooks for subagents](#define-hooks-for-subagents) - [Hooks in subagent frontmatter](#hooks-in-subagent-frontmatter) - [Project-level hooks for subagent events](#project-level-hooks-for-subagent-events) - [Work with subagents](#work-with-subagents) - [Understand automatic delegation](#understand-automatic-delegation) - [Invoke subagents explicitly](#invoke-subagents-explicitly) - [Run subagents in foreground or background](#run-subagents-in-foreground-or-background) - [API errors in subagents](#api-errors-in-subagents) - [Subagent output scanning](#subagent-output-scanning) - [Common patterns](#common-patterns) - [Isolate high-volume operations](#isolate-high-volume-operations) - [Run parallel research](#run-parallel-research) - [Chain subagents](#chain-subagents) - [Choose between subagents and main conversation](#choose-between-subagents-and-main-conversation) - [Let subagents spawn their own subagents](#let-subagents-spawn-their-own-subagents) - [Session subagent limit](#session-subagent-limit) - [Concurrent subagent limit](#concurrent-subagent-limit) - [Manage subagent context](#manage-subagent-context) - [What loads at startup](#what-loads-at-startup) - [Resume subagents](#resume-subagents) - [Auto-compaction](#auto-compaction) - [Fork the current conversation](#fork-the-current-conversation) - [Observe and steer running forks](#observe-and-steer-running-forks) - [How forks differ from named subagents](#how-forks-differ-from-named-subagents) - [Limitations](#limitations) - [Example subagents](#example-subagents) - [Code reviewer](#code-reviewer) - [Debugger](#debugger) - [Data scientist](#data-scientist) - [Database query validator](#database-query-validator) - [Next steps](#next-steps) Agents and parallel work # Create custom subagents Copy pageCopy page Create and use specialized AI subagents in Claude Code for task-specific workflows and improved context management. Copy pageCopy page Subagents are specialized AI assistants that handle specific types of tasks. Use one when a side task would flood your main conversation with search results, logs, or file contents you won’t reference again: the subagent does that work in its own context and returns only the summary. Define a custom subagent when you keep spawning the same kind of worker with the same instructions. Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. When Claude encounters a task that matches a subagent’s description, it delegates to that subagent, which works independently and returns results. To see the context savings in practice, the [context window visualization](/docs/en/context-window) walks through a session where a subagent handles research in its own separate window. Subagents work within a single session. To run many independent sessions in parallel and monitor them from one place, see [background agents](/docs/en/agent-view). For sessions that communicate with each other, see [agent teams](/docs/en/agent-teams). Subagents help you: - **Preserve context** by keeping exploration and implementation out of your main conversation - **Enforce constraints** by limiting which tools a subagent can use - **Reuse configurations** across projects with user-level subagents - **Specialize behavior** with focused system prompts for specific domains - **Control costs** by routing tasks to faster, cheaper models like Haiku Claude uses each subagent’s description to decide when to delegate tasks. When you create a subagent, write a clear description so Claude knows when to use it. Claude Code includes several built-in subagents such as Explore, Plan, and general-purpose. You can also create custom subagents to handle specific tasks. [​](#built-in-subagents) Built-in subagents Claude Code includes built-in subagents that Claude automatically uses when appropriate. Each inherits the parent conversation’s permissions with additional tool restrictions. Explore and Plan skip your CLAUDE.md files and the parent session’s git status to keep research fast and inexpensive. Every other built-in and [custom subagent](#configure-subagents) loads both. For the full breakdown of what reaches a subagent, see [what loads at startup](#what-loads-at-startup). - Explore - Plan - General-purpose - Other A fast, read-only agent optimized for searching and analyzing codebases. - **Model**: inherits from the main conversation, capped at Opus on the Claude API, so Explore never runs on a more expensive model than the one you already chose for the session - **Tools**: read-only tools; Write and Edit are denied - **Purpose**: file discovery, code search, codebase exploration As of v2.1.198, Explore inherits the main conversation’s model instead of always running on Haiku. On the Claude API, the inherited model is capped at Opus: a main conversation on a higher tier runs Explore on Opus, and a main conversation on Sonnet or Haiku runs Explore on that same model. On any other provider, such as [Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, or Claude Platform on AWS](/docs/en/third-party-integrations), Explore inherits the main conversation’s model directly.A [user or project subagent](#choose-the-subagent-scope) named `Explore` overrides the built-in and keeps its own `model` field, so define one with `model: haiku` to keep exploration on a lower-cost model.Claude delegates to Explore when it needs to search or understand a codebase without making changes. This keeps exploration results out of your main conversation context.When invoking Explore, Claude specifies a thoroughness level: **quick** for targeted lookups, **medium** for balanced exploration, or **very thorough** for comprehensive analysis. A research agent used during [plan mode](/docs/en/permission-modes#analyze-before-you-edit-with-plan-mode) to gather context before presenting a plan. - **Model**: inherits from the main conversation - **Tools**: read-only tools; Write and Edit are denied - **Purpose**: codebase research for planning When you’re in plan mode and Claude needs to understand your codebase, it delegates research to the Plan subagent so that exploration output stays in a separate context window while the main conversation remains read-only. A capable agent for complex, multi-step tasks that require both exploration and action. - **Model**: inherits from the main conversation - **Tools**: every tool [available to subagents](#available-tools) - **Purpose**: complex research, multi-step operations, code modifications Claude delegates to general-purpose when the task requires both exploration and modification, complex reasoning to interpret results, or multiple dependent steps. Claude Code includes additional helper agents for specific tasks. These are typically invoked automatically, so you don’t need to use them directly. | Agent | Model | When Claude uses it | |:------------------|:-------|:---------------------------------------------------------| | statusline-setup | Sonnet | When you run `/statusline` to configure your status line | | claude-code-guide | Haiku | When you ask questions about Claude Code features | Built-in subagents are registered by default in interactive sessions. To restrict them: - To block a specific built-in type, add it to `permissions.deny` as shown in [Disable specific subagents](#disable-specific-subagents). - To prevent Claude from delegating to any subagent, deny the `Agent` tool itself with [`permissions.deny`](/docs/en/permissions#tool-specific-permission-rules). - To remove only the built-in `Explore` and `Plan` subagents, set [`CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1`](/docs/en/env-vars). Claude reads and explores files directly instead of delegating to them. Requires Claude Code v2.1.198 or later. - In [non-interactive mode](/docs/en/headless) and the [Agent SDK](/docs/en/agent-sdk/overview), set [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/docs/en/env-vars) to remove all built-in types and supply only your own. Beyond these built-in subagents, you can create your own with custom prompts, tool restrictions, permission modes, hooks, and skills. The following sections show how to get started and customize subagents. [​](#quickstart-create-your-first-subagent) Quickstart: create your first subagent Subagents are Markdown files with YAML frontmatter. To create one, ask Claude to write it for you, or [write the file yourself](#write-subagent-files). As of v2.1.198, the `/agents` command no longer opens the interactive creation wizard; running it prints a reminder to ask Claude or edit `.claude/agents/` directly. Subagent files, frontmatter fields, and the `.claude/agents/` and `~/.claude/agents/` locations are unchanged; only the terminal wizard is removed. This walkthrough creates a user-level subagent that reviews code and suggests improvements. 1 Ask Claude to create the subagent In Claude Code, describe the subagent you want and where to save it: ```python Create a personal code-improver subagent in ~/.claude/agents/ that scans files and suggests improvements for readability, performance, and best practices. It should explain each issue, show the current code, and provide an improved version. Make it read-only and have it use Sonnet. ``` Claude writes the file with a `name`, a `description`, a `tools` list, a `model`, and a system prompt. 2 Review the file Open `~/.claude/agents/code-improver.md` and confirm the frontmatter matches what you asked for. The result looks like this: ```python --- name: code-improver description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code. tools: Read, Grep, Glob model: sonnet --- You are a code improvement specialist. For each issue you find, explain the problem, show the current code, and provide an improved version. ``` Because the file lives in `~/.claude/agents/`, the subagent is available in every project on your machine. To scope it to one project instead, move it to that project’s `.claude/agents/` directory. [Choose the subagent scope](#choose-the-subagent-scope) compares the two. 3 Try it out Ask Claude to delegate to the new subagent: ```python Use the code-improver agent to suggest improvements in this project ``` Claude delegates to your new subagent, which scans the codebase and returns improvement suggestions.If Claude can’t find the new subagent, restart Claude Code and try again. This happens only when `~/.claude/agents/` didn’t exist before the session started, because a running session doesn’t detect a newly created `agents` directory. You now have a subagent you can use in any project on your machine to analyze codebases and suggest improvements. You can also write subagent files by hand, define them via CLI flags, or distribute them through plugins. The following sections cover all configuration options. On Claude Code v2.1.197 and earlier, `/agents` opens an interactive wizard with a **Running** tab that lists live subagents and a **Library** tab for creating, editing, and deleting them. [​](#configure-subagents) Configure subagents A subagent’s file location determines who it’s available to, and its frontmatter determines what it can do. This section covers where subagent files live and every field they support. [​](#choose-the-subagent-scope) Choose the subagent scope Store subagent files in different locations depending on scope. When multiple subagents share the same name, Claude Code uses the one from the higher-priority location. | Location | Scope | Priority | How to create | |:-----------------------------|:------------------------|:------------|:---------------------------------------------------| | Managed settings | Organization-wide | 1 (highest) | Deployed via [managed settings](/docs/en/settings) | | `--agents` CLI flag | Current session | 2 | Pass JSON when launching Claude Code | | `.claude/agents/` | Current project | 3 | Ask Claude, or create the file manually | | `~/.claude/agents/` | All your projects | 4 | Ask Claude, or create the file manually | | Plugin’s `agents/` directory | Where plugin is enabled | 5 (lowest) | Installed with [plugins](/docs/en/plugins) | **Project subagents** (`.claude/agents/`) are ideal for subagents specific to a codebase. Check them into version control so your team can use and improve them collaboratively. Project subagents are discovered by walking up from the current working directory, so every `.claude/agents/` between there and the repository root is scanned. As of v2.1.178, when more than one of these nested directories defines the same `name`, Claude Code uses the definition closest to the working directory. Directories added with `--add-dir` are also scanned: a `.claude/agents/` folder inside an added directory loads alongside project subagents. See [Additional directories](/docs/en/permissions#additional-directories-grant-file-access-not-configuration) for which other configuration types load from `--add-dir`. To share subagents across projects without `--add-dir`, use `~/.claude/agents/` or a [plugin](/docs/en/plugins). **User subagents** (`~/.claude/agents/`) are personal subagents available in all your projects. Claude Code scans `.claude/agents/` and `~/.claude/agents/` recursively, so you can organize definitions into subfolders such as `agents/review/` or `agents/research/`. The subdirectory path doesn’t affect how a subagent is identified or invoked, because identity comes only from the `name` frontmatter field. Keep `name` values unique across the whole tree: if two files under the same `.claude/agents/` directory, including its subfolders, declare the same name, Claude Code loads only one of them, chosen by filesystem read order rather than a documented precedence. Across nested project directories, the definition closest to the working directory wins, as described above. The [`/doctor`](/docs/en/commands#all-commands) setup checkup reports files in the same directory that share a name and proposes renaming or removing all but one. Before v2.1.205, `/doctor` opened a diagnostics screen that listed duplicates and showed which definition was active. Plugin `agents/` directories are also scanned recursively. Unlike project and user scopes, a subfolder inside a plugin’s `agents/` directory becomes part of the [scoped identifier](#invoke-subagents-explicitly): a file at `agents/review/security.md` in plugin `my-plugin` registers as `my-plugin:review:security`. **CLI-defined subagents** are passed as JSON when launching Claude Code. They exist only for that session and aren’t saved to disk, making them useful for quick testing or automation scripts. You can define multiple subagents in a single `--agents` call: - macOS, Linux, WSL - Windows PowerShell ```python claude --agents '{ "code-reviewer": { "description": "Expert code reviewer. Use proactively after code changes.", "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.", "tools": ["Read", "Grep", "Glob", "Bash"], "model": "sonnet" }, "debugger": { "description": "Debugging specialist for errors and test failures.", "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes." } }' ``` ```python claude --agents @' { "code-reviewer": { "description": "Expert code reviewer. Use proactively after code changes.", "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.", "tools": ["Read", "Grep", "Glob", "Bash"], "model": "sonnet" }, "debugger": { "description": "Debugging specialist for errors and test failures.", "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes." } } '@ ``` The `--agents` flag accepts JSON with the same [frontmatter](#supported-frontmatter-fields) fields as file-based subagents: `description`, `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `isolation`, and `color`. Use `prompt` for the system prompt, equivalent to the markdown body in file-based subagents. **Managed subagents** are deployed by organization administrators. Place markdown files in `.claude/agents/` inside the [managed settings directory](/docs/en/settings#settings-files), using the same frontmatter format as project and user subagents. Managed definitions take precedence over project and user subagents with the same name. **Plugin subagents** come from [plugins](/docs/en/plugins) you’ve installed. They load automatically alongside your custom subagents and appear in the @-mention typeahead under their scoped name. See the [plugin components reference](/docs/en/plugins-reference#agents) for details on creating plugin subagents. For security reasons, plugin subagents don’t support the `hooks`, `mcpServers`, or `permissionMode` frontmatter fields. These fields are ignored when loading agents from a plugin. If you need them, copy the agent file into `.claude/agents/` or `~/.claude/agents/`. You can also add rules to [`permissions.allow`](/docs/en/settings#permission-settings) in `settings.json` or `settings.local.json`, but these rules apply to the entire session, not only the plugin subagent. Subagent definitions from any of these scopes are also available to [agent teams](/docs/en/agent-teams#use-subagent-definitions-for-teammates): when spawning a teammate, you can reference a subagent type and the teammate uses its `tools` and `model`, with the definition’s body appended to the teammate’s system prompt as additional instructions. See [agent teams](/docs/en/agent-teams#use-subagent-definitions-for-teammates) for which frontmatter fields apply on that path. [​](#write-subagent-files) Write subagent files Subagent files use YAML frontmatter for configuration, followed by the system prompt in Markdown: Claude Code watches `~/.claude/agents/` and `.claude/agents/`. When you add or edit a subagent file on disk, or ask Claude to write one for you, Claude Code detects the change within a few seconds and the next delegation uses the updated definition, with no restart needed.Two cases still need a restart: - The watcher covers only directories that existed when the session started, so after creating a scope’s first agent file in a new `agents` directory, restart to load it. - Sessions started with `--disable-slash-commands` don’t watch these directories at all. ```python --- name: code-reviewer description: Reviews code for quality and best practices tools: Read, Glob, Grep model: sonnet --- You are a code reviewer. When invoked, analyze the code and provide specific, actionable feedback on quality, security, and best practices. ``` The frontmatter defines the subagent’s metadata and configuration. The body becomes the system prompt that guides the subagent’s behavior. Subagents receive only this system prompt plus basic environment details like the working directory, not the full Claude Code system prompt. In [non-interactive mode](/docs/en/headless), the [`--append-subagent-system-prompt`](/docs/en/cli-reference#cli-flags) flag appends the text you provide to the end of every subagent’s system prompt, including nested subagents. Requires Claude Code v2.1.205 or later. A subagent starts in the main conversation’s current working directory. Within a subagent, `cd` commands don’t persist between Bash or PowerShell tool calls and don’t affect the main conversation’s working directory. To give the subagent an isolated copy of the repository instead, set [`isolation: worktree`](#supported-frontmatter-fields). A subagent with `isolation: worktree` runs its Bash and PowerShell commands inside its worktree. A command whose working directory resolves to your main checkout instead, for example because the worktree directory was removed while the subagent was running, fails with an error. Before v2.1.203, such a command could run in the main checkout. This working-directory check covers the whole repository containing the directory you launched Claude Code from. When your session runs in a linked [worktree](/docs/en/worktrees) of its own, the check also covers the main checkout that worktree is linked from. Before v2.1.210, the check covered only the launch directory itself. A command whose working directory resolved elsewhere in the same repository, such as the repository root when you launched Claude Code from a monorepo subdirectory, ran there instead of failing. For Bash commands, Claude Code also checks the command itself: a command that redirects git into the main checkout fails with an error, whether it uses `git -C`, `--git-dir`, a `GIT_DIR` or `GIT_WORK_TREE` variable, or a `cd` into the main checkout first. A command too complex to check also fails, with an error telling Claude to split it into separate plain commands. This check applies to Bash only; PowerShell commands get only the working-directory check. [​](#supported-frontmatter-fields) Supported frontmatter fields The following fields can be used in the YAML frontmatter. Only `name` and `description` are required. | Field | Required | Description | |:------------------|:---------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `name` | Yes | Unique identifier using lowercase letters and hyphens. [Hooks](/docs/en/hooks#subagentstart) receive this value as `agent_type`. The filename doesn’t have to match. Names can’t contain `:`, which is reserved for [plugin-scoped identifiers](/docs/en/plugins) such as `my-plugin:reviewer`. Claude Code doesn’t load a file whose name contains one and logs an error to the debug log. Before v2.1.218, such names were accepted | | `description` | Yes | When Claude should delegate to this subagent | | `tools` | No | [Tools](#available-tools) the subagent can use. Inherits every tool available to subagents if omitted. If no entry in the list resolves to a tool, the subagent usually [fails to launch](/docs/en/errors#agent-would-be-spawned-with-zero-tools) with an error naming the entries. To preload Skills into context, use the `skills` field rather than listing `Skill` here | | `disallowedTools` | No | Tools to deny, removed from inherited or specified list | | `model` | No | [Model](#choose-a-model) to use: `sonnet`, `opus`, `haiku`, `fable`, a full model ID (for example, `claude-opus-5`), or `inherit`. Defaults to `inherit` | | `permissionMode` | No | [Permission mode](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`, or `manual` as an alias for `default`. The `manual` alias requires Claude Code v2.1.200 or later. Ignored for [plugin subagents](#choose-the-subagent-scope) | | `maxTurns` | No | Maximum number of agentic turns before the subagent stops | | `skills` | No | [Skills](/docs/en/skills) to preload into the subagent’s context at startup. The full skill content is injected, not only the description. Subagents can still invoke unlisted project, user, and plugin skills through the Skill tool | | `mcpServers` | No | [MCP servers](/docs/en/mcp) available to this subagent. Each entry is either a server name referencing an already-configured server (e.g., `"slack"`) or an inline definition with the server name as key and a full [MCP server config](/docs/en/mcp#installing-mcp-servers) as value. Ignored for [plugin subagents](#choose-the-subagent-scope) | | `hooks` | No | [Lifecycle hooks](#define-hooks-for-subagents) scoped to this subagent. Ignored for [plugin subagents](#choose-the-subagent-scope) | | `memory` | No | [Persistent memory scope](#enable-persistent-memory): `user`, `project`, or `local`. Enables cross-session learning | | `background` | No | Set to `true` to always run this subagent as a [background task](#run-subagents-in-foreground-or-background), even when Claude needs its result right away. When unset, Claude chooses, and as of v2.1.198 it runs subagents in the background by default | | `effort` | No | Effort level when this subagent is active. Overrides the session effort level. Default: inherits from session. Options: `low`, `medium`, `high`, `xhigh`, `max`; available levels depend on the model | | `isolation` | No | Set to `worktree` to run the subagent in a temporary [git worktree](/docs/en/worktrees), giving it an isolated copy of the repository branched by default from your [default branch](/docs/en/worktrees#choose-the-base-branch) rather than the parent session’s `HEAD`. The worktree is automatically cleaned up if the subagent makes no changes | | `color` | No | Display color for the subagent in the task list and transcript. Accepts `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, or `cyan` | | `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main session agent (via `--agent` or the `agent` setting). [Commands](/docs/en/commands) and [skills](/docs/en/skills) are processed. Prepended to any user-provided prompt | [​](#choose-a-model) Choose a model The `model` field controls which [AI model](/docs/en/model-config) the subagent uses: - **Model alias**: use one of the available aliases: `sonnet`, `opus`, `haiku`, or `fable` - **Full model ID**: use a full model ID such as `claude-opus-5` or `claude-sonnet-5`. Accepts the same values as the `--model` flag - **inherit**: use the same model as the main conversation - **Omitted**: defaults to `inherit` and uses the same model as the main conversation When Claude invokes a subagent, it can also pass a `model` parameter for that specific invocation. Claude Code resolves the subagent’s model in this order: 1. The [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/en/model-config#environment-variables) environment variable, when set to a model alias or model ID 2. The per-invocation `model` parameter 3. The subagent definition’s `model` frontmatter 4. The main conversation’s model As of v2.1.196, setting `CLAUDE_CODE_SUBAGENT_MODEL` to `inherit` is the same as leaving it unset: resolution continues with the per-invocation `model` parameter, then the frontmatter. In earlier versions, `inherit` forced subagents onto the main conversation’s model and ignored both of those sources. Claude Code checks the environment variable, per-invocation parameter, and frontmatter values against your organization’s [`availableModels`](/docs/en/model-config#restrict-model-selection) allowlist. It skips a value that resolves to an excluded model and runs the subagent on the inherited model instead. A per-invocation `model` parameter also applies when the subagent is [resumed or sent a follow-up message](#resume-subagents), so the subagent stays on that model. Before v2.1.211, resuming dropped the per-invocation value and the subagent reverted to its definition’s `model` field or, without one, the main conversation’s model. As of v2.1.198, subagents also inherit the main conversation’s [extended thinking](/docs/en/model-config#extended-thinking) configuration: if thinking is on in your session, it’s on for the subagent, and if it’s off, it stays off. There is no per-subagent thinking setting. Before v2.1.198, subagents ran with extended thinking disabled regardless of the main conversation’s setting. [​](#control-subagent-capabilities) Control subagent capabilities You can control what subagents can do through tool access, permission modes, and conditional rules. [​](#available-tools) Available tools Subagents inherit the [built-in tools](/docs/en/tools-reference) and MCP tools available in the main conversation, narrowed by two filters: the first removes a short list of tools from every subagent, and the second reduces the built-in tool set for subagents that run in the [background](#run-subagents-in-foreground-or-background), which is the default. [Forks](#fork-the-current-conversation) skip both filters and receive the main conversation’s exact tool pool. The first filter removes these tools, even when listed in the `tools` field: - `Agent`, when the subagent is at the [depth limit](#let-subagents-spawn-their-own-subagents); in a [fork](#fork-the-current-conversation) the tool stays listed but returns an error instead of spawning - `AskUserQuestion` - `EndConversation`, which can end only the main conversation; see [EndConversation tool behavior](/docs/en/tools-reference#endconversation-tool-behavior) - `EnterPlanMode` - `ExitPlanMode`, unless the subagent’s [`permissionMode`](#permission-modes) is `plan` - `ScheduleWakeup` - `TaskOutput` - `WaitForMcpServers` - `Workflow` The second filter applies to subagents running in the background. Apart from `Agent` and `ExitPlanMode`, which follow the first filter’s conditions wherever the subagent runs, a background subagent keeps every MCP tool but only these built-in tools: `Read`, `Grep`, `Glob`, `Bash`, `PowerShell`, `Edit`, `Write`, `NotebookEdit`, `WebFetch`, `WebSearch`, `TodoWrite`, `Skill`, `ToolSearch`, `EnterWorktree`, `ExitWorktree`, `Monitor`, `TaskStop`, `SendMessage`, and `Artifact`. Claude Code removes every other built-in tool from a background subagent, whether inherited or listed in the `tools` field, so the same definition can resolve to different tools in the foreground and the background. The removal reports no error unless it leaves the `tools` list [resolving to nothing](/docs/en/errors#agent-would-be-spawned-with-zero-tools). Teammates in [agent teams](/docs/en/agent-teams) additionally keep the task tools and cron tools: `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`, `CronCreate`, `CronDelete`, and `CronList`. To restrict tools, use the `tools` field as an allowlist or the `disallowedTools` field as a denylist. This example uses `tools` to allow only Read, Grep, Glob, and Bash. The subagent can’t edit files, write files, or use any MCP tools: ```python --- name: safe-researcher description: Research agent with restricted capabilities tools: Read, Grep, Glob, Bash --- ``` This example uses `disallowedTools` to inherit the subagent’s tool pool except Write and Edit. The subagent keeps Bash, MCP tools, and the rest of its pool: ```python --- name: no-writes description: Inherits the available tools except file writes disallowedTools: Write, Edit --- ``` If both are set, `disallowedTools` is applied first, then `tools` is resolved against the remaining pool. A tool listed in both is removed. When nothing in the `tools` list resolves to a tool, for example because every entry is misspelled or names a tool that isn’t available to subagents, Claude Code usually refuses to launch the subagent and the Agent tool returns an error naming the unresolved entries; see [Agent would be spawned with zero tools](/docs/en/errors#agent-would-be-spawned-with-zero-tools) for the message and how to fix each entry. Before v2.1.208, that subagent launched with no tools and could return an empty or confusing result. Both fields accept MCP server-level patterns in addition to exact tool names: `mcp__<server>` or `mcp__<server>__*` grants or removes every tool from the named server. In `disallowedTools`, `mcp__*` also removes every MCP tool from any server. This example removes every tool from the `github` MCP server while keeping tools from other servers and the built-in tools in its pool: ```python --- name: local-only description: Inherits every tool except those from the github MCP server disallowedTools: mcp__github --- ``` [​](#restrict-which-subagents-can-be-spawned) Restrict which subagents can be spawned When an agent runs as the main thread with `claude --agent`, it can spawn subagents using the Agent tool. To restrict which subagent types it can spawn, use `Agent(agent_type)` syntax in the `tools` field. In version 2.1.63, the Task tool was renamed to Agent. Existing `Task(...)` references in settings and agent definitions still work as aliases. ```python --- name: coordinator description: Coordinates work across specialized agents tools: Agent(worker, researcher), Read, Bash --- ``` This is an allowlist: only the `worker` and `researcher` subagents can be spawned. If the agent tries to spawn any other type, the request fails and the agent sees only the allowed types in its prompt. To block specific agents while allowing all others, use [`permissions.deny`](#disable-specific-subagents) instead. To allow spawning any subagent without restrictions, use `Agent` without parentheses: ```python tools: Agent, Read, Bash ``` If you omit `Agent` from the `tools` list entirely, the agent can’t spawn any subagents with the Agent tool. The `Agent(agent_type)` allowlist syntax applies only to an agent running as the main thread with `claude --agent`. In a subagent definition, listing `Agent` in `tools` lets that subagent spawn subagents of its own while the [depth limit](#let-subagents-spawn-their-own-subagents) allows it, but any type list inside the parentheses is ignored. [​](#scope-mcp-servers-to-a-subagent) Scope MCP servers to a subagent Use the `mcpServers` field to give a subagent access to [MCP](/docs/en/mcp) servers that aren’t available in the main conversation. Inline servers defined here are connected when the subagent starts and disconnected when it finishes. String references share the parent session’s connection. The `mcpServers` field applies in both contexts where an agent file can run: - As a subagent, spawned through the Agent tool or an @-mention - As the main session, launched with [`--agent`](#invoke-subagents-explicitly) or the `agent` setting When the agent is the main session, inline server definitions connect at startup alongside servers from [`.mcp.json`](/docs/en/mcp) and settings files. Each entry in the list is either an inline server definition or a string referencing an MCP server already configured in your session: ```python --- name: browser-tester description: Tests features in a real browser using Playwright mcpServers: # Inline definition: scoped to this subagent only - playwright: type: stdio command: npx args: ["-y", "@playwright/mcp@latest"] # Reference by name: reuses an already-configured server - github --- Use the Playwright tools to navigate, screenshot, and interact with pages. ``` Inline definitions use the same schema as `.mcp.json` server entries, keyed by the server name, and support the `stdio`, `http`, `sse`, and `ws` types. To keep an MCP server out of the main conversation entirely and avoid its tool descriptions consuming context there, define it inline here rather than in `.mcp.json`. The subagent gets the tools; the parent conversation doesn’t. As of v2.1.153, the MCP restrictions that apply to the main session also cover servers declared in subagent frontmatter: - [`--strict-mcp-config`](/docs/en/cli-reference) and [`--bare`](/docs/en/cli-reference) - [Enterprise managed MCP configuration](/docs/en/managed-mcp) - [`allowedMcpServers` and `deniedMcpServers` policies](/docs/en/managed-mcp#policy-based-control-with-allowlists-and-denylists) When one of these blocks a server, Claude Code skips it and shows a warning naming the blocked servers. Managed-settings restrictions apply to every subagent regardless of how it is defined. `--strict-mcp-config` doesn’t filter servers you pass inline via `--agents` or the SDK `agents` option, since those are explicit caller input. [​](#permission-modes) Permission modes The `permissionMode` field controls how the subagent handles permission prompts. Subagents inherit the permission context from the main conversation and can override the mode, except when the parent mode takes precedence as described below. | Mode | Behavior | |:--------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `default` | Standard permission checking with prompts | | `acceptEdits` | Auto-accept file edits and common filesystem commands for paths in the working directory or `additionalDirectories` | | `auto` | [Auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode): a background classifier reviews commands and protected-directory writes | | `dontAsk` | Auto-deny permission prompts. Explicitly allowed tools still work; `AskUserQuestion`, connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools), and MCP tools marked [`requiresUserInteraction`](/docs/en/mcp#require-approval-for-a-specific-tool) are denied even if you’ve allowed them | | `bypassPermissions` | Skip permission prompts | | `plan` | Plan mode (read-only exploration) | Use `bypassPermissions` with caution. It skips permission prompts, allowing the subagent to execute operations without approval, including writes to `.git`, `.config/git`, `.claude`, `.vscode`, `.idea`, `.husky`, `.cargo`, `.devcontainer`, `.yarn`, and `.mvn`.Explicit [`ask` rules](/docs/en/permissions#manage-permissions), connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools), MCP tools marked [`requiresUserInteraction`](/docs/en/mcp#require-approval-for-a-specific-tool), and root and home directory removals such as `rm -rf /` still prompt. See [permission modes](/docs/en/permission-modes#skip-all-checks-with-bypasspermissions-mode) for details. If the parent uses `bypassPermissions` or `acceptEdits`, this takes precedence and can’t be overridden. If the parent uses [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode), the subagent inherits auto mode and any `permissionMode` in its frontmatter is ignored: the classifier evaluates the subagent’s tool calls with the same block and allow rules as the parent session. [​](#preload-skills-into-subagents) Preload skills into subagents Use the `skills` field to inject skill content into a subagent’s context at startup. This gives the subagent domain knowledge without requiring it to discover and load skills during execution. ```python --- name: api-developer description: Implement API endpoints following team conventions skills: - api-conventions - error-handling-patterns --- Implement API endpoints. Follow the conventions and patterns from the preloaded skills. ``` The full content of each listed skill is injected into the subagent’s context at startup. This field controls which skills are preloaded, not which skills the subagent can access: without it, the subagent can still discover and invoke project, user, and plugin skills through the Skill tool during execution. To prevent a subagent from invoking skills entirely, omit `Skill` from the [`tools`](#available-tools) list or add it to `disallowedTools`. You can’t preload skills that set [`disable-model-invocation: true`](/docs/en/skills#control-who-invokes-a-skill), since preloading draws from the same set of skills Claude can invoke. This includes the bundled `/verify` and `/code-review` skills: only you can run them, so they can’t be preloaded either. If a listed skill is missing or disabled, Claude Code skips it and logs a warning to the debug log. This is the inverse of [running a skill in a subagent](/docs/en/skills#run-skills-in-a-subagent). With `skills` in a subagent, the subagent controls the system prompt and loads skill content. With `context: fork` in a skill, the skill content is injected into the agent you specify. Both use the same underlying system. [​](#enable-persistent-memory) Enable persistent memory The `memory` field gives the subagent a persistent directory that survives across conversations. The subagent uses this directory to build up knowledge over time, such as codebase patterns, debugging insights, and architectural decisions. ```python --- name: code-reviewer description: Reviews code for quality and best practices memory: user --- You are a code reviewer. As you review code, update your agent memory with patterns, conventions, and recurring issues you discover. ``` Choose a scope based on how broadly the memory should apply: | Scope | Location | Use when | |:----------|:----------------------------------------------|:-------------------------------------------------------------------------------------------| | `user` | `~/.claude/agent-memory/<name-of-agent>/` | the subagent should remember learnings across all projects | | `project` | `.claude/agent-memory/<name-of-agent>/` | the subagent’s knowledge is project-specific and shareable via version control | | `local` | `.claude/agent-memory-local/<name-of-agent>/` | the subagent’s knowledge is project-specific but shouldn’t be checked into version control | Subagent memory is part of [auto memory](/docs/en/memory#auto-memory): if you turn auto memory off, with the `autoMemoryEnabled` setting or `CLAUDE_CODE_DISABLE_AUTO_MEMORY`, the `memory` field has no effect and the subagent launches without the memory instructions or the memory tool access described below. When memory is enabled: - The subagent’s system prompt includes instructions for reading and writing to the memory directory. - The subagent’s system prompt also includes the first 200 lines or 25KB of `MEMORY.md` in the memory directory, whichever comes first, with instructions to curate `MEMORY.md` if it exceeds that limit. - Read, Write, and Edit tools are automatically enabled so the subagent can manage its memory files. ##### Persistent memory tips - `project` is the recommended default scope. It makes subagent knowledge shareable via version control. - Ask the subagent to consult its memory before starting work: “Review this PR, and check your memory for patterns you’ve seen before.” - Ask the subagent to update its memory after completing a task: “Now that you’re done, save what you learned to your memory.” Over time, this builds a knowledge base that makes the subagent more effective. - Include memory instructions directly in the subagent’s markdown file so it proactively maintains its own knowledge base: ``` shiki Update your agent memory as you discover codepaths, patterns, library locations, and key architectural decisions. This builds up institutional knowledge across conversations. Write concise notes about what you found and where. ``` [​](#conditional-rules-with-hooks) Conditional rules with hooks For more dynamic control over tool usage, use `PreToolUse` hooks to validate operations before they execute. This is useful when you need to allow some operations of a tool while blocking others. This example creates a subagent that only allows read-only database queries. The `PreToolUse` hook runs the script specified in `command` before each Bash command executes: ```python --- name: db-reader description: Execute read-only database queries tools: Bash hooks: PreToolUse: - matcher: "Bash" hooks: - type: command command: "./scripts/validate-readonly-query.sh" --- ``` Claude Code [passes hook input as JSON](/docs/en/hooks#pretooluse-input) via stdin to hook commands. The validation script reads this JSON, extracts the Bash command, and [exits with code 2](/docs/en/hooks#exit-code-2-behavior-per-event) to block write operations: ```python #!/bin/bash # ./scripts/validate-readonly-query.sh INPUT=$(cat) COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty') # Block SQL write operations (case-insensitive) if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then echo "Blocked: Only SELECT queries are allowed" >&2 exit 2 fi exit 0 ``` On macOS and Linux, make the script executable, or the hook fails instead of blocking anything: ```python chmod +x ./scripts/validate-readonly-query.sh ``` To test the rule, ask the subagent to run an `UPDATE` statement: the script exits with code 2, Claude Code blocks the command, and the subagent sees the `Blocked: Only SELECT queries are allowed` message. See [Hook input](/docs/en/hooks#pretooluse-input) for the complete input schema and [exit codes](/docs/en/hooks#exit-code-output) for how exit codes affect behavior. On Windows, write hook scripts in PowerShell and add `shell: powershell` to the hook entry as shown in [running hooks in PowerShell](/docs/en/hooks#windows-powershell-tool). [​](#disable-specific-subagents) Disable specific subagents You can prevent Claude from using specific subagents by adding them to the `deny` array in your [settings](/docs/en/settings#permission-settings). Use the format `Agent(subagent-name)` where `subagent-name` matches the subagent’s name field. ```python { "permissions": { "deny": ["Agent(Explore)", "Agent(my-custom-agent)"] } } ``` This works for both built-in and custom subagents. You can also use the `--disallowedTools` CLI flag: ```python claude --disallowedTools "Agent(Explore)" ``` See [Permissions documentation](/docs/en/permissions#tool-specific-permission-rules) for more details on permission rules. [​](#define-hooks-for-subagents) Define hooks for subagents Subagents can define [hooks](/docs/en/hooks) that run during the subagent’s lifecycle. There are two ways to configure hooks: - **In the subagent’s frontmatter**: define hooks that run only while that subagent is active - **In `settings.json`**: define session-wide hooks that also fire inside subagents. Tool events such as `PreToolUse` and `PostToolUse` fire for the subagent’s tool calls the same way they do in the main conversation, and `SubagentStart` and `SubagentStop` fire when a subagent starts or finishes Hooks from [settings files, managed policy settings, and plugins](/docs/en/hooks#hook-locations) all apply inside subagents, so a `PreToolUse` hook in `settings.json` also runs before every tool a subagent uses. [​](#hooks-in-subagent-frontmatter) Hooks in subagent frontmatter Define hooks directly in the subagent’s markdown file. These hooks only run while that specific subagent is active and are cleaned up when it finishes. Frontmatter hooks fire when the agent is spawned as a subagent through the Agent tool or an @-mention, and when the agent runs as the main session via [`--agent`](#invoke-subagents-explicitly) or the `agent` setting. In the main-session case they run alongside any hooks defined in [`settings.json`](/docs/en/hooks). To let a project-level subagent’s frontmatter hooks run, accept the [workspace trust dialog](/docs/en/permissions#project-allow-rules-and-workspace-trust) for the folder that contains the agent file. Hooks from user-level subagents in `~/.claude/agents/` and from definitions you pass with `--agents` run without this step. If you added a folder with `--add-dir` from outside your trusted workspace’s repository, trust that folder separately: its `.claude/agents/` hooks don’t inherit the workspace’s grant. Until you trust the folder, the subagent still runs, but Claude Code skips its frontmatter hooks and logs an error to the debug log explaining how to trust the folder. The grant is the same workspace trust approval that covers project settings and project-level hooks. Before v2.1.218, frontmatter hooks could run from folders you hadn’t trusted, including in non-interactive sessions. All [hook events](/docs/en/hooks#hook-events) are supported. The most common events for subagents are: | Event | Matcher input | When it fires | |:--------------|:--------------|:--------------------------------------------------------------------| | `PreToolUse` | Tool name | Before the subagent uses a tool | | `PostToolUse` | Tool name | After the subagent uses a tool | | `Stop` | (none) | When the subagent finishes (converted to `SubagentStop` at runtime) | This example validates Bash commands with the `PreToolUse` hook and runs a linter after file edits with `PostToolUse`: ```python --- name: code-reviewer description: Review code changes with automatic linting hooks: PreToolUse: - matcher: "Bash" hooks: - type: command command: "./scripts/validate-command.sh $TOOL_INPUT" PostToolUse: - matcher: "Edit|Write" hooks: - type: command command: "./scripts/run-linter.sh" --- ``` When the agent is invoked as a subagent, `Stop` hooks in frontmatter are automatically converted to `SubagentStop` events. [​](#project-level-hooks-for-subagent-events) Project-level hooks for subagent events Configure hooks in `settings.json` that respond to subagent lifecycle events in the main session. | Event | Matcher input | When it fires | |:----------------|:----------------|:---------------------------------| | `SubagentStart` | Agent type name | When a subagent begins execution | | `SubagentStop` | Agent type name | When a subagent completes | Both events support matchers to target specific agent types by name. The matcher value is the agent’s frontmatter `name` for project-level and user-level subagents, or the plugin-scoped identifier such as `my-plugin:db-agent` for [plugin subagents](/docs/en/plugins). A scoped name contains a colon, so it is evaluated as an [unanchored regular expression](/docs/en/hooks#matcher-patterns); anchor it with `^` and `$`, as in `^my-plugin:db-agent$`, to match only that agent. This example runs a setup script only when the `db-agent` subagent starts, and a cleanup script when any subagent stops: ```python { "hooks": { "SubagentStart": [ { "matcher": "db-agent", "hooks": [ { "type": "command", "command": "./scripts/setup-db-connection.sh" } ] } ], "SubagentStop": [ { "hooks": [ { "type": "command", "command": "./scripts/cleanup-db-connection.sh" } ] } ] } } ``` A hyphenated matcher like `db-agent` matches exactly on Claude Code v2.1.195 or later. On earlier versions it is evaluated as an unanchored regular expression and also fires for any agent type that contains it, such as `prod-db-agent`; anchor it as `^db-agent$` on those versions. See [Hooks](/docs/en/hooks) for the complete hook configuration format. [​](#work-with-subagents) Work with subagents [​](#understand-automatic-delegation) Understand automatic delegation Claude automatically delegates tasks based on the task description in your request, the `description` field in subagent configurations, and current context. To encourage proactive delegation, include phrases like “use proactively” in your subagent’s description field. [​](#invoke-subagents-explicitly) Invoke subagents explicitly When automatic delegation isn’t enough, you can request a subagent yourself. Three patterns escalate from a one-off suggestion to a session-wide default: - **Natural language**: name the subagent in your prompt; Claude decides whether to delegate - **@-mention**: guarantees the subagent runs for one task - **Session-wide**: the whole session uses that subagent’s system prompt, tool restrictions, and model via the `--agent` flag or the `agent` setting For natural language, there’s no special syntax. Name the subagent and Claude typically delegates: ```python Use the test-runner subagent to fix failing tests Have the code-reviewer subagent look at my recent changes ``` **@-mention the subagent.** Type `@` and pick the subagent from the typeahead, the same way you @-mention files. This ensures that specific subagent runs rather than leaving the choice to Claude: ```python @"code-reviewer (agent)" look at the auth changes ``` Your full message still goes to Claude, which writes the subagent’s task prompt based on what you asked. The @-mention controls which subagent Claude invokes, not what prompt it receives. Subagents provided by an enabled [plugin](/docs/en/plugins) appear in the typeahead under their scoped name, such as `my-plugin:code-reviewer` or `my-plugin:review:security` when the plugin [organizes agents into subfolders](#choose-the-subagent-scope). Named background subagents currently running in the session also appear in the typeahead, showing their status next to the name. You can also type the mention manually without using the picker: `@agent-<name>` for local subagents, or `@agent-` followed by the scoped name for plugin subagents, for example `@agent-my-plugin:code-reviewer`. While you type this form the typeahead shows file matches rather than agents. The agent mention still resolves when you submit. **Run the whole session as a subagent.** Pass [`--agent <name>`](/docs/en/cli-reference) to start a session where the main thread itself takes on that subagent’s system prompt, tool restrictions, and model: ```python claude --agent code-reviewer ``` The subagent’s system prompt replaces the default Claude Code system prompt entirely, the same way [`--system-prompt`](/docs/en/cli-reference) does. `CLAUDE.md` files and project memory still load through the normal message flow. The agent name appears as `@<name>` in the startup header so you can confirm it’s active. This works with built-in and custom subagents, and the choice persists when you resume the session: Claude Code restores the agent’s system prompt, tool restrictions, and model along with the conversation. If the agent no longer exists when you resume, the session continues with the default tools and system prompt and shows a [warning naming the agent](/docs/en/errors#session-agent-no-longer-available). For a plugin-provided subagent, you can pass only the agent name and Claude Code finds it: ```python claude --agent security-reviewer ``` If multiple plugins provide agents with the same name, pass the scoped name to disambiguate: ```python claude --agent my-plugin:security-reviewer ``` If the plugin places the agent in a subfolder of its `agents/` directory, include the subfolder in the scoped name, for example `claude --agent my-plugin:review:security`. To make it the default for every session in a project, set `agent` in `.claude/settings.json`: ```python { "agent": "code-reviewer" } ``` The CLI flag overrides the setting if both are present. [​](#run-subagents-in-foreground-or-background) Run subagents in foreground or background Subagents can run in the foreground or the background: - **Foreground subagents** block the main conversation until complete. Permission prompts are passed through to you as they come up. - **Background subagents** run concurrently while you continue working. As of v2.1.186, when a background subagent reaches a tool call that needs permission, the prompt surfaces in your main session and names the subagent that is asking. Approve to let the subagent continue, or press Esc to deny that one tool call without stopping the subagent. Before v2.1.186, background subagents auto-denied any tool call that would have prompted. As of v2.1.198, subagents run in the background by default. Claude runs a subagent in the foreground when it needs the result before continuing. Background subagents run with a [smaller built-in tool set](#available-tools) than foreground subagents, except for conversation forks, and they surface every permission prompt in your main session. A background subagent’s results reach Claude as a completion notification in a later turn. Claude waits for that notification before reporting the subagent’s results, and if you ask about progress first, it reports that the subagent is still running. Before v2.1.211, Claude sometimes reported results for a background subagent that hadn’t finished. You can also steer this yourself: - Ask Claude to run a task in the background or in the foreground - Press **Ctrl+B** to background a running task A background subagent that completes stays listed in [`/tasks`](/docs/en/commands), marked done and sorted below running work, until the session cleans up its task list. Its detail view stays open when the subagent finishes. Subagents that fail or that you stop leave the list. Before v2.1.208, a completed subagent left the list the moment it finished and its detail view closed. To disable all background task functionality, set the `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` environment variable to `1`. See [Environment variables](/docs/en/env-vars). When [`CLAUDE_CODE_FORK_SUBAGENT`](#fork-the-current-conversation) is set to `1`, every subagent runs in the background and the frontmatter `background` field has no effect, because fork mode removes the `run_in_background` parameter from the `Agent` tool. `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` takes precedence over fork mode and keeps subagents in the foreground. [​](#api-errors-in-subagents) API errors in subagents As of v2.1.199, a subagent whose run ends on an API error, such as a usage limit or a repeated server error, reports that failure back to Claude instead of returning the error text as if it were the subagent’s findings. What Claude receives depends on where the subagent ran: - **Foreground**: if a rate limit, overload, or server error cuts off a subagent that already produced text output, the Agent tool returns that partial output with a note that the subagent was cut off and didn’t finish its task. A subagent that produced nothing, or whose only output was tool calls, fails with [`Agent terminated early due to an API error`](/docs/en/errors#agent-terminated-early-due-to-an-api-error), followed by the error detail. In v2.1.199, a rate limit, overload, or server error that cut off the tool-calls-only shape returned an empty partial result containing only the cut-off note instead. - **Background**: the subagent is marked failed, and the message Claude receives when it ends names the API error and includes the subagent’s last output, so partial work isn’t lost. Once the underlying API error clears, ask Claude to retry the task or [resume the subagent](#resume-subagents). [​](#subagent-output-scanning) Subagent output scanning Claude Code scans each subagent’s final report before Claude reads it. A subagent may have read files, web pages, or command output you never reviewed, and text from those sources can carry instructions aimed at the main conversation. The scan never removes or rewords anything; it makes two kinds of change you may notice in a report: - **Backslash insertion**: the scan inserts a backslash into text that imitates Claude Code’s own output, such as a `<system-reminder>` tag or a line starting with `Human:` or `Assistant:`, so the imitation reads as ordinary text instead of being mistaken for part of the conversation. - **Marker line**: the scan prepends a line starting with `[harness: subagent output matched instruction-shaped pattern(s):` when the report imitates a tag like `<system-reminder>` or mentions permission settings such as `bypassPermissions` or `--dangerously-skip-permissions`. Permission-setting mentions get the marker line, but the text itself stays as written. The scan doesn’t judge whether content is malicious, and it doesn’t change what an instruction in a report can do: a tool call the report leads Claude to make still goes through the session’s [permission checks](/docs/en/permissions) and [sandboxing](/docs/en/sandboxing). It isn’t a substitute for [restricting what a subagent can reach](#control-subagent-capabilities). Subagent output scanning requires Claude Code v2.1.210 or later. [​](#common-patterns) Common patterns [​](#isolate-high-volume-operations) Isolate high-volume operations One of the most effective uses for subagents is isolating operations that produce large amounts of output. Running tests, fetching documentation, or processing log files can consume significant context. By delegating these to a subagent, the verbose output stays in the subagent’s context while only the relevant summary returns to your main conversation. ```python Use a subagent to run the test suite and report only the failing tests with their error messages ``` [​](#run-parallel-research) Run parallel research For independent investigations, spawn multiple subagents to work simultaneously: ```python Research the authentication, database, and API modules in parallel using separate subagents ``` Each subagent explores its area independently, then Claude synthesizes the findings. This works best when the research paths don’t depend on each other. When subagents complete, their results return to your main conversation. Running many subagents that each return detailed results can consume significant context. For tasks that need sustained parallelism or exceed your context window, [agent teams](/docs/en/agent-teams) give each worker its own independent context. [​](#chain-subagents) Chain subagents For multi-step workflows, ask Claude to use subagents in sequence. Each subagent completes its task and returns results to Claude, which then passes relevant context to the next subagent. ```python Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them ``` [​](#choose-between-subagents-and-main-conversation) Choose between subagents and main conversation Use the **main conversation** when: - The task needs frequent back-and-forth or iterative refinement - Multiple phases share significant context, such as planning, implementation, and testing - You’re making a quick, targeted change - Latency matters. Subagents start fresh and may need time to gather context Use **subagents** when: - The task produces verbose output you don’t need in your main context - You want to enforce specific tool restrictions or permissions - The work is self-contained and can return a summary Consider [Skills](/docs/en/skills) instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context. For a quick question about something already in your conversation, use [`/btw`](/docs/en/interactive-mode#side-questions-with-%2Fbtw) instead of a subagent. It sees your full context but has no tool access, and the answer is discarded rather than added to history. [​](#let-subagents-spawn-their-own-subagents) Let subagents spawn their own subagents By default, a subagent can spawn subagents of its own, up to three layers below the main conversation. At the depth limit, Claude Code withholds the `Agent` tool from every subagent except a [fork](#fork-the-current-conversation), so a subagent at the limit does its delegated work itself and returns one summary. A fork at the limit keeps `Agent` in its inherited tool list, but the tool returns an error instead of spawning. Nested subagents suit a delegated task that itself splits into parallel subtasks, such as a reviewer subagent that dispatches a verifier per finding, so the intermediate output never reaches your main conversation. Only the top-level subagent’s summary returns to you. To change the limit, set [`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`](/docs/en/env-vars) to the number of subagent layers you want below your main conversation. For example, this entry in [`settings.json`](/docs/en/settings) caps nesting at two layers: ```python { "env": { "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2" } } ``` With this value, your subagents can delegate to a second layer of their own, and that second layer can’t delegate further. Set `1` to turn nesting off. A nested subagent is configured the same way as a top-level one and resolves from the same [scopes](#choose-the-subagent-scope). To keep one subagent from spawning while nesting is on, such as a reviewer that should stay read-only, omit `Agent` from its [`tools`](#available-tools) list or add it to `disallowedTools`. The subagent panel below the prompt input shows the full tree: each row displays a `(+N)` count of descendants, and as of v2.1.193, opening a row shows that subagent’s siblings and direct children with a path back to `main`. Earlier versions used different defaults: - **v2.1.172 through v2.1.216**: subagents could nest by default, up to five layers deep, and the limit couldn’t be changed. - **v2.1.217 through v2.1.218**: the limit defaulted to one, so a subagent couldn’t spawn its own unless you raised it; v2.1.219 raised the default to three. [​](#session-subagent-limit) Session subagent limit Three separate limits control subagent use, each with its own variable: this one caps the total spawned over a session, the [concurrent subagent limit](#concurrent-subagent-limit) stops Claude from spawning more while too many are running, and the [depth limit](#let-subagents-spawn-their-own-subagents) caps how deeply subagents nest. By default, Claude can spawn at most 200 subagents per session. To raise the limit, set [`CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION`](/docs/en/env-vars) to any positive whole number; there is no upper bound, but the limit can’t be turned off. Requires Claude Code v2.1.212 or later. Every subagent Claude spawns with the Agent tool counts toward the limit: nested subagents, [forks](#fork-the-current-conversation), and background subagents, including subagents that a [workflow](/docs/en/workflows)’s agents spawn with the Agent tool. An in-session fork you start yourself with `/subtask` counts too: it spends the same budget, though the limit blocks only subagents Claude spawns with the Agent tool, so your own `/subtask` still starts after Claude reaches the limit. A session you create with `/fork` doesn’t count; it runs as a separate background session with its own budget. Before v2.1.212, the in-session fork was named `/fork`. Agents a workflow script spawns with `agent()` don’t count; workflows have their own per-run limit. A finished subagent still counts. When Claude reaches the limit, the Agent tool fails with `Subagent spawn limit reached`, and the error tells Claude to complete the remaining work directly with its own tools. Run [`/clear`](/docs/en/commands#all-commands) to reset the count and start a new conversation with the full budget. If work that can still spawn subagents survives the clear, such as a running workflow, the count carries over instead. [​](#concurrent-subagent-limit) Concurrent subagent limit By default, when 20 subagents are running in a session, spawning another with the Agent tool fails with `Concurrent subagent limit reached`, and the error tells Claude not to retry. Spawning succeeds again when the running count drops below the limit. To change the limit, set [`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`](/docs/en/env-vars) to any positive whole number. Sessions with [ultracode](/docs/en/model-config#adjust-effort-level) active are exempt: the limit isn’t enforced there. Requires Claude Code v2.1.217 or later. The limit blocks only subagents Claude spawns with the Agent tool, but other runs occupy the same slots: - An in-session fork you start with [`/subtask`](#fork-the-current-conversation) takes a slot while it runs and is never blocked by the limit. - [Resuming a subagent](#resume-subagents) that already finished takes a fresh slot without checking the limit, so resumes can push the running count past it. Agents that other features run, such as [workflow](/docs/en/workflows) agents and [agent team](/docs/en/agent-teams) teammates, follow their own limits instead. The [session subagent limit](#session-subagent-limit) separately caps the total Claude spawns over the whole session. [​](#manage-subagent-context) Manage subagent context [​](#what-loads-at-startup) What loads at startup Each subagent starts with a fresh, isolated context window. It doesn’t see your conversation history, the skills you’ve already invoked, or the files Claude has already read. Claude composes a delegation message that summarizes the task, and the subagent works from there. The exception is a [fork](#fork-the-current-conversation), which inherits the parent conversation instead of starting fresh. A non-fork subagent’s initial context contains: - **System prompt**: the agent’s own prompt plus environment details that Claude Code appends, not the full Claude Code system prompt. Custom subagents define theirs in the [markdown body](#write-subagent-files) or `prompt` field. Built-in agents have predefined prompts. - **Task message**: the delegation prompt Claude writes when it hands off the work. - **CLAUDE.md files**: every level of the [CLAUDE.md hierarchy](/docs/en/memory#how-claude-md-files-load) the main conversation loads, including `~/.claude/CLAUDE.md`, project rules, `CLAUDE.local.md`, and managed policy files. The built-in Explore and Plan agents skip this. - **Git status**: a snapshot taken at the start of the parent session. Absent when the working directory isn’t a Git repository or when [`includeGitInstructions`](/docs/en/settings#available-settings) is `false`. Explore and Plan skip it regardless. - **Preloaded skills**: full content of any skill named in the agent’s [`skills` field](#preload-skills-into-subagents). Built-in agents don’t preload skills. - **Sibling roster**: a system reminder listing `main` and every other named agent in the session, each a valid `to` value for [`SendMessage`](#resume-subagents). Requires Claude Code v2.1.206 or later. The roster appears only when the subagent’s tools include `SendMessage` and at least one other agent has a name, whether Claude named it when spawning it or it runs as an [agent team](/docs/en/agent-teams) teammate. It is a snapshot taken when the subagent starts, so agents named later don’t appear. Explore and Plan are the only subagents that omit CLAUDE.md and git status. There is no frontmatter field or per-agent setting to change which agents skip them. The main conversation reads Explore and Plan results with full CLAUDE.md context, so most rules don’t need to reach the subagent itself. If a rule must, such as “ignore the `vendor/` directory,” restate it in the prompt you give Claude when delegating. Some main-conversation state never reaches a non-fork subagent: - **Output style**: a subagent runs its own system prompt, so your [output style](/docs/en/output-styles) doesn’t shape its responses, except in a [fork](#fork-the-current-conversation). - **Auto memory**: the main conversation’s [auto memory](/docs/en/memory#auto-memory) isn’t loaded. To give a subagent persistent memory of its own, use the [`memory` field](#enable-persistent-memory). - **Context window size**: a subagent’s context window is sized by its own model, not the parent’s. Delegating to a model with a smaller window gives that subagent the smaller window. [​](#resume-subagents) Resume subagents Each subagent invocation creates a new instance with fresh context. To continue an existing subagent’s work instead of starting over, ask Claude to resume it. Resumed subagents retain their full conversation history, including all previous tool calls, results, and reasoning. The subagent picks up exactly where it stopped rather than starting fresh. When a subagent completes, Claude receives its agent ID. The built-in Explore and Plan agents are one-shot and return no agent ID, so they can’t be resumed; use `general-purpose` or a custom subagent when you need to continue the work. Claude uses the `SendMessage` tool with the agent’s ID or name as the `to` field to resume it. `SendMessage` doesn’t require [agent teams](/docs/en/agent-teams) to be enabled; only structured team-protocol messages such as `shutdown_request` and `plan_approval_response` do. To resume a subagent, ask Claude to continue the previous work: ```python Use the code-reviewer subagent to review the authentication module [Agent completes] Continue that code review and now analyze the authorization logic [Claude resumes the subagent with full context from previous conversation] ``` A completed subagent that receives a `SendMessage` auto-resumes in the background without a new `Agent` invocation. The same applies to a subagent that Claude stopped with the `TaskStop` tool. As of v2.1.191, a subagent you stopped yourself, with `x` in `/tasks` or an SDK `stop_task` request, doesn’t auto-resume. The `SendMessage` call returns a refusal telling Claude the agent was cancelled. Type into that subagent’s transcript in the subagent panel to resume it yourself, which clears the stop so later `SendMessage` calls can auto-resume it again. Resuming starts a new run of the agent under the same ID, so a subagent that had already failed or completed shows as running again in the task list and in the Agent SDK’s task events. Before v2.1.205, it kept showing its earlier failed or completed status while the resumed run was working. As of v2.1.199, `SendMessage` checks that a name still refers to the same agent it reached earlier in the conversation. If a newer agent has taken the name, such as a re-spawned background agent that reused it, Claude Code refuses the send rather than delivering it to the wrong agent, and the error reports which agent the name now reaches so Claude can retarget. To reach the earlier agent while it’s still running, Claude addresses it by the agent ID it received when it spawned that agent. The check is scoped to the current conversation and resets on `/clear`. As of v2.1.198, a subagent treats messages from the agent that launched it as normal task direction, including mid-task course corrections, and acts on them within its own permission settings. Two limits still hold regardless of who sent the message: no message from any agent counts as your approval for a pending permission prompt, and no agent message can change a subagent’s permission settings, `CLAUDE.md`, or configuration. Only the permission system or your own messages can grant approval. You can also ask Claude for the agent ID if you want to reference it explicitly, or find IDs in the transcript files at `~/.claude/projects/{project}/{sessionId}/subagents/`. Each transcript is stored as `agent-{agentId}.jsonl`. Subagent transcripts persist independently of the main conversation: - **Main conversation compaction**: when the main conversation compacts, subagent transcripts are unaffected. They’re stored in separate files. - **Session persistence**: subagent transcripts persist within their session. You can [resume a subagent](#resume-subagents) after restarting Claude Code by resuming the same session. - **Automatic cleanup**: Claude Code deletes subagent transcripts after the `cleanupPeriodDays` retention period, 30 days by default. [​](#auto-compaction) Auto-compaction Subagents support automatic compaction using the same logic as the main conversation. Compaction triggers under the same conditions, and `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` applies to subagents as well. See [environment variables](/docs/en/env-vars) for when the override takes effect. Compaction events are logged in subagent transcript files: ```python { "type": "system", "subtype": "compact_boundary", "compactMetadata": { "trigger": "auto", "preTokens": 167189 } } ``` The `preTokens` value shows how many tokens were used before compaction occurred. [​](#fork-the-current-conversation) Fork the current conversation Run a forked subagent with `/subtask`, which requires Claude Code v2.1.212 or later. When [agent view is turned off](/docs/en/agent-view#turn-off-agent-view), `/subtask` isn’t available and `/fork` starts the forked subagent instead; otherwise `/fork` copies the whole session into a new [background session](/docs/en/agent-view#from-inside-a-session).Before v2.1.212, the forked-subagent command was `/fork`. It was enabled by default on v2.1.161 or later; on v2.1.117 through v2.1.160 it required setting the [`CLAUDE_CODE_FORK_SUBAGENT`](/docs/en/env-vars) environment variable to `1`, unless a server-side rollout enabled it.Letting Claude itself spawn forks is experimental and may change in future releases. This capability may also be enabled in interactive sessions as part of a staged rollout. A fork is a subagent that inherits the entire conversation so far instead of starting fresh. This drops the input isolation that subagents otherwise provide: a fork sees the same system prompt, tools, model, and message history as the main session, so you can hand it a side task without re-explaining the situation. The fork’s own tool calls still stay out of your conversation and only its final result comes back, so your main context window stays clean. Use a fork when a named subagent would need too much background to be useful, or when you want to try several approaches in parallel from the same starting point. To control fork mode regardless of the staged rollout, set [`CLAUDE_CODE_FORK_SUBAGENT`](/docs/en/env-vars) to `1` to enable it explicitly or to `0` to disable it. The variable is honored in interactive mode and via the SDK or `claude -p`. Enabling fork mode changes Claude Code in two ways: - Claude can spawn a fork by requesting the `fork` subagent type explicitly. When Claude doesn’t request a type, it still gets the [general-purpose](#built-in-subagents) subagent, and named subagents such as Explore still spawn as before. - Every subagent runs in the [background](#run-subagents-in-foreground-or-background), whether it is a fork or a named subagent. Set `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` to `1` to keep subagents synchronous. You can start a fork yourself with `/subtask` followed by a task, with or without the variable set. On v2.1.161 through v2.1.211 the command is `/fork`. Claude Code names the fork from the first words of the task. The following example forks the conversation to draft test cases while you continue with the implementation in the main session: ```python /subtask draft unit tests for the parser changes so far ``` The fork appears in a panel below your prompt and runs in the background while you keep working. When it finishes, its result arrives as a message in your main conversation. The next section covers the panel controls for watching and steering forks while they run. [​](#observe-and-steer-running-forks) Observe and steer running forks Running forks appear in a panel below the prompt input, with one row for the main session and one for each fork. Use these keys to interact with the panel: | Key | Action | |:----------|:-------------------------------------------------------------------| | `↑` / `↓` | Move between rows | | `Enter` | Open the selected fork’s transcript and send it follow-up messages | | `x` | Dismiss a finished fork or stop a running one | | `Esc` | Return focus to the prompt input | With a fork’s or subagent’s transcript open, follow-up messages and [skills](/docs/en/skills) go to that agent, but built-in commands still run in your main conversation. As of v2.1.199, typing `/model` or `/fast` in that view shows a notice that it changes the main conversation’s model or fast mode, not the viewed agent’s, instead of running it silently. [​](#how-forks-differ-from-named-subagents) How forks differ from named subagents A fork inherits everything the main session has at the moment it spawns. A named subagent starts from its own definition. | | Fork | Named subagent | |:------------------------|:---------------------------------|:------------------------------------------------------------------------------------------------------------------| | Context | Full conversation history | Fresh context with the prompt you pass | | System prompt and tools | Same as main session | From the subagent’s [definition file](#write-subagent-files), [filtered for background runs](#available-tools) | | Model | Same as main session | From the subagent’s `model` field | | Permissions | Prompts surface in your terminal | [Prompts surface in your main session](#run-subagents-in-foreground-or-background) when running in the background | | Prompt cache | Shared with main session | Separate cache | Because a fork’s system prompt and tool definitions are identical to the parent, its first request reuses the parent’s [prompt cache](/docs/en/prompt-caching#subagents-and-the-cache). This makes forking cheaper than spawning a fresh subagent for tasks that need the same context. When Claude spawns a fork through the Agent tool, it can pass `isolation: "worktree"` so the fork’s file edits are written to a separate git worktree instead of your checkout. [​](#limitations) Limitations Setting `CLAUDE_CODE_FORK_SUBAGENT=1` enables fork mode in interactive sessions, [non-interactive mode](/docs/en/headless), and the Agent SDK; setting it to `0` disables fork mode everywhere, including any server-side rollout. A fork can’t spawn further forks. [​](#example-subagents) Example subagents These examples demonstrate effective patterns for building subagents. Use them as starting points, or generate a customized version with Claude. **Best practices:** - **Design focused subagents:** each subagent should excel at one specific task - **Write detailed descriptions:** Claude uses the description to decide when to delegate - **Limit tool access:** grant only necessary permissions for security and focus - **Check into version control:** share project subagents with your team [​](#code-reviewer) Code reviewer A read-only subagent that reviews code without modifying it. This example shows how to design a focused subagent with limited tool access that excludes Edit and Write, and a detailed prompt that specifies exactly what to look for and how to format output. ```python --- name: code-reviewer description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code. tools: Read, Grep, Glob, Bash model: inherit --- You are a senior code reviewer ensuring high standards of code quality and security. When invoked: 1. Run git diff to see recent changes 2. Focus on modified files 3. Begin review immediately Review checklist: - Code is clear and readable - Functions and variables are well-named - No duplicated code - Proper error handling - No exposed secrets or API keys - Input validation implemented - Good test coverage - Performance considerations addressed Provide feedback organized by priority: - Critical issues (must fix) - Warnings (should fix) - Suggestions (consider improving) Include specific examples of how to fix issues. ``` [​](#debugger) Debugger A subagent that can both analyze and fix issues. Unlike the code reviewer, this one includes Edit because fixing bugs requires modifying code. The prompt provides a clear workflow from diagnosis to verification. ```python --- name: debugger description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues. tools: Read, Edit, Bash, Grep, Glob --- You are an expert debugger specializing in root cause analysis. When invoked: 1. Capture error message and stack trace 2. Identify reproduction steps 3. Isolate the failure location 4. Implement minimal fix 5. Verify solution works Debugging process: - Analyze error messages and logs - Check recent code changes - Form and test hypotheses - Add strategic debug logging - Inspect variable states For each issue, provide: - Root cause explanation - Evidence supporting the diagnosis - Specific code fix - Testing approach - Prevention recommendations Focus on fixing the underlying issue, not the symptoms. ``` [​](#data-scientist) Data scientist A domain-specific subagent for data analysis work. This example shows how to create subagents for specialized workflows outside of typical coding tasks. It explicitly sets `model: sonnet` for more capable analysis. ```python --- name: data-scientist description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries. tools: Bash, Read, Write model: sonnet --- You are a data scientist specializing in SQL and BigQuery analysis. When invoked: 1. Understand the data analysis requirement 2. Write efficient SQL queries 3. Use BigQuery command line tools (bq) when appropriate 4. Analyze and summarize results 5. Present findings clearly Key practices: - Write optimized SQL queries with proper filters - Use appropriate aggregations and joins - Include comments explaining complex logic - Format results for readability - Provide data-driven recommendations For each analysis: - Explain the query approach - Document any assumptions - Highlight key findings - Suggest next steps based on data Always ensure queries are efficient and cost-effective. ``` [​](#database-query-validator) Database query validator A subagent that allows Bash access but validates commands to permit only read-only SQL queries. This example shows how to use `PreToolUse` hooks for conditional validation when you need finer control than the `tools` field provides. ```python --- name: db-reader description: Execute read-only database queries. Use when analyzing data or generating reports. tools: Bash hooks: PreToolUse: - matcher: "Bash" hooks: - type: command command: "./scripts/validate-readonly-query.sh" --- You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data. When asked to analyze data: 1. Identify which tables contain the relevant data 2. Write efficient SELECT queries with appropriate filters 3. Present results clearly with context You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access. ``` Claude Code [passes hook input as JSON](/docs/en/hooks#pretooluse-input) via stdin to hook commands. The validation script reads this JSON, extracts the command being executed, and checks it against a list of SQL write operations. If a write operation is detected, the script [exits with code 2](/docs/en/hooks#exit-code-2-behavior-per-event) to block execution and returns an error message to Claude via stderr. Create the validation script anywhere in your project. The path must match the `command` field in your hook configuration: ```python #!/bin/bash # Blocks SQL write operations, allows SELECT queries # Read JSON input from stdin INPUT=$(cat) # Extract the command field from tool_input using jq COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty') if [ -z "$COMMAND" ]; then exit 0 fi # Block write operations (case-insensitive) if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2 exit 2 fi exit 0 ``` On macOS and Linux, make the script executable: ```python chmod +x ./scripts/validate-readonly-query.sh ``` On Windows, write the validation script in PowerShell and add `shell: powershell` to the hook entry. See [running hooks in PowerShell](/docs/en/hooks#windows-powershell-tool). The hook receives JSON via stdin with the Bash command in `tool_input.command`. Exit code 2 blocks the operation and feeds the error message back to Claude. See [Hooks](/docs/en/hooks#exit-code-output) for details on exit codes and [Hook input](/docs/en/hooks#pretooluse-input) for the complete input schema. The system prompt tells the subagent to refuse write requests, so the hook is a backstop: if the subagent attempts a write anyway, Claude Code blocks the command and the subagent sees the `Blocked: Write operations not allowed. Use SELECT queries only.` message. [​](#next-steps) Next steps Now that you understand subagents, explore these related features: - [Distribute subagents with plugins](/docs/en/plugins) to share subagents across teams or projects - [Run Claude Code programmatically](/docs/en/headless) with the Agent SDK for CI/CD and automation - [Use MCP servers](/docs/en/mcp) to give subagents access to external tools and data --- ## customer-service-agent.md # Creating a Customer Service Agent with Client-Side Tools In this recipe, we\'ll demonstrate how to create a customer service chatbot using Claude 3 plus client-side tools. The chatbot will be able to look up customer information, retrieve order details, and cancel orders on behalf of the customer. We\'ll define the necessary tools and simulate synthetic responses to showcase the chatbot\'s capabilities. ::: ::: {.cell .markdown} ## Step 1: Set up the environment First, let\'s install the required libraries and set up the Claude API client. ::: ::: {.cell .code} ``` python %pip install anthropic ``` ::: ::: {.cell .code execution_count="18"} ``` python import anthropic client = anthropic.Client() MODEL_NAME = "claude-opus-4-1" ``` ::: ::: {.cell .markdown} ## Step 2: Define the client-side tools Next, we\'ll define the client-side tools that our chatbot will use to assist customers. We\'ll create three tools: get_customer_info, get_order_details, and cancel_order. ::: ::: {.cell .code execution_count="2"} ``` python tools = [ { "name": "get_customer_info", "description": "Retrieves customer information based on their customer ID. Returns the customer's name, email, and phone number.", "input_schema": { "type": "object", "properties": { "customer_id": { "type": "string", "description": "The unique identifier for the customer.", } }, "required": ["customer_id"], }, }, { "name": "get_order_details", "description": "Retrieves the details of a specific order based on the order ID. Returns the order ID, product name, quantity, price, and order status.", "input_schema": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The unique identifier for the order.", } }, "required": ["order_id"], }, }, { "name": "cancel_order", "description": "Cancels an order based on the provided order ID. Returns a confirmation message if the cancellation is successful.", "input_schema": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The unique identifier for the order to be cancelled.", } }, "required": ["order_id"], }, }, ] ``` ::: ::: {.cell .markdown} ## Step 3: Simulate synthetic tool responses Since we don\'t have real customer data or order information, we\'ll simulate synthetic responses for our tools. In a real-world scenario, these functions would interact with your actual customer database and order management system. ::: ::: {.cell .code execution_count="15"} ``` python def get_customer_info(customer_id): # Simulated customer data customers = { "C1": {"name": "John Doe", "email": "john@example.com", "phone": "123-456-7890"}, "C2": {"name": "Jane Smith", "email": "jane@example.com", "phone": "987-654-3210"}, } return customers.get(customer_id, "Customer not found") def get_order_details(order_id): # Simulated order data orders = { "O1": { "id": "O1", "product": "Widget A", "quantity": 2, "price": 19.99, "status": "Shipped", }, "O2": { "id": "O2", "product": "Gadget B", "quantity": 1, "price": 49.99, "status": "Processing", }, } return orders.get(order_id, "Order not found") def cancel_order(order_id): # Simulated order cancellation if order_id in ["O1", "O2"]: return True else: return False ``` ::: ::: {.cell .markdown} ## Step 4: Process tool calls and return results We\'ll create a function to process the tool calls made by Claude and return the appropriate results. ::: ::: {.cell .code execution_count="4"} ``` python def process_tool_call(tool_name, tool_input): if tool_name == "get_customer_info": return get_customer_info(tool_input["customer_id"]) elif tool_name == "get_order_details": return get_order_details(tool_input["order_id"]) elif tool_name == "cancel_order": return cancel_order(tool_input["order_id"]) ``` ::: ::: {.cell .markdown} ## Step 5: Interact with the chatbot Now, let\'s create a function to interact with the chatbot. We\'ll send a user message, process any tool calls made by Claude, and return the final response to the user. ::: ::: {.cell .code execution_count="13"} ``` python import json def chatbot_interaction(user_message): print(f"\n{'=' * 50}\nUser Message: {user_message}\n{'=' * 50}") messages = [{"role": "user", "content": user_message}] response = client.messages.create( model=MODEL_NAME, max_tokens=4096, tools=tools, messages=messages ) print("\nInitial Response:") print(f"Stop Reason: {response.stop_reason}") print(f"Content: {response.content}") while response.stop_reason == "tool_use": tool_use = next(block for block in response.content if block.type == "tool_use") tool_name = tool_use.name tool_input = tool_use.input print(f"\nTool Used: {tool_name}") print("Tool Input:") print(json.dumps(tool_input, indent=2)) tool_result = process_tool_call(tool_name, tool_input) print("\nTool Result:") print(json.dumps(tool_result, indent=2)) messages = [ {"role": "user", "content": user_message}, {"role": "assistant", "content": response.content}, { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": tool_use.id, "content": str(tool_result), } ], }, ] response = client.messages.create( model=MODEL_NAME, max_tokens=4096, tools=tools, messages=messages ) print("\nResponse:") print(f"Stop Reason: {response.stop_reason}") print(f"Content: {response.content}") final_response = next( (block.text for block in response.content if hasattr(block, "text")), None, ) print(f"\nFinal Response: {final_response}") return final_response ``` ::: ::: {.cell .markdown} ## Step 6: Test the chatbot Let\'s test our customer service chatbot with a few sample queries. ::: ::::: {.cell .code execution_count="17"} ``` python chatbot_interaction("Can you tell me the email address for customer C1?") chatbot_interaction("What is the status of order O2?") chatbot_interaction("Please cancel order O1 for me.") ``` ::: {.output .stream .stdout} ================================================== User Message: Can you tell me the email address for customer C1? ================================================== Initial Response: Stop Reason: tool_use Content: [ContentBlock(text='<thinking>The get_customer_info function retrieves a customer\'s name, email, and phone number given their customer ID. To call this function, I need the customer_id parameter. The user provided the customer ID "C1" in their request, so I have the necessary information to make the API call.</thinking>', type='text'), ContentBlockToolUse(id='toolu_019F9JHokMkJ1dHw5BEh28sA', input={'customer_id': 'C1'}, name='get_customer_info', type='tool_use')] Tool Used: get_customer_info Tool Input: { "customer_id": "C1" } Tool Result: { "name": "John Doe", "email": "john@example.com", "phone": "123-456-7890" } Response: Stop Reason: end_turn Content: [ContentBlock(text='The email address for customer C1 (John Doe) is john@example.com.', type='text')] Final Response: The email address for customer C1 (John Doe) is john@example.com. ================================================== User Message: What is the status of order O2? ================================================== Initial Response: Stop Reason: tool_use Content: [ContentBlock(text='<thinking>\nBased on the provided functions, the most relevant one for this request is get_order_details, which takes an order_id parameter and returns details about that specific order, including the order status.\n\nThe user has provided an order ID in their request - "O2". So the required order_id parameter can be filled with this value.\n\nSince the required parameter is available, I can proceed with calling the get_order_details function to retrieve the order status for order O2.\n</thinking>', type='text'), ContentBlockToolUse(id='toolu_01K1u68uC94edXx8MVT35eR3', input={'order_id': 'O2'}, name='get_order_details', type='tool_use')] Tool Used: get_order_details Tool Input: { "order_id": "O2" } Tool Result: { "id": "O2", "product": "Gadget B", "quantity": 1, "price": 49.99, "status": "Processing" } Response: Stop Reason: end_turn Content: [ContentBlock(text='Based on the details returned from the get_order_details function, the status of order O2 is "Processing".', type='text')] Final Response: Based on the details returned from the get_order_details function, the status of order O2 is "Processing". ================================================== User Message: Please cancel order O1 for me. ================================================== Initial Response: Stop Reason: tool_use Content: [ContentBlock(text='<thinking>\nThe relevant tool to cancel an order is the cancel_order function. \nThis function requires an order_id parameter.\nThe user provided the order ID "O1" in their request, so we have the necessary parameter to call the cancel_order function.\n</thinking>', type='text'), ContentBlockToolUse(id='toolu_01W3ZkP2QCrjHf5bKM6wvT2s', input={'order_id': 'O1'}, name='cancel_order', type='tool_use')] Tool Used: cancel_order Tool Input: { "order_id": "O1" } Tool Result: true Response: Stop Reason: end_turn Content: [ContentBlock(text='Based on the confirmation received, your order O1 has been successfully cancelled. Please let me know if there is anything else I can assist you with.', type='text')] Final Response: Based on the confirmation received, your order O1 has been successfully cancelled. Please let me know if there is anything else I can assist you with. ::: ::: {.output .execute_result execution_count="17"} 'Based on the confirmation received, your order O1 has been successfully cancelled. Please let me know if there is anything else I can assist you with.' ::: ::::: ::: {.cell .markdown} And that\'s it! We\'ve created a customer service chatbot using Claude 3 models and client-side tools. The chatbot can look up customer information, retrieve order details, and cancel orders based on the user\'s requests. By defining clear tool descriptions and schemas, we enable Claude to effectively understand and utilize the available tools to assist customers. Feel free to expand on this example by integrating with your actual customer database and order management system, and by adding more tools to handle a wider range of customer service tasks. ::: --- ## documentation-patterns.md # Command Documentation Patterns Strategies for creating self-documenting, maintainable commands with excellent user experience. ## Overview Well-documented commands are easier to use, maintain, and distribute. Documentation should be embedded in the command itself, making it immediately accessible to users and maintainers. ## Self-Documenting Command Structure ### Complete Command Template ```markdown --- description: Clear, actionable description under 60 chars argument-hint: [arg1] [arg2] [optional-arg] allowed-tools: Read, Bash(git:*) model: sonnet --- <!-- COMMAND: command-name VERSION: 1.0.0 AUTHOR: Team Name LAST UPDATED: 2025-01-15 PURPOSE: Detailed explanation of what this command does and why it exists. USAGE: /command-name arg1 arg2 ARGUMENTS: arg1: Description of first argument (required) arg2: Description of second argument (optional, defaults to X) EXAMPLES: /command-name feature-branch main → Compares feature-branch with main /command-name my-branch → Compares my-branch with current branch REQUIREMENTS: - Git repository - Branch must exist - Permissions to read repository RELATED COMMANDS: /other-command - Related functionality /another-command - Alternative approach TROUBLESHOOTING: - If branch not found: Check branch name spelling - If permission denied: Check repository access CHANGELOG: v1.0.0 (2025-01-15): Initial release v0.9.0 (2025-01-10): Beta version --> # Command Implementation [Command prompt content here...] [Explain what will happen...] [Guide user through steps...] [Provide clear output...] ``` ### Documentation Comment Sections **PURPOSE**: Why the command exists - Problem it solves - Use cases - When to use vs when not to use **USAGE**: Basic syntax - Command invocation pattern - Required vs optional arguments - Default values **ARGUMENTS**: Detailed argument documentation - Each argument described - Type information - Valid values/ranges - Defaults **EXAMPLES**: Concrete usage examples - Common use cases - Edge cases - Expected outputs **REQUIREMENTS**: Prerequisites - Dependencies - Permissions - Environmental setup **RELATED COMMANDS**: Connections - Similar commands - Complementary commands - Alternative approaches **TROUBLESHOOTING**: Common issues - Known problems - Solutions - Workarounds **CHANGELOG**: Version history - What changed when - Breaking changes highlighted - Migration guidance ## In-Line Documentation Patterns ### Commented Sections ```markdown --- description: Complex multi-step command --- <!-- SECTION 1: VALIDATION --> <!-- This section checks prerequisites before proceeding --> Checking prerequisites... - Git repository: !`git rev-parse --git-dir 2>/dev/null` - Branch exists: [validation logic] <!-- SECTION 2: ANALYSIS --> <!-- Analyzes the differences between branches --> Analyzing differences between $1 and $2... [Analysis logic...] <!-- SECTION 3: RECOMMENDATIONS --> <!-- Provides actionable recommendations --> Based on analysis, recommend: [Recommendations...] <!-- END: Next steps for user --> ``` ### Inline Explanations ```markdown --- description: Deployment command with inline docs --- # Deploy to $1 ## Pre-flight Checks <!-- We check branch status to prevent deploying from wrong branch --> Current branch: !`git branch --show-current` <!-- Production deploys must come from main/master --> if [ "$1" = "production" ] && [ "$(git branch --show-current)" != "main" ]; then ⚠️ WARNING: Not on main branch for production deploy This is unusual. Confirm this is intentional. fi <!-- Test status ensures we don't deploy broken code --> Running tests: !`npm test` ✓ All checks passed ## Deployment <!-- Actual deployment happens here --> <!-- Uses blue-green strategy for zero-downtime --> Deploying to $1 environment... [Deployment steps...] <!-- Post-deployment verification --> Verifying deployment health... [Health checks...] Deployment complete! ## Next Steps <!-- Guide user on what to do after deployment --> 1. Monitor logs: /logs $1 2. Run smoke tests: /smoke-test $1 3. Notify team: /notify-deployment $1 ``` ### Decision Point Documentation ```markdown --- description: Interactive deployment command --- # Interactive Deployment ## Configuration Review Target: $1 Current version: !`cat version.txt` New version: $2 <!-- DECISION POINT: User confirms configuration --> <!-- This pause allows user to verify everything is correct --> <!-- We can't automatically proceed because deployment is risky --> Review the above configuration. **Continue with deployment?** - Reply "yes" to proceed - Reply "no" to cancel - Reply "edit" to modify configuration [Await user input before continuing...] <!-- After user confirms, we proceed with deployment --> <!-- All subsequent steps are automated --> Proceeding with deployment... ``` ## Help Text Patterns ### Built-in Help Command Create a help subcommand for complex commands: ```markdown --- description: Main command with help argument-hint: [subcommand] [args] --- # Command Processor if [ "$1" = "help" ] || [ "$1" = "--help" ] || [ "$1" = "-h" ]; then **Command Help** USAGE: /command [subcommand] [args] SUBCOMMANDS: init [name] Initialize new configuration deploy [env] Deploy to environment status Show current status rollback Rollback last deployment help Show this help EXAMPLES: /command init my-project /command deploy staging /command status /command rollback For detailed help on a subcommand: /command [subcommand] --help Exit. fi [Regular command processing...] ``` ### Contextual Help Provide help based on context: ```markdown --- description: Context-aware command argument-hint: [operation] [target] --- # Context-Aware Operation if [ -z "$1" ]; then **No operation specified** Available operations: - analyze: Analyze target for issues - fix: Apply automatic fixes - report: Generate detailed report Usage: /command [operation] [target] Examples: /command analyze src/ /command fix src/app.js /command report Run /command help for more details. Exit. fi [Command continues if operation provided...] ``` ## Error Message Documentation ### Helpful Error Messages ```markdown --- description: Command with good error messages --- # Validation Command if [ -z "$1" ]; then ❌ ERROR: Missing required argument The 'file-path' argument is required. USAGE: /validate [file-path] EXAMPLE: /validate src/app.js Try again with a file path. Exit. fi if [ ! -f "$1" ]; then ❌ ERROR: File not found: $1 The specified file does not exist or is not accessible. COMMON CAUSES: 1. Typo in file path 2. File was deleted or moved 3. Insufficient permissions SUGGESTIONS: - Check spelling: $1 - Verify file exists: ls -la $(dirname "$1") - Check permissions: ls -l "$1" Exit. fi [Command continues if validation passes...] ``` ### Error Recovery Guidance ```markdown --- description: Command with recovery guidance --- # Operation Command Running operation... !`risky-operation.sh` if [ $? -ne 0 ]; then ❌ OPERATION FAILED The operation encountered an error and could not complete. WHAT HAPPENED: The risky-operation.sh script returned a non-zero exit code. WHAT THIS MEANS: - Changes may be partially applied - System may be in inconsistent state - Manual intervention may be needed RECOVERY STEPS: 1. Check operation logs: cat /tmp/operation.log 2. Verify system state: /check-state 3. If needed, rollback: /rollback-operation 4. Fix underlying issue 5. Retry operation: /retry-operation NEED HELP? - Check troubleshooting guide: /help troubleshooting - Contact support with error code: ERR_OP_FAILED_001 Exit. fi ``` ## Usage Example Documentation ### Embedded Examples ```markdown --- description: Command with embedded examples --- # Feature Command This command performs feature analysis with multiple options. ## Basic Usage \`\`\` /feature analyze src/ \`\`\` Analyzes all files in src/ directory for feature usage. ## Advanced Usage \`\`\` /feature analyze src/ --detailed \`\`\` Provides detailed analysis including: - Feature breakdown by file - Usage patterns - Optimization suggestions ## Use Cases **Use Case 1: Quick overview** \`\`\` /feature analyze . \`\`\` Get high-level feature summary of entire project. **Use Case 2: Specific directory** \`\`\` /feature analyze src/components \`\`\` Focus analysis on components directory only. **Use Case 3: Comparison** \`\`\` /feature analyze src/ --compare baseline.json \`\`\` Compare current features against baseline. --- Now processing your request... [Command implementation...] ``` ### Example-Driven Documentation ```markdown --- description: Example-heavy command --- # Transformation Command ## What This Does Transforms data from one format to another. ## Examples First ### Example 1: JSON to YAML **Input:** `data.json` \`\`\`json {"name": "test", "value": 42} \`\`\` **Command:** `/transform data.json yaml` **Output:** `data.yaml` \`\`\`yaml name: test value: 42 \`\`\` ### Example 2: CSV to JSON **Input:** `data.csv` \`\`\`csv name,value test,42 \`\`\` **Command:** `/transform data.csv json` **Output:** `data.json` \`\`\`json [{"name": "test", "value": "42"}] \`\`\` ### Example 3: With Options **Command:** `/transform data.json yaml --pretty --sort-keys` **Result:** Formatted YAML with sorted keys --- ## Your Transformation File: $1 Format: $2 [Perform transformation...] ``` ## Maintenance Documentation ### Version and Changelog ```markdown <!-- VERSION: 2.1.0 LAST UPDATED: 2025-01-15 AUTHOR: DevOps Team CHANGELOG: v2.1.0 (2025-01-15): - Added support for YAML configuration - Improved error messages - Fixed bug with special characters in arguments v2.0.0 (2025-01-01): - BREAKING: Changed argument order - BREAKING: Removed deprecated --old-flag - Added new validation checks - Migration guide: /migration-v2 v1.5.0 (2024-12-15): - Added --verbose flag - Improved performance by 50% v1.0.0 (2024-12-01): - Initial stable release MIGRATION NOTES: From v1.x to v2.0: Old: /command arg1 arg2 --old-flag New: /command arg2 arg1 The --old-flag is removed. Use --new-flag instead. DEPRECATION WARNINGS: - The --legacy-mode flag is deprecated as of v2.1.0 - Will be removed in v3.0.0 (estimated 2025-06-01) - Use --modern-mode instead KNOWN ISSUES: - #123: Slow performance with large files (workaround: use --stream flag) - #456: Special characters in Windows (fix planned for v2.2.0) --> ``` ### Maintenance Notes ```markdown <!-- MAINTENANCE NOTES: CODE STRUCTURE: - Lines 1-50: Argument parsing and validation - Lines 51-100: Main processing logic - Lines 101-150: Output formatting - Lines 151-200: Error handling DEPENDENCIES: - Requires git 2.x or later - Uses jq for JSON processing - Needs bash 4.0+ for associative arrays PERFORMANCE: - Fast path for small inputs (< 1MB) - Streams large files to avoid memory issues - Caches results in /tmp for 1 hour SECURITY CONSIDERATIONS: - Validates all inputs to prevent injection - Uses allowed-tools to limit Bash access - No credentials in command file TESTING: - Unit tests: tests/command-test.sh - Integration tests: tests/integration/ - Manual test checklist: tests/manual-checklist.md FUTURE IMPROVEMENTS: - TODO: Add support for TOML format - TODO: Implement parallel processing - TODO: Add progress bar for large files RELATED FILES: - lib/parser.sh: Shared parsing logic - lib/formatter.sh: Output formatting - config/defaults.yml: Default configuration --> ``` ## README Documentation Commands should have companion README files: ```markdown # Command Name Brief description of what the command does. ## Installation This command is part of the [plugin-name] plugin. Install with: \`\`\` /plugin install plugin-name \`\`\` ## Usage Basic usage: \`\`\` /command-name [arg1] [arg2] \`\`\` ## Arguments - `arg1`: Description (required) - `arg2`: Description (optional, defaults to X) ## Examples ### Example 1: Basic Usage \`\`\` /command-name value1 value2 \`\`\` Description of what happens. ### Example 2: Advanced Usage \`\`\` /command-name value1 --option \`\`\` Description of advanced feature. ## Configuration Optional configuration file: `.claude/command-name.local.md` \`\`\`markdown --- default_arg: value enable_feature: true --- \`\`\` ## Requirements - Git 2.x or later - jq (for JSON processing) - Node.js 14+ (optional, for advanced features) ## Troubleshooting ### Issue: Command not found **Solution:** Ensure plugin is installed and enabled. ### Issue: Permission denied **Solution:** Check file permissions and allowed-tools setting. ## Contributing Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md). ## License MIT License - See [LICENSE](LICENSE). ## Support - Issues: https://github.com/user/plugin/issues - Docs: https://docs.example.com - Email: support@example.com ``` ## Best Practices ### Documentation Principles 1. **Write for your future self**: Assume you'll forget details 2. **Examples before explanations**: Show, then tell 3. **Progressive disclosure**: Basic info first, details available 4. **Keep it current**: Update docs when code changes 5. **Test your docs**: Verify examples actually work ### Documentation Locations 1. **In command file**: Core usage, examples, inline explanations 2. **README**: Installation, configuration, troubleshooting 3. **Separate docs**: Detailed guides, tutorials, API reference 4. **Comments**: Implementation details for maintainers ### Documentation Style 1. **Clear and concise**: No unnecessary words 2. **Active voice**: "Run the command" not "The command can be run" 3. **Consistent terminology**: Use same terms throughout 4. **Formatted well**: Use headings, lists, code blocks 5. **Accessible**: Assume reader is beginner ### Documentation Maintenance 1. **Version everything**: Track what changed when 2. **Deprecate gracefully**: Warn before removing features 3. **Migration guides**: Help users upgrade 4. **Archive old docs**: Keep old versions accessible 5. **Review regularly**: Ensure docs match reality ## Documentation Checklist Before releasing a command: - [ ] Description in frontmatter is clear - [ ] argument-hint documents all arguments - [ ] Usage examples in comments - [ ] Common use cases shown - [ ] Error messages are helpful - [ ] Requirements documented - [ ] Related commands listed - [ ] Changelog maintained - [ ] Version number updated - [ ] README created/updated - [ ] Examples actually work - [ ] Troubleshooting section complete With good documentation, commands become self-service, reducing support burden and improving user experience. --- ## engineering-building-effective-agents.md <!-- Source: https://www.anthropic.com/engineering/building-effective-agents --> # Building Effective Agents **Published:** Dec 19, 2024 **Authors:** Erik Schluntz and Barry Zhang ## Introduction After collaborating with numerous teams developing LLM agents across industries, Anthropic found that "the most successful implementations weren't using complex frameworks or specialized libraries." ## What are agents? The term "agent" has multiple definitions. Some define agents as fully autonomous systems operating independently over extended periods using various tools. Others describe more prescriptive implementations following predefined workflows. Anthropic distinguishes between two agentic system types: - **Workflows**: Systems where LLMs and tools are orchestrated through predefined code paths - **Agents**: Systems where LLMs dynamically direct their own processes and tool usage ## When (and when not) to use agents Developers should pursue "the simplest solution possible, and only increasing complexity when needed." Agentic systems trade latency and cost for better task performance. Workflows offer predictability for well-defined tasks, while agents suit situations requiring flexibility and model-driven decision-making at scale. ## When and how to use frameworks Available frameworks include the Claude Agent SDK, Strands Agents SDK by AWS, Rivet, and Vellum. These simplify standard tasks like calling LLMs and chaining calls together. However, they create abstraction layers that obscure underlying prompts and responses, making debugging harder. Developers should "start by using LLM APIs directly: many patterns can be implemented in a few lines of code." ## Building blocks, workflows, and agents ### The Augmented LLM The foundational building block enhances LLMs with retrieval, tools, and memory capabilities. Models can generate search queries, select tools, and determine what information to retain. ### Workflow: Prompt Chaining This decomposes tasks into sequential steps where each LLM call processes the previous output. Programmatic checks ensure the process stays on track. Use this for tasks decomposable into fixed subtasks, trading latency for accuracy. **Examples**: Marketing copy generation followed by translation; document outline creation with validation before writing. ### Workflow: Routing Routing classifies inputs and directs them to specialized followup tasks, enabling separation of concerns and specialized prompts. **Examples**: Directing different customer service query types to appropriate processes; routing easy questions to smaller models like Claude Haiku and complex ones to Claude Sonnet. ### Workflow: Parallelization Two variations exist: - **Sectioning**: Breaking tasks into independent parallel subtasks - **Voting**: Running the same task multiple times for diverse outputs Parallelization works when subtasks parallelize for speed or when multiple perspectives increase confidence. **Examples**: Guardrail screening; code vulnerability reviews; content appropriateness evaluation. ### Workflow: Orchestrator-workers A central LLM dynamically breaks down tasks, delegates to worker LLMs, and synthesizes results. This suits complex tasks with unpredictable subtask needs. **Examples**: Coding products making complex multi-file changes; search tasks gathering information from multiple sources. ### Workflow: Evaluator-optimizer One LLM generates responses while another provides evaluation and feedback in a loop. Effective when clear evaluation criteria exist and iterative refinement adds measurable value. **Examples**: Literary translation refinement; complex multi-round search tasks. ### Agents Agents are emerging in production as LLMs mature in reasoning, planning, tool usage, and error recovery. They "begin their work with either a command from, or interactive discussion with, the human user." During execution, agents gain "ground truth" from the environment at each step to assess progress. They may pause for human feedback at checkpoints or when encountering blockers. "Agents can handle sophisticated tasks, but their implementation is often straightforward. They are typically just LLMs using tools based on environmental feedback in a loop." **When to use**: Open-ended problems where required steps are unpredictable and a fixed path cannot be hardcoded. Agents' autonomy makes them ideal for scaling trusted-environment tasks, though they incur higher costs and potential for compounding errors. **Examples**: Coding agents resolving SWE-bench tasks; computer use implementations. ## Core principles for implementation 1. Maintain **simplicity** in agent design 2. Prioritize **transparency** by explicitly showing planning steps 3. Craft agent-computer interfaces through thorough tool **documentation and testing** ## Appendix 1: Agents in practice ### Customer support Customer support naturally combines chatbot interfaces with tool-enhanced capabilities. Success can be measured through user-defined resolutions. Some companies use usage-based pricing, charging only for successful resolutions. ### Coding agents Software development shows remarkable potential for LLM features. Solutions are verifiable through automated testing, enabling iterative refinement. Agents can solve real GitHub issues, though human review remains crucial for broader system requirements. ## Appendix 2: Prompt engineering your tools Tool definitions deserve equal prompt engineering attention as overall prompts. "Tool definitions and specifications should be given just as much prompt engineering attention as your overall prompts." When designing tool formats: - Provide sufficient tokens for reasoning before models constrain themselves - Keep formats close to naturally occurring internet text - Eliminate formatting overhead like line counting Invest effort in agent-computer interfaces (ACI) equal to human-computer interface (HCI) design. Include example usage, edge cases, input requirements, and clear tool boundaries in definitions. --- ## flow-diagram.md # Chief of Staff Agent Architecture ```mermaid graph TD User[User] --> Chief[Chief of Staff Agent] Chief --> Memory[CLAUDE.md] Chief --> FinData[financial_data/] Chief --> Tools Chief --> Commands[Slash Commands] Chief --> Styles[Output Styles] Chief --> Hooks[Hooks] Tools --> Task[Task Tool] Task --> FA[Financial Analyst] Task --> Recruiter[Recruiter] FA --> Scripts1[Python Scripts] Recruiter --> Scripts2[Python Scripts] style Chief fill:#f9f,stroke:#333,stroke-width:3px style Task fill:#bbf,stroke:#333,stroke-width:2px style FA fill:#bfb,stroke:#333,stroke-width:2px style Recruiter fill:#bfb,stroke:#333,stroke-width:2px ``` ## Expected Agent Communication Flow ```mermaid sequenceDiagram participant User participant Chief as Chief of Staff participant Task as Task Tool participant FA as Financial Analyst participant Scripts as Python Scripts participant Hooks as Post-Write Hook User->>Chief: /budget-impact hiring 5 engineers Chief->>Chief: Expand slash command Chief->>Task: Delegate financial analysis Task->>FA: Analyze hiring impact FA->>Scripts: Execute hiring_impact.py Scripts-->>FA: Return analysis results FA->>FA: Generate report FA-->>Task: Return findings Task-->>Chief: Subagent results Chief->>Chief: Write report to disk Chief->>Hooks: Trigger post-write hook Hooks->>Hooks: Log to audit trail Chief-->>User: Executive summary ``` --- ## get-structured-output-from-agents-claude-code-docs-3b82938145.md ## On this page - [Why structured outputs?](#why-structured-outputs) - [Quick start](#quick-start) - [Type-safe schemas with Zod and Pydantic](#type-safe-schemas-with-zod-and-pydantic) - [Output format configuration](#output-format-configuration) - [Example: TODO tracking agent](#example-todo-tracking-agent) - [Error handling](#error-handling) - [Related resources](#related-resources) Input and output # Get structured output from agents Copy pageCopy page Return validated JSON from agent workflows using JSON Schema, Zod, or Pydantic. Get type-safe, structured data after multi-turn tool use. Copy pageCopy page Structured outputs let you define the exact shape of data you want back from an agent. The agent can use any tools it needs to complete the task, and you still get validated JSON matching your schema at the end. Define a [JSON Schema](https://json-schema.org/understanding-json-schema/about) for the structure you need, and the SDK validates the output against it, re-prompting on mismatch. If validation does not succeed within the retry limit, the result is an error instead of structured data; see [Error handling](#error-handling). For full type safety, use [Zod](#type-safe-schemas-with-zod-and-pydantic) (TypeScript) or [Pydantic](#type-safe-schemas-with-zod-and-pydantic) (Python) to define your schema and get strongly-typed objects back. [​](#why-structured-outputs) Why structured outputs? Agents return free-form text by default, which works for chat but not when you need to use the output programmatically. Structured outputs give you typed data you can pass directly to your application logic, database, or UI components. Consider a recipe app where an agent searches the web and brings back recipes. Without structured outputs, you get free-form text that you’d need to parse yourself. With structured outputs, you define the shape you want and get typed data you can use directly in your app. Without structured outputs ```python Here's a classic chocolate chip cookie recipe! **Chocolate Chip Cookies** Prep time: 15 minutes | Cook time: 10 minutes Ingredients: - 2 1/4 cups all-purpose flour - 1 cup butter, softened ... ``` To use this in your app, you’d need to parse out the title, convert “15 minutes” to a number, separate ingredients from instructions, and handle inconsistent formatting across responses. With structured outputs ```python { "name": "Chocolate Chip Cookies", "prep_time_minutes": 15, "cook_time_minutes": 10, "ingredients": [ { "item": "all-purpose flour", "amount": 2.25, "unit": "cups" }, { "item": "butter, softened", "amount": 1, "unit": "cup" } // ... ], "steps": ["Preheat oven to 375°F", "Cream butter and sugar" /* ... */] } ``` Typed data you can use directly in your UI. [​](#quick-start) Quick start To use structured outputs, define a [JSON Schema](https://json-schema.org/understanding-json-schema/about) describing the shape of data you want, then pass it to `query()` via the `outputFormat` option (TypeScript) or `output_format` option (Python). When the agent finishes, the result message includes a `structured_output` field with validated data matching your schema. The example below asks the agent to research Anthropic and return the company name, year founded, and headquarters as structured output. TypeScript Python ```python import { query } from "@anthropic-ai/claude-agent-sdk"; // Define the shape of data you want back const schema = { type: "object", properties: { company_name: { type: "string" }, founded_year: { type: "number" }, headquarters: { type: "string" } }, required: ["company_name"] }; try { for await (const message of query({ prompt: "Research Anthropic and provide key company information", options: { outputFormat: { type: "json_schema", schema: schema } } })) { // The result message contains structured_output with validated data if (message.type === "result" && message.subtype === "success" && message.structured_output) { console.log(message.structured_output); // { company_name: "Anthropic", founded_year: 2021, headquarters: "San Francisco, CA" } } } } catch (error) { // A single-shot query() throws after yielding an error result, such as // error_max_structured_output_retries; see the Error handling section. console.error(`Session ended with an error: ${error}`); } ``` ```python import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage # Define the shape of data you want back schema = { "type": "object", "properties": { "company_name": {"type": "string"}, "founded_year": {"type": "number"}, "headquarters": {"type": "string"}, }, "required": ["company_name"], } async def main(): try: async for message in query( prompt="Research Anthropic and provide key company information", options=ClaudeAgentOptions( output_format={"type": "json_schema", "schema": schema} ), ): # The result message contains structured_output with validated data if isinstance(message, ResultMessage) and message.structured_output: print(message.structured_output) # {'company_name': 'Anthropic', 'founded_year': 2021, 'headquarters': 'San Francisco, CA'} except Exception as error: # A single-shot query() raises after yielding an error result, such as # error_max_structured_output_retries; see the Error handling section. print(f"Session ended with an error: {error}") asyncio.run(main()) ``` [​](#type-safe-schemas-with-zod-and-pydantic) Type-safe schemas with Zod and Pydantic Instead of writing JSON Schema by hand, you can use [Zod](https://zod.dev/) (TypeScript) or [Pydantic](https://docs.pydantic.dev/latest/) (Python) to define your schema. These libraries generate the JSON Schema for you and let you parse the response into a fully-typed object you can use throughout your codebase with autocomplete and type checking. The example below defines a schema for a feature implementation plan with a summary, list of steps (each with complexity level), and potential risks. The agent plans the feature and returns a typed `FeaturePlan` object. You can then access properties like `plan.summary` and iterate over `plan.steps` with full type safety. The SDK validates schemas with JSON Schema draft-07, so schemas that declare a newer version are rejected. Zod targets draft 2020-12 by default, so pass `target: "draft-7"` when converting your schema. TypeScript Python ```python import { z } from "zod"; import { query } from "@anthropic-ai/claude-agent-sdk"; // Define schema with Zod const FeaturePlan = z.object({ feature_name: z.string(), summary: z.string(), steps: z.array( z.object({ step_number: z.number(), description: z.string(), estimated_complexity: z.enum(["low", "medium", "high"]) }) ), risks: z.array(z.string()) }); type FeaturePlan = z.infer<typeof FeaturePlan>; // Convert to JSON Schema using the draft-07 target the SDK expects const schema = z.toJSONSchema(FeaturePlan, { target: "draft-7" }); // Use in query try { for await (const message of query({ prompt: "Plan how to add dark mode support to a React app. Break it into implementation steps.", options: { outputFormat: { type: "json_schema", schema: schema } } })) { if (message.type === "result" && message.subtype === "success" && message.structured_output) { // Validate and get fully typed result const parsed = FeaturePlan.safeParse(message.structured_output); if (parsed.success) { const plan: FeaturePlan = parsed.data; console.log(`Feature: ${plan.feature_name}`); console.log(`Summary: ${plan.summary}`); plan.steps.forEach((step) => { console.log(`${step.step_number}. [${step.estimated_complexity}] ${step.description}`); }); } } } } catch (error) { // A single-shot query() throws after yielding an error result, such as // error_max_structured_output_retries; see the Error handling section. console.error(`Session ended with an error: ${error}`); } ``` ```python import asyncio from pydantic import BaseModel from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage class Step(BaseModel): step_number: int description: str estimated_complexity: str # 'low', 'medium', 'high' class FeaturePlan(BaseModel): feature_name: str summary: str steps: list[Step] risks: list[str] async def main(): try: async for message in query( prompt="Plan how to add dark mode support to a React app. Break it into implementation steps.", options=ClaudeAgentOptions( output_format={ "type": "json_schema", "schema": FeaturePlan.model_json_schema(), } ), ): if isinstance(message, ResultMessage) and message.structured_output: # Validate and get fully typed result plan = FeaturePlan.model_validate(message.structured_output) print(f"Feature: {plan.feature_name}") print(f"Summary: {plan.summary}") for step in plan.steps: print( f"{step.step_number}. [{step.estimated_complexity}] {step.description}" ) except Exception as error: # A single-shot query() raises after yielding an error result, such as # error_max_structured_output_retries; see the Error handling section. print(f"Session ended with an error: {error}") asyncio.run(main()) ``` **Benefits:** - Full type inference (TypeScript) and type hints (Python) - Runtime validation with `safeParse()` or `model_validate()` - Better error messages - Composable, reusable schemas [​](#output-format-configuration) Output format configuration The `outputFormat` (TypeScript) or `output_format` (Python) option accepts an object with: - `type`: Set to `"json_schema"` for structured outputs - `schema`: A [JSON Schema](https://json-schema.org/understanding-json-schema/about) object defining your output structure. You can generate this from a Zod schema with `z.toJSONSchema(schema, { target: "draft-7" })` or a Pydantic model with `.model_json_schema()` The SDK supports standard JSON Schema features including all basic types (object, array, string, number, boolean, null), `enum`, `const`, `required`, nested objects, and `$ref` definitions. For the full list of supported features and limitations, see [JSON Schema limitations](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#json-schema-limitations). A schema that isn’t valid JSON Schema fails the run at startup with an error naming the problem. Before v2.1.205, an invalid schema was silently ignored and the agent returned unstructured text. The `format` keyword, such as `"format": "email"`, is accepted as an annotation and isn’t enforced by the SDK’s validator. Before v2.1.205, any schema containing `format` was treated as invalid. [​](#example-todo-tracking-agent) Example: TODO tracking agent This example demonstrates how structured outputs work with multi-step tool use. The agent needs to find TODO comments in the codebase, then look up git blame information for each one. It autonomously decides which tools to use (Grep to search, Bash to run git commands) and combines the results into a single structured response. The schema includes optional fields (`author` and `date`) since git blame information might not be available for all files. The agent fills in what it can find and omits the rest. TypeScript Python ```python import { query } from "@anthropic-ai/claude-agent-sdk"; // Define structure for TODO extraction const todoSchema = { type: "object", properties: { todos: { type: "array", items: { type: "object", properties: { text: { type: "string" }, file: { type: "string" }, line: { type: "number" }, author: { type: "string" }, date: { type: "string" } }, required: ["text", "file", "line"] } }, total_count: { type: "number" } }, required: ["todos", "total_count"] }; // Agent uses Grep to find TODOs, Bash to get git blame info try { for await (const message of query({ prompt: "Find all TODO comments in this codebase and identify who added them", options: { outputFormat: { type: "json_schema", schema: todoSchema } } })) { if (message.type === "result" && message.subtype === "success" && message.structured_output) { const data = message.structured_output as { total_count: number; todos: Array<{ file: string; line: number; text: string; author?: string; date?: string }> }; console.log(`Found ${data.total_count} TODOs`); data.todos.forEach((todo) => { console.log(`${todo.file}:${todo.line} - ${todo.text}`); if (todo.author) { console.log(` Added by ${todo.author} on ${todo.date}`); } }); } } } catch (error) { // A single-shot query() throws after yielding an error result, such as // error_max_structured_output_retries; see the Error handling section. console.error(`Session ended with an error: ${error}`); } ``` ```python import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage # Define structure for TODO extraction todo_schema = { "type": "object", "properties": { "todos": { "type": "array", "items": { "type": "object", "properties": { "text": {"type": "string"}, "file": {"type": "string"}, "line": {"type": "number"}, "author": {"type": "string"}, "date": {"type": "string"}, }, "required": ["text", "file", "line"], }, }, "total_count": {"type": "number"}, }, "required": ["todos", "total_count"], } async def main(): # Agent uses Grep to find TODOs, Bash to get git blame info try: async for message in query( prompt="Find all TODO comments in this codebase and identify who added them", options=ClaudeAgentOptions( output_format={"type": "json_schema", "schema": todo_schema} ), ): if isinstance(message, ResultMessage) and message.structured_output: data = message.structured_output print(f"Found {data['total_count']} TODOs") for todo in data["todos"]: print(f"{todo['file']}:{todo['line']} - {todo['text']}") if "author" in todo: print(f" Added by {todo['author']} on {todo['date']}") except Exception as error: # A single-shot query() raises after yielding an error result, such as # error_max_structured_output_retries; see the Error handling section. print(f"Session ended with an error: {error}") asyncio.run(main()) ``` [​](#error-handling) Error handling Structured output generation can fail when the agent cannot produce valid JSON matching your schema. This typically happens when the schema is too complex for the task, the task itself is ambiguous, or the agent hits its retry limit trying to fix validation errors. It can also happen without any validation failure: a [model fallback](/docs/en/model-config#automatic-model-fallback) can retract an already-completed output mid-stream, and if no retry replaces it the run ends with the same error. Check the `errors` list on the result message to tell the two causes apart before debugging your schema. When an error occurs, the result message has a `subtype` indicating what went wrong: | Subtype | Meaning | |---------------------------------------|---------------------------------------------------------------------------------------------------------------------------------| | `success` | Output was generated and validated successfully | | `error_max_structured_output_retries` | No valid output remained after multiple attempts (validation failures, or a model-fallback retraction with no successful retry) | A result can also end with subtype `success` but no `structured_output` value, for example when the run completes without the agent producing a structured output. Treat that case as a failure as well. The example below treats a result as successful only when the `subtype` is `success` and `structured_output` is present, and handles every other result as a failure: TypeScript Python ```python import { query } from "@anthropic-ai/claude-agent-sdk"; const contactSchema = { type: "object", properties: { name: { type: "string" }, email: { type: "string" } }, required: ["name"] }; try { for await (const msg of query({ prompt: "Extract contact info from the document", options: { outputFormat: { type: "json_schema", schema: contactSchema } } })) { if (msg.type === "result") { if (msg.subtype === "success" && msg.structured_output) { // Use the validated output console.log(msg.structured_output); } else if (msg.subtype === "error_max_structured_output_retries") { console.error("Could not produce valid output"); } else { console.error("Run ended without a structured output"); } } } } catch (error) { // A single-shot query() throws after yielding an error result. If the // failure was an error result, the error subtype branches above have // already run; connection or process failures yield no result message. console.log(`Session ended with an error: ${error}`); } ``` ```python import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage contact_schema = { "type": "object", "properties": { "name": {"type": "string"}, "email": {"type": "string"}, }, "required": ["name"], } async def main(): try: async for message in query( prompt="Extract contact info from the document", options=ClaudeAgentOptions( output_format={"type": "json_schema", "schema": contact_schema} ), ): if isinstance(message, ResultMessage): if message.subtype == "success" and message.structured_output: # Use the validated output print(message.structured_output) elif message.subtype == "error_max_structured_output_retries": print("Could not produce valid output") else: print("Run ended without a structured output") except Exception as error: # A single-shot query() raises after yielding an error result. If the # failure was an error result, the error subtype branches above have # already run; connection or process failures yield no result message. print(f"Session ended with an error: {error}") asyncio.run(main()) ``` **Tips for avoiding errors:** - **Keep schemas focused.** Deeply nested schemas with many required fields are harder to satisfy. Start simple and add complexity as needed. - **Match schema to task.** If the task might not have all the information your schema requires, make those fields optional. - **Use clear prompts.** Ambiguous prompts make it harder for the agent to know what output to produce. [​](#related-resources) Related resources - [JSON Schema documentation](https://json-schema.org/): learn JSON Schema syntax for defining complex schemas with nested objects, arrays, enums, and validation constraints - [API Structured Outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs): use structured outputs with the Claude API directly for single-turn requests without tool use - [Custom tools](/docs/en/agent-sdk/custom-tools): give your agent custom tools to call during execution before returning structured output --- ## give-claude-custom-tools-claude-code-docs-1ff2a59e92.md ## On this page - [Quick reference](#quick-reference) - [Create a custom tool](#create-a-custom-tool) - [Weather tool example](#weather-tool-example) - [Call a custom tool](#call-a-custom-tool) - [Add more tools](#add-more-tools) - [Add tool annotations](#add-tool-annotations) - [Control tool access](#control-tool-access) - [Tool name format](#tool-name-format) - [Configure allowed tools](#configure-allowed-tools) - [Handle errors](#handle-errors) - [Return images and resources](#return-images-and-resources) - [Images](#images) - [Resources](#resources) - [Return structured data](#return-structured-data) - [Example: unit converter](#example-unit-converter) - [Next steps](#next-steps) - [Related documentation](#related-documentation) Extend with tools # Give Claude custom tools Copy pageCopy page Define custom tools with the Claude Agent SDK’s in-process MCP server so Claude can call your functions, hit your APIs, and perform domain-specific operations. Copy pageCopy page Custom tools extend the Agent SDK by letting you define your own functions that Claude can call during a conversation. Using the SDK’s in-process MCP server, you can give Claude access to databases, external APIs, domain-specific logic, or any other capability your application needs. This guide covers how to define tools with input schemas and handlers, bundle them into an MCP server, pass them to `query`, and control which tools Claude can access. It also covers error handling, tool annotations, and returning non-text content like images. [​](#quick-reference) Quick reference | If you want to… | Do this | |:---------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Define a tool | Use [`@tool`](/docs/en/agent-sdk/python#tool) (Python) or [`tool()`](/docs/en/agent-sdk/typescript#tool) (TypeScript) with a name, description, schema, and handler. See [Create a custom tool](#create-a-custom-tool). | | Register a tool with Claude | Wrap in `create_sdk_mcp_server` / `createSdkMcpServer` and pass to `mcpServers` in `query()`. See [Call a custom tool](#call-a-custom-tool). | | Pre-approve a tool | Add to your allowed tools. See [Configure allowed tools](#configure-allowed-tools). | | Remove a built-in tool from Claude’s context | Pass a `tools` array listing only the built-ins you want. See [Configure allowed tools](#configure-allowed-tools). | | Let Claude call tools in parallel | Set `readOnlyHint: true` on tools with no side effects. See [Add tool annotations](#add-tool-annotations). | | Control the error message Claude reads | Return `isError: true` to compose the message instead of surfacing the raw exception. See [Handle errors](#handle-errors). | | Return images or files | Use `image` or `resource` blocks in the content array. See [Return images and resources](#return-images-and-resources). | | Return a machine-readable JSON result | Set `structuredContent` on the result. See [Return structured data](#return-structured-data). | | Scale to many tools | Use [tool search](/docs/en/agent-sdk/tool-search) to load tools on demand. | [​](#create-a-custom-tool) Create a custom tool A tool is defined by four parts, passed as arguments to the [`tool()`](/docs/en/agent-sdk/typescript#tool) helper in TypeScript or the [`@tool`](/docs/en/agent-sdk/python#tool) decorator in Python: - **Name:** a unique identifier Claude uses to call the tool. - **Description:** what the tool does. Claude reads this to decide when to call it. - **Input schema:** the arguments Claude must provide. In TypeScript this is always a [Zod schema](https://zod.dev/), and the handler’s `args` are typed from it automatically. In Python this is a dict mapping names to types, like `{"latitude": float}`, which the SDK converts to JSON Schema for you. The Python decorator also accepts a full [JSON Schema](https://json-schema.org/understanding-json-schema/about) dict directly when you need enums, ranges, optional fields, or nested objects. - **Handler:** the async function that runs when Claude calls the tool. It receives the validated arguments and must return an object with: - `content` (required): an array of result blocks, each with a `type` of `"text"`, `"image"`, `"audio"`, `"resource"`, or `"resource_link"`. See [Return images and resources](#return-images-and-resources) for non-text blocks. - `structuredContent` (optional): a JSON object holding the result as machine-readable data, returned alongside `content`. See [Return structured data](#return-structured-data). - `isError` (optional): set to `true` to signal a tool failure so Claude can react to it. See [Handle errors](#handle-errors). After defining a tool, wrap it in a server with [`createSdkMcpServer`](/docs/en/agent-sdk/typescript#createsdkmcpserver) (TypeScript) or [`create_sdk_mcp_server`](/docs/en/agent-sdk/python#create_sdk_mcp_server) (Python). The server runs in-process inside your application, not as a separate process. [​](#weather-tool-example) Weather tool example This example defines a `get_temperature` tool and wraps it in an MCP server. It only sets up the tool; to pass it to `query` and run it, see [Call a custom tool](#call-a-custom-tool) below. Python TypeScript ```python from typing import Any import httpx from claude_agent_sdk import tool, create_sdk_mcp_server # Define a tool: name, description, input schema, handler @tool( "get_temperature", "Get the current temperature at a location", {"latitude": float, "longitude": float}, ) async def get_temperature(args: dict[str, Any]) -> dict[str, Any]: async with httpx.AsyncClient() as client: response = await client.get( "https://api.open-meteo.com/v1/forecast", params={ "latitude": args["latitude"], "longitude": args["longitude"], "current": "temperature_2m", "temperature_unit": "fahrenheit", }, ) data = response.json() # Return a content array - Claude sees this as the tool result return { "content": [ { "type": "text", "text": f"Temperature: {data['current']['temperature_2m']}°F", } ] } # Wrap the tool in an in-process MCP server weather_server = create_sdk_mcp_server( name="weather", version="1.0.0", tools=[get_temperature], ) ``` ```python import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk"; import { z } from "zod"; // Define a tool: name, description, input schema, handler const getTemperature = tool( "get_temperature", "Get the current temperature at a location", { latitude: z.number().describe("Latitude coordinate"), // .describe() adds a field description Claude sees longitude: z.number().describe("Longitude coordinate") }, async (args) => { // args is typed from the schema: { latitude: number; longitude: number } const response = await fetch( `https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}¤t=temperature_2m&temperature_unit=fahrenheit` ); const data: any = await response.json(); // Return a content array - Claude sees this as the tool result return { content: [{ type: "text", text: `Temperature: ${data.current.temperature_2m}°F` }] }; } ); // Wrap the tool in an in-process MCP server const weatherServer = createSdkMcpServer({ name: "weather", version: "1.0.0", tools: [getTemperature] }); ``` See the [`tool()`](/docs/en/agent-sdk/typescript#tool) TypeScript reference or the [`@tool`](/docs/en/agent-sdk/python#tool) Python reference for full parameter details, including JSON Schema input formats and return value structure. To make a parameter optional: in TypeScript, add `.default()` to the Zod field. In Python, the dict schema treats every key as required, so leave the parameter out of the schema, mention it in the description string, and read it with `args.get()` in the handler. The [`get_precipitation_chance` tool below](#add-more-tools) shows both patterns. [​](#call-a-custom-tool) Call a custom tool Pass the MCP server you created to `query` via the `mcpServers` option. The key in `mcpServers` becomes the `{server_name}` segment in each tool’s fully qualified name: `mcp__{server_name}__{tool_name}`. List that name in `allowedTools` so the tool runs without a permission prompt. These snippets reuse the `weatherServer` from the [example above](#weather-tool-example) to ask Claude what the weather is in a specific location. Python TypeScript ```python import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage async def main(): options = ClaudeAgentOptions( mcp_servers={"weather": weather_server}, allowed_tools=["mcp__weather__get_temperature"], ) async for message in query( prompt="What's the temperature in San Francisco?", options=options, ): # ResultMessage is the final message after all tool calls complete if isinstance(message, ResultMessage) and message.subtype == "success": print(message.result) asyncio.run(main()) ``` ```python import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "What's the temperature in San Francisco?", options: { mcpServers: { weather: weatherServer }, allowedTools: ["mcp__weather__get_temperature"] } })) { // "result" is the final message after all tool calls complete if (message.type === "result" && message.subtype === "success") { console.log(message.result); } } ``` Combine this snippet with the tool and server definitions from the [weather tool example](#weather-tool-example) in one file, then run it with `python weather.py` for Python or `npx tsx weather.ts` for TypeScript. Claude calls `get_temperature` and the script prints a one-line answer with the current temperature in San Francisco. [​](#add-more-tools) Add more tools A server holds as many tools as you list in its `tools` array. With more than one tool on a server, you can list each one in `allowedTools` individually or use the wildcard `mcp__weather__*` to cover every tool the server exposes. The example below defines a second tool, `get_precipitation_chance`, and replaces the `weatherServer` definition from the [weather tool example](#weather-tool-example) with one that lists both tools in the array. Python TypeScript ```python # Define a second tool for the same server @tool( "get_precipitation_chance", "Get the hourly precipitation probability for a location. " "Optionally pass 'hours' (1-24) to control how many hours to return.", {"latitude": float, "longitude": float}, ) async def get_precipitation_chance(args: dict[str, Any]) -> dict[str, Any]: # 'hours' isn't in the schema - read it with .get() to make it optional hours = args.get("hours", 12) async with httpx.AsyncClient() as client: response = await client.get( "https://api.open-meteo.com/v1/forecast", params={ "latitude": args["latitude"], "longitude": args["longitude"], "hourly": "precipitation_probability", "forecast_days": 1, }, ) data = response.json() chances = data["hourly"]["precipitation_probability"][:hours] return { "content": [ { "type": "text", "text": f"Next {hours} hours: {'%, '.join(map(str, chances))}%", } ] } # Rebuild the server with both tools in the array weather_server = create_sdk_mcp_server( name="weather", version="1.0.0", tools=[get_temperature, get_precipitation_chance], ) ``` ```python // Define a second tool for the same server const getPrecipitationChance = tool( "get_precipitation_chance", "Get the hourly precipitation probability for a location", { latitude: z.number(), longitude: z.number(), hours: z .number() .int() .min(1) .max(24) .default(12) // .default() makes the parameter optional .describe("How many hours of forecast to return") }, async (args) => { const response = await fetch( `https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}&hourly=precipitation_probability&forecast_days=1` ); const data: any = await response.json(); const chances = data.hourly.precipitation_probability.slice(0, args.hours); return { content: [{ type: "text", text: `Next ${args.hours} hours: ${chances.join("%, ")}%` }] }; } ); // Rebuild the server with both tools in the array const weatherServer = createSdkMcpServer({ name: "weather", version: "1.0.0", tools: [getTemperature, getPrecipitationChance] }); ``` [Tool search](/docs/en/agent-sdk/tool-search) is on by default and defers SDK MCP tools: Claude sees each tool’s name in a compact list and loads its full schema on demand. With tool search disabled, every tool in this array consumes context window space on every turn. In TypeScript, pass `alwaysLoad: true` in the `extras` argument of [`tool()`](/docs/en/agent-sdk/typescript#tool) or in the options of [`createSdkMcpServer()`](/docs/en/agent-sdk/typescript#createsdkmcpserver) to keep a tool’s full schema in the initial prompt. [​](#add-tool-annotations) Add tool annotations [Tool annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) are optional metadata describing how a tool behaves. Pass them as the fifth argument to `tool()` helper in TypeScript or via the `annotations` keyword argument for the `@tool` decorator in Python. All hint fields are Booleans. | Field | Default | Meaning | |:------------------|:--------|:----------------------------------------------------------------------------------------------------------------------| | `readOnlyHint` | `false` | Tool does not modify its environment. Controls whether the tool can be called in parallel with other read-only tools. | | `destructiveHint` | `true` | Tool may perform destructive updates. Informational only. | | `idempotentHint` | `false` | Repeated calls with the same arguments have no additional effect. Informational only. | | `openWorldHint` | `true` | Tool reaches systems outside your process. Informational only. | Annotations are metadata, not enforcement. A tool marked `readOnlyHint: true` can still write to disk if that’s what the handler does. Keep the annotation accurate to the handler. This example adds `readOnlyHint` to the `get_temperature` tool from the [weather tool example](#weather-tool-example). Python TypeScript ```python from claude_agent_sdk import tool, ToolAnnotations @tool( "get_temperature", "Get the current temperature at a location", {"latitude": float, "longitude": float}, annotations=ToolAnnotations( readOnlyHint=True ), # Lets Claude batch this with other read-only calls ) async def get_temperature(args): return {"content": [{"type": "text", "text": "..."}]} ``` ```python import { tool } from "@anthropic-ai/claude-agent-sdk"; import { z } from "zod"; tool( "get_temperature", "Get the current temperature at a location", { latitude: z.number(), longitude: z.number() }, async (args) => ({ content: [{ type: "text", text: `...` }] }), { annotations: { readOnlyHint: true } } // Lets Claude batch this with other read-only calls ); ``` See `ToolAnnotations` in the [TypeScript](/docs/en/agent-sdk/typescript#toolannotations) or [Python](/docs/en/agent-sdk/python#toolannotations) reference. [​](#control-tool-access) Control tool access The [weather tool example](#weather-tool-example) registered a server and listed tools in `allowedTools`. This section covers how tool names are constructed and how to scope access when you have multiple tools or want to restrict built-ins. [​](#tool-name-format) Tool name format When MCP tools are exposed to Claude, their names follow a specific format: - Pattern: `mcp__{server_name}__{tool_name}` - Example: A tool named `get_temperature` in server `weather` becomes `mcp__weather__get_temperature` [​](#configure-allowed-tools) Configure allowed tools The `tools` option and the allowed/disallowed lists affect two layers: availability, which controls whether a tool appears in Claude’s context, and permission, which controls whether a call is approved once Claude attempts it. `tools` and bare-name `disallowedTools` entries change availability. `allowedTools` and scoped `disallowedTools` rules change permission only. | Option | Layer | Effect | |:--------------------------|:-------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `tools: ["Read", "Grep"]` | Availability | Only the listed built-ins are in Claude’s context. Unlisted built-ins are removed. MCP tools are unaffected. | | `tools: []` | Availability | All built-ins are removed. Claude can only use your MCP tools. | | allowed tools | Permission | Listed tools run without a permission prompt. Unlisted tools remain available; calls go through the [permission flow](/docs/en/agent-sdk/permissions). | | disallowed tools | Both | A bare tool name such as `"Bash"` removes the tool from Claude’s context, the same as omitting it from `tools`. A scoped rule such as `"Bash(rm *)"` leaves the tool in context and denies only matching calls. | To remove a built-in entirely, omit it from `tools` or list its bare name in `disallowedTools` (Python: `disallowed_tools`); both keep the tool out of context so Claude never attempts it. A scoped `disallowedTools` rule blocks matching calls but leaves the tool visible, so Claude may waste a turn trying it. See [Configure permissions](/docs/en/agent-sdk/permissions) for the full evaluation order. [​](#handle-errors) Handle errors A handler error doesn’t stop the agent loop. The SDK’s in-process MCP server catches uncaught exceptions and returns them as error results, so how you report an error determines what Claude reads, not whether the query fails: | What happens | Result | |:-----------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------| | Handler throws an uncaught exception | The MCP server converts it to an error result carrying the raw exception message. Claude sees that message, and the agent loop continues. | | Handler catches the error and returns `isError: true` (TS) / `"is_error": True` (Python) | Claude sees the message you compose. You can add context the raw exception lacks, such as which request failed or what to try instead. | In both cases Claude can retry, try a different tool, or explain the failure. Catch errors yourself when the raw exception message isn’t enough for Claude to act on. The example below catches two kinds of failures inside the handler and composes the error message Claude reads. A non-200 HTTP status is caught from the response and returned as an error result. A network error or invalid JSON is caught by the surrounding `try/except` (Python) or `try/catch` (TypeScript) and also returned as an error result. In both cases Claude receives a message that describes the failure instead of a bare exception string. Python TypeScript ```python import json import httpx from typing import Any from claude_agent_sdk import tool from claude_agent_sdk import tool @tool( "fetch_data", "Fetch data from an API", {"endpoint": str}, # Simple schema ) async def fetch_data(args: dict[str, Any]) -> dict[str, Any]: try: async with httpx.AsyncClient() as client: response = await client.get(args["endpoint"]) if response.status_code != 200: # Return the failure as a tool result so Claude can react to it. # is_error marks this as a failed call rather than odd-looking data. return { "content": [ { "type": "text", "text": f"API error: {response.status_code} {response.reason_phrase}", } ], "is_error": True, } data = response.json() return {"content": [{"type": "text", "text": json.dumps(data, indent=2)}]} except Exception as e: # Composes the message Claude reads. An uncaught exception would # reach Claude as the raw str(e) with no context. return { "content": [{"type": "text", "text": f"Failed to fetch data: {str(e)}"}], "is_error": True, } ``` ```python import { tool } from "@anthropic-ai/claude-agent-sdk"; import { z } from "zod"; tool( "fetch_data", "Fetch data from an API", { endpoint: z.string().url().describe("API endpoint URL") }, async (args) => { try { const response = await fetch(args.endpoint); if (!response.ok) { // Return the failure as a tool result so Claude can react to it. // isError marks this as a failed call rather than odd-looking data. return { content: [ { type: "text", text: `API error: ${response.status} ${response.statusText}` } ], isError: true }; } const data = await response.json(); return { content: [ { type: "text", text: JSON.stringify(data, null, 2) } ] }; } catch (error) { // Composes the message Claude reads. An uncaught throw would // reach Claude as the raw error message with no context. return { content: [ { type: "text", text: `Failed to fetch data: ${error instanceof Error ? error.message : String(error)}` } ], isError: true }; } } ); ``` [​](#return-images-and-resources) Return images and resources The `content` array in a tool result accepts `text`, `image`, `audio`, `resource`, and `resource_link` blocks. You can mix them in the same response. In TypeScript, the SDK saves audio blocks to disk and Claude receives a text block with the saved file path; in Python, the SDK drops audio blocks from the tool result and logs a warning. The SDK converts resource link blocks to a text block containing the link’s name, URI, and description. [​](#images) Images An image block carries the image bytes inline, encoded as base64. There is no URL field. To return an image that lives at a URL, fetch it in the handler, read the response bytes, and base64-encode them before returning. The result is processed as visual input. | Field | Type | Notes | |:-----------|:----------|:---------------------------------------------------------------------------| | `type` | `"image"` | | | `data` | `string` | Base64-encoded bytes. Raw base64 only, no `data:image/...;base64,` prefix | | `mimeType` | `string` | Required. For example `image/png`, `image/jpeg`, `image/webp`, `image/gif` | Python TypeScript ```python import base64 import httpx from claude_agent_sdk import tool from claude_agent_sdk import tool # Define a tool that fetches an image from a URL and returns it to Claude @tool("fetch_image", "Fetch an image from a URL and return it to Claude", {"url": str}) async def fetch_image(args): async with httpx.AsyncClient() as client: # Fetch the image bytes response = await client.get(args["url"]) return { "content": [ { "type": "image", "data": base64.b64encode(response.content).decode( "ascii" ), # Base64-encode the raw bytes "mimeType": response.headers.get( "content-type", "image/png" ), # Read MIME type from the response } ] } ``` ```python import { tool } from "@anthropic-ai/claude-agent-sdk"; import { z } from "zod"; tool( "fetch_image", "Fetch an image from a URL and return it to Claude", { url: z.string().url() }, async (args) => { const response = await fetch(args.url); // Fetch the image bytes const buffer = Buffer.from(await response.arrayBuffer()); // Read into a Buffer for base64 encoding const mimeType = response.headers.get("content-type") ?? "image/png"; return { content: [ { type: "image", data: buffer.toString("base64"), // Base64-encode the raw bytes mimeType } ] }; } ); ``` [​](#resources) Resources A resource block embeds a piece of content identified by a URI. The URI is a label for Claude to reference; the actual content rides in the block’s `text` or `blob` field. Use this when your tool produces something that makes sense to address by name later, such as a generated file or a record from an external system. | Field | Type | Notes | |:--------------------|:-------------|:-------------------------------------------------------------------------------------------------------------------------------------------| | `type` | `"resource"` | | | `resource.uri` | `string` | Identifier for the content. Any URI scheme | | `resource.text` | `string` | The content, if it’s text. Provide this or `blob`, not both | | `resource.blob` | `string` | The content base64-encoded, if it’s binary. TypeScript only: the Python SDK drops binary resources from the tool result and logs a warning | | `resource.mimeType` | `string` | Optional | This example shows a resource block returned from inside a tool handler. The URI `file:///tmp/report.md` is a label that Claude can reference later; the SDK does not read from that path. TypeScript Python ```python return { content: [ { type: "resource", resource: { uri: "file:///tmp/report.md", // Label for Claude to reference, not a path the SDK reads mimeType: "text/markdown", text: "# Report\n..." // The actual content, inline } } ] }; ``` ```python return { "content": [ { "type": "resource", "resource": { "uri": "file:///tmp/report.md", # Label for Claude to reference, not a path the SDK reads "mimeType": "text/markdown", "text": "# Report\n...", # The actual content, inline }, } ] } ``` These block shapes come from the MCP `CallToolResult` type. See the [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-result) for the full definition. [​](#return-structured-data) Return structured data `structuredContent` is an optional JSON object on the result, separate from the `content` array. Use it to return raw values that Claude can read as exact fields instead of parsing them out of a text string or image. When `structuredContent` is set, Claude receives the JSON plus any image or resource blocks from `content`. Text blocks in `content` are not forwarded, since they are assumed to duplicate the structured data. The example below renders a chart as an image block and returns the data points behind it in `structuredContent` from the same handler. In the snippet, `chartPngBuffer` is a `Buffer` holding the rendered PNG bytes. TypeScript ```python return { content: [ { type: "image", data: chartPngBuffer.toString("base64"), mimeType: "image/png" } ], structuredContent: { series: "temperature_2m", unit: "fahrenheit", points: [62.1, 63.4, 65.0, 64.2] } }; ``` The Python `@tool` decorator forwards only `content` and `is_error` from the handler’s return dict. To return `structuredContent` from Python, run a [standalone MCP server](/docs/en/agent-sdk/mcp) instead of an in-process SDK server. [​](#example-unit-converter) Example: unit converter This tool converts values between units of length, temperature, and weight. A user can ask “convert 100 kilometers to miles” or “what is 72°F in Celsius,” and Claude picks the right unit type and units from the request. It demonstrates two patterns: - **Enum schemas:** `unit_type` is constrained to a fixed set of values. In TypeScript, use `z.enum()`. In Python, the dict schema doesn’t support enums, so the full JSON Schema dict is required. - **Unsupported input handling:** when a conversion pair isn’t found, the handler returns `isError: true` so Claude can tell the user what went wrong rather than treating a failure as a normal result. Python TypeScript ```python from typing import Any from claude_agent_sdk import tool, create_sdk_mcp_server # z.enum() in TypeScript becomes an "enum" constraint in JSON Schema. # The dict schema has no equivalent, so full JSON Schema is required. @tool( "convert_units", "Convert a value from one unit to another", { "type": "object", "properties": { "unit_type": { "type": "string", "enum": ["length", "temperature", "weight"], "description": "Category of unit", }, "from_unit": { "type": "string", "description": "Unit to convert from, e.g. kilometers, fahrenheit, pounds", }, "to_unit": {"type": "string", "description": "Unit to convert to"}, "value": {"type": "number", "description": "Value to convert"}, }, "required": ["unit_type", "from_unit", "to_unit", "value"], }, ) async def convert_units(args: dict[str, Any]) -> dict[str, Any]: conversions = { "length": { "kilometers_to_miles": lambda v: v * 0.621371, "miles_to_kilometers": lambda v: v * 1.60934, "meters_to_feet": lambda v: v * 3.28084, "feet_to_meters": lambda v: v * 0.3048, }, "temperature": { "celsius_to_fahrenheit": lambda v: (v * 9) / 5 + 32, "fahrenheit_to_celsius": lambda v: (v - 32) * 5 / 9, "celsius_to_kelvin": lambda v: v + 273.15, "kelvin_to_celsius": lambda v: v - 273.15, }, "weight": { "kilograms_to_pounds": lambda v: v * 2.20462, "pounds_to_kilograms": lambda v: v * 0.453592, "grams_to_ounces": lambda v: v * 0.035274, "ounces_to_grams": lambda v: v * 28.3495, }, } key = f"{args['from_unit']}_to_{args['to_unit']}" fn = conversions.get(args["unit_type"], {}).get(key) if not fn: return { "content": [ { "type": "text", "text": f"Unsupported conversion: {args['from_unit']} to {args['to_unit']}", } ], "is_error": True, } result = fn(args["value"]) return { "content": [ { "type": "text", "text": f"{args['value']} {args['from_unit']} = {result:.4f} {args['to_unit']}", } ] } converter_server = create_sdk_mcp_server( name="converter", version="1.0.0", tools=[convert_units], ) ``` ```python import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk"; import { z } from "zod"; const convert = tool( "convert_units", "Convert a value from one unit to another", { unit_type: z.enum(["length", "temperature", "weight"]).describe("Category of unit"), from_unit: z .string() .describe("Unit to convert from, e.g. kilometers, fahrenheit, pounds"), to_unit: z.string().describe("Unit to convert to"), value: z.number().describe("Value to convert") }, async (args) => { type Conversions = Record<string, Record<string, (v: number) => number>>; const conversions: Conversions = { length: { kilometers_to_miles: (v) => v * 0.621371, miles_to_kilometers: (v) => v * 1.60934, meters_to_feet: (v) => v * 3.28084, feet_to_meters: (v) => v * 0.3048 }, temperature: { celsius_to_fahrenheit: (v) => (v * 9) / 5 + 32, fahrenheit_to_celsius: (v) => ((v - 32) * 5) / 9, celsius_to_kelvin: (v) => v + 273.15, kelvin_to_celsius: (v) => v - 273.15 }, weight: { kilograms_to_pounds: (v) => v * 2.20462, pounds_to_kilograms: (v) => v * 0.453592, grams_to_ounces: (v) => v * 0.035274, ounces_to_grams: (v) => v * 28.3495 } }; const key = `${args.from_unit}_to_${args.to_unit}`; const fn = conversions[args.unit_type]?.[key]; if (!fn) { return { content: [ { type: "text", text: `Unsupported conversion: ${args.from_unit} to ${args.to_unit}` } ], isError: true }; } const result = fn(args.value); return { content: [ { type: "text", text: `${args.value} ${args.from_unit} = ${result.toFixed(4)} ${args.to_unit}` } ] }; } ); const converterServer = createSdkMcpServer({ name: "converter", version: "1.0.0", tools: [convert] }); ``` Once the server is defined, pass it to `query` the same way as the weather example. This example sends three different prompts in a loop to show the same tool handling different unit types. For each response, it inspects `AssistantMessage` objects (which contain the tool calls Claude made during that turn) and prints each `ToolUseBlock` before printing the final `ResultMessage` text. This lets you see when Claude is using the tool versus answering from its own knowledge. Because [tool search](/docs/en/agent-sdk/tool-search) is on by default, the output may also include a `ToolSearch` call as Claude loads the deferred tool schema. Python TypeScript ```python import asyncio from claude_agent_sdk import ( query, ClaudeAgentOptions, ResultMessage, AssistantMessage, ToolUseBlock, ) async def main(): options = ClaudeAgentOptions( mcp_servers={"converter": converter_server}, allowed_tools=["mcp__converter__convert_units"], ) prompts = [ "Convert 100 kilometers to miles.", "What is 72°F in Celsius?", "How many pounds is 5 kilograms?", ] for prompt in prompts: try: async for message in query(prompt=prompt, options=options): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, ToolUseBlock): print(f"[tool call] {block.name}({block.input})") elif isinstance(message, ResultMessage) and message.subtype == "success": print(f"Q: {prompt}\nA: {message.result}\n") except Exception as error: # A single-shot query() raises after yielding an error result. Only success # results are printed above, so handle the failure here and continue with # the next prompt. print(f"Call failed: {error}") asyncio.run(main()) ``` ```python import { query } from "@anthropic-ai/claude-agent-sdk"; const prompts = [ "Convert 100 kilometers to miles.", "What is 72°F in Celsius?", "How many pounds is 5 kilograms?" ]; for (const prompt of prompts) { try { for await (const message of query({ prompt, options: { mcpServers: { converter: converterServer }, allowedTools: ["mcp__converter__convert_units"] } })) { if (message.type === "assistant") { for (const block of message.message.content) { if (block.type === "tool_use") { console.log(`[tool call] ${block.name}`, block.input); } } } else if (message.type === "result" && message.subtype === "success") { console.log(`Q: ${prompt}\nA: ${message.result}\n`); } } } catch (error) { // A single-shot query() throws after yielding an error result. Only success // results are logged above, so handle the failure here and continue with // the next prompt. console.error(`Call failed: ${error}`); } } ``` [​](#next-steps) Next steps Custom tools wrap async functions in a standard interface. You can mix the patterns on this page in the same server: a single server can hold a database tool, an API gateway tool, and an image renderer alongside each other. From here: - If your server grows to dozens of tools, see [tool search](/docs/en/agent-sdk/tool-search) to defer loading them until Claude needs them. - To connect to external MCP servers (filesystem, GitHub, Slack) instead of building your own, see [Connect MCP servers](/docs/en/agent-sdk/mcp). - To control which tools run automatically versus requiring approval, see [Configure permissions](/docs/en/agent-sdk/permissions). [​](#related-documentation) Related documentation - [TypeScript SDK Reference](/docs/en/agent-sdk/typescript) - [Python SDK Reference](/docs/en/agent-sdk/python) - [MCP Documentation](https://modelcontextprotocol.io) - [SDK Overview](/docs/en/agent-sdk/overview) --- ## handle-approvals-and-user-input-claude-code-docs-7847f7d11b.md ## On this page - [Detect when Claude needs input](#detect-when-claude-needs-input) - [Handle tool approval requests](#handle-tool-approval-requests) - [Respond to tool requests](#respond-to-tool-requests) - [Handle clarifying questions](#handle-clarifying-questions) - [Question format](#question-format) - [Option previews (TypeScript)](#option-previews-typescript) - [Response format](#response-format) - [Support free-text input](#support-free-text-input) - [Complete example](#complete-example) - [Limitations](#limitations) - [Other ways to get user input](#other-ways-to-get-user-input) - [Streaming input](#streaming-input) - [Custom tools](#custom-tools) - [Related resources](#related-resources) Input and output # Handle approvals and user input Copy pageCopy page Surface Claude’s approval requests and clarifying questions to users, then return their decisions to the SDK. Copy pageCopy page While working on a task, Claude sometimes needs to check in with users. It might need permission before deleting files, or need to ask which database to use for a new project. Your application needs to surface these requests to users so Claude can continue with their input. Claude requests user input in two situations: when it needs **permission to use a tool** (like deleting files or running commands), and when it has **clarifying questions** (via the `AskUserQuestion` tool). Both trigger your `canUseTool` callback, which pauses execution until you return a response. This is different from normal conversation turns where Claude finishes and waits for your next message. For clarifying questions, Claude generates the questions and options. Your role is to present them to users and return their selections. You can’t add your own questions to this flow; if you need to ask users something yourself, do that separately in your application logic. The callback can stay pending indefinitely. Execution remains paused until your callback returns, and the SDK only cancels the wait when the query itself is cancelled. If a user might take longer to respond than your process can reasonably stay running, return the [`defer` hook decision](/docs/en/hooks#defer-a-tool-call-for-later), which lets the process exit and resume later from the persisted session. This guide shows you how to detect each type of request and respond appropriately. [​](#detect-when-claude-needs-input) Detect when Claude needs input Pass a `canUseTool` callback in your query options. The callback fires whenever Claude needs user input, receiving the tool name and input as arguments: Python TypeScript ```python from claude_agent_sdk import ClaudeAgentOptions async def handle_tool_request(tool_name, input_data, context): # Prompt user and return allow or deny ... options = ClaudeAgentOptions(can_use_tool=handle_tool_request) ``` ```python async function handleToolRequest(toolName, input, options) { // options includes { signal: AbortSignal, suggestions?: PermissionUpdate[] } // Prompt user and return allow or deny } const options = { canUseTool: handleToolRequest }; ``` The callback fires in two cases: 1. **Tool needs approval**: Claude wants to use a tool that isn’t auto-approved by a [permission rule](/docs/en/agent-sdk/permissions) or permission mode. Check `tool_name` for the tool (e.g., `"Bash"`, `"Write"`). 2. **Claude asks a question**: Claude calls the `AskUserQuestion` tool. Check if `tool_name == "AskUserQuestion"` to handle it differently. If you specify a `tools` array, include `AskUserQuestion` for this to work. See [Handle clarifying questions](#handle-clarifying-questions) for details. **The callback never fires for auto-approved tools.** Any approval earlier in the [permission evaluation flow](/docs/en/agent-sdk/permissions#how-permissions-are-evaluated), an allow rule or a mode like `acceptEdits` or `bypassPermissions`, resolves the call before `canUseTool` is consulted. If you list a tool bare in `allowed_tools`, a `canUseTool` check for that tool never runs unless an ask rule or `plan` mode routes the call back to a prompt. For logic that must apply to every tool call, use a [`PreToolUse` hook](/docs/en/agent-sdk/hooks), which executes before the rest of the flow and can allow, deny, or modify requests.`AskUserQuestion`, MCP tools marked [`requiresUserInteraction`](/docs/en/mcp#require-approval-for-a-specific-tool), and connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools) reach the callback even when an allow rule matches. In `dontAsk` mode these calls are denied instead, without invoking the callback. You can also use the [`PermissionRequest` hook](/docs/en/agent-sdk/hooks#available-hooks) to send external notifications (Slack, email, push) when Claude is waiting for approval. [​](#handle-tool-approval-requests) Handle tool approval requests Once you’ve passed a `canUseTool` callback in your query options, it fires when Claude wants to use a tool that nothing earlier in the permission flow has approved. Your callback receives three arguments: | Argument | Description | |-------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `toolName` | The name of the tool Claude wants to use (e.g., `"Bash"`, `"Write"`, `"Edit"`) | | `input` | The parameters Claude is passing to the tool. Contents vary by tool. | | `options` (TS) / `context` (Python) | Additional context including optional `suggestions` (proposed `PermissionUpdate` entries to avoid re-prompting) and a cancellation signal. In TypeScript, `signal` is an `AbortSignal`; in Python, the signal field is reserved for future use. See [`ToolPermissionContext`](/docs/en/agent-sdk/python#toolpermissioncontext) for Python. | The `input` object contains tool-specific parameters. Common examples: | Tool | Input fields | |---------|-----------------------------------------| | `Bash` | `command`, `description`, `timeout` | | `Write` | `file_path`, `content` | | `Edit` | `file_path`, `old_string`, `new_string` | | `Read` | `file_path`, `offset`, `limit` | See the SDK reference for complete input schemas: [Python](/docs/en/agent-sdk/python#tool-input%2Foutput-types) \| [TypeScript](/docs/en/agent-sdk/typescript#tool-input-types). You can display this information to the user so they can decide whether to allow or reject the action, then return the appropriate response. The following example asks Claude to create and delete a test file. When Claude attempts each operation, the callback prints the tool request to the terminal and prompts for y/n approval. Python TypeScript ```python import asyncio from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query from claude_agent_sdk.types import ( HookMatcher, PermissionResultAllow, PermissionResultDeny, ToolPermissionContext, ) async def can_use_tool( tool_name: str, input_data: dict, context: ToolPermissionContext ) -> PermissionResultAllow | PermissionResultDeny: # Display the tool request print(f"\nTool: {tool_name}") if tool_name == "Bash": print(f"Command: {input_data.get('command')}") if input_data.get("description"): print(f"Description: {input_data.get('description')}") else: print(f"Input: {input_data}") # Get user approval response = input("Allow this action? (y/n): ") # Return allow or deny based on user's response if response.lower() == "y": # Allow: tool executes with the original (or modified) input return PermissionResultAllow(updated_input=input_data) else: # Deny: tool doesn't execute, Claude sees the message return PermissionResultDeny(message="User denied this action") # Required workaround: dummy hook keeps the stream open for can_use_tool async def dummy_hook(input_data, tool_use_id, context): return {"continue_": True} async def prompt_stream(): yield { "type": "user", "message": { "role": "user", "content": "Create a test file in /tmp and then delete it", }, } async def main(): async for message in query( prompt=prompt_stream(), options=ClaudeAgentOptions( can_use_tool=can_use_tool, hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]}, ), ): if isinstance(message, ResultMessage) and message.subtype == "success": print(message.result) asyncio.run(main()) ``` ```python import { query } from "@anthropic-ai/claude-agent-sdk"; import * as readline from "readline"; // Helper to prompt user for input in the terminal function prompt(question: string): Promise<string> { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(question, (answer) => { rl.close(); resolve(answer); }) ); } for await (const message of query({ prompt: "Create a test file in /tmp and then delete it", options: { canUseTool: async (toolName, input) => { // Display the tool request console.log(`\nTool: ${toolName}`); if (toolName === "Bash") { console.log(`Command: ${input.command}`); if (input.description) console.log(`Description: ${input.description}`); } else { console.log(`Input: ${JSON.stringify(input, null, 2)}`); } // Get user approval const response = await prompt("Allow this action? (y/n): "); // Return allow or deny based on user's response if (response.toLowerCase() === "y") { // Allow: tool executes with the original (or modified) input return { behavior: "allow", updatedInput: input }; } else { // Deny: tool doesn't execute, Claude sees the message return { behavior: "deny", message: "User denied this action" }; } } } })) { if ("result" in message) console.log(message.result); } ``` In Python, `can_use_tool` requires [streaming mode](/docs/en/agent-sdk/streaming-vs-single-mode). When you pass a finite message stream through `query(prompt=generator)` or `ClaudeSDKClient.connect(prompt=async_iterable)`, the SDK closes the input stream after the last message, before the permission callback can be invoked, unless a registered hook or in-process MCP server is keeping it open. The example above keeps it open with a `PreToolUse` hook that returns `{"continue_": True}`. Connecting with no prompt and sending messages through `ClaudeSDKClient.query()` keeps the stream open on its own and needs no hook. This example uses a `y/n` flow where any input other than `y` is treated as a denial. In practice, you might build a richer UI that lets users modify the request, provide feedback, or redirect Claude entirely. See [Respond to tool requests](#respond-to-tool-requests) for all the ways you can respond. [​](#respond-to-tool-requests) Respond to tool requests Your callback returns one of two response types: | Response | Python | TypeScript | |-----------|--------------------------------------------|---------------------------------------| | **Allow** | `PermissionResultAllow(updated_input=...)` | `{ behavior: "allow", updatedInput }` | | **Deny** | `PermissionResultDeny(message=...)` | `{ behavior: "deny", message }` | When allowing, the tool runs with the input Claude requested unless you return a modified input, `updatedInput` in TypeScript or `updated_input` in Python. Before v2.1.207, Claude Code rejected an allow result that omitted `updatedInput` and denied the tool call with a validation error. When denying, provide a message explaining why. Claude sees this message and may adjust its approach. Python TypeScript ```python from claude_agent_sdk.types import PermissionResultAllow, PermissionResultDeny # Allow the tool to execute return PermissionResultAllow(updated_input=input_data) # Block the tool return PermissionResultDeny(message="User rejected this action") ``` ```python // Allow the tool to execute return { behavior: "allow", updatedInput: input }; // Block the tool return { behavior: "deny", message: "User rejected this action" }; ``` Beyond allowing or denying, you can modify the tool’s input or provide context that helps Claude adjust its approach: - **Approve**: let the tool execute as Claude requested - **Approve with changes**: modify the input before execution (e.g., sanitize paths, add constraints) - **Approve and remember**: echo a suggested permission rule back so matching calls skip the prompt next time - **Reject**: block the tool and tell Claude why - **Suggest alternative**: block but guide Claude toward what the user wants instead - **Redirect entirely**: use [streaming input](/docs/en/agent-sdk/streaming-vs-single-mode) to send Claude a completely new instruction The `ask_user` and `askUser` helpers in the following snippets stand in for your application’s own prompt UI. - Approve - Approve with changes - Approve and remember - Reject - Suggest alternative - Redirect entirely The user approves the action as-is. Pass through the `input` from your callback unchanged and the tool executes exactly as Claude requested. Python TypeScript ```python async def can_use_tool(tool_name, input_data, context): print(f"Claude wants to use {tool_name}") approved = await ask_user("Allow this action?") if approved: return PermissionResultAllow(updated_input=input_data) return PermissionResultDeny(message="User declined") ``` ```python canUseTool: async (toolName, input) => { console.log(`Claude wants to use ${toolName}`); const approved = await askUser("Allow this action?"); if (approved) { return { behavior: "allow", updatedInput: input }; } return { behavior: "deny", message: "User declined" }; }; ``` The user approves but wants to modify the request first. You can change the input before the tool executes. Claude sees the result but isn’t told you changed anything. Useful for sanitizing parameters, adding constraints, or scoping access. Python TypeScript ```python async def can_use_tool(tool_name, input_data, context): if tool_name == "Bash": # User approved, but scope all commands to sandbox sandboxed_input = {**input_data} sandboxed_input["command"] = input_data["command"].replace( "/tmp", "/tmp/sandbox" ) return PermissionResultAllow(updated_input=sandboxed_input) return PermissionResultAllow(updated_input=input_data) ``` ```python canUseTool: async (toolName, input) => { if (toolName === "Bash") { // User approved, but scope all commands to sandbox const sandboxedInput = { ...input, command: input.command.replace("/tmp", "/tmp/sandbox") }; return { behavior: "allow", updatedInput: sandboxedInput }; } return { behavior: "allow", updatedInput: input }; }; ``` The user approves and doesn’t want to be asked again for this kind of call. The third callback argument carries `suggestions`, an array of ready-made [`PermissionUpdate`](/docs/en/agent-sdk/typescript#permissionupdate) entries. Echo one back in `updatedPermissions` to apply it. A suggestion with the `localSettings` destination writes the rule to `.claude/settings.local.json` so future sessions skip the prompt for matching calls.The Python example requires `claude-agent-sdk` 0.1.80 or later. Python TypeScript ```python async def can_use_tool(tool_name, input_data, context): choice = await ask_user(f"Allow {tool_name}?", ["once", "always", "no"]) if choice == "always": persist = [ s for s in context.suggestions if s.destination == "localSettings" ] return PermissionResultAllow( updated_input=input_data, updated_permissions=persist ) if choice == "once": return PermissionResultAllow(updated_input=input_data) return PermissionResultDeny(message="User declined") ``` ```python canUseTool: async (toolName, input, { suggestions = [] }) => { const choice = await askUser(`Allow ${toolName}?`, ["once", "always", "no"]); if (choice === "always") { const persist = suggestions.filter( (s) => s.destination === "localSettings" ); return { behavior: "allow", updatedInput: input, updatedPermissions: persist }; } if (choice === "once") { return { behavior: "allow", updatedInput: input }; } return { behavior: "deny", message: "User declined" }; }; ``` The user doesn’t want this action to happen. Block the tool and provide a message explaining why. Claude sees this message and may try a different approach. Python TypeScript ```python async def can_use_tool(tool_name, input_data, context): approved = await ask_user(f"Allow {tool_name}?") if not approved: return PermissionResultDeny(message="User rejected this action") return PermissionResultAllow(updated_input=input_data) ``` ```python canUseTool: async (toolName, input) => { const approved = await askUser(`Allow ${toolName}?`); if (!approved) { return { behavior: "deny", message: "User rejected this action" }; } return { behavior: "allow", updatedInput: input }; }; ``` The user doesn’t want this specific action, but has a different idea. Block the tool and include guidance in your message. Claude will read this and decide how to proceed based on your feedback. Python TypeScript ```python async def can_use_tool(tool_name, input_data, context): if tool_name == "Bash" and "rm" in input_data.get("command", ""): # User doesn't want to delete, suggest archiving instead return PermissionResultDeny( message="User doesn't want to delete files. They asked if you could compress them into an archive instead." ) return PermissionResultAllow(updated_input=input_data) ``` ```python canUseTool: async (toolName, input) => { if (toolName === "Bash" && input.command.includes("rm")) { // User doesn't want to delete, suggest archiving instead return { behavior: "deny", message: "User doesn't want to delete files. They asked if you could compress them into an archive instead." }; } return { behavior: "allow", updatedInput: input }; }; ``` For a complete change of direction (not just a nudge), use [streaming input](/docs/en/agent-sdk/streaming-vs-single-mode) to send Claude a new instruction directly. This bypasses the current tool request and gives Claude entirely new instructions to follow. [​](#handle-clarifying-questions) Handle clarifying questions When Claude needs more direction on a task with multiple valid approaches, it calls the `AskUserQuestion` tool. This triggers your `canUseTool` callback with `toolName` set to `AskUserQuestion`. The input contains Claude’s questions as multiple-choice options, which you display to the user and return their selections. Clarifying questions are especially common in [`plan` mode](/docs/en/agent-sdk/permissions#plan-mode-plan), where Claude explores the codebase and asks questions before proposing a plan. This makes plan mode ideal for interactive workflows where you want Claude to gather requirements before making changes. The following steps show how to handle clarifying questions: 1 Pass a canUseTool callback Pass a `canUseTool` callback in your query options. By default, `AskUserQuestion` is available. If you specify a `tools` array to restrict Claude’s capabilities (for example, a read-only agent with only `Read`, `Glob`, and `Grep`), include `AskUserQuestion` in that array. Otherwise, Claude won’t be able to ask clarifying questions: Python TypeScript ```python async for message in query( prompt="Analyze this codebase", options=ClaudeAgentOptions( # Include AskUserQuestion in your tools list tools=["Read", "Glob", "Grep", "AskUserQuestion"], can_use_tool=can_use_tool, ), ): print(message) ``` ```python for await (const message of query({ prompt: "Analyze this codebase", options: { // Include AskUserQuestion in your tools list tools: ["Read", "Glob", "Grep", "AskUserQuestion"], canUseTool: async (toolName, input) => { // Handle clarifying questions here } } })) { console.log(message); } ``` 2 Detect AskUserQuestion In your callback, check if `toolName` equals `AskUserQuestion` to handle it differently from other tools: Python TypeScript ```python async def can_use_tool(tool_name: str, input_data: dict, context): if tool_name == "AskUserQuestion": # Your implementation to collect answers from the user return await handle_clarifying_questions(input_data) # Handle other tools normally return await prompt_for_approval(tool_name, input_data) ``` ```python canUseTool: async (toolName, input) => { if (toolName === "AskUserQuestion") { // Your implementation to collect answers from the user return handleClarifyingQuestions(input); } // Handle other tools normally return promptForApproval(toolName, input); }; ``` 3 Parse the question input The input contains Claude’s questions in a `questions` array. Each question has a `question` (the text to display), `options` (the choices), and `multiSelect` (whether multiple selections are allowed): ```python { "questions": [ { "question": "How should I format the output?", "header": "Format", "options": [ { "label": "Summary", "description": "Brief overview" }, { "label": "Detailed", "description": "Full explanation" } ], "multiSelect": false }, { "question": "Which sections should I include?", "header": "Sections", "options": [ { "label": "Introduction", "description": "Opening context" }, { "label": "Conclusion", "description": "Final summary" } ], "multiSelect": true } ] } ``` See [Question format](#question-format) for full field descriptions. 4 Collect answers from the user Present the questions to the user and collect their selections. How you do this depends on your application: a terminal prompt, a web form, a mobile dialog, etc. 5 Return answers to Claude Build the `answers` object as a record where each key is the `question` text and each value is the selected option’s `label`: | From the question object | Use as | |--------------------------------------------------------------|--------| | `question` field (e.g., `"How should I format the output?"`) | Key | | Selected option’s `label` field (e.g., `"Summary"`) | Value | For multi-select questions, pass an array of labels or join them with `", "`. If you [support free-text input](#support-free-text-input), use the user’s custom text as the value. Python TypeScript ```python return PermissionResultAllow( updated_input={ "questions": input_data.get("questions", []), "answers": { "How should I format the output?": "Summary", "Which sections should I include?": ["Introduction", "Conclusion"], }, } ) ``` ```python return { behavior: "allow", updatedInput: { questions: input.questions, answers: { "How should I format the output?": "Summary", "Which sections should I include?": "Introduction, Conclusion" } } }; ``` [​](#question-format) Question format The input contains Claude’s generated questions in a `questions` array. Each question has these fields: | Field | Description | |---------------|----------------------------------------------------------------------------------------------------------------------------------------| | `question` | The full question text to display | | `header` | Short label for the question (max 12 characters) | | `options` | Array of 2-4 choices, each with `label` and `description`. TypeScript: optionally `preview` (see [below](#option-previews-typescript)) | | `multiSelect` | If `true`, users can select multiple options | The structure your callback receives: ```python { "questions": [ { "question": "How should I format the output?", "header": "Format", "options": [ { "label": "Summary", "description": "Brief overview of key points" }, { "label": "Detailed", "description": "Full explanation with examples" } ], "multiSelect": false } ] } ``` [​](#option-previews-typescript) Option previews (TypeScript) `toolConfig.askUserQuestion.previewFormat` adds a `preview` field to each option so your app can show a visual mockup alongside the label. Without this setting, Claude does not generate previews and the field is absent. | `previewFormat` | `preview` contains | |:----------------|:--------------------------------------------------------------------------------------------------------------| | unset (default) | Field is absent. Claude does not generate previews. | | `"markdown"` | ASCII art and fenced code blocks | | `"html"` | A styled `<div>` fragment (the SDK rejects `<script>`, `<style>`, and `<!DOCTYPE>` before your callback runs) | The format applies to all questions in the session. Claude includes `preview` on options where a visual comparison helps (layout choices, color schemes) and omits it where one wouldn’t (yes/no confirmations, text-only choices). Check for `undefined` before rendering. ```python import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Help me choose a card layout", options: { toolConfig: { askUserQuestion: { previewFormat: "html" } }, canUseTool: async (toolName, input) => { // input.questions[].options[].preview is an HTML string or undefined return { behavior: "allow", updatedInput: input }; } } })) { // ... } ``` An option with an HTML preview: ```python { "label": "Compact", "description": "Title and metric value only", "preview": "<div style=\"padding:12px;border:1px solid #ddd;border-radius:8px\"><div style=\"font-size:12px;color:#666\">Active users</div><div style=\"font-size:28px;font-weight:600\">1,284</div></div>" } ``` [​](#response-format) Response format Return an `answers` object mapping each question’s `question` field to the selected option’s `label`: | Field | Description | |-------------|--------------------------------------------------------------------------------------| | `questions` | Pass through the original questions array (required for tool processing) | | `answers` | Object where keys are question text and values are selected labels | | `response` | Optional freeform reply the user typed instead of answering the structured questions | For multi-select questions, pass an array of labels or join them with `", "`. For per-question free text such as an “Other” option, put the user’s text in `answers[question]` as shown in [Support free-text input](#support-free-text-input). Set `response` only when your UI lets the user dismiss the question card and type a general reply that isn’t an answer to any specific question. When `response` is set, Claude receives “The user responded: …” instead of the per-question answer list. ```python { "questions": [ // ... ], "answers": { "How should I format the output?": "Summary", "Which sections should I include?": ["Introduction", "Conclusion"] } } ``` [​](#support-free-text-input) Support free-text input Claude’s predefined options won’t always cover what users want. To let users type their own answer: - Display an additional “Other” choice after Claude’s options that accepts text input - Use the user’s custom text as the answer value (not the word “Other”) See the [complete example](#complete-example) below for a full implementation. [​](#complete-example) Complete example Claude asks clarifying questions when it needs user input to proceed. For example, when asked to help decide on a tech stack for a mobile app, Claude might ask about cross-platform vs native, backend preferences, or target platforms. These questions help Claude make decisions that match the user’s preferences rather than guessing. This example handles those questions in a terminal application. Here’s what happens at each step: 1. **Route the request**: The `canUseTool` callback checks if the tool name is `"AskUserQuestion"` and routes to a dedicated handler 2. **Display questions**: The handler loops through the `questions` array and prints each question with numbered options 3. **Collect input**: The user can enter a number to select an option, or type free text directly (e.g., “jquery”, “i don’t know”) 4. **Map answers**: The code checks if input is numeric (uses the option’s label) or free text (uses the text directly) 5. **Return to Claude**: The response includes both the original `questions` array and the `answers` mapping Save the TypeScript version as `ask.ts` and run it with `npx tsx ask.ts`, or save the Python version as `ask.py` and run it with `python ask.py`. Python TypeScript ```python import asyncio from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query from claude_agent_sdk.types import HookMatcher, PermissionResultAllow def parse_response(response: str, options: list) -> str: """Parse user input as option number(s) or free text.""" try: indices = [int(s.strip()) - 1 for s in response.split(",")] labels = [options[i]["label"] for i in indices if 0 <= i < len(options)] return ", ".join(labels) if labels else response except ValueError: return response async def handle_ask_user_question(input_data: dict) -> PermissionResultAllow: """Display Claude's questions and collect user answers.""" answers = {} for q in input_data.get("questions", []): print(f"\n{q['header']}: {q['question']}") options = q["options"] for i, opt in enumerate(options): print(f" {i + 1}. {opt['label']} - {opt['description']}") if q.get("multiSelect"): print(" (Enter numbers separated by commas, or type your own answer)") else: print(" (Enter a number, or type your own answer)") response = input("Your choice: ").strip() answers[q["question"]] = parse_response(response, options) return PermissionResultAllow( updated_input={ "questions": input_data.get("questions", []), "answers": answers, } ) async def can_use_tool( tool_name: str, input_data: dict, context ) -> PermissionResultAllow: # Route AskUserQuestion to our question handler if tool_name == "AskUserQuestion": return await handle_ask_user_question(input_data) # Auto-approve other tools for this example return PermissionResultAllow(updated_input=input_data) async def prompt_stream(): yield { "type": "user", "message": { "role": "user", "content": "Help me decide on the tech stack for a new mobile app", }, } # Required workaround: dummy hook keeps the stream open for can_use_tool async def dummy_hook(input_data, tool_use_id, context): return {"continue_": True} async def main(): async for message in query( prompt=prompt_stream(), options=ClaudeAgentOptions( can_use_tool=can_use_tool, hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]}, ), ): if isinstance(message, ResultMessage) and message.subtype == "success": print(message.result) asyncio.run(main()) ``` ```python import { query } from "@anthropic-ai/claude-agent-sdk"; import * as readline from "readline/promises"; // Helper to prompt user for input in the terminal async function prompt(question: string): Promise<string> { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); const answer = await rl.question(question); rl.close(); return answer; } // Parse user input as option number(s) or free text function parseResponse(response: string, options: any[]): string { const indices = response.split(",").map((s) => parseInt(s.trim()) - 1); const labels = indices .filter((i) => !isNaN(i) && i >= 0 && i < options.length) .map((i) => options[i].label); return labels.length > 0 ? labels.join(", ") : response; } // Display Claude's questions and collect user answers async function handleAskUserQuestion(input: any) { const answers: Record<string, string> = {}; for (const q of input.questions) { console.log(`\n${q.header}: ${q.question}`); const options = q.options; options.forEach((opt: any, i: number) => { console.log(` ${i + 1}. ${opt.label} - ${opt.description}`); }); if (q.multiSelect) { console.log(" (Enter numbers separated by commas, or type your own answer)"); } else { console.log(" (Enter a number, or type your own answer)"); } const response = (await prompt("Your choice: ")).trim(); answers[q.question] = parseResponse(response, options); } // Return the answers to Claude (must include original questions) return { behavior: "allow", updatedInput: { questions: input.questions, answers } }; } async function main() { for await (const message of query({ prompt: "Help me decide on the tech stack for a new mobile app", options: { canUseTool: async (toolName, input) => { // Route AskUserQuestion to our question handler if (toolName === "AskUserQuestion") { return handleAskUserQuestion(input); } // Auto-approve other tools for this example return { behavior: "allow", updatedInput: input }; } } })) { if ("result" in message) console.log(message.result); } } main(); ``` [​](#limitations) Limitations - **Subagents**: `AskUserQuestion` is not currently available in subagents spawned via the Agent tool - **Question limits**: each `AskUserQuestion` call supports 1-4 questions with 2-4 options each [​](#other-ways-to-get-user-input) Other ways to get user input The `canUseTool` callback and `AskUserQuestion` tool cover most approval and clarification scenarios, but the SDK offers other ways to get input from users: [​](#streaming-input) Streaming input Use [streaming input](/docs/en/agent-sdk/streaming-vs-single-mode) when you need to: - **Interrupt the agent mid-task**: send a cancel signal or change direction while Claude is working - **Provide additional context**: add information Claude needs without waiting for it to ask - **Build chat interfaces**: let users send follow-up messages during long-running operations Streaming input is ideal for conversational UIs where users interact with the agent throughout execution, not just at approval checkpoints. [​](#custom-tools) Custom tools Use [custom tools](/docs/en/agent-sdk/custom-tools) when you need to: - **Collect structured input**: build forms, wizards, or multi-step workflows that go beyond `AskUserQuestion`’s multiple-choice format - **Integrate external approval systems**: connect to existing ticketing, workflow, or approval platforms - **Implement domain-specific interactions**: create tools tailored to your application’s needs, like code review interfaces or deployment checklists Custom tools give you full control over the interaction, but require more implementation work than using the built-in `canUseTool` callback. [​](#related-resources) Related resources - [Configure permissions](/docs/en/agent-sdk/permissions): set up permission modes and rules - [Control execution with hooks](/docs/en/agent-sdk/hooks): run custom code at key points in the agent lifecycle - [TypeScript SDK reference](/docs/en/agent-sdk/typescript#canusetool): full canUseTool API documentation --- ## hosting-the-agent-sdk-claude-code-docs-3666f01f83.md ## On this page - [The subprocess model](#the-subprocess-model) - [State that lives on local disk](#state-that-lives-on-local-disk) - [Choose a session pattern](#choose-a-session-pattern) - [Ephemeral sessions](#ephemeral-sessions) - [Long-running sessions](#long-running-sessions) - [Hybrid sessions](#hybrid-sessions) - [Multi-agent container](#multi-agent-container) - [Provision the container](#provision-the-container) - [Container-based sandboxing](#container-based-sandboxing) - [Runtime dependencies](#runtime-dependencies) - [Resources](#resources) - [Network](#network) - [Handle production concerns](#handle-production-concerns) - [Session and state persistence](#session-and-state-persistence) - [Observability](#observability) - [Auth and secrets](#auth-and-secrets) - [Scaling and concurrency](#scaling-and-concurrency) - [Cost](#cost) - [Multi-tenant isolation](#multi-tenant-isolation) - [Known limitations](#known-limitations) - [Next steps](#next-steps) Deployment # Hosting the Agent SDK Copy pageCopy page Deploy the Agent SDK in production: subprocess architecture, session persistence, scaling, observability, and multi-tenant isolation for Docker, Kubernetes, and sandbox providers. Copy pageCopy page The Agent SDK spawns and supervises a `claude` CLI subprocess that owns a shell, a working directory, and session files on disk. Hosting it is not like hosting a stateless API wrapper. Every running agent is a long-lived process tied to local state, which shapes how you allocate resources, persist sessions, and scale across tenants. This page covers self-hosting on your own infrastructure: understand [the subprocess model](#the-subprocess-model), [choose a session pattern](#choose-a-session-pattern), [provision the container](#provision-the-container), and [handle production concerns](#handle-production-concerns) like persistence, observability, auth, and multi-tenant isolation. For deployable Dockerfiles and Kubernetes manifests, see the [hosting cookbook](https://github.com/anthropics/claude-cookbooks/tree/main/claude_agent_sdk/hosting). If you do not need infrastructure control, custom isolation, or your own data plane, consider [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) instead: a hosted REST API where Anthropic runs the agent and the sandbox, so your application sends events and streams back results with no hosting infrastructure to operate. For security hardening beyond basic sandboxing, including network controls, credential management, and isolation options, see [Secure Deployment](/docs/en/agent-sdk/secure-deployment). [​](#the-subprocess-model) The subprocess model Every hosting decision on this page follows from how the SDK runs the agent. When your code calls `query()`, the SDK spawns a separate `claude` CLI process and talks to it over stdio. That subprocess owns the shell, the working directory, and the JSONL session transcripts on local disk. One agent session maps to one subprocess. Running N concurrent sessions means N subprocesses, each with its own process tree and transcript file. By default they all inherit your application’s working directory, so pass `cwd` on each `query()` call when sessions need separate filesystems: TypeScript Python ```python query({ prompt, options: { cwd: "/work/session-a" } }) ``` ```python query(prompt=prompt, options=ClaudeAgentOptions(cwd="/work/session-a")) ``` [​](#state-that-lives-on-local-disk) State that lives on local disk Three kinds of agent state live on the container’s filesystem by default. None of them survive a container restart, a scale-down, or a move to a different node. | State | Default location | |-----------------------------|--------------------------------------------------------------------------------------------------| | Session transcripts | `~/.claude/projects/`, or the `projects/` directory under `CLAUDE_CONFIG_DIR` if set | | `CLAUDE.md` memory files | `~/.claude/CLAUDE.md` for the user tier and the session’s working directory for the project tier | | Working-directory artifacts | The session’s working directory | To persist transcripts across hosts, configure a [`SessionStore` adapter](/docs/en/agent-sdk/session-storage). Memory files and other working-directory artifacts need their own storage strategy, such as a mounted volume or an object-store sync. For how sessions, resumption, and forking work at the API level, see [Sessions](/docs/en/agent-sdk/sessions). [​](#choose-a-session-pattern) Choose a session pattern These four patterns cover session lifecycle: how long a container lives relative to the sessions it serves. For where the container runs, the [hosting cookbook](https://github.com/anthropics/claude-cookbooks/blob/main/claude_agent_sdk/07_Hosting_the_agent.ipynb) has [deployable code](https://github.com/anthropics/claude-cookbooks/tree/main/claude_agent_sdk/hosting) for local Docker, Modal, and Kubernetes. Choose a session pattern here and a deployment target from the cookbook. [​](#ephemeral-sessions) Ephemeral sessions Create a container for each user task and destroy it when the task completes. Best for one-off tasks. The user may still interact with the AI while the task is completing, but once completed the container is destroyed. Example workloads include bug investigation and fix, invoice and receipt extraction, document translation, and media transformation. The container runs a one-shot entrypoint that calls the SDK and exits. In TypeScript, save the file as `entrypoint.mts` or set `"type": "module"` in `package.json` so top-level `await` is available. TypeScript Python ```python import { query } from "@anthropic-ai/claude-agent-sdk"; const prompt = process.env.TASK_PROMPT!; for await (const message of query({ prompt, options: { maxTurns: 20 } })) { console.log(message); } ``` ```python import asyncio import os from claude_agent_sdk import ClaudeAgentOptions, query async def main(): async for message in query( prompt=os.environ["TASK_PROMPT"], options=ClaudeAgentOptions(max_turns=20), ): print(message) asyncio.run(main()) ``` [​](#long-running-sessions) Long-running sessions Run persistent container instances, often hosting multiple SDK processes per container, to serve ongoing work. Best for agents that take autonomous action, serve content, or handle high-volume message streams. Example workloads include an email agent that triages and responds to incoming mail, a site builder that hosts a per-user editable site through container ports, and a chat bot that handles continuous traffic from a platform like Slack. The container exposes an HTTP or WebSocket endpoint and maps each active session to a long-lived query and the subprocess behind it. In TypeScript, use [`streamInput()`](/docs/en/agent-sdk/typescript#query-object) to add turns to an active session and [`startup()`](/docs/en/agent-sdk/typescript#startup) to pre-warm subprocesses ahead of incoming traffic. In Python, use [`ClaudeSDKClient`](/docs/en/agent-sdk/python#claudesdkclient) to hold a session open across turns. Size the container so it can hold the maximum number of concurrent sessions in memory. [​](#hybrid-sessions) Hybrid sessions Ephemeral containers that hydrate from a [`SessionStore`](/docs/en/agent-sdk/session-storage) on startup and persist updates back. Best for sessions that span many interactions but sit idle between them. The container spins down during idle periods and spins back up when the user returns. Example workloads include a personal project manager with intermittent check-ins, deep research that pauses and resumes over hours, and a customer support agent that loads ticket history across interactions. Tune your provider’s idle timeout to how frequently you expect users to return. Shutting a container down without a `SessionStore` configured loses the transcript with it, so the store is required for this pattern, not optional. The pattern hinges on resuming a session by ID with a shared store attached: TypeScript Python ```python import { query, type SessionStore } from "@anthropic-ai/claude-agent-sdk"; declare const userInput: string; declare const sessionId: string; // looked up from your database by user declare const sessionStore: SessionStore; // S3, Redis, Postgres, or your own adapter for await (const message of query({ prompt: userInput, options: { resume: sessionId, sessionStore }, })) { // ... } ``` ```python from claude_agent_sdk import query, ClaudeAgentOptions, SessionStore import asyncio user_input: str = ... session_id: str = ... # looked up from your database by user session_store: SessionStore = ... # S3, Redis, Postgres, or your own adapter async def main(): async for message in query( prompt=user_input, options=ClaudeAgentOptions( resume=session_id, session_store=session_store, ), ): ... asyncio.run(main()) ``` See [Session storage](/docs/en/agent-sdk/session-storage) for the full `SessionStore` interface and reference adapters. [​](#multi-agent-container) Multi-agent container Run multiple SDK subprocesses inside one container. Best for agents that must collaborate closely, for example multi-agent simulations where the agents interact with each other in a shared environment. Give each agent its own working directory so they do not overwrite each other’s files, and isolate settings loading so per-agent `CLAUDE.md` files do not leak across agents. See [Multi-tenant isolation](#multi-tenant-isolation) for the specific options. [​](#provision-the-container) Provision the container [​](#container-based-sandboxing) Container-based sandboxing Run the SDK inside a sandboxed container for process isolation, resource limits, network control, and an ephemeral filesystem. Several providers specialize in sandboxed container environments that fit the Agent SDK’s model. Questions to answer when choosing a provider: - **Who runs the sandbox**: a sandbox-as-a-service provider operates the infrastructure for you, while self-hosted options give you software to run on your own. - **Cold-start latency**: how long from “create a sandbox” to “ready to accept the first request.” Ephemeral patterns need sub-second starts. Long-running patterns tolerate more. - **Persistent storage**: whether the provider offers durable volumes or only ephemeral disk. The hybrid pattern needs durable storage somewhere, whether in the sandbox or alongside it. - **Pricing model**: per-second, per-request, or flat hourly billing. Per-second pricing suits bursty ephemeral workloads. Hourly suits long-running sessions. - **Networking**: support for custom egress rules, outbound proxies, and private VPC peering for regulated environments. Providers to evaluate: - [Modal Sandbox](https://modal.com/docs/guide/sandbox), with a [demo implementation](https://modal.com/docs/examples/claude-slack-gif-creator) - [Cloudflare Sandboxes](https://github.com/cloudflare/sandbox-sdk) - [Daytona](https://www.daytona.io/) - [E2B](https://e2b.dev/) - [Fly Machines](https://fly.io/docs/machines/) - [Vercel Sandbox](https://vercel.com/docs/functions/sandbox) For self-hosted options such as Docker, gVisor, and Firecracker, and detailed isolation configuration, see [Isolation Technologies](/docs/en/agent-sdk/secure-deployment#isolation-technologies). [​](#runtime-dependencies) Runtime dependencies The container needs only your SDK’s language runtime: - Python 3.10+ for the Python SDK, or Node.js 18+ for the TypeScript SDK - Both SDK packages bundle a native Claude Code binary for the host platform, so no separate Claude Code or Node.js install is needed for the spawned CLI The bundled binary is pinned to the SDK package version, so updating the SDK is how you update the CLI. The SDK follows semver: take patch releases continuously and review the [TypeScript](https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md) or [Python](https://github.com/anthropics/claude-agent-sdk-python/blob/main/CHANGELOG.md) changelog before taking a minor. [​](#resources) Resources 1 GiB RAM, 5 GiB disk, and 1 CPU per agent is a reasonable starting point for a freshly started instance. Memory usage grows with session length and tool activity, so size for the session lengths and concurrency you actually need rather than the idle baseline. See [Scaling and concurrency](#scaling-and-concurrency) for how to work out agents per host. [​](#network) Network The SDK needs outbound HTTPS to `api.anthropic.com`, or to your provider’s regional endpoint when running on Amazon Bedrock or Google Cloud’s Agent Platform. If your agents use [MCP servers](/docs/en/agent-sdk/mcp) or external tools, they need outbound access to those endpoints as well. For production, route outbound traffic through an egress proxy that enforces domain allowlists, injects credentials, and logs requests. See [Secure Deployment](/docs/en/agent-sdk/secure-deployment) for the full pattern. For inbound traffic, expose an HTTP or WebSocket port on the container. Your application handles client requests on that port and calls the SDK internally; the subprocess itself does not listen on the network. [​](#handle-production-concerns) Handle production concerns Work through these decisions before shipping a self-hosted agent. [​](#session-and-state-persistence) Session and state persistence Default local disk is lost on restart, scale-down, or a move to a different node. For any session a user expects to resume, mirror the transcript to durable storage with a [`SessionStore` adapter](/docs/en/agent-sdk/session-storage). See [Reference implementations](/docs/en/agent-sdk/session-storage#reference-implementations) for S3, Redis, and Postgres adapters and a conformance suite for your own. Three things to know about how `SessionStore` behaves: - **Transcripts only**: `SessionStore` mirrors transcripts, not `CLAUDE.md` memory files or other working-directory artifacts. Mount a shared volume or sync those separately. - **Mirror, not replacement**: the subprocess writes to local disk first, and the store receives a copy of each batch. Local writes remain authoritative. - **`mirror_error` messages**: a batch the store rejects is sent up to three times in total, with a short backoff before each retry; a timed-out call isn’t retried. If the batch still fails, the SDK drops it, emits a `{ type: "system", subtype: "mirror_error" }` message, and continues the query. Alert on these if store durability matters. [​](#observability) Observability Agent SDK agents are long-lived processes that spawn tool calls across many API round-trips. Without telemetry you cannot see which tools ran, how long they took, or where a session stalled. The SDK inherits OpenTelemetry configuration from the environment. Set the OTEL environment variables at the container or orchestrator level so every `query()` call exports spans, metrics, and log events to your collector. The example below enables OTLP export for all three signals. `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` is required only for traces; omit it if you export metrics and logs alone. .env ```python CLAUDE_CODE_ENABLE_TELEMETRY=1 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 OTEL_TRACES_EXPORTER=otlp OTEL_METRICS_EXPORTER=otlp OTEL_LOGS_EXPORTER=otlp OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4318 ``` Prompt text and tool inputs are not included in exports by default. See [Control sensitive data in exports](/docs/en/agent-sdk/observability#control-sensitive-data-in-exports) for the opt-in flags, and [Observability](/docs/en/agent-sdk/observability) for the full signal catalog. [​](#auth-and-secrets) Auth and secrets Three auth concerns matter at hosting time: - **Anthropic API**: the subprocess reads `ANTHROPIC_API_KEY` from its environment. Supply it from your secret manager, or set `ANTHROPIC_BASE_URL` to route model calls through a proxy that injects the key outside the container. See [Credential management](/docs/en/agent-sdk/secure-deployment#credential-management) for the proxy pattern and [Setup in the SDK quickstart](/docs/en/agent-sdk/quickstart#setup) for supported authentication methods. - **Inbound**: put authentication at a gateway in front of the agent container. The agent should receive pre-authenticated requests and should not be the component that validates user tokens. - **Outbound tools**: keep tool credentials out of the agent environment. Route outbound calls through a proxy that injects API keys after the request leaves the container. The agent makes the call; the proxy adds the credential. [​](#scaling-and-concurrency) Scaling and concurrency Each session runs in its own subprocess, so concurrency on a host is bounded by how many subprocesses its RAM can hold. Size each host with this formula: ```python agents per host = (host RAM - overhead) / (per-session RAM ceiling) ``` Measure the per-session ceiling by running a representative session to your target length under your expected tool load and recording peak RSS. The 1 GiB starting point in [Resources](#resources) is a floor, not the ceiling. Horizontal-scale routing depends on your pattern. For long-running sessions, where containers hold many sessions, run a pool of containers behind a load balancer and pin each session to one container using consistent hashing on `sessionId`. A pinned session keeps hitting the same container, and therefore the same running subprocess, until it is evicted or the container restarts. Large fanouts of concurrent [subagents](/docs/en/agent-sdk/subagents) from a single session can hit API rate limits. Break the work into smaller batches rather than issuing one wide dispatch. [​](#cost) Cost Anthropic token cost typically dominates container infrastructure cost by an order of magnitude or more. A minimally provisioned container runs roughly \$0.05 per hour, while a single long agent session can spend dollars in tokens. See [Cost tracking](/docs/en/agent-sdk/cost-tracking) for per-session token accounting. [​](#multi-tenant-isolation) Multi-tenant isolation Default SDK behavior reads settings and `CLAUDE.md` memory files from the filesystem. In a shared container that serves multiple tenants, those files can leak one tenant’s context into another tenant’s session. To isolate tenants inside a shared container: - Pass `settingSources: []` in TypeScript or `setting_sources=[]` in Python so no filesystem settings load. - Set `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` in `env`. [Auto memory](/docs/en/memory#auto-memory) at `~/.claude/projects/<project>/memory/` loads into the system prompt regardless of `settingSources`. See [What settingSources does not control](/docs/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) for the other inputs that load unconditionally. - Point `CLAUDE_CONFIG_DIR` at a per-tenant directory so tenants do not share the `~/.claude.json` global config. - Use a per-tenant working directory. Pass `cwd` explicitly on every `query()` call. - Apply per-tenant egress rules at your proxy, such as distinct outbound IPs, credentials, or domain allowlists, so a compromised tenant cannot exfiltrate data via another tenant’s outbound policy. The example below applies the four SDK-level options together. Construct `tenantDir` and `configDir` so each tenant gets a path no other tenant can read. In TypeScript, `env` replaces the subprocess environment, so spread `...process.env` to keep inherited variables like `PATH` and `ANTHROPIC_API_KEY`. In Python, `env` is merged on top of the inherited environment. TypeScript Python ```python import { query } from "@anthropic-ai/claude-agent-sdk"; declare const prompt: string; declare const tenantDir: string; declare const configDir: string; for await (const message of query({ prompt, options: { cwd: tenantDir, settingSources: [], env: { ...process.env, CLAUDE_CONFIG_DIR: configDir, CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1", }, }, })) { // ... } ``` ```python from claude_agent_sdk import query, ClaudeAgentOptions import asyncio prompt: str = ... tenant_dir: str = ... config_dir: str = ... async def main(): async for message in query( prompt=prompt, options=ClaudeAgentOptions( cwd=tenant_dir, setting_sources=[], env={ "CLAUDE_CONFIG_DIR": config_dir, "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1", }, ), ): ... asyncio.run(main()) ``` For per-tenant network controls, see [Secure Deployment](/docs/en/agent-sdk/secure-deployment). [​](#known-limitations) Known limitations Plan around these in your deployment design. | Limitation | What to do | |-----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | No top-level session timeout | A session does not time out on its own. Set `maxTurns` in `Options` to bound how many tool-use round trips the agent takes before stopping. | | Memory growth over long sessions | Cap session length or recycle subprocesses periodically. See [Scaling and concurrency](#scaling-and-concurrency). | | Large parallel-subagent fanouts can hit rate limits | Break work into smaller batches rather than issuing one wide dispatch. | | No per-subagent wall-clock deadline | Cap each [subagent](/docs/en/agent-sdk/subagents) with `maxTurns` in its `AgentDefinition`. For background subagents only, `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` sets a stall watchdog that fires when a `run_in_background` subagent stops producing output; it is not a total-runtime deadline. | [​](#next-steps) Next steps - [Hosting cookbook](https://github.com/anthropics/claude-cookbooks/blob/main/claude_agent_sdk/07_Hosting_the_agent.ipynb): notebook walkthrough with [deployable code](https://github.com/anthropics/claude-cookbooks/tree/main/claude_agent_sdk/hosting) for Docker, Modal, and Kubernetes. - [Session storage](/docs/en/agent-sdk/session-storage): persist transcripts across hosts with a `SessionStore` adapter. - [Observability](/docs/en/agent-sdk/observability): export OTEL traces, metrics, and logs to your collector. - [Secure deployment](/docs/en/agent-sdk/secure-deployment): network controls, credential management, and isolation hardening. - [Cost tracking](/docs/en/agent-sdk/cost-tracking): per-session token and cost accounting. --- ## how-the-agent-loop-works-claude-code-docs-b174364e9e.md ## On this page - [The loop at a glance](#the-loop-at-a-glance) - [Turns and messages](#turns-and-messages) - [Message types](#message-types) - [Handle messages](#handle-messages) - [Tool execution](#tool-execution) - [Built-in tools](#built-in-tools) - [Tool permissions](#tool-permissions) - [Parallel tool execution](#parallel-tool-execution) - [Control how the loop runs](#control-how-the-loop-runs) - [Turns and budget](#turns-and-budget) - [Effort level](#effort-level) - [Permission mode](#permission-mode) - [Model](#model) - [The context window](#the-context-window) - [What consumes context](#what-consumes-context) - [Automatic compaction](#automatic-compaction) - [Keep context efficient](#keep-context-efficient) - [Sessions and continuity](#sessions-and-continuity) - [Handle the result](#handle-the-result) - [Hooks](#hooks) - [Put it all together](#put-it-all-together) - [Next steps](#next-steps) Core concepts # How the agent loop works Copy pageCopy page Understand the message lifecycle, tool execution, context window, and architecture that power your SDK agents. Copy pageCopy page The Agent SDK lets you embed Claude Code’s autonomous agent loop in your own applications. The SDK is a standalone package that gives you programmatic control over tools, permissions, cost limits, and output. You don’t need the Claude Code CLI installed to use it. When you start an agent, the SDK runs the same [execution loop that powers Claude Code](/docs/en/how-claude-code-works#the-agentic-loop): Claude evaluates your prompt, calls tools to take action, receives the results, and repeats until the task is complete. This page explains what happens inside that loop so you can build, debug, and optimize your agents effectively. [​](#the-loop-at-a-glance) The loop at a glance Every agent session follows the same cycle: 1. **Receive prompt.** Claude receives your prompt, along with the system prompt, tool definitions, and conversation history. The SDK yields a [`SystemMessage`](#message-types) with subtype `"init"` containing session metadata. 2. **Evaluate and respond.** Claude evaluates the current state and determines how to proceed. It may respond with text, request one or more tool calls, or both. The SDK yields an [`AssistantMessage`](#message-types) containing the text and any tool call requests. 3. **Execute tools.** The SDK runs each requested tool and collects the results. Each set of tool results feeds back to Claude for the next decision. You can use [hooks](/docs/en/agent-sdk/hooks) to intercept, modify, or block tool calls before they run. 4. **Repeat.** Steps 2 and 3 repeat as a cycle. Each full cycle is one turn. Claude continues calling tools and processing results until it produces a response with no tool calls. 5. **Return result.** The SDK yields a final [`AssistantMessage`](#message-types) with the text response (no tool calls), followed by a [`ResultMessage`](#message-types) with the final text, token usage, cost, and session ID. A quick question (“what files are here?”) might take one or two turns of calling `Glob` and responding with the results. A complex task (“refactor the auth module and update the tests”) can chain dozens of tool calls across many turns, reading files, editing code, and running tests, with Claude adjusting its approach based on each result. [​](#turns-and-messages) Turns and messages A turn is one round trip inside the loop: Claude produces output that includes tool calls, the SDK executes those tools, and the results feed back to Claude automatically. This happens without yielding control back to your code. Turns continue until Claude produces output with no tool calls, at which point the loop ends and the final result is delivered. Consider what a full session might look like for the prompt “Fix the failing tests in auth.ts”. First, the SDK sends your prompt to Claude and yields a [`SystemMessage`](#message-types) with the session metadata. Then the loop begins: 1. **Turn 1:** Claude calls `Bash` to run `npm test`. The SDK yields an [`AssistantMessage`](#message-types) with the tool call, executes the command, then yields a [`UserMessage`](#message-types) with the output (three failures). 2. **Turn 2:** Claude calls `Read` on `auth.ts` and `auth.test.ts`. The SDK returns the file contents and yields an `AssistantMessage`. 3. **Turn 3:** Claude calls `Edit` to fix `auth.ts`, then calls `Bash` to re-run `npm test`. All three tests pass. The SDK yields an `AssistantMessage`. 4. **Final turn:** Claude produces a text-only response with no tool calls: “Fixed the auth bug, all three tests pass now.” The SDK yields a final `AssistantMessage` with this text, then a [`ResultMessage`](#message-types) with the same text plus cost and usage. That was four turns: three with tool calls, one final text-only response. You can cap the loop with `max_turns` / `maxTurns`, which counts tool-use turns only. For example, `max_turns=2` in the loop above would have stopped before the edit step. You can also use `max_budget_usd` / `maxBudgetUsd` to cap turns based on a spend threshold. Without limits, the loop runs until Claude finishes on its own, which is fine for well-scoped tasks but can run long on open-ended prompts (“improve this codebase”). Setting a budget is a good default for production agents. See [Turns and budget](#turns-and-budget) below for the option reference. [​](#message-types) Message types As the loop runs, the SDK yields a stream of messages. Each message carries a type that tells you what stage of the loop it came from. The five core types are: - **`SystemMessage`:** session lifecycle events. The `subtype` field distinguishes them: - `"init"`: session metadata for the run. When a `SessionStart` or `Setup` hook runs during session startup, its [hook lifecycle messages](/docs/en/agent-sdk/typescript#sdkhookstartedmessage) arrive before the `init` message - `"compact_boundary"`: fires after [compaction](#automatic-compaction) - `"informational"`: plain-text status banners from the loop - `"worker_shutting_down"`: the loop will end after the current turn because the host is exiting or Remote Control disconnected In TypeScript, each subtype other than `"init"` is its own type in the [`SDKMessage` union](/docs/en/agent-sdk/typescript#sdkmessage) rather than a subtype of `SDKSystemMessage`. - **`AssistantMessage`:** emitted after each Claude response, including the final text-only one. Contains text content blocks and tool call blocks from that turn. - **`UserMessage`:** emitted after each tool execution with the tool result content sent back to Claude. Also emitted for any user inputs you stream mid-loop. - **`StreamEvent`:** only emitted when partial messages are enabled. Contains raw API streaming events (text deltas, tool input chunks). See [Stream responses](/docs/en/agent-sdk/streaming-output). - **`ResultMessage`:** marks the end of the agent loop. Contains the final text result, token usage, cost, and session ID. Check the `subtype` field to determine whether the task succeeded or hit a limit. A small number of trailing system events, such as `prompt_suggestion`, can arrive after it, so iterate the stream to completion rather than breaking on the result. See [Handle the result](#handle-the-result). These five types cover the full agent loop lifecycle. Both SDKs also yield observability events such as rate-limit status and task notifications that are not required to drive the loop. See the [Python message types reference](/docs/en/agent-sdk/python#message-types) and [TypeScript message types reference](/docs/en/agent-sdk/typescript#message-types) for the complete lists. [​](#handle-messages) Handle messages Which messages you handle depends on what you’re building: - **Final results only:** handle `ResultMessage` to get the output, cost, and whether the task succeeded or hit a limit. - **Progress updates:** handle `AssistantMessage` to see what Claude is doing each turn, including which tools it called. - **Live streaming:** enable partial messages (`include_partial_messages` in Python, `includePartialMessages` in TypeScript) to get `StreamEvent` messages in real time. See [Stream responses in real-time](/docs/en/agent-sdk/streaming-output). How you check message types depends on the SDK: - **Python:** check message types with `isinstance()` against classes imported from `claude_agent_sdk` (for example, `isinstance(message, ResultMessage)`). - **TypeScript:** check the `type` string field (for example, `message.type === "result"`). `AssistantMessage` and `UserMessage` wrap the raw API message in a `.message` field, so content blocks are at `message.message.content`, not `message.content`. Example: Check message types and handle results Python TypeScript ```python import asyncio from claude_agent_sdk import query, AssistantMessage, ResultMessage async def main(): try: async for message in query(prompt="Summarize this project"): if isinstance(message, AssistantMessage): print(f"Turn completed: {len(message.content)} content blocks") if isinstance(message, ResultMessage): if message.subtype == "success": print(message.result) else: print(f"Stopped: {message.subtype}") except Exception as error: # A single-shot query() raises after yielding an error result. If the # failure was an error result, the error subtype branches above have # already run; connection or process failures yield no result message. print(f"Session ended with an error: {error}") asyncio.run(main()) ``` ```python import { query } from "@anthropic-ai/claude-agent-sdk"; try { for await (const message of query({ prompt: "Summarize this project" })) { if (message.type === "assistant") { console.log(`Turn completed: ${message.message.content.length} content blocks`); } if (message.type === "result") { if (message.subtype === "success") { console.log(message.result); } else { console.log(`Stopped: ${message.subtype}`); } } } } catch (error) { // A single-shot query() throws after yielding an error result. If the // failure was an error result, the error subtype branches above have // already run; connection or process failures yield no result message. console.log(`Session ended with an error: ${error}`); } ``` [​](#tool-execution) Tool execution Tools give your agent the ability to take action. Without tools, Claude can only respond with text. With tools, Claude can read files, run commands, search code, and interact with external services. [​](#built-in-tools) Built-in tools The SDK includes the same tools that power Claude Code: | Category | Tools | What they do | |:--------------------|:----------------------------------------------------------------|:----------------------------------------------------------------------------| | **File operations** | `Read`, `Edit`, `Write` | Read, modify, and create files | | **Search** | `Glob`, `Grep` | Find files by pattern, search content with regex | | **Execution** | `Bash` | Run shell commands, scripts, git operations | | **Web** | `WebSearch`, `WebFetch` | Search the web, fetch and parse pages | | **Discovery** | `ToolSearch` | Dynamically find and load tools on-demand instead of preloading all of them | | **Orchestration** | `Agent`, `Skill`, `AskUserQuestion`, `TaskCreate`, `TaskUpdate` | Spawn subagents, invoke skills, ask the user, track tasks | Beyond built-in tools, you can: - **Connect external services** with [MCP servers](/docs/en/agent-sdk/mcp) (databases, browsers, APIs) - **Define custom tools** with [custom tool handlers](/docs/en/agent-sdk/custom-tools) - **Load project skills** via [setting sources](/docs/en/agent-sdk/claude-code-features) for reusable workflows [​](#tool-permissions) Tool permissions Claude determines which tools to call based on the task, but you control whether those calls are allowed to execute. You can auto-approve specific tools, block others entirely, or require approval for everything. Three options work together to determine what runs: - **`allowed_tools` / `allowedTools`** auto-approves listed tools. A read-only agent with `["Read", "Glob", "Grep"]` in its allowed tools list runs those tools without prompting. Tools not listed are still available but require permission. - **`disallowed_tools` / `disallowedTools`** blocks listed tools, regardless of other settings. See [Permissions](/docs/en/agent-sdk/permissions) for the order that rules are checked before a tool runs. - **`permission_mode` / `permissionMode`** controls what happens to tools that aren’t covered by allow or deny rules. See [Permission mode](#permission-mode) for available modes. You can also scope individual tools with rules like `"Bash(npm *)"` to allow only specific commands. See [Permissions](/docs/en/agent-sdk/permissions) for the full rule syntax. When a tool is denied, Claude receives a rejection message as the tool result and typically attempts a different approach or reports that it couldn’t proceed. [​](#parallel-tool-execution) Parallel tool execution When Claude requests multiple tool calls in a single turn, both SDKs can run them concurrently or sequentially depending on the tool. Read-only tools (like `Read`, `Glob`, `Grep`, and MCP tools marked as read-only) can run concurrently. Tools that modify state (like `Edit`, `Write`, and `Bash`) run sequentially to avoid conflicts. Custom tools default to sequential execution. To enable parallel execution for a custom tool, set `readOnlyHint` in its annotations. Both the [TypeScript](/docs/en/agent-sdk/typescript#tool) and [Python](/docs/en/agent-sdk/python#tool) SDKs use this field name from the MCP SDK. [​](#control-how-the-loop-runs) Control how the loop runs You can limit how many turns the loop takes, how much it costs, how deeply Claude reasons, and whether tools require approval before running. All of these are fields on [`ClaudeAgentOptions`](/docs/en/agent-sdk/python#claudeagentoptions) (Python) / [`Options`](/docs/en/agent-sdk/typescript#options) (TypeScript). [​](#turns-and-budget) Turns and budget | Option | What it controls | Default | |:-----------------------------------------------|:-----------------------------|:---------| | Max turns (`max_turns` / `maxTurns`) | Maximum tool-use round trips | No limit | | Max budget (`max_budget_usd` / `maxBudgetUsd`) | Maximum cost before stopping | No limit | When either limit is hit, the SDK returns a `ResultMessage` with a corresponding error subtype (`error_max_turns` or `error_max_budget_usd`). See [Handle the result](#handle-the-result) for how to check these subtypes and [`ClaudeAgentOptions`](/docs/en/agent-sdk/python#claudeagentoptions) / [`Options`](/docs/en/agent-sdk/typescript#options) for syntax. The budget cap covers [subagents](/docs/en/agent-sdk/subagents): their spend counts toward the total. Once spend reaches the cap, spawning another subagent fails with `Budget limit reached`, and Claude Code stops any background subagents still running. The cap-enforcement behaviors require Claude Code v2.1.217 or later. With [streaming input](/docs/en/agent-sdk/streaming-vs-single-mode), a message you send while a turn is still running stays queued when that turn ends at the max-turns limit, and it starts its own turn with its own max-turns limit. Before v2.1.205, a message that arrived on the turn’s final iteration could be consumed into the ending turn and lost without ever reaching the model. [​](#effort-level) Effort level The `effort` option controls how much reasoning Claude applies. Lower effort levels use fewer tokens per turn and reduce cost. Not all models support the effort parameter. See [Effort](https://platform.claude.com/docs/en/build-with-claude/effort) for which models support it. | Level | Behavior | Good for | |:-----------|:----------------------------------|:--------------------------------------------------------------------------| | `"low"` | Minimal reasoning, fast responses | File lookups, listing directories | | `"medium"` | Balanced reasoning | Routine edits, standard tasks | | `"high"` | Thorough analysis | Refactors, debugging | | `"xhigh"` | Extended reasoning depth | Coding and agentic tasks; recommended on Fable 5, Opus 4.7+, and Sonnet 5 | | `"max"` | Maximum reasoning depth | Multi-step problems requiring deep analysis | If you don’t set `effort`, both SDKs leave the parameter unset and defer to the model’s default behavior. `effort` trades latency and token cost for reasoning depth within each response. [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) is a separate feature that produces `thinking` blocks in the output, and the `display` field on `ThinkingConfig` for [Python](/docs/en/agent-sdk/python#thinkingconfig) or [TypeScript](/docs/en/agent-sdk/typescript#thinkingconfig) controls whether you receive their text. They are independent: you can set `effort: "low"` with extended thinking enabled, or `effort: "max"` without it. Use lower effort for agents doing simple, well-scoped tasks (like listing files or running a single grep) to reduce cost and latency. Set `effort` in the top-level `query()` options for the whole session, or per subagent with the `effort` field on [`AgentDefinition`](/docs/en/agent-sdk/subagents#agentdefinition-configuration) to override the session level. [​](#permission-mode) Permission mode The permission mode option (`permission_mode` in Python, `permissionMode` in TypeScript) controls whether the agent asks for approval before using tools: | Mode | Behavior | Use case | |:----------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------| | `"default"` | Tools not covered by allow rules trigger your `canUseTool` callback; no callback means deny | Interactive applications with a custom approval callback | | `"acceptEdits"` | Auto-approves file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.); other Bash commands follow default rules | You trust Claude’s edits and want faster iteration, such as during prototyping or when working in an isolated directory | | `"plan"` | Claude explores and plans without editing your source files; file edits are never auto-approved and prompt through your `canUseTool` callback | You want Claude to propose changes without executing them, such as during code review or when you need to approve changes before they’re made | | `"dontAsk"` | Never prompts. Tools pre-approved by [permission rules](/docs/en/settings#permission-settings) run; everything else is denied. `AskUserQuestion`, connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools), and MCP tools marked [`requiresUserInteraction`](/docs/en/mcp#require-approval-for-a-specific-tool) are denied even if you’ve allowed them | You want a fixed, explicit tool surface for a headless agent and prefer a hard deny over silent reliance on `canUseTool` being absent | | `"auto"` | Uses a model classifier to approve or deny permission prompts. See [Auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) for availability and behavior | Autonomous agents that still want safety guardrails on tool use | | `"bypassPermissions"` | Runs all allowed tools without asking, except tools matched by an explicit [`ask` rule](/docs/en/settings#permission-settings), connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools), and tools that require user interaction; see [How permissions are evaluated](/docs/en/agent-sdk/permissions#how-permissions-are-evaluated) for the precedence order. In the TypeScript SDK, also requires `allowDangerouslySkipPermissions: true` in `options`. Cannot be used when running as root on Unix. Use only in isolated environments where the agent’s actions cannot affect systems you care about | CI, containers, or other isolated environments | For interactive applications, use `"default"` with a tool approval callback to surface approval prompts. For autonomous agents on a dev machine, `"acceptEdits"` auto-approves file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.) while still gating other `Bash` commands behind allow rules. Reserve `"bypassPermissions"` for CI, containers, or other isolated environments. See [Permissions](/docs/en/agent-sdk/permissions) for full details. [​](#model) Model If you don’t set `model`, the SDK uses Claude Code’s default, which depends on your authentication method and subscription. Set it explicitly (for example, `model="claude-sonnet-5"`) to pin a specific model or to use a smaller model for faster, cheaper agents. See [models](https://platform.claude.com/docs/en/about-claude/models) for available IDs. [​](#the-context-window) The context window The context window is the total amount of information available to Claude during a session. It does not reset between turns within a session. Everything accumulates: the system prompt, tool definitions, conversation history, tool inputs, and tool outputs. Content that stays the same across turns (system prompt, tool definitions, CLAUDE.md) is automatically [prompt cached](https://platform.claude.com/docs/en/build-with-claude/prompt-caching), which reduces cost and latency for repeated prefixes. For how a custom system prompt or `append` text affects cache reuse across sessions, see [Modifying system prompts](/docs/en/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines). [​](#what-consumes-context) What consumes context Here’s how each component affects context in the SDK: | Source | When it loads | Impact | |:-------------------------|:-------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **System prompt** | Every request | Small fixed cost, always present | | **CLAUDE.md files** | Session start, via [`settingSources`](/docs/en/agent-sdk/claude-code-features) | Full content in every request (but prompt-cached, so only the first request pays full cost) | | **Tool definitions** | Every request; MCP schemas deferred by default | Built-in tool schemas load every request. [Tool search](/docs/en/agent-sdk/mcp#mcp-tool-search) defers MCP tool schemas by default, falling back to upfront loading on Google Cloud’s Agent Platform, a non-first-party `ANTHROPIC_BASE_URL`, or a Microsoft Foundry deployment hosted on Azure. See [Configure tool search](/docs/en/agent-sdk/tool-search#configure-tool-search) for the full matrix | | **Conversation history** | Accumulates over turns | Grows with each turn: prompts, responses, tool inputs, tool outputs | | **Skill descriptions** | Session start, via setting sources | Short summaries; full content loads only when invoked | Large tool outputs consume significant context. Reading a big file or running a command with verbose output can use thousands of tokens in a single turn. Context accumulates across turns, so longer sessions with many tool calls build up significantly more context than short ones. [​](#automatic-compaction) Automatic compaction When the context window approaches its limit, the SDK automatically compacts the conversation: it summarizes older history to free space, keeping your most recent exchanges and key decisions intact. The SDK emits a message with `type: "system"` and `subtype: "compact_boundary"` in the stream when this happens (in Python this is a `SystemMessage`; in TypeScript it is a separate `SDKCompactBoundaryMessage` type). Compaction replaces older messages with a summary, so specific instructions from early in the conversation may not be preserved. Persistent rules belong in CLAUDE.md (loaded via [`settingSources`](/docs/en/agent-sdk/claude-code-features)) rather than in the initial prompt, because CLAUDE.md content is re-injected on every request. You can customize compaction behavior in several ways: - **Summarization instructions in CLAUDE.md:** The compactor reads your CLAUDE.md like any other context, so you can include a section telling it what to preserve when summarizing. The section header is free-form (not a magic string); the compactor matches on intent. - **`PreCompact` hook:** Run custom logic before compaction occurs, for example to archive the full transcript. The hook receives a `trigger` field (`manual` or `auto`). See [hooks](/docs/en/agent-sdk/hooks). - **Manual compaction:** Send `/compact` as a prompt string to trigger compaction on demand. Commands sent this way are SDK inputs, not CLI-only shortcuts. See [commands in the SDK](/docs/en/agent-sdk/slash-commands). Example: Summarization instructions in CLAUDE.md Add a section to your project’s CLAUDE.md telling the compactor what to preserve. The header name isn’t special; use any clear label. CLAUDE.md ```python # Summary instructions When summarizing this conversation, always preserve: - The current task objective and acceptance criteria - File paths that have been read or modified - Test results and error messages - Decisions made and the reasoning behind them ``` [​](#keep-context-efficient) Keep context efficient A few strategies for long-running agents: - **Use subagents for subtasks.** Each subagent starts with a fresh conversation (no prior message history, though it does load its own system prompt and project-level context like CLAUDE.md). It does not see the parent’s turns, and only its final response returns to the parent as a tool result. The main agent’s context grows by that summary, not by the full subtask transcript. See [What subagents inherit](/docs/en/agent-sdk/subagents#what-subagents-inherit) for details. - **Be selective with tools.** Every tool definition takes context space. Use the `tools` field on [`AgentDefinition`](/docs/en/agent-sdk/subagents#agentdefinition-configuration) to scope subagents to the minimum set they need. - **Watch MCP server costs.** [MCP tool search](/docs/en/agent-sdk/mcp#mcp-tool-search) defers MCP tool schemas by default and loads them on demand. When tool search is off or has fallen back to upfront loading, each MCP server adds all its tool schemas to every request, so a few servers with many tools can consume significant context before the agent does any work. The fallback applies on Google Cloud’s Agent Platform, behind a non-first-party `ANTHROPIC_BASE_URL`, and on a Microsoft Foundry deployment hosted on Azure. - **Use lower effort for routine tasks.** Set [effort](#effort-level) to `"low"` for agents that only need to read files or list directories. This reduces token usage and cost. For a detailed breakdown of per-feature context costs, see [Understand context costs](/docs/en/features-overview#understand-context-costs). [​](#sessions-and-continuity) Sessions and continuity Each interaction with the SDK creates or continues a session. Capture the session ID from `ResultMessage.session_id` (available in both SDKs) to resume later. The TypeScript SDK also exposes it as a direct field on the init `SystemMessage`; in Python it’s nested in `SystemMessage.data`. When you resume, the full context from previous turns is restored: files that were read, analysis that was performed, and actions that were taken. You can also fork a session to branch into a different approach without modifying the original. See [Session management](/docs/en/agent-sdk/sessions) for the full guide on resume, continue, and fork patterns. To resume sessions across stateless containers or serverless hosts, pass a [`session_store` / `sessionStore` adapter](/docs/en/agent-sdk/session-storage) so transcripts are mirrored to your own backend and any host can resume them. The Claude Code subprocess still writes to local disk first; point `CLAUDE_CONFIG_DIR` at a temp directory in `options.env` if the local copy needs to be ephemeral. In Python, `ClaudeSDKClient` handles session IDs automatically across multiple calls. See the [Python SDK reference](/docs/en/agent-sdk/python#choosing-between-query-and-claudesdkclient) for details. [​](#handle-the-result) Handle the result When the loop ends, the `ResultMessage` tells you what happened and gives you the output. The `subtype` field (available in both SDKs) is the primary way to check termination state. | Result subtype | What happened | `result` field available? | |:--------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------:| | `success` | Claude finished the task normally | Yes | | `error_max_turns` | Hit the `maxTurns` limit before finishing | No | | `error_max_budget_usd` | Hit the `maxBudgetUsd` limit before finishing | No | | `error_during_execution` | An error interrupted the loop (for example, an API failure or cancelled request) | No | | `error_max_structured_output_retries` | No valid structured output was produced within the configured retry limit: every attempt failed validation, or a model fallback retracted the completed output with no successful retry | No | The `result` field (the final text output) is only present on the `success` variant, so always check the subtype before reading it. All result subtypes carry `total_cost_usd`, `usage`, `num_turns`, and `session_id` so you can track cost and resume even after errors. In Python, `total_cost_usd` and `usage` are typed as optional and may be `None` on some error paths, so guard before formatting them. See [Tracking costs and usage](/docs/en/agent-sdk/cost-tracking) for details on interpreting the `usage` fields. When a query ends on an error result: - A single-shot `query()` call yields the final result message, then raises an error that includes the failure text, such as `Reached maximum number of turns`. The raise is intentional — wrap the loop in a try block if your code needs to continue past it. The underlying Claude Code process also exits with a nonzero code. - A streaming input session stays alive, and you can keep sending messages. The result also includes a `stop_reason` field (`string | null` in TypeScript, `str | None` in Python) indicating why the model stopped generating on its final turn. Common values are `end_turn` (model finished normally), `max_tokens` (hit the output token limit), and `refusal` (the model declined the request). On error result subtypes, `stop_reason` carries the value from the last assistant response before the loop ended. To detect refusals, check `stop_reason === "refusal"` (TypeScript) or `stop_reason == "refusal"` (Python). See [`SDKResultMessage`](/docs/en/agent-sdk/typescript#sdkresultmessage) (TypeScript) or [`ResultMessage`](/docs/en/agent-sdk/python#resultmessage) (Python) for the full type. [​](#hooks) Hooks [Hooks](/docs/en/agent-sdk/hooks) are callbacks that fire at specific points in the loop: before a tool runs, after it returns, when the agent finishes, and so on. Some commonly used hooks are: | Hook | When it fires | Common uses | |:---------------------------------|:------------------------------------|:-------------------------------------------| | `PreToolUse` | Before a tool executes | Validate inputs, block dangerous commands | | `PostToolUse` | After a tool returns | Audit outputs, trigger side effects | | `UserPromptSubmit` | When a prompt is sent | Inject additional context into prompts | | `Stop` | When the agent finishes | Validate the result, save session state | | `SubagentStart` / `SubagentStop` | When a subagent spawns or completes | Track and aggregate parallel task results | | `PreCompact` | Before context compaction | Archive full transcript before summarizing | Hooks run in your application process, not inside the agent’s context window, so they don’t consume context. Hooks can also short-circuit the loop: a `PreToolUse` hook that rejects a tool call prevents it from executing, and Claude receives the rejection message instead. Both SDKs support all the events above. The TypeScript SDK includes additional events that Python does not yet support. See [Control execution with hooks](/docs/en/agent-sdk/hooks) for the complete event list, per-SDK availability, and the full callback API. [​](#put-it-all-together) Put it all together This example combines the key concepts from this page into a single agent that fixes failing tests. It configures the agent with allowed tools (auto-approved so the agent runs autonomously), project settings, and safety limits on turns and reasoning effort. As the loop runs, it captures the session ID for potential resumption, handles the final result, and prints the total cost. Because a single-shot `query()` call raises after yielding an error result, the loop is wrapped in a try block so the script exits cleanly when a limit is hit. Python TypeScript ```python import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage async def run_agent(): session_id = None try: async for message in query( prompt="Find and fix the bug causing test failures in the auth module", options=ClaudeAgentOptions( allowed_tools=[ "Read", "Edit", "Bash", "Glob", "Grep", ], # Listing tools here auto-approves them (no prompting) setting_sources=[ "project" ], # Load CLAUDE.md, skills, hooks from current directory max_turns=30, # Prevent runaway sessions effort="high", # Thorough reasoning for complex debugging ), ): # Handle the final result if isinstance(message, ResultMessage): session_id = message.session_id # Save for potential resumption if message.subtype == "success": print(f"Done: {message.result}") elif message.subtype == "error_max_turns": # Agent ran out of turns. Resume with a higher limit. print(f"Hit turn limit. Resume session {session_id} to continue.") elif message.subtype == "error_max_budget_usd": print("Hit budget limit.") else: print(f"Stopped: {message.subtype}") if message.total_cost_usd is not None: print(f"Cost: ${message.total_cost_usd:.4f}") except Exception as error: # A single-shot query() raises after yielding an error result. If the # failure was an error result, the error subtype branches above have # already run; connection or process failures yield no result message. print(f"Session ended with an error: {error}") asyncio.run(run_agent()) ``` ```python import { query } from "@anthropic-ai/claude-agent-sdk"; let sessionId: string | undefined; try { for await (const message of query({ prompt: "Find and fix the bug causing test failures in the auth module", options: { allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"], // Listing tools here auto-approves them (no prompting) settingSources: ["project"], // Load CLAUDE.md, skills, hooks from current directory maxTurns: 30, // Prevent runaway sessions effort: "high" // Thorough reasoning for complex debugging } })) { // Save the session ID to resume later if needed if (message.type === "system" && message.subtype === "init") { sessionId = message.session_id; } // Handle the final result if (message.type === "result") { if (message.subtype === "success") { console.log(`Done: ${message.result}`); } else if (message.subtype === "error_max_turns") { // Agent ran out of turns. Resume with a higher limit. console.log(`Hit turn limit. Resume session ${sessionId} to continue.`); } else if (message.subtype === "error_max_budget_usd") { console.log("Hit budget limit."); } else { console.log(`Stopped: ${message.subtype}`); } console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`); } } } catch (error) { // A single-shot query() throws after yielding an error result. If the // failure was an error result, the error subtype branches above have // already run; connection or process failures yield no result message. console.log(`Session ended with an error: ${error}`); } ``` When the agent finishes successfully, the example prints a `Done:` line with the agent’s summary of the fix, then a line like `Cost: $0.0312`. [​](#next-steps) Next steps Now that you understand the loop, here’s where to go depending on what you’re building: - **Haven’t run an agent yet?** Start with the [quickstart](/docs/en/agent-sdk/quickstart) to get the SDK installed and see a full example running end to end. - **Ready to hook into your project?** [Load CLAUDE.md, skills, and filesystem hooks](/docs/en/agent-sdk/claude-code-features) so the agent follows your project conventions automatically. - **Building an interactive UI?** Enable [streaming](/docs/en/agent-sdk/streaming-output) to show live text and tool calls as the loop runs. - **Need tighter control over what the agent can do?** Lock down tool access with [permissions](/docs/en/agent-sdk/permissions), and use [hooks](/docs/en/agent-sdk/hooks) to audit, block, or transform tool calls before they execute. - **Running long or expensive tasks?** Offload isolated work to [subagents](/docs/en/agent-sdk/subagents) to keep your main context lean. - **Deploying as a service?** See [Hosting the Agent SDK](/docs/en/agent-sdk/hosting) for container and serverless guidance, and [Session storage](/docs/en/agent-sdk/session-storage) to persist sessions to your own backend. For the broader conceptual picture of the agentic loop (not SDK-specific), see [How Claude Code works](/docs/en/how-claude-code-works). For a practical guide to designing loops in Claude Code, from turn-based to goal-based and proactive loops, see [Loop engineering: getting started with loops](https://claude.com/blog/getting-started-with-loops) on the blog. --- ## interactive-commands.md # Interactive Command Patterns Comprehensive guide to creating commands that gather user feedback and make decisions through the AskUserQuestion tool. ## Overview Some commands need user input that doesn't work well with simple arguments. For example: - Choosing between multiple complex options with trade-offs - Selecting multiple items from a list - Making decisions that require explanation - Gathering preferences or configuration interactively For these cases, use the **AskUserQuestion tool** within command execution rather than relying on command arguments. ## When to Use AskUserQuestion ### Use AskUserQuestion When: 1. **Multiple choice decisions** with explanations needed 2. **Complex options** that require context to choose 3. **Multi-select scenarios** (choosing multiple items) 4. **Preference gathering** for configuration 5. **Interactive workflows** that adapt based on answers ### Use Command Arguments When: 1. **Simple values** (file paths, numbers, names) 2. **Known inputs** user already has 3. **Scriptable workflows** that should be automatable 4. **Fast invocations** where prompting would slow down ## AskUserQuestion Basics ### Tool Parameters ```typescript { questions: [ { question: "Which authentication method should we use?", header: "Auth method", // Short label (max 12 chars) multiSelect: false, // true for multiple selection options: [ { label: "OAuth 2.0", description: "Industry standard, supports multiple providers" }, { label: "JWT", description: "Stateless, good for APIs" }, { label: "Session", description: "Traditional, server-side state" } ] } ] } ``` **Key points:** - Users can always choose "Other" to provide custom input (automatic) - `multiSelect: true` allows selecting multiple options - Options should be 2-4 choices (not more) - Can ask 1-4 questions per tool call ## Command Pattern for User Interaction ### Basic Interactive Command ```markdown --- description: Interactive setup command allowed-tools: AskUserQuestion, Write --- # Interactive Plugin Setup This command will guide you through configuring the plugin with a series of questions. ## Step 1: Gather Configuration Use the AskUserQuestion tool to ask: **Question 1 - Deployment target:** - header: "Deploy to" - question: "Which deployment platform will you use?" - options: - AWS (Amazon Web Services with ECS/EKS) - GCP (Google Cloud with GKE) - Azure (Microsoft Azure with AKS) - Local (Docker on local machine) **Question 2 - Environment strategy:** - header: "Environments" - question: "How many environments do you need?" - options: - Single (Just production) - Standard (Dev, Staging, Production) - Complete (Dev, QA, Staging, Production) **Question 3 - Features to enable:** - header: "Features" - question: "Which features do you want to enable?" - multiSelect: true - options: - Auto-scaling (Automatic resource scaling) - Monitoring (Health checks and metrics) - CI/CD (Automated deployment pipeline) - Backups (Automated database backups) ## Step 2: Process Answers Based on the answers received from AskUserQuestion: 1. Parse the deployment target choice 2. Set up environment-specific configuration 3. Enable selected features 4. Generate configuration files ## Step 3: Generate Configuration Create `.claude/plugin-name.local.md` with: \`\`\`yaml --- deployment_target: [answer from Q1] environments: [answer from Q2] features: auto_scaling: [true if selected in Q3] monitoring: [true if selected in Q3] ci_cd: [true if selected in Q3] backups: [true if selected in Q3] --- # Plugin Configuration Generated: [timestamp] Target: [deployment_target] Environments: [environments] \`\`\` ## Step 4: Confirm and Next Steps Confirm configuration created and guide user on next steps. ``` ### Multi-Stage Interactive Workflow ```markdown --- description: Multi-stage interactive workflow allowed-tools: AskUserQuestion, Read, Write, Bash --- # Multi-Stage Deployment Setup This command walks through deployment setup in stages, adapting based on your answers. ## Stage 1: Basic Configuration Use AskUserQuestion to ask about deployment basics. Based on answers, determine which additional questions to ask. ## Stage 2: Advanced Options (Conditional) If user selected "Advanced" deployment in Stage 1: Use AskUserQuestion to ask about: - Load balancing strategy - Caching configuration - Security hardening options If user selected "Simple" deployment: - Skip advanced questions - Use sensible defaults ## Stage 3: Confirmation Show summary of all selections. Use AskUserQuestion for final confirmation: - header: "Confirm" - question: "Does this configuration look correct?" - options: - Yes (Proceed with setup) - No (Start over) - Modify (Let me adjust specific settings) If "Modify", ask which specific setting to change. ## Stage 4: Execute Setup Based on confirmed configuration, execute setup steps. ``` ## Interactive Question Design ### Question Structure **Good questions:** ```markdown Question: "Which database should we use for this project?" Header: "Database" Options: - PostgreSQL (Relational, ACID compliant, best for complex queries) - MongoDB (Document store, flexible schema, best for rapid iteration) - Redis (In-memory, fast, best for caching and sessions) ``` **Poor questions:** ```markdown Question: "Database?" // Too vague Header: "DB" // Unclear abbreviation Options: - Option 1 // Not descriptive - Option 2 ``` ### Option Design Best Practices **Clear labels:** - Use 1-5 words - Specific and descriptive - No jargon without context **Helpful descriptions:** - Explain what the option means - Mention key benefits or trade-offs - Help user make informed decision - Keep to 1-2 sentences **Appropriate number:** - 2-4 options per question - Don't overwhelm with too many choices - Group related options - "Other" automatically provided ### Multi-Select Questions **When to use multiSelect:** ```markdown Use AskUserQuestion for enabling features: Question: "Which features do you want to enable?" Header: "Features" multiSelect: true // Allow selecting multiple Options: - Logging (Detailed operation logs) - Metrics (Performance monitoring) - Alerts (Error notifications) - Backups (Automatic backups) ``` User can select any combination: none, some, or all. **When NOT to use multiSelect:** ```markdown Question: "Which authentication method?" multiSelect: false // Only one auth method makes sense ``` Mutually exclusive choices should not use multiSelect. ## Command Patterns with AskUserQuestion ### Pattern 1: Simple Yes/No Decision ```markdown --- description: Command with confirmation allowed-tools: AskUserQuestion, Bash --- # Destructive Operation This operation will delete all cached data. Use AskUserQuestion to confirm: Question: "This will delete all cached data. Are you sure?" Header: "Confirm" Options: - Yes (Proceed with deletion) - No (Cancel operation) If user selects "Yes": Execute deletion Report completion If user selects "No": Cancel operation Exit without changes ``` ### Pattern 2: Multiple Configuration Questions ```markdown --- description: Multi-question configuration allowed-tools: AskUserQuestion, Write --- # Project Configuration Setup Gather configuration through multiple questions. Use AskUserQuestion with multiple questions in one call: **Question 1:** - question: "Which programming language?" - header: "Language" - options: Python, TypeScript, Go, Rust **Question 2:** - question: "Which test framework?" - header: "Testing" - options: Jest, PyTest, Go Test, Cargo Test (Adapt based on language from Q1) **Question 3:** - question: "Which CI/CD platform?" - header: "CI/CD" - options: GitHub Actions, GitLab CI, CircleCI **Question 4:** - question: "Which features do you need?" - header: "Features" - multiSelect: true - options: Linting, Type checking, Code coverage, Security scanning Process all answers together to generate cohesive configuration. ``` ### Pattern 3: Conditional Question Flow ```markdown --- description: Conditional interactive workflow allowed-tools: AskUserQuestion, Read, Write --- # Adaptive Configuration ## Question 1: Deployment Complexity Use AskUserQuestion: Question: "How complex is your deployment?" Header: "Complexity" Options: - Simple (Single server, straightforward) - Standard (Multiple servers, load balancing) - Complex (Microservices, orchestration) ## Conditional Questions Based on Answer If answer is "Simple": - No additional questions - Use minimal configuration If answer is "Standard": - Ask about load balancing strategy - Ask about scaling policy If answer is "Complex": - Ask about orchestration platform (Kubernetes, Docker Swarm) - Ask about service mesh (Istio, Linkerd, None) - Ask about monitoring (Prometheus, Datadog, CloudWatch) - Ask about logging aggregation ## Process Conditional Answers Generate configuration appropriate for selected complexity level. ``` ### Pattern 4: Iterative Collection ```markdown --- description: Collect multiple items iteratively allowed-tools: AskUserQuestion, Write --- # Collect Team Members We'll collect team member information for the project. ## Question: How many team members? Use AskUserQuestion: Question: "How many team members should we set up?" Header: "Team size" Options: - 2 people - 3 people - 4 people - 6 people ## Iterate Through Team Members For each team member (1 to N based on answer): Use AskUserQuestion for member details: Question: "What role for team member [number]?" Header: "Role" Options: - Frontend Developer - Backend Developer - DevOps Engineer - QA Engineer - Designer Store each member's information. ## Generate Team Configuration After collecting all N members, create team configuration file with all members and their roles. ``` ### Pattern 5: Dependency Selection ```markdown --- description: Select dependencies with multi-select allowed-tools: AskUserQuestion --- # Configure Project Dependencies ## Question: Required Libraries Use AskUserQuestion with multiSelect: Question: "Which libraries does your project need?" Header: "Dependencies" multiSelect: true Options: - React (UI framework) - Express (Web server) - TypeORM (Database ORM) - Jest (Testing framework) - Axios (HTTP client) User can select any combination. ## Process Selections For each selected library: - Add to package.json dependencies - Generate sample configuration - Create usage examples - Update documentation ``` ## Best Practices for Interactive Commands ### Question Design 1. **Clear and specific**: Question should be unambiguous 2. **Concise header**: Max 12 characters for clean display 3. **Helpful options**: Labels are clear, descriptions explain trade-offs 4. **Appropriate count**: 2-4 options per question, 1-4 questions per call 5. **Logical order**: Questions flow naturally ### Error Handling ```markdown # Handle AskUserQuestion Responses After calling AskUserQuestion, verify answers received: If answers are empty or invalid: Something went wrong gathering responses. Please try again or provide configuration manually: [Show alternative approach] Exit. If answers look correct: Process as expected ``` ### Progressive Disclosure ```markdown # Start Simple, Get Detailed as Needed ## Question 1: Setup Type Use AskUserQuestion: Question: "How would you like to set up?" Header: "Setup type" Options: - Quick (Use recommended defaults) - Custom (Configure all options) - Guided (Step-by-step with explanations) If "Quick": Apply defaults, minimal questions If "Custom": Ask all available configuration questions If "Guided": Ask questions with extra explanation Provide recommendations along the way ``` ### Multi-Select Guidelines **Good multi-select use:** ```markdown Question: "Which features do you want to enable?" multiSelect: true Options: - Logging - Metrics - Alerts - Backups Reason: User might want any combination ``` **Bad multi-select use:** ```markdown Question: "Which database engine?" multiSelect: true // ❌ Should be single-select Reason: Can only use one database engine ``` ## Advanced Patterns ### Validation Loop ```markdown --- description: Interactive with validation allowed-tools: AskUserQuestion, Bash --- # Setup with Validation ## Gather Configuration Use AskUserQuestion to collect settings. ## Validate Configuration Check if configuration is valid: - Required dependencies available? - Settings compatible with each other? - No conflicts detected? If validation fails: Show validation errors Use AskUserQuestion to ask: Question: "Configuration has issues. What would you like to do?" Header: "Next step" Options: - Fix (Adjust settings to resolve issues) - Override (Proceed despite warnings) - Cancel (Abort setup) Based on answer, retry or proceed or exit. ``` ### Build Configuration Incrementally ```markdown --- description: Incremental configuration builder allowed-tools: AskUserQuestion, Write, Read --- # Incremental Setup ## Phase 1: Core Settings Use AskUserQuestion for core settings. Save to `.claude/config-partial.yml` ## Phase 2: Review Core Settings Show user the core settings: Based on these core settings, you need to configure: - [Setting A] (because you chose [X]) - [Setting B] (because you chose [Y]) Ready to continue? ## Phase 3: Detailed Settings Use AskUserQuestion for settings based on Phase 1 answers. Merge with core settings. ## Phase 4: Final Review Present complete configuration. Use AskUserQuestion for confirmation: Question: "Is this configuration correct?" Options: - Yes (Save and apply) - No (Start over) - Modify (Edit specific settings) ``` ### Dynamic Options Based on Context ```markdown --- description: Context-aware questions allowed-tools: AskUserQuestion, Bash, Read --- # Context-Aware Setup ## Detect Current State Check existing configuration: - Current language: !`detect-language.sh` - Existing frameworks: !`detect-frameworks.sh` - Available tools: !`check-tools.sh` ## Ask Context-Appropriate Questions Based on detected language, ask relevant questions. If language is TypeScript: Use AskUserQuestion: Question: "Which TypeScript features should we enable?" Options: - Strict Mode (Maximum type safety) - Decorators (Experimental decorator support) - Path Mapping (Module path aliases) If language is Python: Use AskUserQuestion: Question: "Which Python tools should we configure?" Options: - Type Hints (mypy for type checking) - Black (Code formatting) - Pylint (Linting and style) Questions adapt to project context. ``` ## Real-World Example: Multi-Agent Swarm Launch **From multi-agent-swarm plugin:** ```markdown --- description: Launch multi-agent swarm allowed-tools: AskUserQuestion, Read, Write, Bash --- # Launch Multi-Agent Swarm ## Interactive Mode (No Task List Provided) If user didn't provide task list file, help create one interactively. ### Question 1: Agent Count Use AskUserQuestion: Question: "How many agents should we launch?" Header: "Agent count" Options: - 2 agents (Best for simple projects) - 3 agents (Good for medium projects) - 4 agents (Standard team size) - 6 agents (Large projects) - 8 agents (Complex multi-component projects) ### Question 2: Task Definition Approach Use AskUserQuestion: Question: "How would you like to define tasks?" Header: "Task setup" Options: - File (I have a task list file ready) - Guided (Help me create tasks interactively) - Custom (Other approach) If "File": Ask for file path Validate file exists and has correct format If "Guided": Enter iterative task creation mode (see below) ### Question 3: Coordination Mode Use AskUserQuestion: Question: "How should agents coordinate?" Header: "Coordination" Options: - Team Leader (One agent coordinates others) - Collaborative (Agents coordinate as peers) - Autonomous (Independent work, minimal coordination) ### Iterative Task Creation (If "Guided" Selected) For each agent (1 to N from Question 1): **Question A: Agent Name** Question: "What should we call agent [number]?" Header: "Agent name" Options: - auth-agent - api-agent - ui-agent - db-agent (Provide relevant suggestions based on common patterns) **Question B: Task Type** Question: "What task for [agent-name]?" Header: "Task type" Options: - Authentication (User auth, JWT, OAuth) - API Endpoints (REST/GraphQL APIs) - UI Components (Frontend components) - Database (Schema, migrations, queries) - Testing (Test suites and coverage) - Documentation (Docs, README, guides) **Question C: Dependencies** Question: "What does [agent-name] depend on?" Header: "Dependencies" multiSelect: true Options: - [List of previously defined agents] - No dependencies **Question D: Base Branch** Question: "Which base branch for PR?" Header: "PR base" Options: - main - staging - develop Store all task information for each agent. ### Generate Task List File After collecting all agent task details: 1. Ask for project name 2. Generate task list in proper format 3. Save to `.daisy/swarm/tasks.md` 4. Show user the file path 5. Proceed with launch using generated task list ``` ## Best Practices ### Question Writing 1. **Be specific**: "Which database?" not "Choose option?" 2. **Explain trade-offs**: Describe pros/cons in option descriptions 3. **Provide context**: Question text should stand alone 4. **Guide decisions**: Help user make informed choice 5. **Keep concise**: Header max 12 chars, descriptions 1-2 sentences ### Option Design 1. **Meaningful labels**: Specific, clear names 2. **Informative descriptions**: Explain what each option does 3. **Show trade-offs**: Help user understand implications 4. **Consistent detail**: All options equally explained 5. **2-4 options**: Not too few, not too many ### Flow Design 1. **Logical order**: Questions flow naturally 2. **Build on previous**: Later questions use earlier answers 3. **Minimize questions**: Ask only what's needed 4. **Group related**: Ask related questions together 5. **Show progress**: Indicate where in flow ### User Experience 1. **Set expectations**: Tell user what to expect 2. **Explain why**: Help user understand purpose 3. **Provide defaults**: Suggest recommended options 4. **Allow escape**: Let user cancel or restart 5. **Confirm actions**: Summarize before executing ## Common Patterns ### Pattern: Feature Selection ```markdown Use AskUserQuestion: Question: "Which features do you need?" Header: "Features" multiSelect: true Options: - Authentication - Authorization - Rate Limiting - Caching ``` ### Pattern: Environment Configuration ```markdown Use AskUserQuestion: Question: "Which environment is this?" Header: "Environment" Options: - Development (Local development) - Staging (Pre-production testing) - Production (Live environment) ``` ### Pattern: Priority Selection ```markdown Use AskUserQuestion: Question: "What's the priority for this task?" Header: "Priority" Options: - Critical (Must be done immediately) - High (Important, do soon) - Medium (Standard priority) - Low (Nice to have) ``` ### Pattern: Scope Selection ```markdown Use AskUserQuestion: Question: "What scope should we analyze?" Header: "Scope" Options: - Current file (Just this file) - Current directory (All files in directory) - Entire project (Full codebase scan) ``` ## Combining Arguments and Questions ### Use Both Appropriately **Arguments for known values:** ```markdown --- argument-hint: [project-name] allowed-tools: AskUserQuestion, Write --- Setup for project: $1 Now gather additional configuration... Use AskUserQuestion for options that require explanation. ``` **Questions for complex choices:** ```markdown Project name from argument: $1 Now use AskUserQuestion to choose: - Architecture pattern - Technology stack - Deployment strategy These require explanation, so questions work better than arguments. ``` ## Troubleshooting **Questions not appearing:** - Verify AskUserQuestion in allowed-tools - Check question format is correct - Ensure options array has 2-4 items **User can't make selection:** - Check option labels are clear - Verify descriptions are helpful - Consider if too many options - Ensure multiSelect setting is correct **Flow feels confusing:** - Reduce number of questions - Group related questions - Add explanation between stages - Show progress through workflow With AskUserQuestion, commands become interactive wizards that guide users through complex decisions while maintaining the clarity that simple arguments provide for straightforward inputs. --- *Truncated: 40 more documents not shown (size limit)*