Methods
| Method | Description |
|---|---|
interrupt() | Interrupts the query. Only available in streaming input mode. When the CLI advertises the interrupt_receipt_v1 capability in SDKSystemMessage.capabilities, resolves with an SDKControlInterruptResponse listing the messages that were pending when the interrupt arrived. Resolves undefined on CLIs before v2.1.205 |
rewindFiles(userMessageId, options?) | Restores files to their state at the specified user message. Pass \{ dryRun: true \} to preview changes. Requires enableFileCheckpointing: true. See File checkpointing |
setPermissionMode() | Changes the permission mode (only available in streaming input mode) |
setModel() | Changes the model (only available in streaming input mode). Passing undefined or the string "default" resets to the session default model |
setMaxThinkingTokens() | Deprecated: Use the thinking option instead. Changes the maximum thinking tokens. Passing null resets thinking to the session default: a mid-session override is cleared, and thinking stays off for sessions that have it disabled |
applyFlagSettings(settings) | Merges settings into the session's flag settings layer at runtime (only available in streaming input mode). See applyFlagSettings() |
updateSettings(source, settings) | Merges settings into the project's local settings file, .claude/settings.local.json; they take effect on the next request. Accepts only source: 'localSettings' and an allowlisted key set, currently outputStyle, with string values; deleting a key isn't supported. Rejects on remote transports and in sessions whose settingSources exclude local. Requires TypeScript SDK v0.3.257 or later, which bundles Claude Code v2.1.257 |
initializationResult() | Returns the full initialization result including supported commands, models, account info, and output style configuration |
reinitialize() | Re-sends the initialize control request to the running CLI and returns a fresh result instead of the cached first-connect result. Use it after a transport gap, such as reattaching to a session after a disconnect, so pending permission requests reach your canUseTool callback again. Make the callback idempotent per request ID, because a request whose response was lost is dispatched again. Requires Claude Code v2.1.195 or later |
supportedCommands() | Returns available commands. From Agent SDK v0.3.216 the list reflects mid-session command changes; see SDKCommandsChangedMessage |
supportedModels() | Returns available models with display info |
supportedAgents() | Returns available subagents as AgentInfo[] |
mcpServerStatus() | Returns status of connected MCP servers |
getContextUsage(opts?) | Returns an SDKControlGetContextUsageResponse breaking down the session's context window usage by category, skill, and tool. With the default detail, it is the same data /context shows in an interactive session. The detail option requires Agent SDK v0.3.257 or later |
readFile(path, options?) | Reads a file from the session's filesystem. Claude Code resolves the path against cwd and applies the same read-permission rules as the Read tool. Pass \{ maxBytes \} to change the read cap (default 1 MB, ceiling 10 MB) and \{ encoding: 'base64' \} for binary files such as images. Resolves with an SDKControlReadFileResponse, or null on permission denial, a missing file, or a transport error. Requires TypeScript SDK v0.2.121 or later |
reloadSkills() | Reloads skills from disk, so skills you add or edit mid-session become available to the running session. Resolves with an SDKControlReloadSkillsResponse listing the skills available after the reload. Requires Agent SDK v0.3.163 or later |
accountInfo() | Returns account information |
reconnectMcpServer(serverName) | Reconnect an MCP server by name. If the name also matches an entry in a settings file such as .mcp.json or ~/.claude.json, Claude Code reconnects the server you configured through mcpServers or setMcpServers(), not the settings-file entry. That resolution order requires Claude Code v2.1.257 or later |
toggleMcpServer(serverName, enabled) | Enable or disable an MCP server by name, with the same name resolution as reconnectMcpServer(). Disabling disconnects the server |
setMcpServers(servers) | Dynamically replace the set of MCP servers for this session. Resolves with an McpSetServersResult naming which servers were added and 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 |