Struct ConfigBuilder 

pub struct ConfigBuilder { /* private fields */ }

Fluent builder for Config.

Implementations

impl ConfigBuilder

pub fn apply_profile(self, p: &ConfigProfile) -> ConfigBuilder

Apply the set fields of a ConfigProfile over the current builder.

impl ConfigBuilder

pub fn from_config(config: Config) -> ConfigBuilder

P4d (design §5.2 P1 CLI-adapter): resume building from an ALREADY-constructed Config rather than Config::default — lets a caller that assembled a Config with its own precedence logic (e.g. the CLI’s build_config: flag > env > project > user > interactive-default) layer a narrowly-scoped ConfigProfile on top via Self::apply_profile afterward, reusing that method’s correct per-key merge semantics (tables merge key-wise, e.g. tool_overrides/prompts/extra_headers/extra_body) instead of a second hand-rolled copy of the same merge logic at the call site.

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

Set the model identifier.

pub fn base_url(self, url: impl Into<String>) -> ConfigBuilder

Set the OpenAI-compatible base URL (defaults to OpenRouter).

pub fn api_key(self, key: impl Into<String>) -> ConfigBuilder

Provide the API key explicitly.

pub fn api_key_env(self, var: impl Into<String>) -> ConfigBuilder

Change which environment variable the key is read from.

pub fn api_key_cmd(self, cmd: impl Into<String>) -> ConfigBuilder

Set the credential-helper command — see Config::api_key_cmd.

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

Replace the system prompt.

pub fn temperature(self, t: f32) -> ConfigBuilder

Set the sampling temperature.

pub fn max_tokens(self, n: u32) -> ConfigBuilder

Set the max output tokens.

pub fn max_iterations(self, n: usize) -> ConfigBuilder

Set the per-send iteration budget.

pub fn effort(self, level: impl Into<String>) -> ConfigBuilder

Set the reasoning/effort level (reasoning_effort).

pub fn response_format(self, format: Value) -> ConfigBuilder

Constrain output to a JSON schema (response_format).

pub fn extra_body_field( self, key: impl Into<String>, value: Value, ) -> ConfigBuilder

Merge an extra request-body field (provider-native passthrough).

pub fn max_tool_output_bytes(self, n: usize) -> ConfigBuilder

Cap cumulative output tokens across one send loop. Cap a single tool result at n bytes (see Config::max_tool_output_bytes). Pass 0 only via the field to disable.

pub fn max_total_output_tokens(self, n: u64) -> ConfigBuilder

Cap on cumulative output tokens across one send loop. Output tokens only; input/prompt tokens are not counted, so this is not a cost cap.

pub fn cwd(self, dir: impl Into<PathBuf>) -> ConfigBuilder

Set the working directory tools operate in.

pub fn add_dir(self, dir: impl Into<PathBuf>) -> ConfigBuilder

Add an extra root directory (--add-dir / multi-root / worktree).

pub fn project_context(self, enabled: bool) -> ConfigBuilder

Enable auto-loading of CLAUDE.md / AGENTS.md into the system prompt.

pub fn prompt( self, name: impl Into<String>, template: impl Into<String>, ) -> ConfigBuilder

Register a named prompt template (skill / slash command).

pub fn compact_after_messages(self, n: usize) -> ConfigBuilder

Compact the conversation once it exceeds n messages.

pub fn sandbox(self, policy: SandboxPolicy) -> ConfigBuilder

Set the filesystem sandbox policy for write-capable tools.

pub fn approval(self, policy: ApprovalPolicy) -> ConfigBuilder

Set the tool-approval policy.

pub fn auto_approve_tool(self, name: impl Into<String>) -> ConfigBuilder

Add a tool to the auto-approve allowlist (no approval under OnRequest).

pub fn deny_tool_pattern(self, pattern: impl Into<String>) -> ConfigBuilder

P4: add a glob pattern to Config::tool_deny_patterns — a match forces approval unconditionally, even under ApprovalPolicy::Never.

pub fn allow_tool_pattern(self, pattern: impl Into<String>) -> ConfigBuilder

P4: add a glob pattern to Config::tool_allow_patterns — the pattern generalization of Self::auto_approve_tool.

pub fn approval_handler( self, handler: Box<dyn Fn(&ToolCall) -> bool + Send + Sync>, ) -> ConfigBuilder

Set the handler consulted when a tool call needs approval.

pub fn pre_tool_hook( self, hook: Box<dyn Fn(&str, &Value) -> Option<String> + Send + Sync>, ) -> ConfigBuilder

Set the pre-tool hook (may block a call by returning Some(reason)).

pub fn post_tool_hook( self, hook: Box<dyn Fn(&str, &str, bool) + Send + Sync>, ) -> ConfigBuilder

Set the post-tool hook (observational).

pub fn disable_tool(self, name: impl Into<String>) -> ConfigBuilder

Disable a tool by name.

pub fn enable_tool(self, name: impl Into<String>) -> ConfigBuilder

Enable a tool by name (overriding a prior disable).

pub fn tool_description( self, name: impl Into<String>, description: impl Into<String>, ) -> ConfigBuilder

Override the description the model sees for a tool.

pub fn tool_advertising(self, advertising: ToolAdvertising) -> ConfigBuilder

Set how tools are advertised to the model (B6).

pub fn schema_tier(self, tier: SchemaTier) -> ConfigBuilder

Set the global tool-schema tier (TR-8/T5): how verbose ADVERTISED tool schemas are. Per-tool overrides (Self::tool_schema_tier) still win for the specific tools they name.

pub fn tool_schema_tier( self, name: impl Into<String>, tier: SchemaTier, ) -> ConfigBuilder

Override the schema tier for a single tool (TR-8/T5), regardless of the global knob — e.g. keep one load-bearing tool at Full while everything else shrinks to Minimal.

pub fn header( self, key: impl Into<String>, value: impl Into<String>, ) -> ConfigBuilder

Add an extra HTTP header sent on every request.

pub fn event_sink( self, sink: Box<dyn Fn(AgentEvent) + Send + Sync>, ) -> ConfigBuilder

Attach a streaming event sink.

pub fn cache_plan(self, plan: CachePlan) -> ConfigBuilder

Set the prompt-caching plan (B7).

pub fn cache_warnings(self, enabled: bool) -> ConfigBuilder

UX-26 (B7-warn): enable/disable the cache-cold warning (default on).

pub fn module_registry(self, enabled: bool) -> ConfigBuilder

P3: turn on the [experimental] module_registry gate — see Config::module_registry.

pub fn module_activation(self, activation: ModuleActivation) -> ConfigBuilder

P3: set the resolved module-activation set — see Config::module_activation.

pub fn core_tools_enabled(self, tools: Vec<String>) -> ConfigBuilder

P3: set the effective [core.tools] enabled list — see Config::core_tools_enabled.

pub fn skills_enabled(self, enabled: bool) -> ConfigBuilder

P3: set [core.skills].enabled — see Config::skills_enabled.

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

P4: set the small/utility model id — see Config::small_model.

pub fn model_fallback(self, chain: Vec<String>) -> ConfigBuilder

P4: set the model failure-fallback chain — see Config::model_fallback.

pub fn env_context(self, enabled: bool) -> ConfigBuilder

P4b: turn on the environment-context block — see Config::env_context.

pub fn project_root_markers(self, markers: Vec<String>) -> ConfigBuilder

P4b: set the project-root marker filenames — see Config::project_root_markers.

pub fn project_doc_max_bytes(self, n: usize) -> ConfigBuilder

P4b: cap the total bytes of assembled instruction-file content — see Config::project_doc_max_bytes.

pub fn instruction_imports(self, enabled: bool) -> ConfigBuilder

P4b: turn on @path instruction imports — see Config::instruction_imports.

pub fn retry( self, enabled: bool, max_retries: Option<u32>, base_delay_ms: Option<u64>, ) -> ConfigBuilder

P4b: configure request retry with backoff — see Config::retry_enabled. max_retries/base_delay_ms override the transport’s built-in defaults when Some.

pub fn compaction_pressure( self, reserve_tokens: u64, keep_recent_tokens: u64, ) -> ConfigBuilder

P4b: turn on the compaction token-pressure trigger — see Config::compaction_reserve_tokens.

pub fn compaction_focus_instructions( self, text: impl Into<String>, ) -> ConfigBuilder

P4b: set the compaction focus instructions — see Config::compaction_focus_instructions.

pub fn auto_title(self, enabled: bool) -> ConfigBuilder

P4b: turn on the auto-title gate — see Config::auto_title.

pub fn steering_mode(self, mode: SteeringMode) -> ConfigBuilder

P4b: set the mid-turn steering delivery mode — see Config::steering_mode.

pub fn follow_up_mode(self, mode: SteeringMode) -> ConfigBuilder

P4b: set the idle follow-up delivery mode — see Config::follow_up_mode.

pub fn stop_gate( self, hook: Box<dyn Fn(&str) -> Option<String> + Send + Sync>, ) -> ConfigBuilder

P4b: install a stop-gate hook — see Config::stop_gate.

pub fn read_file_multimodal(self, enabled: bool) -> ConfigBuilder

P4c: turn on multimodal read_file — see Config::read_file_multimodal.

pub fn edit_file_require_read_before_edit(self, enabled: bool) -> ConfigBuilder

P4c: require a prior read before edit_file accepts an edit — see Config::edit_file_require_read_before_edit.

pub fn edit_file_notebook_aware(self, enabled: bool) -> ConfigBuilder

P4c: turn on notebook-cell-aware edit_file — see Config::edit_file_notebook_aware.

pub fn shell_env_snapshot(self, enabled: bool) -> ConfigBuilder

P4c: turn on shell-environment snapshotting — see Config::shell_env_snapshot.

pub fn doom_loop_threshold(self, n: u32) -> ConfigBuilder

P4c: set the doom-loop repetition threshold — see Config::doom_loop_threshold.

pub fn nested_instructions(self, enabled: bool) -> ConfigBuilder

P4c: turn on on-demand nested instruction loading — see Config::nested_instructions.

pub fn model_switch_allow_switch(self, enabled: bool) -> ConfigBuilder

P4c: turn on mid-session model switch’s persisted-record + reasoning-filter behavior — see Config::model_switch_allow_switch.

pub fn context_injections(self, enabled: bool) -> ConfigBuilder

P4e: turn on ambient context-injection blocks — see Config::context_injections.

pub fn context_injection_block( self, name: impl Into<String>, content: impl Into<String>, ) -> ConfigBuilder

P4e: append one named ambient context block — see Config::context_injection_blocks.

pub fn compaction_enabled(self, enabled: bool) -> ConfigBuilder

P4e: master gate for all auto-compaction — see Config::compaction_enabled.

pub fn parallel_tool_calls(self, enabled: bool) -> ConfigBuilder

P4e: run independent tool calls concurrently — see Config::parallel_tool_calls.

pub fn session_git_metadata(self, enabled: bool) -> ConfigBuilder

P4e: capture git branch/sha/dirty at construction — see Config::session_git_metadata.

pub fn session_persist(self, enabled: bool) -> ConfigBuilder

P4e DEFECT-FIX: ephemeral vs. persisted session gate — see Config::session_persist.

pub fn session_name(self, name: impl Into<String>) -> ConfigBuilder

P4e DEFECT-FIX: a caller-configured session name — see Config::session_name.

pub fn subagents_enabled(self, enabled: bool) -> ConfigBuilder

P5-3 (§3.1 capabilities.subagents.enabled) — see Config::subagents_enabled.

pub fn subagents_max_depth(self, n: usize) -> ConfigBuilder

P5-3 (§3.1 capabilities.subagents.max_depth) — see Config::subagents_max_depth.

pub fn subagents_max_concurrent(self, n: usize) -> ConfigBuilder

P5-3 (resource bound) — see Config::subagents_max_concurrent.

pub fn subagents_background(self, enabled: bool) -> ConfigBuilder

P5-3 (§3.1 capabilities.subagents.background) — see Config::subagents_background.

pub fn subagents_background_prompts( self, policy: BackgroundPromptsPolicy, ) -> ConfigBuilder

P5-3 (§2.2 C6) — see Config::subagents_background_prompts.

pub fn subagents_claude_agent_alias(self, enabled: bool) -> ConfigBuilder

Enable Claude Code’s Agent compatibility alias for named subagents.

pub fn claude_runtime_tools_enabled(self, enabled: bool) -> ConfigBuilder

Enable Claude’s paused runtime-state compatibility intrinsics.

pub fn subagent_definition(self, def: NamedAgentDefinition) -> ConfigBuilder

P5-3 (§3.1 capabilities.subagents.agents.<name>) — register one named agent definition, keyed by crate::subagents::NamedAgentDefinition::name.

pub fn subagent_depth(self, depth: usize) -> ConfigBuilder

P5-3 (runtime-only) — see Config::subagent_depth. Not something an ordinary caller sets by hand; Agent::run_spawn_subagent sets it on the CHILD config it builds.

pub fn tools_background_enabled(self, enabled: bool) -> ConfigBuilder

P5-6 (§3.1 capabilities.tools_background.enabled) — see Config::tools_background_enabled.

pub fn tools_background_max_concurrent(self, n: usize) -> ConfigBuilder

P5-6 (resource bound) — see Config::tools_background_max_concurrent.

pub fn tools_background_max_output_bytes(self, n: usize) -> ConfigBuilder

P5-6 (resource bound) — see Config::tools_background_max_output_bytes.

pub fn checkpoint_enabled(self, enabled: bool) -> ConfigBuilder

P5-9 (§3.1 capabilities.checkpoint.enabled) — see Config::checkpoint_enabled.

pub fn checkpoint_retain(self, n: usize) -> ConfigBuilder

P5-9 (bounded-disk requirement) — see Config::checkpoint_retain.

pub fn checkpoint_dir(self, dir: impl Into<PathBuf>) -> ConfigBuilder

P5-9 (embedder/test override) — see Config::checkpoint_dir.

pub fn lsp_enabled(self, enabled: bool) -> ConfigBuilder

P5-11 (§3.1 capabilities.lsp.enabled) — see Config::lsp_enabled.

pub fn lsp_servers(self, servers: Vec<(String, LspServerSpec)>) -> ConfigBuilder

P5-11 (capabilities.lsp.servers) — see Config::lsp_servers.

pub fn lsp_max_diagnostics(self, n: usize) -> ConfigBuilder

P5-11 (bounded-context requirement) — see Config::lsp_max_diagnostics.

pub fn lsp_timeout_secs(self, secs: u64) -> ConfigBuilder

P5-11 (bounded-latency requirement) — see Config::lsp_timeout_secs.

pub fn formatters_enabled(self, enabled: bool) -> ConfigBuilder

P5-11 (§3.1 capabilities.formatters.enabled) — see Config::formatters_enabled.

pub fn formatters( self, formatters: Vec<(String, FormatterSpec)>, ) -> ConfigBuilder

P5-11 (capabilities.formatters.<name>) — see Config::formatters.

pub fn formatters_diff_back(self, diff_back: bool) -> ConfigBuilder

P5-11 (§3.1 capabilities.formatters.diff_back, C10) — see Config::formatters_diff_back.

pub fn formatters_timeout_secs(self, secs: u64) -> ConfigBuilder

P5-11 (bounded-latency requirement) — see Config::formatters_timeout_secs.

pub fn trust_enabled(self, enabled: bool) -> ConfigBuilder

P5-12 (§3.1 capabilities.trust.enabled) — see Config::trust_enabled.

pub fn trust_default(self, default: TrustDecision) -> ConfigBuilder

P5-12 (capabilities.trust.default) — see Config::trust_default.

pub fn plugins_enabled(self, enabled: bool) -> ConfigBuilder

P5-12 (§3.1 capabilities.plugins.enabled) — see Config::plugins_enabled.

pub fn plugins_dirs(self, dirs: Vec<PathBuf>) -> ConfigBuilder

P5-12 (capabilities.plugins.dirs) — see Config::plugins_dirs.

pub fn build(self) -> Config

Finalize the configuration.

Trait Implementations

impl Default for ConfigBuilder

fn default() -> ConfigBuilder

Returns the “default value” for a type.