Interface: QueryOptions

Generated from the public TypeScript API.

Migration-oriented one-shot query options.

The call shape follows Claude Agent SDK conventions, but Cognitio stream message shapes remain native to this package. Resume applies explicit runtime overrides and reattaches supplied callbacks before work starts; changing the existing working directory is rejected. A configured fork applies the full facade profile to the new session.

​

Example

const options: QueryOptions = {
  model: "anthropic/claude-sonnet-4-5",
  resume: "ses_existing",
}

​

Extends

• AgentOptions

​

Properties

​

agents?

optional agents?: Record<string, AgentDefinition>;

Session-scoped helper and subagent definitions, keyed by name.

​

Inherited from

AgentOptions.agents

---

​

allowedTools?

optional allowedTools?: string[];

Nonempty tool allowlist, including scoped expressions such as bash(npm:). An empty array adds no allowlist restriction; use disallowedTools: [""] to hide ordinary tools. Matching grants can bypass the permission callback.

​

Inherited from

AgentOptions.allowedTools

---

​

appendSystemPrompt?

optional appendSystemPrompt?: string;

Append application instructions after the selected base system prompt.

​

Inherited from

AgentOptions.appendSystemPrompt

---

​

autoPermissionClassifierModel?

optional autoPermissionClassifierModel?: ModelId;

Provider/model used to classify unresolved permissions in auto mode.

​

Inherited from

AgentOptions.autoPermissionClassifierModel

---

​

backgroundTaskPolicy?

optional backgroundTaskPolicy?: object;

V2 awaits tasks within the current turn. Detached durable jobs are outside this release.

​

mode

mode: "foreground";

​

Inherited from

AgentOptions.backgroundTaskPolicy

---

​

baseUrl?

optional baseUrl?: string;

Attach to an existing server; mutually exclusive with spawn and client.

​

Inherited from

AgentOptions.baseUrl

---

​

canUseTool?

optional canUseTool?: false | CanUseToolCallback;

Answer unresolved tool approval requests. Explicit allow rules can approve a tool before this callback runs. Set false to disable a prior callback on resume.

​

Inherited from

AgentOptions.canUseTool

---

​

checkpointing?

optional checkpointing?: CheckpointingConfig;

Fine-grained file checkpoint policy.

​

Inherited from

AgentOptions.checkpointing

---

​

client?

optional client?: AgentClient;

Borrowed low-level client. Agent and shutdown() never close it.

​

Inherited from

AgentOptions.client

---

​

commands?

optional commands?: CommandDefinition[];

Programmatic commands invoked by Session.command(name, arguments).

​

Inherited from

AgentOptions.commands

---

​

compaction?

optional compaction?: object;

Per-session automatic compaction and summary formatting.

​

auto?

optional auto?: boolean;

​

includeFiles?

optional includeFiles?: boolean;

​

Inherited from

AgentOptions.compaction

---

​

control?

optional control?: ControlOptions;

Control-channel tuning for a dedicated client.

​

Inherited from

AgentOptions.control

---

​

cwd?

optional cwd?: string;

Session working directory.

​

Inherited from

AgentOptions.cwd

---

​

deleteSessionsOnClose?

optional deleteSessionsOnClose?: boolean;

Delete sessions created or forked by this Agent on close. Resumed sessions are retained. Defaults to false.

​

Inherited from

AgentOptions.deleteSessionsOnClose

---

​

directory?

optional directory?: string;

Alias for cwd; the two must match when both are supplied.

​

Inherited from

AgentOptions.directory

---

​

disallowedTools?

optional disallowedTools?: string[];

Tool denylist. [”*”] disables tool execution, including the runtime’s StructuredOutput tool. Use deterministic deny rules for operations that must never be approved.

​

Inherited from

AgentOptions.disallowedTools

---

​

effort?

optional effort?: "high" | "medium" | "low" | "max";

Provider-specific reasoning effort; unsupported combinations are rejected.

​

Inherited from

AgentOptions.effort

---

​

enableFileCheckpointing?

optional enableFileCheckpointing?: boolean;

Enable automatic file checkpointing. Requires a Git-backed workspace with runtime snapshots enabled.

​

Inherited from

AgentOptions.enableFileCheckpointing

---

​

enableToolSearch?

optional enableToolSearch?: boolean | "always" | "auto" | "never";

Control deferred tool discovery. Directly loaded tools remain governed by normal tool policy.

​

Inherited from

AgentOptions.enableToolSearch

---

​

forkMessageId?

optional forkMessageId?: string;

Optional fork boundary. Requires forkSession: true.

---

​

forkSession?

optional forkSession?: boolean;

Fork resume instead of attaching to it. Requires resume.

---

​

headers?

optional headers?: Record<string, string>;

Remote runtime request headers, including Authorization. Requires baseUrl; incompatible with client or spawn.

​

Inherited from

AgentOptions.headers

---

​

hooks?

optional hooks?: HookRegistration;

Callbacks keyed by lifecycle event. Callbacks remain local and must be rebound after restarting the application. An empty object clears prior hooks on resume.

​

Inherited from

AgentOptions.hooks

---

​

includeEnvironment?

optional includeEnvironment?: boolean;

Include working directory and platform context in the model’s system prompt.

​

Inherited from

AgentOptions.includeEnvironment

---

​

includePartialMessages?

optional includePartialMessages?: boolean;

Yield partial delta envelopes.

---

​

instructions?

optional instructions?: string;

Full custom system prompt (sugar for a custom systemPrompt). Cannot be combined with systemPrompt.

​

Inherited from

AgentOptions.instructions

---

​

maxBudgetUsd?

optional maxBudgetUsd?: number;

Positive estimated USD budget; a reached limit ends with error_max_budget. Provider accounting is authoritative.

​

Inherited from

AgentOptions.maxBudgetUsd

---

​

maxTurns?

optional maxTurns?: number;

Positive maximum number of assistant turns before error_max_turns.

​

Inherited from

AgentOptions.maxTurns

---

​

model?

optional model?: ModelId;

Provider/model identifier used for the main agent turn.

​

Inherited from

AgentOptions.model

---

​

outputFormat?

optional outputFormat?: OutputFormatSpec<unknown>;

Expected structured JSON output schema and bounded schema retry policy.

​

Inherited from

AgentOptions.outputFormat

---

​

permission?

optional permission?: PermissionRuleset;

Server permission rules, distinct from runtime permissionMode.

​

Inherited from

AgentOptions.permission

---

​

permissionMode?

optional permissionMode?: PermissionMode;

Approval policy for unresolved tool requests. This does not create an OS sandbox.

​

Inherited from

AgentOptions.permissionMode

---

​

plugins?

optional plugins?: PluginSpec[];

Inline plugin bundles or local Claude-format plugin directories.

​

Inherited from

AgentOptions.plugins

---

​

resume?

optional resume?: string;

Existing session id to attach to or fork.

---

​

sdkMcpServers?

optional sdkMcpServers?: RuntimeMcpServer[];

SDK-hosted or external MCP descriptors. An explicit empty array clears prior MCP registrations on resume.

​

Inherited from

AgentOptions.sdkMcpServers

---

​

settingSources?

optional settingSources?: ("user" | "local" | "project")[];

Instruction/config resource sources to load. SDK sessions default to an empty array.

​

Inherited from

AgentOptions.settingSources

---

​

signal?

optional signal?: AbortSignal;

Abort the active turn without changing iterator ownership.

---

​

skills?

optional skills?: SkillDefinition[];

Programmatic reusable skill descriptions and content.

​

Inherited from

AgentOptions.skills

---

​

spawn?

optional spawn?: SpawnOptions;

Dedicated local-server options.

Defined scalar values replace facade defaults. config is merged by top-level key and, under agent, by agent name; a named agent’s own object replaces wholesale, so agent: { title: {…} } drops the facade’s title.disable and restores the per-session title model call. Explicit false, "", and [] values are preserved.

​

Inherited from

AgentOptions.spawn

---

​

systemPrompt?

optional systemPrompt?: SystemPromptSpec;

Replace the base prompt with a string/custom prompt, or explicitly select the coding preset.

​

Inherited from

AgentOptions.systemPrompt

---

​

thinkingConfig?

optional thinkingConfig?: ThinkingConfig;

Provider reasoning configuration; unsupported model/provider combinations fail explicitly.

​

Inherited from

AgentOptions.thinkingConfig

---

​

title?

optional title?: string;

Explicit server-session title.

​

Inherited from

AgentOptions.title

---

​

tools?

optional tools?: ToolDefinition[];

Direct SDK tools, exposed as sdk_<sanitized-name>.

They execute in the caller process rather than the isolated server.

​

Inherited from

AgentOptions.tools

---

​

workspaceId?

optional workspaceId?: string;

Workspace id for a dedicated client.

​

Inherited from

AgentOptions.workspaceId