Struct DuplexOptions

Source

pub struct DuplexOptions { /* private fields */ }

Expand description

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§

Source §

impl DuplexOptions

Source

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

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

Source

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

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

Source

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

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

Source

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).

Source

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.

Source

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.

Source

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.

Source

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"}}.

Source

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.

Source

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.

Source

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

Start a new session under a caller-chosen id (--session-id <uuid>).

Mirrors QueryCommand::session_id for the duplex path. Unlike Self::resume (pick up an existing session) or Self::continue_session (pick up the most recent one), this mints a fresh session whose id the host knows up front – useful when the host indexes sessions externally before the first turn completes.

Source

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

Set a JSON schema for structured output validation (--json-schema <schema>).

Mirrors QueryCommand::json_schema for the duplex path. schema is the inline JSON of the schema; the turn’s closing result message carries the validated structured_output.

Source

pub fn allowed_tools<I, T>(self, tools: I) -> Self
where I: IntoIterator<Item = T>, T: Into<ToolPattern>,

Add allowed tool patterns (--allowed-tools).

Mirrors QueryCommand::allowed_tools for the duplex path: accepts anything convertible into ToolPattern, including bare strings (e.g. "Bash", "Bash(git log:*)", "mcp__my-server__*"), and joins them into the comma-separated form the CLI expects.

Source

pub fn allowed_tool(self, tool: impl Into<ToolPattern>) -> Self

Add a single allowed tool pattern.

Source

pub fn disallowed_tools<I, T>(self, tools: I) -> Self
where I: IntoIterator<Item = T>, T: Into<ToolPattern>,

Add disallowed tool patterns (--disallowed-tools).

Source

pub fn disallowed_tool(self, tool: impl Into<ToolPattern>) -> Self

Add a single disallowed tool pattern.

Source

pub fn max_turns(self, turns: u32) -> Self

Cap the number of agentic turns (--max-turns <n>).

The cap applies per turn sent through DuplexSession::send; a turn that exhausts it closes with an error_max_turns result rather than an assistant reply.

Source

pub fn max_budget_usd(self, budget: f64) -> Self

Cap claude’s own spend for the session (--max-budget-usd <usd>).

This is the CLI’s cap, checked post-hoc after each API call, so a session can overspend before tripping. It is distinct from the wrapper’s BudgetTracker ceiling, which gates dispatch host-side – attach one via Conversation::with_budget to stop a duplex conversation before the next turn is sent.

Source

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

Set a fallback model for when the primary is overloaded (--fallback-model <model>).

Source

pub fn effort(self, effort: Effort) -> Self

Set the reasoning effort level (--effort <level>).

Source

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

Add an additional directory for tool access (--add-dir <dir>, repeatable).

Source

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

Add an MCP config file path (--mcp-config <path>, repeatable).

Pair with crate::McpConfigBuilder to generate the file.

Source

pub fn strict_mcp_config(self) -> Self

Only use MCP servers from --mcp-config files, ignoring the user- and project-level MCP configuration (--strict-mcp-config).

Source

pub fn no_session_persistence(self) -> Self

Do not persist the session to on-disk history (--no-session-persistence).

Source

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.

Source

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.

Source

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.