Skip to main content
The Query class returned by query() provides methods for controlling the query session, inspecting state, and modifying behavior mid-session.

Overview

A Query instance implements AsyncIterable<SDKMessage>, allowing you to iterate over messages:

Methods

getSessionId()

Get the unique session identifier.

Returns

sessionId
string
The session ID (UUID format).

Example

Use Cases

  • Resume sessions later with the resume option
  • Track sessions across multiple queries
  • Link sessions with external systems
  • Debug and logging

isClosed()

Check if the query session has been closed.

Returns

closed
boolean
true if the session is closed, false otherwise.

Example

Use Cases

  • Check session state before calling methods
  • Conditional logic based on session status
  • Resource cleanup verification

interrupt()

Interrupt the current operation. The AI will stop what it’s doing and await further instructions.

Returns

promise
Promise<void>
Promise that resolves when the interrupt is acknowledged.

Example

Notes

  • Throws an error if the query is already closed
  • The interrupt is sent as a control request to the CLI
  • The AI will finish the current tool execution before stopping

setPermissionMode()

Change the permission mode during the session.

Parameters

mode
PermissionMode
required
The new permission mode: 'default', 'plan', 'auto-edit', or 'yolo'.

Returns

promise
Promise<void>
Promise that resolves when the mode change is acknowledged.

Example

Notes

  • Changes take effect immediately for subsequent tool requests
  • Does not affect ongoing tool executions
  • Throws an error if the query is closed

setModel()

Change the AI model during the session.

Parameters

model
string
required
The new model identifier (e.g., 'gpt-4', 'qwen-max').

Returns

promise
Promise<void>
Promise that resolves when the model change is acknowledged.

Example

Notes

  • The new model is used for subsequent AI requests
  • Does not affect the current ongoing request
  • Throws an error if the query is closed

close()

Manually close the query session and cleanup resources.

Returns

promise
Promise<void>
Promise that resolves when the session is fully closed.

Example

What Gets Cleaned Up

  • CLI process terminated
  • Pending control requests rejected
  • MCP transports closed
  • Input stream completed
  • Event listeners removed

Notes

  • Automatically called when iteration completes normally
  • Safe to call multiple times (subsequent calls are no-ops)
  • Pending operations will be rejected with “Query is closed” error

streamInput()

Stream user messages for multi-turn conversations.
This is a low-level method. For most use cases, pass an async iterable as the prompt parameter to query() instead.

Parameters

messages
AsyncIterable<SDKUserMessage>
required
Async iterable of user messages to send.

Returns

promise
Promise<void>
Promise that resolves when all messages have been sent.

Example

endInput()

Signal that no more user messages will be sent (for multi-turn mode).
This is a low-level method. The SDK automatically calls this when using async iterables.

Example

supportedCommands()

Get the list of control commands supported by the CLI.

Returns

commands
Record<string, unknown> | null
Object containing supported command names and their metadata.

Example

mcpServerStatus()

Get the status of MCP servers connected to the session.

Returns

status
Record<string, unknown> | null
Object containing MCP server status information.

Example

Complete Example

Here’s a comprehensive example using multiple methods:

Error Handling

All methods throw errors if called on a closed query:

See Also