Struct DuplexOptions 

pub struct DuplexOptions { /* private fields */ }

Configuration for DuplexSession::spawn.

Builder methods cover the most common spawn-time options. The spawn call always includes --print --verbose --input-format stream-json --output-format stream-json regardless of these options.

Implementations

impl DuplexOptions

pub fn model(self, model: impl Into<String>) -> Self

Set the model for this session (--model).

pub fn system_prompt(self, prompt: impl Into<String>) -> Self

Set the system prompt for this session (--system-prompt).

pub fn append_system_prompt(self, prompt: impl Into<String>) -> Self

Append to the default system prompt (--append-system-prompt).

pub fn resume(self, session_id: impl Into<String>) -> Self

Resume a prior session by id (--resume <session_id>).

Mirrors QueryCommand::resume for the duplex path. The spawned claude process picks up the conversation that produced session_id and continues it; turns sent through DuplexSession::send append to the existing history rather than starting fresh.

Use case: a host (IDE, MCP server, agent backend) wants to upgrade a passive on-disk session to a live duplex one – pulls the session_id out of the existing JSONL log, opens a duplex session here, and the next turn extends the same conversation.

resume and Self::continue_session are mutually exclusive at the CLI; passing both lets the CLI decide (it errors today).

pub fn continue_session(self) -> Self

Continue the most recent session in the current working directory (--continue).

Mirrors QueryCommand::continue_session for the duplex path. Use Self::resume to pick a specific session id; use this when “the last one” is what you want.

pub fn worktree(self, name: Option<impl Into<String>>) -> Self

Run this session in a fresh git worktree (--worktree [name]).

name is the optional worktree name (the CLI auto-generates one if omitted). Calling this method always enables the worktree flag, with or without a name.

Use case: an agent host wants the chat’s writes isolated from the current working tree – the chat opens with a fresh worktree, mutations land there, and the host can inspect or merge later.

pub fn agent(self, name: impl Into<String>) -> Self

Pin the session to a named subagent (--agent <name>).

name is resolved by the CLI in this order: inline definitions from Self::agents_json, then user-level ~/.claude/agents/<name>.md files, then project-level dirs loaded by the active --setting-sources.

Caveat: as of Claude Code 2.1.143, the CLI silently ignores an unknown name and falls back to the default behavior – no warning, no error. Callers that want a hard “agent must exist” semantics should validate the name out of band (e.g. via crate::artifacts::AgentsRoot::get) before passing it here.

pub fn agents_json(self, json: impl Into<String>) -> Self

Inline subagent definitions for this session (--agents <json>).

json is a JSON object keyed by agent name, with each value carrying at least description and prompt. Inline definitions take precedence over on-disk ~/.claude/agents/*.md of the same name. Pass Self::agent to select which one to use as the session’s persona.

Example: {"reviewer": {"description": "Reviews code", "prompt": "You are a code reviewer"}}.

pub fn permission_mode(self, mode: PermissionMode) -> Self

Set the permission mode for this session (--permission-mode <mode>).

Mirrors QueryCommand::permission_mode for the duplex path. The default mode (when this method isn’t called) drops to the CLI’s interactive prompt for every tool-use approval, which is broken for non-interactive duplex sessions – nothing answers the prompts and the session stalls or fails. Call this with PermissionMode::AcceptEdits for the “edit files autonomously” pattern, PermissionMode::Plan for read-only planning, etc.

Bypass mode is a footgun; reach for Self::dangerously_skip_permissions (or, for stricter discipline, crate::dangerous::DangerousClient) when you really need it.

pub fn dangerously_skip_permissions(self) -> Self

Pass --dangerously-skip-permissions to the spawned session.

Bypasses ALL permission checks – file edits, bash, network, the lot. Use only when you know the session runs in a trusted sandbox (a fresh worktree, a container, etc.). For most “run autonomously” cases you want Self::permission_mode with PermissionMode::AcceptEdits instead.

pub fn arg(self, arg: impl Into<String>) -> Self

Add a raw argument to the spawn command line.

Escape hatch for flags not covered by the dedicated builder methods.

pub fn subscriber_capacity(self, capacity: usize) -> Self

Set the per-session broadcast::Sender capacity backing DuplexSession::subscribe.

Defaults to DEFAULT_SUBSCRIBER_CAPACITY (256). Larger values give slow subscribers more room before they Lagged; smaller values reclaim memory if you do not subscribe.

pub fn on_permission(self, handler: PermissionHandler) -> Self

Register a PermissionHandler to answer the CLI’s tool-use permission prompts in-flight.

When set, the spawn command line includes --permission-prompt-tool stdio, which configures the CLI to emit control_request messages for tool use over the duplex channel rather than blocking on a TUI prompt.

Without a handler, the session does not pass --permission-prompt-tool and the CLI applies its default permission policy (driven by --permission-mode).

Known limitation: as of claude CLI 2.1.x the CLI does not emit control_request {subtype: "can_use_tool"} in stream-json print mode, so this handler will not be invoked end-to-end until an upstream fix lands. The wire handling is correct; see https://github.com/anthropics/claude-agent-sdk-python/issues/469.

Trait Implementations

impl Clone for DuplexOptions

fn clone(&self) -> DuplexOptions

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DuplexOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for DuplexOptions

fn default() -> DuplexOptions

Returns the “default value” for a type.