## 1. Project Overview & Quickstart (zhukunpenglinyutong/jetbrains-cc-gui)
## File: README.md
> To mitigate Claude trademark risks, this project has been renamed to CC GUI (originally Claude Code GUI). The logo has also been updated to reduce Chinese-specific elements. Regarding security, a
/security-review audit will be conducted before each minor version release, and a comprehensive claude-code-security audit will be performed every 10 minor versions.
A powerful IntelliJ IDEA plugin that provides a visual interface for **Claude Code** and **OpenAI Codex** dual AI tools, making AI-assisted programming more efficient and intuitive.
---
## Installation
[CC GUI（Claude or Codex） Installation](https://plugins.jetbrains.com/plugin/29342-cc-gui-claude-or-codex-)
---
## Key Features
### Dual AI Engine Support
- **Claude Code** - Anthropic's official AI programming assistant, supporting Opus 4.5 and other models
- **OpenAI Codex** - OpenAI's powerful code generation engine
### Intelligent Conversation
- Context-aware AI coding assistant
- @file reference support for precise code context
- Image sending support for visual requirement description
- Conversation rewind feature for flexible history adjustment
- Enhanced prompts for better AI understanding
### Agent System
- Built-in Agent system for automated complex tasks
- Skills slash command system (/init, /review, etc.)
- MCP server support to extend AI capabilities
### Developer Experience
- Comprehensive permission management and security controls
- Code DIFF comparison feature
- File navigation and code jumping
- Dark/Light theme switching
- Font scaling and IDE font synchronization
- Internationalization support (auto-switch between Chinese/English)
### Session Management
- History session records and search
- Session favorites
- Message export support
- Provider management (cc-switch compatible)
- Usage statistics analysis
---
## Project Status
The project is under active development with continuous updates. For version history and iteration progress, please read [CHANGELOG.md](CHANGELOG.md)
---
### Collaborative Contributing
For contributing guidelines, please read [CONTRIBUTING.md](CONTRIBUTING.md)
---
## Local Development and Debugging
### 1. Install Frontend Dependencies
```bash
cd webview
npm install
```
### 2. Install ai-bridge Dependencies
```bash
cd ai-bridge
npm install
```
### 3. Debug Plugin
Run in IDEA:
```bash
./gradlew clean runIde
```
### 4. Build Plugin
```sh
./gradlew clean buildPlugin
# The generated plugin package will be in the build/distributions/ directory (package size approximately 40MB)
```
---
## License
MIT
---
## Contributing
Thanks to all contributors who help make IDEA-Claude-Code-GUI better!
---
## Sponsor
If this project is helpful to you, you can invite the author to have a KFC or a cup of coffee~
如果这个项目对你有帮助，想请作者吃顿肯德基（KFC）或者喝杯咖啡，都是可以的~
[View Sponsors List →](./SPONSORS.md)
---
## Friendship Link
Thanks for the support and feedback from the friends at [LINUX DO](https://linux.do/).
Thank you for [AtomGit](https://atomgit.com/zhukunpenglinyutong/idea-claude-code-gui) platform G-Star certification
---
## Acknowledgements
Recently, many bloggers have recommended this project on their own initiative, and I am deeply grateful. Thanks again to bloggers including "沉默的王二", "macrozheng", "JavaGuide", "Java知音", "鲲鹏talk 公众号", and "程序员青戈" for recommending this project. I will keep iterating to make it more comfortable for everyone to use.
[github-contributors-shield]: https://img.shields.io/github/contributors/zhukunpenglinyutong/idea-claude-code-gui?color=c4f042&labelColor=black&style=flat-square
[github-forks-shield]: https://img.shields.io/github/forks/zhukunpenglinyutong/idea-claude-code-gui?color=8ae8ff&labelColor=black&style=flat-square
[github-issues-link]: https://github.com/zhukunpenglinyutong/idea-claude-code-gui/issues
[github-issues-shield]: https://img.shields.io/github/issues/zhukunpenglinyutong/idea-claude-code-gui?color=ff80eb&labelColor=black&style=flat-square
[github-license-link]: https://github.com/zhukunpenglinyutong/idea-claude-code-gui/blob/main/LICENSE
[github-stars-shield]: https://img.shields.io/github/stars/zhukunpenglinyutong/idea-claude-code-gui?color=ffcb47&labelColor=black&style=flat-square
[github-mit]: https://img.shields.io/badge/github-MIT-blue?logo=github
---
## File: docs/testing/project-level-prompts-testing-checklist.md
# Project-Level Prompts Testing Checklist
## Overview
This document provides a comprehensive manual testing checklist for the project-level prompts feature implementation.
**Feature**: Dual-scope prompt management (Global + Project)
**Test Date**: _To be filled during testing_
**Tester**: _To be filled during testing_
---
## Pre-Testing Setup
- [ ] Build the project: `./gradlew buildPlugin`
- [ ] Install the plugin in IntelliJ IDEA
- [ ] Open a test project in IntelliJ IDEA
- [ ] Ensure no existing `.codemoss/prompt.json` in home directory or project
- [ ] Clear browser cache for webview
---
## 1. Global Prompts Management
### 1.1 Create Global Prompt
- [ ] Open Settings (Tools → Codemoss → Settings)
- [ ] Navigate to "Prompt Library" section
- [ ] Click "Create" button in "Global Prompts" section
- [ ] Enter prompt name: "Test Global Prompt"
- [ ] Enter prompt content: "This is a test global prompt"
- [ ] Click "Save"
- [ ] **Expected**: Prompt appears in global prompts list
- [ ] **Expected**: Success message displayed
- [ ] **Verify**: File `~/.codemoss/prompt.json` exists and contains the prompt
### 1.2 Edit Global Prompt
- [ ] Click the three-dot menu (⋮) on a global prompt
- [ ] Select "Edit"
- [ ] Change prompt name to "Updated Global Prompt"
- [ ] Change content to "Updated content"
- [ ] Click "Save"
- [ ] **Expected**: Prompt name and content updated in the list
- [ ] **Expected**: Success message displayed
- [ ] **Verify**: Changes persisted in `~/.codemoss/prompt.json`
### 1.3 Delete Global Prompt
- [ ] Click the three-dot menu on a global prompt
- [ ] Select "Delete"
- [ ] Confirm deletion in the dialog
- [ ] **Expected**: Prompt removed from list
- [ ] **Expected**: Success message displayed
- [ ] **Verify**: Prompt removed from `~/.codemoss/prompt.json`
### 1.4 Export Global Prompts
- [ ] Create 2-3 global prompts
- [ ] Click "Export" button in global section
- [ ] Select prompts to export
- [ ] Click "Export"
- [ ] Choose export location
- [ ] **Expected**: JSON file created with selected prompts
- [ ] **Verify**: Exported file is valid JSON
- [ ] **Verify**: Exported prompts match selection
### 1.5 Import Global Prompts
- [ ] Click "Import" button in global section
- [ ] Select a valid prompt JSON file
- [ ] Review import preview dialog
- [ ] Select conflict resolution strategy (SKIP/OVERWRITE/DUPLICATE)
- [ ] Click "Import"
- [ ] **Expected**: Prompts imported according to strategy
- [ ] **Expected**: Import summary message displayed
- [ ] **Verify**: Imported prompts appear in global list
- [ ] **Verify**: Conflicts handled correctly
---
## 2. Project Prompts Management
### 2.1 Create Project Prompt
- [ ] Open Settings
- [ ] Navigate to "Prompt Library" section
- [ ] Verify "Project Prompts - {ProjectName}" section appears
- [ ] Click "Create" button in project section
- [ ] Enter prompt name: "Test Project Prompt"
- [ ] Enter prompt content: "This is a test project prompt"
- [ ] Click "Save"
- [ ] **Expected**: Prompt appears in project prompts list
- [ ] **Expected**: Success message displayed
- [ ] **Verify**: File `/.codemoss/prompt.json` exists and contains the prompt
### 2.2 Edit Project Prompt
- [ ] Click the three-dot menu on a project prompt
- [ ] Select "Edit"
- [ ] Change prompt name to "Updated Project Prompt"
- [ ] Change content to "Updated project content"
- [ ] Click "Save"
- [ ] **Expected**: Prompt updated in project list
- [ ] **Expected**: Success message displayed
- [ ] **Verify**: Changes persisted in `/.codemoss/prompt.json`
### 2.3 Delete Project Prompt
- [ ] Click the three-dot menu on a project prompt
- [ ] Select "Delete"
- [ ] Confirm deletion
- [ ] **Expected**: Prompt removed from project list
- [ ] **Expected**: Success message displayed
- [ ] **Verify**: Prompt removed from `/.codemoss/prompt.json`
### 2.4 Export Project Prompts
- [ ] Create 2-3 project prompts
- [ ] Click "Export" button in project section
- [ ] Select prompts to export
- [ ] Click "Export"
- [ ] Choose export location
- [ ] **Expected**: JSON file created with selected prompts
- [ ] **Verify**: Exported file is valid JSON
- [ ] **Verify**: Exported prompts match selection
### 2.5 Import Project Prompts
- [ ] Click "Import" button in project section
- [ ] Select a valid prompt JSON file
- [ ] Review import preview dialog
- [ ] Select conflict resolution strategy
- [ ] Click "Import"
- [ ] **Expected**: Prompts imported to project scope
- [ ] **Expected**: Import summary displayed
- [ ] **Verify**: Imported prompts appear in project list
### 2.6 Copy Project Prompt to Global
- [ ] Create a project prompt
- [ ] Click the three-dot menu on the prompt
- [ ] Select "Copy to Global"
- [ ] **Expected**: Prompt copied to global scope
- [ ] **Expected**: Success message displayed
- [ ] **Verify**: Prompt appears in both project and global lists
- [ ] **Verify**: Both copies have unique IDs
---
## 3. Scope Isolation
### 3.1 Global and Project Independence
- [ ] Create a prompt named "Test" in global scope
- [ ] Create a prompt named "Test" in project scope
- [ ] **Expected**: Both prompts exist independently
- [ ] Edit global "Test" prompt
- [ ] **Expected**: Project "Test" prompt remains unchanged
- [ ] Delete global "Test" prompt
- [ ] **Expected**: Project "Test" prompt still exists
### 3.2 ID Uniqueness
- [ ] Create multiple prompts in global scope
- [ ] Create multiple prompts in project scope
- [ ] **Verify**: All prompt IDs are unique within each scope
- [ ] **Verify**: IDs don't conflict between scopes
---
## 4. Multi-Project Support
### 4.1 Switch Between Projects
- [ ] Open Project A
- [ ] Create project prompts in Project A
- [ ] Note project prompt names
- [ ] Close Project A
- [ ] Open Project B
- [ ] Open Settings
- [ ] **Expected**: Project section shows "Project Prompts - Project B"
- [ ] **Expected**: Project A's prompts NOT visible
- [ ] Create different project prompts in Project B
- [ ] Close Project B
- [ ] Reopen Project A
- [ ] **Expected**: Project A's prompts visible again
- [ ] **Expected**: Project B's prompts NOT visible
### 4.2 No Active Project
- [ ] Close all projects
- [ ] Open the plugin without a project
- [ ] Open Settings
- [ ] **Expected**: "No Active Project" message displayed
- [ ] **Expected**: Global prompts still accessible
- [ ] **Expected**: Project section disabled or hidden
---
## 5. Chat Integration
### 5.1 Autocomplete with Global Prompts
- [ ] Create 2-3 global prompts with distinct names
- [ ] Open chat input
- [ ] Type "/" to trigger autocomplete
- [ ] **Expected**: Global prompts appear with "[全局]" label
- [ ] Select a global prompt
- [ ] **Expected**: Prompt content inserted into chat
### 5.2 Autocomplete with Project Prompts
- [ ] Create 2-3 project prompts with distinct names
- [ ] Open chat input
- [ ] Type "/" to trigger autocomplete
- [ ] **Expected**: Project prompts appear with "[项目]" label
- [ ] **Expected**: Project prompts appear BEFORE global prompts
- [ ] Select a project prompt
- [ ] **Expected**: Prompt content inserted into chat
### 5.3 Autocomplete with Both Scopes
- [ ] Ensure both global and project prompts exist
- [ ] Open chat input
- [ ] Type "/" to trigger autocomplete
- [ ] **Expected**: Both scopes visible
- [ ] **Expected**: Project prompts listed first
- [ ] **Expected**: Clear scope labels distinguish prompts
- [ ] **Expected**: Prompts with same name in different scopes both visible
---
## 6. Error Handling
### 6.1 Invalid JSON Import
- [ ] Click "Import" in either section
- [ ] Select an invalid JSON file
- [ ] **Expected**: Error message displayed
- [ ] **Expected**: No prompts imported
- [ ] **Expected**: Existing prompts unaffected
### 6.2 Permission Errors
- [ ] Make `~/.codemoss` directory read-only
- [ ] Try to create a global prompt
- [ ] **Expected**: Error message displayed
- [ ] Restore permissions
### 6.3 Empty Project Path
- [ ] Create a project without a base path (if possible)
- [ ] Try to create a project prompt
- [ ] **Expected**: Error message or graceful degradation
- [ ] **Expected**: Global prompts still functional
---
## 7. UI/UX Validation
### 7.1 Layout and Styling
- [ ] **Verify**: Two distinct sections (Global and Project)
- [ ] **Verify**: Section headers clearly labeled
- [ ] **Verify**: Action buttons properly aligned
- [ ] **Verify**: Prompt cards have consistent styling
- [ ] **Verify**: Dropdown menus positioned correctly
- [ ] **Verify**: Loading spinners appear during operations
### 7.2 Internationalization
- [ ] Switch language to English (en-US)
- [ ] **Verify**: All labels translated to English
- [ ] **Verify**: "Global Prompts" and "Project Prompts" labels correct
- [ ] Switch language to Chinese (zh-CN)
- [ ] **Verify**: All labels translated to Chinese
- [ ] **Verify**: "全局提示词" and "项目提示词" labels correct
### 7.3 Responsive Behavior
- [ ] Resize settings window to minimum width
- [ ] **Verify**: UI remains usable
- [ ] **Verify**: No text overflow or layout breaks
- [ ] Expand window to maximum width
- [ ] **Verify**: UI scales appropriately
---
## 8. Edge Cases
### 8.1 Empty States
- [ ] Delete all global prompts
- [ ] **Expected**: "No prompts available" message in global section
- [ ] Delete all project prompts
- [ ] **Expected**: "No prompts available" message in project section
### 8.2 Large Number of Prompts
- [ ] Import 50+ prompts into global scope
- [ ] **Verify**: List scrollable
- [ ] **Verify**: Performance acceptable
- [ ] **Verify**: Search/filter works (if implemented)
### 8.3 Special Characters in Names
- [ ] Create prompts with special characters: `@#$%^&*()`
- [ ] **Verify**: Names saved and displayed correctly
- [ ] **Verify**: No encoding issues
### 8.4 Very Long Prompt Content
- [ ] Create a prompt with 10,000+ characters of content
- [ ] **Verify**: Content saved successfully
- [ ] **Verify**: UI truncates display appropriately
- [ ] **Verify**: Full content accessible on edit
---
## 9. Backward Compatibility
### 9.1 Existing Global Prompts
- [ ] Manually create `~/.codemoss/prompt.json` with old format prompts
- [ ] Open Settings
- [ ] **Verify**: Existing prompts load in global section
- [ ] **Verify**: Can edit and delete existing prompts
- [ ] **Verify**: New prompts saved in compatible format
### 9.2 Migration from Single Scope
- [ ] Start with only old global prompts
- [ ] Create first project prompt
- [ ] **Verify**: Global prompts unaffected
- [ ] **Verify**: Project prompts stored in correct location
---
## 10. Performance
### 10.1 Load Time
- [ ] Measure time to open Settings with 100 global prompts
- [ ] **Expected**: < 2 seconds to fully load
- [ ] Measure time to open Settings with 100 project prompts
- [ ] **Expected**: < 2 seconds to fully load
### 10.2 Operation Speed
- [ ] Measure time to create a prompt
- [ ] **Expected**: < 500ms
- [ ] Measure time to delete a prompt
- [ ] **Expected**: < 500ms
- [ ] Measure time to import 50 prompts
- [ ] **Expected**: < 3 seconds
---
## Bug Tracker
| # | Description | Severity | Steps to Reproduce | Status |
|---|-------------|----------|-------------------|--------|
| 1 | | | | |
| 2 | | | | |
| 3 | | | | |
---
## Test Summary
**Total Test Cases**: 80+
**Passed**: ___
**Failed**: ___
**Blocked**: ___
**Not Tested**: ___
**Pass Rate**: ___%
---
## Notes
_Add any additional observations, suggestions, or issues encountered during testing._
---
## Sign-off
**Tested by**: _______________
**Date**: _______________
**Approved by**: _______________
**Date**: _______________
---
## File: docs/skills/avoiding-tmp-writes.md
# 解决 Claude CLI 在 IDEA 插件中写入 `/tmp` 的问题
在 IDE 插件中调用 `claude-code` CLI 时，模型经常会把 `Write/Edit` 等工具的 `file_path` 指向 `/tmp/xxx`。如果直接将 CLI 入口点切换到 `claude-vscode`，虽然会沿用 VSCode 的“工作区信任”策略，但也会强制要求通过 `/login` 获取官方凭证，并且只支持官方 `https://api.anthropic.com`。对于使用自建网关或手动配置 `ANTHROPIC_API_KEY` 的场景，这条路不可行。
最终有效的方案有两部分：
## 1. 使用 `sdk-ts` 入口点并注入自有 API 凭证
1. 在 `claude-bridge/channel-manager.js` 中把入口点固定为 `sdk-ts`：
```java
process.env.CLAUDE_CODE_ENTRYPOINT = "sdk-ts";
```
2. 调用 CLI 前，从 `~/.claude/settings.json` 或环境变量读取 `ANTHROPIC_AUTH_TOKEN / ANTHROPIC_BASE_URL`，写入 `process.env`。这样 CLI 就不会提示 `/login`，自建 API 也能正常工作。
3. 仍然可以保留现有的 `cwd`/`TMPDIR` 设置与 `additionalDirectories`，便于调试和记录日志，但不再依赖 `WorkspaceTrustManager` 自动改写 `settings.json`。
## 2. 在 `permission-handler` 中重写工具的写入路径
1. 在 `claude-bridge/permission-handler.js` 的 `canUseTool` 里增加一段重写逻辑：当检测到工具输入中出现 `file_path` 且指向 `/tmp`、`/var/tmp` 等临时目录时，自动改写为当前工作区根 (`IDEA_PROJECT_PATH` 或 `PROJECT_PATH`) 下的同名文件。
```javascript
rewriteToolInputPaths(toolName, input);
```
2. `rewriteToolInputPaths` 会递归检查 `input`，遇到 `/tmp/foo.js` 这类路径时将其换成 `path.join(workdir, "foo.js")`，并在日志中打印所有改写记录，方便验证。
3. 由于这一步发生在 CLI 真正执行工具之前，Claude 即使仍然生成 `/tmp/...` 也会被我们拦下，从而保证所有写入都落在项目目录内。
## 3. 验证方式
1. 在 IDE 中触发“创建文件”之类的工作流。
2. 观察插件日志，确认：
- `CLAUDE_CODE_ENTRYPOINT` 为 `sdk-ts`；
- `permission-handler` 输出了 `[PERMISSION] Rewrote paths ...`，说明临时路径被成功改写；
- CLI `tool_use` 日志中仍可能出现 `/tmp/...`，但实际执行时使用的则是被改写后的路径。
通过这套方案，可以继续使用自管的 API/网关，并根除 CLI 在 IDEA 环境下写入 `/tmp` 的问题，同时避免依赖 VSCode 专用的认证流程。
---
## File: docs/skills/cmdline-argument-escaping-bug.md
# 命令行参数特殊字符解析问题
## 问题描述
在 Windows PowerShell 环境中，通过 `ProcessBuilder` 将用户输入作为命令行参数传递给 Node.js 进程时，如果用户输入包含特殊字符（如括号、引号、换行符等），会导致参数被错误解析和拆分。
### 典型错误表现
用户发送包含代码片段的消息：
```go
queryBuild := data.DB.Table("flight_record").
Where("deleted_at is null").
Order(fmt.Sprintf("CASE WHEN inspection_status = %d THEN 0..."))
```
在 Node.js 端收到的参数会被错误拆分：
- `args[0]` (message): 只包含部分消息
- `args[1]` (sessionId): 变成 `"null).\r\n\t\tOrder(fmt.Sprintf(CASE"`
- `args[2]` (cwd): 变成 `"inspection_status"`
### 问题原因
Windows PowerShell 对命令行参数有特殊的解析规则：
1. 括号 `()` 被解释为子表达式
2. 引号 `"` 需要特殊转义
3. 换行符 `\r\n` 会分割参数
4. 百分号 `%` 可能触发变量替换
## 解决方案
**通过 stdin 传递参数，而不是命令行参数。**
### Java 端实现
```java
// 1. 构建 JSON 对象
JsonObject stdinInput = new JsonObject();
stdinInput.addProperty("message", message);
stdinInput.addProperty("sessionId", sessionId);
// ... 其他参数
String stdinJson = gson.toJson(stdinInput);
// 2. 构建命令（不包含用户输入）
List command = new ArrayList<>();
command.add(node);
command.add(scriptPath);
command.add("send"); // 只传固定的命令名称
// 3. 设置环境变量
ProcessBuilder pb = new ProcessBuilder(command);
pb.environment().put("CLAUDE_USE_STDIN", "true");
// 4. 启动进程后写入 stdin
Process process = pb.start();
try (OutputStream stdin = process.getOutputStream()) {
stdin.write(stdinJson.getBytes(StandardCharsets.UTF_8));
stdin.flush();
}
```
### Node.js 端实现
```javascript
// 读取 stdin 数据
async function readStdinData() {
if (process.env.CLAUDE_USE_STDIN !== 'true') {
return null;
}
return new Promise((resolve) => {
let data = '';
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => data += chunk);
process.stdin.on('end', () => {
try {
resolve(JSON.parse(data));
} catch {
resolve(null);
}
});
// 超时回退
setTimeout(() => resolve(null), 100);
});
}
// 使用时
const stdinData = await readStdinData();
if (stdinData && stdinData.message !== undefined) {
// 从 stdin 读取参数
const { message, sessionId, cwd } = stdinData;
} else {
// 向后兼容：从命令行参数读取
const [message, sessionId, cwd] = process.argv.slice(3);
}
```
## 受影响的文件
已修复的文件列表：
| 文件 | 方法/函数 |
|------|-----------|
| `ClaudeSDKBridge.java` | `sendMessageWithChannel()` |
| `ClaudeSDKBridge.java` | `executeQuerySync()` |
| `ClaudeSDKBridge.java` | `executeQueryStream()` |
| `ClaudeSDKTest.java` | `executeQuery()` |
| `channel-manager.js` | `send` 和 `sendWithAttachments` 命令 |
| `simple-query.js` | `getUserPrompt()` |
## 开发注意事项
⚠️ **重要规则**：
1. **永远不要**通过命令行参数传递用户输入的自由文本
2. **始终使用** stdin + JSON 的方式传递可能包含特殊字符的数据
3. 只有固定的、已知安全的值（如命令名称、UUID）可以通过命令行参数传递
4. 新增任何调用 Node.js 脚本的代码时，必须检查是否涉及用户输入
## 复现 Bug 的测试用例
以下消息可以在**未修复版本**中稳定复现此 bug：
### 测试用例 1：包含括号和引号的 Go 代码
```
queryBuild := data.DB.Table("flight_record").Where("deleted_at is null")
```
### 测试用例 2：包含 fmt.Sprintf 的代码
```
fmt.Sprintf("CASE WHEN status = %d THEN 0", constant.StatusRunning)
```
### 测试用例 3：包含换行和缩进的多行代码
```
if err != nil {
return fmt.Errorf("failed: %w", err)
}
```
### 测试用例 4：包含 SQL 语句
```
SELECT * FROM users WHERE name = 'test' AND status IN (1, 2, 3)
```
### 测试用例 5：包含 JSON 字符串
```
{"key": "value", "array": [1, 2, 3]}
```
### 测试用例 6：Windows 路径
```
C:\Users\test\Documents\file (1).txt
```
---
## File: docs/skills/multimodal-permission-bug.md
# 多模态消息权限弹窗失效问题
## 问题描述
当用户发送包含图片的多模态消息时，Claude 在执行工具（如 Write、Bash）时不会弹出权限确认对话框，工具直接执行。而发送纯文本消息时权限弹窗正常工作。
### 表现形式
| 消息类型 | 权限弹窗 | 结果 |
|---------|---------|------|
| 纯文本消息 | ✅ 正常显示 | 用户可以确认或拒绝 |
| 图片+文本消息 | ❌ 不显示 | 工具直接执行，无需确认 |
| 先发图片，AI回复后再发纯文本 | ✅ 正常显示 | 用户可以确认或拒绝 |
## 根本原因
### Claude Agent SDK 的 `query()` 函数签名
```typescript
function query({
prompt,
options
}: {
prompt: string | AsyncIterable;
options?: Options;
}): Query
```
`prompt` 参数有两种模式：
1. **字符串模式** (`string`)：直接传递文本消息
2. **流式模式** (`AsyncIterable`)：用于发送复杂的多模态消息
### 问题所在
**当使用 `AsyncIterable` 作为 `prompt` 时，SDK 的 `canUseTool` 回调不会被触发。**
这是 SDK 在流式输入模式下的一个行为特性（或 bug）。在这种模式下，`options.canUseTool` 虽然被设置，但 SDK 内部不会调用它。
### 代码对比
**纯文本消息（正常工作）：**
```javascript
const result = query({
prompt: message, // string 类型
options: {
canUseTool: canUseTool // ✅ 会被调用
}
});
```
**多模态消息（权限失效）：**
```javascript
const inputStream = new AsyncStream();
inputStream.enqueue(userMessage); // SDKUserMessage 包含图片
inputStream.done();
const result = query({
prompt: inputStream, // AsyncIterable 类型
options: {
canUseTool: canUseTool // ❌ 不会被调用
}
});
```
## 解决方案
使用 **PreToolUse Hook** 替代 `canUseTool` 回调。
SDK 提供了 hooks 机制，其中 `PreToolUse` hook 会在工具执行前被调用，无论 `prompt` 是什么类型。
### 修复代码
```javascript
// PreToolUse hook 用于权限控制
const preToolUseHook = async (input, toolUseID, options) => {
console.log('[HOOK] PreToolUse called:', input.tool_name);
if (normalizedPermissionMode !== 'default') {
return { decision: 'approve' };
}
// 调用原有的 canUseTool 进行权限检查
const result = await canUseTool(input.tool_name, input.tool_input);
if (result.behavior === 'allow') {
return { decision: 'approve' };
} else if (result.behavior === 'deny') {
return {
decision: 'block',
reason: result.message || 'Permission denied'
};
}
return {};
};
const options = {
// ... 其他配置
hooks: {
PreToolUse: [{
hooks: [preToolUseHook]
}]
}
};
```
## 后续开发注意事项
### 1. 多模态消息必须使用 hooks
当需要发送包含图片的消息时，**不要依赖 `canUseTool`**，必须同时配置 `PreToolUse` hook：
```javascript
const options = {
canUseTool: canUseTool, // 可能不生效
hooks: {
PreToolUse: [{ hooks: [preToolUseHook] }] // 必须配置
}
};
```
### 2. Hook 的返回值格式
```typescript
// 允许执行
return { decision: 'approve' };
// 拒绝执行
return { decision: 'block', reason: '拒绝原因' };
// 让 SDK 自行决定（显示默认权限提示）
return {};
```
### 3. Hook 输入参数
```typescript
interface PreToolUseHookInput {
hook_event_name: 'PreToolUse';
tool_name: string; // 工具名称：Write, Bash, Edit 等
tool_input: ToolInput; // 工具参数
session_id: string;
cwd: string;
}
```
### 4. 测试清单
添加多模态功能时，务必测试以下场景：
- [ ] 纯文本消息 + Write 工具 → 权限弹窗
- [ ] 纯文本消息 + Bash 工具 → 权限弹窗
- [ ] 图片+文本消息 + Write 工具 → 权限弹窗
- [ ] 图片+文本消息 + Bash 工具 → 权限弹窗
- [ ] 拒绝权限后工具不执行
## 相关文件
- `claude-bridge/services/message-service.js` - 消息发送逻辑
- `claude-bridge/permission-handler.js` - 权限处理逻辑
- `docs/claude-agent-sdk.md` - SDK 官方文档参考
## 参考资料
- [Claude Agent SDK - Hooks 文档](docs/claude-agent-sdk.md#钩子类型)
- [Claude Agent SDK - CanUseTool 类型](docs/claude-agent-sdk.md#canusetool)
---
## File: docs/skills/SLASH_COMMANDS.md
# 斜杠指令系统 - 完整技术文档
> IDEA 插件版 Claude Code 的斜杠指令（Slash Commands）实现分析
**版本**: v0.1.1
**更新时间**: 2025-12-14
**技术栈**: React + TypeScript + IntelliJ IDEA Plugin
---
## 目录
1. [一句话解释](#一句话解释)
2. [系统架构](#系统架构)
3. [核心流程](#核心流程)
4. [五大核心模块](#五大核心模块)
5. [数据结构定义](#数据结构定义)
6. [关键实现细节](#关键实现细节)
7. [性能优化](#性能优化)
8. [文件映射表](#文件映射表)
9. [常见问题](#常见问题)
---
## 一句话解释
**斜杠指令就是：当用户在输入框行首打 `/` 时，弹出一个命令菜单让用户选择。**
就像你在微信里 `@某人` 会弹出好友列表一样，这里打 `/` 会弹出命令列表。
---
## 系统架构
### 架构拓扑图
```
/* Detailed source-code truncated for AI context efficiency. */
```
### 技术栈
| 层级 | 技术 | 文件位置 |
|-----|------|---------|
| 后端 | Java + IntelliJ SDK | `src/main/java/com/github/claudecodegui/` |
| 桥接 | JCEF Bridge | `ai-bridge/` |
| 前端框架 | React 18 + TypeScript | `webview/src/` |
| 状态管理 | React Hooks | `webview/src/components/ChatInputBox/hooks/` |
| UI 组件 | 自定义 React 组件 | `webview/src/components/ChatInputBox/` |
---
## 核心流程
### 完整数据流程图
```
/* Detailed source-code truncated for AI context efficiency. */
```
### 简化流程图
```
用户输入 "/" (行首)
│
▼
┌─────────────┐
│ 检测到 / │ ← useTriggerDetection
└──────┬──────┘
│
▼
┌─────────────┐
│ 获取命令列表 │ ← slashCommandProvider (缓存 + 后端请求)
└──────┬──────┘
│
▼
┌─────────────┐
│ 弹出下拉菜单 │ ← CompletionDropdown
└──────┬──────┘
│
▼
┌─────────────┐
│ 用户选择命令 │ ← 键盘 ↑↓ 或鼠标点击
└──────┬──────┘
│
▼
┌─────────────┐
│ 替换输入文本 │ ← replaceText()
└──────┬──────┘
│
▼
┌─────────────┐
│ 执行命令 │ ← 用户按回车后发送给后端
└─────────────┘
```
---
## 五大核心模块
用 **餐厅点餐** 来比喻：
| 模块 | 比喻 | 做什么 |
|------|------|--------|
| **触发检测器** | 服务员的眼睛 | 监视用户有没有在行首输入 `/` |
| **命令缓存** | 菜单本 | 存储从后端获取的所有可用命令 |
| **数据提供者** | 后厨传菜员 | 根据用户输入过滤命令，隐藏不适用的命令 |
| **下拉菜单** | 菜单展示板 | 显示可选的命令列表 |
| **键盘导航** | 点餐手势 | 处理上下键和回车选择 |
### 模块 1：触发检测器 (useTriggerDetection)
**位置**: `webview/src/components/ChatInputBox/hooks/useTriggerDetection.ts`
**核心特点**:
- 仅检测**行首**的 `/`（与原 VSCode 版本不同）
- 同时支持 `@` 文件引用触发
```typescript
/**
* 检测 / 斜杠命令触发（仅行首）
*/
function detectSlashTrigger(text: string, cursorPosition: number): TriggerQuery | null {
// 从光标位置向前查找 /
let start = cursorPosition - 1;
while (start >= 0) {
const char = text[start];
// 遇到空格或换行，停止搜索
if (char === ' ' || char === '\t' || char === '\n') {
return null;
}
// 找到 /
if (char === '/') {
// 检查 / 前是否为行首
const isLineStart = start === 0 || text[start - 1] === '\n';
if (isLineStart) {
return {
trigger: '/',
query: text.slice(start + 1, cursorPosition),
start,
end: cursorPosition,
};
}
return null; // / 不在行首
}
start--;
}
return null;
}
```
**检测示例**：
| 输入 | 光标位置 | 检测结果 |
|------|---------|---------|
| `/cle` | 4 | ✓ `{ query: "cle", start: 0 }` |
| `hello /cle` | 10 | ✗ `null` (/ 不在行首) |
| `行1\n/cle` | 6 | ✓ `{ query: "cle", start: 3 }` |
### 模块 2：命令缓存 (slashCommandProvider)
**位置**: `webview/src/components/ChatInputBox/providers/slashCommandProvider.ts`
**核心特点**:
- 从后端接收命令并缓存
- 过滤隐藏命令（IDEA 插件不适用的命令）
- 首次加载显示加载提示
```typescript
/**
* 隐藏的命令列表
* 这些命令是 Claude Code CLI 内置命令，不应在 IDEA 插件中显示
*/
const HIDDEN_COMMANDS = new Set([
'/clear', // 清除对话历史
'/context', // 上下文可视化
'/cost', // 显示费用
'/init', // 初始化 CLAUDE.md
'/pr-comments', // PR 评论
'/release-notes',// 发布说明
'/review', // 审查 PR
'/security-review', // 安全审查
'/todo', // 待办事项
]);
// SDK 命令缓存
let cachedSdkCommands: CommandItem[] = [];
let isInitialLoading = true;
/**
* 斜杠命令数据提供者
*/
export async function slashCommandProvider(
query: string,
signal: AbortSignal
): Promise {
// 确保回调已设置
setupSlashCommandsCallback();
// 如果缓存为空且正在首次加载，请求后端刷新
if (cachedSdkCommands.length < 20 && !refreshRequested && isInitialLoading) {
sendBridgeEvent('refresh_slash_commands');
refreshRequested = true;
}
// 如果缓存为空，返回加载提示
if (cachedSdkCommands.length === 0 && isInitialLoading) {
return [{
id: '__loading__',
label: '正在加载斜杠指令...',
category: 'system',
}];
}
// 过滤隐藏命令和搜索
return filterCommands(cachedSdkCommands, query);
}
```
### 模块 3：数据提供者与转换
**位置**: `webview/src/components/ChatInputBox/providers/slashCommandProvider.ts`
```typescript
/**
* 将 CommandItem 转换为 DropdownItemData
*/
export function commandToDropdownItem(command: CommandItem): DropdownItemData {
return {
id: command.id,
label: command.label,
icon: 'codicon-terminal',
type: 'command',
data: { command },
};
}
```
### 模块 4：下拉菜单 (CompletionDropdown)
**位置**: `webview/src/components/ChatInputBox/Dropdown/`
**关键功能**：
- 位置计算（锚定在 `/` 字符下方）
- 高亮状态管理
- 键盘/鼠标导航模式切换
- 加载状态和空状态显示
### 模块 5：补全管理 (useCompletionDropdown)
**位置**: `webview/src/components/ChatInputBox/hooks/useCompletionDropdown.ts`
**核心功能**：
- 防抖搜索（200ms）
- AbortController 取消请求
- 竞态条件防护
- 键盘事件处理
```typescript
export function useCompletionDropdown({
trigger,
provider,
toDropdownItem,
onSelect,
debounceMs = 200,
}: CompletionDropdownOptions) {
const [state, setState] = useState({...});
// AbortController 用于取消请求
const abortControllerRef = useRef(null);
/**
* 防抖搜索
*/
const debouncedSearch = useCallback((query: string) => {
if (debounceTimerRef.current) {
clearTimeout(debounceTimerRef.current);
}
debounceTimerRef.current = window.setTimeout(() => {
search(query);
}, debounceMs);
}, [search, debounceMs]);
/**
* 处理键盘事件
*/
const handleKeyDown = useCallback((e: KeyboardEvent): boolean => {
if (!currentState.isOpen) return false;
switch (e.key) {
case 'ArrowDown':
e.preventDefault();
setState(prev => ({
...prev,
activeIndex: (prev.activeIndex + 1) % selectableCount,
}));
return true;
case 'ArrowUp':
e.preventDefault();
setState(prev => ({
...prev,
activeIndex: (prev.activeIndex - 1 + selectableCount) % selectableCount,
}));
return true;
case 'Enter':
case 'Tab':
e.preventDefault();
selectActive();
return true;
case 'Escape':
e.preventDefault();
close();
return true;
}
return false;
}, [selectActive, close]);
return {
isOpen: state.isOpen,
items: state.items,
activeIndex: state.activeIndex,
// ...
handleKeyDown,
selectActive,
};
}
```
---
## 数据结构定义
### TriggerQuery (触发查询)
```typescript
interface TriggerQuery {
trigger: string; // 触发符，'/' 或 '@'
query: string; // 查询文本 (不包括触发符)
start: number; // 触发符在文本中的位置
end: number; // 查询结束位置（光标位置）
}
// 示例：
// 输入: "/workflow"
// TriggerQuery: { trigger: '/', query: 'workflow', start: 0, end: 9 }
```
### CommandItem (命令项)
```typescript
interface CommandItem {
id: string; // 命令 ID
label: string; // 显示标签，如 "/workflow:plan"
category: string; // 分类: 'workflow', 'memory', 'task', 'user' 等
}
```
### DropdownItemData (下拉项)
```typescript
interface DropdownItemData {
id: string;
label: string;
description?: string;
icon?: string;
type: 'command' | 'file' | 'separator' | 'section-header';
data?: any;
}
```
### DropdownPosition (位置)
```typescript
interface DropdownPosition {
top: number;
left: number;
width: number;
height: number;
}
```
---
## 关键实现细节
### 1. 行首检测（与 VSCode 版本的区别）
**原 VSCode 版本**：
- 使用正则 `(?:^|\s)/[^\s/]*` 匹配行首或空格后的 `/`
**IDEA 插件版本**：
- 仅检测**行首**的 `/`
- 空格后的 `/` 不会触发
```typescript
// 检查 / 前是否为行首
const isLineStart = start === 0 || text[start - 1] === '\n';
if (isLineStart) {
return { trigger: '/', query, start, end };
}
return null; // / 不在行首
```
### 2. 命令过滤
IDEA 插件会过滤掉不适用的命令：
```typescript
const HIDDEN_COMMANDS = new Set([
'/clear', // 在 IDEA 中无意义
'/context', // CLI 特定功能
'/cost', // CLI 特定功能
'/init', // CLI 特定功能
'/pr-comments', // CLI 特定功能
'/release-notes',// CLI 特定功能
'/review', // CLI 特定功能
'/security-review', // CLI 特定功能
'/todo', // CLI 特定功能
]);
```
### 3. 后端通信机制
```typescript
// 前端发送请求
sendBridgeEvent('refresh_slash_commands');
// 后端返回数据（通过 JCEF Bridge）
window.updateSlashCommands(jsonString);
// 前端注册回调
window.updateSlashCommands = (json: string) => {
const commands = JSON.parse(json);
cachedSdkCommands = commands.map(cmd => ({...}));
};
```
### 4. 防抖与取消
```typescript
// 1. 清除之前的定时器
if (debounceTimerRef.current) {
clearTimeout(debounceTimerRef.current);
}
// 2. 取消之前的请求
if (abortControllerRef.current) {
abortControllerRef.current.abort();
}
// 3. 设置新的定时器
debounceTimerRef.current = window.setTimeout(() => {
abortControllerRef.current = new AbortController();
search(query);
}, 200);
```
---
## 性能优化
| 优化 | 位置 | 效果 |
|-----|------|------|
| **防抖 (200ms)** | `useCompletionDropdown.ts` | 减少搜索次数 |
| **AbortController** | `useCompletionDropdown.ts` | 取消前一个请求 |
| **命令缓存** | `slashCommandProvider.ts` | 避免重复请求后端 |
| **首次加载提示** | `slashCommandProvider.ts` | 改善用户体验 |
| **导航模式隔离** | `useCompletionDropdown.ts` | 减少不必要的样式更新 |
---
## 文件映射表
| 功能 | 文件位置 |
|-----|---------|
| **主组件** | `webview/src/components/ChatInputBox/ChatInputBox.tsx` |
| **触发检测** | `webview/src/components/ChatInputBox/hooks/useTriggerDetection.ts` |
| **补全管理** | `webview/src/components/ChatInputBox/hooks/useCompletionDropdown.ts` |
| **斜杠命令提供者** | `webview/src/components/ChatInputBox/providers/slashCommandProvider.ts` |
| **文件引用提供者** | `webview/src/components/ChatInputBox/providers/fileReferenceProvider.ts` |
| **下拉菜单组件** | `webview/src/components/ChatInputBox/Dropdown/` |
| **类型定义** | `webview/src/components/ChatInputBox/types.ts` |
| **样式** | `webview/src/components/ChatInputBox/styles.css` |
| **Java 后端桥接** | `src/main/java/com/github/claudecodegui/ClaudeSDKBridge.java` |
| **命令缓存** | `src/main/java/com/github/claudecodegui/cache/SlashCommandCache.java` |
---
## 常见问题
### Q1: 为什么只在行首触发？
**A**: IDEA 插件版本设计为仅在行首触发斜杠命令，这与 VSCode 版本不同。这是为了：
1. 避免在输入路径时误触发（如 `/Users/...`）
2. 更符合命令行的使用习惯
### Q2: 为什么有些命令被隐藏？
**A**: `HIDDEN_COMMANDS` 中的命令是 Claude Code CLI 的内置命令，它们在 IDEA 插件环境中：
- 没有意义（如 `/clear` 清除 CLI 历史）
- 不可用（如 `/pr-comments` 需要 Git 集成）
- 由 IDEA 提供替代方案
### Q3: 首次加载为什么需要时间？
**A**: 首次加载时需要：
1. 通过 JCEF Bridge 向 Java 后端发送请求
2. Java 后端调用 Claude SDK 获取命令列表
3. 命令列表通过 Bridge 返回前端
4. 前端缓存命令以供后续使用
后续使用会直接使用缓存，无需等待。
### Q4: 如何添加新的斜杠命令？
**A**: 斜杠命令来自 Claude SDK，由用户的 `.claude/commands/` 目录定义。插件会自动加载这些命令。
如果要在前端过滤或修改命令显示：
1. 编辑 `slashCommandProvider.ts` 中的 `HIDDEN_COMMANDS`
2. 或修改 `commandToDropdownItem()` 函数
### Q5: 键盘导航支持哪些按键？
| 按键 | 功能 |
|------|------|
| `↓` | 选择下一项 |
| `↑` | 选择上一项 |
| `Enter` | 确认选择 |
| `Tab` | 确认选择 |
| `Escape` | 关闭菜单 |
---
## 总结
IDEA 插件版的斜杠指令系统是一个**模块化设计**：
1. **触发检测**: 独立的检测逻辑，仅行首触发 ✓
2. **命令缓存**: 从后端获取并缓存命令 ✓
3. **命令过滤**: 隐藏不适用的 CLI 命令 ✓
4. **补全管理**: 通用的下拉菜单管理器 ✓
5. **键盘导航**: 独立的导航处理 ✓
6. **UI 组件**: 完全解耦的显示层 ✓
这个架构使得添加新功能（如标签补全、代码片段等）变得非常简单。
---
*文档最后更新: 2025-12-14*
*项目版本: v0.1.1*
---
## File: docs/skills/tempdir-permission-sync.md
# Claude 临时目录与权限通道改进说明
## 背景
此前 `claude-agent-sdk` 会在运行 `Bash`/`Write` 等工具时：
- 把当前 `process.cwd()` 作为临时目录根路径并生成 `claude-xxxx-cwd` 标记文件；
- 在 `TMPDIR/claude-permission/` 下与 IDE 交换权限请求。
这会带来两个问题：
1. 项目根目录持续出现大量 `claude-*-cwd` 文件，影响使用体验；
2. 若我们把 `TMPDIR` 改到其它位置，Node 侧的 `permission-handler` 与 Java 侧 `PermissionService` 将监听不同目录，最终导致所有写入请求超时并被默认拒绝。
## 改动概览
### 1. 定制临时目录
- 在 `ClaudeSDKBridge` 启动任何 Node 子进程时，统一创建 `System.getProperty("java.io.tmpdir")/claude-agent-tmp`，并通过 `TMPDIR/TEMP/TMP` 环境变量强制使用该目录；
- 记录进程前后的 `claude-*-cwd` 文件，待进程结束后只保留原有文件，其余全部清理。
这样 IDE 项目目录不再出现无意义的临时标记文件，真实的临时数据会集中在系统 `tmp` 目录下，并在每次任务结束时自动回收。
### 2. 同步权限通道目录
- 新增 `CLAUDE_PERMISSION_DIR` 环境变量，并在 `updateProcessEnvironment` 中默认指向 `System.getProperty("java.io.tmpdir")/claude-permission`；
- `claude-bridge/permission-handler.js` 读取该变量，若不存在则回退到 `os.tmpdir()`；
- Java 端的 `PermissionService` 依然监听系统 `tmp/claude-permission`，因此 Node/Java 再次共享同一个通信目录，权限弹窗能正常弹出。
## 使用方式
1. **无需额外配置**：安装新版插件后自动启用上述逻辑；
2. **自定义路径**（可选）：若想把权限目录指向其它位置，可在 IDE 进程环境中设置 `CLAUDE_PERMISSION_DIR=/your/path/claude-permission`，Node 侧会按此目录写入，Java 侧同步读取；
3. **验证**：
- 运行任意会写文件的指令（例如 “创建 hello.js”），应能看到权限弹窗；
- 权限通过后，文件应成功写入，且项目根目录不再出现 `claude-*-cwd`；
- 系统 `tmp/claude-agent-tmp` 目录中的残留文件会在指令结束后清理；若需排查，可手动查看该目录。
## 相关文件
- `src/main/java/com/github/claudecodegui/ClaudeSDKBridge.java`：负责设置 `TMPDIR`、清理临时文件、注入 `CLAUDE_PERMISSION_DIR`；
- `claude-bridge/permission-handler.js`：读取 `CLAUDE_PERMISSION_DIR` 并在该目录下与 Java 交互；
- `src/main/java/com/github/claudecodegui/permission/PermissionService.java`：继续监听系统 `tmp/claude-permission` 目录（无需修改）。
如需进一步扩展（例如把权限记录持久化到项目目录），可以基于 `CLAUDE_PERMISSION_DIR` 再封装自定义路径逻辑。
---
## File: docs/skills/windows-cli-path-bug.md
# Windows 下 Claude CLI 路径问题
## 问题描述
在 Windows 环境下，插件启动时会报错：
```
process exited with code 1
```
日志显示 ENOENT 错误：
```
[Node.js] [DEBUG] Error in message loop: Failed to spawn Claude Code process: spawn D:\Apps\Scoop\apps\nvm\current\nodejs\nodejs\claude ENOENT
```
## 问题原因
### 1. `where claude` 命令返回的路径问题
在 Windows 上，`where claude` 命令会返回多个匹配结果：
```
D:\Apps\Scoop\apps\nvm\current\nodejs\nodejs\claude
D:\Apps\Scoop\apps\nvm\current\nodejs\nodejs\claude.cmd
```
原代码取第一个结果 `claude`（无扩展名），但这个路径：
- 在 Windows 上**不能直接被 `spawn()` 执行**
- 它实际上是一个 shim 文件，需要通过 `.cmd` 包装器来调用
- 直接 spawn 会导致 `ENOENT`（文件不存在）错误
### 2. SDK 的 spawn 机制
Claude Agent SDK 使用 Node.js 的 `child_process.spawn()` 来启动 CLI 进程。在 Windows 上：
- `.cmd` 文件可以通过 `shell: true` 选项执行
- 但无扩展名的 shim 文件无法直接执行
## 解决方案
**完全使用 SDK 内置的 cli.js，不再查找系统安装的 Claude CLI。**
SDK 内置了官方 CLI：
- 路径：`node_modules/@anthropic-ai/claude-agent-sdk/cli.js`
- 这是 Anthropic 官方 Claude Code CLI 的 Node 版本
- 当不传递 `pathToClaudeCodeExecutable` 选项时，SDK 会自动使用它
### 修改内容
#### 1. `claude-bridge/services/message-service.js`
移除 `getClaudeCliPath` 相关代码：
```javascript
// 之前
import { mapModelIdToSdkName, getClaudeCliPath } from '../utils/model-utils.js';
const claudeCliPath = getClaudeCliPath();
const options = {
// ...
pathToClaudeCodeExecutable: claudeCliPath,
};
// 之后
import { mapModelIdToSdkName } from '../utils/model-utils.js';
const options = {
// ...
// 不传递 pathToClaudeCodeExecutable，SDK 将自动使用内置 cli.js
};
```
#### 2. `claude-bridge/utils/model-utils.js`
删除整个 `getClaudeCliPath()` 函数（约 60 行代码），包括：
- `where claude` / `which claude` 命令调用
- 常见路径检测逻辑
- 相关的 `fs` 和 `child_process` import
## 使用内置 CLI 的优点
1. **跨平台最稳定**：不依赖 `where`/`which` 等平台相关命令
2. **版本对齐**：CLI 版本与 SDK 完全一致，避免兼容性问题
3. **自定义 Base URL 仍然有效**：SDK 会继承 `process.env` 中的 `ANTHROPIC_BASE_URL`
4. **配置来源一致**：内置 CLI 同样读取 `~/.claude/settings.json`
## 注意事项
- 如果将来需要支持"使用系统 CLI"的高级选项，需要在 Windows 上：
- 优先选择 `.cmd` 结尾的路径
- 或者使用 `shell: true` 选项执行
- 当前方案是最简单可靠的修复，适用于大多数用户场景
---
## File: docs/sdk/claude-agent-sdk.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.
## Installation
```bash theme={null}
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. 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
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:
```typescript theme={null}
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
### `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;
options?: Options;
}): Query;
```
#### 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 a [`Query`](#query-object) object that extends `AsyncGenerator<`[`SDKMessage`](#sdkmessage)`, 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`](#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.
```typescript theme={null}
function startup(params?: {
options?: Options;
initializeTimeoutMs?: number;
}): Promise;
```
#### 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`](#warmquery)`>` 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(
name: string,
inputSchema: Schema,
handler: (args: InferShape, extra: unknown) => Promise,
extras?: { annotations?: ToolAnnotations }
): SdkMcpToolDefinition;
```
#### 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)` }` | 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>;
}): McpSdkServerConfigWithInstance;
```
#### Parameters
| Parameter | Type | Description |
| :---------------- | :---------------------------- | :------------------------------------------------------- |
| `options.name` | `string` | The name of the MCP server |
| `options.version` | `string` | Optional version string |
| `options.tools` | `Array` | 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;
```
#### 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()`](#tagsession)) |
| `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;
```
#### 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` | `string \| null` | For subagent messages, the `tool_use_id` of the spawning `Agent` tool call. `null` for main-session messages and older sessions |
#### 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;
```
#### 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()`
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;
```
#### 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;
```
#### 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()`
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.
```typescript theme={null}
function resolveSettings(
options?: ResolveSettingsOptions
): Promise;
```
#### 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. Managed policy settings load in all cases |
| `options.managedSettings` | `Settings` | `undefined` | Restrictive policy-tier settings supplied by the embedding host. Dropped by default when an admin-deployed managed tier is present; merged under that tier when [`parentSettingsBehavior`](/en/settings#available-settings) is `"merge"`. Non-restrictive keys such as `model` are silently dropped so this option can tighten managed policy but not loosen it |
| `options.serverManagedSettings` | `Settings` | `undefined` | Server-managed settings payload from `/api/claude_code/settings`. Non-restrictive keys pass through unfiltered |
#### 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
The example below resolves settings for a project directory and prints the source that controls the cleanup period.
```typescript theme={null}
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
### `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](/en/agent-sdk/permissions#allow-and-deny-rules) |
| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | Enable beta features |
| `canUseTool` | [`CanUseTool`](#canusetool) | `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 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](/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](/en/model-config#adjust-effort-level) |
| `enableFileCheckpointing` | `boolean` | `false` | Enable file change tracking for rewinding. See [File checkpointing](/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](/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 |
| `hooks` | `Partial>` | `{}` | Hook callbacks for events |
| `includeHookEvents` | `boolean` | `false` | Include hook lifecycle events in the message stream as [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage), and [`SDKHookResponseMessage`](#sdkhookresponsemessage) |
| `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 supplied by the spawning parent process. Dropped when an IT-controlled managed-settings tier already exists on the machine, unless that admin opts in with `parentSettingsBehavior: 'merge'`. Filtered to restrictive-only keys regardless |
| `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` | `{}` | MCP server configurations |
| `model` | `string` | Default from CLI | Claude model alias or full model name. See [accepted values and provider-specific IDs](/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](/en/agent-sdk/structured-outputs) for details |
| `outputStyle` | `string` | `undefined` | Not an `Options` field. Set `outputStyle` in the inline [`settings`](/en/settings) object or a settings file instead. See [Activate an output style](/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](/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`](/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](/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](/en/settings) object or path to a settings file. Populates the flag-settings layer in the [precedence order](/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. Managed policy settings load regardless. See [Use Claude Code features](/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](/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](/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](/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
The CLI subprocess reads several environment variables that control API timeouts and stall detection. Pass them through the `env` option:
```typescript theme={null}
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`. 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.
* `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=1` with `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: aborts the request when headers have arrived but the response body stops streaming. When `CLAUDE_ENABLE_STREAM_WATCHDOG` is unset, the default is server-controlled on the direct Anthropic API and off on other providers. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` defaults to `300000` and is clamped to that minimum. The aborted request goes through the normal retry path.
### `Query` object
Interface returned by the `query()` function.
```typescript theme={null}
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;
supportedCommands(): Promise;
supportedModels(): Promise;
supportedAgents(): Promise;
mcpServerStatus(): 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
| 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 |
| `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 |
| `supportedCommands()` | Returns available slash commands |
| `supportedModels()` | Returns available models with display info |
| `supportedAgents()` | Returns available subagents as [`AgentInfo`](#agentinfo)`[]` |
| `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 |
#### `applyFlagSettings()`
Changes [settings](/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**: `model`, `effortLevel`, `ultracode`, `permissions`, `hooks`, `skillOverrides`, `fastMode`, `awaySummaryEnabled`, `agent`. Switching `agent` also applies that agent's model override, hooks, and system prompt on 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.
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](/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.
```typescript theme={null}
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`
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): 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";
};
```
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, so read this array to surface in-flight permission prompts immediately; they will not be re-sent.
### `AgentDefinition`
Configuration for a subagent defined programmatically.
```typescript theme={null}
type AgentDefinition = {
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. 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 |
| `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`
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;
```
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 (not version controlled) | `.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`, `allowedTools`, and `settings` 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 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"; // 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,
options: {
signal: AbortSignal;
suggestions?: PermissionUpdate[];
blockedPath?: string;
decisionReason?: string;
toolUseID: string;
agentID?: 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 |
### `PermissionResult`
Result of a permission check.
```typescript theme={null}
type PermissionResult =
| {
behavior: "allow";
updatedInput?: Record;
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;
};
```
#### `McpSSEServerConfig`
```typescript theme={null}
type McpSSEServerConfig = {
type: "sse";
url: string;
headers?: Record;
};
```
#### `McpHttpServerConfig`
```typescript theme={null}
type McpHttpServerConfig = {
type: "http";
url: string;
headers?: Record;
};
```
#### `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
| SDKSessionStateChangedMessage
| SDKCommandsChangedMessage
| SDKNotificationMessage
| SDKFilesPersistedEvent
| SDKToolUseSummaryMessage
| SDKMemoryRecallMessage
| SDKRateLimitEvent
| SDKElicitationCompleteMessage
| SDKPermissionDeniedMessage
| SDKPromptSuggestionMessage
| SDKAPIRetryMessage
| SDKMirrorErrorMessage;
```
### `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`](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.
### `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;
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.
### `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;
origin?: SDKMessageOrigin;
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;
api_error_status?: number | null;
num_turns: number;
result: string;
stop_reason: string | null;
ttft_ms?: number;
ttft_stream_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;
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;
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.
* `terminal_reason`: why the loop ended. One of `"completed"`, `"max_turns"`, `"tool_deferred"`, `"aborted_streaming"`, `"aborted_tools"`, `"hook_stopped"`, `"stop_hook_prevented"`, `"blocking_limit"`, `"rapid_refill_breaker"`, `"prompt_too_long"`, `"image_error"`, or `"model_error"`.
* `fast_mode_state`: one of `"on"`, `"off"`, or `"cooldown"`.
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](/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;
ttft_ms?: number; // Time to first token in ms, present only on message_start events
};
```
### `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`](/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`.
```typescript theme={null}
type SDKPluginInstallMessage = {
type: "system";
subtype: "plugin_install";
status: "started" | "installed" | "failed" | "completed";
name?: string;
error?: string;
uuid: UUID;
session_id: string;
};
```
### `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.
```typescript theme={null}
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`
Information about a denied tool use.
```typescript theme={null}
type SDKPermissionDenial = {
tool_name: string;
tool_use_id: string;
tool_input: Record;
};
```
### `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.
```typescript theme={null}
type SDKMessageOrigin =
| { kind: "human" }
| { kind: "channel"; server: string }
| { kind: "peer"; from: string; name?: string }
| { kind: "task-notification" }
| { kind: "coordinator" };
```
| `kind` | Meaning |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `human` | Direct input from the end user. On user messages, an absent `origin` also means human input. |
| `channel` | Message arriving on a [channel](/en/channels). `server` is the source MCP server name. |
| `peer` | Message from another agent session via `SendMessage`. `from` is the sender address; `name` is the sender's display name when available. |
| `task-notification` | Synthetic turn injected after a background task finished. See [`SDKTaskNotificationMessage`](#sdktasknotificationmessage). |
| `coordinator` | Message from a team coordinator in an [agent team](/en/agent-teams). |
## 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"
| "MessageDisplay";
```
### `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;
```
### `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
| MessageDisplayHookInput;
```
### `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;
effort?: { level: 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;
background_tasks?: BackgroundTaskSummary[];
session_crons?: SessionCronSummary[];
};
```
#### `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;
background_tasks?: BackgroundTaskSummary[];
session_crons?: SessionCronSummary[];
};
type BackgroundTaskSummary = {
id: string;
type: string;
status: string;
command?: string;
agent_type?: string;
server?: string;
tool?: string;
name?: string;
};
type SessionCronSummary = {
id: string;
schedule: string;
recurring: boolean;
prompt: 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;
};
```
#### `MessageDisplayHookInput`
```typescript theme={null}
type MessageDisplayHookInput = BaseHookInput & {
hook_event_name: "MessageDisplay";
turn_id: string;
message_id: string;
index: number;
final: boolean;
delta: 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;
additionalContext?: string;
}
| {
hookEventName: "UserPromptSubmit";
additionalContext?: string;
}
| {
hookEventName: "SessionStart";
additionalContext?: string;
}
| {
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: "Notification";
additionalContext?: string;
}
| {
hookEventName: "PermissionRequest";
decision:
| {
behavior: "allow";
updatedInput?: Record;
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
| TaskCreateInput
| TaskGetInput
| TaskListInput
| TaskStopInput
| TaskUpdateInput
| TodoWriteInput
| UnsubscribeMcpResourceInput
| UnsubscribePollingInput
| WebFetchInput
| WebSearchInput
| WorkflowInput;
```
### Agent
**Tool name:** `Agent` (previously `Task`, which is still accepted as an alias)
```typescript theme={null}
type AgentInput = {
prompt: string;
subagent_type: string;
model?: "sonnet" | "opus" | "haiku" | "fable";
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;
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.
### Workflow
**Tool name:** `Workflow`
```typescript theme={null}
type WorkflowInput = {
script?: string;
name?: string;
scriptPath?: string;
args?: unknown;
resumeFromRunId?: string;
};
```
Runs a [dynamic workflow](/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, phases }` as a literal, followed by the script body using `agent()`, `parallel()`, `pipeline()`, and `phase()` |
| `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 return cached results; only changed or new calls run live. Same session only |
### 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.
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](/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
**Tool name:** `TaskCreate`
```typescript theme={null}
type TaskCreateInput = {
subject: string;
activeForm?: string;
metadata?: Record;
};
```
Creates a single task and returns its assigned ID.
### TaskUpdate
**Tool name:** `TaskUpdate`
```typescript theme={null}
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
**Tool name:** `TaskGet`
```typescript theme={null}
type TaskGetInput = {
taskId: string;
};
```
Returns full details for one task, or `null` when the ID is not found.
### TaskList
**Tool name:** `TaskList`
```typescript theme={null}
type TaskListInput = {};
```
Returns a snapshot of all tasks in the current list.
### 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:** `ListMcpResourcesTool`
```typescript theme={null}
type ListMcpResourcesInput = {
server?: string;
};
```
Lists available MCP resources from connected servers.
### ReadMcpResource
**Tool name:** `ReadMcpResourceTool`
```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
| TaskCreateOutput
| TaskGetOutput
| TaskListOutput
| TaskStopOutput
| TaskUpdateOutput
| TodoWriteOutput
| WebFetchOutput
| WebSearchOutput
| WorkflowOutput;
```
### 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;
prompt: string;
outputFile: string;
canReadOutputFile?: boolean;
}
| {
status: "sub_agent_entered";
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;
response?: string;
};
```
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
**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.
### Workflow
**Tool name:** `Workflow`
```typescript theme={null}
type WorkflowOutput = {
status: "async_launched";
taskId: string;
runId?: string;
summary?: string;
transcriptDir?: string;
scriptPath?: 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"` | The tool accepted the invocation. This is the only value the field takes |
| `taskId` | `string` | Background task identifier for the run |
| `runId` | `string` | Workflow run identifier to pass as `resumeFromRunId` on a later invocation |
| `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 |
| `error` | `string` | Set when the script fails its syntax check. When present, the run did not start despite the `async_launched` status |
### 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.
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](/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
**Tool name:** `TaskCreate`
```typescript theme={null}
type TaskCreateOutput = {
task: {
id: string;
subject: string;
};
};
```
Returns the created task with its assigned ID.
### TaskUpdate
**Tool name:** `TaskUpdate`
```typescript theme={null}
type TaskUpdateOutput = {
success: boolean;
taskId: string;
updatedFields: string[];
error?: string;
statusChange?: {
from: string;
to: string;
};
};
```
Returns the update result, including which fields changed.
### TaskGet
**Tool name:** `TaskGet`
```typescript theme={null}
type TaskGetOutput = {
task: {
id: string;
subject: 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
**Tool name:** `TaskList`
```typescript theme={null}
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
**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:** `ListMcpResourcesTool`
```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:** `ReadMcpResourceTool`
```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" // Local project 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";
```
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, 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`
Information about an available slash command.
```typescript theme={null}
type SlashCommand = {
name: string;
argumentHint: string;
aliases?: string[];
};
```
### `ModelInfo`
Information about an available model.
```typescript theme={null}
type ModelInfo = {
value: string;
displayName: 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;
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`](#mcpserverconfig) 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`
Token usage statistics. This is the `BetaUsage` type from `@anthropic-ai/sdk`.
```typescript theme={null}
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`
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](/en/agent-sdk/custom-tools#return-structured-data).
```typescript theme={null}
type CallToolResult = {
content: Array<{
type: "text" | "image" | "audio" | "resource" | "resource_link";
// Additional fields vary by type
}>;
structuredContent?: Record;
isError?: boolean;
};
```
### `ThinkingConfig`
Controls Claude's thinking/reasoning behavior. Takes precedence over the deprecated `maxThinkingTokens`.
```typescript theme={null}
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.
### `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;
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`
Result of a `setMcpServers()` operation.
```typescript theme={null}
type McpSetServersResult = {
added: string[];
removed: string[];
errors: Record;
};
```
### `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;
task_type?: string;
uuid: UUID;
session_id: string;
};
```
### `SDKTaskProgressMessage`
Emitted periodically while a subagent or background task is running. The `summary` field is populated only when [`agentProgressSummaries`](#options) is enabled.
```typescript theme={null}
type SDKTaskProgressMessage = {
type: "system";
subtype: "task_progress";
task_id: string;
tool_use_id?: 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`
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;
};
```
### `SDKCommandsChangedMessage`
Emitted when the set of available commands changes mid-session, such as when skills are discovered 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()` again is not equivalent: that method returns the snapshot captured at initialization and does not reflect mid-session changes.
```typescript theme={null}
type SDKCommandsChangedMessage = {
type: "system";
subtype: "commands_changed";
commands: SlashCommand[];
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;
failIfUnavailable?: boolean;
autoAllowBashIfSandboxed?: boolean;
excludedCommands?: string[];
allowUnsandboxedCommands?: boolean;
network?: SandboxNetworkConfig;
filesystem?: SandboxFilesystemConfig;
ignoreViolations?: Record;
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` | `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`, then stops. Watch for that subtype rather than expecting `query()` to throw before yielding messages.
To run unsandboxed instead, set `failIfUnavailable: false`.
#### 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);
}
```
**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. 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](/en/permissions#webfetch) instead.
```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` | Managed-settings only. When set in [managed settings](/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](/en/sandboxing#security-limitations) for details and [Secure deployment](/en/agent-sdk/secure-deployment#traffic-forwarding) for configuring a TLS-terminating proxy.
### `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.
**`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.
```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
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](/en/agent-sdk/permissions#how-permissions-are-evaluated) still forces one). This combination effectively allows the model to escape sandbox isolation silently.
## See also
* [SDK overview](/en/agent-sdk/overview) - General SDK concepts
* [Python SDK reference](/en/agent-sdk/python) - Python SDK documentation
* [CLI reference](/en/cli-reference) - Command-line interface
* [Common workflows](/en/common-workflows) - Step-by-step guides
---
## File: docs/sdk/claude-sdk-permissions.md
# Handling Permissions
Control tool usage and permissions in the Claude Agent SDK
---
# SDK Permissions
The Claude Agent SDK provides powerful permission controls that allow you to manage how Claude uses tools in your application.
This guide covers how to implement permission systems using the `canUseTool` callback, hooks, and settings.json permission rules. For complete API documentation, see the [TypeScript SDK reference](/docs/en/agent-sdk/typescript).
## Overview
The Claude Agent SDK provides four complementary ways to control tool usage:
1. **[Permission Modes](#permission-modes)** - Global permission behavior settings that affect all tools
2. **[canUseTool callback](/docs/en/agent-sdk/typescript#canusetool)** - Runtime permission handler for cases not covered by other rules
3. **[Hooks](/docs/en/agent-sdk/hooks)** - Fine-grained control over every tool execution with custom logic
4. **[Permission rules (settings.json)](https://code.claude.com/docs/en/settings#permission-settings)** - Declarative allow/deny rules with integrated bash command parsing
Use cases for each approach:
- Permission modes - Set overall permission behavior (planning, auto-accepting edits, bypassing checks)
- `canUseTool` - Dynamic approval for uncovered cases, prompts user for permission
- Hooks - Programmatic control over all tool executions
- Permission rules - Static policies with intelligent bash command parsing
## Permission Flow Diagram
```mermaid
flowchart TD
Start([Tool request]) --> PreHook(PreToolUse Hook)
PreHook -->| Allow | Execute(Execute Tool)
PreHook -->| Deny | Denied(Denied)
PreHook -->| Ask | Callback(canUseTool Callback)
PreHook -->| Continue | Deny(Check Deny Rules)
Deny -->| Match | Denied
Deny -->| No Match | Allow(Check Allow Rules)
Allow -->| Match | Execute
Allow -->| No Match | Ask(Check Ask Rules)
Ask -->| Match | Callback
Ask -->| No Match | Mode{Permission Mode?}
Mode -->| bypassPermissions | Execute
Mode -->| Other modes | Callback
Callback -->| Allow | Execute
Callback -->| Deny | Denied
Denied --> DeniedResponse([Feedback to agent])
Execute --> PostHook(PostToolUse Hook)
PostHook --> Done([Tool Response])
```
**Processing Order:** PreToolUse Hook → Deny Rules → Allow Rules → Ask Rules → Permission Mode Check → canUseTool Callback → PostToolUse Hook
## 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 four permission modes, each with different behavior:
| Mode | Description | Tool Behavior |
| :--- | :---------- | :------------ |
| `default` | Standard permission behavior | Normal permission checks apply |
| `plan` | Planning mode - no execution | Claude can only use read-only tools; presents a plan before execution **(Not currently supported in SDK)** |
| `acceptEdits` | Auto-accept file edits | File edits and filesystem operations are automatically approved |
| `bypassPermissions` | Bypass all permission checks | All tools run without permission prompts (use with caution) |
### Setting Permission Mode
You can set the permission mode in two ways:
#### 1. Initial Configuration
Set the mode when creating a query:
```typescript TypeScript
import { query } from "@anthropic-ai/claude-agent-sdk";
const result = await query({
prompt: "Help me refactor this code",
options: {
permissionMode: 'default' // Standard permission mode
}
});
```
```python Python
from claude_agent_sdk import query
result = await query(
prompt="Help me refactor this code",
options={
"permission_mode": "default" # Standard permission mode
}
)
```
#### 2. Dynamic Mode Changes (Streaming Only)
Change the mode during a streaming session:
```typescript TypeScript
import { query } from "@anthropic-ai/claude-agent-sdk";
// Create an async generator for streaming input
async function* streamInput() {
yield {
type: 'user',
message: {
role: 'user',
content: "Let's start with default permissions"
}
};
// Later in the conversation...
yield {
type: 'user',
message: {
role: 'user',
content: "Now let's speed up development"
}
};
}
const q = query({
prompt: streamInput(),
options: {
permissionMode: 'default' // Start in default mode
}
});
// Change mode dynamically
await q.setPermissionMode('acceptEdits');
// Process messages
for await (const message of q) {
console.log(message);
}
```
```python Python
from claude_agent_sdk import query
async def stream_input():
"""Async generator for streaming input"""
yield {
"type": "user",
"message": {
"role": "user",
"content": "Let's start with default permissions"
}
}
# Later in the conversation...
yield {
"type": "user",
"message": {
"role": "user",
"content": "Now let's speed up development"
}
}
q = query(
prompt=stream_input(),
options={
"permission_mode": "default" # Start in default mode
}
)
# Change mode dynamically
await q.set_permission_mode("acceptEdits")
# Process messages
async for message in q:
print(message)
```
### Mode-Specific Behaviors
#### Accept Edits Mode (`acceptEdits`)
In accept edits mode:
- All file edits are automatically approved
- Filesystem operations (mkdir, touch, rm, etc.) are auto-approved
- Other tools still require normal permissions
- Speeds up development when you trust Claude's edits
- Useful for rapid prototyping and iterations
Auto-approved operations:
- File edits (Edit, Write tools)
- Bash filesystem commands (mkdir, touch, rm, mv, cp)
- File creation and deletion
#### Bypass Permissions Mode (`bypassPermissions`)
In bypass permissions mode:
- **ALL tool uses are automatically approved**
- No permission prompts appear
- Hooks still execute (can still block operations)
- **Use with extreme caution** - Claude has full system access
- Recommended only for controlled environments
### Mode Priority in Permission Flow
Permission modes are evaluated at a specific point in the permission flow:
1. **Hooks execute first** - Can allow, deny, ask, or continue
2. **Deny rules** are checked - Block tools regardless of mode
3. **Allow rules** are checked - Permit tools if matched
4. **Ask rules** are checked - Prompt for permission if matched
5. **Permission mode** is evaluated:
- **`bypassPermissions` mode** - If active, allows all remaining tools
- **Other modes** - Defer to `canUseTool` callback
6. **`canUseTool` callback** - Handles remaining cases
This means:
- Hooks can always control tool use, even in `bypassPermissions` mode
- Explicit deny rules override all permission modes
- Ask rules are evaluated before permission modes
- `bypassPermissions` mode overrides the `canUseTool` callback for unmatched tools
### Best Practices
1. **Use default mode** for controlled execution with normal permission checks
2. **Use acceptEdits mode** when working on isolated files or directories
3. **Avoid bypassPermissions** in production or on systems with sensitive data
4. **Combine modes with hooks** for fine-grained control
5. **Switch modes dynamically** based on task progress and confidence
Example of mode progression:
```typescript
// Start in default mode for controlled execution
permissionMode: 'default'
// Switch to acceptEdits for rapid iteration
await q.setPermissionMode('acceptEdits')
```
## canUseTool
The `canUseTool` callback is passed as an option when calling the `query` function. It receives the tool name and input parameters, and must return a decision- either allow or deny.
canUseTool fires whenever Claude Code would show a permission prompt to a user, e.g. hooks and permission rules do not cover it and it is not in acceptEdits mode.
Here's a complete example showing how to implement interactive tool approval:
```typescript TypeScript
import { query } from "@anthropic-ai/claude-agent-sdk";
async function promptForToolApproval(toolName: string, input: any) {
console.log("\n🔧 Tool Request:");
console.log(` Tool: ${toolName}`);
// Display tool parameters
if (input && Object.keys(input).length > 0) {
console.log(" Parameters:");
for (const [key, value] of Object.entries(input)) {
let displayValue = value;
if (typeof value === 'string' && value.length > 100) {
displayValue = value.substring(0, 100) + "...";
} else if (typeof value === 'object') {
displayValue = JSON.stringify(value, null, 2);
}
console.log(` ${key}: ${displayValue}`);
}
}
// Get user approval (replace with your UI logic)
const approved = await getUserApproval();
if (approved) {
console.log(" ✅ Approved\n");
return {
behavior: "allow",
updatedInput: input
};
} else {
console.log(" ❌ Denied\n");
return {
behavior: "deny",
message: "User denied permission for this tool"
};
}
}
// Use the permission callback
const result = await query({
prompt: "Help me analyze this codebase",
options: {
canUseTool: async (toolName, input) => {
return promptForToolApproval(toolName, input);
}
}
});
```
```python Python
from claude_agent_sdk import query
async def prompt_for_tool_approval(tool_name: str, input_params: dict):
print(f"\n🔧 Tool Request:")
print(f" Tool: {tool_name}")
# Display parameters
if input_params:
print(" Parameters:")
for key, value in input_params.items():
display_value = value
if isinstance(value, str) and len(value) > 100:
display_value = value[:100] + "..."
elif isinstance(value, (dict, list)):
display_value = json.dumps(value, indent=2)
print(f" {key}: {display_value}")
# Get user approval
answer = input("\n Approve this tool use? (y/n): ")
if answer.lower() in ['y', 'yes']:
print(" ✅ Approved\n")
return {
"behavior": "allow",
"updatedInput": input_params
}
else:
print(" ❌ Denied\n")
return {
"behavior": "deny",
"message": "User denied permission for this tool"
}
# Use the permission callback
result = await query(
prompt="Help me analyze this codebase",
options={
"can_use_tool": prompt_for_tool_approval
}
)
```
## Handling the AskUserQuestion Tool
The `AskUserQuestion` tool allows Claude to ask the user clarifying questions during a conversation. When this tool is called, your `canUseTool` callback receives the questions and must return the user's answers.
### Input Structure
When `canUseTool` is called with `toolName: "AskUserQuestion"`, the input contains:
```typescript
{
questions: [
{
question: "Which database should we use?",
header: "Database",
options: [
{ label: "PostgreSQL", description: "Relational, ACID compliant" },
{ label: "MongoDB", description: "Document-based, flexible schema" }
],
multiSelect: false
},
{
question: "Which features should we enable?",
header: "Features",
options: [
{ label: "Authentication", description: "User login and sessions" },
{ label: "Logging", description: "Request and error logging" },
{ label: "Caching", description: "Redis-based response caching" }
],
multiSelect: true
}
]
}
```
### Returning Answers
Return the answers in `updatedInput.answers` as a record mapping question text to the selected option label(s):
```typescript
return {
behavior: "allow",
updatedInput: {
questions: input.questions, // Pass through original questions
answers: {
"Which database should we use?": "PostgreSQL",
"Which features should we enable?": "Authentication, Caching"
}
}
}
```
Multi-select answers are comma-separated strings (e.g., `"Authentication, Caching"`).
## Related Resources
- [Hooks Guide](/docs/en/agent-sdk/hooks) - Learn how to implement hooks for fine-grained control over tool execution
- [Settings: Permission Rules](https://code.claude.com/docs/en/settings#permission-settings) - Configure declarative allow/deny rules with bash command parsing
## 2. Official Technical Reference & Guides (zhukunpenglinyutong/docs)
# Mintlify Starter Kit
Click on `Use this template` to copy the Mintlify starter kit. The starter kit contains examples including
- Guide pages
- Navigation
- Customizations
- API Reference pages
- Use of popular components
### Development
Install the [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the documentation changes locally. To install, use the following command
```
npm i mintlify
```
Run the following command at the root of your documentation (where mint.json is)
```
mintlify dev
```
### Publishing Changes
Install our Github App to auto propagate changes from your repo to your deployment. Changes will be deployed to production automatically after pushing to the default branch. Find the link to install on your dashboard.
#### Troubleshooting
- Mintlify dev isn't running - Run `mintlify install` it'll re-install dependencies.
- Page loads as a 404 - Make sure you are running in a folder with `mint.json`